"""
Global configuration models for Mail Intake.

This module defines the **top-level configuration object** used to control
mail ingestion behavior across adapters, authentication providers, and
ingestion workflows.

Configuration is intentionally explicit, immutable, and free of implicit
environment reads to ensure predictability and testability.
"""

from dataclasses import dataclass
from typing import Optional


@dataclass(frozen=True)
class MailIntakeConfig:
    """
    Global configuration for mail-intake.

    This configuration is intentionally explicit and immutable.
    No implicit environment reads or global state.

    Design principles:
    - Immutable once constructed
    - Explicit configuration over implicit defaults
    - No direct environment or filesystem access

    This model is safe to pass across layers and suitable for serialization.
    """

    provider: str = "gmail"
    """Identifier of the mail provider to use (e.g., ``"gmail"``)."""

    user_id: str = "me"
    """Provider-specific user identifier. Defaults to the authenticated user."""

    readonly: bool = True
    """Whether ingestion should operate in read-only mode."""

    credentials_path: Optional[str] = None
    """Optional path to provider credentials configuration."""

    token_path: Optional[str] = None
    """Optional path to persisted authentication tokens."""