oneshot-python 0.1.0__py3-none-any.whl

oneshot/__init__.py

@@ -0,0 +1,23 @@
+"""oneshot-python — Core Python SDK for the OneShot API."""
+
+from oneshot._errors import (
+    ContentBlockedError,
+    JobError,
+    JobTimeoutError,
+    OneShotError,
+    ToolError,
+    ValidationError,
+)
+from oneshot.client import OneShotClient
+from oneshot.x402 import sign_payment_authorization
+
+__all__ = [
+    "OneShotClient",
+    "OneShotError",
+    "ToolError",
+    "JobError",
+    "JobTimeoutError",
+    "ValidationError",
+    "ContentBlockedError",
+    "sign_payment_authorization",
+]

oneshot/_errors.py

@@ -0,0 +1,48 @@
+"""Error classes mirroring the TypeScript OneShot SDK error hierarchy."""
+
+
+class OneShotError(Exception):
+    """Base error for all OneShot operations."""
+
+
+class ToolError(OneShotError):
+    """HTTP-level error from the OneShot API."""
+
+    def __init__(self, message: str, status_code: int, response_body: str) -> None:
+        super().__init__(message)
+        self.status_code = status_code
+        self.response_body = response_body
+
+
+class JobError(OneShotError):
+    """Async job completed with an error."""
+
+    def __init__(self, message: str, job_id: str, job_error: str) -> None:
+        super().__init__(message)
+        self.job_id = job_id
+        self.job_error = job_error
+
+
+class JobTimeoutError(OneShotError):
+    """Async job exceeded the polling timeout."""
+
+    def __init__(self, job_id: str, elapsed_ms: int) -> None:
+        super().__init__(f"Job {job_id} timed out after {elapsed_ms / 1000}s")
+        self.job_id = job_id
+        self.elapsed_ms = elapsed_ms
+
+
+class ValidationError(OneShotError):
+    """Client-side input validation failure."""
+
+    def __init__(self, message: str, field: str) -> None:
+        super().__init__(message)
+        self.field = field
+
+
+class ContentBlockedError(OneShotError):
+    """Content safety filter rejected the request."""
+
+    def __init__(self, message: str, categories: list[str]) -> None:
+        super().__init__(message)
+        self.categories = categories

oneshot/client.py

@@ -0,0 +1,334 @@
+"""OneShotClient — HTTP client with x402 payment flow.
+
+Ports the ``OneShot`` class from ``libs/agent-sdk/src/index.ts``.
+Handles: quote -> pay -> poll lifecycle for paid tools, and simple
+GET/POST for free endpoints.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import time
+from typing import Any, Optional
+
+import httpx
+from eth_account import Account
+
+from oneshot._errors import (
+    ContentBlockedError,
+    JobError,
+    JobTimeoutError,
+    OneShotError,
+    ToolError,
+    ValidationError,
+)
+from oneshot.x402 import sign_payment_authorization
+
+SDK_VERSION = "0.1.0"
+
+# ---------------------------------------------------------------------------
+# Environment configuration (mirrors TS SDK)
+# ---------------------------------------------------------------------------
+
+TEST_ENV = {
+    "base_url": "https://api-stg.oneshotagent.com",
+    "rpc_url": "https://sepolia.base.org",
+    "chain_id": 84532,
+    "usdc_address": "0x036CbD53842c5426634e7929541eC2318f3dCF7e",
+}
+
+PROD_ENV = {
+    "base_url": "https://win.oneshotagent.com",
+    "rpc_url": "https://mainnet.base.org",
+    "chain_id": 8453,
+    "usdc_address": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
+}
+
+_POLL_INTERVAL = 2.0  # seconds
+_MAX_POLL_RETRIES = 3
+
+
+class OneShotClient:
+    """Synchronous + async HTTP client for the OneShot API.
+
+    Supports the full x402 quote-then-pay lifecycle for paid tools and
+    simple requests for free endpoints.
+    """
+
+    def __init__(
+        self,
+        private_key: str,
+        *,
+        test_mode: bool = True,
+        base_url: Optional[str] = None,
+        debug: bool = False,
+    ) -> None:
+        env = TEST_ENV if test_mode else PROD_ENV
+        self.base_url = base_url or env["base_url"]
+        self.chain_id: int = env["chain_id"]
+        self.usdc_address: str = env["usdc_address"]
+        self.test_mode = test_mode
+        self.debug = debug
+
+        # Derive wallet address from private key
+        self._private_key = private_key
+        acct = Account.from_key(private_key)
+        self.address: str = acct.address
+
+    # ------------------------------------------------------------------
+    # Headers
+    # ------------------------------------------------------------------
+
+    def _headers(self) -> dict[str, str]:
+        return {
+            "Content-Type": "application/json",
+            "X-Agent-ID": self.address,
+            "X-OneShot-SDK-Version": SDK_VERSION,
+        }
+
+    def _log(self, msg: str) -> None:
+        if self.debug:
+            print(f"[OneShot] {msg}")
+
+    # ------------------------------------------------------------------
+    # Paid tool flow  (POST -> 402 -> sign -> POST w/ payment -> poll)
+    # ------------------------------------------------------------------
+
+    def call_tool(
+        self,
+        endpoint: str,
+        payload: dict[str, Any],
+        *,
+        max_cost: Optional[float] = None,
+        timeout_sec: int = 120,
+    ) -> Any:
+        """Execute a paid tool call (blocking). Handles the full x402 flow."""
+        return asyncio.get_event_loop().run_until_complete(
+            self.acall_tool(endpoint, payload, max_cost=max_cost, timeout_sec=timeout_sec)
+        )
+
+    async def acall_tool(
+        self,
+        endpoint: str,
+        payload: dict[str, Any],
+        *,
+        max_cost: Optional[float] = None,
+        timeout_sec: int = 120,
+    ) -> Any:
+        """Execute a paid tool call (async). Handles the full x402 flow."""
+        url = f"{self.base_url}{endpoint}"
+
+        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)
+
+            # Handle validation / content-blocked errors
+            if resp.status_code == 400:
+                data = resp.json()
+                err_type = data.get("error", "")
+                if err_type == "content_blocked":
+                    raise ContentBlockedError(
+                        data.get("message", "Content blocked"),
+                        data.get("categories", []),
+                    )
+                raise ValidationError(
+                    data.get("message", "Invalid request"), "request"
+                )
+
+            # If not 402, this might be a free tool that returned directly
+            if resp.status_code != 402:
+                resp.raise_for_status()
+                result = resp.json()
+                # Handle async jobs
+                if isinstance(result, dict) and result.get("request_id") and result.get("status") in (
+                    "pending",
+                    "processing",
+                ):
+                    return await self._poll_job(client, result["request_id"], timeout_sec)
+                return result.get("data", result)
+
+            # Step 2 — Parse 402 response
+            quote_data = resp.json()
+            payment_request = quote_data["payment_request"]
+            context = quote_data.get("context", {})
+            quote_id = context.get("quote_id")
+
+            # Check max_cost
+            total = context.get("total") or context.get("pricing", {}).get("total")
+            if max_cost is not None and total is not None:
+                if float(total) > max_cost:
+                    raise OneShotError(
+                        f"Quote ${total} exceeds max_cost ${max_cost}"
+                    )
+
+            self._log(f"Payment required: {payment_request['amount']} USDC")
+
+            # Step 3 — Sign x402 payment
+            auth = sign_payment_authorization(
+                private_key=self._private_key,
+                from_address=self.address,
+                to_address=payment_request["recipient"],
+                amount=payment_request["amount"],
+                token_address=payment_request["token_address"],
+                chain_id=payment_request["chain_id"],
+                network=f"eip155:{payment_request['chain_id']}",
+            )
+
+            # Step 4 — Re-POST with payment headers
+            headers = {
+                **self._headers(),
+                "x-payment": json.dumps(auth),
+            }
+            if quote_id:
+                headers["x-quote-id"] = quote_id
+
+            resp2 = await client.post(url, headers=headers, json=payload)
+
+            if resp2.status_code not in (200, 201, 202):
+                raise ToolError(
+                    "Tool request failed after payment",
+                    resp2.status_code,
+                    resp2.text,
+                )
+
+            result = resp2.json()
+
+            # Step 5 — Poll if async job
+            if isinstance(result, dict) and result.get("request_id") and result.get("status") in (
+                "pending",
+                "processing",
+            ):
+                self._log(f"Job queued: {result['request_id']}")
+                return await self._poll_job(client, result["request_id"], timeout_sec)
+
+            return result.get("data", result)
+
+    # ------------------------------------------------------------------
+    # Free endpoint helpers
+    # ------------------------------------------------------------------
+
+    def call_free_get(
+        self,
+        endpoint: str,
+        params: Optional[dict[str, str]] = None,
+    ) -> Any:
+        """GET a free endpoint (blocking)."""
+        return asyncio.get_event_loop().run_until_complete(
+            self.acall_free_get(endpoint, params)
+        )
+
+    async def acall_free_get(
+        self,
+        endpoint: str,
+        params: Optional[dict[str, str]] = None,
+    ) -> Any:
+        """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)
+            if not resp.is_success:
+                raise ToolError(f"GET {endpoint} failed", resp.status_code, resp.text)
+            return resp.json()
+
+    def call_free_post(
+        self,
+        endpoint: str,
+        payload: Optional[dict[str, Any]] = None,
+    ) -> Any:
+        """POST to a free endpoint (blocking)."""
+        return asyncio.get_event_loop().run_until_complete(
+            self.acall_free_post(endpoint, payload)
+        )
+
+    async def acall_free_post(
+        self,
+        endpoint: str,
+        payload: Optional[dict[str, Any]] = None,
+    ) -> Any:
+        """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 {})
+            if not resp.is_success:
+                raise ToolError(f"POST {endpoint} failed", resp.status_code, resp.text)
+            return resp.json()
+
+    def call_free_patch(
+        self,
+        endpoint: str,
+        payload: Optional[dict[str, Any]] = None,
+    ) -> Any:
+        """PATCH a free endpoint (blocking)."""
+        return asyncio.get_event_loop().run_until_complete(
+            self.acall_free_patch(endpoint, payload)
+        )
+
+    async def acall_free_patch(
+        self,
+        endpoint: str,
+        payload: Optional[dict[str, Any]] = None,
+    ) -> Any:
+        """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 {})
+            if not resp.is_success:
+                raise ToolError(f"PATCH {endpoint} failed", resp.status_code, resp.text)
+            # PATCH may return empty body (204)
+            if resp.status_code == 204 or not resp.text:
+                return {"success": True}
+            return resp.json()
+
+    # ------------------------------------------------------------------
+    # Job polling
+    # ------------------------------------------------------------------
+
+    async def _poll_job(
+        self,
+        client: httpx.AsyncClient,
+        request_id: str,
+        timeout_sec: int,
+    ) -> Any:
+        start = time.monotonic()
+        retries = 0
+
+        while (time.monotonic() - start) < timeout_sec:
+            try:
+                resp = await client.get(
+                    f"{self.base_url}/v1/requests/{request_id}",
+                    headers=self._headers(),
+                )
+                if not resp.is_success:
+                    raise ToolError(
+                        "Failed to check job status",
+                        resp.status_code,
+                        resp.text,
+                    )
+
+                job = resp.json()
+
+                if job.get("status") == "completed":
+                    self._log("Job completed")
+                    return job.get("result", job)
+
+                if job.get("status") == "failed":
+                    raise JobError(
+                        f"Job failed: {job.get('error', 'Unknown')}",
+                        request_id,
+                        str(job.get("error", "Unknown")),
+                    )
+
+                retries = 0
+                await asyncio.sleep(_POLL_INTERVAL)
+
+            except (OneShotError, JobError):
+                raise
+            except Exception:
+                retries += 1
+                if retries > _MAX_POLL_RETRIES:
+                    raise
+                await asyncio.sleep(_POLL_INTERVAL * (2 ** (retries - 1)))
+
+        elapsed_ms = int((time.monotonic() - start) * 1000)
+        raise JobTimeoutError(request_id, elapsed_ms)

oneshot/x402.py

@@ -0,0 +1,142 @@
+"""EIP-712 payment signing for x402 protocol (USDC TransferWithAuthorization).
+
+Ports the signing logic from:
+- libs/agent-sdk/src/index.ts (L1511-1568)
+- apps/api-service/src/services/x402-facilitator.ts (L28-29) for domain names
+"""
+
+from __future__ import annotations
+
+import os
+import time
+from typing import Any, TypedDict
+
+from eth_account import Account
+from eth_account.messages import encode_typed_data
+
+
+class PaymentSignature(TypedDict):
+    v: int
+    r: str
+    s: str
+
+
+class PaymentAuthorization(TypedDict):
+    """Mirrors the TS SDK PaymentAuthorization interface."""
+
+    from_address: str  # 'from' is reserved in Python
+    to: str
+    value: str
+    validAfter: int
+    validBefore: int
+    nonce: str
+    signature: PaymentSignature
+    network: str
+    token: str
+
+
+def _get_usdc_domain_name(chain_id: int) -> str:
+    """Return the EIP-712 domain name for USDC on the given chain.
+
+    Base Sepolia (84532) uses "USDC", Base Mainnet (8453) uses "USD Coin".
+    Source: apps/api-service/src/services/x402-facilitator.ts:28-29
+    """
+    return "USDC" if chain_id == 84532 else "USD Coin"
+
+
+def sign_payment_authorization(
+    *,
+    private_key: str,
+    from_address: str,
+    to_address: str,
+    amount: str,
+    token_address: str,
+    chain_id: int,
+    network: str,
+) -> dict[str, Any]:
+    """Create an EIP-712 TransferWithAuthorization signature for USDC.
+
+    Args:
+        private_key: Hex-encoded private key (with or without 0x prefix).
+        from_address: Sender wallet address.
+        to_address: Recipient (merchant) address.
+        amount: Amount in USDC human-readable units (e.g. "1.50").
+        token_address: USDC contract address.
+        chain_id: EVM chain ID (84532 for Base Sepolia, 8453 for Base Mainnet).
+        network: CAIP-2 network string (e.g. "eip155:84532").
+
+    Returns:
+        Payment authorization dict ready to be JSON-serialized as x-payment header.
+    """
+    # Convert human-readable amount to USDC base units (6 decimals)
+    value = _parse_usdc_amount(amount)
+    now = int(time.time())
+    nonce = "0x" + os.urandom(32).hex()
+
+    domain_data = {
+        "name": _get_usdc_domain_name(chain_id),
+        "version": "2",
+        "chainId": chain_id,
+        "verifyingContract": token_address,
+    }
+
+    message_types = {
+        "TransferWithAuthorization": [
+            {"name": "from", "type": "address"},
+            {"name": "to", "type": "address"},
+            {"name": "value", "type": "uint256"},
+            {"name": "validAfter", "type": "uint256"},
+            {"name": "validBefore", "type": "uint256"},
+            {"name": "nonce", "type": "bytes32"},
+        ],
+    }
+
+    message_data = {
+        "from": from_address,
+        "to": to_address,
+        "value": value,
+        "validAfter": now - 300,
+        "validBefore": now + 3600,
+        "nonce": bytes.fromhex(nonce[2:]),
+    }
+
+    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)
+
+    return {
+        "from": from_address,
+        "to": to_address,
+        "value": str(value),
+        "validAfter": now - 300,
+        "validBefore": now + 3600,
+        "nonce": nonce,
+        "signature": {
+            "v": signed.v,
+            "r": hex(signed.r),
+            "s": hex(signed.s),
+        },
+        "network": network,
+        "token": token_address,
+    }
+
+
+def _parse_usdc_amount(amount: str) -> int:
+    """Convert a human-readable USDC amount to base units (6 decimals).
+
+    Examples:
+        "1.50" -> 1500000
+        "10"   -> 10000000
+        "0.01" -> 10000
+    """
+    parts = amount.split(".")
+    whole = int(parts[0])
+    if len(parts) == 1:
+        return whole * 1_000_000
+
+    # Pad or truncate fractional part to 6 digits
+    frac_str = parts[1][:6].ljust(6, "0")
+    return whole * 1_000_000 + int(frac_str)

oneshot_python-0.1.0.dist-info/METADATA

@@ -0,0 +1,14 @@
+Metadata-Version: 2.4
+Name: oneshot-python
+Version: 0.1.0
+Summary: Core Python SDK for the OneShot API — HTTP client with x402 payment handling
+License-Expression: MIT
+Requires-Python: >=3.10
+Requires-Dist: eth-account>=0.13.0
+Requires-Dist: httpx>=0.27.0
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Description-Content-Type: text/plain
+
+Core Python SDK for the OneShot API

oneshot_python-0.1.0.dist-info/RECORD

@@ -0,0 +1,7 @@
+oneshot/__init__.py,sha256=yDrp5FGVWFLuMZUBzS2exrdizzBAWXZXS1VVoesmUuM,498
+oneshot/_errors.py,sha256=hbDMBck3JU3pFlNvSKMWZ4j1uFsyTQNciFVjAatE5rc,1432
+oneshot/client.py,sha256=6qlXeGbfWEBOrmsftilm3q23mn3fAqXWg0M05fb2zs0,11585
+oneshot/x402.py,sha256=mSrCy_uRJqm5QUbi1YwOSDtg5wfZQPEyhsJsYItpjIk,3947
+oneshot_python-0.1.0.dist-info/METADATA,sha256=JMapJpeQNn3KqsM0qrKh3wR_8xRh6hxYSLKxGrXFnuY,446
+oneshot_python-0.1.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+oneshot_python-0.1.0.dist-info/RECORD,,

oneshot_python-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.28.0
+Root-Is-Purelib: true
+Tag: py3-none-any