oneshot-python 0.15.0__tar.gz → 0.18.0__tar.gz

{oneshot_python-0.15.0 → oneshot_python-0.18.0}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: oneshot-python
-Version: 0.15.0
+Version: 0.18.0
 Summary: Core Python SDK for the OneShot API — HTTP client with x402 payment handling
 License-Expression: MIT
 Requires-Python: >=3.10

{oneshot_python-0.15.0 → oneshot_python-0.18.0}/README.md

@@ -60,6 +60,12 @@ Paid endpoints use the [x402 protocol](https://x402.org):
 
 Your private key never leaves your machine. All signing happens locally via `eth-account`.
 
+## Read Authentication
+
+Read endpoints (inbox, SMS inbox, notifications, balance, browser profiles) return private, per-agent data. Because a wallet address is public, the client proves you actually control it: on every free/read call it signs a short-lived **EIP-712 read proof** (`sign_read_proof`) and sends it as the `x-agent-proof` header. The API verifies the signature locally and rejects any request whose proof doesn't match the `X-Agent-ID` wallet.
+
+This is automatic — no extra code beyond `private_key`. **Requires `oneshot-python >= 0.17.0`.** Older versions keep working until the API enables enforcement, after which they must send a valid `x-agent-proof`.
+
 ## Configuration
 
 ```python
@@ -87,6 +93,28 @@ The SDK operates on **Base Mainnet** with real USDC. Fund your wallet before mak
 - `call_free_post(endpoint, payload=None)` / `acall_free_post(...)` — POST
 - `call_free_patch(endpoint, payload=None)` / `acall_free_patch(...)` — PATCH
 
+### Sending domains — reputation + rotation
+
+Free, and scoped to the caller's own domains.
+
+```python
+for d in client.list_domains()["domains"]:
+    print(d["domain"], d["warmup_state"], d["warmup_score"], d["warmup_score_updated_at"])
+
+client.pause_domain("example.com")   # out of rotation, still owned
+client.resume_domain("example.com")  # back into rotation
+```
+
+- `list_domains()` / `alist_domains()` — pool + reputation for every domain the agent owns
+- `pause_domain(domain)` / `apause_domain(domain)`
+- `resume_domain(domain)` / `aresume_domain(domain)`
+
+`warmup_state` (reputation: `warming` | `warmed` | `degraded`) is orthogonal to `pool_status`
+(rotation: `active` | `paused` | `removed`) — a domain can be paused *and* warming. Two traps when
+reading `warmup_score`: it is `None` for a domain that was never enrolled in warmup, which is not
+the same as a score of `0` (check `warmup_started_at` to tell them apart), and it is refreshed by a
+poll-only reconciler, so it is only as current as `warmup_score_updated_at`.
+
 ### Compute — autonomous goal orchestration
 
 Launch a compute goal and let the orchestrator plan, execute, and iterate. Paid via x402 (same flow as other tools).
@@ -127,7 +155,7 @@ Every method has an `a*` async mirror (`acompute`, `aget_compute_goal`, …).
 ## Links
 
 - [Documentation](https://docs.oneshotagent.com/sdk/installation#install-via-pip-python)
-- [LangChain integration](https://pypi.org/project/langchain-oneshot/) — 31 tools as LangChain BaseTool
+- [LangChain integration](https://pypi.org/project/langchain-oneshot/) — 34 tools as LangChain BaseTool
 - [GAME plugin](https://pypi.org/project/game-plugin-oneshot/) — Virtuals Protocol integration
 - [TypeScript SDK](https://www.npmjs.com/package/@oneshot-agent/sdk)
 - [MCP Server](https://www.npmjs.com/package/@oneshot-agent/mcp-server)

{oneshot_python-0.15.0 → oneshot_python-0.18.0}/oneshot/__init__.py

@@ -20,6 +20,10 @@ from oneshot._types import (
     ComputeSchedule,
     ComputeTask,
     ComputeTaskResponseResult,
+    DomainAddressEntry,
+    DomainPoolEntry,
+    DomainPoolListResult,
+    DomainPoolStatusResult,
 )
 from oneshot.client import OneShotClient
 from oneshot.x402 import sign_payment_authorization
@@ -44,4 +48,8 @@ __all__ = [
     "ComputePauseResult",
     "ComputeResumeResult",
     "ComputeFundResult",
+    "DomainAddressEntry",
+    "DomainPoolEntry",
+    "DomainPoolListResult",
+    "DomainPoolStatusResult",
 ]

{oneshot_python-0.15.0 → oneshot_python-0.18.0}/oneshot/_types.py

@@ -1,4 +1,4 @@
-"""Type hints for the compute orchestration API.
+"""Type hints for the compute orchestration and email-domain APIs.
 
 These TypedDicts mirror libs/agent-sdk/src/types.ts field-for-field. They are
 optional at runtime — `OneShotClient` continues to return raw dicts — but
@@ -164,6 +164,53 @@ class ComputeFundResult(TypedDict, total=False):
     remaining: str
 
 
+class DomainAddressEntry(TypedDict, total=False):
+    """A mailbox already provisioned on a domain (`addresses[]` in the pool)."""
+
+    address: str
+    status: str  # active | provisioning | failed
+    warmup_state: str  # warming | warmed | degraded — per address
+
+
+class DomainPoolEntry(TypedDict, total=False):
+    """One sending domain. Mirrors `DomainPoolEntry` in TS.
+
+    `pool_status` is rotation eligibility; `warmup_state` is reputation health.
+    They are orthogonal — a domain can be `paused` AND still `warming`.
+    """
+
+    domain: str
+    default_from: str
+    addresses: list[DomainAddressEntry]
+    pool_status: str  # active | paused | removed
+    warmup_state: str  # warming | warmed | degraded
+    pause_reason: Optional[str]  # warming | low_reputation | manual | None
+    provisioning_status: str
+    warmup_score: Optional[int]
+    warmup_score_updated_at: Optional[str]
+    warmup_started_at: Optional[str]
+    daily_send_limit: int
+    daily_sent_count: int
+    daily_sent_date: Optional[str]
+    last_used_at: Optional[str]
+
+
+class DomainPoolListResult(TypedDict, total=False):
+    """Returned by `list_domains()`."""
+
+    agent_id: str
+    domains: list[DomainPoolEntry]
+
+
+class DomainPoolStatusResult(TypedDict, total=False):
+    """Returned by `pause_domain()` / `resume_domain()`."""
+
+    domain: str
+    pool_status: str  # active | paused
+    warmup_state: str
+    pause_reason: Optional[str]
+
+
 __all__ = [
     "ComputeSchedule",
     "ComputeGoalResult",
@@ -175,4 +222,8 @@ __all__ = [
     "ComputePauseResult",
     "ComputeResumeResult",
     "ComputeFundResult",
+    "DomainAddressEntry",
+    "DomainPoolEntry",
+    "DomainPoolListResult",
+    "DomainPoolStatusResult",
 ]

{oneshot_python-0.15.0 → oneshot_python-0.18.0}/oneshot/client.py

@@ -11,6 +11,7 @@ import asyncio
 import json
 import time
 from typing import Any, Optional
+from urllib.parse import quote
 
 import httpx
 from eth_account import Account
@@ -24,11 +25,16 @@ from oneshot._errors import (
     ToolError,
     ValidationError,
 )
+from oneshot._types import (
+    DomainPoolListResult,
+    DomainPoolStatusResult,
+)
 from oneshot.x402 import (
     build_zero_cost_authorization,
     encode_payment_header,
     parse_payment_required,
     sign_payment_authorization,
+    sign_read_proof,
 )
 
 # Derived from the installed package metadata so it never drifts from
@@ -38,7 +44,7 @@ try:
 
     SDK_VERSION = _pkg_version("oneshot-python")
 except Exception:  # pragma: no cover - editable/source runs without dist metadata
-    SDK_VERSION = "0.15.0"
+    SDK_VERSION = "0.18.0"
 
 # ---------------------------------------------------------------------------
 # Environment configuration
@@ -62,6 +68,7 @@ def _build_email_payload(
     extra: dict[str, Any],
     *,
     reply_to_email_id: Optional[str] = None,
+    mailbox_mode: Optional[str] = None,
 ) -> dict[str, Any]:
     """Build the /v1/tools/email/send body in the API's field convention.
 
@@ -93,6 +100,8 @@ def _build_email_payload(
         payload["reply_to_email_id"] = reply_to_email_id
     if from_name:
         payload["from_name"] = from_name
+    if mailbox_mode:
+        payload["mailbox_mode"] = mailbox_mode
     return payload
 
 
@@ -138,6 +147,20 @@ class OneShotClient:
             headers["X-Max-Cost-USDC"] = str(max_cost)
         return headers
 
+    def _read_headers(self) -> dict[str, str]:
+        """Auth headers plus a signed EIP-712 read proof (x-agent-proof) for the
+        free READ routes (inbox, sms inbox, notifications, balance, browser
+        profiles). These identify the caller by wallet, and wallet addresses are
+        public, so without a proof anyone could read another agent's data by
+        supplying its address. Signing failure falls back to plain headers (the
+        server runs log-only until read-proof enforcement is enabled)."""
+        headers = self._headers()
+        try:
+            headers["x-agent-proof"] = sign_read_proof(self._private_key, self.address)
+        except Exception as e:  # noqa: BLE001
+            self._log(f"Failed to sign read proof (continuing without): {e}")
+        return headers
+
     def _log(self, msg: str) -> None:
         if self.debug:
             print(f"[OneShot] {msg}")
@@ -362,7 +385,7 @@ class OneShotClient:
         """GET a free endpoint (async)."""
         url = f"{self.base_url}{endpoint}"
         async with httpx.AsyncClient(timeout=httpx.Timeout(30.0)) as client:
-            resp = await client.get(url, headers=self._headers(), params=params)
+            resp = await client.get(url, headers=self._read_headers(), params=params)
             if not resp.is_success:
                 raise ToolError(f"GET {endpoint} failed", resp.status_code, resp.text)
             return resp.json()
@@ -385,7 +408,7 @@ class OneShotClient:
         """POST to a free endpoint (async)."""
         url = f"{self.base_url}{endpoint}"
         async with httpx.AsyncClient(timeout=httpx.Timeout(30.0)) as client:
-            resp = await client.post(url, headers=self._headers(), json=payload or {})
+            resp = await client.post(url, headers=self._read_headers(), json=payload or {})
             if not resp.is_success:
                 raise ToolError(f"POST {endpoint} failed", resp.status_code, resp.text)
             return resp.json()
@@ -408,7 +431,7 @@ class OneShotClient:
         """PATCH a free endpoint (async)."""
         url = f"{self.base_url}{endpoint}"
         async with httpx.AsyncClient(timeout=httpx.Timeout(30.0)) as client:
-            resp = await client.patch(url, headers=self._headers(), json=payload or {})
+            resp = await client.patch(url, headers=self._read_headers(), json=payload or {})
             if not resp.is_success:
                 raise ToolError(f"PATCH {endpoint} failed", resp.status_code, resp.text)
             # PATCH may return empty body (204)
@@ -432,7 +455,7 @@ class OneShotClient:
         """DELETE a free endpoint (async)."""
         url = f"{self.base_url}{endpoint}"
         async with httpx.AsyncClient(timeout=httpx.Timeout(30.0)) as client:
-            resp = await client.delete(url, headers=self._headers())
+            resp = await client.delete(url, headers=self._read_headers())
             if not resp.is_success:
                 raise ToolError(f"DELETE {endpoint} failed", resp.status_code, resp.text)
             if resp.status_code == 204 or not resp.text:
@@ -760,6 +783,7 @@ class OneShotClient:
         from_mailbox: Optional[str] = None,
         from_name: Optional[str] = None,
         reply_to_email_id: Optional[str] = None,
+        mailbox_mode: Optional[str] = None,
         **kwargs: Any,
     ) -> Any:
         """Send an email. Blocking.
@@ -767,10 +791,21 @@ class OneShotClient:
         Set ``reply_to_email_id`` (an inbound email id from ``inbox()``) to
         reply within a thread — ``to``/``subject`` are then derived from the
         inbound message unless given.
+
+        The first send from any ``from_mailbox`` on an owned domain — including
+        the default ``agent@`` — provisions a mailbox per address and adds a
+        one-time ``mailbox_provisioning_fee`` to the quote; it's free only once
+        that address is already provisioned (``active``).
+
+        ``mailbox_mode`` ('relay' | 'mailbox', default 'relay') selects how a
+        domain sends: 'relay' is header-only send (no per-address mailbox, no
+        mailbox fee); 'mailbox' provisions a real dedicated mailbox per address
+        (better deliverability + per-address warmup). Only applies when a domain
+        is first set up — use it on a new ``from_domain``.
         """
         return self.call_tool(
             "/v1/tools/email/send",
-            _build_email_payload(to, subject, body, from_domain, from_mailbox, from_name, kwargs, reply_to_email_id=reply_to_email_id),
+            _build_email_payload(to, subject, body, from_domain, from_mailbox, from_name, kwargs, reply_to_email_id=reply_to_email_id, mailbox_mode=mailbox_mode),
         )
 
     async def aemail(
@@ -783,6 +818,7 @@ class OneShotClient:
         from_mailbox: Optional[str] = None,
         from_name: Optional[str] = None,
         reply_to_email_id: Optional[str] = None,
+        mailbox_mode: Optional[str] = None,
         **kwargs: Any,
     ) -> Any:
         """Send an email. Async.
@@ -790,10 +826,13 @@ class OneShotClient:
         Set ``reply_to_email_id`` (an inbound email id from ``ainbox()``) to
         reply within a thread — ``to``/``subject`` are then derived from the
         inbound message unless given.
+
+        ``mailbox_mode`` ('relay' | 'mailbox', default 'relay') selects how a
+        domain sends — see ``email()`` for details.
         """
         return await self.acall_tool(
             "/v1/tools/email/send",
-            _build_email_payload(to, subject, body, from_domain, from_mailbox, from_name, kwargs, reply_to_email_id=reply_to_email_id),
+            _build_email_payload(to, subject, body, from_domain, from_mailbox, from_name, kwargs, reply_to_email_id=reply_to_email_id, mailbox_mode=mailbox_mode),
         )
 
     def voice(self, objective: str, target_number: str, **kwargs: Any) -> Any:
@@ -958,6 +997,65 @@ class OneShotClient:
         """Get unified balance (on-chain USDC + credits). Async."""
         return await self.acall_free_get("/v1/tools/balance")
 
+    # ------------------------------------------------------------------
+    # Email domains — rotation pool + sender reputation
+    # ------------------------------------------------------------------
+    # All three endpoints are free. `pause`/`resume` sit behind the API's
+    # paidEndpointLimiter, but that is a rate limiter, not a price — no x402
+    # quote is issued, so they go through `call_free_post`, not `call_tool`.
+
+    def list_domains(self) -> DomainPoolListResult:
+        """List the caller's sending domains with reputation + rotation state. Blocking.
+
+        Each entry carries `pool_status` (rotation eligibility: active | paused |
+        removed), `warmup_state` (reputation health: warming | warmed | degraded),
+        `pause_reason`, `warmup_score`, daily send counters, and `addresses[]` —
+        the mailboxes already provisioned on the domain, each with its own
+        `warmup_state`.
+
+        Two things to know before trusting `warmup_score`:
+
+        - It is ``None`` when the domain was never enrolled in warmup. That is not
+          the same as "enrolled, no score yet" — check `warmup_started_at` to tell
+          the two apart.
+        - Scores are refreshed by a poll-only reconciler, so the number is only as
+          fresh as `warmup_score_updated_at`. A stale timestamp means a stale score,
+          not a current measurement.
+        """
+        return self.call_free_get("/v1/tools/email/domains")
+
+    async def alist_domains(self) -> DomainPoolListResult:
+        """List the caller's sending domains with reputation + rotation state. Async."""
+        return await self.acall_free_get("/v1/tools/email/domains")
+
+    def pause_domain(self, domain: str) -> DomainPoolStatusResult:
+        """Take a domain out of rotation without releasing it. Blocking."""
+        return asyncio.get_event_loop().run_until_complete(self.apause_domain(domain))
+
+    async def apause_domain(self, domain: str) -> DomainPoolStatusResult:
+        """Take a domain out of rotation without releasing it. Async."""
+        return await self.acall_free_post(self._domain_action_path(domain, "pause"))
+
+    def resume_domain(self, domain: str) -> DomainPoolStatusResult:
+        """Put a paused domain back into rotation. Blocking."""
+        return asyncio.get_event_loop().run_until_complete(self.aresume_domain(domain))
+
+    async def aresume_domain(self, domain: str) -> DomainPoolStatusResult:
+        """Put a paused domain back into rotation. Async.
+
+        Reputation pauses (`pause_reason='low_reputation'`) auto-recover once the
+        domain is warmed again; a manual pause needs this call.
+        """
+        return await self.acall_free_post(self._domain_action_path(domain, "resume"))
+
+    @staticmethod
+    def _domain_action_path(domain: str, action: str) -> str:
+        """Build `/v1/tools/email/domains/<domain>/<action>` with the domain
+        percent-encoded (matches the TS SDK's encodeURIComponent)."""
+        if not domain:
+            raise ValidationError("domain is required", "domain")
+        return f"/v1/tools/email/domains/{quote(domain, safe='')}/{action}"
+
     # ------------------------------------------------------------------
     # Receipts — value tagging (RoCS)
     # ------------------------------------------------------------------

{oneshot_python-0.15.0 → oneshot_python-0.18.0}/oneshot/x402.py

@@ -249,3 +249,49 @@ def _parse_usdc_amount(amount: str) -> int:
     # Pad or truncate fractional part to 6 digits
     frac_str = parts[1][:6].ljust(6, "0")
     return whole * 1_000_000 + int(frac_str)
+
+
+def sign_read_proof(private_key: str, address: str, scope: str = "read") -> str:
+    """Build a signed EIP-712 agent read proof — the `x-agent-proof` header value.
+
+    Mirrors the TS SDK's signedReadHeaders() and the server's AgentReadAuth
+    verification (api-service middleware/agent-proof-auth.ts). The agent READ
+    routes (inbox, sms inbox, notifications, balance, browser profiles) identify
+    the caller by wallet; without a proof anyone could read another agent's data
+    by supplying its public address. This binds the request to the wallet the SDK
+    controls. A fresh nonce per call bounds replay.
+    """
+    domain_data = {"name": "OneShot Agent Auth", "version": "1"}
+    message_types = {
+        "AgentReadAuth": [
+            {"name": "agent", "type": "address"},
+            {"name": "scope", "type": "string"},
+            {"name": "issuedAt", "type": "uint256"},
+            {"name": "nonce", "type": "bytes32"},
+        ],
+    }
+    issued_at = int(time.time())
+    nonce_bytes = os.urandom(32)
+    message_data = {
+        "agent": address,
+        "scope": scope,
+        "issuedAt": issued_at,
+        "nonce": nonce_bytes,
+    }
+    signable = encode_typed_data(
+        domain_data=domain_data,
+        message_types=message_types,
+        message_data=message_data,
+    )
+    signed = Account.sign_message(signable, private_key=private_key)
+    signature = "0x" + (
+        signed.signature.hex() if isinstance(signed.signature, bytes) else format(signed.signature, "x")
+    )
+    proof = {
+        "agent": address,
+        "scope": scope,
+        "issuedAt": issued_at,
+        "nonce": "0x" + nonce_bytes.hex(),
+        "signature": signature,
+    }
+    return base64.b64encode(json.dumps(proof).encode("utf-8")).decode("ascii")

{oneshot_python-0.15.0 → oneshot_python-0.18.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "oneshot-python"
-version = "0.15.0"
+version = "0.18.0"
 description = "Core Python SDK for the OneShot API — HTTP client with x402 payment handling"
 readme = {text = "Core Python SDK for the OneShot API", content-type = "text/plain"}
 license = "MIT"

oneshot_python-0.18.0/tests/test_domains.py

@@ -0,0 +1,208 @@
+"""Tests for the email-domain methods on OneShotClient.
+
+Covers list_domains / pause_domain / resume_domain (sync + async): the exact
+endpoints hit, percent-encoding of the domain path segment, and the empty-domain
+guard. All three endpoints are free, so they must route through the
+`call_free_get` / `call_free_post` helpers — never `call_tool` (which would open
+an x402 quote-and-pay flow for a read).
+"""
+
+from __future__ import annotations
+
+from unittest.mock import AsyncMock, patch
+
+import pytest
+from eth_account import Account
+
+from oneshot._errors import ValidationError
+from oneshot.client import OneShotClient
+
+# Deterministic test key (never use with real funds)
+TEST_PRIVATE_KEY = "0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80"
+TEST_ADDRESS = Account.from_key(TEST_PRIVATE_KEY).address
+
+MOCK_DOMAINS_RESPONSE = {
+    "agent_id": "39c6fd04-acfc-4be4-bb35-0e8f6523d8e7",
+    "domains": [
+        {
+            "domain": "warmed-example.com",
+            "default_from": "agent@warmed-example.com",
+            "addresses": [
+                {
+                    "address": "agent@warmed-example.com",
+                    "status": "active",
+                    "warmup_state": "warmed",
+                }
+            ],
+            "pool_status": "active",
+            "warmup_state": "warmed",
+            "pause_reason": None,
+            "provisioning_status": "active",
+            "warmup_score": 98,
+            "warmup_score_updated_at": "2026-08-13T18:00:05.497Z",
+            "warmup_started_at": "2026-06-25T14:07:43.230Z",
+            "daily_send_limit": 100,
+            "daily_sent_count": 5,
+            "daily_sent_date": "2026-08-13",
+            "last_used_at": "2026-08-13T17:12:00.000Z",
+        },
+        {
+            # Never enrolled in warmup: score is None, not 0. Callers must not
+            # read this as "reputation zero".
+            "domain": "never-enrolled.com",
+            "default_from": "agent@never-enrolled.com",
+            "addresses": [],
+            "pool_status": "paused",
+            "warmup_state": "warming",
+            "pause_reason": "warming",
+            "provisioning_status": "active",
+            "warmup_score": None,
+            "warmup_score_updated_at": None,
+            "warmup_started_at": None,
+            "daily_send_limit": 50,
+            "daily_sent_count": 0,
+            "daily_sent_date": None,
+            "last_used_at": None,
+        },
+    ],
+}
+
+MOCK_STATUS_RESPONSE = {
+    "domain": "warmed-example.com",
+    "pool_status": "paused",
+    "warmup_state": "warmed",
+    "pause_reason": "manual",
+}
+
+
+class TestListDomains:
+    """Synchronous list_domains() tests."""
+
+    def test_calls_correct_endpoint(self) -> None:
+        client = OneShotClient(TEST_PRIVATE_KEY)
+
+        with patch.object(client, "call_free_get", return_value=MOCK_DOMAINS_RESPONSE) as mock:
+            result = client.list_domains()
+
+        mock.assert_called_once_with("/v1/tools/email/domains")
+        assert result == MOCK_DOMAINS_RESPONSE
+
+    def test_surfaces_reputation_fields(self) -> None:
+        client = OneShotClient(TEST_PRIVATE_KEY)
+
+        with patch.object(client, "call_free_get", return_value=MOCK_DOMAINS_RESPONSE):
+            domains = client.list_domains()["domains"]
+
+        warmed, never_enrolled = domains
+        assert warmed["warmup_state"] == "warmed"
+        assert warmed["warmup_score"] == 98
+        assert warmed["warmup_score_updated_at"] == "2026-08-13T18:00:05.497Z"
+        assert warmed["addresses"][0]["warmup_state"] == "warmed"
+        # Never enrolled: null score, null started_at — distinct from a real 0.
+        assert never_enrolled["warmup_score"] is None
+        assert never_enrolled["warmup_started_at"] is None
+
+    def test_propagates_errors(self) -> None:
+        client = OneShotClient(TEST_PRIVATE_KEY)
+
+        with patch.object(client, "call_free_get", side_effect=Exception("Network error")):
+            with pytest.raises(Exception, match="Network error"):
+                client.list_domains()
+
+
+class TestAlistDomains:
+    """Async alist_domains() tests."""
+
+    @pytest.mark.asyncio
+    async def test_calls_correct_endpoint(self) -> None:
+        client = OneShotClient(TEST_PRIVATE_KEY)
+
+        with patch.object(
+            client, "acall_free_get", new_callable=AsyncMock, return_value=MOCK_DOMAINS_RESPONSE
+        ) as mock:
+            result = await client.alist_domains()
+
+        mock.assert_called_once_with("/v1/tools/email/domains")
+        assert result == MOCK_DOMAINS_RESPONSE
+
+    @pytest.mark.asyncio
+    async def test_propagates_errors(self) -> None:
+        client = OneShotClient(TEST_PRIVATE_KEY)
+
+        with patch.object(
+            client, "acall_free_get", new_callable=AsyncMock, side_effect=Exception("Timeout")
+        ):
+            with pytest.raises(Exception, match="Timeout"):
+                await client.alist_domains()
+
+
+class TestPauseResumeDomain:
+    """pause_domain() / resume_domain(), sync + async."""
+
+    @pytest.mark.asyncio
+    async def test_pause_calls_correct_endpoint(self) -> None:
+        client = OneShotClient(TEST_PRIVATE_KEY)
+
+        with patch.object(
+            client, "acall_free_post", new_callable=AsyncMock, return_value=MOCK_STATUS_RESPONSE
+        ) as mock:
+            result = await client.apause_domain("warmed-example.com")
+
+        mock.assert_called_once_with("/v1/tools/email/domains/warmed-example.com/pause")
+        assert result == MOCK_STATUS_RESPONSE
+
+    @pytest.mark.asyncio
+    async def test_resume_calls_correct_endpoint(self) -> None:
+        client = OneShotClient(TEST_PRIVATE_KEY)
+
+        with patch.object(
+            client, "acall_free_post", new_callable=AsyncMock, return_value=MOCK_STATUS_RESPONSE
+        ) as mock:
+            await client.aresume_domain("warmed-example.com")
+
+        mock.assert_called_once_with("/v1/tools/email/domains/warmed-example.com/resume")
+
+    @pytest.mark.asyncio
+    async def test_encodes_the_domain_segment(self) -> None:
+        """A domain with a slash must not escape into a different route."""
+        client = OneShotClient(TEST_PRIVATE_KEY)
+
+        with patch.object(
+            client, "acall_free_post", new_callable=AsyncMock, return_value=MOCK_STATUS_RESPONSE
+        ) as mock:
+            await client.apause_domain("evil.com/../../admin")
+
+        mock.assert_called_once_with(
+            "/v1/tools/email/domains/evil.com%2F..%2F..%2Fadmin/pause"
+        )
+
+    @pytest.mark.asyncio
+    async def test_rejects_empty_domain(self) -> None:
+        client = OneShotClient(TEST_PRIVATE_KEY)
+
+        with pytest.raises(ValidationError):
+            await client.apause_domain("")
+        with pytest.raises(ValidationError):
+            await client.aresume_domain("")
+
+    def test_sync_pause_delegates_to_async(self) -> None:
+        client = OneShotClient(TEST_PRIVATE_KEY)
+
+        with patch.object(
+            client, "apause_domain", new_callable=AsyncMock, return_value=MOCK_STATUS_RESPONSE
+        ) as mock:
+            result = client.pause_domain("warmed-example.com")
+
+        mock.assert_called_once_with("warmed-example.com")
+        assert result == MOCK_STATUS_RESPONSE
+
+    def test_sync_resume_delegates_to_async(self) -> None:
+        client = OneShotClient(TEST_PRIVATE_KEY)
+
+        with patch.object(
+            client, "aresume_domain", new_callable=AsyncMock, return_value=MOCK_STATUS_RESPONSE
+        ) as mock:
+            result = client.resume_domain("warmed-example.com")
+
+        mock.assert_called_once_with("warmed-example.com")
+        assert result == MOCK_STATUS_RESPONSE

{oneshot_python-0.15.0 → oneshot_python-0.18.0}/tests/test_email_payload.py

@@ -46,6 +46,18 @@ def test_payload_passes_extra_kwargs():
     assert p["wait"] is True
 
 
+def test_payload_forwards_mailbox_mode():
+    # mailbox_mode is an explicit keyword-only param, forwarded into the send body so
+    # the API's per-domain provider override + fee logic sees it.
+    p = _build_email_payload("r@x.com", "S", "B", "acme.com", None, None, {}, mailbox_mode="mailbox")
+    assert p["mailbox_mode"] == "mailbox"
+
+
+def test_payload_omits_mailbox_mode_when_absent():
+    p = _build_email_payload("r@x.com", "S", "B", "acme.com", None, None, {})
+    assert "mailbox_mode" not in p
+
+
 # ── reply threading (reply_to_email_id) ───────────────────────────────────
 
 def test_reply_payload_omits_to_and_subject_when_derivable():

{oneshot_python-0.15.0 → oneshot_python-0.18.0}/tests/test_tag_receipt_value.py

@@ -105,10 +105,11 @@ def test_sync_wrapper_delegates_to_async(monkeypatch):
     c = OneShotClient(TEST_PRIVATE_KEY)
     called: dict = {}
 
-    async def fake_async(receipt_id=None, value_tag=None, *, request_id=None):
+    async def fake_async(receipt_id=None, value_tag=None, *, request_id=None, goal_id=None):
         called["receipt_id"] = receipt_id
         called["value_tag"] = value_tag
         called["request_id"] = request_id
+        called["goal_id"] = goal_id
         return {"ok": True}
 
     c.atag_receipt_value = fake_async  # type: ignore[method-assign]
@@ -118,4 +119,5 @@ def test_sync_wrapper_delegates_to_async(monkeypatch):
         "receipt_id": "rcpt_01HX",
         "value_tag": {"type": "savings", "amount": 12},
         "request_id": None,
+        "goal_id": None,
     }