oneshot-python 0.38.0__tar.gz → 0.40.0__tar.gz

oneshot_python-0.40.0/CHANGELOG.md

@@ -0,0 +1,7 @@
+# Changelog
+
+## 0.40.0 — breaking release (#1336)
+
+- Renamed `commerce_search()` / `acommerce_search()` → `product_find()` / `aproduct_find()`, without aliases.
+- Product discovery now calls `POST /v1/tools/find/product` (price key `find/product`), replacing `POST /v1/tools/commerce/search` (`commerce/search`). Input, results and Purchase compatibility are unchanged.
+- Release together with the person/company and other tool renames in #1334 and #1382; publish only with the coordinated server release.

{oneshot_python-0.38.0 → oneshot_python-0.40.0}/PKG-INFO

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

{oneshot_python-0.38.0 → oneshot_python-0.40.0}/README.md

@@ -244,7 +244,7 @@ except LinkedInConnectRequiredError:
 
 Account reads stop offering reconnect after confirming upstream deletion.
 Missing accounts are excluded from the active list; `include_revoked=True`
-lets you inspect their `deleted_upstream` status and `reconnect_required=False`.
+lets you inspect their `connection_deleted` status and `reconnect_required=False`.
 Authentication failures and timeouts remain ordinary errors and do not instruct
 the consumer to create a new connection.
 
@@ -343,3 +343,18 @@ async form).
 ## License
 
 MIT
+
+## Optional phone lookup
+
+Phone lookup is off by default. Source-returned numbers and published business or record numbers still appear. `include_phone=True` adds $0.10 × the requested search limit (default 100 → $10), or $0.10 for profile/dossier, for up to that many people with no guaranteed hit. Fallbacks and callbacks cost nothing extra. A completed lookup with no phone match is charged; a failed job is refunded.
+
+`max_cost` and per-transaction budgets apply to the full quote before authorization, even when credits cover it. Wallet and access-token sessions both obtain a quote before execution and retry with `x-quote-id`.
+
+```python
+people = client.person_find(job_titles=["CTO"], limit=3, include_phone=True, max_cost=1, wait_for_phones=True)
+profile = client.person_profile(email="jane@example.com", include_phone=True, max_cost=1, wait_for_phones=True)
+dossier = client.person_dossier(email="jane@example.com", include_phone=True, max_cost=1, wait_for_phones=True, timeout_sec=600)
+# Async equivalents: await client.aperson_find(...), aperson_profile(...), aperson_dossier(...).
+```
+
+`wait=False` returns the job and receipt IDs immediately. `wait_for_phones=True` keeps polling for pending phone callbacks after completion; it does not buy phones by itself. On timeout, the latest result can still have `phones_pending: True`.

{oneshot_python-0.38.0 → oneshot_python-0.40.0}/oneshot/client.py

@@ -60,13 +60,13 @@ try:
 
     SDK_VERSION = _pkg_version("oneshot-python")
 except Exception:  # pragma: no cover - editable/source runs without dist metadata
-    SDK_VERSION = "0.38.0"
+    SDK_VERSION = "0.40.0"
 
 _BASE_URL = "https://win.oneshotagent.com"
 _HUNT_BASE_URL = "https://api.soulhunt.ai"
 _ACCESS_TOKEN_RE = re.compile(r"^oneshot_[0-9a-f]{64}$")
 # Endpoints whose admission reads a "submit"-scoped agent proof (same list as the TypeScript SDK).
-_DURABLE_ADMISSION_ENDPOINT = re.compile(r"(enrich/(profile|email)|verify/email|physical-mail/send)$")
+_DURABLE_ADMISSION_ENDPOINT = re.compile(r"(lookup/person-(profile|email|email-status)|lookup/place-permits|physical-mail/send)$")
 _CHAIN_ID = 8453
 _USDC_ADDRESS = "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"
 
@@ -917,6 +917,7 @@ class OneShotClient:
         on the ``x-quote-id`` header from the very first attempt, since
         quote-based routes reject before the 402 dance even starts without it.
         """
+        person_quote = endpoint in ("/v1/tools/find/person", "/v1/tools/lookup/person-profile", "/v1/tools/lookup/person-dossier")
         memo = payload.get("memo")
         if memo is not None:
             if not isinstance(memo, str) or not memo.strip():
@@ -999,7 +1000,7 @@ class OneShotClient:
                     "processing",
                 ):
                     if not wait:
-                        return result if endpoint.endswith(("/linkedin/invite", "/linkedin/invite/withdraw")) else {"request_id": result["request_id"], "status": result["status"]}
+                        return result if person_quote or endpoint.endswith(("/linkedin/invite", "/linkedin/invite/withdraw")) else {"request_id": result["request_id"], "status": result["status"]}
                     return await self._poll_job(
                         client,
                         result["request_id"],
@@ -1039,6 +1040,9 @@ class OneShotClient:
                         f"Quote ${total} exceeds max_cost ${max_cost}"
                     )
 
+            if person_quote and total is not None:
+                self._assert_within_budget(total)
+
             self._log(f"Payment required: {payment_request['amount']} USDC")
 
             if self._access_token:
@@ -1068,7 +1072,7 @@ class OneShotClient:
                 result = resp2.json()
                 if isinstance(result, dict) and result.get("request_id") and result.get("status") in ("pending", "processing"):
                     if not wait:
-                        return result if endpoint.endswith(("/linkedin/invite", "/linkedin/invite/withdraw")) else {"request_id": result["request_id"], "status": result["status"]}
+                        return result if person_quote or endpoint.endswith(("/linkedin/invite", "/linkedin/invite/withdraw")) else {"request_id": result["request_id"], "status": result["status"]}
                     return await self._poll_job(
                         client, result["request_id"], timeout_sec,
                         wait_for_phones=wait_for_phones, phone_timeout_sec=phone_timeout_sec,
@@ -1158,7 +1162,7 @@ class OneShotClient:
             ):
                 self._log(f"Job queued: {result['request_id']}")
                 if not wait:
-                    return result if endpoint.endswith(("/linkedin/invite", "/linkedin/invite/withdraw")) else {"request_id": result["request_id"], "status": result["status"]}
+                    return result if person_quote or endpoint.endswith(("/linkedin/invite", "/linkedin/invite/withdraw")) else {"request_id": result["request_id"], "status": result["status"]}
                 return await self._poll_job(
                     client,
                     result["request_id"],
@@ -2073,37 +2077,49 @@ class OneShotClient:
         approval_id = kwargs.pop("approval_id", None)
         return await self.acall_tool("/v1/tools/sms/send", {"message": message, "to_number": to_number, **kwargs}, approval_id=approval_id)
 
-    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 company_search(self, **kwargs: Any) -> Any:
+    @staticmethod
+    def _person_call_options(kwargs: dict[str, Any]) -> dict[str, Any]:
+        """Keep SDK controls out of the canonical quoted input."""
+        return {key: kwargs.pop(key) for key in (
+            "max_cost", "timeout_sec", "wait", "wait_for_phones",
+            "phone_timeout_sec", "idempotency_key", "approval_id",
+        ) if key in kwargs}
+
+    def person_find(self, *, include_phone: bool = False, **kwargs: Any) -> Any:
+        """Phone lookup is off by default; opt-in uses the limit (default 100) and the per-person add-on on the pricing page, with no hit guaranteed."""
+        options = self._person_call_options(kwargs)
+        return self.call_tool("/v1/tools/find/person", {**kwargs, "include_phone": include_phone}, **options)
+
+    async def aperson_find(self, *, include_phone: bool = False, **kwargs: Any) -> Any:
+        """Phone lookup is off by default; opt-in uses the limit (default 100) and the per-person add-on on the pricing page, with no hit guaranteed."""
+        options = self._person_call_options(kwargs)
+        return await self.acall_tool("/v1/tools/find/person", {**kwargs, "include_phone": include_phone}, **options)
+
+    def person_profile(self, *, include_phone: bool = False, **kwargs: Any) -> Any:
+        """Phone lookup is off by default; opt-in uses the add-on on the pricing page for one person, with no hit guaranteed."""
+        options = self._person_call_options(kwargs)
+        return self.call_tool("/v1/tools/lookup/person-profile", {**kwargs, "include_phone": include_phone}, **options)
+
+    async def aperson_profile(self, *, include_phone: bool = False, **kwargs: Any) -> Any:
+        """Phone lookup is off by default; opt-in uses the add-on on the pricing page for one person, with no hit guaranteed."""
+        options = self._person_call_options(kwargs)
+        return await self.acall_tool("/v1/tools/lookup/person-profile", {**kwargs, "include_phone": include_phone}, **options)
+
+    def company_find(self, **kwargs: Any) -> Any:
         """Search for companies by name, domain, industry, location, size, etc. Blocking."""
-        return self.call_tool("/v1/tools/research/company", kwargs)
+        return self.call_tool("/v1/tools/find/company", kwargs)
 
-    async def acompany_search(self, **kwargs: Any) -> Any:
+    async def acompany_find(self, **kwargs: Any) -> Any:
         """Search for companies by name, domain, industry, location, size, etc. Async."""
-        return await self.acall_tool("/v1/tools/research/company", kwargs)
+        return await self.acall_tool("/v1/tools/find/company", kwargs)
 
-    def enrich_company(self, **kwargs: Any) -> Any:
+    def company_profile(self, **kwargs: Any) -> Any:
         """Enrich a company from domain, name, LinkedIn URL, or ticker. Blocking."""
-        return self.call_tool("/v1/tools/enrich/company", kwargs)
+        return self.call_tool("/v1/tools/lookup/company-profile", kwargs)
 
-    async def aenrich_company(self, **kwargs: Any) -> Any:
+    async def acompany_profile(self, **kwargs: Any) -> Any:
         """Enrich a company from domain, name, LinkedIn URL, or ticker. Async."""
-        return await self.acall_tool("/v1/tools/enrich/company", kwargs)
+        return await self.acall_tool("/v1/tools/lookup/company-profile", kwargs)
 
     def business_find(self, **kwargs: Any) -> Any:
         """Discover local businesses (restaurants, contractors, practices) by category/keywords x location. Blocking."""
@@ -2129,7 +2145,7 @@ class OneShotClient:
         """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/find/record-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:
+    def person_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:
@@ -2138,9 +2154,9 @@ class OneShotClient:
             payload["first_name"] = first_name
         if last_name:
             payload["last_name"] = last_name
-        return self.call_tool("/v1/tools/enrich/email", payload)
+        return self.call_tool("/v1/tools/lookup/person-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:
+    async def aperson_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:
@@ -2149,71 +2165,73 @@ class OneShotClient:
             payload["first_name"] = first_name
         if last_name:
             payload["last_name"] = last_name
-        return await self.acall_tool("/v1/tools/enrich/email", payload)
+        return await self.acall_tool("/v1/tools/lookup/person-email", payload)
 
-    def verify_email(self, email: str) -> Any:
+    def person_email_status(self, email: str) -> Any:
         """Verify email deliverability. Blocking."""
-        return self.call_tool("/v1/tools/verify/email", {"email": email})
+        return self.call_tool("/v1/tools/lookup/person-email-status", {"email": email})
 
-    async def averify_email(self, email: str) -> Any:
+    async def aperson_email_status(self, email: str) -> Any:
         """Verify email deliverability. Async."""
-        return await self.acall_tool("/v1/tools/verify/email", {"email": email})
+        return await self.acall_tool("/v1/tools/lookup/person-email-status", {"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)
+    def person_dossier(self, *, include_phone: bool = False, **kwargs: Any) -> Any:
+        """Phone lookup is off by default; opt-in uses the add-on on the pricing page for one person, with no hit guaranteed."""
+        options = self._person_call_options(kwargs)
+        return self.call_tool("/v1/tools/lookup/person-dossier", {**kwargs, "include_phone": include_phone}, **options)
 
-    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)
+    async def aperson_dossier(self, *, include_phone: bool = False, **kwargs: Any) -> Any:
+        """Phone lookup is off by default; opt-in uses the add-on on the pricing page for one person, with no hit guaranteed."""
+        options = self._person_call_options(kwargs)
+        return await self.acall_tool("/v1/tools/lookup/person-dossier", {**kwargs, "include_phone": include_phone}, **options)
 
-    def social_profiles(self, **kwargs: Any) -> Any:
+    def person_social_accounts(self, **kwargs: Any) -> Any:
         """Discover social media profiles. Blocking."""
-        return self.call_tool("/v1/tools/research/social", kwargs)
+        return self.call_tool("/v1/tools/lookup/person-social-accounts", kwargs)
 
-    async def asocial_profiles(self, **kwargs: Any) -> Any:
+    async def aperson_social_accounts(self, **kwargs: Any) -> Any:
         """Discover social media profiles. Async."""
-        return await self.acall_tool("/v1/tools/research/social", kwargs)
+        return await self.acall_tool("/v1/tools/lookup/person-social-accounts", kwargs)
 
-    def article_search(self, name: str, company: str, **kwargs: Any) -> Any:
+    def person_articles(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})
+        return self.call_tool("/v1/tools/lookup/person-articles", {"name": name, "company": company, **kwargs})
 
-    async def aarticle_search(self, name: str, company: str, **kwargs: Any) -> Any:
+    async def aperson_articles(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})
+        return await self.acall_tool("/v1/tools/lookup/person-articles", {"name": name, "company": company, **kwargs})
 
-    def person_newsfeed(self, social_media_url: str, **kwargs: Any) -> Any:
+    def person_posts(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})
+        return self.call_tool("/v1/tools/lookup/person-posts", {"social_media_url": social_media_url, **kwargs})
 
-    async def aperson_newsfeed(self, social_media_url: str, **kwargs: Any) -> Any:
+    async def aperson_posts(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})
+        return await self.acall_tool("/v1/tools/lookup/person-posts", {"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)
+        return self.call_tool("/v1/tools/lookup/person-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)
+        return await self.acall_tool("/v1/tools/lookup/person-interests", kwargs)
 
-    def person_interactions(self, social_media_url: str, **kwargs: Any) -> Any:
+    def person_followers(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})
+        return self.call_tool("/v1/tools/lookup/person-followers", {"social_media_url": social_media_url, **kwargs})
 
-    async def aperson_interactions(self, social_media_url: str, **kwargs: Any) -> Any:
+    async def aperson_followers(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})
+        return await self.acall_tool("/v1/tools/lookup/person-followers", {"social_media_url": social_media_url, **kwargs})
 
-    def commerce_search(self, query: str, *, limit: int = 10, **kwargs: Any) -> Any:
+    def product_find(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})
+        return self.call_tool("/v1/tools/find/product", {"query": query, "limit": limit, **kwargs})
 
-    async def acommerce_search(self, query: str, *, limit: int = 10, **kwargs: Any) -> Any:
+    async def aproduct_find(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})
+        return await self.acall_tool("/v1/tools/find/product", {"query": query, "limit": limit, **kwargs})
 
     def commerce_buy(self, product_url: str, shipping_address: dict[str, Any], **kwargs: Any) -> Any:
         """Purchase a product. Blocking."""
@@ -2515,19 +2533,27 @@ class OneShotClient:
     @staticmethod
     def _is_phones_pending(result: Any) -> bool:
         """Detects whether a result is awaiting Apollo's async phone-reveal
-        webhook. Tolerates two shapes: the unwrapped result ``{phones_pending}``
-        and the deep_research_person wrapper ``{result: {phones_pending}}``.
+        webhook. Accepts worker search rows, profile objects, dossier sections
+        and legacy flat results.
 
         Mirrors the TS SDK's _isPhonesPending — kept in lockstep so the worker
         contract works for both SDKs.
         """
         if not isinstance(result, dict):
             return False
-        if result.get("phones_pending") is True:
-            return True
-        inner = result.get("result")
-        if isinstance(inner, dict) and inner.get("phones_pending") is True:
-            return True
+        def pending(value: Any) -> bool:
+            return isinstance(value, dict) and value.get("phones_pending") is True
+
+        for body in (result, result.get("result")):
+            if not isinstance(body, dict):
+                continue
+            profile = body.get("profile")
+            data = profile.get("data") if isinstance(profile, dict) else None
+            rows = body.get("results")
+            if pending(body) or pending(profile) or pending(data):
+                return True
+            if isinstance(rows, list) and any(pending(row) for row in rows):
+                return True
         return False
 
     async def _poll_for_phones(