stacklink-sdk 0.4.0__tar.gz → 0.6.2__tar.gz

{stacklink_sdk-0.4.0/stacklink_sdk.egg-info → stacklink_sdk-0.6.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: stacklink-sdk
-Version: 0.4.0
+Version: 0.6.2
 Summary: Python SDK for Stacklink sessions, tools, MCP, auth, workbench, logs, knowledge, and billing.
 Author: Stacklink
 License-Expression: LicenseRef-Proprietary
@@ -128,6 +128,33 @@ 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.
 
+## Workflows (0.6.2)
+
+Use `https://api.stacklink.in` for production.
+Workflow trigger changes now follow draft → publish. `workflows.triggers(id)`
+returns the draft `revision`, draft `triggers`, and active `liveTriggers`.
+Pass the required `expected_revision` keyword to `save_trigger` or
+`delete_trigger`, then publish the returned revision to apply the change.
+A stale revision returns 409; saving a trigger no longer activates it immediately.
+The async client uses the same lifecycle.
+
+Bot steps, child workflows, For each and Bot attachments accept `"live"` in place
+of a numeric revision/version. New runs resolve live references once and retain
+that setup through waits, retries and every item. Existing numeric pins remain
+supported. Pausing blocks new starts; publishing does not resume a paused workflow.
+The [Workflows guide](https://docs.stacklink.in/docs/workflows) covers definitions,
+permissions, stable job keys and recovery.
+
+Your Python backend can issue customer editor access through
+`workflows.issue_embedded_access(customer_id=..., user_id=..., origin=..., role=...)`.
+Derive those values from your authenticated application session. Mount the hosted
+editor in the frontend with the separate `@stacklink/workflow-builder` JavaScript
+package; never expose the project key. `with_embedded_access(project_id, access_token)`
+provides person-scoped lists, approvals and analytics. `for_customer(customer_id)`
+is for trusted backend administration. The async client supports the same methods.
+See the [embedded guide](https://docs.stacklink.in/docs/workflows#embed-the-builder-in-your-application)
+for the complete lifecycle.
+
 ## 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.

{stacklink_sdk-0.4.0 → stacklink_sdk-0.6.2}/README.md

@@ -107,6 +107,33 @@ 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.
 
+## Workflows (0.6.2)
+
+Use `https://api.stacklink.in` for production.
+Workflow trigger changes now follow draft → publish. `workflows.triggers(id)`
+returns the draft `revision`, draft `triggers`, and active `liveTriggers`.
+Pass the required `expected_revision` keyword to `save_trigger` or
+`delete_trigger`, then publish the returned revision to apply the change.
+A stale revision returns 409; saving a trigger no longer activates it immediately.
+The async client uses the same lifecycle.
+
+Bot steps, child workflows, For each and Bot attachments accept `"live"` in place
+of a numeric revision/version. New runs resolve live references once and retain
+that setup through waits, retries and every item. Existing numeric pins remain
+supported. Pausing blocks new starts; publishing does not resume a paused workflow.
+The [Workflows guide](https://docs.stacklink.in/docs/workflows) covers definitions,
+permissions, stable job keys and recovery.
+
+Your Python backend can issue customer editor access through
+`workflows.issue_embedded_access(customer_id=..., user_id=..., origin=..., role=...)`.
+Derive those values from your authenticated application session. Mount the hosted
+editor in the frontend with the separate `@stacklink/workflow-builder` JavaScript
+package; never expose the project key. `with_embedded_access(project_id, access_token)`
+provides person-scoped lists, approvals and analytics. `for_customer(customer_id)`
+is for trusted backend administration. The async client supports the same methods.
+See the [embedded guide](https://docs.stacklink.in/docs/workflows#embed-the-builder-in-your-application)
+for the complete lifecycle.
+
 ## 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.

{stacklink_sdk-0.4.0 → stacklink_sdk-0.6.2}/pyproject.toml

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

{stacklink_sdk-0.4.0 → stacklink_sdk-0.6.2}/stacklink/bots.py

@@ -238,8 +238,8 @@ class BotsResource:
     def retry_delivery(self, bot_id: str, run_id: str, delivery_id: str):
         return self.client.request("POST", self._path(bot_id, run_id) + "/deliveries/retry", json_body={"deliveryId": delivery_id})
 
-    def list(self):
-        return self.client.request("GET", "/v1/bots")
+    def list(self, *, cursor: str | None = None, search: str | None = None, limit: int = 200):
+        return self.client.request("GET", "/v1/bots", query={"limit": limit, **({"cursor": cursor} if cursor else {}), **({"search": search} if search else {})})
 
     def delete(self, bot_id: str):
         return self.client.request("DELETE", self._path(bot_id))
@@ -275,6 +275,10 @@ class BotsResource:
     def get_run(self, bot_id: str, run_id: str):
         return self.client.request("GET", self._path(bot_id, run_id))
 
+    def continue_run(self, bot_id: str, run_id: str):
+        """Continue the same saved funding pause after its funding is resolved."""
+        return self.client.request("POST", self._path(bot_id, run_id) + "/continue", json_body={})
+
     def wait(self, bot_id: str, run_id: str, *, total_timeout_ms: int = 300_000):
         """Return the finished run, or a run waiting for a person's approval or connection."""
         if total_timeout_ms <= 0:
@@ -285,7 +289,7 @@ class BotsResource:
         deadline = time.monotonic() + total_timeout_ms / 1000
         while time.monotonic() < deadline:
             run = self.get_run(bot_id, run_id)
-            if run["status"] in ("completed", "failed", "stopped", "cancelled", "waiting_for_approval", "waiting_for_connection"):
+            if run["status"] in ("completed", "failed", "stopped", "cancelled", "waiting_for_approval", "waiting_for_connection") or (run.get("waitingOperation") or {}).get("kind") == "funding":
                 return run
             time.sleep(min(1, max(0, deadline - time.monotonic())))
         raise StacklinkError("Bot observation timed out. Continue observing the same run.", status_code=408, code="sdk_run_timeout", details={"botId": bot_id, "runId": run_id})
@@ -294,7 +298,7 @@ class BotsResource:
         deadline = time.monotonic() + total_timeout_ms / 1000
         while time.monotonic() < deadline:
             run = await self.get_run(bot_id, run_id)
-            if run["status"] in ("completed", "failed", "stopped", "cancelled", "waiting_for_approval", "waiting_for_connection"):
+            if run["status"] in ("completed", "failed", "stopped", "cancelled", "waiting_for_approval", "waiting_for_connection") or (run.get("waitingOperation") or {}).get("kind") == "funding":
                 return run
             await asyncio.sleep(min(1, max(0, deadline - time.monotonic())))
         raise StacklinkError("Bot observation timed out. Continue observing the same run.", status_code=408, code="sdk_run_timeout", details={"botId": bot_id, "runId": run_id})

{stacklink_sdk-0.4.0 → stacklink_sdk-0.6.2}/stacklink/client.py

@@ -20,6 +20,7 @@ from .artifacts import ArtifactsResource
 from .auth_configs import AuthConfigsResource
 from .billing import BillingResource
 from .bots import BotsResource
+from .workflows import WorkflowsResource
 from .approvals import ApprovalsResource
 from .connected_accounts import ConnectedAccountsResource
 from .errors import RateLimitError, StacklinkError
@@ -37,7 +38,7 @@ from .types import Json, Transport
 from .webhooks import WebhooksResource
 from .workbench import WorkbenchResource
 
-STACKLINK_PYTHON_SDK_VERSION = "0.4.0"
+STACKLINK_PYTHON_SDK_VERSION = "0.6.2"
 STACKLINK_PYTHON_USER_AGENT = f"stacklink-python/{STACKLINK_PYTHON_SDK_VERSION}"
 
 
@@ -54,6 +55,7 @@ class Stacklink:
         max_attempts: int = 3,
         http_client: httpx.Client | None = None,
     ):
+        self.workflows = WorkflowsResource(self)
         self.bots = BotsResource(self)
         self.approvals = ApprovalsResource(self)
         self.api_key = api_key or os.getenv("STACKLINK_API_KEY")
@@ -419,6 +421,7 @@ class AsyncStacklink:
         max_attempts: int = 3,
         http_client: httpx.AsyncClient | None = None,
     ):
+        self.workflows = WorkflowsResource(self)
         self.bots = BotsResource(self, async_mode=True)
         self.approvals = ApprovalsResource(self, async_mode=True)
         self.api_key = api_key or os.getenv("STACKLINK_API_KEY")

{stacklink_sdk-0.4.0 → stacklink_sdk-0.6.2}/stacklink/sessions.py

@@ -134,8 +134,8 @@ class Session:
     def get_contracts(self, contract_refs: list[str]):
         return self.client.sessions.get_contracts(self.id, contract_refs)
 
-    def authorize(self, connection_ref: str, *, metadata: dict[str, Any] | None = None):
-        return self.client.sessions.authorize(self.id, connection_ref, metadata=metadata)
+    def authorize(self, connection_ref: str, *, metadata: dict[str, Any] | None = None, amazon_seller_region: str | None = None):
+        return self.client.sessions.authorize(self.id, connection_ref, metadata=metadata, amazon_seller_region=amazon_seller_region)
 
     def execute(
         self,
@@ -256,12 +256,16 @@ class SessionsResource:
         connection_ref: str,
         *,
         metadata: dict[str, Any] | None = None,
+        amazon_seller_region: str | None = None,
     ):
+        if amazon_seller_region is not None and amazon_seller_region not in ("NA", "EU", "FE"):
+            raise ValueError("amazon_seller_region must be NA, EU or FE")
         return self.client.request(
             "POST",
             f"/v1/sessions/{session_id}/connections/authorize",
             json_body={
                 "connectionRef": connection_ref,
+                **({"amazonSellerRegion": amazon_seller_region} if amazon_seller_region is not None else {}),
                 "metadata": dict(metadata or {}),
             },
         )

{stacklink_sdk-0.4.0 → stacklink_sdk-0.6.2}/stacklink/workbench.py

@@ -549,10 +549,15 @@ class WorkbenchExecutionResponse(TypedDict, total=False):
     artifact: WorkbenchArtifact
 
 
+def _execution_session_id(response: Mapping[str, Any], fallback: str | None) -> str | None:
+    workspace = response.get("workbenchSession")
+    return workspace["platformSessionId"] if isinstance(workspace, dict) and isinstance(workspace.get("platformSessionId"), str) else fallback
+
+
 class WorkbenchRun:
     def __init__(self, client, platform_session_id: str, response: WorkbenchExecutionResponse):
         self.client = client
-        self.platform_session_id = platform_session_id
+        self.platform_session_id = _execution_session_id(response, platform_session_id)
         self.response = response
         self.execution_id = str(response["executionId"])
         self.execution_kind = str(response["executionKind"])
@@ -651,7 +656,7 @@ def _wait_for_workbench_response(
     request: Mapping[str, Any],
     accepted: WorkbenchExecutionResponse,
 ) -> WorkbenchExecutionResponse:
-    session_id = request.get("sessionId")
+    session_id = _execution_session_id(accepted, request.get("sessionId"))
     execution_id = accepted.get("executionId")
     execution_kind = accepted.get("executionKind")
     if (
@@ -1140,10 +1145,11 @@ class SessionSandbox:
             "workbenchSessionId": body.get("workbenchSessionId") or self.ensure_session_id(),
             "operation": "run_code",
         }
-        response: WorkbenchExecutionResponse = self.client.request("POST", "/v1/workbench/run", json_body=request)
+        response: WorkbenchExecutionResponse = self.client.request("POST", "/v1/workbench/run", json_body=request, idempotency_key=request.get("idempotencyKey"))
         if body.get("background") is not True:
             response = _wait_for_workbench_response(self.client, request, response)
-        self.workbench_session_id = str(response["workbenchSession"]["id"])
+        if _execution_session_id(response, self.platform_session_id) == self.platform_session_id:
+            self.workbench_session_id = str(response["workbenchSession"]["id"])
         return WorkbenchRun(self.client, self.platform_session_id, response)
 
     def bash(self, body: WorkbenchBashInput) -> WorkbenchRun:
@@ -1152,10 +1158,11 @@ class SessionSandbox:
             "sessionId": self.platform_session_id,
             "workbenchSessionId": body.get("workbenchSessionId") or self.ensure_session_id(),
         }
-        response: WorkbenchExecutionResponse = self.client.request("POST", "/v1/workbench/bash", json_body=request)
+        response: WorkbenchExecutionResponse = self.client.request("POST", "/v1/workbench/bash", json_body=request, idempotency_key=request.get("idempotencyKey"))
         if body.get("background") is not True:
             response = _wait_for_workbench_response(self.client, request, response)
-        self.workbench_session_id = str(response["workbenchSession"]["id"])
+        if _execution_session_id(response, self.platform_session_id) == self.platform_session_id:
+            self.workbench_session_id = str(response["workbenchSession"]["id"])
         return WorkbenchRun(self.client, self.platform_session_id, response)
 
     def destroy(self) -> WorkbenchSessionDestroyResponse:
@@ -1184,7 +1191,7 @@ class WorkbenchResource:
         return self.client.request("GET", "/v1/workbench/models")
 
     def run(self, body: dict[str, Any]):
-        response = cast(WorkbenchExecutionResponse, self.client.request("POST", "/v1/workbench/run", json_body=body))
+        response = cast(WorkbenchExecutionResponse, self.client.request("POST", "/v1/workbench/run", json_body=body, idempotency_key=body.get("idempotencyKey")))
         if isinstance(response.get("operation"), dict):
             operation = response["operation"]
             completed = self.wait_operation(body["sessionId"], operation["workbenchSessionId"], operation["operationId"])
@@ -1194,7 +1201,7 @@ class WorkbenchResource:
         return response
 
     def bash(self, body: dict[str, Any]):
-        response = cast(WorkbenchExecutionResponse, self.client.request("POST", "/v1/workbench/bash", json_body=body))
+        response = cast(WorkbenchExecutionResponse, self.client.request("POST", "/v1/workbench/bash", json_body=body, idempotency_key=body.get("idempotencyKey")))
         if body.get("background") is not True:
             return _wait_for_workbench_response(self.client, body, response)
         return response

stacklink_sdk-0.6.2/stacklink/workflows.py

@@ -0,0 +1,129 @@
+"""Durable workflow definitions and runs. Reuse job_key after a timeout."""
+from typing import Any
+from urllib.parse import quote
+
+
+class WorkflowsResource:
+    def __init__(self, client, *, customer_id=None, project_id=None, access_token=None):
+        self.client = client
+        self.customer_id = customer_id
+        self.project_id = project_id
+        self.access_token = access_token
+
+    def for_customer(self, customer_id: str):
+        return WorkflowsResource(self.client, customer_id=customer_id)
+
+    def with_embedded_access(self, project_id: str, access_token: str):
+        return WorkflowsResource(self.client, project_id=project_id, access_token=access_token)
+
+    def _request(self, method, path, **options):
+        headers = dict(options.pop('headers', {}) or {})
+        if self.customer_id:
+            headers['X-Stacklink-Customer'] = self.customer_id
+        if self.access_token:
+            headers['authorization'] = 'Bearer ' + self.access_token
+        return self.client.request(method, path, headers=headers, **options)
+
+    def _path(self, workflow_id: str | None = None) -> str:
+        return ('/embedded/api/projects/' + quote(self.project_id, safe='') + '/workflows' if self.project_id else '/v1/workflows') + ('/' + quote(workflow_id, safe='') if workflow_id else '')
+
+    def list(self, *, cursor: str | None = None, search: str | None = None, limit: int = 200):
+        return self._request('GET', self._path(), query={'limit': limit, **({'cursor': cursor} if cursor else {}), **({'search': search} if search else {})})
+
+    def create(self, name: str, definition: dict[str, Any], *, source: str = 'code', description: str = '', deployment: dict[str, str] | None = None):
+        return self._request('POST', self._path(), json_body={'name': name, 'definition': definition, 'source': source, 'description': description, **({'deployment': deployment} if deployment is not None else {})})
+
+    def get(self, workflow_id: str):
+        return self._request('GET', self._path(workflow_id))
+
+    def update(self, workflow_id: str, revision: int, **changes):
+        return self._request('PATCH', self._path(workflow_id), json_body={**changes, 'revision': revision})
+
+    def validate(self, definition: dict[str, Any]):
+        return self._request('POST', self._path() + '/validate', json_body={'definition': definition})
+
+    def publish(self, workflow_id: str, revision: int):
+        return self._request('POST', self._path(workflow_id) + '/publish', json_body={'revision': revision})
+
+    def set_state(self, workflow_id: str, paused: bool):
+        return self._request('POST', self._path(workflow_id) + '/state', json_body={'paused': paused})
+
+    def versions(self, workflow_id: str):
+        return self._request('GET', self._path(workflow_id) + '/versions')
+
+    def run(self, workflow_id: str, session_id: str, job_key: str, *, input: dict[str, Any] | None = None, **options):
+        return self._request('POST', self._path(workflow_id) + '/runs', json_body={**options, 'sessionId': session_id, 'jobKey': job_key, 'input': input or {}}, idempotency_key=job_key)
+
+    def runs(self, workflow_id: str, *, cursor: str | None = None, limit: int = 50):
+        return self._request('GET', self._path(workflow_id) + '/runs', query={'limit': limit, **({'cursor': cursor} if cursor else {})})
+
+    def get_run(self, workflow_id: str, run_id: str):
+        return self._request('GET', self._path(workflow_id) + '/runs/' + quote(run_id, safe=''))
+
+    def events(self, workflow_id: str, run_id: str, *, before: str | None = None, limit: int = 200):
+        return self._request('GET', self._path(workflow_id) + '/runs/' + quote(run_id, safe='') + '/events', query={'limit': limit, **({'before': before} if before else {})})
+
+    def action(self, workflow_id: str, run_id: str, action: str, **options):
+        return self._request('POST', self._path(workflow_id) + '/runs/' + quote(run_id, safe='') + '/actions', json_body={**options, 'action': action})
+
+    def triggers(self, workflow_id: str):
+        return self._request('GET', self._path(workflow_id) + '/triggers')
+
+    def save_trigger(self, workflow_id: str, configuration: dict[str, Any], *, expected_revision: int):
+        """Save a draft trigger. Publish the returned revision to activate it."""
+        return self._request('POST', self._path(workflow_id) + '/triggers', json_body={**configuration, 'expectedRevision': expected_revision})
+
+    def delete_trigger(self, workflow_id: str, trigger_id: str, *, expected_revision: int):
+        return self._request('DELETE', self._path(workflow_id) + '/triggers/' + quote(trigger_id, safe=''), query={'expectedRevision': expected_revision})
+
+    def invoke_trigger(self, workflow_id: str, trigger_id: str, request_id: str, input: dict[str, Any]):
+        return self._request('POST', self._path(workflow_id) + '/triggers/' + quote(trigger_id, safe='') + '/invoke', json_body={'requestId': request_id, 'input': input}, idempotency_key=request_id)
+
+    def preview_schedule(self, cron: str, timezone: str = 'UTC'):
+        return self._request('POST', self._path() + '/schedule/preview', json_body={'cron': cron, 'timezone': timezone})
+
+    def suggest(self, workflow_id: str, description: str, revision: int, session_id: str):
+        return self._request('POST', self._path(workflow_id) + '/suggest', json_body={'description': description, 'revision': revision, 'sessionId': session_id}, timeout_ms=60_000)
+
+
+    def issue_embedded_access(self, customer_id: str, user_id: str, origin: str, role: str, *, decide_approvals: bool = False, view_usage: bool = False, workflow_id: str | None = None, customer_name: str | None = None, user_name: str | None = None):
+        return self.client.request('POST', '/v1/workflows/embed/access', json_body={
+            'customerId': customer_id, 'userId': user_id, 'origin': origin, 'role': role,
+            'decideApprovals': decide_approvals, 'viewUsage': view_usage,
+            **({'workflowId': workflow_id} if workflow_id else {}),
+            **({'customerName': customer_name} if customer_name else {}),
+            **({'userName': user_name} if user_name else {}),
+        })
+
+    def exchange_embedded_access(self, bootstrap_token: str, origin: str):
+        return self.client.request('POST', '/v1/workflows/embed/exchange', json_body={'bootstrapToken': bootstrap_token, 'origin': origin})
+
+    def embed_settings(self):
+        return self._request('GET', self._path() + '/embed')
+
+    def save_embed_settings(self, revision: int, config: dict):
+        return self._request('PUT', self._path() + '/embed', json_body={'revision': revision, 'config': config})
+
+    def customers(self, **query):
+        return self._request('GET', self._path() + '/embed/customers', query=query)
+
+    def customer(self, customer_id: str):
+        return self._request('GET', self._path() + '/embed/customers/' + quote(customer_id, safe=''))
+
+    def set_customer_automations(self, customer_id: str, enabled: bool):
+        return self._request('POST', self._path() + '/embed/customers/' + quote(customer_id, safe='') + '/automations', json_body={'enabled': enabled})
+
+    def set_customer_person_access(self, customer_id: str, person_id: str, action: str):
+        return self._request('POST', self._path() + '/embed/customers/' + quote(customer_id, safe='') + '/people/' + quote(person_id, safe='') + '/access', json_body={'action': action})
+
+    def analytics(self, *, days: int = 30, customer_id: str | None = None):
+        return self._request('GET', self._path() + '/analytics', query={'days': days, **({'customerId': customer_id} if customer_id else {})})
+
+    def activity(self, **query):
+        return self._request('GET', self._path() + '/activity', query=query)
+
+    def approvals(self, *, view: str = 'inbox', cursor: str | None = None, limit: int = 50):
+        return self._request('GET', self._path() + '/approvals', query={'view': view, 'limit': limit, **({'cursor': cursor} if cursor else {})})
+
+    def decide_approval(self, approval_id: str, decision: dict):
+        return self._request('POST', self._path() + '/approvals/' + quote(approval_id, safe='') + '/decide', json_body=decision)

{stacklink_sdk-0.4.0 → stacklink_sdk-0.6.2/stacklink_sdk.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: stacklink-sdk
-Version: 0.4.0
+Version: 0.6.2
 Summary: Python SDK for Stacklink sessions, tools, MCP, auth, workbench, logs, knowledge, and billing.
 Author: Stacklink
 License-Expression: LicenseRef-Proprietary
@@ -128,6 +128,33 @@ 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.
 
+## Workflows (0.6.2)
+
+Use `https://api.stacklink.in` for production.
+Workflow trigger changes now follow draft → publish. `workflows.triggers(id)`
+returns the draft `revision`, draft `triggers`, and active `liveTriggers`.
+Pass the required `expected_revision` keyword to `save_trigger` or
+`delete_trigger`, then publish the returned revision to apply the change.
+A stale revision returns 409; saving a trigger no longer activates it immediately.
+The async client uses the same lifecycle.
+
+Bot steps, child workflows, For each and Bot attachments accept `"live"` in place
+of a numeric revision/version. New runs resolve live references once and retain
+that setup through waits, retries and every item. Existing numeric pins remain
+supported. Pausing blocks new starts; publishing does not resume a paused workflow.
+The [Workflows guide](https://docs.stacklink.in/docs/workflows) covers definitions,
+permissions, stable job keys and recovery.
+
+Your Python backend can issue customer editor access through
+`workflows.issue_embedded_access(customer_id=..., user_id=..., origin=..., role=...)`.
+Derive those values from your authenticated application session. Mount the hosted
+editor in the frontend with the separate `@stacklink/workflow-builder` JavaScript
+package; never expose the project key. `with_embedded_access(project_id, access_token)`
+provides person-scoped lists, approvals and analytics. `for_customer(customer_id)`
+is for trusted backend administration. The async client supports the same methods.
+See the [embedded guide](https://docs.stacklink.in/docs/workflows#embed-the-builder-in-your-application)
+for the complete lifecycle.
+
 ## 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.

{stacklink_sdk-0.4.0 → stacklink_sdk-0.6.2}/stacklink_sdk.egg-info/SOURCES.txt

@@ -27,12 +27,14 @@ stacklink/triggers.py
 stacklink/types.py
 stacklink/webhooks.py
 stacklink/workbench.py
+stacklink/workflows.py
 stacklink/x_chat.py
 stacklink_sdk.egg-info/PKG-INFO
 stacklink_sdk.egg-info/SOURCES.txt
 stacklink_sdk.egg-info/dependency_links.txt
 stacklink_sdk.egg-info/requires.txt
 stacklink_sdk.egg-info/top_level.txt
+tests/test_amazon_seller_provider.py
 tests/test_client.py
 tests/test_google_docs_provider.py
 tests/test_google_drive_provider.py

stacklink_sdk-0.6.2/tests/test_amazon_seller_provider.py

@@ -0,0 +1,38 @@
+import unittest
+
+from stacklink import Stacklink
+
+
+class AmazonSellerClientTests(unittest.TestCase):
+    def test_authorization_uses_the_shared_session_route_and_exact_region(self):
+        calls = []
+
+        def transport(method, path, headers, body, query, timeout):
+            calls.append((method, path, body))
+            return 200, {}, {"authorization": {"providerKey": "amazon_seller", "status": "pending"}}
+
+        client = Stacklink(api_key="ppk_test", transport=transport)
+        client.sessions.authorize("session-owned", "opaque-ref", amazon_seller_region="EU")
+        self.assertEqual(calls, [("POST", "/v1/sessions/session-owned/connections/authorize", {
+            "connectionRef": "opaque-ref", "amazonSellerRegion": "EU", "metadata": {}
+        })])
+        with self.assertRaises(ValueError):
+            client.sessions.authorize("session-owned", "opaque-ref", amazon_seller_region="India")
+        self.assertEqual(len(calls), 1)
+
+    def test_execution_uses_existing_tool_route_without_provider_credentials(self):
+        calls = []
+
+        def transport(method, path, headers, body, query, timeout):
+            calls.append((method, path, body))
+            return 200, {}, {"status": "completed", "output": {"data": {"payload": []}}}
+
+        client = Stacklink(api_key="ppk_test", transport=transport)
+        payload = {"sessionId": "session-owned", "toolKey": "amazon_seller.seller.get_marketplace_participations", "input": {}}
+        result = client.tools.execute(payload)
+        self.assertEqual(result["status"], "completed")
+        self.assertEqual(calls, [("POST", "/v1/tools/execute", payload)])
+
+
+if __name__ == "__main__":
+    unittest.main()

{stacklink_sdk-0.4.0 → stacklink_sdk-0.6.2}/tests/test_client.py

@@ -63,6 +63,68 @@ def stalled_stream_server(*, final_result=False, execution_page=False):
 
 
 class StacklinkClientTests(unittest.TestCase):
+    def test_workflow_embedded_access_maps_delegated_permissions(self):
+        calls = []
+        def transport(method, path, headers, body, query, timeout):
+            calls.append((method, path, body))
+            return 200, {}, {"bootstrapToken": "one-use", "embedUrl": "https://staging.stacklink.in/embed/workflows/project"}
+        client = Stacklink(api_key="host-backend-key", transport=transport)
+        client.workflows.issue_embedded_access(
+            "fernhill", "maya", "https://acme.example", "viewer",
+            decide_approvals=True, view_usage=True, workflow_id="workflow-1",
+            customer_name="Fernhill", user_name="Maya",
+        )
+        self.assertEqual(calls, [("POST", "/v1/workflows/embed/access", {
+            "customerId": "fernhill", "userId": "maya", "origin": "https://acme.example", "role": "viewer",
+            "decideApprovals": True, "viewUsage": True, "workflowId": "workflow-1",
+            "customerName": "Fernhill", "userName": "Maya",
+        })])
+
+    def test_workflow_embedded_context_does_not_change_project_client(self):
+        calls = []
+        def transport(method, path, headers, body, query, timeout):
+            calls.append((path, dict(headers), body))
+            return 200, {}, {"workflows": [], "nextCursor": None}
+        client = Stacklink(api_key="host-backend-key", transport=transport)
+        a = client.workflows.for_customer("fernhill")
+        b = client.workflows.for_customer("larkspur")
+        a.list()
+        b.list()
+        client.workflows.list()
+        person = client.workflows.with_embedded_access("project-1", "sle_person")
+        person.approvals()
+        person.decide_approval("task-1", {"kind": "workflow", "value": "approved"})
+        self.assertEqual([row[1].get("X-Stacklink-Customer") for row in calls], ["fernhill", "larkspur", None, None, None])
+        self.assertEqual(calls[3][0], "/embedded/api/projects/project-1/workflows/approvals")
+        self.assertEqual({key.lower(): value for key, value in calls[3][1].items()}["authorization"], "Bearer sle_person")
+        self.assertEqual(calls[4][2], {"kind": "workflow", "value": "approved"})
+
+    def test_workflow_retry_and_trigger_use_stable_request_identity(self):
+        calls = []
+        def transport(method, path, headers, body, query, timeout):
+            calls.append((method, path, headers.get("Idempotency-Key"), body, query))
+            if len(calls) == 1:
+                return 503, {}, {"message": "Lost acknowledgement"}
+            return 200, {}, {"id": "same-run", "runs": [], "nextCursor": None}
+        client = Stacklink(api_key="ppk_test", transport=transport)
+        with patch("stacklink.client.time.sleep", return_value=None):
+            result = client.workflows.run("wf-1", "session-1", "upload-42", input={"recording": "चर्चा"})
+        self.assertEqual(result["id"], "same-run")
+        self.assertEqual(calls[0], calls[1])
+        self.assertEqual(calls[0][2], "upload-42")
+        client.workflows.runs("wf-1", cursor="run-1", limit=10)
+        self.assertEqual(calls[2][4], {"cursor": "run-1", "limit": 10})
+        client.workflows.invoke_trigger("wf-1", "trigger-1", "event-8", {"subject": "Ready"})
+        self.assertEqual(calls[3][1:4], ("/v1/workflows/wf-1/triggers/trigger-1/invoke", "event-8", {"requestId": "event-8", "input": {"subject": "Ready"}}))
+        client.workflows.suggest("wf-1", "Review findings", 3, "session-1")
+        self.assertEqual(calls[4][1], "/v1/workflows/wf-1/suggest")
+        self.assertEqual(calls[4][3], {"description": "Review findings", "revision": 3, "sessionId": "session-1"})
+        client.workflows.save_trigger("wf-1", {"kind": "webhook"}, expected_revision=3)
+        self.assertEqual(calls[5][3], {"kind": "webhook", "expectedRevision": 3})
+        client.workflows.delete_trigger("wf-1", "trigger-1", expected_revision=4)
+        self.assertEqual(calls[6][4], {"expectedRevision": 4})
+
+
     def test_workbench_lost_acknowledgement_keeps_upload_and_artifact_identity(self):
         bodies = []
         def transport(method, path, headers, body, query, timeout):
@@ -143,6 +205,48 @@ class StacklinkClientTests(unittest.TestCase):
         self.assertEqual(calls[2][2], {'revision': 2})
 
 
+    def test_workbench_replay_observes_the_original_session(self):
+        for operation in ("bash", "run_code"):
+            calls = []
+            kind = "workbench_bash" if operation == "bash" else "workbench_code"
+            def transport(method, path, headers, body, query, timeout):
+                calls.append((path, body))
+                if path in {"/v1/workbench/bash", "/v1/workbench/run"}:
+                    return 202, {}, {"executionId": "original-execution", "executionKind": kind, "status": "queued", "idempotency": {"replayed": True}, "workbenchSession": {"id": "workspace", "platformSessionId": "original-session"}}
+                self.assertEqual(body["sessionId"], "original-session")
+                return 200, {}, {"execution": {"id": "original-execution", "executionKind": kind, "status": "completed", "stdout": "saved result"}}
+            client = Stacklink(api_key="ppk_test", transport=transport)
+            payload = {"sessionId": "replacement-session", "idempotencyKey": "same-logical-job", "operation": operation, "command": "echo saved", "language": "python", "code": 'print("saved")'}
+            result = client.workbench.bash(payload) if operation == "bash" else client.workbench.run(payload)
+            self.assertEqual(result["status"], "completed")
+            self.assertEqual(len(calls), 2)
+            self.assertEqual(calls[0][1]["sessionId"], "replacement-session")
+
+    def test_replayed_run_keeps_the_replacement_sandbox_separate(self):
+        for operation in ("bash", "run_code"):
+            controls = []
+            def transport(method, path, headers, body, query, timeout):
+                if path.endswith("/files"):
+                    self.assertEqual(query["sessionId"], "replacement-session")
+                    self.assertEqual(path, "/v1/workbench/sessions/replacement-workspace/files")
+                    return 200, {}, {"files": []}
+                if path.startswith("/v1/executions/"):
+                    self.assertEqual(body["sessionId"], "original-session")
+                    controls.append(path)
+                    return 200, {}, {"execution": {"id": "original-execution", "status": "running"}}
+                if path == "/v1/workbench/sessions":
+                    return 200, {}, {"workbenchSession": {"id": "replacement-workspace", "platformSessionId": "replacement-session"}}
+                self.assertEqual(body["sessionId"], "replacement-session")
+                self.assertEqual(body["workbenchSessionId"], "replacement-workspace")
+                return 202, {}, {"executionId": "original-execution", "executionKind": "workbench_bash" if operation == "bash" else "workbench_code", "status": "running", "workbenchSession": {"id": "original-workspace", "platformSessionId": "original-session"}}
+            client = Stacklink(api_key="ppk_test", transport=transport)
+            sandbox = SessionSandbox(client, "replacement-session")
+            run = sandbox.bash({"command": "echo saved", "idempotencyKey": "same-work", "background": True}) if operation == "bash" else sandbox.run({"language": "python", "code": 'print("saved")', "idempotencyKey": "same-work", "background": True})
+            run.wait()
+            run.cancel("explicit cancellation")
+            sandbox.files.list()
+            self.assertEqual(len(controls), 2)
+
     def test_workbench_approval_returns_to_caller_before_decision(self):
         for operation in ("run_code", "bash"):
             for admission_status in ("waiting_for_approval", "queued"):