@salesforce/jsonrpc 9.13.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/dist/errors.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Copyright (c) 2026, Salesforce, Inc.,
+ * All rights reserved.
+ * For full license text, see the LICENSE.txt file
+ */
+/**
+ * JSON-RPC error vocabulary common to every cross-realm protocol that uses
+ * this package. Centralizes the standard JSON-RPC 2.0 error codes plus the
+ * transport-level codes that any JsonRpcClient over a transport with
+ * timeouts and cancellation will emit.
+ *
+ * Codes used by this package:
+ *   - JSON-RPC 2.0 standard: -32700, -32600..-32603
+ *   - Transport-level: a handful within -32010..-32099 (see below)
+ */
+export declare const StandardErrorCode: {
+    readonly PARSE_ERROR: -32700;
+    readonly INVALID_REQUEST: -32600;
+    readonly METHOD_NOT_FOUND: -32601;
+    readonly INVALID_PARAMS: -32602;
+    readonly INTERNAL_ERROR: -32603;
+    /** Transport closed; pending requests rejected locally. */
+    readonly PORT_CLOSED: -32016;
+    /** Payload could not be structured-cloned across the transport. */
+    readonly SERIALIZATION_FAILURE: -32017;
+    /** `default` / `long` timeout-class request expired. */
+    readonly REQUEST_TIMEOUT: -32018;
+    /** In-flight cap reached. */
+    readonly BACKPRESSURE: -32019;
+    /** Terminal response to a $/cancel-ed request. */
+    readonly REQUEST_CANCELLED: -32024;
+};
+/** Numeric type of any value in `StandardErrorCode`. */
+export type StandardErrorCodeValue = (typeof StandardErrorCode)[keyof typeof StandardErrorCode];
+/** Structure of the `data` field on a JSON-RPC error payload. */
+export interface JsonRpcErrorData {
+    retryable?: boolean;
+    details?: Record<string, unknown>;
+}
+/** Shape of a JSON-RPC error payload (the value under `error` on an error response). */
+export interface JsonRpcErrorPayload {
+    code: number;
+    message?: string;
+    data?: JsonRpcErrorData;
+}
+/** Builds a JSON-RPC error payload with sensible `retryable` defaults per code. */
+export declare function makeJsonRpcError(code: number, options?: {
+    message?: string;
+    details?: Record<string, unknown>;
+    retryable?: boolean;
+}): JsonRpcErrorPayload;
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH;;;;;;;;;GASG;AACH,eAAO,MAAM,iBAAiB;;;;;;IAS7B,2DAA2D;;IAE3D,mEAAmE;;IAEnE,wDAAwD;;IAExD,6BAA6B;;IAE7B,kDAAkD;;CAEzC,CAAC;AAEX,wDAAwD;AACxD,MAAM,MAAM,sBAAsB,GAAG,CAAC,OAAO,iBAAiB,CAAC,CAAC,MAAM,OAAO,iBAAiB,CAAC,CAAC;AAEhG,iEAAiE;AACjE,MAAM,WAAW,gBAAgB;IAChC,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAClC;AAED,wFAAwF;AACxF,MAAM,WAAW,mBAAmB;IACnC,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,IAAI,CAAC,EAAE,gBAAgB,CAAC;CACxB;AAYD,mFAAmF;AACnF,wBAAgB,gBAAgB,CAC/B,IAAI,EAAE,MAAM,EACZ,OAAO,GAAE;IACR,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAClC,SAAS,CAAC,EAAE,OAAO,CAAC;CACf,GACJ,mBAAmB,CASrB"}

package/dist/index.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Copyright (c) 2026, Salesforce, Inc.,
+ * All rights reserved.
+ * For full license text, see the LICENSE.txt file
+ */
+/**
+ * @salesforce/jsonrpc
+ *
+ * JSON-RPC 2.0 primitives for cross-realm communication: envelope types and
+ * runtime guards, the request/response engine (JsonRpcClient), and transport
+ * adapters (WindowPostMessageTransport, MessageChannelTransport).
+ */
+export type { JsonRpcMeta, JsonRpcBase, JsonRpcRequest, JsonRpcNotification, JsonRpcSuccessResponse, JsonRpcErrorResponse, JsonRpcResponse, JsonRpcError, JsonRpcFrame, JsonRpcPendingRequest, JsonRpcPendingRequestMap, } from './jsonrpc';
+export { isJsonRpcBase, isJsonRpcRequest, isJsonRpcNotification, isJsonRpcSuccessResponse, isJsonRpcErrorResponse, isJsonRpcResponse, isJsonRpcError, } from './jsonrpc';
+export type { Transport } from './transport';
+export { JsonRpcClient } from './jsonrpc-client';
+export { WindowPostMessageTransport } from './window-postmessage-transport';
+export { MessageChannelTransport, type MessageChannelTransportListener, } from './message-channel-transport';
+export { StandardErrorCode, type StandardErrorCodeValue, type JsonRpcErrorData, type JsonRpcErrorPayload, makeJsonRpcError, } from './errors';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH;;;;;;GAMG;AAEH,YAAY,EACX,WAAW,EACX,WAAW,EACX,cAAc,EACd,mBAAmB,EACnB,sBAAsB,EACtB,oBAAoB,EACpB,eAAe,EACf,YAAY,EACZ,YAAY,EACZ,qBAAqB,EACrB,wBAAwB,GACxB,MAAM,WAAW,CAAC;AACnB,OAAO,EACN,aAAa,EACb,gBAAgB,EAChB,qBAAqB,EACrB,wBAAwB,EACxB,sBAAsB,EACtB,iBAAiB,EACjB,cAAc,GACd,MAAM,WAAW,CAAC;AAEnB,YAAY,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAC7C,OAAO,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AACjD,OAAO,EAAE,0BAA0B,EAAE,MAAM,gCAAgC,CAAC;AAC5E,OAAO,EACN,uBAAuB,EACvB,KAAK,+BAA+B,GACpC,MAAM,6BAA6B,CAAC;AAErC,OAAO,EACN,iBAAiB,EACjB,KAAK,sBAAsB,EAC3B,KAAK,gBAAgB,EACrB,KAAK,mBAAmB,EACxB,gBAAgB,GAChB,MAAM,UAAU,CAAC"}

package/dist/index.js

@@ -0,0 +1,310 @@
+function o(s) {
+  return typeof s == "object" && s !== null && !Array.isArray(s);
+}
+function c(s) {
+  return typeof s.id == "number" && Number.isInteger(s.id) && s.id >= 0;
+}
+function i(s) {
+  return o(s) && s.jsonrpc === "2.0";
+}
+function m(s) {
+  if (!i(s)) return !1;
+  const t = s;
+  return c(t) && typeof t.method == "string";
+}
+function d(s) {
+  if (!i(s)) return !1;
+  const t = s;
+  return !("id" in t) && typeof t.method == "string";
+}
+function p(s) {
+  if (!i(s)) return !1;
+  const t = s;
+  return c(t) && "result" in t && !("error" in t) && !("method" in t);
+}
+function f(s) {
+  if (!i(s)) return !1;
+  const t = s;
+  if (!c(t) || "result" in t || "method" in t) return !1;
+  const e = t.error;
+  return o(e) && typeof e.code == "number";
+}
+function g(s) {
+  return p(s) || f(s);
+}
+function y(s) {
+  return o(s) && typeof s.code == "number";
+}
+class M {
+  nextRequestId = 1;
+  pending = /* @__PURE__ */ new Map();
+  notificationHandlers = /* @__PURE__ */ new Map();
+  transport;
+  /**
+   * Construct a JSON-RPC client bound to the given transport.
+   *
+   * @param transport - the transport to use.
+   */
+  constructor(t) {
+    this.transport = t, this.transport.onMessage(this.onMessage);
+  }
+  /**
+   * 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);
+   * });
+   */
+  registerNotificationHandler(t, e) {
+    this.notificationHandlers.has(t) || this.notificationHandlers.set(t, /* @__PURE__ */ new Set()), this.notificationHandlers.get(t).add(e);
+  }
+  /**
+   * 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.
+   */
+  onMessage = (t) => {
+    if (g(t)) {
+      const e = this.pending.get(t.id);
+      if (!e)
+        return;
+      this.pending.delete(t.id), f(t) ? e.reject(new Error(t.error.message || "Request failed")) : e.resolve(t.result);
+      return;
+    }
+    if (d(t)) {
+      const e = this.notificationHandlers.get(t.method);
+      e && e.forEach((r) => r(t.params));
+    }
+  };
+  /**
+   * 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" }
+   * });
+   */
+  request(t, e) {
+    const r = this.nextRequestId++, n = {
+      jsonrpc: "2.0",
+      id: r,
+      method: t,
+      params: e
+    };
+    return new Promise((h, u) => {
+      this.pending.set(r, {
+        resolve: h,
+        reject: u
+      }), this.transport.post(n);
+    });
+  }
+  /**
+   * 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
+   * });
+   */
+  sendNotification(t, e) {
+    const r = {
+      jsonrpc: "2.0",
+      method: t,
+      params: e
+    };
+    this.transport.post(r);
+  }
+}
+class S {
+  targetOrigin;
+  /**
+   * @param targetOrigin - origin passed as the second argument to
+   *   `window.parent.postMessage`.
+   */
+  constructor(t) {
+    this.targetOrigin = t;
+  }
+  post(t) {
+    window.parent?.postMessage(t, this.targetOrigin);
+  }
+  onMessage(t) {
+    const e = (r) => {
+      t(r.data);
+    };
+    return window.addEventListener("message", e), () => window.removeEventListener("message", e);
+  }
+}
+function R() {
+}
+class T {
+  #t;
+  #e = /* @__PURE__ */ new Set();
+  #n = !1;
+  #r = !1;
+  /** Messages queued before `port.start()` has been called. Flushed on first subscribe. */
+  #s = [];
+  constructor(t) {
+    this.#t = t;
+  }
+  /**
+   * 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(t) {
+    if (!this.#r) {
+      if (!this.#n) {
+        this.#s.push(t);
+        return;
+      }
+      try {
+        this.#t.postMessage(t);
+      } catch {
+      }
+    }
+  }
+  /**
+   * 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(t) {
+    if (this.#r)
+      return R;
+    this.#e.add(t), this.#n || this.#o();
+    let e = !1;
+    return () => {
+      e || (e = !0, this.#e.delete(t));
+    };
+  }
+  /**
+   * 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() {
+    if (!this.#r) {
+      this.#r = !0;
+      try {
+        this.#t.removeEventListener("message", this.#i);
+      } catch {
+      }
+      this.#e.clear(), this.#s.length = 0;
+      try {
+        this.#t.close();
+      } catch {
+      }
+    }
+  }
+  #o() {
+    this.#n = !0, this.#t.addEventListener("message", this.#i);
+    try {
+      this.#t.start();
+    } catch {
+    }
+    if (this.#s.length > 0) {
+      const t = this.#s;
+      this.#s = [];
+      for (const e of t)
+        try {
+          this.#t.postMessage(e);
+        } catch {
+        }
+    }
+  }
+  #i = (t) => {
+    const e = [...this.#e];
+    for (const r of e)
+      try {
+        r(t.data);
+      } catch {
+      }
+  };
+}
+const a = {
+  // --- Standard JSON-RPC 2.0 ----------------------------------------------
+  PARSE_ERROR: -32700,
+  INVALID_REQUEST: -32600,
+  METHOD_NOT_FOUND: -32601,
+  INVALID_PARAMS: -32602,
+  INTERNAL_ERROR: -32603,
+  // --- Transport-level (any JsonRpcClient over a transport will emit) -----
+  /** Transport closed; pending requests rejected locally. */
+  PORT_CLOSED: -32016,
+  /** Payload could not be structured-cloned across the transport. */
+  SERIALIZATION_FAILURE: -32017,
+  /** `default` / `long` timeout-class request expired. */
+  REQUEST_TIMEOUT: -32018,
+  /** In-flight cap reached. */
+  BACKPRESSURE: -32019,
+  /** Terminal response to a $/cancel-ed request. */
+  REQUEST_CANCELLED: -32024
+}, E = /* @__PURE__ */ new Set([
+  a.REQUEST_TIMEOUT,
+  a.BACKPRESSURE
+]);
+function l(s) {
+  return !!E.has(s);
+}
+function b(s, t = {}) {
+  const r = { retryable: t.retryable ?? l(s) };
+  t.details !== void 0 && (r.details = t.details);
+  const n = { code: s };
+  return t.message !== void 0 && (n.message = t.message), n.data = r, n;
+}
+export {
+  M as JsonRpcClient,
+  T as MessageChannelTransport,
+  a as StandardErrorCode,
+  S as WindowPostMessageTransport,
+  i as isJsonRpcBase,
+  y as isJsonRpcError,
+  f as isJsonRpcErrorResponse,
+  d as isJsonRpcNotification,
+  m as isJsonRpcRequest,
+  g as isJsonRpcResponse,
+  p as isJsonRpcSuccessResponse,
+  b as makeJsonRpcError
+};

package/dist/jsonrpc-client.d.ts

@@ -0,0 +1,112 @@
+import { Transport } from './transport';
+/**
+ * Base class for JSON-RPC 2.0 clients.
+ *
+ * This class provides core JSON-RPC client functionality for any cross-realm
+ * surface that speaks JSON-RPC 2.0 (MCP Apps, sf-embedding, future
+ * surfaces). It handles request/response correlation, message validation,
+ * and notification dispatch.
+ *
+ * The transport layer is pluggable via the `Transport` interface and is
+ * REQUIRED at construction. There is no default transport — wildcard-targeted
+ * `window.postMessage` is structurally unsafe, so callers must construct a
+ * transport with an explicit origin (`WindowPostMessageTransport`) or a
+ * port-bound transport (`MessageChannelTransport`).
+ *
+ * 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 transport (window.parent.postMessage to a known origin).
+ * class MyClient extends JsonRpcClient {
+ *   constructor(targetOrigin: string) {
+ *     super(new WindowPostMessageTransport(targetOrigin));
+ *   }
+ * }
+ */
+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.
+     */
+    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/jsonrpc-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"jsonrpc-client.d.ts","sourceRoot":"","sources":["../src/jsonrpc-client.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAE7C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;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;;;;OAIG;gBACS,SAAS,EAAE,SAAS;IAMhC;;;;;;;;;;;;;;;OAeG;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/jsonrpc.d.ts

@@ -0,0 +1,152 @@
+/**
+ * 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.
+ */
+export 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.
+ */
+export interface JsonRpcBase {
+    jsonrpc: "2.0";
+    _meta?: JsonRpcMeta;
+}
+/**
+ * JSON-RPC 2.0 Request — has both `id` and `method`.
+ */
+export 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.
+ */
+export interface JsonRpcNotification<TParams = unknown> extends JsonRpcBase {
+    method: string;
+    params?: TParams;
+}
+/**
+ * JSON-RPC 2.0 Success Response — has `id` and `result`.
+ */
+export interface JsonRpcSuccessResponse<TResult = unknown> extends JsonRpcBase {
+    id: number;
+    result: TResult;
+}
+/**
+ * JSON-RPC 2.0 Error payload (carried under `error` on an error response).
+ */
+export interface JsonRpcError {
+    code: number;
+    message?: string;
+    data?: unknown;
+}
+/**
+ * JSON-RPC 2.0 Error Response — has `id` and `error`.
+ */
+export interface JsonRpcErrorResponse extends JsonRpcBase {
+    id: number;
+    error: JsonRpcError;
+}
+/**
+ * Either flavor of response.
+ */
+export type JsonRpcResponse<TResult = unknown> = JsonRpcSuccessResponse<TResult> | JsonRpcErrorResponse;
+/**
+ * Any JSON-RPC frame the dispatcher might receive.
+ */
+export type JsonRpcFrame = JsonRpcRequest | JsonRpcNotification | JsonRpcResponse;
+/**
+ * Pending-request resolver pair, used by the JsonRpcClient to track
+ * in-flight requests waiting for their terminal response.
+ */
+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: returns true if the value carries the JSON-RPC 2.0 envelope
+ * marker. Building block for the more specific guards below.
+ */
+export declare function isJsonRpcBase(value: unknown): value is JsonRpcBase;
+/**
+ * Type guard: a well-formed request — has `jsonrpc: "2.0"`, a non-negative
+ * integer `id`, and a string `method`.
+ */
+export declare function isJsonRpcRequest(value: unknown): value is JsonRpcRequest;
+/**
+ * Type guard: a well-formed notification — has `method` AND no `id` property.
+ */
+export declare function isJsonRpcNotification(value: unknown): value is JsonRpcNotification;
+/**
+ * Type guard: a well-formed success response — has `id` + `result`,
+ * and does NOT carry `error` or `method` (which would make it ambiguous
+ * with error responses or requests/notifications).
+ */
+export declare function isJsonRpcSuccessResponse(value: unknown): value is JsonRpcSuccessResponse;
+/**
+ * Type guard: a well-formed error response — has `id`, an `error` whose
+ * `code` is numeric, and does NOT carry `result` or `method`.
+ */
+export declare function isJsonRpcErrorResponse(value: unknown): value is JsonRpcErrorResponse;
+/**
+ * Type guard: any well-formed response (success or error).
+ */
+export declare function isJsonRpcResponse(value: unknown): value is JsonRpcResponse;
+/**
+ * Type guard: a JSON-RPC error payload (the value carried under `error`
+ * on an error response). Useful for callers handling rejected promises
+ * from the JsonRpcClient.
+ */
+export declare function isJsonRpcError(value: unknown): value is JsonRpcError;
+//# sourceMappingURL=jsonrpc.d.ts.map

package/dist/jsonrpc.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"jsonrpc.d.ts","sourceRoot":"","sources":["../src/jsonrpc.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AAEH;;;GAGG;AACH,MAAM,WAAW,WAAW;IAC3B,oEAAoE;IACpE,OAAO,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;GAGG;AACH,MAAM,WAAW,WAAW;IAC3B,OAAO,EAAE,KAAK,CAAC;IACf,KAAK,CAAC,EAAE,WAAW,CAAC;CACpB;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,mBAAmB,CAAC,OAAO,GAAG,OAAO,CAAE,SAAQ,WAAW;IAC1E,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,OAAO,CAAC;CACjB;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,YAAY;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,IAAI,CAAC,EAAE,OAAO,CAAC;CACf;AAED;;GAEG;AACH,MAAM,WAAW,oBAAqB,SAAQ,WAAW;IACxD,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,YAAY,CAAC;CACpB;AAED;;GAEG;AACH,MAAM,MAAM,eAAe,CAAC,OAAO,GAAG,OAAO,IAC1C,sBAAsB,CAAC,OAAO,CAAC,GAC/B,oBAAoB,CAAC;AAExB;;GAEG;AACH,MAAM,MAAM,YAAY,GAAG,cAAc,GAAG,mBAAmB,GAAG,eAAe,CAAC;AAElF;;;GAGG;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;AAmB1E;;;GAGG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,WAAW,CAElE;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,cAAc,CAIxE;AAED;;GAEG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,mBAAmB,CAIlF;AAED;;;;GAIG;AACH,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,sBAAsB,CAIxF;AAED;;;GAGG;AACH,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,oBAAoB,CAOpF;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,eAAe,CAE1E;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,YAAY,CAEpE"}

package/dist/message-channel-transport.d.ts

@@ -0,0 +1,74 @@
+import { Transport } from './transport';
+/**
+ * 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;
+/**
+ * `Transport` backed by a `MessagePort`.
+ *
+ * During an 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.
+ *
+ * Contract (symmetric with the `Transport` interface defined alongside
+ * `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/message-channel-transport.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"message-channel-transport.d.ts","sourceRoot":"","sources":["../src/message-channel-transport.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAE7C;;;;GAIG;AACH,MAAM,MAAM,+BAA+B,GAAG,CAAC,GAAG,EAAE,OAAO,KAAK,IAAI,CAAC;AAUrE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;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"}

package/dist/transport.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Copyright (c) 2026, Salesforce, Inc.,
+ * All rights reserved.
+ * For full license text, see the LICENSE.txt file
+ */
+/**
+ * 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.
+ *
+ * Concrete transports plug into the same shape:
+ *   - `WindowPostMessageTransport` (window.parent.postMessage; used by
+ *     MCP Apps)
+ *   - `MessageChannelTransport` (a transferred `MessagePort`; used by
+ *     sf-embedding and any future surface that bootstraps with a
+ *     dedicated channel)
+ */
+export interface Transport {
+    /**
+     * Deliver a single structured message to the peer. Implementations MUST
+     * NOT throw on transient conditions (closed port, 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;
+}
+//# sourceMappingURL=transport.d.ts.map

package/dist/transport.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transport.d.ts","sourceRoot":"","sources":["../src/transport.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH;;;;;;;;;;;;;;;GAeG;AACH,MAAM,WAAW,SAAS;IACzB;;;;;OAKG;IACH,IAAI,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAAC;IAE7B;;;;;;OAMG;IACH,SAAS,CAAC,QAAQ,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,IAAI,GAAG,MAAM,IAAI,CAAC;CAC5D"}

package/dist/window-postmessage-transport.d.ts

@@ -0,0 +1,22 @@
+import { Transport } from './transport';
+/**
+ * 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.
+ *
+ * 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`.
+     */
+    constructor(targetOrigin: string);
+    post(message: unknown): void;
+    onMessage(callback: (message: unknown) => void): () => void;
+}
+//# sourceMappingURL=window-postmessage-transport.d.ts.map

package/dist/window-postmessage-transport.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"window-postmessage-transport.d.ts","sourceRoot":"","sources":["../src/window-postmessage-transport.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAE7C;;;;;;;;;GASG;AACH,qBAAa,0BAA2B,YAAW,SAAS;IAC3D,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAS;IAEtC;;;OAGG;gBACS,YAAY,EAAE,MAAM;IAIhC,IAAI,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI;IAI5B,SAAS,CAAC,QAAQ,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,IAAI,GAAG,MAAM,IAAI;CAO3D"}

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@salesforce/jsonrpc",
+  "version": "9.13.0",
+  "description": "Shareable JSON-RPC 2.0 primitives for cross-realm communication: envelope types and runtime guards, the request/response engine (JsonRpcClient), and transport adapters.",
+  "license": "SEE LICENSE IN LICENSE.txt",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "sideEffects": false,
+  "exports": {
+    "./package.json": "./package.json",
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "vite build",
+    "clean": "rm -rf dist",
+    "dev": "vite build --watch",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage"
+  },
+  "devDependencies": {
+    "vite": "^7.3.1",
+    "vite-plugin-dts": "^4.5.4",
+    "vitest": "^4.0.6"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}