@wix/agent-skills 1.20.0 → 1.20.1

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

@@ -0,0 +1,289 @@
+// The shop listing as a framework-free store — the logic behind useShop, usable from React
+// (useShop wraps it with useSyncExternalStore), from a static page or Vue/Svelte (subscribe and
+// render), or as the specification for a port. Same shape as cart-store.ts: state, actions,
+// subscribe/getState, emit after every change.
+//
+// Category, sort, price/stock/search filters, option facets, and cursor paging are all applied
+// by Wix across the whole catalog (searchCatalog), never to a page already in hand. A changed
+// selection starts a fresh cursor chain; a late response from a superseded query is dropped.
+//
+// SSR-friendly: seed with `initialProducts`/`initialCategories` and they render at once; `start()`
+// then revalidates the first page to open the cursor chain, replacing the seed without a
+// skeleton flash. `initialCategoryId` scopes the first query (a /category/[slug] page).
+//
+// URL state: sort, filters, facet choices (and a live category switch on /shop) are read from the
+// query string by `start()` and written back with replaceState after every change — a filtered
+// gallery is a link a shopper can share, reload, and step back to. Paging stays out of the URL.
+//
+// One store per mounted listing (a page can hold a shop and a featured rail): createShopStore(),
+// not a singleton. The cart store is a singleton because the cart is one per visitor.
+import { CATALOG_SORTS, fetchCategories, fetchFacetData, searchCatalog, type CatalogSort } from "./catalog";
+import type { Category, Facet, PriceRange, ProductSummary } from "./types";
+
+export const SORTS = CATALOG_SORTS;
+
+export interface ShopFilters {
+  minPrice?: number | string;
+  maxPrice?: number | string;
+  inStockOnly?: boolean;
+  /** Name search, max 100 chars. */
+  search?: string;
+}
+
+export interface ShopStoreOptions {
+  initialProducts?: ProductSummary[];
+  initialCategories?: Category[];
+  /** Scope the listing to one category from the first render (a /category/[slug] page). */
+  initialCategoryId?: string | null;
+  pageSize?: number;
+  /** Mirror the selection into the query string (default true; off for a rail that isn't the page's subject). */
+  syncUrl?: boolean;
+}
+
+/** Everything a listing surface renders from. Read it with getState() or through a subscription. */
+export interface ShopState {
+  /** null while the first load is in flight — render skeletons, not an empty state. */
+  products: ProductSummary[] | null;
+  /** Matching products across the whole catalog for the current selection; null until known. */
+  total: number | null;
+  categories: Category[];
+  /** null = "all products". */
+  activeCategoryId: string | null;
+  sort: CatalogSort;
+  filters: ShopFilters;
+  /** The filterable options of the current scope (Color, Size…), from the catalog itself. */
+  facets: Facet[];
+  /** Lowest and highest product price in the scope — the price slider's bounds; null until known or when equal. */
+  priceRange: PriceRange | null;
+  /** Selected facet choice ids — products carrying ANY of them match. */
+  selectedChoiceIds: string[];
+  /** True when any filter or facet is active. */
+  hasActiveFilters: boolean;
+  loading: boolean;
+  error: string | null;
+  hasMore: boolean;
+  loadingMore: boolean;
+}
+
+export interface ShopStore {
+  getState(): ShopState;
+  subscribe(listener: () => void): () => void;
+  /** Adopt the URL, fetch categories/facets, open the cursor chain. Call once when mounted (a browser). */
+  start(): void;
+  /** Stop reacting; drop late responses. */
+  stop(): void;
+  setActiveCategoryId(id: string | null): void;
+  setSort(sort: CatalogSort): void;
+  setFilters(filters: ShopFilters): void;
+  toggleChoice(choiceId: string): void;
+  /** Clears price/stock/search filters and facet selections (keeps category and sort). */
+  clearFilters(): void;
+  retry(): void;
+  loadMore(): Promise<void>;
+}
+
+const URL_KEYS = { sort: "sort", min: "min", max: "max", stock: "stock", q: "q", choice: "choice", category: "category" } as const;
+
+function readUrlState(): { sort?: CatalogSort; filters: ShopFilters; choiceIds: string[]; categoryId?: string | null } | null {
+  if (typeof window === "undefined") return null;
+  const p = new URLSearchParams(window.location.search);
+  const sort = p.get(URL_KEYS.sort);
+  const filters: ShopFilters = {};
+  if (p.get(URL_KEYS.min)) filters.minPrice = p.get(URL_KEYS.min)!;
+  if (p.get(URL_KEYS.max)) filters.maxPrice = p.get(URL_KEYS.max)!;
+  if (p.get(URL_KEYS.stock) === "1") filters.inStockOnly = true;
+  if (p.get(URL_KEYS.q)) filters.search = p.get(URL_KEYS.q)!;
+  return {
+    sort: sort && sort in CATALOG_SORTS ? (sort as CatalogSort) : undefined,
+    filters,
+    choiceIds: p.getAll(URL_KEYS.choice),
+    categoryId: p.has(URL_KEYS.category) ? p.get(URL_KEYS.category) : undefined,
+  };
+}
+
+function writeUrlState(s: { sort: CatalogSort; filters: ShopFilters; selectedChoiceIds: string[]; activeCategoryId: string | null }, initialCategoryId: string | null): void {
+  if (typeof window === "undefined") return;
+  const p = new URLSearchParams(window.location.search);
+  for (const k of Object.values(URL_KEYS)) p.delete(k);
+  if (s.sort !== "featured") p.set(URL_KEYS.sort, s.sort);
+  if (s.filters.minPrice != null && s.filters.minPrice !== "") p.set(URL_KEYS.min, String(s.filters.minPrice));
+  if (s.filters.maxPrice != null && s.filters.maxPrice !== "") p.set(URL_KEYS.max, String(s.filters.maxPrice));
+  if (s.filters.inStockOnly) p.set(URL_KEYS.stock, "1");
+  if (s.filters.search?.trim()) p.set(URL_KEYS.q, s.filters.search.trim());
+  for (const id of s.selectedChoiceIds) p.append(URL_KEYS.choice, id);
+  if (s.activeCategoryId !== initialCategoryId) p.set(URL_KEYS.category, s.activeCategoryId ?? "");
+  const qs = p.toString();
+  const next = `${window.location.pathname}${qs ? `?${qs}` : ""}${window.location.hash}`;
+  if (next !== `${window.location.pathname}${window.location.search}${window.location.hash}`) window.history.replaceState(window.history.state, "", next);
+}
+
+export function createShopStore({ initialProducts, initialCategories, initialCategoryId = null, pageSize = 24, syncUrl = true }: ShopStoreOptions = {}): ShopStore {
+  // selection
+  let activeCategoryId: string | null = initialCategoryId;
+  let sort: CatalogSort = "featured";
+  let filters: ShopFilters = {};
+  let selectedChoiceIds: string[] = [];
+  let attempt = 0;
+  // data
+  let categories: Category[] = initialCategories ?? [];
+  let facets: Facet[] = [];
+  let priceRange: PriceRange | null = null;
+  // the current page; `key` is the selection it answers to (null = the SSR seed, no query yet)
+  let pageKey: string | null = null;
+  let products: ProductSummary[] | null = initialProducts ?? null;
+  let total: number | null = null;
+  let cursor: string | null = null;
+  let error: string | null = null;
+  let loadingMore = false;
+  // control
+  let started = false;
+  let generation = 0;
+  let pendingMore: object | null = null;
+  const listeners = new Set<() => void>();
+
+  const selectionKey = () =>
+    JSON.stringify([pageSize, activeCategoryId, sort, filters.minPrice ?? null, filters.maxPrice ?? null, !!filters.inStockOnly, filters.search ?? "", [...selectedChoiceIds].sort(), attempt]);
+
+  let snapshot: ShopState | null = null;
+  const emit = () => {
+    snapshot = null;
+    for (const fn of listeners) fn();
+  };
+
+  function getState(): ShopState {
+    if (snapshot) return snapshot;
+    const key = selectionKey();
+    const current = pageKey === key;
+    const seeded = pageKey === null && products !== null; // SSR seed, first query in flight
+    const hasActiveFilters =
+      selectedChoiceIds.length > 0 ||
+      !!filters.inStockOnly ||
+      (filters.minPrice != null && filters.minPrice !== "") ||
+      (filters.maxPrice != null && filters.maxPrice !== "") ||
+      !!(filters.search && filters.search.trim());
+    snapshot = {
+      products: current || seeded ? products : null,
+      total: current ? total : null,
+      categories,
+      activeCategoryId,
+      sort,
+      filters,
+      facets,
+      priceRange,
+      selectedChoiceIds,
+      hasActiveFilters,
+      // Seeded content on screen is not "loading" — skeletons are only for a genuinely empty wait.
+      loading: (!current && !seeded) || (current && products === null),
+      error: current ? error : null,
+      hasMore: current && !!cursor,
+      loadingMore: current && loadingMore,
+    };
+    return snapshot;
+  }
+
+  // Facets follow the category scope (a Size facet in "Donuts" is meaningless).
+  let facetScope: string | null | undefined;
+  function loadFacets(): void {
+    if (facetScope === activeCategoryId) return;
+    facetScope = activeCategoryId;
+    const scope = activeCategoryId;
+    fetchFacetData({ categoryId: scope }).then((d) => {
+      if (!started || scope !== activeCategoryId) return;
+      facets = d.facets;
+      priceRange = d.priceRange;
+      emit();
+    });
+  }
+
+  // Run the query for the current selection. Keeps the seed (or the previous page) on screen while
+  // it runs; only a selection change with no seed shows skeletons.
+  function query(): void {
+    if (!started) return;
+    const key = selectionKey();
+    const id = ++generation;
+    pendingMore = null;
+    if (pageKey !== null) products = null;
+    pageKey = key; total = null; cursor = null; error = null; loadingMore = false;
+    emit();
+    const [limit, categoryId, selectedSort, minPrice, maxPrice, inStockOnly, search, choiceIds] = JSON.parse(key);
+    searchCatalog({ limit, categoryId, sort: selectedSort, minPrice, maxPrice, inStockOnly, search, choiceIds })
+      .then((res) => {
+        if (generation !== id || selectionKey() !== key) return; // superseded — drop it
+        products = res.products; total = res.total; cursor = res.nextCursor; error = null;
+        emit();
+      })
+      .catch((e) => {
+        if (generation !== id || selectionKey() !== key) return;
+        products = []; total = null; cursor = null;
+        error = e instanceof Error ? e.message : "Couldn't load products.";
+        emit();
+      });
+  }
+
+  function changed(): void {
+    if (syncUrl) writeUrlState({ sort, filters, selectedChoiceIds, activeCategoryId }, initialCategoryId);
+    loadFacets();
+    // A new filters object with the same values keeps the page (same selection, same query).
+    if (selectionKey() === pageKey) emit();
+    else query();
+  }
+
+  return {
+    getState,
+    subscribe(fn) {
+      listeners.add(fn);
+      return () => listeners.delete(fn);
+    },
+    start() {
+      if (started) return;
+      started = true;
+      // Adopt the URL's selection once (the server rendered the defaults).
+      const u = syncUrl ? readUrlState() : null;
+      if (u) {
+        if (u.sort) sort = u.sort;
+        if (Object.keys(u.filters).length) filters = u.filters;
+        if (u.choiceIds.length) selectedChoiceIds = u.choiceIds;
+        if (u.categoryId !== undefined && u.categoryId !== initialCategoryId) activeCategoryId = u.categoryId || null;
+      }
+      if (!initialCategories) {
+        fetchCategories().then((list) => { if (started) { categories = list; emit(); } }).catch(() => { if (started) { categories = []; emit(); } });
+      }
+      loadFacets();
+      query();
+    },
+    stop() {
+      started = false;
+      generation++;
+    },
+    setActiveCategoryId(id) { if (id === activeCategoryId) return; activeCategoryId = id; changed(); },
+    setSort(next) { if (next === sort) return; sort = next; changed(); },
+    setFilters(next) { filters = next; changed(); },
+    toggleChoice(choiceId) {
+      selectedChoiceIds = selectedChoiceIds.includes(choiceId) ? selectedChoiceIds.filter((x) => x !== choiceId) : [...selectedChoiceIds, choiceId];
+      changed();
+    },
+    clearFilters() { filters = {}; selectedChoiceIds = []; changed(); },
+    retry() { attempt++; changed(); },
+    async loadMore() {
+      const key = selectionKey();
+      if (pageKey !== key || !cursor || pendingMore) return;
+      const request = { generation, key };
+      pendingMore = request; // blocks repeated clicks before a re-render
+      const isCurrent = () => generation === request.generation && selectionKey() === key;
+      loadingMore = true; error = null; emit();
+      try {
+        const res = await searchCatalog({ limit: pageSize, cursor });
+        if (isCurrent()) {
+          const seen = new Set((products ?? []).map((p) => p.id));
+          products = [...(products ?? []), ...res.products.filter((p) => (seen.has(p.id) ? false : (seen.add(p.id), true)))];
+          cursor = res.nextCursor;
+        }
+      } catch (e) {
+        if (isCurrent()) error = e instanceof Error ? e.message : "Couldn't load more products.";
+      } finally {
+        if (pendingMore === request) pendingMore = null;
+        if (isCurrent()) { loadingMore = false; emit(); }
+      }
+    },
+  };
+}

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

@@ -0,0 +1,132 @@
+// Cart + checkout over REST (Wix eCom Cart V2) — the twin of app/wix/storefront/cart.ts. Same
+// exports, same Cart/CartLine DTOs; rules and mappers from cart-core (the SAME file the SDK
+// transport uses, deployed flat next to this one). The request shapes are
+// exact and rewriting them is how carts break. Failures are loud: out-of-stock lines, an empty cart
+// at checkout, a missing required selection all throw — surface the message to the buyer.
+// All calls run with the visitor token: the cart is the token's (see ../shared/client).
+// 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-management/headless/redirects/create-redirect-session.md
+import { WixApiError, wixRequest } from "./client.js";
+import { imgSrc } from "./media.js";
+import { WIX_STORES_APP_ID, addOptions, assertAdded, assertCheckoutable, rawId, summaryTotals, toCart } from "./cart-core.js";
+import type { Raw } from "./catalog-core.js";
+import type { Cart } from "./types.js";
+
+const CART = "/ecom/v2/carts/current";
+
+export interface AddToCartExtras {
+  /** Choice modifiers: modifier key → chosen choice key (options.options — MODIFIERS only, never Size/Color). */
+  modifierChoices?: Record<string, string>;
+  /** Free-text modifiers: freeTextSettings.key → the buyer's text. */
+  customTextFields?: Record<string, string>;
+  /** A chosen recurring plan; omit for a one-time purchase. */
+  subscriptionOptionId?: string;
+  /** The resolved variant is out of stock but pre-orderable → preOrderRequested. */
+  preorder?: boolean;
+}
+
+// A line's attributes.image comes back absent right after an add (verified live) — join the
+// products' main images by catalogItemId, once per product, cached for the session.
+// POST /stores/v3/products/query  { query: { filter: { id: { $in: [...] } } } }
+const lineImageCache = new Map<string, string>();
+async function fillLineImages(cart: Cart, raws: Raw[]): Promise<void> {
+  const wanted = new Map<string, number[]>();
+  raws.forEach((raw, i) => {
+    if (cart.lines[i].imageUrl) return;
+    const pid = raw.source?.catalogReference?.catalogItemId;
+    if (!pid) return;
+    const cached = lineImageCache.get(pid);
+    if (cached !== undefined) { cart.lines[i].imageUrl = cached; return; }
+    wanted.set(pid, [...(wanted.get(pid) ?? []), i]);
+  });
+  if (!wanted.size) return;
+  try {
+    const res = await wixRequest<Raw>("/stores/v3/products/query", { body: { query: { filter: { id: { $in: [...wanted.keys()] } }, cursorPaging: { limit: 100 } } } });
+    for (const p of (res?.products ?? []) as Raw[]) {
+      const url = imgSrc(p.media?.main, 300, 300);
+      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 */
+  }
+}
+
+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 after-discount subtotal and the CART-level discount come from the 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.   POST /ecom/v2/carts/current/estimate
+  let totals = { subtotal: "", discount: "" };
+  try {
+    totals = summaryTotals(await wixRequest<Raw>(`${CART}/estimate`, { body: {} }), raw);
+  } catch {
+    /* the estimate is a display nicety — the cart itself is still valid */
+  }
+  const cart = toCart(raw, totals.subtotal, totals.discount, imgSrc);
+  await fillLineImages(cart, raw.lineItems as Raw[]);
+  return cart;
+}
+
+// GET /ecom/v2/carts/current — a 404 (CURRENT_CART_NOT_FOUND / OWNED_CART_NOT_FOUND) means no cart yet.
+async function getCurrentCartRaw(): Promise<Raw | null> {
+  try {
+    return (await wixRequest<Raw>(CART, { method: "GET" }))?.cart ?? null;
+  } catch (e) {
+    if (e instanceof WixApiError && e.status === 404) return null;
+    throw e;
+  }
+}
+
+/** The visitor's current cart. An empty Cart (not an error) when none exists yet. */
+export async function fetchCart(): Promise<Cart> {
+  return readCartWithSubtotal(await getCurrentCartRaw());
+}
+
+/**
+ * Add a product. `variantId` is REQUIRED for any product with options — resolve it first
+ * (resolveVariant); a refused add still returns 200, so the returned line is checked.
+ * POST /ecom/v2/carts/current/add-line-items  { catalogItems: [{ quantity, catalogReference: { appId, catalogItemId, options } }] }
+ */
+export async function addToCart(productId: string, variantId?: string | null, quantity = 1, extras: AddToCartExtras = {}): Promise<Cart> {
+  const options = addOptions({ variantId, ...extras });
+  const res = await wixRequest<Raw>(`${CART}/add-line-items`, {
+    body: { catalogItems: [{ quantity, catalogReference: { catalogItemId: productId, appId: WIX_STORES_APP_ID, ...(Object.keys(options).length ? { options } : {}) } }] },
+  });
+  assertAdded(res?.cart, productId, variantId);
+  return readCartWithSubtotal(res?.cart ?? null);
+}
+
+/**
+ * Change a line's quantity. `lineItemId` is CartLine.lineItemId, never the product id; a flat
+ * { id, quantity } is a 400.  POST /ecom/v2/carts/current/update-line-items  { lineItems: [{ lineItemId, quantity: { newQuantity } }] }
+ */
+export async function updateQuantity(lineItemId: string, quantity: number): Promise<Cart> {
+  const res = await wixRequest<Raw>(`${CART}/update-line-items`, { body: { lineItems: [{ lineItemId, quantity: { newQuantity: quantity } }] } });
+  return readCartWithSubtotal(res?.cart ?? null);
+}
+
+/** Remove a line by CartLine.lineItemId.  POST /ecom/v2/carts/current/remove-line-items  { lineItemIds } */
+export async function removeLine(lineItemId: string): Promise<Cart> {
+  const res = await wixRequest<Raw>(`${CART}/remove-line-items`, { body: { lineItemIds: [lineItemId] } });
+  return readCartWithSubtotal(res?.cart ?? null);
+}
+
+/**
+ * Start the Wix-hosted checkout and return the URL to navigate the FULL document to. The cart's id
+ * IS the checkout id. `origin` must be the site's real https origin as registered on the OAuth
+ * app's allowed domains (browser: window.location.origin; server: the public https host, never
+ * the request's internal origin) — an unlisted or http origin 403s on return.
+ * POST /headless/v1/redirect-session  { ecomCheckout: { checkoutId }, callbacks: { postFlowUrl, thankYouPageUrl } }
+ */
+export async function checkoutUrl(origin: string = typeof window !== "undefined" ? window.location.origin : ""): Promise<string> {
+  const raw = await getCurrentCartRaw();
+  assertCheckoutable(raw);
+  const res = await wixRequest<Raw>("/headless/v1/redirect-session", {
+    body: { ecomCheckout: { checkoutId: rawId(raw) }, callbacks: origin ? { postFlowUrl: `${origin}/`, thankYouPageUrl: `${origin}/` } : {} },
+  });
+  const url = res?.redirectSession?.fullUrl;
+  if (!url) throw new Error("Checkout couldn't start: no redirect URL returned.");
+  return url;
+}

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

@@ -0,0 +1,123 @@
+// Catalog reads over REST — the twin of app/wix/storefront/catalog.ts. Same exports, same DTOs; the
+// rules and mappers come from catalog-core (the SAME file the SDK transport uses, deployed flat next
+// to this one by deploy.mjs --stack static), so this file is only the transport: one fetch with a
+// literal body per function. Every call here is safe from a
+// browser with a visitor token. Porting: keep the paths, keep the bodies, port the core once.
+// 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/categories/get-category-by-slug.md
+import { WixApiError, wixRequest } from "./client.js";
+import { imgSrc, mediaKey } from "./media.js";
+import {
+  CATALOG_SORTS,
+  DETAIL_FIELDS,
+  LIST_FIELDS,
+  catalogFilter,
+  resolveVariant,
+  searchQuery,
+  sellingPrice,
+  toCategory,
+  toDetail,
+  toFacetData,
+  toSummary,
+  type CatalogSearchOptions,
+  type CatalogSort,
+  type Raw,
+} from "./catalog-core.js";
+import type { Category, FacetData, ProductDetail, ProductSummary } from "./types.js";
+
+export { CATALOG_SORTS, resolveVariant, sellingPrice, type CatalogSearchOptions, type CatalogSort };
+
+const STORES_TREE = { appNamespace: "@wix/stores", treeKey: null };
+const notFound = (e: unknown): boolean => e instanceof WixApiError && e.status === 404;
+
+/**
+ * The gallery query: sort, filter, facets, search, and cursor paging, all applied by Wix across the
+ * whole catalog — never on a page already in hand. `total` is issued with the first page only.
+ * POST /stores/v3/products/search  { fields, search: { filter, sort, search, cursorPaging } }
+ */
+export async function searchCatalog(o: CatalogSearchOptions = {}): Promise<{ products: ProductSummary[]; nextCursor: string | null; total: number | null }> {
+  const search = searchQuery(o);
+  const res = await wixRequest<Raw>("/stores/v3/products/search", { body: { fields: LIST_FIELDS, search } });
+  let total: number | null = null;
+  if (!o.cursor) {
+    try {
+      const c = await wixRequest<Raw>("/stores/v3/products/count", { body: { filter: search.filter } });
+      total = typeof c?.count === "number" ? c.count : null;
+    } catch {
+      /* the count is a nicety — the page is still valid */
+    }
+  }
+  return {
+    products: ((res?.products ?? []) as Raw[]).map((p) => toSummary(p, imgSrc, mediaKey)),
+    nextCursor: res?.pagingMetadata?.cursors?.next ?? null,
+    total,
+  };
+}
+
+/** Facets and price bounds of a scope from one 100-product read. Non-fatal: empty on failure. */
+export async function fetchFacetData({ categoryId }: { categoryId?: string | null } = {}): Promise<FacetData> {
+  try {
+    const res = await wixRequest<Raw>("/stores/v3/products/search", {
+      body: { fields: ["CURRENCY"], search: { filter: catalogFilter({ categoryId }), cursorPaging: { limit: 100 } } },
+    });
+    return toFacetData((res?.products ?? []) as Raw[]);
+  } catch {
+    return { facets: [], priceRange: null };
+  }
+}
+
+export async function fetchProducts({ limit = 24 } = {}): Promise<ProductSummary[]> {
+  return (await searchCatalog({ limit })).products;
+}
+
+export async function fetchProductsByCategory(categoryId: string, { limit = 24 } = {}): Promise<ProductSummary[]> {
+  return (await searchCatalog({ limit, categoryId })).products;
+}
+
+/**
+ * One complete product for the PDP; null when the slug doesn't resolve — a real 404, never a
+ * fallback to another product.  GET /stores/v3/products/slug/{slug}?fields=…&fields=…
+ */
+export async function fetchProductBySlug(slug: string): Promise<ProductDetail | null> {
+  try {
+    const res = await wixRequest<Raw>(`/stores/v3/products/slug/${encodeURIComponent(slug)}`, { method: "GET", query: { fields: DETAIL_FIELDS } });
+    return res?.product ? toDetail(res.product, imgSrc, mediaKey) : null;
+  } catch (e) {
+    if (notFound(e)) return null;
+    throw e;
+  }
+}
+
+/**
+ * The live category tree for navigation — never a seeded list. The filter must be non-empty;
+ * `visible` is not filterable (dropped client-side); the auto-created "all-products" system
+ * category is skipped. Non-fatal: [] on failure.  POST /categories/v1/categories/query
+ */
+export async function fetchCategories(): Promise<Category[]> {
+  try {
+    const res = await wixRequest<Raw>("/categories/v1/categories/query", {
+      body: { treeReference: STORES_TREE, query: { filter: { name: { $exists: true } }, cursorPaging: { limit: 100 } } },
+    });
+    return ((res?.categories ?? []) as Raw[]).filter((c) => c.visible !== false && c.slug !== "all-products").map(toCategory);
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * One category by URL slug (its id feeds searchCatalog). The response is WRAPPED: { category }.
+ * null when missing or hidden → a real 404.  GET /categories/v1/categories/slug/{slug}
+ */
+export async function fetchCategoryBySlug(slug: string): Promise<Category | null> {
+  try {
+    const res = await wixRequest<Raw>(`/categories/v1/categories/slug/${encodeURIComponent(slug)}`, {
+      method: "GET",
+      query: { "treeReference.appNamespace": "@wix/stores" },
+    });
+    const raw: Raw | undefined = res?.category;
+    return raw && raw.visible !== false ? toCategory(raw) : null;
+  } catch (e) {
+    if (notFound(e)) return null;
+    throw e;
+  }
+}

package/skills/wix-headless-fast/references/storefront/seed/SEED.md

@@ -15,6 +15,10 @@ not a store product.
 node <SKILL_ROOT>/references/storefront/seed/seed-store.mjs plan.json
 ```
 
+Run this way, the result is the process itself: exit code `0` and the JSON on stdout (redirect it
+to a file if you want it later). `.seed-exit` and `seed-result.json` are written by
+`install/fast-path.mjs` when IT starts the seed — don't wait for them after a manual run.
+
 `plan.json` is plain data — write it from the brief:
 
 ```json
@@ -69,17 +73,29 @@ node <SKILL_ROOT>/references/storefront/seed/seed-store.mjs plan.json
   For a few seconds afterwards product reads can still report the old currency; that lag is
   expected and self-resolves, so don't re-verify it or retry.
 
-**Default to 3 products** unless the brief asks for a specific catalog — the seed shows the
-shape, not a full inventory; the owner adds the rest in the dashboard. **Make those 3 exercise
-the shipped UI**: give at least one product a color option and put one product on sale —
-truthfully to the business (a ceramics studio has glaze colors; a bakery doesn't).
+**Default to 3 products** when you draft the catalog yourself — the seed shows the shape, not a
+full inventory; the owner adds the rest in the dashboard. **Make those 3 exercise the shipped
+UI**: give at least one product a color option and put one product on sale — truthfully to the
+business (a ceramics studio has glaze colors; a bakery doesn't).
+
+## Supplied content
+
+The general rules are in `references/shared/SUPPLIED-CONTENT.md`. For a store, each product the user
+lists is one entry, whatever form the list arrives in. Its name, description and price become
+`name`, `description` and `price`. A "was", "regular" or "compare at" price becomes `compareAtPrice`
+when it is higher than the price. A stock count becomes `quantity`; "unlimited" or "made to order"
+becomes `"inStock": true`. A category, collection or type becomes an entry in `categories`. A set of
+choices the buyer picks from ("Small / Large", "S, M, L") becomes one `options` entry named after
+what it is (Size, Flavor), `type: "text"`; use `type: "color"` only when the source gives color codes.
+Their image becomes `imageUrl`. If a product has a separate price per size, seed it once at the
+lowest price and tell the user the per-variant prices are set in the dashboard. If a product has no
+price, ask; never invent one. Ribbons ("New", "Best Seller") and SKU codes are not seeded — say so.
 
 **Seeding is additive — never delete or overwrite existing content.** No cleanup, no removing
-"sample" data, no resets. If a cleanup genuinely seems needed, ask the user first. The one
-exception is built in: the fast path passes `--fresh-site` because it created the site seconds
-earlier, and the seed then deletes the Stores install's sample products before creating yours
-(`samplesDeleted` in the result). Never pass that flag by hand against a site that existed before.
-Categories are idempotent by name too — a re-run reuses "Donuts" instead of creating a second one.
+"sample" data, no resets — not even on a site created a minute ago. The Stores install adds its
+own sample products to a new catalog; they stay, and the owner removes them in the dashboard
+(the Manage products link is in your summary). If a cleanup genuinely seems needed, ask the user
+first. Categories are idempotent by name — a re-run reuses "Donuts" instead of creating a second one.
 
 **A bulk create can partially succeed.** The result carries `failures: [{ name, error }]` next
 to `products` — read it. A non-empty `failures` means those products are genuinely absent, not