@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.
@@ -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 };