"""
Message domain models for Mail Intake.

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.

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

    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)."""