@wix/agent-skills 1.19.2 → 1.20.1

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

@@ -0,0 +1,124 @@
+// Online-ordering rules and DTO mapping — transport-agnostic, imported by both ./ordering.ts (SDK)
+// and the REST twin in references/restaurants/rest/ordering.ts (fetch). The restaurant cart rides
+// on the eCom current cart (Cart V2); what makes a line a RESTAURANT line is the catalogReference
+// built here: the Orders app id plus options { operationId, menuId, sectionId } — all three, and
+// no variantId. Raw entities carry `_id` (SDK) or `id` (REST). Has its own formatMoney (a copy of
+// ../money.ts) so it stands alone when stripped. Imports are type-only.
+import type { FulfillmentMethodInfo, OrderCart, OrderLine } from "./types";
+import type { ImgSrc, Raw } from "./menu-core";
+
+/** The Restaurants Orders app id — every restaurant cart line's catalogReference.appId. */
+export const RESTAURANTS_ORDERS_APP_ID = "9a5d83fd-8570-482e-81ab-cfa88942ee60";
+
+export const rawId = (raw: Raw | undefined | null): string => raw?._id ?? raw?.id ?? "";
+
+/**
+ * Cart V2 money is ConvertedMoney { amount, convertedAmount } with NO formatted string, and the
+ * currency lives on the cart, not on the money. Never hardcode a symbol or assume USD.
+ */
+export function formatMoney(money: Raw | null | undefined, currencyCode: string | null | undefined): string {
+  const value = money?.convertedAmount ?? money?.amount;
+  if (value == null || value === "") return "";
+  const currency = currencyCode || "USD";
+  try {
+    return new Intl.NumberFormat(undefined, { style: "currency", currency }).format(Number(value));
+  } catch {
+    return `${value} ${currency}`;
+  }
+}
+
+export const cartCurrency = (raw: Raw | null | undefined): string =>
+  raw?.customerInfo?.currencyCode ?? raw?.businessInfo?.currencyCode ?? "";
+
+/** The operation to order through: ENABLED, else the default, else the first; null when none exists. */
+export function pickOperationId(operations: Raw[]): string | null {
+  const op = operations.find((o) => o.onlineOrderingStatus === "ENABLED") ?? operations.find((o) => o.default) ?? operations[0];
+  return op ? rawId(op) || null : null;
+}
+
+/** Enabled pickup/delivery methods, for display — fees and minimums as decimal strings. */
+export function toFulfillmentMethods(raws: Raw[]): FulfillmentMethodInfo[] {
+  return raws
+    .filter((m) => m.enabled === true)
+    .map((m): FulfillmentMethodInfo => ({
+      id: rawId(m),
+      type: m.type === "DELIVERY" ? "DELIVERY" : "PICKUP",
+      name: m.name ?? "",
+      fee: m.fee ?? "0",
+      minOrderPrice: m.minOrderPrice ?? "0",
+    }))
+    .filter((m) => m.id);
+}
+
+export function toOrderLine(raw: Raw, currency: string, imgSrc: ImgSrc): OrderLine {
+  return {
+    lineItemId: rawId(raw), // the LINE id — what update/remove take, never the menu item 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: ((raw.attributes?.descriptionLines ?? []) as Raw[])
+      .map((d) => {
+        const label = d.name?.original ?? "", value = d.plainText?.original ?? d.colorInfo?.original ?? "";
+        return label && value ? `${label}: ${value}` : value || label;
+      })
+      .filter(Boolean),
+    status: raw.status ?? "IN_STOCK", // not IN_STOCK → the line can't be checked out as-is
+  };
+}
+
+export function toOrderCart(raw: Raw | null, subtotal: string, imgSrc: ImgSrc): OrderCart {
+  const currency = cartCurrency(raw);
+  const lines = ((raw?.lineItems ?? []) as Raw[]).map((l) => toOrderLine(l, currency, imgSrc));
+  return { lines, itemCount: lines.reduce((n, l) => n + l.quantity, 0), subtotal, currency };
+}
+
+/** The after-discount subtotal from a cart estimate; "" when unknown. Fees, tax, delivery resolve at checkout. */
+export function estimateSubtotal(estimate: Raw | null | undefined, raw: Raw): string {
+  return formatMoney(estimate?.summary?.priceSummary?.subtotal, cartCurrency(raw));
+}
+
+/** The line-refusal reasons an add can't recover from — checked before any call. */
+export function assertOrderContext(itemId: string, menuId: string, sectionId: string): void {
+  if (!itemId || !menuId || !sectionId) throw new Error("addToOrder needs the item, menu, and section ids.");
+}
+
+/**
+ * The one catalogItems entry of an add: the Orders app id and the three context ids — the
+ * restaurant analog of the store's variantId. Modifier/variant selections are NOT sent (that
+ * options shape isn't documented for a client add); quantity only.
+ */
+export function orderCatalogItem(itemId: string, ctx: { operationId: string; menuId: string; sectionId: string }, quantity: number): Raw {
+  return {
+    quantity,
+    catalogReference: {
+      catalogItemId: itemId,
+      appId: RESTAURANTS_ORDERS_APP_ID,
+      options: { operationId: ctx.operationId, menuId: ctx.menuId, sectionId: ctx.sectionId },
+    },
+  };
+}
+
+/** Read the add result — a refused add still returns 200: a line whose status isn't IN_STOCK, or no line, is a refusal. */
+export function assertOrderAdded(cart: Raw | null | undefined, itemId: string): void {
+  // V2 nests the reference under `source` — a top-level lineItem.catalogReference no longer exists.
+  const line = ((cart?.lineItems ?? []) as Raw[]).find((l) => l.source?.catalogReference?.catalogItemId === itemId);
+  if (line?.status && line.status !== "IN_STOCK") {
+    throw new Error(`This dish isn't available right now (${String(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.");
+  }
+}
+
+/** Refuse checkout for an empty order or any line not IN_STOCK — say which. */
+export function assertOrderCheckoutable(raw: Raw | null): void {
+  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) {
+    throw new Error(`Some dishes are no longer available: ${unavailable.map((l) => l.name?.original).filter(Boolean).join(", ")}.`);
+  }
+  if (!rawId(raw)) throw new Error("Checkout couldn't start: the order has no id.");
+}

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

@@ -1,13 +1,13 @@
-// 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:
+// Online ordering (Restaurants Orders + Wix eCom Cart V2) over the SDK — the only file that
+// touches the raw cart and operation entities on this transport. Rules and mappers live in
+// ./ordering-core (shared with the REST twin in references/restaurants/rest/); this file is the
+// transport only. 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).
+//   - options MUST carry operationId + menuId + sectionId (all three) — no variantId;
+//   - modifier/variant selections are NOT sent on the line (undocumented for a client add).
 // Failures are loud: throws on a missing ordering operation, unavailable lines, and an empty
-// cart at checkout — surface the message, don't swallow it.
+// order 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
@@ -20,8 +20,22 @@ 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";
+import {
+  RESTAURANTS_ORDERS_APP_ID,
+  assertOrderAdded,
+  assertOrderCheckoutable,
+  assertOrderContext,
+  estimateSubtotal,
+  orderCatalogItem,
+  pickOperationId,
+  rawId,
+  toFulfillmentMethods,
+  toOrderCart,
+} from "./ordering-core";
+import type { Raw } from "./menu-core";
+import type { FulfillmentMethodInfo, OrderCart } from "./types";
+
+export { RESTAURANTS_ORDERS_APP_ID };
 
 const operationsApi = wixModule(operationsModule);
 const fulfillmentApi = wixModule(fulfillmentModule);
@@ -29,11 +43,6 @@ 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;
 
@@ -44,12 +53,7 @@ let operationIdPromise: Promise<string | null> | null = null;
 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;
-    })
+    .then((res: Raw) => pickOperationId(res.operations ?? []))
     .catch(() => {
       operationIdPromise = null; // transient failure — allow a retry on the next call
       return null;
@@ -61,34 +65,24 @@ export function resolveOperationId(): Promise<string | null> {
 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);
+    return toFulfillmentMethods(res.fulfillmentMethods ?? []);
   } 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.
+// A line's attributes.image may come back absent — join the menu items' images 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> {
+async function fillLineImages(cart: OrderCart, raws: Raw[]): Promise<void> {
   const wanted = new Map<string, number[]>(); // itemId -> line indexes
-  raws.forEach((raw: Raw, i: number) => {
-    if (lines[i].imageUrl) return;
+  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) {
-      lines[i].imageUrl = cached;
+      cart.lines[i].imageUrl = cached;
       return;
     }
     wanted.set(itemId, [...(wanted.get(itemId) ?? []), i]);
@@ -98,62 +92,27 @@ async function fillLineImages(lines: OrderLine[], raws: Raw[]): Promise<void> {
     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;
+      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 */
   }
 }
 
-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, "");
+  // Only estimate a cart WITH lines — on an absent/empty cart the endpoint returns 404.
+  if (!raw?.lineItems?.length) return toOrderCart(raw, "", imgSrc);
   // 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));
+    subtotal = estimateSubtotal(await cartApi.estimateCurrentCart(), 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[]);
+  const cart = toOrderCart(raw, subtotal, imgSrc);
+  await fillLineImages(cart, raw.lineItems as Raw[]);
   return cart;
 }
 
@@ -163,7 +122,7 @@ export async function fetchOrderCart(): Promise<OrderCart> {
     const { cart } = await cartApi.getCurrentCart();
     return readCartWithSubtotal(cart as Raw);
   } catch {
-    return toCart(null, "");
+    return toOrderCart(null, "", imgSrc);
   }
 }
 
@@ -179,31 +138,11 @@ export async function addToOrder(
 ): 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.");
-
+  assertOrderContext(itemId, menuId, sectionId);
   const { cart } = await cartApi.addLineItemsToCurrentCart({
-    catalogItems: [
-      {
-        quantity,
-        catalogReference: {
-          catalogItemId: itemId,
-          appId: RESTAURANTS_ORDERS_APP_ID,
-          options: { operationId, menuId, sectionId },
-        },
-      },
-    ],
+    catalogItems: [orderCatalogItem(itemId, { operationId, menuId, sectionId }, quantity)],
   });
-
-  // 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.");
-  }
+  assertOrderAdded(cart as Raw, itemId);
   return readCartWithSubtotal(cart as Raw);
 }
 
@@ -231,18 +170,10 @@ export async function removeOrderLine(lineItemId: string): Promise<OrderCart> {
 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.");
-
+  assertOrderCheckoutable(raw);
   const origin = typeof window !== "undefined" ? window.location.origin : "";
   const session = await redirects.createRedirectSession({
-    ecomCheckout: { checkoutId: raw._id },
+    ecomCheckout: { checkoutId: rawId(raw) },
     callbacks: {
       postFlowUrl: origin ? `${origin}/` : undefined,
       thankYouPageUrl: origin ? `${origin}/` : undefined,

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

@@ -0,0 +1,193 @@
+// The table-reservation state machine as a framework-free store — the logic behind useReservation,
+// usable from React (useReservation wraps it), from a static page or Vue/Svelte, or as the
+// specification for a port. Location, date + party size, AVAILABLE slots, the 10-minute hold, the
+// details form, and confirm. All correctness (AVAILABLE-only slots, hold → reserve with the
+// revision, firstName + E.164 phone, RESERVED vs REQUESTED) lives in the data layer; this store
+// orchestrates. Browser-only: availability is timezone-specific. One store per mounted surface:
+// createReservationStore(), `start()` when mounted.
+import { completeReservation, fetchReservationLocations, fetchReservationSlots, holdReservation } from "./reservations";
+import type { ReservationConfirmation, ReservationHold, ReservationLocationInfo, ReservationReservee, ReservationSlot } from "./types";
+
+const todayKey = (): string => {
+  const d = new Date();
+  const pad = (n: number) => String(n).padStart(2, "0");
+  return `${d.getFullYear()}-${pad(d.getMonth() + 1)}-${pad(d.getDate())}`;
+};
+
+/** Everything a reservation surface renders from. Read it with getState() or through a subscription. */
+export interface ReservationState {
+  /** null while loading; [] when Table Reservations isn't set up (honest empty state). */
+  locations: ReservationLocationInfo[] | null;
+  /** The active location (default first). Render a picker only when locations.length > 1. */
+  location: ReservationLocationInfo | null;
+  /** "YYYY-MM-DD" for a date input. */
+  date: string;
+  /** "HH:mm" anchor for the slot fan-out. */
+  time: string;
+  /** Clamped to the location's partySizeMin/Max. */
+  partySize: number;
+  /** AVAILABLE slots for the current query; null until findSlots ran. */
+  slots: ReservationSlot[] | null;
+  /** Set after holdSlot — the visitor has 10 minutes to confirm. */
+  held: ReservationHold | null;
+  reservee: ReservationReservee;
+  /** True when a slot is held and firstName + phone are filled — gate the confirm CTA. */
+  canConfirm: boolean;
+  /** Set on success. REQUESTED → tell the visitor approval is pending, not confirmed. */
+  confirmed: ReservationConfirmation | null;
+  loading: boolean;
+  error: string | null;
+}
+
+export interface ReservationStore {
+  getState(): ReservationState;
+  subscribe(listener: () => void): () => void;
+  /** Load the locations. Call once when mounted (a browser). */
+  start(): void;
+  stop(): void;
+  setLocationId(id: string): void;
+  setDate(date: string): void;
+  setTime(time: string): void;
+  setPartySize(size: number): void;
+  findSlots(): Promise<void>;
+  holdSlot(slot: ReservationSlot): Promise<void>;
+  setReserveeField(field: keyof ReservationReservee, value: string): void;
+  confirm(): Promise<void>;
+  /** Back to slot picking (keeps date/party). */
+  reset(): void;
+}
+
+export function createReservationStore(): ReservationStore {
+  let locations: ReservationLocationInfo[] | null = null;
+  let locationId: string | null = null;
+  let date = todayKey();
+  let time = "19:00";
+  let partySize = 2;
+  let slots: ReservationSlot[] | null = null;
+  let held: ReservationHold | null = null;
+  let reservee: ReservationReservee = { firstName: "", phone: "" };
+  let confirmed: ReservationConfirmation | null = null;
+  let loading = false;
+  let error: string | null = null;
+  let started = false;
+  const listeners = new Set<() => void>();
+  let snapshot: ReservationState | null = null;
+  const emit = () => {
+    snapshot = null;
+    for (const fn of listeners) fn();
+  };
+
+  const currentLocation = (): ReservationLocationInfo | null => locations?.find((l) => l.id === locationId) ?? locations?.[0] ?? null;
+
+  function getState(): ReservationState {
+    if (snapshot) return snapshot;
+    snapshot = {
+      locations,
+      location: currentLocation(),
+      date,
+      time,
+      partySize,
+      slots,
+      held,
+      reservee,
+      canConfirm: !!held && reservee.firstName.trim().length > 0 && reservee.phone.trim().length > 0 && !loading,
+      confirmed,
+      loading,
+      error,
+    };
+    return snapshot;
+  }
+
+  const fail = (e: unknown) => (e instanceof Error ? e.message : String(e));
+
+  return {
+    getState,
+    subscribe(fn) {
+      listeners.add(fn);
+      return () => listeners.delete(fn);
+    },
+    start() {
+      if (started) return;
+      started = true;
+      fetchReservationLocations()
+        .then((locs) => {
+          if (!started) return;
+          locations = locs;
+          locationId ??= locs[0]?.id ?? null;
+          emit();
+        })
+        .catch((e) => {
+          if (!started) return;
+          locations = [];
+          error = fail(e);
+          emit();
+        });
+    },
+    stop() {
+      started = false;
+    },
+    setLocationId(id) { locationId = id; emit(); },
+    setDate(next) { date = next; emit(); },
+    setTime(next) { time = next; emit(); },
+    setPartySize(size) {
+      const loc = currentLocation();
+      const min = loc?.partySizeMin ?? 1;
+      const max = loc?.partySizeMax ?? 20;
+      partySize = Math.min(Math.max(size, min), max);
+      emit();
+    },
+    async findSlots() {
+      const loc = currentLocation();
+      if (!loc) return;
+      error = null; slots = null; held = null; confirmed = null; loading = true;
+      emit();
+      try {
+        const aroundIso = new Date(`${date}T${time}:00`).toISOString();
+        slots = await fetchReservationSlots(loc.id, aroundIso, partySize);
+      } catch (e) {
+        slots = [];
+        error = fail(e);
+      } finally {
+        loading = false;
+        emit();
+      }
+    },
+    async holdSlot(slot) {
+      const loc = currentLocation();
+      if (!loc) return;
+      error = null; loading = true;
+      emit();
+      try {
+        held = await holdReservation(loc.id, slot.startIso, partySize);
+      } catch (e) {
+        error = fail(e);
+      } finally {
+        loading = false;
+        emit();
+      }
+    },
+    setReserveeField(field, value) {
+      reservee = { ...reservee, [field]: value };
+      emit();
+    },
+    async confirm() {
+      if (!held) return;
+      error = null; loading = true;
+      emit();
+      try {
+        confirmed = await completeReservation(held, reservee);
+      } catch (e) {
+        // An expired hold can't be reserved — send the visitor back to slot picking.
+        error = fail(e);
+        held = null;
+      } finally {
+        loading = false;
+        emit();
+      }
+    },
+    reset() {
+      held = null; confirmed = null; slots = null; error = null;
+      emit();
+    },
+  };
+}

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

@@ -0,0 +1,94 @@
+// Table-reservation rules and DTO mapping — transport-agnostic, imported by both
+// ./reservations.ts (SDK) and the REST twin in references/restaurants/rest/reservations.ts (fetch).
+// 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. Raw entities carry `_id` (SDK)
+// or `id` (REST); slot dates arrive as Date (SDK) or ISO string (REST). Imports are type-only.
+import type {
+  ReservationConfirmation,
+  ReservationHold,
+  ReservationLocationInfo,
+  ReservationReservee,
+  ReservationSlot,
+} from "./types";
+import type { Raw } from "./menu-core";
+
+export const rawId = (raw: Raw | undefined | null): string => raw?._id ?? raw?.id ?? "";
+
+export function toLocation(raw: Raw): ReservationLocationInfo {
+  const online = raw.configuration?.onlineReservations ?? {};
+  return {
+    id: rawId(raw),
+    default: raw.default === true,
+    partySizeMin: online.partySize?.min ?? 1,
+    partySizeMax: online.partySize?.max ?? 20,
+    approvalMode: online.approval?.mode ?? "AUTOMATIC",
+    onlineReservationsEnabled: online.onlineReservationsEnabled === true,
+  };
+}
+
+/** Active (non-archived) locations, default first. `onlineReservationsEnabled: false` → the premium-gated toggle is off. */
+export function toLocations(raws: Raw[]): ReservationLocationInfo[] {
+  return raws
+    .filter((l) => l.archived !== true)
+    .map(toLocation)
+    .filter((l) => l.id)
+    .sort((a, b) => Number(b.default) - Number(a.default));
+}
+
+export 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 slots only — UNAVAILABLE and NON_WORKING_HOURS are dropped (offering them makes the hold fail). */
+export function availableSlots(raws: Raw[]): ReservationSlot[] {
+  return raws.filter((s) => s.status === "AVAILABLE").map(toSlot);
+}
+
+/** The hold's { reservationId, revision } that completeReservation NEEDS; throws when the slot wasn't held. */
+export function toHold(res: Raw | null | undefined, startIso: string, partySize: number): ReservationHold {
+  const reservationId = rawId(res?.reservation);
+  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: String(revision), startIso, partySize };
+}
+
+/** The reservee body of a reserve: firstName + phone (E.164) REQUIRED, trimmed; optional fields only when filled. */
+export function reserveeBody(reservee: ReservationReservee): Raw {
+  if (!reservee.firstName?.trim() || !reservee.phone?.trim()) {
+    throw new Error("First name and phone number are required.");
+  }
+  return {
+    firstName: reservee.firstName.trim(),
+    phone: reservee.phone.trim(),
+    ...(reservee.lastName?.trim() ? { lastName: reservee.lastName.trim() } : {}),
+    ...(reservee.email?.trim() ? { email: reservee.email.trim() } : {}),
+  };
+}
+
+/** RESERVED = confirmed; REQUESTED = pending approval. Throws when the hold expired (no reservation back). */
+export function toConfirmation(res: Raw | null | undefined): ReservationConfirmation {
+  const reservation = res?.reservation;
+  const reservationId = rawId(reservation);
+  if (!reservationId) {
+    throw new Error("The reservation couldn't be completed — the hold may have expired. Start over.");
+  }
+  return { reservationId, status: reservation.status === "REQUESTED" ? "REQUESTED" : "RESERVED" };
+}