@wix/agent-skills 1.20.1 → 1.22.0

package/skills/wix-headless-fast/references/restaurants/rest/menu.ts

@@ -1,60 +0,0 @@
-// Menu reads over REST (Wix Restaurants Menus V1) — the twin of app/wix/restaurants/menu.ts. Same
-// export, same MenuData tree; the rules and the id-array stitching come from menu-core (the SAME
-// file the SDK transport uses, deployed flat next to this one by deploy.mjs --stack static), so
-// this file is only the transport: one GET per list, literal paths and query params. Every call
-// here is safe from a browser with a visitor token. Porting: keep the paths, keep the params, port
-// the core once. Entities carry `id` here (the SDK spells it `_id`); the core accepts both.
-// 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/items/items/list-items.md
-import { wixRequest } from "./client.js";
-import { imgSrc } from "./media.js";
-import { anyLabels, assembleMenus, collectGroupIds, collectModifierIds, collectVariantIds, type Raw } from "./menu-core.js";
-import type { MenuData } from "./types.js";
-
-const VISIBLE = { onlyVisible: "true" };
-const get = (path: string, query?: Record<string, string | readonly string[]>) => wixRequest<Raw>(path, { method: "GET", query });
-
-/**
- * The site's full menu tree, assembled and display-ordered — the one entry point for every menu
- * surface; [] when no menus exist. Three list reads, then the referenced variants, modifier groups,
- * and labels, then the groups' modifiers (an array query param repeats the key: ?variantIds=a&variantIds=b).
- * GET /restaurants/menus-menu/v1/menus?onlyVisible=true
- * GET /restaurants/menus-section/v1/sections?onlyVisible=true
- * GET /restaurants/menus-item/v1/items?onlyVisible=true
- * GET /restaurants/item-variants/v1/variants?variantIds=…
- * GET /restaurants/item-modifier-group/v1/modifier-groups?modifierGroupIds=…
- * GET /restaurants/item-modifiers/v1/modifiers?modifierIds=…
- * GET /restaurants/item-labels/v1/labels
- */
-export async function fetchMenus(): Promise<MenuData[]> {
-  const [menusRes, sectionsRes, itemsRes] = await Promise.all([
-    get("/restaurants/menus-menu/v1/menus", VISIBLE),
-    get("/restaurants/menus-section/v1/sections", VISIBLE),
-    get("/restaurants/menus-item/v1/items", VISIBLE),
-  ]);
-  const menus: Raw[] = menusRes?.menus ?? [];
-  if (!menus.length) return [];
-  const items: Raw[] = itemsRes?.items ?? [];
-  const variantIds = collectVariantIds(items);
-  const groupIds = collectGroupIds(items);
-  const [variantsRes, groupsRes, labelsRes] = await Promise.all([
-    variantIds.length ? get("/restaurants/item-variants/v1/variants", { variantIds }) : Promise.resolve({ variants: [] } as Raw),
-    groupIds.length ? get("/restaurants/item-modifier-group/v1/modifier-groups", { modifierGroupIds: groupIds }) : Promise.resolve({ modifierGroups: [] } as Raw),
-    anyLabels(items) ? get("/restaurants/item-labels/v1/labels") : Promise.resolve({ labels: [] } as Raw),
-  ]);
-  const groups: Raw[] = groupsRes?.modifierGroups ?? [];
-  const modifierIds = collectModifierIds(groups);
-  const modifiersRes: Raw = modifierIds.length ? await get("/restaurants/item-modifiers/v1/modifiers", { modifierIds }) : { modifiers: [] };
-  return assembleMenus(
-    {
-      menus,
-      sections: sectionsRes?.sections ?? [],
-      items,
-      variants: variantsRes?.variants ?? [],
-      groups,
-      modifiers: modifiersRes?.modifiers ?? [],
-      labels: labelsRes?.labels ?? [],
-    },
-    imgSrc,
-  );
-}

package/skills/wix-headless-fast/references/restaurants/rest/ordering.ts

@@ -1,169 +0,0 @@
-// 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, and options
-// { operationId, menuId, sectionId } — all three, no variantId. Failures are loud: a missing
-// operation, 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/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 {
-  RESTAURANTS_ORDERS_APP_ID,
-  assertOrderAdded,
-  assertOrderCheckoutable,
-  assertOrderContext,
-  estimateSubtotal,
-  orderCatalogItem,
-  pickOperationId,
-  rawId,
-  toFulfillmentMethods,
-  toOrderCart,
-} from "./ordering-core.js";
-import type { Raw } from "./menu-core.js";
-import type { FulfillmentMethodInfo, OrderCart } 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 operationIdPromise: Promise<string | null> | null = null;
-
-/** The operation to order through (ENABLED, else default, else first) — null when the site has no online ordering. */
-export function resolveOperationId(): Promise<string | null> {
-  operationIdPromise ??= wixRequest<Raw>("/restaurants-operations/v1/operations", { method: "GET" })
-    .then((res) => pickOperationId(res?.operations ?? []))
-    .catch(() => {
-      operationIdPromise = null; // transient failure — allow a retry on the next call
-      return null;
-    });
-  return operationIdPromise;
-}
-
-/** Enabled pickup/delivery methods, for display.  GET /fulfillment-methods/v1/fulfillment-methods */
-export async function fetchFulfillmentMethods(): Promise<FulfillmentMethodInfo[]> {
-  try {
-    const res = await wixRequest<Raw>("/fulfillment-methods/v1/fulfillment-methods", { method: "GET" });
-    return toFulfillmentMethods(res?.fulfillmentMethods ?? []);
-  } 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 menu item to the current order. `menuId` and `sectionId` are the ids of the menu and
- * section the item is RENDERED UNDER — thread them from the render context (the fetchMenus tree).
- * Throws when ordering isn't configured 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 } } }] }
- */
-export async function addToOrder(
-  itemId: string,
-  { menuId, sectionId }: { menuId: string; sectionId: string },
-  quantity = 1,
-): Promise<OrderCart> {
-  const operationId = await resolveOperationId();
-  if (!operationId) throw new Error("Online ordering isn't available right now.");
-  assertOrderContext(itemId, menuId, sectionId);
-  const res = await wixRequest<Raw>(`${CART}/add-line-items`, {
-    body: { catalogItems: [orderCatalogItem(itemId, { operationId, menuId, sectionId }, quantity)] },
-  });
-  assertOrderAdded(res?.cart, itemId);
-  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-fast/references/restaurants/rest/reservations.ts

@@ -1,68 +0,0 @@
-// 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 → hold → reserve; 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 and reserve 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
-import { wixRequest } from "./client.js";
-import { availableSlots, reserveeBody, toConfirmation, toHold, toLocations } from "./reservations-core.js";
-import type { Raw } from "./menu-core.js";
-import type { ReservationConfirmation, ReservationHold, ReservationLocationInfo, ReservationReservee, ReservationSlot } from "./types.js";
-
-const RESERVATIONS = "/table-reservations/reservations/v1";
-
-/**
- * Active (non-archived) locations, default first; [] when Table Reservations isn't set up.
- * `onlineReservationsEnabled: false` → the premium-gated toggle is off; render an honest notice.
- * 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).
- * POST /table-reservations/reservations/v1/time-slots  { reservationLocationId, date, partySize, slotsBefore, slotsAfter }
- */
-export async function fetchReservationSlots(
-  locationId: string,
-  aroundIso: string,
-  partySize: number,
-  { slotsBefore = 6, slotsAfter = 6 }: { 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 ?? []);
-}
-
-/**
- * Hold a slot for 10 minutes while the visitor enters their details; the hold's { reservationId, revision } feed completeReservation.
- * 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. firstName and phone (E.164) are REQUIRED; an expired hold can't be
- * reserved — start a fresh hold.
- * POST /table-reservations/reservations/v1/reservations/{reservationId}/reserve  { revision, reservee: { firstName, phone, lastName?, email? } }
- */
-export async function completeReservation(
-  hold: Pick<ReservationHold, "reservationId" | "revision">,
-  reservee: ReservationReservee,
-): Promise<ReservationConfirmation> {
-  const body = reserveeBody(reservee);
-  const res = await wixRequest<Raw>(`${RESERVATIONS}/reservations/${encodeURIComponent(hold.reservationId)}/reserve`, {
-    body: { revision: hold.revision, reservee: body },
-  });
-  return toConfirmation(res);
-}

package/skills/wix-headless-fast/references/restaurants/seed/SEED.md

@@ -1,89 +0,0 @@
-# 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 (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>/references/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:
-
-```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, "imageUrl": "https://…" },
-        { "name": "Branzino", "description": "Whole roasted sea bass, lemon, herbs.",
-          "price": 28, "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).
-- `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`) 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.
-- Fresh Menus installs ship a sample "Dinner Menu"; when THIS run installs the app the seed
-  removes that sample (`sampleMenuRemoved: true`). On a site that already had the app,
-  **seeding is strictly additive — never delete or overwrite existing content**; ask first
-  if a cleanup seems needed.
-
-## Supplied content
-
-The general rules are in `references/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` and, when they supplied one, its
-photo as `imageUrl`. 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`, `removeSampleMenu`, `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; the
-authoritative source recipes are `wix-headless/references/inline-recipes/setup-restaurants.md`,
-`setup-restaurant-orders.md`, and `setup-restaurant-reservations.md`.