@saar-ai/web-widget 0.2.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 +209 -0
- package/dist/bot-avatar.d.ts +41 -0
- package/dist/bot-avatar.d.ts.map +1 -0
- package/dist/bot-face.d.ts +39 -0
- package/dist/bot-face.d.ts.map +1 -0
- package/dist/bot-state.d.ts +39 -0
- package/dist/bot-state.d.ts.map +1 -0
- package/dist/chunks/chat-ZLxYRTml.js +173 -0
- package/dist/chunks/esm-DSxqq2-d.js +3299 -0
- package/dist/chunks/host-widget-iy3qC-1p.js +7677 -0
- package/dist/chunks/livekit-client.esm-OPuvn_z-.js +26600 -0
- package/dist/chunks/schemas-Bl_6mxe4.js +4123 -0
- package/dist/chunks/telemetry-Bw-3F_Zk.js +290 -0
- package/dist/cn.d.ts +14 -0
- package/dist/cn.d.ts.map +1 -0
- package/dist/concierge-launcher.d.ts +50 -0
- package/dist/concierge-launcher.d.ts.map +1 -0
- package/dist/concierge-shell.d.ts +194 -0
- package/dist/concierge-shell.d.ts.map +1 -0
- package/dist/error-boundary.d.ts +34 -0
- package/dist/error-boundary.d.ts.map +1 -0
- package/dist/format-money.d.ts +20 -0
- package/dist/format-money.d.ts.map +1 -0
- package/dist/generated/widget-css.d.ts +2 -0
- package/dist/generated/widget-css.d.ts.map +1 -0
- package/dist/host-widget.d.ts +165 -0
- package/dist/host-widget.d.ts.map +1 -0
- package/dist/index.d.ts +28 -0
- package/dist/index.d.ts.map +1 -0
- package/dist/index.js +583 -0
- package/dist/messages.d.ts +116 -0
- package/dist/messages.d.ts.map +1 -0
- package/dist/morphing-loader.d.ts +16 -0
- package/dist/morphing-loader.d.ts.map +1 -0
- package/dist/mount.d.ts +45 -0
- package/dist/mount.d.ts.map +1 -0
- package/dist/next/index.d.ts +3 -0
- package/dist/next/index.d.ts.map +1 -0
- package/dist/next/index.js +86 -0
- package/dist/next/use-next-bridge.d.ts +113 -0
- package/dist/next/use-next-bridge.d.ts.map +1 -0
- package/dist/position.d.ts +65 -0
- package/dist/position.d.ts.map +1 -0
- package/dist/session-log.d.ts +84 -0
- package/dist/session-log.d.ts.map +1 -0
- package/dist/session-panel.d.ts +15 -0
- package/dist/session-panel.d.ts.map +1 -0
- package/dist/sse-parser.d.ts +38 -0
- package/dist/sse-parser.d.ts.map +1 -0
- package/dist/styles.d.ts +19 -0
- package/dist/styles.d.ts.map +1 -0
- package/dist/text-direction.d.ts +49 -0
- package/dist/text-direction.d.ts.map +1 -0
- package/dist/use-chat-session.d.ts +344 -0
- package/dist/use-chat-session.d.ts.map +1 -0
- package/dist/use-voice-session.d.ts +273 -0
- package/dist/use-voice-session.d.ts.map +1 -0
- package/dist/voice-session-state.d.ts +44 -0
- package/dist/voice-session-state.d.ts.map +1 -0
- package/dist/voice-widget.d.ts +167 -0
- package/dist/voice-widget.d.ts.map +1 -0
- package/dist/widget-cards.d.ts +69 -0
- package/dist/widget-cards.d.ts.map +1 -0
- package/dist/widget-cart-summary.d.ts +66 -0
- package/dist/widget-cart-summary.d.ts.map +1 -0
- package/dist/widget-markdown.d.ts +33 -0
- package/dist/widget-markdown.d.ts.map +1 -0
- package/dist/widget.css +2 -0
- package/package.json +88 -0
- package/src/styles/concierge.css +351 -0
- package/src/styles/tokens.css +67 -0
- package/src/styles/widget-entry.css +13 -0
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"styles.d.ts","sourceRoot":"","sources":["../src/styles.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AACH,OAAO,EAAE,UAAU,EAAE,MAAM,2BAA2B,CAAC"}
|
|
@@ -0,0 +1,49 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Base direction for a block of text whose language is the CONTENT's, not the
|
|
3
|
+
* reader's.
|
|
4
|
+
*
|
|
5
|
+
* Copied from `apps/web/src/i18n/text-direction.ts` (docs/WIDGET_EMBED_PLAN.md
|
|
6
|
+
* §4 Phase 3, coupling (2)) rather than imported — this package must not
|
|
7
|
+
* depend on `apps/web`, and the function is small, pure, and has no home in
|
|
8
|
+
* an existing shared package (`@wesence/i18n` / `@wesence/i18n-ui` do not own
|
|
9
|
+
* a direction helper today — see `packages/web-widget/AGENTS.md`'s Sharp
|
|
10
|
+
* edges for the duplication tradeoff, same reasoning as `cn.ts`). Keep the
|
|
11
|
+
* two copies in sync by hand; if a third copy is ever needed, that is the
|
|
12
|
+
* signal to extract a shared, framework-independent package instead.
|
|
13
|
+
*
|
|
14
|
+
* ## Why the widget's own direction is the wrong default
|
|
15
|
+
*
|
|
16
|
+
* `<html dir>` is set from the HOST PAGE's locale, and every element inherits
|
|
17
|
+
* it. That is right for the host's own chrome and wrong for a widget
|
|
18
|
+
* transcript: a shopper on an English storefront asking a question the
|
|
19
|
+
* concierge answers in Arabic would render that reply with an LTR base
|
|
20
|
+
* direction, and the Unicode bidirectional algorithm would then lay out the
|
|
21
|
+
* runs in the wrong order and throw trailing punctuation to the wrong end of
|
|
22
|
+
* the line.
|
|
23
|
+
*
|
|
24
|
+
* ## Mixed runs are the normal case here, not an edge case
|
|
25
|
+
*
|
|
26
|
+
* Verified against live recognition output: Arabic comes back as
|
|
27
|
+
* `رقم الـ order هو 4471. Please check من فضلك.` and Hindi as
|
|
28
|
+
* `मेरा order number 4471 है।`. Latin nouns inside a non-Latin sentence are
|
|
29
|
+
* what this product's transcripts actually contain, so bidirectional layout
|
|
30
|
+
* is exercised on ordinary traffic rather than by an unusual visitor.
|
|
31
|
+
*
|
|
32
|
+
* ## `auto` is the floor, not the goal
|
|
33
|
+
*
|
|
34
|
+
* With a known language this returns a definite direction. Without one it
|
|
35
|
+
* returns `auto`, which delegates to the browser's first-strong-character
|
|
36
|
+
* heuristic — better than inheriting the host page, but wrong for a message
|
|
37
|
+
* that opens with an English word and continues in Arabic
|
|
38
|
+
* (`Please check من فضلك`).
|
|
39
|
+
*/
|
|
40
|
+
export type TextDirection = 'ltr' | 'rtl' | 'auto';
|
|
41
|
+
/**
|
|
42
|
+
* The base direction for text in `locale`.
|
|
43
|
+
*
|
|
44
|
+
* @param locale BCP-47 tag carried on a conversation turn — untyped by the
|
|
45
|
+
* time it reaches here, so anything malformed resolves to `auto` rather
|
|
46
|
+
* than to a guess.
|
|
47
|
+
*/
|
|
48
|
+
export declare function textDirectionFor(locale: string | undefined | null): TextDirection;
|
|
49
|
+
//# sourceMappingURL=text-direction.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"text-direction.d.ts","sourceRoot":"","sources":["../src/text-direction.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AAqCH,MAAM,MAAM,aAAa,GAAG,KAAK,GAAG,KAAK,GAAG,MAAM,CAAC;AAEnD;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,GAAG,aAAa,CASjF"}
|
|
@@ -0,0 +1,344 @@
|
|
|
1
|
+
import type { VisitorEventCollector } from '@saar-ai/widget-bridge';
|
|
2
|
+
import { type ConciergePosition } from './position.js';
|
|
3
|
+
/**
|
|
4
|
+
* Text chat transport for the end-user widget: boots a session, sends typed
|
|
5
|
+
* turns over `POST /widget/chat` (SSE), and receives a human desk reply over
|
|
6
|
+
* a Socket.IO push — falling back to (and staying on, if the socket never
|
|
7
|
+
* connects) 4s polling of `GET /widget/messages` once the conversation is
|
|
8
|
+
* handed to a human. See the pinned contract in the PR-D task doc for the
|
|
9
|
+
* REST wire shapes; this file and `sse-parser.ts` are the only two places
|
|
10
|
+
* that know them.
|
|
11
|
+
*
|
|
12
|
+
* ## Push, with polling as the resilience story — not an either/or
|
|
13
|
+
*
|
|
14
|
+
* `apps/api/src/realtime/widget.gateway.ts` pushes a `desk:message` event to
|
|
15
|
+
* this conversation's room the instant a human's reply commits — see that
|
|
16
|
+
* file and `desk-messages.service.ts`'s doc comment for the "after commit"
|
|
17
|
+
* guarantee. This hook connects a socket ONLY when `socketUrl` is passed
|
|
18
|
+
* (opt-in — see `DemoChatSessionProvider`, the one production caller), ONLY
|
|
19
|
+
* after the session has booted (the socket auth is the widget chat token
|
|
20
|
+
* `POST /widget/session` just minted), and ONLY once `status` becomes
|
|
21
|
+
* `'escalated'` — a conversation still being handled by the AI never opens a
|
|
22
|
+
* socket at all. The poll loop is NEVER deleted: a corporate proxy that
|
|
23
|
+
* blocks WebSocket upgrades is a real condition for an embedded widget, and
|
|
24
|
+
* `connection` staying `'connecting'` or `'disconnected'` is exactly what
|
|
25
|
+
* makes the poll interval stay at its normal 4s cadence instead of dropping
|
|
26
|
+
* to the idle cadence a live socket earns (see the poll-interval effect
|
|
27
|
+
* below).
|
|
28
|
+
*
|
|
29
|
+
* ## `socket.io-client` is loaded lazily, not statically
|
|
30
|
+
*
|
|
31
|
+
* `socket.io-client` (~40 KB min+gz) is bundled into the `desk` artefact
|
|
32
|
+
* (`docs/WIDGET_EMBED_PLAN.md` §5.6/§5.7), which must never reach a shopper
|
|
33
|
+
* whose conversation is never escalated to a human — most of them. So this
|
|
34
|
+
* file holds no runtime `import` of `socket.io-client` at all (only an
|
|
35
|
+
* erased `import type { Socket }` for the ref's type) — the socket effect
|
|
36
|
+
* below resolves the real module via a dynamic `import('socket.io-client')`
|
|
37
|
+
* the first time `status` becomes `'escalated'`, never before. `socketImpl`
|
|
38
|
+
* (tests) bypasses the dynamic import entirely, so a test double never pays
|
|
39
|
+
* for or waits on a module load.
|
|
40
|
+
*
|
|
41
|
+
* ## Push and poll converge to ONE rendered turn, never two
|
|
42
|
+
*
|
|
43
|
+
* Both paths hand their turns to `mergeIncoming`, the ONE function that
|
|
44
|
+
* appends to `turns`. It dedupes by `seq` (`seenSeqRef`, a `Set<number>`),
|
|
45
|
+
* not by comparing against a single "highest seq seen" watermark — a
|
|
46
|
+
* watermark would wrongly DROP a genuinely new, lower-seq turn that a poll
|
|
47
|
+
* delivers late after a socket reconnect skipped ahead to a higher one (a
|
|
48
|
+
* real scenario: the socket drops for a few seconds, misses turn N, then
|
|
49
|
+
* reconnects and receives turn N+1; the next poll still owes the visitor
|
|
50
|
+
* turn N). `afterSeq` — `lastSeqRef`, the query param the poll sends — still
|
|
51
|
+
* only ever moves forward (the highest seq processed by EITHER path), which
|
|
52
|
+
* is what keeps polling from re-fetching turns push already delivered.
|
|
53
|
+
*
|
|
54
|
+
* ## Visitor identity is proven, not asserted
|
|
55
|
+
*
|
|
56
|
+
* `POST /widget/session` no longer trusts a bare client-held `visitorId` to
|
|
57
|
+
* rejoin an existing conversation — see `apps/api/src/widget/
|
|
58
|
+
* widget-chat-token.ts`'s module doc comment for the exploit this closes. The
|
|
59
|
+
* server hands back a `visitorProof` (a short opaque, server-signed token)
|
|
60
|
+
* alongside every `visitorId` it mints; this hook stores BOTH in
|
|
61
|
+
* `localStorage` and sends BOTH on the next boot. It never mints an id
|
|
62
|
+
* itself. A boot whose stored proof is missing, expired, or mismatched is not
|
|
63
|
+
* an error — the server silently falls back to a fresh `visitorId`/
|
|
64
|
+
* `visitorProof` pair, which this hook adopts unconditionally (see the boot
|
|
65
|
+
* effect's `persistVisitor` call).
|
|
66
|
+
*
|
|
67
|
+
* ## Why this is a hook and not a class, unlike `use-voice-session.ts`
|
|
68
|
+
*
|
|
69
|
+
* The voice hook wraps a stateful room object with its own event emitter —
|
|
70
|
+
* there is something worth naming (`VoiceRoomLike`) and swapping in tests.
|
|
71
|
+
* Text chat has no such object: `fetch` + a stream reader is the entire
|
|
72
|
+
* surface, so the fake-able seam is `fetchImpl`, an ordinary parameter, not a
|
|
73
|
+
* port interface.
|
|
74
|
+
*
|
|
75
|
+
* ## "Optimistic" append, precisely
|
|
76
|
+
*
|
|
77
|
+
* The caller turn is appended to `turns` the moment `POST /widget/chat`
|
|
78
|
+
* comes back with an ok status — i.e. before the reply has streamed a single
|
|
79
|
+
* character, which is what "optimistic" buys here (the caller sees their own
|
|
80
|
+
* line immediately, not after the agent finishes). It is NOT appended before
|
|
81
|
+
* the request is even sent: if the POST itself fails (network error, or a
|
|
82
|
+
* non-2xx before any stream starts), `send` returns `false` and nothing is
|
|
83
|
+
* added to `turns` — this keeps `send` a real predicate `VoiceWidget.onSendText`
|
|
84
|
+
* can trust ("resolves true" ⇒ "this really is now part of the conversation"),
|
|
85
|
+
* and avoids ever needing to roll an optimistic turn back out.
|
|
86
|
+
*/
|
|
87
|
+
export type ChatStatus = 'idle' | 'streaming' | 'escalated' | 'error';
|
|
88
|
+
/**
|
|
89
|
+
* `'idle'` — no `socketUrl` configured, or the session hasn't booted yet
|
|
90
|
+
* (poll, once escalated, runs at its normal cadence).
|
|
91
|
+
* `'connecting'` — a chatToken exists and a connection attempt is in
|
|
92
|
+
* flight, including a reconnect after a drop.
|
|
93
|
+
* `'connected'` — the socket handshake succeeded; poll (if escalated) drops
|
|
94
|
+
* to the idle cadence.
|
|
95
|
+
* `'disconnected'` — the socket was connected and is not anymore (dropped,
|
|
96
|
+
* or the handshake was refused); poll restores to its normal cadence.
|
|
97
|
+
*/
|
|
98
|
+
export type ChatConnectionState = 'idle' | 'connecting' | 'connected' | 'disconnected';
|
|
99
|
+
export interface ChatCardItem {
|
|
100
|
+
readonly productId: string;
|
|
101
|
+
/** The INTERNAL catalog UUID (`curation_items.variant_id`) — never a platform id. See {@link ChatCardItem.platformVariantId} for what `addToCart` actually needs. */
|
|
102
|
+
readonly variantId?: string;
|
|
103
|
+
/**
|
|
104
|
+
* The PLATFORM-NATIVE variant id (e.g. Shopify's numeric `/cart/add.js`
|
|
105
|
+
* id, extracted server-side from the variant's provider GID via
|
|
106
|
+
* `apps/api/src/catalog/checkout-permalink.ts`'s
|
|
107
|
+
* `parseShopifyVariantNumericId` — the SAME parser the checkout permalink
|
|
108
|
+
* uses, never a client-side string-slice of {@link ChatCardItem.variantId}).
|
|
109
|
+
*
|
|
110
|
+
* `resolveAddToCartHandler` (`host-widget.tsx`) calls `bridge.addToCart`
|
|
111
|
+
* with THIS field, never `variantId` — adversarial-review finding #2: the
|
|
112
|
+
* internal UUID is meaningless to `ShopifyBridge`'s `POST /cart/add.js`,
|
|
113
|
+
* which needs Shopify's own numeric id. Absent whenever the underlying
|
|
114
|
+
* variant's external id isn't a recognised platform GID (§5.3's "degrade,
|
|
115
|
+
* never fabricate" — never guessed from `variantId`) — in that case the
|
|
116
|
+
* widget offers no add-to-cart action for this card and falls back to a
|
|
117
|
+
* PDP navigation instead, same as a card with no `handle` at all falling
|
|
118
|
+
* back to nothing.
|
|
119
|
+
*/
|
|
120
|
+
readonly platformVariantId?: string;
|
|
121
|
+
readonly title: string;
|
|
122
|
+
readonly imageUrl?: string;
|
|
123
|
+
/** Storefront handle, for the card's link to the PDP. Absent ⇒ the card renders unlinked. */
|
|
124
|
+
readonly handle?: string;
|
|
125
|
+
readonly priceMinor: number;
|
|
126
|
+
readonly currency: string;
|
|
127
|
+
readonly available: boolean;
|
|
128
|
+
readonly reason?: string;
|
|
129
|
+
}
|
|
130
|
+
export interface ChatCards {
|
|
131
|
+
readonly curationId?: string;
|
|
132
|
+
readonly items: readonly ChatCardItem[];
|
|
133
|
+
}
|
|
134
|
+
/**
|
|
135
|
+
* A real Shopify checkout handoff the `checkout_handoff` concierge tool
|
|
136
|
+
* produced — `url` is a server-built permalink (see `apps/api/src/catalog/
|
|
137
|
+
* checkout-permalink.ts`), never anything this client constructs itself.
|
|
138
|
+
*/
|
|
139
|
+
export interface ChatCheckoutHandoff {
|
|
140
|
+
readonly handoffId: string;
|
|
141
|
+
readonly url: string;
|
|
142
|
+
readonly itemCount: number;
|
|
143
|
+
}
|
|
144
|
+
/**
|
|
145
|
+
* A file/image carried on a turn, either direction. `url` is minted FRESH by
|
|
146
|
+
* the server for whichever read delivered this turn (the poll response or
|
|
147
|
+
* the socket push) — never a stored value, and it expires; the widget must
|
|
148
|
+
* not hold onto it past this render.
|
|
149
|
+
*/
|
|
150
|
+
export interface ChatAttachment {
|
|
151
|
+
readonly id: string;
|
|
152
|
+
readonly filename: string;
|
|
153
|
+
readonly contentType: string;
|
|
154
|
+
readonly byteSize: number;
|
|
155
|
+
readonly url: string;
|
|
156
|
+
readonly expiresAt: string;
|
|
157
|
+
}
|
|
158
|
+
export interface ChatTurn {
|
|
159
|
+
readonly id: string;
|
|
160
|
+
readonly speaker: 'caller' | 'agent';
|
|
161
|
+
readonly text: string;
|
|
162
|
+
/** `false` while an agent turn is still streaming in. */
|
|
163
|
+
readonly final: boolean;
|
|
164
|
+
/** Product cards the agent attached to THIS turn, if any. */
|
|
165
|
+
readonly cards?: ChatCards;
|
|
166
|
+
/** Files carried on THIS turn, either direction. Empty/absent for a turn with none. */
|
|
167
|
+
readonly attachments?: readonly ChatAttachment[];
|
|
168
|
+
}
|
|
169
|
+
export interface ChatAttribution {
|
|
170
|
+
readonly pageUrl?: string;
|
|
171
|
+
readonly referrer?: string;
|
|
172
|
+
readonly utmSource?: string;
|
|
173
|
+
readonly [key: string]: unknown;
|
|
174
|
+
}
|
|
175
|
+
export interface UseChatSessionOptions {
|
|
176
|
+
readonly embedKey: string;
|
|
177
|
+
readonly attribution?: ChatAttribution;
|
|
178
|
+
/** Overridable for tests; defaults to the global `fetch`. */
|
|
179
|
+
readonly fetchImpl?: typeof fetch;
|
|
180
|
+
/** Same-origin widget proxy base — see `app/api/widget/[...path]/route.ts`. */
|
|
181
|
+
readonly apiBase?: string;
|
|
182
|
+
/** Poll interval while escalated AND the socket is not connected, ms. Defaults to 4000 per the contract. */
|
|
183
|
+
readonly pollIntervalMs?: number;
|
|
184
|
+
/**
|
|
185
|
+
* Poll interval while escalated AND the socket IS connected — a much
|
|
186
|
+
* slower safety net, not a second primary channel. Defaults to 30000.
|
|
187
|
+
*/
|
|
188
|
+
readonly idlePollIntervalMs?: number;
|
|
189
|
+
/**
|
|
190
|
+
* The api's ORIGIN (e.g. `https://api.example.com`) the widget socket
|
|
191
|
+
* connects to DIRECTLY — never through `apiBase`'s same-origin proxy, which
|
|
192
|
+
* cannot forward a WebSocket upgrade (see the module doc comment and
|
|
193
|
+
* `app/api/widget/[...path]/route.ts`). Omitted ⇒ no socket is ever
|
|
194
|
+
* opened and the hook behaves exactly as it did before push existed
|
|
195
|
+
* (poll-only, at `pollIntervalMs`) — this feature is additive and opt-in
|
|
196
|
+
* per caller.
|
|
197
|
+
*/
|
|
198
|
+
readonly socketUrl?: string;
|
|
199
|
+
/** Path the widget's Socket.IO gateway is mounted on. Defaults to `/socket.io'. */
|
|
200
|
+
readonly socketPath?: string;
|
|
201
|
+
/**
|
|
202
|
+
* Overridable for tests; defaults to a dynamic `import('socket.io-client')`
|
|
203
|
+
* resolved lazily (see the module doc comment) — never call this directly
|
|
204
|
+
* outside the socket effect.
|
|
205
|
+
*/
|
|
206
|
+
readonly socketImpl?: typeof import('socket.io-client').io;
|
|
207
|
+
/**
|
|
208
|
+
* Wires the visitor-event pipeline: when supplied, the moment
|
|
209
|
+
* `POST /widget/session` boots successfully this hook calls
|
|
210
|
+
* `collector.setSession({ chatToken, visitorSessionId, expiresAt })` —
|
|
211
|
+
* `expiresAt` converted from the wire's ISO-8601 string via `Date.parse`,
|
|
212
|
+
* the epoch-ms shape `CollectorSession` wants (docs/WIDGET_EMBED_PLAN.md
|
|
213
|
+
* §4 Phase 3, "Wire the collector"). Absent ⇒ no collector wiring at all,
|
|
214
|
+
* which is the demo storefront's current, tested behaviour
|
|
215
|
+
* (`chat-session-context.tsx` keeps its own `sendEvent`-based queue) —
|
|
216
|
+
* this option is purely additive.
|
|
217
|
+
*/
|
|
218
|
+
readonly collector?: VisitorEventCollector;
|
|
219
|
+
}
|
|
220
|
+
export interface WidgetEventInput {
|
|
221
|
+
readonly kind: 'page.viewed' | 'product.viewed' | 'cart.viewed' | 'cart.changed' | 'checkout.handoff';
|
|
222
|
+
readonly payload: Record<string, unknown>;
|
|
223
|
+
}
|
|
224
|
+
export interface UseChatSessionResult {
|
|
225
|
+
readonly turns: readonly ChatTurn[];
|
|
226
|
+
/**
|
|
227
|
+
* How the tenant configured the COLLAPSED widget — label and starting
|
|
228
|
+
* anchor. Empty until the session boots; see `WidgetLauncherConfig`.
|
|
229
|
+
*/
|
|
230
|
+
readonly launcher: WidgetLauncherConfig;
|
|
231
|
+
/** Every `cards` event received this session, oldest first. */
|
|
232
|
+
readonly cards: readonly ChatCards[];
|
|
233
|
+
/** Every `checkout` event received this session, oldest first — see `checkout_handoff` (the concierge tool). */
|
|
234
|
+
readonly checkoutHandoffs: readonly ChatCheckoutHandoff[];
|
|
235
|
+
readonly status: ChatStatus;
|
|
236
|
+
readonly error?: string;
|
|
237
|
+
/** `true` once `POST /widget/session` has resolved (success or failure). */
|
|
238
|
+
readonly ready: boolean;
|
|
239
|
+
/**
|
|
240
|
+
* The widget socket's live state — see `ChatConnectionState`'s doc
|
|
241
|
+
* comment. Stays `'idle'` for the lifetime of the session when no
|
|
242
|
+
* `socketUrl` was passed; nothing about `send`/`sendEvent`/`checkout`
|
|
243
|
+
* depends on it, it exists for callers that want to show a "live" vs
|
|
244
|
+
* "syncing" indicator.
|
|
245
|
+
*/
|
|
246
|
+
readonly connection: ChatConnectionState;
|
|
247
|
+
/**
|
|
248
|
+
* Which channels the tenant's published widget config enables —
|
|
249
|
+
* `StartWidgetSessionResult.modalities` (`apps/api/src/widget/
|
|
250
|
+
* widget-chat.service.ts`), `{text: true, voice: false}` until the boot
|
|
251
|
+
* response arrives (a browser can always type before anything resolves;
|
|
252
|
+
* it can never assume voice). `ConciergeWidget` (`host-widget.tsx`) reads
|
|
253
|
+
* `modalities.voice` to decide whether to offer the microphone at all —
|
|
254
|
+
* see that file's doc comment.
|
|
255
|
+
*/
|
|
256
|
+
readonly modalities: {
|
|
257
|
+
readonly text: boolean;
|
|
258
|
+
readonly voice: boolean;
|
|
259
|
+
};
|
|
260
|
+
/**
|
|
261
|
+
* The webchat session's own bearer token, once `POST /widget/session` has
|
|
262
|
+
* resolved — `undefined` before boot or on a boot failure. Exposed so a
|
|
263
|
+
* caller that also wants a VOICE leg (`ConciergeWidget`) can authenticate
|
|
264
|
+
* `POST /widget/voice/token` with it; nothing in this hook itself reads
|
|
265
|
+
* it beyond that boot response.
|
|
266
|
+
*/
|
|
267
|
+
readonly chatToken: string | undefined;
|
|
268
|
+
/** Sends a typed turn. Resolves `true` only once the server has accepted it. */
|
|
269
|
+
/**
|
|
270
|
+
* Send a turn.
|
|
271
|
+
*
|
|
272
|
+
* `silent: true` omits the CALLER bubble from this client's transcript while
|
|
273
|
+
* still sending the message — for a nudge the UI issued on the shopper's
|
|
274
|
+
* behalf rather than something they typed (today: "what goes with the thing
|
|
275
|
+
* they just added?"). Rendering it as a shopper line would put words in
|
|
276
|
+
* their mouth; suppressing it entirely would leave the reply answering a
|
|
277
|
+
* question nobody can see, which is why the nudge is phrased so the ANSWER
|
|
278
|
+
* stands on its own.
|
|
279
|
+
*
|
|
280
|
+
* The message is still recorded server-side, so the operator's transcript
|
|
281
|
+
* and the model's context both show it — this hides it in one place, on
|
|
282
|
+
* purpose, and does not rewrite history.
|
|
283
|
+
*/
|
|
284
|
+
readonly send: (text: string, options?: {
|
|
285
|
+
silent?: boolean;
|
|
286
|
+
}) => Promise<boolean>;
|
|
287
|
+
/**
|
|
288
|
+
* `POST /widget/event` with the session's chatToken. Resolves `false` (never
|
|
289
|
+
* throws) with no session or on a network/HTTP failure — browsing telemetry
|
|
290
|
+
* degrading silently is the correct failure mode; it must never surface as a
|
|
291
|
+
* storefront error the visitor sees.
|
|
292
|
+
*/
|
|
293
|
+
readonly sendEvent: (events: readonly WidgetEventInput[]) => Promise<boolean>;
|
|
294
|
+
/**
|
|
295
|
+
* The add-to-cart-time attribution token the SERVER established
|
|
296
|
+
* (`CheckoutHandoffService.recordCartAdd`), surfaced here the moment a
|
|
297
|
+
* `sendEvent` response carries one — see `sendEvent`'s implementation for
|
|
298
|
+
* why `POST /widget/event`'s own response is where this rides, rather
|
|
299
|
+
* than a dedicated endpoint. `null` until then. A caller that wants this
|
|
300
|
+
* to survive a page reload / a later, different conversation must persist
|
|
301
|
+
* it itself (`use-cart.tsx`'s `setAttributionToken` — this hook stays
|
|
302
|
+
* cart-agnostic, the same way it stays ignorant of every other
|
|
303
|
+
* storefront-specific concern).
|
|
304
|
+
*/
|
|
305
|
+
readonly cartAttributionToken: string | null;
|
|
306
|
+
/**
|
|
307
|
+
* `POST /widget/checkout` — the storefront's OWN checkout button, independent
|
|
308
|
+
* of any AI turn (see `apps/api/src/widget/widget-chat.service.ts`'s
|
|
309
|
+
* `createCheckoutHandoff` doc comment). Resolves `null` (never throws) with
|
|
310
|
+
* no session or on a network/HTTP failure.
|
|
311
|
+
*
|
|
312
|
+
* `cartAttributionToken` (third argument, distinct from the field of the
|
|
313
|
+
* same name above) is the CLIENT-held token to send back — the caller
|
|
314
|
+
* reads it from wherever it persisted it (`useCart().attributionToken`)
|
|
315
|
+
* and passes it through; this hook never reaches into cart state itself.
|
|
316
|
+
*/
|
|
317
|
+
readonly checkout: (items: readonly {
|
|
318
|
+
variantId: string;
|
|
319
|
+
quantity: number;
|
|
320
|
+
}[], curationId?: string, cartAttributionToken?: string) => Promise<ChatCheckoutHandoff | null>;
|
|
321
|
+
/**
|
|
322
|
+
* Upload → confirm → append, in one call. See `WidgetChatService.
|
|
323
|
+
* sendAttachment`'s doc comment: this ALWAYS escalates (vision is out of
|
|
324
|
+
* scope), so a successful call also flips `status` to `'escalated'`, the
|
|
325
|
+
* same as the SSE `escalated` event `send` can produce. `message` is an
|
|
326
|
+
* optional caption sent alongside the file, stored on the SAME turn.
|
|
327
|
+
* Resolves `false` (never throws) with no session or on any failure —
|
|
328
|
+
* type/size rejections included; the caller inspects `error` for what to
|
|
329
|
+
* show the visitor.
|
|
330
|
+
*/
|
|
331
|
+
readonly sendAttachment: (file: File, message?: string) => Promise<boolean>;
|
|
332
|
+
}
|
|
333
|
+
/** What the collapsed widget shows, as the tenant configured it. */
|
|
334
|
+
export interface WidgetLauncherConfig {
|
|
335
|
+
readonly label?: string;
|
|
336
|
+
readonly position?: ConciergePosition;
|
|
337
|
+
/**
|
|
338
|
+
* May a visitor move it? Resolved by the control tier, so `undefined` here
|
|
339
|
+
* means only "the session has not booted yet" — never "we could not decide".
|
|
340
|
+
*/
|
|
341
|
+
readonly draggable?: boolean;
|
|
342
|
+
}
|
|
343
|
+
export declare function useChatSession(options: UseChatSessionOptions): UseChatSessionResult;
|
|
344
|
+
//# sourceMappingURL=use-chat-session.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"use-chat-session.d.ts","sourceRoot":"","sources":["../src/use-chat-session.ts"],"names":[],"mappings":"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"}
|