<?php

namespace Limb_Chatbot\Includes\Interfaces;

use Limb_Chatbot\Includes\Data_Objects\Message;
use Limb_Chatbot\Includes\Utilities\Chatbot_Utility;
use WC_Product;

/**
 * Product Confirmation Processor Interface
 *
 * Defines the contract for handling product confirmation based on product type.
 *
 * Each processor handles a specific product type:
 * - Simple products
 * - Grouped products
 * - Variable products
 *
 * @since 1.0.0
 */
interface Product_Confirmation_Processor_Interface {

	/**
	 * Process product confirmation.
	 *
	 * Handles the product confirmation flow based on the product type.
	 * This may include adding to cart, asking for variants, or other actions.
	 *
	 * @param  WC_Product  $product  The WooCommerce product object.
	 * @param  Chatbot_Utility  $utility  The chatbot utility instance.
	 * @param  string  $user_intent  The user's intent (e.g., 'add_to_cart', 'view_details').
	 *
	 * @return Message|null The response message, or null if unable to process.
	 * @since 1.0.0
	 */
	public function process( WC_Product $product, Chatbot_Utility $utility, string $user_intent ): ?Message;

	/**
	 * Check if this processor can handle the given product type.
	 *
	 * @param  WC_Product  $product  The product to check.
	 *
	 * @return bool True if this processor can handle the product.
	 * @since 1.0.0
	 */
	public static function can_handle( WC_Product $product ): bool;

	/**
	 * Get the product type this processor handles.
	 *
	 * @return string The product type (e.g., 'simple', 'variable', 'grouped').
	 * @since 1.0.0
	 */
	public static function get_product_type(): string;
}
