replylayer 0.14.0__py3-none-any.whl

replylayer/resources/drafts.py

@@ -0,0 +1,342 @@
+"""
+Drafts resource — scan-then-review-then-send flow.
+
+A draft is a message in state='draft'. create() and update() run the scanner
+synchronously and attach the verdict to the row. send() re-runs the scanner
+authoritatively; it may raise ReplyLayerError with code DRAFT_REJECTED_BY_RESCAN
+(409) if the latest policy would block, or DRAFT_ALREADY_SENT (409) if the
+draft is already in-flight or sent.
+
+Migration 040 — scheduled send: pass ``send_at`` on ``create()`` to schedule
+for future dispatch. The server runs the full send-time gate stack at
+dispatch time (not at schedule time) — policy changes between schedule and
+dispatch are honored. Dispatch failures surface as
+``message.dispatch_failed`` webhook events, not exceptions.
+
+``send_at`` accepts either an ISO-8601 string WITH explicit offset/Z, or a
+timezone-aware ``datetime`` object (converted to ISO via .isoformat()).
+Naive datetime inputs raise :class:`TimezoneRequiredError` BEFORE the HTTP
+call — failing at the call site where the stack trace points at the bug is
+cheaper than a 400 round-trip from the server.
+"""
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Any, AsyncIterator, Iterator, Union
+
+from .._http import AsyncHttpClient, SyncHttpClient
+from .._pagination import async_auto_paginate, sync_auto_paginate
+from ..errors import TimezoneRequiredError
+from ..types import Page
+
+DEFAULT_LIMIT = 50
+
+
+def _normalize_send_at(value: str | datetime | None) -> str | None:
+    """
+    Migration 040 — accept both string + datetime send_at inputs, reject
+    naive datetimes fail-fast with TimezoneRequiredError. Returns the
+    wire-format ISO string (always carries offset/Z) or None if the caller
+    passed None.
+
+    Strings are passed through verbatim — the server's validate-send-at.ts
+    is authoritative on string-format checks. We only fail-fast on the
+    one case the server can't recover from without a round-trip (naive
+    datetime → silently serialized as naive string).
+    """
+    if value is None:
+        return None
+    if isinstance(value, datetime):
+        if value.tzinfo is None:
+            raise TimezoneRequiredError()
+        return value.isoformat()
+    return value
+
+
+# Sentinel to distinguish "not passed" from "pass null" on update() send_at.
+# send_at=None means "clear the schedule"; send_at=<missing> means "no change".
+# Python has no native way to spell this; a sentinel object is the standard
+# approach (matches e.g. typing's Unset sentinel pattern).
+class _Unset:
+    def __repr__(self) -> str:  # pragma: no cover
+        return "<UNSET>"
+
+
+_UNSET: Any = _Unset()
+
+
+class SyncDrafts:
+    def __init__(self, http: SyncHttpClient) -> None:
+        self._http = http
+
+    def create(
+        self,
+        *,
+        body: str,
+        mailbox_id: str | None = None,
+        to: str | None = None,
+        subject: str | None = None,
+        html: str | None = None,
+        in_reply_to_message_id: str | None = None,
+        # Migration 085 — thread mode (mutually exclusive with
+        # in_reply_to_message_id). Derives mailbox_id/subject from the thread;
+        # `to` is then an optional participant selector.
+        thread_id: str | None = None,
+        subaddress_instance_id: str | None = None,
+        subaddress_mode: str | None = None,
+        # Migration 040 — scheduled-send.
+        send_at: str | datetime | None = None,
+        # Outbound attachment handles — held on the draft, consumed at dispatch.
+        attachment_ids: list[str] | None = None,
+        idempotency_key: str | None = None,
+    ) -> dict[str, Any]:
+        send_at_iso = _normalize_send_at(send_at)
+
+        payload: dict[str, Any] = {"body": body}
+        if mailbox_id is not None:
+            payload["mailbox_id"] = mailbox_id
+        if to is not None:
+            payload["to"] = to
+        if subject is not None:
+            payload["subject"] = subject
+        if html is not None:
+            payload["html"] = html
+        if in_reply_to_message_id is not None:
+            payload["in_reply_to_message_id"] = in_reply_to_message_id
+        if thread_id is not None:
+            payload["thread_id"] = thread_id
+        if subaddress_instance_id is not None:
+            payload["subaddress_instance_id"] = subaddress_instance_id
+        if subaddress_mode is not None:
+            payload["subaddress_mode"] = subaddress_mode
+        if send_at_iso is not None:
+            payload["send_at"] = send_at_iso
+        if attachment_ids is not None:
+            payload["attachment_ids"] = attachment_ids
+
+        extra_headers: dict[str, str] | None = None
+        if idempotency_key is not None:
+            extra_headers = {"Idempotency-Key": idempotency_key}
+
+        return self._http.request(
+            "POST",
+            "/v1/drafts",
+            body=payload,
+            extra_headers=extra_headers,
+        )
+
+    def get(self, id: str, *, view: str | None = None, body_format: str | None = None) -> dict[str, Any]:
+        query = {k: v for k, v in {"view": view, "body_format": body_format}.items() if v is not None}
+        return self._http.request("GET", f"/v1/drafts/{id}", query=query)
+
+    def list(
+        self,
+        mailbox_id: str,
+        *,
+        limit: int = DEFAULT_LIMIT,
+        before: str | None = None,
+        auto_paginate: bool = False,
+    ) -> Union[Page, Iterator[dict[str, Any]]]:
+        query: dict[str, str | None] = {
+            "limit": str(limit),
+            "before": before,
+        }
+
+        def fetch_page(cursor: str | None) -> Page:
+            q = {**query, "before": cursor or query["before"]}
+            res = self._http.request("GET", f"/v1/mailboxes/{mailbox_id}/drafts", query=q)
+            drafts = res.get("drafts", [])
+            next_cursor = drafts[-1]["id"] if len(drafts) == limit else None
+            return Page(data=drafts, has_more=len(drafts) == limit, cursor=next_cursor)
+
+        if auto_paginate:
+            return sync_auto_paginate(fetch_page)
+        return fetch_page(None)
+
+    def update(
+        self,
+        id: str,
+        *,
+        to: str | None = None,
+        subject: str | None = None,
+        body: str | None = None,
+        html: str | None = None,
+        subaddress_instance_id: str | None = None,
+        subaddress_mode: str | None = None,
+        # Migration 040 — scheduled-send. _UNSET = "no change"; None = "clear".
+        send_at: Any = _UNSET,
+        # Outbound attachments — _UNSET = no change; None = clear all; list = replace.
+        attachment_ids: Any = _UNSET,
+    ) -> dict[str, Any]:
+        payload: dict[str, Any] = {}
+        if to is not None:
+            payload["to"] = to
+        if subject is not None:
+            payload["subject"] = subject
+        if body is not None:
+            payload["body"] = body
+        if html is not None:
+            payload["html"] = html
+        if subaddress_instance_id is not None:
+            payload["subaddress_instance_id"] = subaddress_instance_id
+        if subaddress_mode is not None:
+            payload["subaddress_mode"] = subaddress_mode
+        if send_at is not _UNSET:
+            payload["send_at"] = _normalize_send_at(send_at)
+        if attachment_ids is not _UNSET:
+            payload["attachment_ids"] = attachment_ids
+        return self._http.request("PATCH", f"/v1/drafts/{id}", body=payload)
+
+    def send(self, id: str) -> dict[str, Any]:
+        """Dispatch a draft.
+
+        Re-runs the scanner authoritatively + the full send-time gate
+        stack (suppressions, reply-loop, budget, etc) before handing the
+        message to the outbound provider.
+
+        Sandbox accounts are subject to a 250-cumulative-send trial
+        budget. Once exhausted the API returns 403 with
+        ``code='SANDBOX_TRIAL_BUDGET_EXHAUSTED'`` and a ``details``
+        payload carrying ``feature='sandbox_cumulative_send_cap'``. Same
+        cap fires here as on ``messages.send()`` — the cumulative
+        counter is shared across both surfaces.
+        """
+        return self._http.request("POST", f"/v1/drafts/{id}/send", body={})
+
+    def delete(self, id: str) -> None:
+        self._http.request("DELETE", f"/v1/drafts/{id}")
+
+
+class AsyncDrafts:
+    def __init__(self, http: AsyncHttpClient) -> None:
+        self._http = http
+
+    async def create(
+        self,
+        *,
+        body: str,
+        mailbox_id: str | None = None,
+        to: str | None = None,
+        subject: str | None = None,
+        html: str | None = None,
+        in_reply_to_message_id: str | None = None,
+        # Migration 085 — thread mode (mutually exclusive with
+        # in_reply_to_message_id). Derives mailbox_id/subject; `to` optional.
+        thread_id: str | None = None,
+        subaddress_instance_id: str | None = None,
+        subaddress_mode: str | None = None,
+        # Migration 040 — scheduled-send.
+        send_at: str | datetime | None = None,
+        # Outbound attachment handles — held on the draft, consumed at dispatch.
+        attachment_ids: list[str] | None = None,
+        idempotency_key: str | None = None,
+    ) -> dict[str, Any]:
+        send_at_iso = _normalize_send_at(send_at)
+
+        payload: dict[str, Any] = {"body": body}
+        if mailbox_id is not None:
+            payload["mailbox_id"] = mailbox_id
+        if to is not None:
+            payload["to"] = to
+        if subject is not None:
+            payload["subject"] = subject
+        if html is not None:
+            payload["html"] = html
+        if in_reply_to_message_id is not None:
+            payload["in_reply_to_message_id"] = in_reply_to_message_id
+        if thread_id is not None:
+            payload["thread_id"] = thread_id
+        if subaddress_instance_id is not None:
+            payload["subaddress_instance_id"] = subaddress_instance_id
+        if subaddress_mode is not None:
+            payload["subaddress_mode"] = subaddress_mode
+        if send_at_iso is not None:
+            payload["send_at"] = send_at_iso
+        if attachment_ids is not None:
+            payload["attachment_ids"] = attachment_ids
+
+        extra_headers: dict[str, str] | None = None
+        if idempotency_key is not None:
+            extra_headers = {"Idempotency-Key": idempotency_key}
+
+        return await self._http.request(
+            "POST",
+            "/v1/drafts",
+            body=payload,
+            extra_headers=extra_headers,
+        )
+
+    async def get(self, id: str, *, view: str | None = None, body_format: str | None = None) -> dict[str, Any]:
+        query = {k: v for k, v in {"view": view, "body_format": body_format}.items() if v is not None}
+        return await self._http.request("GET", f"/v1/drafts/{id}", query=query)
+
+    async def list(
+        self,
+        mailbox_id: str,
+        *,
+        limit: int = DEFAULT_LIMIT,
+        before: str | None = None,
+        auto_paginate: bool = False,
+    ) -> Page | AsyncIterator[dict[str, Any]]:
+        query: dict[str, str | None] = {
+            "limit": str(limit),
+            "before": before,
+        }
+
+        async def fetch_page(cursor: str | None) -> Page:
+            q = {**query, "before": cursor or query["before"]}
+            res = await self._http.request("GET", f"/v1/mailboxes/{mailbox_id}/drafts", query=q)
+            drafts = res.get("drafts", [])
+            next_cursor = drafts[-1]["id"] if len(drafts) == limit else None
+            return Page(data=drafts, has_more=len(drafts) == limit, cursor=next_cursor)
+
+        if auto_paginate:
+            return async_auto_paginate(fetch_page)
+        return await fetch_page(None)
+
+    async def update(
+        self,
+        id: str,
+        *,
+        to: str | None = None,
+        subject: str | None = None,
+        body: str | None = None,
+        html: str | None = None,
+        subaddress_instance_id: str | None = None,
+        subaddress_mode: str | None = None,
+        # Migration 040 — scheduled-send. _UNSET = "no change"; None = "clear".
+        send_at: Any = _UNSET,
+        # Outbound attachments — _UNSET = no change; None = clear all; list = replace.
+        attachment_ids: Any = _UNSET,
+    ) -> dict[str, Any]:
+        payload: dict[str, Any] = {}
+        if to is not None:
+            payload["to"] = to
+        if subject is not None:
+            payload["subject"] = subject
+        if body is not None:
+            payload["body"] = body
+        if html is not None:
+            payload["html"] = html
+        if subaddress_instance_id is not None:
+            payload["subaddress_instance_id"] = subaddress_instance_id
+        if subaddress_mode is not None:
+            payload["subaddress_mode"] = subaddress_mode
+        if send_at is not _UNSET:
+            payload["send_at"] = _normalize_send_at(send_at)
+        if attachment_ids is not _UNSET:
+            payload["attachment_ids"] = attachment_ids
+        return await self._http.request("PATCH", f"/v1/drafts/{id}", body=payload)
+
+    async def send(self, id: str) -> dict[str, Any]:
+        """Dispatch a draft.
+
+        Sandbox accounts are subject to a 250-cumulative-send trial
+        budget. Once exhausted the API returns 403 with
+        ``code='SANDBOX_TRIAL_BUDGET_EXHAUSTED'`` and a ``details``
+        payload carrying ``feature='sandbox_cumulative_send_cap'``.
+        """
+        return await self._http.request("POST", f"/v1/drafts/{id}/send", body={})
+
+    async def delete(self, id: str) -> None:
+        await self._http.request("DELETE", f"/v1/drafts/{id}")

replylayer/resources/health.py

@@ -0,0 +1,21 @@
+from __future__ import annotations
+
+from typing import Any
+
+from .._http import AsyncHttpClient, SyncHttpClient
+
+
+class SyncHealth:
+    def __init__(self, http: SyncHttpClient) -> None:
+        self._http = http
+
+    def check(self) -> dict[str, Any]:
+        return self._http.request("GET", "/v1/health", no_auth=True)
+
+
+class AsyncHealth:
+    def __init__(self, http: AsyncHttpClient) -> None:
+        self._http = http
+
+    async def check(self) -> dict[str, Any]:
+        return await self._http.request("GET", "/v1/health", no_auth=True)

replylayer/resources/inbound_blocklist.py

@@ -0,0 +1,93 @@
+from __future__ import annotations
+
+from typing import Any
+from urllib.parse import quote
+
+from .._http import AsyncHttpClient, SyncHttpClient
+
+
+class SyncInboundBlocklist:
+    """Migration 047 — account-scoped inbound sender blocklist (sync).
+
+    Reached via ``client.inbound_blocklist``. Mirrors ``client.suppressions``
+    but for the inbound side: customer-managed do-not-receive list. Both
+    ``add`` and ``delete`` accept admin AND agent keys (the threat model
+    that makes the outbound suppression DELETE admin-only does not apply
+    inbound — the customer is being protected from external senders).
+
+    Server forces ``reason='manual'``, ``source='customer'`` on every insert.
+    """
+
+    def __init__(self, http: SyncHttpClient) -> None:
+        self._http = http
+
+    def list(
+        self,
+        *,
+        limit: int | None = None,
+        cursor: str | None = None,
+        all: bool | None = None,  # noqa: A002 — match REST query name
+    ) -> dict[str, Any]:
+        query: dict[str, Any] = {}
+        if limit is not None:
+            query["limit"] = str(limit)
+        if cursor is not None:
+            query["cursor"] = cursor
+        if all:
+            query["all"] = "true"
+        return self._http.request("GET", "/v1/inbound-blocklist", query=query)
+
+    def add(self, *, email: str) -> dict[str, Any]:
+        """Idempotent — repeat calls return ``already_existed: true``."""
+        return self._http.request(
+            "POST", "/v1/inbound-blocklist", body={"email": email}
+        )
+
+    def add_bulk(self, *, emails: list[str]) -> dict[str, Any]:
+        """Up to 1000 entries; partial-success buckets. Rate-limited by entry-count."""
+        return self._http.request(
+            "POST", "/v1/inbound-blocklist/bulk", body={"emails": emails}
+        )
+
+    def delete(self, email: str) -> dict[str, Any]:
+        return self._http.request(
+            "DELETE", f"/v1/inbound-blocklist/{quote(email, safe='')}"
+        )
+
+
+class AsyncInboundBlocklist:
+    """Migration 047 — account-scoped inbound sender blocklist (async)."""
+
+    def __init__(self, http: AsyncHttpClient) -> None:
+        self._http = http
+
+    async def list(
+        self,
+        *,
+        limit: int | None = None,
+        cursor: str | None = None,
+        all: bool | None = None,  # noqa: A002
+    ) -> dict[str, Any]:
+        query: dict[str, Any] = {}
+        if limit is not None:
+            query["limit"] = str(limit)
+        if cursor is not None:
+            query["cursor"] = cursor
+        if all:
+            query["all"] = "true"
+        return await self._http.request("GET", "/v1/inbound-blocklist", query=query)
+
+    async def add(self, *, email: str) -> dict[str, Any]:
+        return await self._http.request(
+            "POST", "/v1/inbound-blocklist", body={"email": email}
+        )
+
+    async def add_bulk(self, *, emails: list[str]) -> dict[str, Any]:
+        return await self._http.request(
+            "POST", "/v1/inbound-blocklist/bulk", body={"emails": emails}
+        )
+
+    async def delete(self, email: str) -> dict[str, Any]:
+        return await self._http.request(
+            "DELETE", f"/v1/inbound-blocklist/{quote(email, safe='')}"
+        )

replylayer/resources/legal_holds.py

@@ -0,0 +1,107 @@
+from __future__ import annotations
+
+from typing import Any
+from urllib.parse import quote
+
+from .._http import AsyncHttpClient, SyncHttpClient
+
+
+class SyncLegalHolds:
+    """Customer-facing legal holds (PR 3 — Pro+ tier-gated MVP, sync).
+
+    Reached via ``client.legal_holds``. ``apply`` and ``list_holds`` are
+    gated by the ``customer_legal_hold`` feature; ``release`` and ``get``
+    are NOT gated so a downgraded customer can still lift their own holds
+    and inspect prior holds. Agent-role API keys 403 — legal hold is
+    admin-only.
+    """
+
+    def __init__(self, http: SyncHttpClient) -> None:
+        self._http = http
+
+    def apply(
+        self,
+        *,
+        scope: str,
+        reason: str,
+        mailbox_id: str | None = None,
+        case_reference: str | None = None,
+    ) -> dict[str, Any]:
+        """Apply a hold. Tier-gated — 403 TIER_LIMIT below Pro."""
+        body: dict[str, Any] = {"scope": scope, "reason": reason}
+        if mailbox_id is not None:
+            body["mailbox_id"] = mailbox_id
+        if case_reference is not None:
+            body["case_reference"] = case_reference
+        return self._http.request("POST", "/v1/legal-holds", body=body)
+
+    def release(self, hold_id: str, *, release_reason: str) -> dict[str, Any]:
+        """Release a hold. Not tier-gated — downgrade-friendly."""
+        return self._http.request(
+            "POST",
+            f"/v1/legal-holds/{quote(hold_id, safe='')}/release",
+            body={"release_reason": release_reason},
+        )
+
+    def list(  # noqa: A003 — list is the canonical resource verb
+        self,
+        *,
+        include_released: bool | None = None,
+        limit: int | None = None,
+    ) -> dict[str, Any]:
+        """List customer holds. Tier-gated. Silent admin holds are filtered server-side."""
+        query: dict[str, Any] = {}
+        if include_released:
+            query["include_released"] = "true"
+        if limit is not None:
+            query["limit"] = str(limit)
+        return self._http.request("GET", "/v1/legal-holds", query=query)
+
+    def get(self, hold_id: str) -> dict[str, Any]:
+        """Read a single hold. Not tier-gated. 404 for cross-account / silent / unknown."""
+        return self._http.request("GET", f"/v1/legal-holds/{quote(hold_id, safe='')}")
+
+
+class AsyncLegalHolds:
+    """Customer-facing legal holds (PR 3 — Pro+ tier-gated MVP, async)."""
+
+    def __init__(self, http: AsyncHttpClient) -> None:
+        self._http = http
+
+    async def apply(
+        self,
+        *,
+        scope: str,
+        reason: str,
+        mailbox_id: str | None = None,
+        case_reference: str | None = None,
+    ) -> dict[str, Any]:
+        body: dict[str, Any] = {"scope": scope, "reason": reason}
+        if mailbox_id is not None:
+            body["mailbox_id"] = mailbox_id
+        if case_reference is not None:
+            body["case_reference"] = case_reference
+        return await self._http.request("POST", "/v1/legal-holds", body=body)
+
+    async def release(self, hold_id: str, *, release_reason: str) -> dict[str, Any]:
+        return await self._http.request(
+            "POST",
+            f"/v1/legal-holds/{quote(hold_id, safe='')}/release",
+            body={"release_reason": release_reason},
+        )
+
+    async def list(  # noqa: A003
+        self,
+        *,
+        include_released: bool | None = None,
+        limit: int | None = None,
+    ) -> dict[str, Any]:
+        query: dict[str, Any] = {}
+        if include_released:
+            query["include_released"] = "true"
+        if limit is not None:
+            query["limit"] = str(limit)
+        return await self._http.request("GET", "/v1/legal-holds", query=query)
+
+    async def get(self, hold_id: str) -> dict[str, Any]:
+        return await self._http.request("GET", f"/v1/legal-holds/{quote(hold_id, safe='')}")