@salesforce/sdk-chat 1.133.1 → 1.133.2

package/README.md

@@ -0,0 +1,291 @@
+# @salesforce/sdk-chat
+
+Chat SDK for participating in conversational flows across Salesforce application surfaces. Provides a unified API for sending messages, executing tools, managing widget state, and reading resources — regardless of whether the host is OpenAI ChatGPT, an MCP Apps host, or Salesforce Agentforce.
+
+## Installation
+
+```sh
+npm install @salesforce/sdk-chat
+```
+
+## Quick Start
+
+```ts
+import { createChatSDK } from "@salesforce/sdk-chat";
+
+const sdk = await createChatSDK();
+
+// Send a message to the host
+await sdk.sendMessageToHost?.({ content: "Hello from the widget" });
+
+// Read tool input provided by the host
+const input = sdk.accessToolInput<{ query: string }>();
+if (input) {
+  console.log(input.data.query);
+}
+```
+
+## Initialization
+
+### Factory (Async)
+
+`createChatSDK` detects the runtime surface and returns the appropriate implementation. Each call creates a new instance.
+
+```ts
+const sdk = await createChatSDK();
+```
+
+### Singleton (Recommended)
+
+`getChatSDK` caches the instance so all callers share one SDK. The Promise itself is cached, preventing race conditions from concurrent callers.
+
+```ts
+import { getChatSDK } from "@salesforce/sdk-chat";
+
+const sdk = await getChatSDK();
+```
+
+### Synchronous Access
+
+After `getChatSDK()` has resolved, you can access the instance synchronously. Returns `null` if not yet initialized.
+
+```ts
+import { getChatSDKSync } from "@salesforce/sdk-chat";
+
+const sdk = getChatSDKSync(); // ChatSDK | null
+```
+
+### Options
+
+```ts
+import { Surface } from "@salesforce/sdk-core";
+
+const sdk = await createChatSDK({
+  // Force a specific surface (skip auto-detection)
+  surface: Surface.MCPApps,
+  // MCP Apps session options
+  mcpApps: {
+    appIdentity: { name: "my-app" },
+    handshakeTimeout: 5000,
+  },
+});
+```
+
+### Reset (Testing)
+
+```ts
+import { resetChatSDK } from "@salesforce/sdk-chat";
+
+resetChatSDK(); // Clears cached singleton; next getChatSDK() creates fresh instance
+```
+
+## API Reference
+
+All `ChatSDK` methods are optional — availability depends on the runtime surface. Always use optional chaining (`?.`) when calling them.
+
+### sendMessageToHost
+
+Send a message into the conversation.
+
+```ts
+await sdk.sendMessageToHost?.({
+  content: "Here are the results",
+  metadata: { source: "search" }, // optional
+});
+```
+
+| Param              | Type                      | Description                 |
+| ------------------ | ------------------------- | --------------------------- |
+| `message.content`  | `string`                  | Message text                |
+| `message.metadata` | `Record<string, unknown>` | Optional key-value metadata |
+
+### callTool
+
+Execute a tool on the MCP server and get the result.
+
+```ts
+const result = await sdk.callTool<{ items: string[] }>({
+  toolName: "search",
+  params: { query: "accounts" },
+});
+```
+
+| Param               | Type                      | Description                |
+| ------------------- | ------------------------- | -------------------------- |
+| `toolCall.toolName` | `string`                  | Name of the tool to invoke |
+| `toolCall.params`   | `Record<string, unknown>` | Optional tool parameters   |
+
+### accessToolInput / accessToolOutput
+
+Read the current tool input or output provided by the host. These are synchronous getters that return the latest state.
+
+```ts
+const input = sdk.accessToolInput<{ accountId: string }>();
+const output = sdk.accessToolOutput<{ name: string; revenue: number }>();
+
+if (input) {
+  console.log(input.data.accountId);
+}
+```
+
+Returns `ToolState<T> | null` where `ToolState<T> = { data: T; timestamp?: number }`.
+
+### accessToolMetadata
+
+Access metadata about the current tool (schema, description, response metadata).
+
+```ts
+const meta = sdk.accessToolMetadata<{ schema: object }>();
+```
+
+### getWidgetState / setWidgetState
+
+Persist widget state across tool invocations via the host's model context.
+
+```ts
+// Save state
+sdk.setWidgetState?.({ selectedTab: "overview", filters: ["active"] });
+
+// Restore state
+const state = sdk.getWidgetState<{ selectedTab: string }>();
+```
+
+`setWidgetState` is fire-and-forget — it sends state to the host but does not wait for acknowledgment.
+
+### readResource
+
+Read resource content by URI. MCP Apps only.
+
+```ts
+const resource = await sdk.readResource<{ html: string }>({
+  uri: "salesforce://accounts/001xxx",
+});
+```
+
+### openLink
+
+Open a URL. On OpenAI, falls back to `window.open()` if the native API is unavailable.
+
+```ts
+await sdk.openLink?.("https://salesforce.com/help");
+```
+
+### setDisplayMode
+
+Request the host to change the widget's display mode.
+
+```ts
+const result = await sdk.setDisplayMode?.("fullscreen");
+// result.mode === "fullscreen"
+```
+
+| Mode           | Description                       |
+| -------------- | --------------------------------- |
+| `"inline"`     | Normal embedded view in chat      |
+| `"fullscreen"` | Expanded full-screen view         |
+| `"pip"`        | Picture-in-Picture floating panel |
+
+### getHostContext
+
+Get environment information from the host. MCP Apps only.
+
+```ts
+const ctx = sdk.getHostContext?.();
+if (ctx) {
+  console.log(ctx.theme); // "light" | "dark"
+  console.log(ctx.displayMode); // "inline" | "fullscreen" | "pip"
+  console.log(ctx.locale); // "en-US"
+  console.log(ctx.maxHeight); // number (CSS pixels)
+  console.log(ctx.safeArea); // { top, right, bottom, left }
+  console.log(ctx.deviceCapabilities); // { touch?, hover? }
+  console.log(ctx.styles); // { variables?, css? }
+}
+```
+
+### subscribe
+
+Subscribe to SDK data changes (tool input, output, metadata, host context). Designed to work with React's `useSyncExternalStore`.
+
+```ts
+const unsubscribe = sdk.subscribe?.(() => {
+  const output = sdk.accessToolOutput();
+  // re-render with new data
+});
+
+// Cleanup
+unsubscribe?.();
+```
+
+### onToolCanceled
+
+Register a callback for when the host cancels tool execution. MCP Apps only.
+
+```ts
+const unsubscribe = sdk.onToolCanceled?.((reason) => {
+  console.log("Tool canceled:", reason);
+});
+```
+
+### followUpActions
+
+Get available follow-up actions (SalesforceACC only, currently returns `[]`).
+
+```ts
+const actions = sdk.followUpActions?.() ?? [];
+```
+
+## Surface Capabilities
+
+Not all methods are available on every surface. Use `getSurfaceCapabilities` from `@salesforce/sdk-core` to check at runtime, or refer to this matrix:
+
+| Method               | MCP Apps | OpenAI | Salesforce ACC |
+| -------------------- | -------- | ------ | -------------- |
+| `sendMessageToHost`  | Yes      | Yes    | Yes            |
+| `callTool`           | Yes      | Yes    | No             |
+| `accessToolInput`    | Yes      | Yes    | No             |
+| `accessToolOutput`   | Yes      | Yes    | No             |
+| `accessToolMetadata` | Yes      | Yes    | No             |
+| `getWidgetState`     | Yes      | Yes    | No             |
+| `setWidgetState`     | Yes      | Yes    | No             |
+| `readResource`       | Yes      | No     | No             |
+| `openLink`           | Yes      | Yes    | Yes            |
+| `setDisplayMode`     | Yes      | Yes    | No             |
+| `getHostContext`     | Yes      | No     | No             |
+| `onToolCanceled`     | Yes      | No     | No             |
+| `subscribe`          | Yes      | Yes    | Yes            |
+
+WebApp and Mosaic surfaces return an empty object with no methods.
+
+```ts
+import { getSurface, getSurfaceCapabilities } from "@salesforce/sdk-core";
+
+const caps = getSurfaceCapabilities(getSurface());
+if (caps.callTool) {
+  await sdk.callTool?.({ toolName: "search", params: { q: "test" } });
+}
+```
+
+## Exported Types
+
+```ts
+import type {
+  ChatSDK,
+  ChatMessage,
+  ToolCall,
+  ToolState,
+  ResourceRequest,
+  DisplayMode,
+  HostContext,
+  SafeAreaInsets,
+  DeviceCapabilities,
+  SDKOptions,
+} from "@salesforce/sdk-chat";
+
+import type { ChatSDKOptions } from "@salesforce/sdk-chat";
+```
+
+## License
+
+Copyright (c) 2026, Salesforce, Inc.
+All rights reserved.
+For full license text, see the LICENSE.txt file.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@salesforce/sdk-chat",
-  "version": "1.133.1",
+  "version": "1.133.2",
   "license": "SEE LICENSE IN LICENSE.txt",
   "type": "module",
   "main": "./dist/index.js",
@@ -26,7 +26,7 @@
     "test:coverage": "vitest run --coverage"
   },
   "dependencies": {
-    "@salesforce/sdk-core": "^1.133.1"
+    "@salesforce/sdk-core": "^1.133.2"
   },
   "devDependencies": {
     "vite": "^7.3.1",