@salesforce/agentforce-conversation-client 12.10.0 → 12.12.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -626,11 +626,12 @@ Embeds the Agentforce Conversation Client by creating a Lightning Out 2.0 app an
626
626
 
627
627
  #### Returns
628
628
 
629
- | Property | Type | Description |
630
- | --------------------- | ----------------------------------- | ---------------------------------------------------------------------------------------------- |
631
- | `loApp` | `AgentforceLightningOutApplication` | Lightning Out 2.0 app, including typed `sessionExpiry` / `sessionRefresh` / `frontdoorUrl` |
632
- | `chatClientComponent` | `HTMLElement` | The chat client component element |
633
- | `setFrontdoorUrl` | `(frontdoorUrl: string) => void` | Re-establish session after ACC asks for regeneration. Chat stays mounted. Ignored after logout |
629
+ | Property | Type | Description |
630
+ | ------------------------------------------- | ----------------------------------- | ---------------------------------------------------------------------------------------------- |
631
+ | `loApp` | `AgentforceLightningOutApplication` | Lightning Out 2.0 app, including typed `sessionExpiry` / `sessionRefresh` / `frontdoorUrl` |
632
+ | `chatClientComponent` | `HTMLElement` | The chat client component element |
633
+ | `setFrontdoorUrl` | `(frontdoorUrl: string) => void` | Re-establish session after ACC asks for regeneration. Chat stays mounted. Ignored after logout |
634
+ | `setContext` / `open` / `close` / `execute` | `AgentforceBridgeMethods` | Context and panel controls. See [Host bridge](#host-bridge--context--panel-controls) |
634
635
 
635
636
  ## Types
636
637
 
@@ -719,13 +720,97 @@ interface AgentforceLightningOutApplication extends HTMLElement {
719
720
  frontdoorUrl: string;
720
721
  }
721
722
 
722
- interface EmbedAgentforceClientResult {
723
+ interface EmbedAgentforceClientResult extends AgentforceBridgeMethods {
723
724
  loApp: AgentforceLightningOutApplication;
724
725
  chatClientComponent: HTMLElement;
725
726
  setFrontdoorUrl: (frontdoorUrl: string) => void;
726
727
  }
727
728
  ```
728
729
 
730
+ ## Host bridge — context & panel controls
731
+
732
+ Once embedded, the host can drive the client via methods on the handle returned by
733
+ `embedAgentforceClient(...)`.
734
+
735
+ ### `embed.setContext(variables, options?)`
736
+
737
+ Push context variables into the agent. They ride the next planner request as
738
+ `additionalContext` and persist across shell rebuilds. **Last write wins.**
739
+
740
+ - **Default:** fire-and-forget, returns `undefined`.
741
+ - **`{ awaitApplied: true }`:** returns `Promise<{ applied: number }>` resolving on the
742
+ LWC ack. One awaited call pending at a time — a later call rejects the earlier one
743
+ ("superseded"); teardown before the ack also rejects.
744
+
745
+ ```typescript
746
+ embed.setContext([{ name: "$Context.PropertyId", value: "p_123", type: "Text" }]);
747
+
748
+ const { applied } = await embed.setContext(
749
+ [{ name: "$Context.PropertyId", value: "p_123", type: "Text" }],
750
+ { awaitApplied: true },
751
+ );
752
+ ```
753
+
754
+ ### `embed.open(botId?)` / `embed.close()` / `embed.execute(utterance, botId)`
755
+
756
+ Drive the existing panel: open/maximize, close/minimize, or send an utterance (opening
757
+ if needed). They act on the current panel and session — they do **not** spin up a new
758
+ one. Each returns `Promise<AccPanelOperationResult>` resolving on the LWC ack, rejecting
759
+ on an error ack or teardown; several can be awaited concurrently.
760
+
761
+ | Method | Parameters | Description |
762
+ | --------- | -------------------- | --------------------------------------------------------- |
763
+ | `open` | `botId?` | Open / maximize. Pass `botId` to target a specific agent. |
764
+ | `close` | — | Close / minimize. |
765
+ | `execute` | `utterance`, `botId` | Send an utterance, opening if needed. `botId` required. |
766
+
767
+ ```typescript
768
+ await embed.open();
769
+ await embed.execute("Tell me about p_123", "0Xxxx0000000001CAA");
770
+ await embed.close();
771
+ ```
772
+
773
+ ### Bridge types
774
+
775
+ ```typescript
776
+ interface AgentforceBridgeHandle {
777
+ chatClientComponent: HTMLElement;
778
+ loApp: HTMLElement;
779
+ }
780
+
781
+ interface AgentforceBridgeMethods {
782
+ setContext(variables: AgentforceContextVariable[]): undefined;
783
+ setContext(
784
+ variables: AgentforceContextVariable[],
785
+ options: SetAgentforceContextOptions & { awaitApplied: true },
786
+ ): Promise<SetAgentforceContextResult>;
787
+ open(botId?: string): Promise<AccPanelOperationResult>;
788
+ close(): Promise<AccPanelOperationResult>;
789
+ execute(utterance: string, botId: string): Promise<AccPanelOperationResult>;
790
+ }
791
+
792
+ type AgentforceContextVariableType = "Text" | "Boolean" | "Number" | (string & {});
793
+
794
+ interface AgentforceContextVariable {
795
+ name: string;
796
+ value: unknown;
797
+ type: AgentforceContextVariableType;
798
+ }
799
+
800
+ interface SetAgentforceContextOptions {
801
+ awaitApplied?: boolean;
802
+ }
803
+
804
+ interface SetAgentforceContextResult {
805
+ applied: number;
806
+ }
807
+
808
+ interface AccPanelOperationResult {
809
+ status: true;
810
+ [key: string]: unknown;
811
+ }
812
+ ```
813
+
729
814
  ## Development
730
815
 
731
816
  ```bash
@@ -0,0 +1,39 @@
1
+ /**
2
+ * Copyright (c) 2026, Salesforce, Inc.,
3
+ * All rights reserved.
4
+ * For full license text, see the LICENSE.txt file
5
+ */
6
+ /**
7
+ * Host-side bridge for driving an embedded ACC over the Lightning Out boundary:
8
+ * context set + panel controls. `onAgentforceResponse` stays hand-shared (its
9
+ * `acc.agent.response` kind is ignored here, so the two coexist).
10
+ *
11
+ * Wire: host writes `chatClientComponent.bridgeRequest = { kind, requestId?, payload }`;
12
+ * LWC replies with `CustomEvent("accbridge", { detail })` where `detail` is the
13
+ * JSON-serialized `{ kind, requestId?, payload }` envelope (a string so it survives
14
+ * the Lightning Out boundary intact); the handler parses it back.
15
+ */
16
+ import type { AccPanelOperationResult, AgentforceBridgeHandle, AgentforceBridgeMethods, AgentforceContextVariable, SetAgentforceContextOptions, SetAgentforceContextResult } from "./types.js";
17
+ /**
18
+ * Push context variables into the agent (rides the next planner request as
19
+ * `additionalContext`; last write wins). Fire-and-forget by default; with
20
+ * `{ awaitApplied: true }` returns a Promise that resolves on the LWC ack and
21
+ * rejects on supersede or teardown (one awaited call pending at a time).
22
+ */
23
+ export declare function setAgentforceContext(embed: AgentforceBridgeHandle, variables: AgentforceContextVariable[]): undefined;
24
+ export declare function setAgentforceContext(embed: AgentforceBridgeHandle, variables: AgentforceContextVariable[], options: SetAgentforceContextOptions & {
25
+ awaitApplied: true;
26
+ }): Promise<SetAgentforceContextResult>;
27
+ export declare function setAgentforceContext(embed: AgentforceBridgeHandle, variables: AgentforceContextVariable[], options?: SetAgentforceContextOptions): Promise<SetAgentforceContextResult> | undefined;
28
+ /** Open / maximize the embedded panel (ACC `open(botId?)`). Resolves on the LWC ack. */
29
+ export declare function open(embed: AgentforceBridgeHandle, botId?: string): Promise<AccPanelOperationResult>;
30
+ /** Close / minimize the embedded panel (ACC `close()`). Resolves on the LWC ack. */
31
+ export declare function close(embed: AgentforceBridgeHandle): Promise<AccPanelOperationResult>;
32
+ /**
33
+ * Send an utterance to the agent, opening the panel if needed (ACC
34
+ * `execute(utterance, botId)`; `botId` required). Resolves on the LWC ack.
35
+ */
36
+ export declare function execute(embed: AgentforceBridgeHandle, utterance: string, botId: string): Promise<AccPanelOperationResult>;
37
+ /** Attach the bridge ops as methods on `handle`, delegating to the functions above. */
38
+ export declare function attachBridgeMethods<T extends AgentforceBridgeHandle>(handle: T): T & AgentforceBridgeMethods;
39
+ //# sourceMappingURL=bridge.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"bridge.d.ts","sourceRoot":"","sources":["../src/bridge.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH;;;;;;;;;GASG;AAEH,OAAO,KAAK,EACX,uBAAuB,EACvB,sBAAsB,EACtB,uBAAuB,EACvB,yBAAyB,EACzB,2BAA2B,EAC3B,0BAA0B,EAC1B,MAAM,YAAY,CAAC;AAkMpB;;;;;GAKG;AACH,wBAAgB,oBAAoB,CACnC,KAAK,EAAE,sBAAsB,EAC7B,SAAS,EAAE,yBAAyB,EAAE,GACpC,SAAS,CAAC;AACb,wBAAgB,oBAAoB,CACnC,KAAK,EAAE,sBAAsB,EAC7B,SAAS,EAAE,yBAAyB,EAAE,EACtC,OAAO,EAAE,2BAA2B,GAAG;IAAE,YAAY,EAAE,IAAI,CAAA;CAAE,GAC3D,OAAO,CAAC,0BAA0B,CAAC,CAAC;AACvC,wBAAgB,oBAAoB,CACnC,KAAK,EAAE,sBAAsB,EAC7B,SAAS,EAAE,yBAAyB,EAAE,EACtC,OAAO,CAAC,EAAE,2BAA2B,GACnC,OAAO,CAAC,0BAA0B,CAAC,GAAG,SAAS,CAAC;AA6CnD,wFAAwF;AACxF,wBAAgB,IAAI,CACnB,KAAK,EAAE,sBAAsB,EAC7B,KAAK,CAAC,EAAE,MAAM,GACZ,OAAO,CAAC,uBAAuB,CAAC,CAElC;AAED,oFAAoF;AACpF,wBAAgB,KAAK,CAAC,KAAK,EAAE,sBAAsB,GAAG,OAAO,CAAC,uBAAuB,CAAC,CAErF;AAED;;;GAGG;AACH,wBAAgB,OAAO,CACtB,KAAK,EAAE,sBAAsB,EAC7B,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,MAAM,GACX,OAAO,CAAC,uBAAuB,CAAC,CAElC;AAED,uFAAuF;AACvF,wBAAgB,mBAAmB,CAAC,CAAC,SAAS,sBAAsB,EACnE,MAAM,EAAE,CAAC,GACP,CAAC,GAAG,uBAAuB,CAQ7B"}
package/dist/bridge.js ADDED
@@ -0,0 +1,206 @@
1
+ /**
2
+ * Copyright (c) 2026, Salesforce, Inc.,
3
+ * All rights reserved.
4
+ * For full license text, see the LICENSE.txt file
5
+ */
6
+ const KIND_SET = "acc.context.set";
7
+ const KIND_CONTEXT_RESULT = "acc.context.result";
8
+ const KIND_OPEN = "acc.open";
9
+ const KIND_CLOSE = "acc.close";
10
+ const KIND_EXECUTE = "acc.execute";
11
+ const KIND_OP_RESULT = "acc.result";
12
+ const BRIDGE_EVENT = "accbridge";
13
+ /** One bridge state per host element; keyed weakly so torn-down hosts are collectable. */
14
+ const STATE = new WeakMap();
15
+ let bridgeCounter = 0;
16
+ function nextRequestId() {
17
+ bridgeCounter += 1;
18
+ return `req-${bridgeCounter}`;
19
+ }
20
+ // Per-kind envelope handlers
21
+ function handleContextResult(state, envelope) {
22
+ if (!state.pendingContext || state.pendingContext.requestId !== envelope.requestId)
23
+ return;
24
+ const err = envelope.payload?.error;
25
+ if (err) {
26
+ state.rejectPendingContext(err.message ?? "setAgentforceContext failed");
27
+ return;
28
+ }
29
+ const success = envelope.payload?.success;
30
+ if (success?.status !== true) {
31
+ state.rejectPendingContext("setAgentforceContext: result envelope missing success");
32
+ return;
33
+ }
34
+ // `applied` comes from untrusted JSON; coerce a non-number to 0 so callers get the promised number.
35
+ const applied = typeof success.applied === "number" ? success.applied : 0;
36
+ const { resolve } = state.pendingContext;
37
+ state.pendingContext = null;
38
+ resolve({ applied });
39
+ }
40
+ /** Narrow an untyped `success` payload to a valid panel-op result (`{ status: true }`). */
41
+ function isPanelOperationResult(value) {
42
+ return (typeof value === "object" && value !== null && value.status === true);
43
+ }
44
+ // Settle a panel op by requestId (its own map, so several can be in flight).
45
+ function handlePanelOperationResult(state, envelope) {
46
+ const requestId = envelope.requestId;
47
+ if (requestId === undefined)
48
+ return;
49
+ const entry = state.pendingOperations.get(requestId);
50
+ if (!entry)
51
+ return;
52
+ state.pendingOperations.delete(requestId);
53
+ const err = envelope.payload?.error;
54
+ if (err) {
55
+ entry.reject(new Error(err.message ?? "acc operation failed"));
56
+ return;
57
+ }
58
+ const success = envelope.payload?.success;
59
+ if (!isPanelOperationResult(success)) {
60
+ // Neither a clean error nor a valid `{ status: true }` ack — a malformed
61
+ // envelope. Reject rather than fabricating a success the LWC never sent.
62
+ entry.reject(new Error("acc operation: result envelope missing success"));
63
+ return;
64
+ }
65
+ entry.resolve(success);
66
+ }
67
+ // Narrows parsed JSON to an envelope object; per-field shapes are checked in the handlers.
68
+ function isInboundEnvelope(value) {
69
+ return typeof value === "object" && value !== null;
70
+ }
71
+ /** Parse the LWC's JSON-string reply detail; undefined if it isn't the string wire or is unparseable. */
72
+ function parseInboundDetail(raw) {
73
+ if (typeof raw !== "string")
74
+ return undefined;
75
+ let parsed;
76
+ try {
77
+ parsed = JSON.parse(raw);
78
+ }
79
+ catch {
80
+ return undefined;
81
+ }
82
+ return isInboundEnvelope(parsed) ? parsed : undefined;
83
+ }
84
+ function createBridgeHandler(state) {
85
+ return (event) => {
86
+ const envelope = parseInboundDetail(event.detail);
87
+ if (!envelope || typeof envelope.kind !== "string")
88
+ return;
89
+ if (envelope.kind === KIND_CONTEXT_RESULT)
90
+ handleContextResult(state, envelope);
91
+ else if (envelope.kind === KIND_OP_RESULT)
92
+ handlePanelOperationResult(state, envelope);
93
+ // Any other kind (e.g. "acc.agent.response") is owned by a separate helper.
94
+ };
95
+ }
96
+ // State (one per host element)
97
+ function getState(embed) {
98
+ const host = embed?.chatClientComponent;
99
+ if (!host) {
100
+ throw new Error("agentforceBridge: embed.chatClientComponent missing — call embedAgentforceClient(...) first");
101
+ }
102
+ const existing = STATE.get(host);
103
+ if (existing)
104
+ return existing;
105
+ const state = {
106
+ host,
107
+ loApp: embed.loApp,
108
+ pendingContext: null,
109
+ pendingOperations: new Map(),
110
+ teardownObserver: null,
111
+ rejectPendingContext: (reason) => {
112
+ if (!state.pendingContext)
113
+ return;
114
+ const { reject } = state.pendingContext;
115
+ state.pendingContext = null;
116
+ reject(new Error(reason));
117
+ },
118
+ rejectPendingOperations: (reason) => {
119
+ if (state.pendingOperations.size === 0)
120
+ return;
121
+ const entries = [...state.pendingOperations.values()];
122
+ state.pendingOperations.clear();
123
+ entries.forEach(({ reject }) => reject(new Error(reason)));
124
+ },
125
+ };
126
+ host.addEventListener(BRIDGE_EVENT, createBridgeHandler(state));
127
+ STATE.set(host, state);
128
+ return state;
129
+ }
130
+ function ensureTeardownObserver(state) {
131
+ if (state.teardownObserver)
132
+ return;
133
+ // Watch the whole document subtree, not just loApp.parentNode's childList:
134
+ // an inline unmount removes the *container* (loApp's parent), so loApp is
135
+ // never removed from its own parent and a childList-only observer on that
136
+ // parent never fires. `isConnected` catches removal anywhere up the tree.
137
+ const root = state.loApp?.ownerDocument?.documentElement;
138
+ if (!root)
139
+ return;
140
+ const observer = new MutationObserver(() => {
141
+ if (!state.loApp.isConnected) {
142
+ state.rejectPendingContext("setAgentforceContext: embed torn down before variables applied");
143
+ state.rejectPendingOperations("acc operation: embed torn down before it completed");
144
+ observer.disconnect();
145
+ state.teardownObserver = null;
146
+ }
147
+ });
148
+ observer.observe(root, { childList: true, subtree: true });
149
+ state.teardownObserver = observer;
150
+ }
151
+ export function setAgentforceContext(embed, variables, options) {
152
+ const state = getState(embed);
153
+ const { host } = state;
154
+ if (!options?.awaitApplied) {
155
+ state.rejectPendingContext("setAgentforceContext: superseded by a fire-and-forget call");
156
+ host.bridgeRequest = { kind: KIND_SET, payload: { variables } };
157
+ return undefined;
158
+ }
159
+ state.rejectPendingContext("setAgentforceContext: superseded by a later awaited call");
160
+ ensureTeardownObserver(state);
161
+ const requestId = nextRequestId();
162
+ const promise = new Promise((resolve, reject) => {
163
+ state.pendingContext = { requestId, resolve, reject };
164
+ });
165
+ host.bridgeRequest = {
166
+ kind: KIND_SET,
167
+ requestId,
168
+ payload: { variables },
169
+ };
170
+ return promise;
171
+ }
172
+ // Send a panel op over the bridge; returns a Promise that settles on `acc.result`.
173
+ function sendPanelOperation(embed, kind, payload) {
174
+ const state = getState(embed);
175
+ ensureTeardownObserver(state);
176
+ const requestId = nextRequestId();
177
+ const promise = new Promise((resolve, reject) => {
178
+ state.pendingOperations.set(requestId, { resolve, reject });
179
+ });
180
+ state.host.bridgeRequest = { kind, requestId, payload };
181
+ return promise;
182
+ }
183
+ /** Open / maximize the embedded panel (ACC `open(botId?)`). Resolves on the LWC ack. */
184
+ export function open(embed, botId) {
185
+ return sendPanelOperation(embed, KIND_OPEN, botId ? { botId } : {});
186
+ }
187
+ /** Close / minimize the embedded panel (ACC `close()`). Resolves on the LWC ack. */
188
+ export function close(embed) {
189
+ return sendPanelOperation(embed, KIND_CLOSE, {});
190
+ }
191
+ /**
192
+ * Send an utterance to the agent, opening the panel if needed (ACC
193
+ * `execute(utterance, botId)`; `botId` required). Resolves on the LWC ack.
194
+ */
195
+ export function execute(embed, utterance, botId) {
196
+ return sendPanelOperation(embed, KIND_EXECUTE, { utterance, botId });
197
+ }
198
+ /** Attach the bridge ops as methods on `handle`, delegating to the functions above. */
199
+ export function attachBridgeMethods(handle) {
200
+ const bound = handle;
201
+ bound.setContext = ((variables, options) => setAgentforceContext(handle, variables, options));
202
+ bound.open = (botId) => open(handle, botId);
203
+ bound.close = () => close(handle);
204
+ bound.execute = (utterance, botId) => execute(handle, utterance, botId);
205
+ return bound;
206
+ }
@@ -0,0 +1,2 @@
1
+ export {};
2
+ //# sourceMappingURL=bridge.spec.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"bridge.spec.d.ts","sourceRoot":"","sources":["../src/bridge.spec.ts"],"names":[],"mappings":""}
@@ -0,0 +1,277 @@
1
+ /**
2
+ * Copyright (c) 2026, Salesforce, Inc.,
3
+ * All rights reserved.
4
+ * For full license text, see the LICENSE.txt file
5
+ */
6
+ // @vitest-environment jsdom
7
+ import { afterEach, beforeEach, describe, expect, it } from "vitest";
8
+ import { close, execute, open, setAgentforceContext } from "./bridge";
9
+ let container;
10
+ /**
11
+ * A fresh embed handle: `chatClientComponent` is the bridge target (host), and
12
+ * `loApp` is a mounted sibling whose removal the teardown observer watches. A new
13
+ * host per test means a new (WeakMap-keyed) bridge state, so tests don't leak.
14
+ */
15
+ function makeEmbed() {
16
+ const host = document.createElement("div");
17
+ const loApp = document.createElement("div");
18
+ container.appendChild(loApp);
19
+ container.appendChild(host);
20
+ return { embed: { chatClientComponent: host, loApp }, host, loApp };
21
+ }
22
+ /**
23
+ * Dispatch an LWC → host reply on the `accbridge` channel. The real LWC
24
+ * serializes the envelope to a JSON string (so it survives the Lightning Out
25
+ * boundary), so the helper does too.
26
+ */
27
+ function reply(host, detail) {
28
+ host.dispatchEvent(new CustomEvent("accbridge", { detail: JSON.stringify(detail) }));
29
+ }
30
+ /** Let the jsdom MutationObserver callback (teardown) run. */
31
+ function flush() {
32
+ return new Promise((resolve) => setTimeout(resolve, 0));
33
+ }
34
+ beforeEach(() => {
35
+ container = document.createElement("div");
36
+ document.body.appendChild(container);
37
+ });
38
+ afterEach(() => {
39
+ document.body.innerHTML = "";
40
+ });
41
+ describe("setAgentforceContext", () => {
42
+ const vars = [
43
+ { name: "$Context.PropertyId", value: "p_123", type: "Text" },
44
+ { name: "lensApiName", value: "MyLens", type: "Text" },
45
+ ];
46
+ it("fire-and-forget: writes the context.set envelope with no requestId and returns undefined", () => {
47
+ const { embed, host } = makeEmbed();
48
+ const result = setAgentforceContext(embed, vars);
49
+ expect(result).toBeUndefined();
50
+ expect(host.bridgeRequest).toEqual({ kind: "acc.context.set", payload: { variables: vars } });
51
+ expect(host.bridgeRequest?.requestId).toBeUndefined();
52
+ });
53
+ it("throws when the embed has no chatClientComponent", () => {
54
+ expect(() => setAgentforceContext({}, vars)).toThrow(/chatClientComponent missing/);
55
+ });
56
+ it("awaitApplied: writes a requestId and resolves with the applied count on success", async () => {
57
+ const { embed, host } = makeEmbed();
58
+ const promise = setAgentforceContext(embed, vars, { awaitApplied: true });
59
+ const { requestId, kind } = host.bridgeRequest;
60
+ expect(kind).toBe("acc.context.set");
61
+ expect(requestId).toBeTruthy();
62
+ reply(host, {
63
+ kind: "acc.context.result",
64
+ requestId,
65
+ payload: { success: { status: true, applied: 2 } },
66
+ });
67
+ await expect(promise).resolves.toEqual({ applied: 2 });
68
+ });
69
+ it("awaitApplied: coerces a non-number applied to 0 (wire shape isn't leaked to callers)", async () => {
70
+ const { embed, host } = makeEmbed();
71
+ const promise = setAgentforceContext(embed, vars, { awaitApplied: true });
72
+ reply(host, {
73
+ kind: "acc.context.result",
74
+ requestId: host.bridgeRequest.requestId,
75
+ // A malformed reply where `applied` isn't the promised number.
76
+ payload: { success: { status: true, applied: "bad" } },
77
+ });
78
+ await expect(promise).resolves.toEqual({ applied: 0 });
79
+ });
80
+ it("awaitApplied: rejects on an error result envelope", async () => {
81
+ const { embed, host } = makeEmbed();
82
+ const promise = setAgentforceContext(embed, vars, { awaitApplied: true });
83
+ reply(host, {
84
+ kind: "acc.context.result",
85
+ requestId: host.bridgeRequest.requestId,
86
+ payload: { error: { message: "broker rejected" } },
87
+ });
88
+ await expect(promise).rejects.toThrow("broker rejected");
89
+ });
90
+ it("awaitApplied: rejects a result envelope that carries neither an error nor a valid success", async () => {
91
+ const { embed, host } = makeEmbed();
92
+ const promise = setAgentforceContext(embed, vars, { awaitApplied: true });
93
+ reply(host, {
94
+ kind: "acc.context.result",
95
+ requestId: host.bridgeRequest.requestId,
96
+ payload: { success: { status: false } },
97
+ });
98
+ await expect(promise).rejects.toThrow(/missing success/);
99
+ });
100
+ it("awaitApplied: ignores a result whose requestId does not match the pending one", async () => {
101
+ const { embed, host } = makeEmbed();
102
+ const promise = setAgentforceContext(embed, vars, { awaitApplied: true });
103
+ let settled = false;
104
+ void promise.then(() => (settled = true), () => (settled = true));
105
+ reply(host, {
106
+ kind: "acc.context.result",
107
+ requestId: "stale-id",
108
+ payload: { success: { status: true, applied: 9 } },
109
+ });
110
+ await flush();
111
+ expect(settled).toBe(false);
112
+ // The real reply still settles it.
113
+ reply(host, {
114
+ kind: "acc.context.result",
115
+ requestId: host.bridgeRequest.requestId,
116
+ payload: { success: { status: true, applied: 2 } },
117
+ });
118
+ await expect(promise).resolves.toEqual({ applied: 2 });
119
+ });
120
+ it("a later awaited call supersedes and rejects the earlier pending one", async () => {
121
+ const { embed, host } = makeEmbed();
122
+ const first = setAgentforceContext(embed, vars, { awaitApplied: true });
123
+ const second = setAgentforceContext(embed, vars, { awaitApplied: true });
124
+ await expect(first).rejects.toThrow(/superseded by a later awaited call/);
125
+ reply(host, {
126
+ kind: "acc.context.result",
127
+ requestId: host.bridgeRequest.requestId,
128
+ payload: { success: { status: true, applied: 2 } },
129
+ });
130
+ await expect(second).resolves.toEqual({ applied: 2 });
131
+ });
132
+ it("a fire-and-forget call supersedes and rejects a pending awaited one", async () => {
133
+ const { embed } = makeEmbed();
134
+ const pending = setAgentforceContext(embed, vars, { awaitApplied: true });
135
+ setAgentforceContext(embed, vars);
136
+ await expect(pending).rejects.toThrow(/superseded by a fire-and-forget call/);
137
+ });
138
+ it("rejects the pending promise when the embed is torn down", async () => {
139
+ const { embed, loApp } = makeEmbed();
140
+ const promise = setAgentforceContext(embed, vars, { awaitApplied: true });
141
+ // Attach the rejection matcher before teardown so the async rejection is
142
+ // always handled (avoids an unhandled-rejection warning in the gap).
143
+ const assertion = expect(promise).rejects.toThrow(/torn down/);
144
+ loApp.remove();
145
+ await assertion;
146
+ });
147
+ });
148
+ describe("panel controls", () => {
149
+ const AGENT_ID = "0Xxxx0000000001CAA";
150
+ it("open: writes acc.open with the botId and resolves on the matching ack", async () => {
151
+ const { embed, host } = makeEmbed();
152
+ const promise = open(embed, AGENT_ID);
153
+ const { kind, requestId, payload } = host.bridgeRequest;
154
+ expect(kind).toBe("acc.open");
155
+ expect(payload).toEqual({ botId: AGENT_ID });
156
+ reply(host, { kind: "acc.result", requestId, payload: { success: { status: true } } });
157
+ await expect(promise).resolves.toEqual({ status: true });
158
+ });
159
+ it("open: omits botId when none is passed", () => {
160
+ const { embed, host } = makeEmbed();
161
+ // This op never gets an ack; swallow the teardown rejection from afterEach.
162
+ open(embed).catch(() => undefined);
163
+ expect(host.bridgeRequest).toMatchObject({ kind: "acc.open", payload: {} });
164
+ });
165
+ it("close: writes acc.close and resolves on ack", async () => {
166
+ const { embed, host } = makeEmbed();
167
+ const promise = close(embed);
168
+ const { kind, requestId, payload } = host.bridgeRequest;
169
+ expect(kind).toBe("acc.close");
170
+ expect(payload).toEqual({});
171
+ reply(host, { kind: "acc.result", requestId, payload: { success: { status: true } } });
172
+ await expect(promise).resolves.toEqual({ status: true });
173
+ });
174
+ it("execute: writes acc.execute with utterance + botId", async () => {
175
+ const { embed, host } = makeEmbed();
176
+ const promise = execute(embed, "Tell me about p_123", AGENT_ID);
177
+ const { kind, requestId, payload } = host.bridgeRequest;
178
+ expect(kind).toBe("acc.execute");
179
+ expect(payload).toEqual({ utterance: "Tell me about p_123", botId: AGENT_ID });
180
+ reply(host, { kind: "acc.result", requestId, payload: { success: { status: true } } });
181
+ await expect(promise).resolves.toEqual({ status: true });
182
+ });
183
+ it("rejects on an error ack", async () => {
184
+ const { embed, host } = makeEmbed();
185
+ const promise = open(embed, AGENT_ID);
186
+ reply(host, {
187
+ kind: "acc.result",
188
+ requestId: host.bridgeRequest.requestId,
189
+ payload: { error: { message: "no panel" } },
190
+ });
191
+ await expect(promise).rejects.toThrow("no panel");
192
+ });
193
+ it("correlates concurrent operations by requestId", async () => {
194
+ const { embed, host } = makeEmbed();
195
+ const openPromise = open(embed, AGENT_ID);
196
+ const openReqId = host.bridgeRequest.requestId;
197
+ const execPromise = execute(embed, "hi", AGENT_ID);
198
+ const execReqId = host.bridgeRequest.requestId;
199
+ expect(openReqId).not.toBe(execReqId);
200
+ // Ack the second op first — each settles independently.
201
+ reply(host, {
202
+ kind: "acc.result",
203
+ requestId: execReqId,
204
+ payload: { success: { status: true } },
205
+ });
206
+ reply(host, {
207
+ kind: "acc.result",
208
+ requestId: openReqId,
209
+ payload: { success: { status: true, mode: "maximized" } },
210
+ });
211
+ await expect(execPromise).resolves.toEqual({ status: true });
212
+ await expect(openPromise).resolves.toEqual({ status: true, mode: "maximized" });
213
+ });
214
+ it("rejects pending operations when the embed is torn down", async () => {
215
+ const { embed, loApp } = makeEmbed();
216
+ const promise = open(embed, AGENT_ID);
217
+ const assertion = expect(promise).rejects.toThrow(/torn down/);
218
+ loApp.remove();
219
+ await assertion;
220
+ });
221
+ it("rejects when the inline container (loApp's parent) is removed, not loApp itself", async () => {
222
+ // Inline unmount removes the container that holds the embed, so loApp is
223
+ // never detached from its own parent — a childList observer on that parent
224
+ // would miss it. The document-subtree observer catches it via isConnected.
225
+ const { embed } = makeEmbed();
226
+ const promise = open(embed, AGENT_ID);
227
+ const assertion = expect(promise).rejects.toThrow(/torn down/);
228
+ container.remove();
229
+ await assertion;
230
+ });
231
+ it("rejects a malformed ack that is neither an error nor a valid success", async () => {
232
+ const { embed, host } = makeEmbed();
233
+ const promise = open(embed, AGENT_ID);
234
+ reply(host, {
235
+ kind: "acc.result",
236
+ requestId: host.bridgeRequest.requestId,
237
+ // No error, and success is not a `{ status: true }` object.
238
+ payload: { success: { status: false } },
239
+ });
240
+ await expect(promise).rejects.toThrow(/missing success/);
241
+ });
242
+ });
243
+ describe("coexistence with the hand-shared response helper", () => {
244
+ it("ignores acc.agent.response envelopes (owned by a separate helper)", async () => {
245
+ const { embed, host } = makeEmbed();
246
+ // A separate hand-shared listener would own this kind; the packaged bridge
247
+ // must not throw or mis-settle a pending context on it.
248
+ const promise = setAgentforceContext(embed, [{ name: "a", value: "b", type: "Text" }], {
249
+ awaitApplied: true,
250
+ });
251
+ let settled = false;
252
+ void promise.then(() => (settled = true), () => (settled = true));
253
+ reply(host, {
254
+ kind: "acc.agent.response",
255
+ payload: { content: { message: "hi", actions: [] } },
256
+ });
257
+ await flush();
258
+ expect(settled).toBe(false);
259
+ reply(host, {
260
+ kind: "acc.context.result",
261
+ requestId: host.bridgeRequest.requestId,
262
+ payload: { success: { status: true, applied: 1 } },
263
+ });
264
+ await expect(promise).resolves.toEqual({ applied: 1 });
265
+ });
266
+ it("ignores malformed envelopes", () => {
267
+ const { embed, host } = makeEmbed();
268
+ setAgentforceContext(embed, [{ name: "a", value: "b", type: "Text" }]);
269
+ // A non-string detail is not the LWC's JSON wire — ignored.
270
+ expect(() => host.dispatchEvent(new CustomEvent("accbridge", { detail: { kind: "acc.result" } }))).not.toThrow();
271
+ // An unparseable JSON string is ignored.
272
+ expect(() => host.dispatchEvent(new CustomEvent("accbridge", { detail: "{not-json" }))).not.toThrow();
273
+ // Well-formed JSON with no kind is ignored.
274
+ expect(() => reply(host, null)).not.toThrow();
275
+ expect(() => reply(host, { payload: {} })).not.toThrow();
276
+ });
277
+ });
@@ -1 +1 @@
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"}
1
+ {"version":3,"file":"embed.d.ts","sourceRoot":"","sources":["../src/embed.ts"],"names":[],"mappings":"AAiBA,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 CHANGED
@@ -4,6 +4,7 @@
4
4
  * For full license text, see the LICENSE.txt file
5
5
  */
6
6
  import { LightningOutApplication } from "@salesforce/lightning-out";
7
+ import { attachBridgeMethods } from "./bridge.js";
7
8
  import { AGENTFORCE_CLIENT_COMPONENT_NAME_ALIAS, AGENTFORCE_LO_APP_DATA_ATTR, } from "./constants.js";
8
9
  import { createAndMountFrame } from "./frame.js";
9
10
  import { createSessionKeepalive, resolveSessionManagementConfig, } from "./session-keepalive.js";
@@ -57,7 +58,7 @@ function embedIntoContainer(containerElement, options) {
57
58
  containerElement.classList.add("acc-container");
58
59
  const { loApp, setFrontdoorUrl } = createAndMountLoApp(containerElement, salesforceOrigin, appId, frontdoorUrl, sitePrefix, sessionManagement, onError, onReady);
59
60
  const chatClientComponent = createAndMountFrame(containerElement, agentforceClientConfig, loApp);
60
- return { loApp, chatClientComponent, setFrontdoorUrl };
61
+ return attachBridgeMethods({ loApp, chatClientComponent, setFrontdoorUrl });
61
62
  }
62
63
  /**
63
64
  * Embeds the Agentforce Conversation Client into a DOM container.
package/dist/index.d.ts CHANGED
@@ -5,6 +5,6 @@
5
5
  */
6
6
  export { AGENTFORCE_CLIENT_ELEMENT_TAG, AGENTFORCE_CLIENT_NAMESPACE, AGENTFORCE_CLIENT_COMPONENT_NAME, AGENTFORCE_LO_APP_DATA_ATTR, AGENTFORCE_CLIENT_COMPONENT_NAME_ALIAS, AGENTFORCE_FRONTDOOR_URL_REQUIRED_EVENT, RenderingMode, } from "./constants.js";
7
7
  export type { RenderingModeValue } from "./constants.js";
8
- export type { StyleTokens, TypewriterConfig, AgentforceClientConfig, AgentforceLoErrorEvent, AgentforceErrorHandler, AgentforceReadyHandler, AgentforceSessionRecoveryRequest, AgentforceSessionManagementConfig, EmbedAgentforceClientOptions, AgentforceLightningOutApplication, EmbedAgentforceClientResult, } from "./types.js";
8
+ export type { StyleTokens, TypewriterConfig, AgentforceClientConfig, AgentforceLoErrorEvent, AgentforceErrorHandler, AgentforceReadyHandler, AgentforceSessionRecoveryRequest, AgentforceSessionManagementConfig, EmbedAgentforceClientOptions, AgentforceLightningOutApplication, EmbedAgentforceClientResult, AgentforceBridgeHandle, AgentforceBridgeMethods, AgentforceContextVariable, AgentforceContextVariableType, SetAgentforceContextOptions, SetAgentforceContextResult, AccPanelOperationResult, } from "./types.js";
9
9
  export { embedAgentforceClient } from "./embed.js";
10
10
  //# sourceMappingURL=index.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EACN,6BAA6B,EAC7B,2BAA2B,EAC3B,gCAAgC,EAChC,2BAA2B,EAC3B,sCAAsC,EACtC,uCAAuC,EACvC,aAAa,GACb,MAAM,gBAAgB,CAAC;AACxB,YAAY,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AAEzD,YAAY,EACX,WAAW,EACX,gBAAgB,EAChB,sBAAsB,EACtB,sBAAsB,EACtB,sBAAsB,EACtB,sBAAsB,EACtB,gCAAgC,EAChC,iCAAiC,EACjC,4BAA4B,EAC5B,iCAAiC,EACjC,2BAA2B,GAC3B,MAAM,YAAY,CAAC;AAEpB,OAAO,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAC"}
1
+ {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EACN,6BAA6B,EAC7B,2BAA2B,EAC3B,gCAAgC,EAChC,2BAA2B,EAC3B,sCAAsC,EACtC,uCAAuC,EACvC,aAAa,GACb,MAAM,gBAAgB,CAAC;AACxB,YAAY,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AAEzD,YAAY,EACX,WAAW,EACX,gBAAgB,EAChB,sBAAsB,EACtB,sBAAsB,EACtB,sBAAsB,EACtB,sBAAsB,EACtB,gCAAgC,EAChC,iCAAiC,EACjC,4BAA4B,EAC5B,iCAAiC,EACjC,2BAA2B,EAC3B,sBAAsB,EACtB,uBAAuB,EACvB,yBAAyB,EACzB,6BAA6B,EAC7B,2BAA2B,EAC3B,0BAA0B,EAC1B,uBAAuB,GACvB,MAAM,YAAY,CAAC;AAEpB,OAAO,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAC"}
@@ -512,4 +512,70 @@ describe("Agentforce Conversation Client SDK", () => {
512
512
  await vi.advanceTimersByTimeAsync(1_000);
513
513
  expect(mockSessionExpiry).toHaveBeenCalledOnce();
514
514
  });
515
+ describe("handle bridge methods", () => {
516
+ function embed() {
517
+ return embedAgentforceClient({
518
+ container: "#test-container",
519
+ salesforceOrigin: "https://test.salesforce.com",
520
+ });
521
+ }
522
+ /** LWC → host reply; `detail` is a JSON string on the wire. */
523
+ function reply(host, detail) {
524
+ host.dispatchEvent(new CustomEvent("accbridge", { detail: JSON.stringify(detail) }));
525
+ }
526
+ it("exposes setContext/open/close/execute on the handle", () => {
527
+ const result = embed();
528
+ expect(typeof result.setContext).toBe("function");
529
+ expect(typeof result.open).toBe("function");
530
+ expect(typeof result.close).toBe("function");
531
+ expect(typeof result.execute).toBe("function");
532
+ });
533
+ it("setContext delegates: writes the context-set request and resolves on ack", async () => {
534
+ const result = embed();
535
+ const host = result.chatClientComponent;
536
+ const vars = [{ name: "accountId", value: "001", type: "Text" }];
537
+ const promise = result.setContext(vars, { awaitApplied: true });
538
+ expect(host.bridgeRequest).toMatchObject({
539
+ kind: "acc.context.set",
540
+ payload: { variables: vars },
541
+ });
542
+ reply(host, {
543
+ kind: "acc.context.result",
544
+ requestId: host.bridgeRequest.requestId,
545
+ payload: { success: { status: true, applied: 1 } },
546
+ });
547
+ await expect(promise).resolves.toEqual({ applied: 1 });
548
+ });
549
+ it("open/close/execute delegate: write the op request and resolve on ack", async () => {
550
+ const result = embed();
551
+ const host = result.chatClientComponent;
552
+ const openPromise = result.open("bot-1");
553
+ expect(host.bridgeRequest).toMatchObject({ kind: "acc.open", payload: { botId: "bot-1" } });
554
+ reply(host, {
555
+ kind: "acc.result",
556
+ requestId: host.bridgeRequest.requestId,
557
+ payload: { success: { status: true } },
558
+ });
559
+ await expect(openPromise).resolves.toEqual({ status: true });
560
+ const execPromise = result.execute("hi", "bot-1");
561
+ expect(host.bridgeRequest).toMatchObject({
562
+ kind: "acc.execute",
563
+ payload: { utterance: "hi", botId: "bot-1" },
564
+ });
565
+ reply(host, {
566
+ kind: "acc.result",
567
+ requestId: host.bridgeRequest.requestId,
568
+ payload: { success: { status: true } },
569
+ });
570
+ await expect(execPromise).resolves.toEqual({ status: true });
571
+ const closePromise = result.close();
572
+ expect(host.bridgeRequest).toMatchObject({ kind: "acc.close", payload: {} });
573
+ reply(host, {
574
+ kind: "acc.result",
575
+ requestId: host.bridgeRequest.requestId,
576
+ payload: { success: { status: true } },
577
+ });
578
+ await expect(closePromise).resolves.toEqual({ status: true });
579
+ });
580
+ });
515
581
  });
package/dist/types.d.ts CHANGED
@@ -105,7 +105,22 @@ export interface AgentforceLightningOutApplication extends HTMLElement {
105
105
  sessionRefresh(): Promise<void>;
106
106
  frontdoorUrl: string;
107
107
  }
108
- export interface EmbedAgentforceClientResult {
108
+ /** Bridge ops as methods on the embed handle; mirrors the standalone functions. */
109
+ export interface AgentforceBridgeMethods {
110
+ /** Method form of {@link setAgentforceContext}. */
111
+ setContext(variables: AgentforceContextVariable[]): undefined;
112
+ setContext(variables: AgentforceContextVariable[], options: SetAgentforceContextOptions & {
113
+ awaitApplied: true;
114
+ }): Promise<SetAgentforceContextResult>;
115
+ setContext(variables: AgentforceContextVariable[], options?: SetAgentforceContextOptions): Promise<SetAgentforceContextResult> | undefined;
116
+ /** Method form of {@link open}. */
117
+ open(botId?: string): Promise<AccPanelOperationResult>;
118
+ /** Method form of {@link close}. */
119
+ close(): Promise<AccPanelOperationResult>;
120
+ /** Method form of {@link execute}. */
121
+ execute(utterance: string, botId: string): Promise<AccPanelOperationResult>;
122
+ }
123
+ export interface EmbedAgentforceClientResult extends AgentforceBridgeMethods {
109
124
  loApp: AgentforceLightningOutApplication;
110
125
  chatClientComponent: HTMLElement;
111
126
  /**
@@ -115,4 +130,31 @@ export interface EmbedAgentforceClientResult {
115
130
  */
116
131
  setFrontdoorUrl: (frontdoorUrl: string) => void;
117
132
  }
133
+ /** Handle the bridge helpers operate on; `EmbedAgentforceClientResult` satisfies it. */
134
+ export interface AgentforceBridgeHandle {
135
+ chatClientComponent: HTMLElement;
136
+ /** Lightning Out app element; watched for teardown. */
137
+ loApp: HTMLElement;
138
+ }
139
+ /** `"Text" | "Boolean" | "Number"` in practice; open to `string` for future broker types. */
140
+ export type AgentforceContextVariableType = "Text" | "Boolean" | "Number" | (string & {});
141
+ /** A `$Context.`-prefixed `name` maps to a Context Variable; any other to a Conversation Variable. */
142
+ export interface AgentforceContextVariable {
143
+ name: string;
144
+ value: unknown;
145
+ type: AgentforceContextVariableType;
146
+ }
147
+ export interface SetAgentforceContextOptions {
148
+ /** Await the LWC ack; makes {@link setAgentforceContext} return a Promise. */
149
+ awaitApplied?: boolean;
150
+ }
151
+ export interface SetAgentforceContextResult {
152
+ /** Variables the LWC handed to its broker. */
153
+ applied: number;
154
+ }
155
+ /** Resolved value of a panel operation ({@link open} / {@link close} / {@link execute}). */
156
+ export interface AccPanelOperationResult {
157
+ status: true;
158
+ [key: string]: unknown;
159
+ }
118
160
  //# sourceMappingURL=types.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}
1
+ {"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}
@@ -3,27 +3,7 @@
3
3
  * All rights reserved.
4
4
  * For full license text, see the LICENSE.txt file
5
5
  */
6
- /**
7
- * Framework-agnostic glue for embedding the Agentforce Conversation Client (ACC)
8
- * via Lightning Out. This is the shared orchestration that used to be duplicated
9
- * across the React `AgentforceConversationClient` component and the Angular
10
- * `AgentforceEmbedService`:
11
- *
12
- * - a window-scoped singleton so exactly one embed happens per window, no matter
13
- * how many client wrappers mount;
14
- * - a shared body-level host for floating mode (created on demand);
15
- * - auth resolution — the dev frontdoor URL (`/__lo/frontdoor`) on localhost,
16
- * `SFDC_ENV.orgUrl` otherwise — merged with caller overrides;
17
- * - detection of an already-embedded client (`lightning-out-application[data-lo="acc"]`)
18
- * and cleanup of a partially-created element so the next mount can retry.
19
- *
20
- * Shipped as the `@salesforce/agentforce-conversation-client/ui-bundle` subpath
21
- * so it lives alongside the low-level `embedAgentforceClient` it orchestrates.
22
- * It still takes that embed function by dependency injection rather than
23
- * importing it directly, which keeps the glue framework-agnostic and unit-testable
24
- * with a mock embed function. The React/Angular feature templates own the import
25
- * and hand the function to {@link createAccEmbedder}.
26
- */
6
+ import type { AgentforceBridgeHandle, AgentforceBridgeMethods } from "./types.js";
27
7
  /** ACC ready callback — receives the Lightning Out ready detail. */
28
8
  export type AccReadyHandler = (detail: unknown) => void;
29
9
  /** ACC error callback — receives the Lightning Out error event. */
@@ -64,11 +44,16 @@ export interface AccEmbedRequest<TConfig extends AccConfigShape> {
64
44
  onReady?: AccReadyHandler;
65
45
  onError?: AccErrorHandler;
66
46
  }
47
+ /** Handle captured from the embed function and exposed via {@link getAccEmbed}. */
48
+ export interface AccEmbedHandle extends AgentforceBridgeMethods {
49
+ chatClientComponent: HTMLElement;
50
+ loApp: HTMLElement;
51
+ }
67
52
  /**
68
- * The low-level embed function (structurally, ACC's `embedAgentforceClient`),
69
- * supplied by the caller. Its return value is ignored by the glue.
53
+ * Low-level embed function (ACC's `embedAgentforceClient`); its handle is captured.
54
+ * Only the minimal handle is required — the bridge methods are attached on capture.
70
55
  */
71
- export type AccEmbedFn<TConfig extends AccConfigShape> = (options: AccEmbedRequest<TConfig>) => unknown;
56
+ export type AccEmbedFn<TConfig extends AccConfigShape> = (options: AccEmbedRequest<TConfig>) => AgentforceBridgeHandle | void;
72
57
  /** A configured embedder that guarantees a single embed per window. */
73
58
  export interface AccEmbedder<TConfig extends AccConfigShape> {
74
59
  /**
@@ -79,6 +64,8 @@ export interface AccEmbedder<TConfig extends AccConfigShape> {
79
64
  */
80
65
  embedAcc(config: TConfig, overrides?: AccEmbedOverrides, host?: HTMLElement | null, handlers?: AccEmbedHandlers): void;
81
66
  }
67
+ /** Embed handle for the bridge helpers, or `undefined` before the client embeds. */
68
+ export declare function getAccEmbed(): AccEmbedHandle | undefined;
82
69
  /**
83
70
  * Create an embedder bound to a low-level embed function.
84
71
  *
@@ -1 +1 @@
1
- {"version":3,"file":"ui-bundle.d.ts","sourceRoot":"","sources":["../src/ui-bundle.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,oEAAoE;AACpE,MAAM,MAAM,eAAe,GAAG,CAAC,MAAM,EAAE,OAAO,KAAK,IAAI,CAAC;AAExD,mEAAmE;AACnE,MAAM,MAAM,eAAe,GAAG,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC;AAEvD,+EAA+E;AAC/E,MAAM,WAAW,iBAAiB;IACjC,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,YAAY,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,gBAAgB;IAChC,OAAO,CAAC,CAAC,MAAM,EAAE,OAAO,GAAG,IAAI,CAAC;IAChC,OAAO,CAAC,CAAC,KAAK,EAAE,OAAO,GAAG,IAAI,CAAC;CAC/B;AAED;;;;GAIG;AACH,MAAM,WAAW,cAAc;IAC9B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,eAAe,CAAC,EAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;CACpC;AAED,0DAA0D;AAC1D,MAAM,WAAW,eAAe,CAAC,OAAO,SAAS,cAAc;IAC9D,SAAS,EAAE,WAAW,CAAC;IACvB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,sBAAsB,CAAC,EAAE,OAAO,CAAC;IACjC,OAAO,CAAC,EAAE,eAAe,CAAC;IAC1B,OAAO,CAAC,EAAE,eAAe,CAAC;CAC1B;AAED;;;GAGG;AACH,MAAM,MAAM,UAAU,CAAC,OAAO,SAAS,cAAc,IAAI,CACxD,OAAO,EAAE,eAAe,CAAC,OAAO,CAAC,KAC7B,OAAO,CAAC;AAEb,uEAAuE;AACvE,MAAM,WAAW,WAAW,CAAC,OAAO,SAAS,cAAc;IAC1D;;;;;OAKG;IACH,QAAQ,CACP,MAAM,EAAE,OAAO,EACf,SAAS,CAAC,EAAE,iBAAiB,EAC7B,IAAI,CAAC,EAAE,WAAW,GAAG,IAAI,EACzB,QAAQ,CAAC,EAAE,gBAAgB,GACzB,IAAI,CAAC;CACR;AAqDD;;;;;;;;;GASG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,SAAS,cAAc,EAC/D,OAAO,EAAE,UAAU,CAAC,OAAO,CAAC,GAC1B,WAAW,CAAC,OAAO,CAAC,CAuGtB"}
1
+ {"version":3,"file":"ui-bundle.d.ts","sourceRoot":"","sources":["../src/ui-bundle.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AA0BH,OAAO,KAAK,EAAE,sBAAsB,EAAE,uBAAuB,EAAE,MAAM,YAAY,CAAC;AAElF,oEAAoE;AACpE,MAAM,MAAM,eAAe,GAAG,CAAC,MAAM,EAAE,OAAO,KAAK,IAAI,CAAC;AAExD,mEAAmE;AACnE,MAAM,MAAM,eAAe,GAAG,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC;AAEvD,+EAA+E;AAC/E,MAAM,WAAW,iBAAiB;IACjC,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,YAAY,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,gBAAgB;IAChC,OAAO,CAAC,CAAC,MAAM,EAAE,OAAO,GAAG,IAAI,CAAC;IAChC,OAAO,CAAC,CAAC,KAAK,EAAE,OAAO,GAAG,IAAI,CAAC;CAC/B;AAED;;;;GAIG;AACH,MAAM,WAAW,cAAc;IAC9B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,eAAe,CAAC,EAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;CACpC;AAED,0DAA0D;AAC1D,MAAM,WAAW,eAAe,CAAC,OAAO,SAAS,cAAc;IAC9D,SAAS,EAAE,WAAW,CAAC;IACvB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,sBAAsB,CAAC,EAAE,OAAO,CAAC;IACjC,OAAO,CAAC,EAAE,eAAe,CAAC;IAC1B,OAAO,CAAC,EAAE,eAAe,CAAC;CAC1B;AAED,mFAAmF;AACnF,MAAM,WAAW,cAAe,SAAQ,uBAAuB;IAC9D,mBAAmB,EAAE,WAAW,CAAC;IACjC,KAAK,EAAE,WAAW,CAAC;CACnB;AAED;;;GAGG;AACH,MAAM,MAAM,UAAU,CAAC,OAAO,SAAS,cAAc,IAAI,CACxD,OAAO,EAAE,eAAe,CAAC,OAAO,CAAC,KAC7B,sBAAsB,GAAG,IAAI,CAAC;AAEnC,uEAAuE;AACvE,MAAM,WAAW,WAAW,CAAC,OAAO,SAAS,cAAc;IAC1D;;;;;OAKG;IACH,QAAQ,CACP,MAAM,EAAE,OAAO,EACf,SAAS,CAAC,EAAE,iBAAiB,EAC7B,IAAI,CAAC,EAAE,WAAW,GAAG,IAAI,EACzB,QAAQ,CAAC,EAAE,gBAAgB,GACzB,IAAI,CAAC;CACR;AAkCD,oFAAoF;AACpF,wBAAgB,WAAW,IAAI,cAAc,GAAG,SAAS,CAExD;AAsCD;;;;;;;;;GASG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,SAAS,cAAc,EAC/D,OAAO,EAAE,UAAU,CAAC,OAAO,CAAC,GAC1B,WAAW,CAAC,OAAO,CAAC,CAgHtB"}
package/dist/ui-bundle.js CHANGED
@@ -3,6 +3,29 @@
3
3
  * All rights reserved.
4
4
  * For full license text, see the LICENSE.txt file
5
5
  */
6
+ /**
7
+ * Framework-agnostic glue for embedding the Agentforce Conversation Client (ACC)
8
+ * via Lightning Out. This is the shared orchestration that used to be duplicated
9
+ * across the React `AgentforceConversationClient` component and the Angular
10
+ * `AgentforceEmbedService`:
11
+ *
12
+ * - a window-scoped singleton so exactly one embed happens per window, no matter
13
+ * how many client wrappers mount;
14
+ * - a shared body-level host for floating mode (created on demand);
15
+ * - auth resolution — the dev frontdoor URL (`/__lo/frontdoor`) on localhost,
16
+ * `SFDC_ENV.orgUrl` otherwise — merged with caller overrides;
17
+ * - detection of an already-embedded client (`lightning-out-application[data-lo="acc"]`)
18
+ * and cleanup of a partially-created element so the next mount can retry.
19
+ *
20
+ * Shipped as the `@salesforce/agentforce-conversation-client/ui-bundle` subpath
21
+ * so it lives alongside the low-level `embedAgentforceClient` it orchestrates.
22
+ * It still takes that embed function by dependency injection rather than
23
+ * importing it directly, which keeps the glue framework-agnostic and unit-testable
24
+ * with a mock embed function. The React/Angular feature templates own the import
25
+ * and hand the function to {@link createAccEmbedder}.
26
+ */
27
+ import { attachBridgeMethods } from "./bridge.js";
28
+ import { AGENTFORCE_CLIENT_ELEMENT_TAG } from "./constants.js";
6
29
  const GLOBAL_HOST_ID = "agentforce-conversation-client-global-host";
7
30
  const EXISTING_EMBED_SELECTOR = 'lightning-out-application[data-lo="acc"]';
8
31
  const SINGLETON_KEY = "__agentforceConversationClientSingleton";
@@ -19,6 +42,27 @@ function getSingleton() {
19
42
  }
20
43
  return win[SINGLETON_KEY];
21
44
  }
45
+ /** Embed handle for the bridge helpers, or `undefined` before the client embeds. */
46
+ export function getAccEmbed() {
47
+ return window[SINGLETON_KEY]?.embed;
48
+ }
49
+ /**
50
+ * Rebuild an {@link AccEmbedHandle} from an embed already in the DOM (another
51
+ * embedder instance, HMR, or a prior init whose handle was lost) so
52
+ * {@link getAccEmbed} stays functional. Returns `undefined` when either element
53
+ * is missing — a partial or foreign embed we cannot drive.
54
+ */
55
+ function getExistingEmbed() {
56
+ const loApp = document.querySelector(EXISTING_EMBED_SELECTOR);
57
+ if (!loApp)
58
+ return undefined;
59
+ const container = loApp.closest(".acc-container") ?? loApp.parentElement;
60
+ const chatClientComponent = container?.querySelector(AGENTFORCE_CLIENT_ELEMENT_TAG);
61
+ if (!chatClientComponent)
62
+ return undefined;
63
+ // Reconstructed handles need the bridge methods too.
64
+ return attachBridgeMethods({ chatClientComponent, loApp });
65
+ }
22
66
  function getOrCreateGlobalHost() {
23
67
  let host = document.getElementById(GLOBAL_HOST_ID);
24
68
  if (!host) {
@@ -66,7 +110,13 @@ export function createAccEmbedder(embedFn) {
66
110
  return;
67
111
  }
68
112
  if (document.querySelector(EXISTING_EMBED_SELECTOR)) {
69
- singleton.initialized = true;
113
+ // Reuse the existing embed's handle. Only mark initialized once we hold
114
+ // one, so an embed we can't drive leaves the path open for a real retry.
115
+ const existing = getExistingEmbed();
116
+ if (existing) {
117
+ singleton.embed = existing;
118
+ singleton.initialized = true;
119
+ }
70
120
  return;
71
121
  }
72
122
  const container = inline ? host : getOrCreateGlobalHost();
@@ -75,7 +125,7 @@ export function createAccEmbedder(embedFn) {
75
125
  // exclusive — setting both throws. The dev frontdoor URL (localhost)
76
126
  // wins when present; otherwise fall back to the org URL.
77
127
  const useFrontdoor = Boolean(options.frontdoorUrl);
78
- embedFn({
128
+ const handle = embedFn({
79
129
  container,
80
130
  salesforceOrigin: useFrontdoor ? undefined : options.salesforceOrigin,
81
131
  frontdoorUrl: options.frontdoorUrl,
@@ -83,6 +133,10 @@ export function createAccEmbedder(embedFn) {
83
133
  onReady: handlers?.onReady,
84
134
  onError: handlers?.onError,
85
135
  });
136
+ // Expose the handle so hosts can drive the panel / push context via
137
+ // getAccEmbed(). Undefined-safe: a void-returning embedFn just leaves it unset.
138
+ if (handle)
139
+ singleton.embed = attachBridgeMethods(handle); // exposed via getAccEmbed()
86
140
  singleton.initialized = true;
87
141
  }
88
142
  catch (err) {
@@ -0,0 +1,2 @@
1
+ export {};
2
+ //# sourceMappingURL=ui-bundle.spec.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"ui-bundle.spec.d.ts","sourceRoot":"","sources":["../src/ui-bundle.spec.ts"],"names":[],"mappings":""}
@@ -0,0 +1,90 @@
1
+ /**
2
+ * Copyright (c) 2026, Salesforce, Inc.,
3
+ * All rights reserved.
4
+ * For full license text, see the LICENSE.txt file
5
+ */
6
+ // @vitest-environment jsdom
7
+ import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
8
+ import { AGENTFORCE_CLIENT_ELEMENT_TAG } from "./constants";
9
+ import { createAccEmbedder, getAccEmbed } from "./ui-bundle";
10
+ const SINGLETON_KEY = "__agentforceConversationClientSingleton";
11
+ const FRAME_TAG = AGENTFORCE_CLIENT_ELEMENT_TAG;
12
+ /** Mount an ACC embed's two DOM elements (LO app + chat wrapper) inside a container. */
13
+ function mountExistingEmbed() {
14
+ const container = document.createElement("div");
15
+ container.classList.add("acc-container");
16
+ const loApp = document.createElement("lightning-out-application");
17
+ loApp.setAttribute("data-lo", "acc");
18
+ const frame = document.createElement(FRAME_TAG);
19
+ container.appendChild(loApp);
20
+ container.appendChild(frame);
21
+ document.body.appendChild(container);
22
+ return { loApp, frame, container };
23
+ }
24
+ /** Drain the embedder's async init (frontdoor fetch → safeInitialize). */
25
+ async function drainInit() {
26
+ const promise = window[SINGLETON_KEY]?.initPromise;
27
+ if (promise)
28
+ await promise;
29
+ }
30
+ beforeEach(() => {
31
+ // localhost (jsdom default) takes the frontdoor-fetch branch; stub a success.
32
+ vi.stubGlobal("fetch", vi.fn(async () => ({ ok: true, json: async () => ({ frontdoorUrl: "http://localhost/fd" }) })));
33
+ });
34
+ afterEach(() => {
35
+ delete window[SINGLETON_KEY];
36
+ document.body.innerHTML = "";
37
+ vi.unstubAllGlobals();
38
+ });
39
+ describe("createAccEmbedder recovery of an already-embedded client", () => {
40
+ const config = { agentId: "0Xxxx0000000001CAA" };
41
+ it("recovers the handle from the DOM instead of leaving getAccEmbed() undefined", async () => {
42
+ const { loApp, frame } = mountExistingEmbed();
43
+ const embedFn = vi.fn(() => undefined);
44
+ createAccEmbedder(embedFn).embedAcc(config);
45
+ await drainInit();
46
+ // It must not embed a second client...
47
+ expect(embedFn).not.toHaveBeenCalled();
48
+ // ...but the pre-existing embed is now driveable via getAccEmbed().
49
+ const handle = getAccEmbed();
50
+ expect(handle?.loApp).toBe(loApp);
51
+ expect(handle?.chatClientComponent).toBe(frame);
52
+ });
53
+ it("leaves the path open (not initialized) when the existing embed cannot be recovered", async () => {
54
+ // LO app present but no sibling chat wrapper — a partial/foreign embed we
55
+ // cannot drive. We must not mark initialized, so a later real embed retries.
56
+ const container = document.createElement("div");
57
+ const loApp = document.createElement("lightning-out-application");
58
+ loApp.setAttribute("data-lo", "acc");
59
+ container.appendChild(loApp);
60
+ document.body.appendChild(container);
61
+ const embedFn = vi.fn(() => undefined);
62
+ createAccEmbedder(embedFn).embedAcc(config);
63
+ await drainInit();
64
+ expect(embedFn).not.toHaveBeenCalled();
65
+ expect(getAccEmbed()).toBeUndefined();
66
+ const singleton = window[SINGLETON_KEY];
67
+ expect(singleton?.initialized).not.toBe(true);
68
+ });
69
+ });
70
+ describe("createAccEmbedder with a minimal-handle embed function", () => {
71
+ it("accepts a handle without bridge methods and attaches them on capture", async () => {
72
+ const config = { agentId: "0Xx000000000001", renderingConfig: {} };
73
+ const chatClientComponent = document.createElement(FRAME_TAG);
74
+ const loApp = document.createElement("lightning-out-application");
75
+ // Typed as the minimal handle: must stay assignable to AccEmbedFn.
76
+ const embedFn = vi.fn(() => ({
77
+ chatClientComponent,
78
+ loApp,
79
+ }));
80
+ createAccEmbedder(embedFn).embedAcc(config);
81
+ await drainInit();
82
+ expect(embedFn).toHaveBeenCalledOnce();
83
+ const handle = getAccEmbed();
84
+ expect(handle?.chatClientComponent).toBe(chatClientComponent);
85
+ expect(typeof handle?.setContext).toBe("function");
86
+ expect(typeof handle?.open).toBe("function");
87
+ expect(typeof handle?.close).toBe("function");
88
+ expect(typeof handle?.execute).toBe("function");
89
+ });
90
+ });
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "@salesforce/agentforce-conversation-client",
3
3
  "description": "Agentforce Conversation Client SDK for embedding via Lightning Out 2.0",
4
- "version": "12.10.0",
4
+ "version": "12.12.0",
5
5
  "license": "SEE LICENSE IN LICENSE.txt",
6
6
  "type": "module",
7
7
  "main": "./dist/index.js",