oneshot-python 0.8.1__tar.gz → 0.8.3__tar.gz

{oneshot_python-0.8.1 → oneshot_python-0.8.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: oneshot-python
-Version: 0.8.1
+Version: 0.8.3
 Summary: Core Python SDK for the OneShot API — HTTP client with x402 payment handling
 License-Expression: MIT
 Requires-Python: >=3.10

{oneshot_python-0.8.1 → oneshot_python-0.8.3}/oneshot/client.py

@@ -23,9 +23,14 @@ from oneshot._errors import (
     ToolError,
     ValidationError,
 )
-from oneshot.x402 import sign_payment_authorization, encode_payment_header, parse_payment_required
+from oneshot.x402 import (
+    build_zero_cost_authorization,
+    encode_payment_header,
+    parse_payment_required,
+    sign_payment_authorization,
+)
 
-SDK_VERSION = "0.8.1"
+SDK_VERSION = "0.8.3"
 
 # ---------------------------------------------------------------------------
 # Environment configuration
@@ -157,11 +162,21 @@ class OneShotClient:
 
             self._log(f"Payment required: {payment_request['amount']} USDC")
 
-            # Step 3 — Sign x402 payment (skip if credits cover full cost)
+            # Step 3 — Sign x402 payment (zero-cost auth if credits cover full cost)
             amount = float(payment_request["amount"])
             if amount == 0:
-                self._log("Credits cover full cost — skipping payment signature")
-                headers = {**self._headers()}
+                self._log("Credits cover full cost — sending zero-cost authorization")
+                auth = build_zero_cost_authorization(
+                    from_address=self.address,
+                    to_address=payment_request["recipient"],
+                    accepted=accepted,
+                    resource=parsed_req.get("resource"),
+                    extensions=parsed_req.get("extensions"),
+                )
+                headers = {
+                    **self._headers(),
+                    "payment-signature": encode_payment_header(auth),
+                }
                 if quote_id:
                     headers["x-quote-id"] = quote_id
                 resp2 = await client.post(url, headers=headers, json=payload)
@@ -389,6 +404,182 @@ class OneShotClient:
         """Delete a browser profile. Async."""
         return await self.acall_free_delete(f"/v1/tools/browser/profiles/{profile_id}")
 
+    # ------------------------------------------------------------------
+    # Paid tool convenience methods
+    # ------------------------------------------------------------------
+
+    def research(self, topic: str, *, depth: str = "deep", **kwargs: Any) -> Any:
+        """Run deep web research on a topic. Blocking."""
+        return self.call_tool("/v1/tools/research", {"topic": topic, "depth": depth, **kwargs})
+
+    async def aresearch(self, topic: str, *, depth: str = "deep", **kwargs: Any) -> Any:
+        """Run deep web research on a topic. Async."""
+        return await self.acall_tool("/v1/tools/research", {"topic": topic, "depth": depth, **kwargs})
+
+    def web_search(self, query: str, *, max_results: int = 5, **kwargs: Any) -> Any:
+        """Search the web. Blocking."""
+        return self.call_tool("/v1/tools/search", {"query": query, "max_results": max_results, **kwargs})
+
+    async def aweb_search(self, query: str, *, max_results: int = 5, **kwargs: Any) -> Any:
+        """Search the web. Async."""
+        return await self.acall_tool("/v1/tools/search", {"query": query, "max_results": max_results, **kwargs})
+
+    def web_read(self, url: str, **kwargs: Any) -> Any:
+        """Read a web page and extract content as markdown. Blocking."""
+        return self.call_tool("/v1/tools/web-read", {"url": url, **kwargs})
+
+    async def aweb_read(self, url: str, **kwargs: Any) -> Any:
+        """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:
+        """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)
+
+    async def aemail(self, to: str, subject: str, body: str, *, from_domain: 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)
+
+    def voice(self, objective: str, target_number: str, **kwargs: Any) -> Any:
+        """Make an AI voice call. Blocking."""
+        return self.call_tool("/v1/tools/voice/call", {"objective": objective, "target_number": target_number, **kwargs})
+
+    async def avoice(self, objective: str, target_number: str, **kwargs: Any) -> Any:
+        """Make an AI voice call. Async."""
+        return await self.acall_tool("/v1/tools/voice/call", {"objective": objective, "target_number": target_number, **kwargs})
+
+    def sms(self, message: str, to_number: str, **kwargs: Any) -> Any:
+        """Send an SMS message. Blocking."""
+        return self.call_tool("/v1/tools/sms/send", {"message": message, "to_number": to_number, **kwargs})
+
+    async def asms(self, message: str, to_number: str, **kwargs: Any) -> Any:
+        """Send an SMS message. Async."""
+        return await self.acall_tool("/v1/tools/sms/send", {"message": message, "to_number": to_number, **kwargs})
+
+    def people_search(self, **kwargs: Any) -> Any:
+        """Search for people by job title, company, etc. Blocking."""
+        return self.call_tool("/v1/tools/research/people", kwargs)
+
+    async def apeople_search(self, **kwargs: Any) -> Any:
+        """Search for people by job title, company, etc. Async."""
+        return await self.acall_tool("/v1/tools/research/people", kwargs)
+
+    def enrich_profile(self, **kwargs: Any) -> Any:
+        """Enrich a person's profile from LinkedIn URL, email, or name. Blocking."""
+        return self.call_tool("/v1/tools/enrich/profile", kwargs)
+
+    async def aenrich_profile(self, **kwargs: Any) -> Any:
+        """Enrich a person's profile from LinkedIn URL, email, or name. Async."""
+        return await self.acall_tool("/v1/tools/enrich/profile", 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}
+        if full_name:
+            payload["full_name"] = full_name
+        if first_name:
+            payload["first_name"] = first_name
+        if last_name:
+            payload["last_name"] = last_name
+        return self.call_tool("/v1/tools/enrich/email", payload)
+
+    async def afind_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. Async."""
+        payload: dict[str, Any] = {"company_domain": company_domain, **kwargs}
+        if full_name:
+            payload["full_name"] = full_name
+        if first_name:
+            payload["first_name"] = first_name
+        if last_name:
+            payload["last_name"] = last_name
+        return await self.acall_tool("/v1/tools/enrich/email", payload)
+
+    def verify_email(self, email: str) -> Any:
+        """Verify email deliverability. Blocking."""
+        return self.call_tool("/v1/tools/verify/email", {"email": email})
+
+    async def averify_email(self, email: str) -> Any:
+        """Verify email deliverability. Async."""
+        return await self.acall_tool("/v1/tools/verify/email", {"email": email})
+
+    def deep_research_person(self, **kwargs: Any) -> Any:
+        """Deep research on a person. Blocking."""
+        return self.call_tool("/v1/tools/research/person", kwargs)
+
+    async def adeep_research_person(self, **kwargs: Any) -> Any:
+        """Deep research on a person. Async."""
+        return await self.acall_tool("/v1/tools/research/person", kwargs)
+
+    def social_profiles(self, **kwargs: Any) -> Any:
+        """Discover social media profiles. Blocking."""
+        return self.call_tool("/v1/tools/research/social", kwargs)
+
+    async def asocial_profiles(self, **kwargs: Any) -> Any:
+        """Discover social media profiles. Async."""
+        return await self.acall_tool("/v1/tools/research/social", kwargs)
+
+    def article_search(self, name: str, company: str, **kwargs: Any) -> Any:
+        """Find articles by or about a person. Blocking."""
+        return self.call_tool("/v1/tools/research/articles", {"name": name, "company": company, **kwargs})
+
+    async def aarticle_search(self, name: str, company: str, **kwargs: Any) -> Any:
+        """Find articles by or about a person. Async."""
+        return await self.acall_tool("/v1/tools/research/articles", {"name": name, "company": company, **kwargs})
+
+    def person_newsfeed(self, social_media_url: str, **kwargs: Any) -> Any:
+        """Get recent social posts from a person. Blocking."""
+        return self.call_tool("/v1/tools/research/newsfeed", {"social_media_url": social_media_url, **kwargs})
+
+    async def aperson_newsfeed(self, social_media_url: str, **kwargs: Any) -> Any:
+        """Get recent social posts from a person. Async."""
+        return await self.acall_tool("/v1/tools/research/newsfeed", {"social_media_url": social_media_url, **kwargs})
+
+    def person_interests(self, **kwargs: Any) -> Any:
+        """Analyze a person's interests from their digital footprint. Blocking."""
+        return self.call_tool("/v1/tools/research/interests", kwargs)
+
+    async def aperson_interests(self, **kwargs: Any) -> Any:
+        """Analyze a person's interests from their digital footprint. Async."""
+        return await self.acall_tool("/v1/tools/research/interests", kwargs)
+
+    def person_interactions(self, social_media_url: str, **kwargs: Any) -> Any:
+        """Get a person's social interactions. Blocking."""
+        return self.call_tool("/v1/tools/research/interactions", {"social_media_url": social_media_url, **kwargs})
+
+    async def aperson_interactions(self, social_media_url: str, **kwargs: Any) -> Any:
+        """Get a person's social interactions. Async."""
+        return await self.acall_tool("/v1/tools/research/interactions", {"social_media_url": social_media_url, **kwargs})
+
+    def commerce_search(self, query: str, *, limit: int = 10, **kwargs: Any) -> Any:
+        """Search for products. Blocking."""
+        return self.call_tool("/v1/tools/commerce/search", {"query": query, "limit": limit, **kwargs})
+
+    async def acommerce_search(self, query: str, *, limit: int = 10, **kwargs: Any) -> Any:
+        """Search for products. Async."""
+        return await self.acall_tool("/v1/tools/commerce/search", {"query": query, "limit": limit, **kwargs})
+
+    def commerce_buy(self, product_url: str, shipping_address: dict[str, Any], **kwargs: Any) -> Any:
+        """Purchase a product. Blocking."""
+        return self.call_tool("/v1/tools/commerce/buy", {"product_url": product_url, "shipping_address": shipping_address, **kwargs})
+
+    async def acommerce_buy(self, product_url: str, shipping_address: dict[str, Any], **kwargs: Any) -> Any:
+        """Purchase a product. Async."""
+        return await self.acall_tool("/v1/tools/commerce/buy", {"product_url": product_url, "shipping_address": shipping_address, **kwargs})
+
+    def build(self, product: dict[str, Any], **kwargs: Any) -> Any:
+        """Build a website. Blocking."""
+        return self.call_tool("/v1/tools/build", {"product": product, **kwargs})
+
+    async def abuild(self, product: dict[str, Any], **kwargs: Any) -> Any:
+        """Build a website. Async."""
+        return await self.acall_tool("/v1/tools/build", {"product": product, **kwargs})
+
     # ------------------------------------------------------------------
     # Balance
     # ------------------------------------------------------------------

{oneshot_python-0.8.1 → oneshot_python-0.8.3}/oneshot/x402.py

@@ -192,6 +192,42 @@ def sign_payment_authorization(
     return result
 
 
+def build_zero_cost_authorization(
+    *,
+    from_address: str,
+    to_address: str,
+    accepted: PaymentRequirements | dict[str, Any] | None = None,
+    resource: dict[str, Any] | None = None,
+    extensions: dict[str, Any] | None = None,
+) -> dict[str, Any]:
+    """Build a zero-cost x402 PaymentPayload for credit-covered requests.
+
+    Instead of skipping the payment header entirely (which causes the server's
+    x402 SDK to return a 402 error), we send a stub authorization with value=0
+    and signature=0x so the server can recognise the zero-cost intent.
+    """
+    result: dict[str, Any] = {
+        "x402Version": 2,
+        "accepted": dict(accepted) if accepted else {},
+        "payload": {
+            "signature": "0x",
+            "authorization": {
+                "from": from_address,
+                "to": to_address,
+                "value": "0",
+                "validAfter": "0",
+                "validBefore": "0",
+                "nonce": "0x" + "00" * 32,
+            },
+        },
+    }
+    if resource:
+        result["resource"] = resource
+    if extensions:
+        result["extensions"] = extensions
+    return result
+
+
 def encode_payment_header(auth: dict[str, Any]) -> str:
     """Base64-encode a PaymentPayload dict for the payment-signature header."""
     return base64.b64encode(json.dumps(auth).encode()).decode()

{oneshot_python-0.8.1 → oneshot_python-0.8.3}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "oneshot-python"
-version = "0.8.1"
+version = "0.8.3"
 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.8.1 → oneshot_python-0.8.3}/tests/test_x402.py

@@ -15,6 +15,7 @@ from eth_account import Account
 
 from oneshot.x402 import (
     _parse_usdc_amount,
+    build_zero_cost_authorization,
     encode_payment_header,
     parse_payment_required,
     sign_payment_authorization,
@@ -158,6 +159,101 @@ class TestSignPaymentAuthorization:
         assert auth1["payload"]["authorization"]["nonce"] != auth2["payload"]["authorization"]["nonce"]
 
 
+class TestBuildZeroCostAuthorization:
+    def test_returns_valid_payload(self) -> None:
+        auth = build_zero_cost_authorization(
+            from_address=TEST_ADDRESS,
+            to_address=TO_ADDRESS,
+            accepted=MOCK_ACCEPTED,
+        )
+        assert auth["x402Version"] == 2
+        assert auth["payload"]["signature"] == "0x"
+        assert auth["payload"]["authorization"]["value"] == "0"
+
+    def test_authorization_addresses(self) -> None:
+        auth = build_zero_cost_authorization(
+            from_address=TEST_ADDRESS,
+            to_address=TO_ADDRESS,
+            accepted=MOCK_ACCEPTED,
+        )
+        assert auth["payload"]["authorization"]["from"] == TEST_ADDRESS
+        assert auth["payload"]["authorization"]["to"] == TO_ADDRESS
+
+    def test_nonce_is_32_zero_bytes(self) -> None:
+        auth = build_zero_cost_authorization(
+            from_address=TEST_ADDRESS,
+            to_address=TO_ADDRESS,
+        )
+        nonce = auth["payload"]["authorization"]["nonce"]
+        assert nonce == "0x" + "00" * 32
+        assert len(nonce) == 66
+
+    def test_includes_resource_when_provided(self) -> None:
+        resource = {"url": "https://api.example.com/v1/tools/research", "mimeType": "application/json"}
+        auth = build_zero_cost_authorization(
+            from_address=TEST_ADDRESS,
+            to_address=TO_ADDRESS,
+            resource=resource,
+        )
+        assert auth["resource"] == resource
+
+    def test_omits_resource_when_not_provided(self) -> None:
+        auth = build_zero_cost_authorization(
+            from_address=TEST_ADDRESS,
+            to_address=TO_ADDRESS,
+        )
+        assert "resource" not in auth
+
+    def test_includes_extensions_when_provided(self) -> None:
+        extensions = {"discovery": {"bodyType": "json", "input": {"topic": "AI"}}}
+        auth = build_zero_cost_authorization(
+            from_address=TEST_ADDRESS,
+            to_address=TO_ADDRESS,
+            extensions=extensions,
+        )
+        assert auth["extensions"] == extensions
+
+    def test_omits_extensions_when_not_provided(self) -> None:
+        auth = build_zero_cost_authorization(
+            from_address=TEST_ADDRESS,
+            to_address=TO_ADDRESS,
+        )
+        assert "extensions" not in auth
+
+    def test_echoes_accepted_requirements(self) -> None:
+        auth = build_zero_cost_authorization(
+            from_address=TEST_ADDRESS,
+            to_address=TO_ADDRESS,
+            accepted=MOCK_ACCEPTED,
+        )
+        assert auth["accepted"]["scheme"] == "exact"
+        assert auth["accepted"]["payTo"] == TO_ADDRESS
+
+    def test_base64_roundtrip(self) -> None:
+        """Encoded zero-cost auth should be decodable by the server."""
+        auth = build_zero_cost_authorization(
+            from_address=TEST_ADDRESS,
+            to_address=TO_ADDRESS,
+            accepted=MOCK_ACCEPTED,
+        )
+        encoded = encode_payment_header(auth)
+        decoded = json.loads(base64.b64decode(encoded))
+        assert decoded["payload"]["authorization"]["value"] == "0"
+        assert decoded["payload"]["signature"] == "0x"
+
+    def test_server_detects_zero_value(self) -> None:
+        """Server step 5c: checks decoded.payload.authorization.value === '0'."""
+        auth = build_zero_cost_authorization(
+            from_address=TEST_ADDRESS,
+            to_address=TO_ADDRESS,
+            accepted=MOCK_ACCEPTED,
+        )
+        encoded = encode_payment_header(auth)
+        decoded = json.loads(base64.b64decode(encoded))
+        # This is the exact check the server does in step 5c
+        assert decoded.get("payload", {}).get("authorization", {}).get("value") == "0"
+
+
 class TestEncodePaymentHeader:
     def test_base64_roundtrip(self) -> None:
         auth = sign_payment_authorization(