replylayer 0.14.0__tar.gz → 0.17.0__tar.gz

replylayer-0.14.0/README.md → replylayer-0.17.0/PKG-INFO

@@ -1,7 +1,26 @@
+Metadata-Version: 2.4
+Name: replylayer
+Version: 0.17.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'
+Requires-Dist: respx>=0.21; extra == 'dev'
+Description-Content-Type: text/markdown
+
 # replylayer
 
 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 +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` |
@@ -130,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`.
@@ -148,7 +167,7 @@ except ReplyLayerError as err:
 
 ## Outbound attachments (Pro+)
 
-Attaching a file is a **two-phase** flow: upload the bytes to stage a handle, then reference `handle["id"]` in a send/reply/draft `attachment_ids` list. Every attachment is scanned (byte-level family validation + AV + secrets/PII over extracted text **and** filename) before it leaves. The mailbox must have outbound attachments **explicitly enabled** (a Pro+, session-gated dashboard action) — uploads to a non-enabled mailbox raise `ForbiddenError` with `code="OUTBOUND_ATTACHMENTS_DISABLED"`.
+Attaching a file is a **two-phase** flow: upload the bytes to stage a handle, then reference `handle["id"]` in a send/reply/draft `attachment_ids` list. Every attachment is scanned (byte-level family validation + AV + secrets/PII over extracted text **and** filename) before it leaves. The mailbox must have outbound attachments **explicitly enabled** by a human account owner in the dashboard (Pro+, mailbox Settings page, TOTP/password re-auth). Once enabled, API keys can send attachments; uploads to a non-enabled mailbox raise `ForbiddenError` with `code="OUTBOUND_ATTACHMENTS_DISABLED"`.
 
 ```python
 import time
@@ -451,7 +470,7 @@ Error classes: `ReplyLayerError` (base), `AuthenticationError` (401), `Forbidden
 
 ## Webhook signature verification
 
-> For a full integration guide (event catalog, retry behavior, idempotency, security, troubleshooting), see [`docs/webhooks.md`](../../docs/webhooks.md).
+> For a full integration guide (event catalog, retry behavior, idempotency, security, troubleshooting), see the hosted webhook docs (coming).
 
 ```python
 from replylayer import verify_webhook_signature
@@ -464,6 +483,19 @@ verify_webhook_signature(
 )
 ```
 
+Once verified, parse and dispatch on the event type. **The discriminator field is `event`, not `type`:**
+
+```python
+import json
+
+payload = json.loads(request.body)
+# payload["event"] is the discriminator — NOT payload["type"]
+if payload["event"] == "message.received":
+    # handle inbound message
+elif payload["event"] == "message.dispatch_failed":
+    # handle failed outbound send
+```
+
 ## Context managers
 
 Both clients support context managers to properly close connection pools:

replylayer-0.14.0/PKG-INFO → replylayer-0.17.0/README.md

@@ -1,22 +1,9 @@
-Metadata-Version: 2.4
-Name: replylayer
-Version: 0.14.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: dev
-Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
-Requires-Dist: pytest>=8.0; extra == 'dev'
-Requires-Dist: respx>=0.21; extra == 'dev'
-Description-Content-Type: text/markdown
-
 # replylayer
 
 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 +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` |
@@ -145,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`.
@@ -163,7 +150,7 @@ except ReplyLayerError as err:
 
 ## Outbound attachments (Pro+)
 
-Attaching a file is a **two-phase** flow: upload the bytes to stage a handle, then reference `handle["id"]` in a send/reply/draft `attachment_ids` list. Every attachment is scanned (byte-level family validation + AV + secrets/PII over extracted text **and** filename) before it leaves. The mailbox must have outbound attachments **explicitly enabled** (a Pro+, session-gated dashboard action) — uploads to a non-enabled mailbox raise `ForbiddenError` with `code="OUTBOUND_ATTACHMENTS_DISABLED"`.
+Attaching a file is a **two-phase** flow: upload the bytes to stage a handle, then reference `handle["id"]` in a send/reply/draft `attachment_ids` list. Every attachment is scanned (byte-level family validation + AV + secrets/PII over extracted text **and** filename) before it leaves. The mailbox must have outbound attachments **explicitly enabled** by a human account owner in the dashboard (Pro+, mailbox Settings page, TOTP/password re-auth). Once enabled, API keys can send attachments; uploads to a non-enabled mailbox raise `ForbiddenError` with `code="OUTBOUND_ATTACHMENTS_DISABLED"`.
 
 ```python
 import time
@@ -466,7 +453,7 @@ Error classes: `ReplyLayerError` (base), `AuthenticationError` (401), `Forbidden
 
 ## Webhook signature verification
 
-> For a full integration guide (event catalog, retry behavior, idempotency, security, troubleshooting), see [`docs/webhooks.md`](../../docs/webhooks.md).
+> For a full integration guide (event catalog, retry behavior, idempotency, security, troubleshooting), see the hosted webhook docs (coming).
 
 ```python
 from replylayer import verify_webhook_signature
@@ -479,6 +466,19 @@ verify_webhook_signature(
 )
 ```
 
+Once verified, parse and dispatch on the event type. **The discriminator field is `event`, not `type`:**
+
+```python
+import json
+
+payload = json.loads(request.body)
+# payload["event"] is the discriminator — NOT payload["type"]
+if payload["event"] == "message.received":
+    # handle inbound message
+elif payload["event"] == "message.dispatch_failed":
+    # handle failed outbound send
+```
+
 ## Context managers
 
 Both clients support context managers to properly close connection pools:

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

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "replylayer"
-version = "0.14.0"
+version = "0.17.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.17.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.17.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.17.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.17.0}/replylayer/_http.py

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

{replylayer-0.14.0 → replylayer-0.17.0}/replylayer/resources/attachments.py

@@ -51,8 +51,9 @@ class SyncAttachments:
         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
+        pass ``handle["id"]`` in a send/reply/draft ``attachment_ids`` list. A
+        human account owner must first enable outbound attachments for the
+        mailbox in the dashboard (Pro+, TOTP/password re-auth). 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``.

{replylayer-0.14.0 → replylayer-0.17.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
 
@@ -146,8 +146,14 @@ class SyncDrafts:
             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)
+            # UAT-22 — consume the server's authoritative `has_more` (#296) instead
+            # of the old `len(drafts) == limit` inference, which over-reported at
+            # the exact-`limit` boundary. Derive `next_cursor` FROM has_more so we
+            # only advance when the server says another page exists. Defensive
+            # default `False` for a pre-#296 server that omits the field.
+            has_more = res.get("has_more") is True
+            next_cursor = drafts[-1]["id"] if has_more and drafts else None
+            return Page(data=drafts, has_more=has_more, cursor=next_cursor)
 
         if auto_paginate:
             return sync_auto_paginate(fetch_page)
@@ -187,13 +193,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 +218,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}")
@@ -287,8 +305,14 @@ class AsyncDrafts:
             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)
+            # UAT-22 — consume the server's authoritative `has_more` (#296) instead
+            # of the old `len(drafts) == limit` inference (byte-identical to the
+            # sync method). A sync-only fix would leave this async path still
+            # over-reporting at the exact-`limit` boundary. Defensive default
+            # `False` for a pre-#296 server that omits the field.
+            has_more = res.get("has_more") is True
+            next_cursor = drafts[-1]["id"] if has_more and drafts else None
+            return Page(data=drafts, has_more=has_more, cursor=next_cursor)
 
         if auto_paginate:
             return async_auto_paginate(fetch_page)
@@ -328,15 +352,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.17.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.17.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
 
@@ -24,6 +24,7 @@ class SyncThreads:
         has_inbound: bool | None = None,
         include_firewall_blocked: bool = False,
         view: str | None = None,
+        starred: bool | None = None,
         auto_paginate: bool = False,
     ) -> Union[Page, Iterator[dict[str, Any]]]:
         def fetch_page(cursor: str | None) -> Page:
@@ -34,6 +35,9 @@ class SyncThreads:
                 "has_inbound": ("true" if has_inbound else "false") if has_inbound is not None else None,
                 "include_firewall_blocked": "true" if include_firewall_blocked else None,
                 "view": view,
+                # UAT-04 (F04 residual) — filter starred/unstarred threads. Mirrors
+                # the messages.list idiom; omitted when None so no param is sent.
+                "starred": str(starred).lower() if starred is not None else None,
             }
             res = self._http.request("GET", f"/v1/mailboxes/{mailbox_id}/threads", query=query)
             threads = res.get("threads", [])
@@ -44,8 +48,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 +90,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:
@@ -83,6 +119,7 @@ class AsyncThreads:
         has_inbound: bool | None = None,
         include_firewall_blocked: bool = False,
         view: str | None = None,
+        starred: bool | None = None,
         auto_paginate: bool = False,
     ) -> Page | AsyncIterator[dict[str, Any]]:
         async def fetch_page(cursor: str | None) -> Page:
@@ -93,6 +130,9 @@ class AsyncThreads:
                 "has_inbound": ("true" if has_inbound else "false") if has_inbound is not None else None,
                 "include_firewall_blocked": "true" if include_firewall_blocked else None,
                 "view": view,
+                # UAT-04 (F04 residual) — filter starred/unstarred threads (async
+                # parity with SyncThreads.list). Omitted when None.
+                "starred": str(starred).lower() if starred is not None else None,
             }
             res = await self._http.request("GET", f"/v1/mailboxes/{mailbox_id}/threads", query=query)
             threads = res.get("threads", [])
@@ -104,8 +144,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 +167,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},
+        )