@wix/agent-skills 1.14.0 → 1.15.1

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

@@ -0,0 +1,157 @@
+
+# Wix Bookings Skill
+
+> **Source files (in this skill):** the shared transport `references/shared/wix-client.js` and both bookings helpers from `references/bookings/`. All helpers import from `"./wix-client.js"`, so copy them into the same folder (e.g. `src/rest/`). Copy **both** for the full booking flow:
+>
+> | File | What it covers |
+> |---|---|
+> | `wix-bookings-services.js` | Service listing, slot availability, media URL helper |
+> | `wix-bookings-checkout.js` | Create booking, hosted checkout, bookAndCheckout convenience |
+
+Builds a real, client-only Wix Bookings front end. The browser talks to Wix directly over a
+public `WIX_CLIENT_ID`. Never mock services or slots; never hand-build a `/checkout` URL —
+always create the booking through the API and complete it via the eCom checkout + redirect-session.
+
+This skill ships the single-service booking flow for **APPOINTMENT and CLASS** services: browse
+services → pick a service → pick an available slot → enter details → book → hosted checkout.
+Appointments and classes differ only in the availability call (`listAvailableSlots` vs
+`listEventTimeSlots`); `listSlotsForService` routes by `service.type`, and `createBooking` handles
+either slot. **COURSE (whole-course enrollment) is not covered** — see "Beyond the snippets".
+
+## When to use
+- User wants a Wix Bookings appointment site or asks to "connect Wix Bookings".
+- Replacing placeholder/mock services or fake calendars with live Wix data.
+- Adding service listings, a slot picker, booking creation, or checkout over an existing
+  Wix Bookings setup.
+
+## Prerequisites
+1. A Wix site with **Wix Bookings installed and at least one appointment service created**
+   (this skill does NOT provision — it's read-only over services). Staff/resources and a
+   booking policy should be configured so slots are bookable.
+2. The site's public headless **`WIX_CLIENT_ID`**, provided in the handoff prompt (the Wix
+   Business Manager surfaces a copyable prompt with the id filled in — see the router `SKILL.md`). Paste
+   it into `src/rest/wix-client.js` in place of the placeholder. It is a buyer-facing credential
+   (it only mints anonymous visitor tokens), **not** a secret, so hardcoding/committing it is fine.
+3. The site must **accept payments** for paid services, and the deployed app domain must be
+   allow-listed on the OAuth client for Wix-hosted checkout to return. These are **separate Wix
+   setup flows the user completes later** — out of this skill's scope. If checkout return fails
+   before that setup is done, that's expected; flag it and continue.
+
+## The API (copy as-is; do not re-derive it)
+This skill ships only the REST layer — no UI components. Build the booking UI however the
+project wants; wire it to these two snippets. Copy them into the app (e.g. `src/api/`) and only
+adjust import paths:
+- `src/rest/wix-client.js` — visitor-token mint/refresh + transport. Set `WIX_CLIENT_ID` to the
+  id from the prompt (replace the `<YOUR-CLIENT-ID>` placeholder). The visitor refresh token IS
+  the booking visitor identity; it is persisted to localStorage. Do not re-mint anonymously per
+  load.
+- `src/rest/wix-bookings-services.js` — **Services & availability:**
+  `queryServices`, `getService`, `countServices`, `listAvailableSlots`, `getAvailableSlot`,
+  `mediaUrl` (resolve a service image to an absolute URL)
+- `src/rest/wix-bookings-checkout.js` — **Booking & checkout:**
+  `createBooking`, `checkoutBooking`, `bookAndCheckout`
+
+The `Service`, `TimeSlot`, and `Booking` shapes are documented as JSDoc comments at the top of
+each helper file. Read them before building the UI — they describe the key fields and link to
+the full API reference for anything not shown.
+
+## How to wire it (UI is the project's choice)
+- **Service list** — `queryServices()` for the listing (visitor-visible services only). Render
+  `name`, `tagLine`, the image via `mediaUrl(service.media?.items?.[0]?.image)`, and the price
+  from `payment.fixed.price`. `value` + `currency` are always present; `formattedValue` is
+  **optional** (it may be missing), so don't depend on it — build the price from `value`+`currency`
+  and use `formattedValue` only when present. e.g. `new Intl.NumberFormat(undefined, { style:
+  'currency', currency }).format(Number(value))`. (Rendering `formattedValue` alone leaves the price
+  blank — or your "Varies" fallback — whenever it's absent.) Pass the returned
+  `nextOffset` back as `offset` to load the next page. Books **APPOINTMENT and CLASS** services
+  (see the slot picker below); COURSE is whole-course enrollment and out of scope.
+- **Service detail** — `getService(serviceId)` keyed off the URL/route; returns null on miss —
+  show a not-found state, never invent a service. Render `description`, price, and `locations`.
+- **Slot picker** — use **`listSlotsForService(service, { fromLocalDate, toLocalDate, timeZone? })`**:
+  it routes by `service.type` — APPOINTMENT → `listAvailableSlots` (staff working hours), CLASS/COURSE
+  → `listEventTimeSlots` (scheduled sessions). Both return the same slot shape. (Call the specific
+  function directly if you already know the type.) Dates are **local** wall-clock strings
+  `"YYYY-MM-DDThh:mm:ss"` (no zone), interpreted in `timeZone` (defaults to the visitor's IANA zone).
+  Only `bookable: true` slots come back. Render each `slot.localStartDate`/`localEndDate`; group by
+  day for a calendar. Pass `nextCursor` back
+  as `cursor` to page.
+- **Booking form** — collect the buyer's `firstName`, `lastName`, `email`, `phone`. Keep it
+  minimal; richer per-service form fields live in the service's `form.id` (see "Beyond the snippets").
+- **Participant count** — cap it by the service policy, not just slot capacity. The most a single
+  booking may reserve is `service.bookingPolicy.participantsPolicy.maxParticipantsPerBooking`. Only
+  render a participant selector when that value is `> 1`, and bound its max at
+  `min(maxParticipantsPerBooking, slot.remainingCapacity)` for a class; when it is `1` (the common
+  case) show no selector and book exactly one. Never offer a fixed range like 1–4 — the slot's
+  `remainingCapacity` tells you the class's open spots, not how many one buyer may take, so relying
+  on it alone lets the buyer pick a count that `createBooking` then rejects. Pass the chosen count
+  as `createBooking`'s `totalParticipants`.
+- **Re-validate + book** — right before submitting, call
+  `getAvailableSlot(serviceId, { localStartDate, localEndDate, timeZone? })` to confirm the slot
+  is still open (and to pick up the staff resource). Then create + check out in one step:
+  `window.location.href = (await bookAndCheckout(slot, { email, firstName, lastName, phone })).checkoutUrl;`
+  Or split it: `const booking = await createBooking(slot, contact); const url = await checkoutBooking(booking.id);`
+- **Confirmation / return** — after the buyer returns from hosted checkout, the order is placed
+  and Wix Bookings confirms the booking automatically (status becomes `CONFIRMED`, or `PENDING`
+  if the service needs manual approval). Show a confirmation screen on return.
+- **Empty state** — if `countServices()` is 0, show an empty state telling the user to add a
+  service in their Wix dashboard. Never invent services.
+
+## Hard rules (do not violate)
+- ✅ Book ONLY via `createBooking()` → `checkoutBooking()` (or `bookAndCheckout()`), then redirect
+  to the returned `fullUrl`.
+- ❌ Never hand-build a `/checkout`, booking, or calendar URL.
+- ❌ Never mock services, time slots, or availability — render live Wix data or the empty state.
+- ❌ Never invent reviews, ratings, staff, or testimonials. Empty review UI only.
+- ✅ Set `WIX_CLIENT_ID` from the prompt's value (public client id — safe to hardcode).
+- ✅ Send availability/booking dates as **local** `"YYYY-MM-DDThh:mm:ss"` strings plus a
+  `timeZone` — do not send UTC `Z` timestamps to the slot APIs.
+- ✅ Re-validate the slot with `getAvailableSlot()` before `createBooking()` — slots get taken.
+- ✅ Cap participant count at `service.bookingPolicy.participantsPolicy.maxParticipantsPerBooking`
+  (render no selector when it is 1); never offer a fixed range and never use slot capacity as the
+  per-buyer limit — a count above the policy makes `createBooking` fail.
+- The client fails loudly on purpose: `createBooking`/`checkoutBooking` throw on an unbookable
+  slot, a missing booking id, or a missing redirect URL. A green path means it's really bookable —
+  don't swallow these.
+
+## Beyond the snippets
+The snippets cover **APPOINTMENT and CLASS** bookings (the slot picker routes by `service.type`).
+For anything beyond that, extend the client: add a new helper on `wixApiRequest`, looking up the
+exact endpoint, method, and body in the **official Wix API reference** first (never guess):
+- Official Wix API reference: https://dev.wix.com/docs/api-reference.md
+- Single-service booking flow (the full picture): https://dev.wix.com/docs/api-reference/business-solutions/bookings/flow-single-service-booking.md
+- **Courses are NOT covered — a course is enrolled as a *whole*, not booked per session.**
+  `listEventTimeSlots` returns **no** per-session slots for a COURSE (verified — empty even for admin),
+  so the slot-picker flow doesn't apply. Enrolling in a course uses a course-specific flow (whole-course
+  capacity computed from bookings) that these snippets don't implement —
+  https://dev.wix.com/docs/api-reference/business-solutions/bookings/bookings/bookings-reader-v2/query-extended-bookings.md
+- **Service variants / participants** (duration- or person-based pricing):
+  https://dev.wix.com/docs/api-reference/business-solutions/bookings/services/service-options-and-variants/get-service-options-and-variants-by-service-id.md
+- **Add-ons:** https://dev.wix.com/docs/api-reference/business-solutions/bookings/services/services-v2/list-add-on-groups-by-service-id.md
+- **Custom booking form fields** (render `service.form.id`): Get Form Summary —
+  https://dev.wix.com/docs/rest/crm/forms/form-schemas/get-form-summary.md
+- **Member login + a "my bookings" account view** → the **members** vertical
+  (`references/members/INSTRUCTIONS.md`): booking itself works anonymously, but signing a member in
+  (custom login on your own UI) lets them see their own appointments/history.
+
+Keep the snippets as the default for everything they already do; reach for the API reference
+only for the gap.
+
+## Point the user to their dashboard
+In some cases, users need to access the Wix dashboard in order to edit the bookings content for their site. To facilitate this, provide the user with deep links directly to the relevant dashboard pages. For bookings data those pages are:
+- **Booking Services** — `https://manage.wix.com/dashboard/{metaSiteId}/bookings/services` (`Dashboard → Bookings → Booking Services`; add services and service categories)
+- **Staff** — `https://manage.wix.com/dashboard/{metaSiteId}/bookings/staff` (`Dashboard → Bookings → Staff`; add staff and set working hours, so slots are actually bookable)
+
+Substitute the site's `metaSiteId` to complete the links (you have it from the handoff / `ListWixSites`). Include the in-dashboard navigation as a fallback.
+
+## Verification checklist (before declaring done)
+- [ ] `WIX_CLIENT_ID` set to the prompt's value (not the `<YOUR-CLIENT-ID>` placeholder)
+- [ ] Visitor token persists across reload (same visitor identity across reloads)
+- [ ] `queryServices()` renders live services; `countServices()` 0 → empty state (no mock services)
+- [ ] `listAvailableSlots()` returns real bookable slots for a chosen service and date range
+- [ ] Slot is re-validated with `getAvailableSlot()` immediately before booking
+- [ ] Participant selector capped by `maxParticipantsPerBooking` (hidden when 1) — a count above the policy is not offerable
+- [ ] `createBooking()` returns a booking with `status: "CREATED"` and a real id
+- [ ] Checkout redirects via redirect-session `fullUrl` (no hand-built URL)
+- [ ] On return from checkout the booking is confirmed (status `CONFIRMED`/`PENDING`)
+- [ ] No mock services, slots, or availability anywhere
+- [ ] Told the user at least once that they can continue setting up their bookings in the dashboard and provided deep links.

package/skills/wix-vibe-headless/references/bookings/wix-bookings-checkout.js

@@ -0,0 +1,147 @@
+import { wixApiRequest } from "./wix-client.js";
+
+// Data model reference: see INSTRUCTIONS.md
+// Service and TimeSlot shapes: see wix-bookings-services.js
+
+// Wix Bookings app id — required inside catalogReference for the eCommerce checkout.
+const BOOKINGS_APP_ID = "13d21c63-b5ec-5912-8397-c3a5ddb27a97";
+
+/**
+ * Wix Bookings Booking (Bookings Writer V2) — what createBooking returns.
+ * Full model: https://dev.wix.com/docs/api-reference/business-solutions/bookings/bookings/bookings-writer-v2/create-booking.md
+ *
+ *   id {string}, status "CREATED" (not yet on calendar; confirmed after hosted checkout),
+ *   paymentStatus {string} — "NOT_PAID" until checkout completes,
+ *   bookedEntity.slot {object} — { serviceId, scheduleId, startDate, endDate, timezone, location },
+ *   contactDetails {object}, totalParticipants {number}
+ */
+
+/** Visitor's local IANA time zone — used as default for the booking timezone. */
+function defaultTimeZone() {
+  try {
+    return Intl.DateTimeFormat().resolvedOptions().timeZone || "UTC";
+  } catch {
+    return "UTC";
+  }
+}
+
+/**
+ * Create a booking for a slot. The booking starts as status "CREATED" and is NOT yet on the
+ * calendar — it is confirmed automatically after the buyer completes the hosted checkout (call
+ * checkoutBooking next). selectedPaymentOption is "ONLINE".
+ *
+ * Works for **both** service types — it reads the discriminator off the slot:
+ *  - APPOINTMENT slot (from `listAvailableSlots`/`getAvailableSlot`) carries `scheduleId`.
+ *  - CLASS/COURSE slot (from `listEventTimeSlots`) carries `eventInfo.eventId` and no `scheduleId`;
+ *    Wix derives the session's date/resource/location from that event.
+ * For appointments, call `getAvailableSlot` first to re-validate and get staff (`availableResources`).
+ * Throws on an unbookable slot or missing booking id.
+ * https://dev.wix.com/docs/api-reference/business-solutions/bookings/bookings/bookings-writer-v2/create-booking.md
+ *
+ * @param {object} slot                       A TimeSlot from listAvailableSlots/getAvailableSlot/listEventTimeSlots.
+ * @param {{ firstName?: string, lastName?: string, email: string, phone?: string }} contactDetails
+ * @param {{ totalParticipants?: number, timeZone?: string, title?: string }} [options]
+ * @returns {Promise<object>} The created booking (status "CREATED").
+ */
+export async function createBooking(slot, contactDetails, { totalParticipants = 1, timeZone, title } = {}) {
+  if (!slot || slot.bookable === false) {
+    throw new Error("Cannot book: the selected slot is not bookable. Re-check availability and pick another time.");
+  }
+  // A slot is bound either by scheduleId (appointment) or by eventInfo.eventId (class/course).
+  const eventId = slot.eventInfo?.eventId;
+  if (!slot.serviceId || (!slot.scheduleId && !eventId) || !slot.localStartDate || !slot.localEndDate) {
+    throw new Error("Cannot book: slot is missing serviceId, localStartDate/localEndDate, and a scheduleId (appointment) or eventInfo.eventId (class/course).");
+  }
+  if (!contactDetails?.email) {
+    throw new Error("Cannot book: contactDetails.email is required.");
+  }
+
+  const resource = slot.availableResources?.[0]?.resources?.[0];
+
+  // The availability slot's location uses the SERVICE location enum (e.g. "BUSINESS"), but the
+  // createBooking endpoint expects the BOOKING location enum [UNDEFINED, OWNER_BUSINESS,
+  // OWNER_CUSTOM, CUSTOM]. Passing slot.location straight through 400s
+  // ("slot.location.locationType enum must be in [...]"). Remap before sending.
+  const bookingLocation = (() => {
+    const loc = slot.location;
+    if (!loc) return null;
+    const valid = ["UNDEFINED", "OWNER_BUSINESS", "OWNER_CUSTOM", "CUSTOM"];
+    const map = { BUSINESS: "OWNER_BUSINESS", CUSTOM: "CUSTOM", CUSTOMER: "CUSTOM" };
+    const locationType = map[loc.locationType] || (valid.includes(loc.locationType) ? loc.locationType : "OWNER_BUSINESS");
+    return { ...loc, locationType };
+  })();
+
+  const bookedSlot = {
+    serviceId: slot.serviceId,
+    // Appointment → scheduleId; class/course → eventId. Send exactly one.
+    ...(eventId ? { eventId } : { scheduleId: slot.scheduleId }),
+    startDate: slot.localStartDate,
+    endDate: slot.localEndDate,
+    timezone: timeZone || defaultTimeZone(),
+    ...(bookingLocation ? { location: bookingLocation } : {}),
+    ...(resource ? { resource: { id: resource.id, name: resource.name } } : {}),
+  };
+
+  const res = await wixApiRequest("/bookings/v2/bookings", {
+    method: "POST",
+    body: {
+      booking: {
+        bookedEntity: { slot: bookedSlot, title: title || undefined, tags: ["INDIVIDUAL"] },
+        contactDetails,
+        additionalFields: [],
+        totalParticipants,
+        selectedPaymentOption: "ONLINE",
+      },
+      participantNotification: { notifyParticipants: true },
+    },
+  });
+  const booking = res?.booking;
+  if (!booking?.id) throw new Error("Failed to create the booking (no booking id returned).");
+  return booking;
+}
+
+/**
+ * Create an eCommerce checkout for a created booking and return the hosted checkout URL.
+ * Redirect the buyer there (window.location.href = ...). On return, the booking is confirmed.
+ * Throws if no redirect URL is produced.
+ * https://dev.wix.com/docs/rest/business-solutions/e-commerce/checkout/create-checkout.md
+ * @param {string} bookingId  booking.id from createBooking().
+ * @returns {Promise<string>} The hosted-checkout URL to redirect to.
+ */
+export async function checkoutBooking(bookingId) {
+  if (!bookingId) throw new Error("checkoutBooking requires a bookingId.");
+
+  const checkoutRes = await wixApiRequest("/ecom/v1/checkouts", {
+    method: "POST",
+    body: {
+      channelType: "WEB",
+      lineItems: [
+        { quantity: 1, catalogReference: { appId: BOOKINGS_APP_ID, catalogItemId: bookingId } },
+      ],
+    },
+  });
+  const checkoutId = checkoutRes?.checkout?.id;
+  if (!checkoutId) throw new Error("Failed to create a checkout for the booking.");
+
+  const redirect = await wixApiRequest("/headless/v1/redirect-session", {
+    method: "POST",
+    body: { ecomCheckout: { checkoutId }, callbacks: { postFlowUrl: window.location.href } },
+  });
+  const url = redirect?.redirectSession?.fullUrl;
+  if (!url) throw new Error("Failed to create the checkout redirect session.");
+  return url;
+}
+
+/**
+ * Convenience: create the booking and return the hosted-checkout URL in one call.
+ * Equivalent to createBooking() then checkoutBooking(booking.id). Throws loudly on any failure.
+ * @param {object} slot
+ * @param {{ firstName?: string, lastName?: string, email: string, phone?: string }} contactDetails
+ * @param {{ totalParticipants?: number, timeZone?: string, title?: string }} [options]
+ * @returns {Promise<{ booking: object, checkoutUrl: string }>}
+ */
+export async function bookAndCheckout(slot, contactDetails, options = {}) {
+  const booking = await createBooking(slot, contactDetails, options);
+  const checkoutUrl = await checkoutBooking(booking.id);
+  return { booking, checkoutUrl };
+}

package/skills/wix-vibe-headless/references/bookings/wix-bookings-services.js

@@ -0,0 +1,217 @@
+import { wixApiRequest } from "./wix-client.js";
+
+// Data model reference: see INSTRUCTIONS.md
+
+/**
+ * Wix Bookings Service (Services V2) — key fields for the services list and booking UI.
+ * This skill ships the APPOINTMENT flow; CLASS/COURSE are "Beyond the snippets".
+ * Full model: https://dev.wix.com/docs/api-reference/business-solutions/bookings/services/services-v2/query-services.md
+ *
+ *   id {string}, type "APPOINTMENT"|"CLASS"|"COURSE", name {string}, tagLine {string},
+ *   description {string}, hidden {boolean},
+ *   media.items {array} — [{ image: { id, url, width, height, altText } }]
+ *     (url may be a bare Wix media handle — pass through mediaUrl() before rendering),
+ *   payment.rateType "FIXED"|"CUSTOM"|"VARIED"|"NO_FEE"|"SUBSCRIPTION",
+ *   payment.fixed.price { value, currency, formattedValue } — value + currency are always
+ *     present; formattedValue is optional (may be missing), so format the price from
+ *     value+currency and use formattedValue only when present,
+ *   payment.options { online, inPerson, deposit, pricingPlan },
+ *   schedule.id {string}, onlineBooking.enabled {boolean},
+ *   category { id, name }, staffMemberIds {string[]}, locations {array},
+ *   bookingPolicy.participantsPolicy { enabled {boolean}, maxParticipantsPerBooking {number} }
+ *     — the MOST participants a single booking may reserve. Cap the participant selector at this
+ *     value (for a CLASS, also bound by the slot's remainingCapacity). It is commonly 1, in which
+ *     case there is no participant choice at all — book exactly 1. Sending totalParticipants above
+ *     this makes createBooking fail.
+ *
+ * TimeSlot (Time Slots V2, appointments):
+ *   serviceId {string}, localStartDate {string}, localEndDate {string} — "YYYY-MM-DDThh:mm:ss" (no zone),
+ *   bookable {boolean}, scheduleId {string},
+ *   location { id, name, formattedAddress, locationType "BUSINESS"|"CUSTOM"|"CUSTOMER" },
+ *   totalCapacity {number}, remainingCapacity {number},
+ *   availableResources {array} — staff (populated by getAvailableSlot, not listAvailableSlots)
+ * Full model: https://dev.wix.com/docs/api-reference/business-solutions/bookings/time-slots/time-slots-v2/list-availability-time-slots.md
+ */
+
+/** The visitor's local IANA time zone — used as the default for availability queries. */
+function defaultTimeZone() {
+  try {
+    return Intl.DateTimeFormat().resolvedOptions().timeZone || "UTC";
+  } catch {
+    return "UTC";
+  }
+}
+
+/**
+ * Resolve a service image to an absolute URL. Wix media fields are sometimes a bare
+ * handle ("abc.jpg") rather than a full URL; this prefixes the Wix static host.
+ * @param {{ url?: string, id?: string }|string} image
+ * @returns {string|null}
+ */
+export function mediaUrl(image) {
+  const raw = typeof image === "string" ? image : image?.url || image?.id;
+  if (!raw) return null;
+  if (raw.startsWith("http")) return raw;
+  if (raw.startsWith("wix:image://")) {
+    const stripped = raw.slice("wix:image://".length).replace(/^v1\//, "");
+    return `https://static.wixstatic.com/media/${stripped.split("#")[0].split("/")[0]}`;
+  }
+  return `https://static.wixstatic.com/media/${raw}`;
+}
+
+/**
+ * Query bookable services (one page). Returns only services visible to visitors (hidden:false).
+ * https://dev.wix.com/docs/api-reference/business-solutions/bookings/services/services-v2/query-services.md
+ * @param {{ limit?: number, offset?: number }} [options]
+ * @returns {Promise<{ services: object[], total: number, nextOffset: number|null }>}
+ */
+export async function queryServices({ limit = 100, offset = 0 } = {}) {
+  const res = await wixApiRequest("/bookings/v2/services/query", {
+    method: "POST",
+    body: {
+      query: {
+        filter: { hidden: false },
+        paging: { limit, offset },
+      },
+    },
+  });
+  const services = res?.services ?? [];
+  const total = res?.pagingMetadata?.total ?? services.length;
+  const loaded = offset + services.length;
+  return { services, total, nextOffset: loaded < total ? loaded : null };
+}
+
+/**
+ * Fetch a single service by its GUID. Returns null if not found.
+ * @param {string} serviceId
+ * @returns {Promise<object|null>}
+ */
+export async function getService(serviceId) {
+  const res = await wixApiRequest("/bookings/v2/services/query", {
+    method: "POST",
+    body: { query: { filter: { id: serviceId }, paging: { limit: 1 } } },
+  });
+  return res?.services?.[0] ?? null;
+}
+
+/**
+ * Total number of visitor-visible services. Used for empty-state logic.
+ * @returns {Promise<number>}
+ */
+export async function countServices() {
+  const res = await wixApiRequest("/bookings/v2/services/query", {
+    method: "POST",
+    body: { query: { filter: { hidden: false }, paging: { limit: 1 } } },
+  });
+  return res?.pagingMetadata?.total ?? (res?.services?.length ?? 0);
+}
+
+/**
+ * List bookable time slots for an **APPOINTMENT** service within a local date range (availability
+ * comes from staff working hours). For **CLASS / COURSE** services (booked against scheduled
+ * sessions) use `listEventTimeSlots` — this endpoint returns an empty list for them, silently.
+ * If you render a mixed catalog, route by `service.type` via `listSlotsForService`.
+ * Dates are LOCAL ("YYYY-MM-DDThh:mm:ss") in timeZone.
+ * https://dev.wix.com/docs/api-reference/business-solutions/bookings/time-slots/time-slots-v2/list-availability-time-slots.md
+ * @param {string} serviceId
+ * @param {{ fromLocalDate: string, toLocalDate: string, timeZone?: string, limit?: number, cursor?: string }} options
+ * @returns {Promise<{ slots: object[], nextCursor: string|null }>}
+ */
+export async function listAvailableSlots(serviceId, { fromLocalDate, toLocalDate, timeZone, limit = 1000, cursor } = {}) {
+  if (!cursor && (!fromLocalDate || !toLocalDate)) {
+    throw new Error("listAvailableSlots requires fromLocalDate and toLocalDate (local 'YYYY-MM-DDThh:mm:ss').");
+  }
+  const body = cursor
+    ? { cursorPaging: { limit, cursor } }
+    : {
+        serviceId,
+        bookable: true,
+        fromLocalDate,
+        toLocalDate,
+        timeZone: timeZone || defaultTimeZone(),
+        cursorPaging: { limit },
+      };
+  const res = await wixApiRequest("/_api/service-availability/v2/time-slots", { method: "POST", body });
+  return {
+    slots: res?.timeSlots ?? [],
+    nextCursor: res?.cursorPagingMetadata?.cursors?.next ?? null,
+  };
+}
+
+/**
+ * Re-validate a specific appointment slot right before booking, and fetch its available
+ * resources (staff). Always re-check before createBooking — slots can be taken between listing
+ * and booking. Returns the slot or null if it's gone.
+ * https://dev.wix.com/docs/api-reference/business-solutions/bookings/time-slots/time-slots-v2/get-availability-time-slot.md
+ * @param {string} serviceId
+ * @param {{ localStartDate: string, localEndDate: string, timeZone?: string, location?: object }} options
+ * @returns {Promise<object|null>}
+ */
+export async function getAvailableSlot(serviceId, { localStartDate, localEndDate, timeZone, location } = {}) {
+  if (!localStartDate || !localEndDate) {
+    throw new Error("getAvailableSlot requires localStartDate and localEndDate.");
+  }
+  const res = await wixApiRequest("/_api/service-availability/v2/time-slots/get", {
+    method: "POST",
+    body: {
+      serviceId,
+      localStartDate,
+      localEndDate,
+      timeZone: timeZone || defaultTimeZone(),
+      ...(location ? { location } : {}),
+    },
+  });
+  return res?.timeSlot ?? null;
+}
+
+/**
+ * List bookable session slots for **CLASS / COURSE** services within a local date range. These
+ * services are booked against scheduled sessions (calendar events), not staff working hours, so
+ * they use a different endpoint than appointments. Each returned slot carries `eventInfo.eventId`
+ * (the session) and has **no** `scheduleId` — `createBooking` reads that `eventId`.
+ * Dates are LOCAL ("YYYY-MM-DDThh:mm:ss") in timeZone.
+ * https://dev.wix.com/docs/api-reference/business-solutions/bookings/time-slots/time-slots-v2/list-event-time-slots.md
+ * @param {string|string[]} serviceIds  One service id or several (the endpoint takes a plural list).
+ * @param {{ fromLocalDate: string, toLocalDate: string, timeZone?: string, limit?: number, cursor?: string }} options
+ * @returns {Promise<{ slots: object[], nextCursor: string|null }>}
+ */
+export async function listEventTimeSlots(serviceIds, { fromLocalDate, toLocalDate, timeZone, limit = 1000, cursor } = {}) {
+  if (!cursor && (!fromLocalDate || !toLocalDate)) {
+    throw new Error("listEventTimeSlots requires fromLocalDate and toLocalDate (local 'YYYY-MM-DDThh:mm:ss').");
+  }
+  const ids = Array.isArray(serviceIds) ? serviceIds : [serviceIds];
+  const body = cursor
+    ? { cursorPaging: { limit, cursor } }
+    : {
+        serviceIds: ids,
+        bookable: true,
+        fromLocalDate,
+        toLocalDate,
+        timeZone: timeZone || defaultTimeZone(),
+        cursorPaging: { limit },
+      };
+  const res = await wixApiRequest("/_api/service-availability/v2/time-slots/event", { method: "POST", body });
+  return {
+    slots: res?.timeSlots ?? [],
+    nextCursor: res?.cursorPagingMetadata?.cursors?.next ?? null,
+  };
+}
+
+/**
+ * Type-agnostic convenience: list bookable slots for a service, routing to the right endpoint by
+ * `service.type` — APPOINTMENT → `listAvailableSlots`, CLASS/COURSE → `listEventTimeSlots`. The
+ * returned slots are shaped the same either way (`localStartDate`/`localEndDate`/`location`/
+ * `availableResources`), and each is bookable via `createBooking`.
+ * NOTE: a **COURSE** is enrolled as a whole (not per session), so it typically returns **no** slots
+ * here — the per-slot booking flow applies to APPOINTMENT and CLASS.
+ * @param {{ _id?: string, id?: string, type?: string }} service  A service from queryServices.
+ * @param {{ fromLocalDate: string, toLocalDate: string, timeZone?: string, limit?: number, cursor?: string }} options
+ * @returns {Promise<{ slots: object[], nextCursor: string|null }>}
+ */
+export async function listSlotsForService(service, options = {}) {
+  const serviceId = service?._id || service?.id;
+  if (!serviceId) throw new Error("listSlotsForService requires a service with an id.");
+  return service?.type === "CLASS" || service?.type === "COURSE"
+    ? listEventTimeSlots(serviceId, options)
+    : listAvailableSlots(serviceId, options);
+}