@salesforce/platform-sdk 3.0.0

package/dist/core/chat.d.ts

@@ -0,0 +1,203 @@
+import { ThemeMode } from './view';
+/**
+ * Message payload for chat stream
+ */
+export interface ChatMessage {
+    content: string;
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Tool execution payload
+ */
+export interface ToolCall {
+    toolName: string;
+    params?: Record<string, unknown>;
+}
+/**
+ * Resource read request
+ */
+export interface ResourceRequest {
+    uri: string;
+}
+/**
+ * Tool input/output state
+ */
+export interface ToolState<T = unknown> {
+    data: T;
+    timestamp?: number;
+}
+/**
+ * Display modes
+ * - inline: Normal embedded view in chat
+ * - fullscreen: Expanded full-screen view
+ * - pip: Picture-in-Picture (floating panel)
+ */
+export type DisplayMode = "inline" | "fullscreen" | "pip";
+/**
+ * Safe area insets describing the non-occluded region of the viewport.
+ * Values are in CSS pixels.
+ */
+export interface SafeAreaInsets {
+    top: number;
+    right: number;
+    bottom: number;
+    left: number;
+}
+/**
+ * Device interaction capabilities.
+ */
+export interface DeviceCapabilities {
+    /** Whether the device supports touch input */
+    touch?: boolean;
+    /** Whether the device supports hover (pointer) input */
+    hover?: boolean;
+}
+/**
+ * Styles provided by the host for theming and font loading.
+ */
+export interface HostStyles {
+    /** CSS variables for theming */
+    variables?: Record<string, string | undefined>;
+    /** CSS blocks that Views can inject */
+    css?: {
+        /** CSS for font loading (@font-face rules or @import statements) */
+        fonts?: string;
+    };
+}
+/**
+ * Protocol-agnostic host context exposed to Chat SDK consumers.
+ *
+ * Contains environment information provided by the host. All fields are
+ * optional because availability depends on the host surface and its
+ * configuration.
+ */
+export interface HostContext {
+    /** Current theme mode */
+    theme?: ThemeMode;
+    /** Current display mode of the widget */
+    displayMode?: DisplayMode;
+    /** Maximum height available for the widget, in CSS pixels */
+    maxHeight?: number;
+    /** Safe area insets (e.g. for notch, system bars) */
+    safeArea?: SafeAreaInsets;
+    /** Host user agent string */
+    userAgent?: string;
+    /** BCP 47 locale tag (e.g. "en-US") */
+    locale?: string;
+    /** Device interaction capabilities */
+    deviceCapabilities?: DeviceCapabilities;
+    /** Styles provided by the host for theming and font loading */
+    styles?: HostStyles;
+}
+/**
+ * Chat SDK API with optional methods based on surface capabilities
+ */
+export interface ChatSDK {
+    /**
+     * Send a message to the host
+     *
+     * @param message - The message to send
+     */
+    sendMessageToHost?: (message: ChatMessage) => Promise<void>;
+    /**
+     * Execute a tool on the MCP Server
+     *
+     * @param toolCall - The tool to call with parameters
+     */
+    callTool?: <T>(toolCall: ToolCall) => Promise<T>;
+    /**
+     * Access the current tool input data
+     *
+     * @returns The tool input data or null if not available
+     */
+    accessToolInput?: <T>() => ToolState<T> | null;
+    /**
+     * Access the current tool output data
+     *
+     * @returns The tool output data or null if not available
+     */
+    accessToolOutput?: <T>() => ToolState<T> | null;
+    /**
+     * Access metadata about the current tool
+     *
+     * @returns Tool metadata including schema, description, etc.
+     */
+    accessToolMetadata?: <T>() => T | null;
+    /**
+     * Get the current widget state
+     *
+     * @returns The widget state or null if not available
+     */
+    getWidgetState?: <T>() => T | null;
+    /**
+     * Set the widget state
+     *
+     * @param state - The widget state to persist
+     */
+    setWidgetState?: <T>(state: T) => void;
+    /**
+     * Read resource content by URI
+     *
+     * @param request - The resource request with URI
+     */
+    readResource?: <T>(request: ResourceRequest) => Promise<T>;
+    /**
+     * Open a URL in a new window or tab
+     *
+     * @param url - The URL to open
+     */
+    openLink?: (url: string) => Promise<void>;
+    /**
+     * Register a callback for when tool execution is canceled
+     *
+     * @param callback - Function to call when tool is canceled
+     */
+    onToolCanceled?: (callback: () => void) => void;
+    /**
+     * Get available follow-up actions
+     *
+     * @returns Array of available actions
+     */
+    followUpActions?: <T>() => T[];
+    /**
+     * Set the display mode for the widget
+     *
+     * @param mode - The desired display mode
+     * @returns Promise resolving to the applied display mode
+     */
+    setDisplayMode?: (mode: DisplayMode) => Promise<{
+        mode: DisplayMode;
+    }>;
+    /**
+     * Get the current host context
+     *
+     * Returns environment information from the host surface including
+     * display mode, theme, locale, dimensions, and device capabilities.
+     * Returns an empty object if the host has not provided context information.
+     *
+     * @returns The current host context (empty object if not available)
+     */
+    getHostContext?: () => HostContext;
+    /**
+     * Subscribe to data changes from the host
+     *
+     * This method provides a platform-agnostic way to listen for changes to
+     * tool input, output, metadata, and other SDK data. It's designed to work
+     * with React's useSyncExternalStore and other reactive patterns.
+     *
+     * @param callback - Function to call when data changes
+     * @returns Cleanup function to unsubscribe
+     *
+     * @example
+     * ```typescript
+     * const unsubscribe = sdk.subscribe?.(() => {
+     *   console.log('SDK data changed');
+     * });
+     *
+     * // Later, cleanup
+     * unsubscribe?.();
+     * ```
+     */
+    subscribe?: (callback: () => void) => () => void;
+}
+//# sourceMappingURL=chat.d.ts.map

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

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

package/dist/core/data.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Copyright (c) 2026, Salesforce, Inc.,
+ * All rights reserved.
+ * For full license text, see the LICENSE.txt file
+ */
+export interface GraphQLResponse<T> {
+    data: T;
+    errors?: {
+        message: string;
+        locations?: {
+            line: number;
+            column: number;
+        }[];
+        path?: string[];
+    }[];
+}
+export interface GraphQLRequest<V = Record<string, unknown>> {
+    query: string;
+    variables?: V;
+    operationName?: string;
+}
+export interface DataSDK {
+    /**
+     * Run a GraphQL query
+     *
+     * @param request - The GraphQL request options (query, variables, operationName)
+     */
+    graphql?: <T, V = Record<string, unknown>>(request: GraphQLRequest<V>) => Promise<GraphQLResponse<T>>;
+    /**
+     * Make a request using the Fetch API.
+     *
+     * @param input - The URL or Request object
+     * @param init - Optional RequestInit configuration
+     * @returns Promise resolving to Response
+     */
+    fetch?: typeof fetch;
+}
+//# sourceMappingURL=data.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"data.d.ts","sourceRoot":"","sources":["../../src/core/data.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,MAAM,WAAW,eAAe,CAAC,CAAC;IACjC,IAAI,EAAE,CAAC,CAAC;IACR,MAAM,CAAC,EAAE;QACR,OAAO,EAAE,MAAM,CAAC;QAChB,SAAS,CAAC,EAAE;YAAE,IAAI,EAAE,MAAM,CAAC;YAAC,MAAM,EAAE,MAAM,CAAA;SAAE,EAAE,CAAC;QAC/C,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;KAChB,EAAE,CAAC;CACJ;AAED,MAAM,WAAW,cAAc,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAC1D,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,CAAC,EAAE,CAAC,CAAC;IACd,aAAa,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,OAAO;IACvB;;;;OAIG;IACH,OAAO,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACxC,OAAO,EAAE,cAAc,CAAC,CAAC,CAAC,KACtB,OAAO,CAAC,eAAe,CAAC,CAAC,CAAC,CAAC,CAAC;IAEjC;;;;;;OAMG;IACH,KAAK,CAAC,EAAE,OAAO,KAAK,CAAC;CACrB"}

package/dist/core/index.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Copyright (c) 2026, Salesforce, Inc.,
+ * All rights reserved.
+ * For full license text, see the LICENSE.txt file
+ */
+export { Surface, getSurface } from './surface';
+export type { ACCConnection, ACCPanelCallbacks, ACCPreReceiveArgs } from './acc-types';
+export type { SDKOptions } from './options';
+export type { HostContext, HostStyles, ChatMessage, ChatSDK, DeviceCapabilities, DisplayMode, ResourceRequest, SafeAreaInsets, ToolCall, ToolState, } from './chat';
+export type { AlertOptions, MessageLevel, ModalOptions, ToastOptions, Theme, ThemeMode, ViewSDK, } from './view';
+export type { DataSDK, GraphQLRequest, GraphQLResponse } from './data';
+export type { LightningSDK, LMSMessage, LMSSubscription, MessageChannel } from './lightning';
+export type { OpenAISDK, SalesforceACCSDK } from './platforms';
+export type { JsonRpcBase, JsonRpcRequest, JsonRpcError, JsonRpcSuccessResponse, JsonRpcErrorResponse, JsonRpcResponse, JsonRpcNotification, JsonRpcMessage, JsonRpcPendingRequest, JsonRpcPendingRequestMap, } from './jsonrpc';
+export { isJsonRpcBase, isJsonRpcSuccessResponse, isJsonRpcErrorResponse, isJsonRpcResponse, isJsonRpcNotification, isJsonRpcRequest, } from './jsonrpc';
+export { JsonRpcClient, WindowPostMessageTransport } from './jsonrpc-client';
+export type { Transport } from './jsonrpc-client';
+export { MessageChannelTransport, type MessageChannelTransportListener, } from './mfe-protocol/message-channel-transport';
+export { McpAppsSession } from './mcpapps-session';
+export type { McpAppsHostContext, McpAppsSessionOptions } from './mcpapps-session';
+export { getSurfaceCapabilities } from './capabilities';
+export type { SurfaceCapabilities } from './capabilities';
+export { wrapSDKPromise } from './sdk-promise';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/core/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,EAAE,OAAO,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AAGhD,YAAY,EAAE,aAAa,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAGvF,YAAY,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AAG5C,YAAY,EACX,WAAW,EACX,UAAU,EACV,WAAW,EACX,OAAO,EACP,kBAAkB,EAClB,WAAW,EACX,eAAe,EACf,cAAc,EACd,QAAQ,EACR,SAAS,GACT,MAAM,QAAQ,CAAC;AAGhB,YAAY,EACX,YAAY,EACZ,YAAY,EACZ,YAAY,EACZ,YAAY,EACZ,KAAK,EACL,SAAS,EACT,OAAO,GACP,MAAM,QAAQ,CAAC;AAGhB,YAAY,EAAE,OAAO,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,QAAQ,CAAC;AAGvE,YAAY,EAAE,YAAY,EAAE,UAAU,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAG7F,YAAY,EAAE,SAAS,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAG/D,YAAY,EACX,WAAW,EACX,cAAc,EACd,YAAY,EACZ,sBAAsB,EACtB,oBAAoB,EACpB,eAAe,EACf,mBAAmB,EACnB,cAAc,EACd,qBAAqB,EACrB,wBAAwB,GACxB,MAAM,WAAW,CAAC;AAEnB,OAAO,EACN,aAAa,EACb,wBAAwB,EACxB,sBAAsB,EACtB,iBAAiB,EACjB,qBAAqB,EACrB,gBAAgB,GAChB,MAAM,WAAW,CAAC;AAEnB,OAAO,EAAE,aAAa,EAAE,0BAA0B,EAAE,MAAM,kBAAkB,CAAC;AAC7E,YAAY,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAKlD,OAAO,EACN,uBAAuB,EACvB,KAAK,+BAA+B,GACpC,MAAM,0CAA0C,CAAC;AAGlD,OAAO,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AACnD,YAAY,EAAE,kBAAkB,EAAE,qBAAqB,EAAE,MAAM,mBAAmB,CAAC;AAGnF,OAAO,EAAE,sBAAsB,EAAE,MAAM,gBAAgB,CAAC;AACxD,YAAY,EAAE,mBAAmB,EAAE,MAAM,gBAAgB,CAAC;AAG1D,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC"}

package/dist/core/jsonrpc-client.d.ts

@@ -0,0 +1,167 @@
+/**
+ * Abstract transport for a JSON-RPC 2.0 client.
+ *
+ * A `Transport` is a bidirectional, structured-message pipe. The `JsonRpcClient`
+ * uses it to send JSON-RPC messages (`post`) and subscribe to inbound ones
+ * (`onMessage`). The transport itself is agnostic to the JSON-RPC framing —
+ * it simply moves `unknown` payloads between two endpoints.
+ *
+ * This abstraction exists so `JsonRpcClient` can be driven by either the
+ * `window.parent.postMessage` channel (default, preserved for existing MCP
+ * Apps iframes) or a `MessagePort`-backed transport (used by newer
+ * microfrontend containers that receive a dedicated channel during
+ * bootstrap).
+ */
+export interface Transport {
+    /**
+     * Deliver a single structured message to the peer. Implementations MUST NOT
+     * throw on transient conditions (a closed port, a missing parent window,
+     * etc.) — drop the message silently instead, matching the prior
+     * `window.parent?.postMessage` behaviour.
+     */
+    post(message: unknown): void;
+    /**
+     * Subscribe to inbound structured messages from the peer. The callback
+     * receives the already-unwrapped message payload (never a `MessageEvent`).
+     *
+     * @returns an unsubscribe function that removes this listener.
+     */
+    onMessage(callback: (message: unknown) => void): () => void;
+}
+/**
+ * Default `Transport` backing the JSON-RPC client in an iframe context.
+ *
+ * Outbound messages go to `window.parent` via `postMessage(msg, targetOrigin)`,
+ * and inbound messages come from `window.addEventListener("message", ...)`
+ * with only the `event.data` payload forwarded to subscribers.
+ *
+ * The `targetOrigin` passed to `postMessage` is configurable and defaults to
+ * `"*"` to preserve the pre-refactor wire behaviour. Callers embedding the
+ * iframe should pin this to the expected parent origin when it is known, so
+ * that messages cannot leak to a parent that has been navigated to a
+ * different origin since the iframe loaded.
+ *
+ * Missing `window.parent` (e.g. top-level document) is tolerated: `post` is a
+ * no-op, matching the prior optional-chaining behaviour.
+ */
+export declare class WindowPostMessageTransport implements Transport {
+    private readonly targetOrigin;
+    /**
+     * @param targetOrigin - origin passed as the second argument to
+     *   `window.parent.postMessage`. Defaults to `"*"` for backwards
+     *   compatibility. Pin to the known parent origin when possible to
+     *   prevent leaking messages to a cross-origin navigated parent.
+     */
+    constructor(targetOrigin?: string);
+    post(message: unknown): void;
+    onMessage(callback: (message: unknown) => void): () => void;
+}
+/**
+ * Base class for JSON-RPC 2.0 clients.
+ *
+ * This class provides core JSON-RPC client functionality for MCP Apps and
+ * sf-mfe implementations. It handles request/response correlation, message
+ * validation, and error handling.
+ *
+ * The transport layer is pluggable via the `Transport` interface. By default
+ * the client uses `WindowPostMessageTransport`, which preserves the original
+ * `window.parent.postMessage` wire behaviour. Callers can inject a different
+ * transport (e.g. a `MessageChannelTransport`) without changing any of the
+ * request/response semantics below.
+ *
+ * Subclasses should extend this class and use the protected `request()` method
+ * to send JSON-RPC requests to the peer.
+ *
+ * @example
+ * export class MCPAppsViewSDK extends JsonRpcClient implements ViewSDK {
+ *   async displayAlert(options: AlertOptions): Promise<void> {
+ *     await this.request("ui/message", {
+ *       role: "user",
+ *       content: { type: "text", text: options.message }
+ *     });
+ *   }
+ * }
+ *
+ * @example
+ * // Injecting a custom transport (e.g. for a MessageChannel-based flow).
+ * class MyClient extends JsonRpcClient {
+ *   constructor(transport: Transport) { super(transport); }
+ * }
+ */
+export declare class JsonRpcClient {
+    private nextRequestId;
+    private pending;
+    private notificationHandlers;
+    private readonly transport;
+    /**
+     * Construct a JSON-RPC client bound to the given transport.
+     *
+     * @param transport - the transport to use; defaults to a
+     *   `WindowPostMessageTransport`, which preserves the original
+     *   `window.parent.postMessage` behaviour.
+     */
+    constructor(transport?: Transport);
+    /**
+     * Register a handler for a specific JSON-RPC notification method
+     *
+     * Subclasses can register handlers to process specific notification types.
+     * When a notification with the registered method is received, the handler
+     * will be invoked with the notification params.
+     *
+     * @param method - The notification method to handle (e.g. "ui/notifications/host-context-changed")
+     * @param handler - Callback function to process the notification params
+     *
+     * @example
+     * this.registerNotificationHandler("ui/notifications/host-context-changed", (params) => {
+     *   this.handleHostContextChanged(params);
+     * });
+     */
+    protected registerNotificationHandler(method: string, handler: (params: unknown) => void): void;
+    /**
+     * Handle inbound JSON-RPC messages from the transport.
+     *
+     * Processes both responses (for requests) and notifications. Non-JSON-RPC
+     * payloads are silently ignored so that a shared transport can be used for
+     * multiple protocols without cross-talk.
+     */
+    private onMessage;
+    /**
+     * Send a JSON-RPC request to the peer.
+     *
+     * @param method - The JSON-RPC method name
+     * @param params - The method parameters
+     * @returns Promise that resolves with the result or rejects with error
+     *
+     * @example
+     * const result = await this.request("ui/message", {
+     *   role: "user",
+     *   content: { type: "text", text: "Hello" }
+     * });
+     */
+    protected request<TParams = unknown, TResult = unknown>(method: string, params: TParams): Promise<TResult>;
+    /**
+     * Send a JSON-RPC notification to the peer.
+     *
+     * Notifications are one-way messages that do not expect a response.
+     * Use notifications for:
+     * - Informing the host of state changes
+     * - Fire-and-forget operations
+     * - Events that don't require confirmation
+     *
+     * Use request() instead when you need:
+     * - A response from the host
+     * - Confirmation of success/failure
+     * - Return values from the operation
+     *
+     * @param method - The JSON-RPC method name
+     * @param params - Optional method parameters
+     *
+     * @example
+     * this.sendNotification("ui/notifications/size-changed", {
+     *   width: 800,
+     *   height: 600
+     * });
+     */
+    protected sendNotification<TParams = unknown>(method: string, params?: TParams): void;
+}
+//# sourceMappingURL=jsonrpc-client.d.ts.map

package/dist/core/jsonrpc-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"jsonrpc-client.d.ts","sourceRoot":"","sources":["../../src/core/jsonrpc-client.ts"],"names":[],"mappings":"AAQA;;;;;;;;;;;;;GAaG;AACH,MAAM,WAAW,SAAS;IACzB;;;;;OAKG;IAEH,IAAI,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAAC;IAE7B;;;;;OAKG;IACH,SAAS,CAAC,QAAQ,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,IAAI,GAAG,MAAM,IAAI,CAAC;CAC5D;AAED;;;;;;;;;;;;;;;GAeG;AACH,qBAAa,0BAA2B,YAAW,SAAS;IAC3D,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAS;IAEtC;;;;;OAKG;gBACS,YAAY,SAAM;IAI9B,IAAI,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI;IAI5B,SAAS,CAAC,QAAQ,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,IAAI,GAAG,MAAM,IAAI;CAO3D;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,qBAAa,aAAa;IACzB,OAAO,CAAC,aAAa,CAAK;IAC1B,OAAO,CAAC,OAAO,CAAuC;IACtD,OAAO,CAAC,oBAAoB,CAAqD;IACjF,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAY;IAEtC;;;;;;OAMG;gBACS,SAAS,GAAE,SAA4C;IAMnE;;;;;;;;;;;;;;OAcG;IACH,SAAS,CAAC,2BAA2B,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,MAAM,EAAE,OAAO,KAAK,IAAI,GAAG,IAAI;IAO/F;;;;;;OAMG;IACH,OAAO,CAAC,SAAS,CA0Bf;IAEF;;;;;;;;;;;;OAYG;IACH,SAAS,CAAC,OAAO,CAAC,OAAO,GAAG,OAAO,EAAE,OAAO,GAAG,OAAO,EACrD,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,OAAO,GACb,OAAO,CAAC,OAAO,CAAC;IAkBnB;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH,SAAS,CAAC,gBAAgB,CAAC,OAAO,GAAG,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,OAAO,GAAG,IAAI;CAQrF"}

package/dist/core/jsonrpc.d.ts

@@ -0,0 +1,123 @@
+/**
+ * Copyright (c) 2026, Salesforce, Inc.,
+ * All rights reserved.
+ * For full license text, see the LICENSE.txt file
+ */
+/**
+ * JSON-RPC 2.0 Protocol Types
+ *
+ * This module provides TypeScript types and utilities for implementing
+ * JSON-RPC 2.0 protocol as specified in https://www.jsonrpc.org/specification
+ *
+ * JSON-RPC 2.0 is a stateless, light-weight remote procedure call (RPC) protocol.
+ * Used for iframe communication via postMessage in MCP Apps surface.
+ *
+ * @example
+ * // Creating a request
+ * const request: JsonRpcRequest = {
+ *   jsonrpc: "2.0",
+ *   id: 1,
+ *   method: "ui/message",
+ *   params: { role: "user", content: { type: "text", text: "Hello" } }
+ * };
+ * window.parent.postMessage(request, "*");
+ *
+ * @example
+ * // Validating a response
+ * window.addEventListener("message", (event) => {
+ *   if (isJsonRpcResponse(event.data)) {
+ *     if (isJsonRpcErrorResponse(event.data)) {
+ *       console.error("Error:", event.data.error.message);
+ *     } else {
+ *       console.log("Result:", event.data.result);
+ *     }
+ *   }
+ * });
+ */
+/**
+ * JSON-RPC 2.0 base message with required version field
+ */
+export interface JsonRpcBase {
+    jsonrpc: "2.0";
+}
+/**
+ * JSON-RPC 2.0 Request with numeric ID (per spec)
+ */
+export interface JsonRpcRequest<TParams = unknown> extends JsonRpcBase {
+    id: number;
+    method: string;
+    params?: TParams;
+}
+/**
+ * JSON-RPC 2.0 Error object structure
+ */
+export interface JsonRpcError {
+    code: number;
+    message?: string;
+    data?: unknown;
+}
+/**
+ * JSON-RPC 2.0 Success Response
+ */
+export interface JsonRpcSuccessResponse<TResult = unknown> extends JsonRpcBase {
+    id: number;
+    result: TResult;
+}
+/**
+ * JSON-RPC 2.0 Error Response
+ */
+export interface JsonRpcErrorResponse extends JsonRpcBase {
+    id: number;
+    error: JsonRpcError;
+}
+/**
+ * JSON-RPC 2.0 Notification (no id, no response expected)
+ */
+export interface JsonRpcNotification<TParams = unknown> extends JsonRpcBase {
+    method: string;
+    params?: TParams;
+}
+/**
+ * Union of all JSON-RPC response types
+ */
+export type JsonRpcResponse<TResult = unknown> = JsonRpcSuccessResponse<TResult> | JsonRpcErrorResponse;
+/**
+ * Union of all JSON-RPC message types
+ */
+export type JsonRpcMessage<TRequest = unknown, TResponse = unknown> = JsonRpcRequest<TRequest> | JsonRpcResponse<TResponse> | JsonRpcNotification;
+/**
+ * Pending request resolver functions
+ */
+export interface JsonRpcPendingRequest {
+    resolve: (value: unknown) => void;
+    reject: (error: unknown) => void;
+}
+/**
+ * Map of pending JSON-RPC requests by numeric ID
+ */
+export type JsonRpcPendingRequestMap = Map<number, JsonRpcPendingRequest>;
+/**
+ * Type guard to check if message is valid JSON-RPC 2.0 base
+ */
+export declare function isJsonRpcBase(data: unknown): data is JsonRpcBase;
+/**
+ * Type guard for JSON-RPC success response
+ */
+export declare function isJsonRpcSuccessResponse(data: unknown): data is JsonRpcSuccessResponse;
+/**
+ * Type guard for JSON-RPC error response
+ */
+export declare function isJsonRpcErrorResponse(data: unknown): data is JsonRpcErrorResponse;
+/**
+ * Type guard for any JSON-RPC response (success or error)
+ */
+export declare function isJsonRpcResponse(data: unknown): data is JsonRpcResponse;
+/**
+ * Type guard for JSON-RPC notification
+ */
+export declare function isJsonRpcNotification(data: unknown): data is JsonRpcNotification;
+/**
+ * Type guard for JSON-RPC request
+ */
+export declare function isJsonRpcRequest(data: unknown): data is JsonRpcRequest;
+//# sourceMappingURL=jsonrpc.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"jsonrpc.d.ts","sourceRoot":"","sources":["../../src/core/jsonrpc.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAEH;;GAEG;AACH,MAAM,WAAW,WAAW;IAC3B,OAAO,EAAE,KAAK,CAAC;CACf;AAED;;GAEG;AACH,MAAM,WAAW,cAAc,CAAC,OAAO,GAAG,OAAO,CAAE,SAAQ,WAAW;IACrE,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,OAAO,CAAC;CACjB;AAED;;GAEG;AACH,MAAM,WAAW,YAAY;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,IAAI,CAAC,EAAE,OAAO,CAAC;CACf;AAED;;GAEG;AACH,MAAM,WAAW,sBAAsB,CAAC,OAAO,GAAG,OAAO,CAAE,SAAQ,WAAW;IAC7E,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE,OAAO,CAAC;CAChB;AAED;;GAEG;AACH,MAAM,WAAW,oBAAqB,SAAQ,WAAW;IACxD,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,YAAY,CAAC;CACpB;AAED;;GAEG;AACH,MAAM,WAAW,mBAAmB,CAAC,OAAO,GAAG,OAAO,CAAE,SAAQ,WAAW;IAC1E,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,OAAO,CAAC;CACjB;AAED;;GAEG;AACH,MAAM,MAAM,eAAe,CAAC,OAAO,GAAG,OAAO,IAC1C,sBAAsB,CAAC,OAAO,CAAC,GAC/B,oBAAoB,CAAC;AAExB;;GAEG;AACH,MAAM,MAAM,cAAc,CAAC,QAAQ,GAAG,OAAO,EAAE,SAAS,GAAG,OAAO,IAC/D,cAAc,CAAC,QAAQ,CAAC,GACxB,eAAe,CAAC,SAAS,CAAC,GAC1B,mBAAmB,CAAC;AAEvB;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACrC,OAAO,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC;IAClC,MAAM,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC;CACjC;AAED;;GAEG;AACH,MAAM,MAAM,wBAAwB,GAAG,GAAG,CAAC,MAAM,EAAE,qBAAqB,CAAC,CAAC;AAE1E;;GAEG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,OAAO,GAAG,IAAI,IAAI,WAAW,CAOhE;AAED;;GAEG;AACH,wBAAgB,wBAAwB,CAAC,IAAI,EAAE,OAAO,GAAG,IAAI,IAAI,sBAAsB,CAOtF;AAED;;GAEG;AACH,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,OAAO,GAAG,IAAI,IAAI,oBAAoB,CAOlF;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,OAAO,GAAG,IAAI,IAAI,eAAe,CAExE;AAED;;GAEG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,OAAO,GAAG,IAAI,IAAI,mBAAmB,CAOhF;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,OAAO,GAAG,IAAI,IAAI,cAAc,CAQtE"}

package/dist/core/lightning.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Copyright (c) 2026, Salesforce, Inc.,
+ * All rights reserved.
+ * For full license text, see the LICENSE.txt file
+ */
+/**
+ * Lightning Message Service message payload
+ */
+export type LMSMessage = Record<string, unknown>;
+/**
+ * Lightning Message Service subscription
+ */
+export interface LMSSubscription {
+    unsubscribe: () => void;
+}
+/**
+ * Lightning Message Service channel configuration
+ */
+export interface MessageChannel {
+    channelName: string;
+}
+/**
+ * Lightning SDK interface for Lightning Web Component runtime integration
+ */
+export interface LightningSDK {
+    /**
+     * Publish a message to a Lightning Message Service channel
+     *
+     * @param channel - Message channel configuration
+     * @param message - Message payload to publish
+     */
+    publishLmsMessage?: <M extends LMSMessage>(channel: MessageChannel, message: M) => void;
+    /**
+     * Subscribe to a Lightning Message Service channel
+     *
+     * @param channel - Message channel configuration
+     * @param callback - Callback function to handle received messages
+     * @returns Subscription object with unsubscribe method
+     */
+    subscribeToLmsChannel?: <M extends LMSMessage>(channel: MessageChannel, callback: (message: M) => void) => LMSSubscription;
+}
+//# sourceMappingURL=lightning.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"lightning.d.ts","sourceRoot":"","sources":["../../src/core/lightning.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH;;GAEG;AACH,MAAM,MAAM,UAAU,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAEjD;;GAEG;AACH,MAAM,WAAW,eAAe;IAC/B,WAAW,EAAE,MAAM,IAAI,CAAC;CACxB;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC9B,WAAW,EAAE,MAAM,CAAC;CACpB;AAED;;GAEG;AACH,MAAM,WAAW,YAAY;IAC5B;;;;;OAKG;IACH,iBAAiB,CAAC,EAAE,CAAC,CAAC,SAAS,UAAU,EAAE,OAAO,EAAE,cAAc,EAAE,OAAO,EAAE,CAAC,KAAK,IAAI,CAAC;IAExF;;;;;;OAMG;IACH,qBAAqB,CAAC,EAAE,CAAC,CAAC,SAAS,UAAU,EAC5C,OAAO,EAAE,cAAc,EACvB,QAAQ,EAAE,CAAC,OAAO,EAAE,CAAC,KAAK,IAAI,KAC1B,eAAe,CAAC;CACrB"}