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 for
    read-only mail ingestion. No provider-specific concepts
    should leak beyond implementations of this class.
    """

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

        Must yield dictionaries containing at least:
        - message_id
        - thread_id

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

        Returns the provider-native message payload
        (e.g., Gmail message JSON).
        """
        raise NotImplementedError

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

        Returns the provider-native thread payload.
        """
        raise NotImplementedError