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

namespace FrameworkBLL.EIPConversation
{
    /// <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 IEIPConceptBLL
    {
        /// <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="sessionToken">Unique session identifier for the user (phone number, token, or UUID)</param>
        /// <param name="userMessage">Message text received from the user</param>
        /// <param name="loginContext">User login context. If null, session is treated as external/anonymous.</param>
        /// <param name="platformName">Platform name: "TEXT", "WHATSAPP", "TEAMS", "SLACK", "TELEGRAM". Defaults to "TEXT".</param>
        /// <param name="ct">Cancellation token for async operation</param>
        /// <returns>Reply message text generated by the flow engine, including OTP or action responses.</returns>
        Task<string> HandleIncomingMessageAsync(
           string sessionToken,
           string userMessage,
           LoginDTO loginContext,
           string platformName = "POSTMAN",
           CancellationToken ct = default);

    }
}