@brinkcommerce/agentic-shopping-sdk 0.1.0-alpha.0

package/dist/index.cjs

@@ -0,0 +1,168 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  AgentError: () => AgentError,
+  PRODUCT_MARKER: () => PRODUCT_MARKER,
+  collectReply: () => collectReply,
+  createSessionId: () => createSessionId,
+  formatPrice: () => formatPrice,
+  interleaveProducts: () => interleaveProducts,
+  isWireEvent: () => isWireEvent,
+  parseWireEvents: () => parseWireEvents,
+  stripMarkers: () => stripMarkers
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/ndjson.ts
+function parseLine(line) {
+  const trimmed = line.trim();
+  if (trimmed === "") return void 0;
+  let parsed;
+  try {
+    parsed = JSON.parse(trimmed);
+  } catch {
+    return void 0;
+  }
+  if (typeof parsed !== "object" || parsed === null) return void 0;
+  const event = parsed;
+  return typeof event.type === "string" ? event : void 0;
+}
+function isWireEvent(event, type) {
+  return event.type === type;
+}
+async function* parseWireEvents(body) {
+  const reader = body.getReader();
+  const decoder = new TextDecoder();
+  let buffer = "";
+  try {
+    for (; ; ) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      buffer += decoder.decode(value, { stream: true });
+      let newline = buffer.indexOf("\n");
+      while (newline !== -1) {
+        const event = parseLine(buffer.slice(0, newline));
+        buffer = buffer.slice(newline + 1);
+        if (event !== void 0) yield event;
+        newline = buffer.indexOf("\n");
+      }
+    }
+    buffer += decoder.decode();
+    const last = parseLine(buffer);
+    if (last !== void 0) yield last;
+  } finally {
+    reader.releaseLock();
+  }
+}
+async function collectReply(events) {
+  let text = "";
+  let products = [];
+  let suggestions = [];
+  for await (const event of events) {
+    if (event.type === "text" && typeof event.content === "string") {
+      text += event.content;
+      continue;
+    }
+    if (event.type === "products" && Array.isArray(event.products)) {
+      products = event.products;
+      continue;
+    }
+    if (event.type === "suggestions" && Array.isArray(event.suggestions)) {
+      suggestions = event.suggestions;
+    }
+  }
+  return { text, products, suggestions };
+}
+
+// src/markers.ts
+var PRODUCT_MARKER = /\[product:([\w-]+)\]/g;
+var MARKER_OPEN = "[product:";
+function hidePartialMarker(text) {
+  const open = text.lastIndexOf("[");
+  if (open === -1 || text.includes("]", open)) return text;
+  const tail = text.slice(open);
+  const partial = tail.startsWith(MARKER_OPEN) ? /^\[product:[\w-]*$/.test(tail) : MARKER_OPEN.startsWith(tail);
+  return partial ? text.slice(0, open) : text;
+}
+var PARAGRAPH_BREAK = /\n\s*\n/;
+var MARKER_WITH_PADDING = /[^\S\r\n]*\[product:[\w-]+\][^\S\r\n]*/g;
+function stripMarkersFrom(paragraph) {
+  return paragraph.replace(MARKER_WITH_PADDING, (gap) => /\s/.test(gap) ? " " : "").trim();
+}
+function interleaveProducts(text, products) {
+  const byId = new Map(products.map((product) => [product.productId, product]));
+  const segments = [];
+  const matched = [];
+  const placed = /* @__PURE__ */ new Set();
+  const visible = hidePartialMarker(text);
+  for (const paragraph of visible.split(PARAGRAPH_BREAK)) {
+    const pattern = new RegExp(PRODUCT_MARKER.source, PRODUCT_MARKER.flags);
+    const cards = [];
+    let match;
+    while ((match = pattern.exec(paragraph)) !== null) {
+      const product = byId.get(match[1]);
+      if (product === void 0 || placed.has(product.productId)) continue;
+      placed.add(product.productId);
+      matched.push(product);
+      cards.push(product);
+    }
+    const prose = stripMarkersFrom(paragraph);
+    if (prose !== "") segments.push({ type: "text", content: prose });
+    for (const product of cards) segments.push({ type: "product", product });
+  }
+  return { segments, matched, unmatched: products.filter((product) => !placed.has(product.productId)) };
+}
+function stripMarkers(text) {
+  return hidePartialMarker(text).replace(PRODUCT_MARKER, "");
+}
+
+// src/session.ts
+function createSessionId() {
+  return `session-${crypto.randomUUID()}`;
+}
+
+// src/price.ts
+function formatPrice(amount, currencyCode, locale) {
+  return new Intl.NumberFormat(locale, { style: "currency", currency: currencyCode }).format(amount / 100);
+}
+
+// src/errors.ts
+var AgentError = class extends Error {
+  constructor(statusCode, body) {
+    super(`Agent error: ${statusCode}`);
+    this.statusCode = statusCode;
+    this.body = body;
+    this.name = "AgentError";
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  AgentError,
+  PRODUCT_MARKER,
+  collectReply,
+  createSessionId,
+  formatPrice,
+  interleaveProducts,
+  isWireEvent,
+  parseWireEvents,
+  stripMarkers
+});

package/dist/index.d.cts

@@ -0,0 +1,102 @@
+import { W as WireEvent, U as UnknownWireEvent, P as ProductCard } from './errors-CYbkUYHr.cjs';
+export { A as AgentError, C as CartContext, a as CartLine, b as ProductCardVariant, S as StoreContext } from './errors-CYbkUYHr.cjs';
+
+/**
+ * Narrows an event to one of the five this SDK knows.
+ *
+ * `switch (event.type)` cannot do it on its own: `UnknownWireEvent` carries an index signature, so it stays
+ * in the union on every branch and each field comes out as `unknown`. This is what makes a handler read the
+ * fields without casting.
+ *
+ * @example
+ * if (isWireEvent(event, 'text')) append(event.content)
+ */
+declare function isWireEvent<T extends WireEvent['type']>(event: WireEvent | UnknownWireEvent, type: T): event is Extract<WireEvent, {
+    type: T;
+}>;
+/**
+ * The events in an NDJSON response body, one JSON object per line. Lines arrive split across chunk
+ * boundaries, so partial lines are buffered until their newline.
+ *
+ * An event type this SDK does not know is yielded through untouched — the backend adds types without a major
+ * bump, and dropping them here would hide the new one from a caller that does know it.
+ *
+ * The wire is bare, single-encoded NDJSON: no `data: ` prefix and no double encoding. Stripping a prefix or
+ * parsing twice "just in case" only ever masks a real framing change.
+ *
+ * @example
+ * for await (const event of parseWireEvents(response.body)) {
+ *   if (event.type === 'text') append(event.content)
+ * }
+ */
+declare function parseWireEvents(body: ReadableStream<Uint8Array>): AsyncGenerator<WireEvent | UnknownWireEvent>;
+/**
+ * A whole reply, for callers that render nothing until the agent is done. Streaming is what the protocol is
+ * for — reach for this only when there is no progressive UI to feed.
+ */
+declare function collectReply(events: AsyncIterable<WireEvent | UnknownWireEvent>): Promise<{
+    text: string;
+    products: ProductCard[];
+    suggestions: string[];
+}>;
+
+/**
+ * The marker the agent writes after each product name: `[product:<productId>]`. The card's own id, never
+ * `productParentId` — several cards can share a parent, so a parent id would resolve to an arbitrary one.
+ *
+ * The hyphen in the character class is load-bearing. A product id is a merchant-chosen string over
+ * `[A-Za-z0-9_-]`, and hyphens are common in one — so a `\w+` pattern misses every id that carries one, and
+ * a reply whose ids all carry one loses every card.
+ */
+declare const PRODUCT_MARKER: RegExp;
+type ContentSegment = {
+    type: 'text';
+    content: string;
+} | {
+    type: 'product';
+    product: ProductCard;
+};
+/**
+ * A reply split into the pieces to render in order: prose, with each product card below the paragraph whose
+ * marker named it. Markers are consumed, so no `[product:…]` reaches the shopper — including the half of one
+ * that the tail of a streaming reply holds.
+ *
+ * The cut is at the paragraph boundary rather than at the marker, because the agent writes the marker inside
+ * a sentence — straight after the product name. Cutting at the marker itself puts the card between "The
+ * Gore-Tex Offshore Jacket" and "is the shell", breaking the sentence across it. So each text segment is one
+ * paragraph, trimmed, and the cards it named follow it in the order they were written.
+ *
+ * A marker whose id has no card is stripped silently, which is what the backend expects — the prose already
+ * names the product. Cards no marker referenced come back as `unmatched`, to render as a shelf below the
+ * reply. A product referenced twice gets one card, under the paragraph that mentions it first.
+ *
+ * There is deliberately no fuzzy name matching: a fallback that guesses degrades silently instead of failing,
+ * and any word list it needs is tenant- and language-specific.
+ */
+declare function interleaveProducts(text: string, products: ProductCard[]): {
+    segments: ContentSegment[];
+    matched: ProductCard[];
+    unmatched: ProductCard[];
+};
+/**
+ * The reply with every marker removed, for a caller that renders prose and cards separately. A partial
+ * marker at the end of a streaming reply goes too, for the same reason it does in `interleaveProducts`.
+ */
+declare function stripMarkers(text: string): string;
+
+/**
+ * A session id for one conversation. The agent requires a session id of at least 33 characters; a bare
+ * UUID is 36 and passes, but the prefix makes that constraint visible and the value greppable in logs.
+ *
+ * The first turn pins the session to its store group and market. A later turn naming a different store is
+ * refused, so switching store means a new id.
+ */
+declare function createSessionId(): string;
+
+/**
+ * A card's price, formatted for display. Every amount on the wire is in minor units, so `59900` in `SEK` is
+ * 599,00 kr. Pass the card's own `currencyCode` — it is per product, not per store.
+ */
+declare function formatPrice(amount: number, currencyCode: string, locale?: string): string;
+
+export { type ContentSegment, PRODUCT_MARKER, ProductCard, UnknownWireEvent, WireEvent, collectReply, createSessionId, formatPrice, interleaveProducts, isWireEvent, parseWireEvents, stripMarkers };

package/dist/index.d.ts

@@ -0,0 +1,102 @@
+import { W as WireEvent, U as UnknownWireEvent, P as ProductCard } from './errors-CYbkUYHr.js';
+export { A as AgentError, C as CartContext, a as CartLine, b as ProductCardVariant, S as StoreContext } from './errors-CYbkUYHr.js';
+
+/**
+ * Narrows an event to one of the five this SDK knows.
+ *
+ * `switch (event.type)` cannot do it on its own: `UnknownWireEvent` carries an index signature, so it stays
+ * in the union on every branch and each field comes out as `unknown`. This is what makes a handler read the
+ * fields without casting.
+ *
+ * @example
+ * if (isWireEvent(event, 'text')) append(event.content)
+ */
+declare function isWireEvent<T extends WireEvent['type']>(event: WireEvent | UnknownWireEvent, type: T): event is Extract<WireEvent, {
+    type: T;
+}>;
+/**
+ * The events in an NDJSON response body, one JSON object per line. Lines arrive split across chunk
+ * boundaries, so partial lines are buffered until their newline.
+ *
+ * An event type this SDK does not know is yielded through untouched — the backend adds types without a major
+ * bump, and dropping them here would hide the new one from a caller that does know it.
+ *
+ * The wire is bare, single-encoded NDJSON: no `data: ` prefix and no double encoding. Stripping a prefix or
+ * parsing twice "just in case" only ever masks a real framing change.
+ *
+ * @example
+ * for await (const event of parseWireEvents(response.body)) {
+ *   if (event.type === 'text') append(event.content)
+ * }
+ */
+declare function parseWireEvents(body: ReadableStream<Uint8Array>): AsyncGenerator<WireEvent | UnknownWireEvent>;
+/**
+ * A whole reply, for callers that render nothing until the agent is done. Streaming is what the protocol is
+ * for — reach for this only when there is no progressive UI to feed.
+ */
+declare function collectReply(events: AsyncIterable<WireEvent | UnknownWireEvent>): Promise<{
+    text: string;
+    products: ProductCard[];
+    suggestions: string[];
+}>;
+
+/**
+ * The marker the agent writes after each product name: `[product:<productId>]`. The card's own id, never
+ * `productParentId` — several cards can share a parent, so a parent id would resolve to an arbitrary one.
+ *
+ * The hyphen in the character class is load-bearing. A product id is a merchant-chosen string over
+ * `[A-Za-z0-9_-]`, and hyphens are common in one — so a `\w+` pattern misses every id that carries one, and
+ * a reply whose ids all carry one loses every card.
+ */
+declare const PRODUCT_MARKER: RegExp;
+type ContentSegment = {
+    type: 'text';
+    content: string;
+} | {
+    type: 'product';
+    product: ProductCard;
+};
+/**
+ * A reply split into the pieces to render in order: prose, with each product card below the paragraph whose
+ * marker named it. Markers are consumed, so no `[product:…]` reaches the shopper — including the half of one
+ * that the tail of a streaming reply holds.
+ *
+ * The cut is at the paragraph boundary rather than at the marker, because the agent writes the marker inside
+ * a sentence — straight after the product name. Cutting at the marker itself puts the card between "The
+ * Gore-Tex Offshore Jacket" and "is the shell", breaking the sentence across it. So each text segment is one
+ * paragraph, trimmed, and the cards it named follow it in the order they were written.
+ *
+ * A marker whose id has no card is stripped silently, which is what the backend expects — the prose already
+ * names the product. Cards no marker referenced come back as `unmatched`, to render as a shelf below the
+ * reply. A product referenced twice gets one card, under the paragraph that mentions it first.
+ *
+ * There is deliberately no fuzzy name matching: a fallback that guesses degrades silently instead of failing,
+ * and any word list it needs is tenant- and language-specific.
+ */
+declare function interleaveProducts(text: string, products: ProductCard[]): {
+    segments: ContentSegment[];
+    matched: ProductCard[];
+    unmatched: ProductCard[];
+};
+/**
+ * The reply with every marker removed, for a caller that renders prose and cards separately. A partial
+ * marker at the end of a streaming reply goes too, for the same reason it does in `interleaveProducts`.
+ */
+declare function stripMarkers(text: string): string;
+
+/**
+ * A session id for one conversation. The agent requires a session id of at least 33 characters; a bare
+ * UUID is 36 and passes, but the prefix makes that constraint visible and the value greppable in logs.
+ *
+ * The first turn pins the session to its store group and market. A later turn naming a different store is
+ * refused, so switching store means a new id.
+ */
+declare function createSessionId(): string;
+
+/**
+ * A card's price, formatted for display. Every amount on the wire is in minor units, so `59900` in `SEK` is
+ * 599,00 kr. Pass the card's own `currencyCode` — it is per product, not per store.
+ */
+declare function formatPrice(amount: number, currencyCode: string, locale?: string): string;
+
+export { type ContentSegment, PRODUCT_MARKER, ProductCard, UnknownWireEvent, WireEvent, collectReply, createSessionId, formatPrice, interleaveProducts, isWireEvent, parseWireEvents, stripMarkers };

package/dist/index.js

@@ -0,0 +1,127 @@
+import {
+  AgentError
+} from "./chunk-2MMTZSYZ.js";
+
+// src/ndjson.ts
+function parseLine(line) {
+  const trimmed = line.trim();
+  if (trimmed === "") return void 0;
+  let parsed;
+  try {
+    parsed = JSON.parse(trimmed);
+  } catch {
+    return void 0;
+  }
+  if (typeof parsed !== "object" || parsed === null) return void 0;
+  const event = parsed;
+  return typeof event.type === "string" ? event : void 0;
+}
+function isWireEvent(event, type) {
+  return event.type === type;
+}
+async function* parseWireEvents(body) {
+  const reader = body.getReader();
+  const decoder = new TextDecoder();
+  let buffer = "";
+  try {
+    for (; ; ) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      buffer += decoder.decode(value, { stream: true });
+      let newline = buffer.indexOf("\n");
+      while (newline !== -1) {
+        const event = parseLine(buffer.slice(0, newline));
+        buffer = buffer.slice(newline + 1);
+        if (event !== void 0) yield event;
+        newline = buffer.indexOf("\n");
+      }
+    }
+    buffer += decoder.decode();
+    const last = parseLine(buffer);
+    if (last !== void 0) yield last;
+  } finally {
+    reader.releaseLock();
+  }
+}
+async function collectReply(events) {
+  let text = "";
+  let products = [];
+  let suggestions = [];
+  for await (const event of events) {
+    if (event.type === "text" && typeof event.content === "string") {
+      text += event.content;
+      continue;
+    }
+    if (event.type === "products" && Array.isArray(event.products)) {
+      products = event.products;
+      continue;
+    }
+    if (event.type === "suggestions" && Array.isArray(event.suggestions)) {
+      suggestions = event.suggestions;
+    }
+  }
+  return { text, products, suggestions };
+}
+
+// src/markers.ts
+var PRODUCT_MARKER = /\[product:([\w-]+)\]/g;
+var MARKER_OPEN = "[product:";
+function hidePartialMarker(text) {
+  const open = text.lastIndexOf("[");
+  if (open === -1 || text.includes("]", open)) return text;
+  const tail = text.slice(open);
+  const partial = tail.startsWith(MARKER_OPEN) ? /^\[product:[\w-]*$/.test(tail) : MARKER_OPEN.startsWith(tail);
+  return partial ? text.slice(0, open) : text;
+}
+var PARAGRAPH_BREAK = /\n\s*\n/;
+var MARKER_WITH_PADDING = /[^\S\r\n]*\[product:[\w-]+\][^\S\r\n]*/g;
+function stripMarkersFrom(paragraph) {
+  return paragraph.replace(MARKER_WITH_PADDING, (gap) => /\s/.test(gap) ? " " : "").trim();
+}
+function interleaveProducts(text, products) {
+  const byId = new Map(products.map((product) => [product.productId, product]));
+  const segments = [];
+  const matched = [];
+  const placed = /* @__PURE__ */ new Set();
+  const visible = hidePartialMarker(text);
+  for (const paragraph of visible.split(PARAGRAPH_BREAK)) {
+    const pattern = new RegExp(PRODUCT_MARKER.source, PRODUCT_MARKER.flags);
+    const cards = [];
+    let match;
+    while ((match = pattern.exec(paragraph)) !== null) {
+      const product = byId.get(match[1]);
+      if (product === void 0 || placed.has(product.productId)) continue;
+      placed.add(product.productId);
+      matched.push(product);
+      cards.push(product);
+    }
+    const prose = stripMarkersFrom(paragraph);
+    if (prose !== "") segments.push({ type: "text", content: prose });
+    for (const product of cards) segments.push({ type: "product", product });
+  }
+  return { segments, matched, unmatched: products.filter((product) => !placed.has(product.productId)) };
+}
+function stripMarkers(text) {
+  return hidePartialMarker(text).replace(PRODUCT_MARKER, "");
+}
+
+// src/session.ts
+function createSessionId() {
+  return `session-${crypto.randomUUID()}`;
+}
+
+// src/price.ts
+function formatPrice(amount, currencyCode, locale) {
+  return new Intl.NumberFormat(locale, { style: "currency", currency: currencyCode }).format(amount / 100);
+}
+export {
+  AgentError,
+  PRODUCT_MARKER,
+  collectReply,
+  createSessionId,
+  formatPrice,
+  interleaveProducts,
+  isWireEvent,
+  parseWireEvents,
+  stripMarkers
+};