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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: stacklink-sdk
-Version: 0.3.10
+Version: 0.3.14
 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.14}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "stacklink-sdk"
-version = "0.3.10"
+version = "0.3.14"
 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.14}/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.14}/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,106 @@ 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 BotAttachment(TypedDict, total=False):
+    id: str
+    name: str
+    mediaType: str
+    sizeBytes: int
+    sha256: str | None
+    status: Literal["uploading", "uploaded", "preparing", "ready", "failed", "gone"]
+    facts: dict[str, Any]
+    warnings: list[dict[str, str]]
+    error: dict[str, str] | None
+
+
+class BotFileUpload(TypedDict):
+    fileId: str
+    uploadUrl: str
+    requiredHeaders: dict[str, str]
+    expiresAt: str
+
+
+class BotFiles:
+    """Sync and async clients share this contract; upload bytes with the returned headers."""
+    def __init__(self, client):
+        self.client = client
+
+    def _path(self, bot_id: str, file_id: str | None = None):
+        return "/v1/bots/" + quote(bot_id, safe="") + "/files" + ("/" + quote(file_id, safe="") if file_id else "")
+
+    def create_upload(self, bot_id: str, *, session_id: str, name: str, media_type: str, size_bytes: int):
+        return self.client.request("POST", self._path(bot_id), json_body={"sessionId": session_id, "name": name, "mediaType": media_type, "sizeBytes": size_bytes})
+
+    def finalize(self, bot_id: str, file_id: str, *, session_id: str):
+        return self.client.request("POST", self._path(bot_id, file_id) + "/finalize", json_body={"sessionId": session_id})
+
+    def get(self, bot_id: str, file_id: str, *, session_id: str):
+        return self.client.request("GET", self._path(bot_id, file_id), query={"sessionId": session_id})
+
+    def link(self, bot_id: str, file_id: str, *, session_id: str):
+        return self.client.request("POST", self._path(bot_id, file_id) + "/link", json_body={"sessionId": session_id})
+
+
+class BotRun(TypedDict, total=False):
+    attachments: list[BotAttachment]
+    citations: list[dict[str, Any]]
+    outputs: list[dict[str, Any]]
+    coverage: list[dict[str, Any]]
+    updates: list[dict[str, str]]
+    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))
@@ -60,6 +160,7 @@ def verify_bot_api_request(*, method: str, url: str, body: str, headers: dict[st
 class BotsResource:
     def __init__(self, client, *, async_mode: bool = False):
         self.client = client
+        self.files = BotFiles(client)
         self.async_mode = async_mode
 
     def _path(self, bot_id: str, run_id: str | None = None) -> str:
@@ -132,10 +233,14 @@ 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, attachments: list[str] | None = None):
         body: dict[str, Any] = {"sessionId": session_id, "message": message, "variables": variables or {}, "runId": run_id or str(uuid4())}
+        if attachments is not None:
+            body["attachments"] = attachments
         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.14}/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.14"
 STACKLINK_PYTHON_USER_AGENT = f"stacklink-python/{STACKLINK_PYTHON_SDK_VERSION}"
 
 

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: stacklink-sdk
-Version: 0.3.10
+Version: 0.3.14
 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.14}/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):
@@ -149,6 +159,37 @@ class StacklinkClientTests(unittest.TestCase):
             ("POST", "/v1/bots/bot-one/apis/api-one/signing-key", {"action": "activate", "keyId": "key-two"}),
         ])
 
+    def test_bot_files_preserve_customer_identity_for_sync_and_async_clients(self):
+        expected = [
+            ("POST", "/v1/bots/bot-one/files", {"sessionId": "customer-a", "name": "notes.sql", "mediaType": "text/plain", "sizeBytes": 42}, {}),
+            ("POST", "/v1/bots/bot-one/files/file-one/finalize", {"sessionId": "customer-a"}, {}),
+            ("GET", "/v1/bots/bot-one/files/file-one", None, {"sessionId": "customer-a"}),
+            ("POST", "/v1/bots/bot-one/files/file-one/link", {"sessionId": "customer-a"}, {}),
+        ]
+        sync_calls = []
+        def transport(method, path, headers, body, query, timeout):
+            sync_calls.append((method, path, body, query))
+            return 200, {}, {"ok": True}
+        client = Stacklink(api_key="test", base_url="https://stacklink.test", transport=transport)
+        client.bots.files.create_upload("bot-one", session_id="customer-a", name="notes.sql", media_type="text/plain", size_bytes=42)
+        client.bots.files.finalize("bot-one", "file-one", session_id="customer-a")
+        client.bots.files.get("bot-one", "file-one", session_id="customer-a")
+        client.bots.files.link("bot-one", "file-one", session_id="customer-a")
+        self.assertEqual(sync_calls, expected)
+        async_calls = []
+        async def handler(request):
+            async_calls.append((request.method, request.url.path, json.loads(request.content) if request.content else None, dict(request.url.params)))
+            return httpx.Response(200, json={"ok": True})
+        async def run():
+            async with httpx.AsyncClient(transport=httpx.MockTransport(handler)) as http:
+                client = AsyncStacklink(api_key="test", base_url="https://stacklink.test", http_client=http)
+                await client.bots.files.create_upload("bot-one", session_id="customer-a", name="notes.sql", media_type="text/plain", size_bytes=42)
+                await client.bots.files.finalize("bot-one", "file-one", session_id="customer-a")
+                await client.bots.files.get("bot-one", "file-one", session_id="customer-a")
+                await client.bots.files.link("bot-one", "file-one", session_id="customer-a")
+        asyncio.run(run())
+        self.assertEqual(async_calls, expected)
+
     def test_callback_signature_uses_original_body_and_expiry(self):
         import base64, hashlib, hmac
         from stacklink import verify_webhook_signature