@wix/agent-skills 1.19.2 → 1.20.1

package/skills/wix-headless-fast/references/storefront/app/wix/storefront/cart.ts

@@ -1,7 +1,8 @@
-// Cart + checkout (Wix eCom Cart V2) — the only file that touches raw cart entities.
-// Copy as-is; extend by calling these exports, never by editing them. The request shapes are
-// exact (catalogItems wrapper, options.variantId, the redirect-session body) and rewriting
-// them is how carts break.
+// Cart + checkout (Wix eCom Cart V2) over the SDK — the only file that touches raw cart entities
+// on this transport. Rules and mappers live in ./cart-core (shared with the REST twin in
+// references/storefront/rest/); this file is the transport only. Copy as-is; extend by calling
+// these exports, never by editing them. The request shapes are exact (catalogItems wrapper,
+// options.variantId, the redirect-session body) and rewriting them is how carts break.
 //
 // Failures are loud: these throw on out-of-stock lines, an empty cart at checkout, and a
 // missing required selection — surface the message to the buyer, don't swallow it.
@@ -9,106 +10,74 @@
 // docs: https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/purchase-flow/cart-v2/add-line-items-to-current-cart.md
 // docs: https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/purchase-flow/cart-v2/update-line-items.md
 // docs: https://dev.wix.com/docs/api-reference/business-management/headless/redirects/create-redirect-session.md
-// docs: https://dev.wix.com/docs/api-reference/business-solutions/stores/catalog-v3/products-v3/query-products.md
 import { currentCartV2 } from "@wix/ecom";
 import { redirects as redirectsModule } from "@wix/redirects";
 import { productsV3 } from "@wix/stores";
 import { wixModule } from "../sdk";
 import { imgSrc } from "../media";
-import { formatMoney } from "../money";
-import type { Cart, CartLine } from "./types";
+import { WIX_STORES_APP_ID, addOptions, assertAdded, assertCheckoutable, rawId, summaryTotals, toCart } from "./cart-core";
+import type { Raw } from "./catalog-core";
+import type { Cart } from "./types";
 
 const cartApi = wixModule(currentCartV2);
 const redirects = wixModule(redirectsModule);
 const productsApi = wixModule(productsV3);
 
+export interface AddToCartExtras {
+  /** TEXT_CHOICES modifier selections: modifier key -> choice key (options.options — MODIFIERS only, never Size/Color). */
+  modifierChoices?: Record<string, string>;
+  /** FREE_TEXT modifier inputs: freeTextSettings key -> the buyer's text. */
+  customTextFields?: Record<string, string>;
+  /** The variant is out of stock but pre-orderable — sends preOrderRequested. */
+  preorder?: boolean;
+  /** A chosen recurring plan (subscriptionPricesInfo); omit for a one-time purchase. */
+  subscriptionOptionId?: string;
+}
+
 // The V2 cart does NOT return line-item images (attributes.image is typed but comes back
 // absent — verified against a live cart), so images are joined from the catalog by the
 // line's catalogItemId and cached for the session.
 const lineImageCache = new Map<string, string>();
-
-async function fillLineImages(lines: CartLine[], raws: RawCart[]): Promise<void> {
+async function fillLineImages(cart: Cart, raws: Raw[]): Promise<void> {
   const wanted = new Map<string, number[]>(); // productId -> line indexes
   raws.forEach((raw, i) => {
-    if (lines[i].imageUrl) return;
+    if (cart.lines[i].imageUrl) return;
     const pid = raw.source?.catalogReference?.catalogItemId;
     if (!pid) return;
     const cached = lineImageCache.get(pid);
     if (cached !== undefined) {
-      lines[i].imageUrl = cached;
+      cart.lines[i].imageUrl = cached;
       return;
     }
     wanted.set(pid, [...(wanted.get(pid) ?? []), i]);
   });
   if (!wanted.size) return;
   try {
-    const res = await productsApi
-      .queryProducts()
-      .in("_id", [...wanted.keys()])
-      .find();
-    for (const p of (res.items ?? []) as RawCart[]) {
+    const res = await productsApi.queryProducts().in("_id", [...wanted.keys()]).find();
+    for (const p of (res.items ?? []) as Raw[]) {
       const url = imgSrc(p.media?.main, 300, 300);
-      lineImageCache.set(p._id, url);
-      for (const i of wanted.get(p._id) ?? []) lines[i].imageUrl = url;
+      lineImageCache.set(rawId(p), url);
+      for (const i of wanted.get(rawId(p)) ?? []) cart.lines[i].imageUrl = url;
     }
   } catch {
     /* images are a nicety — the cart stays correct without them */
   }
 }
 
-// Public app id of the Wix Stores catalog — required inside every catalogReference.
-const WIX_STORES_APP_ID = "215238eb-22a5-4c36-9e7b-e7c08025e04e";
-
-type RawCart = Record<string, any>;
-
-function cartCurrency(raw: RawCart | null): string {
-  return raw?.customerInfo?.currencyCode ?? raw?.businessInfo?.currencyCode ?? "";
-}
-
-function toLine(raw: RawCart, currency: string): CartLine {
-  const descriptionLines: string[] = (raw.attributes?.descriptionLines ?? [])
-    .map((d: RawCart) => {
-      const label = d.name?.original ?? "";
-      const value = d.plainText?.original ?? d.colorInfo?.original ?? "";
-      return label && value ? `${label}: ${value}` : value || label;
-    })
-    .filter(Boolean);
-  return {
-    lineItemId: raw._id ?? "",
-    productName: raw.name?.original ?? "",
-    quantity: raw.quantityInfo?.confirmedQuantity ?? 0,
-    unitPrice: formatMoney(raw.pricing?.unitPrice, currency),
-    linePrice: formatMoney(raw.pricing?.totalPrice, currency),
-    imageUrl: imgSrc(raw.attributes?.image, 300, 300),
-    descriptionLines,
-    status: raw.status ?? "IN_STOCK",
-  };
-}
-
-function toCart(raw: RawCart | null, subtotal: string): Cart {
-  const currency = cartCurrency(raw);
-  const lines = (raw?.lineItems ?? []).map((l: RawCart) => toLine(l, currency));
-  return {
-    lines,
-    itemCount: lines.reduce((sum: number, l: CartLine) => sum + l.quantity, 0),
-    subtotal,
-    currency,
-  };
-}
-
-async function readCartWithSubtotal(raw: RawCart | null): Promise<Cart> {
-  if (!raw?.lineItems?.length) return toCart(raw, "");
-  // The authoritative after-discount subtotal comes from the cart estimate, never from
-  // hand-summing line items (tax and shipping resolve at checkout).
-  let subtotal = "";
+async function readCartWithSubtotal(raw: Raw | null): Promise<Cart> {
+  // Only estimate a cart WITH lines — on an absent/empty cart the endpoint returns 404.
+  if (!raw?.lineItems?.length) return toCart(raw, "", "", imgSrc);
+  // The authoritative after-discount subtotal and the CART-level discount come from the cart
+  // estimate, never from hand-summing lines. Its delivery/tax/fees read "0" when nothing was
+  // calculated — never render those as "Free"; shipping and tax resolve at checkout.
+  let totals = { subtotal: "", discount: "" };
   try {
-    const estimate: RawCart = await cartApi.estimateCurrentCart();
-    subtotal = formatMoney(estimate?.summary?.priceSummary?.subtotal, cartCurrency(raw));
+    totals = summaryTotals(await cartApi.estimateCurrentCart(), raw);
   } catch {
     /* estimate is a display nicety — the cart itself is still valid */
   }
-  const cart = toCart(raw, subtotal);
-  await fillLineImages(cart.lines, raw.lineItems as RawCart[]);
+  const cart = toCart(raw, totals.subtotal, totals.discount, imgSrc);
+  await fillLineImages(cart, raw.lineItems as Raw[]);
   return cart;
 }
 
@@ -116,77 +85,36 @@ async function readCartWithSubtotal(raw: RawCart | null): Promise<Cart> {
 export async function fetchCart(): Promise<Cart> {
   try {
     const { cart } = await cartApi.getCurrentCart();
-    return readCartWithSubtotal(cart as RawCart);
+    return readCartWithSubtotal(cart as Raw);
   } catch {
-    return toCart(null, "");
+    return toCart(null, "", "", imgSrc);
   }
 }
 
-export interface AddToCartExtras {
-  /** TEXT_CHOICES modifier selections: modifier key -> choice key. */
-  modifierChoices?: Record<string, string>;
-  /** FREE_TEXT modifier inputs: freeTextSettings key -> the buyer's text. */
-  customTextFields?: Record<string, string>;
-}
-
 /**
- * Add a product to the current cart.
- * For a product WITH options, `variantId` is mandatory — resolve it with
- * `resolveVariant()` from ./catalog first. Mandatory modifiers must be included.
+ * Add a product to the current cart. For a product WITH options, `variantId` is mandatory —
+ * resolve it with `resolveVariant()` from ./catalog first. Mandatory modifiers must be included.
+ * A refused add still returns 200, so the returned line is checked.
  */
-export async function addToCart(
-  productId: string,
-  variantId?: string | null,
-  quantity = 1,
-  { modifierChoices, customTextFields }: AddToCartExtras = {},
-): Promise<Cart> {
-  const options: Record<string, unknown> = {};
-  if (variantId) options.variantId = variantId;
-  if (modifierChoices && Object.keys(modifierChoices).length) options.options = modifierChoices;
-  if (customTextFields && Object.keys(customTextFields).length) options.customTextFields = customTextFields;
-
+export async function addToCart(productId: string, variantId?: string | null, quantity = 1, extras: AddToCartExtras = {}): Promise<Cart> {
+  const options = addOptions({ variantId, ...extras });
   const { cart } = await cartApi.addLineItemsToCurrentCart({
-    catalogItems: [
-      {
-        quantity,
-        catalogReference: {
-          catalogItemId: productId,
-          appId: WIX_STORES_APP_ID,
-          ...(Object.keys(options).length ? { options } : {}),
-        },
-      },
-    ],
+    catalogItems: [{ quantity, catalogReference: { catalogItemId: productId, appId: WIX_STORES_APP_ID, ...(Object.keys(options).length ? { options } : {}) } }],
   });
-
-  const line = ((cart as RawCart)?.lineItems ?? []).find(
-    (l: RawCart) =>
-      l.source?.catalogReference?.catalogItemId === productId &&
-      (!variantId || l.source?.catalogReference?.options?.variantId === variantId),
-  );
-  if (line?.status && line.status !== "IN_STOCK") {
-    throw new Error(`This item isn't available right now (${line.status.toLowerCase().replace(/_/g, " ")}).`);
-  }
-  if (!line || line.quantityInfo?.confirmedQuantity === 0) {
-    throw new Error(
-      "The item couldn't be added. Make sure every required selection was made " +
-        "(options for a product with variants, and all mandatory customizations).",
-    );
-  }
-  return readCartWithSubtotal(cart as RawCart);
+  assertAdded(cart as Raw, productId, variantId);
+  return readCartWithSubtotal(cart as Raw);
 }
 
 /** Change a line's quantity. `lineItemId` is CartLine.lineItemId, never the product id. */
 export async function updateQuantity(lineItemId: string, quantity: number): Promise<Cart> {
-  const { cart } = await cartApi.updateLineItemsInCurrentCart({
-    lineItems: [{ lineItemId, quantity: { newQuantity: quantity } }],
-  });
-  return readCartWithSubtotal(cart as RawCart);
+  const { cart } = await cartApi.updateLineItemsInCurrentCart({ lineItems: [{ lineItemId, quantity: { newQuantity: quantity } }] });
+  return readCartWithSubtotal(cart as Raw);
 }
 
 /** Remove a line from the cart by CartLine.lineItemId. */
 export async function removeLine(lineItemId: string): Promise<Cart> {
   const { cart } = await cartApi.removeLineItemsFromCurrentCart([lineItemId]);
-  return readCartWithSubtotal(cart as RawCart);
+  return readCartWithSubtotal(cart as Raw);
 }
 
 /**
@@ -197,23 +125,12 @@ export async function removeLine(lineItemId: string): Promise<Cart> {
  */
 export async function checkoutUrl(): Promise<string> {
   const { cart } = await cartApi.getCurrentCart();
-  const raw = cart as RawCart;
-  const lines: RawCart[] = raw?.lineItems ?? [];
-  if (!lines.length) throw new Error("Your cart is empty.");
-  const unavailable = lines.filter((l) => l.status && l.status !== "IN_STOCK");
-  if (unavailable.length) {
-    const names = unavailable.map((l) => l.name?.original).filter(Boolean).join(", ");
-    throw new Error(`Some items are no longer available: ${names}.`);
-  }
-  if (!raw?._id) throw new Error("Checkout couldn't start: the cart has no id.");
-
+  const raw = cart as Raw;
+  assertCheckoutable(raw);
   const origin = typeof window !== "undefined" ? window.location.origin : "";
   const session = await redirects.createRedirectSession({
-    ecomCheckout: { checkoutId: raw._id },
-    callbacks: {
-      postFlowUrl: origin ? `${origin}/` : undefined,
-      thankYouPageUrl: origin ? `${origin}/` : undefined,
-    },
+    ecomCheckout: { checkoutId: rawId(raw) },
+    callbacks: { postFlowUrl: origin ? `${origin}/` : undefined, thankYouPageUrl: origin ? `${origin}/` : undefined },
   });
   const url = session?.redirectSession?.fullUrl;
   if (!url) throw new Error("Checkout couldn't start: no redirect URL returned.");

package/skills/wix-headless-fast/references/storefront/app/wix/storefront/catalog-core.ts

@@ -0,0 +1,309 @@
+// Catalog rules and DTO mapping — transport-agnostic, imported by BOTH transports: ./catalog.ts
+// (the SDK, managed Astro and React) and the REST twin in references/storefront/rest/catalog.ts
+// (fetch, a static site or a port to another language). Every rule about prices, ribbons,
+// ranges, media, variants lives HERE, once. A raw entity may come from the SDK (`_id`) or from
+// REST (`id`); the mappers accept both. Imports are type-only so a strip to JS emits no imports.
+import type {
+  Availability,
+  Category,
+  Facet,
+  FacetData,
+  ProductDetail,
+  ProductModifier,
+  ProductOption,
+  ProductSummary,
+  ProductVariant,
+} from "./types";
+
+/** A raw Catalog V3 entity as either transport returns it. */
+export type Raw = Record<string, any>;
+/** Media value + size → https URL. Injected: the SDK transport scales through @wix/sdk, REST through the URL form. */
+export type ImgSrc = (value: any, width: number, height: number) => string;
+/** Media identity before scaling — de-duplicate on this, never on a resolved URL. */
+export type MediaKey = (value: any) => string;
+
+const id = (raw: Raw | undefined): string => raw?._id ?? raw?.id ?? "";
+
+// Requested on every product read. CURRENCY → formattedAmount (without it prices render as bare
+// numbers); MEDIA_ITEMS_INFO → the gallery; MIN_PRICE_VARIANT + DISCOUNT_INFO → the cheapest variant
+// with its discounted price: a card's real price and the direct-add variant id, no per-product fetch.
+export const LIST_FIELDS = ["CURRENCY", "MEDIA_ITEMS_INFO", "MIN_PRICE_VARIANT", "DISCOUNT_INFO"] as const;
+// The detail read adds the HTML description, the variants (VARIANT_OPTION_CHOICE_NAMES — without it
+// variantsInfo is null), and the info sections with HTML bodies.
+export const DETAIL_FIELDS = [
+  ...LIST_FIELDS,
+  "PLAIN_DESCRIPTION",
+  "VARIANT_OPTION_CHOICE_NAMES",
+  "INFO_SECTION",
+  "INFO_SECTION_PLAIN_DESCRIPTION",
+] as const;
+
+// ---- sort + filter ---------------------------------------------------------------------------------
+
+export const CATALOG_SORTS = {
+  featured: { label: "Default order" }, // the catalog's own order — no sort sent, and NOT a sales ranking
+  priceAsc: { label: "Price: low to high" },
+  priceHigh: { label: "Price: high to low" },
+  name: { label: "Name: A–Z" },
+  newest: { label: "Newest" },
+} as const;
+export type CatalogSort = keyof typeof CATALOG_SORTS;
+
+export const SORT_FIELDS: Partial<Record<CatalogSort, { fieldName: string; order: "ASC" | "DESC" }[]>> = {
+  priceAsc: [{ fieldName: "actualPriceRange.minValue.amount", order: "ASC" }, { fieldName: "name", order: "ASC" }],
+  priceHigh: [{ fieldName: "actualPriceRange.minValue.amount", order: "DESC" }, { fieldName: "name", order: "ASC" }],
+  name: [{ fieldName: "name", order: "ASC" }],
+  newest: [{ fieldName: "createdDate", order: "DESC" }, { fieldName: "name", order: "ASC" }],
+};
+
+export interface CatalogSearchOptions {
+  /** 1–100, default 24. */
+  limit?: number;
+  /** Continues the ORIGINAL query — send it alone; any change of selection starts over without one. */
+  cursor?: string | null;
+  categoryId?: string | null;
+  sort?: CatalogSort;
+  /** Inclusive bounds on the product's minimum actual variant price, site currency. */
+  minPrice?: number | string;
+  maxPrice?: number | string;
+  /** IN_STOCK only — excludes partially stocked and preorder-only products. */
+  inStockOnly?: boolean;
+  /** Name search, max 100 chars. */
+  search?: string;
+  /** Option-choice facets: products carrying ANY of these choice ids (see fetchFacetData). */
+  choiceIds?: string[];
+}
+
+export function priceBound(value: number | string | undefined, name: string): number | undefined {
+  if (value == null || value === "") return undefined;
+  const n = Number(value);
+  if (!Number.isFinite(n) || n < 0) throw new Error(`${name} must be a non-negative number.`);
+  return n;
+}
+
+/**
+ * The filter every catalog read shares (the page, its count, the facets) — one place, so they
+ * can't drift. Search rejects two operators in ONE field object: price bounds are separate
+ * conditions joined by $and. Category: `allCategoriesInfo.categories` with `$matchItems` on the
+ * id (includes parent categories); never `$hasSome`, never V1 `collectionIds`. Facets discover
+ * PRODUCTS carrying a choice; the picker / PDP still resolves the variant.
+ */
+export function catalogFilter({ categoryId, minPrice, maxPrice, inStockOnly = false, choiceIds = [] }: CatalogSearchOptions = {}): Raw {
+  const min = priceBound(minPrice, "minPrice"), max = priceBound(maxPrice, "maxPrice");
+  if (min !== undefined && max !== undefined && min > max) throw new Error("minPrice must not exceed maxPrice.");
+  const and: Raw[] = [{ visible: true }];
+  if (categoryId) and.push({ "allCategoriesInfo.categories": { $matchItems: [{ id: categoryId }] } });
+  if (min !== undefined) and.push({ "actualPriceRange.minValue.amount": { $gte: String(min) } });
+  if (max !== undefined) and.push({ "actualPriceRange.minValue.amount": { $lte: String(max) } });
+  if (inStockOnly) and.push({ "inventory.availabilityStatus": { $eq: "IN_STOCK" } });
+  if (choiceIds.length) and.push({ "options.choicesSettings.choices.choiceId": { $hasSome: choiceIds } });
+  return { $and: and };
+}
+
+/** The full Search Products body (minus fields) for a page; a cursor request carries ONLY cursorPaging. */
+export function searchQuery(o: CatalogSearchOptions): Raw {
+  const { limit = 24, cursor, sort = "featured", search = "" } = o;
+  if (!Number.isInteger(limit) || limit < 1 || limit > 100) throw new Error("limit must be between 1 and 100.");
+  const paging = { cursorPaging: { limit, ...(cursor ? { cursor } : {}) } };
+  if (cursor) return paging;
+  if (!(sort in CATALOG_SORTS)) throw new Error("Unsupported catalog sort.");
+  if (search.trim().length > 100) throw new Error("Search must be at most 100 characters.");
+  return {
+    ...paging,
+    filter: catalogFilter(o),
+    ...(SORT_FIELDS[sort] ? { sort: SORT_FIELDS[sort] } : {}),
+    ...(search.trim() ? { search: { expression: search.trim(), fields: ["name"] } } : {}),
+  };
+}
+
+// ---- price rules ----------------------------------------------------------------------------------
+
+/**
+ * The price the buyer pays and the price to strike — exact precedence, shared by cards and
+ * variants. An automatic discount (priceAfterDiscount) wins and strikes the regular actualPrice;
+ * else actualPrice with the merchant's compareAtPrice as the "was". `!== undefined` on purpose:
+ * a discounted price of 0 is a real price.
+ */
+export function sellingPrice(price: Raw | undefined): { current?: Raw; original?: Raw } {
+  if (price?.priceAfterDiscount !== undefined) return { current: price.priceAfterDiscount, original: price.actualPrice };
+  return { current: price?.actualPrice, original: price?.compareAtPrice };
+}
+
+/** The struck price only when it is real and higher than what the buyer pays. */
+export function strike(original: Raw | undefined, current: Raw | undefined): string | null {
+  const o = Number(original?.amount), c = Number(current?.amount);
+  return original?.formattedAmount && Number.isFinite(o) && Number.isFinite(c) && o > c ? original.formattedAmount : null;
+}
+
+/** Every merchant ribbon, primary first, de-duplicated. A ribbon is a label, never proof of a price. */
+export function ribbonsOf(raw: Raw): string[] {
+  return [raw.ribbon?.name, ...((raw.additionalRibbons ?? []) as Raw[]).map((r) => r?.name)]
+    .filter((n, i, all): n is string => typeof n === "string" && n.length > 0 && all.indexOf(n) === i);
+}
+
+export function toAvailability(raw: Raw): Availability {
+  const s = raw.inventory?.availabilityStatus;
+  return s === "OUT_OF_STOCK" || s === "PARTIALLY_OUT_OF_STOCK" ? s : "IN_STOCK";
+}
+
+/**
+ * Every distinct media entry, main first, keyed on identity — two scaled URLs of one photo are
+ * ONE entry (the "two thumbnails for the same image" bug). Shared by the tile and the PDP.
+ */
+export function mediaEntries(raw: Raw, mediaKey: MediaKey): unknown[] {
+  const out: unknown[] = [];
+  const seen = new Set<string>();
+  for (const m of [raw.media?.main, ...((raw.media?.itemsInfo?.items ?? []) as Raw[])]) {
+    const v = m?.image ?? m;
+    const k = mediaKey(v);
+    if (!k || seen.has(k)) continue;
+    seen.add(k);
+    out.push(v);
+  }
+  return out;
+}
+
+// ---- DTO mappers -----------------------------------------------------------------------------------
+
+export function toSummary(raw: Raw, imgSrc: ImgSrc, mediaKey: MediaKey): ProductSummary {
+  const options: Raw[] = raw.options ?? [];
+  const media = mediaEntries(raw, mediaKey);
+  const mainUrl = imgSrc(media[0], 800, 800);
+  const hover = media.slice(1).map((m) => imgSrc(m, 800, 800)).filter(Boolean);
+  const availability = toAvailability(raw);
+  // Price: the cheapest variant's selling price (discount applied); the product RANGE when variants
+  // are priced differently — and NO struck price beside a range (a lone struck minimum claims a
+  // saving that may not apply to the variant picked).
+  const min = raw.actualPriceRange?.minValue, max = raw.actualPriceRange?.maxValue;
+  const isRange = !!(min?.amount && max?.amount && min.amount !== max.amount);
+  const minVariant: Raw | undefined = raw.variantSummary?.minPriceVariant;
+  const { current, original } = sellingPrice(minVariant?.price);
+  const ribbons = ribbonsOf(raw);
+  return {
+    id: id(raw),
+    slug: raw.slug ?? "",
+    name: raw.name ?? "",
+    price: current?.formattedAmount ?? min?.formattedAmount ?? "",
+    maxPrice: max?.formattedAmount ?? "",
+    compareAtPrice: isRange ? null : strike(original ?? raw.compareAtPriceRange?.minValue, current ?? min),
+    ribbon: ribbons[0] ?? null,
+    ribbons,
+    minPriceVariantId: minVariant ? id(minVariant) || minVariant.variantId || null : null,
+    availability,
+    // Out of stock but pre-orderable — label "Pre-order", not "Sold out".
+    preorder: raw.inventory?.preorderStatus === "ENABLED" && availability === "OUT_OF_STOCK",
+    imageUrl: mainUrl,
+    hoverImageUrl: hover[0] ?? "",
+    optionsSummary: options
+      .map((o) => {
+        const n = ((o.choicesSettings?.choices ?? []) as Raw[]).filter((c) => c.visible !== false).length;
+        return `${n} ${String(o.name ?? "").toLowerCase()}${n === 1 ? "" : "s"}`;
+      })
+      .join(" · "),
+    swatches: options
+      .filter((o) => o.optionRenderType === "SWATCH_CHOICES" || o.optionRenderType === "COLOR_CHOICES")
+      .flatMap((o) => (o.choicesSettings?.choices ?? []) as Raw[])
+      .filter((c) => c.visible !== false && c.colorCode)
+      .map((c) => String(c.colorCode)),
+    // Addable in one click: no options and plainly in stock.
+    quickAddable: options.length === 0 && availability === "IN_STOCK",
+  };
+}
+
+export function toOptions(raw: Raw): ProductOption[] {
+  return ((raw.options ?? []) as Raw[]).map((o) => ({
+    id: id(o) || o.name || "",
+    name: o.name ?? "",
+    isColor: o.optionRenderType === "SWATCH_CHOICES" || o.optionRenderType === "COLOR_CHOICES",
+    choices: ((o.choicesSettings?.choices ?? []) as Raw[])
+      .filter((c) => c.visible !== false) // a retired choice the merchant no longer sells
+      .map((c) => ({ choiceId: c.choiceId ?? "", name: c.name ?? "", colorCode: c.colorCode ?? null, inStock: c.inStock !== false })),
+  }));
+}
+
+export function toModifiers(raw: Raw): ProductModifier[] {
+  return ((raw.modifiers ?? []) as Raw[]).map((m) => ({
+    key: m.key ?? m.freeTextSettings?.key ?? m.name ?? "",
+    name: m.name ?? "",
+    mandatory: m.mandatory === true,
+    type: m.modifierRenderType === "FREE_TEXT" ? ("text" as const) : ("choices" as const),
+    choices: ((m.choicesSettings?.choices ?? []) as Raw[]).map((c) => ({ key: c.key ?? c.name ?? "", name: c.name ?? "" })),
+  }));
+}
+
+/** Variants keyed by optionName → choiceName. Buyable when in stock OR pre-orderable. */
+export function toVariants(raw: Raw): ProductVariant[] {
+  return ((raw.variantsInfo?.variants ?? []) as Raw[])
+    .filter((v) => v.visible !== false)
+    .map((v) => {
+      const choices: Record<string, string> = {};
+      for (const c of (v.choices ?? []) as Raw[]) {
+        const on = c.optionChoiceNames?.optionName, cn = c.optionChoiceNames?.choiceName;
+        if (on && cn) choices[on] = cn;
+      }
+      const { current, original } = sellingPrice(v.price);
+      return {
+        variantId: id(v),
+        choices,
+        price: current?.formattedAmount ?? "",
+        compareAtPrice: strike(original, current),
+        inStock: v.inventoryStatus?.inStock !== false,
+        preorderEnabled: v.inventoryStatus?.preorderEnabled === true,
+      };
+    });
+}
+
+export function toDetail(raw: Raw, imgSrc: ImgSrc, mediaKey: MediaKey): ProductDetail {
+  return {
+    ...toSummary(raw, imgSrc, mediaKey),
+    descriptionHtml: raw.plainDescription ?? "", // an HTML string despite the name — render as HTML
+    infoSections: ((raw.infoSections ?? []) as Raw[])
+      .map((s) => ({ title: s.title ?? "", html: s.plainDescription ?? "" }))
+      .filter((s) => s.title || s.html),
+    // De-duplicated on media identity, then resolved once at one size.
+    gallery: mediaEntries(raw, mediaKey).map((m) => imgSrc(m, 1200, 1200)).filter(Boolean),
+    options: toOptions(raw),
+    modifiers: toModifiers(raw),
+    variants: toVariants(raw),
+  };
+}
+
+export function toCategory(raw: Raw): Category {
+  return { id: id(raw), slug: raw.slug ?? "", name: raw.name ?? "", description: raw.description ?? "" };
+}
+
+/** Facets + price bounds from a scope's products (the 100-product read), so the panel only offers filters that exist. */
+export function toFacetData(products: Raw[]): FacetData {
+  const byName = new Map<string, Facet>();
+  let lo = Infinity, hi = -Infinity, currency = "";
+  for (const p of products) {
+    const min = Number(p.actualPriceRange?.minValue?.amount), max = Number(p.actualPriceRange?.maxValue?.amount);
+    if (Number.isFinite(min)) lo = Math.min(lo, min);
+    if (Number.isFinite(max)) hi = Math.max(hi, max);
+    currency = currency || p.currency || "";
+    for (const o of (p.options ?? []) as Raw[]) {
+      if (!o.name) continue;
+      const facet: Facet = byName.get(o.name) ?? { name: o.name, isColor: o.optionRenderType === "SWATCH_CHOICES" || o.optionRenderType === "COLOR_CHOICES", choices: [] };
+      for (const c of (o.choicesSettings?.choices ?? []) as Raw[]) {
+        if (c.visible === false || !c.choiceId) continue;
+        if (!facet.choices.some((x) => x.id === c.choiceId)) facet.choices.push({ id: c.choiceId, name: c.name ?? "", colorCode: c.colorCode ?? null });
+      }
+      byName.set(o.name, facet);
+    }
+  }
+  return {
+    facets: [...byName.values()].filter((f) => f.choices.length > 1),
+    priceRange: Number.isFinite(lo) && Number.isFinite(hi) && hi > lo ? { min: Math.floor(lo), max: Math.ceil(hi), currency } : null,
+  };
+}
+
+/**
+ * Resolve the variant for the buyer's selections (optionName → choiceName). A product with no
+ * options resolves to its single variant; with options every option must be selected and match.
+ * null while incomplete. Selections start EMPTY — never pre-pick a first choice.
+ */
+export function resolveVariant(detail: ProductDetail, selections: Record<string, string>): ProductVariant | null {
+  if (detail.options.length === 0) return detail.variants[0] ?? null;
+  if (!detail.options.every((o) => selections[o.name])) return null;
+  return detail.variants.find((v) => detail.options.every((o) => v.choices[o.name] === selections[o.name])) ?? null;
+}