@saar-ai/web-widget 0.4.1 → 0.6.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/dist/card-aspect.d.ts +58 -0
- package/dist/card-aspect.d.ts.map +1 -0
- package/dist/chunks/chat-tMKkYmTC.js +592 -0
- package/dist/chunks/host-widget-C0XT9lHX.js +9637 -0
- package/dist/chunks/{telemetry-Bw-3F_Zk.js → telemetry-BI_SEWTb.js} +104 -2
- package/dist/dock/dock-caption.d.ts +67 -0
- package/dist/dock/dock-caption.d.ts.map +1 -0
- package/dist/dock/dock-motion.d.ts +155 -0
- package/dist/dock/dock-motion.d.ts.map +1 -0
- package/dist/dock/dock-pill.d.ts +38 -0
- package/dist/dock/dock-pill.d.ts.map +1 -0
- package/dist/dock/dock-row.d.ts +120 -0
- package/dist/dock/dock-row.d.ts.map +1 -0
- package/dist/dock/dock-sheet.d.ts +89 -0
- package/dist/dock/dock-sheet.d.ts.map +1 -0
- package/dist/dock/dock-shelf.d.ts +38 -0
- package/dist/dock/dock-shelf.d.ts.map +1 -0
- package/dist/dock/dock-state.d.ts +221 -0
- package/dist/dock/dock-state.d.ts.map +1 -0
- package/dist/dock/dock.d.ts +344 -0
- package/dist/dock/dock.d.ts.map +1 -0
- package/dist/dock/geometry.d.ts +161 -0
- package/dist/dock/geometry.d.ts.map +1 -0
- package/dist/format-money.d.ts +54 -17
- package/dist/format-money.d.ts.map +1 -1
- package/dist/generated/widget-css.d.ts.map +1 -1
- package/dist/host-widget.d.ts +156 -16
- package/dist/host-widget.d.ts.map +1 -1
- package/dist/index.d.ts +7 -3
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +4029 -7
- package/dist/messages.d.ts +86 -0
- package/dist/messages.d.ts.map +1 -1
- package/dist/next/index.js +1 -1
- package/dist/session-log.d.ts +7 -0
- package/dist/session-log.d.ts.map +1 -1
- package/dist/session-panel.d.ts +13 -3
- package/dist/session-panel.d.ts.map +1 -1
- package/dist/theme/color.d.ts +114 -0
- package/dist/theme/color.d.ts.map +1 -0
- package/dist/theme/derive.d.ts +92 -0
- package/dist/theme/derive.d.ts.map +1 -0
- package/dist/theme/index.d.ts +10 -0
- package/dist/theme/index.d.ts.map +1 -0
- package/dist/turn-order.d.ts +106 -0
- package/dist/turn-order.d.ts.map +1 -0
- package/dist/use-chat-session.d.ts +146 -17
- package/dist/use-chat-session.d.ts.map +1 -1
- package/dist/use-voice-session.d.ts +110 -4
- package/dist/use-voice-session.d.ts.map +1 -1
- package/dist/voice-widget.d.ts +114 -24
- package/dist/voice-widget.d.ts.map +1 -1
- package/dist/widget-cards.d.ts +28 -1
- package/dist/widget-cards.d.ts.map +1 -1
- package/dist/widget.css +1 -1
- package/package.json +4 -4
- package/src/styles/concierge.css +803 -28
- package/src/styles/tokens.css +67 -0
- package/dist/chunks/chat-DfajYOmN.js +0 -240
- package/dist/chunks/host-widget-C9EyGeiN.js +0 -9745
- package/dist/concierge-launcher.d.ts +0 -53
- package/dist/concierge-launcher.d.ts.map +0 -1
- package/dist/concierge-shell.d.ts +0 -256
- package/dist/concierge-shell.d.ts.map +0 -1
- package/dist/position.d.ts +0 -65
- package/dist/position.d.ts.map +0 -1
- package/dist/transcript-geometry.d.ts +0 -220
- package/dist/transcript-geometry.d.ts.map +0 -1
|
@@ -1,6 +1,5 @@
|
|
|
1
1
|
import type { VisitorEventCollector } from '@saar-ai/widget-bridge';
|
|
2
|
-
import type { WidgetChatReport } from '@saar-ai/widget-protocol/chat';
|
|
3
|
-
import { type ConciergePosition } from './position.js';
|
|
2
|
+
import type { WidgetChatCart, WidgetChatReport } from '@saar-ai/widget-protocol/chat';
|
|
4
3
|
/**
|
|
5
4
|
* Text chat transport for the end-user widget: boots a session, sends typed
|
|
6
5
|
* turns over `POST /widget/chat` (SSE), and receives a human desk reply over
|
|
@@ -153,6 +152,22 @@ export interface ChatCards {
|
|
|
153
152
|
readonly curationId?: string;
|
|
154
153
|
readonly items: readonly ChatCardItem[];
|
|
155
154
|
}
|
|
155
|
+
/**
|
|
156
|
+
* The concierge asking the WIDGET to put one item in the shopper's cart —
|
|
157
|
+
* `add_to_cart` (the concierge tool) as it arrives on the typed leg, an
|
|
158
|
+
* `add-to-cart` SSE frame.
|
|
159
|
+
*
|
|
160
|
+
* An ENVELOPE around the card rather than the bare card, so the identity a
|
|
161
|
+
* consumer dedupes on belongs to the REQUEST and not to a product: two adds of
|
|
162
|
+
* the same item are two requests, and the widget must perform both.
|
|
163
|
+
*
|
|
164
|
+
* There is deliberately no quantity, here or on the wire — the widget's add
|
|
165
|
+
* path adds exactly one unit, so a second unit is a second event (see
|
|
166
|
+
* `@saar-ai/widget-protocol`'s `WidgetChatAddToCartEventSchema`).
|
|
167
|
+
*/
|
|
168
|
+
export interface ChatCartAdd {
|
|
169
|
+
readonly item: ChatCardItem;
|
|
170
|
+
}
|
|
156
171
|
/**
|
|
157
172
|
* A real Shopify checkout handoff the `checkout_handoff` concierge tool
|
|
158
173
|
* produced — `url` is a server-built permalink (see `apps/api/src/catalog/
|
|
@@ -309,19 +324,46 @@ export interface WidgetEventInput {
|
|
|
309
324
|
}
|
|
310
325
|
export interface UseChatSessionResult {
|
|
311
326
|
readonly turns: readonly ChatTurn[];
|
|
312
|
-
/**
|
|
313
|
-
* How the tenant configured the COLLAPSED widget — label and starting
|
|
314
|
-
* anchor. Empty until the session boots; see `WidgetLauncherConfig`.
|
|
315
|
-
*/
|
|
316
|
-
readonly launcher: WidgetLauncherConfig;
|
|
317
327
|
/** Every `cards` event received this session, oldest first. */
|
|
318
328
|
readonly cards: readonly ChatCards[];
|
|
319
329
|
/** Every `checkout` event received this session, oldest first — see `checkout_handoff` (the concierge tool). */
|
|
320
330
|
readonly checkoutHandoffs: readonly ChatCheckoutHandoff[];
|
|
331
|
+
/**
|
|
332
|
+
* Every `add-to-cart` event received this session, oldest first — the
|
|
333
|
+
* concierge asking the WIDGET to put an item in the shopper's cart because
|
|
334
|
+
* the shopper asked for it in words (`add_to_cart`, the concierge tool).
|
|
335
|
+
*
|
|
336
|
+
* This hook only COLLECTS them; it never adds anything itself, because the
|
|
337
|
+
* cart lives behind a `HostBridge` this hook has no handle on.
|
|
338
|
+
* `ConciergeWidget` (`host-widget.tsx`) is the consumer, and it must consume
|
|
339
|
+
* these **by object identity** — see its effect's doc comment, and
|
|
340
|
+
* `AGENTS.md` → "Consuming an agent-requested add". Each entry is a distinct
|
|
341
|
+
* object, one per SSE frame, which is what makes "have I already added THIS
|
|
342
|
+
* one" exact across re-renders.
|
|
343
|
+
*/
|
|
344
|
+
readonly cartAdds: readonly ChatCartAdd[];
|
|
321
345
|
readonly status: ChatStatus;
|
|
322
346
|
readonly error?: string;
|
|
323
347
|
/** `true` once `POST /widget/session` has resolved (success or failure). */
|
|
324
348
|
readonly ready: boolean;
|
|
349
|
+
/**
|
|
350
|
+
* The widget is picking a conversation back up, rather than starting one —
|
|
351
|
+
* DOCK_SPEC §8.6's `dock_still_here`.
|
|
352
|
+
*
|
|
353
|
+
* `true` only while the FIRST boot is in flight AND this browser already
|
|
354
|
+
* held a visitor identity, which is what makes the distinction honest: a
|
|
355
|
+
* shopper who has never spoken to this concierge is not "still here", and
|
|
356
|
+
* telling them so would be a claim about a conversation that does not
|
|
357
|
+
* exist. A returning one — the second page of the same visit, the most-seen
|
|
358
|
+
* case on a conventionally navigating storefront — gets a row that says the
|
|
359
|
+
* concierge is still there for the length of one round trip, instead of a
|
|
360
|
+
* spinner or an empty greeting that reads as having been forgotten.
|
|
361
|
+
*
|
|
362
|
+
* It is deliberately NOT the boot response's own `resumed` flag: that only
|
|
363
|
+
* arrives once the boot has resolved, which is exactly when this state is
|
|
364
|
+
* over.
|
|
365
|
+
*/
|
|
366
|
+
readonly resuming: boolean;
|
|
325
367
|
/**
|
|
326
368
|
* The widget socket's live state — see `ChatConnectionState`'s doc
|
|
327
369
|
* comment. Stays `'idle'` for the lifetime of the session when no
|
|
@@ -330,6 +372,14 @@ export interface UseChatSessionResult {
|
|
|
330
372
|
* "syncing" indicator.
|
|
331
373
|
*/
|
|
332
374
|
readonly connection: ChatConnectionState;
|
|
375
|
+
/**
|
|
376
|
+
* A HUMAN operator is composing a reply right now — driven by the desk
|
|
377
|
+
* socket's `desk:typing` pings, expiring `DESK_TYPING_INDICATOR_TTL_MS` (`@saar-ai/widget-protocol/desk-typing`) after
|
|
378
|
+
* the last one and cleared the moment their message actually arrives.
|
|
379
|
+
* Always `false` without a connected socket: the poll transport has no
|
|
380
|
+
* typing signal, and a stale "someone is typing" is worse than none.
|
|
381
|
+
*/
|
|
382
|
+
readonly deskTyping: boolean;
|
|
333
383
|
/**
|
|
334
384
|
* Which channels the tenant's published widget config enables —
|
|
335
385
|
* `StartWidgetSessionResult.modalities` (`apps/api/src/widget/
|
|
@@ -401,6 +451,73 @@ export interface UseChatSessionResult {
|
|
|
401
451
|
* cross-verifying it server-side is deliberately out of scope.
|
|
402
452
|
*/
|
|
403
453
|
readonly sendReport: (report: WidgetChatReport) => Promise<boolean>;
|
|
454
|
+
/**
|
|
455
|
+
* Tell this hook what the shopper's basket currently is, so that every
|
|
456
|
+
* later turn carries it to the concierge as context.
|
|
457
|
+
*
|
|
458
|
+
* ## Why a setter and not an option
|
|
459
|
+
*
|
|
460
|
+
* The basket is assembled by `ConciergeWidget`, which is the SAME component
|
|
461
|
+
* that calls this hook — so it cannot be passed in as an option (the cart
|
|
462
|
+
* does not exist yet when the hook is constructed). A setter called from an
|
|
463
|
+
* effect closes that loop without a second source of truth: the widget goes
|
|
464
|
+
* on owning "what is in the basket" (`bridge.readCart()` merged with its own
|
|
465
|
+
* adds, by the ownership table in this package's `AGENTS.md`), and this hook
|
|
466
|
+
* only carries whatever it was last told.
|
|
467
|
+
*
|
|
468
|
+
* ## Why it is stored in a ref, not state
|
|
469
|
+
*
|
|
470
|
+
* Nothing renders from it. Holding it in state would re-render the whole
|
|
471
|
+
* transcript on every cart read, including the ones that change nothing.
|
|
472
|
+
*
|
|
473
|
+
* ## What is actually sent, and when
|
|
474
|
+
*
|
|
475
|
+
* The value is attached to the NEXT `POST /widget/chat` — a message or a
|
|
476
|
+
* report, both — and to no other request. That makes the cart the model
|
|
477
|
+
* reads the cart the widget held at the moment the shopper pressed send:
|
|
478
|
+
* atomic with the question, with no stored snapshot to go stale and nothing
|
|
479
|
+
* to expire. `null` clears it, which is how a widget says "I no longer know
|
|
480
|
+
* of a cart" rather than repeating a basket it can no longer see.
|
|
481
|
+
*
|
|
482
|
+
* ## Trust
|
|
483
|
+
*
|
|
484
|
+
* CLIENT-ASSERTED, exactly like {@link sendReport}'s report and no more:
|
|
485
|
+
* nothing verifies it, and the server does not persist it — see
|
|
486
|
+
* `WidgetChatCartSchema` (`@saar-ai/widget-protocol`) and
|
|
487
|
+
* `WidgetChatInput.cart` (`apps/api`) for the full posture.
|
|
488
|
+
*/
|
|
489
|
+
readonly setCart: (cart: WidgetChatCart | null) => void;
|
|
490
|
+
/**
|
|
491
|
+
* `POST /widget/cart` — push the basket so a live VOICE CALL can answer a
|
|
492
|
+
* question about it.
|
|
493
|
+
*
|
|
494
|
+
* ## Why {@link setCart} is not enough
|
|
495
|
+
*
|
|
496
|
+
* `setCart` attaches the basket to the next chat REQUEST, which is exactly
|
|
497
|
+
* right for a typed turn and reaches a call not at all: a caller asks out
|
|
498
|
+
* loud, the turn is assembled by the agent tier, and nothing on that path
|
|
499
|
+
* has been near this browser. So while a call is live the basket has to be
|
|
500
|
+
* pushed rather than carried, and the agent tier reads the pushed snapshot
|
|
501
|
+
* on every turn.
|
|
502
|
+
*
|
|
503
|
+
* ## Called when the basket CHANGES, not on a timer
|
|
504
|
+
*
|
|
505
|
+
* A poll would be a request per interval whether or not anything moved, and
|
|
506
|
+
* would still be stale in between. `ConciergeWidget` already recomputes the
|
|
507
|
+
* basket whenever it changes — a card add, a bridge re-read, an add the
|
|
508
|
+
* CONCIERGE itself asked for — so the change is the signal, and the same
|
|
509
|
+
* `chatCart` value that feeds `setCart` feeds this.
|
|
510
|
+
*
|
|
511
|
+
* ## Trust and cost
|
|
512
|
+
*
|
|
513
|
+
* CLIENT-ASSERTED, exactly like {@link setCart}, and nothing is persisted:
|
|
514
|
+
* the server writes a bounded blob with a TTL for the turn tier to read.
|
|
515
|
+
* Resolves `false` (never throws) with no session or on any failure — a
|
|
516
|
+
* push that did not land leaves the previously pushed basket standing and
|
|
517
|
+
* costs the call a grounded answer, which is not worth telling the shopper
|
|
518
|
+
* about.
|
|
519
|
+
*/
|
|
520
|
+
readonly pushCart: (cart: WidgetChatCart) => Promise<boolean>;
|
|
404
521
|
/**
|
|
405
522
|
* `POST /widget/event` with the session's chatToken. Resolves `false` (never
|
|
406
523
|
* throws) with no session or on a network/HTTP failure — browsing telemetry
|
|
@@ -408,6 +525,28 @@ export interface UseChatSessionResult {
|
|
|
408
525
|
* storefront error the visitor sees.
|
|
409
526
|
*/
|
|
410
527
|
readonly sendEvent: (events: readonly WidgetEventInput[]) => Promise<boolean>;
|
|
528
|
+
/**
|
|
529
|
+
* "The shopper is typing" — `POST /widget/typing` with the session's
|
|
530
|
+
* chatToken, relayed to whichever operator is watching this conversation.
|
|
531
|
+
* The mirror of {@link deskTyping}, pointed the other way.
|
|
532
|
+
*
|
|
533
|
+
* Call it on EVERY keystroke: it is leading-edge throttled internally to one
|
|
534
|
+
* request per `SHOPPER_TYPING_PING_INTERVAL_MS`
|
|
535
|
+
* (`@saar-ai/widget-protocol/desk-typing`), so a paragraph costs a handful
|
|
536
|
+
* of requests, not one per character. No timers are armed, so there is
|
|
537
|
+
* nothing to clean up and no trailing request after the shopper stops.
|
|
538
|
+
*
|
|
539
|
+
* Fire-and-forget and synchronous by design — it returns `void`, not a
|
|
540
|
+
* promise, precisely so no caller can be tempted to await a keystroke, and
|
|
541
|
+
* every failure (no session yet, offline, a 4xx) is swallowed. A hint that
|
|
542
|
+
* did not land costs an operator an animation; surfacing it would cost the
|
|
543
|
+
* shopper an error toast over one.
|
|
544
|
+
*
|
|
545
|
+
* The draft itself never leaves the browser: there is no body and no
|
|
546
|
+
* parameter to put one in — see `apps/api/src/widget/widget-chat.controller.ts`'s
|
|
547
|
+
* `typing()` for the server half of that promise.
|
|
548
|
+
*/
|
|
549
|
+
readonly notifyTyping: () => void;
|
|
411
550
|
/**
|
|
412
551
|
* The add-to-cart-time attribution token the SERVER established
|
|
413
552
|
* (`CheckoutHandoffService.recordCartAdd`), surfaced here the moment a
|
|
@@ -471,15 +610,5 @@ export interface UseChatSessionResult {
|
|
|
471
610
|
*/
|
|
472
611
|
readonly markHandoffToHuman: () => void;
|
|
473
612
|
}
|
|
474
|
-
/** What the collapsed widget shows, as the tenant configured it. */
|
|
475
|
-
export interface WidgetLauncherConfig {
|
|
476
|
-
readonly label?: string;
|
|
477
|
-
readonly position?: ConciergePosition;
|
|
478
|
-
/**
|
|
479
|
-
* May a visitor move it? Resolved by the control tier, so `undefined` here
|
|
480
|
-
* means only "the session has not booted yet" — never "we could not decide".
|
|
481
|
-
*/
|
|
482
|
-
readonly draggable?: boolean;
|
|
483
|
-
}
|
|
484
613
|
export declare function useChatSession(options: UseChatSessionOptions): UseChatSessionResult;
|
|
485
614
|
//# sourceMappingURL=use-chat-session.d.ts.map
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"use-chat-session.d.ts","sourceRoot":"","sources":["../src/use-chat-session.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,wBAAwB,CAAC;AAQpE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,+BAA+B,CAAC;
|
|
1
|
+
{"version":3,"file":"use-chat-session.d.ts","sourceRoot":"","sources":["../src/use-chat-session.ts"],"names":[],"mappings":"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"}
|
|
@@ -3,7 +3,7 @@ import type { SessionConfigPayload, TranscriptPayload, TurnCostPayload, TurnLate
|
|
|
3
3
|
import type { SessionTuning } from '@saar-ai/widget-protocol/tuning';
|
|
4
4
|
import type { WidgetToolEvent } from '@saar-ai/widget-protocol/chat';
|
|
5
5
|
import { type SessionLogEntry } from './session-log.js';
|
|
6
|
-
import { type VoicePhase } from './voice-session-state.js';
|
|
6
|
+
import { type VoicePhase, type VoiceSessionSnapshot } from './voice-session-state.js';
|
|
7
7
|
/**
|
|
8
8
|
* The widget's live call: token → room → microphone → the avatar's state.
|
|
9
9
|
*
|
|
@@ -122,6 +122,8 @@ declare function loadVoiceProtocol(): Promise<{
|
|
|
122
122
|
decodeTelemetry: typeof import("@saar-ai/widget-protocol/telemetry").decodeTelemetry;
|
|
123
123
|
encodeCallerText: typeof import("@saar-ai/widget-protocol/telemetry").encodeCallerText;
|
|
124
124
|
VOICE_CALLER_TEXT_TOPIC: string;
|
|
125
|
+
encodeCallerControl: typeof import("@saar-ai/widget-protocol/telemetry").encodeCallerControl;
|
|
126
|
+
VOICE_CALLER_CONTROL_TOPIC: string;
|
|
125
127
|
WidgetToolEventSchema: import("zod").ZodDiscriminatedUnion<[import("zod").ZodObject<{
|
|
126
128
|
type: import("zod").ZodLiteral<"cards">;
|
|
127
129
|
curationId: import("zod").ZodOptional<import("zod").ZodString>;
|
|
@@ -144,9 +146,33 @@ declare function loadVoiceProtocol(): Promise<{
|
|
|
144
146
|
handoffId: import("zod").ZodString;
|
|
145
147
|
url: import("zod").ZodURL;
|
|
146
148
|
itemCount: import("zod").ZodNumber;
|
|
149
|
+
}, import("zod/v4/core").$strip>, import("zod").ZodObject<{
|
|
150
|
+
type: import("zod").ZodLiteral<"add-to-cart">;
|
|
151
|
+
item: import("zod").ZodObject<{
|
|
152
|
+
productId: import("zod").ZodString;
|
|
153
|
+
variantId: import("zod").ZodOptional<import("zod").ZodString>;
|
|
154
|
+
platformVariantId: import("zod").ZodOptional<import("zod").ZodString>;
|
|
155
|
+
title: import("zod").ZodString;
|
|
156
|
+
imageUrl: import("zod").ZodOptional<import("zod").ZodURL>;
|
|
157
|
+
handle: import("zod").ZodOptional<import("zod").ZodString>;
|
|
158
|
+
priceMinor: import("zod").ZodNumber;
|
|
159
|
+
currency: import("zod").ZodString;
|
|
160
|
+
available: import("zod").ZodBoolean;
|
|
161
|
+
reason: import("zod").ZodOptional<import("zod").ZodString>;
|
|
162
|
+
}, import("zod/v4/core").$strip>;
|
|
147
163
|
}, import("zod/v4/core").$strip>], "type">;
|
|
148
164
|
}>;
|
|
149
165
|
export type VoiceProtocol = Awaited<ReturnType<typeof loadVoiceProtocol>>;
|
|
166
|
+
/**
|
|
167
|
+
* Why the shopper cut the agent off, when they did it without speaking.
|
|
168
|
+
*
|
|
169
|
+
* The same three `@saar-ai/widget-protocol/telemetry`'s
|
|
170
|
+
* `CALLER_INTERRUPT_REASONS` names, and `apps/voice`'s `handleCallerControl`
|
|
171
|
+
* records on the turn: `'look'` is §5.1's duck (the shopper turned to the
|
|
172
|
+
* page), `'tap'` the explicit interrupt control, `'keyboard'` a switch to
|
|
173
|
+
* text mid-reply.
|
|
174
|
+
*/
|
|
175
|
+
export type CallerInterruptReason = 'look' | 'tap' | 'keyboard';
|
|
150
176
|
/**
|
|
151
177
|
* `RoomEvent` values, as literals.
|
|
152
178
|
*
|
|
@@ -179,6 +205,22 @@ export interface UseVoiceSessionOptions {
|
|
|
179
205
|
*/
|
|
180
206
|
loadProtocol?: () => Promise<VoiceProtocol>;
|
|
181
207
|
}
|
|
208
|
+
/**
|
|
209
|
+
* One tool event, plus the turn it belongs to.
|
|
210
|
+
*
|
|
211
|
+
* `turnId` rides the telemetry ENVELOPE beside `event`, never inside it: the
|
|
212
|
+
* event's schema belongs to `@saar-ai/widget-protocol/chat` and knows nothing
|
|
213
|
+
* about turns, while the turn is a fact about the conversation. Lifting it
|
|
214
|
+
* here is what lets the mounter draw a curation UNDER the line that introduced
|
|
215
|
+
* it instead of merging it in by arrival time — see `host-widget.tsx`.
|
|
216
|
+
*
|
|
217
|
+
* Optional, and stays optional. An agent that predates the stamp, or a
|
|
218
|
+
* curation raised outside any turn, sends the frame without one; the mounter
|
|
219
|
+
* falls back to arrival order rather than dropping the cards.
|
|
220
|
+
*/
|
|
221
|
+
export type VoiceWidgetEvent = WidgetToolEvent & {
|
|
222
|
+
readonly turnId?: string;
|
|
223
|
+
};
|
|
182
224
|
export interface VoiceSession {
|
|
183
225
|
/**
|
|
184
226
|
* What the concierge's TOOLS put on screen this call, oldest first.
|
|
@@ -188,9 +230,22 @@ export interface VoiceSession {
|
|
|
188
230
|
* beside the transcript — the same split as everything else here: this hook
|
|
189
231
|
* owns the call, the mounter owns the screen.
|
|
190
232
|
*/
|
|
191
|
-
readonly widgetEvents: readonly
|
|
233
|
+
readonly widgetEvents: readonly VoiceWidgetEvent[];
|
|
192
234
|
/** What the avatar should render. */
|
|
193
235
|
readonly state: BotState;
|
|
236
|
+
/**
|
|
237
|
+
* The raw call snapshot `state` is collapsed FROM — see
|
|
238
|
+
* `voice-session-state.ts`.
|
|
239
|
+
*
|
|
240
|
+
* Published because `BotState`'s four values cannot express DOCK_SPEC
|
|
241
|
+
* §5.1's nine: `botStateFor` returns `listening` both for "the caller is
|
|
242
|
+
* speaking right now" and for "the room is live and quiet", and the dock
|
|
243
|
+
* needs to tell those apart (a duck resumes on SPEECH, so a quiet room that
|
|
244
|
+
* reads as speech would resume the moment it paused). `state` stays the
|
|
245
|
+
* four-value answer every existing consumer reads; this is the fuller one
|
|
246
|
+
* beside it, not a replacement.
|
|
247
|
+
*/
|
|
248
|
+
readonly snapshot: VoiceSessionSnapshot;
|
|
194
249
|
readonly phase: VoicePhase;
|
|
195
250
|
readonly micOpen: boolean;
|
|
196
251
|
/**
|
|
@@ -206,8 +261,21 @@ export interface VoiceSession {
|
|
|
206
261
|
readonly error: string | null;
|
|
207
262
|
/** Timestamped account of the call, oldest first. */
|
|
208
263
|
readonly events: readonly SessionLogEntry[];
|
|
209
|
-
/**
|
|
210
|
-
|
|
264
|
+
/**
|
|
265
|
+
* 0..1 RMS of the agent's incoming audio — proof that sound is arriving.
|
|
266
|
+
*
|
|
267
|
+
* A LIVE REF, not a number, and that is DOCK_SPEC §7.1 rule 5, not a style
|
|
268
|
+
* preference: the analyser produces a new value on every animation frame,
|
|
269
|
+
* and a number here means `setState` sixty times a second, which re-renders
|
|
270
|
+
* every consumer of this hook — the whole dock included — for a value that
|
|
271
|
+
* only ever ends up in a CSS custom property. Read `.current` inside your
|
|
272
|
+
* own `requestAnimationFrame` and write it straight to the DOM; never put it
|
|
273
|
+
* in state, and never list it in a dependency array (the object identity is
|
|
274
|
+
* stable for the life of the hook, so it would never fire anyway).
|
|
275
|
+
*/
|
|
276
|
+
readonly agentLevelRef: {
|
|
277
|
+
readonly current: number;
|
|
278
|
+
};
|
|
211
279
|
/** Per-turn latency, newest last, as the worker measured it. */
|
|
212
280
|
readonly turns: readonly TurnLatencyPayload[];
|
|
213
281
|
/** The conversation as it settles. */
|
|
@@ -228,6 +296,44 @@ export interface VoiceSession {
|
|
|
228
296
|
toggleMic(): Promise<void>;
|
|
229
297
|
/** Send a typed turn. Resolves false when the room cannot carry one. */
|
|
230
298
|
sendText(text: string): Promise<boolean>;
|
|
299
|
+
/**
|
|
300
|
+
* DOCK_SPEC §5.2 — tell the worker the caller's utterance ENDED, because
|
|
301
|
+
* the browser knows: a hold-to-talk press bounds the first utterance by the
|
|
302
|
+
* gesture, so the endpointer does not have to find the boundary itself.
|
|
303
|
+
*
|
|
304
|
+
* Advisory in both directions. Resolves `false` when the room cannot carry
|
|
305
|
+
* it (no call, no data channel), and a worker that has never heard of the
|
|
306
|
+
* topic ignores it — which is exactly the state of the world between this
|
|
307
|
+
* change and PR 5, and is why the dock still mutes on release regardless.
|
|
308
|
+
*/
|
|
309
|
+
sendEouHint(): Promise<boolean>;
|
|
310
|
+
/**
|
|
311
|
+
* DOCK_SPEC §5.1 — the shopper is back after a duck, by speaking or by
|
|
312
|
+
* tapping the microphone. Never a timer, at either end.
|
|
313
|
+
*
|
|
314
|
+
* The other half of `interrupt('look')`: that frame left the worker holding
|
|
315
|
+
* a cancelled turn and deliberately silent, and this is what tells it the
|
|
316
|
+
* shopper is listening again. Same "resolves false rather than throwing"
|
|
317
|
+
* contract as `sendText`.
|
|
318
|
+
*/
|
|
319
|
+
sendResume(): Promise<boolean>;
|
|
320
|
+
/**
|
|
321
|
+
* DOCK_SPEC §5.1/§5.5 — a barge-in the CLIENT initiated, carrying WHY.
|
|
322
|
+
*
|
|
323
|
+
* `'look'` is the shopper turning to the merchant's page (a scroll past
|
|
324
|
+
* 24 px, a tap outside the dock, a bridge page change): §5.1's "Paused
|
|
325
|
+
* while you look" is implemented as this, through the existing cancel path
|
|
326
|
+
* and `AbandonmentTracker`, rather than as a new pause primitive.
|
|
327
|
+
* `'tap'` is a deliberate press on the interrupt control (or on the row
|
|
328
|
+
* while the agent is speaking), `'keyboard'` a switch to text mid-reply.
|
|
329
|
+
*
|
|
330
|
+
* The reason is what lets an operator's console tell a shopper who was
|
|
331
|
+
* READING from one who talked over the agent — see the enum's own comment
|
|
332
|
+
* in `@saar-ai/widget-protocol/telemetry`.
|
|
333
|
+
*
|
|
334
|
+
* Same "resolves false rather than throwing" contract as `sendText`.
|
|
335
|
+
*/
|
|
336
|
+
interrupt(reason: CallerInterruptReason): Promise<boolean>;
|
|
231
337
|
}
|
|
232
338
|
export interface WidgetVoiceTokenFetcherOptions {
|
|
233
339
|
/**
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"use-voice-session.d.ts","sourceRoot":"","sources":["../src/use-voice-session.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAC/C,OAAO,KAAK,EACV,oBAAoB,EACpB,iBAAiB,EACjB,eAAe,EACf,kBAAkB,EACnB,MAAM,oCAAoC,CAAC;AAC5C,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,iCAAiC,CAAC;AACrE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,+BAA+B,CAAC;AAErE,OAAO,EAAqC,KAAK,eAAe,EAAE,MAAM,kBAAkB,CAAC;AAC3F,OAAO,EAGL,KAAK,UAAU,
|
|
1
|
+
{"version":3,"file":"use-voice-session.d.ts","sourceRoot":"","sources":["../src/use-voice-session.ts"],"names":[],"mappings":"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"}
|
package/dist/voice-widget.d.ts
CHANGED
|
@@ -1,7 +1,17 @@
|
|
|
1
1
|
import { type CSSProperties } from 'react';
|
|
2
2
|
import { type WidgetMessages } from './messages.js';
|
|
3
|
-
import { type
|
|
4
|
-
|
|
3
|
+
import { type DockProps, type WidgetAttribution } from './dock/dock.js';
|
|
4
|
+
/**
|
|
5
|
+
* Where a call is, from the caller's point of view.
|
|
6
|
+
*
|
|
7
|
+
* Moved here from the retired `concierge-shell.tsx`, name unchanged: it is
|
|
8
|
+
* `host-widget.tsx`'s `deriveCallPhase` output and this package's published
|
|
9
|
+
* surface, and the vocabulary did not change with the chrome. The dock reads
|
|
10
|
+
* it alongside `state` to fill in DOCK_SPEC §5.1's `connecting` and
|
|
11
|
+
* `mic_blocked`, which `BotState`'s four values cannot express.
|
|
12
|
+
*/
|
|
13
|
+
export type ConciergeCallPhase = 'idle' | 'connecting' | 'waiting' | 'live' | 'blocked';
|
|
14
|
+
export type { WidgetAttribution };
|
|
5
15
|
import type { BotState } from './bot-state.js';
|
|
6
16
|
import type { WidgetAvatar } from './avatar.js';
|
|
7
17
|
import type { ChatAttachment, ChatCardItem, ChatCards, ChatTurnDelivery, ChatTurnEvent } from './use-chat-session.js';
|
|
@@ -29,7 +39,16 @@ export interface WidgetTurn {
|
|
|
29
39
|
readonly locale: string;
|
|
30
40
|
/** `false` while the recognizer may still revise it. */
|
|
31
41
|
readonly final?: boolean;
|
|
32
|
-
/**
|
|
42
|
+
/**
|
|
43
|
+
* Product cards the agent attached to this turn, drawn directly under its
|
|
44
|
+
* bubble.
|
|
45
|
+
*
|
|
46
|
+
* Both legs reach here now. The typed leg attaches its `cards` SSE event
|
|
47
|
+
* onto the live agent turn (`use-chat-session.ts`); the spoken leg's
|
|
48
|
+
* curations arrive as their own `widget.event` frames and are folded onto
|
|
49
|
+
* the matching transcript line by `turnId` (`host-widget.tsx`'s merge memo,
|
|
50
|
+
* which also explains what happens to one that finds no line).
|
|
51
|
+
*/
|
|
33
52
|
readonly cards?: ChatCards;
|
|
34
53
|
/** Files carried on this turn, either direction — text mode only. */
|
|
35
54
|
readonly attachments?: readonly ChatAttachment[];
|
|
@@ -60,11 +79,21 @@ export interface VoiceWidgetProps {
|
|
|
60
79
|
readonly onSendText: (text: string) => Promise<boolean> | boolean;
|
|
61
80
|
/** Whether the caller's microphone is currently open. */
|
|
62
81
|
readonly micOpen: boolean;
|
|
63
|
-
/**
|
|
64
|
-
readonly open: boolean;
|
|
65
|
-
readonly onOpenChange: (open: boolean) => void;
|
|
66
|
-
/** Shown under the header — `connecting`, an error, whatever the host knows. */
|
|
82
|
+
/** §5.1's `error` — a broken conversation, or a broken voice leg. */
|
|
67
83
|
readonly status?: string;
|
|
84
|
+
/** Which of the two `status` came from — see `DockProps.statusKind`. */
|
|
85
|
+
readonly statusKind?: 'session' | 'voice';
|
|
86
|
+
/**
|
|
87
|
+
* A line the shopper needs to READ that is not an error — today, only
|
|
88
|
+
* `cart_add_failed`.
|
|
89
|
+
*
|
|
90
|
+
* Split OUT of `status`, and the split is the whole point: as a status it
|
|
91
|
+
* became §5.1's `error`, which took `speaking` down to a keyboard-only row
|
|
92
|
+
* for the rest of the session — the clause gone, mute and interrupt with it,
|
|
93
|
+
* while the agent kept talking. §5.1 asks for `cart_add_failed` in the
|
|
94
|
+
* caption; a notice is exactly that and nothing more.
|
|
95
|
+
*/
|
|
96
|
+
readonly notice?: string;
|
|
68
97
|
/**
|
|
69
98
|
* `'voice'` (the default) shows the microphone alongside the text box, as
|
|
70
99
|
* documented below under "Voice and text are one conversation". `'text'`
|
|
@@ -75,6 +104,33 @@ export interface VoiceWidgetProps {
|
|
|
75
104
|
readonly mode?: WidgetMode;
|
|
76
105
|
/** Shows the "a human will pick this up" banner once the conversation escalates. */
|
|
77
106
|
readonly escalated?: boolean;
|
|
107
|
+
/**
|
|
108
|
+
* A HUMAN operator is composing a reply right now (the desk socket's
|
|
109
|
+
* `desk:typing` pings — see `UseChatSessionResult.deskTyping`). Draws the
|
|
110
|
+
* same typing-dots bubble a still-streaming agent turn gets, pinned after
|
|
111
|
+
* the last turn, so the shopper waiting on a human sees the person is
|
|
112
|
+
* there. Distinct from the model's own dots, which ride on an OPEN agent
|
|
113
|
+
* turn — a human composing has no turn to ride on until they press send.
|
|
114
|
+
*/
|
|
115
|
+
readonly humanTyping?: boolean;
|
|
116
|
+
/**
|
|
117
|
+
* The shopper is typing — called on every keystroke that leaves a NON-EMPTY
|
|
118
|
+
* draft. The mirror of {@link humanTyping}, pointed the other way: it is
|
|
119
|
+
* what puts "…is typing" beside this conversation in the operator console.
|
|
120
|
+
*
|
|
121
|
+
* Called raw, once per keystroke, with no throttling here on purpose. The
|
|
122
|
+
* cadence is a wire contract shared with the server
|
|
123
|
+
* (`SHOPPER_TYPING_PING_INTERVAL_MS`) and is enforced where the request is
|
|
124
|
+
* actually made (`useChatSession.notifyTyping`); a second throttle in this
|
|
125
|
+
* component would be a second thing to retune and a second way for the two
|
|
126
|
+
* to disagree.
|
|
127
|
+
*
|
|
128
|
+
* Deliberately NOT called when a keystroke empties the field: backspacing to
|
|
129
|
+
* blank is a shopper abandoning the message, and it is the one keystroke
|
|
130
|
+
* where "they are typing" is actively misleading. Omitted entirely ⇒ nothing
|
|
131
|
+
* is ever reported, same "additive per caller" posture as `onAddToCart`.
|
|
132
|
+
*/
|
|
133
|
+
readonly onTyping?: () => void;
|
|
78
134
|
/** Forwarded to every product card's "Add to cart" button, text mode only. */
|
|
79
135
|
readonly onAddToCart?: (item: ChatCardItem) => void;
|
|
80
136
|
/**
|
|
@@ -99,15 +155,6 @@ export interface VoiceWidgetProps {
|
|
|
99
155
|
* ⇒ no summary ever renders — same "additive per caller" posture as
|
|
100
156
|
* `onAddToCart`, so a host with no cart (the preview harness) is unaffected.
|
|
101
157
|
*/
|
|
102
|
-
/**
|
|
103
|
-
* The tenant's own words on the collapsed launcher, from their widget
|
|
104
|
-
* config. Absent renders the mascot alone rather than a phrase we invented.
|
|
105
|
-
*/
|
|
106
|
-
readonly launcherLabel?: string;
|
|
107
|
-
/** Where the launcher sits. Defaults to the shell's own bottom-centre. */
|
|
108
|
-
readonly position?: ConciergePosition;
|
|
109
|
-
/** Absent ⇒ a visitor cannot move the widget, and no grip is drawn. */
|
|
110
|
-
readonly onPositionChange?: (position: ConciergePosition) => void;
|
|
111
158
|
readonly cart?: {
|
|
112
159
|
readonly lines: readonly WidgetCartLine[];
|
|
113
160
|
readonly subtotalMinor: number;
|
|
@@ -143,11 +190,30 @@ export interface VoiceWidgetProps {
|
|
|
143
190
|
*/
|
|
144
191
|
readonly avatar?: WidgetAvatar;
|
|
145
192
|
/**
|
|
146
|
-
* Forwarded straight through to
|
|
147
|
-
*
|
|
148
|
-
*
|
|
193
|
+
* Forwarded straight through to the dock's own `attribution` prop — see
|
|
194
|
+
* that prop's doc comment for why this package never resolves it itself.
|
|
195
|
+
* Absent ⇒ no attribution link renders.
|
|
149
196
|
*/
|
|
150
197
|
readonly attribution?: WidgetAttribution;
|
|
198
|
+
/**
|
|
199
|
+
* Everything the DOCK needs that this component does not decide — the
|
|
200
|
+
* tenant's identity, colours, type, layout and copy (DOCK_SPEC §9.1), the
|
|
201
|
+
* §4.2 handover payload, the §5.6 proactive line, and the finer voice
|
|
202
|
+
* snapshot §5.1 needs.
|
|
203
|
+
*
|
|
204
|
+
* It is a PASS-THROUGH rather than a widened prop list, and the split is
|
|
205
|
+
* the same one this file has always kept: this component owns the
|
|
206
|
+
* CONVERSATION (turns, the composer, the basket, the openers) and knows
|
|
207
|
+
* nothing about a tenant's brand or a CDN handover; `host-widget.tsx` owns
|
|
208
|
+
* the session and knows both. Spread BEFORE this component's own props, so
|
|
209
|
+
* a host can supply a better `voice` snapshot (it has one — `useVoiceSession`
|
|
210
|
+
* publishes `snapshot`) without being able to take the composer away.
|
|
211
|
+
*
|
|
212
|
+
* Absent ⇒ the dock renders from `state`/`callPhase`/`micOpen` alone, which
|
|
213
|
+
* is exactly what a harness with no session (Storybook, the marketing
|
|
214
|
+
* preview) has.
|
|
215
|
+
*/
|
|
216
|
+
readonly dock?: Omit<DockProps, 'draft' | 'onDraftChange' | 'onSubmit' | 'transcript' | 'sheetExtra' | 'messages'>;
|
|
151
217
|
}
|
|
152
218
|
/**
|
|
153
219
|
* Does this line read as "I want to pay now"?
|
|
@@ -165,24 +231,48 @@ export interface VoiceWidgetProps {
|
|
|
165
231
|
*/
|
|
166
232
|
export declare function readsAsCheckoutIntent(text: string): boolean;
|
|
167
233
|
/**
|
|
168
|
-
* Does this
|
|
234
|
+
* Does this line ask to SEE the basket — "show me my cart", "what's my
|
|
235
|
+
* total"?
|
|
236
|
+
*
|
|
237
|
+
* A separate read from {@link readsAsCheckoutIntent} because it is a
|
|
238
|
+
* different question with the same answer: the basket itself. Asking what is
|
|
239
|
+
* in the cart, or what it comes to, is answered by lines, prices and a
|
|
240
|
+
* running total — not by prose. Without this the concierge answered "show me
|
|
241
|
+
* my cart" as an ordinary question and TYPED the basket back as a bullet list
|
|
242
|
+
* with no prices at all, then refused the total, because the server's
|
|
243
|
+
* guardrails (rightly) forbid it from stating a price no tool grounded.
|
|
244
|
+
* Observed on the KH storefront.
|
|
245
|
+
*
|
|
246
|
+
* Wider than the checkout list on purpose: a false positive here shows a
|
|
247
|
+
* basket the shopper is already looking at the contents of, which costs
|
|
248
|
+
* nothing. Bare "how much" is deliberately absent — "how much is delivery?"
|
|
249
|
+
* is a question about a policy, not about the basket.
|
|
250
|
+
*/
|
|
251
|
+
export declare function readsAsCartViewIntent(text: string): boolean;
|
|
252
|
+
/**
|
|
253
|
+
* Does this thread, as it stands, want the basket on screen?
|
|
169
254
|
*
|
|
170
255
|
* The shopper's MOST RECENT line, not "any line ever": once they carry on
|
|
171
256
|
* shopping past the summary the basket should get out of the way again, and a
|
|
172
257
|
* sticky flag would leave it wedged at the bottom of every later answer.
|
|
173
258
|
*
|
|
259
|
+
* TWO intents, ONE answer. Asking to pay ({@link readsAsCheckoutIntent}) and
|
|
260
|
+
* asking to see the cart ({@link readsAsCartViewIntent}) are different
|
|
261
|
+
* questions that are both answered by rendering the basket, so they share a
|
|
262
|
+
* single read rather than two flags that could disagree about the same line.
|
|
263
|
+
*
|
|
174
264
|
* There is exactly ONE of these because two consumers ask the same question
|
|
175
265
|
* of the same transcript and must never disagree about the answer:
|
|
176
266
|
* `VoiceWidget` below draws the basket from it, and `ConciergeWidget`
|
|
177
267
|
* (`host-widget.tsx`) re-reads the HOST's cart from it, so the basket the
|
|
178
|
-
* shopper is
|
|
179
|
-
*
|
|
268
|
+
* shopper is looking at is the one that exists now. Two copies of the same
|
|
269
|
+
* `reverse().find()` is how those two quietly drift apart.
|
|
180
270
|
*
|
|
181
271
|
* Takes only what it reads, so a caller with its own merged turn shape (which
|
|
182
272
|
* `ConciergeWidget` has — typed turns plus spoken lines plus rendered cards)
|
|
183
273
|
* can pass it without conversion.
|
|
184
274
|
*/
|
|
185
|
-
export declare function
|
|
275
|
+
export declare function basketIntentFromTurns(turns: readonly Pick<WidgetTurn, 'speaker' | 'text'>[]): boolean;
|
|
186
276
|
/**
|
|
187
277
|
* The end-user agent widget: a launcher bubble that expands into a conversation
|
|
188
278
|
* with both a microphone and a text box.
|
|
@@ -211,5 +301,5 @@ export declare function checkoutIntentFromTurns(turns: readonly Pick<WidgetTurn,
|
|
|
211
301
|
* `dir`, resolved from that line's locale rather than inherited from the page —
|
|
212
302
|
* inheriting is what renders Arabic punctuation on the wrong end of a sentence.
|
|
213
303
|
*/
|
|
214
|
-
export declare function VoiceWidget({ state, turns, onToggleMic, onEndCall, callPhase, onSendText, micOpen,
|
|
304
|
+
export declare function VoiceWidget({ state, turns, onToggleMic, onEndCall, callPhase, onSendText, micOpen, status, statusKind, notice, mode, escalated, humanTyping, onTyping, onAddToCart, curationHref, productHref, onAttachFile, cart, messages, navigate, locale, skinStyle, avatar, attribution, dock, }: VoiceWidgetProps): import("react").JSX.Element;
|
|
215
305
|
//# sourceMappingURL=voice-widget.d.ts.map
|