@salesforce/sf-embedding-bridge 2.2.1-rc.8 → 2.2.3-rc.0

package/dist/index.d.ts

@@ -24,6 +24,8 @@ interface HeartbeatEnvelope {
     type: typeof HEARTBEAT_TYPE;
     /** Mirrors the URL-supplied `hostMetaData.instanceId`; binds the heartbeat to this iframe instance. */
     instanceId: string;
+    /** SemVer protocol version the bridge speaks; host validates against its supported set. */
+    protocolVersion: string;
 }
 /** Embedding-initiated fail-closed shutdown payload (sibling-race detected, etc.). */
 interface ShutdownEnvelope {
@@ -57,6 +59,28 @@ type SfEmbeddingErrorCodeValue = (typeof SfEmbeddingErrorCode)[keyof typeof SfEm
  */
 declare const NON_RETRYABLE_CODES: ReadonlySet<number>;
 
+declare const EVENTS_DISPATCH_METHOD: "ui/events/dispatch";
+declare const EVENTS_SUBSCRIBE_METHOD: "ui/events/subscribe";
+declare const EVENTS_UNSUBSCRIBE_METHOD: "ui/events/unsubscribe";
+interface EventsDispatchParams {
+    eventType: string;
+    detail: unknown;
+    /** Whether the dispatched DOM event bubbles. Default: true. */
+    bubbles?: boolean;
+    /** Whether the dispatched DOM event crosses shadow-DOM boundaries. Default: true. */
+    composed?: boolean;
+    /** Whether the dispatched DOM event is cancelable via `preventDefault()`. Default: false. */
+    cancelable?: boolean;
+}
+interface EventsSubscribeParams {
+}
+interface EventsSubscribeResult {
+    subscriptionId: string;
+}
+interface EventsUnsubscribeParams {
+    subscriptionId: string;
+}
+
 /** Event names the host LWC dispatches on its own element. Reserved by the protocol. */
 declare const HostLwcEvent: {
     /** Synchronous with `ui/discover-capabilities` response; session reaches READY. */
@@ -105,6 +129,12 @@ interface HostMetaData {
     instanceId: string;
 }
 
+/** Throw from a request handler to surface a specific JSON-RPC error code. */
+declare class JsonRpcHandlerError extends Error {
+    readonly code: number;
+    constructor(code: number, message: string);
+}
+
 /** Host announces session identity to the embedding over the port. */
 declare const HOST_INITIALIZED_METHOD: "ui/notifications/host-initialized";
 /** Embedding acknowledges receipt of `host-initialized`. Fire-and-forget. */
@@ -124,6 +154,47 @@ interface EmbeddingInitializedParams {
     embeddingInfo: PeerInfo;
 }
 
+declare const RESIZE_METHOD: "ui/notifications/resize";
+interface ResizeParams {
+    width?: number;
+    height: number;
+}
+
+declare const UI_STATE_SUBSCRIBE_METHOD: "ui/subscribe/ui-state";
+declare const UI_STATE_UNSUBSCRIBE_METHOD: "ui/unsubscribe/ui-state";
+declare const UI_STATE_CHANGED_METHOD: "ui/notifications/ui-state-changed";
+/** Styling hints the host wants the embedding to mirror. */
+interface HostStyles {
+    /** CSS custom properties (`--*`) read from the host element's inline style. */
+    variables?: Record<string, string>;
+    /** Mirrored a11y/i18n/input attributes from the host LWC element. */
+    attributes?: Record<string, string>;
+}
+/** Host → embedding rendering snapshot. */
+interface UiState {
+    props: Record<string, unknown>;
+    styles: HostStyles;
+    theme: string;
+    locale: {
+        tag: string;
+        dir: "ltr" | "rtl";
+    };
+    formFactor: "Small" | "Medium" | "Large";
+}
+interface UiStateSubscribeParams {
+}
+interface UiStateSubscribeResult {
+    subscriptionId: string;
+    current: UiState;
+}
+interface UiStateUnsubscribeParams {
+    subscriptionId: string;
+}
+interface UiStateChangedParams {
+    subscriptionId: string;
+    current: UiState;
+}
+
 type BootstrapEnvelopeValidationFailure = "INVALID_SHAPE" | "WRONG_SOURCE" | "ORIGIN_NOT_ALLOWED" | "WRONG_PORT_COUNT" | "INSTANCE_ID_MISMATCH" | "DUPLICATE_TRANSFER";
 type BootstrapEnvelopeValidationResult = {
     ok: true;
@@ -154,6 +225,111 @@ declare class BootstrapFailureError extends Error {
     constructor(reason: BootstrapFailureReason);
 }
 
+/**
+ * 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 runtime guards for implementing
+ * JSON-RPC 2.0 as specified in https://www.jsonrpc.org/specification.
+ *
+ * JSON-RPC 2.0 is a stateless, light-weight remote procedure call (RPC)
+ * protocol. Used for cross-realm communication via postMessage in iframe-
+ * embedded surfaces (MCP Apps, sf-embedding, and any future surface that
+ * speaks the same wire format).
+ *
+ * Protocol extension: this module relaxes JSON-RPC 2.0's "no other
+ * members" rule for one optional `_meta` field on every envelope. The
+ * underscore signals "protocol-meta, not method semantics." `_meta`
+ * carries fields applying to every method uniformly (currently `traceId`);
+ * method-specific data lives in `params` / `result` / `error`.
+ *
+ * @example
+ * // Creating a request
+ * const request: JsonRpcRequest = {
+ *   jsonrpc: "2.0",
+ *   id: 1,
+ *   method: "ui/message",
+ *   params: { role: "user", content: { type: "text", text: "Hello" } }
+ * };
+ *
+ * @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);
+ *     }
+ *   }
+ * });
+ */
+/**
+ * Protocol-meta envelope. Future minors may add fields additively; old peers
+ * ignore unknown fields per the standard JSON-RPC forward-compat behavior.
+ */
+interface JsonRpcMeta {
+    /** Per-request trace identifier for cross-realm log correlation. */
+    traceId?: string;
+}
+/**
+ * JSON-RPC 2.0 base message with the required version field and the
+ * optional `_meta` extension.
+ */
+interface JsonRpcBase {
+    jsonrpc: "2.0";
+    _meta?: JsonRpcMeta;
+}
+/**
+ * JSON-RPC 2.0 Request — has both `id` and `method`.
+ */
+interface JsonRpcRequest<TParams = unknown> extends JsonRpcBase {
+    id: number;
+    method: string;
+    params?: TParams;
+}
+/**
+ * JSON-RPC 2.0 Notification — has `method` but NO `id`. Fire-and-forget.
+ */
+interface JsonRpcNotification<TParams = unknown> extends JsonRpcBase {
+    method: string;
+    params?: TParams;
+}
+/**
+ * JSON-RPC 2.0 Success Response — has `id` and `result`.
+ */
+interface JsonRpcSuccessResponse<TResult = unknown> extends JsonRpcBase {
+    id: number;
+    result: TResult;
+}
+/**
+ * JSON-RPC 2.0 Error payload (carried under `error` on an error response).
+ */
+interface JsonRpcError {
+    code: number;
+    message?: string;
+    data?: unknown;
+}
+/**
+ * JSON-RPC 2.0 Error Response — has `id` and `error`.
+ */
+interface JsonRpcErrorResponse extends JsonRpcBase {
+    id: number;
+    error: JsonRpcError;
+}
+/**
+ * Either flavor of response.
+ */
+type JsonRpcResponse<TResult = unknown> = JsonRpcSuccessResponse<TResult> | JsonRpcErrorResponse;
+/**
+ * Any JSON-RPC frame the dispatcher might receive.
+ */
+type JsonRpcFrame = JsonRpcRequest | JsonRpcNotification | JsonRpcResponse;
+
 /**
  * Copyright (c) 2026, Salesforce, Inc.,
  * All rights reserved.
@@ -255,7 +431,7 @@ declare class JsonRpcClient {
      *   this.handleHostContextChanged(params);
      * });
      */
-    protected registerNotificationHandler(method: string, handler: (params: unknown) => void): void;
+    protected registerNotificationHandler(method: string, handler: (params: unknown, meta?: JsonRpcMeta) => void): void;
     /**
      * Handle inbound JSON-RPC messages from the transport.
      *
@@ -302,6 +478,23 @@ declare class JsonRpcClient {
      * });
      */
     protected sendNotification<TParams = unknown>(method: string, params?: TParams): void;
+    /**
+     * Outbound `_meta` hook. Override to attach protocol-meta (e.g. a
+     * per-message `traceId`) to every outgoing request and notification.
+     *
+     * Default returns `undefined` so the envelope ships without `_meta`,
+     * matching JSON-RPC 2.0 baseline behavior.
+     */
+    protected getOutboundMeta(_method: string): JsonRpcMeta | undefined;
+    /**
+     * Inbound `_meta` hook. Invoked once per validated inbound frame
+     * (response or notification) before the value is dispatched to the
+     * pending-request resolver or notification handlers.
+     *
+     * Default is a no-op. Override to feed log correlation, tracing, etc.
+     */
+    protected onInboundMeta(_frame: JsonRpcFrame, _meta: JsonRpcMeta | undefined): void;
+    private applyOutboundMeta;
 }
 
 /** Structure of the `data` field on a JSON-RPC error payload. */
@@ -316,9 +509,152 @@ interface JsonRpcErrorPayload {
     data?: JsonRpcErrorData;
 }
 
+/**
+ * EmbeddingResizer - Handles dynamic iframe/container resizing
+ * Uses ResizeObserver to monitor element size changes and notify the host
+ */
+interface ResizeCallback {
+    (height: number): void;
+}
+interface EmbeddingResizerOptions {
+    /**
+     * The element to observe for size changes
+     * Defaults to document.body
+     */
+    targetElement?: Element;
+    /**
+     * Callback function invoked when resize is detected
+     */
+    onResize: ResizeCallback;
+    /**
+     * Callback function invoked when the resizer is ready
+     */
+    onReady?: () => void;
+    /**
+     * Whether to wait for DOMContentLoaded before starting observation
+     * Defaults to true
+     */
+    waitForDOMReady?: boolean;
+}
+declare class EmbeddingResizer {
+    #private;
+    constructor(options: EmbeddingResizerOptions);
+    /**
+     * Start observing the target element for size changes
+     */
+    start(): void;
+    /**
+     * Stop observing and clean up resources
+     */
+    stop(): void;
+    /**
+     * Get the current observed height
+     */
+    getLastHeight(): number;
+    /**
+     * Check if currently observing
+     */
+    isObserving(): boolean;
+}
+
+/**
+ * JSON-RPC plumbing shared by both peers of the sf-embedding protocol.
+ *
+ * Two layers live here:
+ *
+ *  - `BridgeClient` — the OUTBOUND half plus inbound responses/notifications.
+ *    Extends the library `JsonRpcClient`, so it already correlates outbound
+ *    `send()` requests with their inbound responses, dispatches inbound
+ *    notifications to `onNotification` handlers, and stamps every outbound
+ *    frame with a `_meta.traceId`. It owns the single `Transport`.
+ *
+ *  - `JsonRpcRouter` — the INBOUND-REQUEST half. It HOLDS a `BridgeClient`
+ *    and adds the one thing the client deliberately lacks: routing inbound
+ *    JSON-RPC *requests* to registered handlers and replying success/error
+ *    on the same transport (echoing `_meta` for tracing). Notifications,
+ *    responses, and outbound traffic are delegated straight to the client —
+ *    no duplicate handler tables.
+ *
+ * Request vs response/notification dispatch does not collide on the shared
+ * transport: `JsonRpcClient` ignores frames carrying both an `id` and a
+ * `method` (requests), so the router is free to claim them.
+ *
+ * Each peer subclasses `JsonRpcRouter` (see `HostBridge` /
+ * `EmbeddingBridge`): the subclass registers its inbound handlers in the
+ * constructor and exposes named methods for its outbound requests.
+ */
+
+/** Function signature for an inbound-request handler. */
+type RequestHandler<TParams = unknown, TResult = unknown> = (params: TParams, meta?: JsonRpcMeta) => TResult | Promise<TResult>;
+/** Function signature for an inbound-notification handler. */
+type NotificationHandler<TParams = unknown> = (params: TParams, meta?: JsonRpcMeta) => void;
+/** Disposer returned by `onRequest`. */
+type Unregister = () => void;
+/**
+ * Outbound + response/notification half of a JSON-RPC peer, bound to one
+ * transport. Promotes the library client's `protected` send/notify/register
+ * methods to a `public` surface the router (and its subclasses) can call, and
+ * exposes `post`/`subscribe` so the router can reply to and listen for inbound
+ * requests over the same transport.
+ *
+ * Stamps `_meta.traceId` on every outbound frame; both peers want tracing.
+ */
+declare class BridgeClient extends JsonRpcClient {
+    private readonly sharedTransport;
+    constructor(transport: Transport);
+    /** Send a request and await its correlated response. */
+    send<TParams = unknown, TResult = unknown>(method: string, params: TParams): Promise<TResult>;
+    /** Send a fire-and-forget notification. */
+    notify<TParams = unknown>(method: string, params?: TParams): void;
+    /** Register an inbound-notification handler. */
+    onNotification<TParams = unknown>(method: string, handler: NotificationHandler<TParams>): void;
+    /** @internal — used by JsonRpcRouter to reply to inbound requests. */
+    post(frame: unknown): void;
+    /** @internal — used by JsonRpcRouter to claim inbound requests. */
+    subscribe(callback: (data: unknown) => void): Unregister;
+    /** Tear down the underlying transport if it is disposable (e.g. MessageChannelTransport closes its port). */
+    dispose(): void;
+    /** Mints `_meta.traceId` for every outbound request and notification. */
+    protected getOutboundMeta(_method: string): JsonRpcMeta;
+}
+/**
+ * Inbound-request router. Holds a `BridgeClient` for everything else
+ * (outbound requests/notifications, inbound responses, inbound notifications)
+ * and adds inbound-request routing + replies on the shared transport.
+ *
+ * Subclass it per peer: register handlers in the constructor, add named
+ * outbound methods that call `send`/`notify`.
+ */
+declare class JsonRpcRouter {
+    protected readonly client: BridgeClient;
+    private readonly requestHandlers;
+    private readonly log;
+    private unsubscribe;
+    constructor(client: BridgeClient, log?: (...args: unknown[]) => void);
+    /** Register a handler for an inbound request method. Returns a disposer; re-registering overwrites. */
+    onRequest<TParams = unknown, TResult = unknown>(method: string, handler: RequestHandler<TParams, TResult>): Unregister;
+    /** Register an inbound-notification handler (delegates to the client). */
+    onNotification<TParams = unknown>(method: string, handler: NotificationHandler<TParams>): void;
+    /** Send an outbound request and await its response (delegates to the client). */
+    send<TParams = unknown, TResult = unknown>(method: string, params: TParams): Promise<TResult>;
+    /** Send an outbound notification (delegates to the client). */
+    notify<TParams = unknown>(method: string, params?: TParams): void;
+    /**
+     * Tear down: drop the inbound-request subscription, clear handlers, and
+     * dispose the client's transport (closes the port). Idempotent.
+     */
+    dispose(): void;
+    /** Route one inbound frame. Only requests are handled here; the rest is the client's. */
+    private handle;
+    private handleRequest;
+    private respondSuccess;
+    private respondError;
+    private postSafely;
+}
+
 type HostInitializedPayload = Record<string, unknown>;
 interface SessionHandle {
-    client: JsonRpcClient;
+    bridge: EmbeddingBridge;
     hostMetaData: HostMetaData;
     hostInitialized: HostInitializedPayload;
 }
@@ -328,18 +664,50 @@ declare class SessionFailureError extends Error {
     constructor(reason: SessionFailureReason, cause?: unknown);
 }
 interface BootstrapSessionOptions {
-    /**
-     * Cancellation signal. The browser MessagePort API has no port-close event,
-     * so the consumer owns the deadline (e.g. AbortSignal.timeout(30_000)).
-     * Honored only on the first call; subsequent calls return the cached promise.
-     */
+    /** Cancellation signal. Consumer owns the deadline (e.g. AbortSignal.timeout(30_000)). */
     signal?: AbortSignal;
 }
 /**
- * Bootstraps the sf-embedding session. Single-attempt per iframe — recovery
- * from failure requires a host-driven remount (`port1` is one-shot; a new
- * session needs a new `MessageChannel` + `instanceId`).
+ * Embedding-side peer. One object that routes inbound requests (via
+ * `JsonRpcRouter`), handles inbound notifications, and exposes named methods
+ * for the embedding's outbound traffic. Register inbound handlers in the
+ * constructor; add outbound methods as the protocol grows.
  */
+declare class EmbeddingBridge extends JsonRpcRouter {
+    private readonly hostInitialized;
+    private resizer;
+    constructor(transport: Transport);
+    /** Await the host's `host-initialized` notification. */
+    waitForHostInitialized(): Promise<HostInitializedPayload>;
+    /** Announce that the embedding has initialized. */
+    sendInitializedNotification(): void;
+    /** Subscribe to host UI-state. Returns the initial snapshot + active subscription id. */
+    sendUiStateSubscribe(): Promise<UiStateSubscribeResult>;
+    /** Tear down an active UI-state subscription. */
+    sendUiStateUnsubscribe(subscriptionId: string): Promise<void>;
+    /** Register a handler for `ui/notifications/ui-state-changed`. */
+    onUiStateChanged(handler: (params: UiStateChangedParams, meta?: JsonRpcMeta) => void): void;
+    /** Fire-and-forget dispatch of a custom event (bidirectional `ui/events/dispatch`).
+     * `options` controls DOM-event flags on the receiving side; defaults bubble + composed = true. */
+    sendEventDispatch(eventType: string, detail: unknown, options?: {
+        bubbles?: boolean;
+        composed?: boolean;
+        cancelable?: boolean;
+    }): void;
+    /** Subscribe to host-driven events. One subscription per session — local fan-out by eventType is the SDK's job. */
+    sendEventSubscribe(): Promise<EventsSubscribeResult>;
+    /** Tear down a host-event subscription. */
+    sendEventUnsubscribe(subscriptionId: string): Promise<void>;
+    /** Register a handler for inbound `ui/events/dispatch` (host → embedding). */
+    onEventDispatch(handler: (params: EventsDispatchParams, meta?: JsonRpcMeta) => void): void;
+    /** Fire-and-forget resize hint (`ui/notifications/resize`). */
+    sendResize(dimensions: ResizeParams): void;
+    /** Attach an auto-emit resizer; stopped on dispose. Replaces any prior resizer. */
+    attachResizer(resizer: EmbeddingResizer): void;
+    dispose(): void;
+}
+
+/** Single-attempt per iframe; recovery from failure requires a host-driven remount. */
 declare function bootstrapSession(options?: BootstrapSessionOptions): Promise<SessionHandle>;
 
 /** Combined error vocabulary: standard + transport-level + sf-embedding-specific. */
@@ -378,5 +746,5 @@ declare function makeJsonRpcError(code: number, options?: {
  */
 declare function readHostMetaData(search: string): HostMetaData | null;
 
-export { BOOTSTRAP_ENVELOPE_TYPE, BootstrapFailureError, EMBEDDING_INITIALIZED_METHOD, ErrorCode, HEARTBEAT_TYPE, HOST_INITIALIZED_METHOD, HOST_META_DATA_PARAM, HostLwcEvent, NON_RETRYABLE_CODES, PROTOCOL_NAME, SHUTDOWN_TYPE, SessionFailureError, SfEmbeddingErrorCode, bootstrapSession, isBootstrapEnvelope, makeJsonRpcError, readHostMetaData, validateBootstrapEnvelope };
-export type { BootstrapEnvelope, BootstrapEnvelopeValidationFailure, BootstrapEnvelopeValidationInput, BootstrapEnvelopeValidationResult, BootstrapFailureReason, BootstrapSessionOptions, EmbeddingInitializedParams, ErrorCodeValue, HeartbeatEnvelope, HostErrorEventDetail, HostInitializedParams, HostInitializedPayload, HostLwcEventName, HostMetaData, HostReadyEventDetail, PeerInfo, SessionFailureReason, SessionHandle, SfEmbeddingErrorCodeValue, ShutdownEnvelope };
+export { BOOTSTRAP_ENVELOPE_TYPE, BootstrapFailureError, BridgeClient, EMBEDDING_INITIALIZED_METHOD, EVENTS_DISPATCH_METHOD, EVENTS_SUBSCRIBE_METHOD, EVENTS_UNSUBSCRIBE_METHOD, EmbeddingBridge, ErrorCode, HEARTBEAT_TYPE, HOST_INITIALIZED_METHOD, HOST_META_DATA_PARAM, HostLwcEvent, JsonRpcHandlerError, JsonRpcRouter, NON_RETRYABLE_CODES, PROTOCOL_NAME, RESIZE_METHOD, SHUTDOWN_TYPE, SessionFailureError, SfEmbeddingErrorCode, UI_STATE_CHANGED_METHOD, UI_STATE_SUBSCRIBE_METHOD, UI_STATE_UNSUBSCRIBE_METHOD, bootstrapSession, isBootstrapEnvelope, makeJsonRpcError, readHostMetaData, validateBootstrapEnvelope };
+export type { BootstrapEnvelope, BootstrapEnvelopeValidationFailure, BootstrapEnvelopeValidationInput, BootstrapEnvelopeValidationResult, BootstrapFailureReason, BootstrapSessionOptions, EmbeddingInitializedParams, ErrorCodeValue, EventsDispatchParams, EventsSubscribeParams, EventsSubscribeResult, EventsUnsubscribeParams, HeartbeatEnvelope, HostErrorEventDetail, HostInitializedParams, HostInitializedPayload, HostLwcEventName, HostMetaData, HostReadyEventDetail, HostStyles, NotificationHandler, PeerInfo, RequestHandler, ResizeParams, SessionFailureReason, SessionHandle, SfEmbeddingErrorCodeValue, ShutdownEnvelope, UiState, UiStateChangedParams, UiStateSubscribeParams, UiStateSubscribeResult, UiStateUnsubscribeParams, Unregister };