@stacklink/sdk 0.2.2 → 0.3.7

package/README.md

@@ -55,6 +55,29 @@ An execution response can be pending. Keep its `executionKind`, `executionId`, s
 
 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`, your backend can use the session approval read, approve and deny APIs with `platform_approvals:read` / `platform_approvals:manage` scopes. 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.
+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.
+
+## 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.
+
+```ts
+const run = await stacklink.bots.run(botId, { sessionId: session.id, message: "Where is my order?", variables: { orderNumber: "4821" } });
+for await (const event of stacklink.bots.stream(botId, run.id)) console.log(event);
+const result = await stacklink.bots.getRun(botId, run.id);
+console.log(result.output ?? result.finalText);
+```
+
+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. `asCustomer` 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-typescript#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): `getCustomerGrant`, `saveCustomerGrant`, and `removeCustomerGrant` 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.

package/compatibility.json

@@ -1,6 +1,6 @@
 {
   "schemaVersion": 1,
-  "sdkVersion": "0.2.2",
+  "sdkVersion": "0.3.7",
   "node": ">=22.0.0",
   "tested": {
     "ai": "7.0.31",