@wix/agent-skills 1.14.0 → 1.15.0

package/skills/wix-vibe-headless/references/restaurants/INSTRUCTIONS.md

@@ -0,0 +1,138 @@
+
+# Wix Restaurants Skill
+
+> **Source files (in this skill):** the shared transport `references/shared/wix-client.js` and the helper file(s) you need from `references/restaurants/`. All helpers import from `"./wix-client.js"`, so copy them into the same folder (e.g. `src/rest/`).
+>
+> | Need | Copy |
+> |---|---|
+> | Menu display (always) | `wix-restaurants-menu.js` |
+> | Online ordering (cart + checkout) | `wix-restaurants-ordering.js` |
+> | Table reservations | `wix-restaurants-reservations.js` |
+
+Builds a real, client-only Wix restaurant experience. The browser talks to Wix directly over a
+public `WIX_CLIENT_ID`. Never mock the menu; never hand-build `/checkout` or reservation URLs —
+always go through the official cart + redirect-session and the reservations hold/reserve flow.
+
+## When to use
+- User wants a Wix restaurant site, an online food-ordering page, or a table-reservation page.
+- User asks to "connect Wix Restaurants" or replace placeholder menu/ordering/booking UI with live data.
+- Adding a menu, cart + checkout, or reservations over an existing Wix Restaurants setup.
+
+## Prerequisites
+1. A Wix site with the **Wix Restaurants Menus** app installed and **menu content already added**
+   (this skill is read-only over the menu — it does NOT create menus/items).
+2. For **online ordering**: at least one online-ordering **Operation** configured (Wix Restaurants
+   Orders). For **reservations**: the **Table Reservations** app installed with at least one location
+   and online reservations enabled. If a flow's backing app/config isn't set up, that flow returns
+   empty — flag it and continue; don't fabricate data.
+3. The site's public headless **`WIX_CLIENT_ID`**, provided in the handoff prompt (see the router `SKILL.md`).
+   Paste it into `src/rest/wix-client.js` in place of the placeholder. It is a buyer-facing
+   credential (it only mints anonymous visitor tokens), **not** a secret — hardcoding/committing
+   it is fine.
+4. The deployed app domain must be allow-listed on the OAuth client for Wix-hosted checkout to
+   return. This is a **separate Wix setup flow the user completes later** — out of this skill's
+   scope. If checkout return fails before that setup is done, that's expected; flag it and continue.
+
+## The API (copy as-is; do not re-derive it)
+This skill ships only the REST layer — no UI components. Build the restaurant UI however the
+project wants; wire it to these two snippets. Copy them into the app (e.g. `src/api/`) and only
+adjust import paths:
+- `src/rest/wix-client.js` — visitor-token mint/refresh + transport. Set `WIX_CLIENT_ID` to the id
+  from the prompt (replace the `<YOUR-CLIENT-ID>` placeholder). The visitor refresh token IS the
+  cart identity; it is persisted to localStorage. Do not re-mint anonymously per load or the cart
+  silently empties.
+- `src/rest/wix-restaurants-menu.js` — **Menu (read-only):**
+  `getFullMenu` (the assembled tree — start here), `listMenus`, `listSections`, `listItems`,
+  `listVariants`, `listModifierGroups`, `listModifiers`, `listLabels`
+- `src/rest/wix-restaurants-ordering.js` — **Online ordering:**
+  `listOperations`, `getDefaultOperation`, `addItemToCart`, `getCurrentCart`,
+  `updateCartItemQuantity`, `removeFromCart`, `checkout`
+- `src/rest/wix-restaurants-reservations.js` — **Reservations:**
+  `listReservationLocations`, `getTimeSlots`, `createHeldReservation`, `reserveReservation`
+
+The Menu, Item, ModifierGroup, Operation, Cart, ReservationLocation, TimeSlot, and Reservation
+shapes are documented as JSDoc at the top of each helper file. Read the relevant file(s) before
+building the UI — they describe the key fields and link to the full reference for anything not shown.
+
+## How to wire it (UI is the project's choice)
+- **Menu page** — call `getFullMenu()` once. It returns `{ menus: [{ ...menu, sections: [{ ...section,
+  items: [assembledItem] }] }] }`, already ordered by `sectionIds` / `itemIds`. Render each item's
+  `name`, `description`, `image`, `labels` (`name` + `icon`), and `featured` flag. For price, show
+  `item.price` (single) or the `item.variants[]` (each `{ name, price }`). **Restaurants prices are
+  plain decimal strings with NO currency symbol** — format with the site's currency in the UI.
+- **Item detail** — render `item.modifierGroups[]`: each group's `name`, its `rule`
+  (`required`, `minSelections`, `maxSelections`), and `modifiers[]` (`name`, `additionalCharge`,
+  `preSelected`, `inStock`). If `orderSettings.acceptSpecialRequests`, offer a free-text field.
+- **Online ordering** — resolve an operation with `getDefaultOperation()` (or let the user pick from
+  `listOperations()`); if it's `null`, show an "ordering unavailable" state. Add a dish with
+  `addItemToCart(item.id, { operationId, menuId, sectionId, quantity })` — `menuId`/`sectionId` are
+  the menu and section the item was shown under. Read the cart back with `getCurrentCart()`; mutate
+  with `updateCartItemQuantity(lineItemId, qty)` / `removeFromCart(lineItemId)` using
+  `cart.lineItems[].id` (not the item id).
+- **Checkout** — `window.location.href = await checkout()`. After the visitor returns, the order is
+  placed and the cart is empty — re-fetch with `getCurrentCart()` on return (e.g. on mount +
+  `visibilitychange`) to clear the UI.
+- **Reservations** — `listReservationLocations()` for the picker (use `location` details for the
+  label; if a location's `configuration.onlineReservations.onlineReservationsEnabled` is false, hide
+  it). Then `getTimeSlots(locationId, dateISO, partySize)` — render `availableTimeSlots` (already
+  filtered to `AVAILABLE`). On slot pick, `createHeldReservation(locationId, slot.startDate,
+  partySize)` → keep the returned `id` + `revision`. Collect the visitor's details, then
+  `reserveReservation(id, revision, { firstName, phone, lastName?, email? })`. A `RESERVED` status is
+  confirmed; `REQUESTED` means the location requires manual approval — tell the user it's pending.
+- **Empty state** — if `getFullMenu()` returns no menus, show an empty state telling the user to add
+  a menu in their Wix dashboard. Never invent menu items.
+
+## Hard rules (do not violate)
+- ✅ Order ONLY through the cart: `addItemToCart()` → `checkout()` (`create-checkout` →
+  `/headless/v1/redirect-session` `fullUrl`), then redirect.
+- ❌ Never hand-build `/checkout`, ordering, or reservation URLs.
+- ❌ Never mock menus, items, prices, operations, locations, or time slots — render live Wix data or
+  the empty state.
+- ❌ Never generate fake reviews, ratings, or testimonials. Empty review UI only.
+- ✅ Set `WIX_CLIENT_ID` from the prompt's value (public client id — safe to hardcode).
+- ✅ `addItemToCart` requires `operationId`, `menuId`, and `sectionId` — it throws if any is missing.
+- ✅ `lineItemId` for cart mutations is `cart.lineItems[].id`, not the item id.
+- ✅ Reservations: offer only `AVAILABLE` slots; a HELD reservation expires in 10 minutes — pass the
+  `revision` from the hold into `reserveReservation`, and restart the flow if it expired.
+- ✅ Reservee `firstName` + `phone` (E.164, e.g. `+15551234567`) are mandatory to confirm.
+- The engine fails loudly on purpose: `addItemToCart`/`checkout` throw on out-of-stock or empty
+  carts; reservation helpers throw on unavailable slots or expired holds. A green path means it is
+  really orderable/bookable — don't swallow these.
+
+## Beyond the snippets
+The snippets cover the common menu / ordering / reservation paths. For the "20%" they don't cover,
+make the call yourself with `wixApiRequest` — but look up the exact endpoint, HTTP method, and
+request body in the **official Wix API reference** first; never guess:
+- Restaurants API reference: https://dev.wix.com/docs/api-reference/business-solutions/restaurants.md
+- Selecting a specific **price variant** or applying **modifier up-charges** on the cart line: the
+  restaurants `catalogReference.options` shape for these is not documented for client add-to-cart.
+  The menu UI still displays them; confirm the shape before wiring them into `addItemToCart`:
+  https://dev.wix.com/docs/api-reference/business-solutions/restaurants/online-orders/sample-flows.md
+- Fulfillment methods, delivery-address validation, scheduled (preorder) time slots, service fees:
+  see the Online Orders section of the reference.
+- **Member login + a "my orders" account view** → the **members** vertical
+  (`references/members/INSTRUCTIONS.md`): ordering/reserving works anonymously, but signing a member
+  in (custom login on your own UI) lets them see their own order/reservation history.
+
+Keep the snippets as the default for everything they already do; reach for the API reference only
+for the gap.
+
+## Point the user to their dashboard
+In some cases, users need to access the Wix dashboard in order to edit the restaurant content for their site — across up to three apps. To facilitate this, provide the user with deep links directly to the relevant dashboard pages; only mention the apps the project actually uses. Those pages are:
+- **Menu** (always) — `https://manage.wix.com/dashboard/{metaSiteId}/wix-restaurants-menus-new` (`Dashboard → Restaurant Menus`; click **Manage Items** to add dishes; only visible menus appear in the app)
+- **Online ordering** (if wired) — `https://manage.wix.com/dashboard/{metaSiteId}/wix-restaurants-orders-new/settings` (`Dashboard → Restaurant Orders → Settings`). Enable at least one fulfillment method before the site accepts orders — each has its own page: pickup `https://manage.wix.com/dashboard/{metaSiteId}/wix-restaurants-orders-new/settings/pickup`, delivery `.../wix-restaurants-orders-new/settings/delivery`, dine-in `.../wix-restaurants-orders-new/settings/dine-in`.
+- **Table reservations** (if wired) — `https://manage.wix.com/dashboard/{metaSiteId}/wix-table-reservations/table-reservations` (`Dashboard → Table Reservations` → **Settings**; configure tables, availability, and enable online reservations)
+
+Substitute the site's `metaSiteId` to complete the links (you have it from the handoff / `ListWixSites`). Include the in-dashboard navigation as a fallback.
+
+## Verification checklist (before declaring done)
+- [ ] `WIX_CLIENT_ID` set to the prompt's value (not the `<YOUR-CLIENT-ID>` placeholder)
+- [ ] Visitor token persists across reload (cart survives reload, same visitor)
+- [ ] `getFullMenu()` renders real sections/items with prices, variants, modifiers, and labels
+- [ ] Empty state shown when there are no menus (never invented items)
+- [ ] Add to cart works with a real `operationId`/`menuId`/`sectionId`; out-of-stock items throw
+- [ ] Quantity update / remove reflect in `getCurrentCart()`
+- [ ] Checkout redirects via redirect-session `fullUrl` (no hand-built URL); cart re-fetched on return
+- [ ] Reservations: only `AVAILABLE` slots offered; hold → reserve produces `RESERVED`/`REQUESTED`
+- [ ] No mock data anywhere
+- [ ] Told the user at least once that they can continue setting up their restaurant (menu / ordering / reservations) in the dashboard and provided deep links.

package/skills/wix-vibe-headless/references/restaurants/wix-restaurants-menu.js

@@ -0,0 +1,224 @@
+import { wixApiRequest } from "./wix-client.js";
+
+// Data model reference: see INSTRUCTIONS.md
+
+/**
+ * Menu — top of the hierarchy. One per published menu (e.g. Dinner, Drinks).
+ *   id {string}, name {string}, description {string}, visible {boolean},
+ *   sectionIds {string[]} — ordered Section GUIDs,
+ *   urlQueryParam {string} — URL slug fragment, businessLocationId {string}
+ * Full model: https://dev.wix.com/docs/api-reference/business-solutions/restaurants/menus/menus/menu-object.md
+ *
+ * Section — a group of items within a menu (e.g. Appetizers, Mains).
+ *   id {string}, name {string}, description {string},
+ *   image {object} — { id, url, width, height, altText },
+ *   itemIds {string[]} — ordered Item GUIDs, visible {boolean}
+ * Full model: https://dev.wix.com/docs/api-reference/business-solutions/restaurants/menus/sections/section-object.md
+ *
+ * Item — a single dish/drink. Has EITHER priceInfo (single price) OR priceVariants (one-of).
+ *   id {string}, name {string}, description {string},
+ *   image {object} — { id, url, width, height, altText },
+ *   priceInfo.price {string} — decimal string e.g. "12.50" (NO currency symbol),
+ *   priceVariants.variants {object[]} — [{ variantId, priceInfo: { price } }],
+ *   labels {object[]} — [{ id }] resolve via listLabels,
+ *   visible {boolean}, featured {boolean},
+ *   orderSettings.inStock {boolean}, orderSettings.acceptSpecialRequests {boolean},
+ *   modifierGroups {object[]} — [{ id }] resolve via listModifierGroups
+ * Full model: https://dev.wix.com/docs/api-reference/business-solutions/restaurants/menus/items/items/item-object.md
+ *
+ * PriceVariant (from listVariants): { id, name } — name for the variantId in item.priceVariants.
+ * ModifierGroup: { id, name, rule: { required, minSelections, maxSelections },
+ *   modifiers: [{ id, preSelected, additionalChargeInfo: { additionalCharge } }] }
+ * Modifier (from listModifiers): { id, name, inStock }
+ * Label (from listLabels): { id, name, icon: { url } } — e.g. "Vegan", "Spicy"
+ *
+ * NOTE: Restaurant prices are plain decimal strings with NO currency symbol.
+ * getFullMenu() assembles the full tree and is the recommended entry point.
+ */
+
+/**
+ * Internal: fetch a list endpoint by a set of GUIDs, chunked to avoid long query strings.
+ */
+async function fetchAllByIds(path, idParamName, responseKey, ids, extraQuery = {}) {
+  const unique = [...new Set((ids ?? []).filter(Boolean))];
+  if (!unique.length) return [];
+  const out = [];
+  for (let i = 0; i < unique.length; i += 100) {
+    const chunk = unique.slice(i, i + 100);
+    const res = await wixApiRequest(path, {
+      method: "GET",
+      query: { [idParamName]: chunk, ...extraQuery },
+    });
+    out.push(...(res?.[responseKey] ?? []));
+  }
+  return out;
+}
+
+/**
+ * List menus (one page). Pass `onlyVisible: true` for visitor-facing menus.
+ * GET https://www.wixapis.com/restaurants/menus/v1/menus
+ * @param {{ onlyVisible?: boolean, limit?: number, cursor?: string }} [options]
+ * @returns {Promise<{ menus: object[], nextCursor: string|null }>}
+ */
+export async function listMenus({ onlyVisible = true, limit = 500, cursor } = {}) {
+  const res = await wixApiRequest("/restaurants/menus/v1/menus", {
+    method: "GET",
+    query: {
+      onlyVisible: onlyVisible ? "true" : undefined,
+      "paging.limit": String(limit),
+      "paging.cursor": cursor,
+    },
+  });
+  return { menus: res?.menus ?? [], nextCursor: res?.pagingMetadata?.cursors?.next ?? null };
+}
+
+/**
+ * List sections by their GUIDs.
+ * @param {string[]} sectionIds
+ * @param {{ onlyVisible?: boolean }} [options]
+ * @returns {Promise<object[]>}
+ */
+export async function listSections(sectionIds, { onlyVisible = true } = {}) {
+  return fetchAllByIds("/restaurants/menus/v1/sections", "sectionIds", "sections", sectionIds, {
+    onlyVisible: onlyVisible ? "true" : undefined,
+  });
+}
+
+/**
+ * List items by their GUIDs.
+ * @param {string[]} itemIds
+ * @param {{ onlyVisible?: boolean }} [options]
+ * @returns {Promise<object[]>}
+ */
+export async function listItems(itemIds, { onlyVisible = true } = {}) {
+  return fetchAllByIds("/restaurants/menus/v1/items", "itemIds", "items", itemIds, {
+    onlyVisible: onlyVisible ? "true" : undefined,
+  });
+}
+
+/**
+ * List price variants by their GUIDs (resolves variantId → name).
+ * @param {string[]} variantIds
+ * @returns {Promise<object[]>}
+ */
+export async function listVariants(variantIds) {
+  return fetchAllByIds("/restaurants/menus/v1/variants", "variantIds", "variants", variantIds);
+}
+
+/**
+ * List modifier groups by their GUIDs.
+ * @param {string[]} modifierGroupIds
+ * @returns {Promise<object[]>}
+ */
+export async function listModifierGroups(modifierGroupIds) {
+  return fetchAllByIds(
+    "/restaurants/menus/v1/modifier-groups",
+    "modifierGroupIds",
+    "modifierGroups",
+    modifierGroupIds,
+  );
+}
+
+/**
+ * List modifiers by their GUIDs (resolves modifierId → name + inStock).
+ * @param {string[]} modifierIds
+ * @returns {Promise<object[]>}
+ */
+export async function listModifiers(modifierIds) {
+  return fetchAllByIds("/restaurants/item-modifiers/v1/modifiers", "modifierIds", "modifiers", modifierIds);
+}
+
+/**
+ * List every item label on the site.
+ * @returns {Promise<object[]>}
+ */
+export async function listLabels() {
+  const res = await wixApiRequest("/restaurants/menus/v1/labels", { method: "GET" });
+  return res?.labels ?? [];
+}
+
+/**
+ * Retrieve the complete assembled menu tree in one call. Walks menus → sections → items,
+ * then enriches each item with resolved price variants, modifier groups + modifiers, and labels.
+ * This is the recommended entry point for the menu screen.
+ *
+ * Returns:
+ *   { menus: [ { ...menu, sections: [ { ...section, items: [ assembledItem ] } ] } ] }
+ * where assembledItem adds:
+ *   price          {string|null}  Single price (null when variant-priced)
+ *   variants       {object[]}     [{ variantId, name, price }]
+ *   modifierGroups {object[]}     [{ id, name, rule, modifiers: [{ id, name, preSelected, additionalCharge, inStock }] }]
+ *   labels         {object[]}     [{ id, name, icon }]
+ *
+ * https://dev.wix.com/docs/api-reference/business-solutions/restaurants/menus/retrieve-a-complete-menu-structure.md
+ * @param {{ onlyVisible?: boolean }} [options]
+ * @returns {Promise<{ menus: object[] }>}
+ */
+export async function getFullMenu({ onlyVisible = true } = {}) {
+  const { menus } = await listMenus({ onlyVisible });
+  if (!menus.length) return { menus: [] };
+
+  const sectionIds = menus.flatMap((m) => m.sectionIds ?? []);
+  const sections = await listSections(sectionIds, { onlyVisible });
+
+  const itemIds = sections.flatMap((s) => s.itemIds ?? []);
+  const items = await listItems(itemIds, { onlyVisible });
+
+  const variantIds = items.flatMap((i) => (i.priceVariants?.variants ?? []).map((v) => v.variantId));
+  const modifierGroupIds = items.flatMap((i) => (i.modifierGroups ?? []).map((g) => g.id));
+
+  const [variants, modifierGroups, labels] = await Promise.all([
+    listVariants(variantIds),
+    listModifierGroups(modifierGroupIds),
+    listLabels(),
+  ]);
+
+  const modifierIds = modifierGroups.flatMap((g) => (g.modifiers ?? []).map((m) => m.id));
+  const modifiers = await listModifiers(modifierIds);
+
+  const variantMap = new Map(variants.map((v) => [v.id, v]));
+  const groupMap = new Map(modifierGroups.map((g) => [g.id, g]));
+  const modifierMap = new Map(modifiers.map((m) => [m.id, m]));
+  const labelMap = new Map(labels.map((l) => [l.id, l]));
+
+  const assembleItem = (item) => ({
+    ...item,
+    price: item.priceInfo?.price ?? null,
+    variants: (item.priceVariants?.variants ?? []).map((v) => ({
+      variantId: v.variantId,
+      name: variantMap.get(v.variantId)?.name ?? null,
+      price: v.priceInfo?.price ?? null,
+    })),
+    modifierGroups: (item.modifierGroups ?? [])
+      .map((ref) => groupMap.get(ref.id))
+      .filter(Boolean)
+      .map((group) => ({
+        id: group.id,
+        name: group.name,
+        rule: group.rule ?? null,
+        modifiers: (group.modifiers ?? []).map((m) => ({
+          id: m.id,
+          name: modifierMap.get(m.id)?.name ?? null,
+          preSelected: m.preSelected ?? false,
+          additionalCharge: m.additionalChargeInfo?.additionalCharge ?? "0",
+          inStock: modifierMap.get(m.id)?.inStock ?? true,
+        })),
+      })),
+    labels: (item.labels ?? []).map((ref) => labelMap.get(ref.id)).filter(Boolean),
+  });
+
+  const itemMap = new Map(items.map((i) => [i.id, assembleItem(i)]));
+  const sectionMap = new Map(
+    sections.map((s) => [
+      s.id,
+      { ...s, items: (s.itemIds ?? []).map((id) => itemMap.get(id)).filter(Boolean) },
+    ]),
+  );
+
+  return {
+    menus: menus.map((m) => ({
+      ...m,
+      sections: (m.sectionIds ?? []).map((id) => sectionMap.get(id)).filter(Boolean),
+    })),
+  };
+}

package/skills/wix-vibe-headless/references/restaurants/wix-restaurants-ordering.js

@@ -0,0 +1,156 @@
+import { wixApiRequest } from "./wix-client.js";
+
+// Data model reference: see INSTRUCTIONS.md
+
+/**
+ * Operation — online-ordering context (fulfillment + scheduling). Every cart line item must
+ * reference an operationId. Pick the default / first enabled one for a simple flow.
+ *   id {string}, name {string}, default {boolean},
+ *   onlineOrderingStatus {string} — "ENABLED"|"DISABLED"|"PAUSED_UNTIL"|UNDEFINED,
+ *   defaultFulfillmentType {string} — "PICKUP"|"DELIVERY",
+ *   fulfillmentIds {string[]}, businessLocationId {string}
+ * Full model: https://dev.wix.com/docs/api-reference/business-solutions/restaurants/online-orders/operations/operation-object.md
+ *
+ * Cart (Wix eCom) — restaurant orders use the same visitor cart as the storefront.
+ *   id {string}, currency {string},
+ *   lineItems[].id {string} — lineItemId for update/remove (NOT the item id),
+ *   lineItems[].quantity {number},
+ *   lineItems[].catalogReference.catalogItemId {string} — the ordered item's GUID,
+ *   lineItems[].productName.original {string},
+ *   lineItems[].price.formattedAmount {string},
+ *   lineItems[].availability.status {string} — "AVAILABLE"|"NOT_AVAILABLE"|"PARTIALLY_AVAILABLE"|"NOT_FOUND"
+ * Full model: https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/cart/cart-object.md
+ */
+
+// Wix Restaurants Orders app id — required in catalogReference when adding menu items to the eCom cart.
+const RESTAURANTS_ORDERS_APP_ID = "9a5d83fd-8570-482e-81ab-cfa88942ee60";
+
+/**
+ * List the restaurant's online-ordering operations.
+ * GET https://www.wixapis.com/restaurants-operations/v1/operations
+ * @returns {Promise<object[]>}
+ */
+export async function listOperations() {
+  const res = await wixApiRequest("/restaurants-operations/v1/operations", { method: "GET" });
+  return res?.operations ?? [];
+}
+
+/**
+ * Pick the operation to order through — the default, else the first ENABLED, else the first.
+ * Returns null when no operation is configured (show an "ordering unavailable" state).
+ * @returns {Promise<object|null>}
+ */
+export async function getDefaultOperation() {
+  const operations = await listOperations();
+  return (
+    operations.find((o) => o.default) ??
+    operations.find((o) => o.onlineOrderingStatus === "ENABLED") ??
+    operations[0] ??
+    null
+  );
+}
+
+/**
+ * Add a restaurant menu item to the visitor's current eCom cart.
+ *
+ * Requires operationId (from listOperations/getDefaultOperation), menuId, and sectionId.
+ * Throws if any is missing, or if the added line is not AVAILABLE.
+ *
+ * Variant selection and modifier up-charges on the cart line are not covered here — the
+ * restaurants catalogReference.options shape for those is not documented for client add-to-cart.
+ * Confirm the shape before extending:
+ * https://dev.wix.com/docs/api-reference/business-solutions/restaurants/online-orders/sample-flows.md
+ *
+ * POST https://www.wixapis.com/ecom/v1/carts/current/add-to-cart
+ * @param {string} itemId  Menu item GUID (item.id).
+ * @param {{ operationId: string, menuId: string, sectionId: string, onlineOrderingPageUrl?: string, quantity?: number }} opts
+ * @returns {Promise<object>} Updated cart.
+ */
+export async function addItemToCart(itemId, { operationId, menuId, sectionId, onlineOrderingPageUrl, quantity = 1 } = {}) {
+  if (!itemId) throw new Error("addItemToCart: itemId is required.");
+  if (!operationId || !menuId || !sectionId) {
+    throw new Error("addItemToCart: operationId, menuId and sectionId are all required for a restaurant line item.");
+  }
+  const options = { operationId, menuId, sectionId };
+  if (onlineOrderingPageUrl) options.onlineOrderingPageUrl = onlineOrderingPageUrl;
+
+  const res = await wixApiRequest("/ecom/v1/carts/current/add-to-cart", {
+    method: "POST",
+    body: {
+      lineItems: [{ catalogReference: { appId: RESTAURANTS_ORDERS_APP_ID, catalogItemId: itemId, options }, quantity }],
+    },
+  });
+  const line = (res?.cart?.lineItems ?? []).find((l) => l.catalogReference?.catalogItemId === itemId);
+  if (line?.availability?.status && line.availability.status !== "AVAILABLE") {
+    throw new Error(`Item not available to order (status: ${line.availability.status}).`);
+  }
+  return res?.cart;
+}
+
+/** Read the visitor's current cart. Returns null if no cart exists yet. */
+export async function getCurrentCart() {
+  try {
+    const res = await wixApiRequest("/ecom/v1/carts/current", { method: "GET" });
+    return res?.cart ?? null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Update the quantity of a cart line. lineItemId is cart.lineItems[].id, not the item id.
+ * POST https://www.wixapis.com/ecom/v1/carts/current/update-line-items-quantity
+ * @returns {Promise<object>} Updated cart.
+ */
+export async function updateCartItemQuantity(lineItemId, quantity) {
+  const res = await wixApiRequest("/ecom/v1/carts/current/update-line-items-quantity", {
+    method: "POST",
+    body: { lineItems: [{ id: lineItemId, quantity }] },
+  });
+  return res?.cart;
+}
+
+/**
+ * Remove a line from the current cart by its cart.lineItems[].id.
+ * POST https://www.wixapis.com/ecom/v1/carts/current/remove-line-items
+ * @returns {Promise<object>} Updated cart.
+ */
+export async function removeFromCart(lineItemId) {
+  const res = await wixApiRequest("/ecom/v1/carts/current/remove-line-items", {
+    method: "POST",
+    body: { lineItemIds: [lineItemId] },
+  });
+  return res?.cart;
+}
+
+/**
+ * Create a checkout from the current cart and return the Wix-hosted checkout URL.
+ * Throws on empty cart, unavailable lines, or a missing redirect URL.
+ * Redirect with: window.location.href = await checkout()
+ * @returns {Promise<string>}
+ */
+export async function checkout() {
+  const cart = await getCurrentCart();
+  const lines = cart?.lineItems ?? [];
+  if (!lines.length) throw new Error("Cannot check out: the cart is empty.");
+  const unavailable = lines.filter((l) => l.availability?.status && l.availability.status !== "AVAILABLE");
+  if (unavailable.length) {
+    const names = unavailable.map((l) => l.productName?.original ?? l.catalogReference?.catalogItemId).join(", ");
+    throw new Error(`Cannot check out: ${unavailable.length} item(s) not available — ${names}.`);
+  }
+
+  const checkoutRes = await wixApiRequest("/ecom/v1/carts/current/create-checkout", {
+    method: "POST",
+    body: { channelType: "WEB" },
+  });
+  const checkoutId = checkoutRes?.checkoutId;
+  if (!checkoutId) throw new Error("Failed to create checkout from the current cart.");
+
+  const redirect = await wixApiRequest("/headless/v1/redirect-session", {
+    method: "POST",
+    body: { ecomCheckout: { checkoutId }, callbacks: { postFlowUrl: window.location.href } },
+  });
+  const url = redirect?.redirectSession?.fullUrl;
+  if (!url) throw new Error("Failed to create the checkout redirect session.");
+  return url;
+}

package/skills/wix-vibe-headless/references/restaurants/wix-restaurants-reservations.js

@@ -0,0 +1,107 @@
+import { wixApiRequest } from "./wix-client.js";
+
+// Data model reference: see INSTRUCTIONS.md
+
+/**
+ * ReservationLocation — a restaurant location that accepts table reservations.
+ *   id {string}, default {boolean}, archived {boolean},
+ *   location {object} — physical location details,
+ *   configuration {object}:
+ *     onlineReservations.approval.mode — "AUTOMATIC"|"MANUAL"|"MANUAL_FOR_LARGE_PARTIES"
+ *     partySize.min / partySize.max — guest count limits
+ *     timeSlotInterval — minutes between slots
+ *     reservationForm: { lastNameRequired, emailRequired, customFieldDefinitions }
+ * Full model: https://dev.wix.com/docs/api-reference/business-solutions/restaurants/reservations/reservation-locations/reservation-location-object.md
+ *
+ * TimeSlot (from getTimeSlots):
+ *   { startDate, duration, status, manualApproval }
+ *   status: "AVAILABLE" | "UNAVAILABLE" | "NON_WORKING_HOURS" — offer only AVAILABLE slots.
+ *
+ * Reservation (from createHeldReservation / reserveReservation):
+ *   { id, revision, status, details: { reservationLocationId, startDate, endDate, partySize }, reservee, paymentStatus }
+ *   status: "HELD" → "RESERVED" (auto-approved) or "REQUESTED" (manual approval required) after reserve.
+ * Full model: https://dev.wix.com/docs/api-reference/business-solutions/restaurants/reservations/reservations/reservation-object.md
+ */
+
+/**
+ * List the site's reservation locations (up to 100).
+ * GET https://www.wixapis.com/table-reservations/reservation-locations/v1/reservation-locations
+ * @returns {Promise<object[]>}
+ */
+export async function listReservationLocations() {
+  const res = await wixApiRequest(
+    "/table-reservations/reservation-locations/v1/reservation-locations",
+    { method: "GET" },
+  );
+  return res?.reservationLocations ?? [];
+}
+
+/**
+ * Get reservation time slots for a location on a date, filtered to AVAILABLE only.
+ * Use slotsBefore / slotsAfter to fan out around the chosen date.
+ * POST https://www.wixapis.com/table-reservations/reservations/v1/time-slots
+ * https://dev.wix.com/docs/api-reference/business-solutions/restaurants/reservations/time-slots/get-time-slots.md
+ * @param {string} reservationLocationId
+ * @param {string} date       ISO-8601 datetime e.g. "2026-07-01T19:00:00.000Z"
+ * @param {number} partySize
+ * @param {{ slotsBefore?: number, slotsAfter?: number, duration?: number }} [options]
+ * @returns {Promise<{ timeSlots: object[], availableTimeSlots: object[] }>}
+ */
+export async function getTimeSlots(reservationLocationId, date, partySize, { slotsBefore = 4, slotsAfter = 4, duration } = {}) {
+  if (!reservationLocationId || !date || !partySize) {
+    throw new Error("getTimeSlots: reservationLocationId, date and partySize are required.");
+  }
+  const res = await wixApiRequest("/table-reservations/reservations/v1/time-slots", {
+    method: "POST",
+    body: { reservationLocationId, date, partySize, slotsBefore, slotsAfter, ...(duration ? { duration } : {}) },
+  });
+  const timeSlots = res?.timeSlots ?? [];
+  return { timeSlots, availableTimeSlots: timeSlots.filter((s) => s.status === "AVAILABLE") };
+}
+
+/**
+ * Hold a reservation for 10 minutes while the visitor fills in their details.
+ * Returns a reservation with status "HELD" — keep its id and revision for reserveReservation.
+ * POST https://www.wixapis.com/table-reservations/reservations/v1/reservations/hold
+ * @param {string} reservationLocationId
+ * @param {string} startDate  ISO-8601 datetime of the chosen time slot.
+ * @param {number} partySize
+ * @returns {Promise<object>} The held reservation ({ id, revision, status: "HELD", ... }).
+ */
+export async function createHeldReservation(reservationLocationId, startDate, partySize) {
+  if (!reservationLocationId || !startDate || !partySize) {
+    throw new Error("createHeldReservation: reservationLocationId, startDate and partySize are required.");
+  }
+  const res = await wixApiRequest("/table-reservations/reservations/v1/reservations/hold", {
+    method: "POST",
+    body: { reservationDetails: { reservationLocationId, startDate, partySize } },
+  });
+  const reservation = res?.reservation;
+  if (!reservation?.id) throw new Error("Failed to hold the reservation (the slot may no longer be available).");
+  return reservation;
+}
+
+/**
+ * Confirm a held reservation with the visitor's details. Moves status from "HELD" to
+ * "RESERVED" (auto-approval) or "REQUESTED" (manual approval required).
+ * reservee.firstName and reservee.phone (E.164, e.g. "+15551234567") are REQUIRED.
+ * Pass the revision returned by createHeldReservation. Holds expire after 10 minutes.
+ * POST https://www.wixapis.com/table-reservations/reservations/v1/reservations/{id}/reserve
+ * @param {string} reservationId
+ * @param {string} revision
+ * @param {{ firstName: string, phone: string, lastName?: string, email?: string, marketingConsent?: boolean }} reservee
+ * @returns {Promise<object>} The updated reservation.
+ */
+export async function reserveReservation(reservationId, revision, reservee) {
+  if (!reservationId || !revision) throw new Error("reserveReservation: reservationId and revision are required.");
+  if (!reservee?.firstName || !reservee?.phone) {
+    throw new Error("reserveReservation: reservee.firstName and reservee.phone are required.");
+  }
+  const res = await wixApiRequest(
+    `/table-reservations/reservations/v1/reservations/${encodeURIComponent(reservationId)}/reserve`,
+    { method: "POST", body: { revision, reservee } },
+  );
+  const reservation = res?.reservation;
+  if (!reservation?.id) throw new Error("Failed to confirm the reservation (the hold may have expired — start over).");
+  return reservation;
+}