@wix/agent-skills 1.26.0 → 1.27.0

package/skills/wix-headless-templates/restaurants/rest/ordering.ts

@@ -0,0 +1,222 @@
+// Online ordering over REST (Restaurants Orders + Wix eCom Cart V2) — the twin of
+// app/wix/restaurants/ordering.ts. Same exports, same OrderCart/OrderLine DTOs; rules and mappers
+// from ordering-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: the Orders app id, options
+// { operationId, menuId, sectionId } — all three — and the visitor's choices in
+// options.priceVariant / options.modifierGroups / options.specialRequests, the keys Wix's own
+// ordering sends. Failures are loud: a missing or paused operation, an invalid selection, an
+// unavailable line, an empty order at checkout all throw — surface the message.
+// All calls run with the visitor token: the cart is the token's (see ./client).
+// docs: https://dev.wix.com/docs/api-reference/business-solutions/restaurants/online-orders/operations/list-operations.md
+// docs: https://dev.wix.com/docs/api-reference/business-solutions/restaurants/online-orders/menu-ordering-settings/query-menu-ordering-settings.md
+// docs: https://dev.wix.com/docs/api-reference/business-solutions/restaurants/online-orders/fulfillment-methods/list-fulfillment-methods.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-management/headless/redirects/create-redirect-session.md
+import { WixApiError, wixRequest } from "./client.js";
+import { imgSrc } from "./media.js";
+import { fetchSiteMoney } from "./menu.js";
+import { initialSelection, nextCursor, validateSelection, type Raw } from "./menu-core.js";
+import {
+  RESTAURANTS_ORDERS_APP_ID,
+  assertOrderAdded,
+  assertOrderCheckoutable,
+  assertOrderContext,
+  assertOrderable,
+  estimateSubtotal,
+  orderCatalogItem,
+  rawId,
+  resolveOperation,
+  toFulfillmentMethods,
+  toMenuOrderingMap,
+  toOrderCart,
+} from "./ordering-core.js";
+import type { FulfillmentMethodInfo, MenuItem, MenuOrderingInfo, OrderCart, OrderSelection, OrderingStatus } from "./types.js";
+
+export { RESTAURANTS_ORDERS_APP_ID };
+
+const CART = "/ecom/v2/carts/current";
+
+// The ordering operation is site config — resolve once, reuse for every add.
+// GET /restaurants-operations/v1/operations
+let orderingPromise: Promise<OrderingStatus> | null = null;
+
+/**
+ * The operation to order through and its state (ENABLED, else the default, else the first).
+ * `status` "NONE" when the site has no online ordering; DISABLED / PAUSED_UNTIL refuse every add.
+ */
+export function resolveOrdering(): Promise<OrderingStatus> {
+  orderingPromise ??= wixRequest<Raw>("/restaurants-operations/v1/operations", { method: "GET" })
+    .then((res) => resolveOperation(res?.operations ?? []))
+    .catch(() => {
+      orderingPromise = null; // transient failure — allow a retry on the next call
+      return resolveOperation([]);
+    });
+  return orderingPromise;
+}
+
+/** The id of the operation to order through — null when the site has none. */
+export function resolveOperationId(): Promise<string | null> {
+  return resolveOrdering().then((s) => s.operationId);
+}
+
+/**
+ * Every menu's ordering settings under the operation, keyed by menuId (which menus take online
+ * orders and when). A menu absent from the map is not orderable. {} when there is no operation.
+ * POST /menu-ordering-settings/v1/menu-ordering-settings/query  { query: { filter: { operationId }, cursorPaging: { cursor? } } }
+ */
+export async function fetchMenuOrdering(): Promise<Record<string, MenuOrderingInfo>> {
+  const { operationId } = await resolveOrdering();
+  if (!operationId) return {};
+  const raws: Raw[] = [];
+  let cursor: string | null = null;
+  do {
+    const res: Raw = await wixRequest<Raw>("/menu-ordering-settings/v1/menu-ordering-settings/query", {
+      body: { query: { filter: { operationId }, ...(cursor ? { cursorPaging: { cursor } } : {}) } },
+    });
+    raws.push(...((res?.menuOrderingSettings ?? []) as Raw[]));
+    cursor = nextCursor(res);
+  } while (cursor);
+  return toMenuOrderingMap(raws);
+}
+
+/**
+ * The operation's enabled pickup/delivery methods (operation.fulfillmentIds only), fees and
+ * minimums formatted in the site currency — for display.
+ * GET /fulfillment-methods/v1/fulfillment-methods[?cursorPaging.cursor=…]
+ */
+export async function fetchFulfillmentMethods(): Promise<FulfillmentMethodInfo[]> {
+  try {
+    const [status, money] = await Promise.all([resolveOrdering(), fetchSiteMoney()]);
+    if (!status.fulfillmentIds.length) return [];
+    const raws: Raw[] = [];
+    let cursor: string | null = null;
+    do {
+      const res: Raw = await wixRequest<Raw>("/fulfillment-methods/v1/fulfillment-methods", { method: "GET", query: cursor ? { "cursorPaging.cursor": cursor } : {} });
+      raws.push(...((res?.fulfillmentMethods ?? []) as Raw[]));
+      cursor = nextCursor(res);
+    } while (cursor);
+    return toFulfillmentMethods(raws, status.fulfillmentIds, money);
+  } catch {
+    return []; // display nicety — ordering still works without the list
+  }
+}
+
+// A line's attributes.image may come back absent — join the menu items' images by the line's
+// catalogItemId, once per item, cached for the session.  GET /restaurants/menus-item/v1/items?itemIds=…
+const lineImageCache = new Map<string, string>();
+async function fillLineImages(cart: OrderCart, raws: Raw[]): Promise<void> {
+  const wanted = new Map<string, number[]>();
+  raws.forEach((raw, i) => {
+    if (cart.lines[i].imageUrl) return;
+    const itemId = raw.source?.catalogReference?.catalogItemId;
+    if (!itemId) return;
+    const cached = lineImageCache.get(itemId);
+    if (cached !== undefined) { cart.lines[i].imageUrl = cached; return; }
+    wanted.set(itemId, [...(wanted.get(itemId) ?? []), i]);
+  });
+  if (!wanted.size) return;
+  try {
+    const res = await wixRequest<Raw>("/restaurants/menus-item/v1/items", { method: "GET", query: { itemIds: [...wanted.keys()] } });
+    for (const item of (res?.items ?? []) as Raw[]) {
+      const url = imgSrc(item.image, 300, 300);
+      lineImageCache.set(rawId(item), url);
+      for (const i of wanted.get(rawId(item)) ?? []) cart.lines[i].imageUrl = url;
+    }
+  } catch {
+    /* images are a nicety — the cart stays correct without them */
+  }
+}
+
+async function readCartWithSubtotal(raw: Raw | null): Promise<OrderCart> {
+  // Only estimate a cart WITH lines — on an absent/empty cart the endpoint returns 404.
+  if (!raw?.lineItems?.length) return toOrderCart(raw, "", imgSrc);
+  // The after-discount subtotal comes from the estimate, never from hand-summing lines; fees, tax,
+  // and delivery resolve at checkout.   POST /ecom/v2/carts/current/estimate  {}
+  let subtotal = "";
+  try {
+    subtotal = estimateSubtotal(await wixRequest<Raw>(`${CART}/estimate`, { body: {} }), raw);
+  } catch {
+    /* the estimate is a display nicety — the cart itself is still valid */
+  }
+  const cart = toOrderCart(raw, subtotal, imgSrc);
+  await fillLineImages(cart, raw.lineItems as Raw[]);
+  return cart;
+}
+
+// GET /ecom/v2/carts/current — a 404 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 order cart. An empty cart (not an error) when none exists yet. */
+export async function fetchOrderCart(): Promise<OrderCart> {
+  return readCartWithSubtotal(await getCurrentCartRaw());
+}
+
+/**
+ * Add a dish to the current order. `item` is the MenuItem DTO as rendered; `menuId` and `sectionId`
+ * are the ids of the menu and section it is RENDERED UNDER (the fetchMenus tree); `selection` is
+ * what the visitor chose (start from initialSelection(item)). Throws when ordering isn't accepting,
+ * the dish can't be ordered, a modifier rule fails, or the line is refused (a refused add still returns 200).
+ * POST /ecom/v2/carts/current/add-line-items
+ *   { catalogItems: [{ quantity, catalogReference: { catalogItemId, appId: <Orders app>, options: {
+ *       operationId, menuId, sectionId, priceVariant?: { id, formattedPrice },
+ *       modifierGroups?: [{ id, modifiers: [{ id, price, formattedPrice? }] }], specialRequests? } } }] }
+ */
+export async function addToOrder(
+  item: MenuItem,
+  { menuId, sectionId }: { menuId: string; sectionId: string },
+  quantity = 1,
+  selection: OrderSelection = initialSelection(item),
+): Promise<OrderCart> {
+  const { operationId, status } = await resolveOrdering();
+  if (!operationId || status !== "ENABLED") throw new Error("Online ordering isn't available right now.");
+  assertOrderContext(item.id, menuId, sectionId);
+  assertOrderable(item);
+  const check = validateSelection(item, selection);
+  if (!check.ok) throw new Error(Object.values(check.errors)[0]);
+  const res = await wixRequest<Raw>(`${CART}/add-line-items`, {
+    body: { catalogItems: [orderCatalogItem(item, { operationId, menuId, sectionId }, quantity, selection)] },
+  });
+  assertOrderAdded(res?.cart, item.id);
+  return readCartWithSubtotal(res?.cart ?? null);
+}
+
+/**
+ * Change a line's quantity. `lineItemId` is OrderLine.lineItemId, never the menu item id.
+ * POST /ecom/v2/carts/current/update-line-items  { lineItems: [{ lineItemId, quantity: { newQuantity } }] }
+ */
+export async function updateOrderQuantity(lineItemId: string, quantity: number): Promise<OrderCart> {
+  const res = await wixRequest<Raw>(`${CART}/update-line-items`, { body: { lineItems: [{ lineItemId, quantity: { newQuantity: quantity } }] } });
+  return readCartWithSubtotal(res?.cart ?? null);
+}
+
+/** Remove a line by OrderLine.lineItemId.  POST /ecom/v2/carts/current/remove-line-items  { lineItemIds } */
+export async function removeOrderLine(lineItemId: string): Promise<OrderCart> {
+  const res = await wixRequest<Raw>(`${CART}/remove-line-items`, { body: { lineItemIds: [lineItemId] } });
+  return readCartWithSubtotal(res?.cart ?? null);
+}
+
+/**
+ * Start the Wix-hosted checkout for the current order and return the URL to navigate the FULL
+ * document to. The cart's id IS the checkout id; fulfillment (pickup/delivery + time) and payment
+ * are collected on the hosted page. `origin` must be the site's real https origin as registered on
+ * the OAuth app's allowed domains (browser: window.location.origin) — an unlisted or http origin
+ * 403s on return.
+ * POST /headless/v1/redirect-session  { ecomCheckout: { checkoutId }, callbacks: { postFlowUrl, thankYouPageUrl } }
+ */
+export async function orderCheckoutUrl(origin: string = typeof window !== "undefined" ? window.location.origin : ""): Promise<string> {
+  const raw = await getCurrentCartRaw();
+  assertOrderCheckoutable(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;
+}

package/skills/wix-headless-templates/restaurants/rest/reservations.ts

@@ -0,0 +1,102 @@
+// Table reservations over REST — the twin of app/wix/restaurants/reservations.ts. Same exports,
+// same DTOs; rules and mappers from reservations-core (the SAME file the SDK transport uses,
+// deployed flat next to this one). The flow is location → AVAILABLE slots → (AUTOMATIC approval)
+// hold → reserve, or (MANUAL approval) one create with details + reservee and no hold; a
+// reservation is a hold, not a purchase — no cart, no checkout. Every call here is a visitor's own
+// action with the visitor token. The hold, reserve, and create calls are premium-gated on the site:
+// a non-premium site answers 428 "site must be premium" — surface it, don't retry.
+// docs: https://dev.wix.com/docs/api-reference/business-solutions/restaurants/reservations/time-slots/get-time-slots.md
+// docs: https://dev.wix.com/docs/api-reference/business-solutions/restaurants/reservations/reservations/create-held-reservation.md
+// docs: https://dev.wix.com/docs/api-reference/business-solutions/restaurants/reservations/reservations/reserve-reservation.md
+// docs: https://dev.wix.com/docs/api-reference/business-solutions/restaurants/reservations/reservations/create-reservation.md
+import { wixRequest } from "./client.js";
+import { availableSlots, reservationBody, reserveeBody, toConfirmation, toHold, toLocations } from "./reservations-core.js";
+import type { Raw } from "./menu-core.js";
+import type {
+  ReservationConfirmation,
+  ReservationFormConfig,
+  ReservationHold,
+  ReservationLocationInfo,
+  ReservationReservee,
+  ReservationSlot,
+} from "./types.js";
+
+const RESERVATIONS = "/table-reservations/reservations/v1";
+
+/**
+ * The locations to offer: those with online reservations ENABLED (default first), or only the
+ * default one when none is enabled (then `onlineReservationsEnabled: false` → render an honest
+ * notice); [] when Table Reservations isn't set up. Each carries name, address, timezone, approval
+ * rule, and the owner's form configuration.
+ * GET /table-reservations/reservation-locations/v1/reservation-locations
+ */
+export async function fetchReservationLocations(): Promise<ReservationLocationInfo[]> {
+  const res = await wixRequest<Raw>("/table-reservations/reservation-locations/v1/reservation-locations", { method: "GET" });
+  return toLocations(res?.reservationLocations ?? []);
+}
+
+/**
+ * AVAILABLE slots around a moment for a party size (UNAVAILABLE / NON_WORKING_HOURS dropped);
+ * `aroundIso` is built in the location's zone (`zonedIso`), labels and day keys use `timeZone`.
+ * POST /table-reservations/reservations/v1/time-slots  { reservationLocationId, date, partySize, slotsBefore, slotsAfter }
+ */
+export async function fetchReservationSlots(
+  locationId: string,
+  aroundIso: string,
+  partySize: number,
+  { timeZone = "", slotsBefore = 6, slotsAfter = 6 }: { timeZone?: string; slotsBefore?: number; slotsAfter?: number } = {},
+): Promise<ReservationSlot[]> {
+  const res = await wixRequest<Raw>(`${RESERVATIONS}/time-slots`, {
+    body: { reservationLocationId: locationId, date: new Date(aroundIso).toISOString(), partySize, slotsBefore, slotsAfter },
+  });
+  return availableSlots(res?.timeSlots ?? [], timeZone);
+}
+
+/**
+ * Hold a slot for 10 minutes while the visitor enters their details (AUTOMATIC approval); the hold's
+ * { reservationId, revision } feed completeReservation, `expiresAtIso` a countdown.
+ * POST /table-reservations/reservations/v1/reservations/hold  { reservationDetails: { reservationLocationId, startDate, partySize } }
+ */
+export async function holdReservation(locationId: string, startIso: string, partySize: number): Promise<ReservationHold> {
+  const res = await wixRequest<Raw>(`${RESERVATIONS}/reservations/hold`, {
+    body: { reservationDetails: { reservationLocationId: locationId, startDate: new Date(startIso).toISOString(), partySize } },
+  });
+  return toHold(res, startIso, partySize);
+}
+
+/**
+ * Complete a held reservation with the visitor's details, validated against the location's `form`
+ * (firstName + phone always; lastName/email/custom fields as configured); an expired hold can't be
+ * reserved — start a fresh hold. The outcome carries the API's real status.
+ * POST /table-reservations/reservations/v1/reservations/{reservationId}/reserve
+ *   { revision, reservee: { firstName, phone, lastName?, email?, marketingConsent?, customFields? } }
+ */
+export async function completeReservation(
+  hold: Pick<ReservationHold, "reservationId" | "revision">,
+  reservee: ReservationReservee,
+  form: ReservationFormConfig,
+): Promise<ReservationConfirmation> {
+  const body = reserveeBody(reservee, form);
+  const res = await wixRequest<Raw>(`${RESERVATIONS}/reservations/${encodeURIComponent(hold.reservationId)}/reserve`, {
+    body: { revision: hold.revision, reservee: body },
+  });
+  return toConfirmation(res);
+}
+
+/**
+ * Request a reservation that needs the restaurant's approval (MANUAL, or a large party under
+ * MANUAL_FOR_LARGE_PARTIES): ONE create with details + reservee, no hold. Normally ends REQUESTED (pending).
+ * POST /table-reservations/reservations/v1/reservations
+ *   { reservation: { details: { reservationLocationId, startDate, partySize }, reservee: { … } } }
+ */
+export async function requestReservation(
+  locationId: string,
+  startIso: string,
+  partySize: number,
+  reservee: ReservationReservee,
+  form: ReservationFormConfig,
+): Promise<ReservationConfirmation> {
+  const reservation = reservationBody(locationId, new Date(startIso).toISOString(), partySize, reservee, form);
+  const res = await wixRequest<Raw>(`${RESERVATIONS}/reservations`, { body: { reservation } });
+  return toConfirmation(res);
+}

package/skills/wix-headless-templates/restaurants/seed/SEED.md

@@ -0,0 +1,118 @@
+# Restaurants — seeding
+
+Seed by **running `seed-restaurants.mjs` with a plan file** — don't hand-write the REST calls.
+The script mints its own site token via the Wix CLI (logged-in session + `wix.config.json`
+required), installs the Restaurants apps, builds each menu bottom-up (modifiers → modifier
+groups → variants → items → sections → menu, all visible), imports+attaches images, and
+configures ordering/reservations.
+
+```bash
+# from the project root (where wix.config.json lives):
+node <SKILL_ROOT>/templates/restaurants/seed/seed-restaurants.mjs plan.json
+```
+
+`plan.json` is plain data — write it from the brief. **Default to one menu with ~3 sections
+of 2–3 items each** (the seed shows the shape; the owner adds the rest in the dashboard),
+every item with an image (a menu without photos looks broken) — the default is an
+`imagePrompt` (AI-generated, ~1 Wix AI credit per image, account-billed): brand-contextual —
+subject, aesthetic/mood, palette, lighting — always ending "no text, no watermarks". At least one image in the set shows the real subject of the business — the actual product/space/service, not abstract decoration. For an asset the user actually
+supplied use `imagePath` (a file on this machine — uploaded to Wix Media) or `imageUrl`
+(their own hosted URL; verify it with `curl -sI` → 200) — never a stock-photo or guessed URL. Images resolve in parallel and never
+block the seed, a failed image leaves that item text-only — and both add-ons on for a
+restaurant that takes orders and reservations. Give at least one dish a choice (a `variants`
+size, or a `modifierGroups` entry) when the restaurant takes orders, so the dish sheet is exercised:
+
+```json
+{
+  "menus": [
+    { "name": "Dinner", "description": "Evening menu", "sections": [
+      { "name": "Antipasti", "description": "To start", "items": [
+        { "name": "Bruschetta al Pomodoro", "description": "Grilled sourdough, San Marzano tomatoes, basil.",
+          "price": 9.5, "imageUrl": "https://…" },
+        { "name": "Burrata", "description": "Creamy burrata, heirloom tomatoes, olive oil.",
+          "price": 14, "imageUrl": "https://…" }
+      ] },
+      { "name": "Mains", "items": [
+        { "name": "Tagliatelle al Ragù", "description": "Slow-braised beef ragù, parmigiano.",
+          "price": 22, "acceptSpecialRequests": true,
+          "modifierGroups": [
+            { "name": "Pasta", "required": true, "min": 1, "max": 1,
+              "modifiers": [{ "name": "Tagliatelle", "preSelected": true }, { "name": "Pappardelle" }, { "name": "Gluten-free penne", "price": 2 }] },
+            { "name": "Extras", "max": 3,
+              "modifiers": [{ "name": "Extra parmigiano", "price": 1.5 }, { "name": "Chili flakes" }] }
+          ],
+          "imageUrl": "https://…" },
+        { "name": "Branzino", "description": "Whole roasted sea bass, lemon, herbs.",
+          "price": 28, "imageUrl": "https://…" }
+      ] },
+      { "name": "Vino", "items": [
+        { "name": "Chianti Classico", "description": "Sangiovese, Tuscany.",
+          "variants": [{ "name": "Glass", "price": 11 }, { "name": "Bottle", "price": 44 }], "imageUrl": "https://…" }
+      ] },
+      { "name": "Dolci", "items": [
+        { "name": "Tiramisù", "description": "Espresso-soaked ladyfingers, mascarpone.",
+          "price": 10, "imageUrl": "https://…" }
+      ] }
+    ] }
+  ],
+  "ordering": { "address": {
+    "name": "Trattoria Lumina", "timeZone": "America/New_York",
+    "address": { "country": "US", "subdivision": "US-NY", "city": "New York", "postalCode": "10012",
+      "streetAddress": { "number": "18", "name": "Prince Street" },
+      "formattedAddress": "18 Prince Street, New York, NY 10012" } } },
+  "reservations": { "partySize": { "min": 1, "max": 10 } }
+}
+```
+
+- `price` — a number; stored as a decimal string in the **site currency** (never send one per item).
+  An item has `price` OR `variants` (each `{ name, price }` — "Glass" / "Bottle"), never both; an
+  item with neither renders as "Market price" and can't be ordered online.
+- `modifierGroups` — per item: `{ name, required?, min?, max?, modifiers: [{ name, price?, preSelected?, inStock? }] }`.
+  `required: true, min: 1, max: 1` is a single choice (radios); `max` alone is "choose up to";
+  `price` is the up-charge (0 when omitted); `preSelected` picks the default. Modifiers and groups
+  are created as their own entities and referenced by id.
+- `acceptSpecialRequests` — `true` lets the visitor leave a note on that dish (sent on the cart line).
+- `currency` — 3-letter ISO code at the top of the plan, set **only when the brief names one**: a
+  sentence about currency, or a price written with its unit ("9 dollars", "$9", "€20"). Do **not**
+  infer it from a language, a country, or an address. The seed sets the site to it before creating
+  anything, because prices are stored in the site currency at create time; a new site starts in the
+  currency of the account that created it, not the business's. The site's currency + locale are what
+  every menu price is formatted with on the live site.
+- `ordering` — installs the Orders app, which **auto-provisions** a working setup (ENABLED
+  operation, Pickup + Delivery methods, every menu orderable); the seed verifies it. The
+  `address` is **required for real ordering** — without one, ordering is "testing only" and
+  checkout breaks. If the brief names no address, pass `"ordering": true` and the result
+  carries a note to flag the owner. Completing a **paid** order additionally needs a premium
+  plan + a connected payment method (dashboard) — mention it, don't treat it as a failure.
+- `reservations` — installs Table Reservations, which auto-provisions a default reservation
+  location; `partySize` (or a full `configuration` — e.g. `reservationForm` with
+  `lastNameRequired`, `emailRequired`, `customFieldDefinitions`, or `onlineReservations.approval`)
+  is a partial PATCH. The final **enable-online-reservations toggle is premium-only**: on a free
+  site the result carries `reservations.premiumRequired: true` — expected, tell the owner, don't retry.
+- **Seeding is strictly additive — the seed never deletes or overwrites anything on the site,
+  and neither do you.** A fresh Menus install ships a sample "Dinner Menu" (about 4 sections and 21
+  items) that the live menu page lists next to the seeded menus; the result's `preexistingMenus[]`
+  names every menu the plan did not create (`{ id, name, sections, items }`) with `dashboardMenusUrl`,
+  and the closing message says so, so the owner removes it there if they want to.
+
+## Supplied content
+
+The general rules are in `templates/shared/SUPPLIED-CONTENT.md`. For a restaurant the user hands
+over the menu, often as a PDF or a photo. Each menu becomes an entry in `menus`, each heading a
+`section`, each dish an `item` with `name`, `description`, `price` (or `variants` when the menu
+lists sizes) and, when they supplied one, its photo as `imageUrl`; a "choose your side" line
+becomes a `modifierGroups` entry. The restaurant's address, hours and party sizes go into
+`ordering` and `reservations` only when the user stated them; otherwise leave those out and say so.
+
+## Escape hatch — individual functions
+`setupRestaurants` composes exported steps — `installMenusApp`, `installOrdersApp`,
+`installTableReservationsApp`, `readPreexistingMenus`, `createModifiers`, `createModifierGroups`,
+`createVariants`, `itemBody`, `createMenu`, `importImage`, `attachItemImages`,
+`setBusinessLocation`, `listOperationsWithRetry`, `enableOperation`,
+`queryMenuOrderingSettings`, `updateMenuOrderingSettings`, `listReservationLocationsWithRetry`,
+`updateReservationLocation`, `enableOnlineReservations`, plus `makeCtx()` — import them only
+for a partial re-seed.
+
+## Reference
+Unexpected shape or an uncovered operation → read the live Wix API reference; every call the script
+makes carries a `docs:` line with its reference page.

package/skills/wix-headless-templates/restaurants/seed/read-site.mjs

@@ -0,0 +1,25 @@
+// What the restaurant holds: menus, sections, items, locations.
+//   node <SKILL_ROOT>/templates/restaurants/seed/read-site.mjs [--site <siteId>] [--limit <n>]
+import { runReader } from "../../shared/seed/read-site.mjs";
+
+const MENUS_APP_ID = "b278a256-2757-4f19-9313-c05c783bec92";
+const D = "https://dev.wix.com/docs/api-reference/business-solutions/restaurants/menus";
+const DL = "https://dev.wix.com/docs/api-reference/business-management/locations";
+
+await runReader({
+  vertical: "restaurants",
+  appId: MENUS_APP_ID,
+  async read(api, { limit }) {
+    const menus = await api.call({ method: "GET", path: "/restaurants/menus/v1/menus", docs: `${D}/menus/list-menus` });
+    const sections = await api.tryCall({ method: "GET", path: "/restaurants/menus/v1/sections", docs: `${D}/sections/list-sections` });
+    const items = await api.tryCall({ method: "GET", path: "/restaurants/menus/v1/items", docs: `${D}/items/items/list-items` });
+    const locs = await api.tryCall({ method: "GET", path: "/locations/v1/locations", docs: `${DL}/list-locations` });
+    const secs = sections?.sections ?? []; const its = items?.items ?? [];
+    return {
+      menus: (menus.menus ?? []).map((m) => ({ name: m.name, visible: m.visible !== false, sections: (m.sectionIds ?? []).map((id) => secs.find((s) => s.id === id)?.name ?? id) })),
+      sectionCount: secs.length, itemCount: its.length,
+      items: its.slice(0, limit).map((i) => ({ name: i.name, price: i.priceInfo?.price ?? i.priceVariants ? "variants" : null, image: !!i.image, labels: (i.labels ?? []).length })),
+      locations: (locs?.locations ?? []).map((l) => ({ name: l.name, default: !!l.default, address: l.address?.formattedAddress ?? null })),
+    };
+  },
+});