@saar-ai/web-widget 0.8.0 → 0.10.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 (54) hide show
  1. package/dist/chunks/{chat-e1afSRBr.js → chat-CU9VPqVO.js} +260 -37
  2. package/dist/chunks/{host-widget-Ce-l1xu1.js → host-widget-BtiYIMwb.js} +5638 -350
  3. package/dist/chunks/{schemas-D-uDc-9q.js → schemas-YN3wGSGZ.js} +7 -4
  4. package/dist/chunks/{telemetry-CBblNC6C.js → telemetry-B1xBTk1s.js} +16 -1
  5. package/dist/dock/dock-drag.d.ts +5 -5
  6. package/dist/dock/dock-drag.d.ts.map +1 -1
  7. package/dist/dock/dock-float.d.ts +116 -0
  8. package/dist/dock/dock-float.d.ts.map +1 -0
  9. package/dist/dock/dock-motion.d.ts +61 -6
  10. package/dist/dock/dock-motion.d.ts.map +1 -1
  11. package/dist/dock/dock-pill.d.ts +18 -1
  12. package/dist/dock/dock-pill.d.ts.map +1 -1
  13. package/dist/dock/dock-row.d.ts +128 -10
  14. package/dist/dock/dock-row.d.ts.map +1 -1
  15. package/dist/dock/dock-sheet.d.ts.map +1 -1
  16. package/dist/dock/dock-state.d.ts +129 -9
  17. package/dist/dock/dock-state.d.ts.map +1 -1
  18. package/dist/dock/dock.d.ts +137 -25
  19. package/dist/dock/dock.d.ts.map +1 -1
  20. package/dist/dock/geometry.d.ts +129 -3
  21. package/dist/dock/geometry.d.ts.map +1 -1
  22. package/dist/generated/widget-css.d.ts.map +1 -1
  23. package/dist/host-routes.d.ts +187 -0
  24. package/dist/host-routes.d.ts.map +1 -0
  25. package/dist/host-widget.d.ts +78 -2
  26. package/dist/host-widget.d.ts.map +1 -1
  27. package/dist/index.d.ts +1 -1
  28. package/dist/index.d.ts.map +1 -1
  29. package/dist/index.js +4 -3889
  30. package/dist/messages.d.ts +88 -1
  31. package/dist/messages.d.ts.map +1 -1
  32. package/dist/mount.d.ts +10 -1
  33. package/dist/mount.d.ts.map +1 -1
  34. package/dist/next/index.js +1 -1
  35. package/dist/rope-knot.d.ts +67 -0
  36. package/dist/rope-knot.d.ts.map +1 -1
  37. package/dist/theme/derive.d.ts +1 -1
  38. package/dist/theme/derive.d.ts.map +1 -1
  39. package/dist/use-chat-session.d.ts +87 -33
  40. package/dist/use-chat-session.d.ts.map +1 -1
  41. package/dist/use-voice-session.d.ts +13 -8
  42. package/dist/use-voice-session.d.ts.map +1 -1
  43. package/dist/voice-widget.d.ts +22 -1
  44. package/dist/voice-widget.d.ts.map +1 -1
  45. package/dist/widget-cards.d.ts +21 -1
  46. package/dist/widget-cards.d.ts.map +1 -1
  47. package/dist/widget-cart-summary.d.ts +10 -1
  48. package/dist/widget-cart-summary.d.ts.map +1 -1
  49. package/dist/widget.css +1 -1
  50. package/package.json +7 -3
  51. package/src/styles/concierge.css +528 -65
  52. package/src/styles/dock-surface.css +284 -0
  53. package/src/styles/tokens.css +22 -6
  54. package/src/styles/widget-entry.css +3 -0
@@ -1,4 +1,4 @@
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";
1
+ import { a as httpUrl, c as number, d as string, f as uuid, i as discriminatedUnion, l as object, n as array, o as literal, r as boolean, t as _enum, u as record } from "./schemas-YN3wGSGZ.js";
2
2
  //#region ../widget-protocol/dist/act.js
3
3
  /**
4
4
  * ACT EVENTS — the concierge moving the store, rather than only describing it.
@@ -177,6 +177,37 @@ var WidgetNavigateFailedReportSchema = object({
177
177
  target: NavigateTargetSchema.optional()
178
178
  }).strict();
179
179
  //#endregion
180
+ //#region ../widget-protocol/dist/currency.js
181
+ /**
182
+ * The ISO 4217 currency-code schema every currency field on this wire
183
+ * shares — three LETTERS, case preserved, never a bare length check.
184
+ *
185
+ * ## Why the charset is the control, not the length
186
+ *
187
+ * `z.string().length(3)` and this schema admit the same LENGTH, but
188
+ * `"\n- "` is three characters and only one of the schemas below refuses
189
+ * it. A currency value that reaches a model as prose — `chat.ts`'s cards,
190
+ * `@wesence/agent-core`'s `renderShopperCartForModel` — sits on the same
191
+ * line as a price, and a newline there forges a line boundary in a block
192
+ * whose entire legibility rests on one line per item. The titles beside it
193
+ * have always been trimmed/bounded for exactly this reason; a currency code
194
+ * was left at `length(3)` because three characters "looks safe," which is
195
+ * precisely the assumption this regex refuses to make.
196
+ *
197
+ * ## Why this lives in its own module, not just `chat.ts`
198
+ *
199
+ * This schema used to be declared privately inside `chat.ts` and never
200
+ * exported. `catalog.ts` and `curation.ts` — this same package — each grew
201
+ * their own `z.string().length(3)` instead of importing it, and
202
+ * `@wesence/agent-core`'s `shopper-cart.ts` grew a fourth copy of the regex
203
+ * itself rather than importing this one. An unexported validator gets
204
+ * re-invented at every call site that needs it, and re-invention is exactly
205
+ * how two of those four copies lost the hardening. This module is the one
206
+ * place `CURRENCY_CODE` is declared; every schema on both legs of a widget
207
+ * conversation imports it from here rather than restating it.
208
+ */
209
+ var CURRENCY_CODE = string().regex(/^[A-Za-z]{3}$/, "must be a three-letter ISO 4217 currency code");
210
+ //#endregion
180
211
  //#region ../widget-protocol/dist/chat.js
181
212
  /**
182
213
  * The webchat SSE wire contract, and the sidecar `widgetEvent` a tool result
@@ -242,14 +273,6 @@ var CARD_TEXT_MAX = 500;
242
273
  /** Bound for an id-shaped field (product/variant/curation ids). */
243
274
  var ID_MAX = 200;
244
275
  /**
245
- * An ISO 4217 currency code, as a schema — three LETTERS, case preserved.
246
- *
247
- * Shared by every currency field on this wire so none of them can drift back
248
- * to a bare `length(3)`. See {@link WidgetChatCardSchema}'s `currency` for the
249
- * prompt-injection reason the charset matters and not just the length.
250
- */
251
- var CURRENCY_CODE = string().regex(/^[A-Za-z]{3}$/, "must be a three-letter ISO 4217 currency code");
252
- /**
253
276
  * One product/curation card. `priceMinor` is the ISO 4217 minor-unit integer
254
277
  * (cents, paise, …) — never a float — and `currency` is the ISO 4217 code, so
255
278
  * the widget formats price itself rather than trusting a pre-formatted
@@ -303,20 +326,150 @@ var WidgetChatCardSchema = object({
303
326
  currency: CURRENCY_CODE,
304
327
  available: boolean(),
305
328
  /** Short, optional "why this" — e.g. "matches your search". Never a price/stock claim. */
306
- reason: string().max(CARD_TEXT_MAX).optional()
329
+ reason: string().max(CARD_TEXT_MAX).optional(),
330
+ /**
331
+ * `true` when the product has MORE THAN ONE sellable variant, so the
332
+ * shopper has to choose one before anything can go in their cart (SAA-175,
333
+ * owner rule: never add a variant the shopper did not choose). Omitted
334
+ * otherwise — never `false`.
335
+ *
336
+ * `variantId`/`platformVariantId`/`priceMinor` on such a card still
337
+ * describe ONE variant — the representative `build_curation` priced the card
338
+ * with (`pickRepresentativeVariant`) — and that is exactly why they must not
339
+ * be added: the shopper never picked it. `@saar-ai/web-widget` replaces the
340
+ * card's Add button with "Choose options", which asks the concierge (whose
341
+ * `add_to_cart` answers `needs_variant_choice`) or opens the product page.
342
+ *
343
+ * A bare literal, deliberately: it carries no option names, labels or
344
+ * prices, so it adds no merchant text to the wire and nothing the model
345
+ * could be handed.
346
+ *
347
+ * **Deploy skew.** A widget bundle that predates this field ignores it: the
348
+ * typed leg casts `items` without parsing, and this schema is a plain
349
+ * `z.object`, which STRIPS an unknown key rather than refusing the card. An
350
+ * old widget therefore draws its old Add button, which is what it did
351
+ * before the field existed — the gap closes when the widget ships, and no
352
+ * capability negotiation is needed. Keep this schema non-strict for that
353
+ * reason; `__tests__/chat.variant-choice.test.ts` pins it.
354
+ */
355
+ variantChoiceRequired: literal(true).optional()
307
356
  });
308
357
  var WidgetChatTextDeltaEventSchema = object({
309
358
  type: literal("text-delta"),
310
359
  delta: string()
311
360
  });
312
- /** Max cards in one event — a chat bubble, not a catalog page. */
361
+ /**
362
+ * Max cards in one event — a chat bubble, not a catalog page.
363
+ *
364
+ * Exported so `build_curation` (`apps/api/src/catalog/tools/build-curation.tool.ts`)
365
+ * can cap what it renders BEFORE persisting, rather than building an
366
+ * oversized array and finding out only when this schema (or
367
+ * {@link buildWidgetChatCardsEvent}'s own cap, for replay) refuses it. A
368
+ * second, hand-typed `20` here would be exactly the kind of drift this
369
+ * package exists to prevent.
370
+ */
313
371
  var MAX_CARDS_PER_EVENT = 20;
314
372
  var WidgetChatCardsEventSchema = object({
315
373
  type: literal("cards"),
316
374
  /** Correlates this render back to whichever tool call produced it, when the tool supplies one. */
317
375
  curationId: string().min(1).max(ID_MAX).optional(),
318
- items: array(WidgetChatCardSchema).min(1).max(MAX_CARDS_PER_EVENT)
376
+ items: array(WidgetChatCardSchema).min(1).max(20)
319
377
  });
378
+ /**
379
+ * The optional {@link WidgetChatCard} fields a validation failure may drop
380
+ * WITHOUT losing the card — a card missing its image or its PDP handle is
381
+ * still a usable recommendation. `title`/`currency`/`priceMinor`/`productId`/
382
+ * `available` stay OUT of this list on purpose: there is no honest way to
383
+ * show a product with no price, or a price with no currency, so a failure in
384
+ * one of those drops the whole card instead (see {@link buildWidgetChatCard}).
385
+ *
386
+ * `variantChoiceRequired` is droppable because every producer writes it as a
387
+ * literal `true` or not at all, so a refusal there is a producer bug, and a
388
+ * producer bug should not cost the shopper the recommendation.
389
+ */
390
+ var DROPPABLE_CARD_FIELDS = [
391
+ "variantId",
392
+ "platformVariantId",
393
+ "imageUrl",
394
+ "handle",
395
+ "reason",
396
+ "variantChoiceRequired"
397
+ ];
398
+ /**
399
+ * Generic "try the whole candidate; if every refusal is on a DROPPABLE field,
400
+ * drop just those and retry once" parser — no card-specific knowledge at all.
401
+ *
402
+ * Exported so `apps/api`'s `act-destinations.ts` `buildActEvent`
403
+ * (`apply_filter`/`spotlight`/`navigate`'s events) can DELEGATE to this
404
+ * instead of keeping its own copy of the identical safeParse/prune/retry
405
+ * algorithm. The dependency has to run this direction — this package cannot
406
+ * import from `apps/api`, which depends on it — so this generic form lives
407
+ * here and `buildActEvent` becomes a thin wrapper around it. One
408
+ * implementation, called from both sides, rather than two that can drift on
409
+ * the next edit to either.
410
+ */
411
+ function buildWithDroppableFields(schema, candidate, droppable = []) {
412
+ const first = schema.safeParse(candidate);
413
+ if (first.success) return first.data;
414
+ const offending = new Set(first.error.issues.map((issue) => String(issue.path[0] ?? "")));
415
+ const pruned = { ...candidate };
416
+ let droppedAny = false;
417
+ for (const key of droppable) {
418
+ if (!offending.has(key)) continue;
419
+ delete pruned[key];
420
+ droppedAny = true;
421
+ }
422
+ if (!droppedAny) return null;
423
+ const second = schema.safeParse(pruned);
424
+ return second.success ? second.data : null;
425
+ }
426
+ /**
427
+ * Build ONE validated {@link WidgetChatCard} from a raw candidate record, or
428
+ * `null` when it cannot be rendered as a card at all.
429
+ *
430
+ * Tries the candidate whole first; if every refusal is on a
431
+ * {@link DROPPABLE_CARD_FIELDS} field, drops JUST those fields and retries
432
+ * once. A REQUIRED field failing has no fallback, so this returns `null` and
433
+ * the caller drops the whole candidate.
434
+ *
435
+ * ## Why this lives here, callable by both the live and the replay leg
436
+ *
437
+ * `build_curation` (`apps/api/src/catalog/tools/build-curation.tool.ts`, the
438
+ * live SSE leg) and {@link buildWidgetChatCardsEvent} (the replay leg, for a
439
+ * resumed session) each turn catalogue data into cards, and a catalogue row
440
+ * with one malformed optional field — an image URL on an underscore host, an
441
+ * IP-address image host, a unicode handle — is exactly as malformed whichever
442
+ * leg reads it. Before this function existed, only the live leg had this
443
+ * drop-the-field-not-the-card contract (via `apps/api`'s own `buildActEvent`);
444
+ * replay did a single `safeParse` with no retry and dropped the WHOLE card
445
+ * for a field the live leg could shrug off. A shopper who reloaded
446
+ * mid-conversation saw fewer cards than the turn had actually streamed. Both
447
+ * legs now call this one function, so the SAME product produces the SAME
448
+ * card — field dropped, not card dropped — regardless of which leg built it.
449
+ *
450
+ * ## An empty/whitespace-only string on a DROPPABLE field is normalized to
451
+ * absent, BEFORE either leg's candidate ever reaches {@link WidgetChatCardSchema}
452
+ *
453
+ * Live and replay build their OWN candidate record from different source
454
+ * shapes and, independently, made different choices about what "no reason"
455
+ * looks like: one omits an empty `reason` (a truthiness check), the other
456
+ * keeps it as `reason: ''` (a not-null check) — and {@link WidgetChatCardSchema}'s
457
+ * `reason` has no `.min(1)`, so `''` parses cleanly on either side, meaning
458
+ * neither call site's own guard was ever exercised by the schema and the two
459
+ * legs rendered DIFFERENT cards for the identical row (one with no `reason`
460
+ * key, one with `reason: ''`). Normalizing here — in the ONE function both
461
+ * legs call, rather than requiring every call site to independently agree on
462
+ * a null convention — is what actually closes that gap, for `reason` and for
463
+ * any other droppable string field a future caller adds the same way.
464
+ */
465
+ function buildWidgetChatCard(candidate) {
466
+ const normalized = { ...candidate };
467
+ for (const key of DROPPABLE_CARD_FIELDS) {
468
+ const value = normalized[key];
469
+ if (typeof value === "string" && value.trim() === "") delete normalized[key];
470
+ }
471
+ return buildWithDroppableFields(WidgetChatCardSchema, normalized, DROPPABLE_CARD_FIELDS);
472
+ }
320
473
  var WidgetChatEscalatedEventSchema = object({ type: literal("escalated") });
321
474
  /**
322
475
  * A real Shopify checkout handoff — `checkout_handoff` (the concierge tool)
@@ -478,8 +631,9 @@ var WidgetCartAddReportSchema = object({
478
631
  *
479
632
  * ## Why this kind has to exist
480
633
  *
481
- * `add_to_cart` (`apps/api/src/catalog/tools/add-to-cart.tool.ts`) returns
482
- * `status: 'requested'` and can never return more: the cart lives in the
634
+ * `add_to_cart` (`apps/api/src/catalog/tools/add-to-cart.tool.ts`) has no
635
+ * status meaning "added": at most `status: 'requested'`, the only answer that
636
+ * emits an event. The cart lives in the
483
637
  * shopper's browser, behind their own session cookie, and the server has no
484
638
  * handle on it. The add is performed afterwards by `@saar-ai/web-widget`'s
485
639
  * `ConciergeWidget` (`performAgentCartAdd`), and when the host bridge rejects
@@ -511,6 +665,40 @@ var WidgetCartAddFailedReportSchema = object({
511
665
  productId: string().min(1).max(ID_MAX).optional()
512
666
  }).strict();
513
667
  /**
668
+ * The storefront reporting that the shopper pressed "Choose options" on a card
669
+ * for a product with more than one sellable variant
670
+ * ({@link WidgetChatCardSchema}'s `variantChoiceRequired`, SAA-175).
671
+ *
672
+ * ## Why a report, and not a sentence the widget types for the shopper
673
+ *
674
+ * The first cut sent "What options does {title} come in?" as an ordinary
675
+ * shopper message. Review found three defects in that, and a typed report
676
+ * fixes all three:
677
+ *
678
+ * - **Injection.** The title is merchant data, and it landed verbatim in a
679
+ * USER-role turn, the one place the model is told to take instructions from
680
+ * the shopper. Here the server composes the model's line from `productId`
681
+ * alone (`composeStorefrontReportText`); `title` never reaches the model.
682
+ * - **Misattribution.** The desk transcript showed the widget's sentence as
683
+ * the shopper's own words. A report renders as a storefront event.
684
+ * - **Loop.** A free-text line is indistinguishable from the shopper asking
685
+ * again, so nothing could tell the server this turn is an open variant
686
+ * question. The report kind is that signal: the server stands its forced
687
+ * curation down for it.
688
+ *
689
+ * `productId` is the catalog UUID the card carries, validated as one, because
690
+ * it is the only id the model is told to pass to `add_to_cart`. `title` is the
691
+ * card's display title, trimmed and bounded like every other report title, and
692
+ * kept ONLY as a label for the operator's transcript. `.strict()`: no
693
+ * `variantId` can ride along, since a variant is exactly what the shopper has
694
+ * not chosen yet.
695
+ */
696
+ var WidgetVariantChoiceRequestReportSchema = object({
697
+ kind: literal("variant_choice_request"),
698
+ productId: uuid(),
699
+ title: string().trim().min(1).max(REPORT_TITLE_MAX).optional()
700
+ }).strict();
701
+ /**
514
702
  * Every report kind a chat request may carry — the shape a further kind
515
703
  * (`cart_removed`, `checkout_started`) slots into without touching either
516
704
  * side's parse code.
@@ -526,7 +714,8 @@ var WidgetChatReportSchema = discriminatedUnion("kind", [
526
714
  WidgetCartAddReportSchema,
527
715
  WidgetCartAddFailedReportSchema,
528
716
  WidgetSpotlightFailedReportSchema,
529
- WidgetNavigateFailedReportSchema
717
+ WidgetNavigateFailedReportSchema,
718
+ WidgetVariantChoiceRequestReportSchema
530
719
  ]);
531
720
  /**
532
721
  * Parse a request body's `report` field. Never throws — the caller decides
@@ -549,15 +738,20 @@ function extractWidgetToolEvent(output) {
549
738
  /**
550
739
  * Rebuild the `cards` event a curation was streamed as, for replay.
551
740
  *
552
- * **Per-item `safeParse`, not one parse of the whole array.** A catalogue is
553
- * live: between the turn that curated a product and the reload that replays
554
- * it, the product can lose its price (a variant deleted), gain an image URL
555
- * the scheme allowlist refuses, or have its handle rewritten into something
556
- * {@link WidgetChatCardSchema}'s slug regex will not accept. Parsing the
557
- * whole array at once would make ONE such row cost the shopper every card in
558
- * that turn; parsing per item drops only the row that no longer renders. That
559
- * is the same "degrade, never fabricate" posture the live path already takes
560
- * for a card with no `platformVariantId`.
741
+ * **Per-item {@link buildWidgetChatCard}, not one parse of the whole array.**
742
+ * A catalogue is live: between the turn that curated a product and the
743
+ * reload that replays it, the product can lose its price (a variant
744
+ * deleted), gain an image URL the scheme allowlist refuses, or have its
745
+ * handle rewritten into something {@link WidgetChatCardSchema}'s slug regex
746
+ * will not accept. Parsing the whole array at once would make ONE such row
747
+ * cost the shopper every card in that turn; parsing per item drops only the
748
+ * row that no longer renders — and, for a droppable field, drops only the
749
+ * FIELD, via {@link buildWidgetChatCard}, the exact "degrade, never
750
+ * fabricate" contract the live leg (`build_curation`) applies to the same
751
+ * data. Before this called the shared builder, a per-item `safeParse` with no
752
+ * retry meant a droppable field's failure still cost the whole card here —
753
+ * so a product with, say, an image URL on an underscore host rendered on
754
+ * reload with one card fewer than the live turn had actually streamed.
561
755
  *
562
756
  * **Filter first, then cap.** The `MAX_CARDS_PER_EVENT` cap used to be taken
563
757
  * as `items.slice(0, MAX)` BEFORE the drops below, so twenty rows that no
@@ -577,7 +771,7 @@ function buildWidgetChatCardsEvent(curationId, items) {
577
771
  for (const item of items) {
578
772
  if (item.priceMinor === null || item.currency === null) continue;
579
773
  if (item.available !== true) continue;
580
- const parsed = WidgetChatCardSchema.safeParse({
774
+ const card = buildWidgetChatCard({
581
775
  productId: item.productId,
582
776
  ...item.variantId !== null ? { variantId: item.variantId } : {},
583
777
  ...item.platformVariantId !== null ? { platformVariantId: item.platformVariantId } : {},
@@ -587,15 +781,16 @@ function buildWidgetChatCardsEvent(curationId, items) {
587
781
  priceMinor: item.priceMinor,
588
782
  currency: item.currency,
589
783
  available: true,
590
- ...item.reason !== null ? { reason: item.reason } : {}
784
+ ...item.reason !== null ? { reason: item.reason } : {},
785
+ ...item.variantChoiceRequired === true ? { variantChoiceRequired: true } : {}
591
786
  });
592
- if (parsed.success) cards.push(parsed.data);
787
+ if (card !== null) cards.push(card);
593
788
  }
594
789
  if (cards.length === 0) return null;
595
790
  return {
596
791
  type: "cards",
597
792
  curationId,
598
- items: cards.slice(0, MAX_CARDS_PER_EVENT)
793
+ items: cards.slice(0, 20)
599
794
  };
600
795
  }
601
796
  /**
@@ -702,16 +897,40 @@ function buildWidgetChatCardsEvent(curationId, items) {
702
897
  * bounded integers, and `.strict()` on both objects so an unknown key is a
703
898
  * rejection rather than something that reaches the prompt.
704
899
  *
705
- * ### What is deliberately NOT on a line
706
- *
707
- * No product or variant ids. The `cart_add` report carries them so a consumer
708
- * can join a report to a product without re-matching prose; nothing joins
709
- * this snapshot to anything — it exists to be READ, in one prompt section, by
710
- * a model that has no use for a UUID and every reason not to be handed one it
711
- * might repeat to a shopper.
900
+ * ### Variant ids ride the wire — and are stripped before any prompt
901
+ *
902
+ * A line MAY name the variant it is (SAA-174), in either id space, both
903
+ * optional: {@link CART_LINE_VARIANT_ID_PATTERN | `variantId`}, our INTERNAL
904
+ * catalogue UUID (what a widget-sourced line built from a card knows, and
905
+ * what a `'catalog'`-space host knows), and
906
+ * {@link CART_LINE_PLATFORM_VARIANT_ID_PATTERN | `platformVariantId`}, the
907
+ * storefront platform's own numeric id (Shopify's `/cart.js` `variant_id`).
908
+ * They exist for ONE consumer: `apps/api`'s price-drift check, which joins a
909
+ * line to `product_variants.price` and logs when the storefront's unit price
910
+ * and our catalogue disagree. That is a signal for us, never for the model —
911
+ * it changes nothing the concierge says, and the storefront's own figures
912
+ * are still the ones quoted.
913
+ *
914
+ * So the ids MUST be stripped before a cart is rendered into a prompt or
915
+ * published to the turn tier (`apps/api`'s `toShopperCart`). A model has no
916
+ * use for a UUID and every reason not to be handed one it might repeat to a
917
+ * shopper, and `@wesence/agent-core`'s `ShopperCartLineSchema` is strict and
918
+ * deliberately does not know these keys.
919
+ *
920
+ * Shaped, not merely bounded: a UUID and a positive integer of at most 20
921
+ * digits, so an id is never free text on its way into a tenant-scoped query
922
+ * or a log line. A client filters with the exported patterns before sending
923
+ * (`@saar-ai/web-widget`'s `toChatCart`), because a malformed id is a 400
924
+ * like any other malformed field. Trust is unchanged: an id is as
925
+ * client-asserted as the price beside it, and a forged one can only point
926
+ * the drift log at a different row of the SAME tenant's catalogue.
712
927
  */
713
928
  /** Bound on a cart line's display title. Tighter than a card's: fifty of these ride in one prompt section. */
714
929
  var CART_LINE_TITLE_MAX = 200;
930
+ /** Shape of a cart line's INTERNAL catalogue variant id — a UUID, any version, either case. */
931
+ var CART_LINE_VARIANT_ID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
932
+ /** Shape of a cart line's PLATFORM variant id — a positive integer in decimal, no leading zero, at most 20 digits (Shopify's numeric variant id). Never a GID. */
933
+ var CART_LINE_PLATFORM_VARIANT_ID_PATTERN = /^[1-9][0-9]{0,19}$/;
715
934
  /** A basket, not a warehouse. Fifty lines is far past any real storefront cart and still a bounded prompt. */
716
935
  var MAX_CART_LINES = 50;
717
936
  /** A billion minor units — past any real cart line or subtotal, and far short of where an integer stops being exact. */
@@ -728,7 +947,11 @@ var WidgetChatCartLineSchema = object({
728
947
  /** Trimmed before it is bounded, so a whitespace-only title is a rejection rather than a line that names nothing — same reasoning as the report's `title`. */
729
948
  title: string().trim().min(1).max(CART_LINE_TITLE_MAX),
730
949
  quantity: number().int().min(1).max(REPORT_QUANTITY_MAX),
731
- priceMinor: number().int().min(0).max(CART_AMOUNT_MINOR_MAX)
950
+ priceMinor: number().int().min(0).max(CART_AMOUNT_MINOR_MAX),
951
+ /** INTERNAL catalogue variant id, for the server's price-drift join only — see "Variant ids ride the wire" above. Never rendered. */
952
+ variantId: string().regex(CART_LINE_VARIANT_ID_PATTERN).optional(),
953
+ /** The storefront platform's numeric variant id, for the same join — see above. Never rendered. */
954
+ platformVariantId: string().regex(CART_LINE_PLATFORM_VARIANT_ID_PATTERN).optional()
732
955
  }).strict();
733
956
  /**
734
957
  * Where the lines came from, because it changes what the reply may honestly
@@ -774,4 +997,4 @@ function parseWidgetChatCart(value) {
774
997
  return parsed.success ? parsed.data : null;
775
998
  }
776
999
  //#endregion
777
- export { MAX_CART_LINES, WidgetCartAddFailedReportSchema, WidgetCartAddReportSchema, WidgetChatAddToCartEventSchema, WidgetChatCardSchema, WidgetChatCardsEventSchema, WidgetChatCartLineSchema, WidgetChatCartSchema, WidgetChatCartSourceSchema, WidgetChatCheckoutEventSchema, WidgetChatDoneEventSchema, WidgetChatErrorEventSchema, WidgetChatEscalatedEventSchema, WidgetChatReportSchema, WidgetChatSseEventSchema, WidgetChatTextDeltaEventSchema, WidgetToolEventSchema, buildWidgetChatCardsEvent, extractWidgetToolEvent, parseWidgetChatCart, parseWidgetChatReport };
1000
+ export { CART_LINE_PLATFORM_VARIANT_ID_PATTERN, CART_LINE_VARIANT_ID_PATTERN, DROPPABLE_CARD_FIELDS, MAX_CARDS_PER_EVENT, MAX_CART_LINES, WidgetCartAddFailedReportSchema, WidgetCartAddReportSchema, WidgetChatAddToCartEventSchema, WidgetChatCardSchema, WidgetChatCardsEventSchema, WidgetChatCartLineSchema, WidgetChatCartSchema, WidgetChatCartSourceSchema, WidgetChatCheckoutEventSchema, WidgetChatDoneEventSchema, WidgetChatErrorEventSchema, WidgetChatEscalatedEventSchema, WidgetChatReportSchema, WidgetChatSseEventSchema, WidgetChatTextDeltaEventSchema, WidgetToolEventSchema, WidgetVariantChoiceRequestReportSchema, buildWidgetChatCard, buildWidgetChatCardsEvent, buildWithDroppableFields, extractWidgetToolEvent, parseWidgetChatCart, parseWidgetChatReport };