@wix/agent-skills 1.8.0 → 1.9.0

package/skills/wix-headless/references/astro/templates/bookings/services/[slug].astro

@@ -5,26 +5,77 @@ import Layout from "../../layouts/Layout.astro";
 import SeoTags from "../../components/SeoTags.astro";
 import ServiceBookingFlow from "../../components/ServiceBookingFlow";
 import { services } from "@wix/bookings";
+import { forms } from "@wix/forms";
 import { auth } from "@wix/essentials";
 
+const BOOKING_APP_ID = "13d21c63-b5ec-5912-8397-c3a5ddb27a97";
 const { slug } = Astro.params;
 
 let service: any = null;
 try {
-  // Ambient SSR via @wix/essentials; query BUILDER (object form returns 0).
-  // Fetch the small catalog and match the slug in JS (robust without a
-  // nested-field `mainSlug.name` builder filter).
-  const result = await auth.elevate(services.queryServices)().limit(100).find();
-  service =
-    (result.items ?? []).find(
-      (s: any) => (s.mainSlug?.name ?? s.supportedSlugs?.[0]?.name) === slug,
-    ) ?? null;
+  // Ambient SSR via @wix/essentials. Single service by slug: the .eq() builder
+  // chain on mainSlug.name + appId (the form the @wix/bookings SDK expects).
+  const result = await auth
+    .elevate(services.queryServices)({ conditionalFields: ["STAFF_MEMBER_DETAILS"] })
+    .eq("mainSlug.name", slug)
+    .eq("appId", BOOKING_APP_ID)
+    .limit(1)
+    .find();
+  service = result.items?.[0] ?? null;
 } catch (err) {
   console.error(`[services/${slug}] detail query failed:`, err);
 }
 
 if (!service) return Astro.redirect("/services", 302);
 
+// Booking-form SCHEMA — the form belongs to the service (service.form._id) in the
+// bookings namespace. Read it server-side and pass the field list to the island.
+// Same renderer the forms vertical uses (references/astro/forms/CONTACT_FORM.md):
+// keep the field's `target` — that is the key createBooking expects in formSubmission.
+let formFields: any[] = [];
+try {
+  const formId = service.form?._id;
+  if (formId) {
+    const res: any = await auth.elevate(forms.getForm)(formId);
+    const form = res?.form ?? res;
+    // Only render field types we can submit as a simple value. Skip complex,
+    // object-valued fields (e.g. a multi-line ADDRESS) — they carry no string
+    // `componentType`, and sending a string for them fails createBooking with
+    // "must be object". The booking enforces only the contact basics
+    // (first_name/last_name/email), so skipping optional complex fields is safe.
+    const RENDERABLE = ["TEXT_INPUT", "PHONE_INPUT", "DROPDOWN"];
+    formFields = (form?.formFields ?? [])
+      .filter(
+        (f: any) =>
+          f.fieldType === "INPUT" &&
+          !f.hidden &&
+          RENDERABLE.includes(f.inputOptions?.stringOptions?.componentType),
+      )
+      .map((f: any) => {
+        const opts = f.inputOptions;
+        const str = opts?.stringOptions;
+        const label =
+          str?.textInputOptions?.label ??
+          str?.dropdownOptions?.label ??
+          str?.phoneInputOptions?.label ??
+          "";
+        return {
+          label,
+          target: opts?.target ?? "",
+          required: opts?.required ?? false,
+          componentType: str?.componentType ?? "TEXT_INPUT",
+          identifier: f.identifier ?? "",
+          options: str?.dropdownOptions?.options?.map((o: any) => ({
+            value: o.value ?? o.label ?? "",
+            label: o.label ?? o.value ?? "",
+          })),
+        };
+      });
+  }
+} catch (err) {
+  console.error(`[services/${slug}] booking form schema failed:`, err);
+}
+
 const formatPrice = (p: any): string | undefined => {
   if (!p || p.rateType === "NO_FEE") return undefined;
   if (p.rateType === "FIXED" && p.fixed?.price) {
@@ -71,9 +122,10 @@ const seoTags = service.seoData?.tags ?? [];
     <section class="border-t border-rule pt-2xl">
       <h2 class="font-display text-3xl leading-tight mb-xl">Book this service</h2>
       <ServiceBookingFlow
-        serviceId={service._id}
+        service={service}
         serviceName={serviceName}
         serviceType={service.type ?? "APPOINTMENT"}
+        fields={formFields}
         client:only="react"
       />
     </section>

package/skills/wix-headless/references/astro/templates/bookings/services/index.astro

@@ -7,13 +7,21 @@ import ServiceCard from "../../components/ServiceCard.astro";
 import { services } from "@wix/bookings";
 import { auth } from "@wix/essentials";
 
+// Wix Bookings app id — the base filter must scope queryServices to it.
+const BOOKING_APP_ID = "13d21c63-b5ec-5912-8397-c3a5ddb27a97";
+
 let serviceList: any[] = [];
 try {
   // Ambient @wix/astro SSR client via @wix/essentials (same pattern as CMS pages).
   // Do NOT build createClient({ auth: OAuthStrategy({ clientId: import.meta.env.* }) }) —
   // that env var is client-only and undefined at server render → 500.
-  // queryServices uses the query BUILDER; the object form returns 0 items.
-  const result = await auth.elevate(services.queryServices)().limit(100).find();
+  // Pass the request object (filter must include appId) + conditionalFields, then .find().
+  const result = await auth
+    .elevate(services.queryServices)({
+      query: { filter: { appId: BOOKING_APP_ID }, paging: { limit: 100 } },
+      conditionalFields: ["STAFF_MEMBER_DETAILS"],
+    })
+    .find();
   serviceList = (result.items ?? []).filter((s: any) => !s.hidden);
 } catch (err) {
   console.error("[services] listing query failed:", err);

package/skills/wix-headless/references/bookings/FLOW.md

@@ -0,0 +1,185 @@
+# Bookings — the booking flow (framework-agnostic logic)
+
+The booking logic — the step model, the shared state, and the exact `@wix` SDK
+sequence — is the **same on every frontend** (astro, react/vite, vue, plain HTML).
+This file is that shared logic. The per-framework wiring layers on top:
+
+- **astro** (`frontendBuild: wix`): `../astro/bookings/SERVICES_PAGES.md` (SSR read pages) + `../astro/bookings/COMPONENTS.md` (the client islands).
+- **own / static** (`frontendBuild: own`/`none`): `../custom/bookings/WIRING.md`.
+
+**Code examples are React** (`../astro/templates/bookings/*.tsx` + `bookingDriver.ts`).
+React is directly usable on astro islands and on react/vite. **On any other
+framework, translate the examples** — the SDK calls and payloads are identical;
+only the UI idiom (`useState`/`useEffect` → a store / `onMounted` / signals) and
+the client acquisition differ (see "Client identity" below).
+
+The flow is **appointment booking**. CLASS sign-up reuses the same sequence with
+an event-slot branch (noted inline) and is a fast-follow, not v1. **Location and
+staff selection are likewise a fast-follow (a separate PR); add-ons are out of
+scope.** v1 threads a single service selection — the shared state below holds no
+location / staff / add-on choice yet.
+
+---
+
+## 1. The step model
+
+A single customer journey, five steps, holding one shared selection:
+
+```
+1. Catalog    list bookable services                         → pick a service
+2. Slots      week calendar of availability for that service → pick a time slot
+3. Details    the service's booking form (collect contact)   → submit
+4. Book       run the SDK sequence (§3)
+5a. paid      → redirect to the Wix-hosted checkout → returns to the confirmation page
+5b. free/offline → place the order → confirmation page
+```
+
+**The catalog is the entry point but optional** — a visitor can land directly on a
+service page and start at the Slots step. Every step rehydrates from the URL (§2),
+so deep links work.
+
+Mapping the steps onto pages/routes is the **target framework's choice** — translate
+the step model to whatever router the framework uses. The skill recommends the routes
+`/services`, `/services/[slug]`, `/booking-confirmation` (advertised in
+`../verticals/bookings.md`). On astro specifically, SSR the catalog + detail pages
+for SEO and run slots + form + book in a `client:only` island.
+
+## 2. Shared booking state
+
+Steps 1–4 build up one selection (this is exactly `BookParams` + `SelectedSlot`
+in `../astro/templates/bookings/bookingDriver.ts`):
+
+- **`service`** — the chosen service object (the booking step reads `service.payment` + `service.bookingPolicy`).
+- **`slot`** — `{ serviceType, serviceId, localStartDate, localEndDate, timezone, scheduleId?, eventId?, locationId?, locationType? }`.
+- **`formSubmission`** — the booking-form values, **keyed by each field's `target`** (§4).
+
+Hold it however the framework prefers (React state lifted to a coordinator, a
+store, route loaders + a provider, query-params). **Two rules that bite:**
+
+1. **Persist the selection before navigating.** When a step lives on its own
+   route, write the selection into the shared state (or the URL) *before* moving
+   on, and let the next step **rehydrate from the slug/URL** on direct load /
+   refresh. A persistent provider that does not re-init on in-app navigation will
+   otherwise show an empty next step.
+2. **The slug is the carry-across key.** `serviceSlug` (the service's
+   `mainSlug.name`) identifies the service across the slots + details steps;
+   resolve the full service from it when state is lost.
+
+## 3. The booking SDK sequence — `bookingDriver.ts`
+
+The whole booking — `createBooking → createCart → calculateCart → checkout-or-place`
+— is in **`../astro/templates/bookings/bookingDriver.ts`**, in plain `@wix` SDK
+calls (no React, no UI). **Use it as-is** (it is framework-agnostic); the booking
+step calls `book(params)` then branches on the result. Do not re-author the
+sequence — the payload shapes are exact and easy to get subtly wrong.
+
+```
+book({ service, slot, formSubmission, timezone }) →
+  createBooking(...)            // booking lands CREATED — the cart holds the seat
+  createCart(...)               // one catalog item per bookingId, appId = BOOKING_APP_ID, channel WEB
+  calculateCart(cartId)         // → { cart, summary }; totals on summary.priceSummary.total.amount
+  isCheckoutRequired(...) ?
+     → { CheckoutRequired, cartId }  // paid → navigateToCheckout(cartId, postFlowUrl) → Wix-hosted checkout
+     : placeOrder(cartId) → { CheckoutSkipped, orderId }   // free / pay-in-person → confirmation
+```
+
+Key facts the driver encodes (do not deviate):
+- **No `confirmBooking`** — `confirmBooking` is the classic Bookings server-side
+  confirm step (it moves a booking from `CREATED` to `CONFIRMED`). Here the **ecom
+  cart holds the seat** instead — `placeOrder` (free/offline) or the hosted checkout
+  (paid) drives confirmation — so a client-only site completes the whole flow with no
+  server elevation.
+- **ANY_RESOURCE fallback (staff)** — v1 has **no staff picker**, so `createBooking`
+  always sends `resourceSelections:[{ resourceTypeId:"1cd44cf8-…", selectionMethod:"ANY_RESOURCE" }]`
+  and Wix auto-assigns a bookable staff resource (appointment slots return
+  `availableResources:[]` yet book fine this way). (Explicit staff selection is a
+  fast-follow.)
+- **Checkout decision** — `isCheckoutRequired`: if the service's booking policy charges
+  a **cancellation fee** (`service.bookingPolicy.cancellationFeePolicy.enabled`) →
+  checkout (a card must be on file); else total 0 → place; else `FULL_PAYMENT_OFFLINE`
+  → place; else checkout.
+- **Redirect shape** — paid bookings hand the cart to the Wix-hosted **ecom**
+  checkout: `createRedirectSession({ ecomCheckout: { checkoutId: cartId }, callbacks:{ postFlowUrl } })`.
+
+### Browse + availability (the read calls the steps make)
+
+Mirror what the Bookings SDK does (`services.queryServices` is the raw SDK, not a component):
+
+```js
+// Catalog (list) — the filter MUST include appId; pass conditionalFields, then .find():
+services.queryServices({
+  query: { filter: { appId: BOOKING_APP_ID }, paging: { limit: 100 } },
+  conditionalFields: ["STAFF_MEMBER_DETAILS"],
+}).find();                                   // → result.items ; filter out s.hidden
+
+// Single service by slug — the .eq() builder chain:
+services.queryServices({ conditionalFields: ["STAFF_MEMBER_DETAILS"] })
+  .eq("mainSlug.name", slug).eq("appId", BOOKING_APP_ID).limit(1).find();
+
+// Availability (APPOINTMENT) — serviceId is a single GUID STRING:
+availabilityTimeSlots.listAvailabilityTimeSlots({
+  serviceId, fromLocalDate, toLocalDate, timeZone, bookable: true, cursorPaging: { limit: 100 },
+});                                          // slots: result.timeSlots[] (localStartDate/localEndDate/scheduleId at top level)
+
+// Availability (CLASS) — different namespace, PLURAL serviceIds; slots carry eventInfo.eventId, no scheduleId:
+eventTimeSlots.listEventTimeSlots({ serviceIds: [serviceId], fromLocalDate, toLocalDate, timeZone, includeNonBookable: false });
+```
+
+`fromLocalDate`/`toLocalDate` are **local** date strings `YYYY-MM-DDThh:mm:ss`
+(no `Z`) with an explicit `timeZone`.
+
+## 4. The booking form — schema-driven (`@wix/forms`)
+
+The booking form is a **`@wix/forms` form** attached to the service
+(`service.form._id`, namespace `wix.bookings.v2.bookings`). Render it
+**schema-driven** — read the field list and render inputs by field type — the
+**same renderer the forms vertical uses** (`../astro/forms/CONTACT_FORM.md`):
+
+1. Fetch the form by `service.form._id` (`@wix/forms` `getForm`; server-side/elevated
+   where the framework allows). Read `form.formFields`.
+2. Keep `fieldType === "INPUT" && !hidden` **and** a recognized string
+   `componentType` (`TEXT_INPUT` / `PHONE_INPUT` / `DROPDOWN`). For each, take
+   `inputOptions.target`, `inputOptions.required`, `inputOptions.stringOptions.componentType`,
+   and the label from `inputOptions.stringOptions.{textInputOptions|dropdownOptions|phoneInputOptions}.label`.
+   **Skip complex, object-valued fields** — e.g. a multi-line `ADDRESS` — they carry
+   no string `componentType`; rendering them as a text input sends a string and
+   `createBooking` rejects it with **"must be object"**. The booking enforces only
+   the contact basics (`first_name`/`last_name`/`email`), so omitting an optional
+   complex field is safe (do **not** default unknown field types to a text input).
+3. Render generic inputs by `componentType`: `TEXT_INPUT` → text input,
+   `DROPDOWN` → select, `PHONE_INPUT` → `type=tel`; treat `identifier === "TEXT_AREA"`
+   (or `target` containing `message`) as a textarea (its `componentType` is still `TEXT_INPUT`).
+4. Collect the values into an object **keyed by each field's `target`** — that is
+   `formSubmission`. Pass it to `book()`. Only include fields the visitor filled;
+   never send a value for a field you didn't render.
+
+**Do not** submit `contactDetails`, and **do not** hardcode field names — key by
+`target`. The default booking form's targets are snake_case `first_name` /
+`last_name` / `email` / `phone`. Reference example: `../astro/templates/bookings/BookingForm.tsx`.
+
+## 5. The day-calendar (slots step)
+
+Show a **week calendar**, not a flat list of every slot: a 7-day strip with
+week navigation → the picked day's times. A flat grid with time-only labels
+leaves the visitor unable to tell which day a slot is on. Fetch availability for
+the visible window (`fromLocalDate`/`toLocalDate` = the week bounds), group slots
+by calendar day, and offer a **"check next availability"** action that probes
+forward when a week is empty. Reference example:
+`../astro/templates/bookings/AvailabilityCalendar.tsx`.
+
+## 6. Client identity (per framework)
+
+The SDK calls are identical everywhere; only how you get the client differs:
+- **astro** — SSR read pages use the ambient `@wix/essentials` client
+  (`auth.elevate(services.queryServices)(...)`); browser islands call the `@wix`
+  modules **ambiently** too (the `@wix/astro` visitor client, like the ecom
+  `CartView` island) — no `createClient`/`OAuthStrategy`.
+- **own / static** — acquire a visitor client once:
+  `createClient({ modules, auth: OAuthStrategy({ clientId: appId }) })` and call
+  the same functions on it. CDN imports for `none`, bundled for `own`.
+
+## 7. Out of v1
+
+Waitlist, on-site manage/cancel, location selector, staff filter, payment
+breakdown, and CLASS sign-up are out of v1. Show bookable slots only;
+post-booking self-service is handled by the Wix-hosted flow / member area.

package/skills/wix-headless/references/bookings/INSTRUCTIONS.md

@@ -1,106 +1,90 @@
 ---
 name: bookings-implementer
-description: "Implements Wix Bookings vertical — services catalog, service detail with availability calendar and booking flow, and booking confirmation. Scopes: seed, components, pages. Extends references/shared/IMPLEMENTER.md."
+description: "Implements the Wix Bookings vertical — services catalog, a service detail page with a week-calendar availability picker, a schema-driven booking form, and confirmation. The booking runs client-side via the @wix SDK (ecom Cart V2 — no confirmBooking). Scopes: seed, components, pages. Extends references/shared/IMPLEMENTER.md."
 ---
 
 # Bookings Implementer
 
-Extends `references/shared/IMPLEMENTER.md`. Read that file first for phase routing, REST auth + doc lookups, site.json read pattern, return contract, style conventions, and common failure modes.
+Extends `references/shared/IMPLEMENTER.md`. Read that file first for phase routing, REST auth + doc lookups, the `.wix/seeded.json` read pattern, the return contract, style conventions, and common failure modes.
+
+## The logic lives in one place
+
+The booking **logic** — the step model, the shared selection state, the exact
+`@wix` SDK sequence, and the schema-driven form — is framework-agnostic and lives
+in **`./FLOW.md`**. Read it first. The astro guides below are the astro *wiring* of
+that logic; the code examples under `<SKILL_ROOT>/references/astro/templates/bookings/`
+are React (the astro islands use them directly). For an own/static build, the wiring guide is
+`../custom/bookings/WIRING.md` (same logic, client-side `@wix/sdk`).
 
 ## Scope routing
 
 | Scope | Phase | Reference |
 |-------|-------|-----------|
-| `seed` | Seed (service creation via Wix Bookings REST API) | `./SERVICES_DATA.md` |
-| `components` | Components: `ServiceCard.astro`, `AvailabilityCalendar.tsx`, `BookingForm.tsx`, `ServiceBookingFlow.tsx`, `ManageBooking.tsx` (`SeoTags.astro` is pre-copied — see Templates) | `../astro/bookings/COMPONENTS.md` |
-| `pages` | Pages: `/services` listing, `/services/[slug]` detail, `/booking-confirmation`, `/manage-booking` | `../astro/bookings/SERVICES_PAGES.md` |
+| `seed` | Seed — create services (and staff) via the Wix Bookings REST API | `./SERVICES_DATA.md` |
+| `components` | Components — the client islands (week calendar, schema-driven form, the flow coordinator) | `./FLOW.md` + `../astro/bookings/COMPONENTS.md` |
+| `pages` | Pages — `/services` listing, `/services/[slug]` detail, `/booking-confirmation`, + nav/home links | `./FLOW.md` + `../astro/bookings/SERVICES_PAGES.md` |
 
-## Files this vertical creates / contributes
+## Templates — read and adapt (don't invent)
 
-See `<SKILL_ROOT>/references/verticals/bookings.md` frontmatter.
+Canonical examples live at `<SKILL_ROOT>/references/astro/templates/bookings/`.
+Your `components` and `pages` scopes **read these and adapt them** — adapt brand
+copy, headings, and styling; keep the SDK calls, payload shapes, and the data
+flow (re-authoring the SDK wiring from scratch is the main source of API-shape bugs).
 
-## Pre-return file-existence assertion (pages scope)
+Components (`components` scope — TSX only, no CSS):
+- `<SKILL_ROOT>/references/astro/templates/bookings/AvailabilityCalendar.tsx` — the week calendar (week strip → the day's slots; APPOINTMENT via `availabilityTimeSlots`, CLASS via `eventTimeSlots`).
+- `<SKILL_ROOT>/references/astro/templates/bookings/BookingForm.tsx` — the schema-driven form (renders the `@wix/forms` field list, keys values by `target`) that drives `bookingDriver.book()`.
+- `<SKILL_ROOT>/references/astro/templates/bookings/ServiceBookingFlow.tsx` — the coordinator island (holds the selected slot; calendar → form → redirect).
 
-Before returning `status: "complete"` from the `pages` scope, verify all route files exist on disk:
-- `src/pages/services/index.astro`
-- `src/pages/services/[slug].astro`
-- `src/pages/booking-confirmation.astro`
-- `src/pages/manage-booking.astro`
+Pages (`pages` scope):
+- `<SKILL_ROOT>/references/astro/templates/bookings/ServiceCard.astro`
+- `<SKILL_ROOT>/references/astro/templates/bookings/services/index.astro`, `<SKILL_ROOT>/references/astro/templates/bookings/services/[slug].astro`
+- `<SKILL_ROOT>/references/astro/templates/bookings/booking-confirmation.astro`
 
-If any declared file is missing, return `status: "partial"` with `errors: [{ code: "PHASE4_FILE_MISSING", path: "<expected path>" }]` rather than claiming success.
+### Pre-copied by the orchestrator (do NOT write these yourself)
+Mechanical, brand-agnostic — the orchestrator copies them before dispatch (BUILD-astro.md § build wave). Rely on them at the listed paths:
+- `src/components/bookingDriver.ts` ← `<SKILL_ROOT>/references/astro/templates/bookings/bookingDriver.ts` — the booking SDK sequence (`book()`, `navigateToCheckout()`). The islands import it; never re-author it.
+- `src/components/SeoTags.astro` ← `<SKILL_ROOT>/references/astro/templates/bookings/SeoTags.astro` — renders `service.seoData.tags`; imported by `services/[slug].astro`.
+- `src/styles/components-bookings.css` ← `<SKILL_ROOT>/references/astro/templates/bookings/components-bookings.css` — the flow's component classes.
 
-## Templates
+If a pre-copied file is missing at runtime, that's an orchestrator-side bug — return `status: "partial"` with `errors: [{code: "UTILITY_TEMPLATE_NOT_PRECOPIED", path: "<missing>"}]`; do not author your own version.
 
-Canonical templates live at `<SKILL_ROOT>/references/astro/templates/bookings/`. Your `components` and `pages` scopes **read these and adapt them — don't invent markup or SDK wiring** (the booking/confirm/availability/waitlist wiring is subtle and was verified against a live site; re-authoring from scratch is a common source of API-shape bugs). Adapt brand copy, headings, and styling; keep the SDK calls and the data flow.
+## Pre-return file-existence assertion (pages scope)
 
-Components (`components` scope — `.tsx`/`.astro`, no CSS):
-- `…/templates/bookings/ServiceCard.astro`
-- `…/templates/bookings/AvailabilityCalendar.tsx` — branches on `serviceType` (APPOINTMENT → `availabilityTimeSlots`, CLASS → `eventTimeSlots`); capacity + instructor + full→waitlist
-- `…/templates/bookings/BookingForm.tsx` — `createBooking` → `/api/confirm-booking`; party size; waitlist on full
-- `…/templates/bookings/ServiceBookingFlow.tsx` — coordinator (threads `serviceType`)
-- `…/templates/bookings/ManageBooking.tsx` — cancel via anonymous token (used by `manage-booking.astro`)
+Before returning `status: "complete"` from `pages`, verify on disk:
+- `src/pages/services/index.astro`
+- `src/pages/services/[slug].astro`
+- `src/pages/booking-confirmation.astro`
 
-Pages (`pages` scope):
-- `…/templates/bookings/services/index.astro`, `…/services/[slug].astro`
-- `…/templates/bookings/booking-confirmation.astro`, `…/manage-booking.astro`
+If any declared file is missing, return `status: "partial"` with `errors: [{ code: "PHASE4_FILE_MISSING", path: "<expected path>" }]`.
 
-### Pre-copied by the orchestrator (do NOT write these yourself)
-These are mechanical (no brand content) — the orchestrator copies them before dispatch (BUILD-astro.md § Step 4.5). Just rely on them at the listed paths:
-- `src/styles/components-bookings.css` ← `…/templates/bookings/components-bookings.css`
-- `src/components/SeoTags.astro` ← `…/templates/bookings/SeoTags.astro` (renders `service.seoData.tags`; imported by `services/[slug].astro`)
-- `src/pages/api/confirm-booking.ts` ← `…/templates/bookings/api/confirm-booking.ts` (elevated `confirmBooking` — holds the seat)
-- `src/pages/api/waitlist.ts` ← `…/templates/bookings/api/waitlist.ts` (elevated native v1 waitlist register)
+## Dependencies (Setup installs these — see SETUP.md)
 
-If a pre-copied file is missing at runtime, that's an orchestrator-side bug — return `status: "partial"` with `errors: [{code: "UTILITY_TEMPLATE_NOT_PRECOPIED", path: "<missing>"}]`; do not author your own version.
+`@wix/bookings @wix/essentials @wix/forms @wix/redirects @wix/auto_sdk_ecom_cart-v-2`.
+`@wix/forms` renders the booking-form schema; `@wix/redirects` + `@wix/auto_sdk_ecom_cart-v-2` run the cart/checkout sequence.
 
 ## CSS ownership — bookings pack
 
-Bookings-specific component CSS lives in `src/styles/components-bookings.css` (pre-copied by the orchestrator from the skill template — see above), NOT in the designer's `global.css`. Classes the pack owns:
-
-- `.service-card`, `.service-card-image`, `.service-card-meta`, `.service-card-price` — the service card itself, including image containment, price badge, and duration tag.
-- `.service-grid` — the layout that lists service cards on `/services`. Include `display: grid; grid-template-columns: repeat(auto-fill, minmax(300px, 1fr)); gap: var(--spacing-xl);` plus View-Transitions opacity fade.
-- `.availability-calendar` — the date-picker shell wrapping the calendar widget.
-- `.time-slot`, `.time-slot--available`, `.time-slot--selected`, `.time-slot--full` (full CLASS session → waitlist), plus the `.time-slot-time` / `.time-slot-capacity` spans inside each slot button.
-- `.booking-form` (+ `.booking-form-note`) — the booking/waitlist form revealed after a slot is selected.
-- `.manage-booking`, `.manage-booking-summary`, `.manage-booking-status`, `.manage-booking-note`, `.manage-booking-link` — the `/manage-booking` view/cancel UI.
-
-If `global.css` ships a partial rule for any class above, flag it in your return JSON's `errors` array (`{code: "GLOBAL_CSS_LEAK", class: "<name>"}`) and override with the complete rule in `components-bookings.css`.
+Bookings-specific CSS lives in `src/styles/components-bookings.css` (pre-copied — see above), NOT in `global.css`. Classes the pack owns: `.service-card*`, `.service-grid`, `.availability-*`, `.time-slot*`, `.booking-*`. If `global.css` ships a partial rule for any of these, flag it (`{code:"GLOBAL_CSS_LEAK", class:"<name>"}`) and override in `components-bookings.css`.
 
 ## Bookings-specific failure modes
 
 | Wrong | Right |
 |-------|-------|
-| Treat `createBooking` as the whole booking — stop after it returns | `createBooking` leaves the booking **`CREATED`**, which **does not hold a seat or block availability** (per the [lifecycle docs](https://dev.wix.com/docs/api-reference/business-solutions/bookings/bookings/introduction): only `CONFIRMED` blocks availability). Without a follow-up **`confirmBooking`**, the class overbooks and capacity never drops. After createBooking returns `CREATED`, call `bookings.confirmBooking(bookingId, revision, { paymentStatus: "NOT_PAID", flowControlSettings: { checkAvailabilityValidation: true } })`. `confirmBooking` needs Manage Bookings → run it **server-side, elevated** (`auth.elevate`), not from the visitor client. |
-| Build the waitlist on `createBooking` (expecting a `WAITING_LIST` status) | `createBooking` has **no** waitlist option (verified: only `participantNotification`/`sendSmsReminder`); a full session returns `SESSION_CAPACITY_EXCEEDED`. The native waitlist is the **legacy v1** API `POST /bookings/v1/waitlist/register` (there is no v2/v3 waitlist). It needs the **v1-encoded session id** as `waitingResource` (surfaced in the `SESSION_CAPACITY_EXCEEDED` message: *"…on session `<id>`"*) **+ a Wix `contactId`** (resolve via Contacts API by email, create if missing), and the **Manage Bookings** scope → server-side elevated. Class/EVENT only. |
-| Call the v1 waitlist (or any Manage-Bookings REST) with `auth.elevate(async () => fetchWithAuth(...))` | `auth.elevate()` only grants permissions for a real **SDK function** (it reads the method's required-permission metadata); a plain closure isn't one, so it runs **un-elevated (visitor)** and 403s. For raw REST with no SDK wrapper, elevate the authenticated fetch itself: `const ef = auth.elevate(httpClient.fetchWithAuth); await ef(url, init)`. (For calls that *do* have an SDK method — `confirmBooking`, `getAnonymousActionToken` — elevate the method directly.) |
-| Pass the v3 `eventId` as the waitlist `waitingResource` | The v1 waitlist can't decode a v3 GUID (`"id … cannot be decoded"`). Use the **v1-encoded session id** (e.g. `2mmoW0vw…`) from the `SESSION_CAPACITY_EXCEEDED` message. |
-| Use Services V1 API endpoint (`/bookings/v1/catalog/services`) | Services V2 is at `POST https://www.wixapis.com/_api/bookings/v2/services`. V1 has a different (nested `info.*`) payload shape. |
-| Nest service fields under `info` (`info.name`, `info.description`) | V2 uses flat fields: `name`, `description`, `tagLine` at the top level of the `service` object. |
-| Use `payment.fixed.price.amount` | V2 uses `payment.fixed.price.value` (a string like `"75.00"`). `amount` is the V1 field name. |
-| Omit `defaultCapacity` when creating a service | Required in V2. Set to `1` for APPOINTMENT; use participant count for CLASS. |
-| Omit `onlineBooking` when creating a service | Required in V2. At minimum `{ "enabled": true }`. |
-| Omit `sessionDurations` for an APPOINTMENT service | Required for APPOINTMENT: `schedule.availabilityConstraints.sessionDurations: [<minutes as int>]`. Do NOT specify for CLASS. |
-| Use `availability.queryAvailability` or `availability` SDK namespace | Branch by service type: APPOINTMENT → `availabilityTimeSlots.listAvailabilityTimeSlots()`; CLASS → **`eventTimeSlots.listEventTimeSlots()`** (a **different namespace** — `eventTimeSlots`, not `availabilityTimeSlots` — with plural `serviceIds` + `includeNonBookable`). The `availability` namespace does not exist in `@wix/bookings`. |
-| Pass UTC ISO strings to `listAvailabilityTimeSlots` | The method expects **local date strings** in `YYYY-MM-DDTHH:mm:ss` format (no `Z`), with a separate `timeZone` parameter. |
-| Read service slug from `service.slug` | V2 response puts slug at `service.mainSlug.name`. Fall back to `service.supportedSlugs[0].name`, then `service.id`. |
-| Call `queryServices({ query: { filter, paging } })` (object form) | In `@wix/bookings` the object form returns **0 items with no error**. Use the **query builder**: `await services.queryServices().limit(100).find()` → `result.items`. For a slug, fetch the (small) catalog and match `mainSlug.name` in JS, or `.eq("mainSlug.name", slug).find()`. |
-| Build a `createClient`/`OAuthStrategy` in `.astro` SSR frontmatter keyed off `import.meta.env.*_WIX_CLIENT_ID` | The `*_WIX_CLIENT_ID` env vars are client-only in `@wix/astro` and `undefined` at server render → `createClient` throws → HTTP 500 (only in the deployed runtime; dev has `.env.local`). SSR reads use `@wix/essentials` `auth.elevate(services.queryServices)()…` — the same ambient pattern as the CMS pages. |
-| Read the client ID in a browser island via `import.meta.env.*_WIX_CLIENT_ID` | Client islands import `{ WIX_CLIENT_ID } from "astro:env/client"`. `import.meta.env` is `undefined` in the browser bundle → `OAuthStrategy` sends an empty `client_id` → `oauth2/token` `400`. The var name is `WIX_CLIENT_ID` (no `PUBLIC_`). |
-| Read service name from `service.info.name` | V2 uses flat `service.name` (not `service.info.name`). Same for `description` and `tagLine`. |
-| Read duration from `service.schedule.sessions.duration` | V2 puts duration at `service.schedule.availabilityConstraints.sessionDurations[0]` (array of ints). |
-| Read media URL from `service.info.images[0].url` | V2 media: `service.media.mainMedia.image.url`. |
-| Use `import { availability } from '@wix/bookings'` | Use `import { availabilityTimeSlots } from '@wix/bookings'`. |
-| Call `availability.queryAvailability` server-side on every render | Availability is real-time and session-specific — always call from the client-side React island, NOT from `.astro` frontmatter SSR. |
-| Create a booking without `totalParticipants` | `createBooking` requires `totalParticipants: 1` (or `participantsChoices`). |
-| Read booking ID from `result.booking.id` | The booking ID field is `result.booking._id` (underscore prefix). |
-| Redirect to `/thank-you` (ecom route) after booking | Redirect to `/booking-confirmation?bookingId=<_id>`. The ecom thank-you page is unrelated to bookings. |
-| Re-fetch the booking with `getBooking` from the confirmation page | Don't. Pass booking details (bookingId, startDate, service name) as URL query params during the client-side redirect after `createBooking` succeeds, and render from those. (A server re-fetch of someone else's booking is out of scope.) NB: this is **not** because `auth.elevate` is unavailable — see next row. |
-| Assume `@wix/essentials` `auth.elevate` doesn't work in headless | It does. **Two different `elevate`s:** `@wix/essentials` `auth.elevate(fn)` works in `@wix/astro` SSR (it's how the listing/detail/CMS pages read data) — use it. What's unavailable is the **`wixClient.auth.elevate`** instance method on a hand-built `createClient({auth: OAuthStrategy})` (a Velo/Blocks API). Don't conflate them. |
-| Mount `AvailabilityCalendar` without `client:only="react"` | Calendar must be fully client-side — SSR renders before timezone is known and breaks slot display. Always use `client:only="react"`. |
-| Omit try/catch on `createBooking` | Booking creation can fail with 409 (slot taken) between slot fetch and submit. Catch and surface a friendly message; do not crash the page. |
-| Use `service.id` to pass the service ID | The Wix SDK uses `_id` (with underscore) for all entity IDs. The service's ID is `service._id`. Using `service.id` will be `undefined`. |
-| Read `resource._id` from `listAvailabilityTimeSlots` response | `availableResources` is EMPTY by default in list results. Omit `resource` from `createBooking` — Wix auto-assigns a resource during confirmation. |
-| Use `timeSlot.slot.startDate` to read slot time | Slot fields are at the TOP LEVEL — there is no nested `slot` on the list response. APPOINTMENT slots: `timeSlot.localStartDate`, `timeSlot.localEndDate`, `timeSlot.scheduleId`. |
-| Treat CLASS (event) slots like APPOINTMENT slots — guard clicks on `scheduleId`, book with `{scheduleId, startDate}` | CLASS event slots carry their session id at **`timeSlot.eventInfo.eventId`** and have **no `scheduleId`** (and no top-level `startDate`). Guarding the slot-click on `scheduleId` drops every CLASS click; the appointment-shaped `createBooking` payload doesn't apply. For CLASS: guard on `eventId`, and book with `bookedEntity.slot = { serviceId, eventId }` (Wix derives start/end/timezone/resource/location from the event). Keep `{ scheduleId, startDate, endDate, timezone, location }` for APPOINTMENT only. |
-| Pass `hidden: true` services to the listing | Always filter with `{ hidden: false }` in your `queryServices` filter to exclude hidden services from the public listing. |
-| Use `../../../` for imports in `[slug].astro` | `src/pages/services/[slug].astro` is two directories deep inside `src/`. Import Layout and components with `../../layouts/Layout.astro` and `../../components/…` — not three `../` which would escape `src/`. |
+| Stop after `createBooking` returns | `createBooking` leaves the booking **`CREATED`**. The seat is held by the **ecom Cart V2**: continue `createCart → calculateCart → isCheckoutRequired ? hosted-checkout redirect : placeOrder`. The whole sequence is in `bookingDriver.ts` — use it. |
+| Hardcode `selectedPaymentOption: "ONLINE"` on `createBooking` | **Derive** it from the service: `online && !inPerson → "ONLINE"`, `!online && inPerson → "OFFLINE"`, else `"ONLINE"`. A free / pay-in-person service is the only kind that reaches `placeOrder`, and booking it `ONLINE` makes the cart reject it with **`INSUFFICIENT_INVENTORY`** (`available_quantity: 0`). `bookingDriver.ts` derives this for you (don't pass `selectedPaymentOption` to `book()`). |
+| Pass `contactDetails` to `createBooking` | Pass **`formSubmission`**, keyed by each field's **`target`** (default booking form: snake_case `first_name`/`last_name`/`email`/`phone`). `contactDetails` is what Wix derives back onto the response. |
+| Hardcode the booking-form fields | Render the form **schema-driven**: read `service.form._id`'s fields via `@wix/forms`, render by `componentType`, key values by `target` (same renderer as `../astro/forms/CONTACT_FORM.md`). |
+| Render every form field as a text input (default unknown types to `TEXT_INPUT`) | Render **only** fields with a recognized string `componentType` (`TEXT_INPUT`/`PHONE_INPUT`/`DROPDOWN`). **Skip complex, object-valued fields** (e.g. the default booking form's multi-line `ADDRESS`) — sending a string for them fails `createBooking` with **"must be object"**. Only `first_name`/`last_name`/`email` are enforced, so skipping optional complex fields is safe. |
+| Call `queryServices` without an `appId` filter | Always include `appId` (`13d21c63-…`) in the filter. List: `queryServices({ query:{ filter:{ appId }, paging }, conditionalFields:["STAFF_MEMBER_DETAILS"] }).find()`. Single: the `.eq("mainSlug.name", slug).eq("appId", …).limit(1).find()` builder chain. |
+| Build `createClient({ auth: OAuthStrategy({ clientId: import.meta.env.* }) })` in `.astro` SSR | The `*_WIX_CLIENT_ID` env var is client-only → `undefined` at server render → 500. SSR reads use the ambient `@wix/essentials`: `auth.elevate(services.queryServices)(...)`. |
+| Build an `OAuthStrategy` client inside an astro browser island | Astro islands call the `@wix` modules **ambiently** (the `@wix/astro` visitor client, like the ecom `CartView`) — no `createClient`. (Own/static builds DO use `OAuthStrategy` — `../custom/bookings/WIRING.md`.) |
+| Pass UTC ISO strings to `listAvailabilityTimeSlots` | Use **local** date strings `YYYY-MM-DDThh:mm:ss` (no `Z`) + a separate `timeZone`. |
+| `availability.queryAvailability` / `import { availability }` | APPOINTMENT → `availabilityTimeSlots.listAvailabilityTimeSlots({ serviceId: <string> })`; CLASS → `eventTimeSlots.listEventTimeSlots({ serviceIds: [<string>] })`. The `availability` namespace does not exist. |
+| Read slot time from `timeSlot.slot.startDate` | Slot fields are at the **top level**: `localStartDate`, `localEndDate`, `scheduleId` (APPOINTMENT). CLASS slots carry `eventInfo.eventId` and have **no** `scheduleId`. |
+| Dump every slot in one flat, time-only grid | Show a **week calendar**: a day strip → the picked day's times. A flat grid hides which day a slot is on. |
+| Read service slug from `service.slug` / name from `service.info.name` | V2 is flat: slug `service.mainSlug.name` (fallback `supportedSlugs[0].name`), `service.name`, `service.description`, `service.tagLine`; duration `service.schedule.availabilityConstraints.sessionDurations[0]`; price `service.payment.fixed.price.value` (string); media `service.media.mainMedia.image.url`. |
+| Use `service.id` / `result.booking.id` | Entity ids are `_id` (underscore): `service._id`, `booking._id`. |
+| Mount the calendar/form without `client:only="react"` | Availability + booking are timezone/session-specific — always `client:only="react"`. SSR only the read pages (catalog/detail) for SEO. |
+| Omit try/catch on the booking | `createBooking` can reject (e.g. a slot taken between fetch and submit, or strict phone validation). Catch and surface a friendly message; don't crash. |
+| Ship a location selector, staff filter, payment breakdown, CLASS sign-up, or waitlist | Out of v1 — appointment booking only. |