sendandretain 0.2.0__py3-none-any.whl

sendandretain/__init__.py

@@ -0,0 +1,67 @@
+"""Send & Retain — Python SDK.
+
+    >>> from sendandretain import SendAndRetain
+    >>> client = SendAndRetain()  # reads SENDANDRETAIN_API_KEY  # doctest: +SKIP
+    >>> email = client.emails.send(to="jane@acme.com", template="welcome")  # doctest: +SKIP
+
+Three layers, top to bottom:
+
+- `SendAndRetain` / `AsyncSendAndRetain` — one method per operation, typed
+  keyword arguments, typed exceptions. Generated from `openapi.json` by
+  `scripts/generate_facade.py` into `_resources.py`.
+- `sendandretain.api` / `sendandretain.models` — the full generated client, for
+  anything the facade does not shape the way you need.
+- `_runtime.py` — the transport (retries, idempotency, User-Agent), synced from
+  the Send & Retain source tree.
+"""
+
+from __future__ import annotations
+
+from . import api, errors, models, types
+from ._client import AsyncSendAndRetain, SendAndRetain
+from ._convenience import API_KEY_ENV_VAR, API_KEY_PREFIX, DEFAULT_BASE_URL, Client
+from ._exceptions import (
+    APIConnectionError,
+    APIError,
+    AuthenticationError,
+    ConflictError,
+    InvalidRequestError,
+    NotFoundError,
+    PermissionDeniedError,
+    QuotaExceededError,
+    RateLimitError,
+    SendAndRetainError,
+    WebhookVerificationError,
+)
+from ._version import __version__
+from ._webhooks import verify_webhook
+from .client import AuthenticatedClient
+from .client import Client as RawClient
+
+__all__ = [
+    "API_KEY_ENV_VAR",
+    "API_KEY_PREFIX",
+    "DEFAULT_BASE_URL",
+    "APIConnectionError",
+    "APIError",
+    "AsyncSendAndRetain",
+    "AuthenticatedClient",
+    "AuthenticationError",
+    "Client",
+    "ConflictError",
+    "InvalidRequestError",
+    "NotFoundError",
+    "PermissionDeniedError",
+    "QuotaExceededError",
+    "RateLimitError",
+    "RawClient",
+    "SendAndRetain",
+    "SendAndRetainError",
+    "WebhookVerificationError",
+    "__version__",
+    "api",
+    "errors",
+    "models",
+    "types",
+    "verify_webhook",
+]

sendandretain/_base.py

@@ -0,0 +1,93 @@
+"""Plumbing shared by every generated resource method in `_resources.py`.
+
+A facade method hands its operation's generated module and plain Python values
+to `_call`; this turns the body into the generated model, invokes the module's
+`sync_detailed` / `asyncio_detailed`, and returns the parsed success model or
+raises a typed `SendAndRetainError`. The per-operation knowledge — which
+arguments are path, query or body — lives in the generated method signatures.
+"""
+
+from __future__ import annotations
+
+import inspect
+import json
+import types
+import typing
+from functools import cache
+from typing import Any
+
+import httpx
+
+from ._exceptions import APIConnectionError, error_for
+
+__all__ = ["AsyncResource", "Resource", "invoke", "ainvoke"]
+
+
+@cache
+def _body_model(module: types.ModuleType) -> Any:
+    """The attrs model the module's `body` parameter takes, or None."""
+    param = inspect.signature(module.sync_detailed).parameters.get("body")
+    if param is None:
+        return None
+    hint = typing.get_type_hints(module.sync_detailed).get("body", param.annotation)
+    for candidate in (hint, *typing.get_args(hint)):
+        if hasattr(candidate, "from_dict"):
+            return candidate
+    return None
+
+
+def _kwargs(module: types.ModuleType, body: dict[str, Any] | None, params: dict[str, Any]) -> dict[str, Any]:
+    kwargs = {k: v for k, v in params.items() if v is not None}
+    if body is not None:
+        model = _body_model(module)
+        compact = {k: v for k, v in body.items() if v is not None}
+        kwargs["body"] = model.from_dict(compact) if model is not None else compact
+    return kwargs
+
+
+def _result(response: Any) -> Any:
+    status = int(response.status_code)
+    if 200 <= status < 300:
+        if response.parsed is not None:
+            return response.parsed
+        try:
+            return json.loads(response.content) if response.content else None
+        except ValueError:
+            return None
+    try:
+        payload = json.loads(response.content) if response.content else None
+    except ValueError:
+        payload = None
+    raise error_for(status, payload, response.headers.get("X-Request-Id"))
+
+
+def invoke(raw: Any, module: types.ModuleType, body: dict[str, Any] | None, params: dict[str, Any]) -> Any:
+    try:
+        response = module.sync_detailed(client=raw, **_kwargs(module, body, params))
+    except httpx.TransportError as exc:
+        raise APIConnectionError(str(exc) or type(exc).__name__, code="network_error") from exc
+    return _result(response)
+
+
+async def ainvoke(raw: Any, module: types.ModuleType, body: dict[str, Any] | None, params: dict[str, Any]) -> Any:
+    try:
+        response = await module.asyncio_detailed(client=raw, **_kwargs(module, body, params))
+    except httpx.TransportError as exc:
+        raise APIConnectionError(str(exc) or type(exc).__name__, code="network_error") from exc
+    return _result(response)
+
+
+class Resource:
+    def __init__(self, client: Any) -> None:
+        self._raw = client
+
+    def _call(self, module: types.ModuleType, *, body: dict[str, Any] | None = None, **params: Any) -> Any:
+        return invoke(self._raw, module, body, params)
+
+
+class AsyncResource:
+    def __init__(self, client: Any) -> None:
+        self._raw = client
+
+    async def _call(self, module: types.ModuleType, *, body: dict[str, Any] | None = None, **params: Any) -> Any:
+        return await ainvoke(self._raw, module, body, params)

sendandretain/_client.py

@@ -0,0 +1,112 @@
+"""`SendAndRetain` and `AsyncSendAndRetain` — the clients most code should use."""
+
+from __future__ import annotations
+
+from typing import Any
+
+import httpx
+
+from ._resources import AsyncResources, Resources
+from ._runtime import (
+    DEFAULT_MAX_RETRIES,
+    DEFAULT_TIMEOUT_SECONDS,
+    AsyncRetryTransport,
+    RetryTransport,
+    resolve_api_key,
+    resolve_base_url,
+)
+from ._version import __version__
+from ._webhooks import verify_webhook
+from .client import AuthenticatedClient
+
+__all__ = ["AsyncSendAndRetain", "SendAndRetain"]
+
+
+def _raw_client(key: str, base_url: str, timeout: float, transport: Any) -> AuthenticatedClient:
+    return AuthenticatedClient(
+        base_url=base_url,
+        token=key,
+        prefix="Bearer",
+        timeout=httpx.Timeout(timeout),
+        httpx_args={"transport": transport},
+    )
+
+
+class SendAndRetain(Resources):
+    """The Send & Retain client.
+
+    >>> from sendandretain import SendAndRetain
+    >>> client = SendAndRetain()  # reads SENDANDRETAIN_API_KEY  # doctest: +SKIP
+    >>> email = client.emails.send(to="jane@acme.com", template="welcome")  # doctest: +SKIP
+    >>> email.id  # doctest: +SKIP
+
+    Methods return the parsed model and raise a `SendAndRetainError` subclass on
+    any failure. Requests that fail with 408/429/5xx or a network error are
+    retried with backoff; every POST carries an `Idempotency-Key` (yours, or a
+    generated one) so a retry can never do the work twice.
+    """
+
+    def __init__(
+        self,
+        api_key: str | None = None,
+        *,
+        base_url: str | None = None,
+        timeout: float = DEFAULT_TIMEOUT_SECONDS,
+        max_retries: int = DEFAULT_MAX_RETRIES,
+        transport: httpx.BaseTransport | None = None,
+    ) -> None:
+        key = resolve_api_key(api_key)
+        retry = RetryTransport(key, __version__, max_retries=max_retries, transport=transport)
+        #: The generated client, for `sendandretain.api.*` functions directly.
+        self.raw = _raw_client(key, resolve_base_url(base_url), timeout, retry)
+        super().__init__(self.raw)
+
+    @staticmethod
+    def verify_webhook(payload: str | bytes, headers: Any, secret: str) -> dict[str, Any]:
+        """Verify a webhook delivery and return the event. See `sendandretain.verify_webhook`."""
+        return verify_webhook(payload, headers, secret)
+
+    def close(self) -> None:
+        self.raw.get_httpx_client().close()
+
+    def __enter__(self) -> SendAndRetain:
+        return self
+
+    def __exit__(self, *_: object) -> None:
+        self.close()
+
+
+class AsyncSendAndRetain(AsyncResources):
+    """The asyncio twin of `SendAndRetain`: same resources, every method awaitable.
+
+    >>> async with AsyncSendAndRetain() as client:  # doctest: +SKIP
+    ...     email = await client.emails.send(to="jane@acme.com", template="welcome")
+    """
+
+    def __init__(
+        self,
+        api_key: str | None = None,
+        *,
+        base_url: str | None = None,
+        timeout: float = DEFAULT_TIMEOUT_SECONDS,
+        max_retries: int = DEFAULT_MAX_RETRIES,
+        transport: httpx.AsyncBaseTransport | None = None,
+    ) -> None:
+        key = resolve_api_key(api_key)
+        retry = AsyncRetryTransport(key, __version__, max_retries=max_retries, transport=transport)
+        self.raw = _raw_client(key, resolve_base_url(base_url), timeout, retry)
+        super().__init__(self.raw)
+
+    @staticmethod
+    def verify_webhook(payload: str | bytes, headers: Any, secret: str) -> dict[str, Any]:
+        """Verify a webhook delivery and return the event. Synchronous — it does no I/O."""
+        return verify_webhook(payload, headers, secret)
+
+    async def close(self) -> None:
+        await self.raw.get_async_httpx_client().aclose()
+
+    async def __aenter__(self) -> AsyncSendAndRetain:
+        return self
+
+    async def __aexit__(self, *_: object) -> None:
+        await self.close()

sendandretain/_convenience.py

@@ -0,0 +1,76 @@
+"""The hand-written convenience layer over the generated client.
+
+Deliberately thin, and one of only two hand-written modules in the package.
+Everything beside it under `sendandretain/` is generated from `openapi.json` and is the
+contract; this module exists only so callers need not remember the base URL,
+spell `AuthenticatedClient`, or wire up the `Bearer` prefix by hand.
+
+Kept out of `__init__.py` so that regeneration, which rewrites `client.py`,
+`api/`, `models/`, `types.py` and `errors.py` wholesale, can never clobber it.
+"""
+
+from __future__ import annotations
+
+import os
+
+import httpx
+
+from .client import AuthenticatedClient
+
+__all__ = ["API_KEY_ENV_VAR", "API_KEY_PREFIX", "DEFAULT_BASE_URL", "Client"]
+
+DEFAULT_BASE_URL = "https://sendandretain.com"
+"""Production base URL for the Send & Retain API."""
+
+API_KEY_PREFIX = "aem_"
+"""Every Send & Retain API key starts with this. The server rejects anything else
+before it touches the database, so checking it here turns a 401 into a
+`ValueError` that names the actual problem."""
+
+API_KEY_ENV_VAR = "SENDANDRETAIN_API_KEY"
+"""Consulted when `api_key` is not passed explicitly."""
+
+
+def Client(  # noqa: N802 - a factory that reads as a constructor at the call site
+    api_key: str | None = None,
+    *,
+    base_url: str = DEFAULT_BASE_URL,
+    timeout: httpx.Timeout | float | None = None,
+    raise_on_unexpected_status: bool = False,
+    **kwargs: object,
+) -> AuthenticatedClient:
+    """Build an authenticated client for the Send & Retain API.
+
+    Args:
+        api_key: A `aem_…` key. Falls back to `$SENDANDRETAIN_API_KEY`.
+        base_url: Override only to target a non-production deployment.
+        timeout: Passed through to httpx. Seconds, or an `httpx.Timeout`.
+        raise_on_unexpected_status: Raise `errors.UnexpectedStatus` on a status
+            the spec does not document, instead of returning `None`.
+        **kwargs: Forwarded to the generated `AuthenticatedClient` — `headers`,
+            `cookies`, `verify_ssl`, `follow_redirects`, `httpx_args`.
+
+    Returns:
+        An `AuthenticatedClient` accepted by every function in
+        `sendandretain.api.*` as the `client=` argument.
+
+    Raises:
+        ValueError: No key was supplied, or it does not look like a Send & Retain key.
+    """
+    key = api_key if api_key is not None else os.environ.get(API_KEY_ENV_VAR)
+    if not key:
+        raise ValueError(f"No API key. Pass Client(api_key=...) or set ${API_KEY_ENV_VAR}.")
+    if not key.startswith(API_KEY_PREFIX):
+        raise ValueError(f"Send & Retain API keys start with {API_KEY_PREFIX!r}; got {key[:8]!r}…")
+
+    if isinstance(timeout, (int, float)):
+        timeout = httpx.Timeout(timeout)
+
+    return AuthenticatedClient(
+        base_url=base_url,
+        token=key,
+        prefix="Bearer",
+        timeout=timeout,
+        raise_on_unexpected_status=raise_on_unexpected_status,
+        **kwargs,  # type: ignore[arg-type]
+    )

sendandretain/_exceptions.py

@@ -0,0 +1,106 @@
+"""Typed exceptions. Every API error raised by the facade is a `SendAndRetainError`."""
+
+from __future__ import annotations
+
+from typing import Any
+
+__all__ = [
+    "APIConnectionError",
+    "APIError",
+    "AuthenticationError",
+    "ConflictError",
+    "InvalidRequestError",
+    "NotFoundError",
+    "PermissionDeniedError",
+    "QuotaExceededError",
+    "RateLimitError",
+    "SendAndRetainError",
+    "WebhookVerificationError",
+]
+
+
+class SendAndRetainError(Exception):
+    """Base class. Branch on `code`; quote `request_id` to support."""
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        code: str,
+        status: int | None = None,
+        request_id: str | None = None,
+        body: dict[str, Any] | None = None,
+    ) -> None:
+        super().__init__(message)
+        self.message = message
+        self.code = code
+        self.status = status
+        self.request_id = request_id
+        #: The full `error` object, including fields like `required_scope`.
+        self.body = body or {}
+
+    def __str__(self) -> str:
+        ref = f" (request_id {self.request_id})" if self.request_id else ""
+        return f"{self.code}: {self.message}{ref}"
+
+
+class APIError(SendAndRetainError):
+    """Any error response not covered by a more specific class — 5xx included."""
+
+
+class InvalidRequestError(APIError):
+    """400 / 422: the request itself is wrong. Nothing changed; fix and resend."""
+
+
+class AuthenticationError(APIError):
+    """401: missing, invalid, revoked or expired key."""
+
+
+class PermissionDeniedError(APIError):
+    """403: the key is valid but lacks the scope or the send grant. See `body["required_scope"]`."""
+
+
+class NotFoundError(APIError):
+    """404: no such resource in this project."""
+
+
+class ConflictError(APIError):
+    """409: an idempotency conflict, or the resource's state forbids the action."""
+
+
+class RateLimitError(APIError):
+    """429 `rate_limited`, after the SDK's own retries were exhausted."""
+
+
+class QuotaExceededError(APIError):
+    """429 `daily_cap` / `monthly_cap`: a sending quota, not a throttle. Never retried."""
+
+
+class APIConnectionError(SendAndRetainError):
+    """No response arrived: DNS, TLS, a reset connection, or a timeout."""
+
+
+class WebhookVerificationError(SendAndRetainError):
+    """A webhook's signature or timestamp did not verify. Answer 400 and do nothing else."""
+
+
+def error_for(status: int, payload: Any, request_id: str | None) -> APIError:
+    envelope = payload.get("error") if isinstance(payload, dict) else None
+    envelope = envelope if isinstance(envelope, dict) else {}
+    code = str(envelope.get("code") or f"http_{status}")
+    message = str(envelope.get("message") or f"HTTP {status}")
+    rid = envelope.get("request_id") or request_id
+    cls: type[APIError]
+    if code in ("daily_cap", "monthly_cap"):
+        cls = QuotaExceededError
+    elif status in (400, 422):
+        cls = InvalidRequestError
+    else:
+        cls = {
+            401: AuthenticationError,
+            403: PermissionDeniedError,
+            404: NotFoundError,
+            409: ConflictError,
+            429: RateLimitError,
+        }.get(status, APIError)
+    return cls(message, code=code, status=status, request_id=rid, body=envelope)