replylayer 0.14.0__py3-none-any.whl

replylayer/__init__.py

@@ -0,0 +1,143 @@
+from ._client import ReplyLayer, AsyncReplyLayer
+from ._http import RetryInfo
+from .resources.webhooks import verify_webhook_signature
+from .errors import (
+    ReplyLayerError,
+    AuthenticationError,
+    ForbiddenError,
+    NotFoundError,
+    ValidationError,
+    RateLimitError,
+    WebhookSignatureError,
+    # Migration 040 — scheduled-send error surface.
+    SchedulingError,
+    TimezoneRequiredError,
+)
+from .types import (
+    WebhookSummary,
+    WebhookDeliverySummary,
+    WebhookDeliveryStatus,
+    ListWebhooksResponse,
+    ListDeliveriesResponse,
+    RetryDeliveryResponse,
+    RotateWebhookSecretResponse,
+    TestWebhookResponse,
+    DraftResponse,
+    DraftSummary,
+    ListDraftsResponse,
+    CreateDraftRequest,
+    UpdateDraftRequest,
+    ListDraftsParams,
+    # Outbound attachments (plans/outbound-attachment-ux.md).
+    OutboundAttachmentScanStatus,
+    UploadAttachmentResponse,
+    ConsumedAttachmentResponse,
+    GetUploadAttachmentResponse,
+    # Migration 036 — recipient allowlist types.
+    RecipientPolicyMode,
+    AllowlistEntry,
+    ListAllowlistResponse,
+    AddAllowlistResponse,
+    BulkAddAllowlistResponse,
+    DeleteAllowlistResponse,
+    # Sprint 039 — email-or-domain pattern in allowlist + suppression entries.
+    RecipientPatternType,
+    # Migration 047 — inbound firewall types.
+    SenderPolicyMode,
+    FirewallBlock,
+    # URL-reputation (Google Web Risk) — additive ScanResult fields +
+    # message.received safety signal. Server-side sanitizer enforces
+    # expiry; SDK consumers do not need client-side expiry logic.
+    ScanResult,
+    WebRiskLearnMore,
+    WebRiskWarning,
+    WebRiskThreatType,
+    MessageReceivedSafetySignal,
+    MessageReceivedWebhookPayload,
+    # PR 6 — HITL review queue webhook payload types.
+    HitlMode,
+    MessageReviewOrigin,
+    MessageReviewQueuedWebhookPayload,
+    MessageReviewApprovedWebhookPayload,
+    MessageReviewDeniedWebhookPayload,
+    # PR 7 — scanner-emit HITL review surface.
+    ReviewQueueTriggerSource,
+    # PR 9 — outbound PII safety tuning.
+    OutboundPiiType,
+    OutboundPiiAction,
+    OutboundPiiPolicy,
+    OutboundReviewApprovalNotePolicy,
+    OutboundReviewPolicy,
+    ScannerPolicy,
+)
+
+__version__ = "0.14.0"
+
+__all__ = [
+    "ReplyLayer",
+    "AsyncReplyLayer",
+    "RetryInfo",
+    "verify_webhook_signature",
+    "ReplyLayerError",
+    "AuthenticationError",
+    "ForbiddenError",
+    "NotFoundError",
+    "ValidationError",
+    "RateLimitError",
+    "WebhookSignatureError",
+    # Migration 040 — scheduled-send.
+    "SchedulingError",
+    "TimezoneRequiredError",
+    "WebhookSummary",
+    "WebhookDeliverySummary",
+    "WebhookDeliveryStatus",
+    "ListWebhooksResponse",
+    "ListDeliveriesResponse",
+    "RetryDeliveryResponse",
+    "RotateWebhookSecretResponse",
+    "TestWebhookResponse",
+    "DraftResponse",
+    "DraftSummary",
+    "ListDraftsResponse",
+    "CreateDraftRequest",
+    "UpdateDraftRequest",
+    "ListDraftsParams",
+    # Outbound attachments.
+    "OutboundAttachmentScanStatus",
+    "UploadAttachmentResponse",
+    "ConsumedAttachmentResponse",
+    "GetUploadAttachmentResponse",
+    "RecipientPolicyMode",
+    "AllowlistEntry",
+    "ListAllowlistResponse",
+    "AddAllowlistResponse",
+    "BulkAddAllowlistResponse",
+    "DeleteAllowlistResponse",
+    "RecipientPatternType",
+    # Migration 047 — inbound firewall.
+    "SenderPolicyMode",
+    "FirewallBlock",
+    # URL reputation — Web Risk
+    "ScanResult",
+    "WebRiskLearnMore",
+    "WebRiskWarning",
+    "WebRiskThreatType",
+    "MessageReceivedSafetySignal",
+    "MessageReceivedWebhookPayload",
+    # PR 6 — HITL review queue.
+    "HitlMode",
+    "MessageReviewOrigin",
+    "MessageReviewQueuedWebhookPayload",
+    "MessageReviewApprovedWebhookPayload",
+    "MessageReviewDeniedWebhookPayload",
+    # PR 7 — scanner-emit HITL.
+    "ReviewQueueTriggerSource",
+    # PR 9 — outbound PII safety tuning.
+    "OutboundPiiType",
+    "OutboundPiiAction",
+    "OutboundPiiPolicy",
+    "OutboundReviewApprovalNotePolicy",
+    "OutboundReviewPolicy",
+    "ScannerPolicy",
+    "__version__",
+]

replylayer/_client.py

@@ -0,0 +1,128 @@
+from __future__ import annotations
+
+# typing.Self lands in 3.11; pyproject.toml targets 3.10 (`requires-python
+# = ">=3.10"`), so on 3.10 `from typing import Self` raises ImportError
+# at module load. typing_extensions backports it. Round-2 audit P2 pin:
+# without this, `import replylayer` fails on the advertised floor.
+from typing_extensions import Self
+
+from .errors import ReplyLayerError
+from ._http import SyncHttpClient, AsyncHttpClient, _MAX_RETRY_AFTER_SECONDS, OnRetry
+from .resources.mailboxes import SyncMailboxes, AsyncMailboxes
+from .resources.messages import SyncMessages, AsyncMessages
+from .resources.drafts import SyncDrafts, AsyncDrafts
+from .resources.threads import SyncThreads, AsyncThreads
+from .resources.attachments import SyncAttachments, AsyncAttachments
+from .resources.webhooks import SyncWebhooks, AsyncWebhooks
+from .resources.recipients import SyncRecipients, AsyncRecipients
+from .resources.suppressions import SyncSuppressions, AsyncSuppressions
+from .resources.inbound_blocklist import SyncInboundBlocklist, AsyncInboundBlocklist
+from .resources.api_keys import SyncApiKeys, AsyncApiKeys
+from .resources.account import SyncAccount, AsyncAccount
+from .resources.health import SyncHealth, AsyncHealth
+from .resources.domains import SyncDomains, AsyncDomains
+from .resources.legal_holds import SyncLegalHolds, AsyncLegalHolds
+
+_DEFAULT_BASE_URL = "https://api.replylayer.ai"
+
+
+class ReplyLayer:
+    def __init__(
+        self,
+        *,
+        api_key: str,
+        base_url: str = _DEFAULT_BASE_URL,
+        max_retries: int = 3,
+        timeout: float = 30.0,
+        max_retry_after_seconds: float = _MAX_RETRY_AFTER_SECONDS,
+        on_retry: OnRetry | None = None,
+    ) -> None:
+        if not api_key:
+            raise ReplyLayerError(
+                0, "MISSING_API_KEY",
+                "api_key is required. Get yours at https://app.replylayer.ai/connect",
+            )
+
+        self._http = SyncHttpClient(
+            api_key=api_key,
+            base_url=base_url.rstrip("/"),
+            max_retries=max_retries,
+            timeout=timeout,
+            max_retry_after_seconds=max_retry_after_seconds,
+            on_retry=on_retry,
+        )
+
+        self.domains = SyncDomains(self._http)
+        self.mailboxes = SyncMailboxes(self._http)
+        self.messages = SyncMessages(self._http)
+        self.drafts = SyncDrafts(self._http)
+        self.threads = SyncThreads(self._http)
+        self.attachments = SyncAttachments(self._http)
+        self.webhooks = SyncWebhooks(self._http)
+        self.recipients = SyncRecipients(self._http)
+        self.suppressions = SyncSuppressions(self._http)
+        self.inbound_blocklist = SyncInboundBlocklist(self._http)
+        self.api_keys = SyncApiKeys(self._http)
+        self.account = SyncAccount(self._http)
+        self.health = SyncHealth(self._http)
+        self.legal_holds = SyncLegalHolds(self._http)
+
+    def close(self) -> None:
+        self._http.close()
+
+    def __enter__(self) -> Self:
+        return self
+
+    def __exit__(self, *args: object) -> None:
+        self.close()
+
+
+class AsyncReplyLayer:
+    def __init__(
+        self,
+        *,
+        api_key: str,
+        base_url: str = _DEFAULT_BASE_URL,
+        max_retries: int = 3,
+        timeout: float = 30.0,
+        max_retry_after_seconds: float = _MAX_RETRY_AFTER_SECONDS,
+        on_retry: OnRetry | None = None,
+    ) -> None:
+        if not api_key:
+            raise ReplyLayerError(
+                0, "MISSING_API_KEY",
+                "api_key is required. Get yours at https://app.replylayer.ai/connect",
+            )
+
+        self._http = AsyncHttpClient(
+            api_key=api_key,
+            base_url=base_url.rstrip("/"),
+            max_retries=max_retries,
+            timeout=timeout,
+            max_retry_after_seconds=max_retry_after_seconds,
+            on_retry=on_retry,
+        )
+
+        self.domains = AsyncDomains(self._http)
+        self.mailboxes = AsyncMailboxes(self._http)
+        self.messages = AsyncMessages(self._http)
+        self.drafts = AsyncDrafts(self._http)
+        self.threads = AsyncThreads(self._http)
+        self.attachments = AsyncAttachments(self._http)
+        self.webhooks = AsyncWebhooks(self._http)
+        self.recipients = AsyncRecipients(self._http)
+        self.suppressions = AsyncSuppressions(self._http)
+        self.inbound_blocklist = AsyncInboundBlocklist(self._http)
+        self.api_keys = AsyncApiKeys(self._http)
+        self.account = AsyncAccount(self._http)
+        self.health = AsyncHealth(self._http)
+        self.legal_holds = AsyncLegalHolds(self._http)
+
+    async def aclose(self) -> None:
+        await self._http.aclose()
+
+    async def __aenter__(self) -> Self:
+        return self
+
+    async def __aexit__(self, *args: object) -> None:
+        await self.aclose()

replylayer/_http.py

@@ -0,0 +1,326 @@
+from __future__ import annotations
+
+import inspect
+import time
+from dataclasses import dataclass
+from typing import Any, Awaitable, Callable, Union
+
+import httpx
+
+from .errors import ReplyLayerError, error_from_response
+
+_VERSION = "0.14.0"
+_USER_AGENT = f"replylayer-sdk-py/{_VERSION}"
+_PROTECTED_HEADER_KEYS = frozenset({"authorization", "content-type", "user-agent"})
+
+# Default cap (seconds) on Retry-After honoring on 429. Raised from 60s
+# (commit b) so the SDK can wait out the suppression-add hour-bucket rate limit
+# (Retry-After ~3600s) instead of throwing immediately. Overridable per-client
+# via ``max_retry_after_seconds``. Mirrors the TS SDK's MAX_RETRY_AFTER_MS
+# (4_000_000 ms ~67 min).
+_MAX_RETRY_AFTER_SECONDS = 4_000.0
+
+
+@dataclass
+class RetryInfo:
+    """Context passed to an ``on_retry`` hook before each retry sleep."""
+
+    attempt: int  # 1-based: the attempt that just failed (1 = the first try)
+    error: ReplyLayerError  # the error that triggered the retry
+    delay_seconds: float  # the computed sleep before the next attempt (post-cap)
+    method: str  # HTTP method
+    path: str  # request path
+
+
+# Silent-by-default retry hook. Returns None, or (for the async client) an
+# awaitable that is awaited. A throwing/rejecting callback is swallowed so it
+# can never break the request loop.
+OnRetry = Callable[[RetryInfo], Union[None, Awaitable[None]]]
+
+
+class SyncHttpClient:
+    def __init__(
+        self,
+        api_key: str,
+        base_url: str,
+        max_retries: int,
+        timeout: float,
+        max_retry_after_seconds: float = _MAX_RETRY_AFTER_SECONDS,
+        on_retry: OnRetry | None = None,
+    ) -> None:
+        self._api_key = api_key
+        self._base_url = base_url
+        self._max_retries = max_retries
+        self._timeout = timeout
+        self._max_retry_after_seconds = max_retry_after_seconds
+        self._on_retry = on_retry
+        self._client = httpx.Client(timeout=timeout)
+
+    def close(self) -> None:
+        self._client.close()
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        body: dict[str, Any] | None = None,
+        query: dict[str, str | None] | None = None,
+        no_auth: bool = False,
+        timeout: float | None = None,
+        extra_headers: dict[str, str] | None = None,
+        files: Any | None = None,
+        data: dict[str, Any] | None = None,
+    ) -> Any:
+        # Migration 040 — extra_headers lets resources pass per-request
+        # headers (Idempotency-Key is the primary caller). Merged AFTER
+        # defaults so protected keys (Authorization, Content-Type,
+        # User-Agent) cannot be overridden by callers.
+        #
+        # Multipart uploads pass `files`/`data` (httpx builds the
+        # multipart/form-data body + boundary itself) — we must NOT set
+        # Content-Type ourselves, or the boundary is lost. Every other request
+        # is JSON.
+        is_multipart = files is not None
+        url = f"{self._base_url}{path}"
+        params = {k: v for k, v in (query or {}).items() if v is not None and v != ""}
+        headers = {"User-Agent": _USER_AGENT}
+        # Content-Type only with a body — Fastify rejects application/json + an
+        # empty body (FST_ERR_CTP_EMPTY_JSON_BODY), e.g. a bodyless DELETE.
+        if not is_multipart and body is not None:
+            headers["Content-Type"] = "application/json"
+        if not no_auth:
+            headers["Authorization"] = f"Bearer {self._api_key}"
+        if extra_headers:
+            for k, v in extra_headers.items():
+                if k.lower() in _PROTECTED_HEADER_KEYS:
+                    continue
+                headers[k] = v
+
+        send_kwargs: dict[str, Any] = {"params": params, "headers": headers}
+        if is_multipart:
+            send_kwargs["files"] = files
+            if data is not None:
+                send_kwargs["data"] = data
+        else:
+            send_kwargs["json"] = body
+
+        last_error: ReplyLayerError | None = None
+        for attempt in range(self._max_retries + 1):
+            try:
+                response = self._client.request(
+                    method, url, **send_kwargs,
+                    timeout=timeout or self._timeout,
+                )
+            except (httpx.ConnectError, httpx.TimeoutException) as exc:
+                raise ReplyLayerError(0, "NETWORK_ERROR", str(exc)) from exc
+
+            if response.is_success:
+                if response.status_code == 204:
+                    return None
+                text = response.text
+                if not text:
+                    return None
+                # Wrap a malformed 2xx body as ReplyLayerError(PARSE_ERROR)
+                # rather than leaking a raw JSONDecodeError (a ValueError
+                # subclass) — callers catch ReplyLayerError. Mirrors the TS SDK.
+                try:
+                    return response.json()
+                except ValueError as exc:
+                    raise ReplyLayerError(
+                        response.status_code,
+                        "PARSE_ERROR",
+                        f"Failed to parse response: {text[:200]}",
+                    ) from exc
+
+            resp_headers = dict(response.headers)
+            try:
+                resp_body = response.json()
+            except Exception:
+                resp_body = {"error": f"HTTP {response.status_code}"}
+
+            last_error = error_from_response(response.status_code, resp_body, resp_headers)
+
+            # POST/PATCH/DELETE are mutating — their 5xx is NOT retried (a retry
+            # risks a double-send, or for DELETE a lost-mutation that retries
+            # into a confusing 404). 429 IS retried on every method (pre-dispatch
+            # gate rejection). No PUT verb exists in this SDK.
+            is_mutating = method in ("POST", "PATCH", "DELETE")
+            # Multipart uploads are never retried: a retry re-sends the same
+            # `files` object, which for a file-like (IO[bytes]) input is already
+            # consumed by the first attempt → an empty/truncated body or a
+            # misleading second error. Matches the CLI's no-retry posture +
+            # "never re-send a partial upload"; a 429 staging-quota surfaces to
+            # the caller immediately.
+            is_retryable = (not is_multipart) and (
+                response.status_code == 429 or (not is_mutating and response.status_code >= 500)
+            )
+            if not is_retryable or attempt == self._max_retries:
+                raise last_error
+
+            backoff = min(0.5 * (2 ** attempt), 30.0)
+            delay = backoff
+            if response.status_code == 429:
+                ra = resp_headers.get("retry-after", "")
+                if ra.isdigit() and int(ra) > 0:
+                    delay = float(int(ra))
+                    # Cap raised from 60s to ~67min (commit b) so the SDK can
+                    # ride out an hour-bucket rate-limit (suppression-add
+                    # returns Retry-After ~3600 when tripped). Without this,
+                    # a 429 on a long bucket short-circuits to throw and the
+                    # caller never retries.
+                    if delay > self._max_retry_after_seconds:
+                        raise last_error
+
+            # Silent-by-default retry hook. Guarded so a throwing callback can't
+            # break the request loop.
+            if self._on_retry is not None:
+                try:
+                    self._on_retry(RetryInfo(attempt + 1, last_error, delay, method, path))
+                except Exception:
+                    pass
+
+            time.sleep(delay)
+
+        raise last_error or ReplyLayerError(0, "UNKNOWN", "Request failed")
+
+
+class AsyncHttpClient:
+    def __init__(
+        self,
+        api_key: str,
+        base_url: str,
+        max_retries: int,
+        timeout: float,
+        max_retry_after_seconds: float = _MAX_RETRY_AFTER_SECONDS,
+        on_retry: OnRetry | None = None,
+    ) -> None:
+        self._api_key = api_key
+        self._base_url = base_url
+        self._max_retries = max_retries
+        self._timeout = timeout
+        self._max_retry_after_seconds = max_retry_after_seconds
+        self._on_retry = on_retry
+        self._client = httpx.AsyncClient(timeout=timeout)
+
+    async def aclose(self) -> None:
+        await self._client.aclose()
+
+    async def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        body: dict[str, Any] | None = None,
+        query: dict[str, str | None] | None = None,
+        no_auth: bool = False,
+        timeout: float | None = None,
+        extra_headers: dict[str, str] | None = None,
+        files: Any | None = None,
+        data: dict[str, Any] | None = None,
+    ) -> Any:
+        # Migration 040 — see SyncHttpClient.request for the protected-key
+        # merge rationale and the multipart (files/data) handling. Keep the two
+        # implementations byte-identical.
+        is_multipart = files is not None
+        url = f"{self._base_url}{path}"
+        params = {k: v for k, v in (query or {}).items() if v is not None and v != ""}
+        headers = {"User-Agent": _USER_AGENT}
+        # Content-Type only with a body — Fastify rejects application/json + an
+        # empty body (FST_ERR_CTP_EMPTY_JSON_BODY), e.g. a bodyless DELETE.
+        if not is_multipart and body is not None:
+            headers["Content-Type"] = "application/json"
+        if not no_auth:
+            headers["Authorization"] = f"Bearer {self._api_key}"
+        if extra_headers:
+            for k, v in extra_headers.items():
+                if k.lower() in _PROTECTED_HEADER_KEYS:
+                    continue
+                headers[k] = v
+
+        send_kwargs: dict[str, Any] = {"params": params, "headers": headers}
+        if is_multipart:
+            send_kwargs["files"] = files
+            if data is not None:
+                send_kwargs["data"] = data
+        else:
+            send_kwargs["json"] = body
+
+        import asyncio
+
+        last_error: ReplyLayerError | None = None
+        for attempt in range(self._max_retries + 1):
+            try:
+                response = await self._client.request(
+                    method, url, **send_kwargs,
+                    timeout=timeout or self._timeout,
+                )
+            except (httpx.ConnectError, httpx.TimeoutException) as exc:
+                raise ReplyLayerError(0, "NETWORK_ERROR", str(exc)) from exc
+
+            if response.is_success:
+                if response.status_code == 204:
+                    return None
+                text = response.text
+                if not text:
+                    return None
+                # Wrap a malformed 2xx body as ReplyLayerError(PARSE_ERROR)
+                # rather than leaking a raw JSONDecodeError (a ValueError
+                # subclass) — callers catch ReplyLayerError. Mirrors the TS SDK.
+                try:
+                    return response.json()
+                except ValueError as exc:
+                    raise ReplyLayerError(
+                        response.status_code,
+                        "PARSE_ERROR",
+                        f"Failed to parse response: {text[:200]}",
+                    ) from exc
+
+            resp_headers = dict(response.headers)
+            try:
+                resp_body = response.json()
+            except Exception:
+                resp_body = {"error": f"HTTP {response.status_code}"}
+
+            last_error = error_from_response(response.status_code, resp_body, resp_headers)
+
+            # POST/PATCH/DELETE are mutating — their 5xx is NOT retried (a retry
+            # risks a double-send, or for DELETE a lost-mutation that retries
+            # into a confusing 404). 429 IS retried on every method (pre-dispatch
+            # gate rejection). No PUT verb exists in this SDK.
+            is_mutating = method in ("POST", "PATCH", "DELETE")
+            # Multipart uploads are never retried: a retry re-sends the same
+            # `files` object, which for a file-like (IO[bytes]) input is already
+            # consumed by the first attempt → an empty/truncated body or a
+            # misleading second error. Matches the CLI's no-retry posture +
+            # "never re-send a partial upload"; a 429 staging-quota surfaces to
+            # the caller immediately.
+            is_retryable = (not is_multipart) and (
+                response.status_code == 429 or (not is_mutating and response.status_code >= 500)
+            )
+            if not is_retryable or attempt == self._max_retries:
+                raise last_error
+
+            backoff = min(0.5 * (2 ** attempt), 30.0)
+            delay = backoff
+            if response.status_code == 429:
+                ra = resp_headers.get("retry-after", "")
+                if ra.isdigit() and int(ra) > 0:
+                    delay = float(int(ra))
+                    # See SyncHttpClient comment — cap raised in commit b.
+                    if delay > self._max_retry_after_seconds:
+                        raise last_error
+
+            # Silent-by-default retry hook. Guarded so a throwing callback can't
+            # break the request loop; awaited if it returns an awaitable.
+            if self._on_retry is not None:
+                try:
+                    result = self._on_retry(RetryInfo(attempt + 1, last_error, delay, method, path))
+                    if inspect.isawaitable(result):
+                        await result
+                except Exception:
+                    pass
+
+            await asyncio.sleep(delay)
+
+        raise last_error or ReplyLayerError(0, "UNKNOWN", "Request failed")

replylayer/_pagination.py

@@ -0,0 +1,34 @@
+from __future__ import annotations
+
+from typing import Any, AsyncIterator, Callable, Awaitable, Iterator
+
+from .types import Page
+
+
+SyncFetcher = Callable[[str | None], Page]
+AsyncFetcher = Callable[[str | None], Awaitable[Page]]
+
+
+def sync_auto_paginate(fetcher: SyncFetcher) -> Iterator[dict[str, Any]]:
+    cursor: str | None = None
+    first = True
+    while True:
+        page = fetcher(None if first else cursor)
+        first = False
+        yield from page.data
+        if not page.cursor:
+            break
+        cursor = page.cursor
+
+
+async def async_auto_paginate(fetcher: AsyncFetcher) -> AsyncIterator[dict[str, Any]]:
+    cursor: str | None = None
+    first = True
+    while True:
+        page = await fetcher(None if first else cursor)
+        first = False
+        for item in page.data:
+            yield item
+        if not page.cursor:
+            break
+        cursor = page.cursor