@saar-ai/web-widget 0.7.0 → 0.8.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,4 +1,182 @@
1
- import { a as httpUrl, c as number, i as discriminatedUnion, l as object, n as array, o as literal, r as boolean, t as _enum, u as string } from "./schemas-Bl_6mxe4.js";
1
+ import { a as httpUrl, c as number, d as string, i as discriminatedUnion, l as object, n as array, o as literal, r as boolean, t as _enum, u as record } from "./schemas-D-uDc-9q.js";
2
+ //#region ../widget-protocol/dist/act.js
3
+ /**
4
+ * ACT EVENTS — the concierge moving the store, rather than only describing it.
5
+ *
6
+ * `cards` and `add-to-cart` (`./chat.ts`) already let the concierge put
7
+ * something on screen and ask for something to be bought. These three let it
8
+ * DRIVE the page the shopper is already on: walk them to a collection, narrow
9
+ * what that collection shows, or point at one card without moving them
10
+ * anywhere at all. Same sidecar mechanism as `add-to-cart` — a commerce tool
11
+ * returns one of these under `widgetEvent`, the server strips it before the
12
+ * model can read it back, and `@saar-ai/web-widget` performs it through
13
+ * `@saar-ai/widget-bridge`.
14
+ *
15
+ * ## Why a separate file from `chat.ts`
16
+ *
17
+ * `chat.ts` owns the SSE lifecycle and the storefront REPORT vocabulary; this
18
+ * file owns the act vocabulary. They meet in exactly one place —
19
+ * `WidgetToolEventSchema`'s union — which keeps a new act event from touching
20
+ * the report schemas at all.
21
+ *
22
+ * ## The rule every schema here encodes: the server names the destination
23
+ *
24
+ * A model that can type a URL can type ANY URL, and a concierge that walks a
25
+ * shopper to an attacker's page is worse than one that cannot navigate at all.
26
+ * So no field on this wire is model prose:
27
+ *
28
+ * - {@link SameOriginPathSchema} admits only a ROOT-RELATIVE path. Not a
29
+ * scheme, not a host, not a protocol-relative `//evil.example`, not a
30
+ * backslash a browser would normalise into one. The host page resolves it
31
+ * against its own origin, so "same-origin" is structural rather than a
32
+ * check that could be got wrong — strictly stronger than an origin
33
+ * allow-list, which still has to parse an attacker-chosen string correctly.
34
+ * - Every id-shaped field is a catalogue id the SERVER resolved
35
+ * (`apps/api/src/catalog/tools/`), never one the model invented — the tools
36
+ * throw `NOT_FOUND` rather than emit an event for a product that does not
37
+ * exist.
38
+ * - `reason` is the ONE free-text field, it is bounded, and the widget never
39
+ * renders it. It exists so a console timeline can say why the shopper was
40
+ * moved.
41
+ */
42
+ /** Bound for an id-shaped field — mirrors `chat.ts`'s own `ID_MAX`. */
43
+ var ID_MAX$1 = 200;
44
+ /** Bound for a path. Generous (Shopify facet queries are long) but finite. */
45
+ var PATH_MAX = 2048;
46
+ /** Bound for the operator-facing "why" on a navigate. Never rendered to the shopper. */
47
+ var REASON_MAX = 200;
48
+ /** Bound for a display title carried alongside a spotlight. */
49
+ var TITLE_MAX = 500;
50
+ /** How many distinct facets one `filter` event may carry. A narrowing, not a re-query. */
51
+ var MAX_FACETS = 10;
52
+ /** How many values one facet may carry (a multi-select colour, say). */
53
+ var MAX_FACET_VALUES = 10;
54
+ var FACET_KEY_MAX = 64;
55
+ var FACET_VALUE_MAX = 255;
56
+ /**
57
+ * A ROOT-RELATIVE, same-origin path — `/collections/rugs?filter.p.vendor=X`.
58
+ *
59
+ * The character class is the security boundary and is deliberately narrow:
60
+ *
61
+ * - must begin with exactly one `/` — so no `https:`, no `javascript:`, no
62
+ * bare `evil.example/x` a browser would resolve as a relative sibling;
63
+ * - the second character may not be `/` or `\` — `//evil.example` is a
64
+ * protocol-relative URL, and browsers normalise `/\evil.example` into one;
65
+ * - no whitespace and no backslash anywhere — both are the raw material of
66
+ * every "URL that reads as one origin and resolves as another" trick, and
67
+ * no legitimate storefront path needs either (a space is `%20`).
68
+ *
69
+ * Anything else is a rejection, never a repair: a path this schema had to fix
70
+ * is a path nobody meant to emit.
71
+ */
72
+ var SameOriginPathSchema = string().min(1).max(PATH_MAX).regex(/^\/(?![/\\])[^\s\\]*$/, "must be a root-relative, same-origin path (e.g. \"/collections/rugs\")");
73
+ /** Which kind of destination a {@link WidgetChatNavigateEventSchema} resolved. Drives nothing in the widget; carried so a console timeline can read the intent without re-parsing the path. */
74
+ var NavigateTargetSchema = _enum([
75
+ "product",
76
+ "collection",
77
+ "search",
78
+ "cart",
79
+ "url"
80
+ ]);
81
+ /**
82
+ * The three act events as one union — imported by `./chat.ts` and spread into
83
+ * {@link WidgetToolEventSchema} and the SSE union there, so a fourth act event
84
+ * is added HERE and reaches both unions without touching either.
85
+ */
86
+ var ACT_EVENT_SCHEMAS = [
87
+ object({
88
+ type: literal("navigate"),
89
+ /** Root-relative, same-origin. The host bridge resolves it against the page's own origin. */
90
+ url: SameOriginPathSchema,
91
+ target: NavigateTargetSchema,
92
+ /** Why the shopper was moved — operator-facing, bounded, never rendered to the shopper. */
93
+ reason: string().trim().min(1).max(REASON_MAX)
94
+ }),
95
+ object({
96
+ type: literal("filter"),
97
+ /**
98
+ * Where to apply the filters, when the concierge named a collection the
99
+ * shopper is not currently on. Absent ⇒ the page they are already on, which
100
+ * is what `applyFilter` operates on.
101
+ */
102
+ collectionUrl: SameOriginPathSchema.optional(),
103
+ filters: record(string().trim().min(1).max(FACET_KEY_MAX), array(string().trim().min(1).max(FACET_VALUE_MAX)).min(1).max(MAX_FACET_VALUES)).refine((value) => Object.keys(value).length >= 1 && Object.keys(value).length <= MAX_FACETS, { message: `filters must carry between 1 and ${MAX_FACETS} facets` })
104
+ }),
105
+ object({
106
+ type: literal("spotlight"),
107
+ /** The INTERNAL catalog UUID — the same field, same meaning, as a card's. */
108
+ productId: string().min(1).max(ID_MAX$1),
109
+ /**
110
+ * The storefront handle — a SLUG, never a path, bounded by the same
111
+ * character class a card's `handle` uses and for the same reason: the widget
112
+ * builds a `a[href*="/products/<handle>"]` selector out of it.
113
+ */
114
+ handle: string().min(1).max(ID_MAX$1).regex(/^[a-z0-9]+(?:-[a-z0-9]+)*$/i).optional(),
115
+ /**
116
+ * The PLATFORM-native product id (Shopify's numeric id), extracted
117
+ * server-side from the product's provider GID by the same parser the
118
+ * checkout permalink uses — never a string-slice, absent when the external
119
+ * id is not a recognised GID.
120
+ */
121
+ platformProductId: string().min(1).max(ID_MAX$1).optional(),
122
+ /** The card's display title — the widget's accessible announcement says which product it pointed at. */
123
+ title: string().trim().min(1).max(TITLE_MAX).optional()
124
+ })
125
+ ];
126
+ Object.freeze([
127
+ "navigate",
128
+ "filter",
129
+ "spotlight"
130
+ ]);
131
+ /**
132
+ * The storefront reporting a spotlight it could NOT perform — the mirror of
133
+ * `cart_add_failed` (`./chat.ts`), and for the identical reason: the server
134
+ * asked for something that happens in a browser it has no handle on, and only
135
+ * the widget learns the answer.
136
+ *
137
+ * A card that is simply not on this page is the ordinary case — the shopper
138
+ * scrolled past it, the collection paginated, the theme lazy-renders. Without
139
+ * this report the concierge says "it's the one highlighted on your screen" and
140
+ * nothing is highlighted, which on a CALL the shopper cannot even see is
141
+ * wrong.
142
+ *
143
+ * `.strict()`, and deliberately no "reason" enum: the widget knows only
144
+ * "found" or "not found", and a richer vocabulary would be a claim about a
145
+ * merchant's DOM that this code cannot make.
146
+ */
147
+ var WidgetSpotlightFailedReportSchema = object({
148
+ kind: literal("spotlight_failed"),
149
+ /** The product the concierge pointed at, so the model can name it in its correction. */
150
+ title: string().trim().min(1).max(TITLE_MAX),
151
+ productId: string().min(1).max(ID_MAX$1).optional()
152
+ }).strict();
153
+ /**
154
+ * The storefront reporting a `navigate` it could NOT perform — the third
155
+ * member of the same family as `cart_add_failed` and
156
+ * {@link WidgetSpotlightFailedReportSchema}, and it exists for the identical
157
+ * reason: the tool returned `status: 'requested'` because the move happens in
158
+ * a browser the server has no handle on, and only the widget learns the
159
+ * answer.
160
+ *
161
+ * A bridge with no `navigate` is the ordinary case, not an exotic one: §3's
162
+ * "every optional method is genuinely optional" means a host can ship a
163
+ * read-only bridge, and a `NextBridge`-style host can refuse a move its router
164
+ * cannot make. Without this report the concierge has said "taking you to the
165
+ * cushions" — out loud, on a call, where the shopper cannot see that the page
166
+ * did not change — and nothing ever corrects it.
167
+ *
168
+ * **No path and no url**, deliberately. The one thing the guardrails forbid
169
+ * the concierge to say is a URL, and a report carrying one puts it in the
170
+ * model's context with nothing but an instruction standing between it and the
171
+ * shopper's ear. `target` is the KIND of destination, which is all a
172
+ * correction needs ("I can't open your basket from here").
173
+ */
174
+ var WidgetNavigateFailedReportSchema = object({
175
+ kind: literal("navigate_failed"),
176
+ /** What kind of page the concierge was trying to open. Never the path. */
177
+ target: NavigateTargetSchema.optional()
178
+ }).strict();
179
+ //#endregion
2
180
  //#region ../widget-protocol/dist/chat.js
3
181
  /**
4
182
  * The webchat SSE wire contract, and the sidecar `widgetEvent` a tool result
@@ -221,6 +399,7 @@ var WidgetChatSseEventSchema = discriminatedUnion("type", [
221
399
  WidgetChatEscalatedEventSchema,
222
400
  WidgetChatCheckoutEventSchema,
223
401
  WidgetChatAddToCartEventSchema,
402
+ ...ACT_EVENT_SCHEMAS,
224
403
  WidgetChatDoneEventSchema,
225
404
  WidgetChatErrorEventSchema
226
405
  ]);
@@ -236,7 +415,8 @@ var WidgetToolEventSchema = discriminatedUnion("type", [
236
415
  WidgetChatCardsEventSchema,
237
416
  WidgetChatEscalatedEventSchema,
238
417
  WidgetChatCheckoutEventSchema,
239
- WidgetChatAddToCartEventSchema
418
+ WidgetChatAddToCartEventSchema,
419
+ ...ACT_EVENT_SCHEMAS
240
420
  ]);
241
421
  /**
242
422
  * ## Storefront reports — the OTHER direction, and why they are not messages
@@ -342,7 +522,12 @@ var WidgetCartAddFailedReportSchema = object({
342
522
  * costs the shopper nothing, and the widget's own status line still says the
343
523
  * add did not land.
344
524
  */
345
- var WidgetChatReportSchema = discriminatedUnion("kind", [WidgetCartAddReportSchema, WidgetCartAddFailedReportSchema]);
525
+ var WidgetChatReportSchema = discriminatedUnion("kind", [
526
+ WidgetCartAddReportSchema,
527
+ WidgetCartAddFailedReportSchema,
528
+ WidgetSpotlightFailedReportSchema,
529
+ WidgetNavigateFailedReportSchema
530
+ ]);
346
531
  /**
347
532
  * Parse a request body's `report` field. Never throws — the caller decides
348
533
  * whether `null` means "absent" (no report was sent) or "malformed", which