mailcue 0.1.0__py3-none-any.whl

mailcue/__init__.py

@@ -0,0 +1,110 @@
+"""MailCue Python SDK.
+
+Drop-in client for the MailCue REST API. Both ``Mailcue`` (sync) and
+``AsyncMailcue`` (async) clients expose the same resource surface:
+``emails``, ``mailboxes``, ``domains``, ``aliases``, ``gpg``,
+``api_keys``, ``system``, and the SSE ``events`` stream.
+
+Example:
+    >>> from mailcue import Mailcue
+    >>> client = Mailcue(api_key="mc_...")
+    >>> client.emails.send(
+    ...     from_="hello@example.com",
+    ...     to=["user@example.com"],
+    ...     subject="Welcome",
+    ...     html="<h1>Hi</h1>",
+    ... )
+"""
+
+from __future__ import annotations
+
+from mailcue._version import __version__
+from mailcue.client import AsyncMailcue, Mailcue
+from mailcue.exceptions import (
+    AuthenticationError,
+    AuthorizationError,
+    ConflictError,
+    MailcueError,
+    NetworkError,
+    NotFoundError,
+    RateLimitError,
+    ServerError,
+    TimeoutError,
+    ValidationError,
+)
+from mailcue.transport import DEFAULT_BASE_URL
+from mailcue.types import (
+    Alias,
+    AliasListResponse,
+    ApiKey,
+    AttachmentInfo,
+    BulkInjectResponse,
+    CreatedApiKey,
+    DnsCheckResponse,
+    DnsRecordInfo,
+    Domain,
+    DomainDetail,
+    DomainListResponse,
+    EmailDetail,
+    EmailListResponse,
+    EmailSummary,
+    Event,
+    FolderInfo,
+    GpgEmailInfo,
+    GpgKey,
+    GpgKeyExport,
+    GpgKeyListResponse,
+    HealthResponse,
+    KeyserverPublishResult,
+    Mailbox,
+    MailboxListResponse,
+    MailboxStats,
+    SendResult,
+    SignatureStatus,
+    TlsCertificateStatus,
+)
+
+__all__ = [
+    "DEFAULT_BASE_URL",
+    "Alias",
+    "AliasListResponse",
+    "ApiKey",
+    "AsyncMailcue",
+    "AttachmentInfo",
+    "AuthenticationError",
+    "AuthorizationError",
+    "BulkInjectResponse",
+    "ConflictError",
+    "CreatedApiKey",
+    "DnsCheckResponse",
+    "DnsRecordInfo",
+    "Domain",
+    "DomainDetail",
+    "DomainListResponse",
+    "EmailDetail",
+    "EmailListResponse",
+    "EmailSummary",
+    "Event",
+    "FolderInfo",
+    "GpgEmailInfo",
+    "GpgKey",
+    "GpgKeyExport",
+    "GpgKeyListResponse",
+    "HealthResponse",
+    "KeyserverPublishResult",
+    "Mailbox",
+    "MailboxListResponse",
+    "MailboxStats",
+    "Mailcue",
+    "MailcueError",
+    "NetworkError",
+    "NotFoundError",
+    "RateLimitError",
+    "SendResult",
+    "ServerError",
+    "SignatureStatus",
+    "TimeoutError",
+    "TlsCertificateStatus",
+    "ValidationError",
+    "__version__",
+]

mailcue/_version.py

@@ -0,0 +1,5 @@
+"""Single source of truth for the package version."""
+
+from __future__ import annotations
+
+__version__ = "0.1.0"

mailcue/auth.py

@@ -0,0 +1,50 @@
+"""Auth header builders.
+
+MailCue accepts either an API key (``X-API-Key: mc_...``) or a JWT bearer
+token (``Authorization: Bearer ...``). The transport calls ``headers()``
+on the configured strategy for each request.
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import Dict
+
+
+class AuthStrategy(ABC):
+    """Strategy that produces auth headers for outgoing requests."""
+
+    @abstractmethod
+    def headers(self) -> Dict[str, str]:
+        """Return the headers to merge into each request."""
+
+
+class ApiKeyAuth(AuthStrategy):
+    """Authenticate using a MailCue API key."""
+
+    def __init__(self, api_key: str) -> None:
+        if not api_key:
+            raise ValueError("api_key must not be empty")
+        self._api_key = api_key
+
+    def headers(self) -> Dict[str, str]:
+        return {"X-API-Key": self._api_key}
+
+
+class BearerAuth(AuthStrategy):
+    """Authenticate using a JWT bearer token."""
+
+    def __init__(self, token: str) -> None:
+        if not token:
+            raise ValueError("token must not be empty")
+        self._token = token
+
+    def headers(self) -> Dict[str, str]:
+        return {"Authorization": f"Bearer {self._token}"}
+
+
+class NoAuth(AuthStrategy):
+    """No-op strategy used for unauthenticated endpoints (e.g. /health)."""
+
+    def headers(self) -> Dict[str, str]:
+        return {}

mailcue/client.py

@@ -0,0 +1,164 @@
+"""Top-level :class:`Mailcue` and :class:`AsyncMailcue` clients."""
+
+from __future__ import annotations
+
+from typing import Optional
+
+import httpx
+
+from mailcue.auth import ApiKeyAuth, AuthStrategy, BearerAuth, NoAuth
+from mailcue.events import AsyncSSEClient, SSEClient
+from mailcue.resources.aliases import Aliases, AsyncAliases
+from mailcue.resources.api_keys import ApiKeys, AsyncApiKeys
+from mailcue.resources.domains import AsyncDomains, Domains
+from mailcue.resources.emails import AsyncEmails, Emails
+from mailcue.resources.gpg import AsyncGpg, Gpg
+from mailcue.resources.mailboxes import AsyncMailboxes, Mailboxes
+from mailcue.resources.system import AsyncSystem, System
+from mailcue.transport import (
+    DEFAULT_BASE_URL,
+    AsyncTransport,
+    SyncTransport,
+    build_config,
+)
+
+
+def _resolve_auth(
+    api_key: Optional[str],
+    bearer_token: Optional[str],
+) -> AuthStrategy:
+    if api_key and bearer_token:
+        raise ValueError("Pass either api_key or bearer_token, not both")
+    if api_key:
+        return ApiKeyAuth(api_key)
+    if bearer_token:
+        return BearerAuth(bearer_token)
+    return NoAuth()
+
+
+class Mailcue:
+    """Synchronous MailCue API client.
+
+    Example:
+        >>> from mailcue import Mailcue
+        >>> client = Mailcue(api_key="mc_...", base_url="https://mail.example.com")
+        >>> client.emails.send(
+        ...     from_="hello@example.com",
+        ...     to=["user@example.com"],
+        ...     subject="Hi",
+        ...     html="<h1>Hello</h1>",
+        ... )
+    """
+
+    def __init__(
+        self,
+        *,
+        api_key: Optional[str] = None,
+        bearer_token: Optional[str] = None,
+        base_url: Optional[str] = None,
+        timeout: float = 30.0,
+        max_retries: int = 3,
+        backoff_base: float = 0.5,
+        backoff_cap: float = 8.0,
+        verify: bool = True,
+        http_client: Optional[httpx.Client] = None,
+    ) -> None:
+        auth = _resolve_auth(api_key, bearer_token)
+        config = build_config(
+            base_url=base_url,
+            timeout=timeout,
+            max_retries=max_retries,
+            backoff_base=backoff_base,
+            backoff_cap=backoff_cap,
+            verify=verify,
+        )
+        self._transport = SyncTransport(config, auth, client=http_client)
+        self.emails = Emails(self._transport)
+        self.mailboxes = Mailboxes(self._transport)
+        self.domains = Domains(self._transport)
+        self.aliases = Aliases(self._transport)
+        self.gpg = Gpg(self._transport)
+        self.api_keys = ApiKeys(self._transport)
+        self.system = System(self._transport)
+        self.events = SSEClient(self._transport)
+
+    @property
+    def base_url(self) -> str:
+        return self._transport.base_url
+
+    def close(self) -> None:
+        """Close the underlying HTTP client (only if owned by this client)."""
+        self._transport.close()
+
+    def __enter__(self) -> "Mailcue":
+        return self
+
+    def __exit__(self, *_: object) -> None:
+        self.close()
+
+
+class AsyncMailcue:
+    """Asynchronous MailCue API client.
+
+    Example:
+        >>> import asyncio
+        >>> from mailcue import AsyncMailcue
+        >>> async def main() -> None:
+        ...     async with AsyncMailcue(api_key="mc_...") as client:
+        ...         await client.emails.send(
+        ...             from_="hello@example.com",
+        ...             to=["user@example.com"],
+        ...             subject="Hi",
+        ...             html="<h1>Hello</h1>",
+        ...         )
+        >>> asyncio.run(main())
+    """
+
+    def __init__(
+        self,
+        *,
+        api_key: Optional[str] = None,
+        bearer_token: Optional[str] = None,
+        base_url: Optional[str] = None,
+        timeout: float = 30.0,
+        max_retries: int = 3,
+        backoff_base: float = 0.5,
+        backoff_cap: float = 8.0,
+        verify: bool = True,
+        http_client: Optional[httpx.AsyncClient] = None,
+    ) -> None:
+        auth = _resolve_auth(api_key, bearer_token)
+        config = build_config(
+            base_url=base_url,
+            timeout=timeout,
+            max_retries=max_retries,
+            backoff_base=backoff_base,
+            backoff_cap=backoff_cap,
+            verify=verify,
+        )
+        self._transport = AsyncTransport(config, auth, client=http_client)
+        self.emails = AsyncEmails(self._transport)
+        self.mailboxes = AsyncMailboxes(self._transport)
+        self.domains = AsyncDomains(self._transport)
+        self.aliases = AsyncAliases(self._transport)
+        self.gpg = AsyncGpg(self._transport)
+        self.api_keys = AsyncApiKeys(self._transport)
+        self.system = AsyncSystem(self._transport)
+        self.events = AsyncSSEClient(self._transport)
+
+    @property
+    def base_url(self) -> str:
+        return self._transport.base_url
+
+    async def aclose(self) -> None:
+        """Close the underlying HTTP client (only if owned by this client)."""
+        await self._transport.aclose()
+
+    async def __aenter__(self) -> "AsyncMailcue":
+        return self
+
+    async def __aexit__(self, *_: object) -> None:
+        await self.aclose()
+
+
+__all__ = ["DEFAULT_BASE_URL", "AsyncMailcue", "Mailcue"]

mailcue/events.py

@@ -0,0 +1,200 @@
+"""Server-Sent Events client (sync + async) with auto-reconnect."""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import logging
+import random
+import time
+from typing import AsyncIterator, Iterator, List, Optional
+
+import httpx
+
+from mailcue.exceptions import MailcueError, NetworkError
+from mailcue.exceptions import TimeoutError as MailcueTimeoutError
+from mailcue.transport import AsyncTransport, SyncTransport
+from mailcue.types import Event
+
+logger = logging.getLogger("mailcue.events")
+
+_RECONNECT_BASE = 0.5
+_RECONNECT_CAP = 30.0
+
+
+def _parse_event(lines: List[str]) -> Optional[Event]:
+    """Parse one SSE block of lines into an :class:`Event`."""
+    event_type = "message"
+    data_lines: List[str] = []
+    event_id: Optional[str] = None
+    retry: Optional[int] = None
+    for line in lines:
+        if not line or line.startswith(":"):
+            continue
+        field, _, value = line.partition(":")
+        if value.startswith(" "):
+            value = value[1:]
+        if field == "event":
+            event_type = value
+        elif field == "data":
+            data_lines.append(value)
+        elif field == "id":
+            event_id = value
+        elif field == "retry":
+            try:
+                retry = int(value)
+            except ValueError:
+                retry = None
+    if not data_lines and event_type == "message":
+        return None
+    raw_data = "\n".join(data_lines)
+    payload: object = {}
+    if raw_data:
+        try:
+            payload = json.loads(raw_data)
+        except json.JSONDecodeError:
+            payload = {"raw": raw_data}
+    if not isinstance(payload, dict):
+        payload = {"value": payload}
+    return Event(event_type=event_type, data=payload, id=event_id, retry=retry)
+
+
+def _reconnect_delay(attempt: int) -> float:
+    raw: float = min(_RECONNECT_CAP, _RECONNECT_BASE * float(2**attempt))
+    jitter: float = raw * 0.2
+    delay: float = raw + random.uniform(-jitter, jitter)
+    return max(0.0, delay)
+
+
+class SSEClient:
+    """Synchronous SSE consumer with exponential-backoff reconnects."""
+
+    def __init__(
+        self,
+        transport: SyncTransport,
+        *,
+        path: str = "/events/stream",
+        reconnect: bool = True,
+    ) -> None:
+        self._transport = transport
+        self._path = path
+        self._reconnect = reconnect
+
+    def __iter__(self) -> Iterator[Event]:
+        return self.stream()
+
+    def stream(self) -> Iterator[Event]:
+        """Yield events forever (or until the server signals close).
+
+        Example:
+            >>> for event in client.events.stream():
+            ...     print(event.event_type, event.data)
+        """
+        attempt = 0
+        while True:
+            try:
+                yield from self._iterate_once()
+                attempt = 0
+                if not self._reconnect:
+                    return
+            except (NetworkError, MailcueTimeoutError, httpx.HTTPError) as exc:
+                if not self._reconnect:
+                    raise
+                delay = _reconnect_delay(attempt)
+                logger.warning(
+                    "SSE connection lost (%s); reconnecting in %.2fs",
+                    exc,
+                    delay,
+                )
+                time.sleep(delay)
+                attempt += 1
+
+    def _iterate_once(self) -> Iterator[Event]:
+        response = self._transport.open_stream(
+            "GET",
+            self._path,
+            headers={"Accept": "text/event-stream", "Cache-Control": "no-cache"},
+            timeout=None,
+        )
+        try:
+            buffer: List[str] = []
+            for line in response.iter_lines():
+                if line == "":
+                    event = _parse_event(buffer)
+                    buffer = []
+                    if event is not None:
+                        yield event
+                else:
+                    buffer.append(line)
+            if buffer:
+                event = _parse_event(buffer)
+                if event is not None:
+                    yield event
+        finally:
+            response.close()
+
+
+class AsyncSSEClient:
+    """Asynchronous SSE consumer with exponential-backoff reconnects."""
+
+    def __init__(
+        self,
+        transport: AsyncTransport,
+        *,
+        path: str = "/events/stream",
+        reconnect: bool = True,
+    ) -> None:
+        self._transport = transport
+        self._path = path
+        self._reconnect = reconnect
+
+    def __aiter__(self) -> AsyncIterator[Event]:
+        return self.stream()
+
+    async def stream(self) -> AsyncIterator[Event]:
+        """Yield events forever (or until the server signals close)."""
+        attempt = 0
+        while True:
+            try:
+                async for event in self._iterate_once():
+                    attempt = 0
+                    yield event
+                if not self._reconnect:
+                    return
+            except (NetworkError, MailcueTimeoutError, httpx.HTTPError) as exc:
+                if not self._reconnect:
+                    raise
+                delay = _reconnect_delay(attempt)
+                logger.warning(
+                    "SSE connection lost (%s); reconnecting in %.2fs",
+                    exc,
+                    delay,
+                )
+                await asyncio.sleep(delay)
+                attempt += 1
+            except MailcueError:
+                raise
+
+    async def _iterate_once(self) -> AsyncIterator[Event]:
+        response = await self._transport.open_stream(
+            "GET",
+            self._path,
+            headers={"Accept": "text/event-stream", "Cache-Control": "no-cache"},
+            timeout=None,
+        )
+        try:
+            buffer: List[str] = []
+            async for line in response.aiter_lines():
+                if line == "":
+                    event = _parse_event(buffer)
+                    buffer = []
+                    if event is not None:
+                        yield event
+                else:
+                    buffer.append(line)
+            if buffer:
+                event = _parse_event(buffer)
+                if event is not None:
+                    yield event
+        finally:
+            await response.aclose()

mailcue/exceptions.py

@@ -0,0 +1,81 @@
+"""Exception hierarchy for the MailCue SDK."""
+
+from __future__ import annotations
+
+from typing import Any, Optional
+
+
+class MailcueError(Exception):
+    """Base class for every error raised by the MailCue SDK."""
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        status_code: Optional[int] = None,
+        detail: Any = None,
+        response_body: Any = None,
+    ) -> None:
+        super().__init__(message)
+        self.message = message
+        self.status_code = status_code
+        self.detail = detail
+        self.response_body = response_body
+
+    def __str__(self) -> str:
+        if self.status_code is not None:
+            return f"[{self.status_code}] {self.message}"
+        return self.message
+
+
+class NetworkError(MailcueError):
+    """Connection failure, DNS error, or other transport-level network issue."""
+
+
+class TimeoutError(MailcueError):
+    """Request exceeded the configured timeout."""
+
+
+class AuthenticationError(MailcueError):
+    """HTTP 401: invalid or missing API key / bearer token."""
+
+
+class AuthorizationError(AuthenticationError):
+    """HTTP 403: caller authenticated but lacks required privileges."""
+
+
+class NotFoundError(MailcueError):
+    """HTTP 404: requested resource does not exist."""
+
+
+class ConflictError(MailcueError):
+    """HTTP 409: request conflicts with current resource state."""
+
+
+class ValidationError(MailcueError):
+    """HTTP 400 or 422: request failed server-side validation."""
+
+
+class RateLimitError(MailcueError):
+    """HTTP 429: caller exceeded the rate limit."""
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        retry_after: Optional[float] = None,
+        status_code: Optional[int] = 429,
+        detail: Any = None,
+        response_body: Any = None,
+    ) -> None:
+        super().__init__(
+            message,
+            status_code=status_code,
+            detail=detail,
+            response_body=response_body,
+        )
+        self.retry_after = retry_after
+
+
+class ServerError(MailcueError):
+    """HTTP 5xx: MailCue server-side failure."""

mailcue/resources/__init__.py

@@ -0,0 +1,3 @@
+"""Resource modules grouping related API endpoints."""
+
+from __future__ import annotations

mailcue/resources/_base.py

@@ -0,0 +1,19 @@
+"""Base classes for API resource bindings."""
+
+from __future__ import annotations
+
+from mailcue.transport import AsyncTransport, SyncTransport
+
+
+class SyncResource:
+    """Resource backed by a synchronous transport."""
+
+    def __init__(self, transport: SyncTransport) -> None:
+        self._transport = transport
+
+
+class AsyncResource:
+    """Resource backed by an asynchronous transport."""
+
+    def __init__(self, transport: AsyncTransport) -> None:
+        self._transport = transport