@salesforce/agentforce-conversation-client 12.9.0 → 12.11.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 +91 -6
- package/dist/bridge.d.ts +39 -0
- package/dist/bridge.d.ts.map +1 -0
- package/dist/bridge.js +206 -0
- package/dist/bridge.spec.d.ts +2 -0
- package/dist/bridge.spec.d.ts.map +1 -0
- package/dist/bridge.spec.js +277 -0
- package/dist/embed.d.ts.map +1 -1
- package/dist/embed.js +2 -1
- package/dist/index.d.ts +1 -1
- package/dist/index.d.ts.map +1 -1
- package/dist/index.spec.js +66 -0
- package/dist/types.d.ts +43 -1
- package/dist/types.d.ts.map +1 -1
- package/dist/ui-bundle.d.ts +11 -24
- package/dist/ui-bundle.d.ts.map +1 -1
- package/dist/ui-bundle.js +56 -2
- package/dist/ui-bundle.spec.d.ts +2 -0
- package/dist/ui-bundle.spec.d.ts.map +1 -0
- package/dist/ui-bundle.spec.js +90 -0
- package/package.json +1 -1
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
|
|
630
|
-
|
|
|
631
|
-
| `loApp`
|
|
632
|
-
| `chatClientComponent`
|
|
633
|
-
| `setFrontdoorUrl`
|
|
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
|
package/dist/bridge.d.ts
ADDED
|
@@ -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 @@
|
|
|
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
|
+
});
|
package/dist/embed.d.ts.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"embed.d.ts","sourceRoot":"","sources":["../src/embed.ts"],"names":[],"mappings":"
|
|
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
|
package/dist/index.d.ts.map
CHANGED
|
@@ -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,
|
|
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"}
|
package/dist/index.spec.js
CHANGED
|
@@ -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
|
-
|
|
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
|
package/dist/types.d.ts.map
CHANGED
|
@@ -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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"}
|
package/dist/ui-bundle.d.ts
CHANGED
|
@@ -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
|
-
*
|
|
69
|
-
*
|
|
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>) =>
|
|
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
|
*
|
package/dist/ui-bundle.d.ts.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"ui-bundle.d.ts","sourceRoot":"","sources":["../src/ui-bundle.ts"],"names":[],"mappings":"AAAA;;;;GAIG;
|
|
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
|
-
|
|
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 @@
|
|
|
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.
|
|
4
|
+
"version": "12.11.0",
|
|
5
5
|
"license": "SEE LICENSE IN LICENSE.txt",
|
|
6
6
|
"type": "module",
|
|
7
7
|
"main": "./dist/index.js",
|