@salesforce/agentforce-conversation-client 9.9.3 → 9.10.0

package/README.md

@@ -355,6 +355,38 @@ const { loApp } = embedAgentforceClient({
 
 ### Listening for Events
 
+#### Callback props (recommended)
+
+Use the `onReady` and `onError` callback options for a simpler, declarative approach:
+
+```typescript
+import { embedAgentforceClient } from "@salesforce/agentforce-conversation-client";
+
+embedAgentforceClient({
+  container: "#agentforce-container",
+  salesforceOrigin: "https://myorg.my.salesforce.com",
+  onReady: (detail) => {
+    console.log("Lightning Out is ready", detail);
+  },
+  onError: (error) => {
+    // error.type is "lo.application.error" or "lo.iframe.error"
+    // error.detail contains the error payload from Lightning Out
+    console.error(`[${error.type}]`, error.detail);
+  },
+});
+```
+
+| Callback  | Fires when                                                      | Argument shape                                                           |
+| --------- | --------------------------------------------------------------- | ------------------------------------------------------------------------ |
+| `onReady` | Lightning Out application has finished loading                  | `detail: unknown` — the raw detail from the `lo.application.ready` event |
+| `onError` | An application-level or iframe-level Lightning Out error occurs | `{ type: "lo.application.error" \| "lo.iframe.error", detail: unknown }` |
+
+Both callbacks are optional.
+
+#### Low-level event listeners
+
+For finer-grained control (e.g. `lo.component.ready`, `lo.application.logout`), use the returned `loApp` element directly:
+
 ```typescript
 const { loApp } = embedAgentforceClient({
   container: "#agentforce-container",
@@ -401,6 +433,8 @@ Embeds the Agentforce Conversation Client by creating a Lightning Out 2.0 app an
 | `agentforceClientConfig.renderingConfig.headerEnabled`  | `boolean`                | No       | Show or hide the chat header bar. Defaults to hidden in inline mode. Set `true` to show it                                                       |
 | `agentforceClientConfig.renderingConfig.showHeaderIcon` | `boolean`                | No       | Show or hide the icon in the header. Omit or set `false` to hide                                                                                 |
 | `agentforceClientConfig.renderingConfig.showAvatar`     | `boolean`                | No       | Show or hide avatars in message rows. Defaults to `true`                                                                                         |
+| `options.onReady`                                       | `AgentforceReadyHandler` | No       | Callback invoked when the Lightning Out application is ready. Receives the event detail                                                          |
+| `options.onError`                                       | `AgentforceErrorHandler` | No       | Callback invoked on Lightning Out errors. Receives `{ type, detail }` with the error source and payload                                          |
 
 #### Returns
 
@@ -432,6 +466,15 @@ interface AgentforceClientConfig {
   };
 }
 
+// Error event passed to the onError callback
+interface AgentforceLoErrorEvent {
+  type: "lo.application.error" | "lo.iframe.error";
+  detail: unknown;
+}
+
+type AgentforceErrorHandler = (error: AgentforceLoErrorEvent) => void;
+type AgentforceReadyHandler = (detail: unknown) => void;
+
 interface EmbedAgentforceClientOptions {
   container: string | HTMLElement;
   salesforceOrigin?: string;
@@ -439,6 +482,8 @@ interface EmbedAgentforceClientOptions {
   frontdoorUrl?: string;
   sitePrefix?: string;
   agentforceClientConfig?: AgentforceClientConfig;
+  onReady?: AgentforceReadyHandler;
+  onError?: AgentforceErrorHandler;
 }
 
 interface EmbedAgentforceClientResult {

package/dist/index.d.ts

@@ -29,6 +29,12 @@ export interface AgentforceClientConfig {
     };
     channel?: string;
 }
+export interface AgentforceLoErrorEvent {
+    type: "lo.application.error" | "lo.iframe.error";
+    detail: unknown;
+}
+export type AgentforceErrorHandler = (error: AgentforceLoErrorEvent) => void;
+export type AgentforceReadyHandler = (detail: unknown) => void;
 export interface EmbedAgentforceClientOptions {
     container: string | HTMLElement;
     salesforceOrigin?: string;
@@ -36,6 +42,8 @@ export interface EmbedAgentforceClientOptions {
     frontdoorUrl?: string;
     sitePrefix?: string;
     agentforceClientConfig?: AgentforceClientConfig;
+    onError?: AgentforceErrorHandler;
+    onReady?: AgentforceReadyHandler;
 }
 export interface EmbedAgentforceClientResult {
     loApp: LightningOutApplication;

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EAAE,uBAAuB,EAAE,MAAM,4BAA4B,CAAC;AAMrE,eAAO,MAAM,6BAA6B,oCAAoC,CAAC;AAC/E,eAAO,MAAM,2BAA2B,oBAAoB,CAAC;AAC7D,eAAO,MAAM,gCAAgC,kBAAkB,CAAC;AAChE,eAAO,MAAM,2BAA2B,YAAY,CAAC;AACrD,eAAO,MAAM,sCAAsC,qEAA2G,CAAC;AAE/J,eAAO,MAAM,aAAa;;;EAGf,CAAC;AAEZ,MAAM,MAAM,kBAAkB,GAAG,CAAC,OAAO,aAAa,CAAC,CAAC,MAAM,OAAO,aAAa,CAAC,CAAC;AAMpF,MAAM,MAAM,WAAW,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;AAEjD,MAAM,WAAW,sBAAsB;IACtC,WAAW,CAAC,EAAE,WAAW,CAAC;IAC1B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,eAAe,CAAC,EAAE;QACjB,IAAI,CAAC,EAAE,kBAAkB,CAAC;QAC1B,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;QACxB,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;QACzB,aAAa,CAAC,EAAE,OAAO,CAAC;QACxB,cAAc,CAAC,EAAE,OAAO,CAAC;QACzB,UAAU,CAAC,EAAE,OAAO,CAAC;KACrB,CAAC;IACF,OAAO,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,4BAA4B;IAC5C,SAAS,EAAE,MAAM,GAAG,WAAW,CAAC;IAChC,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,sBAAsB,CAAC,EAAE,sBAAsB,CAAC;CAChD;AAED,MAAM,WAAW,2BAA2B;IAC3C,KAAK,EAAE,uBAAuB,CAAC;IAC/B,mBAAmB,EAAE,WAAW,CAAC;CACjC;AA6UD;;;;;;;;;;GAUG;AACH,wBAAgB,qBAAqB,CACpC,OAAO,CAAC,EAAE,4BAA4B,GAAG,IAAI,GAC3C,2BAA2B,CAyB7B"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EAAE,uBAAuB,EAAE,MAAM,4BAA4B,CAAC;AAMrE,eAAO,MAAM,6BAA6B,oCAAoC,CAAC;AAC/E,eAAO,MAAM,2BAA2B,oBAAoB,CAAC;AAC7D,eAAO,MAAM,gCAAgC,kBAAkB,CAAC;AAChE,eAAO,MAAM,2BAA2B,YAAY,CAAC;AACrD,eAAO,MAAM,sCAAsC,qEAA2G,CAAC;AAE/J,eAAO,MAAM,aAAa;;;EAGf,CAAC;AAEZ,MAAM,MAAM,kBAAkB,GAAG,CAAC,OAAO,aAAa,CAAC,CAAC,MAAM,OAAO,aAAa,CAAC,CAAC;AAMpF,MAAM,MAAM,WAAW,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;AAEjD,MAAM,WAAW,sBAAsB;IACtC,WAAW,CAAC,EAAE,WAAW,CAAC;IAC1B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,eAAe,CAAC,EAAE;QACjB,IAAI,CAAC,EAAE,kBAAkB,CAAC;QAC1B,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;QACxB,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;QACzB,aAAa,CAAC,EAAE,OAAO,CAAC;QACxB,cAAc,CAAC,EAAE,OAAO,CAAC;QACzB,UAAU,CAAC,EAAE,OAAO,CAAC;KACrB,CAAC;IACF,OAAO,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,sBAAsB;IACtC,IAAI,EAAE,sBAAsB,GAAG,iBAAiB,CAAC;IACjD,MAAM,EAAE,OAAO,CAAC;CAChB;AAED,MAAM,MAAM,sBAAsB,GAAG,CAAC,KAAK,EAAE,sBAAsB,KAAK,IAAI,CAAC;AAC7E,MAAM,MAAM,sBAAsB,GAAG,CAAC,MAAM,EAAE,OAAO,KAAK,IAAI,CAAC;AAE/D,MAAM,WAAW,4BAA4B;IAC5C,SAAS,EAAE,MAAM,GAAG,WAAW,CAAC;IAChC,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,sBAAsB,CAAC,EAAE,sBAAsB,CAAC;IAChD,OAAO,CAAC,EAAE,sBAAsB,CAAC;IACjC,OAAO,CAAC,EAAE,sBAAsB,CAAC;CACjC;AAED,MAAM,WAAW,2BAA2B;IAC3C,KAAK,EAAE,uBAAuB,CAAC;IAC/B,mBAAmB,EAAE,WAAW,CAAC;CACjC;AAyVD;;;;;;;;;;GAUG;AACH,wBAAgB,qBAAqB,CACpC,OAAO,CAAC,EAAE,4BAA4B,GAAG,IAAI,GAC3C,2BAA2B,CA6B7B"}

package/dist/index.js

@@ -211,7 +211,7 @@ function createAndMountFrame(container, clientConfig, loApp) {
 // ═══════════════════════════════════════════════════════════════════════════════
 // LIGHTNING OUT – LO app creation and error handling
 // ═══════════════════════════════════════════════════════════════════════════════
-function createAndMountLoApp(container, salesforceOrigin, appId, frontdoorUrl, sitePrefix) {
+function createAndMountLoApp(container, salesforceOrigin, appId, frontdoorUrl, sitePrefix, onError, onReady) {
     const loApp = new LightningOutApplication();
     if (salesforceOrigin)
         loApp.setAttribute("org-url", salesforceOrigin);
@@ -225,19 +225,25 @@ function createAndMountLoApp(container, salesforceOrigin, appId, frontdoorUrl, s
         loApp.setAttribute("site-prefix", sitePrefix);
     loApp.style.opacity = "0";
     loApp.style.pointerEvents = "none";
-    attachLoEventHandlers(loApp);
+    attachLoEventHandlers(loApp, onError, onReady);
     container.appendChild(loApp);
     return loApp;
 }
-function attachLoEventHandlers(loApp) {
+function attachLoEventHandlers(loApp, onError, onReady) {
     loApp.addEventListener("lo.application.ready", (e) => {
-        console.log("Agentforce Conversation Client: Lightning Out ready", e.detail != null ? e.detail : "");
+        const detail = e.detail;
+        console.log("Agentforce Conversation Client: Lightning Out ready", detail != null ? detail : "");
+        onReady?.(detail);
     });
     loApp.addEventListener("lo.application.error", (e) => {
-        console.error("Agentforce Conversation Client: Lightning Out error:", e.detail);
+        const detail = e.detail;
+        console.error("Agentforce Conversation Client: Lightning Out error:", detail);
+        onError?.({ type: "lo.application.error", detail });
     });
     loApp.addEventListener("lo.iframe.error", (e) => {
-        console.error("Agentforce Conversation Client: Lightning Out iframe error:", e.detail);
+        const detail = e.detail;
+        console.error("Agentforce Conversation Client: Lightning Out iframe error:", detail);
+        onError?.({ type: "lo.iframe.error", detail });
     });
 }
 // ═══════════════════════════════════════════════════════════════════════════════
@@ -251,9 +257,9 @@ function resolveContainer(container) {
     return null;
 }
 function embedIntoContainer(containerElement, options) {
-    const { salesforceOrigin, appId, frontdoorUrl, sitePrefix, agentforceClientConfig = {}, } = options;
+    const { salesforceOrigin, appId, frontdoorUrl, sitePrefix, agentforceClientConfig = {}, onError, onReady, } = options;
     containerElement.classList.add("acc-container");
-    const loApp = createAndMountLoApp(containerElement, salesforceOrigin, appId, frontdoorUrl, sitePrefix);
+    const loApp = createAndMountLoApp(containerElement, salesforceOrigin, appId, frontdoorUrl, sitePrefix, onError, onReady);
     const chatClientComponent = createAndMountFrame(containerElement, agentforceClientConfig, loApp);
     return { loApp, chatClientComponent };
 }
@@ -272,7 +278,7 @@ function embedIntoContainer(containerElement, options) {
  * });
  */
 export function embedAgentforceClient(options) {
-    const { container, salesforceOrigin, appId, frontdoorUrl, sitePrefix, agentforceClientConfig = {}, } = options ?? {};
+    const { container, salesforceOrigin, appId, frontdoorUrl, sitePrefix, agentforceClientConfig = {}, onError, onReady, } = options ?? {};
     if (!container)
         throw new Error("Agentforce Conversation Client: container is required");
     if (!salesforceOrigin && !frontdoorUrl) {
@@ -289,5 +295,7 @@ export function embedAgentforceClient(options) {
         frontdoorUrl,
         sitePrefix,
         agentforceClientConfig,
+        onError,
+        onReady,
     });
 }

package/dist/index.spec.js

@@ -157,4 +157,65 @@ describe("Agentforce Conversation Client SDK", () => {
         expect(container.style.getPropertyValue("--acc-height")).toBe("600px");
         expect(container.style.getPropertyValue("--agentic-chat-container-height")).toBe("600px");
     });
+    it("registers lo.application.ready listener when onReady is provided", () => {
+        const onReady = vi.fn();
+        embedAgentforceClient({
+            container: "#test-container",
+            salesforceOrigin: "https://test.salesforce.com",
+            onReady,
+        });
+        expect(mockAddEventListener).toHaveBeenCalledWith("lo.application.ready", expect.any(Function));
+    });
+    it("registers lo.application.error and lo.iframe.error listeners when onError is provided", () => {
+        const onError = vi.fn();
+        embedAgentforceClient({
+            container: "#test-container",
+            salesforceOrigin: "https://test.salesforce.com",
+            onError,
+        });
+        expect(mockAddEventListener).toHaveBeenCalledWith("lo.application.error", expect.any(Function));
+        expect(mockAddEventListener).toHaveBeenCalledWith("lo.iframe.error", expect.any(Function));
+    });
+    it("invokes onReady with detail when lo.application.ready fires", () => {
+        const onReady = vi.fn();
+        embedAgentforceClient({
+            container: "#test-container",
+            salesforceOrigin: "https://test.salesforce.com",
+            onReady,
+        });
+        const readyHandler = mockAddEventListener.mock.calls.find(([name]) => name === "lo.application.ready")?.[1];
+        readyHandler?.(new CustomEvent("lo.application.ready", { detail: { foo: "bar" } }));
+        expect(onReady).toHaveBeenCalledWith({ foo: "bar" });
+    });
+    it("invokes onError with type and detail when lo.application.error fires", () => {
+        const onError = vi.fn();
+        embedAgentforceClient({
+            container: "#test-container",
+            salesforceOrigin: "https://test.salesforce.com",
+            onError,
+        });
+        const errorHandler = mockAddEventListener.mock.calls.find(([name]) => name === "lo.application.error")?.[1];
+        errorHandler?.(new CustomEvent("lo.application.error", { detail: { code: 500 } }));
+        expect(onError).toHaveBeenCalledWith({
+            type: "lo.application.error",
+            detail: { code: 500 },
+        });
+    });
+    it("invokes onError with type=lo.iframe.error when iframe error fires", () => {
+        const onError = vi.fn();
+        embedAgentforceClient({
+            container: "#test-container",
+            salesforceOrigin: "https://test.salesforce.com",
+            onError,
+        });
+        const iframeErrorHandler = mockAddEventListener.mock.calls.find(([name]) => name === "lo.iframe.error")?.[1];
+        iframeErrorHandler?.(new CustomEvent("lo.iframe.error", { detail: "boom" }));
+        expect(onError).toHaveBeenCalledWith({ type: "lo.iframe.error", detail: "boom" });
+    });
+    it("does not throw when onError/onReady are omitted (backward compatible)", () => {
+        expect(() => embedAgentforceClient({
+            container: "#test-container",
+            salesforceOrigin: "https://test.salesforce.com",
+        })).not.toThrow();
+    });
 });

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": "9.9.3",
+  "version": "9.10.0",
   "license": "SEE LICENSE IN LICENSE.txt",
   "type": "module",
   "main": "./dist/index.js",