@salesforce/agentforce-conversation-client 11.67.1 → 11.68.1

package/dist/index.spec.js

@@ -5,10 +5,13 @@
  */
 // @vitest-environment jsdom
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
-import { embedAgentforceClient, AGENTFORCE_CLIENT_ELEMENT_TAG, AGENTFORCE_CLIENT_NAMESPACE, AGENTFORCE_CLIENT_COMPONENT_NAME, } from "./index";
-const { mockSetAttribute, mockAddEventListener } = vi.hoisted(() => ({
+import { embedAgentforceClient, AGENTFORCE_CLIENT_ELEMENT_TAG, AGENTFORCE_CLIENT_NAMESPACE, AGENTFORCE_CLIENT_COMPONENT_NAME, AGENTFORCE_FRONTDOOR_URL_REQUIRED_EVENT, } from "./index";
+const { mockSetAttribute, mockAddEventListener, mockSessionExpiry, mockSessionRefresh, mockFrontdoorUrlSetter, } = vi.hoisted(() => ({
     mockSetAttribute: vi.fn(),
     mockAddEventListener: vi.fn(),
+    mockSessionExpiry: vi.fn(),
+    mockSessionRefresh: vi.fn(),
+    mockFrontdoorUrlSetter: vi.fn(),
 }));
 vi.mock("@salesforce/lightning-out", () => ({
     LightningOutApplication: class {
@@ -16,22 +19,62 @@ vi.mock("@salesforce/lightning-out", () => ({
             const element = document.createElement("lightning-out-application");
             element.setAttribute = mockSetAttribute;
             element.addEventListener = mockAddEventListener;
+            Object.assign(element, {
+                sessionExpiry: mockSessionExpiry,
+                sessionRefresh: mockSessionRefresh,
+            });
+            // Real accessor rather than an expando, so tests observe the write
+            // the SDK makes rather than a value they set themselves.
+            let frontdoorUrl;
+            Object.defineProperty(element, "frontdoorUrl", {
+                configurable: true,
+                get: () => frontdoorUrl,
+                set: (value) => {
+                    frontdoorUrl = value;
+                    mockFrontdoorUrlSetter(value);
+                },
+            });
             return element;
         }
     },
 }));
+const FRONTDOOR_URL = "https://test.salesforce.com/secur/frontdoor.jsp";
+const FRESH_FRONTDOOR_URL = "https://test.salesforce.com/secur/frontdoor.jsp?otp=fresh";
 describe("Agentforce Conversation Client SDK", () => {
     let container;
+    let onFrontdoorUrlRequired;
     beforeEach(() => {
         container = document.createElement("div");
         container.id = "test-container";
         document.body.appendChild(container);
+        onFrontdoorUrlRequired = vi.fn();
     });
     afterEach(() => {
         document.body.innerHTML = "";
         mockSetAttribute.mockClear();
         mockAddEventListener.mockClear();
+        mockSessionExpiry.mockReset();
+        mockSessionRefresh.mockReset();
+        mockFrontdoorUrlSetter.mockReset();
+        vi.useRealTimers();
     });
+    /** Invokes every registered handler, so tests don't depend on listener order. */
+    function fireLoEvent(name) {
+        mockAddEventListener.mock.calls
+            .filter(([eventName]) => eventName === name)
+            .forEach(([, handler]) => handler(new Event(name)));
+    }
+    function embedWithKeepalive(overrides = {}) {
+        return embedAgentforceClient({
+            container: "#test-container",
+            frontdoorUrl: FRONTDOOR_URL,
+            sessionManagement: {
+                onFrontdoorUrlRequired,
+                checkIntervalMs: 1_000,
+                ...overrides,
+            },
+        });
+    }
     it("exports element/tag constants", () => {
         expect(AGENTFORCE_CLIENT_ELEMENT_TAG).toBe("runtime_copilot-acc-sdk-wrapper");
         expect(AGENTFORCE_CLIENT_NAMESPACE).toBe("runtime_copilot");
@@ -88,19 +131,19 @@ describe("Agentforce Conversation Client SDK", () => {
         embedAgentforceClient({
             container: "#test-container",
             salesforceOrigin: "https://test.salesforce.com",
-            frontdoorUrl: "https://test.salesforce.com/secur/frontdoor.jsp",
+            frontdoorUrl: FRONTDOOR_URL,
         });
         expect(mockSetAttribute).toHaveBeenCalledWith("org-url", "https://test.salesforce.com");
         expect(mockSetAttribute).toHaveBeenCalledWith("components", `${AGENTFORCE_CLIENT_NAMESPACE}/${AGENTFORCE_CLIENT_COMPONENT_NAME} as ${AGENTFORCE_CLIENT_ELEMENT_TAG}`);
-        expect(mockSetAttribute).toHaveBeenCalledWith("frontdoor-url", "https://test.salesforce.com/secur/frontdoor.jsp");
+        expect(mockSetAttribute).toHaveBeenCalledWith("frontdoor-url", FRONTDOOR_URL);
     });
     it("supports frontdoor URL without salesforceOrigin", () => {
         embedAgentforceClient({
             container: "#test-container",
-            frontdoorUrl: "https://test.salesforce.com/secur/frontdoor.jsp",
+            frontdoorUrl: FRONTDOOR_URL,
         });
         expect(mockSetAttribute).not.toHaveBeenCalledWith("org-url", expect.anything());
-        expect(mockSetAttribute).toHaveBeenCalledWith("frontdoor-url", "https://test.salesforce.com/secur/frontdoor.jsp");
+        expect(mockSetAttribute).toHaveBeenCalledWith("frontdoor-url", FRONTDOOR_URL);
     });
     it("sets site-prefix when provided", () => {
         embedAgentforceClient({
@@ -218,4 +261,255 @@ describe("Agentforce Conversation Client SDK", () => {
             salesforceOrigin: "https://test.salesforce.com",
         })).not.toThrow();
     });
+    // ── Session: setFrontdoorUrl ─────────────────────────────────────────────
+    it("hands a host-supplied URL to Lightning Out via setFrontdoorUrl", () => {
+        const { setFrontdoorUrl } = embedAgentforceClient({
+            container: "#test-container",
+            frontdoorUrl: FRONTDOOR_URL,
+        });
+        setFrontdoorUrl(FRESH_FRONTDOOR_URL);
+        expect(mockFrontdoorUrlSetter).toHaveBeenCalledWith(FRESH_FRONTDOOR_URL);
+    });
+    it("exposes typed LO session primitives on loApp", () => {
+        const { loApp } = embedAgentforceClient({
+            container: "#test-container",
+            frontdoorUrl: FRONTDOOR_URL,
+        });
+        expect(typeof loApp.sessionExpiry).toBe("function");
+        expect(typeof loApp.sessionRefresh).toBe("function");
+    });
+    it("ignores a frontdoor URL pushed after logout", () => {
+        const consoleWarn = vi.spyOn(console, "warn").mockImplementation(() => undefined);
+        const { setFrontdoorUrl } = embedAgentforceClient({
+            container: "#test-container",
+            frontdoorUrl: FRONTDOOR_URL,
+        });
+        fireLoEvent("lo.application.logout");
+        setFrontdoorUrl(FRESH_FRONTDOOR_URL);
+        expect(mockFrontdoorUrlSetter).not.toHaveBeenCalled();
+        consoleWarn.mockRestore();
+    });
+    it("rejects an empty frontdoor URL", () => {
+        const { setFrontdoorUrl } = embedAgentforceClient({
+            container: "#test-container",
+            frontdoorUrl: FRONTDOOR_URL,
+        });
+        expect(() => setFrontdoorUrl("")).toThrow("setFrontdoorUrl requires a non-empty URL");
+        expect(mockFrontdoorUrlSetter).not.toHaveBeenCalled();
+    });
+    it("rejects setFrontdoorUrl in org-url mode", () => {
+        const { setFrontdoorUrl } = embedAgentforceClient({
+            container: "#test-container",
+            salesforceOrigin: "https://test.salesforce.com",
+        });
+        expect(() => setFrontdoorUrl(FRESH_FRONTDOOR_URL)).toThrow("setFrontdoorUrl is not supported in org-url mode");
+    });
+    // ── Session keepalive (option B) ─────────────────────────────────────────
+    it("requires frontdoor-URL-only mode for sessionManagement overrides", () => {
+        expect(() => embedAgentforceClient({
+            container: "#test-container",
+            salesforceOrigin: "https://test.salesforce.com",
+            frontdoorUrl: FRONTDOOR_URL,
+            sessionManagement: {},
+        })).toThrow("Agentforce Conversation Client: sessionManagement requires frontdoorUrl-only mode");
+    });
+    it("enables keepalive by default in frontdoor-URL-only mode", () => {
+        expect(() => embedAgentforceClient({
+            container: "#test-container",
+            frontdoorUrl: FRONTDOOR_URL,
+        })).not.toThrow();
+    });
+    it("allows keepalive without an onFrontdoorUrlRequired callback", () => {
+        expect(() => embedAgentforceClient({
+            container: "#test-container",
+            frontdoorUrl: FRONTDOOR_URL,
+            sessionManagement: { checkIntervalMs: 1_000 },
+        })).not.toThrow();
+    });
+    it("validates keepalive thresholds before mutating the container", () => {
+        expect(() => embedWithKeepalive({ checkIntervalMs: 0 })).toThrow("sessionManagement.checkIntervalMs must be greater than 0");
+        expect(container.classList.contains("acc-container")).toBe(false);
+    });
+    it("waits for Lightning Out readiness before checking the session", async () => {
+        vi.useFakeTimers();
+        mockSessionExpiry.mockResolvedValue(1_000);
+        embedWithKeepalive();
+        await vi.advanceTimersByTimeAsync(2_000);
+        expect(mockSessionExpiry).not.toHaveBeenCalled();
+    });
+    it("leaves healthy sessions alone", async () => {
+        vi.useFakeTimers();
+        mockSessionExpiry.mockResolvedValue(601);
+        embedWithKeepalive();
+        fireLoEvent("lo.application.ready");
+        await vi.advanceTimersByTimeAsync(1_000);
+        expect(mockSessionExpiry).toHaveBeenCalledOnce();
+        expect(mockSessionRefresh).not.toHaveBeenCalled();
+        expect(onFrontdoorUrlRequired).not.toHaveBeenCalled();
+    });
+    it("calls sessionRefresh inside the keepalive window", async () => {
+        vi.useFakeTimers();
+        mockSessionExpiry.mockResolvedValue(600);
+        mockSessionRefresh.mockResolvedValue(undefined);
+        embedWithKeepalive();
+        fireLoEvent("lo.application.ready");
+        await vi.advanceTimersByTimeAsync(1_000);
+        expect(mockSessionRefresh).toHaveBeenCalledOnce();
+        expect(onFrontdoorUrlRequired).not.toHaveBeenCalled();
+    });
+    it("calls sessionRefresh by default without sessionManagement", async () => {
+        vi.useFakeTimers();
+        mockSessionExpiry.mockResolvedValue(600);
+        mockSessionRefresh.mockResolvedValue(undefined);
+        embedAgentforceClient({
+            container: "#test-container",
+            frontdoorUrl: FRONTDOOR_URL,
+        });
+        fireLoEvent("lo.application.ready");
+        await vi.advanceTimersByTimeAsync(60_000);
+        expect(mockSessionRefresh).toHaveBeenCalledOnce();
+        expect(onFrontdoorUrlRequired).not.toHaveBeenCalled();
+    });
+    it("asks the host when the session has expired", async () => {
+        vi.useFakeTimers();
+        mockSessionExpiry.mockResolvedValue(0);
+        embedWithKeepalive();
+        fireLoEvent("lo.application.ready");
+        await vi.advanceTimersByTimeAsync(1_000);
+        expect(mockSessionRefresh).not.toHaveBeenCalled();
+        expect(onFrontdoorUrlRequired).toHaveBeenCalledWith({ reason: "expired", ttlSeconds: 0 });
+    });
+    it("dispatches agentforce:frontdoorurlrequired on the container", async () => {
+        vi.useFakeTimers();
+        mockSessionExpiry.mockResolvedValue(0);
+        const listener = vi.fn();
+        container.addEventListener(AGENTFORCE_FRONTDOOR_URL_REQUIRED_EVENT, listener);
+        embedAgentforceClient({
+            container: "#test-container",
+            frontdoorUrl: FRONTDOOR_URL,
+            sessionManagement: { checkIntervalMs: 1_000 },
+        });
+        fireLoEvent("lo.application.ready");
+        await vi.advanceTimersByTimeAsync(1_000);
+        expect(listener).toHaveBeenCalledOnce();
+        const firstCall = listener.mock.calls[0];
+        expect(firstCall).toBeDefined();
+        const event = firstCall[0];
+        expect(event.type).toBe(AGENTFORCE_FRONTDOOR_URL_REQUIRED_EVENT);
+        expect(event.bubbles).toBe(true);
+        expect(event.detail).toEqual({ reason: "expired", ttlSeconds: 0 });
+    });
+    it("asks the host when sessionRefresh fails", async () => {
+        vi.useFakeTimers();
+        const refreshError = new Error("refresh failed");
+        mockSessionExpiry.mockResolvedValue(600);
+        mockSessionRefresh.mockRejectedValue(refreshError);
+        embedWithKeepalive();
+        fireLoEvent("lo.application.ready");
+        await vi.advanceTimersByTimeAsync(1_000);
+        expect(onFrontdoorUrlRequired).toHaveBeenCalledWith({
+            reason: "refresh-failed",
+            ttlSeconds: 600,
+            error: refreshError,
+        });
+    });
+    it("asks the host once per outage rather than once per check", async () => {
+        vi.useFakeTimers();
+        mockSessionExpiry.mockResolvedValue(0);
+        embedWithKeepalive();
+        fireLoEvent("lo.application.ready");
+        await vi.advanceTimersByTimeAsync(20_000);
+        expect(mockSessionExpiry.mock.calls.length).toBeGreaterThan(1);
+        expect(onFrontdoorUrlRequired).toHaveBeenCalledOnce();
+    });
+    it("asks again after a pushed URL expires in turn", async () => {
+        vi.useFakeTimers();
+        mockSessionExpiry.mockResolvedValue(0);
+        const { setFrontdoorUrl } = embedWithKeepalive();
+        fireLoEvent("lo.application.ready");
+        await vi.advanceTimersByTimeAsync(1_000);
+        expect(onFrontdoorUrlRequired).toHaveBeenCalledOnce();
+        setFrontdoorUrl(FRESH_FRONTDOOR_URL);
+        await vi.advanceTimersByTimeAsync(1_000);
+        expect(onFrontdoorUrlRequired).toHaveBeenCalledTimes(2);
+    });
+    it("stops keepalive after Lightning Out logout", async () => {
+        vi.useFakeTimers();
+        mockSessionExpiry.mockResolvedValue(1_000);
+        embedWithKeepalive();
+        fireLoEvent("lo.application.ready");
+        fireLoEvent("lo.application.logout");
+        await vi.advanceTimersByTimeAsync(2_000);
+        expect(mockSessionExpiry).not.toHaveBeenCalled();
+    });
+    it("does not poll in org-url mode", async () => {
+        vi.useFakeTimers();
+        mockSessionExpiry.mockResolvedValue(0);
+        embedAgentforceClient({
+            container: "#test-container",
+            salesforceOrigin: "https://test.salesforce.com",
+        });
+        fireLoEvent("lo.application.ready");
+        await vi.advanceTimersByTimeAsync(120_000);
+        expect(mockSessionExpiry).not.toHaveBeenCalled();
+    });
+    it("disables keepalive when LO session APIs are missing at ready", async () => {
+        vi.useFakeTimers();
+        const onError = vi.fn();
+        const { loApp } = embedAgentforceClient({
+            container: "#test-container",
+            frontdoorUrl: FRONTDOOR_URL,
+            sessionManagement: { checkIntervalMs: 1_000 },
+            onError,
+        });
+        Reflect.deleteProperty(loApp, "sessionExpiry");
+        fireLoEvent("lo.application.ready");
+        await vi.advanceTimersByTimeAsync(2_000);
+        expect(mockSessionExpiry).not.toHaveBeenCalled();
+        expect(onError).toHaveBeenCalledWith(expect.objectContaining({ type: "lo.session.error" }));
+    });
+    it("forwards async onFrontdoorUrlRequired rejections to onError", async () => {
+        vi.useFakeTimers();
+        const onError = vi.fn();
+        const mintError = new Error("mint failed");
+        onFrontdoorUrlRequired.mockImplementation(() => Promise.reject(mintError));
+        mockSessionExpiry.mockResolvedValue(0);
+        embedAgentforceClient({
+            container: "#test-container",
+            frontdoorUrl: FRONTDOOR_URL,
+            onError,
+            sessionManagement: { onFrontdoorUrlRequired, checkIntervalMs: 1_000 },
+        });
+        fireLoEvent("lo.application.ready");
+        await vi.advanceTimersByTimeAsync(1_000);
+        await Promise.resolve();
+        expect(onError).toHaveBeenCalledWith({ type: "lo.session.error", detail: mintError });
+    });
+    it("stops keepalive when the LO app is unmounted", async () => {
+        vi.useFakeTimers();
+        mockSessionExpiry.mockResolvedValue(601);
+        const { loApp } = embedWithKeepalive();
+        fireLoEvent("lo.application.ready");
+        await vi.advanceTimersByTimeAsync(1_000);
+        expect(mockSessionExpiry).toHaveBeenCalledOnce();
+        loApp.remove();
+        await vi.advanceTimersByTimeAsync(5_000);
+        expect(mockSessionExpiry).toHaveBeenCalledOnce();
+    });
+    it("keeps waiting when the host embeds into a detached container, then polls after attach", async () => {
+        vi.useFakeTimers();
+        mockSessionExpiry.mockResolvedValue(601);
+        const detached = document.createElement("div");
+        embedAgentforceClient({
+            container: detached,
+            frontdoorUrl: FRONTDOOR_URL,
+            sessionManagement: { onFrontdoorUrlRequired, checkIntervalMs: 1_000 },
+        });
+        fireLoEvent("lo.application.ready");
+        await vi.advanceTimersByTimeAsync(3_000);
+        expect(mockSessionExpiry).not.toHaveBeenCalled();
+        document.body.appendChild(detached);
+        await vi.advanceTimersByTimeAsync(1_000);
+        expect(mockSessionExpiry).toHaveBeenCalledOnce();
+    });
 });

package/dist/session-keepalive.d.ts

@@ -0,0 +1,17 @@
+import type { AgentforceErrorHandler, AgentforceLightningOutApplication, AgentforceSessionManagementConfig, AgentforceSessionRecoveryRequest } from "./types.js";
+export interface ResolvedSessionManagementConfig {
+    onFrontdoorUrlRequired?: (request: AgentforceSessionRecoveryRequest) => void | Promise<void>;
+    checkIntervalMs: number;
+    skipThresholdSeconds: number;
+    refreshThresholdSeconds: number;
+}
+export declare function resolveSessionManagementConfig(config: AgentforceSessionManagementConfig): ResolvedSessionManagementConfig;
+/** Runtime guard — LO package types do not guarantee session primitives exist. */
+export declare function isSessionCapable(loApp: HTMLElement): loApp is AgentforceLightningOutApplication;
+/**
+ * ACC polls and calls `sessionRefresh()` while the session is
+ * alive. Credential minting stays with the host, when ACC cannot extend the
+ * session it notifies once and waits for `setFrontdoorUrl`.
+ */
+export declare function createSessionKeepalive(loApp: HTMLElement, container: HTMLElement, isOrgUrlMode: boolean, resolved: ResolvedSessionManagementConfig | undefined, onError?: AgentforceErrorHandler): (frontdoorUrl: string) => void;
+//# sourceMappingURL=session-keepalive.d.ts.map

package/dist/session-keepalive.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-keepalive.d.ts","sourceRoot":"","sources":["../src/session-keepalive.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EACX,sBAAsB,EACtB,iCAAiC,EACjC,iCAAiC,EACjC,gCAAgC,EAChC,MAAM,YAAY,CAAC;AAQpB,MAAM,WAAW,+BAA+B;IAC/C,sBAAsB,CAAC,EAAE,CAAC,OAAO,EAAE,gCAAgC,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC7F,eAAe,EAAE,MAAM,CAAC;IACxB,oBAAoB,EAAE,MAAM,CAAC;IAC7B,uBAAuB,EAAE,MAAM,CAAC;CAChC;AAED,wBAAgB,8BAA8B,CAC7C,MAAM,EAAE,iCAAiC,GACvC,+BAA+B,CAqCjC;AAED,kFAAkF;AAClF,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,WAAW,GAAG,KAAK,IAAI,iCAAiC,CAO/F;AAED;;;;GAIG;AACH,wBAAgB,sBAAsB,CACrC,KAAK,EAAE,WAAW,EAClB,SAAS,EAAE,WAAW,EACtB,YAAY,EAAE,OAAO,EACrB,QAAQ,EAAE,+BAA+B,GAAG,SAAS,EACrD,OAAO,CAAC,EAAE,sBAAsB,GAC9B,CAAC,YAAY,EAAE,MAAM,KAAK,IAAI,CAkJhC"}

package/dist/session-keepalive.js

@@ -0,0 +1,183 @@
+/**
+ * Copyright (c) 2026, Salesforce, Inc.,
+ * All rights reserved.
+ * For full license text, see the LICENSE.txt file
+ */
+import { AGENTFORCE_FRONTDOOR_URL_REQUIRED_EVENT } from "./constants.js";
+const SESSION_KEEPALIVE_DEFAULTS = Object.freeze({
+    CHECK_INTERVAL_MS: 60_000,
+    SKIP_THRESHOLD_SECONDS: 600,
+    REFRESH_THRESHOLD_SECONDS: 300,
+});
+export function resolveSessionManagementConfig(config) {
+    const resolved = {
+        onFrontdoorUrlRequired: config.onFrontdoorUrlRequired,
+        checkIntervalMs: config.checkIntervalMs ?? SESSION_KEEPALIVE_DEFAULTS.CHECK_INTERVAL_MS,
+        skipThresholdSeconds: config.skipThresholdSeconds ?? SESSION_KEEPALIVE_DEFAULTS.SKIP_THRESHOLD_SECONDS,
+        refreshThresholdSeconds: config.refreshThresholdSeconds ?? SESSION_KEEPALIVE_DEFAULTS.REFRESH_THRESHOLD_SECONDS,
+    };
+    if (resolved.onFrontdoorUrlRequired !== undefined &&
+        typeof resolved.onFrontdoorUrlRequired !== "function") {
+        throw new Error("Agentforce Conversation Client: sessionManagement.onFrontdoorUrlRequired must be a function");
+    }
+    if (!Number.isFinite(resolved.checkIntervalMs) || resolved.checkIntervalMs <= 0) {
+        throw new Error("Agentforce Conversation Client: sessionManagement.checkIntervalMs must be greater than 0");
+    }
+    if (!Number.isFinite(resolved.skipThresholdSeconds) || resolved.skipThresholdSeconds <= 0) {
+        throw new Error("Agentforce Conversation Client: sessionManagement.skipThresholdSeconds must be greater than 0");
+    }
+    if (!Number.isFinite(resolved.refreshThresholdSeconds) ||
+        resolved.refreshThresholdSeconds < 0 ||
+        resolved.refreshThresholdSeconds >= resolved.skipThresholdSeconds) {
+        throw new Error("Agentforce Conversation Client: sessionManagement.refreshThresholdSeconds must be between 0 and skipThresholdSeconds");
+    }
+    return resolved;
+}
+/** Runtime guard — LO package types do not guarantee session primitives exist. */
+export function isSessionCapable(loApp) {
+    const candidate = loApp;
+    return (typeof candidate.sessionExpiry === "function" &&
+        typeof candidate.sessionRefresh === "function" &&
+        "frontdoorUrl" in loApp);
+}
+/**
+ * ACC polls and calls `sessionRefresh()` while the session is
+ * alive. Credential minting stays with the host, when ACC cannot extend the
+ * session it notifies once and waits for `setFrontdoorUrl`.
+ */
+export function createSessionKeepalive(loApp, container, isOrgUrlMode, resolved, onError) {
+    let timer;
+    let checkInFlight = false;
+    let stopped = false;
+    // Edge-triggered: ask the host once per outage, not once per check.
+    let recoveryPending = false;
+    /** Set after `lo.application.ready` confirms session primitives exist. */
+    let sessionApp;
+    const stop = () => {
+        stopped = true;
+        if (timer !== undefined) {
+            window.clearTimeout(timer);
+            timer = undefined;
+        }
+    };
+    loApp.addEventListener("lo.application.logout", stop);
+    const reportSessionError = (error, context) => {
+        console.error(`Agentforce Conversation Client: ${context}`, error);
+        onError?.({ type: "lo.session.error", detail: error });
+    };
+    const requestRecovery = (request) => {
+        if (recoveryPending || !resolved)
+            return;
+        recoveryPending = true;
+        container.dispatchEvent(new CustomEvent(AGENTFORCE_FRONTDOOR_URL_REQUIRED_EVENT, {
+            detail: request,
+            bubbles: true,
+        }));
+        if (!resolved.onFrontdoorUrlRequired)
+            return;
+        try {
+            const result = resolved.onFrontdoorUrlRequired(request);
+            void Promise.resolve(result).catch((error) => {
+                reportSessionError(error, "onFrontdoorUrlRequired rejected");
+            });
+        }
+        catch (error) {
+            reportSessionError(error, "onFrontdoorUrlRequired threw");
+        }
+    };
+    const setFrontdoorUrl = (frontdoorUrl) => {
+        if (isOrgUrlMode) {
+            throw new Error("Agentforce Conversation Client: setFrontdoorUrl is not supported in org-url mode");
+        }
+        if (typeof frontdoorUrl !== "string" || !frontdoorUrl) {
+            throw new Error("Agentforce Conversation Client: setFrontdoorUrl requires a non-empty URL");
+        }
+        if (stopped) {
+            console.warn("Agentforce Conversation Client: ignoring frontdoor URL after logout");
+            return;
+        }
+        if (!isSessionCapable(loApp)) {
+            throw new Error("Agentforce Conversation Client: Lightning Out session APIs are unavailable (frontdoorUrl)");
+        }
+        recoveryPending = false;
+        loApp.frontdoorUrl = frontdoorUrl;
+    };
+    if (resolved)
+        startKeepalive(resolved);
+    return setFrontdoorUrl;
+    function startKeepalive(config) {
+        /** True once LO + container have been in the document; disconnect after that is teardown. */
+        let wasMounted = false;
+        const isMounted = () => loApp.isConnected && container.isConnected;
+        const checkSession = async () => {
+            timer = undefined;
+            if (stopped)
+                return;
+            if (!isMounted()) {
+                if (wasMounted) {
+                    stop();
+                    return;
+                }
+                // Detached embed (modal / template): keep waiting until the host attaches.
+                schedule();
+                return;
+            }
+            wasMounted = true;
+            if (!sessionApp) {
+                stop();
+                return;
+            }
+            checkInFlight = true;
+            try {
+                let ttlSeconds;
+                try {
+                    ttlSeconds = await sessionApp.sessionExpiry();
+                }
+                catch (error) {
+                    requestRecovery({ reason: "expiry-unavailable", error });
+                    return;
+                }
+                if (ttlSeconds > config.skipThresholdSeconds) {
+                    recoveryPending = false;
+                    return;
+                }
+                if (ttlSeconds > config.refreshThresholdSeconds) {
+                    try {
+                        await sessionApp.sessionRefresh();
+                        recoveryPending = false;
+                        return;
+                    }
+                    catch (error) {
+                        requestRecovery({ reason: "refresh-failed", ttlSeconds, error });
+                        return;
+                    }
+                }
+                requestRecovery({ reason: "expired", ttlSeconds });
+            }
+            finally {
+                checkInFlight = false;
+                schedule();
+            }
+        };
+        function schedule() {
+            if (stopped || timer !== undefined || checkInFlight)
+                return;
+            if (!isMounted() && wasMounted) {
+                stop();
+                return;
+            }
+            timer = window.setTimeout(() => void checkSession(), config.checkIntervalMs);
+        }
+        loApp.addEventListener("lo.application.ready", () => {
+            if (stopped)
+                return;
+            if (!isSessionCapable(loApp)) {
+                reportSessionError(new Error("Lightning Out session APIs unavailable (sessionExpiry / sessionRefresh / frontdoorUrl)"), "session keepalive disabled");
+                stop();
+                return;
+            }
+            sessionApp = loApp;
+            schedule();
+        });
+    }
+}

package/dist/styles.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Copyright (c) 2026, Salesforce, Inc.,
+ * All rights reserved.
+ * For full license text, see the LICENSE.txt file
+ */
+export declare function injectStyles(additionalCss?: string): void;
+//# sourceMappingURL=styles.d.ts.map

package/dist/styles.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"styles.d.ts","sourceRoot":"","sources":["../src/styles.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAgGH,wBAAgB,YAAY,CAAC,aAAa,SAAK,GAAG,IAAI,CAMrD"}

package/dist/styles.js

@@ -0,0 +1,105 @@
+/**
+ * Copyright (c) 2026, Salesforce, Inc.,
+ * All rights reserved.
+ * For full license text, see the LICENSE.txt file
+ */
+const STYLE_ID = "agentforce-client-injected-styles";
+const AGENTFORCE_CLIENT_CSS = `
+:root {
+    --minimized-iframe-width: 180px !important;
+    --minimized-iframe-height: 70px !important;
+}
+
+.acc-container:has(> .acc-frame.inline) {
+    height: 100%;
+    width: 100%;
+}
+
+.sds-overrides {
+  width: auto;
+}
+
+.acc-container > .acc-frame {
+    display: block;
+    position: fixed;
+    background: transparent;
+    border: none;
+    outline: none;
+    border-radius: 20px;
+    bottom: 24px;
+    right: 24px;
+    height: 0 !important;
+    width: 0 !important;
+    max-width: calc(100vw - 4rem);
+    max-height: calc(100dvh - 4rem);
+    z-index: 999;
+}
+
+.acc-container > .acc-frame.inline,
+.acc-container > .acc-frame.inline.maximize {
+    height: 100% !important;
+    width: 100% !important;
+    position: static;
+    bottom: 0;
+    right: 0;
+    max-height: 100%;
+    max-width: 100%;
+    box-shadow: none;
+    border-radius: 0;
+}
+
+.acc-container > .acc-frame.inline:not(.maximize) {
+    width: var(--acc-width, auto) !important;
+    height: var(--acc-height, auto) !important;
+}
+
+.acc-container > .acc-frame.initial {
+    height: var(--minimized-iframe-height, 56px) !important;
+    width: var(--minimized-iframe-width, 145px) !important;
+    transition: all 0s ease;
+}
+
+.acc-container > .acc-frame.minimize {
+    height: var(--minimized-iframe-height, 56px) !important;
+    width: var(--minimized-iframe-width, 145px) !important;
+    transition: width 0.25s ease-in-out, height 0.25s ease-in-out;
+}
+
+.acc-container > .acc-frame.maximize {
+    width: 450px !important;
+    height: 700px !important;
+    background: #ffffff;
+    box-shadow: 0 10px 25px -3px rgba(0, 0, 0, 0.1), 0 4px 12px -2px rgba(0, 0, 0, 0.05),
+        0 0 2px 0 rgba(0, 0, 0, 0.05), 0 20px 45px -5px rgba(0, 0, 0, 0.08);
+    transition: all 0.3s ease;
+}
+
+.acc-container > lightning-out-application {
+    background: transparent;
+}
+
+@media (max-width: 639px) {
+    .acc-container > .acc-frame.maximize {
+        bottom: 0;
+        right: 0;
+        width: 100% !important;
+        height: 100vh !important;
+        height: 100dvh !important;
+        border-radius: 0;
+        max-width: 100%;
+        max-height: 100vh;
+        overflow-y: auto;
+        overflow-x: hidden;
+        -webkit-overflow-scrolling: touch;
+        transition: height 0.2s ease-in-out;
+    }
+}
+`;
+export function injectStyles(additionalCss = "") {
+    if (document.getElementById(STYLE_ID))
+        return;
+    const style = document.createElement("style");
+    style.id = STYLE_ID;
+    style.textContent = AGENTFORCE_CLIENT_CSS + (additionalCss ? "\n" + additionalCss : "");
+    document.head.appendChild(style);
+}