@salesforce/sdk-core 1.30.1 → 1.31.0

package/dist/index.d.ts

@@ -9,4 +9,7 @@ export type { AlertOptions, MessageLevel, ModalOptions, ToastOptions, Theme, The
 export type { DataSDK, GraphQLResponse, LabelRequest, ResourceUrlRequest, SchemaDescriptor, SchemaRequest, UserInfo, } from "./data.js";
 export type { LightningSDK, LMSMessage, LMSSubscription, MessageChannel } from "./lightning.js";
 export type { OpenAISDK, SalesforceACCSDK } from "./platforms.js";
+export type { JsonRpcBase, JsonRpcRequest, JsonRpcError, JsonRpcSuccessResponse, JsonRpcErrorResponse, JsonRpcResponse, JsonRpcNotification, JsonRpcMessage, JsonRpcPendingRequest, JsonRpcPendingRequestMap, } from "./jsonrpc.js";
+export { isJsonRpcBase, isJsonRpcSuccessResponse, isJsonRpcErrorResponse, isJsonRpcResponse, isJsonRpcNotification, isJsonRpcRequest, } from "./jsonrpc.js";
+export { JsonRpcClient } from "./jsonrpc-client.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,EAAE,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAGnD,YAAY,EACX,WAAW,EACX,OAAO,EACP,WAAW,EACX,eAAe,EACf,QAAQ,EACR,SAAS,GACT,MAAM,WAAW,CAAC;AAGnB,YAAY,EACX,YAAY,EACZ,YAAY,EACZ,YAAY,EACZ,YAAY,EACZ,KAAK,EACL,SAAS,EACT,OAAO,GACP,MAAM,WAAW,CAAC;AAGnB,YAAY,EACX,OAAO,EACP,eAAe,EACf,YAAY,EACZ,kBAAkB,EAClB,gBAAgB,EAChB,aAAa,EACb,QAAQ,GACR,MAAM,WAAW,CAAC;AAGnB,YAAY,EAAE,YAAY,EAAE,UAAU,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAGhG,YAAY,EAAE,SAAS,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,EAAE,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAGnD,YAAY,EACX,WAAW,EACX,OAAO,EACP,WAAW,EACX,eAAe,EACf,QAAQ,EACR,SAAS,GACT,MAAM,WAAW,CAAC;AAGnB,YAAY,EACX,YAAY,EACZ,YAAY,EACZ,YAAY,EACZ,YAAY,EACZ,KAAK,EACL,SAAS,EACT,OAAO,GACP,MAAM,WAAW,CAAC;AAGnB,YAAY,EACX,OAAO,EACP,eAAe,EACf,YAAY,EACZ,kBAAkB,EAClB,gBAAgB,EAChB,aAAa,EACb,QAAQ,GACR,MAAM,WAAW,CAAC;AAGnB,YAAY,EAAE,YAAY,EAAE,UAAU,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAGhG,YAAY,EAAE,SAAS,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAGlE,YAAY,EACX,WAAW,EACX,cAAc,EACd,YAAY,EACZ,sBAAsB,EACtB,oBAAoB,EACpB,eAAe,EACf,mBAAmB,EACnB,cAAc,EACd,qBAAqB,EACrB,wBAAwB,GACxB,MAAM,cAAc,CAAC;AAEtB,OAAO,EACN,aAAa,EACb,wBAAwB,EACxB,sBAAsB,EACtB,iBAAiB,EACjB,qBAAqB,EACrB,gBAAgB,GAChB,MAAM,cAAc,CAAC;AAEtB,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC"}

package/dist/index.js

@@ -5,3 +5,5 @@
  */
 // Surface detection
 export { Surface, getSurface } from "./surface.js";
+export { isJsonRpcBase, isJsonRpcSuccessResponse, isJsonRpcErrorResponse, isJsonRpcResponse, isJsonRpcNotification, isJsonRpcRequest, } from "./jsonrpc.js";
+export { JsonRpcClient } from "./jsonrpc-client.js";

package/dist/jsonrpc-client.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Base class for JSON-RPC 2.0 clients using postMessage
+ *
+ * This class provides core JSON-RPC client functionality for MCP Apps implementations.
+ * It handles request/response correlation, message validation, and error handling.
+ *
+ * Subclasses should extend this class and use the protected `request()` method
+ * to send JSON-RPC requests to the parent window.
+ *
+ * @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 }
+ *     });
+ *   }
+ * }
+ */
+export declare class JsonRpcClient {
+    private nextRequestId;
+    private pending;
+    constructor();
+    /**
+     * Handle incoming JSON-RPC messages from parent window
+     */
+    private onMessage;
+    /**
+     * Send a JSON-RPC request to the parent window
+     *
+     * @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>;
+}
+//# 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":"AAQA;;;;;;;;;;;;;;;;;;GAkBG;AACH,qBAAa,aAAa;IACzB,OAAO,CAAC,aAAa,CAAK;IAC1B,OAAO,CAAC,OAAO,CAAuC;;IAOtD;;OAEG;IACH,OAAO,CAAC,SAAS,CAqBf;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;CAiBnB"}

package/dist/jsonrpc-client.js

@@ -0,0 +1,79 @@
+import { isJsonRpcResponse, isJsonRpcErrorResponse } from "./jsonrpc.js";
+/**
+ * Base class for JSON-RPC 2.0 clients using postMessage
+ *
+ * This class provides core JSON-RPC client functionality for MCP Apps implementations.
+ * It handles request/response correlation, message validation, and error handling.
+ *
+ * Subclasses should extend this class and use the protected `request()` method
+ * to send JSON-RPC requests to the parent window.
+ *
+ * @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 }
+ *     });
+ *   }
+ * }
+ */
+export class JsonRpcClient {
+    nextRequestId = 1;
+    pending = new Map();
+    constructor() {
+        // Listen for JSON-RPC messages from parent window
+        window.addEventListener("message", this.onMessage);
+    }
+    /**
+     * Handle incoming JSON-RPC messages from parent window
+     */
+    onMessage = (event) => {
+        const data = event.data;
+        // Use type guard for validation with type narrowing
+        if (!isJsonRpcResponse(data)) {
+            return;
+        }
+        const slot = this.pending.get(data.id);
+        if (!slot) {
+            return;
+        }
+        this.pending.delete(data.id);
+        // Type guard provides proper type narrowing
+        if (isJsonRpcErrorResponse(data)) {
+            slot.reject(new Error(data.error.message || "Request failed"));
+        }
+        else {
+            slot.resolve(data.result);
+        }
+    };
+    /**
+     * Send a JSON-RPC request to the parent window
+     *
+     * @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(method, params) {
+        const id = this.nextRequestId++;
+        const message = {
+            jsonrpc: "2.0",
+            id,
+            method,
+            params,
+        };
+        return new Promise((resolve, reject) => {
+            this.pending.set(id, {
+                resolve: resolve,
+                reject,
+            });
+            window.parent?.postMessage(message, "*");
+        });
+    }
+}

package/dist/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/jsonrpc.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"jsonrpc.d.ts","sourceRoot":"","sources":["../src/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/jsonrpc.js

@@ -0,0 +1,57 @@
+/**
+ * Copyright (c) 2026, Salesforce, Inc.,
+ * All rights reserved.
+ * For full license text, see the LICENSE.txt file
+ */
+/**
+ * Type guard to check if message is valid JSON-RPC 2.0 base
+ */
+export function isJsonRpcBase(data) {
+    return (typeof data === "object" &&
+        data !== null &&
+        "jsonrpc" in data &&
+        data.jsonrpc === "2.0");
+}
+/**
+ * Type guard for JSON-RPC success response
+ */
+export function isJsonRpcSuccessResponse(data) {
+    return (isJsonRpcBase(data) &&
+        "id" in data &&
+        typeof data.id === "number" &&
+        "result" in data);
+}
+/**
+ * Type guard for JSON-RPC error response
+ */
+export function isJsonRpcErrorResponse(data) {
+    return (isJsonRpcBase(data) &&
+        "id" in data &&
+        typeof data.id === "number" &&
+        "error" in data);
+}
+/**
+ * Type guard for any JSON-RPC response (success or error)
+ */
+export function isJsonRpcResponse(data) {
+    return isJsonRpcSuccessResponse(data) || isJsonRpcErrorResponse(data);
+}
+/**
+ * Type guard for JSON-RPC notification
+ */
+export function isJsonRpcNotification(data) {
+    return (isJsonRpcBase(data) &&
+        "method" in data &&
+        typeof data.method === "string" &&
+        !("id" in data));
+}
+/**
+ * Type guard for JSON-RPC request
+ */
+export function isJsonRpcRequest(data) {
+    return (isJsonRpcBase(data) &&
+        "id" in data &&
+        typeof data.id === "number" &&
+        "method" in data &&
+        typeof data.method === "string");
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@salesforce/sdk-core",
-  "version": "1.30.1",
+  "version": "1.31.0",
   "license": "SEE LICENSE IN LICENSE.txt",
   "type": "module",
   "main": "./dist/index.js",
@@ -31,5 +31,5 @@
   "publishConfig": {
     "access": "public"
   },
-  "gitHead": "a5cc859ca5bec49a2501879befaa90787bf5c578"
+  "gitHead": "2e24fd71a18e7912a6caae854ef7f462d0df5080"
 }