<?php

namespace AIPT\Api\Chatbot;

/**
 * Interface for chatbot service operations.
 *
 * @package AIPT\Api\Chatbot
 * @since 2.5.0
 */
interface ChatbotServiceInterface {

    /**
     * Process a customer message and generate AI response.
     *
     * @param string $message    Customer's message.
     * @param string $session_id UUID session identifier.
     * @param array  $history    Conversation history for context.
     * @return array{
     *     success: bool,
     *     response?: string,
     *     products?: array,
     *     queued?: bool,
     *     queue_id?: int,
     *     error?: string
     * }
     * @throws \InvalidArgumentException If message or session_id invalid.
     */
    public function processMessage(string $message, string $session_id, array $history = []): array;

    /**
     * Check if chatbot is available for use.
     *
     * @return bool True if enabled and index available.
     */
    public function isAvailable(): bool;

    /**
     * Get product recommendations for a query.
     *
     * @param string $query      Natural language query.
     * @param int    $max_results Maximum products to return.
     * @return array Array of product data.
     */
    public function getProductRecommendations(string $query, int $max_results = 3): array;

    /**
     * Format products for chat response.
     *
     * @param array $products Raw product data from index.
     * @return array Formatted product cards.
     */
    public function formatProductCards(array $products): array;
}
