@wix/agent-skills 1.26.0 → 1.27.0

package/skills/wix-headless-templates/bookings/rest/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 REST — the twin of
+// app/wix/bookings/booking.ts. Same exports, same DTOs; every body comes from booking-core (the SAME
+// file the SDK transport uses, deployed flat next to this one), so this file is only the transport:
+// literal paths, one fetch per step. Failures are loud where a visitor acts (booking): a taken slot,
+// a refused cart, a checkout that won't start all throw — surface the message. Reads that only
+// inform (settings, sessions, offered days, add-ons) fall back to an empty default.
+// All calls run with the visitor token: the booking and its cart are the token's (see ./client).
+// 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-management/headless/redirects/create-redirect-session.md
+// docs: https://dev.wix.com/docs/api-reference/crm/forms/form-schemas/get-form-summary.md
+import { wixRequest } from "./client.js";
+import { DEFAULT_BOOKINGS_SETTINGS, toBookingsSettings } from "./services-core.js";
+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.js";
+import type { AddOnGroup, BookingFormField, BookingResult, BookingsSettings, CourseAvailability, ServiceDetail, Session, Slot, SlotsPage, Weekday } from "./types.js";
+
+export { resolveDisplayTimeZone, toLocalDateString };
+
+// The two time-slot endpoints. APPOINTMENT pages on `cursorPagingMetadata`, CLASS on `pagingMetadata`.
+//   POST /service-availability/v2/time-slots        { serviceId, fromLocalDate, toLocalDate, timeZone?, bookable, cursorPaging, includeResourceTypeIds, resourceTypes? }
+//   POST /service-availability/v2/time-slots/event  { serviceIds, fromLocalDate, toLocalDate, timeZone?, includeNonBookable, cursorPaging, eventFilter? }
+const listSlots = (type: string, body: Raw): Promise<Raw> =>
+  wixRequest<Raw>(type === "CLASS" ? "/service-availability/v2/time-slots/event" : "/service-availability/v2/time-slots", { body });
+
+/**
+ * Every slot for a service in [start of `from`'s day, +days) — APPOINTMENT and CLASS use different
+ * endpoints; 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 body = service.type === "CLASS" ? classSlotsRequest(service.id, { ...window, cursor }) : appointmentSlotsRequest(service.id, { ...window, cursor });
+    const res = await listSlots(service.type, body);
+    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 []. Same two endpoints as fetchSlots.
+ */
+export async function fetchNextAvailableSlots(service: Pick<ServiceDetail, "id" | "type">, options: NextAvailableOptions = {}): Promise<SlotsPage> {
+  if (service.type === "COURSE") return { slots: [], timeZone: null };
+  const res = await listSlots(service.type, nextAvailableRequest(service, options));
+  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. The path is the one the @wix/bookings SDK resolves for
+ * `bookingsSettings.getBookingsSettings()` (no public reference page yet).
+ *   GET /_api/bookings-settings/v2/settings  → { bookingsSettings: { displayTimeZone: { basedOn, customerCanChange } } }
+ */
+export async function fetchBookingsSettings(): Promise<BookingsSettings> {
+  try {
+    return toBookingsSettings(await wixRequest<Raw>("/_api/bookings-settings/v2/settings", { method: "GET" }));
+  } catch {
+    return DEFAULT_BOOKINGS_SETTINGS;
+  }
+}
+
+/**
+ * The service's add-on groups with their add-ons (prices formatted). Non-fatal (empty on failure).
+ *   POST /bookings/v2/services/add-on-groups/list-add-on-groups-by-service-id  { serviceId }  → { addOnGroupsDetails }
+ */
+export async function fetchAddOnGroups(serviceId: string): Promise<AddOnGroup[]> {
+  try {
+    return toAddOnGroups(await wixRequest<Raw>("/bookings/v2/services/add-on-groups/list-add-on-groups-by-service-id", { body: addOnGroupsRequest(serviceId) }));
+  } catch {
+    return [];
+  }
+}
+
+// The Calendar Events query: sessions (INSTANCE events of one schedule) and recurring MASTER events.
+//   POST /calendar/v3/events/query  { query: { filter, cursorPaging }, fromLocalDate, timeZone?, recurrenceType? }  → { events, pagingMetadata }
+const queryEvents = (body: Raw): Promise<Raw> => wixRequest<Raw>("/calendar/v3/events/query", { body });
+
+/**
+ * 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 queryEvents(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 queryEvents(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 keyed by `target`). ALWAYS a
+ * non-empty list — contact basics when the schema is missing/unusable — so the form renders
+ * unconditionally.  GET /form-schema-service/v4/forms/{formId}/summary (labels, types) and
+ * GET /form-schema-service/v4/forms/{formId} (which fields are required — the summary doesn't say).
+ */
+export async function fetchBookingForm(formId: string | null): Promise<BookingFormField[]> {
+  if (!formId) return FALLBACK_FIELDS;
+  try {
+    const id = encodeURIComponent(formId);
+    const [res, form] = await Promise.all([
+      wixRequest<Raw>(`/form-schema-service/v4/forms/${id}/summary`, { method: "GET" }),
+      wixRequest<Raw>(`/form-schema-service/v4/forms/${id}`, { method: "GET" }).catch(() => null),
+    ]);
+    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 the refusal (slot taken, invalid form) — surface it, don't
+ * swallow it. `origin` is the site's real https origin as registered on the OAuth app's allowed
+ * domains (browser: window.location.origin).
+ *   POST /bookings/v2/bookings            { booking, participantNotification, sendSmsReminder, formSubmission }
+ *   POST /ecom/v2/carts                   { catalogItems: [{ quantity: 1, catalogReference: { catalogItemId: <bookingId>, appId } }], cart: { source, businessInfo?, customerInfo? } }
+ *   POST /ecom/v2/carts/{cartId}/calculate {}
+ *   POST /headless/v1/redirect-session    { ecomCheckout: { checkoutId: <cartId> }, callbacks: { postFlowUrl } }
+ *   POST /ecom/v2/carts/{cartId}/place-order {}
+ */
+export async function bookService(
+  service: ServiceDetail,
+  slot: Slot | null,
+  formValues: Record<string, unknown>,
+  {
+    staffId,
+    timeZone = defaultTimeZone(),
+    participants,
+    depositSelected,
+    origin = typeof window !== "undefined" ? window.location.origin : "",
+  }: Omit<BookingOptions, "idKey"> & { origin?: string } = {},
+): Promise<BookingResult> {
+  const created = await wixRequest<Raw>("/bookings/v2/bookings", {
+    body: { booking: bookingRequest(service, slot, { staffId, timeZone, participants, depositSelected, idKey: "id" }), ...bookingOptions(formValues) },
+  });
+  const bookingId = bookingIdOf(created);
+  if (!bookingId) throw new Error("The booking couldn't be created — the slot may have just been taken.");
+
+  const newCart = await wixRequest<Raw>("/ecom/v2/carts", {
+    body: bookingCartRequest([bookingId], contactOf(created), slot?.location?.type === "BUSINESS" ? slot.location.id : null),
+  });
+  const cartId = cartIdOf(newCart);
+  if (!cartId) throw new Error("The booking couldn't be reserved — please try again.");
+
+  const calc = await wixRequest<Raw>(`/ecom/v2/carts/${cartId}/calculate`, { body: {} });
+  if (checkoutRequired(service, calc)) {
+    const session = await wixRequest<Raw>("/headless/v1/redirect-session", { body: 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 = await wixRequest<Raw>(`/ecom/v2/carts/${cartId}/place-order`, { body: {} });
+  return confirmedResult(bookingId, order);
+}

package/skills/wix-headless-templates/bookings/rest/services.ts

@@ -0,0 +1,94 @@
+// Service reads over REST — the twin of app/wix/bookings/services.ts. Same exports, same DTOs; the
+// rules and mappers come from services-core (the SAME file the SDK transport uses, deployed flat
+// next to this one by deploy.mjs --stack static), so this file is only the transport: one fetch with
+// a literal body per function. Every call here is safe from a browser with a visitor token.
+// Porting: keep the paths, keep the bodies, port the core once.
+// docs: https://dev.wix.com/docs/api-reference/business-solutions/bookings/services/services-v2/query-services.md
+// docs: https://dev.wix.com/docs/api-reference/business-solutions/bookings/services/services-v2/query-categories.md
+// docs: https://dev.wix.com/docs/api-reference/business-solutions/bookings/services/services-v2/query-locations.md
+import { wixRequest } from "./client.js";
+import { imgSrc } from "./media.js";
+import {
+  BOOKINGS_APP_ID,
+  CATEGORIES_QUERY,
+  LOCATIONS_QUERY,
+  OTHER_LOCATIONS_ID,
+  SERVICES_CONDITIONAL_FIELDS,
+  SERVICES_PAGE_SIZE,
+  STAFF_RESOURCE_TYPE_ID,
+  hasMorePage,
+  isKnownType,
+  servicesFilter,
+  toCategories,
+  toDetail,
+  toLocationOptions,
+  toSummary,
+  type Raw,
+  type ServicesFilterOptions,
+} from "./services-core.js";
+import type { BookingCategory, LocationOption, ServiceDetail, ServiceSummary } from "./types.js";
+
+export { BOOKINGS_APP_ID, OTHER_LOCATIONS_ID, SERVICES_PAGE_SIZE, STAFF_RESOURCE_TYPE_ID };
+
+export interface FetchServicesOptions extends ServicesFilterOptions {
+  limit?: number;
+  offset?: number;
+}
+
+export interface ServicesPage {
+  items: ServiceSummary[];
+  /** Another page follows — pass `offset + items.length`. */
+  hasMore: boolean;
+}
+
+// POST /bookings/v2/services/query  { query: { filter, paging: { limit, offset } }, conditionalFields }
+async function queryServices(filter: ServicesFilterOptions, limit: number, offset: number): Promise<Raw> {
+  return wixRequest<Raw>("/bookings/v2/services/query", {
+    body: { query: { filter: servicesFilter(filter), paging: { limit, offset } }, conditionalFields: SERVICES_CONDITIONAL_FIELDS },
+  });
+}
+
+/**
+ * One page of bookable services (this app's, never hidden — filtered by the server), optionally one
+ * category and/or one business location (or OTHER_LOCATIONS_ID for custom/customer locations),
+ * mapped to grid-ready DTOs. Wix pages 20 at a time; `hasMore` says whether to ask for the next.
+ */
+export async function fetchServices({ limit = SERVICES_PAGE_SIZE, offset = 0, categoryId, locationId }: FetchServicesOptions = {}): Promise<ServicesPage> {
+  const res = await queryServices({ categoryId, locationId }, limit, offset);
+  const raws = ((res?.services ?? []) as Raw[]).filter(isKnownType);
+  return { items: raws.map((s) => toSummary(s, imgSrc)), hasMore: hasMorePage(res?.pagingMetadata, offset, (res?.services ?? []).length, limit) };
+}
+
+/** One service by its URL slug (mainSlug.name) — a query with the slug in the filter. Null when not found. */
+export async function fetchServiceBySlug(slug: string): Promise<ServiceDetail | null> {
+  const raw = ((await queryServices({ slug }, 1, 0))?.services ?? [])[0] as Raw | undefined;
+  return raw && isKnownType(raw) ? toDetail(raw, imgSrc) : null;
+}
+
+/**
+ * Service categories for a filter bar — only categories that hold a bookable service, in the owner's
+ * order. Non-fatal (empty array on failure).
+ * POST /bookings/v2/services/categories/query  { filter: { services: {} } }
+ */
+export async function fetchBookingCategories(): Promise<BookingCategory[]> {
+  try {
+    const res = await wixRequest<Raw>("/bookings/v2/services/categories/query", { body: CATEGORIES_QUERY });
+    return toCategories((res?.categories ?? []) as Raw[]);
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Business locations that host a visible service (a listing filter, sorted by name) plus whether any
+ * service is held at a custom/customer location (the OTHER_LOCATIONS_ID bucket). Non-fatal.
+ * POST /bookings/v2/services/locations/query  { filter: { services: { appId, hidden: false } } }
+ */
+export async function fetchLocations(): Promise<{ locations: LocationOption[]; hasOtherLocations: boolean }> {
+  try {
+    const res = await wixRequest<Raw>("/bookings/v2/services/locations/query", { body: LOCATIONS_QUERY });
+    return toLocationOptions(res);
+  } catch {
+    return { locations: [], hasOtherLocations: false };
+  }
+}

package/skills/wix-headless-templates/bookings/seed/SEED.md

@@ -0,0 +1,109 @@
+# Bookings — seeding
+
+Seed by **running `seed-bookings.mjs` with a plan file** — don't hand-write the REST calls.
+The script mints its own site token via the Wix CLI (logged-in session + `wix.config.json`
+required), installs the Bookings app if needed, resolves the staff resources (polling — a fresh
+install provisions the owner asynchronously; extra staff named in the plan are created), creates
+the extra locations and booking policies the plan asks for, and creates everything in the right order.
+
+```bash
+# from the project root (where wix.config.json lives):
+node <SKILL_ROOT>/templates/bookings/seed/seed-bookings.mjs plan.json
+```
+
+`plan.json` is plain data — write it from the brief. **Default to 3–4 services** (the seed
+shows the shape; the owner adds the rest in the dashboard) and make them exercise the UI:
+mix APPOINTMENT, CLASS, and COURSE when it fits the business, include one of each price type the
+brief allows (a fixed price, a free/pay-in-person one, a "From" price, a quote), and give every
+service an image — the default is an `imagePrompt` (AI-generated, ~1 Wix AI credit per image,
+account-billed): brand-contextual — subject, aesthetic/mood, palette, lighting — always ending
+"no text, no watermarks". At least one image in the set shows the real subject of the business —
+the actual product/space/service, not abstract decoration. For an asset the user actually supplied
+use `imagePath` (a file on this machine — uploaded to Wix Media) or `imageUrl` (their own hosted
+URL; verify it with `curl -sI` → 200) — never a stock-photo or guessed URL. Images resolve in
+parallel and never block the seed; a failed image leaves that service text-only.
+
+```json
+{
+  "staff": ["Maya Lin"],
+  "locations": [{ "name": "Downtown studio", "timeZone": "America/New_York",
+                  "address": { "formattedAddress": "12 5th Street, New York", "city": "New York", "country": "US" } }],
+  "services": [
+    { "type": "APPOINTMENT", "name": "Deep Tissue Massage", "tagLine": "60 minutes of relief",
+      "description": "…", "price": 85, "duration": 60, "category": "Massage", "deposit": 20, "payInFull": true,
+      "staff": "Maya Lin", "imageUrl": "https://…" },
+    { "type": "APPOINTMENT", "name": "Intro Consultation", "description": "…", "free": true,
+      "duration": 30, "category": "Massage", "requireManualApproval": true, "imageUrl": "https://…" },
+    { "type": "APPOINTMENT", "name": "Custom Treatment", "description": "…", "priceText": "Ask for a quote",
+      "duration": 90, "category": "Massage", "location": "Downtown studio", "imageUrl": "https://…" },
+    { "type": "CLASS", "name": "Morning Yoga", "description": "…", "price": { "from": 20 }, "capacity": 12,
+      "waitlist": 4, "maxParticipants": 3, "category": "Classes", "conferencing": true, "imageUrl": "https://…",
+      "weekly": { "days": ["MONDAY", "WEDNESDAY"], "time": "09:00", "duration": 60, "start": "2026-10-05", "end": "2026-12-20" },
+      "sessions": [{ "start": "2026-10-03T09:00:00", "end": "2026-10-03T10:00:00" }] },
+    { "type": "COURSE", "name": "6-Week Pottery Course", "description": "…", "price": 240, "capacity": 8,
+      "category": "Courses", "imageUrl": "https://…",
+      "weekly": { "days": ["TUESDAY"], "time": "18:00", "duration": 120, "start": "2026-10-06", "end": "2026-11-10" } }
+  ]
+}
+```
+
+- `type` — `APPOINTMENT` (visitor picks a free slot; needs `duration` in minutes), `CLASS` (fixed
+  sessions the visitor picks one of), or `COURSE` (the visitor books the whole series; no slot
+  picking). Classes and courses get their sessions from `weekly` and/or `sessions`:
+  - `weekly` — `{ days: ["MONDAY", …], time: "18:00", duration: 60, start: "YYYY-MM-DD", end: "YYYY-MM-DD" }`
+    creates one recurring session per weekday from the first such day on/after `start` until `end`.
+    This is what makes a course bookable and what the listing shows as "Mon, Wed". **A course needs
+    `weekly`** (its seats and dates come from the recurring sessions).
+  - `sessions` — one-off class sessions, **future local wall-clock** `YYYY-MM-DDThh:mm:ss`, no Z.
+  - A class with neither shows no bookable times.
+- `price` — a number → a fixed price; `{ "from": 30 }` → varied pricing shown as "From €30";
+  `priceText: "Ask for a quote"` → a custom price (text, pay in person); omit or `free: true` → a
+  no-fee, pay-in-person service (books without checkout). The site currency wins over a per-service
+  `currency`. `deposit: 20` makes the service take a deposit (fixed or varied prices only);
+  `payInFull: true` also lets the visitor pay everything upfront.
+- `currency` — 3-letter ISO code at the top of the plan, set **only when the brief names one**: a
+  sentence about currency, or a price written with its unit ("9 dollars", "$9", "€20"). Do **not**
+  infer it from a language, a country, or an address. The seed sets the site to it before creating
+  anything, because prices are stored in the site currency at create time; a new site starts in the
+  currency of the account that created it, not the business's.
+- `capacity` — seats per session (classes) or for the whole series (courses); appointments are 1.
+  `waitlist: 4` adds a waitlist of that size and `maxParticipants: 3` caps seats per booking — both
+  create a booking policy for that service.
+- `requireManualApproval: true` — bookings are requests the owner approves (the CTA reads "Request to
+  book"). `conferencing: true` — sessions carry a video link (the tile shows "Online").
+- `category` — a name; created idempotently. Every service gets one (required for live-site
+  visibility) — uncategorized services fall into a default "Services" category.
+- `staff` — top-level `["Name", …]` creates staff members (idempotent by name); a service's `staff`
+  (a name or names) assigns them to an appointment and puts their sessions on that person. Without
+  it, appointments go to the site's default staff resource; the flow books with ANY_RESOURCE when
+  the visitor doesn't choose. Staff photos and working hours are dashboard work — say so.
+- `locations` — top-level `[{ name, timeZone, address? }]` creates extra business locations
+  (idempotent by name; `timeZone` is required by the API); a service's `location` (a name from that
+  list) puts it there — the listing then offers a location filter. Without it, services sit at the
+  default business location.
+
+**Seeding is additive — never delete or overwrite existing content**; ask first if a cleanup
+seems needed.
+
+## Supplied content
+
+The general rules are in `templates/shared/SUPPLIED-CONTENT.md`. For bookings, each service the
+user lists is one entry. Its name becomes `name` and its length in minutes becomes `duration`. Its
+price becomes `price` ("from €30" → `{ "from": 30 }`; "on request" → `priceText`); a service marked
+free, or with no price, gets `"free": true`. A group activity with a capacity or fixed times becomes
+a `CLASS` with `capacity` and `weekly` (recurring days) or one `sessions` entry per listed time; a
+multi-week series with a start and an end becomes a `COURSE` with `weekly`; everything else is an
+`APPOINTMENT`. A category or group becomes `category`; a named practitioner becomes `staff`; a named
+branch becomes `location` (+ a `locations` entry with its time zone). Their photo becomes
+`imageUrl`. A service with no duration is a question for the user. Opening hours are not seeded —
+say so; the owner sets them in the dashboard.
+
+## Escape hatch — individual functions
+`setupBookings` composes exported steps — `installBookingsApp`, `queryStaffWithRetry`, `createStaff`,
+`createLocations`, `createBookingPolicy`, `createCategories`, `createServices`, `scheduleEvents`
+(`weeklyEvents` builds the recurring ones), `importImage`, `attachServiceImage`, plus `makeCtx()` —
+import them only for a partial re-seed.
+
+## Reference
+Unexpected shape or an uncovered operation → read the live Wix API reference; every call the script
+makes carries a `docs:` line with its reference page.

package/skills/wix-headless-templates/bookings/seed/read-site.mjs

@@ -0,0 +1,28 @@
+// What the booking business holds: services, staff, categories.
+//   node <SKILL_ROOT>/templates/bookings/seed/read-site.mjs [--site <siteId>] [--limit <n>]
+import { runReader } from "../../shared/seed/read-site.mjs";
+
+const BOOKINGS_APP_ID = "13d21c63-b5ec-5912-8397-c3a5ddb27a97";
+const D = "https://dev.wix.com/docs/api-reference/business-solutions/bookings";
+
+await runReader({
+  vertical: "bookings",
+  appId: BOOKINGS_APP_ID,
+  async read(api, { limit }) {
+    const services = await api.call({ path: "/_api/bookings/v2/services/query", body: { query: { paging: { limit }, filter: { hidden: { $eq: false } } } }, docs: `${D}/services/services-v2/query-services` });
+    const staff = await api.tryCall({ path: "/bookings/v1/staff-members/query", body: { query: {}, fields: ["RESOURCE_DETAILS"] }, docs: `${D}/staff-members/staff-members/query-staff-members` });
+    const cats = await api.tryCall({ path: "/bookings/v2/categories/query", body: { query: {} }, docs: `${D}/services/categories-v2/query-categories` });
+    return {
+      serviceCount: services.pagingMetadata?.total ?? (services.services ?? []).length,
+      services: (services.services ?? []).map((s) => ({
+        name: s.name, slug: s.mainSlug?.name ?? null, type: s.type ?? null,
+        category: s.category?.name ?? null,
+        price: s.payment?.fixed?.price ? `${s.payment.fixed.price.value} ${s.payment.fixed.price.currency}` : s.payment?.varied?.defaultPrice ? `from ${s.payment.varied.defaultPrice.value} ${s.payment.varied.defaultPrice.currency}` : (s.payment?.rateType ?? null),
+        durationMinutes: s.schedule?.availabilityConstraints?.sessionDurations?.[0] ?? null,
+        online: s.payment?.options?.online ?? false, inPerson: s.payment?.options?.inPerson ?? false, media: s.media?.mainMedia ? 1 : 0,
+      })),
+      staff: (staff?.staffMembers ?? []).map((m) => m.name),
+      categories: (cats?.categories ?? []).map((c) => ({ id: c.id, name: c.name })),
+    };
+  },
+});