@wix/agent-skills 1.18.1 → 1.18.2

package/skills/wix-vibe-headless/references/storefront/app/context/CartContext.jsx

@@ -40,6 +40,7 @@ export function CartProvider({ children }) {
       return await fn();
     } catch (e) {
       setError(e?.message || "Something went wrong. Please try again.");
+      setIsOpen(true); // Surface refusals even when adding from a card or PDP with the drawer closed.
       if (reread) await refreshCart().catch(() => {});
       return null;
     } finally {

package/skills/wix-vibe-headless/references/storefront/app/hooks/useProductDetail.js

@@ -95,10 +95,10 @@ export function useProductDetail(slug) {
     setAdding(true);
     try {
       // addToCart reports its own failures through the cart context (it opens the drawer with the
-      // reason), so nothing is swallowed by leaving this unguarded beyond resetting the button.
+      // reason). Preserve its undefined-on-success / null-on-failure result for chained actions.
       // Coerce the quantity: the shipped stepper lets the field sit empty mid-edit, and a keyboard
       // submit from that state would otherwise post "" as the quantity.
-      await addToCart(product.id, variant?.id, Math.max(1, Number(quantity) || 1), {
+      return await addToCart(product.id, variant?.id, Math.max(1, Number(quantity) || 1), {
         modifierChoices: Object.keys(modifierChoices).length ? modifierChoices : undefined,
         customTextFields: Object.keys(customTextFields).length ? customTextFields : undefined,
       });

package/skills/wix-vibe-headless/references/storefront/app/hooks/useShop.js

@@ -1,98 +1,83 @@
-// useShop — all catalog-listing logic, no markup: load the category menu, load a page of products for
-// the active category, append the next page on demand, sort client-side, and surface a failure instead
-// of leaving the page on a spinner. The Shop page only renders what this returns.
-//
-// Load-bearing:
-// • paging is CURSOR-based. Keep the cursor from the previous response and pass it back; a cursor
-//   follow-up reuses the original filter, so the category is fixed for the life of that cursor.
-//   Changing category starts a fresh query, never a cursor continuation.
-// • queryCategories returns the auto-created "all-products" system category alongside real ones, and
-//   `visible` does not flag it — filter it by slug or the menu shows a duplicate of everything.
-// • sorting is done here on the loaded page, not by the API: with cursor paging the server would
-//   re-sort per page, so a sort applied across pages already fetched is the honest option. Say so in
-//   the UI if the catalog is larger than one page.
-import { useCallback, useEffect, useMemo, useState } from "react";
-import { queryProducts, queryProductsByCategory, queryCategories } from "@/rest/wix-store-catalog";
+// Catalog queries run on Wix before pagination. A changed selection starts a fresh cursor chain.
+import { useCallback, useEffect, useRef, useState } from "react";
+import { searchProducts, queryCategories, CATALOG_SORTS } from "@/rest/wix-store-catalog";
 
+export const SORTS = CATALOG_SORTS;
 const SYSTEM_CATEGORY_SLUG = "all-products";
-export const SORTS = {
-  featured: { label: "Featured" },
-  priceAsc: { label: "Price: low to high" },
-  priceHigh: { label: "Price: high to low" },
-  name: { label: "Name: A–Z" },
-};
-
-// Prices arrive formatted for display ("$12.00"), so read the numeric value for sorting from the
-// amount when it's there and fall back to digits in the formatted string.
-function priceOf(product) {
-  const min = product?.actualPriceRange?.minValue;
-  const n = Number(min?.amount ?? String(min?.formattedAmount || "").replace(/[^\d.]/g, ""));
-  return Number.isFinite(n) ? n : 0;
-}
 
 export function useShop({ pageSize = 24 } = {}) {
   const [categories, setCategories] = useState([]);
-  const [activeCategory, setActiveCategory] = useState(null); // null = everything
-  const [products, setProducts] = useState(null);             // null = first load
-  const [cursor, setCursor] = useState(null);
-  const [loadingMore, setLoadingMore] = useState(false);
-  const [error, setError] = useState(null);
+  const [activeCategory, setActiveCategory] = useState(null);
   const [sort, setSort] = useState("featured");
+  const [filters, setFilters] = useState({});
+  const [attempt, setAttempt] = useState(0);
+  const [page, setPage] = useState({ key: null, products: null, cursor: null, error: null, loadingMore: false });
+  const generation = useRef(0);
+  const pendingMore = useRef(null);
+  const key = JSON.stringify([pageSize, activeCategory?.id ?? null, sort, filters.minPrice ?? null,
+    filters.maxPrice ?? null, !!filters.inStockOnly, filters.search ?? "", attempt]);
+  const currentKey = useRef(key);
+  currentKey.current = key;
 
   useEffect(() => {
+    let alive = true;
     queryCategories({ limit: 100 })
-      .then(({ categories: list }) =>
-        setCategories((list || []).filter((c) => c.visible !== false && c.slug !== SYSTEM_CATEGORY_SLUG)))
-      .catch(() => setCategories([]));   // a store without categories is normal, not an error
+      .then(({ categories: list }) => {
+        if (alive) setCategories((list || []).filter(c => c.visible !== false && c.slug !== SYSTEM_CATEGORY_SLUG));
+      })
+      .catch(() => { if (alive) setCategories([]); });
+    return () => { alive = false; };
   }, []);
 
-  const load = useCallback(async (categoryId) => {
-    setProducts(null);
-    setCursor(null);
-    setError(null);
-    try {
-      const res = categoryId
-        ? await queryProductsByCategory(categoryId, { limit: pageSize })
-        : await queryProducts({ limit: pageSize });
-      setProducts(res.products);
-      setCursor(res.nextCursor);
-    } catch (e) {
-      setError(e?.message || "Couldn't load products.");
-      setProducts([]);
-    }
-  }, [pageSize]);
-
-  useEffect(() => { load(activeCategory?.id ?? null); }, [activeCategory, load]);
+  useEffect(() => {
+    const id = ++generation.current;
+    let alive = true;
+    pendingMore.current = null;
+    setPage({ key, products: null, cursor: null, error: null, loadingMore: false });
+    const [limit, categoryId, selectedSort, minPrice, maxPrice, inStockOnly, search] = JSON.parse(key);
+    searchProducts({ limit, categoryId, sort: selectedSort, minPrice, maxPrice, inStockOnly, search })
+      .then(res => {
+        if (alive && generation.current === id && currentKey.current === key) {
+          setPage({ key, products: res.products, cursor: res.nextCursor, error: null, loadingMore: false });
+        }
+      })
+      .catch(e => {
+        if (alive && generation.current === id && currentKey.current === key) {
+          setPage({ key, products: [], cursor: null, error: e?.message || "Couldn't load products.", loadingMore: false });
+        }
+      });
+    return () => { alive = false; generation.current++; };
+  }, [key]);
 
-  const loadMore = async () => {
-    if (!cursor || loadingMore) return;
-    setLoadingMore(true);
+  const loadMore = useCallback(async () => {
+    if (page.key !== key || !page.cursor || pendingMore.current) return;
+    const request = { generation: generation.current, key };
+    pendingMore.current = request; // blocks repeated clicks before React rerenders
+    const isCurrent = () => generation.current === request.generation && currentKey.current === key;
+    setPage(p => ({ ...p, loadingMore: true, error: null }));
     try {
-      const res = activeCategory
-        ? await queryProductsByCategory(activeCategory.id, { limit: pageSize, cursor })
-        : await queryProducts({ limit: pageSize, cursor });
-      setProducts((prev) => [...(prev || []), ...res.products]);
-      setCursor(res.nextCursor);
+      const res = await searchProducts({ limit: pageSize, cursor: page.cursor });
+      if (isCurrent()) setPage(p => {
+        const seen = new Set((p.products || []).map(product => product.id));
+        return { ...p, products: [...(p.products || []), ...res.products.filter(product => {
+          if (seen.has(product.id)) return false;
+          seen.add(product.id); return true;
+        })], cursor: res.nextCursor };
+      });
     } catch (e) {
-      setError(e?.message || "Couldn't load more products.");
+      if (isCurrent()) setPage(p => ({ ...p, error: e?.message || "Couldn't load more products." }));
     } finally {
-      setLoadingMore(false);
+      if (pendingMore.current === request) pendingMore.current = null;
+      if (isCurrent()) setPage(p => ({ ...p, loadingMore: false }));
     }
-  };
-
-  const sorted = useMemo(() => {
-    if (!products) return null;
-    const copy = [...products];
-    if (sort === "priceAsc") copy.sort((a, b) => priceOf(a) - priceOf(b));
-    else if (sort === "priceHigh") copy.sort((a, b) => priceOf(b) - priceOf(a));
-    else if (sort === "name") copy.sort((a, b) => (a.name || "").localeCompare(b.name || ""));
-    return copy;
-  }, [products, sort]);
+  }, [key, page.key, page.cursor, pageSize]);
 
+  const retry = useCallback(() => setAttempt(n => n + 1), []);
+  const current = page.key === key;
   return {
-    categories, activeCategory, setActiveCategory,
-    products: sorted, loading: products === null, error,
-    hasMore: !!cursor, loadMore, loadingMore,
-    sort, setSort, retry: () => load(activeCategory?.id ?? null),
+    categories, activeCategory, setActiveCategory, sort, setSort, filters, setFilters,
+    products: current ? page.products : null, loading: !current || page.products === null,
+    error: current ? page.error : null, retry,
+    hasMore: current && !!page.cursor, loadMore, loadingMore: current && page.loadingMore,
   };
 }

package/skills/wix-vibe-headless/references/storefront/app/rest/wix-store-catalog.js

@@ -55,26 +55,67 @@ import { wixApiRequest } from "./wix-client.js";
  * Full model: https://dev.wix.com/docs/api-reference/business-solutions/stores/catalog-v3/categories
  */
 
+// Search Products supports server-side sort/filter before cursor paging:
+// 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" }, // legacy key; no promise of merchant-curated ranking
+  priceAsc: { label: "Price: low to high" },
+  priceHigh: { label: "Price: high to low" },
+  name: { label: "Name: A–Z" },
+  newest: { label: "Newest" },
+};
+const SORT_FIELDS = {
+  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, name) {
+  if (value == null || value === "") return undefined;
+  if (!["number", "string"].includes(typeof value) || !String(value).trim() || !Number.isFinite(Number(value)) || Number(value) < 0) {
+    throw new Error(`${name} must be a non-negative number.`);
+  }
+  return Number(value);
+}
+
 /**
- * Query visible products (one page). Pass nextCursor back as cursor to load the next page.
- * @param {{ limit?: number, cursor?: string }} [options]
+ * Search visible catalog products, sorted/filtered across the whole catalog.
+ * Price bounds and ordering use the product's minimum actual variant price in site currency.
+ * A cursor continues the original query; start without one when any selection changes.
+ * @param {{ limit?: number, cursor?: string, categoryId?: string, sort?: string,
+ *   minPrice?: number|string, maxPrice?: number|string, inStockOnly?: boolean, search?: string }} [options]
  * @returns {Promise<{ products: object[], nextCursor: string|null }>}
  */
-export async function queryProducts({ limit = 100, cursor } = {}) {
-  const res = await wixApiRequest("/stores/v3/products/query", {
+export async function searchProducts({ limit = 100, cursor, categoryId, sort = "featured", minPrice, maxPrice, inStockOnly = false, search = "" } = {}) {
+  if (!Number.isInteger(limit) || limit < 1 || limit > 100) throw new Error("limit must be between 1 and 100.");
+  let query = { cursorPaging: { limit, ...(cursor ? { cursor } : {}) } };
+  if (!cursor) {
+    if (!Object.hasOwn(CATALOG_SORTS, sort)) throw new Error("Unsupported catalog sort.");
+    const min = priceBound(minPrice, "minPrice"), max = priceBound(maxPrice, "maxPrice");
+    if (min !== undefined && max !== undefined && min > max) throw new Error("minPrice must not exceed maxPrice.");
+    if (typeof search !== "string" || search.trim().length > 100) throw new Error("Search must be at most 100 characters.");
+    const conditions = [{ visible: true }];
+    if (categoryId) conditions.push({ "allCategoriesInfo.categories": { $matchItems: [{ id: categoryId }] } });
+    // Search rejects two operators in the same field object. Join separate bounds with $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"] } } : {}),
+    };
+  }
+  const res = await wixApiRequest("/stores/v3/products/search", {
     method: "POST",
-    body: {
-      fields: ["CURRENCY", "PLAIN_DESCRIPTION", "MEDIA_ITEMS_INFO"],
-      query: {
-        ...(cursor ? {} : { filter: { visible: true } }),
-        cursorPaging: cursor ? { limit, cursor } : { limit },
-      },
-    },
+    body: { fields: ["CURRENCY", "PLAIN_DESCRIPTION", "MEDIA_ITEMS_INFO"], search: query },
   });
-  return {
-    products: res?.products ?? [],
-    nextCursor: res?.pagingMetadata?.cursors?.next ?? null,
-  };
+  return { products: res?.products ?? [], nextCursor: res?.pagingMetadata?.cursors?.next ?? null };
+}
+
+/** Visible products; accepts the same sort/filter options as searchProducts. */
+export function queryProducts(options = {}) {
+  return searchProducts(options);
 }
 
 /**
@@ -102,34 +143,9 @@ export async function getProductBySlug(slug) {
   return res?.product ?? null;
 }
 
-/**
- * Query visible products belonging to a category (one page).
- * @param {string} categoryId  Category GUID from queryCategories / getCategoryBySlug.
- * @param {{ limit?: number, cursor?: string }} [options]
- * @returns {Promise<{ products: object[], nextCursor: string|null }>}
- */
-export async function queryProductsByCategory(categoryId, { limit = 100, cursor } = {}) {
-  const res = await wixApiRequest("/stores/v3/products/search", {
-    method: "POST",
-    body: {
-      fields: ["CURRENCY", "PLAIN_DESCRIPTION", "MEDIA_ITEMS_INFO"],
-      search: {
-        ...(cursor
-          ? { cursorPaging: { limit, cursor } }
-          : {
-              cursorPaging: { limit },
-              filter: {
-                visible: true,
-                "allCategoriesInfo.categories": { $matchItems: [{ id: categoryId }] },
-              },
-            }),
-      },
-    },
-  });
-  return {
-    products: res?.products ?? [],
-    nextCursor: res?.pagingMetadata?.cursors?.next ?? null,
-  };
+/** Category products; accepts the same sort/filter options as searchProducts. */
+export function queryProductsByCategory(categoryId, options = {}) {
+  return searchProducts({ ...options, categoryId });
 }
 
 /**

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

@@ -1,8 +1,10 @@
 # Storefront — seeding
 
-Seed a Wix Stores catalog by **calling `seed-store.js`** — don't hand-write the REST calls. It's
+Seed a Wix Stores catalog by **calling `seed-store.cjs`** — don't hand-write the REST calls. It's
 a build-time module (run via `exec_tool`, not shipped in the app) that abstracts every Wix Stores
 seed operation. Load it and call **`setupStore` — the one-call path** — with plain data.
+Pass only the connector token and catalog data. The module handles site configuration internally;
+do not read the config or supply site/client IDs.
 
 **Match each product's type to what the buyer receives** (the example shows both). *Access* — a
 membership, or an online course/program the buyer enrolls in — isn't a store product at all; that's
@@ -11,12 +13,8 @@ the `pricing-plans` vertical, not here.
 ```js
 // build-time exec_tool
 const { accessToken } = await base44.asServiceRole.connectors.getConnection("wix");
-const fs = require("fs");
-// exec_tool's require can return EMPTY exports for these build-time modules — load the file itself:
-const seed = (() => { const m = { exports: {} };
-  new Function("module", "exports", "require", fs.readFileSync("/app/.agents/skills/wix-vibe-headless/references/storefront/seed/seed-store.js", "utf8"))(m, m.exports, require);
-  return m.exports; })();
-const ctx = { token: accessToken, siteId: WIX_METASITE_ID };
+const seed = require(require("path").resolve(".agents/skills/wix-vibe-headless/references/storefront/seed/seed-store.cjs"));
+const ctx = { token: accessToken };
 
 // ONE call: install (+ wait for V3) → create products → categories → attach images, ids kept
 // in memory (no hand-threading). Categories map name -> product NAMES. Pass an imageUrl per product
@@ -25,6 +23,7 @@ const ctx = { token: accessToken, siteId: WIX_METASITE_ID };
 // result — not a still-generating /__generating__/<id>.png placeholder (Wix can't fetch that).
 // generate_image runs in the background while you build, so the urls are ready by seed time.
 const result = await seed.setupStore(ctx, {
+  currency: "EUR", // Pass only if the user asked for a currency or it's obvious for the store; else omit this line.
   products: [
     // physical — a shipped item: carries `quantity` (the default type)
     { name: "The Glam Rocker", description: "Sequin-studded velvet legend…", price: 49.99, quantity: 12, imageUrl: imageUrls[0] },
@@ -38,12 +37,40 @@ const result = await seed.setupStore(ctx, {
   ],
   categories: { "Legends": ["The Glam Rocker"], "Rising Stars": [] },   // omit if the brief names none
 });
-// result: { products:[{id,slug,revision,name}], categories:[{id,name}], imagesAttached }
+// result: { products:[{id,slug,revision,name}], categories:[{id,name}], imagesAttached,
+//   currency: { requested, actual, status, warnings } }
 ```
 
+The optional `currency` sets the site's payment currency before product creation. Pass it only when
+the user explicitly asked for a currency, or when it's obvious for the store — otherwise omit it. Do
+not infer a currency from the builder's country/region or the brief's language; when in doubt, leave
+it out and the current site currency is preserved. Product prices are numbers in that currency;
+changing currency does not convert existing amounts.
+Currency update or verification failures do not stop seeding: inspect `result.currency.status`
+and `warnings`, report the unresolved setting, and use the connector skill to resolve it. An
+unknown actual currency is `null`; do not replace currency symbols to simulate a successful update.
+Currency changes may take time to appear in existing product responses, even after carts and
+checkout use the new currency. If `result.currency.status` confirms the update succeeded, continue
+without waiting for or verifying the change in product responses or the preview.
+
+
 **Seeding is additive — never delete or overwrite existing content.** Don't clean up, don't remove
 "sample" data, don't reset. Just add.
 
+## Stock
+
+```js
+{ name: "Limited Print", price: 25, quantity: 12 } // count stock: integer 0–99999
+{ name: "Made-to-order Print", price: 25, inStock: true } // available without a quantity counter
+{ name: "Unavailable Print", price: 25, inStock: false } // unavailable without a quantity counter
+```
+
+Supply `quantity` **or** `inStock`, never both. Use `inStock: true` for unlimited stock, not a
+large invented quantity. All expanded variants inherit the same setting. Omitting both defaults
+to quantity 0 for physical products and in-stock for downloads. Stock mode doesn't change the
+product type or remove the downloadable-file requirement.
+[Wix inventory tracking](https://dev.wix.com/docs/api-reference/business-solutions/stores/catalog-v3/inventory-items-v3/inventory-item-object).
+
 ## How many, and exercising the UI
 
 **Default to 3 products** unless the brief asks for a specific catalog — the seed shows the shape,
@@ -63,8 +90,12 @@ options: [
 
 - `type: "color"` → `SWATCH_CHOICES` with each choice's `colorCode`, which the PDP draws as a swatch.
   Any other `type` → text pills. Give every colour choice a `colorCode`.
+  Within a batch, reuse the same color code for the same option/choice name across products;
+  give different shades distinct names (for example, Forest Green and Light Green).
+- Choice names must be unique within each product option, for both text and color choices.
+  Reusing a choice name across different products is fine; color choices must follow the consistency rule above.
 - Variants are expanded for you: the full cross-product of the options, each carrying the product's
-  `price`, `compareAtPrice` and `quantity`. Two options with 2 and 3 choices means 6 variants — keep
+  `price`, `compareAtPrice` and stock setting (`quantity` or `inStock`). Two options with 2 and 3 choices means 6 variants — keep
   option counts small.
 - `compareAtPrice` (> `price`) is the "was" price: strikethrough on the PDP and a `−N%` badge on the
   tile, computed from the two amounts. It works with or without options.
@@ -92,6 +123,11 @@ Two things this module does **not** seed, so don't try:
   follows automatically — `choiceImage()` reads it back at `media.items[].mediaId`.
 
 ## Escape hatch — individual functions
+
+If seeding reports a partial failure, keep the reported successful product IDs and correct the
+failed inputs. Do not rerun the whole seed or wrap it in a retry loop: creation may already have
+succeeded for some products. Missing results mean unknown creation status; inspect before creating again.
+
 Reach for the functions below only when the one-call `setupStore` doesn't fit (partial re-seed, custom
 ordering, mid-flow checks). `setupStore` is built from them, in this order:
 
@@ -118,7 +154,7 @@ await seed.attachProductImages(ctx, products.map((p, i) => ({ id: p.id, url: ima
 
 ## Reference
 If a call returns a shape you didn't expect, or you need an operation this module doesn't cover,
-use the **`wix-docs`** skill to search + read the live Wix API reference — never guess. The
+use the documentation skill available in your environment to search + read the live Wix API reference — never guess. The
 authoritative source recipe is `wix-headless/references/inline-recipes/setup-online-store.md`.
 
 Read a method's page before writing its call: it carries the exact body shape, the required