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

stacklink_sdk-0.3.10/PKG-INFO

@@ -0,0 +1,139 @@
+Metadata-Version: 2.4
+Name: stacklink-sdk
+Version: 0.3.10
+Summary: Python SDK for Stacklink sessions, tools, MCP, auth, workbench, logs, knowledge, and billing.
+Author: Stacklink
+License-Expression: LicenseRef-Proprietary
+Project-URL: Documentation, https://docs.stacklink.in/docs/quickstart
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: httpx[http2]<1,>=0.27
+Provides-Extra: x-chat
+Requires-Dist: chatxdk==0.5.0; extra == "x-chat"
+Provides-Extra: openai
+Requires-Dist: openai<3,>=2.0; extra == "openai"
+Provides-Extra: openai-agents
+Requires-Dist: openai-agents<0.19,>=0.18; extra == "openai-agents"
+Provides-Extra: claude-agent
+Requires-Dist: claude-agent-sdk<0.3,>=0.2; extra == "claude-agent"
+Dynamic: license-file
+
+# Stacklink Python SDK
+
+## X Chat bot keys
+
+Install `stacklink-sdk[x-chat]` for the official native Chat XDK. Import
+`create_x_bot_chat`, `restore_x_bot_chat` and `XBotChatKeyState` from
+`stacklink.x_chat`. This optional module runs on your bot infrastructure and makes
+no network requests. Personal X Chat remains in the browser SDK; do not pass a
+person's PIN or private keys to this module or to Stacklink's backend.
+
+Call `create_x_bot_chat(account_id, bot_user_id, persist)` once. The `persist`
+callback must store the opaque key state in your secret manager, replacing the
+value for that exact account and bot before returning. Submit the returned
+`registration` public-key payload through X's bot bearer-token API. Fetch the
+registered public-key record, add its exact `user_id`, and call
+`bind_registered_identity(record)`. The helper checks both public keys and their
+binding before exposing `crypto`, the official native XDK for messages, groups,
+reactions, history and encrypted media. Close the session after use.
+
+On restart, call `restore_x_bot_chat(account_id, bot_user_id, stored_state,
+current_public_record, persist)`. Account, bot, key version and both keys must
+match. An uncertain registration must be reconciled using X's current public
+record; do not generate replacement keys automatically. Keep the bot bearer
+token retrieved by `x.getStoredBotToken` in the same customer-owned secret
+manager, separately from its private key blob. Bot bearer tokens are separate
+from a person's OAuth2 grant. This helper supplies local cryptography; it does
+not turn a person's Stacklink connection into a bot connection.
+
+Stacklink supplies executable, governed tools to an agent harness. The selected harness owns the model call, tool loop, and final answer.
+
+Install the public package with the harness extra you use:
+
+```bash
+uv add 'stacklink-sdk[openai-agents]'
+```
+
+or:
+
+```bash
+uv add 'stacklink-sdk[claude-agent]'
+```
+
+The complete guides and certified recipes live at [docs.stacklink.in](https://docs.stacklink.in/docs/quickstart). PyPI is the package delivery system, not the primary documentation surface. Stacklink does not display registry download badges in its product or documentation.
+
+## Certified agent harnesses
+
+| Harness | Stacklink adapter |
+|---|---|
+| OpenAI Agents SDK | `create_stacklink_openai_agents_tools(session)` |
+| Claude Agent SDK | `create_stacklink_claude_agent_tool_config(session)` |
+
+Both start with one explicit Stacklink session:
+
+```python
+import os
+from stacklink import Stacklink
+
+stacklink = Stacklink(
+    api_key=os.environ['STACKLINK_API_KEY'],
+    base_url=os.getenv('STACKLINK_BASE_URL', 'https://api.stacklink.in'),
+)
+session = stacklink.sessions.create_bound({
+    'externalTenantId': 'acme',
+    'externalUserId': 'user_123',
+    'modelSurface': {'mode': 'router'},
+})
+
+try:
+    # Pass the selected Stacklink adapter output to your agent harness.
+    pass
+finally:
+    session.close()
+```
+
+The complete OpenAI Agents and Claude Agent examples shown by the Stacklink Overview are generated from the executable files under `examples/sdk/`. The dashboard, documentation, and certification tests all read those same files.
+
+The raw OpenAI `with_stacklink_memory` helper remains a separate Memory integration. It is not the agent-tool integration and is not part of basic Overview onboarding.
+
+Environment variables are `STACKLINK_API_KEY`, optional `STACKLINK_BASE_URL`, and the model-provider credentials required by the selected harness. The SDK is proprietary and is provided under the applicable Stacklink agreement.
+
+## Accepted operations, approvals and retries
+
+An execution response can be pending. Keep its `executionKind`, `executionId`, session ID and retry key in your application. Read or wait for that operation using the existing execution APIs. A lost connection does not submit a second action, and closing the application session can remove the authority required to execute pending work.
+
+Retry keys are case-sensitive and accept up to 240 characters. Tool and batch requests have separate key namespaces. Reuse a key only for the exact same request in the same SDK session. Changed inputs return `409 idempotency_key_reused`; an expired stored result returns `410 execution_result_expired`. Neither response authorizes submitting the write again.
+
+For `waiting_for_approval`, read the shared request using `client.approvals` and `platform_approvals:read`. A decision also needs `platform_approvals:manage` and the authority required by that request. A server key alone cannot approve on behalf of a company person; eligible customer confirmation uses the verified session and its scoped grant. Keep the API key on your backend. A pending action must not be labelled completed. `provider_execution_result_unknown` means an external write may have happened; inspect the provider before considering another action.
+
+Use execution cancellation for an explicit Stop request. Losing a stream only stops observation. Vercel and LangChain adapters forward their supported abort signal; other adapters keep the structured operation identity available for explicit cancellation. MCP progress reports actual stages, not invented percentages.
+
+Streaming has a total observation deadline and a separate inactivity timeout. A timeout raises `sdk_stream_timeout` without repeating the action; use its original operation ID to resume observation. Stream responses are limited to 8 MiB, including JSON responses to streaming requests. The synchronous client keeps blocking reads in a bounded reader and releases the response when that read finishes or reaches its inactivity timeout. Custom transports must honor the timeout passed to them. MCP calls return once all matching responses arrive, even if the server keeps the stream open.
+
+## Hosted Bots (0.3.2)
+
+Bots are saved, published agents with project-scoped configuration and durable runs. Use a server-held project API key with `bots:manage` to create/update/publish, and `bots:run` to invoke. Supply a session established from your authenticated customer; input variables do not grant identity or access. Both SDKs expose run status, replayable events, cancellation and callback delivery recovery. A callback failure does not rerun the model.
+
+```python
+bot = stacklink.bots.get(bot_id)
+run = stacklink.bots.run(bot_id, session_id=session.id, message="Where is my order?", variables={"orderNumber": "4821"})
+for event in stacklink.bots.stream(bot_id, run["id"]):
+    print(event)
+result = stacklink.bots.get_run(bot_id, run["id"])
+print(result["output"] or result["finalText"])
+```
+
+The async client provides the same operations with `await` and `async for`.
+
+Reuse the returned `conversationId` for the next message. Preserve the last event sequence to resume observation. Published invocations are available through the existing session MCP endpoint using `STACKLINK_BOTS`; no separate server per bot is needed.
+
+## Shared approvals (0.3.3)
+
+`client.approvals` lists and retrieves approvals for an authorized session, submits a permitted decision or customer correction, and observes reconnectable approval events. A project key represents an application; it cannot substitute for a required human company approver. `as_customer=True` derives the customer from the authenticated session and still requires a scoped customer grant. Continue observing the original execution after deciding; do not resubmit the action.
+
+All enabled notification channels use the same stored request. Decision, notification delivery and execution have separate states. See the [approval guide](https://docs.stacklink.in/docs/reference/sdk-python#shared-approvals) for request and lifecycle details.
+
+When project settings require Workbench code approval, a foreground code/bash call returns `waiting_for_approval`, `approvalRequestId`, and its original execution ID immediately. No runtime sandbox is allocated for that wait. After the authorized person decides, observe the original execution; do not submit the code again.
+
+Server-side customer grant management (0.3.5): `get_customer_grant`, `save_customer_grant`, and `remove_customer_grant` operate on an authenticated customer session. Save exact tool keys and resource restrictions with the returned settings revision. The server supplies identity from the session; callers cannot choose another customer in the request body. These methods never grant company approval or bypass connected-account access.

stacklink_sdk-0.3.10/README.md

@@ -0,0 +1,118 @@
+# Stacklink Python SDK
+
+## X Chat bot keys
+
+Install `stacklink-sdk[x-chat]` for the official native Chat XDK. Import
+`create_x_bot_chat`, `restore_x_bot_chat` and `XBotChatKeyState` from
+`stacklink.x_chat`. This optional module runs on your bot infrastructure and makes
+no network requests. Personal X Chat remains in the browser SDK; do not pass a
+person's PIN or private keys to this module or to Stacklink's backend.
+
+Call `create_x_bot_chat(account_id, bot_user_id, persist)` once. The `persist`
+callback must store the opaque key state in your secret manager, replacing the
+value for that exact account and bot before returning. Submit the returned
+`registration` public-key payload through X's bot bearer-token API. Fetch the
+registered public-key record, add its exact `user_id`, and call
+`bind_registered_identity(record)`. The helper checks both public keys and their
+binding before exposing `crypto`, the official native XDK for messages, groups,
+reactions, history and encrypted media. Close the session after use.
+
+On restart, call `restore_x_bot_chat(account_id, bot_user_id, stored_state,
+current_public_record, persist)`. Account, bot, key version and both keys must
+match. An uncertain registration must be reconciled using X's current public
+record; do not generate replacement keys automatically. Keep the bot bearer
+token retrieved by `x.getStoredBotToken` in the same customer-owned secret
+manager, separately from its private key blob. Bot bearer tokens are separate
+from a person's OAuth2 grant. This helper supplies local cryptography; it does
+not turn a person's Stacklink connection into a bot connection.
+
+Stacklink supplies executable, governed tools to an agent harness. The selected harness owns the model call, tool loop, and final answer.
+
+Install the public package with the harness extra you use:
+
+```bash
+uv add 'stacklink-sdk[openai-agents]'
+```
+
+or:
+
+```bash
+uv add 'stacklink-sdk[claude-agent]'
+```
+
+The complete guides and certified recipes live at [docs.stacklink.in](https://docs.stacklink.in/docs/quickstart). PyPI is the package delivery system, not the primary documentation surface. Stacklink does not display registry download badges in its product or documentation.
+
+## Certified agent harnesses
+
+| Harness | Stacklink adapter |
+|---|---|
+| OpenAI Agents SDK | `create_stacklink_openai_agents_tools(session)` |
+| Claude Agent SDK | `create_stacklink_claude_agent_tool_config(session)` |
+
+Both start with one explicit Stacklink session:
+
+```python
+import os
+from stacklink import Stacklink
+
+stacklink = Stacklink(
+    api_key=os.environ['STACKLINK_API_KEY'],
+    base_url=os.getenv('STACKLINK_BASE_URL', 'https://api.stacklink.in'),
+)
+session = stacklink.sessions.create_bound({
+    'externalTenantId': 'acme',
+    'externalUserId': 'user_123',
+    'modelSurface': {'mode': 'router'},
+})
+
+try:
+    # Pass the selected Stacklink adapter output to your agent harness.
+    pass
+finally:
+    session.close()
+```
+
+The complete OpenAI Agents and Claude Agent examples shown by the Stacklink Overview are generated from the executable files under `examples/sdk/`. The dashboard, documentation, and certification tests all read those same files.
+
+The raw OpenAI `with_stacklink_memory` helper remains a separate Memory integration. It is not the agent-tool integration and is not part of basic Overview onboarding.
+
+Environment variables are `STACKLINK_API_KEY`, optional `STACKLINK_BASE_URL`, and the model-provider credentials required by the selected harness. The SDK is proprietary and is provided under the applicable Stacklink agreement.
+
+## Accepted operations, approvals and retries
+
+An execution response can be pending. Keep its `executionKind`, `executionId`, session ID and retry key in your application. Read or wait for that operation using the existing execution APIs. A lost connection does not submit a second action, and closing the application session can remove the authority required to execute pending work.
+
+Retry keys are case-sensitive and accept up to 240 characters. Tool and batch requests have separate key namespaces. Reuse a key only for the exact same request in the same SDK session. Changed inputs return `409 idempotency_key_reused`; an expired stored result returns `410 execution_result_expired`. Neither response authorizes submitting the write again.
+
+For `waiting_for_approval`, read the shared request using `client.approvals` and `platform_approvals:read`. A decision also needs `platform_approvals:manage` and the authority required by that request. A server key alone cannot approve on behalf of a company person; eligible customer confirmation uses the verified session and its scoped grant. Keep the API key on your backend. A pending action must not be labelled completed. `provider_execution_result_unknown` means an external write may have happened; inspect the provider before considering another action.
+
+Use execution cancellation for an explicit Stop request. Losing a stream only stops observation. Vercel and LangChain adapters forward their supported abort signal; other adapters keep the structured operation identity available for explicit cancellation. MCP progress reports actual stages, not invented percentages.
+
+Streaming has a total observation deadline and a separate inactivity timeout. A timeout raises `sdk_stream_timeout` without repeating the action; use its original operation ID to resume observation. Stream responses are limited to 8 MiB, including JSON responses to streaming requests. The synchronous client keeps blocking reads in a bounded reader and releases the response when that read finishes or reaches its inactivity timeout. Custom transports must honor the timeout passed to them. MCP calls return once all matching responses arrive, even if the server keeps the stream open.
+
+## Hosted Bots (0.3.2)
+
+Bots are saved, published agents with project-scoped configuration and durable runs. Use a server-held project API key with `bots:manage` to create/update/publish, and `bots:run` to invoke. Supply a session established from your authenticated customer; input variables do not grant identity or access. Both SDKs expose run status, replayable events, cancellation and callback delivery recovery. A callback failure does not rerun the model.
+
+```python
+bot = stacklink.bots.get(bot_id)
+run = stacklink.bots.run(bot_id, session_id=session.id, message="Where is my order?", variables={"orderNumber": "4821"})
+for event in stacklink.bots.stream(bot_id, run["id"]):
+    print(event)
+result = stacklink.bots.get_run(bot_id, run["id"])
+print(result["output"] or result["finalText"])
+```
+
+The async client provides the same operations with `await` and `async for`.
+
+Reuse the returned `conversationId` for the next message. Preserve the last event sequence to resume observation. Published invocations are available through the existing session MCP endpoint using `STACKLINK_BOTS`; no separate server per bot is needed.
+
+## Shared approvals (0.3.3)
+
+`client.approvals` lists and retrieves approvals for an authorized session, submits a permitted decision or customer correction, and observes reconnectable approval events. A project key represents an application; it cannot substitute for a required human company approver. `as_customer=True` derives the customer from the authenticated session and still requires a scoped customer grant. Continue observing the original execution after deciding; do not resubmit the action.
+
+All enabled notification channels use the same stored request. Decision, notification delivery and execution have separate states. See the [approval guide](https://docs.stacklink.in/docs/reference/sdk-python#shared-approvals) for request and lifecycle details.
+
+When project settings require Workbench code approval, a foreground code/bash call returns `waiting_for_approval`, `approvalRequestId`, and its original execution ID immediately. No runtime sandbox is allocated for that wait. After the authorized person decides, observe the original execution; do not submit the code again.
+
+Server-side customer grant management (0.3.5): `get_customer_grant`, `save_customer_grant`, and `remove_customer_grant` operate on an authenticated customer session. Save exact tool keys and resource restrictions with the returned settings revision. The server supplies identity from the session; callers cannot choose another customer in the request body. These methods never grant company approval or bypass connected-account access.

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

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "stacklink-sdk"
-version = "0.2.2"
+version = "0.3.10"
 description = "Python SDK for Stacklink sessions, tools, MCP, auth, workbench, logs, knowledge, and billing."
 readme = "README.md"
 license = "LicenseRef-Proprietary"
@@ -17,6 +17,7 @@ dependencies = ["httpx[http2]>=0.27,<1"]
 Documentation = "https://docs.stacklink.in/docs/quickstart"
 
 [project.optional-dependencies]
+x-chat = ["chatxdk==0.5.0"]
 openai = ["openai>=2.0,<3"]
 openai-agents = ["openai-agents>=0.18,<0.19"]
 claude-agent = ["claude-agent-sdk>=0.2,<0.3"]

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

@@ -1,5 +1,8 @@
 from __future__ import annotations
 
+from .bots import verify_bot_api_request, sign_bot_trigger_request
+from .approvals import ApprovalDecision, ApprovalRecord, ApprovalEvent, ApprovalPermissions, CustomerApprovalGrantInput
+from .webhooks import verify_webhook_signature
 from .client import AsyncStacklink, STACKLINK_PYTHON_SDK_VERSION, Stacklink
 from .claude_agent import create_stacklink_claude_agent_tool_config
 from .errors import RateLimitError, StacklinkError
@@ -24,7 +27,12 @@ from .types import (
 )
 
 __all__ = [
+    "ApprovalDecision", "ApprovalRecord", "ApprovalEvent", "ApprovalPermissions",
+    "CustomerApprovalGrantInput",
     "Stacklink",
+    "verify_bot_api_request",
+    "sign_bot_trigger_request",
+    "verify_webhook_signature",
     "AsyncStacklink",
     "STACKLINK_PYTHON_SDK_VERSION",
     "StacklinkError",

stacklink_sdk-0.3.10/stacklink/approvals.py

@@ -0,0 +1,118 @@
+"""Shared approvals. Decisions apply to the stored action; never submit that action again."""
+from __future__ import annotations
+
+import asyncio
+import time
+from typing import Any, Literal, TypedDict, Iterator, AsyncIterator
+from urllib.parse import quote
+
+
+class ApprovalDecision(TypedDict):
+    requirement: Literal['customer', 'company']
+    decision: Literal['approve', 'decline']
+    expectedRevision: int
+
+
+class CustomerApprovalGrantInput(TypedDict):
+    revision: int
+    name: str
+    toolKeys: list[str]
+    accountIds: list[str]
+    resources: list[dict[str, str | int | float | bool]]
+
+
+class ApprovalPermissions(TypedDict):
+    canDecide: bool
+    canManage: bool
+    requirement: Literal['customer', 'company'] | None
+    reason: str | None
+
+
+class ApprovalRecord(TypedDict):
+    id: str
+    projectId: str
+    sessionId: str | None
+    revision: int
+    status: Literal['pending', 'approved', 'applying', 'applied', 'apply_failed', 'denied', 'cancelled', 'expired']
+    audience: Literal['approvers', 'customer', 'customer-approvers']
+    requirements: list[dict[str, Any]]
+    permissions: ApprovalPermissions
+    execution: dict[str, Any]
+    deliveries: list[dict[str, Any]]
+
+
+class ApprovalEvent(TypedDict):
+    sequence: str
+    approvalId: str
+    type: Literal['approval.request.updated']
+    data: dict[str, Any]
+    occurredAt: str
+
+
+class ApprovalsResource:
+    def __init__(self, client, *, async_mode: bool = False):
+        self.client = client
+        self.async_mode = async_mode
+
+    def get_customer_grant(self, *, session_id: str):
+        """Server-only: identity is resolved from this authenticated customer session."""
+        return self.client.request('GET', '/v1/approvals/customer-grant', query={'sessionId': session_id})
+
+    def save_customer_grant(self, grant: CustomerApprovalGrantInput, *, session_id: str):
+        return self.client.request('PUT', '/v1/approvals/customer-grant', query={'sessionId': session_id}, json_body=grant)
+
+    def remove_customer_grant(self, *, session_id: str, revision: int):
+        return self.client.request('DELETE', '/v1/approvals/customer-grant', query={'sessionId': session_id}, json_body={'revision': revision})
+
+    @staticmethod
+    def _query(session_id: str, as_customer: bool) -> dict[str, Any]:
+        return {'sessionId': session_id, 'asCustomer': 'true' if as_customer else 'false'}
+
+    def list(self, *, session_id: str, as_customer: bool = False, **filters):
+        return self.client.request('GET', '/v1/approvals', query={**filters, **self._query(session_id, as_customer)})
+
+    def get(self, approval_id: str, *, session_id: str, as_customer: bool = False):
+        return self.client.request('GET', '/v1/approvals/' + quote(approval_id, safe=''), query=self._query(session_id, as_customer))
+
+    def decide(self, approval_id: str, decision: ApprovalDecision, *, session_id: str, as_customer: bool = False, reason: str | None = None):
+        """Call only after a current authorized person confirms the displayed exact proposal."""
+        body = dict(decision)
+        if reason is not None:
+            body['reason'] = reason
+        return self.client.request('POST', '/v1/approvals/' + quote(approval_id, safe='') + '/decide', query=self._query(session_id, as_customer), json_body=body)
+
+    def change(self, approval_id: str, *, session_id: str, expected_revision: int, message: str, as_customer: bool = False):
+        return self.client.request('POST', '/v1/approvals/' + quote(approval_id, safe='') + '/change', query=self._query(session_id, as_customer), json_body={'expectedRevision': expected_revision, 'message': message})
+
+    def events(self, *, session_id: str, after: str = '0', as_customer: bool = False, timeout_ms: int = 15_000):
+        return self.client.request('GET', '/v1/approvals/events', query={**self._query(session_id, as_customer), 'after': after}, timeout_ms=timeout_ms)
+
+    def observe(self, *, session_id: str, after: str = '0', as_customer: bool = False, timeout_ms: int = 300_000) -> Iterator[ApprovalEvent] | AsyncIterator[ApprovalEvent]:
+        """Save each sequence and pass it back as after when reconnecting. Close the iterator to stop."""
+        if self.async_mode:
+            return self._observe_async(session_id, after, as_customer, timeout_ms)
+        return self._observe_sync(session_id, after, as_customer, timeout_ms)
+
+    def _observe_sync(self, session_id: str, cursor: str, as_customer: bool, timeout_ms: int) -> Iterator[ApprovalEvent]:
+        deadline = time.monotonic() + timeout_ms / 1000
+        while time.monotonic() < deadline:
+            page = self.events(session_id=session_id, after=cursor, as_customer=as_customer, timeout_ms=max(1, min(15_000, int((deadline - time.monotonic()) * 1000))))
+            for event in page['events']:
+                if int(event['sequence']) <= int(cursor):
+                    continue
+                cursor = event['sequence']
+                yield event
+            if len(page['events']) < 100:
+                time.sleep(max(0, min(1, deadline - time.monotonic())))
+
+    async def _observe_async(self, session_id: str, cursor: str, as_customer: bool, timeout_ms: int) -> AsyncIterator[ApprovalEvent]:
+        deadline = time.monotonic() + timeout_ms / 1000
+        while time.monotonic() < deadline:
+            page = await self.events(session_id=session_id, after=cursor, as_customer=as_customer, timeout_ms=max(1, min(15_000, int((deadline - time.monotonic()) * 1000))))
+            for event in page['events']:
+                if int(event['sequence']) <= int(cursor):
+                    continue
+                cursor = event['sequence']
+                yield event
+            if len(page['events']) < 100:
+                await asyncio.sleep(max(0, min(1, deadline - time.monotonic())))