@saar-ai/web-widget 0.3.0 → 0.4.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.
@@ -161,6 +161,73 @@ var WidgetToolEventSchema = discriminatedUnion("type", [
161
161
  WidgetChatEscalatedEventSchema,
162
162
  WidgetChatCheckoutEventSchema
163
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
+ }
164
231
  /** Parse a tool's raw output for an optional, well-shaped `widgetEvent`. Never throws. */
165
232
  function extractWidgetToolEvent(output) {
166
233
  if (typeof output !== "object" || output === null) return null;
@@ -170,4 +237,4 @@ function extractWidgetToolEvent(output) {
170
237
  return parsed.success ? parsed.data : null;
171
238
  }
172
239
  //#endregion
173
- export { WidgetChatCardSchema, WidgetChatCardsEventSchema, WidgetChatCheckoutEventSchema, WidgetChatDoneEventSchema, WidgetChatErrorEventSchema, WidgetChatEscalatedEventSchema, WidgetChatSseEventSchema, WidgetChatTextDeltaEventSchema, WidgetToolEventSchema, extractWidgetToolEvent };
240
+ export { WidgetCartAddReportSchema, WidgetChatCardSchema, WidgetChatCardsEventSchema, WidgetChatCheckoutEventSchema, WidgetChatDoneEventSchema, WidgetChatErrorEventSchema, WidgetChatEscalatedEventSchema, WidgetChatReportSchema, WidgetChatSseEventSchema, WidgetChatTextDeltaEventSchema, WidgetToolEventSchema, extractWidgetToolEvent, parseWidgetChatReport };