@wix/agent-skills 1.26.0 → 1.28.0

package/skills/wix-headless-templates/restaurants/project/src/wix/money.ts

@@ -0,0 +1,24 @@
+// Money formatting for API amounts that carry no formatted string. Copy as-is.
+//
+// Catalog prices come with a ready `formattedAmount` — use that directly. But eCom Cart V2
+// amounts are ConvertedMoney `{ amount, convertedAmount }` with NO formatted string, and the
+// currency lives on the cart, not on the money object. Never hardcode "$" or assume USD.
+export interface ConvertedMoneyLike {
+  amount?: string | null;
+  convertedAmount?: string | null;
+}
+
+/** Format a ConvertedMoney in the given currency, using the visitor's locale. */
+export function formatMoney(
+  money: ConvertedMoneyLike | 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}`;
+  }
+}

package/skills/wix-headless-templates/restaurants/project/src/wix/restaurants/menu-core.ts

@@ -0,0 +1,333 @@
+// Menu rules and DTO mapping — transport-agnostic, imported by BOTH transports: ./menu.ts (the
+// SDK, managed Astro and React) and the REST twin in templates/restaurants/rest/menu.ts (fetch,
+// a static site or a port to another language). The hierarchy is Menu → Sections → Items wired by
+// ID ARRAYS: display structure and order live in menu.sectionIds / section.itemIds, never in a
+// list response's order — the tree is stitched here in id-array order and dangling ids dropped.
+// The modifier rule engine (rule type, single-select, pre-selection, validation, sold-out from a
+// required group, duplicate ids, live price) mirrors Wix's own ordering code and lives here once.
+// A raw entity carries `_id` (SDK) or `id` (REST); every mapper accepts both. Imports are
+// type-only so a strip to JS emits no imports.
+import type {
+  MenuData,
+  MenuItem,
+  MenuItemLabel,
+  MenuItemVariant,
+  MenuModifier,
+  MenuModifierGroup,
+  MenuSection,
+  ModifierRuleType,
+  OrderSelection,
+  SelectionPrice,
+  SelectionValidation,
+  SiteMoney,
+} from "./types";
+
+/** A raw Menus V1 entity as either transport returns it. */
+export type Raw = Record<string, any>;
+/** Media value + size → https URL. Injected: the SDK transport scales through @wix/sdk, REST through the URL form. */
+export type ImgSrc = (value: any, width: number, height: number) => string;
+
+/** An entity's id, or a bare id string (item.labels may be string ids or { _id } refs). */
+export const rawId = (raw: Raw | string | undefined | null): string =>
+  typeof raw === "string" ? raw : (raw?._id ?? raw?.id ?? "");
+
+/** Index raw entities by id (either spelling). */
+export const byId = (arr: Raw[]): Map<string, Raw> => new Map(arr.map((e) => [rawId(e), e]));
+
+const unique = (ids: string[]): string[] => [...new Set(ids.filter(Boolean))];
+
+/** Split an id array for `?ids=…` reads — 100 per call keeps the query string well under the limit. */
+export function chunk<T>(arr: T[], size = 100): T[][] {
+  const out: T[][] = [];
+  for (let i = 0; i < arr.length; i += size) out.push(arr.slice(i, i + size));
+  return out;
+}
+
+/** The next page's cursor of a list response (pagingMetadata.cursors.next), null on the last page. */
+export const nextCursor = (res: Raw | null | undefined): string | null => res?.pagingMetadata?.cursors?.next || null;
+
+// ---- money -------------------------------------------------------------------------------------------
+
+/**
+ * The site's currency + locale from the eCommerce settings' BUSINESS_INFO (ecommerceSettings.
+ * businessInfo.currency / .locale.language / .locale.country), the read Wix's own menus code makes.
+ * Nothing is assumed: an unreadable response yields currency "" and every price formats to "".
+ */
+export function toSiteMoney(settingsRes: Raw | null | undefined): SiteMoney {
+  const info: Raw = settingsRes?.ecommerceSettings?.businessInfo ?? {};
+  const language = info.locale?.language ?? "";
+  const country = info.locale?.country ?? "";
+  return { currency: info.currency ?? "", locale: language ? (country ? `${language}-${country}` : language) : "" };
+}
+
+/**
+ * Format a decimal amount in the site's currency and locale. Prefers a platform-formatted string
+ * when the API sent one; "" when the amount is missing or the currency is unknown — never an
+ * invented symbol, never a USD default.
+ */
+export function formatPrice(amount: string | number | null | undefined, money: SiteMoney, platformFormatted?: string | null): string {
+  if (platformFormatted) return platformFormatted;
+  if (amount == null || amount === "" || !money.currency) return "";
+  const n = Number(amount);
+  if (!Number.isFinite(n)) return "";
+  try {
+    return new Intl.NumberFormat(money.locale || undefined, { style: "currency", currency: money.currency }).format(n);
+  } catch {
+    try {
+      return new Intl.NumberFormat(undefined, { style: "currency", currency: money.currency }).format(n);
+    } catch {
+      return `${n.toFixed(2)} ${money.currency}`;
+    }
+  }
+}
+
+// ---- id collection for the second and third reads ---------------------------------------------
+
+/** The variant ids the items reference — the second read's `variantIds`. */
+export function collectVariantIds(items: Raw[]): string[] {
+  return unique(items.flatMap((i) => ((i.priceVariants?.variants ?? []) as Raw[]).map((v) => v.variantId)));
+}
+
+/** The modifier-group ids the items reference — the second read's `modifierGroupIds`. */
+export function collectGroupIds(items: Raw[]): string[] {
+  return unique(items.flatMap((i) => ((i.modifierGroups ?? []) as Raw[]).map(rawId)));
+}
+
+/** The modifier ids the groups reference — the third read's `modifierIds`. */
+export function collectModifierIds(groups: Raw[]): string[] {
+  return unique(groups.flatMap((g) => ((g.modifiers ?? []) as Raw[]).map(rawId)));
+}
+
+/** Whether any item carries a label — the labels list is read only then. */
+export function anyLabels(items: Raw[]): boolean {
+  return items.some((i) => ((i.labels ?? []) as Raw[]).length > 0);
+}
+
+// ---- modifier rule engine (mirrors Wix's ordering utils) ----------------------------------------
+
+/** required && min 1 && max 1 — the one rule rendered as radios; a new pick replaces the old. */
+export const isSingleSelectRule = (rule: { required: boolean; minSelections: number; maxSelections: number | null }): boolean =>
+  rule.required && rule.minSelections === 1 && rule.maxSelections === 1;
+
+/** The rule's shape, in Wix's precedence (NO_LIMIT → CHOOSE_ONE → CHOOSE_X → AT_LEAST_ONE → AT_LEAST_X → UP_TO_X → BETWEEN). */
+export function ruleType(rule: { required: boolean; minSelections: number; maxSelections: number | null }): ModifierRuleType {
+  const { required, minSelections: min, maxSelections: max } = rule;
+  if (!required && min < 1 && (max ? max < 1 : true)) return "NO_LIMIT";
+  if ((required && min === 1 && max === 1) || (!required && min === 0 && max === 1)) return "CHOOSE_ONE";
+  if (required && max && min === max) return "CHOOSE_X";
+  if (required && min === 1 && max == null) return "CHOOSE_AT_LEAST_ONE";
+  if (required && min > 1 && max == null) return "CHOOSE_AT_LEAST_X";
+  if (!required && min === 0 && max && max > 1) return "CHOOSE_UP_TO_X";
+  if (required && max && min > 0 && max > min) return "CHOOSE_BETWEEN_X_AND_Y";
+  return "NO_LIMIT";
+}
+
+/** Human wording of a group's rule for the sheet ("Choose 1", "Choose up to 3", …). */
+export function ruleLabel(group: MenuModifierGroup): string {
+  const { minSelections: min, maxSelections: max } = group;
+  switch (group.rule) {
+    case "CHOOSE_ONE": return group.required ? "Choose 1" : "Choose up to 1";
+    case "CHOOSE_X": return `Choose ${min}`;
+    case "CHOOSE_AT_LEAST_ONE": return "Choose at least 1";
+    case "CHOOSE_AT_LEAST_X": return `Choose at least ${min}`;
+    case "CHOOSE_UP_TO_X": return `Choose up to ${max}`;
+    case "CHOOSE_BETWEEN_X_AND_Y": return `Choose ${min} to ${max}`;
+    default: return "Optional";
+  }
+}
+
+/** A required group whose in-stock modifiers can't reach minSelections makes the whole item unorderable. */
+export function requiredGroupOutOfStock(groups: MenuModifierGroup[]): boolean {
+  return groups.some((g) => g.required && g.modifiers.filter((m) => m.inStock).length < Math.max(g.minSelections, 0));
+}
+
+/** The cheapest variant — the default the sheet opens on; null for a flat-priced item. */
+export function defaultVariantId(item: Pick<MenuItem, "variants">): string | null {
+  if (!item.variants.length) return null;
+  return item.variants.reduce((cheapest, v) => (Number(v.priceAmount) < Number(cheapest.priceAmount) ? v : cheapest)).variantId;
+}
+
+/** The selection a sheet opens with: preSelected && inStock modifiers (single-select takes the first), the cheapest variant, no note. */
+export function initialSelection(item: Pick<MenuItem, "variants" | "modifierGroups">): OrderSelection {
+  const modifiers: Record<string, string[]> = {};
+  for (const g of item.modifierGroups) {
+    const pre = g.modifiers.filter((m) => m.preSelected && m.inStock).map((m) => m.key);
+    modifiers[g.id] = g.singleSelect ? pre.slice(0, 1) : pre;
+  }
+  return { variantId: defaultVariantId(item), modifiers, specialRequest: "" };
+}
+
+/** A new selection with `key` toggled in `groupId` — single-select replaces, multi-select toggles. Pure. */
+export function toggleModifier(item: Pick<MenuItem, "modifierGroups">, selection: OrderSelection, groupId: string, key: string): OrderSelection {
+  const group = item.modifierGroups.find((g) => g.id === groupId);
+  const current = selection.modifiers[groupId] ?? [];
+  const next = group?.singleSelect ? [key] : current.includes(key) ? current.filter((k) => k !== key) : [...current, key];
+  return { ...selection, modifiers: { ...selection.modifiers, [groupId]: next } };
+}
+
+/** Wix's checks per group: required → at least one; count >= min; count <= max when a max is set. */
+export function validateSelection(item: Pick<MenuItem, "modifierGroups">, selection: OrderSelection): SelectionValidation {
+  const errors: Record<string, string> = {};
+  for (const g of item.modifierGroups) {
+    const count = (selection.modifiers[g.id] ?? []).length;
+    if (g.required && count === 0) errors[g.id] = g.minSelections > 1 ? `Choose at least ${g.minSelections}` : "Choose one";
+    else if (count < g.minSelections) errors[g.id] = `Choose at least ${g.minSelections}`;
+    else if (g.maxSelections && count > g.maxSelections) errors[g.id] = `Choose up to ${g.maxSelections}`;
+  }
+  return { ok: Object.keys(errors).length === 0, errors };
+}
+
+/** The modifiers a selection names, resolved by KEY within their group (duplicate ids stay distinct). */
+export function selectedModifiers(item: Pick<MenuItem, "modifierGroups">, selection: OrderSelection): { group: MenuModifierGroup; modifiers: MenuModifier[] }[] {
+  return item.modifierGroups
+    .map((group) => {
+      const keys = selection.modifiers[group.id] ?? [];
+      return { group, modifiers: keys.map((k) => group.modifiers.find((m) => m.key === k)).filter((m): m is MenuModifier => !!m) };
+    })
+    .filter((g) => g.modifiers.length > 0);
+}
+
+/** (base + variant + modifier charges) × quantity, formatted in the menu's money. */
+export function itemPrice(item: Pick<MenuItem, "priceAmount" | "variants" | "modifierGroups">, selection: OrderSelection, quantity: number, money: SiteMoney): SelectionPrice {
+  const base = Number(item.priceAmount ?? 0) || 0;
+  const variant = Number(item.variants.find((v) => v.variantId === selection.variantId)?.priceAmount ?? 0) || 0;
+  const modifiers = selectedModifiers(item, selection).reduce((sum, g) => sum + g.modifiers.reduce((s, m) => s + (Number(m.additionalChargeAmount) || 0), 0), 0);
+  const amount = (base + variant + modifiers) * Math.max(quantity, 0);
+  return { amount, formatted: formatPrice(amount, money) };
+}
+
+/** True when the dish needs a sheet before adding (a variant, a modifier group, or a note to collect). */
+export const needsSelection = (item: Pick<MenuItem, "variants" | "modifierGroups" | "acceptsSpecialRequests">): boolean =>
+  item.variants.length > 0 || item.modifierGroups.length > 0 || item.acceptsSpecialRequests;
+
+// ---- DTO mapping -----------------------------------------------------------------------------------------
+
+export interface MenuLookups {
+  variantById: Map<string, Raw>;
+  groupById: Map<string, Raw>;
+  modifierById: Map<string, Raw>;
+  labelById: Map<string, Raw>;
+}
+
+export function toModifierGroup(g: Raw, lookups: MenuLookups, money: SiteMoney): MenuModifierGroup {
+  const rule = {
+    required: g.rule?.required === true,
+    minSelections: g.rule?.minSelections ?? 0,
+    maxSelections: g.rule?.maxSelections ?? null,
+  };
+  return {
+    id: rawId(g),
+    name: g.name ?? "",
+    ...rule,
+    rule: ruleType(rule),
+    singleSelect: isSingleSelectRule(rule),
+    // The group-level ref carries preSelected + the up-charge; the modifier entity carries name + inStock.
+    modifiers: ((g.modifiers ?? []) as Raw[]).map((m, index): MenuModifier => {
+      const id = rawId(m);
+      const entity = lookups.modifierById.get(id);
+      const charge = m.additionalChargeInfo?.additionalCharge ?? "0";
+      return {
+        id,
+        key: `${id}~${index}`,
+        name: entity?.name ?? "",
+        preSelected: m.preSelected === true,
+        additionalCharge: Number(charge) > 0 ? formatPrice(charge, money, m.additionalChargeInfo?.formattedAdditionalCharge) : "",
+        additionalChargeAmount: String(charge),
+        inStock: entity?.inStock !== false,
+      };
+    }),
+  };
+}
+
+export function toItem(raw: Raw, lookups: MenuLookups, imgSrc: ImgSrc, money: SiteMoney): MenuItem {
+  const variants: MenuItemVariant[] = ((raw.priceVariants?.variants ?? []) as Raw[])
+    .map((v): MenuItemVariant => ({
+      variantId: v.variantId ?? "",
+      name: lookups.variantById.get(v.variantId)?.name ?? "",
+      price: formatPrice(v.priceInfo?.price, money, v.priceInfo?.formattedPrice),
+      priceAmount: v.priceInfo?.price ?? "0",
+    }))
+    .filter((v) => v.variantId);
+  const modifierGroups: MenuModifierGroup[] = ((raw.modifierGroups ?? []) as Raw[])
+    .map((ref) => lookups.groupById.get(rawId(ref)))
+    .filter((g): g is Raw => !!g)
+    .map((g) => toModifierGroup(g, lookups, money));
+  const labels: MenuItemLabel[] = ((raw.labels ?? []) as (Raw | string)[])
+    .map((ref) => lookups.labelById.get(rawId(ref)))
+    .filter((l): l is Raw => !!l)
+    .map((l): MenuItemLabel => ({ id: rawId(l), name: l.name ?? "", iconUrl: imgSrc(l.icon, 48, 48) }));
+  const priceAmount: string | null = raw.priceInfo?.price ?? null;
+  const price = priceAmount === null ? null : formatPrice(priceAmount, money, raw.priceInfo?.formattedPrice);
+  const marketPrice = priceAmount === null && variants.length === 0;
+  const inStock = raw.orderSettings?.inStock !== false;
+  const soldOut = !inStock || requiredGroupOutOfStock(modifierGroups);
+  const imageUrl = imgSrc(raw.image, 800, 800);
+  return {
+    id: rawId(raw),
+    name: raw.name ?? "",
+    description: raw.description ?? "",
+    price,
+    priceAmount,
+    marketPrice,
+    variants,
+    imageUrl,
+    gallery: [imageUrl, ...((raw.additionalImages ?? []) as any[]).map((m) => imgSrc(m, 800, 800))].filter(Boolean),
+    labels,
+    modifierGroups,
+    inStock,
+    soldOut,
+    orderable: !marketPrice && !soldOut,
+    acceptsSpecialRequests: raw.orderSettings?.acceptSpecialRequests === true,
+    featured: raw.featured === true,
+  };
+}
+
+export function toSection(raw: Raw, itemById: Map<string, MenuItem>, imgSrc: ImgSrc): MenuSection {
+  return {
+    id: rawId(raw),
+    name: raw.name ?? "",
+    description: raw.description ?? "",
+    imageUrl: imgSrc(raw.image, 800, 800),
+    items: ((raw.itemIds ?? []) as string[]).map((iid) => itemById.get(iid)).filter((i): i is MenuItem => !!i),
+  };
+}
+
+export function toMenu(raw: Raw, sectionById: Map<string, Raw>, itemById: Map<string, MenuItem>, imgSrc: ImgSrc, money: SiteMoney): MenuData {
+  return {
+    id: rawId(raw),
+    name: raw.name ?? "",
+    description: raw.description ?? "",
+    slug: raw.urlQueryParam ?? "",
+    sections: ((raw.sectionIds ?? []) as string[])
+      .map((sid) => sectionById.get(sid))
+      .filter((s): s is Raw => !!s)
+      .map((s) => toSection(s, itemById, imgSrc)),
+    money,
+  };
+}
+
+/** The seven list responses' entity arrays, as either transport returns them, plus the site money. */
+export interface MenuTreeParts {
+  menus: Raw[];
+  sections: Raw[];
+  items: Raw[];
+  variants: Raw[];
+  groups: Raw[];
+  modifiers: Raw[];
+  labels: Raw[];
+  money: SiteMoney;
+}
+
+/** The display-ordered tree: visible menus → their sections → their items, each item enriched. [] when no menus. */
+export function assembleMenus(parts: MenuTreeParts, imgSrc: ImgSrc): MenuData[] {
+  if (!parts.menus.length) return [];
+  const lookups: MenuLookups = {
+    variantById: byId(parts.variants),
+    groupById: byId(parts.groups),
+    modifierById: byId(parts.modifiers),
+    labelById: byId(parts.labels),
+  };
+  const sectionById = byId(parts.sections);
+  const itemById = new Map<string, MenuItem>(parts.items.map((i) => [rawId(i), toItem(i, lookups, imgSrc, parts.money)]));
+  return parts.menus.map((m) => toMenu(m, sectionById, itemById, imgSrc, parts.money));
+}

package/skills/wix-headless-templates/restaurants/project/src/wix/restaurants/menu-store.ts

@@ -0,0 +1,89 @@
+// Menu browsing as a framework-free store — the logic behind useMenus, usable from React (useMenus
+// wraps it with useSyncExternalStore), from a static page or Vue/Svelte (subscribe and render), or
+// as the specification for a port. Same shape as order-store.ts: state, actions, subscribe/getState,
+// emit after every change. The whole tree is fetched once; menu switching is local.
+//
+// SSR-friendly: seed with `initialMenus` (Astro frontmatter) and no fetch happens; a SPA passes
+// nothing and `start()` fetches. One store per mounted menu surface: createMenuStore(), not a
+// singleton (the order cart is the singleton — one per visitor).
+import { fetchMenus } from "./menu";
+import type { MenuData } from "./types";
+
+export interface MenuStoreOptions {
+  initialMenus?: MenuData[];
+}
+
+/** Everything a menu surface renders from. Read it with getState() or through a subscription. */
+export interface MenuState {
+  /** null while the first load is in flight — render skeletons, not an empty state. */
+  menus: MenuData[] | null;
+  /** Defaults to the first menu once loaded. */
+  activeMenuId: string | null;
+  /** The menu to render (its sections/items are display-ordered). */
+  activeMenu: MenuData | null;
+  error: string | null;
+}
+
+export interface MenuStore {
+  getState(): MenuState;
+  subscribe(listener: () => void): () => void;
+  /** Fetch the tree when no `initialMenus` were given. Call once when mounted. */
+  start(): void;
+  /** Stop reacting; drop a late response. */
+  stop(): void;
+  setActiveMenuId(id: string): void;
+}
+
+export function createMenuStore({ initialMenus }: MenuStoreOptions = {}): MenuStore {
+  let menus: MenuData[] | null = initialMenus ?? null;
+  let selectedId: string | null = initialMenus?.[0]?.id ?? null;
+  let error: string | null = null;
+  let started = false;
+  const listeners = new Set<() => void>();
+  let snapshot: MenuState | null = null;
+  const emit = () => {
+    snapshot = null;
+    for (const fn of listeners) fn();
+  };
+
+  function getState(): MenuState {
+    if (snapshot) return snapshot;
+    const activeMenu = menus ? (menus.find((m) => m.id === selectedId) ?? menus[0] ?? null) : null;
+    snapshot = { menus, activeMenuId: activeMenu?.id ?? null, activeMenu, error };
+    return snapshot;
+  }
+
+  return {
+    getState,
+    subscribe(fn) {
+      listeners.add(fn);
+      return () => listeners.delete(fn);
+    },
+    start() {
+      if (started) return;
+      started = true;
+      if (initialMenus) return;
+      fetchMenus()
+        .then((m) => {
+          if (!started) return;
+          menus = m;
+          selectedId ??= m[0]?.id ?? null;
+          emit();
+        })
+        .catch((e) => {
+          if (!started) return;
+          menus = [];
+          error = e instanceof Error ? e.message : String(e);
+          emit();
+        });
+    },
+    stop() {
+      started = false;
+    },
+    setActiveMenuId(id) {
+      if (id === selectedId) return;
+      selectedId = id;
+      emit();
+    },
+  };
+}

package/skills/wix-headless-templates/restaurants/project/src/wix/restaurants/menu.ts

@@ -0,0 +1,109 @@
+// Menu reads (Wix Restaurants Menus V1) over the SDK — the only file that touches raw menu
+// entities on this transport. Everything it returns is a plain DTO from ./types. The rules and
+// the tree assembly live in ./menu-core (shared with the REST twin in templates/restaurants/rest/);
+// this file is the transport only. Copy as-is; extend by adding functions, not by editing these.
+// docs: https://dev.wix.com/docs/api-reference/business-solutions/restaurants/menus/menus/list-menus.md
+// docs: https://dev.wix.com/docs/api-reference/business-solutions/restaurants/menus/sections/list-sections.md
+// docs: https://dev.wix.com/docs/api-reference/business-solutions/restaurants/menus/items/items/list-items.md
+// docs: https://dev.wix.com/docs/api-reference/business-solutions/restaurants/menus/items/item-variants/list-variants.md
+// docs: https://dev.wix.com/docs/api-reference/business-solutions/restaurants/menus/items/item-modifier-groups/list-modifier-groups.md
+// docs: https://dev.wix.com/docs/api-reference/business-solutions/restaurants/menus/items/item-modifiers/list-modifiers.md
+// docs: https://dev.wix.com/docs/api-reference/business-solutions/restaurants/menus/items/item-labels/list-labels.md
+// docs: https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/purchase-flow/ecommerce-settings/get-ecommerce-settings.md
+import {
+  menus as menusModule,
+  sections as sectionsModule,
+  items as itemsModule,
+  itemVariants,
+  itemModifierGroups,
+  itemModifiers,
+  itemLabels,
+} from "@wix/restaurants";
+import { ecommerceSettings } from "@wix/ecom";
+import { wixModule } from "../sdk";
+import { imgSrc } from "../media";
+import {
+  anyLabels,
+  assembleMenus,
+  chunk,
+  collectGroupIds,
+  collectModifierIds,
+  collectVariantIds,
+  nextCursor,
+  toSiteMoney,
+  type Raw,
+} from "./menu-core";
+import type { MenuData, SiteMoney } from "./types";
+
+const menusApi = wixModule(menusModule);
+const sectionsApi = wixModule(sectionsModule);
+const itemsApi = wixModule(itemsModule);
+const variantsApi = wixModule(itemVariants);
+const groupsApi = wixModule(itemModifierGroups);
+const modifiersApi = wixModule(itemModifiers);
+const labelsApi = wixModule(itemLabels);
+const settingsApi = wixModule(ecommerceSettings);
+
+// The site's currency + locale are site config — read once per process, reused by every price.
+let moneyPromise: Promise<SiteMoney> | null = null;
+
+/**
+ * The site's currency and locale from the eCommerce settings (BUSINESS_INFO) — the read Wix's own
+ * menus code makes before formatting a price. { currency: "" } when the read fails: prices then
+ * format to "" rather than to a guessed symbol.
+ */
+export function fetchSiteMoney(): Promise<SiteMoney> {
+  moneyPromise ??= settingsApi
+    .getEcommerceSettings(["BUSINESS_INFO"])
+    .then((res: Raw) => toSiteMoney(res))
+    .catch(() => {
+      moneyPromise = null; // transient failure — allow a retry on the next call
+      return { currency: "", locale: "" };
+    });
+  return moneyPromise;
+}
+
+/** Every page of a cursor-paged list (pagingMetadata.cursors.next), the entities concatenated. */
+async function allPages(call: (cursor: string | null) => Promise<Raw>, key: string): Promise<Raw[]> {
+  const out: Raw[] = [];
+  let cursor: string | null = null;
+  do {
+    const res: Raw = await call(cursor);
+    out.push(...((res?.[key] ?? []) as Raw[]));
+    cursor = nextCursor(res);
+  } while (cursor);
+  return out;
+}
+
+/** An id-array read in chunks of 100 ids per call, the entities concatenated. */
+async function byIds(ids: string[], call: (ids: string[]) => Promise<Raw>, key: string): Promise<Raw[]> {
+  const pages = await Promise.all(chunk(ids).map((part) => call(part)));
+  return pages.flatMap((res) => (res?.[key] ?? []) as Raw[]);
+}
+
+/**
+ * The site's full menu tree, assembled and display-ordered: visible menus → their sections →
+ * their items, each item enriched with resolved price variants, modifier groups, and labels, every
+ * price formatted in the site's currency. The one entry point for every menu surface. [] when no
+ * menus exist (honest empty state). The three visible lists are read to the last page; the
+ * referenced variants, groups, and modifiers by id (100 per call).
+ */
+export async function fetchMenus(): Promise<MenuData[]> {
+  const [menus, sections, items, money] = await Promise.all([
+    allPages((cursor) => menusApi.listMenus({ onlyVisible: true, ...(cursor ? { paging: { cursor } } : {}) }), "menus"),
+    allPages((cursor) => sectionsApi.listSections({ onlyVisible: true, ...(cursor ? { paging: { cursor } } : {}) }), "sections"),
+    allPages((cursor) => itemsApi.listItems({ onlyVisible: true, ...(cursor ? { paging: { cursor } } : {}) }), "items"),
+    fetchSiteMoney(),
+  ]);
+  if (!menus.length) return [];
+  const variantIds = collectVariantIds(items);
+  const groupIds = collectGroupIds(items);
+  const [variants, groups, labels] = await Promise.all([
+    byIds(variantIds, (ids) => variantsApi.listVariants({ variantIds: ids }), "variants"),
+    byIds(groupIds, (ids) => groupsApi.listModifierGroups({ modifierGroupIds: ids }), "modifierGroups"),
+    // List Labels has no paging: one call returns them all.
+    anyLabels(items) ? labelsApi.listLabels().then((res: Raw) => (res?.labels ?? []) as Raw[]) : Promise.resolve([] as Raw[]),
+  ]);
+  const modifiers = await byIds(collectModifierIds(groups), (ids) => modifiersApi.listModifiers({ modifierIds: ids }), "modifiers");
+  return assembleMenus({ menus, sections, items, variants, groups, modifiers, labels, money }, imgSrc);
+}