using FrameworkDAL.DTO.EIPConversation;
using GB5Shared.DTO.Framework.Login;
using System.Threading;
using System.Threading.Tasks;

namespace FrameworkBLL.EIPConversation.EIPHandlers.EIPConversationBLL
{
    /// <summary>
    /// Conversation-level business logic interface for MessageHub.
    /// Handles dynamic multi-platform conversations (TEXT, WhatsApp, Teams, Slack, Telegram).
    /// Features:
    /// - Trigger-based session initiation
    /// - Multi-step, multi-level flow engine
    /// - INPUT, CHOICE, MESSAGE, ACTION, EXTERNAL_ACTION, OTP, END steps
    /// - Session caching and context management
    /// - Platform-specific message dispatch
    /// </summary>
    public interface IEIPConversationBLL
    {
        /// <summary>
        /// Processes an incoming user message for a given session.
        /// Responsibilities:
        /// 1. Initializes or retrieves the conversation session
        /// 2. Executes triggers or the current flow step
        /// 3. Handles INPUT, CHOICE, MESSAGE, ACTION, EXTERNAL_ACTION, OTP_SEND, OTP_VERIFY, END
        /// 4. Sends reply to the appropriate platform
        /// 5. Updates session status and last activity
        /// </summary>
        /// <param name="payload">Unique session identifier for the user (phone number, token, or UUID)</param>
        /// <param name="loginDTO">User login context. If null, session is treated as external/anonymous.</param>
        /// <param name="cancellationToken">Cancellation token for async operation</param>
        /// <returns>Reply message text generated by the flow engine, including OTP or action responses.</returns>
        Task<EIPExecutionResultDTO> HandleIncomingConversationAsync(
            EIPConversationDTO payload,
            LoginDTO loginDTO,
            CancellationToken cancellationToken);

        Task<EIPExecutionResultDTO> HandleManualConversationRequestAsync(
            int conversationId,
            LoginDTO loginDTO,
            CancellationToken cancellationToken);

    }
}