@salesforce/platform-sdk 3.0.0

package/LICENSE.txt

@@ -0,0 +1,82 @@
+Terms of Use
+
+Copyright 2026 Salesforce, Inc. All rights reserved.
+
+These Terms of Use govern the download, installation, and/or use of this
+software provided by Salesforce, Inc. ("Salesforce") (the "Software"), were
+last updated on April 15, 2025, and constitute a legally binding
+agreement between you and Salesforce. If you do not agree to these Terms of
+Use, do not install or use the Software.
+
+Salesforce grants you a worldwide, non-exclusive, no-charge, royalty-free
+copyright license to reproduce, prepare derivative works of, publicly
+display, publicly perform, sublicense, and distribute the Software and
+derivative works subject to these Terms. These Terms shall be included in
+all copies or substantial portions of the Software.
+
+Subject to the limited rights expressly granted hereunder, Salesforce
+reserves all rights, title, and interest in and to all intellectual
+property subsisting in the Software. No rights are granted to you hereunder
+other than as expressly set forth herein. Users residing in countries on
+the United States Office of Foreign Assets Control sanction list, or which
+are otherwise subject to a US export embargo, may not use the Software.
+
+Implementation of the Software may require development work, for which you
+are responsible. The Software may contain bugs, errors and
+incompatibilities and is made available on an AS IS basis without support,
+updates, or service level commitments.
+
+Salesforce reserves the right at any time to modify, suspend, or
+discontinue, the Software (or any part thereof) with or without notice. You
+agree that Salesforce shall not be liable to you or to any third party for
+any modification, suspension, or discontinuance.
+
+You agree to defend Salesforce against any claim, demand, suit or
+proceeding made or brought against Salesforce by a third party arising out
+of or accruing from (a) your use of the Software, and (b) any application
+you develop with the Software that infringes any copyright, trademark,
+trade secret, trade dress, patent, or other intellectual property right of
+any person or defames any person or violates their rights of publicity or
+privacy (each a "Claim Against Salesforce"), and will indemnify Salesforce
+from any damages, attorney fees, and costs finally awarded against
+Salesforce as a result of, or for any amounts paid by Salesforce under a
+settlement approved by you in writing of, a Claim Against Salesforce,
+provided Salesforce (x) promptly gives you written notice of the Claim
+Against Salesforce, (y) gives you sole control of the defense and
+settlement of the Claim Against Salesforce (except that you may not settle
+any Claim Against Salesforce unless it unconditionally releases Salesforce
+of all liability), and (z) gives you all reasonable assistance, at your
+expense.
+
+WITHOUT LIMITING THE GENERALITY OF THE FOREGOING, THE SOFTWARE IS NOT
+SUPPORTED AND IS PROVIDED "AS IS," WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED. IN NO EVENT SHALL SALESFORCE HAVE ANY LIABILITY FOR ANY DAMAGES,
+INCLUDING, BUT NOT LIMITED TO, DIRECT, INDIRECT, SPECIAL, INCIDENTAL,
+PUNITIVE, OR CONSEQUENTIAL DAMAGES, OR DAMAGES BASED ON LOST PROFITS, DATA,
+OR USE, IN CONNECTION WITH THE SOFTWARE, HOWEVER CAUSED AND WHETHER IN
+CONTRACT, TORT, OR UNDER ANY OTHER THEORY OF LIABILITY, WHETHER OR NOT YOU
+HAVE BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
+
+These Terms of Use shall be governed exclusively by the internal laws of
+the State of California, without regard to its conflicts of laws
+rules. Each party hereby consents to the exclusive jurisdiction of the
+state and federal courts located in San Francisco County, California to
+adjudicate any dispute arising out of or relating to these Terms of Use and
+the download, installation, and/or use of the Software. Except as expressly
+stated herein, these Terms of Use constitute the entire agreement between
+the parties, and supersede all prior and contemporaneous agreements,
+proposals, or representations, written or oral, concerning their subject
+matter. No modification, amendment, or waiver of any provision of these
+Terms of Use shall be effective unless it is by an update to these Terms of
+Use that Salesforce makes available, or is in writing and signed by the
+party against whom the modification, amendment, or waiver is to be
+asserted.
+
+Data Privacy: Salesforce may collect, process, and store device,
+system, and other information related to your use of the Software. This
+information includes, but is not limited to, IP address, user metrics, and
+other data ("Usage Data"). Salesforce may use Usage Data for analytics,
+product development, and marketing purposes. You acknowledge that files
+generated in conjunction with the Software may contain sensitive or
+confidential data, and you are solely responsible for anonymizing and
+protecting such data.

package/README.md

@@ -0,0 +1,62 @@
+# @salesforce/platform-sdk
+
+Unified runtime SDK for participating in Salesforce application surfaces — Chat, View, Data, Lightning, Telemetry, and Analytics — from a single package.
+
+## Installation
+
+```sh
+npm install @salesforce/platform-sdk
+```
+
+`o11y` and `o11y_schema` are declared as peer dependencies. Consumers that use `createAnalytics`, `createTelemetryTransport`, `registerTelemetryUploader`, or `TelemetryUploader` must install them alongside this package:
+
+```sh
+npm install o11y o11y_schema
+```
+
+Consumers that only use the chat, view, data, lightning, or core surfaces still need to install them to satisfy the peer-dep declaration, but the modules are not loaded at runtime unless an analytics/telemetry symbol is imported.
+
+## Quick Start
+
+```ts
+import { createDataSDK, gql } from "@salesforce/platform-sdk";
+
+const data = await createDataSDK();
+
+const response = await data.graphql?.({
+  query: gql`
+    query Accounts {
+      uiapi {
+        query {
+          Account(first: 10) {
+            edges {
+              node {
+                Id
+                Name {
+                  value
+                }
+              }
+            }
+          }
+        }
+      }
+    }
+  `,
+});
+```
+
+The chat, view, lightning, telemetry, and analytics surfaces follow the same pattern — see [Migrating from individual SDK packages](#migrating-from-individual-sdk-packages) for the full set of factories.
+
+## Migrating from individual SDK packages
+
+This package replaces and consolidates:
+
+- `@salesforce/platform-sdk-core`
+- `@salesforce/platform-sdk-chat`
+- `@salesforce/platform-sdk-view`
+- `@salesforce/platform-sdk-data`
+- `@salesforce/platform-sdk-lightning`
+- `@salesforce/platform-sdk-telemetry`
+- `@salesforce/platform-sdk-analytics`
+
+All factory functions and types previously exported by those packages are exported from `@salesforce/platform-sdk`. Replace imports and remove the old packages from your `package.json`.

package/dist/analytics/analytics.d.ts

@@ -0,0 +1,21 @@
+import { Analytics, AnalyticsOptions } from './types';
+/**
+ * Creates an Analytics instance with auto-instrumentation active immediately.
+ *
+ * Handles all setup internally:
+ * - Creates a ChatSDK instance via getChatSDK() (unless one is provided)
+ * - Calls registerInstrumentedApp() with appPayloadProvider pre-wired
+ *   to attach appId and surface to every o11y log entry
+ * - Wraps the ChatSDK in a Proxy for auto-instrumentation
+ * - Sets up global error listeners (window.onerror, unhandledrejection)
+ * - Tracks session duration from init to dispose()
+ *
+ * @example
+ * ```typescript
+ * import { createAnalytics } from '../analytics';
+ *
+ * const analytics = await createAnalytics({ appId: 'my-app' });
+ * ```
+ */
+export declare function createAnalytics(options: AnalyticsOptions): Promise<Analytics>;
+//# sourceMappingURL=analytics.d.ts.map

package/dist/analytics/analytics.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"analytics.d.ts","sourceRoot":"","sources":["../../src/analytics/analytics.ts"],"names":[],"mappings":"AAmBA,OAAO,KAAK,EAAE,SAAS,EAAE,gBAAgB,EAAmB,MAAM,SAAS,CAAC;AAE5E;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAsB,eAAe,CAAC,OAAO,EAAE,gBAAgB,GAAG,OAAO,CAAC,SAAS,CAAC,CAkGnF"}

package/dist/analytics/error-listener.d.ts

@@ -0,0 +1,9 @@
+import { Instrumentation } from './types';
+/**
+ * Sets up global error auto-capture via window.onerror and
+ * unhandledrejection, delegating to instrumentation.error().
+ *
+ * Returns a cleanup function that removes both listeners.
+ */
+export declare function setupErrorListeners(instrumentation: Instrumentation): () => void;
+//# sourceMappingURL=error-listener.d.ts.map

package/dist/analytics/error-listener.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"error-listener.d.ts","sourceRoot":"","sources":["../../src/analytics/error-listener.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAE/C;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,eAAe,EAAE,eAAe,GAAG,MAAM,IAAI,CAsBhF"}

package/dist/analytics/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Copyright (c) 2026, Salesforce, Inc.,
+ * All rights reserved.
+ * For full license text, see the LICENSE.txt file
+ */
+export { createAnalytics } from './analytics';
+export type { Analytics, AnalyticsOptions } from './types';
+//# sourceMappingURL=index.d.ts.map

package/dist/analytics/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/analytics/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAC9C,YAAY,EAAE,SAAS,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAC"}

package/dist/analytics/method-configs.d.ts

@@ -0,0 +1,11 @@
+import { Instrumentation } from './types';
+export interface MethodConfig {
+    /** Whether this method returns a Promise and should use activityAsync */
+    isAsync: boolean;
+    /** Extract dimensional tags from the method arguments */
+    extractTags: (args: unknown[], surface: string) => Record<string, string>;
+    /** Optional argument transformation (e.g., subscribe callback wrapping) */
+    wrapArgs?: (args: unknown[], instrumentation: Instrumentation) => unknown[];
+}
+export declare const methodConfigs: Record<string, MethodConfig>;
+//# sourceMappingURL=method-configs.d.ts.map

package/dist/analytics/method-configs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"method-configs.d.ts","sourceRoot":"","sources":["../../src/analytics/method-configs.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAE/C,MAAM,WAAW,YAAY;IAC5B,yEAAyE;IACzE,OAAO,EAAE,OAAO,CAAC;IACjB,yDAAyD;IACzD,WAAW,EAAE,CAAC,IAAI,EAAE,OAAO,EAAE,EAAE,OAAO,EAAE,MAAM,KAAK,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC1E,2EAA2E;IAC3E,QAAQ,CAAC,EAAE,CAAC,IAAI,EAAE,OAAO,EAAE,EAAE,eAAe,EAAE,eAAe,KAAK,OAAO,EAAE,CAAC;CAC5E;AAMD,eAAO,MAAM,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,YAAY,CA8DtD,CAAC"}

package/dist/analytics/proxy.d.ts

@@ -0,0 +1,14 @@
+import { ChatSDK } from '../core';
+import { Instrumentation } from './types';
+/**
+ * Creates a Proxy-wrapped ChatSDK that auto-instruments every configured
+ * method using o11y activities and counters.
+ *
+ * - Async methods are wrapped entirely inside activityAsync() for full
+ *   round-trip timing. incrementCounter() records call counts and error rates.
+ * - Sync methods use incrementCounter() only.
+ * - The subscribe method wraps the callback argument via activity().
+ * - Unconfigured methods pass through unchanged.
+ */
+export declare function createInstrumentedProxy(sdk: ChatSDK, instrumentation: Instrumentation, surface: string): ChatSDK;
+//# sourceMappingURL=proxy.d.ts.map

package/dist/analytics/proxy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"proxy.d.ts","sourceRoot":"","sources":["../../src/analytics/proxy.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAEvC,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAE/C;;;;;;;;;GASG;AACH,wBAAgB,uBAAuB,CACtC,GAAG,EAAE,OAAO,EACZ,eAAe,EAAE,eAAe,EAChC,OAAO,EAAE,MAAM,GACb,OAAO,CAqCT"}

package/dist/analytics/schemas.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Copyright (c) 2026, Salesforce, Inc.,
+ * All rights reserved.
+ * For full license text, see the LICENSE.txt file
+ */
+export { customEventSchema, interactionSchema, pageViewSchema, sessionSchema, errorContextSchema, analyticsContextSchema, } from 'o11y_schema/sf_mcpanalytics';
+//# sourceMappingURL=schemas.d.ts.map

package/dist/analytics/schemas.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schemas.d.ts","sourceRoot":"","sources":["../../src/analytics/schemas.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EACN,iBAAiB,EACjB,iBAAiB,EACjB,cAAc,EACd,aAAa,EACb,kBAAkB,EAClB,sBAAsB,GACtB,MAAM,6BAA6B,CAAC"}

package/dist/analytics/subscribe-wrapper.d.ts

@@ -0,0 +1,7 @@
+import { Instrumentation } from './types';
+/**
+ * Wraps a subscribe callback with o11y's sync activity()
+ * so callback execution time and errors are auto-captured.
+ */
+export declare function wrapSubscribeCallback(callback: () => void, instrumentation: Instrumentation): () => void;
+//# sourceMappingURL=subscribe-wrapper.d.ts.map

package/dist/analytics/subscribe-wrapper.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"subscribe-wrapper.d.ts","sourceRoot":"","sources":["../../src/analytics/subscribe-wrapper.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAE/C;;;GAGG;AACH,wBAAgB,qBAAqB,CACpC,QAAQ,EAAE,MAAM,IAAI,EACpB,eAAe,EAAE,eAAe,GAC9B,MAAM,IAAI,CAIZ"}

package/dist/analytics/types.d.ts

@@ -0,0 +1,90 @@
+import { ChatSDK } from '../core';
+import { TelemetryTransport } from '../telemetry';
+/**
+ * o11y Schema interface. Matches the Schema type from o11y.
+ */
+export interface Schema {
+    namespace: string;
+    name: string;
+    pbjsSchema: Record<string, unknown>;
+}
+/**
+ * o11y SchematizedPayload — returned by PayloadProvider.getPayload().
+ */
+export interface SchematizedPayload {
+    schema: Schema;
+    payload: Record<string, unknown>;
+}
+/**
+ * o11y PayloadProviderArgs — passed to PayloadProvider.getPayload().
+ */
+export interface PayloadProviderArgs {
+    schema?: Schema;
+    data?: Record<string, unknown>;
+    logMeta?: Record<string, unknown>;
+}
+/**
+ * o11y PayloadProvider interface.
+ * Called on every log/error/activity/metric emission.
+ */
+export interface PayloadProvider {
+    getPayload(args?: PayloadProviderArgs): SchematizedPayload | undefined;
+}
+/**
+ * o11y Instrumentation interface.
+ * Defines the methods analytics uses for logging and metrics.
+ */
+export interface Instrumentation {
+    log(schema: Schema | string, data?: Record<string, unknown>): void;
+    error(error: unknown, schema?: Schema | string, data?: Record<string, unknown>): void;
+    activityAsync<T>(name: string, fn: () => Promise<T>): Promise<T>;
+    activity<T>(name: string, fn: () => T): T;
+    incrementCounter(name: string, increment?: number, hasError?: boolean, tags?: Record<string, string>): void;
+}
+/**
+ * o11y InstrumentedApp interface.
+ * Returned by registerInstrumentedApp(). Extends Instrumentation with
+ * app-level lifecycle methods.
+ */
+export interface InstrumentedApp extends Instrumentation {
+    registerLogCollector(collector: unknown): void;
+    registerMetricsCollector(collector: unknown): void;
+    activateClickTracker(): void;
+    deactivateClickTracker(): void;
+    getClientSessionId(): string;
+}
+/**
+ * Options for createAnalytics().
+ *
+ * Only `appId` is required. ChatSDK and o11y registration are handled internally.
+ */
+export interface AnalyticsOptions {
+    /** Developer-supplied MCP App identifier */
+    appId: string;
+    /** Optional ChatSDK override. If omitted, created automatically via getChatSDK(). */
+    sdk?: ChatSDK;
+    /** Optional o11y client session ID override */
+    clientSessionId?: string;
+    /** Optional telemetry transport. When provided, an o11y-uploader is auto-wired to route envelopes to transport.enqueue(). */
+    transport?: TelemetryTransport;
+}
+/**
+ * Analytics instance returned by createAnalytics().
+ */
+export interface Analytics {
+    /** Proxy-wrapped SDK — pass to telemetry / widget host */
+    instrumentedSDK: ChatSDK;
+    /** The o11y InstrumentedApp — exposed for advanced use (click tracking, log collectors, etc.) */
+    app: InstrumentedApp;
+    /** Log a custom business event */
+    trackEvent: (eventName: string, properties?: Record<string, unknown>) => void;
+    /** Log a user interaction with a UI element */
+    trackInteraction: (elementId: string, properties?: Record<string, unknown>) => void;
+    /** Log an error explicitly */
+    trackError: (error: Error | string, properties?: Record<string, unknown>) => void;
+    /** Log a component load / page view */
+    trackPageView: (componentRef: string) => void;
+    /** Cleanup — removes listeners, logs session duration, flushes events */
+    dispose: () => void;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/analytics/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/analytics/types.ts"],"names":[],"mappings":"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"}

package/dist/chat/index.d.ts

@@ -0,0 +1,22 @@
+import { ChatSDK, SDKOptions, McpAppsSessionOptions } from '../core';
+/**
+ * Options for creating a ChatSDK instance.
+ */
+export interface ChatSDKOptions extends SDKOptions {
+    /** MCP Apps session options (app identity, handshake timeout) */
+    mcpApps?: McpAppsSessionOptions;
+}
+/**
+ * Create and initialize a ChatSDK instance based on the detected surface
+ *
+ * For MCP Apps surfaces, this performs the SEP-1865 handshake (ui/initialize)
+ * via the shared {@link McpAppsSession} singleton on the first call.
+ *
+ * @param options - Optional configuration including surface override
+ * @returns Promise resolving to an initialized ChatSDK instance
+ */
+export declare function createChatSDK(options?: ChatSDKOptions): Promise<ChatSDK>;
+export { MCPAppsChatSDK } from './mcpapps';
+export { getChatSDK, getChatSDKSync, resetChatSDK } from './singleton';
+export type { HostContext, ChatMessage, ChatSDK, DeviceCapabilities, DisplayMode, ResourceRequest, SafeAreaInsets, SDKOptions, ToolCall, ToolState, } from '../core';
+//# sourceMappingURL=index.d.ts.map

package/dist/chat/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/chat/index.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,OAAO,EAAE,UAAU,EAAE,qBAAqB,EAAE,MAAM,SAAS,CAAC;AAK1E;;GAEG;AACH,MAAM,WAAW,cAAe,SAAQ,UAAU;IACjD,iEAAiE;IACjE,OAAO,CAAC,EAAE,qBAAqB,CAAC;CAChC;AAED;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAAC,OAAO,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,OAAO,CAAC,CA6BxE;AAED,OAAO,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAC3C,OAAO,EAAE,UAAU,EAAE,cAAc,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAEvE,YAAY,EACX,WAAW,EACX,WAAW,EACX,OAAO,EACP,kBAAkB,EAClB,WAAW,EACX,eAAe,EACf,cAAc,EACd,UAAU,EACV,QAAQ,EACR,SAAS,GACT,MAAM,SAAS,CAAC"}

package/dist/chat/mcpapps.d.ts

@@ -0,0 +1,61 @@
+import { ChatSDK, HostContext, ChatMessage, ResourceRequest, ToolCall, ToolState, DisplayMode, McpAppsSession } from '../core';
+/**
+ * Chat SDK implementation for MCP Apps surface using the shared McpAppsSession.
+ *
+ * Supports: sendMessageToHost, callTool, readResource, openLink, accessToolInput, accessToolOutput,
+ * accessToolMetadata, getWidgetState, setWidgetState, onToolCanceled, subscribe
+ *
+ * Uses a shared {@link McpAppsSession} for JSON-RPC 2.0 transport instead of
+ * owning its own postMessage listener, avoiding duplicate listeners and ID
+ * counter collisions when used alongside MCPAppsViewSDK.
+ */
+export declare class MCPAppsChatSDK implements ChatSDK {
+    private session;
+    private globals;
+    private canceledCallbacks;
+    private subscriptions;
+    constructor(session: McpAppsSession);
+    /**
+     * Handle tool result notifications from the host
+     * @param params - Tool result data from the host
+     */
+    private handleToolResult;
+    /**
+     * Handle tool input notifications from the host
+     * @param params - Tool input data from the host
+     */
+    private handleToolInput;
+    /**
+     * Handle tool cancelled notifications from the host
+     * @param params - Tool cancellation data from the host
+     */
+    private handleToolCancelled;
+    /**
+     * Request display mode change from host
+     * @param mode - The requested display mode
+     * @returns Promise with the new display mode (confirmed by host)
+     */
+    setDisplayMode(mode: DisplayMode): Promise<{
+        mode: DisplayMode;
+    }>;
+    sendMessageToHost(message: ChatMessage): Promise<void>;
+    callTool<T>(toolCall: ToolCall): Promise<T>;
+    readResource<T>(request: ResourceRequest): Promise<T>;
+    openLink(url: string): Promise<void>;
+    accessToolInput<T>(): ToolState<T> | null;
+    accessToolOutput<T>(): ToolState<T> | null;
+    accessToolMetadata<T>(): T | null;
+    getWidgetState<T>(): T | null;
+    setWidgetState<T>(state: T): void;
+    /**
+     * Get the current host context.
+     *
+     * Maps MCP Apps wire-format fields to the protocol-agnostic HostContext.
+     * Always returns an object (empty `{}` when no context has been received).
+     */
+    getHostContext(): HostContext;
+    onToolCanceled(callback: (reason: string) => void): () => void;
+    subscribe(callback: () => void): () => void;
+    private notifySubscribers;
+}
+//# sourceMappingURL=mcpapps.d.ts.map

package/dist/chat/mcpapps.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcpapps.d.ts","sourceRoot":"","sources":["../../src/chat/mcpapps.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,KAAK,EACX,OAAO,EACP,WAAW,EACX,WAAW,EACX,eAAe,EACf,QAAQ,EACR,SAAS,EACT,WAAW,EACX,MAAM,SAAS,CAAC;AACjB,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAE9C;;;;;;;;;GASG;AACH,qBAAa,cAAe,YAAW,OAAO;IAWjC,OAAO,CAAC,OAAO;IAV3B,OAAO,CAAC,OAAO,CAMR;IACP,OAAO,CAAC,iBAAiB,CAAuC;IAChE,OAAO,CAAC,aAAa,CAAyB;gBAE1B,OAAO,EAAE,cAAc;IA+B3C;;;OAGG;IACH,OAAO,CAAC,gBAAgB;IA6BxB;;;OAGG;IACH,OAAO,CAAC,eAAe;IAUvB;;;OAGG;IACH,OAAO,CAAC,mBAAmB;IAO3B;;;;OAIG;IACG,cAAc,CAAC,IAAI,EAAE,WAAW,GAAG,OAAO,CAAC;QAAE,IAAI,EAAE,WAAW,CAAA;KAAE,CAAC;IAOjE,iBAAiB,CAAC,OAAO,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC;IAYtD,QAAQ,CAAC,CAAC,EAAE,QAAQ,EAAE,QAAQ,GAAG,OAAO,CAAC,CAAC,CAAC;IAQ3C,YAAY,CAAC,CAAC,EAAE,OAAO,EAAE,eAAe,GAAG,OAAO,CAAC,CAAC,CAAC;IAOrD,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAI1C,eAAe,CAAC,CAAC,KAAK,SAAS,CAAC,CAAC,CAAC,GAAG,IAAI;IAMzC,gBAAgB,CAAC,CAAC,KAAK,SAAS,CAAC,CAAC,CAAC,GAAG,IAAI;IAW1C,kBAAkB,CAAC,CAAC,KAAK,CAAC,GAAG,IAAI;IAWjC,cAAc,CAAC,CAAC,KAAK,CAAC,GAAG,IAAI;IAM7B,cAAc,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,GAAG,IAAI;IAYjC;;;;;OAKG;IACH,cAAc,IAAI,WAAW;IAmC7B,cAAc,CAAC,QAAQ,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,IAAI,GAAG,MAAM,IAAI;IAS9D,SAAS,CAAC,QAAQ,EAAE,MAAM,IAAI,GAAG,MAAM,IAAI;IAQ3C,OAAO,CAAC,iBAAiB;CAGzB"}

package/dist/chat/openai.d.ts

@@ -0,0 +1,25 @@
+import { ChatSDK, ChatMessage, DisplayMode, ToolCall, ToolState } from '../core';
+/**
+ * Event type emitted by OpenAI platform when global data changes
+ */
+export declare const SET_GLOBALS_EVENT_TYPE = "openai:set_globals";
+/**
+ * Chat SDK implementation for OpenAI surface
+ * Supports: sendMessageToHost, callTool, accessToolInput, accessToolOutput,
+ * accessToolMetadata, getWidgetState, setWidgetState, setDisplayMode, subscribe
+ */
+export declare class OpenAIChatSDK implements ChatSDK {
+    sendMessageToHost(message: ChatMessage): Promise<void>;
+    callTool<T>(toolCall: ToolCall): Promise<T>;
+    accessToolInput<T>(): ToolState<T> | null;
+    accessToolOutput<T>(): ToolState<T> | null;
+    accessToolMetadata<T>(): T | null;
+    getWidgetState<T>(): T | null;
+    setWidgetState<T>(state: T): void;
+    openLink(url: string): Promise<void>;
+    setDisplayMode(mode: DisplayMode): Promise<{
+        mode: DisplayMode;
+    }>;
+    subscribe(callback: () => void): () => void;
+}
+//# sourceMappingURL=openai.d.ts.map

package/dist/chat/openai.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"openai.d.ts","sourceRoot":"","sources":["../../src/chat/openai.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,KAAK,EAAE,OAAO,EAAE,WAAW,EAAE,WAAW,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AAEtF;;GAEG;AACH,eAAO,MAAM,sBAAsB,uBAAuB,CAAC;AAE3D;;;;GAIG;AACH,qBAAa,aAAc,YAAW,OAAO;IAC5C,iBAAiB,CAAC,OAAO,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC;IAItD,QAAQ,CAAC,CAAC,EAAE,QAAQ,EAAE,QAAQ,GAAG,OAAO,CAAC,CAAC,CAAC;IAI3C,eAAe,CAAC,CAAC,KAAK,SAAS,CAAC,CAAC,CAAC,GAAG,IAAI;IAMzC,gBAAgB,CAAC,CAAC,KAAK,SAAS,CAAC,CAAC,CAAC,GAAG,IAAI;IAM1C,kBAAkB,CAAC,CAAC,KAAK,CAAC,GAAG,IAAI;IAMjC,cAAc,CAAC,CAAC,KAAK,CAAC,GAAG,IAAI;IAM7B,cAAc,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,GAAG,IAAI;IAI3B,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAWpC,cAAc,CAAC,IAAI,EAAE,WAAW,GAAG,OAAO,CAAC;QAAE,IAAI,EAAE,WAAW,CAAA;KAAE,CAAC;IAIvE,SAAS,CAAC,QAAQ,EAAE,MAAM,IAAI,GAAG,MAAM,IAAI;CAW3C"}

package/dist/chat/salesforce-acc.d.ts

@@ -0,0 +1,13 @@
+import { ChatSDK, ChatMessage } from '../core';
+/**
+ * Chat SDK implementation for Salesforce ACC surface
+ * Supports: sendMessageToHost, followUpActions
+ *
+ * NOTE: This is a stub implementation. Actual implementation depends on
+ * Salesforce ACC surface specification which is not yet available.
+ */
+export declare class SalesforceACCChatSDK implements ChatSDK {
+    sendMessageToHost(message: ChatMessage): Promise<void>;
+    followUpActions<T>(): T[];
+}
+//# sourceMappingURL=salesforce-acc.d.ts.map

package/dist/chat/salesforce-acc.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"salesforce-acc.d.ts","sourceRoot":"","sources":["../../src/chat/salesforce-acc.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,KAAK,EAAE,OAAO,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAEpD;;;;;;GAMG;AACH,qBAAa,oBAAqB,YAAW,OAAO;IAC7C,iBAAiB,CAAC,OAAO,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC;IAM5D,eAAe,CAAC,CAAC,KAAK,CAAC,EAAE;CAKzB"}

package/dist/chat/singleton.d.ts

@@ -0,0 +1,32 @@
+import { ChatSDK } from '../core';
+import { ChatSDKOptions } from './index';
+/**
+ * Get or create a singleton ChatSDK instance.
+ *
+ * The first caller may provide options (e.g. surface-specific configuration).
+ * Subsequent callers receive the same cached Promise regardless of arguments.
+ *
+ * The Promise itself is cached (not the resolved value) so concurrent callers
+ * do not race to create multiple instances.
+ *
+ * @param options - Optional configuration (only used on first call)
+ * @returns Promise resolving to the shared ChatSDK instance
+ */
+export declare function getChatSDK(options?: ChatSDKOptions): Promise<ChatSDK>;
+/**
+ * Synchronously get the singleton ChatSDK instance.
+ *
+ * Returns the resolved instance if {@link getChatSDK} has already been
+ * called and completed, or `null` if not yet initialized. Use this in
+ * contexts where async is not available (e.g., imperative mosaic components).
+ *
+ * @returns The singleton ChatSDK instance, or null if not yet ready
+ */
+export declare function getChatSDKSync(): ChatSDK | null;
+/**
+ * Reset the singleton ChatSDK cache.
+ *
+ * Useful for testing and session reset scenarios.
+ */
+export declare function resetChatSDK(): void;
+//# sourceMappingURL=singleton.d.ts.map

package/dist/chat/singleton.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"singleton.d.ts","sourceRoot":"","sources":["../../src/chat/singleton.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAEvC,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAK9C;;;;;;;;;;;GAWG;AACH,wBAAgB,UAAU,CAAC,OAAO,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,OAAO,CAAC,CAQrE;AAED;;;;;;;;GAQG;AACH,wBAAgB,cAAc,IAAI,OAAO,GAAG,IAAI,CAE/C;AAED;;;;GAIG;AACH,wBAAgB,YAAY,IAAI,IAAI,CAGnC"}

package/dist/core/acc-types.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Copyright (c) 2026, Salesforce, Inc.,
+ * All rights reserved.
+ * For full license text, see the LICENSE.txt file
+ */
+/**
+ * Mirrors the Connection type returned by copilotClientApi.connect().
+ * Structural match — no LWC import dependency.
+ */
+export interface ACCConnection {
+    open: () => Promise<void>;
+    close: () => Promise<void>;
+    execute: (request: {
+        type: string;
+        value: unknown;
+    }) => Promise<void>;
+    addVariables: (variables: {
+        name: string;
+        type: string;
+        value: unknown;
+    }[]) => void;
+    disconnect: () => void;
+}
+/**
+ * The args object passed to preReceive callbacks by the Panel API.
+ */
+export interface ACCPreReceiveArgs {
+    message: unknown;
+    toStreamResponseBlock: (...args: unknown[]) => unknown;
+    toResponseBlock: (...args: unknown[]) => unknown;
+    toErrorBlock: (...args: unknown[]) => unknown;
+}
+/**
+ * Mirrors copilotPanelApi callback registration/unregistration.
+ * Structural match — no LWC import dependency.
+ */
+export interface ACCPanelCallbacks {
+    registerCallback: (options: {
+        panelId?: string;
+        callbackType: string;
+        callback: (content: unknown, args: ACCPreReceiveArgs) => void;
+    }) => Promise<boolean>;
+    unregisterCallback: (options: {
+        panelId?: string;
+        callbackType: string;
+        callback: (content: unknown, args: ACCPreReceiveArgs) => void;
+    }) => Promise<boolean>;
+}
+//# sourceMappingURL=acc-types.d.ts.map

package/dist/core/acc-types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"acc-types.d.ts","sourceRoot":"","sources":["../../src/core/acc-types.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH;;;GAGG;AACH,MAAM,WAAW,aAAa;IAC7B,IAAI,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAC1B,KAAK,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAC3B,OAAO,EAAE,CAAC,OAAO,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,OAAO,CAAA;KAAE,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACtE,YAAY,EAAE,CAAC,SAAS,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,OAAO,CAAA;KAAE,EAAE,KAAK,IAAI,CAAC;IACpF,UAAU,EAAE,MAAM,IAAI,CAAC;CACvB;AAED;;GAEG;AACH,MAAM,WAAW,iBAAiB;IACjC,OAAO,EAAE,OAAO,CAAC;IACjB,qBAAqB,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,OAAO,CAAC;IACvD,eAAe,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,OAAO,CAAC;IACjD,YAAY,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,OAAO,CAAC;CAC9C;AAED;;;GAGG;AACH,MAAM,WAAW,iBAAiB;IACjC,gBAAgB,EAAE,CAAC,OAAO,EAAE;QAC3B,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,YAAY,EAAE,MAAM,CAAC;QACrB,QAAQ,EAAE,CAAC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,iBAAiB,KAAK,IAAI,CAAC;KAC9D,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IACvB,kBAAkB,EAAE,CAAC,OAAO,EAAE;QAC7B,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,YAAY,EAAE,MAAM,CAAC;QACrB,QAAQ,EAAE,CAAC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,iBAAiB,KAAK,IAAI,CAAC;KAC9D,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;CACvB"}

package/dist/core/capabilities.d.ts

@@ -0,0 +1,40 @@
+import { Surface } from './surface';
+/**
+ * Static capability map for each surface.
+ *
+ * Indicates which ChatSDK / ViewSDK methods are available on a given surface.
+ * Use this to conditionally render UI or feature-gate functionality.
+ */
+export interface SurfaceCapabilities {
+    callTool: boolean;
+    sendMessageToHost: boolean;
+    readResource: boolean;
+    openLink: boolean;
+    accessToolInput: boolean;
+    accessToolOutput: boolean;
+    accessToolMetadata: boolean;
+    getWidgetState: boolean;
+    setWidgetState: boolean;
+    onToolCanceled: boolean;
+    setDisplayMode: boolean;
+    getHostContext: boolean;
+    subscribe: boolean;
+    displayAlert: boolean;
+    displayToast: boolean;
+    displayModal: boolean;
+    getTheme: boolean;
+    resize: boolean;
+}
+/**
+ * Returns the static capability map for a given surface.
+ *
+ * @example
+ * ```typescript
+ * const caps = getSurfaceCapabilities(Surface.MCPApps);
+ * if (caps.displayAlert) {
+ *   viewSdk.displayAlert?.({ message: "Hello", level: "info" });
+ * }
+ * ```
+ */
+export declare function getSurfaceCapabilities(surface: Surface): SurfaceCapabilities;
+//# sourceMappingURL=capabilities.d.ts.map

package/dist/core/capabilities.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"capabilities.d.ts","sourceRoot":"","sources":["../../src/core/capabilities.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEpC;;;;;GAKG;AACH,MAAM,WAAW,mBAAmB;IAEnC,QAAQ,EAAE,OAAO,CAAC;IAClB,iBAAiB,EAAE,OAAO,CAAC;IAC3B,YAAY,EAAE,OAAO,CAAC;IACtB,QAAQ,EAAE,OAAO,CAAC;IAClB,eAAe,EAAE,OAAO,CAAC;IACzB,gBAAgB,EAAE,OAAO,CAAC;IAC1B,kBAAkB,EAAE,OAAO,CAAC;IAC5B,cAAc,EAAE,OAAO,CAAC;IACxB,cAAc,EAAE,OAAO,CAAC;IACxB,cAAc,EAAE,OAAO,CAAC;IACxB,cAAc,EAAE,OAAO,CAAC;IACxB,cAAc,EAAE,OAAO,CAAC;IACxB,SAAS,EAAE,OAAO,CAAC;IAGnB,YAAY,EAAE,OAAO,CAAC;IACtB,YAAY,EAAE,OAAO,CAAC;IACtB,YAAY,EAAE,OAAO,CAAC;IACtB,QAAQ,EAAE,OAAO,CAAC;IAElB,MAAM,EAAE,OAAO,CAAC;CAChB;AA0FD;;;;;;;;;;GAUG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,OAAO,GAAG,mBAAmB,CAc5E"}