namespace Cauldron.Messages.Contracts;

/// <summary>
/// <para>
/// Channel message contract for the "ReceiveMessage" event.
/// This mirrors the <c>Morgana.AI.Records.ChannelMessage</c> schema emitted by Morgana's
/// <c>IChannelService</c> implementations.
/// </para>
/// <para>
/// CONTRACT VERSION: 1.0<br/>
/// SYNC WITH: Morgana.AI (Records.ChannelMessage)
/// </para>
/// <para>
/// BREAKING CHANGES: Any modification to required fields or removal of fields is a breaking change.
/// SAFE CHANGES: Adding optional fields with default values.
/// </para>
/// <para>
/// ⚠️ IMPORTANT: This DTO is duplicated in Morgana (Morgana.AI.Records.ChannelMessage).
/// When making changes, update both versions and ensure backward compatibility.
/// Test serialization/deserialization compatibility with integration tests.
/// </para>
/// </summary>
/// <remarks>
/// <para><strong>Contract Sync Policy:</strong></para>
/// <list type="bullet">
/// <item>Required fields must match exactly between backend and frontend</item>
/// <item>Optional fields can be added without breaking compatibility (use default values)</item>
/// <item>Field removal or type changes are BREAKING and require coordinated deployment</item>
/// </list>
/// </remarks>
public sealed class ChannelMessage
{
    /// <summary>
    /// Unique identifier of the conversation this message belongs to.
    /// </summary>
    public string ConversationId { get; set; } = string.Empty;

    /// <summary>
    /// Message text to display to the user.
    /// </summary>
    public string Text { get; set; } = string.Empty;

    /// <summary>
    /// UTC timestamp when this message was generated by the backend.
    /// </summary>
    public DateTime Timestamp { get; set; }

    /// <summary>
    /// Type of message for UI rendering and styling.
    /// Valid values: "assistant", "presentation", "system", "system_warning", "error"
    /// </summary>
    public string MessageType { get; set; } = "assistant";

    /// <summary>
    /// Optional list of quick reply buttons for user interaction.
    /// References the existing QuickReply model which is a stable contract from the LLM.
    /// </summary>
    public List<QuickReply>? QuickReplies { get; set; }

    /// <summary>
    /// Optional rich card for structured visual presentation.
    /// When present, renders structured data components instead of plain text formatting.
    /// </summary>
    /// <remarks>
    /// <para>Rich cards are generated by agents via the SetRichCard tool when presenting
    /// complex structured information like invoices, profiles, reports, or comparisons.</para>
    /// <para>The card contains a title, optional subtitle, and an array of visual components
    /// (key-value pairs, lists, sections, badges, etc.) that Cauldron renders using specialized
    /// Razor components.</para>
    /// </remarks>
    public RichCard? RichCard { get; set; }

    /// <summary>
    /// Optional error reason code when MessageType is "error" or "system_warning".
    /// </summary>
    public string? ErrorReason { get; set; }

    /// <summary>
    /// Name of the agent that generated this message.
    /// Examples: "Morgana", "Morgana (Billing)", "Morgana (Technical Support)"
    /// </summary>
    public string AgentName { get; set; } = "Morgana";

    /// <summary>
    /// Indicates whether this specialized agent has completed its task.
    /// When true, UI should return to default Morgana state.
    /// </summary>
    public bool AgentCompleted { get; set; }

    /// <summary>
    /// Duration of the eventual fading message which will be generated
    /// by this channel message (depending on its MessageType).
    /// </summary>
    public int? FadingMessageDurationSeconds { get; set; } = 10;

    /// <summary>
    /// Conversation-level metadata (e.g. remaining dust budget). Characterises the
    /// conversation, not this message. Null when no such metadata is available.
    /// </summary>
    public ConversationMetadata? ConversationMetadata { get; set; }
}
