oneshot-python 0.10.0__tar.gz → 0.11.0__tar.gz

{oneshot_python-0.10.0 → oneshot_python-0.11.0}/.gitignore

@@ -81,3 +81,12 @@ apps/video-service/out/
 
 # Simulate-players pool (auto-generated, contains player IDs)
 scripts/.simulate-pool.json
+
+# x402 Bazaar seeder wallet (ephemeral, holds a private key during a partial run)
+scripts/.seed-wallet.json
+
+# Generated digest outputs from scripts/weekly-signal-digest.ts
+output/
+
+# Claude Code agent metadata (lockfile + local settings)
+.claude/

{oneshot_python-0.10.0 → oneshot_python-0.11.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: oneshot-python
-Version: 0.10.0
+Version: 0.11.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.10.0 → oneshot_python-0.11.0}/oneshot/__init__.py

@@ -2,6 +2,7 @@
 
 from oneshot._errors import (
     ContentBlockedError,
+    EmergencyNumberError,
     JobError,
     JobTimeoutError,
     OneShotError,
@@ -19,5 +20,6 @@ __all__ = [
     "JobTimeoutError",
     "ValidationError",
     "ContentBlockedError",
+    "EmergencyNumberError",
     "sign_payment_authorization",
 ]

{oneshot_python-0.10.0 → oneshot_python-0.11.0}/oneshot/_errors.py

@@ -46,3 +46,11 @@ class ContentBlockedError(OneShotError):
     def __init__(self, message: str, categories: list[str]) -> None:
         super().__init__(message)
         self.categories = categories
+
+
+class EmergencyNumberError(OneShotError):
+    """Voice call rejected because the target number is an emergency line."""
+
+    def __init__(self, message: str, blocked_number: str) -> None:
+        super().__init__(message)
+        self.blocked_number = blocked_number

{oneshot_python-0.10.0 → oneshot_python-0.11.0}/oneshot/client.py

@@ -17,6 +17,7 @@ from eth_account import Account
 
 from oneshot._errors import (
     ContentBlockedError,
+    EmergencyNumberError,
     JobError,
     JobTimeoutError,
     OneShotError,
@@ -30,7 +31,7 @@ from oneshot.x402 import (
     sign_payment_authorization,
 )
 
-SDK_VERSION = "0.8.3"
+SDK_VERSION = "0.11.0"
 
 # ---------------------------------------------------------------------------
 # Environment configuration
@@ -44,6 +45,35 @@ _POLL_INTERVAL = 2.0  # seconds
 _MAX_POLL_RETRIES = 3
 
 
+def _build_email_payload(
+    to: str,
+    subject: str,
+    body: str,
+    from_domain: Optional[str],
+    from_mailbox: Optional[str],
+    from_name: Optional[str],
+    extra: dict[str, Any],
+) -> dict[str, Any]:
+    """Build the /v1/tools/email/send body in the API's field convention.
+
+    The API expects ``from_address`` + ``to_address`` (see
+    EmailSendRequestSchema). Construct from_address from the mailbox/domain
+    and forward the optional display name.
+    """
+    mailbox = from_mailbox or "agent"
+    domain = from_domain or "oneshotagent.com"
+    payload: dict[str, Any] = {
+        "from_address": f"{mailbox}@{domain}",
+        "to_address": to,
+        "subject": subject,
+        "body": body,
+        **extra,
+    }
+    if from_name:
+        payload["from_name"] = from_name
+    return payload
+
+
 class OneShotClient:
     """Synchronous + async HTTP client for the OneShot API.
 
@@ -72,12 +102,19 @@ class OneShotClient:
     # Headers
     # ------------------------------------------------------------------
 
-    def _headers(self) -> dict[str, str]:
-        return {
+    def _headers(self, max_cost: Optional[float] = None) -> dict[str, str]:
+        headers = {
             "Content-Type": "application/json",
             "X-Agent-ID": self.address,
             "X-OneShot-SDK-Version": SDK_VERSION,
         }
+        # Server-side budget cap. The API rejects with HTTP 400
+        # `exceeds_caller_budget` before requesting payment if the quoted
+        # total exceeds this cap. The local fast-fail below stays as defense
+        # in depth.
+        if max_cost is not None and max_cost > 0:
+            headers["X-Max-Cost-USDC"] = str(max_cost)
+        return headers
 
     def _log(self, msg: str) -> None:
         if self.debug:
@@ -154,9 +191,9 @@ class OneShotClient:
 
         async with httpx.AsyncClient(timeout=httpx.Timeout(120.0)) as client:
             # Step 1 — Initial POST (expect 402 for paid tools)
-            resp = await client.post(url, headers=self._headers(), json=payload)
+            resp = await client.post(url, headers=self._headers(max_cost=max_cost), json=payload)
 
-            # Handle validation / content-blocked errors
+            # Handle validation / content-blocked / emergency-number errors
             if resp.status_code == 400:
                 data = resp.json()
                 err_type = data.get("error", "")
@@ -165,6 +202,11 @@ class OneShotClient:
                         data.get("message", "Content blocked"),
                         data.get("categories", []),
                     )
+                if err_type == "emergency_number_blocked":
+                    raise EmergencyNumberError(
+                        data.get("message", "Emergency number blocked"),
+                        data.get("blocked_number", ""),
+                    )
                 raise ValidationError(
                     data.get("message", "Invalid request"), "request"
                 )
@@ -221,7 +263,7 @@ class OneShotClient:
                     extensions=parsed_req.get("extensions"),
                 )
                 headers = {
-                    **self._headers(),
+                    **self._headers(max_cost=max_cost),
                     "payment-signature": encode_payment_header(auth),
                 }
                 if quote_id:
@@ -243,7 +285,7 @@ class OneShotClient:
 
                 # Step 4 — Re-POST with payment headers (x402 format)
                 headers = {
-                    **self._headers(),
+                    **self._headers(max_cost=max_cost),
                     "payment-signature": encode_payment_header(auth),
                 }
                 if quote_id:
@@ -485,19 +527,39 @@ class OneShotClient:
         """Read a web page and extract content as markdown. Async."""
         return await self.acall_tool("/v1/tools/web-read", {"url": url, **kwargs})
 
-    def email(self, to: str, subject: str, body: str, *, from_domain: Optional[str] = None, **kwargs: Any) -> Any:
+    def email(
+        self,
+        to: str,
+        subject: str,
+        body: str,
+        *,
+        from_domain: Optional[str] = None,
+        from_mailbox: Optional[str] = None,
+        from_name: Optional[str] = None,
+        **kwargs: Any,
+    ) -> Any:
         """Send an email. Blocking."""
-        payload: dict[str, Any] = {"to": to, "subject": subject, "body": body, **kwargs}
-        if from_domain:
-            payload["from_domain"] = from_domain
-        return self.call_tool("/v1/tools/email/send", payload)
+        return self.call_tool(
+            "/v1/tools/email/send",
+            _build_email_payload(to, subject, body, from_domain, from_mailbox, from_name, kwargs),
+        )
 
-    async def aemail(self, to: str, subject: str, body: str, *, from_domain: Optional[str] = None, **kwargs: Any) -> Any:
+    async def aemail(
+        self,
+        to: str,
+        subject: str,
+        body: str,
+        *,
+        from_domain: Optional[str] = None,
+        from_mailbox: Optional[str] = None,
+        from_name: Optional[str] = None,
+        **kwargs: Any,
+    ) -> Any:
         """Send an email. Async."""
-        payload: dict[str, Any] = {"to": to, "subject": subject, "body": body, **kwargs}
-        if from_domain:
-            payload["from_domain"] = from_domain
-        return await self.acall_tool("/v1/tools/email/send", payload)
+        return await self.acall_tool(
+            "/v1/tools/email/send",
+            _build_email_payload(to, subject, body, from_domain, from_mailbox, from_name, kwargs),
+        )
 
     def voice(self, objective: str, target_number: str, **kwargs: Any) -> Any:
         """Make an AI voice call. Blocking."""
@@ -645,6 +707,41 @@ class OneShotClient:
         """Get unified balance (on-chain USDC + credits). Async."""
         return await self.acall_free_get("/v1/tools/balance")
 
+    # ------------------------------------------------------------------
+    # Receipts — value tagging (RoCS)
+    # ------------------------------------------------------------------
+
+    def tag_receipt_value(
+        self,
+        receipt_id: str,
+        value_tag: dict[str, Any],
+    ) -> dict:
+        """Tag a receipt with a value for RoCS computation. Blocking.
+
+        ``value_tag`` shape: ``{"type": ..., "amount": ..., "label": ...}``.
+        ``type`` must be one of ``revenue``, ``lead``, ``conversion``,
+        ``savings``, ``engagement``. Tags are stored as ``pending`` until a
+        judge service confirms them against inbound signals.
+        """
+        return asyncio.get_event_loop().run_until_complete(
+            self.atag_receipt_value(receipt_id, value_tag)
+        )
+
+    async def atag_receipt_value(
+        self,
+        receipt_id: str,
+        value_tag: dict[str, Any],
+    ) -> dict:
+        """Tag a receipt with a value for RoCS computation. Async."""
+        if not receipt_id:
+            raise ValidationError("receipt_id is required", "receipt_id")
+        if not isinstance(value_tag, dict) or not value_tag.get("type"):
+            raise ValidationError("value_tag.type is required", "value_tag.type")
+        return await self.acall_free_patch(
+            f"/v1/analytics/receipts/{receipt_id}/value",
+            value_tag,
+        )
+
     # ------------------------------------------------------------------
     # Job polling
     # ------------------------------------------------------------------

{oneshot_python-0.10.0 → oneshot_python-0.11.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "oneshot-python"
-version = "0.10.0"
+version = "0.11.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.11.0/tests/test_email_payload.py

@@ -0,0 +1,74 @@
+"""Tests for the email payload construction in OneShotClient.
+
+Verifies that email()/aemail() send the API's field convention
+(from_address + to_address), build from_address from from_mailbox/from_domain,
+and forward the optional from_name display name.
+"""
+
+from __future__ import annotations
+
+from unittest.mock import AsyncMock, MagicMock
+
+import pytest
+
+from oneshot.client import OneShotClient, _build_email_payload
+
+TEST_PRIVATE_KEY = "0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80"
+
+
+# ── _build_email_payload (pure) ───────────────────────────────────────────
+
+def test_payload_defaults_to_agent_mailbox():
+    p = _build_email_payload("r@x.com", "S", "B", None, None, None, {})
+    assert p == {
+        "from_address": "agent@oneshotagent.com",
+        "to_address": "r@x.com",
+        "subject": "S",
+        "body": "B",
+    }
+
+
+def test_payload_uses_mailbox_domain_and_name():
+    p = _build_email_payload("r@x.com", "S", "B", "acme.com", "jane", "Jane Doe", {})
+    assert p["from_address"] == "jane@acme.com"
+    assert p["from_name"] == "Jane Doe"
+
+
+def test_payload_omits_empty_from_name():
+    p = _build_email_payload("r@x.com", "S", "B", None, None, "", {})
+    assert "from_name" not in p
+
+
+def test_payload_passes_extra_kwargs():
+    p = _build_email_payload("r@x.com", "S", "B", None, None, None, {"wait": True})
+    assert p["wait"] is True
+
+
+# ── email() delegation ────────────────────────────────────────────────────
+
+def _client() -> OneShotClient:
+    c = OneShotClient(TEST_PRIVATE_KEY)
+    c.call_tool = MagicMock(return_value={"request_id": "r1"})  # type: ignore[method-assign]
+    return c
+
+
+def test_email_sends_correct_contract():
+    c = _client()
+    c.email("r@x.com", "Hi", "Body", from_mailbox="jane", from_domain="acme.com", from_name="Jane Doe")
+    endpoint, payload = c.call_tool.call_args[0]
+    assert endpoint == "/v1/tools/email/send"
+    assert payload["from_address"] == "jane@acme.com"
+    assert payload["to_address"] == "r@x.com"
+    assert payload["from_name"] == "Jane Doe"
+
+
+@pytest.mark.asyncio
+async def test_aemail_sends_correct_contract():
+    c = OneShotClient(TEST_PRIVATE_KEY)
+    c.acall_tool = AsyncMock(return_value={"request_id": "r2"})  # type: ignore[method-assign]
+    await c.aemail("r@x.com", "Hi", "Body")
+    endpoint, payload = c.acall_tool.call_args[0]
+    assert endpoint == "/v1/tools/email/send"
+    assert payload["from_address"] == "agent@oneshotagent.com"
+    assert payload["to_address"] == "r@x.com"
+    assert "from_name" not in payload

oneshot_python-0.11.0/tests/test_emergency_error.py

@@ -0,0 +1,78 @@
+"""Tests for EmergencyNumberError — voice-call refusal on emergency lines.
+
+Mirrors the TS SDK's EmergencyNumberError (libs/agent-sdk/src/errors.ts:64).
+Both error classes get raised on HTTP 400 ``emergency_number_blocked`` from
+apps/api-service/src/routes/tools/voice.ts (line ~349). The Python client
+maps that error code in ``acall_tool``'s 400-branch.
+"""
+
+from __future__ import annotations
+
+from unittest.mock import AsyncMock, MagicMock
+
+import httpx
+import pytest
+
+from oneshot import EmergencyNumberError, OneShotError
+from oneshot._errors import OneShotError as InternalOneShotError
+from oneshot.client import OneShotClient
+
+TEST_PRIVATE_KEY = "0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80"
+
+
+# ── Class shape ──────────────────────────────────────────────────────────
+
+def test_emergency_error_is_oneshot_error_subclass():
+    assert issubclass(EmergencyNumberError, OneShotError)
+    # Identity check — the public re-export and internal class are the same.
+    assert OneShotError is InternalOneShotError
+
+
+def test_emergency_error_carries_blocked_number():
+    err = EmergencyNumberError("Cannot call 911", "+1911")
+    assert str(err) == "Cannot call 911"
+    assert err.blocked_number == "+1911"
+
+
+def test_emergency_error_exported_from_package_barrel():
+    # Re-export check — ``from oneshot import EmergencyNumberError`` must work.
+    import oneshot
+    assert "EmergencyNumberError" in oneshot.__all__
+    assert oneshot.EmergencyNumberError is EmergencyNumberError
+
+
+# ── acall_tool raises EmergencyNumberError on 400 emergency_number_blocked ─
+
+def _fake_400_response(payload: dict) -> MagicMock:
+    resp = MagicMock(spec=httpx.Response)
+    resp.status_code = 400
+    resp.json = MagicMock(return_value=payload)
+    return resp
+
+
+@pytest.mark.asyncio
+async def test_acall_tool_raises_emergency_error_on_blocked_number(monkeypatch):
+    """A 400 with error=emergency_number_blocked must surface as
+    EmergencyNumberError (not the generic ValidationError fallback)."""
+    c = OneShotClient(TEST_PRIVATE_KEY)
+
+    fake_post = AsyncMock(
+        return_value=_fake_400_response({
+            "error": "emergency_number_blocked",
+            "message": "Calls to emergency services are not permitted",
+            "blocked_number": "+1911",
+        })
+    )
+
+    class _FakeClient:
+        def __init__(self, *_a, **_kw): pass
+        async def __aenter__(self): return self
+        async def __aexit__(self, *_): return False
+        post = fake_post
+
+    monkeypatch.setattr(httpx, "AsyncClient", _FakeClient)
+
+    with pytest.raises(EmergencyNumberError) as excinfo:
+        await c.acall_tool("/v1/tools/voice/call", {"target_number": "+1911"})
+    assert excinfo.value.blocked_number == "+1911"
+    assert "emergency" in str(excinfo.value).lower()

oneshot_python-0.11.0/tests/test_max_cost_header.py

@@ -0,0 +1,49 @@
+"""Tests for the X-Max-Cost-USDC server-side budget cap header.
+
+Mirrors tests/unit/max-cost-guard.test.ts on the TS side. The server-side
+parsing is the canonical authority (apps/api-service/src/services/max-cost.ts)
+— these tests just lock in the SDK's emit contract.
+"""
+
+from __future__ import annotations
+
+from oneshot.client import OneShotClient
+
+TEST_PRIVATE_KEY = "0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80"
+HEADER = "X-Max-Cost-USDC"
+
+
+def _client() -> OneShotClient:
+    return OneShotClient(TEST_PRIVATE_KEY)
+
+
+def test_header_absent_when_max_cost_is_none():
+    h = _client()._headers()
+    assert HEADER not in h
+
+
+def test_header_absent_when_max_cost_is_zero():
+    h = _client()._headers(max_cost=0)
+    assert HEADER not in h
+
+
+def test_header_absent_when_max_cost_is_negative():
+    h = _client()._headers(max_cost=-1.5)
+    assert HEADER not in h
+
+
+def test_header_emitted_when_max_cost_positive():
+    h = _client()._headers(max_cost=2.0)
+    assert h[HEADER] == "2.0"
+
+
+def test_header_emitted_for_small_positive_value():
+    h = _client()._headers(max_cost=0.01)
+    assert h[HEADER] == "0.01"
+
+
+def test_headers_still_contain_standard_fields():
+    h = _client()._headers(max_cost=1.0)
+    assert h["Content-Type"] == "application/json"
+    assert "X-Agent-ID" in h
+    assert "X-OneShot-SDK-Version" in h

oneshot_python-0.11.0/tests/test_tag_receipt_value.py

@@ -0,0 +1,87 @@
+"""Tests for OneShotClient.tag_receipt_value / atag_receipt_value.
+
+Mirrors the TS SDK's ``OneShot.tagReceiptValue`` (libs/agent-sdk/src/index.ts).
+The endpoint is PATCH /v1/analytics/receipts/:receipt_id/value — the API
+records the tag as ``pending`` until a judge service confirms it against
+inbound signals.
+"""
+
+from __future__ import annotations
+
+from unittest.mock import AsyncMock
+
+import pytest
+
+from oneshot import ValidationError
+from oneshot.client import OneShotClient
+
+TEST_PRIVATE_KEY = "0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80"
+
+
+def _client_with_mocked_patch() -> tuple[OneShotClient, AsyncMock]:
+    c = OneShotClient(TEST_PRIVATE_KEY)
+    mock = AsyncMock(return_value={"success": True})
+    c.acall_free_patch = mock  # type: ignore[method-assign]
+    return c, mock
+
+
+# ── Validation ───────────────────────────────────────────────────────────
+
+@pytest.mark.asyncio
+async def test_raises_when_receipt_id_empty():
+    c, _ = _client_with_mocked_patch()
+    with pytest.raises(ValidationError) as excinfo:
+        await c.atag_receipt_value("", {"type": "revenue", "amount": 1})
+    assert excinfo.value.field == "receipt_id"
+
+
+@pytest.mark.asyncio
+async def test_raises_when_value_tag_missing_type():
+    c, _ = _client_with_mocked_patch()
+    with pytest.raises(ValidationError) as excinfo:
+        await c.atag_receipt_value("rcpt_01HX", {"amount": 1})
+    assert excinfo.value.field == "value_tag.type"
+
+
+@pytest.mark.asyncio
+async def test_raises_when_value_tag_not_a_dict():
+    c, _ = _client_with_mocked_patch()
+    with pytest.raises(ValidationError):
+        await c.atag_receipt_value("rcpt_01HX", "revenue")  # type: ignore[arg-type]
+
+
+# ── Happy path — forwards to PATCH /v1/analytics/receipts/:id/value ──────
+
+@pytest.mark.asyncio
+async def test_forwards_to_correct_endpoint_and_body():
+    c, mock = _client_with_mocked_patch()
+    tag = {"type": "revenue", "amount": 5.0, "label": "Lead converted"}
+    result = await c.atag_receipt_value("rcpt_01HX", tag)
+    assert result == {"success": True}
+    mock.assert_awaited_once_with("/v1/analytics/receipts/rcpt_01HX/value", tag)
+
+
+@pytest.mark.asyncio
+async def test_accepts_minimal_valid_tag_with_just_type():
+    # The API also rejects tags without amount, but that's a server-side
+    # check. The SDK's local guard only enforces .type — same as TS.
+    c, mock = _client_with_mocked_patch()
+    await c.atag_receipt_value("rcpt_01HX", {"type": "lead"})
+    mock.assert_awaited_once()
+
+
+def test_sync_wrapper_delegates_to_async(monkeypatch):
+    # The blocking ``tag_receipt_value`` should call through to the async
+    # version via the event loop, matching every other tool method.
+    c = OneShotClient(TEST_PRIVATE_KEY)
+    called: dict = {}
+
+    async def fake_async(receipt_id, value_tag):
+        called["receipt_id"] = receipt_id
+        called["value_tag"] = value_tag
+        return {"ok": True}
+
+    c.atag_receipt_value = fake_async  # type: ignore[method-assign]
+    result = c.tag_receipt_value("rcpt_01HX", {"type": "savings", "amount": 12})
+    assert result == {"ok": True}
+    assert called == {"receipt_id": "rcpt_01HX", "value_tag": {"type": "savings", "amount": 12}}