"""
Mail provider adapter contracts for Mail Intake.

---

## Summary

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:

                {
                    "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