@wix/agent-skills 1.19.1 → 1.20.0

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

@@ -1,13 +1,15 @@
-// useProductDetail — all PDP logic, no markup: load product by slug, pre-select first in-stock
-// choice per option, resolve the buyer's selections to a Wix variant, gate add-to-cart on stock +
-// mandatory modifiers, and build the addToCart payload. The data paths here (variant resolution,
-// modifier keys, stock gating) are the bug-prone part — keep them verbatim; the PDP page only
-// renders what this returns.
+// useProductDetail — all PDP logic, no markup: load product by slug, resolve the buyer's selections
+// to a Wix variant, gate add-to-cart on availability + mandatory modifiers, and build the addToCart
+// payload. The data paths here (variant resolution, price precedence, modifier keys, stock gating)
+// are the bug-prone part — keep them verbatim; the PDP page only renders what this returns.
 import { useState, useEffect, useMemo } from "react";
-import { getProductBySlug } from "@/rest/wix-store-catalog";
+import { getProductBySlug, sellingPrice } from "@/rest/wix-store-catalog";
 import { choiceImage, variantImage } from "@/lib/storeImage";
 import { useCart } from "@/context/CartContext";
 
+// A variant is identified by the SET of its choice ids — sorted, so option order can't matter.
+const choiceKey = (choiceIds) => [...choiceIds].sort().join("_");
+
 export function useProductDetail(slug) {
   const { addToCart } = useCart();
   const [product, setProduct] = useState(null);
@@ -16,6 +18,8 @@ export function useProductDetail(slug) {
   // link, the other is worth retrying. Without the split, a network blip reads as "product deleted".
   const [error, setError] = useState(null);
   const [adding, setAdding] = useState(false);
+  // Selections start EMPTY. Pre-picking the first choice lets a buyer who never noticed the default
+  // buy the wrong colour; the PDP shows a neutral "choose a size" until every option is picked.
   const [selectedOptions, setSelectedOptions] = useState({});
   const [modifierValues, setModifierValues] = useState({});
   const [quantity, setQuantity] = useState(1);
@@ -26,17 +30,13 @@ export function useProductDetail(slug) {
     setProduct(null);
     setNotFound(false);
     setError(null);
+    setSelectedOptions({});
+    setQuantity(1);
     getProductBySlug(slug)
       .then((p) => {
         if (cancelled) return;
         if (!p) return setNotFound(true);
         setProduct(p);
-        const initial = {};
-        (p.options || []).forEach((o) => {
-          const first = o.choicesSettings?.choices?.find((c) => c.inStock !== false);
-          if (first) initial[o.id] = first.choiceId;
-        });
-        setSelectedOptions(initial);
       })
       .catch((e) => { if (!cancelled) setError(e?.message || "Couldn't load this product."); });
     return () => { cancelled = true; };
@@ -44,29 +44,70 @@ export function useProductDetail(slug) {
 
   const options = product?.options || [];
   const modifiers = product?.modifiers || [];
-  const variants = product?.variantsInfo?.variants || [];
 
+  // Visible variants keyed by their sorted choice ids. Two variants with the same choices is a
+  // catalog defect — report it instead of silently letting one overwrite the other.
+  const { variantByKey, duplicateKey } = useMemo(() => {
+    const map = new Map();
+    let dup = null;
+    for (const v of product?.variantsInfo?.variants || []) {
+      if (v.visible === false) continue;
+      const k = choiceKey((v.choices || []).map((c) => c.optionChoiceIds?.choiceId));
+      if (map.has(k) && !dup) dup = k;
+      map.set(k, v);
+    }
+    return { variantByKey: map, duplicateKey: dup };
+  }, [product]);
+
+  const selectionComplete = options.length > 0 && options.every((o) => selectedOptions[o.id]);
   const variant = useMemo(() => {
-    if (options.length === 0) return variants[0] || null;
-    if (!options.every((o) => selectedOptions[o.id])) return null;
-    return variants.find((v) => (v.choices || []).every((c) =>
-      selectedOptions[c.optionChoiceIds?.optionId] === c.optionChoiceIds?.choiceId)) || null;
-  }, [options, variants, selectedOptions]);
+    if (options.length === 0) return variantByKey.values().next().value || null;   // the single variant
+    if (!selectionComplete || duplicateKey) return null;
+    return variantByKey.get(choiceKey(options.map((o) => selectedOptions[o.id]))) || null;
+  }, [options, variantByKey, duplicateKey, selectedOptions, selectionComplete]);
 
+  // In stock OR pre-orderable counts as buyable; a preorder add carries preOrderRequested.
   const inStock = variant ? variant.inventoryStatus?.inStock !== false : true;
+  const isPreorder = !!variant && !inStock && variant.inventoryStatus?.preorderEnabled === true;
+  const available = inStock || isPreorder;
+
+  const missingModifier = modifiers.find((m) => m.mandatory && !(
+    m.modifierRenderType === "FREE_TEXT" ? modifierValues[m.freeTextSettings?.key] : modifierValues[m.key]));
+
   const canAdd = useMemo(() => {
+    if (!product) return false;
     if (options.length > 0 && !variant) return false;
-    if (variant && !inStock) return false;
-    return modifiers.filter((m) => m.mandatory).every((m) =>
-      m.modifierRenderType === "FREE_TEXT" ? !!modifierValues[m.freeTextSettings?.key] : !!modifierValues[m.key]);
-  }, [options, variant, inStock, modifiers, modifierValues]);
+    if (variant && !available) return false;
+    return !missingModifier;
+  }, [product, options, variant, available, missingModifier]);
+
+  // Why the buy button is disabled — neutral guidance to render next to the action ("Choose a
+  // size"), not an error; null when the buyer can add. Promote to error styling only after they try.
+  const blockedReason = useMemo(() => {
+    if (!product) return null;
+    if (duplicateKey) return "This product's variants can't be resolved right now.";
+    if (options.length > 0 && !selectionComplete) {
+      const missing = options.filter((o) => !selectedOptions[o.id]).map((o) => o.name);
+      return `Choose ${missing.join(" and ")}`;
+    }
+    if (options.length > 0 && !variant) return "This combination isn't available";
+    if (variant && !available) return "Out of stock";
+    if (missingModifier) return `Add ${missingModifier.name}`;
+    return null;
+  }, [product, duplicateKey, options, selectionComplete, selectedOptions, variant, available, missingModifier]);
 
-  // Everything the buyer sees follows the resolved `variant` (also returned below, so an agent can
-  // surface more from it — sku, barcode, subscriptionPricesInfo — without new plumbing). Price and
-  // its struck-through "was" price come off the variant, falling back to the product's range before
-  // every option is picked.
-  const price = variant?.price?.actualPrice?.formattedAmount || product?.actualPriceRange?.minValue?.formattedAmount || "";
-  const compareAtPrice = variant?.price?.compareAtPrice?.formattedAmount || product?.compareAtPriceRange?.minValue?.formattedAmount || "";
+  // Everything the buyer sees follows the resolved `variant` (also returned below). The price obeys
+  // the exact precedence in sellingPrice(): an automatic discount beats the regular price and strikes
+  // it; else the regular price with the merchant's compare-at as the "was". Before every option is
+  // picked, the product's min–max range (one value when equal) — never an empty price.
+  const min = product?.actualPriceRange?.minValue, max = product?.actualPriceRange?.maxValue;
+  const rangeDisplay = min?.amount && max?.amount && min.amount !== max.amount
+    ? `${min.formattedAmount} – ${max.formattedAmount}` : (min?.formattedAmount || "");
+  const resolved = variant ? sellingPrice(variant.price) : null;
+  const price = resolved?.current?.formattedAmount || rangeDisplay;
+  const compareAtPrice = resolved && resolved.original?.formattedAmount &&
+    Number(resolved.original.amount) > Number(resolved.current?.amount) ? resolved.original.formattedAmount : "";
+  const discountNames = product?.discountInfo?.discountRuleNames || [];   // automatic discounts, product level
 
   // The gallery follows the selection. Prefer the selected choice's own image (the per-swatch photo,
   // choice.media.items[].mediaId) — Wix's per-variant media is often NOT differentiated (it defaults to
@@ -82,7 +123,11 @@ export function useProductDetail(slug) {
     return variantImage(variant);
   }, [variant, options, selectedOptions]);
 
-  const selectOption = (optionId, choiceId) => setSelectedOptions((s) => ({ ...s, [optionId]: choiceId }));
+  // Changing an option resets the quantity — the ceiling belongs to the newly resolved variant.
+  const selectOption = (optionId, choiceId) => {
+    setSelectedOptions((s) => ({ ...s, [optionId]: choiceId }));
+    setQuantity(1);
+  };
   const setModifier = (key, value) => setModifierValues((s) => ({ ...s, [key]: value }));
 
   async function submit() {
@@ -101,6 +146,7 @@ export function useProductDetail(slug) {
       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,
+        preorder: isPreorder,
       });
     } finally {
       setAdding(false);
@@ -111,6 +157,7 @@ export function useProductDetail(slug) {
     product, notFound, error, retry: () => setReloadKey((k) => k + 1),
     options, modifiers,
     selectedOptions, selectOption, modifierValues, setModifier,
-    quantity, setQuantity, variant, inStock, canAdd, adding, price, compareAtPrice, submit, focusMediaUrl,
+    quantity, setQuantity, variant, inStock, isPreorder, canAdd, blockedReason, adding,
+    price, compareAtPrice, discountNames, submit, focusMediaUrl,
   };
 }

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

@@ -40,17 +40,24 @@ const STORES_APP_ID = "215238eb-22a5-4c36-9e7b-e7c08025e04e";
  * 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> }} [extras]
+ * @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 } = {}) {
+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;
@@ -92,8 +99,30 @@ export async function getCurrentCart() {
   }
 }
 
+/**
+ * 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.

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

@@ -13,8 +13,13 @@ import { wixApiRequest } from "./wix-client.js";
  *   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
- *     ("129.00"). Use these for arithmetic: a percent-off badge can't be computed from "€129.00",
+ *   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",
@@ -23,8 +28,9 @@ import { wixApiRequest } from "./wix-client.js";
  *     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,
- *   additionalRibbons {array} — further { id, name } badges,
+ *     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:
@@ -45,9 +51,11 @@ import { wixApiRequest } from "./wix-client.js";
  *     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 }, media, inventoryStatus: { inStock } }]
+ *        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" } —
@@ -55,6 +63,20 @@ import { wixApiRequest } from "./wix-client.js";
  * 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 = {
@@ -108,7 +130,9 @@ export async function searchProducts({ limit = 100, cursor, categoryId, sort = "
   }
   const res = await wixApiRequest("/stores/v3/products/search", {
     method: "POST",
-    body: { fields: ["CURRENCY", "PLAIN_DESCRIPTION", "MEDIA_ITEMS_INFO"], search: query },
+    // 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 };
 }
@@ -137,6 +161,7 @@ export async function getProductBySlug(slug) {
         "MEDIA_ITEMS_INFO",
         "PRODUCT_CHOICES_MEDIA_REFERENCES",
         "VARIANT_OPTION_CHOICE_NAMES",
+        "DISCOUNT_INFO", // variant price.priceAfterDiscount + discountInfo.discountRuleNames
       ],
     },
   });