stacklink-sdk 0.3.10__tar.gz → 0.3.13__tar.gz

{stacklink_sdk-0.3.10/stacklink_sdk.egg-info → stacklink_sdk-0.3.13}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: stacklink-sdk
-Version: 0.3.10
+Version: 0.3.13
 Summary: Python SDK for Stacklink sessions, tools, MCP, auth, workbench, logs, knowledge, and billing.
 Author: Stacklink
 License-Expression: LicenseRef-Proprietary

{stacklink_sdk-0.3.10 → stacklink_sdk-0.3.13}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "stacklink-sdk"
-version = "0.3.10"
+version = "0.3.13"
 description = "Python SDK for Stacklink sessions, tools, MCP, auth, workbench, logs, knowledge, and billing."
 readme = "README.md"
 license = "LicenseRef-Proprietary"

{stacklink_sdk-0.3.10 → stacklink_sdk-0.3.13}/stacklink/__init__.py

@@ -1,6 +1,6 @@
 from __future__ import annotations
 
-from .bots import verify_bot_api_request, sign_bot_trigger_request
+from .bots import verify_bot_api_request, sign_bot_trigger_request, BotRun, BotConnectionAction, BotExecutionWait, BotCapabilityFact, BotRequirement
 from .approvals import ApprovalDecision, ApprovalRecord, ApprovalEvent, ApprovalPermissions, CustomerApprovalGrantInput
 from .webhooks import verify_webhook_signature
 from .client import AsyncStacklink, STACKLINK_PYTHON_SDK_VERSION, Stacklink
@@ -27,6 +27,7 @@ from .types import (
 )
 
 __all__ = [
+    "BotRun", "BotConnectionAction", "BotExecutionWait", "BotCapabilityFact", "BotRequirement",
     "ApprovalDecision", "ApprovalRecord", "ApprovalEvent", "ApprovalPermissions",
     "CustomerApprovalGrantInput",
     "Stacklink",

{stacklink_sdk-0.3.10 → stacklink_sdk-0.3.13}/stacklink/bots.py

@@ -1,6 +1,6 @@
 """Hosted bot management and durable runs for sync and async clients."""
 from __future__ import annotations
-from typing import Any
+from typing import Any, Literal, TypedDict
 from contextlib import closing, aclosing
 import asyncio
 import base64
@@ -15,6 +15,61 @@ from urllib.parse import quote
 from uuid import uuid4
 
 
+class _BotCapabilityAccount(TypedDict, total=False):
+    account: Literal["project", "customer"]
+
+
+class BotCapabilityFact(_BotCapabilityAccount):
+    id: str
+    status: Literal["enabled", "disabled", "sample"]
+    owner: Literal["project_owner", "customer"]
+
+
+class _BotConnectionDetails(TypedDict, total=False):
+    providerName: str
+    providerIconUrl: str
+    intent: Literal["connect", "reconnect"]
+    canResume: bool
+
+
+class BotConnectionAction(_BotConnectionDetails):
+    kind: Literal["connection"]
+    id: str
+    providerKey: str
+    owner: Literal["customer", "project_owner"]
+    status: str
+    expiresAt: str
+    action: dict[str, str] | None
+
+
+class BotExecutionWait(TypedDict):
+    kind: Literal["execution"]
+    id: str
+
+
+class BotRequirement(TypedDict):
+    capabilityId: str
+    code: str
+    owner: Literal["project_owner", "stacklink"]
+    nextAction: Literal["configure_bot", "repair_connection", "use_live_data", "contact_administrator", "unavailable"]
+
+
+class BotRun(TypedDict, total=False):
+    id: str
+    botId: str
+    conversationId: str
+    status: str
+    finalText: str | None
+    output: Any
+    error: Any
+    waitingOperation: BotConnectionAction | BotExecutionWait | None
+    connection: BotConnectionAction | None
+    capabilities: list[BotCapabilityFact]
+    requirements: list[BotRequirement]
+    usage: dict[str, Any]
+    display: dict[str, Any]
+
+
 def sign_bot_trigger_request(*, trigger_id: str, secret: str, body: str, request_id: str | None = None, now: float | None = None) -> dict[str, str]:
     """Sign the exact JSON bytes. Reuse request_id when retrying the same event."""
     timestamp = str(int(time.time() if now is None else now))
@@ -132,10 +187,12 @@ class BotsResource:
     def publish(self, bot_id: str, revision: int, channels: dict[str, bool]):
         return self.client.request("POST", self._path(bot_id) + "/publish", json_body={"revision": revision, "channels": channels})
 
-    def run(self, bot_id: str, *, session_id: str, message: str, variables: dict[str, Any] | None = None, conversation_id: str | None = None, run_id: str | None = None):
+    def run(self, bot_id: str, *, session_id: str, message: str, variables: dict[str, Any] | None = None, conversation_id: str | None = None, run_id: str | None = None, connection_return_url: str | None = None):
         body: dict[str, Any] = {"sessionId": session_id, "message": message, "variables": variables or {}, "runId": run_id or str(uuid4())}
         if conversation_id:
             body["conversationId"] = conversation_id
+        if connection_return_url is not None:
+            body["connectionReturnUrl"] = connection_return_url
         return self.client.request("POST", self._path(bot_id) + "/runs", json_body=body)
 
     def get_run(self, bot_id: str, run_id: str):

{stacklink_sdk-0.3.10 → stacklink_sdk-0.3.13}/stacklink/client.py

@@ -37,7 +37,7 @@ from .types import Json, Transport
 from .webhooks import WebhooksResource
 from .workbench import WorkbenchResource
 
-STACKLINK_PYTHON_SDK_VERSION = "0.3.10"
+STACKLINK_PYTHON_SDK_VERSION = "0.3.13"
 STACKLINK_PYTHON_USER_AGENT = f"stacklink-python/{STACKLINK_PYTHON_SDK_VERSION}"
 
 

{stacklink_sdk-0.3.10 → stacklink_sdk-0.3.13/stacklink_sdk.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: stacklink-sdk
-Version: 0.3.10
+Version: 0.3.13
 Summary: Python SDK for Stacklink sessions, tools, MCP, auth, workbench, logs, knowledge, and billing.
 Author: Stacklink
 License-Expression: LicenseRef-Proprietary

{stacklink_sdk-0.3.10 → stacklink_sdk-0.3.13}/tests/test_client.py

@@ -130,6 +130,16 @@ class StacklinkClientTests(unittest.TestCase):
         self.assertEqual(headers["stacklink-signature"], hmac.new(b"fixture", signed.encode(), hashlib.sha256).hexdigest())
         self.assertNotEqual(headers["stacklink-signature"], sign_bot_trigger_request(trigger_id="trigger-one", secret="fixture", body=body + " ", request_id="event-one", now=1000)["stacklink-signature"])
 
+    def test_bot_connection_return_url_uses_the_admitted_run_contract(self):
+        calls = []
+        def transport(method, path, headers, body, query, timeout):
+            calls.append((method, path, body))
+            return 200, {}, {"id": "run"}
+        client = Stacklink(api_key="ppk_test", base_url="http://stacklink.test", transport=transport)
+        client.bots.run("bot-one", session_id="session-one", message="Read profile", connection_return_url="https://client.example/connected")
+        self.assertEqual(calls[0][2]["connectionReturnUrl"], "https://client.example/connected")
+        self.assertEqual(calls[0][2]["sessionId"], "session-one")
+
     def test_bot_management_uses_shared_routes_and_exact_customer_session(self):
         calls = []
         def transport(method, path, headers, body, query, timeout):