assistant-runtime-sdk 1.0.1__tar.gz → 1.2.0__tar.gz

{assistant_runtime_sdk-1.0.1 → assistant_runtime_sdk-1.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: assistant_runtime_sdk
-Version: 1.0.1
+Version: 1.2.0
 Summary: Python SDK for FAC Cloud - the Assistant Runtime AI assistant backend
 Keywords: frappe,ai,assistant,llm,mcp,anthropic,openai,streaming
 Author: Paul Clinton
@@ -157,8 +157,9 @@ surface. A representative selection:
 `create_message()`, `update_conversation()`, `delete_conversation()`, `delete_message()`
 
 **Billing** — `get_plan_comparison()`, `get_usage_dashboard()`, `get_usage_history()`,
-`get_credit_balance()`, `initiate_checkout()`, `verify_checkout()`, `upgrade_plan()`,
-`cancel_subscription()`, `get_invoices()`
+`get_credit_balance()`, `initiate_checkout()`, `create_hosted_checkout()`,
+`verify_checkout()`, `upgrade_plan()`, `cancel_subscription()`, `get_invoices()`,
+`get_payment_instrument()`, `update_payment_method()`
 
 **Users & seats** — `register_user()`, `get_user()`, `list_users()`, `invite_user()`,
 `add_user_seat()`, `set_user_credit_limit()`, `get_user_auth_status()`

{assistant_runtime_sdk-1.0.1 → assistant_runtime_sdk-1.2.0}/README.md

@@ -124,8 +124,9 @@ surface. A representative selection:
 `create_message()`, `update_conversation()`, `delete_conversation()`, `delete_message()`
 
 **Billing** — `get_plan_comparison()`, `get_usage_dashboard()`, `get_usage_history()`,
-`get_credit_balance()`, `initiate_checkout()`, `verify_checkout()`, `upgrade_plan()`,
-`cancel_subscription()`, `get_invoices()`
+`get_credit_balance()`, `initiate_checkout()`, `create_hosted_checkout()`,
+`verify_checkout()`, `upgrade_plan()`, `cancel_subscription()`, `get_invoices()`,
+`get_payment_instrument()`, `update_payment_method()`
 
 **Users & seats** — `register_user()`, `get_user()`, `list_users()`, `invite_user()`,
 `add_user_seat()`, `set_user_credit_limit()`, `get_user_auth_status()`

{assistant_runtime_sdk-1.0.1 → assistant_runtime_sdk-1.2.0}/assistant_runtime_sdk/__init__.py

@@ -53,7 +53,7 @@ Standalone Functions:
 
 """
 
-__version__ = "1.0.1"
+__version__ = "1.2.0"
 __author__ = "Paul Clinton"
 __license__ = "AGPL-3.0"
 

{assistant_runtime_sdk-1.0.1 → assistant_runtime_sdk-1.2.0}/assistant_runtime_sdk/async_client.py

@@ -872,6 +872,16 @@ class AsyncAssistantRuntimeClient(BaseAssistantRuntimeClient):
         endpoint, payload = self._prepare_initiate_checkout(plan, billing_cycle, gateway, billing_name, billing_email)
         return await self._request_post_json(endpoint, payload, api_base=self.billing_api_base)
 
+    async def create_hosted_checkout(
+        self,
+        purpose: str,
+        params: Optional[Dict[str, Any]] = None,
+        return_url: Optional[str] = None,
+    ) -> Optional[Dict[str, Any]]:
+        """Async version of AssistantRuntimeClient.create_hosted_checkout."""
+        endpoint, payload = self._prepare_create_hosted_checkout(purpose, params, return_url)
+        return await self._request_post_json(endpoint, payload, api_base=self.billing_api_base)
+
     async def verify_checkout(self, session_id: Optional[str] = None) -> Optional[Dict[str, Any]]:
         """Async version of AssistantRuntimeClient.verify_checkout."""
         endpoint, payload = self._prepare_verify_checkout(session_id)
@@ -951,6 +961,11 @@ class AsyncAssistantRuntimeClient(BaseAssistantRuntimeClient):
         endpoint, payload = self._prepare_get_payment_methods()
         return await self._request_post_json(endpoint, payload, api_base=self.billing_api_base)
 
+    async def get_payment_instrument(self) -> Optional[Dict[str, Any]]:
+        """Async version of AssistantRuntimeClient.get_payment_instrument."""
+        endpoint, payload = self._prepare_get_payment_instrument()
+        return await self._request_post_json(endpoint, payload, api_base=self.billing_api_base)
+
     async def upgrade_plan(
         self,
         new_plan: str,
@@ -1020,9 +1035,16 @@ class AsyncAssistantRuntimeClient(BaseAssistantRuntimeClient):
         endpoint, payload = self._prepare_resume_subscription()
         return await self._request_post_json(endpoint, payload, api_base=self.billing_api_base)
 
-    async def update_payment_method(self) -> Optional[Dict[str, Any]]:
+    async def update_payment_method(
+        self,
+        payment_method: Optional[str] = None,
+        billing_name: Optional[str] = None,
+    ) -> Optional[Dict[str, Any]]:
         """Async version of AssistantRuntimeClient.update_payment_method."""
-        endpoint, payload = self._prepare_update_payment_method()
+        endpoint, payload = self._prepare_update_payment_method(
+            payment_method=payment_method,
+            billing_name=billing_name,
+        )
         return await self._request_post_json(endpoint, payload, api_base=self.billing_api_base)
 
     async def get_subscription_status(self) -> Optional[Dict[str, Any]]:

{assistant_runtime_sdk-1.0.1 → assistant_runtime_sdk-1.2.0}/assistant_runtime_sdk/base.py

@@ -906,6 +906,20 @@ class BaseAssistantRuntimeClient:
             payload["billing_email"] = billing_email
         return "initiate_checkout", payload
 
+    def _prepare_create_hosted_checkout(
+        self, purpose: str, params: Optional[Dict[str, Any]] = None,
+        return_url: Optional[str] = None,
+    ) -> tuple:
+        self._require_billing()
+        payload: Dict[str, Any] = {
+            "tenant_id": self.tenant_id,
+            "purpose": purpose,
+            "params": params or {},
+        }
+        if return_url:
+            payload["return_url"] = return_url
+        return "create_hosted_checkout", payload
+
     def _prepare_verify_checkout(self, session_id: Optional[str] = None) -> tuple:
         self._require_billing()
         payload: Dict[str, Any] = {"tenant_id": self.tenant_id}
@@ -989,6 +1003,12 @@ class BaseAssistantRuntimeClient:
         self._require_billing()
         return "get_payment_methods", {"tenant_id": self.tenant_id}
 
+    def _prepare_get_payment_instrument(self) -> tuple:
+        """Build the request for ``get_payment_instrument`` — the instrument
+        on file for autopay, plus how it can be changed."""
+        self._require_billing()
+        return "get_payment_instrument", {"tenant_id": self.tenant_id}
+
     def _prepare_upgrade_plan(
         self, new_plan: str, billing_cycle: str = "monthly",
         gateway: Optional[str] = None, billing_name: Optional[str] = None,
@@ -1070,9 +1090,24 @@ class BaseAssistantRuntimeClient:
         self._require_billing()
         return "resume_subscription", {"tenant_id": self.tenant_id}
 
-    def _prepare_update_payment_method(self) -> tuple:
+    def _prepare_update_payment_method(
+        self,
+        payment_method: Optional[str] = None,
+        billing_name: Optional[str] = None,
+    ) -> tuple:
+        """Build the request for ``update_payment_method``.
+
+        Optional values are omitted rather than sent as null: the endpoint
+        derives its own defaults (UPI for India, card otherwise), and an
+        explicit null would override that with nothing.
+        """
         self._require_billing()
-        return "update_payment_method", {"tenant_id": self.tenant_id}
+        payload: Dict[str, Any] = {"tenant_id": self.tenant_id}
+        if payment_method:
+            payload["payment_method"] = payment_method
+        if billing_name:
+            payload["billing_name"] = billing_name
+        return "update_payment_method", payload
 
     def _prepare_get_subscription_status(self) -> tuple:
         self._require_billing()

{assistant_runtime_sdk-1.0.1 → assistant_runtime_sdk-1.2.0}/assistant_runtime_sdk/client.py

@@ -1238,6 +1238,34 @@ class AssistantRuntimeClient(BaseAssistantRuntimeClient):
         endpoint, payload = self._prepare_initiate_checkout(plan, billing_cycle, gateway, billing_name, billing_email)
         return self._request_post_json(endpoint, payload, api_base=self.billing_api_base)
 
+    def create_hosted_checkout(
+        self,
+        purpose: str,
+        params: Optional[Dict[str, Any]] = None,
+        return_url: Optional[str] = None,
+    ) -> Optional[Dict[str, Any]]:
+        """
+        Get a link to the page where a purchase is paid for.
+
+        Payments are collected on the runtime's own public site rather than
+        on this one, so that a payment gateway can be onboarded against a
+        single declared address. Send the user to ``checkout_url``; they are
+        returned to ``return_url`` when they are done.
+
+        Args:
+            purpose: "Subscription", "Payment Method", "Credits", "Pack" or "Seat".
+            params: Purpose-specific arguments — e.g. ``{"plan": "Team",
+                "billing_cycle": "monthly"}`` for a subscription, or
+                ``{"credit_amount": 5000}`` for credits.
+            return_url: Where to send the user afterwards. Must be on this
+                site; defaults to the registered site URL.
+
+        Returns:
+            Dict with checkout_url, session, purpose and expires_at.
+        """
+        endpoint, payload = self._prepare_create_hosted_checkout(purpose, params, return_url)
+        return self._request_post_json(endpoint, payload, api_base=self.billing_api_base)
+
     def verify_checkout(self, session_id: Optional[str] = None) -> Optional[Dict[str, Any]]:
         """Verify payment completion after checkout."""
         endpoint, payload = self._prepare_verify_checkout(session_id)
@@ -1375,6 +1403,51 @@ class AssistantRuntimeClient(BaseAssistantRuntimeClient):
         endpoint, payload = self._prepare_get_payment_methods()
         return self._request_post_json(endpoint, payload, api_base=self.billing_api_base)
 
+    def get_payment_instrument(self) -> Optional[Dict[str, Any]]:
+        """Get the instrument on file for automatic payments.
+
+        One shape regardless of gateway — callers never need to branch on
+        ``gateway`` to read ``autopay``. Fields that only apply to Razorpay
+        (``mandate``, ``max_amount``, ``authorized_on``, ``needs_reauth``,
+        ``vpa``, ``bank``, and ``card.issuer``) are ``None`` on Stripe, not
+        omitted.
+
+        Returns:
+            {
+              "gateway": "razorpay" | "stripe",
+              "autopay": {
+                "mandate": str | None,      # Razorpay only
+                "status": str,
+                "method": "upi" | "card" | "emandate",
+                "label": str,               # "UPI Autopay"
+                "display": str,             # "paul@okhdfcbank" / "Visa •••• 4242"
+                "card": {
+                    "last4": str | None,
+                    "network": str | None,
+                    "issuer": str | None,   # Razorpay only
+                    "expiry": str | None,   # "MM/YYYY"
+                } | None,
+                "vpa": str | None,          # Razorpay UPI only
+                "bank": str | None,         # Razorpay only
+                "max_amount": float | None, # per-debit ceiling, Razorpay only
+                "currency": str,
+                "authorized_on": str | None,  # Razorpay only
+                "next_charge_date": str | None,
+                "needs_reauth": bool | None,  # Razorpay only
+                "suspended": bool,
+              } | None,               # None when no instrument is on file
+              "can_update": bool,
+              "update_mode": "settle" | "swap" | "portal",
+              "amount_due": {"invoice", "amount", "currency"} | None,
+            }
+
+        ``update_mode`` tells the caller what ``update_payment_method`` will
+        do: settle an outstanding invoice, swap the saved instrument, or
+        hand back a Stripe portal URL.
+        """
+        endpoint, payload = self._prepare_get_payment_instrument()
+        return self._request_post_json(endpoint, payload, api_base=self.billing_api_base)
+
     def upgrade_plan(
         self,
         new_plan: str,
@@ -1487,9 +1560,40 @@ class AssistantRuntimeClient(BaseAssistantRuntimeClient):
         endpoint, payload = self._prepare_resume_subscription()
         return self._request_post_json(endpoint, payload, api_base=self.billing_api_base)
 
-    def update_payment_method(self) -> Optional[Dict[str, Any]]:
-        """Get URL to update payment method."""
-        endpoint, payload = self._prepare_update_payment_method()
+    def update_payment_method(
+        self,
+        payment_method: Optional[str] = None,
+        billing_name: Optional[str] = None,
+    ) -> Optional[Dict[str, Any]]:
+        """Change the instrument that pays for this subscription.
+
+        What this does depends on whether anything is owed, which the
+        server decides — call ``get_payment_instrument`` first if you need
+        to know in advance:
+
+        - An unpaid renewal exists: the returned Razorpay checkout settles
+          *that* invoice at the amount it was billed for and registers the
+          new instrument for autopay in the same authorization. The billing
+          period does not move. ``amount_due`` carries the figure.
+        - Nothing is owed: the checkout debits one currency unit purely to
+          register the token, refunded automatically on capture.
+        - Stripe: returns ``portal_url`` for the Customer Portal.
+
+        Args:
+            payment_method: Razorpay only — "upi" (UPI Autopay) or "card".
+                Defaults to "upi" for India, "card" for international.
+            billing_name: Name to prefill in the checkout widget.
+
+        Returns:
+            Razorpay: the checkout payload (``razorpay_key``,
+            ``razorpay_order_id``, ``amount``, ``currency``, ``prefill``, …)
+            plus ``update_mode`` and, when settling, ``amount_due``.
+            Stripe: ``{"update_mode": "portal", "portal_url": str}``.
+        """
+        endpoint, payload = self._prepare_update_payment_method(
+            payment_method=payment_method,
+            billing_name=billing_name,
+        )
         return self._request_post_json(endpoint, payload, api_base=self.billing_api_base)
 
     def get_subscription_status(self) -> Optional[Dict[str, Any]]:

{assistant_runtime_sdk-1.0.1 → assistant_runtime_sdk-1.2.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "assistant_runtime_sdk"
-version = "1.0.1"
+version = "1.2.0"
 description = "Python SDK for FAC Cloud - the Assistant Runtime AI assistant backend"
 readme = "README.md"
 license = {text = "AGPL-3.0"}