@saar-ai/web-widget 0.4.1 → 0.5.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/chunks/chat-tMKkYmTC.js +592 -0
- package/dist/chunks/{host-widget-C9EyGeiN.js → host-widget-B0SkhMIs.js} +1450 -103
- 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 +62 -0
- package/dist/host-widget.d.ts.map +1 -1
- package/dist/index.js +3 -3
- package/dist/messages.d.ts +17 -0
- package/dist/messages.d.ts.map +1 -1
- package/dist/next/index.js +1 -1
- package/dist/turn-order.d.ts +106 -0
- package/dist/turn-order.d.ts.map +1 -0
- package/dist/use-chat-session.d.ts +128 -1
- package/dist/use-chat-session.d.ts.map +1 -1
- package/dist/use-voice-session.d.ts +31 -1
- package/dist/use-voice-session.d.ts.map +1 -1
- package/dist/voice-widget.d.ts +66 -6
- package/dist/voice-widget.d.ts.map +1 -1
- package/dist/widget-cards.d.ts.map +1 -1
- package/dist/widget.css +1 -1
- package/package.json +3 -3
- package/src/styles/concierge.css +45 -0
- package/dist/chunks/chat-DfajYOmN.js +0 -240
|
@@ -1,240 +0,0 @@
|
|
|
1
|
-
import { a as httpUrl, c as number, i as discriminatedUnion, l as object, n as array, o as literal, r as boolean, u as string } from "./schemas-Bl_6mxe4.js";
|
|
2
|
-
//#region ../widget-protocol/dist/chat.js
|
|
3
|
-
/**
|
|
4
|
-
* The webchat SSE wire contract, and the sidecar `widgetEvent` a tool result
|
|
5
|
-
* may carry to short-circuit into one of those events.
|
|
6
|
-
*
|
|
7
|
-
* ## Why this lives in `@saar-ai/widget-protocol`, zod, not a plain interface
|
|
8
|
-
*
|
|
9
|
-
* Two independent runtimes read this shape: `apps/api`'s
|
|
10
|
-
* `widget-chat.controller.ts` WRITES it onto an SSE response, and
|
|
11
|
-
* `@saar-ai/web-widget`'s voice leg (`use-voice-session.ts`, via the
|
|
12
|
-
* `widget.event` sidecar on the telemetry channel — see `./telemetry.ts`)
|
|
13
|
-
* PARSES `WidgetToolEventSchema` off it. A hand-maintained interface on each
|
|
14
|
-
* side drifts silently — the failure mode is a widget that renders
|
|
15
|
-
* `undefined` for a field the server renamed. Zod schemas, exported from one
|
|
16
|
-
* package both sides can import, make the shape a single source of truth and
|
|
17
|
-
* let each side `.parse()`/`.safeParse()` at its own boundary instead of
|
|
18
|
-
* trusting an unchecked cast.
|
|
19
|
-
*
|
|
20
|
-
* Moved here from the framework-inherited `@wesence/shared-types` — this
|
|
21
|
-
* package's own `AGENTS.md` explains why a widget-only contract does not
|
|
22
|
-
* belong inside a package a framework regeneration can silently clobber, and
|
|
23
|
-
* why it must not be reachable from `@saar-ai/web-widget`'s published bundle
|
|
24
|
-
* via a `@wesence/*` import path at all (docs/PACKAGE_DISTRIBUTION.md).
|
|
25
|
-
*
|
|
26
|
-
* ## The six event types, and why cards/checkout are separate events from text
|
|
27
|
-
*
|
|
28
|
-
* A reply may interleave prose with product/price/checkout data. Prices,
|
|
29
|
-
* stock, and product attributes are NEVER stated as text by the model (see
|
|
30
|
-
* `widget-chat.service.ts`'s system-prompt guardrail) — they arrive only as
|
|
31
|
-
* `cards`, sourced from a tool result, so the widget can render them as
|
|
32
|
-
* structured UI (an image, a price, an availability badge) rather than text
|
|
33
|
-
* the model could hallucinate. The real checkout URL is likewise never typed
|
|
34
|
-
* by the model — it arrives only as `checkout`.
|
|
35
|
-
*
|
|
36
|
-
* - `text-delta` — one chunk of the assistant's streamed reply.
|
|
37
|
-
* - `cards` — one or more product/curation cards to render.
|
|
38
|
-
* - `escalated` — the conversation just moved to a human/queue; the AI
|
|
39
|
-
* will not reply further on this turn. The widget should show a "connecting
|
|
40
|
-
* you with a person" state and start polling `/widget/messages`.
|
|
41
|
-
* - `checkout` — a real Shopify cart permalink to hand the shopper off
|
|
42
|
-
* to; the widget renders a "Go to checkout" control around `url`.
|
|
43
|
-
* - `done` — the turn is over. Carries the turn id so the widget can
|
|
44
|
-
* correlate a later `/widget/messages` page against what it already
|
|
45
|
-
* rendered inline.
|
|
46
|
-
* - `error` — the turn failed. `message` is safe to show the visitor
|
|
47
|
-
* (never a raw exception/stack).
|
|
48
|
-
*
|
|
49
|
-
* ## `widgetEvent` — the tool-result sidecar
|
|
50
|
-
*
|
|
51
|
-
* A tool (e.g. a product-search tool) may attach `widgetEvent` to its output
|
|
52
|
-
* to ask the chat loop to forward one of these events verbatim, alongside the
|
|
53
|
-
* tool's own return value the model sees. Only `cards`, `escalated`, and
|
|
54
|
-
* `checkout` are valid sidecar events — `text-delta`/`done`/`error` are
|
|
55
|
-
* lifecycle events the runtime itself owns and a tool must never emit.
|
|
56
|
-
*/
|
|
57
|
-
/** Bound for a display string a card renders. Never free-form model prose. */
|
|
58
|
-
var CARD_TEXT_MAX = 500;
|
|
59
|
-
/** Bound for an id-shaped field (product/variant/curation ids). */
|
|
60
|
-
var ID_MAX = 200;
|
|
61
|
-
/**
|
|
62
|
-
* One product/curation card. `priceMinor` is the ISO 4217 minor-unit integer
|
|
63
|
-
* (cents, paise, …) — never a float — and `currency` is the ISO 4217 code, so
|
|
64
|
-
* the widget formats price itself rather than trusting a pre-formatted
|
|
65
|
-
* string the model could get wrong.
|
|
66
|
-
*/
|
|
67
|
-
var WidgetChatCardSchema = object({
|
|
68
|
-
productId: string().min(1).max(ID_MAX),
|
|
69
|
-
/** The INTERNAL catalog UUID (`curation_items.variant_id`) — never a platform id. See `platformVariantId` for what a storefront `addToCart` bridge actually needs. */
|
|
70
|
-
variantId: string().min(1).max(ID_MAX).optional(),
|
|
71
|
-
/**
|
|
72
|
-
* The PLATFORM-NATIVE variant id (e.g. Shopify's numeric `/cart/add.js`
|
|
73
|
-
* id) — extracted server-side from the variant's provider GID via
|
|
74
|
-
* `apps/api/src/catalog/checkout-permalink.ts`'s
|
|
75
|
-
* `parseShopifyVariantNumericId`, the SAME parser the checkout permalink
|
|
76
|
-
* uses, never a string-slice of `variantId`. `@saar-ai/web-widget`'s
|
|
77
|
-
* `resolveAddToCartHandler` calls a storefront bridge's `addToCart` with
|
|
78
|
-
* THIS field, never `variantId` (adversarial-review finding #2 — the
|
|
79
|
-
* internal UUID is meaningless to `ShopifyBridge`'s `POST /cart/add.js`).
|
|
80
|
-
* Absent whenever the underlying variant's external id isn't a
|
|
81
|
-
* recognised platform GID (§5.3's "degrade, never fabricate" — never
|
|
82
|
-
* guessed) — the widget then offers no add-to-cart action for the card
|
|
83
|
-
* and falls back to a PDP navigation instead.
|
|
84
|
-
*/
|
|
85
|
-
platformVariantId: string().min(1).max(ID_MAX).optional(),
|
|
86
|
-
title: string().min(1).max(CARD_TEXT_MAX),
|
|
87
|
-
/** http(s) only — `z.httpUrl()` refuses `javascript:`/`data:`/etc, the same scheme allowlist `conversations/attribution.ts` enforces for stored URLs. */
|
|
88
|
-
imageUrl: httpUrl().optional(),
|
|
89
|
-
/**
|
|
90
|
-
* The product's storefront handle, so the widget's card can link to its PDP.
|
|
91
|
-
*
|
|
92
|
-
* A SLUG, never a URL or a path: the widget's host builds the href from it
|
|
93
|
-
* (`widget-launcher.tsx`'s `productHref`), so anything path-like here would
|
|
94
|
-
* let a catalogue row steer where a card points. The character class below
|
|
95
|
-
* is what a Shopify handle actually is, and it cannot express a scheme, a
|
|
96
|
-
* host, a `..` segment or a leading slash.
|
|
97
|
-
*/
|
|
98
|
-
handle: string().min(1).max(ID_MAX).regex(/^[a-z0-9]+(?:-[a-z0-9]+)*$/i).optional(),
|
|
99
|
-
/** ISO 4217 minor units — an integer, never a float. */
|
|
100
|
-
priceMinor: number().int().min(0),
|
|
101
|
-
/** ISO 4217 currency code, e.g. "USD". */
|
|
102
|
-
currency: string().length(3),
|
|
103
|
-
available: boolean(),
|
|
104
|
-
/** Short, optional "why this" — e.g. "matches your search". Never a price/stock claim. */
|
|
105
|
-
reason: string().max(CARD_TEXT_MAX).optional()
|
|
106
|
-
});
|
|
107
|
-
var WidgetChatTextDeltaEventSchema = object({
|
|
108
|
-
type: literal("text-delta"),
|
|
109
|
-
delta: string()
|
|
110
|
-
});
|
|
111
|
-
var WidgetChatCardsEventSchema = object({
|
|
112
|
-
type: literal("cards"),
|
|
113
|
-
/** Correlates this render back to whichever tool call produced it, when the tool supplies one. */
|
|
114
|
-
curationId: string().min(1).max(ID_MAX).optional(),
|
|
115
|
-
items: array(WidgetChatCardSchema).min(1).max(20)
|
|
116
|
-
});
|
|
117
|
-
var WidgetChatEscalatedEventSchema = object({ type: literal("escalated") });
|
|
118
|
-
/**
|
|
119
|
-
* A real Shopify checkout handoff — `checkout_handoff` (the concierge tool)
|
|
120
|
-
* emits this as a `widgetEvent` sidecar so the widget can render a "Go to
|
|
121
|
-
* checkout" control instead of the model reciting a raw URL. `url` is a
|
|
122
|
-
* SERVER-BUILT Shopify cart permalink (`apps/api/src/catalog/checkout-permalink.ts`)
|
|
123
|
-
* — never a client- or model-supplied value; it carries no internal
|
|
124
|
-
* identifier, only Shopify variant ids/quantities and an opaque attribution
|
|
125
|
-
* token (see that module's doc comment).
|
|
126
|
-
*/
|
|
127
|
-
var WidgetChatCheckoutEventSchema = object({
|
|
128
|
-
type: literal("checkout"),
|
|
129
|
-
handoffId: string().min(1).max(ID_MAX),
|
|
130
|
-
url: httpUrl(),
|
|
131
|
-
itemCount: number().int().positive()
|
|
132
|
-
});
|
|
133
|
-
var WidgetChatDoneEventSchema = object({
|
|
134
|
-
type: literal("done"),
|
|
135
|
-
turnId: string().min(1)
|
|
136
|
-
});
|
|
137
|
-
var WidgetChatErrorEventSchema = object({
|
|
138
|
-
type: literal("error"),
|
|
139
|
-
/** Safe to show the visitor as-is — never a raw exception message or stack. */
|
|
140
|
-
message: string().min(1).max(CARD_TEXT_MAX)
|
|
141
|
-
});
|
|
142
|
-
/** The full SSE event union — every `event:`/`data:` pair `/widget/chat` may write. */
|
|
143
|
-
var WidgetChatSseEventSchema = discriminatedUnion("type", [
|
|
144
|
-
WidgetChatTextDeltaEventSchema,
|
|
145
|
-
WidgetChatCardsEventSchema,
|
|
146
|
-
WidgetChatEscalatedEventSchema,
|
|
147
|
-
WidgetChatCheckoutEventSchema,
|
|
148
|
-
WidgetChatDoneEventSchema,
|
|
149
|
-
WidgetChatErrorEventSchema
|
|
150
|
-
]);
|
|
151
|
-
/**
|
|
152
|
-
* What a tool result may carry, under an `output.widgetEvent` key, to ask the
|
|
153
|
-
* chat loop to forward one of these as its own SSE event. Deliberately a
|
|
154
|
-
* NARROWER union than {@link WidgetChatSseEventSchema} — `text-delta`,
|
|
155
|
-
* `done`, and `error` are lifecycle events the runtime alone controls; a tool
|
|
156
|
-
* asserting one of those could inject a fake "done" mid-stream or spoof a
|
|
157
|
-
* fake error to the visitor.
|
|
158
|
-
*/
|
|
159
|
-
var WidgetToolEventSchema = discriminatedUnion("type", [
|
|
160
|
-
WidgetChatCardsEventSchema,
|
|
161
|
-
WidgetChatEscalatedEventSchema,
|
|
162
|
-
WidgetChatCheckoutEventSchema
|
|
163
|
-
]);
|
|
164
|
-
/**
|
|
165
|
-
* ## Storefront reports — the OTHER direction, and why they are not messages
|
|
166
|
-
*
|
|
167
|
-
* A chat request carries EITHER a shopper `message` or a `report`: a typed
|
|
168
|
-
* statement of something the STOREFRONT did, which the shopper never typed.
|
|
169
|
-
* Today there is exactly one kind, `cart_add`, sent by
|
|
170
|
-
* `@saar-ai/web-widget`'s `ConciergeWidget` the moment a bridge add resolves,
|
|
171
|
-
* so the concierge can answer with something that goes WITH the item.
|
|
172
|
-
*
|
|
173
|
-
* It replaced a free-text `Added <title> to cart` sentence sent over the
|
|
174
|
-
* ordinary shopper message channel, which had three defects a shape fixes:
|
|
175
|
-
* a shopper who TYPED those words got the storefront's treatment; the
|
|
176
|
-
* synthetic sentence persisted as a shopper line in the operator's
|
|
177
|
-
* transcript; and the server matched it by its exact wording, so any change
|
|
178
|
-
* to how a card renders a title broke the match with nothing failing.
|
|
179
|
-
*
|
|
180
|
-
* **The sentence the model sees is composed SERVER-side** from these fields
|
|
181
|
-
* (`apps/api/src/widget/widget-chat.service.ts`'s
|
|
182
|
-
* `composeStorefrontReportText`) — the client no longer authors any part of
|
|
183
|
-
* the model's input, which is what makes shopper prose and a storefront
|
|
184
|
-
* report structurally impossible to confuse.
|
|
185
|
-
*
|
|
186
|
-
* **Still client-asserted, and that is unchanged.** A report is trusted
|
|
187
|
-
* exactly as far as the chat token that carried it: whoever holds a session
|
|
188
|
-
* can claim an add that never happened, precisely as they could type the old
|
|
189
|
-
* sentence. Cross-verifying a report against the server's own
|
|
190
|
-
* `CheckoutHandoffService.recordCartAdd` record is explicitly out of scope —
|
|
191
|
-
* the win here is typing, non-collision with shopper prose, and a turn the
|
|
192
|
-
* console can tell apart, not a new trust boundary.
|
|
193
|
-
*/
|
|
194
|
-
var REPORT_TITLE_MAX = CARD_TEXT_MAX;
|
|
195
|
-
/**
|
|
196
|
-
* The storefront reporting a completed add. `title` is the card's own
|
|
197
|
-
* display title (what the shopper saw); the ids are the catalog's, carried
|
|
198
|
-
* so a later consumer can join the report to a product without re-matching
|
|
199
|
-
* on prose.
|
|
200
|
-
*/
|
|
201
|
-
var WidgetCartAddReportSchema = object({
|
|
202
|
-
kind: literal("cart_add"),
|
|
203
|
-
/**
|
|
204
|
-
* Trimmed before it is bounded, so a whitespace-only title is a
|
|
205
|
-
* rejection rather than a report that names nothing: the server trims
|
|
206
|
-
* the title again when it composes its line, and `min(1)` on the raw
|
|
207
|
-
* string would let `" "` through to `added ""`.
|
|
208
|
-
*/
|
|
209
|
-
title: string().trim().min(1).max(REPORT_TITLE_MAX),
|
|
210
|
-
quantity: number().int().min(1).max(999),
|
|
211
|
-
/** The INTERNAL catalog UUID — same field, same meaning, as {@link WidgetChatCardSchema}'s. */
|
|
212
|
-
variantId: string().min(1).max(ID_MAX).optional(),
|
|
213
|
-
productId: string().min(1).max(ID_MAX).optional()
|
|
214
|
-
}).strict();
|
|
215
|
-
/**
|
|
216
|
-
* Every report kind a chat request may carry. A discriminated union of one
|
|
217
|
-
* today — the shape a second kind (`cart_removed`, `checkout_started`) slots
|
|
218
|
-
* into without touching either side's parse code.
|
|
219
|
-
*/
|
|
220
|
-
var WidgetChatReportSchema = discriminatedUnion("kind", [WidgetCartAddReportSchema]);
|
|
221
|
-
/**
|
|
222
|
-
* Parse a request body's `report` field. Never throws — the caller decides
|
|
223
|
-
* whether `null` means "absent" (no report was sent) or "malformed", which
|
|
224
|
-
* `apps/api`'s widget chat controller distinguishes by checking presence
|
|
225
|
-
* first and rejecting a present-but-unparseable value with a 400.
|
|
226
|
-
*/
|
|
227
|
-
function parseWidgetChatReport(value) {
|
|
228
|
-
const parsed = WidgetChatReportSchema.safeParse(value);
|
|
229
|
-
return parsed.success ? parsed.data : null;
|
|
230
|
-
}
|
|
231
|
-
/** Parse a tool's raw output for an optional, well-shaped `widgetEvent`. Never throws. */
|
|
232
|
-
function extractWidgetToolEvent(output) {
|
|
233
|
-
if (typeof output !== "object" || output === null) return null;
|
|
234
|
-
const candidate = output["widgetEvent"];
|
|
235
|
-
if (candidate === void 0) return null;
|
|
236
|
-
const parsed = WidgetToolEventSchema.safeParse(candidate);
|
|
237
|
-
return parsed.success ? parsed.data : null;
|
|
238
|
-
}
|
|
239
|
-
//#endregion
|
|
240
|
-
export { WidgetCartAddReportSchema, WidgetChatCardSchema, WidgetChatCardsEventSchema, WidgetChatCheckoutEventSchema, WidgetChatDoneEventSchema, WidgetChatErrorEventSchema, WidgetChatEscalatedEventSchema, WidgetChatReportSchema, WidgetChatSseEventSchema, WidgetChatTextDeltaEventSchema, WidgetToolEventSchema, extractWidgetToolEvent, parseWidgetChatReport };
|