lib init

mail_intake/adapters/base.py

@@ -0,0 +1,48 @@
+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