"""
# Summary

Mail provider adapter contracts for Mail Intake.

This module defines the **provider-agnostic adapter interface** used for
read-only mail ingestion.

Adapters encapsulate all provider-specific access logic and expose a
minimal, normalized contract to the rest of the system. No provider-specific
types or semantics should leak beyond implementations of this interface.
"""

from abc import ABC, abstractmethod
from typing import Iterator, Dict, Any


class MailIntakeAdapter(ABC):
    """
    Base adapter interface for mail providers.

    Notes:
        **Guarantees:**

            - Discover messages matching a query.
            - Retrieve full message payloads.
            - Retrieve full thread payloads.

        **Lifecycle:**

            - Adapters are intentionally read-only and must not mutate provider state.
    """

    @abstractmethod
    def iter_message_refs(self, query: str) -> Iterator[Dict[str, str]]:
        """
        Iterate over lightweight message references matching a query.

        Args:
            query (str):
                Provider-specific query string used to filter messages.

        Yields:
            Dict[str, str]:
                Dictionaries containing message and thread identifiers.

        Notes:
            **Guarantees:**

                - Implementations must yield dictionaries containing at least
                  `message_id` and `thread_id`.

        Example:
            Typical yield:

            ```python
            {
                "message_id": "...",
                "thread_id": "..."
            }
            ```
        """
        raise NotImplementedError

    @abstractmethod
    def fetch_message(self, message_id: str) -> Dict[str, Any]:
        """
        Fetch a full raw message by message identifier.

        Args:
            message_id (str):
                Provider-specific message identifier.

        Returns:
            Dict[str, Any]:
                Provider-native message payload (e.g., Gmail message JSON structure).
        """
        raise NotImplementedError

    @abstractmethod
    def fetch_thread(self, thread_id: str) -> Dict[str, Any]:
        """
        Fetch a full raw thread by thread identifier.

        Args:
            thread_id (str):
                Provider-specific thread identifier.

        Returns:
            Dict[str, Any]:
                Provider-native thread payload.
        """
        raise NotImplementedError