@wix/agent-skills 1.19.2 → 1.20.1

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

@@ -0,0 +1,289 @@
+// The shop listing as a framework-free store — the logic behind useShop, usable from React
+// (useShop wraps it with useSyncExternalStore), from a static page or Vue/Svelte (subscribe and
+// render), or as the specification for a port. Same shape as cart-store.ts: state, actions,
+// subscribe/getState, emit after every change.
+//
+// Category, sort, price/stock/search filters, option facets, and cursor paging are all applied
+// by Wix across the whole catalog (searchCatalog), never to a page already in hand. A changed
+// selection starts a fresh cursor chain; a late response from a superseded query is dropped.
+//
+// SSR-friendly: seed with `initialProducts`/`initialCategories` and they render at once; `start()`
+// then revalidates the first page to open the cursor chain, replacing the seed without a
+// skeleton flash. `initialCategoryId` scopes the first query (a /category/[slug] page).
+//
+// URL state: sort, filters, facet choices (and a live category switch on /shop) are read from the
+// query string by `start()` and written back with replaceState after every change — a filtered
+// gallery is a link a shopper can share, reload, and step back to. Paging stays out of the URL.
+//
+// One store per mounted listing (a page can hold a shop and a featured rail): createShopStore(),
+// not a singleton. The cart store is a singleton because the cart is one per visitor.
+import { CATALOG_SORTS, fetchCategories, fetchFacetData, searchCatalog, type CatalogSort } from "./catalog";
+import type { Category, Facet, PriceRange, ProductSummary } from "./types";
+
+export const SORTS = CATALOG_SORTS;
+
+export interface ShopFilters {
+  minPrice?: number | string;
+  maxPrice?: number | string;
+  inStockOnly?: boolean;
+  /** Name search, max 100 chars. */
+  search?: string;
+}
+
+export interface ShopStoreOptions {
+  initialProducts?: ProductSummary[];
+  initialCategories?: Category[];
+  /** Scope the listing to one category from the first render (a /category/[slug] page). */
+  initialCategoryId?: string | null;
+  pageSize?: number;
+  /** Mirror the selection into the query string (default true; off for a rail that isn't the page's subject). */
+  syncUrl?: boolean;
+}
+
+/** Everything a listing surface renders from. Read it with getState() or through a subscription. */
+export interface ShopState {
+  /** null while the first load is in flight — render skeletons, not an empty state. */
+  products: ProductSummary[] | null;
+  /** Matching products across the whole catalog for the current selection; null until known. */
+  total: number | null;
+  categories: Category[];
+  /** null = "all products". */
+  activeCategoryId: string | null;
+  sort: CatalogSort;
+  filters: ShopFilters;
+  /** The filterable options of the current scope (Color, Size…), from the catalog itself. */
+  facets: Facet[];
+  /** Lowest and highest product price in the scope — the price slider's bounds; null until known or when equal. */
+  priceRange: PriceRange | null;
+  /** Selected facet choice ids — products carrying ANY of them match. */
+  selectedChoiceIds: string[];
+  /** True when any filter or facet is active. */
+  hasActiveFilters: boolean;
+  loading: boolean;
+  error: string | null;
+  hasMore: boolean;
+  loadingMore: boolean;
+}
+
+export interface ShopStore {
+  getState(): ShopState;
+  subscribe(listener: () => void): () => void;
+  /** Adopt the URL, fetch categories/facets, open the cursor chain. Call once when mounted (a browser). */
+  start(): void;
+  /** Stop reacting; drop late responses. */
+  stop(): void;
+  setActiveCategoryId(id: string | null): void;
+  setSort(sort: CatalogSort): void;
+  setFilters(filters: ShopFilters): void;
+  toggleChoice(choiceId: string): void;
+  /** Clears price/stock/search filters and facet selections (keeps category and sort). */
+  clearFilters(): void;
+  retry(): void;
+  loadMore(): Promise<void>;
+}
+
+const URL_KEYS = { sort: "sort", min: "min", max: "max", stock: "stock", q: "q", choice: "choice", category: "category" } as const;
+
+function readUrlState(): { sort?: CatalogSort; filters: ShopFilters; choiceIds: string[]; categoryId?: string | null } | null {
+  if (typeof window === "undefined") return null;
+  const p = new URLSearchParams(window.location.search);
+  const sort = p.get(URL_KEYS.sort);
+  const filters: ShopFilters = {};
+  if (p.get(URL_KEYS.min)) filters.minPrice = p.get(URL_KEYS.min)!;
+  if (p.get(URL_KEYS.max)) filters.maxPrice = p.get(URL_KEYS.max)!;
+  if (p.get(URL_KEYS.stock) === "1") filters.inStockOnly = true;
+  if (p.get(URL_KEYS.q)) filters.search = p.get(URL_KEYS.q)!;
+  return {
+    sort: sort && sort in CATALOG_SORTS ? (sort as CatalogSort) : undefined,
+    filters,
+    choiceIds: p.getAll(URL_KEYS.choice),
+    categoryId: p.has(URL_KEYS.category) ? p.get(URL_KEYS.category) : undefined,
+  };
+}
+
+function writeUrlState(s: { sort: CatalogSort; filters: ShopFilters; selectedChoiceIds: string[]; activeCategoryId: string | null }, initialCategoryId: string | null): void {
+  if (typeof window === "undefined") return;
+  const p = new URLSearchParams(window.location.search);
+  for (const k of Object.values(URL_KEYS)) p.delete(k);
+  if (s.sort !== "featured") p.set(URL_KEYS.sort, s.sort);
+  if (s.filters.minPrice != null && s.filters.minPrice !== "") p.set(URL_KEYS.min, String(s.filters.minPrice));
+  if (s.filters.maxPrice != null && s.filters.maxPrice !== "") p.set(URL_KEYS.max, String(s.filters.maxPrice));
+  if (s.filters.inStockOnly) p.set(URL_KEYS.stock, "1");
+  if (s.filters.search?.trim()) p.set(URL_KEYS.q, s.filters.search.trim());
+  for (const id of s.selectedChoiceIds) p.append(URL_KEYS.choice, id);
+  if (s.activeCategoryId !== initialCategoryId) p.set(URL_KEYS.category, s.activeCategoryId ?? "");
+  const qs = p.toString();
+  const next = `${window.location.pathname}${qs ? `?${qs}` : ""}${window.location.hash}`;
+  if (next !== `${window.location.pathname}${window.location.search}${window.location.hash}`) window.history.replaceState(window.history.state, "", next);
+}
+
+export function createShopStore({ initialProducts, initialCategories, initialCategoryId = null, pageSize = 24, syncUrl = true }: ShopStoreOptions = {}): ShopStore {
+  // selection
+  let activeCategoryId: string | null = initialCategoryId;
+  let sort: CatalogSort = "featured";
+  let filters: ShopFilters = {};
+  let selectedChoiceIds: string[] = [];
+  let attempt = 0;
+  // data
+  let categories: Category[] = initialCategories ?? [];
+  let facets: Facet[] = [];
+  let priceRange: PriceRange | null = null;
+  // the current page; `key` is the selection it answers to (null = the SSR seed, no query yet)
+  let pageKey: string | null = null;
+  let products: ProductSummary[] | null = initialProducts ?? null;
+  let total: number | null = null;
+  let cursor: string | null = null;
+  let error: string | null = null;
+  let loadingMore = false;
+  // control
+  let started = false;
+  let generation = 0;
+  let pendingMore: object | null = null;
+  const listeners = new Set<() => void>();
+
+  const selectionKey = () =>
+    JSON.stringify([pageSize, activeCategoryId, sort, filters.minPrice ?? null, filters.maxPrice ?? null, !!filters.inStockOnly, filters.search ?? "", [...selectedChoiceIds].sort(), attempt]);
+
+  let snapshot: ShopState | null = null;
+  const emit = () => {
+    snapshot = null;
+    for (const fn of listeners) fn();
+  };
+
+  function getState(): ShopState {
+    if (snapshot) return snapshot;
+    const key = selectionKey();
+    const current = pageKey === key;
+    const seeded = pageKey === null && products !== null; // SSR seed, first query in flight
+    const hasActiveFilters =
+      selectedChoiceIds.length > 0 ||
+      !!filters.inStockOnly ||
+      (filters.minPrice != null && filters.minPrice !== "") ||
+      (filters.maxPrice != null && filters.maxPrice !== "") ||
+      !!(filters.search && filters.search.trim());
+    snapshot = {
+      products: current || seeded ? products : null,
+      total: current ? total : null,
+      categories,
+      activeCategoryId,
+      sort,
+      filters,
+      facets,
+      priceRange,
+      selectedChoiceIds,
+      hasActiveFilters,
+      // Seeded content on screen is not "loading" — skeletons are only for a genuinely empty wait.
+      loading: (!current && !seeded) || (current && products === null),
+      error: current ? error : null,
+      hasMore: current && !!cursor,
+      loadingMore: current && loadingMore,
+    };
+    return snapshot;
+  }
+
+  // Facets follow the category scope (a Size facet in "Donuts" is meaningless).
+  let facetScope: string | null | undefined;
+  function loadFacets(): void {
+    if (facetScope === activeCategoryId) return;
+    facetScope = activeCategoryId;
+    const scope = activeCategoryId;
+    fetchFacetData({ categoryId: scope }).then((d) => {
+      if (!started || scope !== activeCategoryId) return;
+      facets = d.facets;
+      priceRange = d.priceRange;
+      emit();
+    });
+  }
+
+  // Run the query for the current selection. Keeps the seed (or the previous page) on screen while
+  // it runs; only a selection change with no seed shows skeletons.
+  function query(): void {
+    if (!started) return;
+    const key = selectionKey();
+    const id = ++generation;
+    pendingMore = null;
+    if (pageKey !== null) products = null;
+    pageKey = key; total = null; cursor = null; error = null; loadingMore = false;
+    emit();
+    const [limit, categoryId, selectedSort, minPrice, maxPrice, inStockOnly, search, choiceIds] = JSON.parse(key);
+    searchCatalog({ limit, categoryId, sort: selectedSort, minPrice, maxPrice, inStockOnly, search, choiceIds })
+      .then((res) => {
+        if (generation !== id || selectionKey() !== key) return; // superseded — drop it
+        products = res.products; total = res.total; cursor = res.nextCursor; error = null;
+        emit();
+      })
+      .catch((e) => {
+        if (generation !== id || selectionKey() !== key) return;
+        products = []; total = null; cursor = null;
+        error = e instanceof Error ? e.message : "Couldn't load products.";
+        emit();
+      });
+  }
+
+  function changed(): void {
+    if (syncUrl) writeUrlState({ sort, filters, selectedChoiceIds, activeCategoryId }, initialCategoryId);
+    loadFacets();
+    // A new filters object with the same values keeps the page (same selection, same query).
+    if (selectionKey() === pageKey) emit();
+    else query();
+  }
+
+  return {
+    getState,
+    subscribe(fn) {
+      listeners.add(fn);
+      return () => listeners.delete(fn);
+    },
+    start() {
+      if (started) return;
+      started = true;
+      // Adopt the URL's selection once (the server rendered the defaults).
+      const u = syncUrl ? readUrlState() : null;
+      if (u) {
+        if (u.sort) sort = u.sort;
+        if (Object.keys(u.filters).length) filters = u.filters;
+        if (u.choiceIds.length) selectedChoiceIds = u.choiceIds;
+        if (u.categoryId !== undefined && u.categoryId !== initialCategoryId) activeCategoryId = u.categoryId || null;
+      }
+      if (!initialCategories) {
+        fetchCategories().then((list) => { if (started) { categories = list; emit(); } }).catch(() => { if (started) { categories = []; emit(); } });
+      }
+      loadFacets();
+      query();
+    },
+    stop() {
+      started = false;
+      generation++;
+    },
+    setActiveCategoryId(id) { if (id === activeCategoryId) return; activeCategoryId = id; changed(); },
+    setSort(next) { if (next === sort) return; sort = next; changed(); },
+    setFilters(next) { filters = next; changed(); },
+    toggleChoice(choiceId) {
+      selectedChoiceIds = selectedChoiceIds.includes(choiceId) ? selectedChoiceIds.filter((x) => x !== choiceId) : [...selectedChoiceIds, choiceId];
+      changed();
+    },
+    clearFilters() { filters = {}; selectedChoiceIds = []; changed(); },
+    retry() { attempt++; changed(); },
+    async loadMore() {
+      const key = selectionKey();
+      if (pageKey !== key || !cursor || pendingMore) return;
+      const request = { generation, key };
+      pendingMore = request; // blocks repeated clicks before a re-render
+      const isCurrent = () => generation === request.generation && selectionKey() === key;
+      loadingMore = true; error = null; emit();
+      try {
+        const res = await searchCatalog({ limit: pageSize, cursor });
+        if (isCurrent()) {
+          const seen = new Set((products ?? []).map((p) => p.id));
+          products = [...(products ?? []), ...res.products.filter((p) => (seen.has(p.id) ? false : (seen.add(p.id), true)))];
+          cursor = res.nextCursor;
+        }
+      } catch (e) {
+        if (isCurrent()) error = e instanceof Error ? e.message : "Couldn't load more products.";
+      } finally {
+        if (pendingMore === request) pendingMore = null;
+        if (isCurrent()) { loadingMore = false; emit(); }
+      }
+    },
+  };
+}

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

@@ -10,14 +10,24 @@ export interface ProductSummary {
   id: string;
   slug: string;
   name: string;
-  /** Lowest price, formatted with currency symbol (e.g. "€34.99"). */
+  /**
+   * The price the buyer pays for the cheapest variant, formatted (an automatic discount already
+   * applied). When `price !== maxPrice` the product is a RANGE — render "price – maxPrice".
+   */
   price: string;
-  /** Highest price, formatted — differs from `price` when variants are priced differently. */
+  /** Highest variant price, formatted — differs from `price` when variants are priced differently. */
   maxPrice: string;
-  /** Strikethrough "was" price, formatted; null when not on sale. */
+  /**
+   * Struck "was" price, formatted; null when not on sale — and ALWAYS null for a range (a lone
+   * struck minimum beside a range claims a saving that may not apply to the variant picked).
+   */
   compareAtPrice: string | null;
-  /** Merchant-set badge ("New", "Best Seller"); null when none. */
+  /** The primary merchant ribbon ("New", "Best Seller"); null when none. Same as ribbons[0]. */
   ribbon: string | null;
+  /** EVERY merchant ribbon, primary first ("New", "Sale") — render all of them, one shared style. */
+  ribbons: string[];
+  /** The cheapest variant's id — what a direct add sends for a product with no options; null when unknown. */
+  minPriceVariantId: string | null;
   availability: Availability;
   /** OUT_OF_STOCK but pre-orderable — label "Pre-order", not "Sold out". */
   preorder: boolean;
@@ -27,6 +37,11 @@ export interface ProductSummary {
   hoverImageUrl: string;
   /** e.g. "2 colors · 3 sizes"; "" for a single-variant product. */
   optionsSummary: string;
+  /**
+   * Hex colors of a color option's visible choices, catalog order — render as small dots on the
+   * tile (a preview, not a picker: selection happens in QuickAdd or on the PDP). [] when none.
+   */
+  swatches: string[];
   /** True when the product can be added to the cart with no choices (single variant, in stock). */
   quickAddable: boolean;
 }
@@ -60,15 +75,21 @@ export interface ProductVariant {
   variantId: string;
   /** The option selections this variant answers to: optionName -> choiceName. */
   choices: Record<string, string>;
+  /** The price the buyer pays, formatted — an automatic discount beats the regular price. */
   price: string;
+  /** Struck "was" price, formatted; null unless it is real and higher than `price`. */
   compareAtPrice: string | null;
   inStock: boolean;
+  /** Out of stock but pre-orderable — still buyable (the add carries preOrderRequested). */
+  preorderEnabled: boolean;
 }
 
 /** A product as the detail page needs it. */
 export interface ProductDetail extends ProductSummary {
   /** Product description as an HTML string — render with innerHTML, not as text. */
   descriptionHtml: string;
+  /** Merchant info sections (materials, shipping, care…) — title + HTML; render as sections or accordions. */
+  infoSections: { title: string; html: string }[];
   /** Every gallery image as a resolved https URL, main image first, de-duplicated. */
   gallery: string[];
   options: ProductOption[];
@@ -80,6 +101,36 @@ export interface Category {
   id: string;
   slug: string;
   name: string;
+  /** Plain-text description when the merchant wrote one; "" otherwise. */
+  description: string;
+}
+
+export interface FacetChoice {
+  /** The option choice id — what searchCatalog({ choiceIds }) filters on. */
+  id: string;
+  name: string;
+  /** Hex color for a swatch facet; null for a text facet. */
+  colorCode: string | null;
+}
+
+/** One filterable option across the catalog (or a category): "Color" with its choices. */
+export interface Facet {
+  name: string;
+  isColor: boolean;
+  choices: FacetChoice[];
+}
+
+/** The catalog's (or category's) lowest and highest product price, as numbers in site currency — the slider's bounds. */
+export interface PriceRange {
+  min: number;
+  max: number;
+  currency: string;
+}
+
+/** What the filter panel needs beyond the product page: the facets and the price bounds of the scope. */
+export interface FacetData {
+  facets: Facet[];
+  priceRange: PriceRange | null;
 }
 
 export interface CartLine {
@@ -97,6 +148,11 @@ export interface CartLine {
   descriptionLines: string[];
   /** Not IN_STOCK → the line can't be checked out as-is. */
   status: string;
+  /**
+   * The recurring plan's terms for a subscription line — "Monthly plan · every month · 12 payments";
+   * "" for a one-time purchase. A subscription line must read as one in the cart.
+   */
+  subscription: string;
 }
 
 export interface Cart {
@@ -105,5 +161,7 @@ export interface Cart {
   itemCount: number;
   /** Formatted subtotal (after discounts) — from the cart estimate, not hand-summed. */
   subtotal: string;
+  /** Formatted CART-level discount (a coupon or cart rule) — "" when none; item discounts are already in subtotal. */
+  discount: string;
   currency: string;
 }

package/skills/wix-headless-fast/references/storefront/app-astro/layouts/SiteLayout.astro

@@ -1,12 +1,18 @@
 ---
 // The site chrome for every storefront page — THIS file (header/footer/nav) plus the @theme
 // token block in src/styles/global.css are what you brand. Keep:
-//   - the <slot name="seo-tags" /> in <head> (the product page's owner-editable SEO lands there)
+//   - the <slot name="seo-tags" /> in <head> (the product page's owner-editable SEO lands there,
+//     including the <title> — which is why ours is printed only when the slot is empty)
 //   - the global.css import (Tailwind + the design tokens every shipped component reads)
 //   - one <CartButton> in the header and one <CartDrawer> per page (both client:only —
 //     they read browser cart state and must not server-render)
+//   - category links in the nav (or your own menu/footer) — every category page reachable by
+//     a real link (`/category/<slug>`), from the live tree, so a category the owner adds later
+//     shows up with no code change
 import CartButton from "../components/storefront/CartButton";
 import CartDrawer from "../components/storefront/CartDrawer";
+import { fetchCategories } from "../wix/storefront/catalog";
+import type { Category } from "../wix/storefront/types";
 import "../styles/global.css";
 
 interface Props {
@@ -14,6 +20,15 @@ interface Props {
   description?: string;
 }
 const { title, description } = Astro.props;
+
+// Non-fatal: the chrome renders without the links if the read fails. Six in the header keeps a
+// large tree from crowding it — put the rest in a menu or the footer, but keep them linked.
+let navCategories: Category[] = [];
+try {
+  navCategories = (await fetchCategories()).slice(0, 6);
+} catch {
+  /* the shop link still reaches everything */
+}
 ---
 
 <!doctype html>
@@ -21,7 +36,8 @@ const { title, description } = Astro.props;
   <head>
     <meta charset="UTF-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
-    <title>{title}</title>
+    {/* The product page's <SEO.Tags> renders the <title>; print ours only when no page filled the slot — two titles otherwise. */}
+    {!Astro.slots.has("seo-tags") && <title>{title}</title>}
     {description && <meta name="description" content={description} />}
     <slot name="seo-tags" />
   </head>
@@ -31,6 +47,9 @@ const { title, description } = Astro.props;
         <a href="/" class="text-base font-bold tracking-tight text-foreground no-underline">Brand Name</a>
         <nav class="flex items-center gap-6 text-sm">
           <a href="/shop" class="text-foreground no-underline transition-colors hover:text-muted-foreground">Shop</a>
+          {navCategories.map((c) => (
+            <a href={`/category/${c.slug}`} class="hidden text-foreground no-underline transition-colors hover:text-muted-foreground md:inline">{c.name}</a>
+          ))}
           <CartButton client:only="react" />
         </nav>
       </div>

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

@@ -0,0 +1,132 @@
+// Cart + checkout over REST (Wix eCom Cart V2) — the twin of app/wix/storefront/cart.ts. Same
+// exports, same Cart/CartLine DTOs; rules and mappers from cart-core (the SAME file the SDK
+// transport uses, deployed flat next to this one). The request shapes are
+// exact and rewriting them is how carts break. Failures are loud: out-of-stock lines, an empty cart
+// at checkout, a missing required selection all throw — surface the message to the buyer.
+// All calls run with the visitor token: the cart is the token's (see ../shared/client).
+// 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-management/headless/redirects/create-redirect-session.md
+import { WixApiError, wixRequest } from "./client.js";
+import { imgSrc } from "./media.js";
+import { WIX_STORES_APP_ID, addOptions, assertAdded, assertCheckoutable, rawId, summaryTotals, toCart } from "./cart-core.js";
+import type { Raw } from "./catalog-core.js";
+import type { Cart } from "./types.js";
+
+const CART = "/ecom/v2/carts/current";
+
+export interface AddToCartExtras {
+  /** Choice modifiers: modifier key → chosen choice key (options.options — MODIFIERS only, never Size/Color). */
+  modifierChoices?: Record<string, string>;
+  /** Free-text modifiers: freeTextSettings.key → the buyer's text. */
+  customTextFields?: Record<string, string>;
+  /** A chosen recurring plan; omit for a one-time purchase. */
+  subscriptionOptionId?: string;
+  /** The resolved variant is out of stock but pre-orderable → preOrderRequested. */
+  preorder?: boolean;
+}
+
+// A line's attributes.image comes back absent right after an add (verified live) — join the
+// products' main images by catalogItemId, once per product, cached for the session.
+// POST /stores/v3/products/query  { query: { filter: { id: { $in: [...] } } } }
+const lineImageCache = new Map<string, string>();
+async function fillLineImages(cart: Cart, raws: Raw[]): Promise<void> {
+  const wanted = new Map<string, number[]>();
+  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 wixRequest<Raw>("/stores/v3/products/query", { body: { query: { filter: { id: { $in: [...wanted.keys()] } }, cursorPaging: { limit: 100 } } } });
+    for (const p of (res?.products ?? []) 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 after-discount subtotal and the CART-level discount come from the 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.   POST /ecom/v2/carts/current/estimate
+  let totals = { subtotal: "", discount: "" };
+  try {
+    totals = summaryTotals(await wixRequest<Raw>(`${CART}/estimate`, { body: {} }), raw);
+  } catch {
+    /* the 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;
+}
+
+// GET /ecom/v2/carts/current — a 404 (CURRENT_CART_NOT_FOUND / OWNED_CART_NOT_FOUND) means no cart yet.
+async function getCurrentCartRaw(): Promise<Raw | null> {
+  try {
+    return (await wixRequest<Raw>(CART, { method: "GET" }))?.cart ?? null;
+  } catch (e) {
+    if (e instanceof WixApiError && e.status === 404) return null;
+    throw e;
+  }
+}
+
+/** The visitor's current cart. An empty Cart (not an error) when none exists yet. */
+export async function fetchCart(): Promise<Cart> {
+  return readCartWithSubtotal(await getCurrentCartRaw());
+}
+
+/**
+ * Add a product. `variantId` is REQUIRED for any product with options — resolve it first
+ * (resolveVariant); a refused add still returns 200, so the returned line is checked.
+ * POST /ecom/v2/carts/current/add-line-items  { catalogItems: [{ quantity, catalogReference: { appId, catalogItemId, options } }] }
+ */
+export async function addToCart(productId: string, variantId?: string | null, quantity = 1, extras: AddToCartExtras = {}): Promise<Cart> {
+  const options = addOptions({ variantId, ...extras });
+  const res = await wixRequest<Raw>(`${CART}/add-line-items`, {
+    body: { catalogItems: [{ quantity, catalogReference: { catalogItemId: productId, appId: WIX_STORES_APP_ID, ...(Object.keys(options).length ? { options } : {}) } }] },
+  });
+  assertAdded(res?.cart, productId, variantId);
+  return readCartWithSubtotal(res?.cart ?? null);
+}
+
+/**
+ * Change a line's quantity. `lineItemId` is CartLine.lineItemId, never the product id; a flat
+ * { id, quantity } is a 400.  POST /ecom/v2/carts/current/update-line-items  { lineItems: [{ lineItemId, quantity: { newQuantity } }] }
+ */
+export async function updateQuantity(lineItemId: string, quantity: number): Promise<Cart> {
+  const res = await wixRequest<Raw>(`${CART}/update-line-items`, { body: { lineItems: [{ lineItemId, quantity: { newQuantity: quantity } }] } });
+  return readCartWithSubtotal(res?.cart ?? null);
+}
+
+/** Remove a line by CartLine.lineItemId.  POST /ecom/v2/carts/current/remove-line-items  { lineItemIds } */
+export async function removeLine(lineItemId: string): Promise<Cart> {
+  const res = await wixRequest<Raw>(`${CART}/remove-line-items`, { body: { lineItemIds: [lineItemId] } });
+  return readCartWithSubtotal(res?.cart ?? null);
+}
+
+/**
+ * Start the Wix-hosted checkout and return the URL to navigate the FULL document to. The cart's id
+ * IS the checkout id. `origin` must be the site's real https origin as registered on the OAuth
+ * app's allowed domains (browser: window.location.origin; server: the public https host, never
+ * the request's internal origin) — an unlisted or http origin 403s on return.
+ * POST /headless/v1/redirect-session  { ecomCheckout: { checkoutId }, callbacks: { postFlowUrl, thankYouPageUrl } }
+ */
+export async function checkoutUrl(origin: string = typeof window !== "undefined" ? window.location.origin : ""): Promise<string> {
+  const raw = await getCurrentCartRaw();
+  assertCheckoutable(raw);
+  const res = await wixRequest<Raw>("/headless/v1/redirect-session", {
+    body: { ecomCheckout: { checkoutId: rawId(raw) }, callbacks: origin ? { postFlowUrl: `${origin}/`, thankYouPageUrl: `${origin}/` } : {} },
+  });
+  const url = res?.redirectSession?.fullUrl;
+  if (!url) throw new Error("Checkout couldn't start: no redirect URL returned.");
+  return url;
+}