"""
Message domain models for Mail Intake.

---

## Summary

This module defines the **canonical, provider-agnostic representation**
of an individual email message as used internally by the Mail Intake
ingestion pipeline.

Models in this module are safe to persist and must not contain any
provider-specific fields or semantics.
"""

from dataclasses import dataclass
from datetime import datetime
from typing import Optional, Dict


@dataclass(frozen=True)
class MailIntakeMessage:
    """
    Canonical internal representation of a single email message.

    Notes:
        **Guarantees:**

            - This model represents a fully parsed and normalized email message
            - It is intentionally provider-agnostic and suitable for persistence, indexing, and downstream processing

        **Constraints:**
        
            - No provider-specific identifiers, payloads, or API semantics should appear in this model
    """

    message_id: str
    """
    Provider-specific message identifier.
    """

    thread_id: str
    """
    Provider-specific thread identifier to which this message belongs.
    """

    timestamp: datetime
    """
    Message timestamp as a timezone-naive UTC datetime.
    """

    from_email: str
    """
    Sender email address.
    """

    from_name: Optional[str]
    """
    Optional human-readable sender name.
    """

    subject: str
    """
    Raw subject line of the message.
    """

    body_text: str
    """
    Extracted plain-text body content of the message.
    """

    snippet: str
    """
    Short provider-supplied preview snippet of the message.
    """

    raw_headers: Dict[str, str]
    """
    Normalized mapping of message headers (header name → value).
    """