@wix/agent-skills 1.19.2 → 1.20.1

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

@@ -1,6 +1,8 @@
-// Availability, the booking form, and the createBooking → Cart V2 → checkout-or-place
-// sequence. The payload shapes here are exact and easy to get subtly wrong — copy as-is;
-// extend by calling these exports, never by editing them. Failures are loud.
+// Availability, 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 references/bookings/rest/); this file is the
+// transport only. Copy as-is; extend by calling these exports, never by editing them. Failures
+// are loud.
 // 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
@@ -9,106 +11,51 @@
 // 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,
-} from "@wix/bookings";
+import { availabilityTimeSlots, eventTimeSlots, bookings as bookingsModule } from "@wix/bookings";
 import { createCart, calculateCart, placeOrder } from "@wix/auto_sdk_ecom_cart-v-2";
 import { redirects as redirectsModule } from "@wix/redirects";
-import { forms as formsModule } from "@wix/forms";
-import { wixModule } from "../sdk";
-import { BOOKINGS_APP_ID, STAFF_RESOURCE_TYPE_ID } from "./services";
+import { wixFetch, wixModule } from "../sdk";
+import {
+  FALLBACK_FIELDS,
+  appointmentSlotsRequest,
+  bookingCartRequest,
+  bookingIdOf,
+  bookingRequest,
+  cartIdOf,
+  cartTotal,
+  checkoutRedirectRequest,
+  checkoutRequired,
+  classSlotsRequest,
+  confirmedResult,
+  defaultTimeZone,
+  toFormFields,
+  toLocalDateString,
+  toSlot,
+  type Raw,
+  type SlotsWindow,
+} from "./booking-core";
 import type { BookingFormField, BookingResult, ServiceDetail, Slot } from "./types";
 
+export { toLocalDateString };
+
 const apptSlots = wixModule(availabilityTimeSlots);
 const classSlots = wixModule(eventTimeSlots);
 const bookings = wixModule(bookingsModule);
 const cart = wixModule({ createCart, calculateCart, placeOrder });
 const redirects = wixModule(redirectsModule);
-const forms = wixModule(formsModule);
-
-type Raw = Record<string, any>;
-
-const pad = (n: number) => String(n).padStart(2, "0");
-/** Local wall-clock "YYYY-MM-DDThh:mm:ss" (NO Z) — the format the availability APIs require. */
-export function toLocalDateString(d: Date): string {
-  return `${d.getFullYear()}-${pad(d.getMonth() + 1)}-${pad(d.getDate())}T${pad(d.getHours())}:${pad(d.getMinutes())}:${pad(d.getSeconds())}`;
-}
-
-function toSlot(raw: Raw): Slot {
-  const start: string = raw.localStartDate ?? "";
-  const staff = (raw.availableResources ?? [])
-    .flatMap((ar: Raw) => ar.resources ?? [])
-    .map((r: Raw) => ({ id: r._id ?? "", name: r.name ?? "" }))
-    .filter((r: { id: string }) => r.id);
-  let label = start.slice(11, 16);
-  try {
-    label = new Date(start).toLocaleTimeString(undefined, { hour: "numeric", minute: "2-digit" });
-  } catch {
-    /* keep the hh:mm fallback */
-  }
-  return {
-    startLocal: start,
-    endLocal: raw.localEndDate ?? "",
-    dayKey: start.slice(0, 10),
-    label,
-    scheduleId: raw.scheduleId ?? null,
-    eventId: raw.eventInfo?.eventId ?? null,
-    staff,
-  };
-}
 
 /**
- * Bookable slots for a service in [from, to) — APPOINTMENT and CLASS use different APIs;
+ * 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.
  */
-export async function fetchSlots(
-  service: Pick<ServiceDetail, "id" | "type">,
-  {
-    from = new Date(),
-    days = 7,
-    timeZone = Intl.DateTimeFormat().resolvedOptions().timeZone,
-    staffId,
-  }: { from?: Date; days?: number; timeZone?: string; staffId?: string } = {},
-): Promise<Slot[]> {
-  const to = new Date(from.getTime() + days * 24 * 3600 * 1000);
-  const fromLocalDate = toLocalDateString(from);
-  const toLocalDate = toLocalDateString(to);
-
-  if (service.type === "CLASS") {
-    const res: Raw = await classSlots.listEventTimeSlots({
-      serviceIds: [service.id],
-      fromLocalDate,
-      toLocalDate,
-      timeZone,
-      includeNonBookable: false,
-      ...(staffId ? { eventFilter: { "resources.id": { $hasSome: [staffId] } } } : {}),
-    } as any);
-    return (res.timeSlots ?? []).map((t: Raw) => toSlot(t));
-  }
-
-  const res: Raw = await apptSlots.listAvailabilityTimeSlots({
-    serviceId: service.id,
-    fromLocalDate,
-    toLocalDate,
-    timeZone,
-    bookable: true,
-    cursorPaging: { limit: 100 },
-    includeResourceTypeIds: [STAFF_RESOURCE_TYPE_ID],
-    ...(staffId
-      ? { resourceTypes: [{ resourceTypeId: STAFF_RESOURCE_TYPE_ID, resourceIds: [staffId] }] }
-      : {}),
-  } as any);
-  return (res.timeSlots ?? []).map((t: Raw) => toSlot(t));
+export async function fetchSlots(service: Pick<ServiceDetail, "id" | "type">, window: SlotsWindow = {}): Promise<Slot[]> {
+  const res: Raw =
+    service.type === "CLASS"
+      ? await classSlots.listEventTimeSlots(classSlotsRequest(service.id, window) as any)
+      : await apptSlots.listAvailabilityTimeSlots(appointmentSlotsRequest(service.id, window) as any);
+  return ((res.timeSlots ?? []) as Raw[]).map(toSlot);
 }
 
-const FALLBACK_FIELDS: BookingFormField[] = [
-  { target: "first_name", label: "First Name", type: "STRING" },
-  { target: "last_name", label: "Last Name", type: "STRING" },
-  { target: "email", label: "Email", type: "EMAIL" },
-];
-
 /**
  * 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 —
@@ -117,18 +64,20 @@ const FALLBACK_FIELDS: BookingFormField[] = [
 export async function fetchBookingForm(formId: string | null): Promise<BookingFormField[]> {
   if (!formId) return FALLBACK_FIELDS;
   try {
-    const res: Raw = await forms.getFormSummary(formId);
-    const fields = (res.formSummary?.fields ?? [])
-      .filter((f: Raw) => !f.deleted)
-      .filter((f: Raw) => f.type && ["STRING", "EMAIL", "PHONE", "NUMBER", "URL"].includes(f.type))
-      .map((f: Raw) => ({
-        target: f.target ?? "",
-        label: f.label ?? f.target ?? "",
-        type: f.type,
-        ...(Array.isArray(f.options) && f.options.length ? { options: f.options } : {}),
-      }))
-      .filter((f: BookingFormField) => f.target);
-    return fields.length ? fields : FALLBACK_FIELDS;
+    // 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;
   }
@@ -145,62 +94,28 @@ export async function bookService(
   service: ServiceDetail,
   slot: Slot,
   formValues: Record<string, unknown>,
-  { staffId, timeZone = Intl.DateTimeFormat().resolvedOptions().timeZone }: { staffId?: string; timeZone?: string } = {},
+  { staffId, timeZone = defaultTimeZone() }: { staffId?: string; timeZone?: string } = {},
 ): Promise<BookingResult> {
-  const staff = staffId ? slot.staff.find((s) => s.id === staffId) : undefined;
   const created: Raw = await bookings.createBooking(
-    {
-      selectedPaymentOption: service.paymentOption,
-      totalParticipants: 1,
-      bookedEntity: {
-        slot: {
-          serviceId: service.id,
-          scheduleId: slot.scheduleId ?? undefined, // APPOINTMENT: the SLOT's scheduleId (never service.schedule.id)
-          eventId: slot.eventId ?? undefined, // CLASS
-          startDate: slot.startLocal,
-          endDate: slot.endLocal,
-          timezone: timeZone,
-          ...(staff
-            ? { resource: { _id: staff.id, name: staff.name } }
-            : {
-                resourceSelections: [
-                  { resourceTypeId: STAFF_RESOURCE_TYPE_ID, selectionMethod: "ANY_RESOURCE" },
-                ],
-              }),
-          location: { locationType: "OWNER_BUSINESS" },
-        },
-      },
-    } as any,
+    bookingRequest(service, slot, { staffId, timeZone, idKey: "_id" }) as any,
     { formSubmission: formValues } as any,
   );
-  const bookingId: string | undefined = created.booking?._id;
+  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({
-    catalogItems: [
-      { quantity: 1, catalogReference: { catalogItemId: bookingId, appId: BOOKINGS_APP_ID } },
-    ],
-    cart: { source: { channelType: "WEB" } },
-  } as any);
-  const cartId: string | undefined = newCart._id ?? newCart.cart?._id;
+  const newCart: Raw = await cart.createCart(bookingCartRequest(bookingId) 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);
-  const total = Number(calc?.summary?.priceSummary?.total?.amount ?? 0);
-  const checkoutRequired =
-    service.cancellationFeeEnabled || (total > 0 && service.paymentOption !== "OFFLINE");
-
-  if (checkoutRequired) {
+  if (checkoutRequired(service, cartTotal(calc))) {
     const origin = typeof window !== "undefined" ? window.location.origin : "";
-    const session: Raw = await redirects.createRedirectSession({
-      ecomCheckout: { checkoutId: cartId },
-      callbacks: { postFlowUrl: origin ? `${origin}/` : undefined },
-    });
+    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 { kind: "confirmed", bookingId, orderId: order?.orderId ?? order?.order?._id ?? null };
+  return confirmedResult(bookingId, order);
 }

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. */