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

    This interface defines the minimal contract required to:
    - Discover messages matching a query
    - Retrieve full message payloads
    - Retrieve full thread payloads

    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.

        Implementations must yield dictionaries containing at least:
        - ``message_id``: Provider-specific message identifier
        - ``thread_id``: Provider-specific thread identifier

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

        Yields:
            Dictionaries containing message and thread identifiers.

        Example 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: Provider-specific message identifier.

        Returns:
            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: Provider-specific thread identifier.

        Returns:
            Provider-native thread payload.
        """
        raise NotImplementedError