@wix/agent-skills 1.25.0 → 1.27.0

package/skills/wix-headless-templates/storefront/project/src/wix/storefront/catalog-core.ts

@@ -0,0 +1,698 @@
+// Catalog rules and DTO mapping — transport-agnostic, imported by BOTH transports: ./catalog.ts
+// (the SDK, managed Astro and React) and the REST twin in templates/storefront/rest/catalog.ts
+// (fetch, a static site or a port to another language). Every rule about prices, ribbons,
+// ranges, media, variants, facets 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,
+  Breadcrumb,
+  Category,
+  Facet,
+  FacetChoice,
+  FacetData,
+  ProductDetail,
+  ProductModifier,
+  ProductOption,
+  ProductSummary,
+  ProductVariant,
+  SubscriptionPlan,
+  VariantInventory,
+} 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 and the discount rule names: 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), the info sections with HTML bodies, each variant's plan prices
+// (SUBSCRIPTION_PRICES_INFO), and the category path (BREADCRUMBS_INFO, DIRECT_CATEGORIES_INFO).
+export const DETAIL_FIELDS = [
+  ...LIST_FIELDS,
+  "PLAIN_DESCRIPTION",
+  "VARIANT_OPTION_CHOICE_NAMES",
+  "INFO_SECTION",
+  "INFO_SECTION_PLAIN_DESCRIPTION",
+  "SUBSCRIPTION_PRICES_INFO",
+  "BREADCRUMBS_INFO",
+  "DIRECT_CATEGORIES_INFO",
+  // the gallery image linked to each option choice (the dashboard's "image per colour"); variant
+  // media is derived from it at creation only, so the choice is the source of truth
+  "PRODUCT_CHOICES_MEDIA_REFERENCES",
+] as const;
+
+/** Stores' category tree — every Categories API call names it. */
+export const STORES_TREE = { appNamespace: "@wix/stores", treeKey: null } 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" },
+  nameDesc: { label: "Name: Z–A" },
+  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" }],
+  nameDesc: [{ fieldName: "name", order: "DESC" }],
+  newest: [{ fieldName: "createdDate", order: "DESC" }, { fieldName: "name", order: "ASC" }],
+};
+
+// The search fields a product carries its customization ids under — the same paths aggregate
+// (facets) and filter (selection), so a facet always filters on the field it was counted from.
+export const OPTION_CHOICE_FIELD = "options.choicesSettings.choices.choiceId";
+export const MODIFIER_CHOICE_FIELD = "modifiers.choicesSettings.choices.choiceId";
+
+/** The buyer's picks in ONE facet: a choice matches when the product carries ANY of them; facets AND together. */
+export interface FacetSelection {
+  /** The facet (customization) id. */
+  id: string;
+  kind: "option" | "modifier";
+  /** Choice ids — linked choices already expanded under their primary (see expandFacetChoiceIds). */
+  choiceIds: string[];
+}
+
+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, site currency: the cheapest variant at least `minPrice`, the dearest at most `maxPrice`. */
+  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;
+  /** Facet selections — one $hasSome per facet, AND-ed across facets (Red OR Blue, AND Large). */
+  facetSelections?: FacetSelection[];
+}
+
+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`. The price bounds
+ * bracket the product's RANGE: its minimum at least `minPrice`, its maximum at most `maxPrice` —
+ * a "$10–$50" filter must not admit a $12–$400 product. Facets discover PRODUCTS carrying a
+ * choice; the picker / PDP still resolves the variant.
+ */
+export function catalogFilter({ categoryId, minPrice, maxPrice, inStockOnly = false, facetSelections = [] }: 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.maxValue.amount": { $lte: String(max) } });
+  if (inStockOnly) and.push({ "inventory.availabilityStatus": { $eq: "IN_STOCK" } });
+  for (const f of facetSelections) {
+    if (!f.choiceIds.length) continue;
+    and.push({ [f.kind === "modifier" ? MODIFIER_CHOICE_FIELD : OPTION_CHOICE_FIELD]: { $hasSome: f.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"] } } : {}),
+  };
+}
+
+/** Read a search response's paging: `hasNext` is authoritative, the cursor is what continues. */
+export function pageInfo(res: Raw | null | undefined): { nextCursor: string | null; hasMore: boolean } {
+  const nextCursor: string | null = res?.pagingMetadata?.cursors?.next ?? null;
+  const hasNext = res?.pagingMetadata?.hasNext;
+  return { nextCursor, hasMore: typeof hasNext === "boolean" ? hasNext && !!nextCursor : !!nextCursor };
+}
+
+// ---- facets (aggregations + customizations) ---------------------------------------------------------
+
+// The aggregations-only search that discovers a scope's filters: price bounds as scalars, the
+// option/modifier ids and their choice ids as value buckets with counts. `cursorPaging.limit: 0`
+// returns no products — the whole catalog is summarised in one call, however many products.
+export const FACET_AGGREGATIONS: Raw[] = [
+  { name: "min_price", type: "SCALAR", fieldPath: "actualPriceRange.minValue.amount", scalar: { type: "MIN" } },
+  { name: "max_price", type: "SCALAR", fieldPath: "actualPriceRange.maxValue.amount", scalar: { type: "MAX" } },
+  { name: "options", type: "VALUE", fieldPath: "options.id", value: { limit: 1000, sortType: "COUNT", sortDirection: "DESC" } },
+  { name: "options_with_choice", type: "VALUE", fieldPath: OPTION_CHOICE_FIELD, value: { limit: 20000, sortType: "COUNT", sortDirection: "DESC" } },
+  { name: "modifiers", type: "VALUE", fieldPath: "modifiers.id", value: { limit: 1000, sortType: "COUNT", sortDirection: "DESC" } },
+  { name: "modifiers_with_choice", type: "VALUE", fieldPath: MODIFIER_CHOICE_FIELD, value: { limit: 20000, sortType: "COUNT", sortDirection: "DESC" } },
+];
+
+/** The Search Products body that returns only the aggregations of a scope. */
+export function facetSearchBody(categoryId?: string | null): Raw {
+  return { filter: catalogFilter({ categoryId }), cursorPaging: { limit: 0 }, aggregations: FACET_AGGREGATIONS };
+}
+
+/** The ids the aggregations named, plus per-choice product counts and the price bounds. */
+export interface FacetAggregates {
+  minPrice: number | null;
+  maxPrice: number | null;
+  optionIds: string[];
+  modifierIds: string[];
+  /** choiceId -> products carrying it, options and modifiers together (ids are GUIDs, they never collide). */
+  choiceCounts: Record<string, number>;
+}
+
+export function readFacetAggregates(res: Raw | null | undefined): FacetAggregates {
+  const byName = new Map<string, Raw>();
+  for (const r of (res?.aggregationData?.results ?? []) as Raw[]) if (r?.name) byName.set(r.name, r);
+  const ids = (name: string): string[] => ((byName.get(name)?.values?.results ?? []) as Raw[]).map((b) => b?.value).filter((v): v is string => typeof v === "string" && v.length > 0);
+  const counts: Record<string, number> = {};
+  for (const name of ["options_with_choice", "modifiers_with_choice"]) {
+    for (const b of (byName.get(name)?.values?.results ?? []) as Raw[]) if (typeof b?.value === "string" && typeof b?.count === "number") counts[b.value] = b.count;
+  }
+  const scalar = (name: string): number | null => {
+    const v = byName.get(name)?.scalar?.value;
+    return typeof v === "number" && Number.isFinite(v) ? v : null;
+  };
+  return { minPrice: scalar("min_price"), maxPrice: scalar("max_price"), optionIds: ids("options"), modifierIds: ids("modifiers"), choiceCounts: counts };
+}
+
+/** Every customization id the facets need names, colors and choice order for. */
+export function facetCustomizationIds(agg: FacetAggregates): string[] {
+  return [...new Set([...agg.optionIds, ...agg.modifierIds])];
+}
+
+const numeric = (s: string): number | null => {
+  const t = s.trim();
+  if (!t) return null;
+  const n = Number(t);
+  return Number.isFinite(n) ? n : null;
+};
+// Names sort case-insensitively, numbers first and numerically ("2", "10", "L").
+const byNameNumericFirst = <T>(items: T[], name: (t: T) => string): T[] =>
+  [...items].sort((a, b) => {
+    const na = numeric(name(a)), nb = numeric(name(b));
+    if (na !== null && nb !== null) return na - nb;
+    if (na !== null) return -1;
+    if (nb !== null) return 1;
+    return name(a).toLowerCase().localeCompare(name(b).toLowerCase());
+  });
+
+/**
+ * One facet from a customization entity and the counts the aggregation gave its choices: only
+ * choices some product in the scope carries; a linked choice ("Light red", `primaryChoiceIds`)
+ * folds into its primary with its count and rides along as a childId when the primary is picked;
+ * order per the merchant's `choicesSettings.sortOrder` (BY_NAME, BY_PRODUCT_COUNT, MANUAL; the
+ * default is name for text, count for swatches).
+ */
+export function toFacet(customization: Raw, kind: Facet["kind"], choiceCounts: Record<string, number>): Facet {
+  const all: Raw[] = customization.choicesSettings?.choices ?? [];
+  const parentOf = new Map<string, string[]>(); // childId -> primary ids
+  for (const c of all) if (Array.isArray(c.primaryChoiceIds) && c.primaryChoiceIds.length) parentOf.set(id(c), c.primaryChoiceIds);
+  const choices = new Map<string, FacetChoice>();
+  const choiceOf = (c: Raw): FacetChoice => ({ id: id(c), name: c.name ?? "", colorCode: c.colorCode ?? null, count: 0, childIds: [] });
+  for (const c of all) {
+    const count = choiceCounts[id(c)] ?? 0;
+    const primaries = parentOf.get(id(c));
+    if (primaries) {
+      if (!count) continue;
+      for (const pid of primaries) {
+        const primary = all.find((p) => id(p) === pid);
+        if (!primary) continue;
+        const entry = choices.get(pid) ?? choiceOf(primary);
+        entry.count += count;
+        entry.childIds.push(id(c));
+        choices.set(pid, entry);
+      }
+      continue;
+    }
+    if (!count && !choices.has(id(c))) continue;
+    const entry = choices.get(id(c)) ?? choiceOf(c);
+    entry.count += count;
+    choices.set(id(c), entry);
+  }
+  // a primary that only got children (no own count) surfaces through them above; drop empties
+  let list = [...choices.values()].filter((c) => c.id && c.count > 0);
+  const isColor = customization.customizationRenderType === "SWATCH_CHOICES";
+  const order: string = customization.choicesSettings?.sortOrder ?? "DEFAULT";
+  if (order === "BY_NAME" || (order === "DEFAULT" && !isColor)) list = byNameNumericFirst(list, (c) => c.name);
+  else if (order === "BY_PRODUCT_COUNT" || (order === "DEFAULT" && parentOf.size > 0)) list = [...list].sort((a, b) => b.count - a.count);
+  else if (order === "MANUAL") {
+    const pos = new Map(all.map((c, i) => [id(c), i]));
+    list = [...list].sort((a, b) => (pos.get(a.id) ?? 1e9) - (pos.get(b.id) ?? 1e9));
+  }
+  return { id: id(customization), name: customization.name ?? "", kind, isColor, choices: list };
+}
+
+/**
+ * Facets + price bounds from the aggregations and the customization entities they named. Free-text
+ * customizations never arrive (the query excludes them); a facet with one choice narrows nothing
+ * and is dropped; swatch facets first, then text, each by name.
+ */
+export function toFacetData(agg: FacetAggregates, customizations: Raw[]): FacetData {
+  const byId = new Map(customizations.map((c) => [id(c), c]));
+  const build = (ids: string[], kind: Facet["kind"]): Facet[] =>
+    ids.flatMap((cid) => {
+      const c = byId.get(cid);
+      if (!c || c.customizationRenderType === "FREE_TEXT") return [];
+      const f = toFacet(c, kind, agg.choiceCounts);
+      return f.choices.length > 1 ? [f] : [];
+    });
+  const facets = [...build(agg.optionIds, "option"), ...build(agg.modifierIds, "modifier")];
+  const swatches = byNameNumericFirst(facets.filter((f) => f.isColor), (f) => f.name);
+  const texts = byNameNumericFirst(facets.filter((f) => !f.isColor), (f) => f.name);
+  const lo = agg.minPrice, hi = agg.maxPrice;
+  return {
+    facets: [...swatches, ...texts],
+    priceRange: lo !== null && hi !== null && hi > lo ? { min: Math.floor(lo), max: Math.ceil(hi) } : null,
+  };
+}
+
+/** The ids a selection sends for a facet: each picked choice plus the linked choices folded under it. */
+export function expandFacetChoiceIds(facet: Facet | undefined, choiceIds: string[]): string[] {
+  const out = new Set<string>();
+  for (const cid of choiceIds) {
+    out.add(cid);
+    for (const child of facet?.choices.find((c) => c.id === cid)?.childIds ?? []) out.add(child);
+  }
+  return [...out];
+}
+
+// ---- 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";
+}
+
+/**
+ * The product-level pre-order state: every variant pre-orderable, or some are and the product
+ * is out of stock (`inventory.preorderAvailability`). Older responses without that field fall
+ * back to `preorderStatus`.
+ */
+export function isPreorderProduct(raw: Raw): boolean {
+  const availability = toAvailability(raw);
+  const pa = raw.inventory?.preorderAvailability;
+  if (pa) return pa === "ALL_VARIANTS" || (pa === "SOME_VARIANTS" && availability === "OUT_OF_STOCK");
+  return raw.inventory?.preorderStatus === "ENABLED" && availability === "OUT_OF_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;
+}
+
+const visibleSubscriptions = (raw: Raw): Raw[] => ((raw.subscriptionDetails?.subscriptions ?? []) as Raw[]).filter((s) => s.visible !== false);
+
+// ---- 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). When that cheapest variant is DISCOUNTED the
+  // range's top is unknown here (actualPriceRange is pre-discount) — the tile says "From {price}"
+  // and the PDP recomputes the range from its variants.
+  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 discounted = minVariant?.price?.priceAfterDiscount !== undefined;
+  const price = current?.formattedAmount ?? min?.formattedAmount ?? "";
+  const fromPrice = isRange && discounted;
+  const ribbons = ribbonsOf(raw);
+  const hasSubscriptions = visibleSubscriptions(raw).length > 0;
+  return {
+    id: id(raw),
+    slug: raw.slug ?? "",
+    name: raw.name ?? "",
+    price,
+    maxPrice: fromPrice ? price : max?.formattedAmount ?? "",
+    fromPrice,
+    compareAtPrice: isRange ? null : strike(original ?? raw.compareAtPriceRange?.minValue, current ?? min),
+    discountNames: ((raw.discountInfo?.discountRuleNames ?? []) as unknown[]).filter((n): n is string => typeof n === "string" && n.length > 0),
+    pricePerUnit: minVariant?.physicalProperties?.pricePerUnit?.description ?? raw.physicalProperties?.pricePerUnitRange?.minValue?.description ?? null,
+    ribbon: ribbons[0] ?? null,
+    ribbons,
+    minPriceVariantId: minVariant ? id(minVariant) || minVariant.variantId || null : null,
+    availability,
+    preorder: isPreorderProduct(raw),
+    hasSubscriptions,
+    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, plainly in stock, and no plan to choose.
+    quickAddable: options.length === 0 && availability === "IN_STOCK" && !hasSubscriptions,
+  };
+}
+
+/**
+ * A choice's linked image. With PRODUCT_CHOICES_MEDIA_REFERENCES the choice carries
+ * `media.items[].mediaId` pointing into the product gallery; without it Wix returns the same link
+ * as the deprecated `linkedMedia` with the media object inline. Both read forms are handled.
+ */
+function choiceImage(c: Raw, gallery: Map<string, Raw>, imgSrc: ImgSrc | undefined): string | null {
+  if (!imgSrc) return null;
+  const ref = (c.media?.items ?? [])[0]?.mediaId;
+  const linked = (c.linkedMedia ?? [])[0];
+  const m = ref ? gallery.get(String(ref)) : linked ? (linked.image ?? linked) : null;
+  return m ? imgSrc(m, 1200, 1200) || null : null;
+}
+
+export function toOptions(raw: Raw, imgSrc?: ImgSrc): ProductOption[] {
+  // the gallery by item id — `id` over REST, `_id` through the SDK (both feed this mapper)
+  const gallery = new Map<string, Raw>();
+  for (const m of [raw.media?.main, ...((raw.media?.itemsInfo?.items ?? []) as Raw[])]) {
+    const key = m?._id ?? m?.id;
+    if (key) gallery.set(String(key), m.image ?? m);
+  }
+  return ((raw.options ?? []) as Raw[]).map((o) => ({
+    id: id(o) || o.name || "",
+    key: o.key ?? 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 ?? "",
+        key: c.key ?? c.name ?? "",
+        name: c.name ?? "",
+        colorCode: c.colorCode ?? null,
+        inStock: c.inStock !== false,
+        imageUrl: choiceImage(c, gallery, imgSrc),
+      })),
+  }));
+}
+
+// Mandatory unless the API says `mandatory: false` — an omitted flag is REQUIRED on Wix's own
+// storefront. A free-text modifier is keyed by `freeTextSettings.key` (what `customTextFields`
+// takes); a choice modifier by its own `key` (what `options` takes).
+export function toModifiers(raw: Raw): ProductModifier[] {
+  return ((raw.modifiers ?? []) as Raw[]).map((m) => {
+    const isText = m.modifierRenderType === "FREE_TEXT";
+    const ft: Raw = m.freeTextSettings ?? {};
+    const charCount = (v: unknown): number | null => (typeof v === "number" && v > 0 ? v : null);
+    return {
+      id: id(m) || m.key || m.name || "",
+      key: isText ? ft.key ?? m.key ?? m.name ?? "" : m.key ?? m.name ?? "",
+      name: m.name ?? "",
+      mandatory: m.mandatory !== false,
+      type: isText ? ("text" as const) : ("choices" as const),
+      title: (isText ? ft.title : undefined) || m.name || "",
+      maxChars: isText ? charCount(ft.maxCharCount) : null,
+      minChars: isText ? charCount(ft.minCharCount) : null,
+      choices: ((m.choicesSettings?.choices ?? []) as Raw[]).map((c) => ({ choiceId: c.choiceId ?? "", key: c.key ?? c.name ?? "", name: c.name ?? "" })),
+    };
+  });
+}
+
+const FREQUENCY_WORD: Record<string, string> = { DAY: "day", WEEK: "week", MONTH: "month", YEAR: "year" };
+
+/** "every 2 months · 6 payments" / "every month · until cancelled" from a plan's settings. */
+export function planTerms(frequency: string | null, interval: number, billingCycles: number | null): string {
+  const parts: string[] = [];
+  const u = FREQUENCY_WORD[String(frequency ?? "")];
+  if (u) parts.push(`every ${interval > 1 ? `${interval} ${u}s` : u}`);
+  parts.push(billingCycles ? `${billingCycles} payments` : "until cancelled");
+  return parts.join(" · ");
+}
+
+/** The product's visible recurring plans; a plan without `billingCycles` auto-renews. */
+export function toSubscriptionPlans(raw: Raw): SubscriptionPlan[] {
+  return visibleSubscriptions(raw).map((s) => {
+    const frequency = (["DAY", "WEEK", "MONTH", "YEAR"] as const).find((f) => f === s.frequency) ?? null;
+    const interval = typeof s.interval === "number" && s.interval > 0 ? s.interval : 1;
+    const billingCycles = s.autoRenewal === true ? null : typeof s.billingCycles === "number" && s.billingCycles > 0 ? s.billingCycles : null;
+    return { id: id(s), name: s.title ?? "", description: s.description ?? "", frequency, interval, billingCycles, terms: planTerms(frequency, interval, billingCycles) };
+  });
+}
+
+/**
+ * Variants keyed by optionId → choiceId (names kept for display). Buyable when in stock OR
+ * pre-orderable. `quantity`/`preorderMessage` stay null here — the Inventory Items read fills them
+ * (mergeInventory). `variant.media` is read-only on the API: Wix derives it from the media linked
+ * to the variant's choice (a product with several options derives it only when the choices
+ * agree). Mapped to a URL so a PDP can show the selected variant's picture without knowing how
+ * Wix derives it.
+ */
+export function toVariants(raw: Raw, imgSrc: ImgSrc): ProductVariant[] {
+  return ((raw.variantsInfo?.variants ?? []) as Raw[])
+    .filter((v) => v.visible !== false)
+    .map((v) => {
+      const choices: Record<string, string> = {};
+      const choiceIds: 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 oi = c.optionChoiceIds?.optionId, ci = c.optionChoiceIds?.choiceId;
+        if (oi && ci) choiceIds[oi] = ci;
+      }
+      const { current, original } = sellingPrice(v.price);
+      const vm = v.media ? (v.media.image ?? v.media) : null;
+      const subscriptionPrices: Record<string, string> = {};
+      for (const sp of (v.subscriptionPricesInfo?.subscriptionPrices ?? []) as Raw[]) {
+        const formatted = sp.priceAfterDiscount?.formattedAmount ?? sp.price?.formattedAmount;
+        if (sp.subscriptionId && formatted) subscriptionPrices[sp.subscriptionId] = formatted;
+      }
+      const amount = Number(current?.amount);
+      return {
+        variantId: id(v),
+        choiceIds,
+        choices,
+        price: current?.formattedAmount ?? "",
+        priceAmount: Number.isFinite(amount) ? amount : 0,
+        compareAtPrice: strike(original, current),
+        pricePerUnit: v.physicalProperties?.pricePerUnit?.description ?? null,
+        sku: v.sku ?? null,
+        subscriptionPrices,
+        inStock: v.inventoryStatus?.inStock !== false,
+        preorderEnabled: v.inventoryStatus?.preorderEnabled === true,
+        quantity: null,
+        preorderMessage: null,
+        imageUrl: vm ? imgSrc(vm, 1200, 1200) || null : null,
+      };
+    });
+}
+
+/** The product's category path and direct categories, from BREADCRUMBS_INFO / DIRECT_CATEGORIES_INFO. */
+export function toBreadcrumbs(info: Raw | undefined): Breadcrumb[] {
+  return ((info?.breadcrumbs ?? []) as Raw[])
+    .filter((b) => b.categoryId)
+    .map((b) => ({ id: b.categoryId, name: b.categoryName ?? "", slug: b.categorySlug ?? "" }));
+}
+
+export function toDetail(raw: Raw, imgSrc: ImgSrc, mediaKey: MediaKey): ProductDetail {
+  const summary = toSummary(raw, imgSrc, mediaKey);
+  const variants = toVariants(raw, imgSrc);
+  // The exact range from the variants' SELLING prices (discounts applied) — the summary's range is
+  // pre-discount and had to say "From" when the cheapest variant was discounted.
+  let price = summary.price, maxPrice = summary.maxPrice, compareAtPrice = summary.compareAtPrice;
+  if (variants.length) {
+    const lo = variants.reduce((a, v) => (v.priceAmount < a.priceAmount ? v : a));
+    const hi = variants.reduce((a, v) => (v.priceAmount > a.priceAmount ? v : a));
+    price = lo.price || price;
+    maxPrice = hi.price || maxPrice;
+    compareAtPrice = price !== maxPrice ? null : lo.compareAtPrice;
+  }
+  return {
+    ...summary,
+    price,
+    maxPrice,
+    fromPrice: false,
+    compareAtPrice,
+    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),
+    breadcrumbs: toBreadcrumbs(raw.breadcrumbsInfo),
+    categoryIds: ((raw.directCategoriesInfo?.categories ?? []) as Raw[]).map((c) => id(c)).filter(Boolean),
+    options: toOptions(raw, imgSrc),
+    modifiers: toModifiers(raw),
+    variants,
+    subscriptions: toSubscriptionPlans(raw),
+    allowOneTimePurchase: raw.subscriptionDetails?.allowOneTimePurchases === true,
+  };
+}
+
+export function toCategory(raw: Raw, imgSrc: ImgSrc): Category {
+  const parent: Raw | undefined = raw.parentCategory;
+  return {
+    id: id(raw),
+    slug: raw.slug ?? "",
+    name: raw.name ?? "",
+    description: raw.description ?? "",
+    imageUrl: imgSrc(raw.image, 1200, 1200),
+    parentId: parent ? id(parent) || null : null,
+    index: typeof parent?.index === "number" ? parent.index : 0,
+    productCount: typeof raw.itemCounter === "number" ? raw.itemCounter : null,
+    breadcrumbs: toBreadcrumbs(raw.breadcrumbsInfo),
+  };
+}
+
+// ---- inventory --------------------------------------------------------------------------------------
+
+/** Inventory Items → per-variant record: a PREORDER item's remaining allowance is `preorderInfo.quantity`. */
+export function toInventory(items: Raw[]): Record<string, VariantInventory> {
+  const out: Record<string, VariantInventory> = {};
+  for (const it of items) {
+    if (!it?.variantId) continue;
+    const status = it.availabilityStatus === "IN_STOCK" || it.availabilityStatus === "PREORDER" ? it.availabilityStatus : "OUT_OF_STOCK";
+    const tracked = it.trackQuantity === true;
+    out[it.variantId] = {
+      status,
+      quantity: tracked && typeof it.quantity === "number" ? Math.max(0, it.quantity) : null,
+      preorderQuantity: tracked && typeof it.preorderInfo?.quantity === "number" ? Math.max(0, it.preorderInfo.quantity) : null,
+      preorderMessage: it.preorderInfo?.message || null,
+    };
+  }
+  return out;
+}
+
+/**
+ * The variants with the default location's live inventory: status → inStock/preorderEnabled, the
+ * remaining units (`quantity`: stock, or the pre-order allowance while pre-ordering), the pre-order
+ * message. A variant without a record keeps its catalog flags.
+ */
+export function mergeInventory(variants: ProductVariant[], inventory: Record<string, VariantInventory>): ProductVariant[] {
+  return variants.map((v) => {
+    const inv = inventory[v.variantId];
+    if (!inv) return v;
+    const preorder = inv.status === "PREORDER";
+    return {
+      ...v,
+      inStock: inv.status === "IN_STOCK",
+      preorderEnabled: preorder,
+      quantity: preorder ? inv.preorderQuantity : inv.quantity,
+      preorderMessage: preorder ? inv.preorderMessage : null,
+    };
+  });
+}
+
+// ---- selection rules --------------------------------------------------------------------------------
+
+/**
+ * Resolve the variant for the buyer's selections (optionId → choiceId). 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.id])) return null;
+  return detail.variants.find((v) => detail.options.every((o) => v.choiceIds[o.id] === selections[o.id])) ?? null;
+}
+
+/**
+ * Per-choice availability AGAINST the current selection: optionId → choiceId → { inStock, exists }.
+ * With nothing picked, a choice's catalog flag. Otherwise each choice is judged as if picked on
+ * top of the other selections: `exists` when some variant answers to that combination, `inStock`
+ * when one of those is buyable (in stock or pre-orderable). Red picked → XL greys out when Red/XL
+ * is sold out, but stays clickable elsewhere.
+ */
+export function choiceAvailability(detail: ProductDetail, selections: Record<string, string>): Record<string, Record<string, { inStock: boolean; exists: boolean }>> {
+  const picked = Object.entries(selections).filter(([oid, cid]) => oid && cid);
+  const out: Record<string, Record<string, { inStock: boolean; exists: boolean }>> = {};
+  for (const o of detail.options) {
+    out[o.id] = {};
+    for (const c of o.choices) {
+      if (!picked.length) {
+        out[o.id][c.choiceId] = { inStock: c.inStock, exists: true };
+        continue;
+      }
+      const candidate = [...picked.filter(([oid]) => oid !== o.id), [o.id, c.choiceId] as [string, string]];
+      let exists = false, inStock = false;
+      for (const v of detail.variants) {
+        if (!candidate.every(([oid, cid]) => v.choiceIds[oid] === cid)) continue;
+        exists = true;
+        if (v.inStock || v.preorderEnabled) { inStock = true; break; }
+      }
+      out[o.id][c.choiceId] = { inStock, exists };
+    }
+  }
+  return out;
+}
+
+/** Wix's storefront caps the stepper at 99999 when stock isn't counted. */
+export const MAX_QUANTITY = 99999;
+
+/** The most a buyer may add of a variant: its remaining units when counted (none left → the cap; the add is blocked anyway), else the cap. */
+export function maxPurchasable(variant: ProductVariant | null): number {
+  return variant?.quantity || MAX_QUANTITY;
+}