@stacklink/sdk 0.2.2 → 0.3.8

package/README.md

@@ -55,6 +55,55 @@ 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.
+
+### X Chat on the user device
+
+Install the optional browser dependencies with `npm install @xdevplatform/chat-xdk@0.5.0 juicebox-sdk@0.3.7`, then import the client from `@stacklink/sdk/x-chat`. The main SDK does not load the WASM engine.
+
+For Vite, install `vite-plugin-wasm`, add `wasm()` to `plugins`, and use `build.target: 'esnext'` for the official engine's top-level WASM initialization. The production browser bundle has been exercised with these settings.
+
+Use the connected account's existing OAuth grant to call `x.getUsersPublicKey` with `juicebox_config`, `public_key_version`, `public_key`, `signing_public_key`, and `identity_public_key_signature` in `public_key.fields`. This read returns its result directly and does not retain secure-backup tokens in execution history. Pass the original `juicebox_config` JSON to `createStacklinkXChat`; supply `getAuthToken` using `xChatRealmToken(configJson, realmId)`. Refresh that exact user's public-key record if its realm token expires.
+
+Collect the PIN in the browser and pass its `Uint8Array` to `chat.unlock`. Never include the PIN, private keys, or an unwrapped conversation key in a Stacklink tool request, artifact, log, or Memory selection. Call `chat.close()` on logout, account change, or component teardown. Backup operations are serialized across accounts because the official SDK uses one global realm-token callback.
+
+Fetch participant public-key records through the same connection and call `chat.setParticipants`. It verifies each identity/signing-key binding before allowing a key change. `prepareConversationKeyChange`, `prepareGroupCreate`, and `prepareGroupMembersChange` retain the official SDK shapes; `xChatConversationChangeBody` selects only the wrapped participant keys and signatures for the API. Keep the returned raw conversation key on device. `xChatApiConversationId` converts the SDK's direct-conversation ID to the HTTP-path form used by X; `xChatCryptoConversationId` performs the inverse.
+
+`encryptMessage`, `encryptReply`, `encryptEdit`, and the reaction methods return the exact encrypted message body for `x.sendChatMessage`. Execute it through the normal Stacklink client with the same account, stable idempotency key, and normal approval. Retrieve the full execution receipt before deciding whether an uncertain send can be retried. `decryptEvents` and `decryptEvent` verify and decrypt on device. Media encryption/decryption and incremental media encoders use the official engine; upload only the encrypted artifact through `x.chatMediaUploadAppend` and decrypt downloaded bytes locally.
+
+New identities use `generateRegistration`, `x.addUserPublicKey`, then `updateConfig` and `setup` using the configuration returned for that registered public key. Keep first-time setup distinct from unlocking existing keys. The SDK never silently generates replacement keys.
+
+Bot-owned key blobs use the official native Chat XDK and a secret manager. The personal browser client does not accept private-key imports or expose private-key exports. This does not yet constitute a hosted Stacklink bot-key flow.
+
+### X streams and asynchronous results
+
+Create an X trigger with `deliveryMode: 'stream'` and its exact `streamOperation`. These triggers require a verified `app_bearer` credential profile for the customer's own X application. Filtered posts require existing exact `ruleIds`; Activity streams require exact `activityTags`. Subscriptions sharing an application endpoint must use the same field/partition parameters and share one upstream connection. Removing a subscription does not delete the customer's pre-existing rules. Provider reconnects may leave a source gap; checkpoint metadata does not claim guaranteed replay.
+
+Media finalization, compliance creation, and Ads analytics creation return a `providerJob` receipt. Retrieve the same tool execution with `client.getExecution`: its `execution.providerJobs` contains the current status, next check time, and completed result. The tool receipt confirms submission; the provider job confirms completion. Removing or replacing a credential profile stops its existing job reconciliation.
+
+Download compliance results by job ID and upload the selected artifact without handling signed tokens. `x.ads.downloadAnalyticsJobResult` verifies the exact completed advertiser/job pair, resolves X's signed storage URL internally, and writes bounded decompressed JSON to a Workbench artifact. Ads REST operations require the separate `ads_oauth1` profile and the corresponding X entitlement. The two official MCP endpoints share the primary OAuth2 grant.

package/compatibility.json

@@ -1,6 +1,6 @@
 {
   "schemaVersion": 1,
-  "sdkVersion": "0.2.2",
+  "sdkVersion": "0.3.8",
   "node": ">=22.0.0",
   "tested": {
     "ai": "7.0.31",
@@ -9,6 +9,7 @@
     "@anthropic-ai/claude-agent-sdk": "0.3.214"
   },
   "pythonTested": {
+    "chatxdk": "0.5.0",
     "openai-agents": "0.18.3",
     "claude-agent-sdk": "0.2.122"
   },
@@ -19,6 +20,7 @@
     "@anthropic-ai/claude-agent-sdk": "^0.3.214"
   },
   "pythonSupported": {
+    "chatxdk": "==0.5.0",
     "openai-agents": ">=0.18,<0.19",
     "claude-agent-sdk": ">=0.2,<0.3"
   },