<?php

namespace AIPT\Api\Chatbot;

/**
 * Interface for action registry.
 *
 * @package AIPT\Api\Chatbot
 * @since 2.5.0
 */
interface ActionRegistryInterface {

    /**
     * Register a new action.
     *
     * @param ChatActionInterface $action Action instance.
     * @return void
     * @throws \InvalidArgumentException If action ID already registered.
     */
    public function register(ChatActionInterface $action): void;

    /**
     * Unregister an action by ID.
     *
     * @param string $action_id Action identifier.
     * @return bool True if action was removed.
     */
    public function unregister(string $action_id): bool;

    /**
     * Get all registered actions.
     *
     * @return ChatActionInterface[] Array of actions sorted by priority.
     */
    public function getAll(): array;

    /**
     * Get actions available for a specific product.
     *
     * @param int $product_id WooCommerce product ID.
     * @return ChatActionInterface[] Available actions.
     */
    public function getAvailableForProduct(int $product_id): array;

    /**
     * Get a specific action by ID.
     *
     * @param string $action_id Action identifier.
     * @return ChatActionInterface|null Action instance or null.
     */
    public function get(string $action_id): ?ChatActionInterface;

    /**
     * Execute an action.
     *
     * @param string $action_id  Action identifier.
     * @param int    $product_id WooCommerce product ID.
     * @param array  $params     Additional parameters.
     * @return array Execution result.
     * @throws \InvalidArgumentException If action not found.
     */
    public function execute(string $action_id, int $product_id, array $params = []): array;
}
