@wix/agent-skills 1.26.0 → 1.27.0

package/skills/wix-headless-templates/bookings/project/src/wix/bookings/booking-flow-store.ts

@@ -0,0 +1,410 @@
+// The whole booking state machine for one service as a framework-free store — the logic behind
+// useBookingFlow, usable from React (useBookingFlow wraps it), from a static page's booking surface,
+// from Vue/Svelte, or as the specification for a port: the display time zone (the site's setting),
+// the availability window (day-grouped slots, week paging, optional staff filter, next availability),
+// a course's seats and dates, a class's upcoming sessions, participants, deposit choice, add-on
+// selection, the schema-driven form, the CTA state, and book(). All correctness (slot scheduleId vs
+// eventId vs a course's schedule, ANY_RESOURCE, the slot's location, formSubmission, payment option,
+// checkout-or-place) lives in the data layer; this store orchestrates. A late response from a
+// superseded window is dropped. One store per booking surface: createBookingFlowStore(service).
+import {
+  bookService,
+  fetchAddOnGroups,
+  fetchBookingForm,
+  fetchBookingsSettings,
+  fetchCourseAvailability,
+  fetchNextAvailableSlots,
+  fetchOfferedDays,
+  fetchSessions,
+  fetchSlots,
+  resolveDisplayTimeZone,
+} from "./booking";
+import { ctaStateOf } from "./services-core";
+import {
+  addOnsDuration,
+  addOnsTotal,
+  canSelectMore,
+  groupSlotsByDay,
+  maxParticipants,
+  showsNextAvailability,
+  startOfDay,
+  timeZoneLabel,
+  withAddOnQuantity,
+  type AddOnSelection,
+  type BookingDay,
+} from "./booking-core";
+import type { AddOnGroup, BookingFormField, BookingResult, BookingsSettings, CourseAvailability, CtaState, ServiceDetail, Session, Slot, Weekday } from "./types";
+
+export type { BookingDay };
+
+const WINDOW_DAYS = 7;
+const RESOURCE_PARAM = "resource";
+
+/** Everything a booking surface renders from. Read it with getState() or through a subscription. */
+export interface BookingFlowState {
+  /** Slots grouped by day, in order — [{ dayKey, dayLabel, slots }]. null while loading; [] for a COURSE (no slots). */
+  days: BookingDay[] | null;
+  /** The 7-day window start (a day boundary); page with nextWeek/prevWeek (prev clamps to today). */
+  windowStart: Date;
+  /** The next few bookable times beyond the window — what an empty week points at; null while loading, [] when none/not applicable. */
+  nextAvailable: Slot[] | null;
+  /** Staff filter — render a picker only when service.staff.length > 1. Seeded from `?resource=`. */
+  staffId: string | undefined;
+  selectedSlot: Slot | null;
+  /** The IANA zone the shown times are in (the response's), and its label ("Eastern Time (EDT)"); null/"" until known. */
+  timeZone: string | null;
+  timeZoneLabel: string;
+  /** Which zone is in use and whether the owner lets the visitor switch (setDisplayTimeZone). */
+  displayTimeZone: "BUSINESS" | "CUSTOMER";
+  customerCanChangeTimeZone: boolean;
+  /** COURSE only: seats from its sessions (null while loading, once ended, or for other types). */
+  course: CourseAvailability | null;
+  /** Weekdays a class/course meets ("MONDAY"…), from its recurring sessions; [] for appointments or until loaded. */
+  offeredDays: Weekday[];
+  /** Upcoming sessions of a class (or a running course); null while loading, [] for appointments. */
+  sessions: Session[] | null;
+  hasMoreSessions: boolean;
+  /** Seats in this booking and the most allowed (policy / capacity / seats left on the slot). */
+  participants: number;
+  maxParticipants: number;
+  /** Deposit choice: true = pay the deposit now (the default when the service takes one); false = pay in full now. */
+  payDeposit: boolean;
+  /** Add-on groups (empty unless service.hasAddOns), the selection (quantity by add-on id), and its totals. */
+  addOnGroups: AddOnGroup[];
+  addOns: AddOnSelection;
+  /** Formatted extra price of the selected add-ons ("" when none). Shown, not yet booked — see INSTRUCTIONS. */
+  addOnsTotal: string;
+  addOnsMinutes: number;
+  /** Schema-driven form fields (never empty — contact basics fallback). */
+  formFields: BookingFormField[];
+  values: Record<string, string>;
+  /** book / requestToBook / viewCourse — the CTA's label and the confirmed copy follow it. */
+  ctaState: CtaState;
+  /** True when a bookable slot is selected (or the service is a bookable course) and every required field has a value. */
+  canBook: boolean;
+  booking: boolean;
+  /** Set after a free/offline booking completes — the only REAL success signal. */
+  confirmed: BookingResult | null;
+  error: string | null;
+}
+
+export interface BookingFlowStore {
+  getState(): BookingFlowState;
+  subscribe(listener: () => void): () => void;
+  /** Load settings, the first window, next availability, sessions/seats, add-ons, and the form. Call once when mounted (a browser). */
+  start(): void;
+  /** Stop reacting; drop late responses. */
+  stop(): void;
+  nextWeek(): void;
+  prevWeek(): void;
+  /** Move the window to the week holding this day ("YYYY-MM-DD" — a nextAvailable slot's dayKey). */
+  jumpTo(dayKey: string): void;
+  setStaffId(id: string | undefined): void;
+  /** Ignored for a non-bookable slot (full session, policy). */
+  setSelectedSlot(slot: Slot | null): void;
+  /** Only when customerCanChangeTimeZone; reloads the window in the other zone. */
+  setDisplayTimeZone(zone: "BUSINESS" | "CUSTOMER"): void;
+  setParticipants(n: number): void;
+  /** Only meaningful when service.deposit?.fullUpfrontAllowed; otherwise the deposit is mandatory. */
+  setPayDeposit(payDeposit: boolean): void;
+  toggleAddOn(id: string): void;
+  setAddOnQuantity(id: string, quantity: number): void;
+  /** Whether `groupId` accepts another distinct add-on. */
+  canSelectMore(groupId: string): boolean;
+  loadMoreSessions(): Promise<void>;
+  setValue(target: string, value: string): void;
+  /** Books the selected slot (a course: the course). On "redirect" the browser is already navigating; otherwise `confirmed` is set. Rejects with the refusal (also in .error). */
+  book(): Promise<BookingResult>;
+}
+
+const readResourceParam = (): string | undefined => {
+  if (typeof window === "undefined") return undefined;
+  try {
+    return new URL(window.location.href).searchParams.get(RESOURCE_PARAM) || undefined;
+  } catch {
+    return undefined;
+  }
+};
+
+export function createBookingFlowStore(service: ServiceDetail): BookingFlowStore {
+  const isCourse = service.type === "COURSE";
+  let windowStart = startOfDay(new Date());
+  let staffId: string | undefined = readResourceParam();
+  let slots: Slot[] | null = isCourse ? [] : null;
+  let nextAvailable: Slot[] | null = showsNextAvailability(service) ? null : [];
+  let selectedSlot: Slot | null = null;
+  let settings: BookingsSettings = { displayTimeZone: "BUSINESS", customerCanChange: false };
+  let requestZone: string | undefined; // what the requests send; undefined = the business zone
+  let timeZone: string | null = null; // what the response says the times are in
+  let course: CourseAvailability | null = null;
+  let offeredDays: Weekday[] = service.offeredDays;
+  let sessions: Session[] | null = service.type === "APPOINTMENT" ? [] : null;
+  let sessionsCursor: string | null = null;
+  let participants = 1;
+  let payDeposit = !!service.deposit;
+  let addOnGroups: AddOnGroup[] = [];
+  let addOns: AddOnSelection = {};
+  let formFields: BookingFormField[] = [];
+  let values: Record<string, string> = {};
+  let booking = false;
+  let confirmed: BookingResult | null = null;
+  let error: string | null = null;
+  let started = false;
+  let generation = 0;
+  const listeners = new Set<() => void>();
+  let snapshot: BookingFlowState | null = null;
+  const emit = () => {
+    snapshot = null;
+    for (const fn of listeners) fn();
+  };
+
+  const ctaState = (): CtaState => ctaStateOf(service, course?.full ?? false);
+  const formComplete = () => formFields.every((f) => !f.required || (values[f.target] ?? "").trim().length > 0);
+  const zoneForBooking = () => timeZone ?? requestZone ?? undefined;
+
+  function getState(): BookingFlowState {
+    if (snapshot) return snapshot;
+    const cta = ctaState();
+    const target = isCourse ? !service.course?.ended && cta !== "viewCourse" && !!service.scheduleId : !!selectedSlot?.bookable;
+    snapshot = {
+      days: slots === null ? null : groupSlotsByDay(slots),
+      windowStart,
+      nextAvailable,
+      staffId,
+      selectedSlot,
+      timeZone,
+      timeZoneLabel: timeZoneLabel(timeZone, selectedSlot ? new Date(selectedSlot.startLocal) : windowStart),
+      displayTimeZone: settings.displayTimeZone,
+      customerCanChangeTimeZone: settings.customerCanChange,
+      course,
+      offeredDays,
+      sessions,
+      hasMoreSessions: !!sessionsCursor,
+      participants,
+      maxParticipants: maxParticipants(service, selectedSlot),
+      payDeposit,
+      addOnGroups,
+      addOns,
+      addOnsTotal: addOnsTotal(addOnGroups, addOns),
+      addOnsMinutes: addOnsDuration(addOnGroups, addOns),
+      formFields,
+      values,
+      ctaState: cta,
+      canBook: target && formComplete() && !booking,
+      booking,
+      confirmed,
+      error,
+    };
+    return snapshot;
+  }
+
+  // The window, the staff filter, or the zone changed: clear the picker and load the slots for the new selection.
+  function loadSlots(): void {
+    if (!started || isCourse) return;
+    const id = ++generation;
+    slots = null;
+    selectedSlot = null;
+    emit();
+    fetchSlots(service, { from: windowStart, days: WINDOW_DAYS, staffId, timeZone: requestZone })
+      .then((page) => {
+        if (!started || generation !== id) return; // superseded — drop it
+        slots = page.slots;
+        timeZone = page.timeZone ?? requestZone ?? null;
+        emit();
+      })
+      .catch((e) => {
+        if (!started || generation !== id) return;
+        slots = [];
+        error = e instanceof Error ? e.message : String(e);
+        emit();
+      });
+  }
+
+  // Next availability follows the staff filter and the zone, not the window.
+  function loadNextAvailable(): void {
+    if (!started || !showsNextAvailability(service)) return;
+    const id = generation;
+    nextAvailable = null;
+    fetchNextAvailableSlots(service, { staffId, timeZone: requestZone })
+      .then((page) => {
+        if (!started || generation !== id) return;
+        nextAvailable = page.slots;
+        emit();
+      })
+      .catch(() => {
+        if (!started || generation !== id) return;
+        nextAvailable = [];
+        emit();
+      });
+  }
+
+  // Sessions: a class always, a course while it still runs, never an appointment.
+  function loadSessions(): void {
+    const scheduleId = service.scheduleId;
+    if (!started || !scheduleId || service.type === "APPOINTMENT" || (isCourse && service.course?.ended)) {
+      sessions = sessions ?? [];
+      return;
+    }
+    const id = generation;
+    fetchSessions(scheduleId, { timeZone: requestZone }).then((page) => {
+      if (!started || generation !== id) return;
+      sessions = page.sessions;
+      sessionsCursor = page.nextCursor;
+      emit();
+    });
+  }
+
+  // The recurring sessions: the weekdays a class/course meets, and a course's seats.
+  function loadSchedule(): void {
+    if (!started || service.type === "APPOINTMENT" || !service.scheduleId) return;
+    const id = generation;
+    const scheduleId = service.scheduleId;
+    fetchOfferedDays([scheduleId], requestZone).then((days) => {
+      if (!started || generation !== id) return;
+      offeredDays = days[scheduleId] ?? offeredDays;
+      emit();
+    });
+    if (!isCourse) return;
+    fetchCourseAvailability(service, requestZone).then((c) => {
+      if (!started || generation !== id) return;
+      course = c;
+      timeZone = timeZone ?? requestZone ?? null;
+      emit();
+    });
+  }
+
+  function loadForZone(): void {
+    loadSlots();
+    loadNextAvailable();
+    loadSessions();
+    loadSchedule();
+    emit();
+  }
+
+  return {
+    getState,
+    subscribe(fn) {
+      listeners.add(fn);
+      return () => listeners.delete(fn);
+    },
+    start() {
+      if (started) return;
+      started = true;
+      // The zone policy first: everything time-related is requested in the zone the owner chose.
+      fetchBookingsSettings().then((s) => {
+        if (!started) return;
+        settings = s;
+        requestZone = resolveDisplayTimeZone(s);
+        loadForZone();
+      });
+      fetchBookingForm(service.formId).then((f) => { if (started) { formFields = f; emit(); } });
+      if (service.hasAddOns) fetchAddOnGroups(service.id).then((g) => { if (started) { addOnGroups = g; emit(); } });
+    },
+    stop() {
+      started = false;
+      generation++;
+    },
+    nextWeek() {
+      windowStart = new Date(windowStart.getFullYear(), windowStart.getMonth(), windowStart.getDate() + WINDOW_DAYS);
+      loadSlots();
+    },
+    prevWeek() {
+      const today = startOfDay(new Date());
+      const prev = new Date(windowStart.getFullYear(), windowStart.getMonth(), windowStart.getDate() - WINDOW_DAYS);
+      windowStart = prev < today ? today : prev;
+      loadSlots();
+    },
+    jumpTo(dayKey) {
+      const day = new Date(`${dayKey}T12:00:00`);
+      if (Number.isNaN(day.getTime())) return;
+      const today = startOfDay(new Date());
+      const target = startOfDay(day);
+      windowStart = target < today ? today : target;
+      loadSlots();
+    },
+    setStaffId(id) {
+      if (id === staffId) return;
+      staffId = id;
+      loadSlots();
+      loadNextAvailable();
+    },
+    setSelectedSlot(slot) {
+      if (slot && !slot.bookable) return;
+      selectedSlot = slot;
+      participants = Math.min(participants, maxParticipants(service, slot));
+      emit();
+    },
+    setDisplayTimeZone(zone) {
+      if (!settings.customerCanChange || zone === settings.displayTimeZone) return;
+      settings = { ...settings, displayTimeZone: zone };
+      requestZone = resolveDisplayTimeZone(settings);
+      timeZone = null;
+      generation++;
+      loadForZone();
+    },
+    setParticipants(n) {
+      participants = Math.max(1, Math.min(Math.floor(n) || 1, maxParticipants(service, selectedSlot)));
+      emit();
+    },
+    setPayDeposit(v) {
+      if (!service.deposit) return;
+      payDeposit = service.deposit.fullUpfrontAllowed ? v : true;
+      emit();
+    },
+    toggleAddOn(id) {
+      addOns = withAddOnQuantity(addOnGroups, addOns, id, addOns[id] > 0 ? 0 : 1);
+      emit();
+    },
+    setAddOnQuantity(id, quantity) {
+      addOns = withAddOnQuantity(addOnGroups, addOns, id, quantity);
+      emit();
+    },
+    canSelectMore(groupId) {
+      const group = addOnGroups.find((g) => g.id === groupId);
+      return group ? canSelectMore(group, addOns) : false;
+    },
+    async loadMoreSessions() {
+      if (!started || !sessionsCursor || !service.scheduleId) return;
+      const id = generation;
+      const cursor = sessionsCursor;
+      sessionsCursor = null;
+      emit();
+      const page = await fetchSessions(service.scheduleId, { cursor, timeZone: requestZone });
+      if (!started || generation !== id) return;
+      sessions = [...(sessions ?? []), ...page.sessions];
+      sessionsCursor = page.nextCursor;
+      emit();
+    },
+    setValue(target, value) {
+      values = { ...values, [target]: value };
+      emit();
+    },
+    async book() {
+      if (!isCourse && !selectedSlot) throw new Error("Pick a time first.");
+      if (isCourse && ctaState() === "viewCourse") throw new Error("This course can't be booked anymore.");
+      booking = true;
+      error = null;
+      emit();
+      try {
+        const result = await bookService(service, isCourse ? null : selectedSlot, values, {
+          staffId,
+          timeZone: zoneForBooking(),
+          participants,
+          depositSelected: service.deposit?.fullUpfrontAllowed ? payDeposit : undefined,
+        });
+        if (result.kind === "redirect") {
+          window.location.href = result.url;
+        } else {
+          confirmed = result;
+        }
+        return result;
+      } catch (e) {
+        error = e instanceof Error ? e.message : String(e);
+        throw e;
+      } finally {
+        booking = false;
+        emit();
+      }
+    },
+  };
+}

package/skills/wix-headless-templates/bookings/project/src/wix/bookings/booking.ts

@@ -0,0 +1,227 @@
+// Availability, the calendar reads (sessions, offered days, course seats), add-ons, settings, the
+// booking form, and the createBooking → Cart V2 → checkout-or-place sequence over the SDK. The
+// payload shapes are exact and easy to get subtly wrong — they are built in ./booking-core (shared
+// with the REST twin in templates/bookings/rest/); this file is the transport only. Copy as-is;
+// extend by calling these exports, never by editing them. Failures are loud where a visitor acts
+// (booking), silent-with-a-default where they only inform (settings, sessions, offered days).
+// docs: https://dev.wix.com/docs/api-reference/business-solutions/bookings/time-slots/time-slots-v2/list-availability-time-slots.md
+// docs: https://dev.wix.com/docs/api-reference/business-solutions/bookings/time-slots/time-slots-v2/list-event-time-slots.md
+// docs: https://dev.wix.com/docs/api-reference/business-management/calendar/events-v3/query-events.md
+// docs: https://dev.wix.com/docs/api-reference/business-solutions/bookings/services/services-v2/list-add-on-groups-by-service-id.md
+// docs: https://dev.wix.com/docs/api-reference/business-solutions/bookings/bookings/bookings-writer-v2/create-booking.md
+// docs: https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/purchase-flow/cart-v2/create-cart.md
+// docs: https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/purchase-flow/cart-v2/calculate-cart.md
+// docs: https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/purchase-flow/cart-v2/place-order.md
+// docs: https://dev.wix.com/docs/api-reference/business-management/headless/redirects/create-redirect-session.md
+// docs: https://dev.wix.com/docs/api-reference/crm/forms/form-schemas/get-form-summary.md
+import { availabilityTimeSlots, eventTimeSlots, bookings as bookingsModule, bookingsSettings as settingsModule, services as servicesModule } from "@wix/bookings";
+import { createCart, calculateCart, placeOrder } from "@wix/auto_sdk_ecom_cart-v-2";
+import { redirects as redirectsModule } from "@wix/redirects";
+import { wixFetch, wixModule } from "../sdk";
+import { DEFAULT_BOOKINGS_SETTINGS, toBookingsSettings } from "./services-core";
+import {
+  FALLBACK_FIELDS,
+  addOnGroupsRequest,
+  appointmentSlotsRequest,
+  bookingCartRequest,
+  bookingIdOf,
+  bookingOptions,
+  bookingRequest,
+  cartIdOf,
+  checkoutRedirectRequest,
+  checkoutRequired,
+  classSlotsRequest,
+  clampNextAvailable,
+  confirmedResult,
+  contactOf,
+  courseAvailabilityOf,
+  defaultTimeZone,
+  masterEventsRequest,
+  nextAvailableRequest,
+  nextEventsCursor,
+  nextSlotsCursor,
+  offeredDaysByScheduleId,
+  resolveDisplayTimeZone,
+  sessionsRequest,
+  toAddOnGroups,
+  toFormFields,
+  toLocalDateString,
+  toSession,
+  toSlotsPage,
+  type BookingOptions,
+  type NextAvailableOptions,
+  type Raw,
+  type SlotsWindow,
+} from "./booking-core";
+import type { AddOnGroup, BookingFormField, BookingResult, BookingsSettings, CourseAvailability, ServiceDetail, Session, Slot, SlotsPage, Weekday } from "./types";
+
+export { resolveDisplayTimeZone, toLocalDateString };
+
+const apptSlots = wixModule(availabilityTimeSlots);
+const classSlots = wixModule(eventTimeSlots);
+const bookings = wixModule(bookingsModule);
+const settings = wixModule(settingsModule);
+const services = wixModule(servicesModule);
+const cart = wixModule({ createCart, calculateCart, placeOrder });
+const redirects = wixModule(redirectsModule);
+
+/** A POST to a Wix REST endpoint whose SDK module isn't bundled (the Calendar events module); throws on a non-2xx. */
+async function postJson(path: string, body: Raw): Promise<Raw> {
+  const r = await wixFetch(path, { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify(body) });
+  if (!r.ok) throw new Error(`${path} failed (${r.status}).`);
+  return (await r.json()) as Raw;
+}
+
+/**
+ * Every slot for a service in [start of `from`'s day, +days) — APPOINTMENT and CLASS use different
+ * APIs; this branches and follows the cursor until the week is complete. Same-time slots across staff
+ * are merged; full class sessions come back with `bookable: false`. `timeZone` undefined → the
+ * business zone (the response says which zone the local times are in). COURSE has no slots ([]).
+ */
+export async function fetchSlots(service: Pick<ServiceDetail, "id" | "type">, window: SlotsWindow = {}): Promise<SlotsPage> {
+  if (service.type === "COURSE") return { slots: [], timeZone: window.timeZone ?? null };
+  const raws: Raw[] = [];
+  let timeZone: string | null = null;
+  let cursor: string | undefined;
+  do {
+    const res: Raw =
+      service.type === "CLASS"
+        ? await classSlots.listEventTimeSlots(classSlotsRequest(service.id, { ...window, cursor }) as any)
+        : await apptSlots.listAvailabilityTimeSlots(appointmentSlotsRequest(service.id, { ...window, cursor }) as any);
+    raws.push(...((res.timeSlots ?? []) as Raw[]));
+    timeZone ??= res.timeZone ?? null;
+    cursor = nextSlotsCursor(res) ?? undefined;
+  } while (cursor);
+  return toSlotsPage(raws, timeZone);
+}
+
+/**
+ * The next few bookable times (default 3, clamped 1..6) scanning from today to the end of the month
+ * six months out — what an empty week points at. Not meaningful for VARIED pricing, add-ons, or a
+ * course (`showsNextAvailability`); those return [].
+ */
+export async function fetchNextAvailableSlots(service: Pick<ServiceDetail, "id" | "type">, options: NextAvailableOptions = {}): Promise<SlotsPage> {
+  if (service.type === "COURSE") return { slots: [], timeZone: null };
+  const body = nextAvailableRequest(service, options);
+  const res: Raw = service.type === "CLASS" ? await classSlots.listEventTimeSlots(body as any) : await apptSlots.listAvailabilityTimeSlots(body as any);
+  const page = toSlotsPage((res.timeSlots ?? []) as Raw[], res.timeZone);
+  return { ...page, slots: page.slots.slice(0, clampNextAvailable(options.limit)) };
+}
+
+/** Which zone the site shows times in and whether visitors may switch. Never rejects: Wix's default (business zone) on failure. */
+export async function fetchBookingsSettings(): Promise<BookingsSettings> {
+  try {
+    return toBookingsSettings((await settings.getBookingsSettings()) as Raw);
+  } catch {
+    return DEFAULT_BOOKINGS_SETTINGS;
+  }
+}
+
+/** The service's add-on groups with their add-ons (prices formatted). Non-fatal (empty on failure). */
+export async function fetchAddOnGroups(serviceId: string): Promise<AddOnGroup[]> {
+  try {
+    // The SDK takes the id positionally; REST sends addOnGroupsRequest(serviceId) as the body.
+    const res: Raw = await services.listAddOnGroupsByServiceId(addOnGroupsRequest(serviceId).serviceId);
+    return toAddOnGroups(res);
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Upcoming sessions of a class or course schedule, oldest first, 7 per page; `nextCursor` fetches the
+ * next page. Informational (booking goes through a Slot or the course itself). Non-fatal.
+ */
+export async function fetchSessions(scheduleId: string, options: { limit?: number; cursor?: string; timeZone?: string } = {}): Promise<{ sessions: Session[]; nextCursor: string | null }> {
+  try {
+    const res = await postJson("/calendar/v3/events/query", sessionsRequest(scheduleId, options));
+    return { sessions: ((res.events ?? []) as Raw[]).map(toSession), nextCursor: nextEventsCursor(res) };
+  } catch {
+    return { sessions: [], nextCursor: null };
+  }
+}
+
+async function queryMasterEvents(scheduleIds: string[], timeZone?: string): Promise<Raw[]> {
+  if (!scheduleIds.length) return [];
+  try {
+    return ((await postJson("/calendar/v3/events/query", masterEventsRequest(scheduleIds, timeZone))).events ?? []) as Raw[];
+  } catch {
+    return [];
+  }
+}
+
+/** The weekdays each class/course schedule meets on — ONE batched call for a whole listing page. Non-fatal ({}). */
+export async function fetchOfferedDays(scheduleIds: string[], timeZone?: string): Promise<Record<string, Weekday[]>> {
+  return offeredDaysByScheduleId(await queryMasterEvents(scheduleIds, timeZone));
+}
+
+/** A COURSE's seats (total, left, full) from its recurring sessions; null once ended or without sessions. Non-fatal. */
+export async function fetchCourseAvailability(service: Pick<ServiceDetail, "scheduleId" | "course">, timeZone?: string): Promise<CourseAvailability | null> {
+  if (!service.scheduleId) return null;
+  return courseAvailabilityOf(await queryMasterEvents([service.scheduleId], timeZone), service.course?.ended ?? true);
+}
+
+/**
+ * The service's booking-form fields, flat and render-ready (values are keyed by `target`).
+ * ALWAYS returns a non-empty list — contact basics when the schema is missing/unusable —
+ * so the form can render unconditionally.
+ */
+export async function fetchBookingForm(formId: string | null): Promise<BookingFormField[]> {
+  if (!formId) return FALLBACK_FIELDS;
+  try {
+    // Over wixFetch, not the @wix/forms `forms` module: that generated module is 15 MB and would
+    // ride into the booking island's client chunk (11 MB per visitor). The summary has labels and
+    // types; only the full schema says which fields are required.
+    const id = encodeURIComponent(formId);
+    const json = async (path: string): Promise<Raw | null> => {
+      const r = await wixFetch(path);
+      return r.ok ? ((await r.json()) as Raw) : null;
+    };
+    const [res, form] = await Promise.all([
+      json(`/form-schema-service/v4/forms/${id}/summary`),
+      json(`/form-schema-service/v4/forms/${id}`).catch(() => null),
+    ]);
+    if (!res) return FALLBACK_FIELDS;
+    return toFormFields(res.formSummary, form?.form);
+  } catch {
+    return FALLBACK_FIELDS;
+  }
+}
+
+/**
+ * Book a slot (or, for a COURSE, the whole course — pass `slot: null`): createBooking → createCart
+ * (holds the seat, carries the contact and location) → calculateCart → hosted checkout (paid) or
+ * placeOrder (free / pay-in-person, decided from the calculated cart). Call from the browser.
+ * `formValues` is the object your inputs wrote, keyed by field `target` — passed as the
+ * formSubmission DIRECTLY. Throws with a friendly message on refusal (slot taken, invalid form) —
+ * surface it, don't swallow it.
+ */
+export async function bookService(
+  service: ServiceDetail,
+  slot: Slot | null,
+  formValues: Record<string, unknown>,
+  { staffId, timeZone = defaultTimeZone(), participants, depositSelected }: Omit<BookingOptions, "idKey"> = {},
+): Promise<BookingResult> {
+  const created: Raw = await bookings.createBooking(
+    bookingRequest(service, slot, { staffId, timeZone, participants, depositSelected, idKey: "_id" }) as any,
+    bookingOptions(formValues) as any,
+  );
+  const bookingId = bookingIdOf(created);
+  if (!bookingId) throw new Error("The booking couldn't be created — the slot may have just been taken.");
+
+  const newCart: Raw = await cart.createCart(bookingCartRequest([bookingId], contactOf(created), slot?.location?.type === "BUSINESS" ? slot.location.id : null) as any);
+  const cartId = cartIdOf(newCart);
+  if (!cartId) throw new Error("The booking couldn't be reserved — please try again.");
+
+  const calc: Raw = await cart.calculateCart(cartId);
+  if (checkoutRequired(service, calc)) {
+    const origin = typeof window !== "undefined" ? window.location.origin : "";
+    const session: Raw = await redirects.createRedirectSession(checkoutRedirectRequest(cartId, origin));
+    const url = session?.redirectSession?.fullUrl;
+    if (!url) throw new Error("Checkout couldn't start — please try again.");
+    return { kind: "redirect", url };
+  }
+
+  const order: Raw = await cart.placeOrder(cartId);
+  return confirmedResult(bookingId, order);
+}