@salesforce/sf-embedding-bridge 0.0.1 → 2.2.1-rc.7

package/LICENSE.txt

@@ -0,0 +1,21 @@
+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, 2022, ** 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/bootstrap-envelope.d.ts

@@ -0,0 +1,25 @@
+import { type BootstrapEnvelope } from "@salesforce/sf-embedding-contract";
+export type BootstrapEnvelopeValidationFailure = "INVALID_SHAPE" | "WRONG_SOURCE" | "ORIGIN_NOT_ALLOWED" | "WRONG_PORT_COUNT" | "INSTANCE_ID_MISMATCH" | "DUPLICATE_TRANSFER";
+export type BootstrapEnvelopeValidationResult = {
+    ok: true;
+    envelope: BootstrapEnvelope;
+    port: MessagePort;
+} | {
+    ok: false;
+    reason: BootstrapEnvelopeValidationFailure;
+};
+export interface BootstrapEnvelopeValidationInput {
+    data: unknown;
+    source: MessageEventSource | null;
+    origin: string;
+    ports: ReadonlyArray<MessagePort>;
+    expectedSource: MessageEventSource | null;
+    allowedOrigins: ReadonlyArray<string>;
+    expectedInstanceId: string;
+    alreadyAccepted: boolean;
+}
+/** Type guard: true iff `value` is shape-compatible with `BootstrapEnvelope`. */
+export declare function isBootstrapEnvelope(value: unknown): value is BootstrapEnvelope;
+/** Validates an inbound bootstrap envelope; never throws — failures returned as typed reasons. */
+export declare function validateBootstrapEnvelope(input: BootstrapEnvelopeValidationInput): BootstrapEnvelopeValidationResult;
+//# sourceMappingURL=bootstrap-envelope.d.ts.map

package/dist/bootstrap-listener.d.ts

@@ -0,0 +1,12 @@
+import { type HostMetaData } from "@salesforce/sf-embedding-contract";
+export interface PortCaptureResult {
+    port: MessagePort;
+    hostMetaData: HostMetaData;
+}
+export type BootstrapFailureReason = "MISSING_HOST_METADATA";
+export declare class BootstrapFailureError extends Error {
+    readonly reason: BootstrapFailureReason;
+    constructor(reason: BootstrapFailureReason);
+}
+export declare function installBootstrapListener(): Promise<PortCaptureResult>;
+//# sourceMappingURL=bootstrap-listener.d.ts.map

package/dist/bootstrap-session.d.ts

@@ -0,0 +1,29 @@
+import { JsonRpcClient } from "@salesforce/jsonrpc";
+import { type HostMetaData } from "@salesforce/sf-embedding-contract";
+import { type BootstrapFailureReason } from "./bootstrap-listener";
+export type HostInitializedPayload = Record<string, unknown>;
+export interface SessionHandle {
+    client: JsonRpcClient;
+    hostMetaData: HostMetaData;
+    hostInitialized: HostInitializedPayload;
+}
+export type SessionFailureReason = BootstrapFailureReason | "ABORTED";
+export declare class SessionFailureError extends Error {
+    readonly reason: SessionFailureReason;
+    constructor(reason: SessionFailureReason, cause?: unknown);
+}
+export 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.
+     */
+    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`).
+ */
+export declare function bootstrapSession(options?: BootstrapSessionOptions): Promise<SessionHandle>;
+//# sourceMappingURL=bootstrap-session.d.ts.map

package/dist/embedding-info.d.ts

@@ -0,0 +1,4 @@
+import type { PeerInfo } from "@salesforce/sf-embedding-contract";
+/** Identity emitted on `ui/notifications/embedding-initialized`. */
+export declare const EMBEDDING_INFO: PeerInfo;
+//# sourceMappingURL=embedding-info.d.ts.map

package/dist/errors.d.ts

@@ -0,0 +1,30 @@
+import { type JsonRpcErrorPayload } from "@salesforce/jsonrpc";
+/** Combined error vocabulary: standard + transport-level + sf-embedding-specific. */
+export declare const ErrorCode: {
+    readonly CAPABILITY_NOT_ALLOWED: -32010;
+    readonly CAPABILITY_REVOKED: -32011;
+    readonly NOT_INITIALIZED: -32012;
+    readonly PROTOCOL_VERSION_MISMATCH: -32013;
+    readonly ORIGIN_MISMATCH: -32014;
+    readonly PROTOCOL_VIOLATION: -32020;
+    readonly BOOTSTRAP_DUPLICATE_TRANSFER: -32023;
+    readonly PARSE_ERROR: -32700;
+    readonly INVALID_REQUEST: -32600;
+    readonly METHOD_NOT_FOUND: -32601;
+    readonly INVALID_PARAMS: -32602;
+    readonly INTERNAL_ERROR: -32603;
+    readonly PORT_CLOSED: -32016;
+    readonly SERIALIZATION_FAILURE: -32017;
+    readonly REQUEST_TIMEOUT: -32018;
+    readonly BACKPRESSURE: -32019;
+    readonly REQUEST_CANCELLED: -32024;
+};
+/** Numeric type of any value in `ErrorCode`. */
+export type ErrorCodeValue = (typeof ErrorCode)[keyof typeof ErrorCode];
+/** Builds a JSON-RPC error payload with sf-embedding-specific retryable defaults; falls through to @salesforce/jsonrpc for codes it owns. */
+export declare function makeJsonRpcError(code: number, options?: {
+    message?: string;
+    details?: Record<string, unknown>;
+    retryable?: boolean;
+}): JsonRpcErrorPayload;
+//# sourceMappingURL=errors.d.ts.map

package/dist/host-meta-data.d.ts

@@ -0,0 +1,8 @@
+import { type HostMetaData } from "@salesforce/sf-embedding-contract";
+/**
+ * Parses the JSON-encoded `hostMetaData` query parameter from an iframe URL's
+ * search string (per ADR 0029). Returns null on any malformed input — caller
+ * fails fast rather than partially initializing.
+ */
+export declare function readHostMetaData(search: string): HostMetaData | null;
+//# sourceMappingURL=host-meta-data.d.ts.map

package/dist/index.cjs.js

@@ -0,0 +1,332 @@
+'use strict';
+
+var jsonrpc = require('@salesforce/jsonrpc');
+
+// Bootstrap envelope vocabulary. Spec: EMBEDDING-PROTOCOL.md §3.1, §3.1.1,
+// MC-7/MC-8/MC-10 in §2.2.
+/** Wire identifier for this protocol. Carried verbatim on every bootstrap envelope. */
+const PROTOCOL_NAME = "sf-embedding";
+/** Discriminator for the host → embedding bootstrap envelope. */
+const BOOTSTRAP_ENVELOPE_TYPE = "sf-embedding.bootstrap";
+/** Discriminator for the embedding → host content-free heartbeat. */
+const HEARTBEAT_TYPE = "sf-embedding/ready";
+/**
+ * Discriminator for the embedding → host fail-closed shutdown signal
+ * (e.g., duplicate-transfer detection). Posted via window-level postMessage,
+ * not over the JSON-RPC port.
+ */
+const SHUTDOWN_TYPE = "sf-embedding/shutdown";
+
+// sf-embedding protocol-specific JSON-RPC error codes. Spec §8.2.
+//
+// Standard JSON-RPC codes (-32700, -32600..-32603) and transport-level codes
+// (PORT_CLOSED, SERIALIZATION_FAILURE, REQUEST_TIMEOUT, BACKPRESSURE,
+// REQUEST_CANCELLED) live in `@salesforce/jsonrpc`'s
+// `StandardErrorCode` and are NOT re-exported here. Consumers that need the
+// merged vocabulary compose them at the call site.
+/** sf-embedding protocol-specific error codes (§8.2 numeric assignments). */
+const SfEmbeddingErrorCode = {
+    /** Method exists at selected version but is not granted (§6.5). */
+    CAPABILITY_NOT_ALLOWED: -32010,
+    /** In-flight request gated on a capability that was just revoked (§6.6). */
+    CAPABILITY_REVOKED: -32011,
+    /** Frame arrived before the required handshake step completed (§5.2, §4.2). */
+    NOT_INITIALIZED: -32012,
+    /** Embedding's protocol version is not supported by the host (§4.2, §3.1.2). */
+    PROTOCOL_VERSION_MISMATCH: -32013,
+    /** Frame's origin does not match the bound peer origin (§3.1). */
+    ORIGIN_MISMATCH: -32014,
+    /** Catch-all — duplicate ui/select-version, duplicate ui/discover-capabilities, etc. */
+    PROTOCOL_VIOLATION: -32020,
+    /** Embedding observed a second valid bootstrap envelope and shut down (§3.1.2). */
+    BOOTSTRAP_DUPLICATE_TRANSFER: -32023,
+};
+/**
+ * Codes that are non-retryable by default (§8.4). Consumers building error
+ * payloads SHOULD set `retryable: false` automatically for these.
+ */
+const NON_RETRYABLE_CODES = new Set([
+    SfEmbeddingErrorCode.CAPABILITY_NOT_ALLOWED,
+    SfEmbeddingErrorCode.CAPABILITY_REVOKED,
+    SfEmbeddingErrorCode.ORIGIN_MISMATCH,
+]);
+
+// Host LWC reserved DOM event names and detail shapes. Spec §12.3.
+//
+// These are dispatched by the host LWC on its own element so application
+// code on the page can react. The embedding never observes them.
+/** Event names the host LWC dispatches on its own element. Reserved by the protocol. */
+const HostLwcEvent = {
+    /** Synchronous with `ui/discover-capabilities` response; session reaches READY. */
+    READY: "sf-embedding.component.ready",
+    /** Misconfiguration, bootstrap failure, embedding-reported fatal, or protocol violation. */
+    ERROR: "sf-embedding.component.error",
+};
+
+// Host-supplied iframe URL metadata (per ADR 0029). Spec §3.1, MC-8/MC-10.
+/** URL query-parameter name carrying the JSON-encoded `HostMetaData`. */
+const HOST_META_DATA_PARAM = "hostMetaData";
+
+// JSON-RPC method names on the wire today.
+/** Host announces session identity to the embedding over the port. */
+const HOST_INITIALIZED_METHOD = "ui/notifications/host-initialized";
+/** Embedding acknowledges receipt of `host-initialized`. Fire-and-forget. */
+const EMBEDDING_INITIALIZED_METHOD = "ui/notifications/embedding-initialized";
+
+// Bootstrap envelope validator for the iframe (embedding) side of the
+// sf-embedding handshake.
+//
+// Wire-format types and discriminator constants live in
+// `@salesforce/sf-embedding-contract`; consumers MUST import them from there.
+// This module owns only the embedding-side validator
+// (`validateBootstrapEnvelope`) and its supporting types — intentionally NOT
+// in the contract package because the host and embedding sides have
+// different validation rules per spec §3.1.2.
+/** Type guard: true iff `value` is shape-compatible with `BootstrapEnvelope`. */
+function isBootstrapEnvelope(value) {
+    if (typeof value !== "object" || value === null || Array.isArray(value))
+        return false;
+    const v = value;
+    if (v.type !== BOOTSTRAP_ENVELOPE_TYPE)
+        return false;
+    if (v.protocol !== PROTOCOL_NAME)
+        return false;
+    if (typeof v.instanceId !== "string" || v.instanceId.length === 0)
+        return false;
+    if (!Array.isArray(v.allowedOrigins))
+        return false;
+    return v.allowedOrigins.every((o) => typeof o === "string");
+}
+/** Validates an inbound bootstrap envelope; never throws — failures returned as typed reasons. */
+function validateBootstrapEnvelope(input) {
+    if (!isBootstrapEnvelope(input.data))
+        return { ok: false, reason: "INVALID_SHAPE" };
+    if (input.source !== input.expectedSource)
+        return { ok: false, reason: "WRONG_SOURCE" };
+    if (!input.allowedOrigins.includes(input.origin)) {
+        return { ok: false, reason: "ORIGIN_NOT_ALLOWED" };
+    }
+    if (input.ports.length !== 1)
+        return { ok: false, reason: "WRONG_PORT_COUNT" };
+    if (input.data.instanceId !== input.expectedInstanceId) {
+        return { ok: false, reason: "INSTANCE_ID_MISMATCH" };
+    }
+    if (input.alreadyAccepted)
+        return { ok: false, reason: "DUPLICATE_TRANSFER" };
+    return { ok: true, envelope: input.data, port: input.ports[0] };
+}
+
+/**
+ * Parses the JSON-encoded `hostMetaData` query parameter from an iframe URL's
+ * search string (per ADR 0029). Returns null on any malformed input — caller
+ * fails fast rather than partially initializing.
+ */
+function readHostMetaData(search) {
+    let params;
+    try {
+        params = new URLSearchParams(search);
+    }
+    catch {
+        return null;
+    }
+    const raw = params.get(HOST_META_DATA_PARAM);
+    if (!raw)
+        return null;
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+    if (typeof parsed !== "object" || parsed === null)
+        return null;
+    const obj = parsed;
+    const instanceId = obj.instanceId;
+    const hostAppOrigin = obj.hostAppOrigin;
+    if (typeof instanceId !== "string" || instanceId.length === 0)
+        return null;
+    if (typeof hostAppOrigin !== "string" || hostAppOrigin.length === 0)
+        return null;
+    // hostAppOrigin is the targetOrigin for postMessage; reject anything that isn't
+    // a syntactically valid origin (scheme://host[:port]) so a malformed value can't
+    // silently drop the heartbeat.
+    try {
+        if (new URL(hostAppOrigin).origin !== hostAppOrigin)
+            return null;
+    }
+    catch {
+        return null;
+    }
+    return { instanceId, hostAppOrigin };
+}
+
+class BootstrapFailureError extends Error {
+    reason;
+    constructor(reason) {
+        super(`sf-embedding bootstrap failed: ${reason}`);
+        this.reason = reason;
+        this.name = "BootstrapFailureError";
+    }
+}
+function installBootstrapListener() {
+    const meta = readHostMetaData(window.location.search);
+    if (!meta) {
+        return Promise.reject(new BootstrapFailureError("MISSING_HOST_METADATA"));
+    }
+    return new Promise((resolve) => {
+        let accepted = false;
+        const handler = (event) => {
+            const result = validateBootstrapEnvelope({
+                data: event.data,
+                source: event.source,
+                origin: event.origin,
+                ports: event.ports,
+                expectedSource: window.parent,
+                allowedOrigins: [meta.hostAppOrigin],
+                expectedInstanceId: meta.instanceId,
+                alreadyAccepted: accepted,
+            });
+            if (!result.ok) {
+                if (result.reason === "DUPLICATE_TRANSFER") {
+                    try {
+                        window.parent.postMessage({ type: SHUTDOWN_TYPE, reason: "DUPLICATE_PORT_TRANSFER" }, meta.hostAppOrigin);
+                    }
+                    catch {
+                        // ignore
+                    }
+                    window.removeEventListener("message", handler);
+                }
+                return;
+            }
+            accepted = true;
+            resolve({ port: result.port, hostMetaData: meta });
+            // Listener stays registered per spec §3.1 — a second valid
+            // envelope MUST trigger the fail-closed shutdown branch above.
+        };
+        window.addEventListener("message", handler);
+        try {
+            window.parent.postMessage({ type: HEARTBEAT_TYPE, instanceId: meta.instanceId }, meta.hostAppOrigin);
+        }
+        catch {
+            // ignore
+        }
+    });
+}
+
+/** Identity emitted on `ui/notifications/embedding-initialized`. */
+const EMBEDDING_INFO = {
+    name: "@salesforce/sf-embedding-bridge",
+    version: "2.2.1-rc.7",
+};
+
+class SessionFailureError extends Error {
+    reason;
+    constructor(reason, cause) {
+        super(`sf-embedding session bootstrap failed: ${reason}`);
+        this.reason = reason;
+        this.name = "SessionFailureError";
+        if (cause !== undefined) {
+            this.cause = cause;
+        }
+    }
+}
+class SessionClient extends jsonrpc.JsonRpcClient {
+    waitForHostInitialized() {
+        return new Promise((resolve) => {
+            this.registerNotificationHandler(HOST_INITIALIZED_METHOD, (params) => {
+                const payload = params && typeof params === "object" && !Array.isArray(params)
+                    ? params
+                    : {};
+                resolve(payload);
+            });
+        });
+    }
+    sendInitializedNotification() {
+        const params = { embeddingInfo: EMBEDDING_INFO };
+        this.sendNotification(EMBEDDING_INITIALIZED_METHOD, params);
+    }
+}
+function rejectOnAbort(signal) {
+    if (!signal)
+        return new Promise(() => { });
+    if (signal.aborted)
+        return Promise.reject(new SessionFailureError("ABORTED"));
+    return new Promise((_, reject) => {
+        signal.addEventListener("abort", () => reject(new SessionFailureError("ABORTED")), { once: true });
+    });
+}
+let sessionPromise = null;
+/**
+ * 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`).
+ */
+function bootstrapSession(options = {}) {
+    if (sessionPromise)
+        return sessionPromise;
+    sessionPromise = installBootstrapListener()
+        .then(async (capture) => {
+        const transport = new jsonrpc.MessageChannelTransport(capture.port);
+        const client = new SessionClient(transport);
+        const hostInitialized = await Promise.race([
+            client.waitForHostInitialized(),
+            rejectOnAbort(options.signal),
+        ]);
+        client.sendInitializedNotification();
+        return {
+            client,
+            hostMetaData: capture.hostMetaData,
+            hostInitialized,
+        };
+    })
+        .catch((err) => {
+        if (err instanceof SessionFailureError)
+            throw err;
+        if (err instanceof Error && "reason" in err) {
+            throw new SessionFailureError(err.reason, err);
+        }
+        throw err;
+    });
+    sessionPromise.catch(() => {
+        // no-op
+    });
+    return sessionPromise;
+}
+
+// Bridge-side error vocabulary: composes the standard JSON-RPC + transport
+// codes from `@salesforce/jsonrpc` with the sf-embedding-specific
+// codes from `@salesforce/sf-embedding-contract`, and wraps `makeJsonRpcError`
+// to inject sf-embedding-specific retryable defaults.
+/** Combined error vocabulary: standard + transport-level + sf-embedding-specific. */
+const ErrorCode = {
+    ...jsonrpc.StandardErrorCode,
+    ...SfEmbeddingErrorCode,
+};
+/** Builds a JSON-RPC error payload with sf-embedding-specific retryable defaults; falls through to @salesforce/jsonrpc for codes it owns. */
+function makeJsonRpcError(code, options = {}) {
+    if (NON_RETRYABLE_CODES.has(code) && options.retryable === undefined) {
+        return jsonrpc.makeJsonRpcError(code, { ...options, retryable: false });
+    }
+    return jsonrpc.makeJsonRpcError(code, options);
+}
+
+exports.BOOTSTRAP_ENVELOPE_TYPE = BOOTSTRAP_ENVELOPE_TYPE;
+exports.BootstrapFailureError = BootstrapFailureError;
+exports.EMBEDDING_INITIALIZED_METHOD = EMBEDDING_INITIALIZED_METHOD;
+exports.ErrorCode = ErrorCode;
+exports.HEARTBEAT_TYPE = HEARTBEAT_TYPE;
+exports.HOST_INITIALIZED_METHOD = HOST_INITIALIZED_METHOD;
+exports.HOST_META_DATA_PARAM = HOST_META_DATA_PARAM;
+exports.HostLwcEvent = HostLwcEvent;
+exports.NON_RETRYABLE_CODES = NON_RETRYABLE_CODES;
+exports.PROTOCOL_NAME = PROTOCOL_NAME;
+exports.SHUTDOWN_TYPE = SHUTDOWN_TYPE;
+exports.SessionFailureError = SessionFailureError;
+exports.SfEmbeddingErrorCode = SfEmbeddingErrorCode;
+exports.bootstrapSession = bootstrapSession;
+exports.isBootstrapEnvelope = isBootstrapEnvelope;
+exports.makeJsonRpcError = makeJsonRpcError;
+exports.readHostMetaData = readHostMetaData;
+exports.validateBootstrapEnvelope = validateBootstrapEnvelope;
+//# sourceMappingURL=index.cjs.js.map

package/dist/index.d.ts

@@ -0,0 +1,382 @@
+/** Wire identifier for this protocol. Carried verbatim on every bootstrap envelope. */
+declare const PROTOCOL_NAME: "sf-embedding";
+/** Discriminator for the host → embedding bootstrap envelope. */
+declare const BOOTSTRAP_ENVELOPE_TYPE: "sf-embedding.bootstrap";
+/** Discriminator for the embedding → host content-free heartbeat. */
+declare const HEARTBEAT_TYPE: "sf-embedding/ready";
+/**
+ * Discriminator for the embedding → host fail-closed shutdown signal
+ * (e.g., duplicate-transfer detection). Posted via window-level postMessage,
+ * not over the JSON-RPC port.
+ */
+declare const SHUTDOWN_TYPE: "sf-embedding/shutdown";
+/** Bootstrap envelope the host transfers to the embedding alongside `port1`. */
+interface BootstrapEnvelope {
+    type: typeof BOOTSTRAP_ENVELOPE_TYPE;
+    protocol: typeof PROTOCOL_NAME;
+    /** Host-minted; byte-for-byte identical to `hostMetaData.instanceId` (MC-10). */
+    instanceId: string;
+    /** Origins the host expects its wrapper chrome to load on; embedding reverse-checks. */
+    allowedOrigins: string[];
+}
+/** Heartbeat the embedding posts to `window.parent` before the port is transferred. */
+interface HeartbeatEnvelope {
+    type: typeof HEARTBEAT_TYPE;
+    /** Mirrors the URL-supplied `hostMetaData.instanceId`; binds the heartbeat to this iframe instance. */
+    instanceId: string;
+}
+/** Embedding-initiated fail-closed shutdown payload (sibling-race detected, etc.). */
+interface ShutdownEnvelope {
+    type: typeof SHUTDOWN_TYPE;
+    /** Free-form; common values: `"DUPLICATE_PORT_TRANSFER"`. */
+    reason?: string;
+}
+
+/** sf-embedding protocol-specific error codes (§8.2 numeric assignments). */
+declare const SfEmbeddingErrorCode: {
+    /** Method exists at selected version but is not granted (§6.5). */
+    readonly CAPABILITY_NOT_ALLOWED: -32010;
+    /** In-flight request gated on a capability that was just revoked (§6.6). */
+    readonly CAPABILITY_REVOKED: -32011;
+    /** Frame arrived before the required handshake step completed (§5.2, §4.2). */
+    readonly NOT_INITIALIZED: -32012;
+    /** Embedding's protocol version is not supported by the host (§4.2, §3.1.2). */
+    readonly PROTOCOL_VERSION_MISMATCH: -32013;
+    /** Frame's origin does not match the bound peer origin (§3.1). */
+    readonly ORIGIN_MISMATCH: -32014;
+    /** Catch-all — duplicate ui/select-version, duplicate ui/discover-capabilities, etc. */
+    readonly PROTOCOL_VIOLATION: -32020;
+    /** Embedding observed a second valid bootstrap envelope and shut down (§3.1.2). */
+    readonly BOOTSTRAP_DUPLICATE_TRANSFER: -32023;
+};
+/** Numeric type of any value in `SfEmbeddingErrorCode`. */
+type SfEmbeddingErrorCodeValue = (typeof SfEmbeddingErrorCode)[keyof typeof SfEmbeddingErrorCode];
+/**
+ * Codes that are non-retryable by default (§8.4). Consumers building error
+ * payloads SHOULD set `retryable: false` automatically for these.
+ */
+declare const NON_RETRYABLE_CODES: ReadonlySet<number>;
+
+/** 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. */
+    readonly READY: "sf-embedding.component.ready";
+    /** Misconfiguration, bootstrap failure, embedding-reported fatal, or protocol violation. */
+    readonly ERROR: "sf-embedding.component.error";
+};
+/** Type-level union of the reserved event names. */
+type HostLwcEventName = (typeof HostLwcEvent)[keyof typeof HostLwcEvent];
+/** Detail of `sf-embedding.component.ready`. */
+interface HostReadyEventDetail {
+    instanceId: string;
+}
+/** Detail of `sf-embedding.component.error` (§12.3). */
+interface HostErrorEventDetail {
+    instanceId?: string;
+    /** Failure category — drives consumer reaction. */
+    phase: "configuration" | "bootstrap" | "session";
+    /** ErrorCode constant or a configuration-error string (e.g. `"SAME_ORIGIN_SRC"`). */
+    code: string;
+    message: string;
+    /**
+     * Whether remount is plausibly fruitful (per spec §12.3).
+     * `true` — transient failures where a fresh attempt may succeed: bootstrap
+     *   handshake timeout, embedding-reported runtime error.
+     * `false` — fix the underlying problem first: configuration errors
+     *   (same-origin src, allow-scripts stripped, malformed src) and protocol
+     *   violations (duplicate port transfer).
+     */
+    retryable: boolean;
+    cause?: unknown;
+}
+
+/** URL query-parameter name carrying the JSON-encoded `HostMetaData`. */
+declare const HOST_META_DATA_PARAM: "hostMetaData";
+/**
+ * Shape of the JSON-encoded `hostMetaData` query parameter on the iframe URL.
+ *
+ * The host MUST write this onto `iframe.src` when assigning it; the embedding
+ * MUST read it before emitting the heartbeat. `hostAppOrigin` is the trust
+ * root for the embedding's inbound bootstrap envelope (MC-8). `instanceId`
+ * binds the inbound bootstrap envelope to this iframe instance (MC-10).
+ */
+interface HostMetaData {
+    hostAppOrigin: string;
+    instanceId: 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. */
+declare const EMBEDDING_INITIALIZED_METHOD: "ui/notifications/embedding-initialized";
+/** Identity of the host or embedding product. */
+interface PeerInfo {
+    name: string;
+    version: string;
+}
+/** Params for `ui/notifications/host-initialized`. */
+interface HostInitializedParams {
+    instanceId: string;
+    hostInfo: PeerInfo;
+}
+/** Params for `ui/notifications/embedding-initialized`. */
+interface EmbeddingInitializedParams {
+    embeddingInfo: PeerInfo;
+}
+
+type BootstrapEnvelopeValidationFailure = "INVALID_SHAPE" | "WRONG_SOURCE" | "ORIGIN_NOT_ALLOWED" | "WRONG_PORT_COUNT" | "INSTANCE_ID_MISMATCH" | "DUPLICATE_TRANSFER";
+type BootstrapEnvelopeValidationResult = {
+    ok: true;
+    envelope: BootstrapEnvelope;
+    port: MessagePort;
+} | {
+    ok: false;
+    reason: BootstrapEnvelopeValidationFailure;
+};
+interface BootstrapEnvelopeValidationInput {
+    data: unknown;
+    source: MessageEventSource | null;
+    origin: string;
+    ports: ReadonlyArray<MessagePort>;
+    expectedSource: MessageEventSource | null;
+    allowedOrigins: ReadonlyArray<string>;
+    expectedInstanceId: string;
+    alreadyAccepted: boolean;
+}
+/** Type guard: true iff `value` is shape-compatible with `BootstrapEnvelope`. */
+declare function isBootstrapEnvelope(value: unknown): value is BootstrapEnvelope;
+/** Validates an inbound bootstrap envelope; never throws — failures returned as typed reasons. */
+declare function validateBootstrapEnvelope(input: BootstrapEnvelopeValidationInput): BootstrapEnvelopeValidationResult;
+
+type BootstrapFailureReason = "MISSING_HOST_METADATA";
+declare class BootstrapFailureError extends Error {
+    readonly reason: BootstrapFailureReason;
+    constructor(reason: BootstrapFailureReason);
+}
+
+/**
+ * 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)
+ */
+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;
+}
+
+/**
+ * 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));
+ *   }
+ * }
+ */
+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;
+}
+
+/** Structure of the `data` field on a JSON-RPC error payload. */
+interface JsonRpcErrorData {
+    retryable?: boolean;
+    details?: Record<string, unknown>;
+}
+/** Shape of a JSON-RPC error payload (the value under `error` on an error response). */
+interface JsonRpcErrorPayload {
+    code: number;
+    message?: string;
+    data?: JsonRpcErrorData;
+}
+
+type HostInitializedPayload = Record<string, unknown>;
+interface SessionHandle {
+    client: JsonRpcClient;
+    hostMetaData: HostMetaData;
+    hostInitialized: HostInitializedPayload;
+}
+type SessionFailureReason = BootstrapFailureReason | "ABORTED";
+declare class SessionFailureError extends Error {
+    readonly reason: SessionFailureReason;
+    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.
+     */
+    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`).
+ */
+declare function bootstrapSession(options?: BootstrapSessionOptions): Promise<SessionHandle>;
+
+/** Combined error vocabulary: standard + transport-level + sf-embedding-specific. */
+declare const ErrorCode: {
+    readonly CAPABILITY_NOT_ALLOWED: -32010;
+    readonly CAPABILITY_REVOKED: -32011;
+    readonly NOT_INITIALIZED: -32012;
+    readonly PROTOCOL_VERSION_MISMATCH: -32013;
+    readonly ORIGIN_MISMATCH: -32014;
+    readonly PROTOCOL_VIOLATION: -32020;
+    readonly BOOTSTRAP_DUPLICATE_TRANSFER: -32023;
+    readonly PARSE_ERROR: -32700;
+    readonly INVALID_REQUEST: -32600;
+    readonly METHOD_NOT_FOUND: -32601;
+    readonly INVALID_PARAMS: -32602;
+    readonly INTERNAL_ERROR: -32603;
+    readonly PORT_CLOSED: -32016;
+    readonly SERIALIZATION_FAILURE: -32017;
+    readonly REQUEST_TIMEOUT: -32018;
+    readonly BACKPRESSURE: -32019;
+    readonly REQUEST_CANCELLED: -32024;
+};
+/** Numeric type of any value in `ErrorCode`. */
+type ErrorCodeValue = (typeof ErrorCode)[keyof typeof ErrorCode];
+/** Builds a JSON-RPC error payload with sf-embedding-specific retryable defaults; falls through to @salesforce/jsonrpc for codes it owns. */
+declare function makeJsonRpcError(code: number, options?: {
+    message?: string;
+    details?: Record<string, unknown>;
+    retryable?: boolean;
+}): JsonRpcErrorPayload;
+
+/**
+ * Parses the JSON-encoded `hostMetaData` query parameter from an iframe URL's
+ * search string (per ADR 0029). Returns null on any malformed input — caller
+ * fails fast rather than partially initializing.
+ */
+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 };

package/dist/index.esm.js

@@ -0,0 +1,313 @@
+import { MessageChannelTransport, JsonRpcClient, StandardErrorCode, makeJsonRpcError as makeJsonRpcError$1 } from '@salesforce/jsonrpc';
+
+// Bootstrap envelope vocabulary. Spec: EMBEDDING-PROTOCOL.md §3.1, §3.1.1,
+// MC-7/MC-8/MC-10 in §2.2.
+/** Wire identifier for this protocol. Carried verbatim on every bootstrap envelope. */
+const PROTOCOL_NAME = "sf-embedding";
+/** Discriminator for the host → embedding bootstrap envelope. */
+const BOOTSTRAP_ENVELOPE_TYPE = "sf-embedding.bootstrap";
+/** Discriminator for the embedding → host content-free heartbeat. */
+const HEARTBEAT_TYPE = "sf-embedding/ready";
+/**
+ * Discriminator for the embedding → host fail-closed shutdown signal
+ * (e.g., duplicate-transfer detection). Posted via window-level postMessage,
+ * not over the JSON-RPC port.
+ */
+const SHUTDOWN_TYPE = "sf-embedding/shutdown";
+
+// sf-embedding protocol-specific JSON-RPC error codes. Spec §8.2.
+//
+// Standard JSON-RPC codes (-32700, -32600..-32603) and transport-level codes
+// (PORT_CLOSED, SERIALIZATION_FAILURE, REQUEST_TIMEOUT, BACKPRESSURE,
+// REQUEST_CANCELLED) live in `@salesforce/jsonrpc`'s
+// `StandardErrorCode` and are NOT re-exported here. Consumers that need the
+// merged vocabulary compose them at the call site.
+/** sf-embedding protocol-specific error codes (§8.2 numeric assignments). */
+const SfEmbeddingErrorCode = {
+    /** Method exists at selected version but is not granted (§6.5). */
+    CAPABILITY_NOT_ALLOWED: -32010,
+    /** In-flight request gated on a capability that was just revoked (§6.6). */
+    CAPABILITY_REVOKED: -32011,
+    /** Frame arrived before the required handshake step completed (§5.2, §4.2). */
+    NOT_INITIALIZED: -32012,
+    /** Embedding's protocol version is not supported by the host (§4.2, §3.1.2). */
+    PROTOCOL_VERSION_MISMATCH: -32013,
+    /** Frame's origin does not match the bound peer origin (§3.1). */
+    ORIGIN_MISMATCH: -32014,
+    /** Catch-all — duplicate ui/select-version, duplicate ui/discover-capabilities, etc. */
+    PROTOCOL_VIOLATION: -32020,
+    /** Embedding observed a second valid bootstrap envelope and shut down (§3.1.2). */
+    BOOTSTRAP_DUPLICATE_TRANSFER: -32023,
+};
+/**
+ * Codes that are non-retryable by default (§8.4). Consumers building error
+ * payloads SHOULD set `retryable: false` automatically for these.
+ */
+const NON_RETRYABLE_CODES = new Set([
+    SfEmbeddingErrorCode.CAPABILITY_NOT_ALLOWED,
+    SfEmbeddingErrorCode.CAPABILITY_REVOKED,
+    SfEmbeddingErrorCode.ORIGIN_MISMATCH,
+]);
+
+// Host LWC reserved DOM event names and detail shapes. Spec §12.3.
+//
+// These are dispatched by the host LWC on its own element so application
+// code on the page can react. The embedding never observes them.
+/** Event names the host LWC dispatches on its own element. Reserved by the protocol. */
+const HostLwcEvent = {
+    /** Synchronous with `ui/discover-capabilities` response; session reaches READY. */
+    READY: "sf-embedding.component.ready",
+    /** Misconfiguration, bootstrap failure, embedding-reported fatal, or protocol violation. */
+    ERROR: "sf-embedding.component.error",
+};
+
+// Host-supplied iframe URL metadata (per ADR 0029). Spec §3.1, MC-8/MC-10.
+/** URL query-parameter name carrying the JSON-encoded `HostMetaData`. */
+const HOST_META_DATA_PARAM = "hostMetaData";
+
+// JSON-RPC method names on the wire today.
+/** Host announces session identity to the embedding over the port. */
+const HOST_INITIALIZED_METHOD = "ui/notifications/host-initialized";
+/** Embedding acknowledges receipt of `host-initialized`. Fire-and-forget. */
+const EMBEDDING_INITIALIZED_METHOD = "ui/notifications/embedding-initialized";
+
+// Bootstrap envelope validator for the iframe (embedding) side of the
+// sf-embedding handshake.
+//
+// Wire-format types and discriminator constants live in
+// `@salesforce/sf-embedding-contract`; consumers MUST import them from there.
+// This module owns only the embedding-side validator
+// (`validateBootstrapEnvelope`) and its supporting types — intentionally NOT
+// in the contract package because the host and embedding sides have
+// different validation rules per spec §3.1.2.
+/** Type guard: true iff `value` is shape-compatible with `BootstrapEnvelope`. */
+function isBootstrapEnvelope(value) {
+    if (typeof value !== "object" || value === null || Array.isArray(value))
+        return false;
+    const v = value;
+    if (v.type !== BOOTSTRAP_ENVELOPE_TYPE)
+        return false;
+    if (v.protocol !== PROTOCOL_NAME)
+        return false;
+    if (typeof v.instanceId !== "string" || v.instanceId.length === 0)
+        return false;
+    if (!Array.isArray(v.allowedOrigins))
+        return false;
+    return v.allowedOrigins.every((o) => typeof o === "string");
+}
+/** Validates an inbound bootstrap envelope; never throws — failures returned as typed reasons. */
+function validateBootstrapEnvelope(input) {
+    if (!isBootstrapEnvelope(input.data))
+        return { ok: false, reason: "INVALID_SHAPE" };
+    if (input.source !== input.expectedSource)
+        return { ok: false, reason: "WRONG_SOURCE" };
+    if (!input.allowedOrigins.includes(input.origin)) {
+        return { ok: false, reason: "ORIGIN_NOT_ALLOWED" };
+    }
+    if (input.ports.length !== 1)
+        return { ok: false, reason: "WRONG_PORT_COUNT" };
+    if (input.data.instanceId !== input.expectedInstanceId) {
+        return { ok: false, reason: "INSTANCE_ID_MISMATCH" };
+    }
+    if (input.alreadyAccepted)
+        return { ok: false, reason: "DUPLICATE_TRANSFER" };
+    return { ok: true, envelope: input.data, port: input.ports[0] };
+}
+
+/**
+ * Parses the JSON-encoded `hostMetaData` query parameter from an iframe URL's
+ * search string (per ADR 0029). Returns null on any malformed input — caller
+ * fails fast rather than partially initializing.
+ */
+function readHostMetaData(search) {
+    let params;
+    try {
+        params = new URLSearchParams(search);
+    }
+    catch {
+        return null;
+    }
+    const raw = params.get(HOST_META_DATA_PARAM);
+    if (!raw)
+        return null;
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+    if (typeof parsed !== "object" || parsed === null)
+        return null;
+    const obj = parsed;
+    const instanceId = obj.instanceId;
+    const hostAppOrigin = obj.hostAppOrigin;
+    if (typeof instanceId !== "string" || instanceId.length === 0)
+        return null;
+    if (typeof hostAppOrigin !== "string" || hostAppOrigin.length === 0)
+        return null;
+    // hostAppOrigin is the targetOrigin for postMessage; reject anything that isn't
+    // a syntactically valid origin (scheme://host[:port]) so a malformed value can't
+    // silently drop the heartbeat.
+    try {
+        if (new URL(hostAppOrigin).origin !== hostAppOrigin)
+            return null;
+    }
+    catch {
+        return null;
+    }
+    return { instanceId, hostAppOrigin };
+}
+
+class BootstrapFailureError extends Error {
+    reason;
+    constructor(reason) {
+        super(`sf-embedding bootstrap failed: ${reason}`);
+        this.reason = reason;
+        this.name = "BootstrapFailureError";
+    }
+}
+function installBootstrapListener() {
+    const meta = readHostMetaData(window.location.search);
+    if (!meta) {
+        return Promise.reject(new BootstrapFailureError("MISSING_HOST_METADATA"));
+    }
+    return new Promise((resolve) => {
+        let accepted = false;
+        const handler = (event) => {
+            const result = validateBootstrapEnvelope({
+                data: event.data,
+                source: event.source,
+                origin: event.origin,
+                ports: event.ports,
+                expectedSource: window.parent,
+                allowedOrigins: [meta.hostAppOrigin],
+                expectedInstanceId: meta.instanceId,
+                alreadyAccepted: accepted,
+            });
+            if (!result.ok) {
+                if (result.reason === "DUPLICATE_TRANSFER") {
+                    try {
+                        window.parent.postMessage({ type: SHUTDOWN_TYPE, reason: "DUPLICATE_PORT_TRANSFER" }, meta.hostAppOrigin);
+                    }
+                    catch {
+                        // ignore
+                    }
+                    window.removeEventListener("message", handler);
+                }
+                return;
+            }
+            accepted = true;
+            resolve({ port: result.port, hostMetaData: meta });
+            // Listener stays registered per spec §3.1 — a second valid
+            // envelope MUST trigger the fail-closed shutdown branch above.
+        };
+        window.addEventListener("message", handler);
+        try {
+            window.parent.postMessage({ type: HEARTBEAT_TYPE, instanceId: meta.instanceId }, meta.hostAppOrigin);
+        }
+        catch {
+            // ignore
+        }
+    });
+}
+
+/** Identity emitted on `ui/notifications/embedding-initialized`. */
+const EMBEDDING_INFO = {
+    name: "@salesforce/sf-embedding-bridge",
+    version: "2.2.1-rc.7",
+};
+
+class SessionFailureError extends Error {
+    reason;
+    constructor(reason, cause) {
+        super(`sf-embedding session bootstrap failed: ${reason}`);
+        this.reason = reason;
+        this.name = "SessionFailureError";
+        if (cause !== undefined) {
+            this.cause = cause;
+        }
+    }
+}
+class SessionClient extends JsonRpcClient {
+    waitForHostInitialized() {
+        return new Promise((resolve) => {
+            this.registerNotificationHandler(HOST_INITIALIZED_METHOD, (params) => {
+                const payload = params && typeof params === "object" && !Array.isArray(params)
+                    ? params
+                    : {};
+                resolve(payload);
+            });
+        });
+    }
+    sendInitializedNotification() {
+        const params = { embeddingInfo: EMBEDDING_INFO };
+        this.sendNotification(EMBEDDING_INITIALIZED_METHOD, params);
+    }
+}
+function rejectOnAbort(signal) {
+    if (!signal)
+        return new Promise(() => { });
+    if (signal.aborted)
+        return Promise.reject(new SessionFailureError("ABORTED"));
+    return new Promise((_, reject) => {
+        signal.addEventListener("abort", () => reject(new SessionFailureError("ABORTED")), { once: true });
+    });
+}
+let sessionPromise = null;
+/**
+ * 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`).
+ */
+function bootstrapSession(options = {}) {
+    if (sessionPromise)
+        return sessionPromise;
+    sessionPromise = installBootstrapListener()
+        .then(async (capture) => {
+        const transport = new MessageChannelTransport(capture.port);
+        const client = new SessionClient(transport);
+        const hostInitialized = await Promise.race([
+            client.waitForHostInitialized(),
+            rejectOnAbort(options.signal),
+        ]);
+        client.sendInitializedNotification();
+        return {
+            client,
+            hostMetaData: capture.hostMetaData,
+            hostInitialized,
+        };
+    })
+        .catch((err) => {
+        if (err instanceof SessionFailureError)
+            throw err;
+        if (err instanceof Error && "reason" in err) {
+            throw new SessionFailureError(err.reason, err);
+        }
+        throw err;
+    });
+    sessionPromise.catch(() => {
+        // no-op
+    });
+    return sessionPromise;
+}
+
+// Bridge-side error vocabulary: composes the standard JSON-RPC + transport
+// codes from `@salesforce/jsonrpc` with the sf-embedding-specific
+// codes from `@salesforce/sf-embedding-contract`, and wraps `makeJsonRpcError`
+// to inject sf-embedding-specific retryable defaults.
+/** Combined error vocabulary: standard + transport-level + sf-embedding-specific. */
+const ErrorCode = {
+    ...StandardErrorCode,
+    ...SfEmbeddingErrorCode,
+};
+/** Builds a JSON-RPC error payload with sf-embedding-specific retryable defaults; falls through to @salesforce/jsonrpc for codes it owns. */
+function makeJsonRpcError(code, options = {}) {
+    if (NON_RETRYABLE_CODES.has(code) && options.retryable === undefined) {
+        return makeJsonRpcError$1(code, { ...options, retryable: false });
+    }
+    return makeJsonRpcError$1(code, options);
+}
+
+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 };
+//# sourceMappingURL=index.esm.js.map

package/package.json

@@ -1,10 +1,42 @@
 {
-  "name": "@salesforce/sf-embedding-bridge",
-  "version": "0.0.1",
-  "description": "OIDC trusted publishing setup package for @salesforce/sf-embedding-bridge",
-  "keywords": [
-    "oidc",
-    "trusted-publishing",
-    "setup"
-  ]
+    "name": "@salesforce/sf-embedding-bridge",
+    "version": "2.2.1-rc.7",
+    "private": false,
+    "description": "JSON-RPC 2.0 bridge for the sf-embedding host ↔ embedding protocol",
+    "license": "SEE LICENSE IN LICENSE.txt",
+    "author": "Salesforce ECS Team",
+    "main": "dist/index.cjs.js",
+    "module": "dist/index.esm.js",
+    "types": "dist/index.d.ts",
+    "exports": {
+        ".": {
+            "types": "./dist/index.d.ts",
+            "import": "./dist/index.esm.js",
+            "require": "./dist/index.cjs.js",
+            "default": "./dist/index.esm.js"
+        }
+    },
+    "scripts": {
+        "build": "rollup -c",
+        "test": "jest --passWithNoTests"
+    },
+    "dependencies": {
+        "@salesforce/jsonrpc": "^9.13.0"
+    },
+    "devDependencies": {
+        "@salesforce/sf-embedding-contract": "2.2.1-rc.7"
+    },
+    "files": [
+        "dist/",
+        "!dist/__tests__/",
+        "!dist/__mocks__/",
+        "!dist/*.test.js",
+        "!dist/*.map",
+        "README.md",
+        "LICENSE.txt"
+    ],
+    "publishConfig": {
+        "access": "public"
+    },
+    "sideEffects": false
 }

package/README.md

@@ -1,45 +0,0 @@
-# @salesforce/sf-embedding-bridge
-
-## ⚠️ IMPORTANT NOTICE ⚠️
-
-**This package is created solely for the purpose of setting up OIDC (OpenID Connect) trusted publishing with npm.**
-
-This is **NOT** a functional package and contains **NO** code or functionality beyond the OIDC setup configuration.
-
-## Purpose
-
-This package exists to:
-1. Configure OIDC trusted publishing for the package name `@salesforce/sf-embedding-bridge`
-2. Enable secure, token-less publishing from CI/CD workflows
-3. Establish provenance for packages published under this name
-
-## What is OIDC Trusted Publishing?
-
-OIDC trusted publishing allows package maintainers to publish packages directly from their CI/CD workflows without needing to manage npm access tokens. Instead, it uses OpenID Connect to establish trust between the CI/CD provider (like GitHub Actions) and npm.
-
-## Setup Instructions
-
-To properly configure OIDC trusted publishing for this package:
-
-1. Go to [npmjs.com](https://www.npmjs.com/) and navigate to your package settings
-2. Configure the trusted publisher (e.g., GitHub Actions)
-3. Specify the repository and workflow that should be allowed to publish
-4. Use the configured workflow to publish your actual package
-
-## DO NOT USE THIS PACKAGE
-
-This package is a placeholder for OIDC configuration only. It:
-- Contains no executable code
-- Provides no functionality
-- Should not be installed as a dependency
-- Exists only for administrative purposes
-
-## More Information
-
-For more details about npm's trusted publishing feature, see:
-- [npm Trusted Publishing Documentation](https://docs.npmjs.com/generating-provenance-statements)
-- [GitHub Actions OIDC Documentation](https://docs.github.com/en/actions/deployment/security-hardening-your-deployments/about-security-hardening-with-openid-connect)
-
----
-
-**Maintained for OIDC setup purposes only**