@wix/agent-skills 1.20.0 → 1.21.0

package/skills/wix-headless-fast/references/bookings/app/wix/bookings/services-core.ts

@@ -0,0 +1,92 @@
+// Service rules and DTO mapping — transport-agnostic, imported by BOTH transports: ./services.ts
+// (the SDK, managed Astro and React) and the REST twin in references/bookings/rest/services.ts
+// (fetch, a static site or a port to another language). Every rule about price, "Free", duration,
+// media, staff, and the payment option lives HERE, once. A raw entity may come from the SDK (`_id`,
+// media as a `wix:image://` string) or from REST (`id`, media as an { id, url, width, height }
+// object); the mappers accept both. Imports are type-only so a strip to JS emits no imports.
+import type { BookingCategory, ServiceDetail, ServiceSummary, ServiceType } from "./types";
+
+/** A raw Services V2 entity as either transport returns it. */
+export type Raw = Record<string, any>;
+/** Media value + size → https URL. Injected: the SDK transport scales through @wix/sdk, REST through the URL form. */
+export type ImgSrc = (value: any, width: number, height: number) => string;
+
+/** The Wix Bookings app id — the cart's catalogReference.appId and the services filter. */
+export const BOOKINGS_APP_ID = "13d21c63-b5ec-5912-8397-c3a5ddb27a97";
+/** Staff-member resource type id (ANY_RESOURCE fallback + staff filtering). */
+export const STAFF_RESOURCE_TYPE_ID = "1cd44cf8-756f-41c3-bd90-3e2ffcaf1155";
+/** Requested on every service read — without it `staffMemberDetails` is absent and the DTO's staff is []. */
+export const SERVICES_CONDITIONAL_FIELDS = ["STAFF_MEMBER_DETAILS"] as const;
+
+export const rawId = (raw: Raw | undefined | null): string => raw?._id ?? raw?.id ?? "";
+
+/** The filter every services read shares: this app's services, optionally one slug (`mainSlug.name`). */
+export function servicesFilter(slug?: string): Raw {
+  return { appId: BOOKINGS_APP_ID, ...(slug ? { "mainSlug.name": slug } : {}) };
+}
+
+/** Hidden services never reach a tile — the same rule on both transports. */
+export const isVisible = (raw: Raw): boolean => !raw.hidden;
+
+/**
+ * A media value the image helpers can resolve. The SDK hands over a `wix:image://v1/<id>/<name>#…`
+ * string (or an https URL); REST hands over the image OBJECT with a bare file id — rebuilt into the
+ * same `wix:image://` form the SDK produces, so imgSrc scales both identically.
+ */
+export function mediaValue(image: unknown): unknown {
+  if (!image || typeof image === "string") return image;
+  const o = image as Raw;
+  const url: string = o.url ?? "";
+  if (/^(https?:|wix:image:)/.test(url)) return url;
+  if (o.id) return `wix:image://v1/${o.id}/${encodeURIComponent(o.filename ?? "")}#originWidth=${o.width ?? 0}&originHeight=${o.height ?? 0}`;
+  return url;
+}
+
+export function formatPrice(value: string | undefined, currency: string | undefined): string {
+  if (value == null || value === "" || Number(value) === 0) return "Free";
+  try {
+    return new Intl.NumberFormat(undefined, { style: "currency", currency: currency || "USD" }).format(Number(value));
+  } catch {
+    return `${value} ${currency ?? ""}`.trim();
+  }
+}
+
+export function toSummary(raw: Raw, imgSrc: ImgSrc): ServiceSummary {
+  const price = raw.payment?.fixed?.price;
+  const free = raw.payment?.rateType === "NO_FEE" || !price?.value || Number(price.value) === 0;
+  return {
+    id: rawId(raw),
+    slug: raw.mainSlug?.name ?? raw.supportedSlugs?.[0]?.name ?? "",
+    name: raw.name ?? "",
+    tagLine: raw.tagLine ?? "",
+    type: (raw.type ?? "APPOINTMENT") as ServiceType,
+    price: free ? "Free" : formatPrice(price?.value, price?.currency),
+    free,
+    durationMinutes: raw.schedule?.availabilityConstraints?.sessionDurations?.[0] ?? null,
+    imageUrl: imgSrc(mediaValue(raw.media?.mainMedia?.image), 800, 800),
+    categoryId: rawId(raw.category) || null,
+    staff: ((raw.staffMemberDetails?.staffMembers ?? []) as Raw[])
+      .map((m) => ({ id: m.staffMemberId ?? "", name: m.name ?? "" }))
+      .filter((m) => m.id),
+  };
+}
+
+export function toDetail(raw: Raw, imgSrc: ImgSrc): ServiceDetail {
+  const summary = toSummary(raw, imgSrc);
+  const online = raw.payment?.options?.online === true;
+  const inPerson = raw.payment?.options?.inPerson === true;
+  // Derive — never hardcode "ONLINE": a free/pay-in-person service booked ONLINE gets
+  // rejected by the cart with INSUFFICIENT_INVENTORY.
+  const paymentOption: "ONLINE" | "OFFLINE" = !online && inPerson ? "OFFLINE" : "ONLINE";
+  return {
+    ...summary,
+    description: raw.description ?? "",
+    formId: rawId(raw.form) || null,
+    paymentOption,
+    cancellationFeeEnabled: raw.bookingPolicy?.cancellationFeePolicy?.enabled === true,
+  };
+}
+
+export function toCategory(raw: Raw): BookingCategory {
+  return { id: rawId(raw), name: raw.name ?? "" };
+}

package/skills/wix-headless-fast/references/bookings/app/wix/bookings/services-store.ts

@@ -0,0 +1,90 @@
+// The services listing as a framework-free store — the logic behind useServices, usable from React
+// (useServices wraps it with useSyncExternalStore), from a static page or Vue/Svelte (subscribe and
+// render), or as the specification for a port. State, actions, subscribe/getState, emit after every
+// change. SSR-friendly: seed with `initialServices`/`initialCategories` and nothing is fetched;
+// without them `start()` loads both. Category filtering is client-side — bookings catalogs are
+// small and fully fetched. One store per mounted listing: createServicesStore(), not a singleton.
+import { fetchBookingCategories, fetchServices } from "./services";
+import type { BookingCategory, ServiceSummary } from "./types";
+
+export interface ServicesStoreOptions {
+  initialServices?: ServiceSummary[];
+  initialCategories?: BookingCategory[];
+}
+
+/** Everything a listing surface renders from. Read it with getState() or through a subscription. */
+export interface ServicesState {
+  /** null while the first load is in flight — render skeletons, not an empty state. */
+  services: ServiceSummary[] | null;
+  categories: BookingCategory[];
+  activeCategoryId: string | null;
+  error: string | null;
+}
+
+export interface ServicesStore {
+  getState(): ServicesState;
+  subscribe(listener: () => void): () => void;
+  /** Fetch whatever wasn't seeded. Call once when mounted (a browser). */
+  start(): void;
+  /** Stop reacting; drop late responses. */
+  stop(): void;
+  setActiveCategoryId(id: string | null): void;
+}
+
+export function createServicesStore({ initialServices, initialCategories }: ServicesStoreOptions = {}): ServicesStore {
+  let all: ServiceSummary[] | null = initialServices ?? null;
+  let categories: BookingCategory[] = initialCategories ?? [];
+  let activeCategoryId: string | null = null;
+  let error: string | null = null;
+  let started = false;
+  const listeners = new Set<() => void>();
+  let snapshot: ServicesState | null = null;
+  const emit = () => {
+    snapshot = null;
+    for (const fn of listeners) fn();
+  };
+
+  function getState(): ServicesState {
+    if (snapshot) return snapshot;
+    snapshot = {
+      services: all === null ? null : activeCategoryId ? all.filter((s) => s.categoryId === activeCategoryId) : all,
+      categories,
+      activeCategoryId,
+      error,
+    };
+    return snapshot;
+  }
+
+  return {
+    getState,
+    subscribe(fn) {
+      listeners.add(fn);
+      return () => listeners.delete(fn);
+    },
+    start() {
+      if (started) return;
+      started = true;
+      if (!initialServices) {
+        fetchServices()
+          .then((s) => { if (started) { all = s; emit(); } })
+          .catch((e) => {
+            if (!started) return;
+            all = [];
+            error = e instanceof Error ? e.message : String(e);
+            emit();
+          });
+      }
+      if (!initialCategories) {
+        fetchBookingCategories().then((c) => { if (started) { categories = c; emit(); } });
+      }
+    },
+    stop() {
+      started = false;
+    },
+    setActiveCategoryId(id) {
+      if (id === activeCategoryId) return;
+      activeCategoryId = id;
+      emit();
+    },
+  };
+}

package/skills/wix-headless-fast/references/bookings/app/wix/bookings/services.ts

@@ -1,95 +1,56 @@
-// Service reads (Wix Bookings Services V2) — the only file that touches raw service
-// entities. Everything it returns is a plain DTO from ./types. Copy as-is; extend by adding
-// functions, not by editing these.
+// Service reads (Wix Bookings Services V2) over the SDK — the only file that touches raw service
+// entities on this transport. Everything it returns is a plain DTO from ./types. The rules and
+// mappers live in ./services-core (shared with the REST twin in references/bookings/rest/); this
+// file is the transport only. Copy as-is; extend by adding functions, not by editing these.
 // 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/categories-v2/query-categories.md
 import { services as servicesModule, categoriesV2 } from "@wix/bookings";
 import { wixModule } from "../sdk";
 import { imgSrc } from "../media";
-import type { BookingCategory, ServiceDetail, ServiceSummary, ServiceType } from "./types";
+import {
+  BOOKINGS_APP_ID,
+  SERVICES_CONDITIONAL_FIELDS,
+  STAFF_RESOURCE_TYPE_ID,
+  isVisible,
+  toCategory,
+  toDetail,
+  toSummary,
+  type Raw,
+} from "./services-core";
+import type { BookingCategory, ServiceDetail, ServiceSummary } from "./types";
+
+export { BOOKINGS_APP_ID, STAFF_RESOURCE_TYPE_ID };
 
 const services = wixModule(servicesModule);
 const categories = wixModule(categoriesV2);
 
-/** The Wix Bookings app id — the cart's catalogReference.appId and the services filter. */
-export const BOOKINGS_APP_ID = "13d21c63-b5ec-5912-8397-c3a5ddb27a97";
-/** Staff-member resource type id (ANY_RESOURCE fallback + staff filtering). */
-export const STAFF_RESOURCE_TYPE_ID = "1cd44cf8-756f-41c3-bd90-3e2ffcaf1155";
-
-type Raw = Record<string, any>;
-
-function formatPrice(value: string | undefined, currency: string | undefined): string {
-  if (value == null || value === "" || Number(value) === 0) return "Free";
-  try {
-    return new Intl.NumberFormat(undefined, { style: "currency", currency: currency || "USD" }).format(Number(value));
-  } catch {
-    return `${value} ${currency ?? ""}`.trim();
-  }
-}
-
-function toSummary(raw: Raw): ServiceSummary {
-  const price = raw.payment?.fixed?.price;
-  const free = raw.payment?.rateType === "NO_FEE" || !price?.value || Number(price.value) === 0;
-  return {
-    id: raw._id ?? "",
-    slug: raw.mainSlug?.name ?? raw.supportedSlugs?.[0]?.name ?? "",
-    name: raw.name ?? "",
-    tagLine: raw.tagLine ?? "",
-    type: (raw.type ?? "APPOINTMENT") as ServiceType,
-    price: free ? "Free" : formatPrice(price?.value, price?.currency),
-    free,
-    durationMinutes: raw.schedule?.availabilityConstraints?.sessionDurations?.[0] ?? null,
-    imageUrl: imgSrc(raw.media?.mainMedia?.image, 800, 800),
-    categoryId: raw.category?._id ?? null,
-    staff: (raw.staffMemberDetails?.staffMembers ?? [])
-      .map((m: Raw) => ({ id: m.staffMemberId ?? "", name: m.name ?? "" }))
-      .filter((m: { id: string }) => m.id),
-  };
-}
-
-function toDetail(raw: Raw): ServiceDetail {
-  const summary = toSummary(raw);
-  const online = raw.payment?.options?.online === true;
-  const inPerson = raw.payment?.options?.inPerson === true;
-  // Derive — never hardcode "ONLINE": a free/pay-in-person service booked ONLINE gets
-  // rejected by the cart with INSUFFICIENT_INVENTORY.
-  const paymentOption: "ONLINE" | "OFFLINE" = !online && inPerson ? "OFFLINE" : "ONLINE";
-  return {
-    ...summary,
-    description: raw.description ?? "",
-    formId: raw.form?._id ?? null,
-    paymentOption,
-    cancellationFeeEnabled: raw.bookingPolicy?.cancellationFeePolicy?.enabled === true,
-  };
-}
-
 /** List bookable services (hidden ones filtered), mapped to grid-ready DTOs. */
 export async function fetchServices({ limit = 100 } = {}): Promise<ServiceSummary[]> {
   const res = await services
-    .queryServices({ conditionalFields: ["STAFF_MEMBER_DETAILS"] as any })
+    .queryServices({ conditionalFields: SERVICES_CONDITIONAL_FIELDS as any })
     .eq("appId", BOOKINGS_APP_ID)
     .limit(limit)
     .find();
-  return (res.items ?? []).filter((s: Raw) => !s.hidden).map((s: Raw) => toSummary(s));
+  return ((res.items ?? []) as Raw[]).filter(isVisible).map((s) => toSummary(s, imgSrc));
 }
 
 /** Fetch one service by its URL slug (mainSlug.name). Null when not found. */
 export async function fetchServiceBySlug(slug: string): Promise<ServiceDetail | null> {
   const res = await services
-    .queryServices({ conditionalFields: ["STAFF_MEMBER_DETAILS"] as any })
+    .queryServices({ conditionalFields: SERVICES_CONDITIONAL_FIELDS as any })
     .eq("mainSlug.name", slug)
     .eq("appId", BOOKINGS_APP_ID)
     .limit(1)
     .find();
   const raw = res.items?.[0];
-  return raw ? toDetail(raw as Raw) : null;
+  return raw ? toDetail(raw as Raw, imgSrc) : null;
 }
 
 /** Service categories for a filter bar — non-fatal (empty array on failure). */
 export async function fetchBookingCategories(): Promise<BookingCategory[]> {
   try {
     const res = await categories.queryCategories().find();
-    return (res.items ?? []).map((c: Raw) => ({ id: c._id ?? "", name: c.name ?? "" })).filter((c) => c.id);
+    return ((res.items ?? []) as Raw[]).map(toCategory).filter((c) => c.id);
   } catch {
     return [];
   }

package/skills/wix-headless-fast/references/bookings/app/wix/bookings/types.ts

@@ -56,12 +56,14 @@ export interface Slot {
   staff: { id: string; name: string }[];
 }
 
-/** A booking-form field (flat, from getFormSummary; values are keyed by `target`). */
+/** A booking-form field (flat, from the form summary + schema; values are keyed by `target`). */
 export interface BookingFormField {
   target: string;
   label: string;
   type: "STRING" | "EMAIL" | "PHONE" | "NUMBER" | "URL";
   options?: string[];
+  /** The form marks it required — the only fields that gate `canBook`; the rest may stay empty. */
+  required: boolean;
 }
 
 /** The outcome of book(): either the browser is being redirected, or it's done. */

package/skills/wix-headless-fast/references/bookings/rest/booking.ts

@@ -0,0 +1,113 @@
+// Availability, 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: a taken slot, a
+// refused cart, a checkout that won't start all throw — surface the message to the visitor.
+// 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-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 {
+  FALLBACK_FIELDS,
+  appointmentSlotsRequest,
+  bookingCartRequest,
+  bookingIdOf,
+  bookingRequest,
+  cartIdOf,
+  cartTotal,
+  checkoutRedirectRequest,
+  checkoutRequired,
+  classSlotsRequest,
+  confirmedResult,
+  defaultTimeZone,
+  toFormFields,
+  toLocalDateString,
+  toSlot,
+  type Raw,
+  type SlotsWindow,
+} from "./booking-core.js";
+import type { BookingFormField, BookingResult, ServiceDetail, Slot } from "./types.js";
+
+export { toLocalDateString };
+
+/**
+ * Bookable slots for a service in [from, from + days) — APPOINTMENT and CLASS use different APIs;
+ * this branches for you. Dates are local wall-clock; timeZone defaults to the visitor's.
+ * APPOINTMENT: POST /service-availability/v2/time-slots  { serviceId, fromLocalDate, toLocalDate, timeZone, bookable, cursorPaging, includeResourceTypeIds, resourceTypes? }
+ * CLASS:       POST /service-availability/v2/time-slots/event  { serviceIds, fromLocalDate, toLocalDate, timeZone, includeNonBookable, eventFilter? }
+ */
+export async function fetchSlots(service: Pick<ServiceDetail, "id" | "type">, window: SlotsWindow = {}): Promise<Slot[]> {
+  const res =
+    service.type === "CLASS"
+      ? await wixRequest<Raw>("/service-availability/v2/time-slots/event", { body: classSlotsRequest(service.id, window) })
+      : await wixRequest<Raw>("/service-availability/v2/time-slots", { body: appointmentSlotsRequest(service.id, window) });
+  return ((res?.timeSlots ?? []) as Raw[]).map(toSlot);
+}
+
+/**
+ * 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: createBooking → createCart (holds the seat) → calculateCart → hosted checkout (paid)
+ * or placeOrder (free / pay-in-person). 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, formSubmission }
+ *   POST /ecom/v2/carts                   { catalogItems: [{ quantity: 1, catalogReference: { catalogItemId: <bookingId>, appId } }], cart: { source: { channelType: "WEB" } } }
+ *   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,
+  formValues: Record<string, unknown>,
+  {
+    staffId,
+    timeZone = defaultTimeZone(),
+    origin = typeof window !== "undefined" ? window.location.origin : "",
+  }: { staffId?: string; timeZone?: string; origin?: string } = {},
+): Promise<BookingResult> {
+  const created = await wixRequest<Raw>("/bookings/v2/bookings", {
+    body: { booking: bookingRequest(service, slot, { staffId, timeZone, idKey: "id" }), formSubmission: 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) });
+  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, cartTotal(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-fast/references/bookings/rest/services.ts

@@ -0,0 +1,55 @@
+// 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/categories-v2/query-categories.md
+import { wixRequest } from "./client.js";
+import { imgSrc } from "./media.js";
+import {
+  BOOKINGS_APP_ID,
+  SERVICES_CONDITIONAL_FIELDS,
+  STAFF_RESOURCE_TYPE_ID,
+  isVisible,
+  servicesFilter,
+  toCategory,
+  toDetail,
+  toSummary,
+  type Raw,
+} from "./services-core.js";
+import type { BookingCategory, ServiceDetail, ServiceSummary } from "./types.js";
+
+export { BOOKINGS_APP_ID, STAFF_RESOURCE_TYPE_ID };
+
+// POST /bookings/v2/services/query  { query: { filter, paging: { limit } }, conditionalFields }
+async function queryServices(slug: string | undefined, limit: number): Promise<Raw[]> {
+  const res = await wixRequest<Raw>("/bookings/v2/services/query", {
+    body: { query: { filter: servicesFilter(slug), paging: { limit } }, conditionalFields: SERVICES_CONDITIONAL_FIELDS },
+  });
+  return (res?.services ?? []) as Raw[];
+}
+
+/** List bookable services (hidden ones filtered), mapped to grid-ready DTOs. */
+export async function fetchServices({ limit = 100 } = {}): Promise<ServiceSummary[]> {
+  return (await queryServices(undefined, limit)).filter(isVisible).map((s) => toSummary(s, imgSrc));
+}
+
+/** 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];
+  return raw ? toDetail(raw, imgSrc) : null;
+}
+
+/**
+ * Service categories for a filter bar — non-fatal (empty array on failure).
+ * POST /bookings/v2/categories/query  { query: {} }
+ */
+export async function fetchBookingCategories(): Promise<BookingCategory[]> {
+  try {
+    const res = await wixRequest<Raw>("/bookings/v2/categories/query", { body: { query: {} } });
+    return ((res?.categories ?? []) as Raw[]).map(toCategory).filter((c) => c.id);
+  } catch {
+    return [];
+  }
+}

package/skills/wix-headless-fast/references/bookings/seed/SEED.md

@@ -51,6 +51,16 @@ image leaves that service text-only.
 **Seeding is additive — never delete or overwrite existing content**; ask first if a cleanup
 seems needed.
 
+## Supplied content
+
+The general rules are in `references/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`; 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 one `sessions` entry per listed
+time; everything else is an `APPOINTMENT`. A category or group becomes `category`. Their photo
+becomes `imageUrl`. A service with no duration is a question for the user. Staff members and
+opening hours are not seeded — say so; the owner sets them in the dashboard.
+
 ## Escape hatch — individual functions
 `setupBookings` composes exported steps — `installBookingsApp`, `queryStaffWithRetry`,
 `createCategories`, `createServices`, `scheduleClassSessions`, `importImage`,

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

@@ -0,0 +1,28 @@
+// What the booking business holds: services, staff, categories.
+//   node <SKILL_ROOT>/references/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 })),
+    };
+  },
+});