replylayer 0.14.0__tar.gz → 0.16.0__tar.gz

{replylayer-0.14.0 → replylayer-0.16.0}/PKG-INFO

@@ -1,12 +1,14 @@
 Metadata-Version: 2.4
 Name: replylayer
-Version: 0.14.0
+Version: 0.16.0
 Summary: Official Python SDK for ReplyLayer — email for AI agents
 License-Expression: MIT
 Keywords: agent,ai,email,mailbox,replylayer,sdk,webhook
 Requires-Python: >=3.10
 Requires-Dist: httpx>=0.27
 Requires-Dist: typing-extensions>=4.0
+Provides-Extra: cli
+Requires-Dist: rly>=0.6.3; extra == 'cli'
 Provides-Extra: dev
 Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
 Requires-Dist: pytest>=8.0; extra == 'dev'
@@ -17,6 +19,8 @@ Description-Content-Type: text/markdown
 
 Official Python SDK for [ReplyLayer](https://replylayer.ai) — secure email for AI agents.
 
+> **Looking for the command-line tool?** This package is the SDK *library* (`import replylayer`). For the `rly` / `replylayer` CLI, install [`rly`](https://pypi.org/project/rly/) instead: `pipx install rly`.
+
 ## Install
 
 ```bash
@@ -114,9 +118,9 @@ contract — read it before relying on retries:
 |----------|---------|
 | `rl.mailboxes` | `create`, `list`, `delete`, `update`, `set_recipient_policy` |
 | `rl.mailboxes.allowlist` | `list`, `add`, `add_bulk`, `delete`, `list_blocked_attempts` |
-| `rl.messages` | `send`, `list`, `get`, `reply`, `wait`, `release`, `block` |
+| `rl.messages` | `send`, `list`, `get`, `reply`, `wait`, `release`, `block`, `set_starred` |
 | `rl.drafts` | `create`, `get`, `list`, `update`, `send`, `delete` |
-| `rl.threads` | `list`, `get` |
+| `rl.threads` | `list`, `get`, `set_starred` |
 | `rl.attachments` | `get_download_url`, `get_preview`, `upload`, `get_upload`, `delete_upload` |
 | `rl.webhooks` | `create`, `list`, `get`, `update`, `delete`, `rotate_secret`, `test`, `list_deliveries`, `retry_delivery` |
 | `rl.recipients` | `create`, `list`, `delete`, `resend` |
@@ -145,7 +149,7 @@ if draft["worst_decision"] == "allow":
 
 The send/reply/draft-send response carries two additive, nullable keys that explain a held send inline (no second `messages.get` call). `result["scan"]` is the vendor-neutral scanner verdict (`ScanSummary`); `result["hold_context"]` (`{"trigger_source", "summary_reasons"}` or `None`) is the policy/HITL reason, non-null only when the delivery `status` diverges from `scan["verdict"]` because of a policy/HITL hold — a clean scan held for review by your mailbox policy, or a scanner review-flag held as quarantine on a plan without the review queue (`trigger_source`: `mailbox_policy` | `scanner` | `both`).
 
-This SDK always sends **synchronously** — `drafts.send()`, `messages.send()`, and `messages.reply()` return only once the scanner verdict is known, with `scan` and `hold_context` inline. The optimistic-ack async path (`Prefer: respond-async` → `202 queued_for_dispatch`, then poll the message to a terminal state) is a REST-level capability of `POST /v1/drafts/:id/send` only; the SDK exposes no `Prefer` option. To use it, drive that route directly (see ENDPOINTS.md "Asynchronous send (optimistic-ack) & polling") and poll `messages.get(message_id)` (or handle the lifecycle webhook) until `state` is terminal. (`messages.wait()` is a mailbox long-poll for new *inbound* mail, not a way to observe a specific message by ID.)
+By default `drafts.send()`, `messages.send()`, and `messages.reply()` return only once the scanner verdict is known, with `scan` and `hold_context` inline. Pass `async_dispatch=True` to `drafts.send()` to send the `Prefer: respond-async` hint. **The hint is advisory** — the server returns a `202 AsyncSendAck` only when `OUTBOUND_ASYNC_DISPATCH_ENABLED` is on; otherwise it ignores the hint and returns a normal `SendMessageResponse`. **Always branch on the result**: `result["status"] == "queued_for_dispatch"` ⇒ `AsyncSendAck`, otherwise `SendMessageResponse`. Poll `messages.get(message_id)` (or handle the lifecycle webhook) until `state` is terminal. Attachment-bearing drafts fail closed on the async path (`400 ATTACHMENTS_REQUIRE_SYNC_SEND`). (`messages.wait()` is a mailbox long-poll for new *inbound* mail, not a way to observe a specific message by ID.)
 
 The send endpoint raises `ReplyLayerError` with distinct `.code` values on 409:
 - `DRAFT_REJECTED_BY_RESCAN` — send-time scan flipped the verdict to `block`/`quarantine`. The draft stays in `draft` state; edit the body and retry. `err.details` carries `scan` and, when a policy/HITL decision drove the hold, `hold_context`.

{replylayer-0.14.0 → replylayer-0.16.0}/README.md

@@ -2,6 +2,8 @@
 
 Official Python SDK for [ReplyLayer](https://replylayer.ai) — secure email for AI agents.
 
+> **Looking for the command-line tool?** This package is the SDK *library* (`import replylayer`). For the `rly` / `replylayer` CLI, install [`rly`](https://pypi.org/project/rly/) instead: `pipx install rly`.
+
 ## Install
 
 ```bash
@@ -99,9 +101,9 @@ contract — read it before relying on retries:
 |----------|---------|
 | `rl.mailboxes` | `create`, `list`, `delete`, `update`, `set_recipient_policy` |
 | `rl.mailboxes.allowlist` | `list`, `add`, `add_bulk`, `delete`, `list_blocked_attempts` |
-| `rl.messages` | `send`, `list`, `get`, `reply`, `wait`, `release`, `block` |
+| `rl.messages` | `send`, `list`, `get`, `reply`, `wait`, `release`, `block`, `set_starred` |
 | `rl.drafts` | `create`, `get`, `list`, `update`, `send`, `delete` |
-| `rl.threads` | `list`, `get` |
+| `rl.threads` | `list`, `get`, `set_starred` |
 | `rl.attachments` | `get_download_url`, `get_preview`, `upload`, `get_upload`, `delete_upload` |
 | `rl.webhooks` | `create`, `list`, `get`, `update`, `delete`, `rotate_secret`, `test`, `list_deliveries`, `retry_delivery` |
 | `rl.recipients` | `create`, `list`, `delete`, `resend` |
@@ -130,7 +132,7 @@ if draft["worst_decision"] == "allow":
 
 The send/reply/draft-send response carries two additive, nullable keys that explain a held send inline (no second `messages.get` call). `result["scan"]` is the vendor-neutral scanner verdict (`ScanSummary`); `result["hold_context"]` (`{"trigger_source", "summary_reasons"}` or `None`) is the policy/HITL reason, non-null only when the delivery `status` diverges from `scan["verdict"]` because of a policy/HITL hold — a clean scan held for review by your mailbox policy, or a scanner review-flag held as quarantine on a plan without the review queue (`trigger_source`: `mailbox_policy` | `scanner` | `both`).
 
-This SDK always sends **synchronously** — `drafts.send()`, `messages.send()`, and `messages.reply()` return only once the scanner verdict is known, with `scan` and `hold_context` inline. The optimistic-ack async path (`Prefer: respond-async` → `202 queued_for_dispatch`, then poll the message to a terminal state) is a REST-level capability of `POST /v1/drafts/:id/send` only; the SDK exposes no `Prefer` option. To use it, drive that route directly (see ENDPOINTS.md "Asynchronous send (optimistic-ack) & polling") and poll `messages.get(message_id)` (or handle the lifecycle webhook) until `state` is terminal. (`messages.wait()` is a mailbox long-poll for new *inbound* mail, not a way to observe a specific message by ID.)
+By default `drafts.send()`, `messages.send()`, and `messages.reply()` return only once the scanner verdict is known, with `scan` and `hold_context` inline. Pass `async_dispatch=True` to `drafts.send()` to send the `Prefer: respond-async` hint. **The hint is advisory** — the server returns a `202 AsyncSendAck` only when `OUTBOUND_ASYNC_DISPATCH_ENABLED` is on; otherwise it ignores the hint and returns a normal `SendMessageResponse`. **Always branch on the result**: `result["status"] == "queued_for_dispatch"` ⇒ `AsyncSendAck`, otherwise `SendMessageResponse`. Poll `messages.get(message_id)` (or handle the lifecycle webhook) until `state` is terminal. Attachment-bearing drafts fail closed on the async path (`400 ATTACHMENTS_REQUIRE_SYNC_SEND`). (`messages.wait()` is a mailbox long-poll for new *inbound* mail, not a way to observe a specific message by ID.)
 
 The send endpoint raises `ReplyLayerError` with distinct `.code` values on 409:
 - `DRAFT_REJECTED_BY_RESCAN` — send-time scan flipped the verdict to `block`/`quarantine`. The draft stays in `draft` state; edit the body and retry. `err.details` carries `scan` and, when a policy/HITL decision drove the hold, `hold_context`.

{replylayer-0.14.0 → replylayer-0.16.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "replylayer"
-version = "0.14.0"
+version = "0.16.0"
 description = "Official Python SDK for ReplyLayer — email for AI agents"
 readme = "README.md"
 license = "MIT"
@@ -18,6 +18,11 @@ dependencies = [
 ]
 
 [project.optional-dependencies]
+# Optional CLI convenience: `pip install "replylayer[cli]"` also installs the
+# `rly` launcher (the `rly` / `replylayer` command-line tools). The SDK itself
+# is a pure library; this extra is opt-in and is never pulled by a plain
+# `pip install replylayer`.
+cli = ["rly>=0.6.3"]
 dev = [
   "pytest>=8.0",
   "pytest-asyncio>=0.24",

{replylayer-0.14.0 → replylayer-0.16.0}/replylayer/__init__.py

@@ -14,6 +14,11 @@ from .errors import (
     TimezoneRequiredError,
 )
 from .types import (
+    # WS1 — star response types (0.16.0).
+    MessageStarResponse,
+    ThreadStarResponse,
+    # WS6-SDK — async optimistic-ack (0.16.0).
+    AsyncSendAck,
     WebhookSummary,
     WebhookDeliverySummary,
     WebhookDeliveryStatus,
@@ -71,9 +76,14 @@ from .types import (
     ScannerPolicy,
 )
 
-__version__ = "0.14.0"
+__version__ = "0.16.0"
 
 __all__ = [
+    # WS1 — star response types (0.16.0).
+    "MessageStarResponse",
+    "ThreadStarResponse",
+    # WS6-SDK — async optimistic-ack (0.16.0).
+    "AsyncSendAck",
     "ReplyLayer",
     "AsyncReplyLayer",
     "RetryInfo",

replylayer-0.16.0/replylayer/__main__.py

@@ -0,0 +1,25 @@
+"""Entry point for ``python -m replylayer``.
+
+The ``replylayer`` PyPI package is the ReplyLayer Python **SDK** — a library you
+``import``, not a command-line tool. This module exists only to redirect anyone
+who tries to "run" the package toward the actual CLI (the separate ``rly``
+package), rather than failing silently.
+"""
+
+from __future__ import annotations
+
+
+def main() -> None:
+    print(
+        "replylayer is the ReplyLayer Python SDK (a library, not a CLI).\n"
+        "\n"
+        "  Use it in code:   import replylayer\n"
+        "  Install the CLI:  pipx install rly      "
+        "# provides the `rly` and `replylayer` commands\n"
+        "\n"
+        "Docs: https://replylayer.ai"
+    )
+
+
+if __name__ == "__main__":
+    main()

{replylayer-0.14.0 → replylayer-0.16.0}/replylayer/_http.py

@@ -9,7 +9,7 @@ import httpx
 
 from .errors import ReplyLayerError, error_from_response
 
-_VERSION = "0.14.0"
+_VERSION = "0.16.0"
 _USER_AGENT = f"replylayer-sdk-py/{_VERSION}"
 _PROTECTED_HEADER_KEYS = frozenset({"authorization", "content-type", "user-agent"})
 

{replylayer-0.14.0 → replylayer-0.16.0}/replylayer/resources/drafts.py

@@ -27,7 +27,7 @@ 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
+from ..types import AsyncSendAck, Page, SendMessageResponse
 
 DEFAULT_LIMIT = 50
 
@@ -187,13 +187,24 @@ class SyncDrafts:
             payload["attachment_ids"] = attachment_ids
         return self._http.request("PATCH", f"/v1/drafts/{id}", body=payload)
 
-    def send(self, id: str) -> dict[str, Any]:
+    def send(self, id: str, *, async_dispatch: bool = False) -> "SendMessageResponse | AsyncSendAck":
         """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.
 
+        Pass ``async_dispatch=True`` to send the ``Prefer: respond-async``
+        hint. **The hint is advisory** — the server returns a 202
+        ``AsyncSendAck`` (``status == "queued_for_dispatch"``) only when
+        ``OUTBOUND_ASYNC_DISPATCH_ENABLED`` is on; otherwise it ignores the
+        hint and returns a normal ``SendMessageResponse``. **Always branch on
+        the result**: ``status == "queued_for_dispatch"`` ⇒ ``AsyncSendAck``,
+        otherwise ``SendMessageResponse``. Attachment-bearing drafts fail
+        closed on the async path (``400 ATTACHMENTS_REQUIRE_SYNC_SEND``).
+        Poll ``messages.get(message_id)`` until ``state`` is terminal to
+        observe the final outcome.
+
         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``
@@ -201,7 +212,8 @@ class SyncDrafts:
         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={})
+        extra_headers: dict[str, str] | None = {"Prefer": "respond-async"} if async_dispatch else None
+        return self._http.request("POST", f"/v1/drafts/{id}/send", body={}, extra_headers=extra_headers)
 
     def delete(self, id: str) -> None:
         self._http.request("DELETE", f"/v1/drafts/{id}")
@@ -328,15 +340,17 @@ class AsyncDrafts:
             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.
+    async def send(self, id: str, *, async_dispatch: bool = False) -> "SendMessageResponse | AsyncSendAck":
+        """Dispatch a draft (async). See SyncDrafts.send for the full contract.
 
-        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'``.
+        Pass ``async_dispatch=True`` to send the ``Prefer: respond-async``
+        hint. The hint is advisory — the server returns a 202 ``AsyncSendAck``
+        only when ``OUTBOUND_ASYNC_DISPATCH_ENABLED`` is on; otherwise it
+        ignores the hint and returns a normal ``SendMessageResponse``. Always
+        branch on ``status == "queued_for_dispatch"`` to distinguish the two.
         """
-        return await self._http.request("POST", f"/v1/drafts/{id}/send", body={})
+        extra_headers: dict[str, str] | None = {"Prefer": "respond-async"} if async_dispatch else None
+        return await self._http.request("POST", f"/v1/drafts/{id}/send", body={}, extra_headers=extra_headers)
 
     async def delete(self, id: str) -> None:
         await self._http.request("DELETE", f"/v1/drafts/{id}")

{replylayer-0.14.0 → replylayer-0.16.0}/replylayer/resources/messages.py

@@ -4,7 +4,7 @@ from typing import Any, AsyncIterator, Iterator
 
 from .._http import AsyncHttpClient, SyncHttpClient
 from .._pagination import async_auto_paginate, sync_auto_paginate
-from ..types import Page
+from ..types import MessageStarResponse, Page
 
 DEFAULT_LIMIT = 50
 
@@ -81,6 +81,8 @@ class SyncMessages:
         until: str | None = None,
         search: str | None = None,
         view: str | None = None,
+        starred: bool | None = None,
+        has_attachment: bool | None = None,
         auto_paginate: bool = False,
     ) -> Union[Page, Iterator[dict[str, Any]]]:
         """List messages in a mailbox.
@@ -90,6 +92,10 @@ class SyncMessages:
         server's blind-trigram index has no shorter form. A 1-2 character
         ``search`` is rejected with HTTP 400 ``code='SEARCH_TERM_TOO_SHORT'``
         (``details.min_search_length=3``).
+
+        ``has_attachment`` requires a server advertising
+        ``messages.has_attachment_filter`` in ``GET /v1/health``'s
+        ``capabilities``; older servers reject the param.
         """
         query: dict[str, str | None] = {
             "limit": str(limit),
@@ -102,6 +108,8 @@ class SyncMessages:
             "until": until,
             "search": search,
             "view": view,
+            "starred": str(starred).lower() if starred is not None else None,
+            "has_attachment": str(has_attachment).lower() if has_attachment is not None else None,
         }
 
         def fetch_page(cursor: str | None) -> Page:
@@ -195,6 +203,17 @@ class SyncMessages:
             "POST", f"/v1/messages/{message_id}/read", body={}
         )
 
+    def set_starred(self, message_id: str, *, starred: bool) -> "MessageStarResponse":
+        """Star or unstar a message.
+
+        ``starred=True`` marks the message as starred (favorited);
+        ``starred=False`` clears the star. Idempotent.
+        Wraps ``PATCH /v1/messages/:id/star``.
+        """
+        return self._http.request(
+            "PATCH", f"/v1/messages/{message_id}/star", body={"starred": starred}
+        )
+
     def approve_review(
         self, message_id: str, *, reason: str | None = None
     ) -> dict[str, Any]:
@@ -298,6 +317,8 @@ class AsyncMessages:
         until: str | None = None,
         search: str | None = None,
         view: str | None = None,
+        starred: bool | None = None,
+        has_attachment: bool | None = None,
         auto_paginate: bool = False,
     ) -> Page | AsyncIterator[dict[str, Any]]:
         """List messages in a mailbox.
@@ -307,6 +328,10 @@ class AsyncMessages:
         server's blind-trigram index has no shorter form. A 1-2 character
         ``search`` is rejected with HTTP 400 ``code='SEARCH_TERM_TOO_SHORT'``
         (``details.min_search_length=3``).
+
+        ``has_attachment`` requires a server advertising
+        ``messages.has_attachment_filter`` in ``GET /v1/health``'s
+        ``capabilities``; older servers reject the param.
         """
         query: dict[str, str | None] = {
             "limit": str(limit),
@@ -319,6 +344,8 @@ class AsyncMessages:
             "until": until,
             "search": search,
             "view": view,
+            "starred": str(starred).lower() if starred is not None else None,
+            "has_attachment": str(has_attachment).lower() if has_attachment is not None else None,
         }
 
         async def fetch_page(cursor: str | None) -> Page:
@@ -396,6 +423,12 @@ class AsyncMessages:
             "POST", f"/v1/messages/{message_id}/read", body={}
         )
 
+    async def set_starred(self, message_id: str, *, starred: bool) -> "MessageStarResponse":
+        """Star or unstar a message (async). See SyncMessages.set_starred."""
+        return await self._http.request(
+            "PATCH", f"/v1/messages/{message_id}/star", body={"starred": starred}
+        )
+
     async def approve_review(
         self, message_id: str, *, reason: str | None = None
     ) -> dict[str, Any]:

{replylayer-0.14.0 → replylayer-0.16.0}/replylayer/resources/threads.py

@@ -5,7 +5,7 @@ from urllib.parse import quote
 
 from .._http import AsyncHttpClient, SyncHttpClient
 from .._pagination import async_auto_paginate, sync_auto_paginate
-from ..types import Page
+from ..types import Page, ThreadStarResponse
 
 DEFAULT_LIMIT = 50
 
@@ -44,8 +44,26 @@ class SyncThreads:
             return sync_auto_paginate(fetch_page)
         return fetch_page(None)
 
-    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}
+    def get(
+        self,
+        id: str,
+        *,
+        view: str | None = None,
+        body_format: str | None = None,
+        mailbox: str | None = None,
+    ) -> dict[str, Any]:
+        """Read a full thread (ordered messages).
+
+        Account-wide by default; pass ``mailbox`` (name or UUID) to scope the
+        lookup to one mailbox when the same thread key collides across two of
+        the account's mailboxes. ``mailbox`` requires a server that accepts
+        the param — older servers reject it.
+        """
+        query = {
+            k: v for k, v in {
+                "view": view, "body_format": body_format, "mailbox": mailbox,
+            }.items() if v is not None
+        }
         return self._http.request("GET", f"/v1/threads/{quote(id, safe='')}", query=query)
 
     def mark_read(self, mailbox_id: str, thread_id: str) -> dict[str, Any]:
@@ -68,6 +86,20 @@ class SyncThreads:
             body={},
         )
 
+    def set_starred(self, mailbox_id: str, thread_id: str, *, starred: bool) -> "ThreadStarResponse":
+        """Star or unstar a thread.
+
+        ``starred=True`` marks the thread as starred; ``starred=False`` clears it.
+        Both ``mailbox_id`` and ``thread_id`` are URL-encoded (mirrors existing
+        ``mark_read`` behaviour). Wraps
+        ``PATCH /v1/mailboxes/:id/threads/:thread_id/star``.
+        """
+        return self._http.request(
+            "PATCH",
+            f"/v1/mailboxes/{quote(mailbox_id, safe='')}/threads/{quote(thread_id, safe='')}/star",
+            body={"starred": starred},
+        )
+
 
 class AsyncThreads:
     def __init__(self, http: AsyncHttpClient) -> None:
@@ -104,8 +136,20 @@ class AsyncThreads:
 
         return await fetch_page(None)
 
-    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}
+    async def get(
+        self,
+        id: str,
+        *,
+        view: str | None = None,
+        body_format: str | None = None,
+        mailbox: str | None = None,
+    ) -> dict[str, Any]:
+        """Read a full thread (async). See SyncThreads.get for the full contract."""
+        query = {
+            k: v for k, v in {
+                "view": view, "body_format": body_format, "mailbox": mailbox,
+            }.items() if v is not None
+        }
         return await self._http.request("GET", f"/v1/threads/{quote(id, safe='')}", query=query)
 
     async def mark_read(self, mailbox_id: str, thread_id: str) -> dict[str, Any]:
@@ -115,3 +159,11 @@ class AsyncThreads:
             f"/v1/mailboxes/{quote(mailbox_id, safe='')}/threads/{quote(thread_id, safe='')}/read",
             body={},
         )
+
+    async def set_starred(self, mailbox_id: str, thread_id: str, *, starred: bool) -> "ThreadStarResponse":
+        """Star or unstar a thread (async). See SyncThreads.set_starred."""
+        return await self._http.request(
+            "PATCH",
+            f"/v1/mailboxes/{quote(mailbox_id, safe='')}/threads/{quote(thread_id, safe='')}/star",
+            body={"starred": starred},
+        )

{replylayer-0.14.0 → replylayer-0.16.0}/replylayer/types.py

@@ -602,6 +602,31 @@ class SendMessageResponse(TypedDict):
     sends_remaining: int
 
 
+class AsyncSendAck(TypedDict):
+    """202 optimistic-ack from POST /v1/drafts/:id/send with Prefer: respond-async.
+
+    Exactly 4 fields — no scan/warning/hold_context (those only appear on the
+    synchronous 200 path). Poll messages.get(message_id) until state is terminal.
+    """
+    message_id: str
+    status: Literal["queued_for_dispatch"]
+    daily_limit: int
+    sends_remaining: int
+
+
+class MessageStarResponse(TypedDict):
+    """PATCH /v1/messages/:id/star response."""
+    message_id: str
+    starred: bool
+
+
+class ThreadStarResponse(TypedDict):
+    """PATCH /v1/mailboxes/:id/threads/:thread_id/star response."""
+    thread_id: str
+    starred: bool
+    updated_count: int
+
+
 class MessageSummary(TypedDict, total=False):
     """List-response item shape.
 
@@ -641,6 +666,8 @@ class MessageSummary(TypedDict, total=False):
     review_trigger_source: NotRequired[ReviewQueueTriggerSource | None]
     # Plaintext, whitespace-normalized, 200-character list excerpt.
     body_preview: NotRequired[str | None]
+    # Customer inbox star/favorite marker. Optional — mirrors TS SDK MessageSummary.starred? (optional).
+    starred: NotRequired[bool]
     # S7 NTH-003 — server-computed deep link into the web inbox shell, or None
     # when PUBLIC_LINK_BASE_URL is unset on the server (fail-closed).
     dashboard_url: NotRequired[str | None]
@@ -1187,6 +1214,8 @@ class ThreadSummary(TypedDict):
     last_message_at: str
     message_count: int
     unread_count: int
+    # Required — mirrors TS SDK ThreadSummary.starred (required, not optional).
+    starred: bool
     participants: list[str]
 
 

replylayer-0.16.0/tests/test_version.py

@@ -0,0 +1,18 @@
+"""Drift guard: _http._VERSION must match the installed package version.
+
+If these diverge the User-Agent header sent to the API will report the wrong
+SDK version. This test catches that before a release.
+"""
+import importlib.metadata
+
+import replylayer._http as _http
+
+
+def test_user_agent_version_matches_package_version() -> None:
+    """_VERSION in _http.py must equal the installed replylayer package version."""
+    package_version = importlib.metadata.version("replylayer")
+    assert _http._VERSION == package_version, (
+        f"_http._VERSION ({_http._VERSION!r}) does not match the installed "
+        f"package version ({package_version!r}). "
+        f"Update _VERSION in replylayer/_http.py to match pyproject.toml."
+    )

replylayer-0.16.0/tests/test_ws1_ws6.py

@@ -0,0 +1,369 @@
+"""Tests for WS1 (star + filter parity) and WS6-SDK (async_dispatch) — 0.16.0."""
+from __future__ import annotations
+
+import json
+
+import httpx
+import pytest
+import respx
+
+from replylayer import AsyncReplyLayer, ReplyLayer
+
+BASE = "https://api.test.replylayer.ai"
+
+
+def sdk() -> ReplyLayer:
+    return ReplyLayer(api_key="rl_live_test", base_url=BASE, max_retries=0)
+
+
+def async_sdk() -> AsyncReplyLayer:
+    return AsyncReplyLayer(api_key="rl_live_test", base_url=BASE, max_retries=0)
+
+
+# ── WS1: messages.set_starred ──────────────────────────────────────────────
+
+
+@respx.mock
+def test_messages_set_starred_true_issues_patch():
+    route = respx.patch(f"{BASE}/v1/messages/msg-1/star").mock(
+        return_value=httpx.Response(200, json={"message_id": "msg-1", "starred": True})
+    )
+    res = sdk().messages.set_starred("msg-1", starred=True)
+    assert route.called
+    assert res["message_id"] == "msg-1"
+    assert res["starred"] is True
+    payload = json.loads(route.calls[0].request.content)
+    assert payload == {"starred": True}
+
+
+@respx.mock
+def test_messages_set_starred_false_issues_patch():
+    route = respx.patch(f"{BASE}/v1/messages/msg-2/star").mock(
+        return_value=httpx.Response(200, json={"message_id": "msg-2", "starred": False})
+    )
+    res = sdk().messages.set_starred("msg-2", starred=False)
+    assert route.called
+    payload = json.loads(route.calls[0].request.content)
+    assert payload == {"starred": False}
+    assert res["starred"] is False
+
+
+@respx.mock
+@pytest.mark.asyncio
+async def test_async_messages_set_starred_issues_patch():
+    route = respx.patch(f"{BASE}/v1/messages/msg-3/star").mock(
+        return_value=httpx.Response(200, json={"message_id": "msg-3", "starred": True})
+    )
+    rl = async_sdk()
+    res = await rl.messages.set_starred("msg-3", starred=True)
+    assert route.called
+    payload = json.loads(route.calls[0].request.content)
+    assert payload == {"starred": True}
+    assert res["starred"] is True
+    await rl.aclose()
+
+
+# ── WS1: messages.list() starred + has_attachment serialization ────────────
+
+
+@respx.mock
+def test_messages_list_starred_true_serializes_as_lowercase():
+    route = respx.get(f"{BASE}/v1/mailboxes/mbx1/messages").mock(
+        return_value=httpx.Response(200, json={"messages": []})
+    )
+    sdk().messages.list("mbx1", starred=True)
+    params = route.calls[0].request.url.params
+    assert params["starred"] == "true"
+
+
+@respx.mock
+def test_messages_list_starred_false_serializes_as_lowercase():
+    route = respx.get(f"{BASE}/v1/mailboxes/mbx1/messages").mock(
+        return_value=httpx.Response(200, json={"messages": []})
+    )
+    sdk().messages.list("mbx1", starred=False)
+    params = route.calls[0].request.url.params
+    assert params["starred"] == "false"
+
+
+@respx.mock
+def test_messages_list_has_attachment_true_serializes_as_lowercase():
+    route = respx.get(f"{BASE}/v1/mailboxes/mbx1/messages").mock(
+        return_value=httpx.Response(200, json={"messages": []})
+    )
+    sdk().messages.list("mbx1", has_attachment=True)
+    params = route.calls[0].request.url.params
+    assert params["has_attachment"] == "true"
+
+
+@respx.mock
+def test_messages_list_has_attachment_false_serializes_as_lowercase():
+    route = respx.get(f"{BASE}/v1/mailboxes/mbx1/messages").mock(
+        return_value=httpx.Response(200, json={"messages": []})
+    )
+    sdk().messages.list("mbx1", has_attachment=False)
+    params = route.calls[0].request.url.params
+    assert params["has_attachment"] == "false"
+
+
+@respx.mock
+def test_messages_list_starred_and_has_attachment_both_omitted_when_none():
+    route = respx.get(f"{BASE}/v1/mailboxes/mbx1/messages").mock(
+        return_value=httpx.Response(200, json={"messages": []})
+    )
+    sdk().messages.list("mbx1")
+    params = route.calls[0].request.url.params
+    assert "starred" not in params
+    assert "has_attachment" not in params
+
+
+# ── WS1: threads.set_starred ────────────────────────────────────────────────
+
+
+@respx.mock
+def test_threads_set_starred_true_issues_patch():
+    route = respx.patch(f"{BASE}/v1/mailboxes/mbx-1/threads/t%40host.com/star").mock(
+        return_value=httpx.Response(
+            200,
+            json={"thread_id": "t@host.com", "starred": True, "updated_count": 3},
+        )
+    )
+    res = sdk().threads.set_starred("mbx-1", "t@host.com", starred=True)
+    assert route.called
+    payload = json.loads(route.calls[0].request.content)
+    assert payload == {"starred": True}
+    assert res["starred"] is True
+    assert res["updated_count"] == 3
+
+
+@respx.mock
+def test_threads_set_starred_false_issues_patch():
+    route = respx.patch(f"{BASE}/v1/mailboxes/mbx-1/threads/t1/star").mock(
+        return_value=httpx.Response(
+            200,
+            json={"thread_id": "t1", "starred": False, "updated_count": 1},
+        )
+    )
+    res = sdk().threads.set_starred("mbx-1", "t1", starred=False)
+    assert route.called
+    payload = json.loads(route.calls[0].request.content)
+    assert payload == {"starred": False}
+    assert res["starred"] is False
+
+
+@respx.mock
+@pytest.mark.asyncio
+async def test_async_threads_set_starred_issues_patch():
+    route = respx.patch(f"{BASE}/v1/mailboxes/mbx-1/threads/t2/star").mock(
+        return_value=httpx.Response(
+            200,
+            json={"thread_id": "t2", "starred": True, "updated_count": 2},
+        )
+    )
+    rl = async_sdk()
+    res = await rl.threads.set_starred("mbx-1", "t2", starred=True)
+    assert route.called
+    payload = json.loads(route.calls[0].request.content)
+    assert payload == {"starred": True}
+    assert res["starred"] is True
+    await rl.aclose()
+
+
+# ── WS1: threads.get() mailbox param ────────────────────────────────────────
+
+
+@respx.mock
+def test_threads_get_includes_mailbox_in_query_when_set():
+    route = respx.get(f"{BASE}/v1/threads/t-1").mock(
+        return_value=httpx.Response(
+            200,
+            json={"id": "t-1", "mailbox_id": "mbx-1", "subject": "Hi", "message_count": 1, "messages": []},
+        )
+    )
+    sdk().threads.get("t-1", mailbox="support")
+    params = route.calls[0].request.url.params
+    assert params["mailbox"] == "support"
+
+
+@respx.mock
+def test_threads_get_omits_mailbox_when_not_set():
+    route = respx.get(f"{BASE}/v1/threads/t-1").mock(
+        return_value=httpx.Response(
+            200,
+            json={"id": "t-1", "mailbox_id": "mbx-1", "subject": "Hi", "message_count": 1, "messages": []},
+        )
+    )
+    sdk().threads.get("t-1")
+    params = route.calls[0].request.url.params
+    assert "mailbox" not in params
+
+
+@respx.mock
+@pytest.mark.asyncio
+async def test_async_threads_get_includes_mailbox_in_query_when_set():
+    route = respx.get(f"{BASE}/v1/threads/t-2").mock(
+        return_value=httpx.Response(
+            200,
+            json={"id": "t-2", "mailbox_id": "mbx-2", "subject": "Hey", "message_count": 1, "messages": []},
+        )
+    )
+    rl = async_sdk()
+    await rl.threads.get("t-2", mailbox="support")
+    params = route.calls[0].request.url.params
+    assert params["mailbox"] == "support"
+    await rl.aclose()
+
+
+# ── WS1: list-row deserialization surfaces `starred` ────────────────────────
+
+
+def test_message_summary_starred_field_is_deserialized():
+    """MessageSummary surfaces starred when present (NotRequired[bool])."""
+    row: dict = {
+        "id": "msg-s1",
+        "direction": "inbound",
+        "state": "available",
+        "sender": "a@b.com",
+        "recipient": "c@d.com",
+        "subject": "Hi",
+        "subaddress_instance_id": None,
+        "firewall_block": None,
+        "thread_id": None,
+        "created_at": "2026-06-07T00:00:00Z",
+        "read_at": None,
+        "starred": True,
+    }
+    # Validate the field is accessible (TypedDict is a dict at runtime).
+    assert row["starred"] is True
+
+
+def test_thread_summary_starred_field_is_required():
+    """ThreadSummary.starred is required — confirm the dict can be built."""
+    row: dict = {
+        "id": "t-s1",
+        "subject": "Thread",
+        "first_message_at": "2026-06-07T00:00:00Z",
+        "last_message_at": "2026-06-07T01:00:00Z",
+        "message_count": 1,
+        "unread_count": 0,
+        "starred": False,
+        "participants": ["a@b.com"],
+    }
+    assert row["starred"] is False
+
+
+# ── WS6-SDK: drafts.send(async_dispatch=True) ───────────────────────────────
+
+
+@respx.mock
+def test_drafts_send_async_dispatch_true_sends_prefer_header():
+    route = respx.post(f"{BASE}/v1/drafts/d-1/send").mock(
+        return_value=httpx.Response(
+            202,
+            json={
+                "message_id": "msg-async-1",
+                "status": "queued_for_dispatch",
+                "daily_limit": 15,
+                "sends_remaining": 14,
+            },
+        )
+    )
+    res = sdk().drafts.send("d-1", async_dispatch=True)
+    assert route.called
+    req = route.calls[0].request
+    assert req.headers.get("prefer") == "respond-async"
+    assert res["status"] == "queued_for_dispatch"
+    assert res["message_id"] == "msg-async-1"
+    assert res["daily_limit"] == 15
+    assert res["sends_remaining"] == 14
+
+
+@respx.mock
+def test_drafts_send_async_dispatch_false_does_not_send_prefer_header():
+    route = respx.post(f"{BASE}/v1/drafts/d-2/send").mock(
+        return_value=httpx.Response(
+            200,
+            json={
+                "message_id": "msg-sync-1",
+                "status": "sent",
+                "warning": None,
+                "daily_limit": 15,
+                "sends_remaining": 14,
+            },
+        )
+    )
+    res = sdk().drafts.send("d-2")
+    assert route.called
+    req = route.calls[0].request
+    assert "prefer" not in {k.lower() for k in req.headers.keys()}
+    assert res["status"] == "sent"
+
+
+@respx.mock
+def test_drafts_send_async_dispatch_default_does_not_send_prefer_header():
+    """Default (async_dispatch not passed) must not include Prefer header."""
+    route = respx.post(f"{BASE}/v1/drafts/d-3/send").mock(
+        return_value=httpx.Response(
+            200,
+            json={"message_id": "msg-sync-2", "status": "sent", "warning": None, "daily_limit": 15, "sends_remaining": 14},
+        )
+    )
+    sdk().drafts.send("d-3")
+    req = route.calls[0].request
+    assert "prefer" not in {k.lower() for k in req.headers.keys()}
+
+
+@respx.mock
+@pytest.mark.asyncio
+async def test_async_drafts_send_async_dispatch_true_sends_prefer_header():
+    route = respx.post(f"{BASE}/v1/drafts/d-4/send").mock(
+        return_value=httpx.Response(
+            202,
+            json={
+                "message_id": "msg-async-2",
+                "status": "queued_for_dispatch",
+                "daily_limit": 15,
+                "sends_remaining": 14,
+            },
+        )
+    )
+    rl = async_sdk()
+    res = await rl.drafts.send("d-4", async_dispatch=True)
+    assert route.called
+    req = route.calls[0].request
+    assert req.headers.get("prefer") == "respond-async"
+    assert res["status"] == "queued_for_dispatch"
+    await rl.aclose()
+
+
+@respx.mock
+@pytest.mark.asyncio
+async def test_async_drafts_send_default_does_not_send_prefer_header():
+    route = respx.post(f"{BASE}/v1/drafts/d-5/send").mock(
+        return_value=httpx.Response(
+            200,
+            json={"message_id": "msg-sync-3", "status": "sent", "warning": None, "daily_limit": 15, "sends_remaining": 14},
+        )
+    )
+    rl = async_sdk()
+    await rl.drafts.send("d-5")
+    req = route.calls[0].request
+    assert "prefer" not in {k.lower() for k in req.headers.keys()}
+    await rl.aclose()
+
+
+# ── WS6-SDK: AsyncSendAck type shape ────────────────────────────────────────
+
+
+def test_async_send_ack_type_has_four_fields():
+    """AsyncSendAck TypedDict has exactly the 4 required fields."""
+    from replylayer import AsyncSendAck
+    ack: AsyncSendAck = {
+        "message_id": "msg-1",
+        "status": "queued_for_dispatch",
+        "daily_limit": 15,
+        "sends_remaining": 14,
+    }
+    assert ack["status"] == "queued_for_dispatch"
+    assert ack["daily_limit"] == 15
+    assert ack["sends_remaining"] == 14

{replylayer-0.14.0 → replylayer-0.16.0}/uv.lock

@@ -171,13 +171,17 @@ wheels = [
 
 [[package]]
 name = "replylayer"
-version = "0.13.0"
+version = "0.16.0"
 source = { editable = "." }
 dependencies = [
     { name = "httpx" },
+    { name = "typing-extensions" },
 ]
 
 [package.optional-dependencies]
+cli = [
+    { name = "rly" },
+]
 dev = [
     { name = "pytest" },
     { name = "pytest-asyncio" },
@@ -190,8 +194,10 @@ requires-dist = [
     { name = "pytest", marker = "extra == 'dev'", specifier = ">=8.0" },
     { name = "pytest-asyncio", marker = "extra == 'dev'", specifier = ">=0.24" },
     { name = "respx", marker = "extra == 'dev'", specifier = ">=0.21" },
+    { name = "rly", marker = "extra == 'cli'", specifier = ">=0.6.3" },
+    { name = "typing-extensions", specifier = ">=4.0" },
 ]
-provides-extras = ["dev"]
+provides-extras = ["cli", "dev"]
 
 [[package]]
 name = "respx"
@@ -205,6 +211,19 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/1d/4a/221da6ca167db45693d8d26c7dc79ccfc978a440251bf6721c9aaf251ac0/respx-0.23.1-py2.py3-none-any.whl", hash = "sha256:b18004b029935384bccfa6d7d9d74b4ec9af73a081cc28600fffc0447f4b8c1a", size = 25557, upload-time = "2026-04-08T14:37:14.613Z" },
 ]
 
+[[package]]
+name = "rly"
+version = "0.6.3"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/36/c4/82ff082990ce46c9d2d47f587bfc078cb33554aa076e2dad1f068fe010f0/rly-0.6.3.tar.gz", hash = "sha256:c5ab3dffe218f639e72298787c34e827e2c25ecb7c730553850136e8a6131ecd", size = 15405, upload-time = "2026-06-06T14:09:27.386Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/40/9d/eab2b5b68f4cf187b882af768e2c7956a52c55715db4d016aebacf9204be/rly-0.6.3-py3-none-macosx_14_0_arm64.whl", hash = "sha256:b9837a5800b4dc9f2a709fdf637e891d11513d08a265e6d0a6f465e5def3c266", size = 34891158, upload-time = "2026-06-06T14:09:12.295Z" },
+    { url = "https://files.pythonhosted.org/packages/c4/20/e209429517988e7de53db131f4f81e9942c497599448055f5c18fb12f678/rly-0.6.3-py3-none-macosx_14_0_x86_64.whl", hash = "sha256:33996146630e8b2151135854f86817f8b259a87022cfd7c36782074a400bb681", size = 36857258, upload-time = "2026-06-06T14:09:15.239Z" },
+    { url = "https://files.pythonhosted.org/packages/19/28/8b9d4cc26a0396585939837e68dc621e4db796da63970a2eab070eddd52b/rly-0.6.3-py3-none-manylinux_2_28_aarch64.whl", hash = "sha256:26da04b1635338a923b528172af113a1945e97573549bd66935c983c82b26aa3", size = 39009513, upload-time = "2026-06-06T14:09:19.131Z" },
+    { url = "https://files.pythonhosted.org/packages/d2/48/dbff54bfc88156373fcd133513b3aa4cf9a876934377ab7dc95a1959d731/rly-0.6.3-py3-none-manylinux_2_28_x86_64.whl", hash = "sha256:692fb50af3721278511b08b25183a687689454421efe2ce9dd970677b3675456", size = 39380097, upload-time = "2026-06-06T14:09:22.111Z" },
+    { url = "https://files.pythonhosted.org/packages/92/20/6a7c55b3d70dc9448d793771f82e3a3aa76855bb8e3323a8861156f0385a/rly-0.6.3-py3-none-win_amd64.whl", hash = "sha256:451e201af43f031cbac2d1d221d2e6295374a9acd7f4e2386c6d9c4947199103", size = 31372056, upload-time = "2026-06-06T14:09:25.1Z" },
+]
+
 [[package]]
 name = "tomli"
 version = "2.4.1"