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

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

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

@@ -6,6 +6,7 @@ from oneshot._errors import (
     JobError,
     JobTimeoutError,
     OneShotError,
+    PaymentError,
     ToolError,
     ValidationError,
 )
@@ -32,6 +33,7 @@ __all__ = [
     "OneShotClient",
     "OneShotError",
     "ToolError",
+    "PaymentError",
     "JobError",
     "JobTimeoutError",
     "ValidationError",

{oneshot_python-0.18.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.18.0 → oneshot_python-0.19.0}/oneshot/client.py

@@ -10,6 +10,7 @@ from __future__ import annotations
 import asyncio
 import json
 import time
+from decimal import Decimal
 from typing import Any, Optional
 from urllib.parse import quote
 
@@ -22,6 +23,7 @@ from oneshot._errors import (
     JobError,
     JobTimeoutError,
     OneShotError,
+    PaymentError,
     ToolError,
     ValidationError,
 )
@@ -44,7 +46,7 @@ try:
 
     SDK_VERSION = _pkg_version("oneshot-python")
 except Exception:  # pragma: no cover - editable/source runs without dist metadata
-    SDK_VERSION = "0.18.0"
+    SDK_VERSION = "0.19.0"
 
 # ---------------------------------------------------------------------------
 # Environment configuration
@@ -105,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.
 
@@ -297,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(
@@ -319,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']}",
@@ -339,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,

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

@@ -1,6 +1,6 @@
 [project]
 name = "oneshot-python"
-version = "0.18.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_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)