@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.
Files changed (72) hide show
  1. package/README.md +209 -0
  2. package/dist/bot-avatar.d.ts +41 -0
  3. package/dist/bot-avatar.d.ts.map +1 -0
  4. package/dist/bot-face.d.ts +39 -0
  5. package/dist/bot-face.d.ts.map +1 -0
  6. package/dist/bot-state.d.ts +39 -0
  7. package/dist/bot-state.d.ts.map +1 -0
  8. package/dist/chunks/chat-ZLxYRTml.js +173 -0
  9. package/dist/chunks/esm-DSxqq2-d.js +3299 -0
  10. package/dist/chunks/host-widget-iy3qC-1p.js +7677 -0
  11. package/dist/chunks/livekit-client.esm-OPuvn_z-.js +26600 -0
  12. package/dist/chunks/schemas-Bl_6mxe4.js +4123 -0
  13. package/dist/chunks/telemetry-Bw-3F_Zk.js +290 -0
  14. package/dist/cn.d.ts +14 -0
  15. package/dist/cn.d.ts.map +1 -0
  16. package/dist/concierge-launcher.d.ts +50 -0
  17. package/dist/concierge-launcher.d.ts.map +1 -0
  18. package/dist/concierge-shell.d.ts +194 -0
  19. package/dist/concierge-shell.d.ts.map +1 -0
  20. package/dist/error-boundary.d.ts +34 -0
  21. package/dist/error-boundary.d.ts.map +1 -0
  22. package/dist/format-money.d.ts +20 -0
  23. package/dist/format-money.d.ts.map +1 -0
  24. package/dist/generated/widget-css.d.ts +2 -0
  25. package/dist/generated/widget-css.d.ts.map +1 -0
  26. package/dist/host-widget.d.ts +165 -0
  27. package/dist/host-widget.d.ts.map +1 -0
  28. package/dist/index.d.ts +28 -0
  29. package/dist/index.d.ts.map +1 -0
  30. package/dist/index.js +583 -0
  31. package/dist/messages.d.ts +116 -0
  32. package/dist/messages.d.ts.map +1 -0
  33. package/dist/morphing-loader.d.ts +16 -0
  34. package/dist/morphing-loader.d.ts.map +1 -0
  35. package/dist/mount.d.ts +45 -0
  36. package/dist/mount.d.ts.map +1 -0
  37. package/dist/next/index.d.ts +3 -0
  38. package/dist/next/index.d.ts.map +1 -0
  39. package/dist/next/index.js +86 -0
  40. package/dist/next/use-next-bridge.d.ts +113 -0
  41. package/dist/next/use-next-bridge.d.ts.map +1 -0
  42. package/dist/position.d.ts +65 -0
  43. package/dist/position.d.ts.map +1 -0
  44. package/dist/session-log.d.ts +84 -0
  45. package/dist/session-log.d.ts.map +1 -0
  46. package/dist/session-panel.d.ts +15 -0
  47. package/dist/session-panel.d.ts.map +1 -0
  48. package/dist/sse-parser.d.ts +38 -0
  49. package/dist/sse-parser.d.ts.map +1 -0
  50. package/dist/styles.d.ts +19 -0
  51. package/dist/styles.d.ts.map +1 -0
  52. package/dist/text-direction.d.ts +49 -0
  53. package/dist/text-direction.d.ts.map +1 -0
  54. package/dist/use-chat-session.d.ts +344 -0
  55. package/dist/use-chat-session.d.ts.map +1 -0
  56. package/dist/use-voice-session.d.ts +273 -0
  57. package/dist/use-voice-session.d.ts.map +1 -0
  58. package/dist/voice-session-state.d.ts +44 -0
  59. package/dist/voice-session-state.d.ts.map +1 -0
  60. package/dist/voice-widget.d.ts +167 -0
  61. package/dist/voice-widget.d.ts.map +1 -0
  62. package/dist/widget-cards.d.ts +69 -0
  63. package/dist/widget-cards.d.ts.map +1 -0
  64. package/dist/widget-cart-summary.d.ts +66 -0
  65. package/dist/widget-cart-summary.d.ts.map +1 -0
  66. package/dist/widget-markdown.d.ts +33 -0
  67. package/dist/widget-markdown.d.ts.map +1 -0
  68. package/dist/widget.css +2 -0
  69. package/package.json +88 -0
  70. package/src/styles/concierge.css +351 -0
  71. package/src/styles/tokens.css +67 -0
  72. 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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"}