<?php

namespace AIPT\Api\Chatbot;

/**
 * Interface for chat actions (product card buttons).
 *
 * Implement this interface to create custom actions that can be
 * triggered from product cards in the chatbot.
 *
 * @package AIPT\Api\Chatbot
 * @since 2.5.0
 */
interface ChatActionInterface {

    /**
     * Get unique action identifier.
     *
     * @return string Action ID (e.g., 'view_product', 'add_to_cart').
     */
    public function getId(): string;

    /**
     * Get action label for button.
     *
     * @param string $language Language code for translation.
     * @return string Translated label.
     */
    public function getLabel(string $language = 'en'): string;

    /**
     * Get action icon identifier.
     *
     * @return string Icon name (CSS class or SVG reference).
     */
    public function getIcon(): string;

    /**
     * Check if action is available for a specific product.
     *
     * @param int $product_id WooCommerce product ID.
     * @return bool True if action can be performed.
     */
    public function isAvailable(int $product_id): bool;

    /**
     * Execute the action.
     *
     * @param int   $product_id WooCommerce product ID.
     * @param array $params     Additional parameters from request.
     * @return array{success: bool, message?: string, data?: array}
     */
    public function execute(int $product_id, array $params = []): array;

    /**
     * Get action priority for ordering.
     *
     * Lower numbers appear first. Default actions:
     * - view_product: 10
     * - add_to_cart: 20
     *
     * @return int Priority value.
     */
    public function getPriority(): int;
}
