<?php
/**
 * Order Fields Helper
 *
 * Shared field definitions and context builders for order-related triggers.
 *
 * @package Sequensy\Integrations\WooCommerce
 * @since 1.0.0
 */

declare(strict_types=1);

namespace Sequensy\Integrations\WooCommerce\Helpers;

// If this file is called directly, abort.
if ( ! defined( 'WPINC' ) ) {
	die;
}

/**
 * Class OrderFields
 *
 * Provides shared order field definitions for triggers and actions.
 */
final class OrderFields {

	/**
	 * Get available fields shared by all order-related triggers.
	 *
	 * @return array Available field definitions.
	 */
	public static function available_fields(): array {
		return array(
			array(
				'name'        => 'order_id',
				'type'        => 'integer',
				'description' => __( 'Unique identifier for the order', 'sequensy' ),
				'example'     => '1234',
			),
			array(
				'name'        => 'order_number',
				'type'        => 'string',
				'description' => __( 'Display order number', 'sequensy' ),
				'example'     => '1234',
			),
			array(
				'name'        => 'order_status',
				'type'        => 'string',
				'description' => __( 'Current status of the order', 'sequensy' ),
				'example'     => 'processing',
			),
			array(
				'name'        => 'order_total',
				'type'        => 'string',
				'description' => __( 'Total amount of the order', 'sequensy' ),
				'example'     => '99.99',
			),
			array(
				'name'        => 'order_currency',
				'type'        => 'string',
				'description' => __( 'Currency code for the order', 'sequensy' ),
				'example'     => 'USD',
			),
			array(
				'name'        => 'billing_email',
				'type'        => 'string',
				'description' => __( 'Billing email address', 'sequensy' ),
				'example'     => 'customer@example.com',
			),
			array(
				'name'        => 'billing_first_name',
				'type'        => 'string',
				'description' => __( 'Billing first name', 'sequensy' ),
				'example'     => 'John',
			),
			array(
				'name'        => 'billing_last_name',
				'type'        => 'string',
				'description' => __( 'Billing last name', 'sequensy' ),
				'example'     => 'Doe',
			),
			array(
				'name'        => 'billing_phone',
				'type'        => 'string',
				'description' => __( 'Billing phone number', 'sequensy' ),
				'example'     => '+1-555-123-4567',
			),
			array(
				'name'        => 'shipping_method',
				'type'        => 'string',
				'description' => __( 'Shipping method used for the order', 'sequensy' ),
				'example'     => 'flat_rate',
			),
			array(
				'name'        => 'payment_method',
				'type'        => 'string',
				'description' => __( 'Payment method used for the order', 'sequensy' ),
				'example'     => 'stripe',
			),
			array(
				'name'        => 'customer_id',
				'type'        => 'integer',
				'description' => __( 'WordPress user ID of the customer', 'sequensy' ),
				'example'     => '42',
			),
			array(
				'name'        => 'order_date',
				'type'        => 'datetime',
				'description' => __( 'Date when the order was created', 'sequensy' ),
				'example'     => '2024-01-15 10:30:00',
			),
		);
	}

	/**
	 * Build order context from an order ID and optional order object.
	 *
	 * @param int        $order_id Order ID.
	 * @param mixed|null $order    Optional WC_Order object (may not be passed by older WC versions).
	 * @return array|null Context array or null if order not found.
	 */
	public static function build_context( int $order_id, $order = null ): ?array {
		if ( ! $order instanceof \WC_Order ) {
			$order = wc_get_order( $order_id );
		}

		if ( ! $order ) {
			return null;
		}

		$shipping_methods = $order->get_shipping_methods();
		$first_shipping   = ! empty( $shipping_methods ) ? reset( $shipping_methods ) : null;

		return array(
			'order_id'           => $order->get_id(),
			'order_number'       => $order->get_order_number(),
			'order_status'       => $order->get_status(),
			'order_total'        => $order->get_total(),
			'order_currency'     => $order->get_currency(),
			'billing_email'      => $order->get_billing_email(),
			'billing_first_name' => $order->get_billing_first_name(),
			'billing_last_name'  => $order->get_billing_last_name(),
			'billing_phone'      => $order->get_billing_phone(),
			'shipping_method'    => $first_shipping ? $first_shipping->get_method_id() : '',
			'payment_method'     => $order->get_payment_method(),
			'customer_id'        => $order->get_customer_id(),
			'order_date'         => $order->get_date_created() ? $order->get_date_created()->date( 'Y-m-d H:i:s' ) : '',
		);
	}
}
