@salesforce/agentforce-conversation-client 11.67.1 → 11.68.1

package/README.md

@@ -11,6 +11,7 @@ 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).
+- In **frontdoor-URL-only** mode, ACC **automatically** keeps the Salesforce session alive via `sessionRefresh()`. For host-driven frontdoor **regeneration** when refresh can no longer help, see [Session management](#session-management).
 
 - 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.
@@ -374,6 +375,151 @@ const { loApp } = embedAgentforceClient({
 });
 ```
 
+### Session management
+
+Long-lived embeds can hit Salesforce session expiry. ACC splits ownership so users are not
+left stuck mid-conversation:
+
+| Owner               | Responsibility                                                                                                                                                |
+| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **ACC**             | Session **maintenance** — watch TTL and call Lightning Out `sessionRefresh()` while the session is still alive (**on by default** in frontdoor-URL-only mode) |
+| **Your app (host)** | Session **establishment / re-establishment** — provide the initial `frontdoorUrl`, and mint a **new** frontdoor URL when ACC asks                             |
+
+Lightning Out only exposes primitives (`sessionExpiry`, `sessionRefresh`, assign `frontdoorUrl`).
+It does not poll. ACC runs that policy automatically whenever you embed with `frontdoorUrl`
+and without `salesforceOrigin`. Pass `sessionManagement` only to tune thresholds or handle
+regeneration.
+
+#### Requirements
+
+- Use **frontdoor-URL-only mode**: pass `frontdoorUrl`, do **not** also pass `salesforceOrigin`.
+  Keepalive is unsupported in org-url mode.
+- Mint frontdoor URLs **server-side** (token exchange). Never put a client secret in the browser.
+- Handle regeneration in the host page — do not pass functions into Lightning Out component
+  props (they cannot cross the iframe `postMessage` boundary).
+
+#### What ACC does automatically (refresh)
+
+After `lo.application.ready` in frontdoor-URL-only mode, ACC:
+
+1. Polls remaining TTL on an interval (default every **60 seconds**).
+2. Does nothing while TTL is healthy (default: more than **10 minutes** left).
+3. Calls `loApp.sessionRefresh()` in the keepalive window (default: **5–10 minutes** left).
+   That reloads only the hidden auth iframe — **no host call, no new credentials**, and the
+   chat conversation stays mounted.
+
+You do **not** need to call `sessionRefresh()` yourself, and you do **not** need to pass
+`sessionManagement` to get this behavior.
+
+#### When you must regenerate the frontdoor URL
+
+`sessionRefresh()` only extends a **live** session. It cannot help when:
+
+- TTL is already at or near zero (absolute / idle timeout already hit)
+- `sessionRefresh()` itself fails (network, IdP, LO timeout)
+- TTL cannot be queried
+- The user logged out / the session was revoked
+
+In those cases ACC **stops trying to self-heal** and notifies your app **once per outage**
+(not once per poll). Your job is to mint a fresh frontdoor URL and push it back with
+`setFrontdoorUrl`. Only the auth iframe reloads; the chat iframe stays mounted, so the
+conversation is not torn down.
+
+#### How to handle regeneration
+
+**Recommended — listen on the container:**
+
+```typescript
+import {
+  embedAgentforceClient,
+  AGENTFORCE_FRONTDOOR_URL_REQUIRED_EVENT,
+} from "@salesforce/agentforce-conversation-client";
+
+const container = document.querySelector("#agentforce-container")!;
+
+const { setFrontdoorUrl } = embedAgentforceClient({
+  container,
+  frontdoorUrl: initialFrontdoorUrl, // establishment — keepalive starts automatically
+});
+
+container.addEventListener(AGENTFORCE_FRONTDOOR_URL_REQUIRED_EVENT, async (event) => {
+  const { reason, ttlSeconds } = (event as CustomEvent).detail;
+  console.warn("ACC needs a new frontdoor URL", { reason, ttlSeconds });
+
+  // Re-establishment — call YOUR backend (example only)
+  const response = await fetch("/api/salesforce/frontdoor", { method: "POST" });
+  if (!response.ok) {
+    // Retry on your schedule, or prompt the user to sign in again
+    return;
+  }
+  const { frontdoorUrl } = await response.json();
+  setFrontdoorUrl(frontdoorUrl); // applies without remounting the chat
+});
+```
+
+**Optional — same payload via callback** (instead of or in addition to the event):
+
+```typescript
+const { setFrontdoorUrl } = embedAgentforceClient({
+  container: "#agentforce-container",
+  frontdoorUrl: initialFrontdoorUrl,
+  sessionManagement: {
+    onFrontdoorUrlRequired: async ({ reason, ttlSeconds }) => {
+      console.warn("ACC needs a new frontdoor URL", { reason, ttlSeconds });
+      const response = await fetch("/api/salesforce/frontdoor", { method: "POST" });
+      if (!response.ok) return;
+      const { frontdoorUrl } = await response.json();
+      setFrontdoorUrl(frontdoorUrl);
+    },
+  },
+});
+```
+
+Until you call `setFrontdoorUrl`, keepalive will not ask again for that outage. After a
+successful push, ACC resumes watching; if that session later dies, you will be notified again.
+
+`setFrontdoorUrl` is always returned in frontdoor-URL-only mode, so you can also push a
+renewed URL proactively if your host already tracks Salesforce session lifetime.
+
+#### TTL policy (defaults)
+
+| TTL band                                                                       | What ACC does                  | Host action                  |
+| ------------------------------------------------------------------------------ | ------------------------------ | ---------------------------- |
+| Above `skipThresholdSeconds` (default **600s** / 10 min)                       | Do nothing                     | None                         |
+| Between refresh and skip thresholds (default **300–600s**)                     | Auto `sessionRefresh()`        | None                         |
+| At or below `refreshThresholdSeconds` (default **300s**), or refresh/TTL fails | Emit regeneration request once | Mint URL → `setFrontdoorUrl` |
+
+Omit the threshold fields to use the defaults above. To tune them:
+
+```typescript
+embedAgentforceClient({
+  container: "#agentforce-container",
+  frontdoorUrl: initialFrontdoorUrl,
+  sessionManagement: {
+    checkIntervalMs: 120_000, // poll every 2 minutes (default: 60_000)
+    skipThresholdSeconds: 900, // do nothing above 15 min TTL (default: 600)
+    refreshThresholdSeconds: 180, // auto-refresh between 3–15 min; ask host at ≤ 3 min (default: 300)
+  },
+});
+```
+
+`refreshThresholdSeconds` must be lower than `skipThresholdSeconds`.
+
+Polling starts after `lo.application.ready`. It stops permanently on `lo.application.logout`
+(a later `setFrontdoorUrl` is ignored so a logged-out user is not silently re-authenticated).
+
+#### Regeneration event / callback payload
+
+| Field        | Type                                                    | Notes                                        |
+| ------------ | ------------------------------------------------------- | -------------------------------------------- |
+| `reason`     | `"expired" \| "refresh-failed" \| "expiry-unavailable"` | Why maintenance could not continue           |
+| `ttlSeconds` | `number \| undefined`                                   | Absent when the TTL query itself failed      |
+| `error`      | `unknown \| undefined`                                  | Underlying Lightning Out error, when present |
+
+Event name: `agentforce:frontdoorurlrequired` (`AGENTFORCE_FRONTDOOR_URL_REQUIRED_EVENT`).
+Dispatched on the **embed container** (bubbles). Prefer this over putting handlers on LO
+proxy elements.
+
 ### Listening for Events
 
 #### Callback props (recommended)
@@ -390,17 +536,17 @@ embedAgentforceClient({
     console.log("Lightning Out is ready", detail);
   },
   onError: (error) => {
-    // error.type is "lo.application.error" or "lo.iframe.error"
+    // error.type is "lo.application.error", "lo.iframe.error", or "lo.session.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 }` |
+| 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, iframe-level, or session-callback error | `{ type: "lo.application.error" \| "lo.iframe.error" \| "lo.session.error", detail: unknown }` |
 
 Both callbacks are optional.
 
@@ -437,48 +583,54 @@ Embeds the Agentforce Conversation Client by creating a Lightning Out 2.0 app an
 
 #### Parameters
 
-| Parameter                                                   | Type                     | Required | Description                                                                                                                                      |
-| ----------------------------------------------------------- | ------------------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `options.container`                                         | `string \| HTMLElement`  | Yes      | CSS selector or HTMLElement to embed into                                                                                                        |
-| `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                                                      |
-| `agentforceClientConfig.styleTokens`                        | `Record<string, string>` | No       | Theme colors and style overrides (see Style Tokens section)                                                                                      |
-| `agentforceClientConfig.renderingConfig.mode`               | `"inline" \| "floating"` | No       | Rendering mode. Defaults to `"floating"`                                                                                                         |
-| `agentforceClientConfig.renderingConfig.width`              | `string \| number`       | No       | Width of the inline frame. Number values are treated as `px`, strings as CSS values (e.g. `"100%"`)                                              |
-| `agentforceClientConfig.renderingConfig.height`             | `string \| number`       | No       | Height of the inline frame. Number values are treated as `px`, strings as CSS values (e.g. `"100%"`)                                             |
-| `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`                                                                                         |
-| `agentforceClientConfig.renderingConfig.agentAvatarUrl`     | `string`                 | No       | Custom avatar image URL for agent messages                                                                                                       |
-| `agentforceClientConfig.renderingConfig.agentAvatarAltText` | `string`                 | No       | Alt text for the custom agent avatar image                                                                                                       |
-| `agentforceClientConfig.renderingConfig.headerIconName`     | `string`                 | No       | SLDS icon name for the header (e.g. `"utility:agent"`)                                                                                           |
-| `agentforceClientConfig.renderingConfig.headerIconSize`     | `string`                 | No       | Header icon size                                                                                                                                 |
-| `agentforceClientConfig.renderingConfig.headerImageUrl`     | `string`                 | No       | Custom header logo image URL                                                                                                                     |
-| `agentforceClientConfig.renderingConfig.headerImageAlt`     | `string`                 | No       | Alt text for the custom header logo image                                                                                                        |
-| `agentforceClientConfig.channel`                            | `string`                 | No       | Channel identifier for analytics/instrumentation                                                                                                 |
-| `agentforceClientConfig.messageInputPlaceholderText`        | `string`                 | No       | Custom placeholder text for the message input field                                                                                              |
-| `agentforceClientConfig.isHistoryIntroNeeded`               | `boolean`                | No       | Show a conversation history intro block                                                                                                          |
-| `agentforceClientConfig.isFileBased`                        | `boolean`                | No       | Indicates the selected agent is file-based; forwarded to `accSdkWrapper`/`accSdk` for file-agent-specific behavior                               |
-| `agentforceClientConfig.typewriterConfig`                   | `TypewriterConfig`       | No       | Customize typewriter animation (see TypewriterConfig type below)                                                                                 |
-| `agentforceClientConfig.floatingButtonLabel`                | `string`                 | No       | Label text for the floating action button (floating mode)                                                                                        |
-| `agentforceClientConfig.floatingButtonIcon`                 | `string`                 | No       | SLDS icon name for the FAB (e.g. `"utility:agent"`)                                                                                              |
-| `agentforceClientConfig.floatingButtonImage`                | `string`                 | No       | URL to an external image (PNG/SVG) shown in place of the FAB icon                                                                                |
-| `agentforceClientConfig.floatingButtonImageAlt`             | `string`                 | No       | Alt text for the floating button image                                                                                                           |
-| `agentforceClientConfig.iconPosition`                       | `"left" \| "right"`      | No       | Icon position in the FAB. Defaults to `"left"`                                                                                                   |
-| `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                                          |
+| Parameter                                                   | Type                                | Required | Description                                                                                                                                      |
+| ----------------------------------------------------------- | ----------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `options.container`                                         | `string \| HTMLElement`             | Yes      | CSS selector or HTMLElement to embed into                                                                                                        |
+| `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                                                      |
+| `agentforceClientConfig.styleTokens`                        | `Record<string, string>`            | No       | Theme colors and style overrides (see Style Tokens section)                                                                                      |
+| `agentforceClientConfig.renderingConfig.mode`               | `"inline" \| "floating"`            | No       | Rendering mode. Defaults to `"floating"`                                                                                                         |
+| `agentforceClientConfig.renderingConfig.width`              | `string \| number`                  | No       | Width of the inline frame. Number values are treated as `px`, strings as CSS values (e.g. `"100%"`)                                              |
+| `agentforceClientConfig.renderingConfig.height`             | `string \| number`                  | No       | Height of the inline frame. Number values are treated as `px`, strings as CSS values (e.g. `"100%"`)                                             |
+| `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`                                                                                         |
+| `agentforceClientConfig.renderingConfig.agentAvatarUrl`     | `string`                            | No       | Custom avatar image URL for agent messages                                                                                                       |
+| `agentforceClientConfig.renderingConfig.agentAvatarAltText` | `string`                            | No       | Alt text for the custom agent avatar image                                                                                                       |
+| `agentforceClientConfig.renderingConfig.headerIconName`     | `string`                            | No       | SLDS icon name for the header (e.g. `"utility:agent"`)                                                                                           |
+| `agentforceClientConfig.renderingConfig.headerIconSize`     | `string`                            | No       | Header icon size                                                                                                                                 |
+| `agentforceClientConfig.renderingConfig.headerImageUrl`     | `string`                            | No       | Custom header logo image URL                                                                                                                     |
+| `agentforceClientConfig.renderingConfig.headerImageAlt`     | `string`                            | No       | Alt text for the custom header logo image                                                                                                        |
+| `agentforceClientConfig.channel`                            | `string`                            | No       | Channel identifier for analytics/instrumentation                                                                                                 |
+| `agentforceClientConfig.messageInputPlaceholderText`        | `string`                            | No       | Custom placeholder text for the message input field                                                                                              |
+| `agentforceClientConfig.isHistoryIntroNeeded`               | `boolean`                           | No       | Show a conversation history intro block                                                                                                          |
+| `agentforceClientConfig.isFileBased`                        | `boolean`                           | No       | Indicates the selected agent is file-based; forwarded to `accSdkWrapper`/`accSdk` for file-agent-specific behavior                               |
+| `agentforceClientConfig.typewriterConfig`                   | `TypewriterConfig`                  | No       | Customize typewriter animation (see TypewriterConfig type below)                                                                                 |
+| `agentforceClientConfig.floatingButtonLabel`                | `string`                            | No       | Label text for the floating action button (floating mode)                                                                                        |
+| `agentforceClientConfig.floatingButtonIcon`                 | `string`                            | No       | SLDS icon name for the FAB (e.g. `"utility:agent"`)                                                                                              |
+| `agentforceClientConfig.floatingButtonImage`                | `string`                            | No       | URL to an external image (PNG/SVG) shown in place of the FAB icon                                                                                |
+| `agentforceClientConfig.floatingButtonImageAlt`             | `string`                            | No       | Alt text for the floating button image                                                                                                           |
+| `agentforceClientConfig.iconPosition`                       | `"left" \| "right"`                 | No       | Icon position in the FAB. Defaults to `"left"`                                                                                                   |
+| `options.sessionManagement`                                 | `AgentforceSessionManagementConfig` | No       | Optional overrides for default keepalive (frontdoor-URL-only). Tune thresholds or handle regeneration; omit to use defaults                      |
+| `sessionManagement.onFrontdoorUrlRequired`                  | `(request) => void`                 | No       | Optional; same payload as `agentforce:frontdoorurlrequired`. Prefer the container event                                                          |
+| `sessionManagement.checkIntervalMs`                         | `number`                            | No       | How often ACC polls TTL. Defaults to `60000`                                                                                                     |
+| `sessionManagement.skipThresholdSeconds`                    | `number`                            | No       | TTL above this → ACC does nothing. Defaults to `600`                                                                                             |
+| `sessionManagement.refreshThresholdSeconds`                 | `number`                            | No       | TTL above this (and ≤ skip) → ACC `sessionRefresh()`; at or below → ask host. Defaults to `300`                                                  |
+| `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 or session-callback errors. Receives `{ type, detail }`                                                        |
 
 #### Returns
 
-| Property              | Type                      | Description                       |
-| --------------------- | ------------------------- | --------------------------------- |
-| `loApp`               | `LightningOutApplication` | The Lightning Out 2.0 application |
-| `chatClientComponent` | `HTMLElement`             | The chat client component element |
+| Property              | Type                                | Description                                                                                    |
+| --------------------- | ----------------------------------- | ---------------------------------------------------------------------------------------------- |
+| `loApp`               | `AgentforceLightningOutApplication` | Lightning Out 2.0 app, including typed `sessionExpiry` / `sessionRefresh` / `frontdoorUrl`     |
+| `chatClientComponent` | `HTMLElement`                       | The chat client component element                                                              |
+| `setFrontdoorUrl`     | `(frontdoorUrl: string) => void`    | Re-establish session after ACC asks for regeneration. Chat stays mounted. Ignored after logout |
 
 ## Types
 
@@ -529,13 +681,26 @@ interface AgentforceClientConfig {
 
 // Error event passed to the onError callback
 interface AgentforceLoErrorEvent {
-  type: "lo.application.error" | "lo.iframe.error";
+  type: "lo.application.error" | "lo.iframe.error" | "lo.session.error";
   detail: unknown;
 }
 
 type AgentforceErrorHandler = (error: AgentforceLoErrorEvent) => void;
 type AgentforceReadyHandler = (detail: unknown) => void;
 
+interface AgentforceSessionRecoveryRequest {
+  reason: "expired" | "refresh-failed" | "expiry-unavailable";
+  ttlSeconds?: number;
+  error?: unknown;
+}
+
+interface AgentforceSessionManagementConfig {
+  onFrontdoorUrlRequired?: (request: AgentforceSessionRecoveryRequest) => void;
+  checkIntervalMs?: number;
+  skipThresholdSeconds?: number;
+  refreshThresholdSeconds?: number;
+}
+
 interface EmbedAgentforceClientOptions {
   container: string | HTMLElement;
   salesforceOrigin?: string;
@@ -543,13 +708,21 @@ interface EmbedAgentforceClientOptions {
   frontdoorUrl?: string;
   sitePrefix?: string;
   agentforceClientConfig?: AgentforceClientConfig;
+  sessionManagement?: AgentforceSessionManagementConfig;
   onReady?: AgentforceReadyHandler;
   onError?: AgentforceErrorHandler;
 }
 
+interface AgentforceLightningOutApplication extends HTMLElement {
+  sessionExpiry(): Promise<number>;
+  sessionRefresh(): Promise<void>;
+  frontdoorUrl: string;
+}
+
 interface EmbedAgentforceClientResult {
-  loApp: LightningOutApplication;
+  loApp: AgentforceLightningOutApplication;
   chatClientComponent: HTMLElement;
+  setFrontdoorUrl: (frontdoorUrl: string) => void;
 }
 ```
 

package/dist/constants.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Copyright (c) 2026, Salesforce, Inc.,
+ * All rights reserved.
+ * For full license text, see the LICENSE.txt file
+ */
+export declare const AGENTFORCE_CLIENT_ELEMENT_TAG = "runtime_copilot-acc-sdk-wrapper";
+export declare const AGENTFORCE_CLIENT_NAMESPACE = "runtime_copilot";
+export declare const AGENTFORCE_CLIENT_COMPONENT_NAME = "accSdkWrapper";
+export declare const AGENTFORCE_LO_APP_DATA_ATTR = "data-lo";
+export declare const AGENTFORCE_CLIENT_COMPONENT_NAME_ALIAS = "runtime_copilot/accSdkWrapper as runtime_copilot-acc-sdk-wrapper";
+/** Dispatched on the embed container when ACC cannot keepalive and needs a fresh frontdoor URL. */
+export declare const AGENTFORCE_FRONTDOOR_URL_REQUIRED_EVENT = "agentforce:frontdoorurlrequired";
+export declare const RenderingMode: Readonly<{
+    readonly INLINE: "inline";
+    readonly FLOATING: "floating";
+}>;
+export type RenderingModeValue = (typeof RenderingMode)[keyof typeof RenderingMode];
+//# sourceMappingURL=constants.d.ts.map

package/dist/constants.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../src/constants.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,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;AAC/J,mGAAmG;AACnG,eAAO,MAAM,uCAAuC,oCAAoC,CAAC;AAEzF,eAAO,MAAM,aAAa;;;EAGf,CAAC;AAEZ,MAAM,MAAM,kBAAkB,GAAG,CAAC,OAAO,aAAa,CAAC,CAAC,MAAM,OAAO,aAAa,CAAC,CAAC"}

package/dist/constants.js

@@ -0,0 +1,16 @@
+/**
+ * Copyright (c) 2026, Salesforce, Inc.,
+ * All rights reserved.
+ * For full license text, see the LICENSE.txt file
+ */
+export const AGENTFORCE_CLIENT_ELEMENT_TAG = "runtime_copilot-acc-sdk-wrapper";
+export const AGENTFORCE_CLIENT_NAMESPACE = "runtime_copilot";
+export const AGENTFORCE_CLIENT_COMPONENT_NAME = "accSdkWrapper";
+export const AGENTFORCE_LO_APP_DATA_ATTR = "data-lo";
+export const AGENTFORCE_CLIENT_COMPONENT_NAME_ALIAS = `${AGENTFORCE_CLIENT_NAMESPACE}/${AGENTFORCE_CLIENT_COMPONENT_NAME} as ${AGENTFORCE_CLIENT_ELEMENT_TAG}`;
+/** Dispatched on the embed container when ACC cannot keepalive and needs a fresh frontdoor URL. */
+export const AGENTFORCE_FRONTDOOR_URL_REQUIRED_EVENT = "agentforce:frontdoorurlrequired";
+export const RenderingMode = Object.freeze({
+    INLINE: "inline",
+    FLOATING: "floating",
+});

package/dist/embed.d.ts

@@ -0,0 +1,17 @@
+import type { EmbedAgentforceClientOptions, EmbedAgentforceClientResult } from "./types.js";
+/**
+ * Embeds the Agentforce Conversation Client into a DOM container.
+ * Embed is hidden (opacity 0) until the frame receives the "accready" event.
+ *
+ * In frontdoor-URL-only mode, ACC keepalives by default via `sessionRefresh()`
+ * and asks the host for a frontdoor URL only when recovery needs new credentials.
+ * Pass `sessionManagement` only to tune thresholds or handle regeneration.
+ *
+ * @example
+ * const { loApp, setFrontdoorUrl } = embedAgentforceClient({
+ *   container: '#agentforce-container',
+ *   frontdoorUrl: initialUrl,
+ * });
+ */
+export declare function embedAgentforceClient(options?: EmbedAgentforceClientOptions | null): EmbedAgentforceClientResult;
+//# sourceMappingURL=embed.d.ts.map

package/dist/embed.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"embed.d.ts","sourceRoot":"","sources":["../src/embed.ts"],"names":[],"mappings":"AAgBA,OAAO,KAAK,EAKX,4BAA4B,EAC5B,2BAA2B,EAC3B,MAAM,YAAY,CAAC;AA2GpB;;;;;;;;;;;;;GAaG;AACH,wBAAgB,qBAAqB,CACpC,OAAO,CAAC,EAAE,4BAA4B,GAAG,IAAI,GAC3C,2BAA2B,CAwC7B"}

package/dist/embed.js

@@ -0,0 +1,105 @@
+/**
+ * Copyright (c) 2026, Salesforce, Inc.,
+ * All rights reserved.
+ * For full license text, see the LICENSE.txt file
+ */
+import { LightningOutApplication } from "@salesforce/lightning-out";
+import { AGENTFORCE_CLIENT_COMPONENT_NAME_ALIAS, AGENTFORCE_LO_APP_DATA_ATTR, } from "./constants.js";
+import { createAndMountFrame } from "./frame.js";
+import { createSessionKeepalive, resolveSessionManagementConfig, } from "./session-keepalive.js";
+function createAndMountLoApp(container, salesforceOrigin, appId, frontdoorUrl, sitePrefix, sessionManagement, onError, onReady) {
+    const loApp = new LightningOutApplication();
+    if (salesforceOrigin)
+        loApp.setAttribute("org-url", salesforceOrigin);
+    loApp.setAttribute("components", AGENTFORCE_CLIENT_COMPONENT_NAME_ALIAS);
+    loApp.setAttribute(AGENTFORCE_LO_APP_DATA_ATTR, `acc`);
+    if (appId)
+        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, onError, onReady);
+    const setFrontdoorUrl = createSessionKeepalive(loApp, container, Boolean(salesforceOrigin), sessionManagement, onError);
+    container.appendChild(loApp);
+    // Public API types the LO element with session primitives; keepalive validates
+    // those methods at runtime after `lo.application.ready` before calling them.
+    return { loApp: loApp, setFrontdoorUrl };
+}
+function attachLoEventHandlers(loApp, onError, onReady) {
+    loApp.addEventListener("lo.application.ready", (e) => {
+        const detail = e.detail;
+        console.log("Agentforce Conversation Client: Lightning Out ready", detail != null ? detail : "");
+        onReady?.(detail);
+    });
+    loApp.addEventListener("lo.application.error", (e) => {
+        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) => {
+        const detail = e.detail;
+        console.error("Agentforce Conversation Client: Lightning Out iframe error:", detail);
+        onError?.({ type: "lo.iframe.error", detail });
+    });
+}
+function resolveContainer(container) {
+    if (container instanceof HTMLElement)
+        return container;
+    if (typeof container === "string")
+        return document.querySelector(container);
+    return null;
+}
+function embedIntoContainer(containerElement, options) {
+    const { salesforceOrigin, appId, frontdoorUrl, sitePrefix, agentforceClientConfig = {}, sessionManagement, onError, onReady, } = options;
+    containerElement.classList.add("acc-container");
+    const { loApp, setFrontdoorUrl } = createAndMountLoApp(containerElement, salesforceOrigin, appId, frontdoorUrl, sitePrefix, sessionManagement, onError, onReady);
+    const chatClientComponent = createAndMountFrame(containerElement, agentforceClientConfig, loApp);
+    return { loApp, chatClientComponent, setFrontdoorUrl };
+}
+/**
+ * Embeds the Agentforce Conversation Client into a DOM container.
+ * Embed is hidden (opacity 0) until the frame receives the "accready" event.
+ *
+ * In frontdoor-URL-only mode, ACC keepalives by default via `sessionRefresh()`
+ * and asks the host for a frontdoor URL only when recovery needs new credentials.
+ * Pass `sessionManagement` only to tune thresholds or handle regeneration.
+ *
+ * @example
+ * const { loApp, setFrontdoorUrl } = embedAgentforceClient({
+ *   container: '#agentforce-container',
+ *   frontdoorUrl: initialUrl,
+ * });
+ */
+export function embedAgentforceClient(options) {
+    const { container, salesforceOrigin, appId, frontdoorUrl, sitePrefix, agentforceClientConfig = {}, sessionManagement, onError, onReady, } = options ?? {};
+    if (!container)
+        throw new Error("Agentforce Conversation Client: container is required");
+    if (!salesforceOrigin && !frontdoorUrl) {
+        throw new Error("Agentforce Conversation Client: salesforceOrigin or frontdoorUrl is required");
+    }
+    const frontdoorOnlyMode = Boolean(frontdoorUrl) && !salesforceOrigin;
+    if (sessionManagement && !frontdoorOnlyMode) {
+        throw new Error("Agentforce Conversation Client: sessionManagement requires frontdoorUrl-only mode");
+    }
+    const resolvedSessionManagement = frontdoorOnlyMode
+        ? resolveSessionManagementConfig(sessionManagement ?? {})
+        : undefined;
+    const containerElement = resolveContainer(container);
+    if (!containerElement) {
+        throw new Error(`Agentforce Conversation Client: container not found: ${container}`);
+    }
+    return embedIntoContainer(containerElement, {
+        container,
+        salesforceOrigin,
+        appId,
+        frontdoorUrl,
+        sitePrefix,
+        agentforceClientConfig,
+        sessionManagement: resolvedSessionManagement,
+        onError,
+        onReady,
+    });
+}

package/dist/frame.d.ts

@@ -0,0 +1,7 @@
+import type { AgentforceClientConfig } from "./types.js";
+interface AccFrameElement extends HTMLElement {
+    configuration?: AgentforceClientConfig;
+}
+export declare function createAndMountFrame(container: HTMLElement, clientConfig: AgentforceClientConfig | undefined, loApp: HTMLElement): AccFrameElement;
+export {};
+//# sourceMappingURL=frame.d.ts.map

package/dist/frame.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"frame.d.ts","sourceRoot":"","sources":["../src/frame.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,YAAY,CAAC;AAkBzD,UAAU,eAAgB,SAAQ,WAAW;IAC5C,aAAa,CAAC,EAAE,sBAAsB,CAAC;CACvC;AAsFD,wBAAgB,mBAAmB,CAClC,SAAS,EAAE,WAAW,EACtB,YAAY,EAAE,sBAAsB,GAAG,SAAS,EAChD,KAAK,EAAE,WAAW,GAChB,eAAe,CAUjB"}

package/dist/frame.js

@@ -0,0 +1,92 @@
+/**
+ * Copyright (c) 2026, Salesforce, Inc.,
+ * All rights reserved.
+ * For full license text, see the LICENSE.txt file
+ */
+import { AGENTFORCE_CLIENT_ELEMENT_TAG, RenderingMode } from "./constants.js";
+import { injectStyles } from "./styles.js";
+const EVENTS = Object.freeze({
+    ACC_MAXIMIZE: "accmaximize",
+    ACC_MINIMIZE: "accminimize",
+    ACC_READY: "accready",
+});
+const FLOATING_DIMENSIONS = Object.freeze({
+    MINIMIZED_HEIGHT: "56px",
+});
+function toCssLength(value) {
+    return typeof value === "number" ? `${value}px` : value;
+}
+function normalizeRenderingMode(value) {
+    if (value === RenderingMode.INLINE || value === RenderingMode.FLOATING)
+        return value;
+    return undefined;
+}
+function getRenderingContext(clientConfig) {
+    const renderingConfig = clientConfig?.renderingConfig ?? {};
+    const mode = normalizeRenderingMode(renderingConfig.mode) ?? RenderingMode.FLOATING;
+    const isFloating = mode !== RenderingMode.INLINE;
+    return { mode, isFloating, renderingConfig };
+}
+function applyInlineSizing(container, { width, height }) {
+    if (width != null)
+        container.style.setProperty("--acc-width", toCssLength(width));
+    if (height != null) {
+        const h = toCssLength(height);
+        container.style.setProperty("--acc-height", h);
+        container.style.setProperty("--agentic-chat-container-height", h);
+    }
+}
+function createFrameElement() {
+    const el = document.createElement(AGENTFORCE_CLIENT_ELEMENT_TAG);
+    el.classList.add("acc-frame");
+    return el;
+}
+function applyFrameInitialState(el, context, container) {
+    el.style.opacity = "0";
+    el.style.pointerEvents = "none";
+    el.style.setProperty("--agentic-chat-container-height", "100vh");
+    if (context.isFloating) {
+        el.classList.add("floating");
+        el.classList.remove("maximize", "minimize");
+        el.classList.add("initial");
+    }
+    else {
+        el.classList.add("inline");
+        applyInlineSizing(container, context.renderingConfig);
+    }
+}
+function attachFrameResizeHandlers(el, container, isFloating, loApp) {
+    const onAccReady = () => {
+        el.style.opacity = "";
+        el.style.pointerEvents = "";
+        if (loApp) {
+            loApp.style.opacity = "";
+            loApp.style.pointerEvents = "";
+        }
+    };
+    el.addEventListener(EVENTS.ACC_READY, onAccReady);
+    if (!isFloating)
+        return;
+    const onMaximize = () => {
+        el.classList.remove("initial", "minimize");
+        el.classList.add("maximize");
+    };
+    const onMinimize = () => {
+        el.classList.remove("maximize");
+        el.classList.add("minimize");
+        container.style.setProperty("--agentic-chat-container-height", FLOATING_DIMENSIONS.MINIMIZED_HEIGHT);
+    };
+    el.addEventListener(EVENTS.ACC_MAXIMIZE, onMaximize);
+    el.addEventListener(EVENTS.ACC_MINIMIZE, onMinimize);
+}
+export function createAndMountFrame(container, clientConfig, loApp) {
+    injectStyles();
+    const config = { ...(clientConfig ?? {}) };
+    const context = getRenderingContext(config);
+    const el = createFrameElement();
+    el.configuration = config;
+    applyFrameInitialState(el, context, container);
+    attachFrameResizeHandlers(el, container, context.isFloating, loApp);
+    container.appendChild(el);
+    return el;
+}