@wix/agent-skills 1.16.3 → 1.18.0

package/skills/wix-headless-fast/references/bookings/app/components/bookings/ServicesView.tsx

@@ -0,0 +1,119 @@
+// REFERENCE listing surface: category filter + services grid on the @theme tokens.
+// Correct and complete; per the skill's model you design and build your own on useServices.
+import type { ComponentType, ReactNode } from "react";
+import { useServices } from "../../hooks/bookings/useServices";
+import type { BookingCategory, ServiceSummary } from "../../wix/bookings/types";
+
+export interface LinkLikeProps {
+  href: string;
+  className?: string;
+  children?: ReactNode;
+}
+
+const PlainLink = ({ href, className, children }: LinkLikeProps) => (
+  <a href={href} className={className}>
+    {children}
+  </a>
+);
+
+export interface ServiceCardProps {
+  service: ServiceSummary;
+  serviceHref?: (slug: string) => string;
+  LinkComponent?: ComponentType<LinkLikeProps>;
+}
+
+export function ServiceCard({
+  service,
+  serviceHref = (slug) => `/services/${slug}`,
+  LinkComponent = PlainLink,
+}: ServiceCardProps) {
+  return (
+    <LinkComponent href={serviceHref(service.slug)} className="group block no-underline">
+      <div className="relative aspect-[4/3] overflow-hidden rounded-lg bg-secondary">
+        {service.imageUrl && (
+          <img
+            src={service.imageUrl}
+            alt={service.name}
+            loading="lazy"
+            className="h-full w-full object-cover transition-transform duration-300 group-hover:scale-[1.03]"
+          />
+        )}
+        <span className="absolute left-3 top-3 rounded-full bg-background/90 px-3 py-1 text-xs font-semibold text-foreground backdrop-blur">
+          {service.type === "CLASS" ? "Class" : "Appointment"}
+        </span>
+      </div>
+      <p className="mt-3 text-sm font-medium text-foreground">{service.name}</p>
+      {service.tagLine && <p className="mt-0.5 text-xs text-muted-foreground">{service.tagLine}</p>}
+      <p className="mt-1 text-sm text-muted-foreground">
+        {service.durationMinutes ? `${service.durationMinutes} min · ` : ""}
+        <span className="text-foreground">{service.price}</span>
+      </p>
+    </LinkComponent>
+  );
+}
+
+export interface ServicesViewProps {
+  initialServices?: ServiceSummary[];
+  initialCategories?: BookingCategory[];
+  emptyMessage?: string;
+  serviceHref?: ServiceCardProps["serviceHref"];
+  LinkComponent?: ComponentType<LinkLikeProps>;
+  CardComponent?: ComponentType<ServiceCardProps>;
+}
+
+const pill = (active: boolean) =>
+  `rounded-full border px-4 py-1.5 text-sm font-medium transition-colors ${
+    active
+      ? "border-primary bg-primary text-primary-foreground"
+      : "border-border text-foreground hover:bg-secondary"
+  }`;
+
+export default function ServicesView({
+  initialServices,
+  initialCategories,
+  emptyMessage = "No services yet — check back soon.",
+  serviceHref,
+  LinkComponent,
+  CardComponent = ServiceCard,
+}: ServicesViewProps) {
+  const { services, categories, activeCategoryId, setActiveCategoryId, error } = useServices({
+    initialServices,
+    initialCategories,
+  });
+
+  return (
+    <div>
+      {categories.length > 1 && (
+        <div className="mb-8 flex flex-wrap gap-2" role="group" aria-label="Categories">
+          <button type="button" className={pill(activeCategoryId === null)} onClick={() => setActiveCategoryId(null)}>
+            All
+          </button>
+          {categories.map((c) => (
+            <button key={c.id} type="button" className={pill(activeCategoryId === c.id)} onClick={() => setActiveCategoryId(c.id)}>
+              {c.name}
+            </button>
+          ))}
+        </div>
+      )}
+      {error && <p className="mb-4 text-sm text-red-600">{error}</p>}
+      {services === null ? (
+        <div className="grid grid-cols-1 gap-8 sm:grid-cols-2 lg:grid-cols-3" aria-busy="true">
+          {Array.from({ length: 6 }, (_, i) => (
+            <div key={i}>
+              <div className="aspect-[4/3] animate-pulse rounded-lg bg-secondary" />
+              <div className="mt-3 h-3.5 w-2/3 animate-pulse rounded bg-secondary" />
+            </div>
+          ))}
+        </div>
+      ) : services.length === 0 ? (
+        <p className="py-16 text-center text-muted-foreground">{emptyMessage}</p>
+      ) : (
+        <div className="grid grid-cols-1 gap-8 sm:grid-cols-2 lg:grid-cols-3">
+          {services.map((s) => (
+            <CardComponent key={s.id} service={s} serviceHref={serviceHref} LinkComponent={LinkComponent} />
+          ))}
+        </div>
+      )}
+    </div>
+  );
+}

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

@@ -0,0 +1,138 @@
+// The whole booking state machine for one service: availability window (day-grouped slots,
+// week paging, optional staff filter), the schema-driven form, and book(). All correctness
+// (slot scheduleId vs eventId, ANY_RESOURCE, formSubmission, payment option, checkout-or-
+// place) lives in the data layer — this hook orchestrates; you own how it looks.
+import { useEffect, useMemo, useState } from "react";
+import { bookService, fetchBookingForm, fetchSlots } from "../../wix/bookings/booking";
+import type { BookingFormField, BookingResult, ServiceDetail, Slot } from "../../wix/bookings/types";
+
+export interface UseBookingFlow {
+  /** Slots grouped by day, in order — [{ dayKey, dayLabel, slots }]. null while loading. */
+  days: { dayKey: string; dayLabel: string; slots: Slot[] }[] | null;
+  /** The 7-day window start; page with nextWeek/prevWeek (prev clamps to today). */
+  windowStart: Date;
+  nextWeek: () => void;
+  prevWeek: () => void;
+  /** Staff filter — render a picker only when service.staff.length > 1. */
+  staffId: string | undefined;
+  setStaffId: (id: string | undefined) => void;
+  selectedSlot: Slot | null;
+  setSelectedSlot: (s: Slot | null) => void;
+  /** Schema-driven form fields (never empty — contact basics fallback). */
+  formFields: BookingFormField[];
+  values: Record<string, string>;
+  setValue: (target: string, value: string) => void;
+  /** True when a slot is selected and every field has a value. */
+  canBook: boolean;
+  /** Books the selected slot. On "redirect" the browser is already navigating. */
+  book: () => Promise<BookingResult>;
+  booking: boolean;
+  /** Set after a free/offline booking completes. */
+  confirmed: BookingResult | null;
+  error: string | null;
+}
+
+const dayLabel = (dayKey: string): string => {
+  try {
+    return new Date(`${dayKey}T12:00:00`).toLocaleDateString(undefined, {
+      weekday: "short",
+      month: "short",
+      day: "numeric",
+    });
+  } catch {
+    return dayKey;
+  }
+};
+
+export function useBookingFlow(service: ServiceDetail): UseBookingFlow {
+  const [windowStart, setWindowStart] = useState<Date>(() => new Date());
+  const [staffId, setStaffId] = useState<string | undefined>(undefined);
+  const [slots, setSlots] = useState<Slot[] | null>(null);
+  const [selectedSlot, setSelectedSlot] = useState<Slot | null>(null);
+  const [formFields, setFormFields] = useState<BookingFormField[]>([]);
+  const [values, setValues] = useState<Record<string, string>>({});
+  const [booking, setBooking] = useState(false);
+  const [confirmed, setConfirmed] = useState<BookingResult | null>(null);
+  const [error, setError] = useState<string | null>(null);
+
+  useEffect(() => {
+    let alive = true;
+    setSlots(null);
+    setSelectedSlot(null);
+    fetchSlots(service, { from: windowStart, days: 7, staffId })
+      .then((s) => alive && setSlots(s))
+      .catch((e) => {
+        if (!alive) return;
+        setSlots([]);
+        setError(e instanceof Error ? e.message : String(e));
+      });
+    return () => {
+      alive = false;
+    };
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [service.id, windowStart, staffId]);
+
+  useEffect(() => {
+    let alive = true;
+    fetchBookingForm(service.formId).then((f) => alive && setFormFields(f));
+    return () => {
+      alive = false;
+    };
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [service.formId]);
+
+  const days = useMemo(() => {
+    if (slots === null) return null;
+    const byDay = new Map<string, Slot[]>();
+    for (const s of slots) byDay.set(s.dayKey, [...(byDay.get(s.dayKey) ?? []), s]);
+    return [...byDay.entries()]
+      .sort(([a], [b]) => a.localeCompare(b))
+      .map(([dayKey, daySlots]) => ({ dayKey, dayLabel: dayLabel(dayKey), slots: daySlots }));
+  }, [slots]);
+
+  const canBook =
+    !!selectedSlot && formFields.every((f) => (values[f.target] ?? "").trim().length > 0);
+
+  async function book(): Promise<BookingResult> {
+    if (!selectedSlot) throw new Error("Pick a time first.");
+    setBooking(true);
+    setError(null);
+    try {
+      const result = await bookService(service, selectedSlot, values, { staffId });
+      if (result.kind === "redirect") {
+        window.location.href = result.url;
+      } else {
+        setConfirmed(result);
+      }
+      return result;
+    } catch (e) {
+      setError(e instanceof Error ? e.message : String(e));
+      throw e;
+    } finally {
+      setBooking(false);
+    }
+  }
+
+  return {
+    days,
+    windowStart,
+    nextWeek: () => setWindowStart((d) => new Date(d.getTime() + 7 * 24 * 3600 * 1000)),
+    prevWeek: () =>
+      setWindowStart((d) => {
+        const prev = new Date(d.getTime() - 7 * 24 * 3600 * 1000);
+        return prev < new Date() ? new Date() : prev;
+      }),
+    staffId,
+    setStaffId,
+    selectedSlot,
+    setSelectedSlot,
+    formFields,
+    values,
+    setValue: (target, value) => setValues((v) => ({ ...v, [target]: value })),
+    canBook,
+    book,
+    booking,
+    confirmed,
+    error,
+  };
+}

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

@@ -0,0 +1,54 @@
+// Services listing + category filter. SSR-friendly: pass server-fetched data as `initial*`
+// (Astro frontmatter / server component) and no client fetch happens; a SPA passes nothing.
+// Category filtering is client-side (bookings catalogs are small and fully fetched).
+import { useEffect, useMemo, useState } from "react";
+import { fetchBookingCategories, fetchServices } from "../../wix/bookings/services";
+import type { BookingCategory, ServiceSummary } from "../../wix/bookings/types";
+
+export interface UseServicesOptions {
+  initialServices?: ServiceSummary[];
+  initialCategories?: BookingCategory[];
+}
+
+export interface UseServices {
+  /** null while the first load is in flight — render skeletons, not an empty state. */
+  services: ServiceSummary[] | null;
+  categories: BookingCategory[];
+  activeCategoryId: string | null;
+  setActiveCategoryId: (id: string | null) => void;
+  error: string | null;
+}
+
+export function useServices({ initialServices, initialCategories }: UseServicesOptions = {}): UseServices {
+  const [all, setAll] = useState<ServiceSummary[] | null>(initialServices ?? null);
+  const [categories, setCategories] = useState<BookingCategory[]>(initialCategories ?? []);
+  const [activeCategoryId, setActiveCategoryId] = useState<string | null>(null);
+  const [error, setError] = useState<string | null>(null);
+
+  useEffect(() => {
+    let alive = true;
+    if (!initialServices) {
+      fetchServices()
+        .then((s) => alive && setAll(s))
+        .catch((e) => {
+          if (!alive) return;
+          setAll([]);
+          setError(e instanceof Error ? e.message : String(e));
+        });
+    }
+    if (!initialCategories) {
+      fetchBookingCategories().then((c) => alive && setCategories(c));
+    }
+    return () => {
+      alive = false;
+    };
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, []);
+
+  const services = useMemo(() => {
+    if (all === null) return null;
+    return activeCategoryId ? all.filter((s) => s.categoryId === activeCategoryId) : all;
+  }, [all, activeCategoryId]);
+
+  return { services, categories, activeCategoryId, setActiveCategoryId, error };
+}

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

@@ -0,0 +1,206 @@
+// 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.
+// 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-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,
+} 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 type { BookingFormField, BookingResult, ServiceDetail, Slot } from "./types";
+
+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;
+ * 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));
+}
+
+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 —
+ * so the form can render unconditionally.
+ */
+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;
+  } 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 a friendly message on refusal (slot taken, invalid
+ * form) — surface it, don't swallow it.
+ */
+export async function bookService(
+  service: ServiceDetail,
+  slot: Slot,
+  formValues: Record<string, unknown>,
+  { staffId, timeZone = Intl.DateTimeFormat().resolvedOptions().timeZone }: { 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,
+    { formSubmission: formValues } as any,
+  );
+  const bookingId: string | undefined = created.booking?._id;
+  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;
+  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) {
+    const origin = typeof window !== "undefined" ? window.location.origin : "";
+    const session: Raw = await redirects.createRedirectSession({
+      ecomCheckout: { checkoutId: cartId },
+      callbacks: { postFlowUrl: origin ? `${origin}/` : undefined },
+    });
+    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 };
+}

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

@@ -0,0 +1,96 @@
+// 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.
+// 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";
+
+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 })
+    .eq("appId", BOOKINGS_APP_ID)
+    .limit(limit)
+    .find();
+  return (res.items ?? []).filter((s: Raw) => !s.hidden).map((s: Raw) => toSummary(s));
+}
+
+/** 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 })
+    .eq("mainSlug.name", slug)
+    .eq("appId", BOOKINGS_APP_ID)
+    .limit(1)
+    .find();
+  const raw = res.items?.[0];
+  return raw ? toDetail(raw as Raw) : 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);
+  } catch {
+    return [];
+  }
+}

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

@@ -0,0 +1,70 @@
+// Bookings DTOs — the serializable shapes every hook, component, and page consumes.
+// Plain JSON: safe as Astro island props or across server/client boundaries. Images are
+// resolved https URLs; every displayable price is a ready formatted string.
+
+export type ServiceType = "APPOINTMENT" | "CLASS";
+
+/** A service as a listing/grid tile needs it. */
+export interface ServiceSummary {
+  id: string;
+  slug: string;
+  name: string;
+  tagLine: string;
+  type: ServiceType;
+  /** Formatted price (e.g. "€75.00"); "Free" when the service has no fee. */
+  price: string;
+  free: boolean;
+  /** Session length in minutes (appointments; classes may have none). */
+  durationMinutes: number | null;
+  /** Resolved https URL ("" when the service has no image). */
+  imageUrl: string;
+  categoryId: string | null;
+  /** Bookable staff: id is the resource GUID used for filtering and booking. */
+  staff: { id: string; name: string }[];
+}
+
+/** A service as the booking page needs it. */
+export interface ServiceDetail extends ServiceSummary {
+  /** Description HTML/text as stored. */
+  description: string;
+  /** The @wix/forms booking-form id (null → the contact-basics fallback form). */
+  formId: string | null;
+  /** Derived payment option the booking must send ("ONLINE" | "OFFLINE"). */
+  paymentOption: "ONLINE" | "OFFLINE";
+  /** True → checkout is always required regardless of price (cancellation-fee policy). */
+  cancellationFeeEnabled: boolean;
+}
+
+export interface BookingCategory {
+  id: string;
+  name: string;
+}
+
+/** One bookable time slot, appointment or class. */
+export interface Slot {
+  /** Local wall-clock strings "YYYY-MM-DDThh:mm:ss" (no Z). */
+  startLocal: string;
+  endLocal: string;
+  /** "YYYY-MM-DD" — for grouping slots by day. */
+  dayKey: string;
+  /** Display label, e.g. "9:00 AM". */
+  label: string;
+  /** APPOINTMENT slots carry their own scheduleId; CLASS slots carry an eventId instead. */
+  scheduleId: string | null;
+  eventId: string | null;
+  /** Staff able to take this slot (may be empty — ANY_RESOURCE still books). */
+  staff: { id: string; name: string }[];
+}
+
+/** A booking-form field (flat, from getFormSummary; values are keyed by `target`). */
+export interface BookingFormField {
+  target: string;
+  label: string;
+  type: "STRING" | "EMAIL" | "PHONE" | "NUMBER" | "URL";
+  options?: string[];
+}
+
+/** The outcome of book(): either the browser is being redirected, or it's done. */
+export type BookingResult =
+  | { kind: "redirect"; url: string }
+  | { kind: "confirmed"; bookingId: string; orderId: string | null };