@wix/agent-skills 1.16.3 → 1.18.0

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

@@ -0,0 +1,165 @@
+// Menu reads (Wix Restaurants Menus V1) — the only file that touches raw menu entities.
+// Everything it returns is a plain DTO from ./types. Copy as-is; extend by adding functions,
+// not by editing these.
+//
+// The hierarchy is Menu → Sections → Items wired by ID ARRAYS: display structure and order
+// live in menu.sectionIds / section.itemIds, NOT in the list* response order — fetchMenus
+// stitches in id-array order and drops dangling ids. Entity ids are `_id` (never `id`).
+// 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
+import {
+  menus as menusModule,
+  sections as sectionsModule,
+  items as itemsModule,
+  itemVariants,
+  itemModifierGroups,
+  itemModifiers,
+  itemLabels,
+} from "@wix/restaurants";
+import { wixModule } from "../sdk";
+import { imgSrc } from "../media";
+import type {
+  MenuData,
+  MenuItem,
+  MenuItemLabel,
+  MenuItemVariant,
+  MenuModifier,
+  MenuModifierGroup,
+  MenuSection,
+} 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);
+
+type Raw = Record<string, any>;
+
+// Menu prices are decimal strings in the site currency with NO symbol; the response may
+// carry a platform-formatted twin (formattedPrice) — prefer it, never invent a symbol.
+function displayPrice(priceInfo: Raw | undefined): string | null {
+  if (!priceInfo) return null;
+  return priceInfo.formattedPrice ?? priceInfo.price ?? null;
+}
+
+function toItem(
+  raw: Raw,
+  lookups: { variantById: Map<string, Raw>; groupById: Map<string, Raw>; modifierById: Map<string, Raw>; labelById: Map<string, Raw> },
+): MenuItem {
+  const variants: MenuItemVariant[] = (raw.priceVariants?.variants ?? [])
+    .map((v: Raw): MenuItemVariant => ({
+      variantId: v.variantId ?? "",
+      name: lookups.variantById.get(v.variantId)?.name ?? "",
+      price: displayPrice(v.priceInfo) ?? v.price ?? "",
+    }))
+    .filter((v: MenuItemVariant) => v.variantId);
+  const modifierGroups: MenuModifierGroup[] = (raw.modifierGroups ?? [])
+    .map((ref: Raw) => lookups.groupById.get(ref._id))
+    .filter(Boolean)
+    .map((g: Raw): MenuModifierGroup => ({
+      id: g._id ?? "",
+      name: g.name ?? "",
+      required: g.rule?.required === true,
+      minSelections: g.rule?.minSelections ?? 0,
+      maxSelections: g.rule?.maxSelections ?? null,
+      modifiers: (g.modifiers ?? []).map((m: Raw): MenuModifier => ({
+        id: m._id ?? "",
+        name: lookups.modifierById.get(m._id)?.name ?? "",
+        preSelected: m.preSelected === true,
+        additionalCharge: m.additionalChargeInfo?.additionalCharge ?? "0",
+        inStock: lookups.modifierById.get(m._id)?.inStock !== false,
+      })),
+    }));
+  const labels: MenuItemLabel[] = (raw.labels ?? [])
+    .map((ref: Raw) => lookups.labelById.get(ref._id))
+    .filter(Boolean)
+    .map((l: Raw): MenuItemLabel => ({ id: l._id ?? "", name: l.name ?? "", iconUrl: imgSrc(l.icon, 48, 48) }));
+  const price = displayPrice(raw.priceInfo);
+  return {
+    id: raw._id ?? "",
+    name: raw.name ?? "",
+    description: raw.description ?? "",
+    price,
+    marketPrice: price === null && variants.length === 0,
+    variants,
+    imageUrl: imgSrc(raw.image, 800, 800),
+    labels,
+    modifierGroups,
+    inStock: raw.orderSettings?.inStock !== false,
+    featured: raw.featured === true,
+  };
+}
+
+/**
+ * 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.
+ * The one entry point for every menu surface. [] when no menus exist (honest empty state).
+ * Caps at the APIs' 500-per-list limit — plenty for a restaurant.
+ */
+export async function fetchMenus(): Promise<MenuData[]> {
+  const [menusRes, sectionsRes, itemsRes]: Raw[] = await Promise.all([
+    menusApi.listMenus({ onlyVisible: true }),
+    sectionsApi.listSections({ onlyVisible: true }),
+    itemsApi.listItems({ onlyVisible: true }),
+  ]);
+  const menus: Raw[] = menusRes.menus ?? [];
+  if (!menus.length) return [];
+  const sections: Raw[] = sectionsRes.sections ?? [];
+  const items: Raw[] = itemsRes.items ?? [];
+
+  const variantIds: string[] = [
+    ...new Set(items.flatMap((i: Raw) => (i.priceVariants?.variants ?? []).map((v: Raw) => v.variantId)).filter(Boolean)),
+  ] as string[];
+  const groupIds: string[] = [
+    ...new Set(items.flatMap((i: Raw) => (i.modifierGroups ?? []).map((g: Raw) => g._id)).filter(Boolean)),
+  ] as string[];
+  const hasLabels = items.some((i: Raw) => (i.labels ?? []).length > 0);
+
+  const [variantsRes, groupsRes, labelsRes]: Raw[] = await Promise.all([
+    variantIds.length ? variantsApi.listVariants({ variantIds }) : Promise.resolve({ variants: [] }),
+    groupIds.length ? groupsApi.listModifierGroups({ modifierGroupIds: groupIds }) : Promise.resolve({ modifierGroups: [] }),
+    hasLabels ? labelsApi.listLabels() : Promise.resolve({ labels: [] }),
+  ]);
+  const groups: Raw[] = groupsRes.modifierGroups ?? [];
+  const modifierIds: string[] = [
+    ...new Set(groups.flatMap((g: Raw) => (g.modifiers ?? []).map((m: Raw) => m._id)).filter(Boolean)),
+  ] as string[];
+  const modifiersRes: Raw = modifierIds.length
+    ? await modifiersApi.listModifiers({ modifierIds })
+    : { modifiers: [] };
+
+  const byId = (arr: Raw[]) => new Map<string, Raw>(arr.map((e: Raw) => [e._id, e]));
+  const lookups = {
+    variantById: byId(variantsRes.variants ?? []),
+    groupById: byId(groups),
+    modifierById: byId(modifiersRes.modifiers ?? []),
+    labelById: byId(labelsRes.labels ?? []),
+  };
+  const sectionById = byId(sections);
+  const itemById = new Map<string, MenuItem>(items.map((i: Raw) => [i._id, toItem(i, lookups)]));
+
+  return menus.map((m: Raw): MenuData => ({
+    id: m._id ?? "",
+    name: m.name ?? "",
+    description: m.description ?? "",
+    slug: m.urlQueryParam ?? "",
+    sections: (m.sectionIds ?? [])
+      .map((sid: string) => sectionById.get(sid))
+      .filter(Boolean)
+      .map((s: Raw): MenuSection => ({
+        id: s._id ?? "",
+        name: s.name ?? "",
+        description: s.description ?? "",
+        imageUrl: imgSrc(s.image, 800, 800),
+        items: (s.itemIds ?? []).map((iid: string) => itemById.get(iid)).filter(Boolean) as MenuItem[],
+      })),
+  }));
+}

package/skills/wix-headless-fast/references/restaurants/app/wix/restaurants/order-store.ts

@@ -0,0 +1,103 @@
+// Client-side order-cart state — a module-scope store, deliberately NOT a React context.
+// A context can't span Astro islands (each island is its own React root); a module singleton
+// is shared by every island in the page bundle, and works identically in a single-root SPA.
+// Consume it through useOrderCart() (hooks/), or subscribe directly.
+import type { OrderCart } from "./types";
+import {
+  addToOrder as apiAdd,
+  fetchOrderCart,
+  orderCheckoutUrl,
+  removeOrderLine as apiRemove,
+  resolveOperationId,
+  updateOrderQuantity as apiUpdate,
+} from "./ordering";
+
+export interface OrderCartState {
+  cart: OrderCart | null;
+  /** null while resolving; false → no ordering operation configured (show "unavailable"). */
+  ordering: boolean | null;
+  /** True while any cart operation is in flight. */
+  busy: boolean;
+  /** Last failed operation's message — render it; a new operation clears it. */
+  error: string | null;
+  /** Order drawer visibility (OrderCartButton opens it, OrderCartDrawer renders by it). */
+  open: boolean;
+}
+
+const EMPTY: OrderCartState = { cart: null, ordering: null, busy: false, error: null, open: false };
+
+let state: OrderCartState = EMPTY;
+const listeners = new Set<() => void>();
+let loaded = false;
+
+function setState(patch: Partial<OrderCartState>): void {
+  state = { ...state, ...patch };
+  for (const l of listeners) l();
+}
+
+export function getOrderCartState(): OrderCartState {
+  return state;
+}
+
+export function subscribeOrderCart(listener: () => void): () => void {
+  listeners.add(listener);
+  // First subscriber triggers the initial load (browser only — SSR renders the empty state).
+  if (!loaded && typeof window !== "undefined") {
+    loaded = true;
+    void refreshOrderCart();
+    void resolveOperationId().then((id) => setState({ ordering: id !== null }));
+  }
+  return () => listeners.delete(listener);
+}
+
+async function run(op: () => Promise<OrderCart>): Promise<void> {
+  setState({ busy: true, error: null });
+  try {
+    setState({ cart: await op(), busy: false });
+  } catch (e) {
+    setState({ busy: false, error: e instanceof Error ? e.message : String(e) });
+    throw e;
+  }
+}
+
+export async function refreshOrderCart(): Promise<void> {
+  try {
+    setState({ cart: await fetchOrderCart() });
+  } catch {
+    /* no cart yet — leave the empty state */
+  }
+}
+
+/** Add a menu item to the order and open the drawer. Throws (and sets .error) on refusal. */
+export async function addOrderLine(
+  itemId: string,
+  context: { menuId: string; sectionId: string },
+  quantity = 1,
+): Promise<void> {
+  await run(() => apiAdd(itemId, context, quantity));
+  setState({ open: true });
+}
+
+export async function updateOrderLineQuantity(lineItemId: string, quantity: number): Promise<void> {
+  await run(() => apiUpdate(lineItemId, quantity));
+}
+
+export async function removeLineFromOrder(lineItemId: string): Promise<void> {
+  await run(() => apiRemove(lineItemId));
+}
+
+/** Navigate to the Wix-hosted checkout. Never hand-build a checkout URL. */
+export async function goToOrderCheckout(): Promise<void> {
+  setState({ busy: true, error: null });
+  try {
+    const url = await orderCheckoutUrl();
+    window.location.href = url;
+  } catch (e) {
+    setState({ busy: false, error: e instanceof Error ? e.message : String(e) });
+    throw e;
+  }
+}
+
+export function setOrderCartOpen(open: boolean): void {
+  setState({ open });
+}

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

@@ -0,0 +1,254 @@
+// Online ordering (Restaurants Orders + Wix eCom Cart V2) — the only file that touches the
+// raw cart and operation entities. Copy as-is; extend by calling these exports, never by
+// editing them. The request shapes are exact and rewriting them is how carts break:
+//   - the catalogReference appId is the ORDERS app (9a5d83fd-…), never the Stores id;
+//   - options MUST carry operationId + menuId + sectionId (all three) — the restaurant
+//     analog of the store's variantId; there is NO variantId here;
+//   - modifier/variant selections on the cart line are NOT sent — that options shape isn't
+//     documented for client add-to-cart (display modifiers; send quantity only).
+// Failures are loud: throws on a missing ordering operation, unavailable lines, and an empty
+// cart at checkout — surface the message, don't swallow it.
+// 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/restaurants/menus/items/items/list-items.md
+// docs: https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/purchase-flow/cart-v2/get-current-cart.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-solutions/e-commerce/purchase-flow/cart-v2/update-line-items.md
+// docs: https://dev.wix.com/docs/api-reference/business-management/headless/redirects/create-redirect-session.md
+import { operations as operationsModule, fulfillmentMethods as fulfillmentModule, items as itemsModule } from "@wix/restaurants";
+import { currentCartV2 } from "@wix/ecom";
+import { redirects as redirectsModule } from "@wix/redirects";
+import { wixModule } from "../sdk";
+import { imgSrc } from "../media";
+import { formatMoney } from "../money";
+import type { FulfillmentMethodInfo, OrderCart, OrderLine } from "./types";
+
+const operationsApi = wixModule(operationsModule);
+const fulfillmentApi = wixModule(fulfillmentModule);
+const itemsApi = wixModule(itemsModule);
+const cartApi = wixModule(currentCartV2);
+const redirects = wixModule(redirectsModule);
+
+/** The Restaurants Orders app id — every restaurant cart line's catalogReference.appId. */
+export const RESTAURANTS_ORDERS_APP_ID = "9a5d83fd-8570-482e-81ab-cfa88942ee60";
+
+type Raw = Record<string, any>;
+
+// The ordering operation is site config — resolve once, reuse for every add.
+let operationIdPromise: Promise<string | null> | null = null;
+
+/**
+ * The id of the operation to order through (ENABLED, else default, else first) — null when
+ * the site has no online ordering configured (show an "ordering unavailable" state).
+ */
+export function resolveOperationId(): Promise<string | null> {
+  operationIdPromise ??= operationsApi
+    .listOperations()
+    .then((res: Raw) => {
+      const ops: Raw[] = res.operations ?? [];
+      const op =
+        ops.find((o: Raw) => o.onlineOrderingStatus === "ENABLED") ?? ops.find((o: Raw) => o.default) ?? ops[0];
+      return op?._id ?? null;
+    })
+    .catch(() => {
+      operationIdPromise = null; // transient failure — allow a retry on the next call
+      return null;
+    });
+  return operationIdPromise;
+}
+
+/** Enabled pickup/delivery methods, for display — the buyer picks one on the hosted checkout. */
+export async function fetchFulfillmentMethods(): Promise<FulfillmentMethodInfo[]> {
+  try {
+    const res: Raw = await fulfillmentApi.listFulfillmentMethods();
+    return (res.fulfillmentMethods ?? [])
+      .filter((m: Raw) => m.enabled === true)
+      .map((m: Raw): FulfillmentMethodInfo => ({
+        id: m._id ?? "",
+        type: m.type === "DELIVERY" ? "DELIVERY" : "PICKUP",
+        name: m.name ?? "",
+        fee: m.fee ?? "0",
+        minOrderPrice: m.minOrderPrice ?? "0",
+      }))
+      .filter((m: FulfillmentMethodInfo) => m.id);
+  } catch {
+    return []; // display nicety — ordering still works without the list
+  }
+}
+
+// The V2 cart doesn't reliably return line-item images — join them from the menu items by
+// the line's catalogItemId and cache for the session.
+const lineImageCache = new Map<string, string>();
+
+async function fillLineImages(lines: OrderLine[], raws: Raw[]): Promise<void> {
+  const wanted = new Map<string, number[]>(); // itemId -> line indexes
+  raws.forEach((raw: Raw, i: number) => {
+    if (lines[i].imageUrl) return;
+    const itemId = raw.source?.catalogReference?.catalogItemId;
+    if (!itemId) return;
+    const cached = lineImageCache.get(itemId);
+    if (cached !== undefined) {
+      lines[i].imageUrl = cached;
+      return;
+    }
+    wanted.set(itemId, [...(wanted.get(itemId) ?? []), i]);
+  });
+  if (!wanted.size) return;
+  try {
+    const res: Raw = await itemsApi.listItems({ itemIds: [...wanted.keys()] });
+    for (const item of (res.items ?? []) as Raw[]) {
+      const url = imgSrc(item.image, 300, 300);
+      lineImageCache.set(item._id, url);
+      for (const i of wanted.get(item._id) ?? []) lines[i].imageUrl = url;
+    }
+  } catch {
+    /* images are a nicety — the cart stays correct without them */
+  }
+}
+
+function cartCurrency(raw: Raw | null): string {
+  return raw?.customerInfo?.currencyCode ?? raw?.businessInfo?.currencyCode ?? "";
+}
+
+function toLine(raw: Raw, currency: string): OrderLine {
+  const descriptionLines: string[] = (raw.attributes?.descriptionLines ?? [])
+    .map((d: Raw) => {
+      const label = d.name?.original ?? "";
+      const value = d.plainText?.original ?? d.colorInfo?.original ?? "";
+      return label && value ? `${label}: ${value}` : value || label;
+    })
+    .filter(Boolean);
+  return {
+    lineItemId: raw._id ?? "",
+    itemName: raw.name?.original ?? "",
+    quantity: raw.quantityInfo?.confirmedQuantity ?? 0,
+    unitPrice: formatMoney(raw.pricing?.unitPrice, currency),
+    linePrice: formatMoney(raw.pricing?.totalPrice, currency),
+    imageUrl: imgSrc(raw.attributes?.image, 300, 300),
+    descriptionLines,
+    status: raw.status ?? "IN_STOCK",
+  };
+}
+
+function toCart(raw: Raw | null, subtotal: string): OrderCart {
+  const currency = cartCurrency(raw);
+  const lines = (raw?.lineItems ?? []).map((l: Raw) => toLine(l, currency));
+  return {
+    lines,
+    itemCount: lines.reduce((sum: number, l: OrderLine) => sum + l.quantity, 0),
+    subtotal,
+    currency,
+  };
+}
+
+async function readCartWithSubtotal(raw: Raw | null): Promise<OrderCart> {
+  if (!raw?.lineItems?.length) return toCart(raw, "");
+  // The authoritative after-discount subtotal comes from the cart estimate, never from
+  // hand-summing line items (fees, tax, and delivery resolve at checkout).
+  let subtotal = "";
+  try {
+    const estimate: Raw = await cartApi.estimateCurrentCart();
+    subtotal = formatMoney(estimate?.summary?.priceSummary?.subtotal, cartCurrency(raw));
+  } catch {
+    /* estimate is a display nicety — the cart itself is still valid */
+  }
+  const cart = toCart(raw, subtotal);
+  await fillLineImages(cart.lines, raw.lineItems as Raw[]);
+  return cart;
+}
+
+/** Read the visitor's current order cart. An empty cart (not an error) when none exists yet. */
+export async function fetchOrderCart(): Promise<OrderCart> {
+  try {
+    const { cart } = await cartApi.getCurrentCart();
+    return readCartWithSubtotal(cart as Raw);
+  } catch {
+    return toCart(null, "");
+  }
+}
+
+/**
+ * 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), never re-derive them. Throws when ordering isn't configured or the line is refused.
+ */
+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.");
+  if (!itemId || !menuId || !sectionId) throw new Error("addToOrder needs the item, menu, and section ids.");
+
+  const { cart } = await cartApi.addLineItemsToCurrentCart({
+    catalogItems: [
+      {
+        quantity,
+        catalogReference: {
+          catalogItemId: itemId,
+          appId: RESTAURANTS_ORDERS_APP_ID,
+          options: { operationId, menuId, sectionId },
+        },
+      },
+    ],
+  });
+
+  // V2 nests the reference under `source` — a top-level lineItem.catalogReference no longer exists.
+  const line = ((cart as Raw)?.lineItems ?? []).find(
+    (l: Raw) => l.source?.catalogReference?.catalogItemId === itemId,
+  );
+  if (line?.status && line.status !== "IN_STOCK") {
+    throw new Error(`This dish isn't available right now (${line.status.toLowerCase().replace(/_/g, " ")}).`);
+  }
+  if (!line || line.quantityInfo?.confirmedQuantity === 0) {
+    throw new Error("The dish couldn't be added to the order — please try again.");
+  }
+  return readCartWithSubtotal(cart as Raw);
+}
+
+/** Change a line's quantity. `lineItemId` is OrderLine.lineItemId, never the menu item id. */
+export async function updateOrderQuantity(lineItemId: string, quantity: number): Promise<OrderCart> {
+  const { cart } = await cartApi.updateLineItemsInCurrentCart({
+    lineItems: [{ lineItemId, quantity: { newQuantity: quantity } }],
+  });
+  return readCartWithSubtotal(cart as Raw);
+}
+
+/** Remove a line from the order by OrderLine.lineItemId. */
+export async function removeOrderLine(lineItemId: string): Promise<OrderCart> {
+  const { cart } = await cartApi.removeLineItemsFromCurrentCart([lineItemId]);
+  return readCartWithSubtotal(cart as Raw);
+}
+
+/**
+ * Start the Wix-hosted checkout for the current order and return the URL to navigate to.
+ * The cart's id IS the checkout id — no separate checkout-creation call. Fulfillment
+ * (pickup/delivery + time) and payment are collected on the hosted page. Call from the
+ * browser: the return origin must be window.location.origin (https), never a server-derived
+ * request origin (http behind the proxy → the return redirect 403s).
+ */
+export async function orderCheckoutUrl(): Promise<string> {
+  const { cart } = await cartApi.getCurrentCart();
+  const raw = cart as Raw;
+  const lines: Raw[] = raw?.lineItems ?? [];
+  if (!lines.length) throw new Error("Your order is empty.");
+  const unavailable = lines.filter((l) => l.status && l.status !== "IN_STOCK");
+  if (unavailable.length) {
+    const names = unavailable.map((l) => l.name?.original).filter(Boolean).join(", ");
+    throw new Error(`Some dishes are no longer available: ${names}.`);
+  }
+  if (!raw?._id) throw new Error("Checkout couldn't start: the order has no id.");
+
+  const origin = typeof window !== "undefined" ? window.location.origin : "";
+  const session = await redirects.createRedirectSession({
+    ecomCheckout: { checkoutId: raw._id },
+    callbacks: {
+      postFlowUrl: origin ? `${origin}/` : undefined,
+      thankYouPageUrl: origin ? `${origin}/` : undefined,
+    },
+  });
+  const url = session?.redirectSession?.fullUrl;
+  if (!url) throw new Error("Checkout couldn't start: no redirect URL returned.");
+  return url;
+}

package/skills/wix-headless-fast/references/restaurants/app/wix/restaurants/reservations.ts

@@ -0,0 +1,146 @@
+// Table reservations (@wix/table-reservations) — the only file that touches raw reservation
+// entities. Copy as-is; extend by calling these exports, never by editing them.
+//
+// The flow is location → AVAILABLE slots → hold (10-minute temporary reservation) → reserve
+// with the visitor's details. A reservation is a hold, not a purchase — no cart, no checkout.
+// getTimeSlots takes POSITIONAL args and a Date (not an ISO string); reserveReservation takes
+// THREE positional args (id, reservee, revision) and the only exit from HELD is reserve.
+// Failures are loud — surface the message, don't swallow it.
+// docs: https://dev.wix.com/docs/api-reference/business-solutions/restaurants/reservations/reservation-locations/list-reservation-locations.md
+// 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 { reservationLocations, timeSlots, reservations as reservationsModule } from "@wix/table-reservations";
+import { wixModule } from "../sdk";
+import type {
+  ReservationConfirmation,
+  ReservationHold,
+  ReservationLocationInfo,
+  ReservationReservee,
+  ReservationSlot,
+} from "./types";
+
+const locationsApi = wixModule(reservationLocations);
+const timeSlotsApi = wixModule(timeSlots);
+const reservationsApi = wixModule(reservationsModule);
+
+type Raw = Record<string, any>;
+
+/**
+ * Active (non-archived) reservation locations, default first. [] when Table Reservations
+ * isn't set up. `onlineReservationsEnabled: false` means the premium-gated toggle is off —
+ * slots and booking won't work; render an honest "reservations aren't open yet" state.
+ */
+export async function fetchReservationLocations(): Promise<ReservationLocationInfo[]> {
+  const res: Raw = await locationsApi.listReservationLocations();
+  return (res.reservationLocations ?? [])
+    .filter((l: Raw) => l.archived !== true)
+    .map((l: Raw): ReservationLocationInfo => {
+      const online = l.configuration?.onlineReservations ?? {};
+      return {
+        id: l._id ?? "",
+        default: l.default === true,
+        partySizeMin: online.partySize?.min ?? 1,
+        partySizeMax: online.partySize?.max ?? 20,
+        approvalMode: online.approval?.mode ?? "AUTOMATIC",
+        onlineReservationsEnabled: online.onlineReservationsEnabled === true,
+      };
+    })
+    .filter((l: ReservationLocationInfo) => l.id)
+    .sort((a: ReservationLocationInfo, b: ReservationLocationInfo) => Number(b.default) - Number(a.default));
+}
+
+function toSlot(raw: Raw): ReservationSlot {
+  const start: Date = raw.startDate instanceof Date ? raw.startDate : new Date(raw.startDate);
+  let label = "";
+  let dayKey = "";
+  try {
+    label = start.toLocaleTimeString(undefined, { hour: "numeric", minute: "2-digit" });
+    const pad = (n: number) => String(n).padStart(2, "0");
+    dayKey = `${start.getFullYear()}-${pad(start.getMonth() + 1)}-${pad(start.getDate())}`;
+  } catch {
+    /* label/dayKey stay "" — startIso still books */
+  }
+  return {
+    startIso: start.toISOString(),
+    label,
+    dayKey,
+    durationMinutes: raw.duration ?? 0,
+    manualApproval: raw.manualApproval === true,
+  };
+}
+
+/**
+ * AVAILABLE reservation slots around a moment for a party size — UNAVAILABLE and
+ * NON_WORKING_HOURS slots are already filtered out (offering them makes the hold fail).
+ * `aroundIso` anchors the fan-out: slotsBefore/slotsAfter extra slots on each side.
+ */
+export async function fetchReservationSlots(
+  locationId: string,
+  aroundIso: string,
+  partySize: number,
+  { slotsBefore = 6, slotsAfter = 6 }: { slotsBefore?: number; slotsAfter?: number } = {},
+): Promise<ReservationSlot[]> {
+  // The date param is a Date — the SDK types it as Date, not the ISO string the docs show.
+  const res: Raw = await timeSlotsApi.getTimeSlots(locationId, new Date(aroundIso), partySize, {
+    slotsBefore,
+    slotsAfter,
+  });
+  return (res.timeSlots ?? [])
+    .filter((s: Raw) => s.status === "AVAILABLE")
+    .map((s: Raw) => toSlot(s));
+}
+
+/**
+ * Hold a slot for 10 minutes while the visitor enters their details. The returned hold
+ * carries the { reservationId, revision } that completeReservation NEEDS — keep both.
+ */
+export async function holdReservation(
+  locationId: string,
+  startIso: string,
+  partySize: number,
+): Promise<ReservationHold> {
+  const res: Raw = await reservationsApi.createHeldReservation({
+    reservationLocationId: locationId,
+    startDate: new Date(startIso),
+    partySize,
+  });
+  const reservationId = res.reservation?._id;
+  const revision = res.reservation?.revision;
+  if (!reservationId || !revision) {
+    throw new Error("That time couldn't be held — it may have just been taken. Pick another slot.");
+  }
+  return { reservationId, revision, startIso, partySize };
+}
+
+/**
+ * Complete a held reservation with the visitor's details. firstName and phone (E.164, e.g.
+ * "+15551234567") are REQUIRED. A hold expires after 10 minutes — on failure, start a fresh
+ * hold; never try to update a HELD reservation by other means.
+ */
+export async function completeReservation(
+  hold: Pick<ReservationHold, "reservationId" | "revision">,
+  reservee: ReservationReservee,
+): Promise<ReservationConfirmation> {
+  if (!reservee.firstName?.trim() || !reservee.phone?.trim()) {
+    throw new Error("First name and phone number are required.");
+  }
+  const res: Raw = await reservationsApi.reserveReservation(
+    hold.reservationId,
+    {
+      firstName: reservee.firstName.trim(),
+      phone: reservee.phone.trim(),
+      ...(reservee.lastName?.trim() ? { lastName: reservee.lastName.trim() } : {}),
+      ...(reservee.email?.trim() ? { email: reservee.email.trim() } : {}),
+    },
+    hold.revision,
+  );
+  const reservation = res.reservation;
+  if (!reservation?._id) {
+    throw new Error("The reservation couldn't be completed — the hold may have expired. Start over.");
+  }
+  return {
+    reservationId: reservation._id,
+    status: reservation.status === "REQUESTED" ? "REQUESTED" : "RESERVED",
+  };
+}