@wix/agent-skills 1.21.0 → 1.22.0

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

@@ -1,48 +0,0 @@
-// React binding for the cart store. Works in any React root — Astro islands (several on one
-// page share the same store) and SPAs alike.
-import { useSyncExternalStore } from "react";
-import {
-  addLine,
-  getCartState,
-  goToCheckout,
-  refreshCart,
-  removeCartLine,
-  setCartOpen,
-  subscribeCart,
-  updateLineQuantity,
-  type CartState,
-} from "../../wix/storefront/cart-store";
-import type { AddToCartExtras } from "../../wix/storefront/cart";
-
-const SERVER_STATE = getCartState();
-
-export interface UseCart extends CartState {
-  itemCount: number;
-  addToCart: (
-    productId: string,
-    variantId?: string | null,
-    quantity?: number,
-    extras?: AddToCartExtras,
-  ) => Promise<void>;
-  updateQuantity: (lineItemId: string, quantity: number) => Promise<void>;
-  removeLine: (lineItemId: string) => Promise<void>;
-  checkout: () => Promise<void>;
-  openCart: () => void;
-  closeCart: () => void;
-  refresh: () => Promise<void>;
-}
-
-export function useCart(): UseCart {
-  const state = useSyncExternalStore(subscribeCart, getCartState, () => SERVER_STATE);
-  return {
-    ...state,
-    itemCount: state.cart?.itemCount ?? 0,
-    addToCart: addLine,
-    updateQuantity: updateLineQuantity,
-    removeLine: removeCartLine,
-    checkout: goToCheckout,
-    openCart: () => setCartOpen(true),
-    closeCart: () => setCartOpen(false),
-    refresh: refreshCart,
-  };
-}

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

@@ -1,39 +0,0 @@
-// React binding of the product-detail store (wix/storefront/product-detail-store.ts) — option
-// selection → variant resolution → add-to-cart lives there, framework-free. Always drive a PDP or
-// quick-add picker through this hook (or the store): resolving variants by hand is where
-// "added variants[0] regardless of the buyer's choice" comes from.
-//
-// SSR-friendly: pass the server-fetched ProductDetail as `initial` (Astro/Next); in a SPA pass
-// the slug and it fetches on mount.
-import { useEffect, useRef, useSyncExternalStore } from "react";
-import {
-  createProductDetailStore,
-  type ProductDetailState,
-  type ProductDetailStore,
-  type ProductDetailStoreOptions,
-} from "../../wix/storefront/product-detail-store";
-
-export { type OptionGroupView } from "../../wix/storefront/product-detail-store";
-
-export type UseProductDetailOptions = ProductDetailStoreOptions;
-
-export type UseProductDetail = ProductDetailState &
-  Pick<ProductDetailStore, "selectOption" | "setModifier" | "setQuantity" | "add">;
-
-export function useProductDetail({ initial, slug }: UseProductDetailOptions): UseProductDetail {
-  const ref = useRef<{ slug?: string; store: ProductDetailStore } | null>(null);
-  if (!ref.current || ref.current.slug !== slug) ref.current = { slug, store: createProductDetailStore({ initial, slug }) };
-  const store = ref.current.store;
-  useEffect(() => {
-    store.start();
-    return () => store.stop();
-  }, [store]);
-  const state = useSyncExternalStore(store.subscribe, store.getState, store.getState);
-  return {
-    ...state,
-    selectOption: store.selectOption,
-    setModifier: store.setModifier,
-    setQuantity: store.setQuantity,
-    add: store.add,
-  };
-}

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

@@ -1,34 +0,0 @@
-// React binding of the shop store (wix/storefront/shop-store.ts) — the listing state machine
-// lives there, framework-free; this hook subscribes to one instance per mounted listing and
-// exposes its state and actions under one name. Astro islands and React SPAs use this; a static
-// page, Vue, or Svelte uses the store directly.
-import { useEffect, useRef, useSyncExternalStore } from "react";
-import { createShopStore, type ShopState, type ShopStore, type ShopStoreOptions } from "../../wix/storefront/shop-store";
-
-export { SORTS, type ShopFilters } from "../../wix/storefront/shop-store";
-
-export type UseShopOptions = ShopStoreOptions;
-
-export type UseShop = ShopState &
-  Pick<ShopStore, "setActiveCategoryId" | "setSort" | "setFilters" | "toggleChoice" | "clearFilters" | "retry" | "loadMore">;
-
-export function useShop(options: UseShopOptions = {}): UseShop {
-  const ref = useRef<ShopStore | null>(null);
-  if (!ref.current) ref.current = createShopStore(options);
-  const store = ref.current;
-  useEffect(() => {
-    store.start();
-    return () => store.stop();
-  }, [store]);
-  const state = useSyncExternalStore(store.subscribe, store.getState, store.getState);
-  return {
-    ...state,
-    setActiveCategoryId: store.setActiveCategoryId,
-    setSort: store.setSort,
-    setFilters: store.setFilters,
-    toggleChoice: store.toggleChoice,
-    clearFilters: store.clearFilters,
-    retry: store.retry,
-    loadMore: store.loadMore,
-  };
-}

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

@@ -1,121 +0,0 @@
-// Cart rules and DTO mapping — transport-agnostic, imported by both ./cart.ts (SDK) and the REST
-// twin in references/storefront/rest/cart.ts (fetch). Raw Cart V2 entities may carry `_id` (SDK)
-// or `id` (REST). Has its own formatMoney (a copy of ../money.ts) so it stands alone when stripped.
-import type { Cart, CartLine } from "./types";
-import type { ImgSrc, Raw } from "./catalog-core";
-
-/** Public app id of the Wix Stores catalog — required inside every catalogReference. */
-export const WIX_STORES_APP_ID = "215238eb-22a5-4c36-9e7b-e7c08025e04e";
-
-export const rawId = (raw: Raw | undefined | null): string => raw?._id ?? raw?.id ?? "";
-
-/**
- * Cart V2 money is ConvertedMoney { amount, convertedAmount } with NO formatted string, and the
- * currency lives on the cart, not on the money. Format with the buyer's display currency when
- * present, else the site's. Never hardcode "$" or assume USD.
- */
-export function formatMoney(money: Raw | null | undefined, currencyCode: string | null | undefined): string {
-  const value = money?.convertedAmount ?? money?.amount;
-  if (value == null || value === "") return "";
-  const currency = currencyCode || "USD";
-  try {
-    return new Intl.NumberFormat(undefined, { style: "currency", currency }).format(Number(value));
-  } catch {
-    return `${value} ${currency}`;
-  }
-}
-
-export const cartCurrency = (raw: Raw | null | undefined): string =>
-  raw?.customerInfo?.currencyCode ?? raw?.businessInfo?.currencyCode ?? "";
-
-/**
- * "Monthly plan · every 2 months · 6 payments" from the line's subscriptionInfo (Cart V2 carries
- * the plan on the line); "" for a one-time purchase. Every word comes from the plan — a
- * subscription line must read as one in the cart, never a generic "recurring".
- */
-export function subscriptionTerms(info: Raw | undefined): string {
-  if (!info) return "";
-  const s: Raw = info.subscriptionSettings ?? {};
-  const unit: Record<string, string> = { DAY: "day", WEEK: "week", MONTH: "month", YEAR: "year" };
-  const parts: string[] = [];
-  const title = info.title?.original ?? info.title?.translated ?? "";
-  if (title) parts.push(title);
-  const u = unit[String(s.frequency ?? "")];
-  if (u) parts.push(`every ${s.interval && s.interval > 1 ? `${s.interval} ${u}s` : u}`);
-  if (!s.autoRenewal && s.billingCycles) parts.push(`${s.billingCycles} payments`);
-  return parts.join(" · ");
-}
-
-export function toLine(raw: Raw, currency: string, imgSrc: ImgSrc): CartLine {
-  return {
-    lineItemId: rawId(raw), // the LINE id — what update/remove take, never the product 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: ((raw.attributes?.descriptionLines ?? []) as Raw[])
-      .map((d) => {
-        const label = d.name?.original ?? "", value = d.plainText?.original ?? d.colorInfo?.original ?? "";
-        return label && value ? `${label}: ${value}` : value || label;
-      })
-      .filter(Boolean),
-    status: raw.status ?? "IN_STOCK", // not IN_STOCK → the line can't be checked out as-is
-    subscription: subscriptionTerms(raw.subscriptionInfo),
-  };
-}
-
-export function toCart(raw: Raw | null, subtotal: string, discount: string, imgSrc: ImgSrc): Cart {
-  const currency = cartCurrency(raw);
-  const lines = ((raw?.lineItems ?? []) as Raw[]).map((l) => toLine(l, currency, imgSrc));
-  return { lines, itemCount: lines.reduce((n, l) => n + l.quantity, 0), subtotal, discount, currency };
-}
-
-/** The after-discount subtotal and the CART-level discount from an estimate; "" when unknown. */
-export function summaryTotals(estimate: Raw | null | undefined, raw: Raw): { subtotal: string; discount: string } {
-  const s = estimate?.summary?.priceSummary;
-  const currency = cartCurrency(raw);
-  const d = s?.discount;
-  return {
-    subtotal: formatMoney(s?.subtotal, currency),
-    discount: Number(d?.convertedAmount ?? d?.amount ?? 0) > 0 ? formatMoney(d, currency) : "",
-  };
-}
-
-/** The catalogReference.options object for an add — omits every key the buyer didn't use. */
-export function addOptions({ variantId, modifierChoices, customTextFields, subscriptionOptionId, preorder }: {
-  variantId?: string | null; modifierChoices?: Record<string, string>; customTextFields?: Record<string, string>;
-  subscriptionOptionId?: string; preorder?: boolean;
-}): Raw {
-  const o: Raw = {};
-  if (variantId) o.variantId = variantId;                                            // REQUIRED for any product with options
-  if (modifierChoices && Object.keys(modifierChoices).length) o.options = modifierChoices; // MODIFIERS only, never Size/Color
-  if (customTextFields && Object.keys(customTextFields).length) o.customTextFields = customTextFields;
-  if (subscriptionOptionId) o.subscriptionOptionId = subscriptionOptionId;
-  if (preorder) o.preOrderRequested = true;
-  return o;
-}
-
-/** Read the add result — a refused add still returns 200: a line whose status isn't IN_STOCK, or no line, is a refusal. */
-export function assertAdded(cart: Raw | null | undefined, productId: string, variantId?: string | null): void {
-  const line = ((cart?.lineItems ?? []) as Raw[]).find(
-    (l) => 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 (${String(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).");
-  }
-}
-
-/** Refuse checkout for an empty cart or any line not IN_STOCK — say which. */
-export function assertCheckoutable(raw: Raw | null): void {
-  const lines: Raw[] = 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) {
-    throw new Error(`Some items are no longer available: ${unavailable.map((l) => l.name?.original).filter(Boolean).join(", ")}.`);
-  }
-  if (!rawId(raw)) throw new Error("Checkout couldn't start: the cart has no id.");
-}

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

@@ -1,107 +0,0 @@
-// 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> {
-  try {
-    await run(() => apiAdd(productId, variantId, quantity, extras));
-  } finally {
-    // Open either way. On success this shows the new line; on refusal it's the only thing that
-    // makes .error visible — the drawer renders it, and a drawer that stays shut on failure
-    // turns a refused add (out of stock, a digital product with no file) into silence.
-    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

@@ -1,138 +0,0 @@
-// Cart + checkout (Wix eCom Cart V2) over the SDK — the only file that touches raw cart entities
-// on this transport. Rules and mappers live in ./cart-core (shared with the REST twin in
-// references/storefront/rest/); this file is the transport only. 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
-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 { WIX_STORES_APP_ID, addOptions, assertAdded, assertCheckoutable, rawId, summaryTotals, toCart } from "./cart-core";
-import type { Raw } from "./catalog-core";
-import type { Cart } from "./types";
-
-const cartApi = wixModule(currentCartV2);
-const redirects = wixModule(redirectsModule);
-const productsApi = wixModule(productsV3);
-
-export interface AddToCartExtras {
-  /** TEXT_CHOICES modifier selections: modifier key -> choice key (options.options — MODIFIERS only, never Size/Color). */
-  modifierChoices?: Record<string, string>;
-  /** FREE_TEXT modifier inputs: freeTextSettings key -> the buyer's text. */
-  customTextFields?: Record<string, string>;
-  /** The variant is out of stock but pre-orderable — sends preOrderRequested. */
-  preorder?: boolean;
-  /** A chosen recurring plan (subscriptionPricesInfo); omit for a one-time purchase. */
-  subscriptionOptionId?: string;
-}
-
-// 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(cart: Cart, raws: Raw[]): Promise<void> {
-  const wanted = new Map<string, number[]>(); // productId -> line indexes
-  raws.forEach((raw, i) => {
-    if (cart.lines[i].imageUrl) return;
-    const pid = raw.source?.catalogReference?.catalogItemId;
-    if (!pid) return;
-    const cached = lineImageCache.get(pid);
-    if (cached !== undefined) {
-      cart.lines[i].imageUrl = cached;
-      return;
-    }
-    wanted.set(pid, [...(wanted.get(pid) ?? []), i]);
-  });
-  if (!wanted.size) return;
-  try {
-    const res = await productsApi.queryProducts().in("_id", [...wanted.keys()]).find();
-    for (const p of (res.items ?? []) as Raw[]) {
-      const url = imgSrc(p.media?.main, 300, 300);
-      lineImageCache.set(rawId(p), url);
-      for (const i of wanted.get(rawId(p)) ?? []) cart.lines[i].imageUrl = url;
-    }
-  } catch {
-    /* images are a nicety — the cart stays correct without them */
-  }
-}
-
-async function readCartWithSubtotal(raw: Raw | null): Promise<Cart> {
-  // Only estimate a cart WITH lines — on an absent/empty cart the endpoint returns 404.
-  if (!raw?.lineItems?.length) return toCart(raw, "", "", imgSrc);
-  // The authoritative after-discount subtotal and the CART-level discount come from the cart
-  // estimate, never from hand-summing lines. Its delivery/tax/fees read "0" when nothing was
-  // calculated — never render those as "Free"; shipping and tax resolve at checkout.
-  let totals = { subtotal: "", discount: "" };
-  try {
-    totals = summaryTotals(await cartApi.estimateCurrentCart(), raw);
-  } catch {
-    /* estimate is a display nicety — the cart itself is still valid */
-  }
-  const cart = toCart(raw, totals.subtotal, totals.discount, imgSrc);
-  await fillLineImages(cart, raw.lineItems as Raw[]);
-  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 Raw);
-  } catch {
-    return toCart(null, "", "", imgSrc);
-  }
-}
-
-/**
- * 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.
- * A refused add still returns 200, so the returned line is checked.
- */
-export async function addToCart(productId: string, variantId?: string | null, quantity = 1, extras: AddToCartExtras = {}): Promise<Cart> {
-  const options = addOptions({ variantId, ...extras });
-  const { cart } = await cartApi.addLineItemsToCurrentCart({
-    catalogItems: [{ quantity, catalogReference: { catalogItemId: productId, appId: WIX_STORES_APP_ID, ...(Object.keys(options).length ? { options } : {}) } }],
-  });
-  assertAdded(cart as Raw, productId, variantId);
-  return readCartWithSubtotal(cart as Raw);
-}
-
-/** 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 Raw);
-}
-
-/** 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 Raw);
-}
-
-/**
- * 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 Raw;
-  assertCheckoutable(raw);
-  const origin = typeof window !== "undefined" ? window.location.origin : "";
-  const session = await redirects.createRedirectSession({
-    ecomCheckout: { checkoutId: rawId(raw) },
-    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;
-}