"""
Defines the ``KurierMessage`` envelope — the standardized message wrapper
that travels across all Kurier transports.
"""

from datetime import datetime, timezone
from typing import Any

from pydantic import BaseModel, Field

from kurier.utilities.uuidv7 import UUIDv7


class KurierMessage(BaseModel):
    """
    Represents a standardized Kurier message (message envelope).

    This model defines the structure for messages transmitted within the Kurier
    system, ensuring consistent metadata and payload encapsulation.

    Attributes:
        timestamp (str): The ISO formatted timestamp (UTC) when the message was created.
        message_id (str): A unique identifier (UUIDv7) for the message.
        correlation_id (str): An identifier used to link related messages across a flow.
        object_type_name (str): The string name of the original Python type of the message payload.
        message_payload (dict[str, Any]): The actual content of the message, typically a
                                           serialized dictionary representation of an object.
        metadata (Optional[dict[str, Any]]): A flexible dictionary for additional, custom metadata.
    """

    timestamp: str = Field(default_factory=lambda: datetime.now(timezone.utc).isoformat())
    message_id: str = Field(default_factory=lambda: str(UUIDv7.get_as_str()))
    correlation_id: str = Field(default_factory=lambda: str(UUIDv7.get_as_str()))
    object_type_name: str
    qualified_object_type_name: str | None = None
    message_payload: dict[str, Any] | Any
    metadata: dict[str, Any] | None = Field(
        None,
        description="A flexible dictionary for additional, custom metadata.",
    )
