@wix/agent-skills 1.26.0 → 1.28.0

package/skills/wix-headless-templates/restaurants/project/src/wix/restaurants/reservation-store.ts

@@ -0,0 +1,279 @@
+// 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 (in the LOCATION's timezone), AVAILABLE
+// slots, then one of two paths Wix's own code takes: AUTOMATIC approval → a 10-minute hold with a
+// countdown → the details form → reserve; MANUAL approval (or a large party) → the details form →
+// one createReservation, no hold. All correctness (AVAILABLE-only slots, hold → reserve with the
+// revision, the form rules from the location's configuration, the real status) lives in the data
+// layer; this store orchestrates. Browser-only: availability is time-specific. One store per
+// mounted surface: createReservationStore(), `start()` when mounted, `stop()` when unmounted.
+import { completeReservation, fetchReservationLocations, fetchReservationSlots, holdReservation, requestReservation } from "./reservations";
+import { holdSecondsLeft as secondsLeft, resolveApproval, validateReservee } from "./reservations-core";
+import { zonedDayKey, zonedIso } from "./time-core";
+import type { ReservationConfirmation, ReservationHold, ReservationLocationInfo, ReservationReservee, ReservationSlot } from "./types";
+
+/** 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" in the location's timezone, for a date input. */
+  date: string;
+  /** "HH:mm" anchor for the slot fan-out, wall clock at the restaurant. */
+  time: string;
+  /** Clamped to the location's partySizeMin/Max. */
+  partySize: number;
+  /** How this party at this location is approved: AUTOMATIC → hold then reserve; MANUAL → request, pending approval. */
+  approval: "AUTOMATIC" | "MANUAL";
+  /** AVAILABLE slots for the current query; null until findSlots ran. */
+  slots: ReservationSlot[] | null;
+  /** The slot the visitor picked (both paths) — render the details form when set. */
+  selectedSlot: ReservationSlot | null;
+  /** Set after a successful hold (AUTOMATIC path only) — the visitor has 10 minutes to confirm. */
+  held: ReservationHold | null;
+  /** Seconds until the hold lapses, ticking; null when nothing is held. */
+  holdSecondsLeft: number | null;
+  reservee: ReservationReservee;
+  /** Validation messages per field (firstName, lastName, phone, email, custom:<id>) against the location's form; {} when valid. */
+  fieldErrors: Record<string, string>;
+  /** True when a slot is picked (and held, on the AUTOMATIC path), the form validates, and nothing is in flight — gate the CTA. */
+  canConfirm: boolean;
+  /** Set on success. Only outcome "confirmed" is a confirmed table; "pending" awaits the restaurant. */
+  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>;
+  /** Pick a slot: AUTOMATIC approval holds it for 10 minutes; MANUAL approval just selects it (no hold). Then render the form. */
+  holdSlot(slot: ReservationSlot): Promise<void>;
+  setReserveeField(field: "firstName" | "lastName" | "phone" | "email", value: string): void;
+  setMarketingConsent(value: boolean): void;
+  setCustomField(id: string, value: string): void;
+  /** Reserve the held slot, or send the approval request — by `approval`. */
+  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 = zonedDayKey(new Date(), "");
+  let time = "19:00";
+  let partySize = 2;
+  let slots: ReservationSlot[] | null = null;
+  let selectedSlot: ReservationSlot | null = null;
+  let held: ReservationHold | null = null;
+  let holdSecondsLeft: number | null = null;
+  let reservee: ReservationReservee = { firstName: "", phone: "", lastName: "", email: "", customFields: {} };
+  let confirmed: ReservationConfirmation | null = null;
+  let loading = false;
+  let error: string | null = null;
+  let started = false;
+  let timer: ReturnType<typeof setInterval> | null = null;
+  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;
+  const approvalFor = (loc: ReservationLocationInfo | null): "AUTOMATIC" | "MANUAL" => (loc ? resolveApproval(loc, partySize) : "AUTOMATIC");
+
+  const clearTimer = () => {
+    if (timer) clearInterval(timer);
+    timer = null;
+    holdSecondsLeft = null;
+  };
+  const startTimer = () => {
+    clearTimer();
+    if (!held) return;
+    holdSecondsLeft = secondsLeft(held);
+    timer = setInterval(() => {
+      if (!held) return clearTimer();
+      holdSecondsLeft = secondsLeft(held);
+      if (holdSecondsLeft <= 0) {
+        // The hold lapsed: the reservation can't be reserved any more — back to slot picking.
+        held = null; selectedSlot = null; clearTimer();
+        error = "The hold expired — pick a time again.";
+      }
+      emit();
+    }, 1000);
+  };
+
+  /** Apply a (new) location: date in its zone, party clamped to its bounds, the form's defaults. */
+  const adoptLocation = (loc: ReservationLocationInfo | null) => {
+    if (!loc) return;
+    date = zonedDayKey(new Date(), loc.timeZone);
+    partySize = Math.min(Math.max(partySize, loc.partySizeMin), Math.max(loc.partySizeMax, loc.partySizeMin));
+    reservee = { ...reservee, marketingConsent: loc.form.marketingCheckbox ? loc.form.marketingCheckbox.checkedByDefault : undefined };
+  };
+
+  function getState(): ReservationState {
+    if (snapshot) return snapshot;
+    const location = currentLocation();
+    const approval = approvalFor(location);
+    const check = location ? validateReservee(reservee, location.form) : { ok: false, errors: {} };
+    const picked = approval === "MANUAL" ? !!selectedSlot : !!held;
+    snapshot = {
+      locations,
+      location,
+      date,
+      time,
+      partySize,
+      approval,
+      slots,
+      selectedSlot,
+      held,
+      holdSecondsLeft,
+      reservee,
+      fieldErrors: check.errors,
+      canConfirm: picked && check.ok && !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;
+          adoptLocation(currentLocation());
+          emit();
+        })
+        .catch((e) => {
+          if (!started) return;
+          locations = [];
+          error = fail(e);
+          emit();
+        });
+    },
+    stop() {
+      started = false;
+      clearTimer();
+    },
+    setLocationId(id) {
+      if (id === locationId) return;
+      locationId = id;
+      slots = null; selectedSlot = null; held = null; clearTimer();
+      adoptLocation(currentLocation());
+      emit();
+    },
+    setDate(next) { date = next; emit(); },
+    setTime(next) { time = next; emit(); },
+    setPartySize(size) {
+      const loc = currentLocation();
+      const min = loc?.partySizeMin ?? 1;
+      const max = Math.max(loc?.partySizeMax ?? 1, min);
+      partySize = Math.min(Math.max(size, min), max);
+      emit();
+    },
+    async findSlots() {
+      const loc = currentLocation();
+      if (!loc) return;
+      error = null; slots = null; selectedSlot = null; held = null; confirmed = null; loading = true; clearTimer();
+      emit();
+      try {
+        // The anchor is the restaurant's wall clock, not the visitor's.
+        const aroundIso = zonedIso(date, time, loc.timeZone);
+        if (!aroundIso) throw new Error("Pick a date and a time.");
+        slots = await fetchReservationSlots(loc.id, aroundIso, partySize, { timeZone: loc.timeZone });
+      } catch (e) {
+        slots = [];
+        error = fail(e);
+      } finally {
+        loading = false;
+        emit();
+      }
+    },
+    async holdSlot(slot) {
+      const loc = currentLocation();
+      if (!loc) return;
+      error = null;
+      // Manual approval (the location's mode, or the slot says so): no hold — the form leads to a request.
+      if (approvalFor(loc) === "MANUAL" || slot.manualApproval) {
+        selectedSlot = slot; held = null; clearTimer();
+        emit();
+        return;
+      }
+      loading = true;
+      emit();
+      try {
+        held = await holdReservation(loc.id, slot.startIso, partySize);
+        selectedSlot = slot;
+        startTimer();
+      } catch (e) {
+        error = fail(e);
+      } finally {
+        loading = false;
+        emit();
+      }
+    },
+    setReserveeField(field, value) {
+      reservee = { ...reservee, [field]: value };
+      emit();
+    },
+    setMarketingConsent(value) {
+      reservee = { ...reservee, marketingConsent: value };
+      emit();
+    },
+    setCustomField(id, value) {
+      reservee = { ...reservee, customFields: { ...(reservee.customFields ?? {}), [id]: value } };
+      emit();
+    },
+    async confirm() {
+      const loc = currentLocation();
+      if (!loc || !selectedSlot) return;
+      const manual = approvalFor(loc) === "MANUAL" || selectedSlot.manualApproval || !held;
+      if (!manual && !held) return;
+      error = null; loading = true;
+      emit();
+      try {
+        confirmed = manual
+          ? await requestReservation(loc.id, selectedSlot.startIso, partySize, reservee, loc.form)
+          : await completeReservation(held!, reservee, loc.form);
+        held = null; selectedSlot = null; clearTimer();
+      } catch (e) {
+        error = fail(e);
+        // A validation message keeps the form; anything else on the hold path means the hold is gone.
+        if (!manual && !/required|valid|too long|country code/i.test(error)) {
+          held = null; selectedSlot = null; clearTimer();
+        }
+      } finally {
+        loading = false;
+        emit();
+      }
+    },
+    reset() {
+      held = null; selectedSlot = null; confirmed = null; slots = null; error = null; clearTimer();
+      emit();
+    },
+  };
+}

package/skills/wix-headless-templates/restaurants/project/src/wix/restaurants/reservations-core.ts

@@ -0,0 +1,218 @@
+// Table-reservation rules and DTO mapping — transport-agnostic, imported by both
+// ./reservations.ts (SDK) and the REST twin in templates/restaurants/rest/reservations.ts (fetch).
+// The flow is location → slots → (AUTOMATIC approval) hold, then reserve with the visitor's
+// details, or (MANUAL approval) one createReservation with details + reservee and NO hold — the two
+// paths Wix's own reservation code takes. Every instant is computed in the LOCATION's timezone
+// (slot search window, labels, day keys), never the visitor's. A reservation is a hold, not a
+// purchase. Raw entities carry `_id` (SDK) or `id` (REST); dates arrive as Date (SDK) or ISO
+// string (REST). Imports are type-only except the zone helpers from ./time-core.
+import type {
+  ReservationConfirmation,
+  ReservationCustomField,
+  ReservationFormConfig,
+  ReservationHold,
+  ReservationLocationInfo,
+  ReservationPolicy,
+  ReservationReservee,
+  ReservationSlot,
+  ReservationStatus,
+} from "./types";
+import type { Raw } from "./menu-core";
+import { zonedDayKey, zonedTimeLabel } from "./time-core";
+
+export const rawId = (raw: Raw | undefined | null): string => raw?._id ?? raw?.id ?? "";
+
+/** A hold lasts 10 minutes from its creation (Wix's own countdown: 600 s from _createdDate). */
+export const HOLD_SECONDS = 10 * 60;
+
+// ---- locations -----------------------------------------------------------------------------------------------
+
+const toPolicy = (raw: Raw | undefined): ReservationPolicy | null =>
+  raw && raw.enabled !== false && (raw.url || raw.text) ? { url: raw.url ?? "", text: raw.text ?? "" } : null;
+
+/** The owner's form configuration (reservationForm) → what to render and what to require. */
+export function toFormConfig(raw: Raw | undefined): ReservationFormConfig {
+  const f: Raw = raw ?? {};
+  return {
+    lastNameRequired: f.lastNameRequired === true,
+    emailRequired: f.emailRequired === true,
+    marketingCheckbox: f.emailMarketingCheckbox?.enabled === true ? { checkedByDefault: f.emailMarketingCheckbox.checkedByDefault === true } : null,
+    customFields: ((f.customFieldDefinitions ?? []) as Raw[])
+      .map((d): ReservationCustomField => ({ id: rawId(d), name: d.name ?? "", required: d.required === true }))
+      .filter((d) => d.id),
+    terms: toPolicy(f.termsAndConditions),
+    privacy: toPolicy(f.privacyPolicy),
+    submitMessage: f.submitMessage ?? "",
+  };
+}
+
+export function toLocation(raw: Raw): ReservationLocationInfo {
+  const online: Raw = raw.configuration?.onlineReservations ?? {};
+  const approval: Raw = online.approval ?? {};
+  const mode = approval.mode === "MANUAL" || approval.mode === "MANUAL_FOR_LARGE_PARTIES" ? approval.mode : "AUTOMATIC";
+  const threshold = approval.manualForLargePartiesOptions?.partySizeThreshold;
+  return {
+    id: rawId(raw),
+    name: raw.location?.name ?? "",
+    address: raw.location?.address?.formatted ?? "",
+    timeZone: raw.location?.timeZone ?? "",
+    default: raw.default === true,
+    partySizeMin: online.partySize?.min ?? 1,
+    partySizeMax: online.partySize?.max ?? 1, // Wix's default when the owner set no maximum
+    approvalMode: mode,
+    manualApprovalPartySizeThreshold: mode === "MANUAL_FOR_LARGE_PARTIES" && typeof threshold === "number" ? threshold : null,
+    onlineReservationsEnabled: online.onlineReservationsEnabled === true,
+    form: toFormConfig(raw.configuration?.reservationForm),
+  };
+}
+
+/**
+ * The locations to offer, Wix's rule: only those with online reservations ENABLED (the default
+ * one first when it is enabled); when none is enabled, only the default location, so the surface
+ * can say "online reservations aren't open" instead of listing dead options. [] when none exist.
+ */
+export function toLocations(raws: Raw[]): ReservationLocationInfo[] {
+  const all = raws.filter((l) => l.archived !== true).map(toLocation).filter((l) => l.id);
+  const enabled = all.filter((l) => l.onlineReservationsEnabled);
+  if (enabled.length) return enabled.sort((a, b) => Number(b.default) - Number(a.default));
+  const def = all.find((l) => l.default);
+  return def ? [def] : [];
+}
+
+/** AUTOMATIC → hold then reserve; MANUAL → one createReservation, no hold (also MANUAL_FOR_LARGE_PARTIES from the threshold up). */
+export function resolveApproval(location: Pick<ReservationLocationInfo, "approvalMode" | "manualApprovalPartySizeThreshold">, partySize: number): "AUTOMATIC" | "MANUAL" {
+  if (location.approvalMode === "MANUAL") return "MANUAL";
+  if (location.approvalMode === "MANUAL_FOR_LARGE_PARTIES" && partySize >= (location.manualApprovalPartySizeThreshold ?? 0)) return "MANUAL";
+  return "AUTOMATIC";
+}
+
+// ---- slots ----------------------------------------------------------------------------------------------------------
+
+const toDate = (v: unknown): Date => (v instanceof Date ? v : new Date(String(v)));
+
+/** A raw slot → DTO with its label and day key in the LOCATION's timezone. */
+export function toSlot(raw: Raw, timeZone: string): ReservationSlot {
+  const start = toDate(raw.startDate);
+  return {
+    startIso: start.toISOString(),
+    label: zonedTimeLabel(start, timeZone),
+    dayKey: zonedDayKey(start, timeZone),
+    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[], timeZone: string): ReservationSlot[] {
+  return raws.filter((s) => s.status === "AVAILABLE").map((s) => toSlot(s, timeZone));
+}
+
+// ---- hold ------------------------------------------------------------------------------------------------------------
+
+/** The hold's { reservationId, revision } that completeReservation NEEDS, plus its expiry; 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.");
+  }
+  const created = res?.reservation?._createdDate ?? res?.reservation?.createdDate;
+  const createdMs = created ? toDate(created).getTime() : NaN;
+  const expiresAt = new Date((Number.isFinite(createdMs) ? createdMs : Date.now()) + HOLD_SECONDS * 1000);
+  return { reservationId, revision: String(revision), startIso, partySize, expiresAtIso: expiresAt.toISOString() };
+}
+
+/** Whole seconds until the hold lapses (0 when it has). */
+export function holdSecondsLeft(hold: Pick<ReservationHold, "expiresAtIso">, now: Date = new Date()): number {
+  return Math.max(0, Math.ceil((new Date(hold.expiresAtIso).getTime() - now.getTime()) / 1000));
+}
+
+// ---- reservee form ------------------------------------------------------------------------------------------
+
+const STRING_LIMIT = 200; // Wix's COMMON_STRING_LIMIT: every text field shorter than this
+const EMAIL = /^(([^<>()[\].,;:\s@"]+(\.[^<>()[\].,;:\s@"]+)*)|(".+"))@(([^<>()[\].,;:\s@"]+\.)+[^<>()[\].,;:\s@"]{2,})$/i;
+// E.164-shaped after stripping formatting: optional +, 7-15 digits, no leading 0 (no libphonenumber dependency).
+const PHONE = /^\+?[1-9]\d{6,14}$/;
+
+const okString = (value: string | undefined, required: boolean): boolean => {
+  const v = (value ?? "").trim();
+  if (!v) return !required;
+  return v.length < STRING_LIMIT;
+};
+
+/** The visitor's phone with spaces, dashes, dots, and parentheses removed — what gets validated and sent. */
+export const normalizePhone = (phone: string | undefined): string => (phone ?? "").replace(/[\s().-]/g, "");
+
+/**
+ * Validate the reservee against the location's form config, Wix's rules: firstName and phone
+ * always required; lastName/email per config; email by pattern; phone E.164-shaped; every text
+ * under 200 characters; each required custom field filled. Empty `errors` means submittable.
+ */
+export function validateReservee(reservee: ReservationReservee, form: ReservationFormConfig): { ok: boolean; errors: Record<string, string> } {
+  const errors: Record<string, string> = {};
+  if (!okString(reservee.firstName, true)) errors.firstName = "First name is required.";
+  if (!okString(reservee.lastName, form.lastNameRequired)) errors.lastName = form.lastNameRequired ? "Last name is required." : "Last name is too long.";
+  const phone = normalizePhone(reservee.phone);
+  if (!phone) errors.phone = "Phone number is required.";
+  else if (!PHONE.test(phone)) errors.phone = "Enter a phone number with its country code, e.g. +15551234567.";
+  const email = (reservee.email ?? "").trim();
+  if (!email && form.emailRequired) errors.email = "Email is required.";
+  else if (email && !(EMAIL.test(email) && email.length < STRING_LIMIT)) errors.email = "Enter a valid email address.";
+  for (const f of form.customFields) {
+    if (!okString(reservee.customFields?.[f.id], f.required)) errors[`custom:${f.id}`] = f.required ? `${f.name || "This field"} is required.` : `${f.name || "This field"} is too long.`;
+  }
+  return { ok: Object.keys(errors).length === 0, errors };
+}
+
+/**
+ * The reservee body of a reserve/create: validated against the form, trimmed, optional fields
+ * only when filled, `marketingConsent` only when the form shows the checkbox, `customFields` as
+ * { id: answer } for the filled ones. Throws the first validation message.
+ */
+export function reserveeBody(reservee: ReservationReservee, form: ReservationFormConfig): Raw {
+  const check = validateReservee(reservee, form);
+  if (!check.ok) throw new Error(Object.values(check.errors)[0]);
+  const customFields = Object.fromEntries(
+    form.customFields.map((f) => [f.id, (reservee.customFields?.[f.id] ?? "").trim()]).filter(([, v]) => v),
+  );
+  return {
+    firstName: reservee.firstName.trim(),
+    phone: normalizePhone(reservee.phone),
+    ...(reservee.lastName?.trim() ? { lastName: reservee.lastName.trim() } : {}),
+    ...(reservee.email?.trim() ? { email: reservee.email.trim() } : {}),
+    ...(form.marketingCheckbox ? { marketingConsent: reservee.marketingConsent === true } : {}),
+    ...(Object.keys(customFields).length ? { customFields } : {}),
+  };
+}
+
+/** The body of a MANUAL-approval createReservation: details + reservee, no hold. */
+export function reservationBody(locationId: string, startIso: string, partySize: number, reservee: ReservationReservee, form: ReservationFormConfig): Raw {
+  if (!locationId || !startIso || !partySize) throw new Error("Pick a time before sending the request.");
+  return {
+    details: { reservationLocationId: locationId, startDate: startIso, partySize },
+    reservee: reserveeBody(reservee, form),
+  };
+}
+
+// ---- outcome -------------------------------------------------------------------------------------------------------
+
+const STATUSES: ReservationStatus[] = ["HELD", "RESERVED", "REQUESTED", "PAYMENT_INFORMATION_PENDING", "CANCELED", "DECLINED", "FINISHED", "NO_SHOW", "SEATED"];
+
+/** RESERVED is the only confirmed status; REQUESTED and PAYMENT_INFORMATION_PENDING are pending; the rest are other. */
+export function confirmationOutcome(status: ReservationStatus): ReservationConfirmation["outcome"] {
+  if (status === "RESERVED") return "confirmed";
+  if (status === "REQUESTED" || status === "PAYMENT_INFORMATION_PENDING") return "pending";
+  return "other";
+}
+
+/** The API's real status, unmapped. Throws when no reservation came back (an expired hold). */
+export function toConfirmation(res: Raw | null | undefined): ReservationConfirmation {
+  const reservation: Raw | undefined = res?.reservation;
+  const reservationId = rawId(reservation);
+  if (!reservationId) {
+    throw new Error("The reservation couldn't be completed — the hold may have expired. Start over.");
+  }
+  const raw = String(reservation?.status ?? "");
+  const status: ReservationStatus = (STATUSES as string[]).includes(raw) ? (raw as ReservationStatus) : "UNKNOWN";
+  return { reservationId, status, outcome: confirmationOutcome(status) };
+}

package/skills/wix-headless-templates/restaurants/project/src/wix/restaurants/reservations.ts

@@ -0,0 +1,109 @@
+// Table reservations (@wix/table-reservations) over the SDK — the only file that touches raw
+// reservation entities on this transport. Rules and mappers live in ./reservations-core (shared
+// with the REST twin in templates/restaurants/rest/); this file is the transport only. Copy
+// as-is; extend by calling these exports, never by editing them.
+//
+// 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;
+// createReservation (manual approval, no hold) returns the reservation itself, unwrapped.
+// 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
+// docs: https://dev.wix.com/docs/api-reference/business-solutions/restaurants/reservations/reservations/create-reservation.md
+import { reservationLocations, timeSlots, reservations as reservationsModule } from "@wix/table-reservations";
+import { wixModule } from "../sdk";
+import { availableSlots, reservationBody, reserveeBody, toConfirmation, toHold, toLocations } from "./reservations-core";
+import type { Raw } from "./menu-core";
+import type {
+  ReservationConfirmation,
+  ReservationFormConfig,
+  ReservationHold,
+  ReservationLocationInfo,
+  ReservationReservee,
+  ReservationSlot,
+} from "./types";
+
+const locationsApi = wixModule(reservationLocations);
+const timeSlotsApi = wixModule(timeSlots);
+const reservationsApi = wixModule(reservationsModule);
+
+/**
+ * The reservation locations to offer: those with online reservations ENABLED (default first),
+ * or only the default one when none is enabled — then `onlineReservationsEnabled: false` means
+ * the premium-gated toggle is off and the surface renders an honest "reservations aren't open
+ * yet" state. [] when Table Reservations isn't set up. Each carries its name, address, timezone,
+ * approval rule, and the owner's form configuration.
+ */
+export async function fetchReservationLocations(): Promise<ReservationLocationInfo[]> {
+  const res: Raw = await locationsApi.listReservationLocations();
+  return toLocations(res.reservationLocations ?? []);
+}
+
+/**
+ * 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 (build it in the location's zone with `zonedIso`);
+ * `timeZone` is the location's — labels and day keys are computed in it.
+ */
+export async function fetchReservationSlots(
+  locationId: string,
+  aroundIso: string,
+  partySize: number,
+  { timeZone = "", slotsBefore = 6, slotsAfter = 6 }: { timeZone?: string; 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 availableSlots(res.timeSlots ?? [], timeZone);
+}
+
+/**
+ * Hold a slot for 10 minutes while the visitor enters their details (AUTOMATIC approval only).
+ * The returned hold carries the { reservationId, revision } that completeReservation NEEDS —
+ * keep both — and `expiresAtIso` for a countdown.
+ */
+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,
+  });
+  return toHold(res, startIso, partySize);
+}
+
+/**
+ * Complete a held reservation with the visitor's details, validated against the location's
+ * `form` (firstName + phone always; lastName/email/custom fields as configured). A hold expires
+ * after 10 minutes — on failure, start a fresh hold; never try to update a HELD reservation by
+ * other means. The outcome carries the API's real status.
+ */
+export async function completeReservation(
+  hold: Pick<ReservationHold, "reservationId" | "revision">,
+  reservee: ReservationReservee,
+  form: ReservationFormConfig,
+): Promise<ReservationConfirmation> {
+  const body = reserveeBody(reservee, form);
+  const res: Raw = await reservationsApi.reserveReservation(hold.reservationId, body as any, hold.revision);
+  return toConfirmation(res);
+}
+
+/**
+ * Request a reservation that needs the restaurant's approval (MANUAL, or a large party under
+ * MANUAL_FOR_LARGE_PARTIES): ONE createReservation with details + reservee, no hold — the path
+ * Wix's own reservation code takes. The outcome is normally REQUESTED (pending), never confirmed.
+ */
+export async function requestReservation(
+  locationId: string,
+  startIso: string,
+  partySize: number,
+  reservee: ReservationReservee,
+  form: ReservationFormConfig,
+): Promise<ReservationConfirmation> {
+  const body = reservationBody(locationId, startIso, partySize, reservee, form);
+  const reservation: Raw = await reservationsApi.createReservation({
+    details: { ...body.details, startDate: new Date(startIso) },
+    reservee: body.reservee,
+  } as any);
+  return toConfirmation({ reservation });
+}