@wix/agent-skills 1.17.0 → 1.18.1

package/skills/wix-headless-fast/references/storefront/app/hooks/storefront/useProductDetail.ts

@@ -0,0 +1,140 @@
+// Product detail state: option selection → variant resolution → add-to-cart, plus modifier
+// inputs. This is the logic the turtle-run class of bugs comes from (adding variants[0]
+// regardless of the buyer's choice) — always drive a PDP through this hook.
+//
+// SSR-friendly: pass the server-fetched ProductDetail as `initial` (Astro/Next); in a SPA
+// pass the slug and it fetches on mount.
+import { useEffect, useMemo, useState } from "react";
+import { fetchProductBySlug, resolveVariant } from "../../wix/storefront/catalog";
+import type { ProductDetail, ProductOption, ProductVariant } from "../../wix/storefront/types";
+import { useCart } from "./useCart";
+
+export interface UseProductDetailOptions {
+  initial?: ProductDetail | null;
+  slug?: string;
+}
+
+export interface OptionGroupView extends ProductOption {
+  choices: (ProductOption["choices"][number] & { selected: boolean })[];
+}
+
+export interface UseProductDetail {
+  /** null while loading (or when the slug doesn't resolve — check notFound). */
+  product: ProductDetail | null;
+  notFound: boolean;
+  /** Option groups with per-choice `selected`, ready to render as pills/swatches. */
+  optionGroups: OptionGroupView[];
+  selectOption: (optionName: string, choiceName: string) => void;
+  /** Modifier inputs keyed by modifier key. */
+  modifierValues: Record<string, string>;
+  setModifier: (key: string, value: string) => void;
+  /** The resolved variant; null while the selection is incomplete. */
+  variant: ProductVariant | null;
+  /** Price to display right now (variant price once resolved, else the product range). */
+  price: string;
+  compareAtPrice: string | null;
+  /** False until every option is selected (and the resolved variant is in stock). */
+  canAdd: boolean;
+  quantity: number;
+  setQuantity: (n: number) => void;
+  /** Adds the resolved variant to the cart (opens the drawer). Throws on refusal. */
+  add: () => Promise<void>;
+  adding: boolean;
+  error: string | null;
+}
+
+export function useProductDetail({ initial, slug }: UseProductDetailOptions): UseProductDetail {
+  const [product, setProduct] = useState<ProductDetail | null>(initial ?? null);
+  const [notFound, setNotFound] = useState(false);
+  const [selections, setSelections] = useState<Record<string, string>>({});
+  const [modifierValues, setModifierValues] = useState<Record<string, string>>({});
+  const [quantity, setQuantity] = useState(1);
+  const [adding, setAdding] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+  const { addToCart } = useCart();
+
+  useEffect(() => {
+    if (initial || !slug) return;
+    let alive = true;
+    fetchProductBySlug(slug)
+      .then((p) => {
+        if (!alive) return;
+        setProduct(p);
+        setNotFound(p === null);
+      })
+      .catch(() => alive && setNotFound(true));
+    return () => {
+      alive = false;
+    };
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [slug]);
+
+  const variant = useMemo(
+    () => (product ? resolveVariant(product, selections) : null),
+    [product, selections],
+  );
+
+  const optionGroups: OptionGroupView[] = useMemo(
+    () =>
+      (product?.options ?? []).map((o) => ({
+        ...o,
+        choices: o.choices.map((c) => ({ ...c, selected: selections[o.name] === c.name })),
+      })),
+    [product, selections],
+  );
+
+  const mandatoryModifiersFilled = (product?.modifiers ?? [])
+    .filter((m) => m.mandatory)
+    .every((m) => (modifierValues[m.key] ?? "").length > 0);
+
+  const canAdd =
+    !!product &&
+    product.availability !== "OUT_OF_STOCK" &&
+    variant !== null &&
+    variant.inStock &&
+    mandatoryModifiersFilled;
+
+  async function add(): Promise<void> {
+    if (!product || !variant) return;
+    setAdding(true);
+    setError(null);
+    try {
+      const choiceModifiers: Record<string, string> = {};
+      const textModifiers: Record<string, string> = {};
+      for (const m of product.modifiers) {
+        const value = modifierValues[m.key];
+        if (!value) continue;
+        if (m.type === "text") textModifiers[m.key] = value;
+        else choiceModifiers[m.key] = value;
+      }
+      await addToCart(product.id, variant.variantId, quantity, {
+        modifierChoices: choiceModifiers,
+        customTextFields: textModifiers,
+      });
+    } catch (e) {
+      setError(e instanceof Error ? e.message : String(e));
+      throw e;
+    } finally {
+      setAdding(false);
+    }
+  }
+
+  return {
+    product,
+    notFound,
+    optionGroups,
+    selectOption: (optionName, choiceName) =>
+      setSelections((s) => ({ ...s, [optionName]: choiceName })),
+    modifierValues,
+    setModifier: (key, value) => setModifierValues((v) => ({ ...v, [key]: value })),
+    variant,
+    price: variant?.price || product?.price || "",
+    compareAtPrice: variant ? variant.compareAtPrice : (product?.compareAtPrice ?? null),
+    canAdd,
+    quantity,
+    setQuantity,
+    add,
+    adding,
+    error,
+  };
+}

package/skills/wix-headless-fast/references/storefront/app/hooks/storefront/useShop.ts

@@ -0,0 +1,80 @@
+// Catalog listing + category filter for a shop/listing surface.
+//
+// SSR-friendly: when the host fetched the data already (Astro frontmatter, a server
+// component), pass it as `initial` and no client fetch happens for it. In a pure SPA,
+// pass nothing and the hook fetches on mount. Category switches always fetch live
+// (server-side-filtered by the category id).
+import { useEffect, useState } from "react";
+import {
+  fetchCategories,
+  fetchProducts,
+  fetchProductsByCategory,
+} from "../../wix/storefront/catalog";
+import type { Category, ProductSummary } from "../../wix/storefront/types";
+
+export interface UseShopOptions {
+  initialProducts?: ProductSummary[];
+  initialCategories?: Category[];
+  limit?: number;
+}
+
+export interface UseShop {
+  /** null while the first load is in flight — render skeletons, not an empty state. */
+  products: ProductSummary[] | null;
+  categories: Category[];
+  /** null = "all products". */
+  activeCategoryId: string | null;
+  setActiveCategoryId: (id: string | null) => void;
+  loading: boolean;
+  error: string | null;
+}
+
+export function useShop({ initialProducts, initialCategories, limit = 100 }: UseShopOptions = {}): UseShop {
+  const [products, setProducts] = useState<ProductSummary[] | null>(initialProducts ?? null);
+  const [categories, setCategories] = useState<Category[]>(initialCategories ?? []);
+  const [activeCategoryId, setActiveCategoryId] = useState<string | null>(null);
+  const [loading, setLoading] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+
+  useEffect(() => {
+    if (initialCategories) return;
+    let alive = true;
+    fetchCategories().then((c) => alive && setCategories(c));
+    return () => {
+      alive = false;
+    };
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, []);
+
+  useEffect(() => {
+    // The initial all-products data may have come from the server; only fetch when it
+    // didn't, or when the buyer picked a category.
+    if (activeCategoryId === null && initialProducts) {
+      setProducts(initialProducts);
+      return;
+    }
+    let alive = true;
+    setLoading(true);
+    setError(null);
+    const load = activeCategoryId
+      ? fetchProductsByCategory(activeCategoryId, { limit })
+      : fetchProducts({ limit });
+    load
+      .then((items) => {
+        if (!alive) return;
+        setProducts(items);
+      })
+      .catch((e) => {
+        if (!alive) return;
+        setProducts([]);
+        setError(e instanceof Error ? e.message : String(e));
+      })
+      .finally(() => alive && setLoading(false));
+    return () => {
+      alive = false;
+    };
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [activeCategoryId, limit]);
+
+  return { products, categories, activeCategoryId, setActiveCategoryId, loading, error };
+}

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

@@ -0,0 +1,101 @@
+// Client-side cart state — a module-scope store, deliberately NOT a React context.
+// A context can't span Astro islands (each island is its own React root); a module
+// singleton is shared by every island in the page bundle, and works identically in a
+// single-root SPA. Consume it through useCart() (hooks/), or subscribe directly.
+import type { Cart } from "./types";
+import {
+  addToCart as apiAdd,
+  fetchCart,
+  removeLine as apiRemove,
+  updateQuantity as apiUpdate,
+  checkoutUrl,
+  type AddToCartExtras,
+} from "./cart";
+
+export interface CartState {
+  cart: Cart | null;
+  /** True while any cart operation is in flight. */
+  busy: boolean;
+  /** Last failed operation's message — render it; a new operation clears it. */
+  error: string | null;
+  /** Cart drawer visibility (CartButton opens it, CartDrawer renders by it). */
+  open: boolean;
+}
+
+const EMPTY: CartState = { cart: null, busy: false, error: null, open: false };
+
+let state: CartState = EMPTY;
+const listeners = new Set<() => void>();
+let loaded = false;
+
+function setState(patch: Partial<CartState>): void {
+  state = { ...state, ...patch };
+  for (const l of listeners) l();
+}
+
+export function getCartState(): CartState {
+  return state;
+}
+
+export function subscribeCart(listener: () => void): () => void {
+  listeners.add(listener);
+  // First subscriber triggers the initial load (browser only — SSR renders the empty state).
+  if (!loaded && typeof window !== "undefined") {
+    loaded = true;
+    void refreshCart();
+  }
+  return () => listeners.delete(listener);
+}
+
+async function run(op: () => Promise<Cart>): Promise<void> {
+  setState({ busy: true, error: null });
+  try {
+    setState({ cart: await op(), busy: false });
+  } catch (e) {
+    setState({ busy: false, error: e instanceof Error ? e.message : String(e) });
+    throw e;
+  }
+}
+
+export async function refreshCart(): Promise<void> {
+  try {
+    setState({ cart: await fetchCart() });
+  } catch {
+    /* no cart yet — leave the empty state */
+  }
+}
+
+/** Add to cart and open the drawer. Throws (and sets .error) on refusal. */
+export async function addLine(
+  productId: string,
+  variantId?: string | null,
+  quantity = 1,
+  extras?: AddToCartExtras,
+): Promise<void> {
+  await run(() => apiAdd(productId, variantId, quantity, extras));
+  setState({ open: true });
+}
+
+export async function updateLineQuantity(lineItemId: string, quantity: number): Promise<void> {
+  await run(() => apiUpdate(lineItemId, quantity));
+}
+
+export async function removeCartLine(lineItemId: string): Promise<void> {
+  await run(() => apiRemove(lineItemId));
+}
+
+/** Navigate to the Wix-hosted checkout. Never hand-build a checkout URL. */
+export async function goToCheckout(): Promise<void> {
+  setState({ busy: true, error: null });
+  try {
+    const url = await checkoutUrl();
+    window.location.href = url;
+  } catch (e) {
+    setState({ busy: false, error: e instanceof Error ? e.message : String(e) });
+    throw e;
+  }
+}
+
+export function setCartOpen(open: boolean): void {
+  setState({ open });
+}

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

@@ -0,0 +1,221 @@
+// Cart + checkout (Wix eCom Cart V2) — the only file that touches raw cart entities.
+// Copy as-is; extend by calling these exports, never by editing them. The request shapes are
+// exact (catalogItems wrapper, options.variantId, the redirect-session body) and rewriting
+// them is how carts break.
+//
+// Failures are loud: these throw on out-of-stock lines, an empty cart at checkout, and a
+// missing required selection — surface the message to the buyer, don't swallow it.
+// docs: https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/purchase-flow/cart-v2/get-current-cart.md
+// 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-solutions/e-commerce/purchase-flow/cart-v2/update-line-items.md
+// docs: https://dev.wix.com/docs/api-reference/business-management/headless/redirects/create-redirect-session.md
+// docs: https://dev.wix.com/docs/api-reference/business-solutions/stores/catalog-v3/products-v3/query-products.md
+import { currentCartV2 } from "@wix/ecom";
+import { redirects as redirectsModule } from "@wix/redirects";
+import { productsV3 } from "@wix/stores";
+import { wixModule } from "../sdk";
+import { imgSrc } from "../media";
+import { formatMoney } from "../money";
+import type { Cart, CartLine } from "./types";
+
+const cartApi = wixModule(currentCartV2);
+const redirects = wixModule(redirectsModule);
+const productsApi = wixModule(productsV3);
+
+// The V2 cart does NOT return line-item images (attributes.image is typed but comes back
+// absent — verified against a live cart), so images are joined from the catalog by the
+// line's catalogItemId and cached for the session.
+const lineImageCache = new Map<string, string>();
+
+async function fillLineImages(lines: CartLine[], raws: RawCart[]): Promise<void> {
+  const wanted = new Map<string, number[]>(); // productId -> line indexes
+  raws.forEach((raw, i) => {
+    if (lines[i].imageUrl) return;
+    const pid = raw.source?.catalogReference?.catalogItemId;
+    if (!pid) return;
+    const cached = lineImageCache.get(pid);
+    if (cached !== undefined) {
+      lines[i].imageUrl = cached;
+      return;
+    }
+    wanted.set(pid, [...(wanted.get(pid) ?? []), i]);
+  });
+  if (!wanted.size) return;
+  try {
+    const res = await productsApi
+      .queryProducts()
+      .in("_id", [...wanted.keys()])
+      .find();
+    for (const p of (res.items ?? []) as RawCart[]) {
+      const url = imgSrc(p.media?.main, 300, 300);
+      lineImageCache.set(p._id, url);
+      for (const i of wanted.get(p._id) ?? []) lines[i].imageUrl = url;
+    }
+  } catch {
+    /* images are a nicety — the cart stays correct without them */
+  }
+}
+
+// Public app id of the Wix Stores catalog — required inside every catalogReference.
+const WIX_STORES_APP_ID = "215238eb-22a5-4c36-9e7b-e7c08025e04e";
+
+type RawCart = Record<string, any>;
+
+function cartCurrency(raw: RawCart | null): string {
+  return raw?.customerInfo?.currencyCode ?? raw?.businessInfo?.currencyCode ?? "";
+}
+
+function toLine(raw: RawCart, currency: string): CartLine {
+  const descriptionLines: string[] = (raw.attributes?.descriptionLines ?? [])
+    .map((d: RawCart) => {
+      const label = d.name?.original ?? "";
+      const value = d.plainText?.original ?? d.colorInfo?.original ?? "";
+      return label && value ? `${label}: ${value}` : value || label;
+    })
+    .filter(Boolean);
+  return {
+    lineItemId: raw._id ?? "",
+    productName: raw.name?.original ?? "",
+    quantity: raw.quantityInfo?.confirmedQuantity ?? 0,
+    unitPrice: formatMoney(raw.pricing?.unitPrice, currency),
+    linePrice: formatMoney(raw.pricing?.totalPrice, currency),
+    imageUrl: imgSrc(raw.attributes?.image, 300, 300),
+    descriptionLines,
+    status: raw.status ?? "IN_STOCK",
+  };
+}
+
+function toCart(raw: RawCart | null, subtotal: string): Cart {
+  const currency = cartCurrency(raw);
+  const lines = (raw?.lineItems ?? []).map((l: RawCart) => toLine(l, currency));
+  return {
+    lines,
+    itemCount: lines.reduce((sum: number, l: CartLine) => sum + l.quantity, 0),
+    subtotal,
+    currency,
+  };
+}
+
+async function readCartWithSubtotal(raw: RawCart | null): Promise<Cart> {
+  if (!raw?.lineItems?.length) return toCart(raw, "");
+  // The authoritative after-discount subtotal comes from the cart estimate, never from
+  // hand-summing line items (tax and shipping resolve at checkout).
+  let subtotal = "";
+  try {
+    const estimate: RawCart = await cartApi.estimateCurrentCart();
+    subtotal = formatMoney(estimate?.summary?.priceSummary?.subtotal, cartCurrency(raw));
+  } catch {
+    /* estimate is a display nicety — the cart itself is still valid */
+  }
+  const cart = toCart(raw, subtotal);
+  await fillLineImages(cart.lines, raw.lineItems as RawCart[]);
+  return cart;
+}
+
+/** Read the visitor's current cart. An empty Cart (not an error) when none exists yet. */
+export async function fetchCart(): Promise<Cart> {
+  try {
+    const { cart } = await cartApi.getCurrentCart();
+    return readCartWithSubtotal(cart as RawCart);
+  } catch {
+    return toCart(null, "");
+  }
+}
+
+export interface AddToCartExtras {
+  /** TEXT_CHOICES modifier selections: modifier key -> choice key. */
+  modifierChoices?: Record<string, string>;
+  /** FREE_TEXT modifier inputs: freeTextSettings key -> the buyer's text. */
+  customTextFields?: Record<string, string>;
+}
+
+/**
+ * Add a product to the current cart.
+ * For a product WITH options, `variantId` is mandatory — resolve it with
+ * `resolveVariant()` from ./catalog first. Mandatory modifiers must be included.
+ */
+export async function addToCart(
+  productId: string,
+  variantId?: string | null,
+  quantity = 1,
+  { modifierChoices, customTextFields }: AddToCartExtras = {},
+): Promise<Cart> {
+  const options: Record<string, unknown> = {};
+  if (variantId) options.variantId = variantId;
+  if (modifierChoices && Object.keys(modifierChoices).length) options.options = modifierChoices;
+  if (customTextFields && Object.keys(customTextFields).length) options.customTextFields = customTextFields;
+
+  const { cart } = await cartApi.addLineItemsToCurrentCart({
+    catalogItems: [
+      {
+        quantity,
+        catalogReference: {
+          catalogItemId: productId,
+          appId: WIX_STORES_APP_ID,
+          ...(Object.keys(options).length ? { options } : {}),
+        },
+      },
+    ],
+  });
+
+  const line = ((cart as RawCart)?.lineItems ?? []).find(
+    (l: RawCart) =>
+      l.source?.catalogReference?.catalogItemId === productId &&
+      (!variantId || l.source?.catalogReference?.options?.variantId === variantId),
+  );
+  if (line?.status && line.status !== "IN_STOCK") {
+    throw new Error(`This item isn't available right now (${line.status.toLowerCase().replace(/_/g, " ")}).`);
+  }
+  if (!line || line.quantityInfo?.confirmedQuantity === 0) {
+    throw new Error(
+      "The item couldn't be added. Make sure every required selection was made " +
+        "(options for a product with variants, and all mandatory customizations).",
+    );
+  }
+  return readCartWithSubtotal(cart as RawCart);
+}
+
+/** Change a line's quantity. `lineItemId` is CartLine.lineItemId, never the product id. */
+export async function updateQuantity(lineItemId: string, quantity: number): Promise<Cart> {
+  const { cart } = await cartApi.updateLineItemsInCurrentCart({
+    lineItems: [{ lineItemId, quantity: { newQuantity: quantity } }],
+  });
+  return readCartWithSubtotal(cart as RawCart);
+}
+
+/** Remove a line from the cart by CartLine.lineItemId. */
+export async function removeLine(lineItemId: string): Promise<Cart> {
+  const { cart } = await cartApi.removeLineItemsFromCurrentCart([lineItemId]);
+  return readCartWithSubtotal(cart as RawCart);
+}
+
+/**
+ * Start the Wix-hosted checkout for the current cart and return the URL to navigate to.
+ * The cart's id IS the checkout id — no separate checkout-creation call.
+ * Call from the browser: the return origin must be the site's real https origin
+ * (window.location.origin), never a server-derived request origin.
+ */
+export async function checkoutUrl(): Promise<string> {
+  const { cart } = await cartApi.getCurrentCart();
+  const raw = cart as RawCart;
+  const lines: RawCart[] = raw?.lineItems ?? [];
+  if (!lines.length) throw new Error("Your 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).filter(Boolean).join(", ");
+    throw new Error(`Some items are no longer available: ${names}.`);
+  }
+  if (!raw?._id) throw new Error("Checkout couldn't start: the cart has no id.");
+
+  const origin = typeof window !== "undefined" ? window.location.origin : "";
+  const session = await redirects.createRedirectSession({
+    ecomCheckout: { checkoutId: raw._id },
+    callbacks: {
+      postFlowUrl: origin ? `${origin}/` : undefined,
+      thankYouPageUrl: origin ? `${origin}/` : undefined,
+    },
+  });
+  const url = session?.redirectSession?.fullUrl;
+  if (!url) throw new Error("Checkout couldn't start: no redirect URL returned.");
+  return url;
+}