@salesforce/platform-sdk 9.12.1 → 9.13.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@salesforce/platform-sdk",
-  "version": "9.12.1",
+  "version": "9.13.0",
   "license": "SEE LICENSE IN LICENSE.txt",
   "type": "module",
   "main": "./dist/index.js",
@@ -35,7 +35,8 @@
     "@conduit-client/service-fetch-network": "3.19.6",
     "@conduit-client/service-pubsub": "3.19.6",
     "@conduit-client/service-retry": "3.19.6",
-    "@conduit-client/utils": "3.19.6"
+    "@conduit-client/utils": "3.19.6",
+    "@salesforce/jsonrpc": "^9.13.0"
   },
   "peerDependencies": {
     "o11y": ">=260.0.0",

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

@@ -1,167 +0,0 @@
-/**
- * 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

@@ -1 +0,0 @@
-{"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

@@ -1,123 +0,0 @@
-/**
- * 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

@@ -1 +0,0 @@
-{"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/mfe-protocol/message-channel-transport.d.ts

@@ -1,79 +0,0 @@
-import { Transport } from '../jsonrpc-client';
-/**
- * Subscriber callback invoked for each unwrapped payload delivered on the
- * port. Receivers get the `MessageEvent.data` directly — they do not need
- * to reach into a `MessageEvent` wrapper.
- */
-export type MessageChannelTransportListener = (msg: unknown) => void;
-/**
- * MFE-side `Transport` backed by a `MessagePort`.
- *
- * During the MFE handshake, the iframe receives a transferred `MessagePort`
- * (`event.ports[0]`) in the single bootstrap envelope posted by the host.
- * That port is the `port1` half of the host's `MessageChannel`. Wrapping it
- * in this class produces the same `Transport` shape that `JsonRpcClient`
- * already consumes, so callers can swap in MessagePort-backed traffic
- * without changing any of the JSON-RPC request/response/notification
- * semantics.
- *
- * The implementation mirrors the host-side `MessageChannelTransport` that
- * ships from `packages/core/src/MessageChannelTransport.ts` in the
- * `ui-embedding` repo. Both sides MUST honour the same contract so one
- * `JsonRpcClient` can drive either end.
- *
- * Contract (symmetric with the host-side transport, and with the
- * `Transport` interface defined next to `WindowPostMessageTransport`):
- *
- *  - `post(msg)` never throws on transient failure. A closed / neutered /
- *    disposed port silently drops the message. This matches the
- *    optional-chaining behaviour of `WindowPostMessageTransport.post`.
- *  - `onMessage(cb)` delivers the **unwrapped** payload (`MessageEvent.data`),
- *    not the raw `MessageEvent`. Returns an unsubscribe function.
- *  - The port is started (`port.start()`) lazily on the first `onMessage`
- *    subscription. Messages queued via `post` before that first subscribe
- *    are buffered in-process and flushed FIFO when the port starts.
- *  - `dispose()` removes listeners, closes the port, clears the outbound
- *    buffer, and puts the transport into a terminal state where further
- *    `post` calls silently no-op and further `onMessage` calls return a
- *    no-op unsubscribe.
- *
- * Usage from the container bootstrap:
- * ```ts
- * const transport = new MessageChannelTransport(event.ports[0]);
- * // Hand the transport to the session layer; subscription drives start().
- * ```
- */
-export declare class MessageChannelTransport implements Transport {
-    #private;
-    constructor(port: MessagePort);
-    /**
-     * Post a message to the peer.
-     *
-     * Never throws on transient failure — a closed / neutered / disposed
-     * port silently drops the message. If the transport has not yet
-     * started (no `onMessage` subscriber), the message is buffered and
-     * flushed on first subscription.
-     */
-    post(message: unknown): void;
-    /**
-     * Subscribe to inbound messages from the peer. The callback receives
-     * the **unwrapped** payload (`MessageEvent.data`) — callers never see
-     * the `MessageEvent` wrapper.
-     *
-     * Starts the underlying port on first subscription and flushes any
-     * messages queued via `post` before the port was started.
-     *
-     * Returns an unsubscribe function. Calling it is idempotent.
-     */
-    onMessage(callback: MessageChannelTransportListener): () => void;
-    /**
-     * Tear down the transport:
-     *  - remove the internal `message` listener
-     *  - call `port.close()`
-     *  - clear subscriber set and outbound buffer
-     *  - subsequent `post` calls silently no-op
-     *  - subsequent `onMessage` calls return a no-op unsubscribe
-     */
-    dispose(): void;
-}
-//# sourceMappingURL=message-channel-transport.d.ts.map

package/dist/core/mfe-protocol/message-channel-transport.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"message-channel-transport.d.ts","sourceRoot":"","sources":["../../../src/core/mfe-protocol/message-channel-transport.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC;AAEnD;;;;GAIG;AACH,MAAM,MAAM,+BAA+B,GAAG,CAAC,GAAG,EAAE,OAAO,KAAK,IAAI,CAAC;AAUrE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,qBAAa,uBAAwB,YAAW,SAAS;;gBAQ5C,IAAI,EAAE,WAAW;IAI7B;;;;;;;OAOG;IACH,IAAI,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI;IAqB5B;;;;;;;;;OASG;IACH,SAAS,CAAC,QAAQ,EAAE,+BAA+B,GAAG,MAAM,IAAI;IAoBhE;;;;;;;OAOG;IACH,OAAO,IAAI,IAAI;CAyDf"}