<?php

namespace AIPT\Api\Chatbot;

/**
 * Interface for message queue operations.
 *
 * @package AIPT\Api\Chatbot
 * @since 2.5.0
 */
interface MessageQueueInterface {

    /**
     * Queue a message for later processing.
     *
     * @param string   $message           Customer's message.
     * @param string   $session_id        Session identifier.
     * @param string   $error_msg         Optional error message for logging.
     * @param string   $user_name         Optional user name from pre-chat form.
     * @param string   $user_email        Optional user email from pre-chat form.
     * @param bool     $consent_given     Whether user gave consent for PII storage.
     * @param int|null $consent_timestamp Unix timestamp when consent was given.
     * @return int Queue record ID.
     */
    public function enqueue(
        string $message,
        string $session_id,
        string $error_msg = '',
        string $user_name = '',
        string $user_email = '',
        bool $consent_given = false,
        ?int $consent_timestamp = null
    ): int;

    /**
     * Get queued messages.
     *
     * @param string $status   Filter by status.
     * @param int    $page     Page number.
     * @param int    $per_page Items per page.
     * @return array{messages: array, total: int, pages: int}
     */
    public function getQueued(string $status = 'queued', int $page = 1, int $per_page = 20): array;

    /**
     * Get a single queued message by ID.
     *
     * @param int $id Queue record ID.
     * @return array|null Message data or null if not found.
     */
    public function get(int $id): ?array;

    /**
     * Mark message as responded with admin response.
     *
     * @param int    $id       Queue record ID.
     * @param string $response Admin's response text.
     * @return bool True on success.
     */
    public function markResponded(int $id, string $response): bool;

    /**
     * Mark message as responded with AI response (from retry).
     *
     * @param int    $id          Queue record ID.
     * @param string $ai_response AI-generated response.
     * @return bool True on success.
     */
    public function markRetriedSuccess(int $id, string $ai_response): bool;

    /**
     * Record a successfully answered chatbot exchange.
     *
     * @param string $message     Customer's message.
     * @param string $session_id  Session identifier.
     * @param string $ai_response AI-generated response.
     * @return int Queue record ID.
     */
    public function recordSuccessfulExchange(
        string $message,
        string $session_id,
        string $ai_response
    ): int;

    /**
     * Increment retry count and optionally mark as failed.
     *
     * @param int    $id        Queue record ID.
     * @param string $error_msg Error message from retry attempt.
     * @return bool True on success, false if max retries reached.
     */
    public function incrementRetry(int $id, string $error_msg = ''): bool;

    /**
     * Delete a queued message.
     *
     * @param int $id Queue record ID.
     * @return bool True on success.
     */
    public function delete(int $id): bool;

    /**
     * Get messages pending retry.
     *
     * @param int $limit Maximum messages to retrieve.
     * @return array Array of queue records.
     */
    public function getPendingRetry(int $limit = 10): array;

    /**
     * Clean up old records.
     *
     * @param int $days_old Delete records older than this many days.
     * @return int Number of records deleted.
     */
    public function cleanup(int $days_old = 30): int;
}
