oneshot-python 0.20.2__tar.gz → 0.23.1__tar.gz

{oneshot_python-0.20.2 → oneshot_python-0.23.1}/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.5
 Name: oneshot-python
-Version: 0.20.2
-Summary: Core Python SDK for the OneShot API — HTTP client with x402 payment handling
+Version: 0.23.1
+Summary: Core Python SDK for the OneShot API — HTTP client with x402 payment handling — 35 tools
 License-Expression: MIT
 Requires-Python: >=3.10
 Requires-Dist: eth-account>=0.13.0

{oneshot_python-0.20.2 → oneshot_python-0.23.1}/README.md

@@ -201,3 +201,7 @@ Every method has an `a*` async mirror (`acompute`, `aget_compute_goal`, …).
 ## License
 
 MIT
+
+### Physical mail
+
+`client.physical_mail` supports U.S. letters and 4×6 postcards through `upload_artwork`, `validate_address`, `preview`, `get_quote`, `approve`, `send`, `get_order`, `recover`, and `cancel`. Async variants prefix the method with `a`. Review each proof and price, then call `approve(..., approved=True)` explicitly. Persist `idempotency_key` before sending. `recover(key)` retrieves the original order without creating another charge. Postal delivery does not prove readership; paid receipts and fulfillment events remain separate. Lob credentials stay on OneShot's server.

{oneshot_python-0.20.2 → oneshot_python-0.23.1}/oneshot/__init__.py

@@ -1,5 +1,7 @@
 """oneshot-python — Core Python SDK for the OneShot API."""
 
+from oneshot.physical_mail import PhysicalMail, PostalAddress, MailQuote, MailOrder
+
 from oneshot._errors import (
     BudgetExceededError,
     BudgetSyncError,
@@ -34,6 +36,7 @@ from oneshot.client import OneShotClient
 from oneshot.x402 import sign_payment_authorization
 
 __all__ = [
+    "PhysicalMail", "PostalAddress", "MailQuote", "MailOrder",
     "OneShotClient",
     "OneShotError",
     "ToolError",

{oneshot_python-0.20.2 → oneshot_python-0.23.1}/oneshot/client.py

@@ -51,7 +51,7 @@ try:
 
     SDK_VERSION = _pkg_version("oneshot-python")
 except Exception:  # pragma: no cover - editable/source runs without dist metadata
-    SDK_VERSION = "0.20.2"
+    SDK_VERSION = "0.23.1"
 
 # ---------------------------------------------------------------------------
 # Environment configuration
@@ -313,6 +313,11 @@ class OneShotClient:
             headers["X-Max-Cost-USDC"] = str(max_cost)
         return headers
 
+    @property
+    def physical_mail(self):
+        from oneshot.physical_mail import PhysicalMail
+        return PhysicalMail(self)
+
     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
@@ -1235,6 +1240,30 @@ class OneShotClient:
         """Enrich a company from domain, name, LinkedIn URL, or ticker. Async."""
         return await self.acall_tool("/v1/tools/enrich/company", kwargs)
 
+    def local_search(self, **kwargs: Any) -> Any:
+        """Discover local businesses (restaurants, contractors, practices) by category/keywords x location. Blocking."""
+        return self.call_tool("/v1/tools/local/search", kwargs)
+
+    async def alocal_search(self, **kwargs: Any) -> Any:
+        """Discover local businesses (restaurants, contractors, practices) by category/keywords x location. Async."""
+        return await self.acall_tool("/v1/tools/local/search", kwargs)
+
+    def local_resolve(self, name: str, **kwargs: Any) -> Any:
+        """Resolve a business name + one locating field (address/city/postal_code/phone) to its domain, phone, status. Blocking."""
+        return self.call_tool("/v1/tools/local/resolve", {"name": name, **kwargs})
+
+    async def alocal_resolve(self, name: str, **kwargs: Any) -> Any:
+        """Resolve a business name + one locating field (address/city/postal_code/phone) to its domain, phone, status. Async."""
+        return await self.acall_tool("/v1/tools/local/resolve", {"name": name, **kwargs})
+
+    def gov_solicitations(self, naics: list[str], **kwargs: Any) -> Any:
+        """Federal Sources Sought / Presolicitation notices (SAM.gov) by NAICS code with the contracting officer's contact. Result carries `data_as_of` (snapshot behind the rows). Blocking."""
+        return self.call_tool("/v1/tools/gov/solicitations", {"naics": naics, **kwargs})
+
+    async def agov_solicitations(self, naics: list[str], **kwargs: Any) -> Any:
+        """Federal Sources Sought / Presolicitation notices (SAM.gov) by NAICS code with the contracting officer's contact. Result carries `data_as_of` (snapshot behind the rows). Async."""
+        return await self.acall_tool("/v1/tools/gov/solicitations", {"naics": naics, **kwargs})
+
     def find_email(self, company_domain: str, *, full_name: Optional[str] = None, first_name: Optional[str] = None, last_name: Optional[str] = None, **kwargs: Any) -> Any:
         """Find a person's email address. Blocking."""
         payload: dict[str, Any] = {"company_domain": company_domain, **kwargs}

oneshot_python-0.23.1/oneshot/physical_mail.py

@@ -0,0 +1,168 @@
+"""Physical mail: explicit approval, durable recovery, independent fulfillment."""
+from __future__ import annotations
+from typing import Any, Literal, TypedDict
+import math
+import httpx
+from oneshot.x402 import sign_read_proof, parse_payment_required, sign_payment_authorization, encode_payment_header
+from oneshot._errors import OneShotError
+
+class _PostalAddressRequired(TypedDict):
+    name: str
+    address_line1: str
+    address_city: str
+    address_state: str
+    address_zip: str
+
+class PostalAddress(_PostalAddressRequired, total=False):
+    address_line2: str
+    address_country: Literal['US']
+
+class MailQuote(TypedDict):
+    quote_id: str
+    input_hash: str
+    status: Literal['rendering', 'ready']
+    total_usdc: str | None
+    expires_at: str
+    preview: dict[str, Any]
+    input: dict[str, Any]
+    service_fee_usdc: str | None
+    approval_id: str | None
+    delivery_proves_readership: Literal[False]
+
+class MailOrder(TypedDict):
+    order_id: str
+    quote_id: str
+    receipt_id: str
+    order_status: str
+    payment_status: str
+    fulfillment_status: str
+    total_usdc: str
+    cancellation_requested: bool
+    cancellation_error: str | None
+    cancel_before: str | None
+    refunded_at: str | None
+    signed_receipt: Any
+    events: list[dict[str, Any]]
+    idempotency_key: str
+    delivery_proves_readership: Literal[False]
+
+class PhysicalMail:
+    def __init__(self, client: Any):
+        self.client = client
+
+    async def _request(self, path: str, method: str = 'POST', body: Any = None, *, mime: str | None = None, key: str | None = None, max_cost: float | None = None) -> Any:
+        c = self.client
+        scope = 'read' if method == 'GET' else 'submit' if path == '/send' else 'write'
+        def headers() -> dict[str, str]:
+            h = c._headers(max_cost=max_cost)
+            h['x-agent-proof'] = sign_read_proof(c._private_key, c.address, scope=scope)
+            if key:
+                h['Idempotency-Key'] = key
+            if mime:
+                h['Content-Type'] = mime
+            return h
+        if path == '/send':
+            await c.aensure_budgets_synced()
+        async with httpx.AsyncClient(timeout=60.0) as transport:
+            kwargs = {'content': body} if mime else {'json': body}
+            url = f'{c.base_url}/v1/tools/physical-mail{path}'
+            response = await transport.request(method, url, headers=headers(), **kwargs)
+            if response.status_code == 402 and path == '/send':
+                parsed = parse_payment_required(response.headers.get('payment-required'))
+                accepted = parsed['accepted']
+                payment = response.json()['payment_request']
+                charge = str(int(accepted['amount']) / 1_000_000)
+                c._assert_within_budget(charge)
+                if max_cost is not None and float(charge) > max_cost:
+                    raise OneShotError('Physical mail quote exceeds max_cost')
+                auth = sign_payment_authorization(private_key=c._private_key, from_address=c.address,
+                    to_address=payment['recipient'], amount=charge, token_address=payment['token_address'],
+                    chain_id=payment['chain_id'], network=accepted['network'], accepted=accepted,
+                    resource=parsed.get('resource'), extensions=parsed.get('extensions'))
+                h = headers()  # Proof nonces are single use, including the unpaid leg.
+                h['payment-signature'] = encode_payment_header(auth)
+                response = await transport.post(url, headers=h, json=body)
+            response.raise_for_status()
+            return response.json()
+
+    async def aupload_artwork(self, data: bytes, mime: str) -> dict[str, str]:
+        return await self._request('/assets', body=data, mime=mime)
+
+    async def avalidate_address(self, address: PostalAddress) -> dict[str, Any]:
+        return await self._request('/validate-address', body=address)
+
+    async def apreview(self, mail_input: dict[str, Any]) -> MailQuote:
+        return await self._request('/preview', body=mail_input)
+
+    async def aget_quote(self, quote_id: str) -> MailQuote:
+        from urllib.parse import quote
+        return await self._request(f'/quotes/{quote(quote_id, safe="")}', 'GET')
+
+    async def aapprove(self, *, quote_id: str, input_hash: str, total_usdc: str, approved: Literal[True]) -> dict[str, str]:
+        if approved is not True:
+            raise ValueError('Explicit mailpiece approval required')
+        return await self._request('/approve', body=dict(quote_id=quote_id, input_hash=input_hash, total_usdc=total_usdc, approved=True))
+
+    async def asend(self, *, quote_id: str, approval_id: str, idempotency_key: str, max_cost: float | None = None, memo: str | None = None, decision_context: dict[str, Any] | None = None) -> MailOrder:
+        if max_cost is not None and (not math.isfinite(max_cost) or max_cost <= 0):
+            raise ValueError('Physical mail max_cost must be finite and positive')
+        if not idempotency_key or not approval_id:
+            raise ValueError('Persist an idempotency key and explicitly approve the quote before sending')
+        body: dict[str, Any] = dict(quote_id=quote_id, approval_id=approval_id)
+        if memo is not None:
+            body['memo'] = memo
+        if decision_context is not None:
+            body['decisionContext'] = decision_context
+        try:
+            return await self._request('/send', body=body, key=idempotency_key, max_cost=max_cost)
+        except Exception as error:
+            error.idempotency_key = idempotency_key  # type: ignore[attr-defined]
+            raise
+
+    async def aget_order(self, order_id: str) -> MailOrder:
+        from urllib.parse import quote
+        return await self._request(f'/orders/{quote(order_id, safe="")}', 'GET')
+
+    async def arecover(self, key: str) -> MailOrder:
+        from urllib.parse import quote
+        return await self._request(f'/orders/recover?key={quote(key, safe="")}', 'GET')
+
+    async def acancel(self, order_id: str) -> MailOrder:
+        from urllib.parse import quote
+        return await self._request(f'/orders/{quote(order_id, safe="")}/cancel', body={})
+
+    def upload_artwork(self, *args: Any, **kwargs: Any) -> Any:
+        import asyncio
+        return asyncio.get_event_loop().run_until_complete(self.aupload_artwork(*args, **kwargs))
+
+    def validate_address(self, *args: Any, **kwargs: Any) -> Any:
+        import asyncio
+        return asyncio.get_event_loop().run_until_complete(self.avalidate_address(*args, **kwargs))
+
+    def preview(self, *args: Any, **kwargs: Any) -> Any:
+        import asyncio
+        return asyncio.get_event_loop().run_until_complete(self.apreview(*args, **kwargs))
+
+    def get_quote(self, *args: Any, **kwargs: Any) -> Any:
+        import asyncio
+        return asyncio.get_event_loop().run_until_complete(self.aget_quote(*args, **kwargs))
+
+    def approve(self, *args: Any, **kwargs: Any) -> Any:
+        import asyncio
+        return asyncio.get_event_loop().run_until_complete(self.aapprove(*args, **kwargs))
+
+    def send(self, *args: Any, **kwargs: Any) -> Any:
+        import asyncio
+        return asyncio.get_event_loop().run_until_complete(self.asend(*args, **kwargs))
+
+    def get_order(self, *args: Any, **kwargs: Any) -> Any:
+        import asyncio
+        return asyncio.get_event_loop().run_until_complete(self.aget_order(*args, **kwargs))
+
+    def recover(self, *args: Any, **kwargs: Any) -> Any:
+        import asyncio
+        return asyncio.get_event_loop().run_until_complete(self.arecover(*args, **kwargs))
+
+    def cancel(self, *args: Any, **kwargs: Any) -> Any:
+        import asyncio
+        return asyncio.get_event_loop().run_until_complete(self.acancel(*args, **kwargs))

{oneshot_python-0.20.2 → oneshot_python-0.23.1}/pyproject.toml

@@ -1,7 +1,7 @@
 [project]
 name = "oneshot-python"
-version = "0.20.2"
-description = "Core Python SDK for the OneShot API — HTTP client with x402 payment handling"
+version = "0.23.1"
+description = "Core Python SDK for the OneShot API — HTTP client with x402 payment handling — 35 tools"
 readme = {text = "Core Python SDK for the OneShot API", content-type = "text/plain"}
 license = "MIT"
 requires-python = ">=3.10"

oneshot_python-0.23.1/tests/test_physical_mail.py

@@ -0,0 +1,43 @@
+import pytest
+from unittest.mock import AsyncMock, MagicMock
+from oneshot.physical_mail import PhysicalMail
+
+@pytest.mark.asyncio
+async def test_preview_and_approval_do_not_send():
+    mail = PhysicalMail(MagicMock())
+    mail._request = AsyncMock(return_value={})
+    await mail.apreview({'artwork': {'kind': 'letter', 'file': 'asset'}})
+    assert mail._request.call_args.args[0] == '/preview'
+    with pytest.raises(ValueError):
+        await mail.aapprove(quote_id='q', input_hash='h', total_usdc='1.05', approved=False)
+    await mail.aapprove(quote_id='q', input_hash='h', total_usdc='1.05', approved=True)
+    assert mail._request.call_args.args[0] == '/approve'
+
+@pytest.mark.asyncio
+async def test_send_preserves_key_and_approval_and_recovery_does_not_send():
+    mail = PhysicalMail(MagicMock())
+    mail._request = AsyncMock(return_value={})
+    with pytest.raises(ValueError):
+        await mail.asend(quote_id='q', approval_id='a', idempotency_key='')
+    await mail.asend(quote_id='q', approval_id='a', idempotency_key='durable', max_cost=1.05)
+    assert mail._request.call_args.kwargs['key'] == 'durable'
+    assert mail._request.call_args.kwargs['body'] == {'quote_id': 'q', 'approval_id': 'a'}
+    await mail.arecover('a/b')
+    assert mail._request.call_args.args == ('/orders/recover?key=a%2Fb', 'GET')
+
+@pytest.mark.asyncio
+async def test_transport_error_carries_recovery_key():
+    mail = PhysicalMail(MagicMock())
+    mail._request = AsyncMock(side_effect=TimeoutError())
+    with pytest.raises(TimeoutError) as caught:
+        await mail.asend(quote_id='q', approval_id='a', idempotency_key='persisted')
+    assert caught.value.idempotency_key == 'persisted'
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize('max_cost', [0, -1, float('nan'), float('inf')])
+async def test_invalid_caps_never_submit(max_cost):
+    mail = PhysicalMail(MagicMock())
+    mail._request = AsyncMock()
+    with pytest.raises(ValueError, match='finite and positive'):
+        await mail.asend(quote_id='q', approval_id='a', idempotency_key='key', max_cost=max_cost)
+    mail._request.assert_not_called()

{oneshot_python-0.20.2 → oneshot_python-0.23.1}/uv.lock

@@ -549,7 +549,7 @@ wheels = [
 
 [[package]]
 name = "oneshot-python"
-version = "0.14.0"
+version = "0.23.0"
 source = { editable = "." }
 dependencies = [
     { name = "eth-account" },