@salesforce/agentforce-conversation-client 2.0.0 → 2.1.0

package/README.md

@@ -13,6 +13,8 @@ This library embeds the Agentforce Conversation Client for employee agents using
 - **One of `salesforceOrigin` or `frontdoorUrl` is required.**
 - Use `salesforceOrigin` when your app is hosted inside a Salesforce org and already has an authenticated session.
 - Use `frontdoorUrl` when embedding the chat client outside Salesforce (for example, a localhost or external app).
+
+- Use `sitePrefix` so LO 2.0 can correctly resolve asset URLs and route requests through the right site context. `site-prefix` is the path segment of the Experience Site URL after the host. For example, if your site URL is https://mydomain.my.site.com/sample, the site prefix is /sample
 - Lightning Out 2.0 uses an existing session to initialize; without it, the embed will fail to start.
 
 ## Installation
@@ -341,6 +343,18 @@ const { loApp } = embedAgentforceClient({
 });
 ```
 
+### With Experience Cloud `sitePrefix`
+
+```typescript
+import { embedAgentforceClient } from "@salesforce/agentforce-conversation-client";
+
+const { loApp } = embedAgentforceClient({
+  container: "#agentforce-container",
+  frontdoorUrl: "https://myorg.my.salesforce.com/secur/frontdoor.jsp?otp=...",
+  sitePrefix: "/my-site",
+});
+```
+
 ### Listening for Events
 
 ```typescript
@@ -378,6 +392,7 @@ Embeds the Agentforce Conversation Client by creating a Lightning Out 2.0 app an
 | `options.salesforceOrigin`                              | `string`                 | No       | Salesforce org origin URL (use when hosted in a Salesforce org). At least one of `salesforceOrigin` or `frontdoorUrl` is required                |
 | `options.appId`                                         | `string`                 | No       | 18-digit Lightning Out 2.0 app ID (`app-id`); find it in Lightning Out 2.0 App Manager in Setup; not required for apps created before Spring '26 |
 | `options.frontdoorUrl`                                  | `string`                 | No       | Frontdoor URL for authentication (use when embedding outside Salesforce). At least one of `salesforceOrigin` or `frontdoorUrl` is required       |
+| `options.sitePrefix`                                    | `string`                 | No       | Experience Cloud site prefix used by Lightning Out (for example, `"/my-site"`). Set as `site-prefix` on the LO app                               |
 | `options.agentforceClientConfig`                        | `AgentforceClientConfig` | No       | Configuration for the Agentforce client (see sub-properties below)                                                                               |
 | `agentforceClientConfig.agentId`                        | `string`                 | Yes\*    | The agent to load — required in practice, will not work without it                                                                               |
 | `agentforceClientConfig.agentLabel`                     | `string`                 | No       | Display name shown in the chat header. Falls back to the agent's configured name if omitted                                                      |
@@ -424,6 +439,7 @@ interface EmbedAgentforceClientOptions {
   salesforceOrigin?: string;
   appId?: string;
   frontdoorUrl?: string;
+  sitePrefix?: string;
   agentforceClientConfig?: AgentforceClientConfig;
 }
 

package/dist/index.d.ts

@@ -32,6 +32,7 @@ export interface EmbedAgentforceClientOptions {
     salesforceOrigin?: string;
     appId?: string;
     frontdoorUrl?: string;
+    sitePrefix?: string;
     agentforceClientConfig?: AgentforceClientConfig;
 }
 export interface EmbedAgentforceClientResult {

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;AAErD,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;CACF;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,sBAAsB,CAAC,EAAE,sBAAsB,CAAC;CAChD;AAED,MAAM,WAAW,2BAA2B;IAC3C,KAAK,EAAE,uBAAuB,CAAC;IAC/B,mBAAmB,EAAE,WAAW,CAAC;CACjC;AAiUD;;;;;;;;;;GAUG;AACH,wBAAgB,qBAAqB,CACpC,OAAO,CAAC,EAAE,4BAA4B,GAAG,IAAI,GAC3C,2BAA2B,CAuB7B"}
+{"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;AAErD,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;CACF;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;AAgVD;;;;;;;;;;GAUG;AACH,wBAAgB,qBAAqB,CACpC,OAAO,CAAC,EAAE,4BAA4B,GAAG,IAAI,GAC3C,2BAA2B,CAyB7B"}

package/dist/index.js

@@ -210,7 +210,7 @@ function createAndMountFrame(container, clientConfig, loApp) {
 // ═══════════════════════════════════════════════════════════════════════════════
 // LIGHTNING OUT – LO app creation and error handling
 // ═══════════════════════════════════════════════════════════════════════════════
-function createAndMountLoApp(container, salesforceOrigin, appId, frontdoorUrl) {
+function createAndMountLoApp(container, salesforceOrigin, appId, frontdoorUrl, sitePrefix) {
     const loApp = new LightningOutApplication();
     if (salesforceOrigin)
         loApp.setAttribute("org-url", salesforceOrigin);
@@ -220,6 +220,8 @@ function createAndMountLoApp(container, salesforceOrigin, appId, frontdoorUrl) {
         loApp.setAttribute("app-id", appId);
     if (frontdoorUrl)
         loApp.setAttribute("frontdoor-url", frontdoorUrl);
+    if (sitePrefix)
+        loApp.setAttribute("site-prefix", sitePrefix);
     loApp.style.opacity = "0";
     loApp.style.pointerEvents = "none";
     attachLoEventHandlers(loApp);
@@ -248,9 +250,9 @@ function resolveContainer(container) {
     return null;
 }
 function embedIntoContainer(containerElement, options) {
-    const { salesforceOrigin, appId, frontdoorUrl, agentforceClientConfig = {} } = options;
+    const { salesforceOrigin, appId, frontdoorUrl, sitePrefix, agentforceClientConfig = {}, } = options;
     containerElement.classList.add("acc-container");
-    const loApp = createAndMountLoApp(containerElement, salesforceOrigin, appId, frontdoorUrl);
+    const loApp = createAndMountLoApp(containerElement, salesforceOrigin, appId, frontdoorUrl, sitePrefix);
     const chatClientComponent = createAndMountFrame(containerElement, agentforceClientConfig, loApp);
     return { loApp, chatClientComponent };
 }
@@ -269,7 +271,7 @@ function embedIntoContainer(containerElement, options) {
  * });
  */
 export function embedAgentforceClient(options) {
-    const { container, salesforceOrigin, appId, frontdoorUrl, agentforceClientConfig = {}, } = options ?? {};
+    const { container, salesforceOrigin, appId, frontdoorUrl, sitePrefix, agentforceClientConfig = {}, } = options ?? {};
     if (!container)
         throw new Error("Agentforce Conversation Client: container is required");
     if (!salesforceOrigin && !frontdoorUrl) {
@@ -284,6 +286,7 @@ export function embedAgentforceClient(options) {
         salesforceOrigin,
         appId,
         frontdoorUrl,
+        sitePrefix,
         agentforceClientConfig,
     });
 }

package/dist/index.spec.js

@@ -102,6 +102,14 @@ describe("Agentforce Conversation Client SDK", () => {
         expect(mockSetAttribute).not.toHaveBeenCalledWith("org-url", expect.anything());
         expect(mockSetAttribute).toHaveBeenCalledWith("frontdoor-url", "https://test.salesforce.com/secur/frontdoor.jsp");
     });
+    it("sets site-prefix when provided", () => {
+        embedAgentforceClient({
+            container: "#test-container",
+            salesforceOrigin: "https://test.salesforce.com",
+            sitePrefix: "/my-site",
+        });
+        expect(mockSetAttribute).toHaveBeenCalledWith("site-prefix", "/my-site");
+    });
     it("sets Lightning Out app-id when provided", () => {
         embedAgentforceClient({
             container: "#test-container",

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