93 lines
2.4 KiB
Python
93 lines
2.4 KiB
Python
"""
|
|
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
|