@wix/agent-skills 1.8.0 → 1.10.0

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

@@ -0,0 +1,246 @@
+# 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 covers **appointments and classes**. APPOINTMENT and CLASS share the
+same booking sequence; they differ only in the availability call (`availabilityTimeSlots`
+vs `eventTimeSlots`, noted inline). **Courses and add-ons are out of scope.**
+
+---
+
+## 1. The step model
+
+A single customer journey, holding one shared selection. The catalog optionally
+filters by **location** and **category**; the slots step optionally filters by
+**staff**. All three auto-skip when there's nothing to choose (≤1 location, ≤1
+category, ≤1 staff), so a plain single-location single-staff site sees the simple
+five-step path:
+
+```
+0. Location   (optional) pick a location — only shown when the site has >1 locations → scopes the catalog + availability
+1. Catalog    list bookable services (optionally filtered by location/category) → pick a service
+2. Slots      availability calendar (optionally filtered by staff)               → 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 location/category filters and the staff picker are covered in §§7–8.
+
+**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`; the slots step reads `service.staffMemberDetails.staffMembers` for the staff picker — §8).
+- **`slot`** — `{ serviceType, serviceId, localStartDate, localEndDate, timezone, scheduleId?, eventId?, locationId?, locationType?, resource? }`. `resource = { _id, name }` is set only when a specific staff was chosen (§8); otherwise the driver emits the ANY_RESOURCE fallback. `locationId`/`locationType` come from the slot's own `location` (the booking books at that location).
+- **`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)** — when no staff is chosen (the default, and on
+  single-staff services), `createBooking` sends
+  `resourceSelections:[{ resourceTypeId:"1cd44cf8-756f-41c3-bd90-3e2ffcaf1155", selectionMethod:"ANY_RESOURCE" }]`
+  and Wix auto-assigns a bookable staff resource (appointment slots return
+  `availableResources:[]` yet book fine this way). A specific staff choice sets
+  `slot.resource` instead (§8).
+- **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().
+// Merge the optional category/location filters into the SAME filter object (§7):
+services.queryServices({
+  query: { filter: { appId: BOOKING_APP_ID /* , "category.id": { $eq: catId },
+                       "locations.business.id": { $hasSome: [locId] } */ }, 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. The staff (§8)
+// and location filters are OPTIONAL params on the same call:
+availabilityTimeSlots.listAvailabilityTimeSlots({
+  serviceId, fromLocalDate, toLocalDate, timeZone, bookable: true, cursorPaging: { limit: 100 },
+  // staff:    resourceTypes: [{ resourceTypeId: STAFF_MEMBER_RESOURCE_TYPE_ID, resourceIds: [staffResourceId] }],
+  //           includeResourceTypeIds: [STAFF_MEMBER_RESOURCE_TYPE_ID],
+  // location: locations: [{ _id: locationId, locationType: "BUSINESS" }],
+});                                          // slots: result.timeSlots[] (localStartDate/localEndDate/scheduleId at top level)
+
+// Availability (CLASS) — different namespace, PLURAL serviceIds; slots carry eventInfo.eventId, no scheduleId.
+// CLASS filters staff + location via eventFilter instead:
+eventTimeSlots.listEventTimeSlots({
+  serviceIds: [serviceId], fromLocalDate, toLocalDate, timeZone, includeNonBookable: false,
+  // eventFilter: { "resources.id": { $hasSome: [staffResourceId] }, "location.id": [locationId] },
+});
+```
+
+`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 availability calendar (slots step)
+
+**Group slots by day — don't render a flat list of every slot with time-only
+labels** (the visitor can't tell which day a slot is on; that flat grid was the
+original usability failure). The calendar **shape is your / the brand's choice** —
+week, month, or N-day. The reference example uses a **week view** (a 7-day strip
+with week navigation → the picked day's times); fetch availability for the visible
+window (`fromLocalDate`/`toLocalDate` = that window's bounds), group by calendar
+day, and offer a **"check next availability"** action that probes forward when the
+window 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. Catalog filters — location & category (both auto-skip)
+
+Both filter the **catalog query** and re-render the list. The cleanest
+framework-agnostic shape is a re-query driven by a query param (`?locationId`,
+`?category`) — links/SSR on a static catalog, or a store/router on a SPA. **Show
+each filter only when there is more than one choice**, exactly as the SoT does.
+
+**Location** (the SoT is location-first; here it auto-skips ≤1 location):
+1. `services.queryLocations()` → `{ businessLocations: { locations: [{ _id, type, business: { name } }] }, customLocations: { exists }, customerLocations: { exists } }`.
+2. Count = `businessLocations.locations.length + (customLocations.exists ? 1 : 0) + (customerLocations.exists ? 1 : 0)`. **Show the selector only when count > 1.**
+3. The chosen location filters the catalog query:
+   - a real business id → `filter["locations.business.id"] = { $hasSome: [id] }`;
+   - the synthetic `"custom"` / `"customer"` → `filter["locations.type"] = { $hasSome: ["CUSTOM"|"CUSTOMER"] }` (the SoT's synthetic-id mapping).
+4. **Scope availability to exactly ONE location — always, on a multi-location service.** `listAvailabilityTimeSlots` returns **one slot per location** per time ("if `locations` is not specified, returns time slots for all locations where the service is available"), so an unscoped call on a 2-location service shows every time **twice**. Pass a single-element filter: APPOINTMENT → `locations: [{ _id, locationType: "BUSINESS" }]`; CLASS → `eventFilter: { "location.id": [id] }`. (Staff does **not** multiply rows — one slot carries many `availableResources`; only location does.) The slots step builds its location list from **`queryLocations()`** (the site's real business locations, whose ids the availability engine recognizes) **intersected with the service's own location ids** — not from `service.locations` alone, whose entries can carry an id the availability engine doesn't recognize (scoping to it returns zero slots). A **location picker** defaults to the catalog-carried location (or the first) and scopes the call when there's a real location to scope to; when the site has no business locations the list is empty and the call stays unscoped (one location → no duplicates). The booked slot carries its own `location`, so the booking books at that location (the driver maps it).
+
+**Category:**
+1. `categoriesV2.queryCategories().find()` → `result.items: [{ _id, name }]`. **Non-fatal** — if it fails, render the catalog without the bar.
+2. **Show the bar only when `items.length > 1`** (a fresh site has one default category).
+3. The chosen category filters the catalog query: `filter["category.id"] = { $eq: categoryId }`. A service carries its category at `service.category._id`.
+
+Reference example: `../astro/templates/bookings/services/index.astro` (both filters, link-driven, auto-skipping).
+
+## 8. Staff / resource selection (auto-skips ≤1 staff)
+
+A service carries its staff on the service object via the **`STAFF_MEMBER_DETAILS`
+conditional field** (already requested in the catalog/detail query):
+`service.staffMemberDetails.staffMembers: [{ staffMemberId, name }]`. The id used
+for filtering and booking is **`staffMemberId`** — which, **despite the name, IS the
+resource GUID** (it matches the service's `staffMemberIds` and the Staff Members API
+`resourceId`). Below, `resourceId` is that value.
+
+1. Show a "Any staff member / pick one" control above the calendar **only when
+   there is more than one staff**.
+2. Selecting a staff re-fetches availability filtered to that resource:
+   - APPOINTMENT → `resourceTypes: [{ resourceTypeId: STAFF_MEMBER_RESOURCE_TYPE_ID, resourceIds: [resourceId] }]` (plus `includeResourceTypeIds: [STAFF_MEMBER_RESOURCE_TYPE_ID]`);
+   - CLASS → `eventFilter: { "resources.id": { $hasSome: [resourceId] } }`.
+3. When a slot is picked **with a specific staff selected**, set `slot.resource = { _id: resourceId, name }`. The driver books that resource. With **"any staff"**, leave `resource` unset — the driver emits the **ANY_RESOURCE fallback** and Wix auto-assigns a bookable resource (appointment slots can return `availableResources: []` yet book fine this way).
+
+`STAFF_MEMBER_RESOURCE_TYPE_ID = "1cd44cf8-756f-41c3-bd90-3e2ffcaf1155"` (exported from `bookingDriver.ts`). Reference example: `../astro/templates/bookings/AvailabilityCalendar.tsx` (the staff `<select>` + the filtered fetch).
+
+## 9. Out of scope
+
+Waitlist, on-site manage/cancel, payment/deposit breakdown, and multi-service /
+day-range are out of scope. (Waitlist and manage/cancel have **no headless SoT** —
+neither the components nor the vibe plugin implement join/cancel logic, only
+display-only policy flags — so they are deliberately not built here.) 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,95 @@
 ---
 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 (with optional location + category filters), a service detail page with a week-calendar availability picker (with optional staff selection), a schema-driven booking form, and confirmation, for appointments and classes. 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 | **Group slots by day** — a flat time-only grid hides which day a slot is on. The calendar shape (week / month / N-day) is your choice; the example uses a week strip → the picked day's times. |
+| Read the staff id from `staffMember._id` / `.resourceId` on `staffMemberDetails.staffMembers` | The field is **`staffMemberId`** (on `service.staffMemberDetails.staffMembers[]`) — despite the name it IS the resource GUID (matches the service's `staffMemberIds`). Filter availability: APPOINTMENT `resourceTypes:[{ resourceTypeId: STAFF_MEMBER_RESOURCE_TYPE_ID, resourceIds:[staffMemberId] }]`; CLASS `eventFilter:{ "resources.id": { $hasSome:[staffMemberId] } }`. Record the choice as `slot.resource = { _id: staffMemberId, name }`; leave it unset for "any staff" (ANY_RESOURCE fallback). Show the picker only when >1 staff. |
+| Always show the location selector / staff picker / category bar | **Auto-skip** each when there's nothing to choose: location count ≤1 (`businessLocations.length + custom?.exists + customer?.exists`), staff ≤1, categories ≤1. Single-location single-staff sites see the simple flow. |
+| Filter the catalog by a synthetic location id, or hardcode the location filter | Real business id → `filter["locations.business.id"] = { $hasSome:[id] }`; synthetic `"custom"`/`"customer"` → `filter["locations.type"] = { $hasSome:["CUSTOM"|"CUSTOMER"] }`. Carry the choice to the detail page so availability is scoped too. |
+| Call `listAvailabilityTimeSlots` **without** a `locations` filter on a multi-location service | It returns **one slot per location** per time → every time appears **N×** (duplicated rows). **Always scope availability to one business location** (`locations: [{ _id, locationType:"BUSINESS" }]`; CLASS: `eventFilter:{ "location.id":[id] }`). Build the calendar's location list from **`queryLocations()`** (the site's real business locations) intersected with the service's location ids — NOT from `service.locations` alone (its entries can carry an id the availability engine doesn't recognize → scoping to it returns 0 slots even though the service has availability). Default to the carried/first, picker when >1; no business locations → unscoped. Staff does **not** cause duplicates — one slot carries many `availableResources`; only location multiplies rows. |
+| Let a `queryCategories` failure break the catalog | Categories are **non-fatal** — wrap in try/catch and render the catalog without the bar. Category filter: `filter["category.id"] = { $eq: categoryId }`; a service's category is `service.category._id`. |
+| 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 payment/deposit breakdown, multi-service stacking, waitlist, or on-site manage/cancel | Out of scope. **Waitlist and manage/cancel have no headless SoT** (the components + vibe plugin expose only display-only policy flags — no join/cancel logic) — do not invent them on the REST/anonymous-token layer. Post-booking self-service is handled by the Wix-hosted flow / member area. |

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

@@ -93,6 +93,66 @@ curl -sS -X POST -H "Authorization: Bearer $TOKEN" -H "wix-site-id: <siteId>" -H
 
 ---
 
+## Step 3b — Create categories (OPTIONAL — only to surface the catalog category filter)
+
+A fresh Bookings install has **one** default category ("Our Services"), so the
+front-end's category filter bar stays hidden (it shows only when >1 category
+exists). Create extra categories **only when the build wants a category filter**
+(e.g. `intent.bookings.categories` is set, or several distinct service groups).
+Skip this step otherwise — it's not needed for a basic seed.
+
+```bash
+# Create a category. Returns { category: { id, ... } } — save the id.
+curl -sS -X POST \
+  -H "Authorization: Bearer $TOKEN" -H "wix-site-id: <siteId>" -H "Content-Type: application/json" \
+  -d '{ "category": { "name": "<Category name, e.g. Massage>" } }' \
+  "https://www.wixapis.com/bookings/v2/categories"
+```
+
+Then **assign each service to a category** by including `category` in the Step-4
+create payload: `"category": { "id": "<categoryId>" }`. (If a create rejects
+`category`, assign it after creation via Update Service — `PATCH
+/_api/bookings/v2/services/{id}` with `service.category.id` + the current
+`revision` — per the docs' "create a category and connect a service" flow.) A
+service can belong to **one** category. Distribute services across 2+ categories
+so the filter is meaningful.
+
+> The front-end reads categories via `categoriesV2.queryCategories().find()` and
+> filters services with `filter["category.id"] = { $eq: id }`. No category data →
+> no filter bar (graceful).
+
+---
+
+## Step 3c — Multiple business locations (OPTIONAL — only for a multi-location demo)
+
+The front-end's location selector auto-skips when the site has ≤1 location, so a
+single-location seed needs nothing here (and the booking flow is unaffected).
+Create a second business location **only** for a multi-location build
+(`intent.bookings.multiLocation`):
+
+```bash
+# Create a business location. Returns { location: { id, ... } }.
+curl -sS -X POST \
+  -H "Authorization: Bearer $TOKEN" -H "wix-site-id: <siteId>" -H "Content-Type: application/json" \
+  -d '{ "location": { "name": "<Branch name>", "status": "ACTIVE", "locationType": "BUSINESS",
+        "address": { "city": "<City>", "country": "<ISO country>" } } }' \
+  "https://www.wixapis.com/locations/v1/locations"
+```
+
+Then attach locations to each service's `locations` array on create (Step 4):
+`"locations": [ { "type": "BUSINESS", "business": { "id": "<locationId>" } }, … ]`.
+
+> **Caveat (verified-behavior limitation, not a bug):** filtering *availability*
+> by location also depends on each staff member's **working-hours location
+> coverage** (the `STAFF_WORKING_HOURS_LOCATIONS` setting). Seeding that reliably
+> is as fragile as custom working hours (see Step 3's warning), so for a seed,
+> create the location + attach it to services to exercise the **catalog** location
+> filter, and configure per-location staff hours from the Bookings dashboard if you
+> need per-location availability to differ. The selector + service filtering work
+> from the seed alone; per-location *slot* differences need the dashboard step.
+
+---
+
 ## Step 4 — Create services (Services V2 API)
 
 **Endpoint:** `POST https://www.wixapis.com/_api/bookings/v2/services`