@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,165 @@
1
+ import type { HostBridge } from '@saar-ai/widget-bridge';
2
+ import type { VisitorEventCollector } from '@saar-ai/widget-bridge';
3
+ import { type ChatCardItem } from './use-chat-session.js';
4
+ import { type WidgetMessages } from './messages.js';
5
+ /**
6
+ * Resolves the widget's "add to cart" handler from the bridge's OWN degraded
7
+ * path — docs/WIDGET_EMBED_PLAN.md §3, rule 1 ("every optional method is
8
+ * genuinely optional... the widget has a working degraded path for each —
9
+ * `addToCart` absent ⇒ navigate to the PDP").
10
+ *
11
+ * Returns `undefined` only when NEITHER capability could ever apply — no
12
+ * bridge at all, or a bridge with no `addToCart` AND no way to build a PDP
13
+ * link (`navigate` absent, or the caller gave no `productHref`).
14
+ * `AddToCartButton` renders that as a permanently disabled control, which is
15
+ * correct: a card this widget provably cannot fulfil any way must say so,
16
+ * not silently do nothing on click.
17
+ *
18
+ * When a handler IS returned, the choice is made PER ITEM, not once for the
19
+ * whole widget — `bridge.addToCart` is only used when the specific item
20
+ * carries an id in the SPACE this bridge's `addToCartVariantIdSpace` expects
21
+ * (`host-bridge.ts`'s doc comment):
22
+ *
23
+ * - `'platform'` (the default when the bridge declares nothing — every
24
+ * bridge that shipped before this field existed, i.e. `ShopifyBridge`) —
25
+ * `item.platformVariantId`, the PLATFORM-native variant id (e.g.
26
+ * Shopify's numeric one), NEVER `item.variantId`, the internal catalog
27
+ * UUID (adversarial-review finding #2). A card with no `platformVariantId`
28
+ * (the underlying variant's external id wasn't a recognised platform GID)
29
+ * falls through to the PDP navigation exactly like a bridge with no
30
+ * `addToCart` at all.
31
+ * - `'catalog'` (`WindowCommerceBridge`, docs/WIDGET_EMBED_PLAN.md B3) —
32
+ * `item.variantId` itself, because this bridge's cart backend IS our own
33
+ * catalog, together with a `CartLineContext` built from the SAME card
34
+ * (`buildCartLineContext` below) — this bridge has no server-side way to
35
+ * resolve a bare id into a title/price/image the way a real platform's
36
+ * own cart API does.
37
+ */
38
+ export declare function resolveAddToCartHandler(bridge: HostBridge | undefined, productHref: ((handle: string) => string) | undefined): ((item: ChatCardItem) => Promise<void>) | undefined;
39
+ export interface ConciergeWidgetProps {
40
+ /** The tenant's public embed key — see `packages/widget-bridge/AGENTS.md`'s wire contract. */
41
+ readonly embedKey: string;
42
+ /**
43
+ * The widget's MOUNT POINT, not a bare origin — `useChatSession` inside
44
+ * this component builds every request as `${apiBase}/session`,
45
+ * `${apiBase}/chat`, `${apiBase}/event`, etc, with no separate `/widget`
46
+ * segment ever added on top. `''` (same-origin) by default — see
47
+ * `use-chat-session.ts`'s `DEFAULT_API_BASE` doc comment — which matches
48
+ * `apps/web`'s real deployment, where the analogous mount point is the
49
+ * same-origin Next.js proxy `/api/widget` (`app/api/widget/[...path]/
50
+ * route.ts`), NOT `/api`. A caller passing a bare tenant origin (e.g. the
51
+ * CDN embed's `data-api-base`, `https://api.example.com`) must append the
52
+ * `/widget` segment itself before handing it to this prop — `core.ts`'s
53
+ * `initCore` does exactly that (`joinUrl(apiBase, '/widget')`) when it
54
+ * mounts this component via `ui.ts`'s `mountUi` (adversarial-review
55
+ * finding #2 — this prop used to receive the bare origin, so every fetch
56
+ * 404'd against a path missing `/widget` entirely).
57
+ */
58
+ readonly apiBase?: string;
59
+ /**
60
+ * The api's ORIGIN (e.g. `https://api.example.com`) the widget's human-desk
61
+ * reply push connects to DIRECTLY over Socket.IO — never through `apiBase`'s
62
+ * proxy, which cannot forward a WebSocket upgrade. See
63
+ * `use-chat-session.ts`'s `UseChatSessionOptions.socketUrl` doc comment for
64
+ * the full contract (push with polling as the fallback, never a
65
+ * replacement). Forwarded straight through — this component adds no
66
+ * behaviour of its own around it. Omitted ⇒ poll-only, byte-identical to
67
+ * this component's behaviour before push existed (`useChatSession`'s own
68
+ * default), same opt-in-per-caller posture the hook already documents.
69
+ */
70
+ readonly socketUrl?: string;
71
+ /** Path the widget's Socket.IO gateway is mounted on. Forwarded straight through; see `use-chat-session.ts`'s `socketPath` (defaults to `/socket.io`). */
72
+ readonly socketPath?: string;
73
+ /**
74
+ * What this widget needs FROM the host page — navigation, cart, page
75
+ * awareness (docs/WIDGET_EMBED_PLAN.md §3). Absent ⇒ every card link is a
76
+ * plain `<a href>` and "add to cart" is disabled; the widget still boots
77
+ * and carries a full text conversation.
78
+ */
79
+ readonly bridge?: HostBridge;
80
+ /** Wires the visitor-event pipeline — see `use-chat-session.ts`'s `collector` option. */
81
+ readonly collector?: VisitorEventCollector;
82
+ /** Defaults to the package's brand-neutral fallback — see `messages.ts`. */
83
+ readonly messages?: WidgetMessages;
84
+ /**
85
+ * The tenant's published brand colours (`WidgetAppearance.brandPrimary`/
86
+ * `brandSecondary`/`brandAccent`, `apps/api/src/widget/widget-config.types.ts`),
87
+ * sourced from `GET /widget/config` by whoever mounts this component — see
88
+ * `core.ts`'s `CoreWidgetConfig` doc comment for why that endpoint, not the
89
+ * session response. Absent (the default, and every config published
90
+ * before these fields existed) ⇒ no override for that colour; the
91
+ * widget's built-in default (`concierge.css`'s `--brand-plum`/`-rose`/
92
+ * `-amber`) stands exactly as it always has.
93
+ */
94
+ readonly brandPrimary?: string;
95
+ readonly brandSecondary?: string;
96
+ readonly brandAccent?: string;
97
+ /** BCP-47 locale for price formatting. Defaults to `'en'`. */
98
+ readonly locale?: string;
99
+ /** Builds a product card's PDP href from its handle — also feeds the `addToCart` degraded path, see `resolveAddToCartHandler`. */
100
+ readonly productHref?: (handle: string) => string;
101
+ /** Builds a truncated curation's "See all N" href. */
102
+ readonly curationHref?: (curationId: string) => string;
103
+ /**
104
+ * Whether the panel starts OPEN. Defaults to `false` — a host that renders
105
+ * this component into its own page wants the collapsed launcher first.
106
+ *
107
+ * The CDN embed is the case that needs `true`: `core.ts` shows its own
108
+ * plain-DOM launcher pill BEFORE React exists at all, and only loads
109
+ * `ui.mjs` once the visitor presses it. That press is the open — by the
110
+ * time this component mounts, the shopper has already asked for the panel,
111
+ * and the pill they pressed no longer exists. Booting closed there hands
112
+ * them React's launcher in the same spot instead of the conversation they
113
+ * asked for (SAA-131).
114
+ *
115
+ * Uncontrolled, deliberately: this is the INITIAL state, not a binding.
116
+ * The widget owns open/close from then on, and a host that wants to drive
117
+ * it should compose `VoiceWidget`'s `open`/`onOpenChange` directly — see
118
+ * this component's doc comment.
119
+ */
120
+ readonly defaultOpen?: boolean;
121
+ /**
122
+ * Called if this widget's OWN render throws — never surfaced to the host
123
+ * page otherwise (see `error-boundary.tsx`). Optional; the default is to
124
+ * unmount silently.
125
+ */
126
+ readonly onError?: (error: unknown) => void;
127
+ }
128
+ /**
129
+ * The plain React widget component — for a Next.js host (Phase 5's npm
130
+ * package) that renders it directly, without the shadow-DOM mount
131
+ * `mountConciergeWidget` performs for the CDN embed. Boots its own chat session
132
+ * (`useChatSession`) and owns its own open/closed state; a host wanting
133
+ * different session plumbing should compose `VoiceWidget` directly instead
134
+ * (this component is a convenience, not the only way to use the package).
135
+ *
136
+ * ## Voice — offered when, and only when, the tenant published it
137
+ *
138
+ * This used to be hardcoded `mode="text"`, on the reasoning that "a generic
139
+ * host bridge carries no voice transport — LiveKit token minting is a
140
+ * server concern this package cannot assume any host has". That reasoning
141
+ * no longer holds: `apps/api`'s `POST /widget/voice/token`
142
+ * (`docs/WIDGET_EMBED_PLAN.md` §5.6/§7) mints a LiveKit session for ANY
143
+ * `apiBase` this component is given, the same API surface `useChatSession`
144
+ * already talks to — so a host with no voice leg of its own (the CDN embed,
145
+ * an npm consumer) can still offer one.
146
+ *
147
+ * Three things must ALL hold before the microphone renders at all:
148
+ *
149
+ * 1. `apiBase` is known — `createWidgetVoiceTokenFetcher` needs the widget's
150
+ * mount point, same contract `useChatSession` already uses (see
151
+ * `ConciergeWidgetProps.apiBase`'s doc comment).
152
+ * 2. `session.chatToken` exists — `POST /widget/voice/token` is
153
+ * authenticated by it, same as every other post-`/session` call.
154
+ * 3. `session.modalities.voice` is `true` — the TENANT's own published
155
+ * widget config opted in. `false` (the default before this feature, and
156
+ * for every tenant who hasn't turned it on) keeps this component exactly
157
+ * as it always behaved: text-only, no mic control drawn at all.
158
+ *
159
+ * `useVoiceSession`'s own `import('livekit-client')` stays behind `start()`
160
+ * regardless of any of this — see that hook's doc comment — so nothing
161
+ * about offering voice here costs a byte until a caller actually presses
162
+ * the microphone.
163
+ */
164
+ export declare function ConciergeWidget({ embedKey, apiBase, socketUrl, socketPath, bridge, collector, messages, locale, productHref, curationHref, brandPrimary, brandSecondary, brandAccent, defaultOpen, }: ConciergeWidgetProps): import("react").JSX.Element;
165
+ //# sourceMappingURL=host-widget.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"host-widget.d.ts","sourceRoot":"","sources":["../src/host-widget.tsx"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAmB,UAAU,EAAE,MAAM,wBAAwB,CAAC;AAC1E,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,wBAAwB,CAAC;AAEpE,OAAO,EAAkB,KAAK,YAAY,EAAE,MAAM,uBAAuB,CAAC;AAI1E,OAAO,EAAyB,KAAK,cAAc,EAAE,MAAM,eAAe,CAAC;AAE3E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,wBAAgB,uBAAuB,CACrC,MAAM,EAAE,UAAU,GAAG,SAAS,EAC9B,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE,MAAM,KAAK,MAAM,CAAC,GAAG,SAAS,GACpD,CAAC,CAAC,IAAI,EAAE,YAAY,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC,GAAG,SAAS,CAgDrD;AAkBD,MAAM,WAAW,oBAAoB;IACnC,8FAA8F;IAC9F,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B;;;;;;;;;;;;;;;OAeG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B;;;;;;;;;;OAUG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,0JAA0J;IAC1J,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B;;;;;OAKG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,UAAU,CAAC;IAC7B,yFAAyF;IACzF,QAAQ,CAAC,SAAS,CAAC,EAAE,qBAAqB,CAAC;IAC3C,4EAA4E;IAC5E,QAAQ,CAAC,QAAQ,CAAC,EAAE,cAAc,CAAC;IACnC;;;;;;;;;OASG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,8DAA8D;IAC9D,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,kIAAkI;IAClI,QAAQ,CAAC,WAAW,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,MAAM,CAAC;IAClD,sDAAsD;IACtD,QAAQ,CAAC,YAAY,CAAC,EAAE,CAAC,UAAU,EAAE,MAAM,KAAK,MAAM,CAAC;IACvD;;;;;;;;;;;;;;;;OAgBG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,OAAO,CAAC;IAC/B;;;;OAIG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC;CAC7C;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,wBAAgB,eAAe,CAAC,EAC9B,QAAQ,EACR,OAAO,EACP,SAAS,EACT,UAAU,EACV,MAAM,EACN,SAAS,EACT,QAAgC,EAChC,MAAa,EACb,WAAW,EACX,YAAY,EACZ,YAAY,EACZ,cAAc,EACd,WAAW,EACX,WAAmB,GACpB,EAAE,oBAAoB,+BAuMtB"}
@@ -0,0 +1,28 @@
1
+ export * from './bot-face.js';
2
+ export * from './concierge-launcher.js';
3
+ export * from './concierge-shell.js';
4
+ export * from './position.js';
5
+ export * from './morphing-loader.js';
6
+ export { cn } from './cn.js';
7
+ export * from './messages.js';
8
+ export * from './bot-state.js';
9
+ export * from './bot-avatar.js';
10
+ export * from './session-log.js';
11
+ export * from './sse-parser.js';
12
+ export * from './voice-session-state.js';
13
+ export * from './session-panel.js';
14
+ export * from './widget-markdown.js';
15
+ export * from './widget-cards.js';
16
+ export * from './widget-cart-summary.js';
17
+ export * from './voice-widget.js';
18
+ export * from './use-chat-session.js';
19
+ export * from './use-voice-session.js';
20
+ export * from './text-direction.js';
21
+ export * from './format-money.js';
22
+ export * from './host-widget.js';
23
+ export * from './error-boundary.js';
24
+ export * from './mount.js';
25
+ export * from './styles.js';
26
+ export type { HostBridge, HostPage, HostPageKind, HostIntent, NavigateIntent, ApplyFilterIntent, AddToCartIntent, } from '@saar-ai/widget-bridge';
27
+ export type { VisitorEventCollector, VisitorEventCollectorOptions, CollectorSession, Transport, TransportResponse, ConsentState, } from '@saar-ai/widget-bridge';
28
+ //# sourceMappingURL=index.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAYA,cAAc,eAAe,CAAC;AAC9B,cAAc,yBAAyB,CAAC;AACxC,cAAc,sBAAsB,CAAC;AACrC,cAAc,eAAe,CAAC;AAC9B,cAAc,sBAAsB,CAAC;AACrC,OAAO,EAAE,EAAE,EAAE,MAAM,SAAS,CAAC;AAG7B,cAAc,eAAe,CAAC;AAG9B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,iBAAiB,CAAC;AAChC,cAAc,kBAAkB,CAAC;AACjC,cAAc,iBAAiB,CAAC;AAChC,cAAc,0BAA0B,CAAC;AACzC,cAAc,oBAAoB,CAAC;AACnC,cAAc,sBAAsB,CAAC;AACrC,cAAc,mBAAmB,CAAC;AAClC,cAAc,0BAA0B,CAAC;AACzC,cAAc,mBAAmB,CAAC;AAClC,cAAc,uBAAuB,CAAC;AACtC,cAAc,wBAAwB,CAAC;AAIvC,cAAc,qBAAqB,CAAC;AACpC,cAAc,mBAAmB,CAAC;AAIlC,cAAc,kBAAkB,CAAC;AACjC,cAAc,qBAAqB,CAAC;AACpC,cAAc,YAAY,CAAC;AAC3B,cAAc,aAAa,CAAC;AAa5B,YAAY,EACV,UAAU,EACV,QAAQ,EACR,YAAY,EACZ,UAAU,EACV,cAAc,EACd,iBAAiB,EACjB,eAAe,GAChB,MAAM,wBAAwB,CAAC;AAChC,YAAY,EACV,qBAAqB,EACrB,4BAA4B,EAC5B,gBAAgB,EAChB,SAAS,EACT,iBAAiB,EACjB,YAAY,GACb,MAAM,wBAAwB,CAAC"}