@wix/agent-skills 1.26.0 → 1.28.0

package/skills/wix-headless-templates/storefront/project/src/wix/storefront/shop-store.ts

@@ -0,0 +1,341 @@
+// 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. The
+// previous page stays on screen (with `loading: true`) while the new one loads — skeletons only
+// when there is nothing to show yet.
+//
+// Facet picks are kept PER FACET: choices inside one facet OR together, facets AND together
+// ("Red or Blue, and Large"), exactly as Wix's own storefront filters; a linked choice's children
+// ride along with it.
+//
+// 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, type FacetSelection } from "./catalog";
+import { expandFacetChoiceIds } from "./catalog-core";
+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. During a later selection change the
+   * previous page stays here with `loading: true` (dim it, don't blank it).
+   */
+  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 customizations of the current scope (Color, Size, a choice modifier…), 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 (every facet together) — what the chips and the panel's pressed state read. */
+  selectedChoiceIds: string[];
+  /** True when any filter or facet is active. */
+  hasActiveFilters: boolean;
+  /** A query is in flight for the current selection (the products shown may be the previous page's). */
+  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;
+  /** Select / deselect a facet choice (the facet is found from the loaded facets). */
+  toggleChoice(choiceId: string): void;
+  /** Clears price/stock/search filters and facet selections (keeps category and sort). */
+  clearFilters(): void;
+  retry(): void;
+  loadMore(): Promise<void>;
+}
+
+/** A pick remembers its facet so the query can group it before the facets are loaded (a shared link). */
+interface SelectedChoice {
+  kind: Facet["kind"];
+  facetId: string;
+  choiceId: string;
+}
+
+const URL_KEYS = { sort: "sort", min: "min", max: "max", stock: "stock", q: "q", choice: "choice", category: "category" } as const;
+
+// choice=<kind>:<facetId>:<choiceId>; a bare choice id (an older link) counts as an option pick.
+const encodeChoice = (s: SelectedChoice): string => `${s.kind}:${s.facetId}:${s.choiceId}`;
+function decodeChoice(token: string): SelectedChoice | null {
+  const parts = token.split(":");
+  if (parts.length === 3 && (parts[0] === "option" || parts[0] === "modifier") && parts[2]) return { kind: parts[0], facetId: parts[1], choiceId: parts[2] };
+  if (parts.length === 1 && parts[0]) return { kind: "option", facetId: "", choiceId: parts[0] };
+  return null;
+}
+
+function readUrlState(): { sort?: CatalogSort; filters: ShopFilters; selected: SelectedChoice[]; 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,
+    selected: p.getAll(URL_KEYS.choice).map(decodeChoice).filter((s): s is SelectedChoice => s !== null),
+    categoryId: p.has(URL_KEYS.category) ? p.get(URL_KEYS.category) : undefined,
+  };
+}
+
+function writeUrlState(s: { sort: CatalogSort; filters: ShopFilters; selected: SelectedChoice[]; 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 c of s.selected) p.append(URL_KEYS.choice, encodeChoice(c));
+  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 selected: SelectedChoice[] = [];
+  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 hasMore = false;
+  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>();
+
+  // The picks grouped per facet, each with its linked children (known once the facets loaded),
+  // in a stable order — the query and its key are built from this.
+  function facetSelections(): FacetSelection[] {
+    const groups = new Map<string, FacetSelection>();
+    for (const s of selected) {
+      const key = `${s.kind}:${s.facetId}`;
+      const g = groups.get(key) ?? { id: s.facetId, kind: s.kind, choiceIds: [] };
+      for (const cid of expandFacetChoiceIds(facets.find((f) => f.id === s.facetId), [s.choiceId])) if (!g.choiceIds.includes(cid)) g.choiceIds.push(cid);
+      groups.set(key, g);
+    }
+    return [...groups.values()]
+      .map((g) => ({ ...g, choiceIds: [...g.choiceIds].sort() }))
+      .sort((a, b) => `${a.kind}:${a.id}`.localeCompare(`${b.kind}:${b.id}`));
+  }
+
+  const selectionKey = () =>
+    JSON.stringify([pageSize, activeCategoryId, sort, filters.minPrice ?? null, filters.maxPrice ?? null, !!filters.inStockOnly, filters.search ?? "", facetSelections(), 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 hasActiveFilters =
+      selected.length > 0 ||
+      !!filters.inStockOnly ||
+      (filters.minPrice != null && filters.minPrice !== "") ||
+      (filters.maxPrice != null && filters.maxPrice !== "") ||
+      !!(filters.search && filters.search.trim());
+    snapshot = {
+      // the seed or the previous page stays visible while a query runs; null only before anything loaded
+      products,
+      total: current ? total : null,
+      categories,
+      activeCategoryId,
+      sort,
+      filters,
+      facets,
+      priceRange,
+      selectedChoiceIds: selected.map((s) => s.choiceId),
+      hasActiveFilters,
+      // Content on screen is not "loading" in the skeleton sense — the flag says a query is in flight.
+      loading: !current || products === null,
+      error: current ? error : null,
+      hasMore: current && hasMore && !!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;
+      // A pick from the URL may have gained linked children now that its facet is known.
+      if (selectionKey() !== pageKey) query();
+      else emit();
+    });
+  }
+
+  // Run the query for the current selection. Keeps the seed (or the previous page) on screen while
+  // it runs; skeletons only when there is nothing yet.
+  function query(): void {
+    if (!started) return;
+    const key = selectionKey();
+    const id = ++generation;
+    pendingMore = null;
+    pageKey = key; total = null; cursor = null; hasMore = false; error = null; loadingMore = false;
+    emit();
+    const [limit, categoryId, selectedSort, minPrice, maxPrice, inStockOnly, search, selections] = JSON.parse(key);
+    searchCatalog({ limit, categoryId, sort: selectedSort, minPrice, maxPrice, inStockOnly, search, facetSelections: selections })
+      .then((res) => {
+        if (generation !== id || selectionKey() !== key) return; // superseded — drop it
+        products = res.products; total = res.total; cursor = res.nextCursor; hasMore = res.hasMore; error = null;
+        emit();
+      })
+      .catch((e) => {
+        if (generation !== id || selectionKey() !== key) return;
+        products = []; total = null; cursor = null; hasMore = false;
+        error = e instanceof Error ? e.message : "Couldn't load products.";
+        emit();
+      });
+  }
+
+  function changed(): void {
+    if (syncUrl) writeUrlState({ sort, filters, selected, 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.selected.length) selected = u.selected;
+        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) {
+      const existing = selected.find((s) => s.choiceId === choiceId);
+      if (existing) selected = selected.filter((s) => s !== existing);
+      else {
+        const facet = facets.find((f) => f.choices.some((c) => c.id === choiceId));
+        if (!facet) return; // not a choice of this scope's facets
+        selected = [...selected, { kind: facet.kind, facetId: facet.id, choiceId }];
+      }
+      changed();
+    },
+    clearFilters() { filters = {}; selected = []; changed(); },
+    retry() { attempt++; changed(); },
+    async loadMore() {
+      const key = selectionKey();
+      if (pageKey !== key || !cursor || !hasMore || 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;
+          hasMore = res.hasMore;
+        }
+      } 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-templates/storefront/project/src/wix/storefront/types.ts

@@ -0,0 +1,305 @@
+// Storefront DTOs — the serializable shapes every hook, component, and page consumes.
+// These are plain JSON: safe to pass as Astro island props or across a server/client
+// boundary. Image values are already-resolved https URLs (never wix:image://), and every
+// displayable price is a ready formatted string.
+
+export type Availability = "IN_STOCK" | "OUT_OF_STOCK" | "PARTIALLY_OUT_OF_STOCK";
+
+/** A product as a listing/grid tile needs it. */
+export interface ProductSummary {
+  id: string;
+  slug: string;
+  name: string;
+  /**
+   * 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 variant price, formatted — differs from `price` when variants are priced differently. */
+  maxPrice: string;
+  /**
+   * The cheapest variant is discounted AND variants are priced differently: the discounted
+   * maximum is unknown until the PDP loads the variants, so render "From {price}" (no maxPrice,
+   * no struck price). `maxPrice` equals `price` then.
+   */
+  fromPrice: boolean;
+  /**
+   * 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;
+  /** Names of the automatic discount rules applying to this product ("Summer sale") — render under the price; [] when none. */
+  discountNames: string[];
+  /** Price per unit of the cheapest variant as Wix formats it ("€2.50 / 100 g"); null when the product isn't sold by unit. */
+  pricePerUnit: string | null;
+  /** 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;
+  /** The product sells as a subscription (recurring plans) — the tile routes to the PDP, where the plan is picked. */
+  hasSubscriptions: boolean;
+  /** Resolved https URL of the main image ("" when the product has none). */
+  imageUrl: string;
+  /** Resolved https URL of the second gallery image ("" when there is only one). */
+  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, no subscription plans). */
+  quickAddable: boolean;
+}
+
+export interface OptionChoice {
+  choiceId: string;
+  /** Read-only identifier Wix derives from the name — what `catalogReference.options[option.key]` carries. */
+  key: string;
+  name: string;
+  /** Hex color for swatch rendering; null for text choices. */
+  colorCode: string | null;
+  /** At least one variant with this choice is in stock (catalog-level; the PDP store refines it against the current selection). */
+  inStock: boolean;
+  /** The gallery image the merchant linked to this choice (shown when it is picked), resolved to https; null when none. */
+  imageUrl: string | null;
+}
+
+export interface ProductOption {
+  /** The option's customization id — what `selectOption(optionId, choiceId)` and `ProductVariant.choiceIds` use. */
+  id: string;
+  /** Read-only identifier Wix derives from the name — the key inside `catalogReference.options`. */
+  key: string;
+  name: string;
+  /** Render choices as color swatches (true) or text pills (false). */
+  isColor: boolean;
+  choices: OptionChoice[];
+}
+
+export interface ProductModifier {
+  /** The modifier's customization id. */
+  id: string;
+  /**
+   * The key the cart takes: `catalogReference.options[key] = choice.key` for a choice modifier,
+   * `customTextFields[key] = text` for a free-text one (its `freeTextSettings.key`).
+   */
+  key: string;
+  name: string;
+  /** Input required before adding — Wix treats a modifier as mandatory unless it says otherwise. */
+  mandatory: boolean;
+  /** "choices" renders pills; "text" renders a free-text input. */
+  type: "choices" | "text";
+  /** The label of a free-text input (Wix's `freeTextSettings.title`); the modifier name for choices. */
+  title: string;
+  /** Free text only: character limits from the merchant; null when unlimited / none. */
+  maxChars: number | null;
+  minChars: number | null;
+  choices: { choiceId: string; key: string; name: string }[];
+}
+
+/** A recurring plan the product can be bought on. */
+export interface SubscriptionPlan {
+  id: string;
+  name: string;
+  description: string;
+  /** Payment frequency unit; null when Wix didn't say. */
+  frequency: "DAY" | "WEEK" | "MONTH" | "YEAR" | null;
+  /** Every N frequency units (1 = every month). */
+  interval: number;
+  /** Number of payments; null = until cancelled (auto-renewing). */
+  billingCycles: number | null;
+  /** "every 2 months · 6 payments" — the terms in words, ready to render. */
+  terms: string;
+}
+
+export interface ProductVariant {
+  variantId: string;
+  /** The option selections this variant answers to, by id: optionId -> choiceId (what resolveVariant matches on). */
+  choiceIds: Record<string, string>;
+  /** The same selections by name: optionName -> choiceName (display only). */
+  choices: Record<string, string>;
+  /** The price the buyer pays, formatted — an automatic discount beats the regular price. */
+  price: string;
+  /** The same selling price as a number in site currency — for ranges, never for display. */
+  priceAmount: number;
+  /** Struck "was" price, formatted; null unless it is real and higher than `price`. */
+  compareAtPrice: string | null;
+  /** Price per unit as Wix formats it ("€2.50 / 100 g"); null when not sold by unit. */
+  pricePerUnit: string | null;
+  /** Merchant SKU; null when none. */
+  sku: string | null;
+  /** planId -> the formatted price of this variant on that plan (Wix applies the plan's discount to the variant's price). */
+  subscriptionPrices: Record<string, string>;
+  inStock: boolean;
+  /** Out of stock but pre-orderable — still buyable (the add carries preOrderRequested). */
+  preorderEnabled: boolean;
+  /**
+   * Units left to buy: the tracked stock, or the remaining pre-order allowance when pre-ordering.
+   * null when stock isn't counted (made to order) or the inventory hasn't loaded yet.
+   */
+  quantity: number | null;
+  /** The merchant's pre-order note ("Ships in 3 weeks"); null when none or not pre-orderable. */
+  preorderMessage: string | null;
+  /**
+   * The image Wix derived for this variant from its choice's linked media, resolved to https; null when none.
+   * Wix derives it at product creation only (and only for single-option products), so a choice image the
+   * merchant added later never lands here: read the choice's own `imageUrl` (the detail store's `imageUrl` does).
+   */
+  imageUrl: string | null;
+}
+
+/** One inventory record per variant at the store's default location (fetchInventory). */
+export interface VariantInventory {
+  status: "IN_STOCK" | "OUT_OF_STOCK" | "PREORDER";
+  /** Units in stock when counted; null when stock is a yes/no flag. */
+  quantity: number | null;
+  /** Units still pre-orderable when `status` is PREORDER; null otherwise or when uncounted. */
+  preorderQuantity: number | null;
+  preorderMessage: string | null;
+}
+
+/** A category breadcrumb: an ancestor (or, on a product, the path to its main category). */
+export interface Breadcrumb {
+  id: string;
+  name: string;
+  slug: string;
+}
+
+/** 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[];
+  /** Path to the product's main category, top-level first ("Clothing" > "T-Shirts"); [] when it has no main category. */
+  breadcrumbs: Breadcrumb[];
+  /** Ids of the categories the product is directly assigned to. */
+  categoryIds: string[];
+  options: ProductOption[];
+  modifiers: ProductModifier[];
+  variants: ProductVariant[];
+  /** The recurring plans the product is sold on; [] for a one-time-only product. */
+  subscriptions: SubscriptionPlan[];
+  /** With plans present: whether a plain one-time purchase is also offered. */
+  allowOneTimePurchase: boolean;
+}
+
+export interface Category {
+  id: string;
+  slug: string;
+  name: string;
+  /** Plain-text description when the merchant wrote one; "" otherwise. */
+  description: string;
+  /** The category's own image, resolved to an https URL; "" when none. */
+  imageUrl: string;
+  /** The parent category's id; null for a top-level category. */
+  parentId: string | null;
+  /** Position among its siblings (the merchant's order). */
+  index: number;
+  /** Products directly in this category (not in its subcategories); null when unknown. */
+  productCount: number | null;
+  /** Ancestors, top-level first — only filled by fetchCategoryBySlug; [] elsewhere. */
+  breadcrumbs: Breadcrumb[];
+}
+
+export interface FacetChoice {
+  /** The choice id — what toggleChoice / searchCatalog filter on. */
+  id: string;
+  name: string;
+  /** Hex color for a swatch facet; null for a text facet. */
+  colorCode: string | null;
+  /** Products in the scope carrying this choice (linked choices counted into their primary). */
+  count: number;
+  /** Ids of linked choices shown under this one ("Light red" under "Red") — the filter sends them along; [] when none. */
+  childIds: string[];
+}
+
+/** One filterable customization across the catalog (or a category): "Color" with its choices. */
+export interface Facet {
+  /** The customization id (an option's or a modifier's). */
+  id: string;
+  name: string;
+  /** Options and modifiers filter on different fields — the store keeps them apart. */
+  kind: "option" | "modifier";
+  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;
+}
+
+/** 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 {
+  /** The cart line id — what update/remove take (NOT the product id). */
+  lineItemId: string;
+  productName: string;
+  quantity: number;
+  /** Per-unit price, formatted. */
+  unitPrice: string;
+  /** Line total, formatted. */
+  linePrice: string;
+  /** Struck line total (the catalog price × quantity) when the line is discounted; null otherwise. */
+  compareAtLinePrice: string | null;
+  /** Units the store can still sell of this line; null when uncounted. The stepper's ceiling. */
+  availableQuantity: number | null;
+  /** Resolved https URL ("" when none). */
+  imageUrl: string;
+  /** The item's page URL when Wix returned one; "" otherwise (a headless site links by slug). */
+  productUrl: string;
+  /** Human-readable option/modifier labels, e.g. ["Color: Ink", "Size: M"]. */
+  descriptionLines: string[];
+  /** IN_STOCK | PARTIALLY_IN_STOCK | OUT_OF_STOCK | REMOVED_FROM_CATALOG — 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;
+}
+
+/** A named amount from the cart estimate (a discount, a fee, a tax), formatted. */
+export interface CartAmount {
+  name: string;
+  amount: string;
+}
+
+export interface Cart {
+  lines: CartLine[];
+  /** Sum of line quantities. */
+  itemCount: number;
+  /** Formatted subtotal (after item discounts) — from the cart estimate, not hand-summed. */
+  subtotal: string;
+  /** Formatted CART-level discount total (a coupon or cart rule) — "" when none; item discounts are already in subtotal. */
+  discount: string;
+  /** Every applied discount by name (coupon, automatic rule) with its amount; [] when none. */
+  discounts: CartAmount[];
+  /** Additional fees (handling, platform) with their amounts; [] when none. */
+  fees: CartAmount[];
+  /** Taxes by name; [] when none or not yet calculable (no address). */
+  taxes: CartAmount[];
+  /** Line prices already include tax — don't render a tax row then. */
+  pricesIncludeTax: boolean;
+  /** Formatted total to pay before delivery (shipping resolves at checkout); "" when unknown. */
+  total: string;
+  /** The applied coupon; null when none. */
+  coupon: { id: string; code: string } | null;
+  /** The buyer's note to the merchant; "" when none. */
+  note: string;
+  currency: string;
+}

package/skills/wix-headless-templates/storefront/project/tsconfig.json

@@ -0,0 +1,5 @@
+{
+  "extends": "astro/tsconfigs/strict",
+  "include": [".astro/types.d.ts", "**/*"],
+  "exclude": ["dist"]
+}