<?php
/**
 * Product Fields Helper
 *
 * Shared field definitions and context builders for product-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 ProductFields
 *
 * Provides shared product field definitions for triggers and actions.
 */
final class ProductFields {

	/**
	 * Get available fields for product stock triggers.
	 *
	 * @return array Available field definitions.
	 */
	public static function available_fields(): array {
		return array(
			array(
				'name'        => 'product_id',
				'type'        => 'integer',
				'description' => __( 'Unique identifier for the product', 'sequensy' ),
				'example'     => '567',
			),
			array(
				'name'        => 'product_name',
				'type'        => 'string',
				'description' => __( 'Name of the product', 'sequensy' ),
				'example'     => 'Premium T-Shirt',
			),
			array(
				'name'        => 'product_sku',
				'type'        => 'string',
				'description' => __( 'SKU of the product', 'sequensy' ),
				'example'     => 'TSHIRT-001',
			),
			array(
				'name'        => 'stock_quantity',
				'type'        => 'integer',
				'description' => __( 'Current stock quantity', 'sequensy' ),
				'example'     => '3',
			),
			array(
				'name'        => 'low_stock_threshold',
				'type'        => 'integer',
				'description' => __( 'Low stock threshold for this product', 'sequensy' ),
				'example'     => '5',
			),
			array(
				'name'        => 'stock_status',
				'type'        => 'string',
				'description' => __( 'Stock status (instock, outofstock, onbackorder)', 'sequensy' ),
				'example'     => 'instock',
			),
			array(
				'name'        => 'product_type',
				'type'        => 'string',
				'description' => __( 'Type of product (simple, variable, grouped)', 'sequensy' ),
				'example'     => 'simple',
			),
			array(
				'name'        => 'product_url',
				'type'        => 'string',
				'description' => __( 'URL of the product page', 'sequensy' ),
				'example'     => 'https://example.com/product/premium-t-shirt',
			),
			array(
				'name'        => 'product_price',
				'type'        => 'string',
				'description' => __( 'Regular price of the product', 'sequensy' ),
				'example'     => '29.99',
			),
		);
	}

	/**
	 * Build product context from a WC_Product object.
	 *
	 * @param \WC_Product $product Product object.
	 * @return array|null Context array or null if product is invalid.
	 */
	public static function build_context( $product ): ?array {
		if ( ! $product instanceof \WC_Product ) {
			return null;
		}

		return array(
			'product_id'          => $product->get_id(),
			'product_name'        => $product->get_name(),
			'product_sku'         => $product->get_sku(),
			'stock_quantity'      => $product->get_stock_quantity(),
			'low_stock_threshold' => (int) $product->get_low_stock_amount(),
			'stock_status'        => $product->get_stock_status(),
			'product_type'        => $product->get_type(),
			'product_url'         => get_permalink( $product->get_id() ),
			'product_price'       => $product->get_regular_price(),
		);
	}
}
