oneshot-python 0.14.0__tar.gz → 0.16.0__tar.gz

{oneshot_python-0.14.0 → oneshot_python-0.16.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: oneshot-python
-Version: 0.14.0
+Version: 0.16.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.14.0 → oneshot_python-0.16.0}/oneshot/client.py

@@ -38,7 +38,7 @@ try:
 
     SDK_VERSION = _pkg_version("oneshot-python")
 except Exception:  # pragma: no cover - editable/source runs without dist metadata
-    SDK_VERSION = "0.12.1"
+    SDK_VERSION = "0.16.0"
 
 # ---------------------------------------------------------------------------
 # Environment configuration
@@ -62,6 +62,7 @@ def _build_email_payload(
     extra: dict[str, Any],
     *,
     reply_to_email_id: Optional[str] = None,
+    mailbox_mode: Optional[str] = None,
 ) -> dict[str, Any]:
     """Build the /v1/tools/email/send body in the API's field convention.
 
@@ -93,6 +94,8 @@ def _build_email_payload(
         payload["reply_to_email_id"] = reply_to_email_id
     if from_name:
         payload["from_name"] = from_name
+    if mailbox_mode:
+        payload["mailbox_mode"] = mailbox_mode
     return payload
 
 
@@ -760,6 +763,7 @@ class OneShotClient:
         from_mailbox: Optional[str] = None,
         from_name: Optional[str] = None,
         reply_to_email_id: Optional[str] = None,
+        mailbox_mode: Optional[str] = None,
         **kwargs: Any,
     ) -> Any:
         """Send an email. Blocking.
@@ -767,10 +771,21 @@ class OneShotClient:
         Set ``reply_to_email_id`` (an inbound email id from ``inbox()``) to
         reply within a thread — ``to``/``subject`` are then derived from the
         inbound message unless given.
+
+        The first send from any ``from_mailbox`` on an owned domain — including
+        the default ``agent@`` — provisions a mailbox per address and adds a
+        one-time ``mailbox_provisioning_fee`` to the quote; it's free only once
+        that address is already provisioned (``active``).
+
+        ``mailbox_mode`` ('relay' | 'mailbox', default 'relay') selects how a
+        domain sends: 'relay' is header-only send (no per-address mailbox, no
+        mailbox fee); 'mailbox' provisions a real dedicated mailbox per address
+        (better deliverability + per-address warmup). Only applies when a domain
+        is first set up — use it on a new ``from_domain``.
         """
         return self.call_tool(
             "/v1/tools/email/send",
-            _build_email_payload(to, subject, body, from_domain, from_mailbox, from_name, kwargs, reply_to_email_id=reply_to_email_id),
+            _build_email_payload(to, subject, body, from_domain, from_mailbox, from_name, kwargs, reply_to_email_id=reply_to_email_id, mailbox_mode=mailbox_mode),
         )
 
     async def aemail(
@@ -783,6 +798,7 @@ class OneShotClient:
         from_mailbox: Optional[str] = None,
         from_name: Optional[str] = None,
         reply_to_email_id: Optional[str] = None,
+        mailbox_mode: Optional[str] = None,
         **kwargs: Any,
     ) -> Any:
         """Send an email. Async.
@@ -790,10 +806,13 @@ class OneShotClient:
         Set ``reply_to_email_id`` (an inbound email id from ``ainbox()``) to
         reply within a thread — ``to``/``subject`` are then derived from the
         inbound message unless given.
+
+        ``mailbox_mode`` ('relay' | 'mailbox', default 'relay') selects how a
+        domain sends — see ``email()`` for details.
         """
         return await self.acall_tool(
             "/v1/tools/email/send",
-            _build_email_payload(to, subject, body, from_domain, from_mailbox, from_name, kwargs, reply_to_email_id=reply_to_email_id),
+            _build_email_payload(to, subject, body, from_domain, from_mailbox, from_name, kwargs, reply_to_email_id=reply_to_email_id, mailbox_mode=mailbox_mode),
         )
 
     def voice(self, objective: str, target_number: str, **kwargs: Any) -> Any:
@@ -968,21 +987,27 @@ class OneShotClient:
         value_tag: Optional[dict[str, Any]] = None,
         *,
         request_id: Optional[str] = None,
+        goal_id: Optional[str] = None,
     ) -> dict:
-        """Tag a receipt with a value for RoCS computation. Blocking.
+        """Tag business value for RoCS computation. Blocking.
 
-        Identify the receipt by ``receipt_id`` (``rcpt_…``) or, equivalently, by
-        the ``request_id`` returned from the originating tool call — the API
-        resolves a ``request_id`` via the receipt's ``job_id``, so you can tag
-        value without a prior receipts lookup.
+        Address the value three ways: by ``receipt_id`` (``rcpt_…``); by the
+        ``request_id`` returned from the originating tool call (the API resolves
+        it via the receipt's ``job_id``); or by ``goal_id`` — a correlation key
+        that attributes a whole *cadence's* outcome (a closed deal across the
+        intro email + follow-ups + find/verify/enrich calls sharing
+        ``decisionContext.goalId``) in one call. Read goal-level rollups back via
+        ``rocs_by_goal``.
 
         ``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.
+        ``savings``, ``engagement``. 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, request_id=request_id)
+            self.atag_receipt_value(
+                receipt_id, value_tag, request_id=request_id, goal_id=goal_id
+            )
         )
 
     async def atag_receipt_value(
@@ -991,15 +1016,24 @@ class OneShotClient:
         value_tag: Optional[dict[str, Any]] = None,
         *,
         request_id: Optional[str] = None,
+        goal_id: Optional[str] = None,
     ) -> dict:
-        """Tag a receipt with a value for RoCS computation. Async."""
+        """Tag business value for RoCS computation. Async."""
+        if not isinstance(value_tag, dict) or not value_tag.get("type"):
+            raise ValidationError("value_tag.type is required", "value_tag.type")
+
+        # Cadence-level: route to the outcome ledger by correlation key.
+        if goal_id and not receipt_id and not request_id:
+            return await self.acall_free_post(
+                "/v1/analytics/outcomes",
+                {"goal_id": goal_id, **value_tag},
+            )
+
         target = receipt_id or request_id
         if not target:
             raise ValidationError(
-                "receipt_id or request_id is required", "receipt_id"
+                "receipt_id, request_id, or goal_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/{target}/value",
             value_tag,

{oneshot_python-0.14.0 → oneshot_python-0.16.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "oneshot-python"
-version = "0.14.0"
+version = "0.16.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.14.0 → oneshot_python-0.16.0}/tests/test_email_payload.py

@@ -46,6 +46,18 @@ def test_payload_passes_extra_kwargs():
     assert p["wait"] is True
 
 
+def test_payload_forwards_mailbox_mode():
+    # mailbox_mode is an explicit keyword-only param, forwarded into the send body so
+    # the API's per-domain provider override + fee logic sees it.
+    p = _build_email_payload("r@x.com", "S", "B", "acme.com", None, None, {}, mailbox_mode="mailbox")
+    assert p["mailbox_mode"] == "mailbox"
+
+
+def test_payload_omits_mailbox_mode_when_absent():
+    p = _build_email_payload("r@x.com", "S", "B", "acme.com", None, None, {})
+    assert "mailbox_mode" not in p
+
+
 # ── reply threading (reply_to_email_id) ───────────────────────────────────
 
 def test_reply_payload_omits_to_and_subject_when_derivable():