@wix/agent-skills 1.26.0 → 1.28.0

package/skills/wix-headless-templates/storefront/rest/cart.ts

@@ -0,0 +1,183 @@
+// 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, a bad coupon all throw buyer copy — 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 { EMPTY_TOTALS, WIX_STORES_APP_ID, addOptions, assertAdded, assertCheckoutable, cartErrorMessage, 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 {
+  /** The resolved variant's option selections: option key → choice key (sent beside variantId, as Wix's own storefront does). */
+  optionChoices?: Record<string, string>;
+  /** Choice modifiers: modifier key → chosen choice key. */
+  modifierChoices?: Record<string, string>;
+  /** Free-text modifiers: the modifier's free-text key → the buyer's text. */
+  customTextFields?: Record<string, string>;
+  /** A chosen recurring plan (SubscriptionPlan.id); omit for a one-time purchase. */
+  subscriptionOptionId?: string;
+  /** The resolved variant is out of stock but pre-orderable → preOrderRequested. */
+  preorder?: boolean;
+}
+
+// Every cart call fails with buyer copy (cart-core maps Wix's codes; the rest keep their message).
+async function loud<T>(op: () => Promise<T>): Promise<T> {
+  try {
+    return await op();
+  } catch (e) {
+    throw new Error(cartErrorMessage(e));
+  }
+}
+
+// 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 readCart(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, EMPTY_TOTALS, imgSrc);
+  // The totals come from the estimate, never from hand-summing lines: the after-discount subtotal,
+  // named discounts, fees and taxes (calculated when asked), the total before delivery. Delivery
+  // resolves at checkout — never render it as "Free" here.
+  // POST /ecom/v2/carts/current/estimate  { calculateTax, calculateAdditionalFees }
+  let totals = EMPTY_TOTALS;
+  try {
+    totals = summaryTotals(await wixRequest<Raw>(`${CART}/estimate`, { body: { calculateTax: true, calculateAdditionalFees: true } }), raw);
+  } catch {
+    /* the estimate is a display nicety — the cart itself is still valid */
+  }
+  const cart = toCart(raw, totals, 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 readCart(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> {
+  return loud(async () => {
+    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 readCart(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> {
+  return loud(async () => {
+    const res = await wixRequest<Raw>(`${CART}/update-line-items`, { body: { lineItems: [{ lineItemId, quantity: { newQuantity: quantity } }] } });
+    return readCart(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> {
+  return loud(async () => {
+    const res = await wixRequest<Raw>(`${CART}/remove-line-items`, { body: { lineItemIds: [lineItemId] } });
+    return readCart(res?.cart ?? null);
+  });
+}
+
+/**
+ * Apply a coupon code (one per cart); buyer copy for an unknown, expired, or inapplicable code.
+ * POST /ecom/v2/carts/current/add-coupon  { coupon: { code } }
+ */
+export async function applyCoupon(code: string): Promise<Cart> {
+  return loud(async () => {
+    const res = await wixRequest<Raw>(`${CART}/add-coupon`, { body: { coupon: { code: code.trim() } } });
+    return readCart(res?.cart ?? null);
+  });
+}
+
+/** Remove the applied coupon (a no-op when none).  POST /ecom/v2/carts/current/remove-coupon  { couponId } */
+export async function removeCoupon(): Promise<Cart> {
+  return loud(async () => {
+    const current = await getCurrentCartRaw();
+    const couponId = rawId((current?.coupons ?? [])[0]);
+    if (!couponId) return readCart(current);
+    const res = await wixRequest<Raw>(`${CART}/remove-coupon`, { body: { couponId } });
+    return readCart(res?.cart ?? null);
+  });
+}
+
+/**
+ * Save the buyer's note to the merchant on the cart (it travels to checkout and the order).
+ * PATCH /ecom/v2/carts/current  { cart: { note } }
+ */
+export async function setNote(note: string): Promise<Cart> {
+  return loud(async () => {
+    const res = await wixRequest<Raw>(CART, { method: "PATCH", body: { cart: { note: note.trim() || null } } });
+    return readCart(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 (as on Wix's own storefront). `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-templates/storefront/rest/catalog.ts

@@ -0,0 +1,267 @@
+// 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,
+  STORES_TREE,
+  choiceAvailability,
+  facetCustomizationIds,
+  facetSearchBody,
+  pageInfo,
+  readFacetAggregates,
+  resolveVariant,
+  searchQuery,
+  sellingPrice,
+  toCategory,
+  toDetail,
+  toFacetData,
+  toInventory,
+  toSummary,
+  type CatalogSearchOptions,
+  type CatalogSort,
+  type FacetSelection,
+  type Raw,
+} from "./catalog-core.js";
+import { WIX_STORES_APP_ID } from "./cart-core.js";
+import type { Category, Facet, FacetData, ProductDetail, ProductSummary, VariantInventory } from "./types.js";
+
+export { CATALOG_SORTS, choiceAvailability, resolveVariant, sellingPrice, type CatalogSearchOptions, type CatalogSort, type FacetSelection };
+
+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 alongside the first page only;
+ * `hasMore` is the API's own `hasNext`.
+ * POST /stores/v3/products/search  { fields, search: { filter, sort, search, cursorPaging } }
+ * POST /stores/v3/products/count   { filter }
+ */
+export async function searchCatalog(o: CatalogSearchOptions = {}): Promise<{ products: ProductSummary[]; nextCursor: string | null; hasMore: boolean; total: number | null }> {
+  const search = searchQuery(o);
+  const [res, count] = await Promise.all([
+    wixRequest<Raw>("/stores/v3/products/search", { body: { fields: LIST_FIELDS, search } }),
+    // the count is a nicety — the page is still valid without it
+    !o.cursor ? wixRequest<Raw>("/stores/v3/products/count", { body: { filter: search.filter } }).catch(() => null) : Promise.resolve(null),
+  ]);
+  return {
+    products: ((res?.products ?? []) as Raw[]).map((p) => toSummary(p, imgSrc, mediaKey)),
+    ...pageInfo(res),
+    total: typeof count?.count === "number" ? count.count : null,
+  };
+}
+
+export async function fetchFacets(scope: { categoryId?: string | null } = {}): Promise<Facet[]> {
+  return (await fetchFacetData(scope)).facets;
+}
+
+/**
+ * Facets and price bounds of a scope: ONE aggregations-only search (cursorPaging.limit 0 — no
+ * products, whatever the catalog size), then the named customizations for names, colors, order.
+ * Non-fatal: empty on failure.
+ * POST /stores/v3/products/search        { search: { filter, cursorPaging: { limit: 0 }, aggregations } }
+ * POST /stores/v3/customizations/query   { query: { filter: { id: { $in }, customizationRenderType: { $ne: "FREE_TEXT" } }, cursorPaging: { limit: 100 } } }
+ */
+export async function fetchFacetData({ categoryId }: { categoryId?: string | null } = {}): Promise<FacetData> {
+  try {
+    const res = await wixRequest<Raw>("/stores/v3/products/search", { body: { search: facetSearchBody(categoryId) } });
+    const agg = readFacetAggregates(res);
+    return toFacetData(agg, await fetchCustomizations(facetCustomizationIds(agg)));
+  } catch {
+    return { facets: [], priceRange: null };
+  }
+}
+
+async function fetchCustomizations(ids: string[]): Promise<Raw[]> {
+  if (!ids.length) return [];
+  const batches: string[][] = [];
+  for (let i = 0; i < ids.length; i += 100) batches.push(ids.slice(i, i + 100));
+  const pages = await Promise.all(
+    batches.map((batch) =>
+      wixRequest<Raw>("/stores/v3/customizations/query", {
+        body: { query: { filter: { id: { $in: batch }, customizationRenderType: { $ne: "FREE_TEXT" } }, cursorPaging: { limit: 100 } } },
+      }),
+    ),
+  );
+  return pages.flatMap((p) => (p?.customizations ?? []) as Raw[]);
+}
+
+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(decodeSlug(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;
+  }
+}
+
+function decodeSlug(slug: string): string {
+  try {
+    return decodeURIComponent(slug);
+  } catch {
+    return slug;
+  }
+}
+
+/**
+ * The id of Wix's auto-created "All Products" system category — excluded from navigation by id.
+ * null when the read fails (the slug heuristic then stands in).  GET /stores/v3/all-products-category
+ */
+export async function fetchAllProductsCategoryId(): Promise<string | null> {
+  try {
+    const res = await wixRequest<Raw>("/stores/v3/all-products-category", { method: "GET" });
+    return res?.categoryId ?? null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * The live VISIBLE category tree for navigation — never a seeded list; every page of it; the
+ * "All Products" system category dropped by id. The API returns only visible categories unless
+ * asked otherwise; the `visible` filter also keeps the query non-empty (an empty filter is
+ * rejected on the visitor path). Non-fatal: [] on failure.
+ * POST /categories/v1/categories/query  { treeReference, fields, query: { filter: { visible: true }, cursorPaging: { limit, cursor } } }
+ */
+export async function fetchCategories(): Promise<Category[]> {
+  try {
+    const [allProductsId, items] = await Promise.all([fetchAllProductsCategoryId(), readCategoryPages()]);
+    return items
+      .filter((c) => c.visible !== false)
+      .map((c) => toCategory(c, imgSrc))
+      .filter((c) => (allProductsId ? c.id !== allProductsId : c.slug !== "all-products"));
+  } catch {
+    return [];
+  }
+}
+
+async function readCategoryPages(): Promise<Raw[]> {
+  const out: Raw[] = [];
+  let cursor: string | null = null;
+  for (let i = 0; i < 20; i++) {
+    const res: Raw = await wixRequest<Raw>("/categories/v1/categories/query", {
+      body: {
+        treeReference: STORES_TREE,
+        fields: ["DESCRIPTION"],
+        query: cursor ? { cursorPaging: { limit: 100, cursor } } : { filter: { visible: true }, cursorPaging: { limit: 100 } },
+      },
+    });
+    out.push(...((res?.categories ?? []) as Raw[]));
+    cursor = res?.pagingMetadata?.hasNext ? res?.pagingMetadata?.cursors?.next ?? null : null;
+    if (!cursor) break;
+  }
+  return out;
+}
+
+/**
+ * One category by URL slug (its id feeds searchCatalog; name, description, image, breadcrumbs head
+ * the page). The response is WRAPPED: { category }. null when missing or hidden → a real 404.
+ * GET /categories/v1/categories/slug/{slug}?treeReference.appNamespace=@wix/stores&fields=BREADCRUMBS_INFO&fields=DESCRIPTION
+ */
+export async function fetchCategoryBySlug(slug: string): Promise<Category | null> {
+  try {
+    const res = await wixRequest<Raw>(`/categories/v1/categories/slug/${encodeURIComponent(decodeSlug(slug))}`, {
+      method: "GET",
+      query: { "treeReference.appNamespace": "@wix/stores", fields: ["BREADCRUMBS_INFO", "DESCRIPTION"] },
+    });
+    const raw: Raw | undefined = res?.category;
+    return raw && raw.visible !== false ? toCategory(raw, imgSrc) : null;
+  } catch (e) {
+    if (notFound(e)) return null;
+    throw e;
+  }
+}
+
+// The default Stores location — inventory is per location. Read once per session.
+// POST /stores/v3/locations/query  { query: { filter: { defaultLocation: true } } }
+let defaultLocation: Promise<string | null> | null = null;
+export function fetchDefaultLocationId(): Promise<string | null> {
+  defaultLocation ??= wixRequest<Raw>("/stores/v3/locations/query", { body: { query: { filter: { defaultLocation: true } } } })
+    .then((r) => ((r?.storesLocations ?? []) as Raw[])[0]?.id ?? null)
+    .catch(() => null);
+  return defaultLocation;
+}
+
+/**
+ * Live inventory of a product's variants at the default location, keyed by variantId; {} on
+ * failure. Merge with mergeInventory() from ./catalog-core.
+ * POST /stores/v3/inventory-items/query  { query: { filter: { productId, locationId }, cursorPaging: { limit: 100 } } }
+ */
+export async function fetchInventory(productId: string): Promise<Record<string, VariantInventory>> {
+  try {
+    const locationId = await fetchDefaultLocationId();
+    const items: Raw[] = [];
+    let cursor: string | null = null;
+    for (let i = 0; i < 10; i++) {
+      const res: Raw = await wixRequest<Raw>("/stores/v3/inventory-items/query", {
+        body: { query: cursor ? { cursorPaging: { limit: 100, cursor } } : { filter: { productId, ...(locationId ? { locationId } : {}) }, cursorPaging: { limit: 100 } } },
+      });
+      items.push(...((res?.inventoryItems ?? []) as Raw[]));
+      cursor = res?.pagingMetadata?.hasNext ? res?.pagingMetadata?.cursors?.next ?? null : null;
+      if (!cursor) break;
+    }
+    return toInventory(items);
+  } catch {
+    return {};
+  }
+}
+
+// Back in Stock (eCom). The public paths are the ones the generated SDK resolves for
+// www.wixapis.com: its "/back-in-stock-service" prefix in front of the service paths, and
+// GetSettings as a PUT with an empty body — kept exactly, not guessed.
+const BACK_IN_STOCK = "/back-in-stock-service/v1/back-in-stock-notification-requests";
+
+// Whether the merchant collects "notify me" requests for Stores items. Read once; false on failure.
+// PUT /back-in-stock-service/v1/back-in-stock-notification-requests/settings  {}
+let backInStockEnabled: Promise<boolean> | null = null;
+export function fetchBackInStockEnabled(): Promise<boolean> {
+  backInStockEnabled ??= wixRequest<Raw>(`${BACK_IN_STOCK}/settings`, { method: "PUT", body: {} })
+    .then((r) => ((r?.settings?.collectionStates ?? []) as Raw[]).some((s) => s.appId === WIX_STORES_APP_ID && s.collectingRequests === true))
+    .catch(() => false);
+  return backInStockEnabled;
+}
+
+/**
+ * Ask Wix to email the buyer when the variant is back in stock. `price` is the variant's plain
+ * amount (a decimal string). "already-subscribed" when that email already asked for this item.
+ * POST /back-in-stock-service/v1/back-in-stock-notification-requests  { request: { catalogReference, email }, itemDetails: { name, price, image } }
+ */
+export async function requestBackInStock(
+  productId: string,
+  variantId: string | null,
+  email: string,
+  item: { name: string; price: string; imageUrl?: string },
+): Promise<"created" | "already-subscribed"> {
+  try {
+    await wixRequest<Raw>(BACK_IN_STOCK, {
+      body: {
+        request: { catalogReference: { catalogItemId: productId, appId: WIX_STORES_APP_ID, ...(variantId ? { options: { variantId } } : {}) }, email },
+        itemDetails: { name: item.name, price: item.price, ...(item.imageUrl ? { image: item.imageUrl } : {}) },
+      },
+    });
+    return "created";
+  } catch (e) {
+    if (e instanceof WixApiError && e.code === "BACK_IN_STOCK_NOTIFICATION_REQUEST_ALREADY_EXISTS") return "already-subscribed";
+    throw e;
+  }
+}

package/skills/wix-headless-templates/storefront/seed/SEED.md

@@ -0,0 +1,169 @@
+# Storefront — seeding
+
+Seed the Wix Stores catalog by **running `seed-store.mjs` with a plan file** — don't hand-write
+the REST calls. The script mints its own site token via the Wix CLI (requires a logged-in CLI
+session and a `wix.config.json` in the working directory), installs the Stores app if needed,
+waits for the V3 catalog, and creates everything in the right order.
+
+**Set each product's type by what the buyer receives** — physical (shipped, has `quantity`) or
+digital (a file they keep, `digitalFilePath`/`digitalFileUrl`, no `quantity`); the plan below shows
+both. *Access* — a membership or an online course/program the buyer enrolls in — is Pricing Plans,
+not a store product.
+
+```bash
+# from the project root (where wix.config.json lives):
+node <SKILL_ROOT>/templates/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/setup.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
+{
+  "products": [
+    { "name": "The Glam Rocker", "description": "Sequin-studded velvet legend…",
+      "price": 49.99, "quantity": 12, "imageUrl": "https://…" },
+    { "name": "The Understudy", "description": "…", "price": 245, "quantity": 8,
+      "options": [{ "name": "Color", "type": "color",
+                    "choices": [{ "name": "Ink", "colorCode": "#1B1B2F", "imageUrl": "https://…/ink.jpg" },
+                                { "name": "Bone", "colorCode": "#EDE6D6", "imageUrl": "https://…/bone.jpg" }] }] },
+    { "name": "Encore Jacket", "description": "…", "price": 68, "compareAtPrice": 129,
+      "quantity": 5, "ribbon": "Sale",
+      "options": [{ "name": "Size", "choices": ["S", "M", "L"] }],
+      "variantPrices": { "L": 74 },
+      "modifiers": [{ "name": "Gift wrap", "mandatory": false, "choices": ["None", "Kraft paper"] },
+                    { "name": "Engraving", "type": "text", "maxChars": 30 }],
+      "infoSections": [{ "title": "Care", "description": "Dry clean only." }] },
+    { "name": "Tour Poster", "description": "…", "price": 24, "quantity": 0,
+      "preorder": { "message": "Ships in 3 weeks", "limit": 50 } },
+    { "name": "Backstage Guide", "description": "…", "price": 12,
+      "digitalFilePath": "/Users/me/guide.pdf" }
+  ],
+  "categories": { "Legends": ["The Glam Rocker"], "Rising Stars": [] },
+  "categoryDetails": { "Legends": { "description": "The originals.", "imagePrompt": "…, no text, no watermarks" } },
+  "currency": "EUR"
+}
+```
+
+- `description` — plain text or simple HTML (`<p>`, `<br/>`, `<strong>`, `<em>`); converted to
+  Wix rich text so the storefront renders paragraphs and bold, not tag text.
+- `options` — ONLY things the buyer selects-and-buys (Size, Color); they become variants.
+  `type: "color"` renders as real swatches (give every color choice a `colorCode`); anything
+  else renders as text pills. Variants are expanded automatically (full cross-product, each
+  carrying the product's price/compareAtPrice/quantity) — keep option counts small.
+  A choice may carry its own photo — `imageUrl` | `imagePath` | `imagePrompt` (+ `altText`), the
+  same three forms as a product image: it joins the product's gallery and the product page shows
+  it when that choice is picked (a colour's photo). Give it when the source has one per colour.
+- `variantPrices` — `{ "<choice name>": price }` when one option's choices are priced differently
+  ("L": 74): every variant carrying that choice takes that price (the first priced choice wins);
+  the tile then shows the range. Omit it when every variant costs the same.
+- `compareAtPrice` (> `price`) — the "was" price: strikethrough on the PDP, sale badge data on
+  the tile. Kept only on variants it stays above.
+- `ribbon` — the label on the tile and PDP ("New", "Best Seller"); one per product, created by name.
+- `modifiers` — buyer input that does NOT create variants: `{ name, choices: ["None", "Kraft paper"] }`
+  renders pills, `{ name, type: "text", maxChars?, minChars? }` a free-text field. `mandatory`
+  defaults to true (the storefront blocks the add until it's filled) — set `false` for optional
+  extras. A choice may carry `addedPrice`.
+- `infoSections` — `[{ title, description }]` (same description rules as above) — the PDP renders
+  them as sections/accordions; two products with the same title share one section.
+- `preorder` — `{ message?, limit? }` on a product WITH a `quantity` (pre-order rides on counted
+  stock): once stock hits zero the storefront sells it as "Pre-order" with the message, up to
+  `limit` units. Seed the pre-order item with `quantity: 0` when the brief wants it pre-orderable
+  from day one.
+- **Give every product an image** (a store without product images looks broken: gray boxes on
+  tiles, PDP, and cart) — the default is an `imagePrompt` (AI-generated, ~1 Wix AI credit
+  per image, account-billed): brand-contextual — subject, aesthetic/mood, palette, lighting —
+  always ending "no text, no watermarks". At least one image in the set shows the real subject of the business — the actual product/space/service, not abstract decoration. For an asset the user actually supplied use `imagePath` (a file on
+  this machine — uploaded to Wix Media) or `imageUrl` (their own hosted URL; verify it with
+  `curl -sI` → 200) — never a stock-photo or guessed URL. Images resolve in parallel and never block the seed; a failed image leaves
+  that product text-only. Seed text-only only when the user explicitly asks.
+- `digitalFilePath` (a file on this machine) or `digitalFileUrl` — makes the product a digital
+  download, uploaded and created with both the file and stock (`quantity` is ignored). It's also the
+  only way in: a file-less digital product is created successfully, reads back healthy, and is then
+  rejected at add-to-cart as `ITEM_NOT_FOUND_IN_CATALOG`. **No real file in hand?** Don't invent a
+  URL and don't ship the product as digital — seed it physical with stock (drop
+  `digitalFilePath`/`digitalFileUrl`, add `inStock` or a `quantity`) and tell the user the
+  download needs a real file before it can be sold.
+- `categories` — category name → product NAMES. Omit when the brief names none.
+- `categoryDetails` — per category name: `description` (plain text, the category page's intro)
+  and one image source (`imagePrompt` / `imageUrl` / `imagePath`, same rules as product images)
+  for the category's own image (`Category.imageUrl` — home-page category tiles). Applied on
+  create only; an existing category keeps what it has.
+- `quantity` — tracked stock, a non-negative integer. For stock that isn't counted (made to
+  order, print on demand, unlimited) use `"inStock": true` **instead** of `quantity`; sending
+  both is rejected.
+- `currency` — 3-letter ISO code. Set it **only when the brief names one**: a sentence about
+  currency ("prices in euros") or a price written with its unit ("9 dollars", "$9", "€20"). Do **not** infer it from a language, a country, or an address
+  — an unrequested switch silently reprices the whole catalog. The seed applies it before
+  creating anything, because a product's price is stored in the site currency at create time.
+  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** 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). When the brief mentions gift
+wrap, engraving, a message card, pre-orders, or "coming soon" stock, seed ONE product with that
+modifier and ONE pre-order item so the surfaces exist to design against; never add them to a
+brief that didn't ask.
+
+## Supplied content
+
+The general rules are in `templates/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`. A separate price per size becomes `variantPrices` keyed by the
+choice name, with `price` the lowest. A label like "New" or "Best Seller" becomes `ribbon`; "gift
+wrap", "engraving", "add a message" become `modifiers`; a "ships in N weeks" item becomes
+`preorder`; a materials/shipping/care paragraph becomes an `infoSections` entry. If a product has
+no price, ask; never invent one. SKU codes are not seeded — say so.
+
+**Seeding is additive — the seed never deletes or overwrites anything on the site, and neither do
+you.** There is no cleanup flag and no cleanup step. The Stores install adds its own sample catalog to
+a new site (a dozen products: "Baseball Cap", "Ceramic Flower Vase", "Crew T-Shirt", ...), and the
+live shop lists them next to the owner's, so they are never silent: the result's `preexisting[]` names
+every product the plan did not name (`{ id, name, slug }`), and the closing message says so with the
+Manage products link (`dashboardProductsUrl` in the result) so the owner removes them there if they
+want to. Categories are idempotent by name — a re-run reuses "Donuts" instead of creating a second one.
+
+**Images are confirmed, not assumed.** `imagesAttached` counts the attaches the API reported as
+successful; `imageFailures: [{ name, error }]` names the products left without an image and why.
+`choiceImagesLinked` counts the choice photos linked to their choice, `choiceImageFailures:
+[{ name, choice, error }]` the ones that are in the gallery but not linked (a re-run links them)
+(one miss out of three was seen live — a revision moved between read and update). The seed already
+retries a miss once. To retry again, re-run the same plan: existing products are reused and their
+images attached; nothing is duplicated.
+
+**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
+mis-mapped, so the rest of the catalog is fine to build on. To retry, re-run the **same** plan:
+creation is idempotent by name, so products that already exist are skipped rather than
+duplicated. Never hand-patch ids to "fill the gap".
+
+Two things this module does not seed (dashboard-only — tell the merchant): **SKUs** and
+**subscription plans** (the storefront renders them when the merchant adds them).
+
+## Escape hatch — individual functions
+
+`setupStore` is built from exported steps; import them only for a partial re-seed or custom
+ordering: `installStoresApp`, `readAllProducts`, `bulkCreateProducts`,
+`createCategories(ctx, names, details?)`, `addProductsToCategories`, `attachProductImages` — plus
+`makeCtx()` for the auth context.
+
+## Reference
+
+If a call returns an unexpected shape or you need an operation this module doesn't cover, read
+the live Wix API reference — never guess. Every call in the script carries a `docs:` line
+with its reference page. Key pages:
+
+- Bulk Create Products With Inventory: https://dev.wix.com/docs/api-reference/business-solutions/stores/catalog-v3/products-v3/bulk-create-products-with-inventory.md
+- Create Category: https://dev.wix.com/docs/api-reference/business-solutions/stores/catalog-v3/categories/create-category.md
+- Bulk Add Items To Category: https://dev.wix.com/docs/api-reference/business-solutions/stores/catalog-v3/categories/bulk-add-items-to-category.md
+- Bulk Update Products (image attach): https://dev.wix.com/docs/api-reference/business-solutions/stores/catalog-v3/products-v3/bulk-update-products.md

package/skills/wix-headless-templates/storefront/seed/read-site.mjs

@@ -0,0 +1,38 @@
+// What the store holds: products (names, prices, options, media, stock), categories. Run it before
+// designing a storefront for a site that already has content:
+//   node <SKILL_ROOT>/templates/storefront/seed/read-site.mjs [--site <siteId>] [--limit <n>]
+// Every request here is the one the deployed data layer makes (rest/catalog.ts); the doc URL of
+// each method is in the output's `calls`.
+import { runReader } from "../../shared/seed/read-site.mjs";
+
+const STORES_APP_ID = "215238eb-22a5-4c36-9e7b-e7c08025e04e";
+const D = "https://dev.wix.com/docs/api-reference/business-solutions/stores/catalog-v3";
+const LIST_FIELDS = ["CURRENCY", "MEDIA_ITEMS_INFO", "MIN_PRICE_VARIANT", "DISCOUNT_INFO"];
+const VISIBLE = { $and: [{ visible: true }] };
+const TREE = { appNamespace: "@wix/stores", treeKey: null };
+
+await runReader({
+  vertical: "storefront",
+  appId: STORES_APP_ID,
+  async read(api, { limit }) {
+    const count = await api.tryCall({ path: "/stores/v3/products/count", body: { filter: VISIBLE }, docs: `${D}/products-v3/count-products` });
+    const search = await api.call({ path: "/stores/v3/products/search", body: { fields: LIST_FIELDS, search: { filter: VISIBLE, cursorPaging: { limit } } }, docs: `${D}/products-v3/search-products` });
+    const cats = await api.tryCall({ path: "/categories/v1/categories/query", body: { treeReference: TREE, query: { filter: { name: { $exists: true } }, cursorPaging: { limit: 100 } } }, docs: `${D}/categories/query-categories` });
+    const products = (search.products ?? []).map((p) => ({
+      name: p.name, slug: p.slug,
+      price: p.actualPriceRange?.minValue?.formattedAmount ?? null,
+      priceMax: p.actualPriceRange?.maxValue?.formattedAmount ?? null,
+      compareAt: p.compareAtPriceRange?.minValue?.formattedAmount ?? null,
+      options: (p.options ?? []).map((o) => `${o.name} (${o.choicesSettings?.choices?.length ?? 0})`),
+      media: p.media?.itemsInfo?.items?.length ?? 0,
+      availability: p.inventory?.availabilityStatus ?? null,
+    }));
+    return {
+      currency: search.products?.[0]?.currency ?? null,
+      productCount: typeof count?.count === "number" ? count.count : null,
+      products,
+      productsShown: products.length,
+      categories: (cats?.categories ?? []).filter((c) => c.slug !== "all-products").map((c) => ({ id: c.id, name: c.name, slug: c.slug, visible: c.visible !== false })),
+    };
+  },
+});