@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,273 @@
1
+ import type { BotState } from './bot-state.js';
2
+ import type { SessionConfigPayload, TranscriptPayload, TurnCostPayload, TurnLatencyPayload } from '@saar-ai/widget-protocol/telemetry';
3
+ import type { SessionTuning } from '@saar-ai/widget-protocol/tuning';
4
+ import type { WidgetToolEvent } from '@saar-ai/widget-protocol/chat';
5
+ import { type SessionLogEntry } from './session-log.js';
6
+ import { type VoicePhase } from './voice-session-state.js';
7
+ /**
8
+ * The widget's live call: token → room → microphone → the avatar's state.
9
+ *
10
+ * ## Why there is a port instead of `Room` everywhere
11
+ *
12
+ * `VoiceRoomLike` below names exactly the six things this hook uses and nothing
13
+ * else `livekit-client` exposes. That is the same seam
14
+ * `packages/media/src/transport/livekit/sdk.ts` draws on the server side, for
15
+ * the same payoff: the tests drive a scriptable fake
16
+ * (`__tests__/fake-voice-room.ts`), so they open no socket, need no LiveKit
17
+ * account and run offline — and the parts of this that are easy to get wrong
18
+ * (barge-in precedence, teardown, an agent that never joins) are asserted
19
+ * rather than eyeballed against a live room.
20
+ *
21
+ * ## Why `livekit-client` is imported lazily
22
+ *
23
+ * Statically importing it would pull ~200KB of WebRTC machinery into the bundle
24
+ * of every page that so much as renders the widget shell, and into every test
25
+ * that touches this module. The default room factory imports it at `start()`,
26
+ * which is a user gesture — by then the caller has already decided to talk.
27
+ *
28
+ * ## `loadVoiceProtocol` is lazy for the same reason — "No zod in the client"
29
+ *
30
+ * `@saar-ai/widget-protocol/telemetry` (`decodeTelemetry`, `encodeCallerText`,
31
+ * `VOICE_CALLER_TEXT_TOPIC`) and `@saar-ai/widget-protocol/chat`
32
+ * (`WidgetToolEventSchema`) are both zod-backed. This hook used to import them
33
+ * statically, which meant `ui.mjs` (docs/WIDGET_EMBED_PLAN.md §5.6) carried
34
+ * zod the moment `ConciergeWidget` merely CALLED this hook — every render
35
+ * once a tenant published `modalities.voice: true`, not only once a caller
36
+ * actually pressed the microphone (`ui.mjs` grew 48.9 KB → 78.0 KB min+gz and
37
+ * picked up a zod fingerprint this way). `loadVoiceProtocol()` below defers
38
+ * both subpaths behind the same `start()` gesture `defaultCreateRoom`
39
+ * already gates `livekit-client` behind, so the two load together — a
40
+ * shopper who never starts a call downloads neither. `vite.cdn.config.ts`'s
41
+ * `manualChunks` routes both subpaths into the same `voice` chunk
42
+ * `livekit-client` lands in, so `tools/check-bundle-budget.mjs` measures and
43
+ * budgets this cost as `voice`, never `ui`.
44
+ *
45
+ * Both subpaths are also the reason `@saar-ai/widget-protocol` exists at all
46
+ * rather than importing `@wesence/voice-protocol/telemetry` and
47
+ * `@wesence/shared-types` directly, which is what this hook used to do:
48
+ * `@saar-ai/web-widget` publishes PUBLICLY to npmjs, and a dynamic `import()`
49
+ * resolving to a path under a `@wesence/*` package bundles that package's
50
+ * SOURCE into the published tarball regardless of how browser-safe the code
51
+ * is — a violation of docs/PACKAGE_DISTRIBUTION.md's "no `@wesence/*` source
52
+ * in a published artifact" rule, independent of the zod-bundle-size concern
53
+ * above. See `packages/widget-protocol/AGENTS.md` and
54
+ * `src/__tests__/npm-bundle-provenance.build.test.ts` (the structural proof
55
+ * that no bundled module resolves to a path under a `@wesence/*` package).
56
+ *
57
+ * `SessionTuning` (imported above, statically and type-only) is
58
+ * `@saar-ai/widget-protocol/tuning`'s contribution to the same story: it used
59
+ * to be `import type { SessionTuning } from '@wesence/voice-protocol/tuning'`,
60
+ * which erases from the bundled JS (so it never showed up in the
61
+ * `npm-bundle-provenance` proofs above) but NOT from the `.d.ts`
62
+ * `tsc --emitDeclarationOnly` emits for the published package — that
63
+ * specifier survived verbatim into `dist/use-voice-session.d.ts`, a
64
+ * `@wesence/*` name in a public artifact that no external installer can
65
+ * resolve. `scripts/check-npm-bundle-provenance.mjs` now checks emitted
66
+ * declarations too, not just Rollup's JS module graph, so this class of
67
+ * defect fails the guard.
68
+ *
69
+ * ## What this hook does NOT do
70
+ *
71
+ * It does not carry the transcript. Turn text arrives over the Voice Protocol
72
+ * (a WebSocket between services), not over LiveKit; the widget's `turns` prop
73
+ * stays owned by whatever mounts it.
74
+ */
75
+ export interface CallerSession {
76
+ readonly url: string;
77
+ readonly token: string;
78
+ readonly roomName: string;
79
+ readonly identity: string;
80
+ readonly expiresAt: number;
81
+ }
82
+ export interface VoiceParticipantLike {
83
+ readonly identity: string;
84
+ readonly isLocal?: boolean;
85
+ }
86
+ export interface VoiceTrackLike {
87
+ readonly kind: string;
88
+ attach(): HTMLMediaElement;
89
+ detach(): HTMLMediaElement[];
90
+ }
91
+ export interface VoiceRoomLike {
92
+ on(event: string, listener: (...args: never[]) => void): unknown;
93
+ off(event: string, listener: (...args: never[]) => void): unknown;
94
+ connect(url: string, token: string): Promise<void>;
95
+ disconnect(): Promise<void>;
96
+ /** Satisfies browser autoplay policy; safe to call inside a user gesture. */
97
+ startAudio(): Promise<void>;
98
+ localParticipant: {
99
+ setMicrophoneEnabled(enabled: boolean): Promise<unknown>;
100
+ /**
101
+ * Optional on the port because it is only needed for the TEXT channel, and
102
+ * a room fake written for the voice path should not have to grow a method
103
+ * to stay a faithful double. A room without it simply cannot send text.
104
+ */
105
+ publishData?(payload: Uint8Array, options: {
106
+ reliable: boolean;
107
+ topic: string;
108
+ }): Promise<unknown>;
109
+ };
110
+ remoteParticipants: ReadonlyMap<string, VoiceParticipantLike>;
111
+ }
112
+ /**
113
+ * Loads the call's wire-protocol codec and validation schema — see the module
114
+ * doc comment's "`loadVoiceProtocol` is lazy" section for why this is a
115
+ * dynamic `import()` rather than a top-of-file static one. Called once, at
116
+ * the top of `start()`, in parallel with `fetchSession` — resolved before any
117
+ * `dataReceived` listener is registered, so every real frame is decoded by an
118
+ * already-loaded codec; never re-imported mid-call (the browser's module
119
+ * cache makes a second `start()` after `stop()` free).
120
+ */
121
+ declare function loadVoiceProtocol(): Promise<{
122
+ decodeTelemetry: typeof import("@saar-ai/widget-protocol/telemetry").decodeTelemetry;
123
+ encodeCallerText: typeof import("@saar-ai/widget-protocol/telemetry").encodeCallerText;
124
+ VOICE_CALLER_TEXT_TOPIC: string;
125
+ WidgetToolEventSchema: import("zod").ZodDiscriminatedUnion<[import("zod").ZodObject<{
126
+ type: import("zod").ZodLiteral<"cards">;
127
+ curationId: import("zod").ZodOptional<import("zod").ZodString>;
128
+ items: import("zod").ZodArray<import("zod").ZodObject<{
129
+ productId: import("zod").ZodString;
130
+ variantId: import("zod").ZodOptional<import("zod").ZodString>;
131
+ platformVariantId: import("zod").ZodOptional<import("zod").ZodString>;
132
+ title: import("zod").ZodString;
133
+ imageUrl: import("zod").ZodOptional<import("zod").ZodURL>;
134
+ handle: import("zod").ZodOptional<import("zod").ZodString>;
135
+ priceMinor: import("zod").ZodNumber;
136
+ currency: import("zod").ZodString;
137
+ available: import("zod").ZodBoolean;
138
+ reason: import("zod").ZodOptional<import("zod").ZodString>;
139
+ }, import("zod/v4/core").$strip>>;
140
+ }, import("zod/v4/core").$strip>, import("zod").ZodObject<{
141
+ type: import("zod").ZodLiteral<"escalated">;
142
+ }, import("zod/v4/core").$strip>, import("zod").ZodObject<{
143
+ type: import("zod").ZodLiteral<"checkout">;
144
+ handoffId: import("zod").ZodString;
145
+ url: import("zod").ZodURL;
146
+ itemCount: import("zod").ZodNumber;
147
+ }, import("zod/v4/core").$strip>], "type">;
148
+ }>;
149
+ export type VoiceProtocol = Awaited<ReturnType<typeof loadVoiceProtocol>>;
150
+ /**
151
+ * `RoomEvent` values, as literals.
152
+ *
153
+ * The enum is a plain string enum, so these ARE its values — importing it here
154
+ * only to read six constants would defeat the lazy import above. A test asserts
155
+ * each one against the real enum, so an SDK rename fails the suite instead of
156
+ * silently detaching the widget from the call.
157
+ */
158
+ export declare const ROOM_EVENTS: {
159
+ readonly connected: 'connected';
160
+ readonly disconnected: 'disconnected';
161
+ readonly participantConnected: 'participantConnected';
162
+ readonly participantDisconnected: 'participantDisconnected';
163
+ readonly activeSpeakersChanged: 'activeSpeakersChanged';
164
+ readonly trackSubscribed: 'trackSubscribed';
165
+ readonly dataReceived: 'dataReceived';
166
+ };
167
+ export interface UseVoiceSessionOptions {
168
+ /** Defaults to `POST /api/voice/token`. */
169
+ fetchSession?: (tuning: SessionTuning) => Promise<CallerSession>;
170
+ createRoom?: () => VoiceRoomLike | Promise<VoiceRoomLike>;
171
+ /**
172
+ * Injectable — defaults to `loadVoiceProtocol`, the real dynamic
173
+ * `import()` of the zod-backed wire-protocol codec (`@saar-ai/
174
+ * widget-protocol/telemetry`, `@saar-ai/widget-protocol/chat`). Same reasoning as
175
+ * `createRoom` above: a test that needs to PROVE the codec was never
176
+ * loaded (or was loaded exactly once) should not have to depend on
177
+ * Vitest's own module-mock semantics for something this hook already
178
+ * exposes as a first-class seam. Never called until `start()`.
179
+ */
180
+ loadProtocol?: () => Promise<VoiceProtocol>;
181
+ }
182
+ export interface VoiceSession {
183
+ /**
184
+ * What the concierge's TOOLS put on screen this call, oldest first.
185
+ *
186
+ * A spoken call has no reply stream to hang cards off, so these arrive as
187
+ * their own telemetry frames (`widget.event`) and the mounter renders them
188
+ * beside the transcript — the same split as everything else here: this hook
189
+ * owns the call, the mounter owns the screen.
190
+ */
191
+ readonly widgetEvents: readonly WidgetToolEvent[];
192
+ /** What the avatar should render. */
193
+ readonly state: BotState;
194
+ readonly phase: VoicePhase;
195
+ readonly micOpen: boolean;
196
+ readonly error: string | null;
197
+ /** Timestamped account of the call, oldest first. */
198
+ readonly events: readonly SessionLogEntry[];
199
+ /** 0..1 RMS of the agent's incoming audio — proof that sound is arriving. */
200
+ readonly agentLevel: number;
201
+ /** Per-turn latency, newest last, as the worker measured it. */
202
+ readonly turns: readonly TurnLatencyPayload[];
203
+ /** The conversation as it settles. */
204
+ readonly transcript: readonly TranscriptPayload[];
205
+ /** Per-turn vendor cost, newest last. Aligned turn-for-turn with `turns`. */
206
+ readonly costs: readonly TurnCostPayload[];
207
+ /**
208
+ * What the session ACTUALLY resolved to, reported by the worker.
209
+ *
210
+ * `null` until it arrives. Distinct from the tuning that was requested: an
211
+ * override that failed to apply shows up precisely as a disagreement between
212
+ * the two, and a panel that only showed the request could never reveal it.
213
+ */
214
+ readonly config: SessionConfigPayload | null;
215
+ /** Start a call. The tuning is fixed for its lifetime — it is sealed into the token. */
216
+ start(tuning?: SessionTuning): Promise<void>;
217
+ stop(): Promise<void>;
218
+ toggleMic(): Promise<void>;
219
+ /** Send a typed turn. Resolves false when the room cannot carry one. */
220
+ sendText(text: string): Promise<boolean>;
221
+ }
222
+ export interface WidgetVoiceTokenFetcherOptions {
223
+ /**
224
+ * The widget's MOUNT POINT (`docs/WIDGET_EMBED_PLAN.md` §5.10's `apiBase`
225
+ * contract — same meaning `use-chat-session.ts`'s `apiBase` prop carries:
226
+ * every fetch is `${apiBase}/voice/token`, with no separate `/widget`
227
+ * segment added on top). `''` (same-origin `/voice/token`) is a valid
228
+ * value, same default as `useChatSession`'s own `apiBase`.
229
+ */
230
+ readonly apiBase: string;
231
+ readonly embedKey: string;
232
+ /** The webchat session's own bearer token — `POST /widget/voice/token` is authenticated by IT, never by anything else. */
233
+ readonly chatToken: string;
234
+ readonly fetchImpl?: typeof fetch;
235
+ }
236
+ /**
237
+ * Builds a `UseVoiceSessionOptions.fetchSession` that talks to the API's own
238
+ * `POST /widget/voice/token` (`apps/api/src/widget/widget-voice-token.*`) —
239
+ * the CDN/npm widget's entry point onto voice, as opposed to
240
+ * `defaultFetchSession` above, which is `apps/web`'s Next-route-specific
241
+ * default (`/api/voice/token`, no embed key, no bearer token: that app
242
+ * mints for its own single fixed tenant/agent).
243
+ *
244
+ * ## A known-expired chatToken never reaches the network
245
+ *
246
+ * `options.chatToken` carries its own `exp` claim (see
247
+ * `decodeJwtExpiryMs`'s doc comment). Before spending a round trip on a
248
+ * token this client can already read as expired, this checks it locally and
249
+ * fails fast with the SAME friendly message the API's own 401 maps to —
250
+ * `SESSION_EXPIRED_MESSAGE` — rather than waiting on a 401 that would map to
251
+ * an identical outcome anyway. A token this function cannot decode (not a
252
+ * JWT-shaped string, or a future format) is not treated as expired — it is
253
+ * sent to the API, which is the only party that can authoritatively say so.
254
+ *
255
+ * ## Degrades to text-only, never throws into the host
256
+ *
257
+ * A non-OK response (404 — voice disabled for this tenant, an unknown
258
+ * embed key, or a disallowed origin; all indistinguishable, see that
259
+ * controller's doc comment) throws an ordinary `Error`, exactly like
260
+ * `defaultFetchSession` does for its own non-OK case. `useVoiceSession`'s
261
+ * `start()` already catches whatever `fetchSession` throws (see its own
262
+ * try/catch) and turns it into `{phase: 'failed', error: <message>}` —
263
+ * never an uncaught rejection reaching the host page. Whether the widget
264
+ * even OFFERS the microphone at all (whether `mode` is `'voice'` in the
265
+ * first place) is decided upstream, by the published config's
266
+ * `modalities.voice` — see `host-widget.tsx`'s `ConciergeWidget`; this
267
+ * function's own degrade path is what protects a call that WAS offered but
268
+ * fails at the last moment (a stale cached config, a revoked entitlement).
269
+ */
270
+ export declare function createWidgetVoiceTokenFetcher(options: WidgetVoiceTokenFetcherOptions): (tuning: SessionTuning) => Promise<CallerSession>;
271
+ export declare function useVoiceSession(options?: UseVoiceSessionOptions): VoiceSession;
272
+ export {};
273
+ //# sourceMappingURL=use-voice-session.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"use-voice-session.d.ts","sourceRoot":"","sources":["../src/use-voice-session.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,44 @@
1
+ import type { BotState } from './bot-state.js';
2
+ /**
3
+ * What the widget knows about the live call, as data.
4
+ *
5
+ * Same reason `bot-state.ts` is separate from the avatar: whether the caller is
6
+ * being heard or answered has to be assertable without a room, a socket or a
7
+ * microphone. The hook (`use-voice-session.ts`) does nothing but keep this
8
+ * snapshot current from LiveKit events and hand it to `botStateFor`.
9
+ */
10
+ export type VoicePhase = 'idle' | 'connecting' | 'connected' | 'disconnected' | 'failed';
11
+ export interface VoiceSessionSnapshot {
12
+ readonly phase: VoicePhase;
13
+ /** The caller's microphone track is published to the room. */
14
+ readonly micPublished: boolean;
15
+ /** An agent participant is in the room. */
16
+ readonly agentPresent: boolean;
17
+ /** The agent's audio is active right now. */
18
+ readonly agentSpeaking: boolean;
19
+ /** The caller's own audio is active right now. */
20
+ readonly callerSpeaking: boolean;
21
+ /** The caller has finished a turn and the agent has not answered yet. */
22
+ readonly awaitingAgent: boolean;
23
+ }
24
+ export declare const IDLE_SNAPSHOT: VoiceSessionSnapshot;
25
+ /**
26
+ * Collapse the snapshot onto the four states the avatar can render.
27
+ *
28
+ * The ORDER of these checks is the behaviour, so it is spelled out:
29
+ *
30
+ * 1. Not connected, or not publishing — `idle`. A pulsing "listening" avatar
31
+ * over a closed socket is the one failure a caller cannot detect for
32
+ * themselves; they just keep talking.
33
+ * 2. The caller is speaking — `listening`, even if the agent is also speaking.
34
+ * That overlap IS barge-in, and the caller needs to see the interruption
35
+ * land rather than watch the avatar keep talking over them.
36
+ * 3. The agent is speaking — `speaking`.
37
+ * 4. The agent has the turn but no audio yet, or has not joined the room at
38
+ * all — `thinking`. The dispatcher only places a worker after LiveKit
39
+ * reports the room, so the empty-room gap is real and is not silence from
40
+ * an agent that is listening.
41
+ * 5. Otherwise — `listening`.
42
+ */
43
+ export declare function botStateFor(snapshot: VoiceSessionSnapshot): BotState;
44
+ //# sourceMappingURL=voice-session-state.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"voice-session-state.d.ts","sourceRoot":"","sources":["../src/voice-session-state.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAE/C;;;;;;;GAOG;AACH,MAAM,MAAM,UAAU,GAAG,MAAM,GAAG,YAAY,GAAG,WAAW,GAAG,cAAc,GAAG,QAAQ,CAAC;AAEzF,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,KAAK,EAAE,UAAU,CAAC;IAC3B,8DAA8D;IAC9D,QAAQ,CAAC,YAAY,EAAE,OAAO,CAAC;IAC/B,2CAA2C;IAC3C,QAAQ,CAAC,YAAY,EAAE,OAAO,CAAC;IAC/B,6CAA6C;IAC7C,QAAQ,CAAC,aAAa,EAAE,OAAO,CAAC;IAChC,kDAAkD;IAClD,QAAQ,CAAC,cAAc,EAAE,OAAO,CAAC;IACjC,yEAAyE;IACzE,QAAQ,CAAC,aAAa,EAAE,OAAO,CAAC;CACjC;AAED,eAAO,MAAM,aAAa,EAAE,oBAO3B,CAAC;AAEF;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,WAAW,CAAC,QAAQ,EAAE,oBAAoB,GAAG,QAAQ,CAOpE"}
@@ -0,0 +1,167 @@
1
+ import { type CSSProperties } from 'react';
2
+ import { type WidgetMessages } from './messages.js';
3
+ import { type ConciergeCallPhase } from './concierge-shell.js';
4
+ import type { ConciergePosition } from './position.js';
5
+ import type { BotState } from './bot-state.js';
6
+ import type { ChatAttachment, ChatCardItem, ChatCards } from './use-chat-session.js';
7
+ import { type WidgetNavigate } from './widget-cards.js';
8
+ import { type WidgetCartLine } from './widget-cart-summary.js';
9
+ export interface WidgetTurn {
10
+ readonly speaker: 'caller' | 'agent';
11
+ readonly text: string;
12
+ /** The locale THIS line was spoken in, which need not be the page's. */
13
+ readonly locale: string;
14
+ /** `false` while the recognizer may still revise it. */
15
+ readonly final?: boolean;
16
+ /** Product cards the agent attached to this turn — text mode only. */
17
+ readonly cards?: ChatCards;
18
+ /** Files carried on this turn, either direction — text mode only. */
19
+ readonly attachments?: readonly ChatAttachment[];
20
+ /**
21
+ * Dead-air cover speech ("One moment.") — the voice worker's own
22
+ * `TranscriptPayloadSchema.filler`, forwarded verbatim by `host-widget.tsx`.
23
+ * Always `speaker: 'agent'`. Renders as the transient "still working on
24
+ * it" affordance below, never as an ordinary settled bubble — a filler is
25
+ * cover for a reply still in flight, not the reply itself, and must never
26
+ * read as one.
27
+ */
28
+ readonly filler?: boolean;
29
+ }
30
+ export type WidgetMode = 'voice' | 'text';
31
+ export interface VoiceWidgetProps {
32
+ readonly state: BotState;
33
+ /** The conversation, oldest first. */
34
+ readonly turns: readonly WidgetTurn[];
35
+ readonly onToggleMic: () => void;
36
+ /**
37
+ * Leave the call. Absent ⇒ no hang-up control, which is what a host with no
38
+ * voice leg should render — never a button that cannot end anything.
39
+ */
40
+ readonly onEndCall?: () => void;
41
+ /** Where the call is, for the call bar. Absent ⇒ `idle`. */
42
+ readonly callPhase?: ConciergeCallPhase;
43
+ /** Send a typed turn. The widget clears its input only when this resolves true. */
44
+ readonly onSendText: (text: string) => Promise<boolean> | boolean;
45
+ /** Whether the caller's microphone is currently open. */
46
+ readonly micOpen: boolean;
47
+ /** Collapsed is a launcher; expanded is the conversation. */
48
+ readonly open: boolean;
49
+ readonly onOpenChange: (open: boolean) => void;
50
+ /** Shown under the header — `connecting`, an error, whatever the host knows. */
51
+ readonly status?: string;
52
+ /**
53
+ * `'voice'` (the default) shows the microphone alongside the text box, as
54
+ * documented below under "Voice and text are one conversation". `'text'`
55
+ * hides the microphone entirely — for a host (the demo storefront) that has
56
+ * no voice leg wired at all, rather than rendering a control that always
57
+ * fails when pressed.
58
+ */
59
+ readonly mode?: WidgetMode;
60
+ /** Shows the "a human will pick this up" banner once the conversation escalates. */
61
+ readonly escalated?: boolean;
62
+ /** Forwarded to every product card's "Add to cart" button, text mode only. */
63
+ readonly onAddToCart?: (item: ChatCardItem) => void;
64
+ /**
65
+ * Forwarded to `WidgetCardList` — builds the "See all N" link's href for a
66
+ * curation too large to show inline in full. See that component's own doc
67
+ * comment; omitted here means the same as omitting it there (no link ever
68
+ * renders).
69
+ */
70
+ readonly curationHref?: (curationId: string) => string;
71
+ /** Forwarded to `WidgetCardList` — builds a card's PDP href from its handle. */
72
+ readonly productHref?: (handle: string) => string;
73
+ /**
74
+ * Send a picked file, text mode only. Omitted entirely ⇒ no attach button
75
+ * renders at all — same "the feature is additive per caller" posture as
76
+ * `onAddToCart`. Resolves `true` once the server has accepted it (mirrors
77
+ * `onSendText`'s contract): the widget only clears its own uploading
78
+ * indicator on `true`.
79
+ */
80
+ readonly onAttachFile?: (file: File) => Promise<boolean> | boolean;
81
+ /**
82
+ * The shopper's basket, for the in-widget cart summary. Omitted (or empty)
83
+ * ⇒ no summary ever renders — same "additive per caller" posture as
84
+ * `onAddToCart`, so a host with no cart (the preview harness) is unaffected.
85
+ */
86
+ /**
87
+ * The tenant's own words on the collapsed launcher, from their widget
88
+ * config. Absent renders the mascot alone rather than a phrase we invented.
89
+ */
90
+ readonly launcherLabel?: string;
91
+ /** Where the launcher sits. Defaults to the shell's own bottom-centre. */
92
+ readonly position?: ConciergePosition;
93
+ /** Absent ⇒ a visitor cannot move the widget, and no grip is drawn. */
94
+ readonly onPositionChange?: (position: ConciergePosition) => void;
95
+ readonly cart?: {
96
+ readonly lines: readonly WidgetCartLine[];
97
+ readonly subtotalMinor: number;
98
+ readonly currency: string;
99
+ /** Starts checkout; resolves to the URL to send the shopper to, or `null` on failure. */
100
+ readonly onCheckout: () => Promise<string | null>;
101
+ };
102
+ /**
103
+ * Every string this component renders. Defaults to the package's
104
+ * brand-neutral fallback (`defaultWidgetMessages`) — a host with its own
105
+ * translation catalogue (apps/web's `next-intl` adapter) supplies its own.
106
+ */
107
+ readonly messages?: WidgetMessages;
108
+ /**
109
+ * Fulfils a card's `navigate` intent (§4 Phase 3, coupling (3)) — forwarded
110
+ * to `WidgetCardList`. Absent ⇒ product-card links degrade to a plain
111
+ * `<a href>` full-page navigation.
112
+ */
113
+ readonly navigate?: WidgetNavigate;
114
+ /** BCP-47 locale for product-card price formatting. Defaults to `'en'`. */
115
+ readonly locale?: string;
116
+ /**
117
+ * Inline brand-token overrides, computed by `host-widget.tsx` from the
118
+ * tenant's published config — forwarded straight through to
119
+ * `ConciergeShell`'s own `skinStyle` prop. See that prop's doc comment.
120
+ */
121
+ readonly skinStyle?: CSSProperties;
122
+ }
123
+ /**
124
+ * Does this line read as "I want to pay now"?
125
+ *
126
+ * Deliberately a plain phrase match on the SHOPPER's own words rather than a
127
+ * model signal. The concierge cannot be relied on to call `checkout_handoff`
128
+ * at the right moment — observed in the demo, it answered "use the cart's
129
+ * checkout button", sending the shopper back to the page the conversation
130
+ * existed to keep them out of. Reading their intent directly means the summary
131
+ * appears when they ask, whatever the model decides to do.
132
+ *
133
+ * It is intentionally narrow: a false positive shows a basket nobody asked to
134
+ * see, which is cheap, but this must not fire on "what's in stock". Anything
135
+ * subtler than these phrases is the model's job via a real handoff event.
136
+ */
137
+ export declare function readsAsCheckoutIntent(text: string): boolean;
138
+ /**
139
+ * The end-user agent widget: a launcher bubble that expands into a conversation
140
+ * with both a microphone and a text box.
141
+ *
142
+ * ## Collapsed and expanded, not four states on a toolbar
143
+ *
144
+ * The previous version rendered the avatar's four states from buttons beside
145
+ * it, which is a developer's view of the component and not a product: a visitor
146
+ * never chooses `thinking`. What a visitor has is a closed launcher and an open
147
+ * conversation, so those are the two states this component has. (The state
148
+ * *preview* is still reachable — it moved to the harness page, where a
149
+ * developer's control belongs.)
150
+ *
151
+ * ## Voice and text are one conversation, not two modes
152
+ *
153
+ * Both inputs are present at once and both produce the same kind of turn. A
154
+ * visitor who starts by typing and then presses the microphone is continuing a
155
+ * conversation, not switching product surfaces — and the server treats a typed
156
+ * turn and a spoken one identically (`voice-session.ts`), so the UI would be
157
+ * lying if it separated them.
158
+ *
159
+ * ## Direction is per line, not per page
160
+ *
161
+ * The agent switches language mid-conversation, so one transcript can hold an
162
+ * Arabic caller line above an English agent line. Each line carries its own
163
+ * `dir`, resolved from that line's locale rather than inherited from the page —
164
+ * inheriting is what renders Arabic punctuation on the wrong end of a sentence.
165
+ */
166
+ export declare function VoiceWidget({ state, turns, onToggleMic, onEndCall, callPhase, onSendText, micOpen, open, onOpenChange, status, mode, escalated, onAddToCart, curationHref, productHref, onAttachFile, launcherLabel, position, onPositionChange, cart, messages, navigate, locale, skinStyle, }: VoiceWidgetProps): import("react").JSX.Element;
167
+ //# sourceMappingURL=voice-widget.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"voice-widget.d.ts","sourceRoot":"","sources":["../src/voice-widget.tsx"],"names":[],"mappings":"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"}
@@ -0,0 +1,69 @@
1
+ import type { HostBridge } from '@saar-ai/widget-bridge';
2
+ import { type WidgetMessages } from './messages.js';
3
+ import type { ChatCardItem, ChatCards } from './use-chat-session.js';
4
+ /**
5
+ * `navigate` intent, docs/WIDGET_EMBED_PLAN.md §4 Phase 3, coupling (3):
6
+ * replaces the `next/link` this component used to render directly, which
7
+ * required a Next.js router in every host. Same shape as `HostBridge['navigate']`
8
+ * so a caller can pass `bridge.navigate` straight through.
9
+ */
10
+ export type WidgetNavigate = HostBridge['navigate'];
11
+ export interface WidgetCardListProps {
12
+ readonly cards: ChatCards;
13
+ /**
14
+ * `true` when the widget is in its expanded (80% viewport) size, which is
15
+ * wide enough to stand the cards side by side instead of stacking them.
16
+ * Purely a layout hint — the cards themselves are identical either way.
17
+ */
18
+ readonly roomy?: boolean;
19
+ /**
20
+ * Absent when the host page has no cart to add to (e.g. the preview harness).
21
+ *
22
+ * May be async: the button holds its spinner until the returned promise
23
+ * settles, so a handler that also asks the concierge to acknowledge the add
24
+ * keeps the control honest about when the work is actually finished.
25
+ */
26
+ readonly onAddToCart?: (item: ChatCardItem) => void | Promise<void>;
27
+ /**
28
+ * Builds the "See all N" link's href for a curation whose item count
29
+ * exceeds {@link INLINE_CARD_LIMIT}. Absent ⇒ every item just renders
30
+ * inline, uncapped, and no link ever appears — the correct behaviour for
31
+ * a host with no curation results page to link to (e.g. `widget-preview`'s
32
+ * harness). The demo storefront's `widget-launcher.tsx` supplies
33
+ * `(curationId) => \`/demo-store/c/${curationId}\`}`.
34
+ */
35
+ readonly curationHref?: (curationId: string) => string;
36
+ /**
37
+ * Builds the PDP href for a product handle. Absent — or a card with no
38
+ * `handle` — renders that card unlinked rather than guessing a URL, same
39
+ * "the MOUNTER owns routing" split as {@link WidgetCardListProps.curationHref}.
40
+ */
41
+ readonly productHref?: (handle: string) => string;
42
+ /**
43
+ * Fulfils a `navigate` intent — see `WidgetNavigate`'s doc comment.
44
+ * Absent ⇒ every link degrades to a PLAIN `<a href>`, which the browser
45
+ * navigates on its own; a host with no bridge still gets a working link,
46
+ * just a full page load instead of a soft one.
47
+ */
48
+ readonly navigate?: WidgetNavigate;
49
+ /** BCP-47 locale for price formatting. Defaults to `'en'`. */
50
+ readonly locale?: string;
51
+ /** Defaults to the package's brand-neutral fallback — see `messages.ts`. */
52
+ readonly messages?: WidgetMessages;
53
+ }
54
+ /**
55
+ * The product recommendations the agent attaches to a turn — rendered inline,
56
+ * under that turn's bubble, never as a separate panel. A visitor asking "do
57
+ * you have this in blue?" and getting cards three messages later, detached
58
+ * from the answer that produced them, would not read as an answer at all.
59
+ *
60
+ * `onAddToCart` is the same callback the PLP/PDP use (see
61
+ * `components/demo-store/use-cart.ts`), passed down through whatever mounts
62
+ * the widget — this component owns no cart state of its own. A curation
63
+ * larger than {@link INLINE_CARD_LIMIT} is truncated to the first N items
64
+ * plus a "See all N" link (see {@link WidgetCardListProps.curationHref}) —
65
+ * the inline strip stays the demo's money shot, but a longer list gets the
66
+ * bigger canvas of its own page rather than an unbounded scroll.
67
+ */
68
+ export declare function WidgetCardList({ cards, onAddToCart, curationHref, productHref, navigate, locale, messages, roomy, }: WidgetCardListProps): import("react").JSX.Element | null;
69
+ //# sourceMappingURL=widget-cards.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"widget-cards.d.ts","sourceRoot":"","sources":["../src/widget-cards.tsx"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAC;AAGzD,OAAO,EAAwC,KAAK,cAAc,EAAE,MAAM,eAAe,CAAC;AAC1F,OAAO,KAAK,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAErE;;;;;GAKG;AACH,MAAM,MAAM,cAAc,GAAG,UAAU,CAAC,UAAU,CAAC,CAAC;AAgBpD,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,KAAK,EAAE,SAAS,CAAC;IAC1B;;;;OAIG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC;IACzB;;;;;;OAMG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,CAAC,IAAI,EAAE,YAAY,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACpE;;;;;;;OAOG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,CAAC,UAAU,EAAE,MAAM,KAAK,MAAM,CAAC;IACvD;;;;OAIG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,MAAM,CAAC;IAClD;;;;;OAKG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,cAAc,CAAC;IACnC,8DAA8D;IAC9D,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,4EAA4E;IAC5E,QAAQ,CAAC,QAAQ,CAAC,EAAE,cAAc,CAAC;CACpC;AA2ND;;;;;;;;;;;;;GAaG;AACH,wBAAgB,cAAc,CAAC,EAC7B,KAAK,EACL,WAAW,EACX,YAAY,EACZ,WAAW,EACX,QAAQ,EACR,MAAa,EACb,QAAgC,EAChC,KAAa,GACd,EAAE,mBAAmB,sCAsErB"}
@@ -0,0 +1,66 @@
1
+ import { type WidgetMessages } from './messages.js';
2
+ /** One line of the shopper's basket, as the widget needs to render it. */
3
+ export interface WidgetCartLine {
4
+ readonly key: string;
5
+ readonly title: string;
6
+ readonly imageUrl?: string;
7
+ readonly priceMinor: number;
8
+ readonly currency: string;
9
+ readonly quantity: number;
10
+ }
11
+ export interface WidgetCartSummaryProps {
12
+ readonly lines: readonly WidgetCartLine[];
13
+ readonly subtotalMinor: number;
14
+ readonly currency: string;
15
+ /**
16
+ * Starts checkout. Resolves to a URL to send the shopper to, or `null` if a
17
+ * handoff could not be created — the button reports that rather than opening
18
+ * a dead tab.
19
+ *
20
+ * Async because building a real checkout permalink is a server round-trip
21
+ * (`POST /widget/checkout`).
22
+ */
23
+ readonly onCheckout: () => Promise<string | null>;
24
+ /**
25
+ * How the shopper is sent to checkout. Defaults to a SAME-TAB navigation.
26
+ * Injectable so a test can assert where it sent them without navigating the
27
+ * test runner.
28
+ */
29
+ readonly navigate?: (url: string) => void;
30
+ /** BCP-47 locale for price formatting. Defaults to `'en'`. */
31
+ readonly locale?: string;
32
+ /** Defaults to the package's brand-neutral fallback — see `messages.ts`. */
33
+ readonly messages?: WidgetMessages;
34
+ }
35
+ /**
36
+ * The basket, inside the conversation.
37
+ *
38
+ * ## Why the widget owns a checkout button at all
39
+ *
40
+ * The concierge's job is a basket, not a transcript — a conversation that ends
41
+ * with "use the cart's checkout button" has handed the shopper back to the
42
+ * page it just spent five turns keeping them out of. This puts the last step
43
+ * where the conversation is.
44
+ *
45
+ * ## One press, then it goes
46
+ *
47
+ * Pressing Checkout builds the permalink and navigates straight there in the
48
+ * SAME tab. It briefly rendered a second "Open checkout" link instead, out of
49
+ * a worry about popup blockers — but that worry only applies to `window.open`,
50
+ * which asks for a NEW window. A same-tab `location.assign` after an await is
51
+ * an ordinary navigation and is never blocked, so the second press was pure
52
+ * friction on the one control that matters most.
53
+ *
54
+ * Same tab rather than a new one, deliberately: checkout is the end of this
55
+ * conversation, not a side trip, and the cart and session both survive in
56
+ * `localStorage` if the shopper comes back.
57
+ *
58
+ * ## What it is NOT
59
+ *
60
+ * Not a cart editor. There are no quantity steppers and no remove buttons:
61
+ * this is a confirmation surface shown at the moment of leaving, and every
62
+ * control added here is one more thing between the shopper and checkout. The
63
+ * storefront's own cart drawer remains the place to change quantities.
64
+ */
65
+ export declare function WidgetCartSummary({ lines, subtotalMinor, currency, onCheckout, navigate, locale, messages, }: WidgetCartSummaryProps): import("react").JSX.Element | null;
66
+ //# sourceMappingURL=widget-cart-summary.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"widget-cart-summary.d.ts","sourceRoot":"","sources":["../src/widget-cart-summary.tsx"],"names":[],"mappings":"AAIA,OAAO,EAAyB,KAAK,cAAc,EAAE,MAAM,eAAe,CAAC;AAE3E,0EAA0E;AAC1E,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC3B;AAED,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,KAAK,EAAE,SAAS,cAAc,EAAE,CAAC;IAC1C,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B;;;;;;;OAOG;IACH,QAAQ,CAAC,UAAU,EAAE,MAAM,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IAClD;;;;OAIG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;IAC1C,8DAA8D;IAC9D,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,4EAA4E;IAC5E,QAAQ,CAAC,QAAQ,CAAC,EAAE,cAAc,CAAC;CACpC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wBAAgB,iBAAiB,CAAC,EAChC,KAAK,EACL,aAAa,EACb,QAAQ,EACR,UAAU,EACV,QAAQ,EACR,MAAa,EACb,QAAgC,GACjC,EAAE,sBAAsB,sCA2DxB"}