oneshot-python 0.16.0__tar.gz → 0.19.0__tar.gz

{oneshot_python-0.16.0 → oneshot_python-0.19.0}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: oneshot-python
-Version: 0.16.0
+Version: 0.19.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.16.0 → oneshot_python-0.19.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.16.0 → oneshot_python-0.19.0}/oneshot/__init__.py

@@ -6,6 +6,7 @@ from oneshot._errors import (
     JobError,
     JobTimeoutError,
     OneShotError,
+    PaymentError,
     ToolError,
     ValidationError,
 )
@@ -20,6 +21,10 @@ from oneshot._types import (
     ComputeSchedule,
     ComputeTask,
     ComputeTaskResponseResult,
+    DomainAddressEntry,
+    DomainPoolEntry,
+    DomainPoolListResult,
+    DomainPoolStatusResult,
 )
 from oneshot.client import OneShotClient
 from oneshot.x402 import sign_payment_authorization
@@ -28,6 +33,7 @@ __all__ = [
     "OneShotClient",
     "OneShotError",
     "ToolError",
+    "PaymentError",
     "JobError",
     "JobTimeoutError",
     "ValidationError",
@@ -44,4 +50,8 @@ __all__ = [
     "ComputePauseResult",
     "ComputeResumeResult",
     "ComputeFundResult",
+    "DomainAddressEntry",
+    "DomainPoolEntry",
+    "DomainPoolListResult",
+    "DomainPoolStatusResult",
 ]

{oneshot_python-0.16.0 → oneshot_python-0.19.0}/oneshot/_errors.py

@@ -14,6 +14,33 @@ class ToolError(OneShotError):
         self.response_body = response_body
 
 
+class PaymentError(OneShotError):
+    """The facilitator rejected the payment signed for this request.
+
+    Distinct from the ordinary 402 that opens the quote-pay handshake: this is a
+    402 arriving on the PAID retry, meaning the signature was refused.
+    ``reason`` is the facilitator's machine-readable code
+    (``insufficient_funds``, ``invalid_exact_evm_payload_authorization_value``,
+    …) and ``expected`` / ``received`` name the amounts when the two disagree —
+    the case that produced a silent, bodiless 402 before the server started
+    reporting it.
+    """
+
+    def __init__(
+        self,
+        message: str,
+        reason: str,
+        expected: dict | None = None,
+        received: dict | None = None,
+        quote_id: str | None = None,
+    ) -> None:
+        super().__init__(message)
+        self.reason = reason
+        self.expected = expected or {}
+        self.received = received or {}
+        self.quote_id = quote_id
+
+
 class JobError(OneShotError):
     """Async job completed with an error."""
 

{oneshot_python-0.16.0 → oneshot_python-0.19.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.16.0 → oneshot_python-0.19.0}/oneshot/client.py

@@ -10,7 +10,9 @@ from __future__ import annotations
 import asyncio
 import json
 import time
+from decimal import Decimal
 from typing import Any, Optional
+from urllib.parse import quote
 
 import httpx
 from eth_account import Account
@@ -21,14 +23,20 @@ from oneshot._errors import (
     JobError,
     JobTimeoutError,
     OneShotError,
+    PaymentError,
     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 +46,7 @@ try:
 
     SDK_VERSION = _pkg_version("oneshot-python")
 except Exception:  # pragma: no cover - editable/source runs without dist metadata
-    SDK_VERSION = "0.16.0"
+    SDK_VERSION = "0.19.0"
 
 # ---------------------------------------------------------------------------
 # Environment configuration
@@ -99,6 +107,82 @@ def _build_email_payload(
     return payload
 
 
+def _parse_payment_rejection(resp: Any) -> Optional[PaymentError]:
+    """Build a ``PaymentError`` from a 402 that names its own cause.
+
+    The API attaches ``error='payment_verification_failed'`` plus the
+    facilitator's reason and the expected/received amounts when a presented
+    payment is refused. Returns None for any other response so the caller can
+    fall back to ``ToolError``.
+    """
+    if resp.status_code != 402:
+        return None
+    try:
+        data = resp.json()
+    except Exception:  # noqa: BLE001 - non-JSON body
+        return None
+    if not isinstance(data, dict) or data.get("error") != "payment_verification_failed":
+        return None
+
+    reason = data.get("reason") or "unknown"
+    expected = data.get("expected") or {}
+    received = data.get("received") or {}
+    detail = ", ".join(
+        part for part in (
+            f"expected ${expected.get('amount')}" if expected.get("amount") else None,
+            f"signed ${received.get('amount')}" if received.get("amount") else None,
+        ) if part
+    )
+    message = f"payment rejected: {reason}"
+    if detail:
+        message += f" — {detail}"
+    if data.get("message"):
+        message += f" ({data['message']})"
+
+    return PaymentError(
+        message,
+        reason,
+        expected={
+            "amount": expected.get("amount"),
+            "asset": expected.get("asset"),
+            "network": expected.get("network"),
+            "pay_to": expected.get("pay_to"),
+        },
+        received={"amount": received.get("amount")},
+        quote_id=data.get("quote_id"),
+    )
+
+
+def _resolve_charge_amount(accepted: Any, payment_request: dict[str, Any]) -> str:
+    """The amount to sign, in decimal USDC.
+
+    A 402 advertises its price twice: the x402 v2 ``PAYMENT-REQUIRED`` header
+    (``accepts[0].amount``, atomic units) and the legacy JSON body
+    (``payment_request.amount``, decimal). The header is authoritative — it is
+    what the server rebuilds its requirement from and what
+    ``findMatchingRequirements`` compares against.
+
+    Reading the body alone is how quote-based routes (email/send, sms, voice,
+    build, commerce/buy, compute) silently broke: the body carried a hardcoded
+    ``"0.00"``, so this client took the ``amount == 0`` branch and sent a
+    ZERO-COST authorization against a real charge. The server rejected it with
+    a bodiless 402 and the caller had nothing to go on.
+
+    Falls back to the body when the header is absent or unparseable.
+    """
+    atomic = accepted.get("amount") if isinstance(accepted, dict) else None
+    body = payment_request.get("amount")
+    if not (isinstance(atomic, str) and atomic.isdigit()):
+        return str(body)
+
+    from_header = str(Decimal(atomic) / Decimal(10**6))
+    # When the two agree (every fixed-price route), keep the body's string
+    # verbatim; only a genuine disagreement flips to the header.
+    if body is not None and float(body) == float(from_header):
+        return str(body)
+    return from_header
+
+
 class OneShotClient:
     """Synchronous + async HTTP client for the OneShot API.
 
@@ -141,6 +225,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}")
@@ -277,7 +375,8 @@ class OneShotClient:
             self._log(f"Payment required: {payment_request['amount']} USDC")
 
             # Step 3 — Sign x402 payment (zero-cost auth if credits cover full cost)
-            amount = float(payment_request["amount"])
+            charge = _resolve_charge_amount(accepted, payment_request)
+            amount = float(charge)
             if amount == 0:
                 self._log("Credits cover full cost — sending zero-cost authorization")
                 auth = build_zero_cost_authorization(
@@ -299,7 +398,7 @@ class OneShotClient:
                     private_key=self._private_key,
                     from_address=self.address,
                     to_address=payment_request["recipient"],
-                    amount=payment_request["amount"],
+                    amount=charge,
                     token_address=payment_request["token_address"],
                     chain_id=payment_request["chain_id"],
                     network=f"eip155:{payment_request['chain_id']}",
@@ -319,6 +418,12 @@ class OneShotClient:
                 resp2 = await client.post(url, headers=headers, json=payload)
 
             if resp2.status_code not in (200, 201, 202):
+                # A 402 here means the facilitator refused the signature — not
+                # the ordinary quote-pay 402 handled above. The API names the
+                # cause, so raise the specific error rather than a generic one.
+                rejection = _parse_payment_rejection(resp2)
+                if rejection is not None:
+                    raise rejection
                 raise ToolError(
                     "Tool request failed after payment",
                     resp2.status_code,
@@ -365,7 +470,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()
@@ -388,7 +493,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()
@@ -411,7 +516,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)
@@ -435,7 +540,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:
@@ -977,6 +1082,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.16.0 → oneshot_python-0.19.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.16.0 → oneshot_python-0.19.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "oneshot-python"
-version = "0.16.0"
+version = "0.19.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.19.0/tests/test_charge_amount.py

@@ -0,0 +1,57 @@
+"""The signed amount comes from the PAYMENT-REQUIRED header, not the body.
+
+A 402 advertises its price twice — the x402 v2 header (atomic units) and the
+legacy JSON body (decimal). They disagreed on quote-based routes: the body
+carried a hardcoded "0.00" while the header carried the real total. Reading the
+body made this client take the `amount == 0` branch and send a ZERO-COST
+authorization against a real charge, which the server rejected with a bodiless
+402 (observed in prod on email/send: $20.00 quote, body said 0.00).
+"""
+
+from __future__ import annotations
+
+import pytest
+
+from oneshot.client import _resolve_charge_amount
+
+
+def _accepted(atomic: str) -> dict:
+    return {
+        "scheme": "exact",
+        "network": "eip155:8453",
+        "amount": atomic,
+        "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
+        "payTo": "0x9fb365E4E9385E2a39FeBAd70368267e6f571d9A",
+    }
+
+
+class TestResolveChargeAmount:
+    def test_header_wins_over_a_zeroed_body(self) -> None:
+        """The prod incident: header $20, body "0.00"."""
+        amount = _resolve_charge_amount(_accepted("20000000"), {"amount": "0.00"})
+        assert float(amount) == 20.0
+
+    def test_never_takes_the_zero_cost_branch_on_a_real_charge(self) -> None:
+        amount = _resolve_charge_amount(_accepted("20000000"), {"amount": "0.00"})
+        assert float(amount) != 0
+
+    @pytest.mark.parametrize(
+        "atomic,expected",
+        [("10000", 0.01), ("1431000", 1.431), ("250000000", 250.0), ("1000", 0.001)],
+    )
+    def test_atomic_to_decimal(self, atomic: str, expected: float) -> None:
+        assert float(_resolve_charge_amount(_accepted(atomic), {"amount": "0.00"})) == expected
+
+    def test_falls_back_to_body_when_header_missing(self) -> None:
+        assert float(_resolve_charge_amount(None, {"amount": "0.05"})) == 0.05
+
+    def test_falls_back_to_body_when_header_amount_unparseable(self) -> None:
+        assert float(_resolve_charge_amount({"amount": "not-a-number"}, {"amount": "0.05"})) == 0.05
+
+    def test_genuine_zero_still_reads_as_zero(self) -> None:
+        """Credits covering the full cost must still take the zero-cost path."""
+        assert float(_resolve_charge_amount(_accepted("0"), {"amount": "0.00"})) == 0.0
+
+    def test_no_float_artifacts(self) -> None:
+        """Decimal conversion, so the signed string matches the server's requirement."""
+        assert _resolve_charge_amount(_accepted("1431000"), {"amount": "0.00"}) == "1.431"

oneshot_python-0.19.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.19.0/tests/test_payment_rejection.py

@@ -0,0 +1,88 @@
+"""A refused payment raises PaymentError, not a generic ToolError.
+
+The API now names the cause of a rejected payment in the 402 body
+(`payment_verification_failed` + reason + expected/received amounts). The client
+surfaces that as a typed error so callers can branch on `err.reason` instead of
+string-matching a response body — which was empty before the server started
+reporting it.
+"""
+
+from __future__ import annotations
+
+from oneshot._errors import PaymentError
+from oneshot.client import _parse_payment_rejection
+
+
+class _Resp:
+    """Minimal httpx.Response stand-in."""
+
+    def __init__(self, status_code: int, payload=None, raises: bool = False) -> None:
+        self.status_code = status_code
+        self._payload = payload
+        self._raises = raises
+        self.text = "" if payload is None else str(payload)
+
+    def json(self):
+        if self._raises:
+            raise ValueError("not json")
+        return self._payload
+
+
+REJECTION = {
+    "error": "payment_verification_failed",
+    "reason": "invalid_exact_evm_payload_authorization_value",
+    "message": "authorization value does not match requirement",
+    "expected": {
+        "amount": "20.000000",
+        "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
+        "network": "eip155:8453",
+        "pay_to": "0x9fb365E4E9385E2a39FeBAd70368267e6f571d9A",
+    },
+    "received": {"amount": "0"},
+    "quote_id": "quote_01KZYBN6AE00K8PS29P5469KJM",
+}
+
+
+class TestParsePaymentRejection:
+    def test_builds_a_payment_error(self) -> None:
+        err = _parse_payment_rejection(_Resp(402, REJECTION))
+        assert isinstance(err, PaymentError)
+        assert err.reason == "invalid_exact_evm_payload_authorization_value"
+        assert err.expected["amount"] == "20.000000"
+        assert err.received["amount"] == "0"
+        assert err.quote_id == "quote_01KZYBN6AE00K8PS29P5469KJM"
+
+    def test_message_states_both_amounts(self) -> None:
+        """The whole point: the caller can see the mismatch without server logs."""
+        err = _parse_payment_rejection(_Resp(402, REJECTION))
+        assert "expected $20.000000" in str(err)
+        assert "signed $0" in str(err)
+        assert "invalid_exact_evm_payload_authorization_value" in str(err)
+
+    def test_tolerates_a_reasonless_rejection(self) -> None:
+        err = _parse_payment_rejection(_Resp(402, {"error": "payment_verification_failed"}))
+        assert isinstance(err, PaymentError)
+        assert err.reason == "unknown"
+        assert err.expected["amount"] is None
+
+    def test_ignores_the_ordinary_quote_leg_402(self) -> None:
+        """The quote-pay handshake's 402 is not an error — must not raise."""
+        quote_402 = {
+            "error": "payment_required",
+            "code": 402,
+            "payment_request": {"amount": "20.000000", "recipient": "0x9fb3"},
+        }
+        assert _parse_payment_rejection(_Resp(402, quote_402)) is None
+
+    def test_ignores_non_402(self) -> None:
+        assert _parse_payment_rejection(_Resp(500, {"error": "boom"})) is None
+
+    def test_ignores_a_non_json_body(self) -> None:
+        assert _parse_payment_rejection(_Resp(402, raises=True)) is None
+
+    def test_payment_error_is_a_oneshot_error(self) -> None:
+        from oneshot import OneShotError, PaymentError as Exported
+
+        err = _parse_payment_rejection(_Resp(402, REJECTION))
+        assert isinstance(err, OneShotError)
+        assert isinstance(err, Exported)

{oneshot_python-0.16.0 → oneshot_python-0.19.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,
     }