@salesforce/agentforce-conversation-client 11.49.4 → 11.51.0

package/dist/ui-bundle.d.ts

@@ -0,0 +1,93 @@
+/**
+ * Copyright (c) 2026, Salesforce, Inc.,
+ * All rights reserved.
+ * For full license text, see the LICENSE.txt file
+ */
+/**
+ * Framework-agnostic glue for embedding the Agentforce Conversation Client (ACC)
+ * via Lightning Out. This is the shared orchestration that used to be duplicated
+ * across the React `AgentforceConversationClient` component and the Angular
+ * `AgentforceEmbedService`:
+ *
+ *  - a window-scoped singleton so exactly one embed happens per window, no matter
+ *    how many client wrappers mount;
+ *  - a shared body-level host for floating mode (created on demand);
+ *  - auth resolution — the dev frontdoor URL (`/__lo/frontdoor`) on localhost,
+ *    `SFDC_ENV.orgUrl` otherwise — merged with caller overrides;
+ *  - detection of an already-embedded client (`lightning-out-application[data-lo="acc"]`)
+ *    and cleanup of a partially-created element so the next mount can retry.
+ *
+ * Shipped as the `@salesforce/agentforce-conversation-client/ui-bundle` subpath
+ * so it lives alongside the low-level `embedAgentforceClient` it orchestrates.
+ * It still takes that embed function by dependency injection rather than
+ * importing it directly, which keeps the glue framework-agnostic and unit-testable
+ * with a mock embed function. The React/Angular feature templates own the import
+ * and hand the function to {@link createAccEmbedder}.
+ */
+/** ACC ready callback — receives the Lightning Out ready detail. */
+export type AccReadyHandler = (detail: unknown) => void;
+/** ACC error callback — receives the Lightning Out error event. */
+export type AccErrorHandler = (error: unknown) => void;
+/** Auth options resolved at embed time (frontdoor in dev, org URL in prod). */
+export interface AccEmbedOverrides {
+    salesforceOrigin?: string;
+    frontdoorUrl?: string;
+}
+/**
+ * Optional ready/error handlers forwarded to the embed function. Declared with
+ * method syntax so a caller's handler typed against a *narrower* event type
+ * (e.g. ACC's `AgentforceErrorHandler`, whose param is a concrete error event)
+ * remains assignable — the glue only forwards these callbacks, never invokes
+ * them itself, so bivariance here is safe.
+ */
+export interface AccEmbedHandlers {
+    onReady?(detail: unknown): void;
+    onError?(error: unknown): void;
+}
+/**
+ * Minimal structural shape the glue needs to read off the client config
+ * (rendering mode + agent id). Kept intentionally loose so the concrete
+ * `AgentforceClientConfig` satisfies it structurally.
+ */
+export interface AccConfigShape {
+    agentId?: string;
+    renderingConfig?: {
+        mode?: string;
+    };
+}
+/** Options the injected embed function is called with. */
+export interface AccEmbedRequest<TConfig extends AccConfigShape> {
+    container: HTMLElement;
+    salesforceOrigin?: string;
+    frontdoorUrl?: string;
+    agentforceClientConfig?: TConfig;
+    onReady?: AccReadyHandler;
+    onError?: AccErrorHandler;
+}
+/**
+ * The low-level embed function (structurally, ACC's `embedAgentforceClient`),
+ * supplied by the caller. Its return value is ignored by the glue.
+ */
+export type AccEmbedFn<TConfig extends AccConfigShape> = (options: AccEmbedRequest<TConfig>) => unknown;
+/** A configured embedder that guarantees a single embed per window. */
+export interface AccEmbedder<TConfig extends AccConfigShape> {
+    /**
+     * Embed the client once. Subsequent calls are no-ops while an embed is in
+     * flight or already complete. For inline mode, `host` is the container the
+     * client renders into; when omitted (floating mode) a shared body-level host
+     * is used. `overrides` win over the resolved defaults.
+     */
+    embedAcc(config: TConfig, overrides?: AccEmbedOverrides, host?: HTMLElement | null, handlers?: AccEmbedHandlers): void;
+}
+/**
+ * Create an embedder bound to a low-level embed function.
+ *
+ * @example
+ * import { embedAgentforceClient } from "@salesforce/agentforce-conversation-client";
+ * import { createAccEmbedder } from "@salesforce/agentforce-conversation-client/ui-bundle";
+ *
+ * const embedder = createAccEmbedder(embedAgentforceClient);
+ * embedder.embedAcc(config, { salesforceOrigin }, hostEl, { onReady, onError });
+ */
+export declare function createAccEmbedder<TConfig extends AccConfigShape>(embedFn: AccEmbedFn<TConfig>): AccEmbedder<TConfig>;
+//# sourceMappingURL=ui-bundle.d.ts.map

package/dist/ui-bundle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ui-bundle.d.ts","sourceRoot":"","sources":["../src/ui-bundle.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,oEAAoE;AACpE,MAAM,MAAM,eAAe,GAAG,CAAC,MAAM,EAAE,OAAO,KAAK,IAAI,CAAC;AAExD,mEAAmE;AACnE,MAAM,MAAM,eAAe,GAAG,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC;AAEvD,+EAA+E;AAC/E,MAAM,WAAW,iBAAiB;IACjC,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,YAAY,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,gBAAgB;IAChC,OAAO,CAAC,CAAC,MAAM,EAAE,OAAO,GAAG,IAAI,CAAC;IAChC,OAAO,CAAC,CAAC,KAAK,EAAE,OAAO,GAAG,IAAI,CAAC;CAC/B;AAED;;;;GAIG;AACH,MAAM,WAAW,cAAc;IAC9B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,eAAe,CAAC,EAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;CACpC;AAED,0DAA0D;AAC1D,MAAM,WAAW,eAAe,CAAC,OAAO,SAAS,cAAc;IAC9D,SAAS,EAAE,WAAW,CAAC;IACvB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,sBAAsB,CAAC,EAAE,OAAO,CAAC;IACjC,OAAO,CAAC,EAAE,eAAe,CAAC;IAC1B,OAAO,CAAC,EAAE,eAAe,CAAC;CAC1B;AAED;;;GAGG;AACH,MAAM,MAAM,UAAU,CAAC,OAAO,SAAS,cAAc,IAAI,CACxD,OAAO,EAAE,eAAe,CAAC,OAAO,CAAC,KAC7B,OAAO,CAAC;AAEb,uEAAuE;AACvE,MAAM,WAAW,WAAW,CAAC,OAAO,SAAS,cAAc;IAC1D;;;;;OAKG;IACH,QAAQ,CACP,MAAM,EAAE,OAAO,EACf,SAAS,CAAC,EAAE,iBAAiB,EAC7B,IAAI,CAAC,EAAE,WAAW,GAAG,IAAI,EACzB,QAAQ,CAAC,EAAE,gBAAgB,GACzB,IAAI,CAAC;CACR;AAqDD;;;;;;;;;GASG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,SAAS,cAAc,EAC/D,OAAO,EAAE,UAAU,CAAC,OAAO,CAAC,GAC1B,WAAW,CAAC,OAAO,CAAC,CAuGtB"}

package/dist/ui-bundle.js

@@ -0,0 +1,141 @@
+/**
+ * Copyright (c) 2026, Salesforce, Inc.,
+ * All rights reserved.
+ * For full license text, see the LICENSE.txt file
+ */
+const GLOBAL_HOST_ID = "agentforce-conversation-client-global-host";
+const EXISTING_EMBED_SELECTOR = 'lightning-out-application[data-lo="acc"]';
+const SINGLETON_KEY = "__agentforceConversationClientSingleton";
+const INLINE_MODE = "inline";
+/**
+ * Window-scoped singleton. Storing this on `window` (rather than in a module
+ * closure) preserves the original React "one embed per window" behavior even
+ * across multiple embedder instances or module re-evaluation (HMR).
+ */
+function getSingleton() {
+    const win = window;
+    if (!win[SINGLETON_KEY]) {
+        win[SINGLETON_KEY] = { initialized: false };
+    }
+    return win[SINGLETON_KEY];
+}
+function getOrCreateGlobalHost() {
+    let host = document.getElementById(GLOBAL_HOST_ID);
+    if (!host) {
+        host = document.createElement("div");
+        host.id = GLOBAL_HOST_ID;
+        document.body.appendChild(host);
+    }
+    return host;
+}
+function getDefaultEmbedOptions() {
+    const sfdcEnv = globalThis.SFDC_ENV;
+    return { salesforceOrigin: sfdcEnv?.orgUrl };
+}
+/** Drop keys with undefined/null values so they don't clobber defaults when spread. */
+function stripUndefined(opts) {
+    return Object.fromEntries(Object.entries(opts).filter(([, v]) => v != null));
+}
+/**
+ * Create an embedder bound to a low-level embed function.
+ *
+ * @example
+ * import { embedAgentforceClient } from "@salesforce/agentforce-conversation-client";
+ * import { createAccEmbedder } from "@salesforce/agentforce-conversation-client/ui-bundle";
+ *
+ * const embedder = createAccEmbedder(embedAgentforceClient);
+ * embedder.embedAcc(config, { salesforceOrigin }, hostEl, { onReady, onError });
+ */
+export function createAccEmbedder(embedFn) {
+    function embedAcc(config, overrides = {}, host, handlers) {
+        if (!config.agentId) {
+            throw new Error("AgentforceConversationClient requires agentId. " +
+                "Pass flat props only (agentId, agentLabel, inline, headerEnabled, showHeaderIcon, width, height, styleTokens).");
+        }
+        const inline = config.renderingConfig?.mode === INLINE_MODE;
+        if (inline && !host) {
+            // Inline host not yet in the DOM — the wrapper retries after render.
+            return;
+        }
+        const singleton = getSingleton();
+        if (singleton.initialized || singleton.initPromise) {
+            return;
+        }
+        const initialize = (options) => {
+            if (singleton.initialized) {
+                return;
+            }
+            if (document.querySelector(EXISTING_EMBED_SELECTOR)) {
+                singleton.initialized = true;
+                return;
+            }
+            const container = inline ? host : getOrCreateGlobalHost();
+            try {
+                // Lightning Out treats `org-url` and `frontdoor-url` as mutually
+                // exclusive — setting both throws. The dev frontdoor URL (localhost)
+                // wins when present; otherwise fall back to the org URL.
+                const useFrontdoor = Boolean(options.frontdoorUrl);
+                embedFn({
+                    container,
+                    salesforceOrigin: useFrontdoor ? undefined : options.salesforceOrigin,
+                    frontdoorUrl: options.frontdoorUrl,
+                    agentforceClientConfig: config,
+                    onReady: handlers?.onReady,
+                    onError: handlers?.onError,
+                });
+                singleton.initialized = true;
+            }
+            catch (err) {
+                // Strip a partially-created LO element so the next mount can retry.
+                document.querySelector(EXISTING_EMBED_SELECTOR)?.remove();
+                console.error("AgentforceConversationClient: initialization failed", err);
+            }
+        };
+        const safeInitialize = (options) => {
+            try {
+                initialize(options);
+            }
+            catch (initErr) {
+                console.error("AgentforceConversationClient: initialization failed", initErr);
+                singleton.initialized = false;
+            }
+        };
+        const resolved = { ...getDefaultEmbedOptions(), ...stripUndefined(overrides) };
+        const shouldFetchFrontdoor = window.location.hostname === "localhost";
+        if (shouldFetchFrontdoor) {
+            singleton.initPromise = fetch("/__lo/frontdoor")
+                .then(async (res) => {
+                if (!res.ok) {
+                    console.error("frontdoor fetch failed");
+                    return;
+                }
+                const { frontdoorUrl: resolvedFrontdoorUrl } = await res.json();
+                // An explicit caller-supplied frontdoorUrl override wins over the dev
+                // `/__lo/frontdoor` value; otherwise fall back to the fetched one.
+                safeInitialize({
+                    ...resolved,
+                    frontdoorUrl: resolved.frontdoorUrl ?? resolvedFrontdoorUrl,
+                });
+            })
+                .catch((err) => {
+                console.error("AgentforceConversationClient: failed to fetch frontdoor URL", err);
+            })
+                .finally(() => {
+                singleton.initPromise = undefined;
+            });
+        }
+        else {
+            singleton.initPromise = Promise.resolve()
+                .then(() => {
+                safeInitialize(resolved);
+            })
+                .catch((err) => {
+                console.error("AgentforceConversationClient: failed to embed Agentforce client", err);
+            })
+                .finally(() => {
+                singleton.initPromise = undefined;
+            });
+        }
+    }
+    return { embedAcc };
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@salesforce/agentforce-conversation-client",
   "description": "Agentforce Conversation Client SDK for embedding via Lightning Out 2.0",
-  "version": "11.49.4",
+  "version": "11.51.0",
   "license": "SEE LICENSE IN LICENSE.txt",
   "type": "module",
   "main": "./dist/index.js",
@@ -12,6 +12,10 @@
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js"
     },
+    "./ui-bundle": {
+      "types": "./dist/ui-bundle.d.ts",
+      "import": "./dist/ui-bundle.js"
+    },
     "./package.json": "./package.json"
   },
   "files": [