@wix/agent-skills 1.19.2 → 1.20.1

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

@@ -1,227 +1,80 @@
-// Catalog reads (Wix Stores Catalog V3) — the only file that touches raw catalog entities.
-// Everything it returns is a plain DTO from ./types: images resolved, prices formatted,
-// variants normalized. Copy as-is; extend by adding functions, not by editing these.
+// Catalog reads (Wix Stores Catalog V3) over the SDK — the only file that touches raw catalog
+// entities on this transport. Everything it returns is a plain DTO from ./types. The rules and
+// mappers live in ./catalog-core (shared with the REST twin in references/storefront/rest/); this
+// file is the transport only. Copy as-is; extend by adding functions, not by editing these.
 // docs: https://dev.wix.com/docs/api-reference/business-solutions/stores/catalog-v3/products-v3/search-products.md
 // docs: https://dev.wix.com/docs/api-reference/business-solutions/stores/catalog-v3/products-v3/get-product-by-slug.md
 // docs: https://dev.wix.com/docs/api-reference/business-solutions/stores/catalog-v3/categories/query-categories.md
 import { productsV3 } from "@wix/stores";
 import { categories as categoriesModule } from "@wix/categories";
 import { wixModule } from "../sdk";
-import { imgSrc } from "../media";
-import type {
-  Category,
-  ProductDetail,
-  ProductOption,
-  ProductModifier,
-  ProductSummary,
-  ProductVariant,
-  Availability,
-} from "./types";
+import { imgSrc, mediaKey } from "../media";
+import {
+  CATALOG_SORTS,
+  DETAIL_FIELDS,
+  LIST_FIELDS,
+  catalogFilter,
+  resolveVariant,
+  searchQuery,
+  sellingPrice,
+  toCategory,
+  toDetail,
+  toFacetData,
+  toSummary,
+  type CatalogSearchOptions,
+  type CatalogSort,
+  type Raw,
+} from "./catalog-core";
+import type { Category, Facet, FacetData, ProductDetail, ProductSummary } from "./types";
+
+export { CATALOG_SORTS, resolveVariant, sellingPrice, type CatalogSearchOptions, type CatalogSort };
 
 const products = wixModule(productsV3);
 const categories = wixModule(categoriesModule);
 
-// Requested on every product read. CURRENCY populates formattedAmount (without it, prices render
-// as bare unlocalized numbers); MEDIA_ITEMS_INFO populates the gallery; the detail read adds
-// PLAIN_DESCRIPTION and VARIANT_OPTION_CHOICE_NAMES (which populates variantsInfo.variants).
-const LIST_FIELDS = ["CURRENCY", "MEDIA_ITEMS_INFO"];
-const DETAIL_FIELDS = [...LIST_FIELDS, "PLAIN_DESCRIPTION", "VARIANT_OPTION_CHOICE_NAMES"];
-
-type RawProduct = Record<string, any>;
-
-function toAvailability(raw: RawProduct): Availability {
-  const status = raw.inventory?.availabilityStatus;
-  return status === "OUT_OF_STOCK" || status === "PARTIALLY_OUT_OF_STOCK"
-    ? status
-    : "IN_STOCK";
-}
-
-function toSummary(raw: RawProduct): ProductSummary {
-  const options: RawProduct[] = raw.options ?? [];
-  const galleryItems: RawProduct[] = raw.media?.itemsInfo?.items ?? [];
-  const mainUrl = imgSrc(raw.media?.main, 800, 800);
-  const hover = galleryItems
-    .map((m) => imgSrc(m.image ?? m, 800, 800))
-    .filter((u) => u && u !== mainUrl);
-  const availability = toAvailability(raw);
-  const preorder = raw.inventory?.preorderStatus === "ENABLED" && availability === "OUT_OF_STOCK";
-  const optionsSummary = options
-    .map((o) => {
-      const visible = (o.choicesSettings?.choices ?? []).filter((c: RawProduct) => c.visible !== false);
-      return `${visible.length} ${String(o.name ?? "").toLowerCase()}${visible.length === 1 ? "" : "s"}`;
-    })
-    .join(" · ");
-  return {
-    id: raw._id ?? "",
-    slug: raw.slug ?? "",
-    name: raw.name ?? "",
-    price: raw.actualPriceRange?.minValue?.formattedAmount ?? "",
-    maxPrice: raw.actualPriceRange?.maxValue?.formattedAmount ?? "",
-    compareAtPrice: raw.compareAtPriceRange?.minValue?.formattedAmount ?? null,
-    ribbon: raw.ribbon?.name ?? null,
-    availability,
-    preorder,
-    imageUrl: mainUrl,
-    hoverImageUrl: hover[0] ?? "",
-    optionsSummary,
-    quickAddable: options.length === 0 && availability === "IN_STOCK",
-  };
-}
-
-function toOptions(raw: RawProduct): ProductOption[] {
-  return (raw.options ?? []).map((o: RawProduct) => {
-    const isColor = o.optionRenderType === "SWATCH_CHOICES" || o.optionRenderType === "COLOR_CHOICES";
-    return {
-      id: o._id ?? o.id ?? o.name ?? "",
-      name: o.name ?? "",
-      isColor,
-      choices: (o.choicesSettings?.choices ?? [])
-        .filter((c: RawProduct) => c.visible !== false)
-        .map((c: RawProduct) => ({
-          choiceId: c.choiceId ?? "",
-          name: c.name ?? "",
-          colorCode: c.colorCode ?? null,
-          inStock: c.inStock !== false,
-        })),
-    };
-  });
-}
-
-function toModifiers(raw: RawProduct): ProductModifier[] {
-  return (raw.modifiers ?? []).map((m: RawProduct) => ({
-    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 ?? []).map((c: RawProduct) => ({
-      key: c.key ?? c.name ?? "",
-      name: c.name ?? "",
-    })),
-  }));
-}
-
-function toVariants(raw: RawProduct): ProductVariant[] {
-  return (raw.variantsInfo?.variants ?? []).map((v: RawProduct) => {
-    const choices: Record<string, string> = {};
-    for (const c of v.choices ?? []) {
-      const names = c.optionChoiceNames;
-      if (names?.optionName) choices[names.optionName] = names.choiceName ?? "";
+/**
+ * Search visible catalog products — sorted, filtered, faceted, and searched by Wix across the
+ * whole catalog, then cursor-paged. `nextCursor` continues the same query; start over (no cursor)
+ * whenever any selection changes. `total` (the "N products" line) is issued with the first page.
+ */
+export async function searchCatalog(o: CatalogSearchOptions = {}): Promise<{ products: ProductSummary[]; nextCursor: string | null; total: number | null }> {
+  const query = searchQuery(o);
+  const res: Raw = await products.searchProducts(query, { fields: LIST_FIELDS as any });
+  let total: number | null = null;
+  if (!o.cursor && query.filter) {
+    try {
+      const count: Raw = await products.countProducts({ filter: query.filter });
+      total = typeof count?.count === "number" ? count.count : null;
+    } catch {
+      /* the count is a nicety — the page is still valid */
     }
-    return {
-      variantId: v._id ?? v.variantId ?? "",
-      choices,
-      price: v.price?.actualPrice?.formattedAmount ?? "",
-      compareAtPrice: v.price?.compareAtPrice?.formattedAmount ?? null,
-      inStock: v.inventoryStatus?.inStock !== false,
-    };
-  });
-}
-
-function toDetail(raw: RawProduct): ProductDetail {
-  const summary = toSummary(raw);
-  const gallery = [
-    summary.imageUrl,
-    ...(raw.media?.itemsInfo?.items ?? []).map((m: RawProduct) => imgSrc(m.image ?? m, 1200, 1200)),
-  ].filter((u, i, arr) => u && arr.indexOf(u) === i);
+  }
   return {
-    ...summary,
-    descriptionHtml: raw.plainDescription ?? "",
-    gallery,
-    options: toOptions(raw),
-    modifiers: toModifiers(raw),
-    variants: toVariants(raw),
+    products: ((res.products ?? []) as Raw[]).map((p) => toSummary(p, imgSrc, mediaKey)),
+    nextCursor: res.pagingMetadata?.cursors?.next ?? null,
+    total,
   };
 }
 
-// Search Products applies sort/filter/search server-side, across the WHOLE catalog, before
-// cursor paging — the only correct place for them. Sorting or filtering an already-fetched
-// page only rearranges the slice you happen to hold.
-// docs: https://dev.wix.com/docs/api-reference/business-solutions/stores/catalog-v3/products-v3/search-products.md
-export const CATALOG_SORTS = {
-  featured: { label: "Default order" }, // the catalog's own order; no merchant-curated promise
-  priceAsc: { label: "Price: low to high" },
-  priceHigh: { label: "Price: high to low" },
-  name: { label: "Name: A\u2013Z" },
-  newest: { label: "Newest" },
-} as const;
-export type CatalogSort = keyof typeof CATALOG_SORTS;
-
-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" }],
-};
-
-function priceBound(value: number | string | undefined, name: string): number | undefined {
-  if (value == null || value === "") return undefined;
-  const parsed = Number(value);
-  if (!String(value).trim() || !Number.isFinite(parsed) || parsed < 0) {
-    throw new Error(`${name} must be a non-negative number.`);
-  }
-  return parsed;
-}
-
-export interface CatalogSearchOptions {
-  limit?: number;
-  /** Continues the ORIGINAL query — pass alone; new sort/filter values start without one. */
-  cursor?: string;
-  categoryId?: string | null;
-  sort?: CatalogSort;
-  /** Bounds compare the product's minimum actual variant price, in site currency. */
-  minPrice?: number | string;
-  maxPrice?: number | string;
-  inStockOnly?: boolean;
-  /** Name search, max 100 chars. */
-  search?: string;
+/** The filterable options of the catalog (or one category). Non-fatal: [] when the read fails. */
+export async function fetchFacets(scope: { categoryId?: string | null } = {}): Promise<Facet[]> {
+  return (await fetchFacetData(scope)).facets;
 }
 
 /**
- * Search visible catalog products — sorted, filtered, and searched by Wix across the whole
- * catalog, then cursor-paged. `nextCursor` continues the same query; start over (no cursor)
- * whenever any selection changes.
+ * Facets plus the scope's price bounds (lowest minimum, highest maximum across its products) — the
+ * filter panel's slider needs both, from one 100-product read. Non-fatal: empty on failure.
  */
-export async function searchCatalog({
-  limit = 24,
-  cursor,
-  categoryId,
-  sort = "featured",
-  minPrice,
-  maxPrice,
-  inStockOnly = false,
-  search = "",
-}: CatalogSearchOptions = {}): Promise<{ products: ProductSummary[]; nextCursor: string | null }> {
-  if (!Number.isInteger(limit) || limit < 1 || limit > 100)
-    throw new Error("limit must be between 1 and 100.");
-  let query: RawProduct = { cursorPaging: { limit, ...(cursor ? { cursor } : {}) } };
-  if (!cursor) {
-    if (!(sort in CATALOG_SORTS)) throw new Error("Unsupported catalog sort.");
-    const min = priceBound(minPrice, "minPrice");
-    const max = priceBound(maxPrice, "maxPrice");
-    if (min !== undefined && max !== undefined && min > max)
-      throw new Error("minPrice must not exceed maxPrice.");
-    if (search.trim().length > 100) throw new Error("Search must be at most 100 characters.");
-    const conditions: RawProduct[] = [{ visible: true }];
-    if (categoryId)
-      conditions.push({ "allCategoriesInfo.categories": { $matchItems: [{ id: categoryId }] } });
-    // Search rejects two operators in one field object — separate bounds, joined by $and.
-    if (min !== undefined)
-      conditions.push({ "actualPriceRange.minValue.amount": { $gte: String(min) } });
-    if (max !== undefined)
-      conditions.push({ "actualPriceRange.minValue.amount": { $lte: String(max) } });
-    if (inStockOnly) conditions.push({ "inventory.availabilityStatus": { $eq: "IN_STOCK" } });
-    query = {
-      ...query,
-      filter: { $and: conditions },
-      ...(SORT_FIELDS[sort] ? { sort: SORT_FIELDS[sort] } : {}),
-      ...(search.trim() ? { search: { expression: search.trim(), fields: ["name"] } } : {}),
-    };
+export async function fetchFacetData({ categoryId }: { categoryId?: string | null } = {}): Promise<FacetData> {
+  try {
+    const res: Raw = await products.searchProducts(
+      { filter: catalogFilter({ categoryId }), cursorPaging: { limit: 100 } },
+      { fields: ["CURRENCY"] as any },
+    );
+    return toFacetData((res.products ?? []) as Raw[]);
+  } catch {
+    return { facets: [], priceRange: null };
   }
-  const res: RawProduct = await products.searchProducts(query, { fields: LIST_FIELDS as any });
-  return {
-    products: (res.products ?? []).map((p: RawProduct) => toSummary(p)),
-    nextCursor: res.pagingMetadata?.cursors?.next ?? null,
-  };
 }
 
 /** First page of visible products in the default order — a thin wrap of searchCatalog. */
@@ -230,10 +83,7 @@ export async function fetchProducts({ limit = 24 } = {}): Promise<ProductSummary
 }
 
 /** First page of a category — same wrap; category filtering only works through search. */
-export async function fetchProductsByCategory(
-  categoryId: string,
-  { limit = 24 } = {},
-): Promise<ProductSummary[]> {
+export async function fetchProductsByCategory(categoryId: string, { limit = 24 } = {}): Promise<ProductSummary[]> {
   return (await searchCatalog({ limit, categoryId })).products;
 }
 
@@ -241,7 +91,7 @@ export async function fetchProductsByCategory(
 export async function fetchProductBySlug(slug: string): Promise<ProductDetail | null> {
   try {
     const res = await products.getProductBySlug(slug, { fields: DETAIL_FIELDS as any });
-    return res.product ? toDetail(res.product as RawProduct) : null;
+    return res.product ? toDetail(res.product as Raw, imgSrc, mediaKey) : null;
   } catch {
     return null;
   }
@@ -259,32 +109,25 @@ export async function fetchCategories(): Promise<Category[]> {
       .queryCategories({ treeReference: { appNamespace: "@wix/stores" } })
       .exists("name", true)
       .find();
-    return (res.items ?? [])
-      .map((c) => ({
-        id: (c as RawProduct)._id ?? "",
-        slug: (c as RawProduct).slug ?? "",
-        name: (c as RawProduct).name ?? "",
-      }))
-      .filter((c) => c.slug !== "all-products");
+    return (res.items ?? []).map((c) => toCategory(c as Raw)).filter((c) => c.slug !== "all-products");
   } catch {
     return [];
   }
 }
 
 /**
- * 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. Returns null while the selection is incomplete.
+ * One category by its URL slug — the data a /category/[slug] page needs (its id feeds
+ * searchCatalog / useShop, its name and description head the page). The response is WRAPPED:
+ * { category }. Null when not found or hidden, which the page turns into a real 404 — never a
+ * fallback to all products.
  */
-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
-  );
+export async function fetchCategoryBySlug(slug: string): Promise<Category | null> {
+  try {
+    const res: Raw = await categories.getCategoryBySlug(slug, { appNamespace: "@wix/stores" } as any);
+    const raw: Raw | undefined = res?.category;
+    if (!raw || raw.visible === false) return null;
+    return toCategory(raw);
+  } catch {
+    return null;
+  }
 }

package/skills/wix-headless-fast/references/storefront/app/wix/storefront/product-detail-store.ts

@@ -0,0 +1,147 @@
+// Product detail as a framework-free store — the logic behind useProductDetail, usable from React
+// (useProductDetail wraps it), from a static page's PDP and quick-add picker, from Vue/Svelte, or as
+// the specification for a port. Option selection → variant resolution → add-to-cart, plus modifier
+// inputs. This is where the "adds variants[0] regardless of the buyer's choice" class of bugs comes
+// from — always drive a purchase surface through this store, never resolve variants by hand.
+//
+// Selections start EMPTY (a buyer who never noticed a pre-picked default buys the wrong colour).
+// Pass the server-fetched ProductDetail as `initial` (SSR) or a `slug` (the store fetches on start).
+// One store per product surface: createProductDetailStore(), not a singleton.
+import { fetchProductBySlug, resolveVariant } from "./catalog";
+import { addLine } from "./cart-store";
+import type { ProductDetail, ProductOption, ProductVariant } from "./types";
+
+export interface ProductDetailStoreOptions {
+  initial?: ProductDetail | null;
+  slug?: string;
+}
+
+export interface OptionGroupView extends ProductOption {
+  choices: (ProductOption["choices"][number] & { selected: boolean })[];
+}
+
+export interface ProductDetailState {
+  /** null while loading (or when the slug doesn't resolve — check notFound). */
+  product: ProductDetail | null;
+  notFound: boolean;
+  /** Option groups with per-choice `selected`, ready to render as pills/swatches. */
+  optionGroups: OptionGroupView[];
+  /** Modifier inputs keyed by modifier key. */
+  modifierValues: Record<string, string>;
+  /** The resolved variant; null while the selection is incomplete. */
+  variant: ProductVariant | null;
+  /** The RANGE ("€24.99 – €34.99", one value when equal) until every option is picked, then the variant's price. */
+  price: string;
+  /** Struck "was" price — only once a variant is resolved (or for a single-price product), never beside a range. */
+  compareAtPrice: string | null;
+  /** The resolved variant is out of stock but pre-orderable — label the action "Pre-order". */
+  isPreorder: boolean;
+  /** False until every option is selected and the resolved variant is in stock or pre-orderable. */
+  canAdd: boolean;
+  /** Why the action is disabled — neutral guidance ("Choose Size"), not an error; null when addable. */
+  blockedReason: string | null;
+  quantity: number;
+  adding: boolean;
+  error: string | null;
+}
+
+export interface ProductDetailStore {
+  getState(): ProductDetailState;
+  subscribe(listener: () => void): () => void;
+  /** Fetch by slug when no `initial` was given. Call once when mounted. */
+  start(): void;
+  stop(): void;
+  selectOption(optionName: string, choiceName: string): void;
+  setModifier(key: string, value: string): void;
+  setQuantity(n: number): void;
+  /** Adds the resolved variant to the cart (the cart store opens the drawer). Throws on refusal. */
+  add(): Promise<void>;
+}
+
+export function createProductDetailStore({ initial, slug }: ProductDetailStoreOptions): ProductDetailStore {
+  let product: ProductDetail | null = initial ?? null;
+  let notFound = false;
+  let selections: Record<string, string> = {};
+  let modifierValues: Record<string, string> = {};
+  let quantity = 1;
+  let adding = false;
+  let error: string | null = null;
+  let started = false;
+  const listeners = new Set<() => void>();
+  let snapshot: ProductDetailState | null = null;
+  const emit = () => { snapshot = null; for (const fn of listeners) fn(); };
+
+  function getState(): ProductDetailState {
+    if (snapshot) return snapshot;
+    const variant = product ? resolveVariant(product, selections) : null;
+    const optionGroups: OptionGroupView[] = (product?.options ?? []).map((o) => ({
+      ...o,
+      choices: o.choices.map((c) => ({ ...c, selected: selections[o.name] === c.name })),
+    }));
+    const missingModifier = (product?.modifiers ?? []).find((m) => m.mandatory && (modifierValues[m.key] ?? "").length === 0);
+    const missingOptions = (product?.options ?? []).filter((o) => !selections[o.name]).map((o) => o.name);
+    const selectionComplete = missingOptions.length === 0;
+    // In stock OR pre-orderable counts as buyable; a preorder add carries preOrderRequested.
+    const isPreorder = !!variant && !variant.inStock && variant.preorderEnabled;
+    const available = !!variant && (variant.inStock || variant.preorderEnabled);
+    const canAdd = !!product && available && !missingModifier;
+    const blockedReason: string | null = !product
+      ? null
+      : !selectionComplete ? `Choose ${missingOptions.join(" and ")}`
+      : !variant ? "This combination isn't available"
+      : !available ? "Out of stock"
+      : missingModifier ? `Add ${missingModifier.name}`
+      : null;
+    // Before every option is picked, the range — never an empty price, never a lone struck minimum.
+    const isRange = !!product && product.price !== product.maxPrice && !!product.maxPrice;
+    const rangeDisplay = product ? (isRange ? `${product.price} – ${product.maxPrice}` : product.price) : "";
+    snapshot = {
+      product, notFound, optionGroups, modifierValues, variant,
+      price: variant?.price || rangeDisplay,
+      compareAtPrice: variant ? variant.compareAtPrice : isRange ? null : (product?.compareAtPrice ?? null),
+      isPreorder, canAdd, blockedReason, quantity, adding, error,
+    };
+    return snapshot;
+  }
+
+  return {
+    getState,
+    subscribe(fn) { listeners.add(fn); return () => listeners.delete(fn); },
+    start() {
+      if (started) return;
+      started = true;
+      if (initial || !slug) return;
+      fetchProductBySlug(slug)
+        .then((p) => { if (!started) return; product = p; notFound = p === null; emit(); })
+        .catch(() => { if (started) { notFound = true; emit(); } });
+    },
+    stop() { started = false; },
+    selectOption(optionName, choiceName) {
+      selections = { ...selections, [optionName]: choiceName };
+      quantity = 1; // the ceiling belongs to the newly resolved variant
+      emit();
+    },
+    setModifier(key, value) { modifierValues = { ...modifierValues, [key]: value }; emit(); },
+    setQuantity(n) { quantity = n; emit(); },
+    async add() {
+      const s = getState();
+      if (!product || !s.variant) return;
+      adding = true; error = null; emit();
+      try {
+        const choiceModifiers: Record<string, string> = {};
+        const textModifiers: Record<string, string> = {};
+        for (const m of product.modifiers) {
+          const value = modifierValues[m.key];
+          if (!value) continue;
+          if (m.type === "text") textModifiers[m.key] = value; else choiceModifiers[m.key] = value;
+        }
+        await addLine(product.id, s.variant.variantId, quantity, { modifierChoices: choiceModifiers, customTextFields: textModifiers, preorder: s.isPreorder });
+      } catch (e) {
+        error = e instanceof Error ? e.message : String(e);
+        throw e;
+      } finally {
+        adding = false; emit();
+      }
+    },
+  };
+}