@wix/agent-skills 1.35.1 → 1.36.1

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

@@ -1,76 +0,0 @@
-// Headless data layer for product option/variant/modifier picking.
-// Normalises raw Wix product options + modifiers into flat, render-agnostic structures so you
-// can build whatever UI you want (pills, radios, dropdowns, swatches) without touching the
-// data-edge-case logic (visible filtering, color detection, modifier key resolution).
-//
-// Usage:
-//   const { optionGroups, modifierGroups } = useVariantOptions(
-//     options, modifiers, selectedOptions, modifierValues
-//   );
-//   // then map over optionGroups/modifierGroups to render your own controls and call
-//   // selectOption(optionId, choiceId) / setModifier(key, value) from useProductDetail.
-
-import { useMemo } from "react";
-
-export function useVariantOptions(options, modifiers, selectedOptions, modifierValues) {
-  const optionGroups = useMemo(() =>
-    (options || []).map((option) => {
-      const rawChoices = option.choicesSettings?.choices || [];
-      // `visible: false` = a choice the merchant retired — filter it so buyers can't select it.
-      const choices = rawChoices
-        .filter((c) => c.visible !== false)
-        .map((c) => ({
-          choiceId:   c.choiceId,
-          name:       c.name,
-          colorCode:  c.colorCode || null,
-          // true when this choice should render as a colour swatch (circle) rather than a pill.
-          isColorSwatch: !!(
-            (option.optionRenderType === "COLOR_CHOICES" ||
-             option.optionRenderType === "SWATCH_CHOICES" ||
-             c.choiceType === "ONE_COLOR") &&
-            c.colorCode
-          ),
-          inStock:  c.inStock !== false,
-          selected: selectedOptions[option.id] === c.choiceId,
-        }));
-      return {
-        id:      option.id,
-        name:    option.name,
-        // true if ANY choice in this group is a colour swatch — lets you branch on group type.
-        isColor: choices.some((c) => c.isColorSwatch),
-        choices,
-      };
-    }),
-    [options, selectedOptions]
-  );
-
-  const modifierGroups = useMemo(() =>
-    (modifiers || []).map((m) => {
-      const isText = m.modifierRenderType === "FREE_TEXT";
-      const key = isText ? m.freeTextSettings?.key : m.key;
-      if (isText) {
-        return {
-          key,
-          name:      m.name,
-          mandatory: !!m.mandatory,
-          type:      "text",
-          value:     modifierValues[key] || "",
-        };
-      }
-      return {
-        key,
-        name:      m.name,
-        mandatory: !!m.mandatory,
-        type:      "choices",
-        choices:   (m.choicesSettings?.choices || []).map((c) => ({
-          key:      c.key,
-          name:     c.name,
-          selected: modifierValues[key] === c.key,
-        })),
-      };
-    }),
-    [modifiers, modifierValues]
-  );
-
-  return { optionGroups, modifierGroups };
-}

package/skills/wix-vibe-headless/references/storefront/app/lib/storeImage.js

@@ -1,64 +0,0 @@
-// storeImage — turn a Wix Stores image value into a URL the browser can load.
-// Wix returns these protocol-relative (`//static.wixstatic.com/...`), which resolves against the
-// current page. That works on https pages and breaks on anything else, so normalise it once here
-// instead of at each call site — product media, PDP gallery items, and cart line items all carry the
-// same shape. Returns null for a missing value so callers can render a placeholder.
-export function storeImage(value) {
-  const url = typeof value === "string" ? value : value?.image?.url || value?.url;
-  if (!url) return null;
-  if (url.startsWith("//")) return `https:${url}`;
-  return url;
-}
-
-// A Wix media id (e.g. "abc123~mv2.jpg") is NOT a URL — build the static CDN url for it.
-export function wixMediaUrl(mediaId) {
-  if (!mediaId || typeof mediaId !== "string") return null;
-  if (mediaId.startsWith("http") || mediaId.startsWith("//")) return storeImage(mediaId);
-  return `https://static.wixstatic.com/media/${mediaId}`;
-}
-
-// The media id inside a Wix image url (…/media/<id>/v1/… or a bare …/media/<id>). Compare two urls of
-// the SAME image that differ only in sizing/format params by their id, not full-string equality.
-export function wixMediaId(url) {
-  const m = typeof url === "string" && url.match(/\/media\/([^/?]+)/);
-  return m ? m[1] : url;
-}
-
-// The image assigned to a product OPTION CHOICE (e.g. a colour swatch). The storefront fetches with the
-// PRODUCT_CHOICES_MEDIA_REFERENCES field, so Wix returns the choice image at choice.media.items[].mediaId
-// and returns choice.linkedMedia EMPTY. Read media.items — do NOT switch this to choice.linkedMedia even
-// if a direct admin/API probe shows linkedMedia populated: a probe made WITHOUT that field mask returns
-// linkedMedia, but the storefront requests the mask, which blanks linkedMedia and returns media.items.
-export function choiceImage(choice) {
-  const mediaId = choice?.media?.items?.[0]?.mediaId;
-  return mediaId ? wixMediaUrl(mediaId) : null;
-}
-
-// The image for a resolved VARIANT (a full choice combination). Wix computes variant.media from the
-// picked choices' media, so this is the exact image for the current selection — prefer it over a
-// single choice's image once all options are chosen.
-// ⚠️ Read `media.image.url` (the URL the API already returns), or build from `media.id` — the
-// `~mv2` file id. NOT `media.uploadId`: that's a dashed GUID (the id the file was uploaded with),
-// and https://static.wixstatic.com/media/<uploadId> is a 403. Variants without media (a fresh
-// template's demo products) return null, and the caller falls back to the choice's own image.
-export function variantImage(variant) {
-  const m = variant?.media;
-  if (!m) return null;
-  return storeImage(m.image?.url) || wixMediaUrl(m.id) || storeImage(m.thumbnail?.url);
-}
-
-// The main catalog image for a product (grid tiles, cart fallbacks).
-export function productImage(product) {
-  return storeImage(product?.media?.main?.image?.url);
-}
-
-// Every gallery image for a product, main first, de-duplicated — `media.itemsInfo.items` repeats the
-// main image, and video items carry no `image.url`. Returns [{ url, altText }].
-export function productGallery(product) {
-  const items = product?.media?.itemsInfo?.items || [];
-  const urls = [productImage(product), ...items.map((i) => storeImage(i))];
-  const seen = new Set();
-  return urls
-    .map((url, i) => ({ url, altText: items[i - 1]?.altText || product?.name || "" }))
-    .filter(({ url }) => url && !seen.has(url) && seen.add(url));
-}

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

@@ -1,176 +0,0 @@
-import { wixApiRequest } from "./wix-client.js";
-
-// Data model reference: see INSTRUCTIONS.md
-// Product shape (for addToCart): see wix-store-catalog.js
-
-// Stores app id — required inside catalogReference for store products.
-const STORES_APP_ID = "215238eb-22a5-4c36-9e7b-e7c08025e04e";
-
-/**
- * Wix eCom Cart V2 — key fields for building a cart UI.
- * Full model: https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/purchase-flow/cart-v2/get-current-cart.md
- *
- *   id {string} — the cart id IS the checkout id (currency lives under businessInfo.currencyCode / customerInfo.currencyCode, not at the cart root),
- *   lineItems[].id {string} — lineItemId for update/remove (NOT catalogItemId),
- *   lineItems[].quantityInfo.confirmedQuantity {number},
- *   lineItems[].source.catalogReference.catalogItemId {string} — NOT top-level in V2,
- *   lineItems[].name.original {string},
- *   lineItems[].pricing.unitPrice {ConvertedMoney} — per-unit price after discounts,
- *   lineItems[].pricing.totalPrice {ConvertedMoney} — line total after discounts,
- *     ConvertedMoney is { amount, convertedAmount } with NO formatted string — `amount` is in the
- *     site currency, `convertedAmount` in the display currency; format the number client-side.
- *   lineItems[].attributes.descriptionLines {array} — human-readable option/modifier labels:
- *     [{ name: { original }, plainText: { original } OR colorInfo: { original, code } }],
- *   lineItems[].attributes.image {object} — { id, url, height, width, altText } (use .url),
- *   lineItems[].status {string} — "IN_STOCK"|"PARTIALLY_IN_STOCK"|"OUT_OF_STOCK"|"REMOVED_FROM_CATALOG"
- */
-
-/**
- * Add a product to the visitor's current cart.
- *
- * For products with options (variants), pass the chosen variantId — resolve it from
- * product.variantsInfo.variants (from getProductBySlug) by matching the buyer's selected
- * option choices to variant.choices[].optionChoiceIds.
- *
- * For products with modifiers:
- *   - TEXT_CHOICES: pass modifierChoices: { [modifier.key]: choiceKey }
- *   - FREE_TEXT: pass customTextFields: { [modifier.freeTextSettings.key]: userInput }
- *   Mandatory modifiers (modifier.mandatory === true) MUST be included.
- *
- * Throws on out-of-stock so the buyer can't reach checkout with an unbuyable line.
- * Full catalogReference reference: https://dev.wix.com/docs/api-reference/business-solutions/stores/catalog-v3/e-commerce-integration.md
- *
- * A pre-order variant (inventoryStatus.preorderEnabled, out of stock) is added with `preorder: true`;
- * a recurring subscription plan with its `subscriptionOptionId` (omit it for a one-time purchase).
- * The two may coexist.
- *
- * @param {string} catalogItemId    Product GUID (product.id).
- * @param {string} [variantId]      variantsInfo.variants[].id — required for products with variants.
- * @param {number} [quantity]
- * @param {{ modifierChoices?: Record<string,string>, customTextFields?: Record<string,string>,
- *           subscriptionOptionId?: string, preorder?: boolean }} [extras]
- * @returns {Promise<object>} Updated cart.
- */
-export async function addToCart(catalogItemId, variantId, quantity = 1, { modifierChoices, customTextFields, subscriptionOptionId, preorder } = {}) {
-  const catalogReferenceOptions = {};
-  if (variantId) catalogReferenceOptions.variantId = variantId;
-  if (modifierChoices && Object.keys(modifierChoices).length) catalogReferenceOptions.options = modifierChoices;
-  if (customTextFields && Object.keys(customTextFields).length) catalogReferenceOptions.customTextFields = customTextFields;
-  if (subscriptionOptionId) catalogReferenceOptions.subscriptionOptionId = subscriptionOptionId;
-  if (preorder) catalogReferenceOptions.preOrderRequested = true;
-
-  const catalogReference = { appId: STORES_APP_ID, catalogItemId };
-  if (Object.keys(catalogReferenceOptions).length) catalogReference.options = catalogReferenceOptions;
-  const res = await wixApiRequest("/ecom/v2/carts/current/add-line-items", {
-    method: "POST",
-    body: { catalogItems: [{ catalogReference, quantity }] },
-  });
-  // V2 nests the reference under `source` — a top-level lineItem.catalogReference no longer exists.
-  const line = (res?.cart?.lineItems ?? []).find(
-    (l) => l.source?.catalogReference?.catalogItemId === catalogItemId && (!variantId || l.source?.catalogReference?.options?.variantId === variantId),
-  );
-  // Cart V2 rejects an unbuyable line with an explicit error rather than silently dropping it, but
-  // guard both signals defensively:
-  // 1. status set to something other than IN_STOCK
-  // 2. no matching line at all (confirmed quantity 0 / line absent)
-  if (line?.status && line.status !== "IN_STOCK") {
-    throw new Error(`Item not available for sale (status: ${line.status}). Is it in stock?`);
-  }
-  if (!line || line.quantityInfo?.confirmedQuantity === 0) {
-    // A missing line usually means a required selection wasn't sent — a mandatory modifier
-    // (pass modifierChoices/customTextFields) or the variantId for a product with options —
-    // not necessarily out of stock. Verify every required choice is included in this call.
-    throw new Error(
-      "Item could not be added to the cart. Check that every required selection was sent: " +
-        "the variantId for a product with options, and all mandatory modifiers " +
-        "(modifierChoices for TEXT_CHOICES, customTextFields for FREE_TEXT). It may also be out of stock.",
-    );
-  }
-  return res?.cart;
-}
-
-/** Read the visitor's current cart. Returns null if no cart exists yet. */
-export async function getCurrentCart() {
-  try {
-    const res = await wixApiRequest("/ecom/v2/carts/current", { method: "GET" });
-    return res?.cart ?? null;
-  } catch {
-    return null;
-  }
-}
-
-/**
- * Estimate the current cart's totals — the ONLY source of the after-discount subtotal and the
- * cart-level discount. Line prices already carry item-level discounts; delivery and tax resolve at
- * checkout unless asked for, so never invent them. Returns null when there is no cart or the
- * estimate fails (a display nicety — the cart itself stays valid).
- * https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/purchase-flow/cart-v2/estimate-current-cart.md
- * @returns {Promise<{ priceSummary: { subtotal: object, discount: object, total: object } }|null>}
- *   priceSummary amounts are ConvertedMoney { amount, convertedAmount } — format like line prices.
- */
-export async function estimateCurrentCart() {
-  try {
-    const res = await wixApiRequest("/ecom/v2/carts/current/estimate", { method: "POST", body: {} });
-    return res?.summary ?? null;
-  } catch {
-    return null;
-  }
-}
-
-/**
- * Start the hosted checkout for the current cart and return its URL.
- * This is the shopper's CURRENT cart. A "Buy now" that skips the cart needs a standalone cart
- * (POST /ecom/v2/carts) handed to the redirect session — it must never append to or replace the
- * current cart. Not shipped here; verify the redirect session accepts a standalone cart id under
- * the visitor token before adding it.
- * In Cart V2 the cart id IS the checkout id — there is no separate checkout-creation call; the
- * redirect session is created straight from the current cart's id.
- * Throws on empty cart, unavailable lines, or a missing redirect URL.
- * Usage: window.location.href = await checkout()
- * @returns {Promise<string>}
- */
-export async function checkout() {
-  const cart = await getCurrentCart();
-  const lines = cart?.lineItems ?? [];
-  if (!lines.length) throw new Error("Cannot check out: the cart is empty.");
-  const unavailable = lines.filter((l) => l.status && l.status !== "IN_STOCK");
-  if (unavailable.length) {
-    const names = unavailable.map((l) => l.name?.original ?? l.source?.catalogReference?.catalogItemId).join(", ");
-    throw new Error(`Cannot check out: ${unavailable.length} item(s) not available — ${names}.`);
-  }
-  if (!cart.id) throw new Error("Failed to check out: the current cart has no id.");
-
-  const redirect = await wixApiRequest("/headless/v1/redirect-session", {
-    method: "POST",
-    body: { ecomCheckout: { checkoutId: cart.id }, callbacks: { postFlowUrl: window.location.href } },
-  });
-  const url = redirect?.redirectSession?.fullUrl;
-  if (!url) throw new Error("Failed to create the checkout redirect session.");
-  return url;
-}
-
-/**
- * Update the quantity of a cart line. lineItemId is cart.lineItems[].id, not catalogItemId.
- * Cart V2 rejects an over-stock quantity with an explicit error rather than clamping it.
- * @returns {Promise<object>} Updated cart.
- */
-export async function updateCartItemQuantity(lineItemId, quantity) {
-  const res = await wixApiRequest("/ecom/v2/carts/current/update-line-items", {
-    method: "POST",
-    body: { lineItems: [{ lineItemId, quantity: { newQuantity: quantity } }] },
-  });
-  return res?.cart;
-}
-
-/**
- * Remove a line from the current cart by its cart.lineItems[].id.
- * @param {string} lineItemId
- * @returns {Promise<object>} Updated cart.
- */
-export async function removeFromCart(lineItemId) {
-  const res = await wixApiRequest("/ecom/v2/carts/current/remove-line-items", {
-    method: "POST",
-    body: { lineItemIds: [lineItemId] },
-  });
-  return res?.cart;
-}

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

@@ -1,218 +0,0 @@
-import { wixApiRequest } from "./wix-client.js";
-
-// Data model reference: see INSTRUCTIONS.md
-
-/**
- * Wix Stores V3 Product — key fields for the storefront catalog.
- * Full model: https://dev.wix.com/docs/api-reference/business-solutions/stores/catalog-v3/products-v3/query-products.md
- *
- *   id {string}, name {string}, slug {string}, visible {boolean}, productType "PHYSICAL"|"DIGITAL",
- *   mainCategoryId {string},
- *   media.main.image {object} — { id, url, height, width, altText },
- *   media.itemsInfo.items {array} — gallery: [{ id, altText, image: { id, url, height, width, altText }, mediaType }],
- *   actualPriceRange.minValue.formattedAmount {string} — lowest price with currency symbol,
- *   actualPriceRange.maxValue.formattedAmount {string} — highest price with currency symbol,
- *   compareAtPriceRange.minValue.formattedAmount {string} — strikethrough price (present when on sale),
- *   actualPriceRange/compareAtPriceRange .minValue.amount {string} — the same figures unformatted.
- *     Never compute a percent-off or "you save" claim from them: a range's minimum says nothing about
- *     the variant the buyer picks. The price the buyer pays comes from sellingPrice() below.
- *   variantSummary.minPriceVariant {object} — the lowest-priced visible variant (MIN_PRICE_VARIANT):
- *     { id, price: { actualPrice, compareAtPrice?, priceAfterDiscount? } } — a card's price, and the
- *     variantId for a direct add on a product with no options,
- *   discountInfo.discountRuleNames {string[]} — automatic-discount names (DISCOUNT_INFO), product level,
- *   inventory.availabilityStatus {string} — "IN_STOCK"|"OUT_OF_STOCK"|"PARTIALLY_OUT_OF_STOCK",
- *   inventory.preorderStatus {string} — "ENABLED"|"DISABLED". ENABLED + OUT_OF_STOCK is a pre-order,
- *     which is buyable — label it "Pre-order" rather than "Sold out",
- *     NB: inventory carries no stock COUNT. "Limited stock" (from PARTIALLY_OUT_OF_STOCK) is the most
- *     precise scarcity signal a tile can show; "Only 2 left" needs per-variant inventory, i.e. a
- *     getProductBySlug call per product,
- *   ribbon {object} — { id, name } merchant-set badge: "New", "Sale", "Best Seller". This is the
- *     catalogue's own label, so prefer it over anything derived — a "new" badge computed from
- *     createdDate flags every product at once right after seeding. A ribbon is a LABEL: a "Sale"
- *     ribbon is not proof of a lower price, and a compareAtPrice does not earn a ribbon,
- *   additionalRibbons {array} — up to four further { id, name } badges. Render ALL of them,
- *   createdDate / updatedDate {string} — ISO timestamps,
- *   variantSummary.variantCount {number} — how many variants exist, without fetching them,
- *   options {array} — product options e.g. Size, Color:
- *     [{ id, name, optionRenderType "TEXT_CHOICES"|"COLOR_CHOICES"|"SWATCH_CHOICES",
- *        choicesSettings.choices [{ choiceId, key, name, inStock, visible, choiceType, colorCode,
- *                                   media }] }],
- *     A COLOR/SWATCH option's choices carry choiceType "ONE_COLOR" and colorCode "#395E55" — render
- *     those as real colour swatches, not text pills. A choice's photo is at media.items[].mediaId (a
- *     bare Wix media id — build https://static.wixstatic.com/media/<id>); use choiceImage() from
- *     lib/storeImage to resolve it. Needs the PRODUCT_CHOICES_MEDIA_REFERENCES field (requested by
- *     getProductBySlug below). visible false is a retired choice the merchant no longer sells: filter
- *     it out. (TEXT_CHOICES choices are choiceType "CHOICE_TEXT" with no colorCode.)
- *   modifiers {array} — non-variant customizations (engraving, gift wrap):
- *     [{ id, name, mandatory, modifierRenderType "TEXT_CHOICES"|"FREE_TEXT",
- *        key, choicesSettings.choices, freeTextSettings.key }],
- *   plainDescription {string} — product description as an HTML string (contains <p>, <br>,
- *     <strong>…) despite the "plain" name — NOT plain text. Render with innerHTML /
- *     dangerouslySetInnerHTML; strip tags only for plain-text contexts (meta description, teaser),
- *   variantsInfo.variants {array} — returned only by getProductBySlug:
- *     [{ id, visible, choices [{ optionChoiceIds: { optionId, choiceId } }],
- *        price: { actualPrice, compareAtPrice?, priceAfterDiscount? }, media,
- *        inventoryStatus: { inStock, preorderEnabled } }]
- *     To resolve a buyer's option selections to a variantId: find the variant whose choices
- *     match all selected { optionId, choiceId } pairs, then pass variant.id to addToCart.
- *     A variant is buyable when inStock OR preorderEnabled (a preorder add carries preOrderRequested).
- *
- * Category: { id, name, slug, visible, description, image, itemCounter, parentCategory.id }
- *   NB: queryCategories includes the auto-created system category { slug: "all-products" } —
- *   filter it out of a category menu (see INSTRUCTIONS.md). `visible` does not flag it.
- * Full model: https://dev.wix.com/docs/api-reference/business-solutions/stores/catalog-v3/categories
- */
-
-/**
- * The price the buyer pays, and the price to strike — exact precedence, shared by cards and the PDP.
- * An automatic discount (priceAfterDiscount, present only when DISCOUNT_INFO is requested) wins and
- * strikes the regular actualPrice; otherwise actualPrice with the merchant's compareAtPrice as the
- * "was". `!== undefined` on purpose: a discounted price of 0 is a real price.
- * @param {{ actualPrice?: object, compareAtPrice?: object, priceAfterDiscount?: object }} [price]
- *   variant.price, or variantSummary.minPriceVariant.price. Each is { amount, formattedAmount }.
- * @returns {{ current: object|undefined, original: object|undefined }} render .formattedAmount
- */
-export function sellingPrice(price) {
-  if (price?.priceAfterDiscount !== undefined) return { current: price.priceAfterDiscount, original: price.actualPrice };
-  return { current: price?.actualPrice, original: price?.compareAtPrice };
-}
-
-// 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);
-}
-
-/**
- * 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 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",
-    // MIN_PRICE_VARIANT + DISCOUNT_INFO → variantSummary.minPriceVariant with its discounted price:
-    // the card's price and the direct-add variantId, without a per-product fetch.
-    body: { fields: ["CURRENCY", "PLAIN_DESCRIPTION", "MEDIA_ITEMS_INFO", "MIN_PRICE_VARIANT", "DISCOUNT_INFO"], search: query },
-  });
-  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);
-}
-
-/**
- * Fetch a product by its URL slug. Returns null if not found.
- * Returns the full product including variantsInfo.variants (with per-variant media and choices).
- * @param {string} slug
- * @returns {Promise<object|null>}
- */
-export async function getProductBySlug(slug) {
-  const res = await wixApiRequest(`/stores/v3/products/slug/${encodeURIComponent(slug)}`, {
-    method: "GET",
-    // PRODUCT_CHOICES_MEDIA_REFERENCES → choice.media.items[].mediaId (the per-colour photos, needed
-    // for the swatch→gallery swap); VARIANT_OPTION_CHOICE_NAMES → variant choice names. Without these
-    // the choice media / variant data come back null.
-    query: {
-      fields: [
-        "CURRENCY",
-        "PLAIN_DESCRIPTION",
-        "MEDIA_ITEMS_INFO",
-        "PRODUCT_CHOICES_MEDIA_REFERENCES",
-        "VARIANT_OPTION_CHOICE_NAMES",
-        "DISCOUNT_INFO", // variant price.priceAfterDiscount + discountInfo.discountRuleNames
-      ],
-    },
-  });
-  return res?.product ?? null;
-}
-
-/** Category products; accepts the same sort/filter options as searchProducts. */
-export function queryProductsByCategory(categoryId, options = {}) {
-  return searchProducts({ ...options, categoryId });
-}
-
-/**
- * Total number of visible products. Used for empty-state logic (0 → prompt user to add products).
- * @returns {Promise<number>}
- */
-export async function countProducts() {
-  const res = await wixApiRequest("/stores/v3/products/count", {
-    method: "POST",
-    body: { filter: { visible: true } },
-  });
-  return res?.count ?? 0;
-}
-
-/**
- * Query Wix Stores categories (one page).
- * @param {{ limit?: number, cursor?: string }} [options]
- * @returns {Promise<{ categories: object[], nextCursor: string|null }>}
- */
-export async function queryCategories({ limit = 100, cursor } = {}) {
-  const res = await wixApiRequest("/categories/v1/categories/query", {
-    method: "POST",
-    body: {
-      treeReference: { appNamespace: "@wix/stores", treeKey: null },
-      query: { cursorPaging: cursor ? { limit, cursor } : { limit } },
-    },
-  });
-  return {
-    categories: res?.categories ?? [],
-    nextCursor: res?.pagingMetadata?.cursors?.next ?? null,
-  };
-}
-
-/**
- * Get a single category by its URL slug. Returns null if not found.
- * @param {string} slug
- * @returns {Promise<object|null>}
- */
-export async function getCategoryBySlug(slug) {
-  const res = await wixApiRequest(`/categories/v1/categories/slug/${encodeURIComponent(slug)}`, {
-    method: "GET",
-    query: { "treeReference.appNamespace": "@wix/stores" },
-  });
-  return res?.category ?? null;
-}