replylayer 0.14.0__py3-none-any.whl

replylayer/errors.py

@@ -0,0 +1,152 @@
+from __future__ import annotations
+
+from typing import Any
+
+
+class ReplyLayerError(Exception):
+    def __init__(
+        self,
+        status_code: int,
+        code: str,
+        message: str,
+        details: dict[str, Any] | None = None,
+    ) -> None:
+        super().__init__(message)
+        self.status_code = status_code
+        self.code = code
+        self.details = details
+
+
+class AuthenticationError(ReplyLayerError):
+    def __init__(self, code: str, message: str, details: dict[str, Any] | None = None) -> None:
+        super().__init__(401, code, message, details)
+
+
+class ForbiddenError(ReplyLayerError):
+    def __init__(self, code: str, message: str, details: dict[str, Any] | None = None) -> None:
+        super().__init__(403, code, message, details)
+
+
+class NotFoundError(ReplyLayerError):
+    def __init__(self, code: str, message: str, details: dict[str, Any] | None = None) -> None:
+        super().__init__(404, code, message, details)
+
+
+class ValidationError(ReplyLayerError):
+    def __init__(self, status_code: int, code: str, message: str, details: dict[str, Any] | None = None) -> None:
+        super().__init__(status_code, code, message, details)
+
+
+class RateLimitError(ReplyLayerError):
+    def __init__(
+        self,
+        code: str,
+        message: str,
+        headers: dict[str, str],
+        details: dict[str, Any] | None = None,
+    ) -> None:
+        super().__init__(429, code, message, details)
+        ra = headers.get("retry-after")
+        self.retry_after: int | None = int(ra) if ra and ra.isdigit() else None
+        lim = headers.get("x-ratelimit-limit")
+        self.limit: int | None = int(lim) if lim and lim.isdigit() else None
+        rem = headers.get("x-ratelimit-remaining")
+        self.remaining: int | None = int(rem) if rem and rem.isdigit() else None
+        self.reset: str | None = headers.get("x-ratelimit-reset")
+
+
+class WebhookSignatureError(ReplyLayerError):
+    def __init__(self, message: str) -> None:
+        super().__init__(0, "WEBHOOK_SIGNATURE_ERROR", message)
+
+
+# Migration 040 — scheduled-send error surface. Raised when scheduled-send
+# routes reject a request (invalid TZ / too-soon / too-far / quota breach /
+# Idempotency-Key without send_at). Subclass of ReplyLayerError so generic
+# catches still work; typed .reason_code narrows for per-reason handling.
+#
+# NOT raised for runtime dispatch failures — those surface as
+# message.dispatch_failed webhook events, not SDK exceptions.
+_SCHEDULING_REASON_CODES: frozenset[str] = frozenset({
+    "TIMEZONE_REQUIRED",
+    "SEND_AT_TOO_SOON",
+    "SEND_AT_TOO_FAR",
+    "SCHEDULED_SEND_QUOTA_EXCEEDED",
+    "IDEMPOTENCY_KEY_REQUIRES_SEND_AT",
+})
+
+
+class SchedulingError(ReplyLayerError):
+    def __init__(
+        self,
+        status_code: int,
+        code: str,
+        message: str,
+        details: dict[str, Any] | None = None,
+    ) -> None:
+        super().__init__(status_code, code, message, details)
+        self.reason_code: str = code
+
+
+class TimezoneRequiredError(SchedulingError):
+    """
+    Raised CLIENT-SIDE (before the HTTP call) when a caller passes a
+    ``datetime`` without tzinfo on ``send_at``. The TS SDK equivalent is a
+    400 TIMEZONE_REQUIRED from the server; in Python we fail fast because
+    ``datetime.isoformat()`` on a naive datetime produces a naive ISO
+    string that the server would then reject anyway — better to raise at
+    the call site where the stack trace points at the bug.
+
+    The ``status_code`` is set to 400 for API parity, but no HTTP call was
+    actually made.
+    """
+
+    def __init__(self, message: str | None = None) -> None:
+        super().__init__(
+            400,
+            "TIMEZONE_REQUIRED",
+            message or (
+                "send_at must be timezone-aware. Use datetime.now(timezone.utc) "
+                "or attach tzinfo before passing. An ISO string with offset or "
+                "'Z' is also accepted."
+            ),
+        )
+
+
+def error_from_response(
+    status: int,
+    body: dict[str, Any],
+    headers: dict[str, str],
+) -> ReplyLayerError:
+    message = body.get("error", f"HTTP {status}")
+    # Coerce a non-string ``code`` to a string. ``body["code"]`` is typed as a
+    # string but the wire carries whatever JSON parsed — an edge gateway (e.g.
+    # a proxy on a long-poll 502) can put a NUMERIC code on the body, surprising
+    # any caller doing ``isinstance(err.code, str)``. ``is not None`` preserves a
+    # legitimate ``0`` (-> "0"); the ``or`` catches None/empty -> HTTP_<status>.
+    # Mirrors the CLI client + the TS SDK.
+    raw_code = body.get("code")
+    code = (str(raw_code) if raw_code is not None else "") or f"HTTP_{status}"
+    details = body.get("details")
+
+    # Migration 040 — scheduling errors are a narrow subclass of
+    # status-generic errors. Map BEFORE the status switch so a 429 with
+    # SCHEDULED_SEND_QUOTA_EXCEEDED becomes a SchedulingError, not a
+    # RateLimitError (consumers filtering on .retry_after wouldn't expect
+    # quota-type 429s anyway). 400s likewise become SchedulingError
+    # rather than ValidationError so `isinstance(err, SchedulingError)`
+    # works uniformly across statuses.
+    if code in _SCHEDULING_REASON_CODES:
+        return SchedulingError(status, code, message, details)
+
+    if status == 401:
+        return AuthenticationError(code, message, details)
+    if status == 403:
+        return ForbiddenError(code, message, details)
+    if status == 404:
+        return NotFoundError(code, message, details)
+    if status == 429:
+        return RateLimitError(code, message, headers, details)
+    if status in (400, 422):
+        return ValidationError(status, code, message, details)
+    return ReplyLayerError(status, code, message, details)

replylayer/resources/account.py

@@ -0,0 +1,36 @@
+from __future__ import annotations
+
+from typing import Any
+
+from .._http import AsyncHttpClient, SyncHttpClient
+from ..types import QuotaResponse, UsageResponse
+
+
+class SyncAccount:
+    def __init__(self, http: SyncHttpClient) -> None:
+        self._http = http
+
+    def get_usage(self) -> UsageResponse:
+        return self._http.request("GET", "/v1/accounts/usage")
+
+    def get_quota(self) -> QuotaResponse:
+        return self._http.request("GET", "/v1/accounts/quota")
+
+    def export(self) -> dict[str, Any]:
+        """GDPR Art. 20 data portability export — the full account-data object."""
+        return self._http.request("GET", "/v1/accounts/export")
+
+
+class AsyncAccount:
+    def __init__(self, http: AsyncHttpClient) -> None:
+        self._http = http
+
+    async def get_usage(self) -> UsageResponse:
+        return await self._http.request("GET", "/v1/accounts/usage")
+
+    async def get_quota(self) -> QuotaResponse:
+        return await self._http.request("GET", "/v1/accounts/quota")
+
+    async def export(self) -> dict[str, Any]:
+        """GDPR Art. 20 data portability export — the full account-data object."""
+        return await self._http.request("GET", "/v1/accounts/export")

replylayer/resources/api_keys.py

@@ -0,0 +1,59 @@
+from __future__ import annotations
+
+from typing import Any
+
+from .._http import AsyncHttpClient, SyncHttpClient
+
+
+class SyncApiKeys:
+    def __init__(self, http: SyncHttpClient) -> None:
+        self._http = http
+
+    def create(self, *, role: str, label: str | None = None, mailbox_ids: list[str] | None = None) -> dict[str, Any]:
+        payload: dict[str, Any] = {"role": role}
+        if label is not None:
+            payload["label"] = label
+        if mailbox_ids is not None:
+            payload["mailbox_ids"] = mailbox_ids
+        return self._http.request("POST", "/v1/accounts/api-keys", body=payload)
+
+    def list(self, *, include_revoked: bool = False) -> dict[str, Any]:
+        # D4 / RL-UAT-019 — active-only by default; include_revoked=True returns
+        # revoked keys with revoked_at/revoked_by metadata.
+        query = {"include_revoked": "true"} if include_revoked else None
+        return self._http.request("GET", "/v1/accounts/api-keys", query=query)
+
+    def revoke(self, id: str) -> dict[str, Any]:
+        return self._http.request("DELETE", f"/v1/accounts/api-keys/{id}")
+
+    def rotate(self) -> dict[str, Any]:
+        """Rotate the calling API key. After this call, this SDK instance's key
+        is invalidated. Create a new ReplyLayer instance with the returned key."""
+        return self._http.request("POST", "/v1/accounts/api-keys/rotate")
+
+
+class AsyncApiKeys:
+    def __init__(self, http: AsyncHttpClient) -> None:
+        self._http = http
+
+    async def create(self, *, role: str, label: str | None = None, mailbox_ids: list[str] | None = None) -> dict[str, Any]:
+        payload: dict[str, Any] = {"role": role}
+        if label is not None:
+            payload["label"] = label
+        if mailbox_ids is not None:
+            payload["mailbox_ids"] = mailbox_ids
+        return await self._http.request("POST", "/v1/accounts/api-keys", body=payload)
+
+    async def list(self, *, include_revoked: bool = False) -> dict[str, Any]:
+        # D4 / RL-UAT-019 — active-only by default; include_revoked=True returns
+        # revoked keys with revoked_at/revoked_by metadata.
+        query = {"include_revoked": "true"} if include_revoked else None
+        return await self._http.request("GET", "/v1/accounts/api-keys", query=query)
+
+    async def revoke(self, id: str) -> dict[str, Any]:
+        return await self._http.request("DELETE", f"/v1/accounts/api-keys/{id}")
+
+    async def rotate(self) -> dict[str, Any]:
+        """Rotate the calling API key. After this call, this SDK instance's key
+        is invalidated. Create a new AsyncReplyLayer instance with the returned key."""
+        return await self._http.request("POST", "/v1/accounts/api-keys/rotate")

replylayer/resources/attachments.py

@@ -0,0 +1,115 @@
+from __future__ import annotations
+
+from typing import IO, Any, cast
+
+from .._http import AsyncHttpClient, SyncHttpClient
+from ..types import (
+    AttachmentPreviewResponse,
+    GetUploadAttachmentResponse,
+    UploadAttachmentResponse,
+)
+
+
+def _upload_kwargs(
+    *,
+    mailbox_id: str,
+    file: bytes | IO[bytes],
+    filename: str,
+    content_type: str | None,
+) -> dict[str, Any]:
+    """Build the httpx files=/data= kwargs for POST /v1/attachments.
+
+    The file part is a (filename, content[, content_type]) tuple; the
+    mailbox_id is a plain multipart text field. content_type is advisory — the
+    server re-sniffs the bytes and decides the trusted family regardless.
+    """
+    file_part: tuple[Any, ...] = (
+        (filename, file, content_type) if content_type else (filename, file)
+    )
+    return {"files": {"file": file_part}, "data": {"mailbox_id": mailbox_id}}
+
+
+class SyncAttachments:
+    def __init__(self, http: SyncHttpClient) -> None:
+        self._http = http
+
+    def get_download_url(self, message_id: str, index: int) -> dict[str, Any]:
+        return self._http.request("GET", f"/v1/messages/{message_id}/attachments/{index}")
+
+    def get_preview(self, message_id: str, index: int) -> AttachmentPreviewResponse:
+        return cast(
+            AttachmentPreviewResponse,
+            self._http.request("GET", f"/v1/messages/{message_id}/attachments/{index}/preview"),
+        )
+
+    def upload(
+        self,
+        *,
+        mailbox_id: str,
+        file: bytes | IO[bytes],
+        filename: str,
+        content_type: str | None = None,
+    ) -> UploadAttachmentResponse:
+        """Stage an outbound attachment (phase 1). Returns an opaque handle;
+        pass ``handle["id"]`` in a send/reply/draft ``attachment_ids`` list. The
+        mailbox must have outbound attachments enabled (Pro+). The returned
+        ``content_scan_status`` is ``"pending"`` — poll :meth:`get_upload` until
+        terminal before referencing the handle, or the send fails with
+        ``ATTACHMENT_SCAN_PENDING``.
+        """
+        kwargs = _upload_kwargs(
+            mailbox_id=mailbox_id, file=file, filename=filename, content_type=content_type
+        )
+        return cast(UploadAttachmentResponse, self._http.request("POST", "/v1/attachments", **kwargs))
+
+    def get_upload(self, attachment_id: str) -> GetUploadAttachmentResponse:
+        """Poll a staged-attachment handle for its content-scan status (or
+        consumed state)."""
+        return cast(
+            GetUploadAttachmentResponse,
+            self._http.request("GET", f"/v1/attachments/{attachment_id}"),
+        )
+
+    def delete_upload(self, attachment_id: str) -> None:
+        """Delete an un-consumed staged-attachment handle. A consumed handle → 409."""
+        self._http.request("DELETE", f"/v1/attachments/{attachment_id}")
+
+
+class AsyncAttachments:
+    def __init__(self, http: AsyncHttpClient) -> None:
+        self._http = http
+
+    async def get_download_url(self, message_id: str, index: int) -> dict[str, Any]:
+        return await self._http.request("GET", f"/v1/messages/{message_id}/attachments/{index}")
+
+    async def get_preview(self, message_id: str, index: int) -> AttachmentPreviewResponse:
+        return cast(
+            AttachmentPreviewResponse,
+            await self._http.request("GET", f"/v1/messages/{message_id}/attachments/{index}/preview"),
+        )
+
+    async def upload(
+        self,
+        *,
+        mailbox_id: str,
+        file: bytes | IO[bytes],
+        filename: str,
+        content_type: str | None = None,
+    ) -> UploadAttachmentResponse:
+        """Async variant of :meth:`SyncAttachments.upload`."""
+        kwargs = _upload_kwargs(
+            mailbox_id=mailbox_id, file=file, filename=filename, content_type=content_type
+        )
+        return cast(
+            UploadAttachmentResponse,
+            await self._http.request("POST", "/v1/attachments", **kwargs),
+        )
+
+    async def get_upload(self, attachment_id: str) -> GetUploadAttachmentResponse:
+        return cast(
+            GetUploadAttachmentResponse,
+            await self._http.request("GET", f"/v1/attachments/{attachment_id}"),
+        )
+
+    async def delete_upload(self, attachment_id: str) -> None:
+        await self._http.request("DELETE", f"/v1/attachments/{attachment_id}")

replylayer/resources/domains.py

@@ -0,0 +1,79 @@
+from __future__ import annotations
+
+from typing import Any
+
+from .._http import AsyncHttpClient, SyncHttpClient
+
+
+class SyncDomains:
+    def __init__(self, http: SyncHttpClient) -> None:
+        self._http = http
+
+    def create(self, **params: Any) -> dict[str, Any]:
+        return self._http.request("POST", "/v1/domains", body=params)
+
+    def list(self) -> dict[str, Any]:
+        return self._http.request("GET", "/v1/domains")
+
+    def get(self, id: str) -> dict[str, Any]:
+        return self._http.request("GET", f"/v1/domains/{id}")
+
+    def verify(self, id: str) -> dict[str, Any]:
+        return self._http.request("POST", f"/v1/domains/{id}/verify")
+
+    def update_self_hosted_config(
+        self,
+        id: str,
+        **params: Any,
+    ) -> dict[str, Any]:
+        return self._http.request(
+            "PATCH",
+            f"/v1/domains/{id}/self-hosted-config",
+            body=params,
+        )
+
+    def delete(self, id: str) -> dict[str, Any]:
+        return self._http.request("DELETE", f"/v1/domains/{id}")
+
+    def set_default(self, id: str) -> dict[str, Any]:
+        return self._http.request("PATCH", f"/v1/domains/{id}/set-default")
+
+    def recheck(self, id: str) -> dict[str, Any]:
+        return self._http.request("POST", f"/v1/domains/{id}/self-hosted-recheck")
+
+
+class AsyncDomains:
+    def __init__(self, http: AsyncHttpClient) -> None:
+        self._http = http
+
+    async def create(self, **params: Any) -> dict[str, Any]:
+        return await self._http.request("POST", "/v1/domains", body=params)
+
+    async def list(self) -> dict[str, Any]:
+        return await self._http.request("GET", "/v1/domains")
+
+    async def get(self, id: str) -> dict[str, Any]:
+        return await self._http.request("GET", f"/v1/domains/{id}")
+
+    async def verify(self, id: str) -> dict[str, Any]:
+        return await self._http.request("POST", f"/v1/domains/{id}/verify")
+
+    async def update_self_hosted_config(
+        self,
+        id: str,
+        **params: Any,
+    ) -> dict[str, Any]:
+        return await self._http.request(
+            "PATCH",
+            f"/v1/domains/{id}/self-hosted-config",
+            body=params,
+        )
+
+    async def delete(self, id: str) -> dict[str, Any]:
+        return await self._http.request("DELETE", f"/v1/domains/{id}")
+
+    async def set_default(self, id: str) -> dict[str, Any]:
+        return await self._http.request("PATCH", f"/v1/domains/{id}/set-default")
+
+    async def recheck(self, id: str) -> dict[str, Any]:
+        return await self._http.request("POST", f"/v1/domains/{id}/self-hosted-recheck")