@wix/agent-skills 1.15.0 → 1.16.0

package/skills/wix-vibe-headless/references/bookings/{wix-bookings-services.js → app/rest/wix-bookings-services.js}

@@ -9,25 +9,55 @@ import { wixApiRequest } from "./wix-client.js";
  *
  *   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 },
- *   payment.options { online, inPerson, deposit, pricingPlan },
- *   schedule.id {string}, onlineBooking.enabled {boolean},
- *   category { id, name }, staffMemberIds {string[]}, locations {array},
+ *   defaultCapacity {number} — bookable seats per session; 1 for a typical appointment,
+ *   media.mainMedia.image { id, url, width, height, altText } — the PRIMARY service image (what the
+ *     seed sets and the card shows); media.items {array} is the gallery, media.coverMedia the cover.
+ *     Read mainMedia first, fall back to items[0]/coverMedia. url may be a bare Wix media handle —
+ *     pass through mediaUrl() before rendering,
+ *   mainSlug.name {string} — merchant-facing slug ("swedish-massage"). This client routes on the
+ *     service id; switching to slugs means changing the shipped route too,
+ *   payment.rateType "FIXED"|"CUSTOM"|"VARIED"|"NO_FEE"|"SUBSCRIPTION" — branch on this before
+ *     reading a price. Use servicePriceLabel() from lib/serviceFacts.js instead of payment.fixed
+ *     directly, or VARIED and NO_FEE services render with no price,
+ *   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.varied { defaultPrice, minPrice, maxPrice } — Money each, same shape as fixed.price,
+ *   payment.options { online, inPerson, deposit, pricingPlan } — how a customer may PAY. `online`
+ *     here means "can pay online", NOT that the service happens online; don't build a location
+ *     label from it,
+ *   conferencing.enabled {boolean} — a video service; this is the real "online" signal,
+ *   schedule.id {string},
+ *   schedule.availabilityConstraints.sessionDurations {number[]} — session minutes for an
+ *     APPOINTMENT, empty for CLASS/COURSE; see serviceDuration(),
+ *   onlineBooking { enabled, requireManualApproval } — requireManualApproval means the business
+ *     confirms the booking after the fact, so the CTA is a request, not a confirmation,
+ *   category { id, name } — a service with no category is not visible on the live site,
+ *   staffMemberIds {string[]},
+ *   locations {array} — [{ id, type "BUSINESS"|"CUSTOMER"|"CUSTOM", calculatedAddress }]. The type is
+ *     where the service happens; calculatedAddress is empty for CUSTOMER and often absent until the
+ *     business configures a location. See serviceLocationLabel(),
  *   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.
+ *   bookingPolicy.reschedulePolicy / .cancellationPolicy { enabled, limitLatestReschedule /
+ *     limitLatestCancellation, latestRescheduleInMinutes / latestCancellationInMinutes } — see
+ *     serviceRescheduleNote(),
  *
  * 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)
+ *   bookableCapacity {number} — CLASS slots: seats still bookable after policy limits, which can be
+ *     lower than remainingCapacity,
+ *   bookingPolicyViolations { tooEarlyToBook, tooLateToBook, bookOnlineDisabled } — why a listed slot
+ *     still isn't bookable; only reachable if you drop the `bookable: true` filter,
+ *   availableResources {array} — staff. getAvailableSlot populates it for an APPOINTMENT; a
+ *     CLASS/COURSE slot already carries it from the list call,
+ *   eventInfo { eventId, eventTitle } — CLASS/COURSE only; those slots have no scheduleId
  * Full model: https://dev.wix.com/docs/api-reference/business-solutions/bookings/time-slots/time-slots-v2/list-availability-time-slots.md
  */
 
@@ -79,6 +109,48 @@ export async function queryServices({ limit = 100, offset = 0 } = {}) {
   return { services, total, nextOffset: loaded < total ? loaded : null };
 }
 
+/**
+ * Query visitor-visible services in one category, for a category-filtered listing.
+ * The filter key is the dotted path `category.id` — a bare `categoryId` is rejected as an unknown
+ * field.
+ * @param {string} categoryId
+ * @param {{ limit?: number, offset?: number }} [options]
+ * @returns {Promise<{ services: object[], total: number, nextOffset: number|null }>}
+ */
+export async function queryServicesByCategory(categoryId, { limit = 100, offset = 0 } = {}) {
+  const res = await wixApiRequest("/bookings/v2/services/query", {
+    method: "POST",
+    body: {
+      query: {
+        filter: { hidden: false, "category.id": categoryId },
+        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 };
+}
+
+/**
+ * The categories that visitor-visible services actually belong to, in the order Wix sorts them.
+ * Derived from a services page rather than the Categories API, so the menu can never list a category
+ * with nothing bookable in it.
+ * @param {object[]} services
+ * @returns {{ id: string, name: string }[]}
+ */
+export function categoriesOf(services) {
+  const byId = new Map();
+  for (const s of services || []) {
+    const c = s?.category;
+    if (c?.id && !byId.has(c.id)) byId.set(c.id, { id: c.id, name: c.name, sortOrder: c.sortOrder ?? 0 });
+  }
+  return [...byId.values()]
+    .sort((a, b) => a.sortOrder - b.sortOrder)
+    .map(({ id, name }) => ({ id, name }));
+}
+
 /**
  * Fetch a single service by its GUID. Returns null if not found.
  * @param {string} serviceId
@@ -113,7 +185,7 @@ export async function countServices() {
  * 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 }>}
+ * @returns {Promise<{ slots: object[], nextCursor: string|null, timeZone: string|null }>}
  */
 export async function listAvailableSlots(serviceId, { fromLocalDate, toLocalDate, timeZone, limit = 1000, cursor } = {}) {
   if (!cursor && (!fromLocalDate || !toLocalDate)) {
@@ -133,6 +205,9 @@ export async function listAvailableSlots(serviceId, { fromLocalDate, toLocalDate
   return {
     slots: res?.timeSlots ?? [],
     nextCursor: res?.cursorPagingMetadata?.cursors?.next ?? null,
+    // The zone the returned localStartDate strings are in — label the picker with this, so the times
+    // on screen and the zone named beside them can't disagree.
+    timeZone: res?.timeZone ?? null,
   };
 }
 
@@ -171,7 +246,7 @@ export async function getAvailableSlot(serviceId, { localStartDate, localEndDate
  * 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 }>}
+ * @returns {Promise<{ slots: object[], nextCursor: string|null, timeZone: string|null }>}
  */
 export async function listEventTimeSlots(serviceIds, { fromLocalDate, toLocalDate, timeZone, limit = 1000, cursor } = {}) {
   if (!cursor && (!fromLocalDate || !toLocalDate)) {
@@ -191,7 +266,10 @@ export async function listEventTimeSlots(serviceIds, { fromLocalDate, toLocalDat
   const res = await wixApiRequest("/_api/service-availability/v2/time-slots/event", { method: "POST", body });
   return {
     slots: res?.timeSlots ?? [],
-    nextCursor: res?.cursorPagingMetadata?.cursors?.next ?? null,
+    // This endpoint nests the cursor under `pagingMetadata`, where the appointment one uses
+    // `cursorPagingMetadata` — reading only the latter silently disables paging for classes.
+    nextCursor: res?.pagingMetadata?.cursors?.next ?? res?.cursorPagingMetadata?.cursors?.next ?? null,
+    timeZone: res?.timeZone ?? null,
   };
 }
 
@@ -204,7 +282,7 @@ export async function listEventTimeSlots(serviceIds, { fromLocalDate, toLocalDat
  * 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 }>}
+ * @returns {Promise<{ slots: object[], nextCursor: string|null, timeZone: string|null }>}
  */
 export async function listSlotsForService(service, options = {}) {
   const serviceId = service?._id || service?.id;

package/skills/wix-vibe-headless/references/bookings/seed/SEED.md

@@ -0,0 +1,117 @@
+# Bookings — seeding
+
+Seed a Wix Bookings catalog by **calling `seed-bookings.js`** — don't hand-write the REST calls.
+It's a build-time module (run via `exec_tool`, not shipped in the app) that abstracts every Wix
+Bookings seed operation. Load it and call **`setupBookings` — the one-call path** — with plain data.
+
+> **Transcribed from `wix-headless/references/inline-recipes/setup-bookings.md` — NOT yet live-verified.**
+
+```js
+// build-time exec_tool
+const { accessToken } = await base44.asServiceRole.connectors.getConnection("wix"); // Base44 (generic: use $TOKEN)
+const fs = require("fs");
+// exec_tool's require can return EMPTY exports for these build-time modules — load the file itself:
+const seed = (() => { const m = { exports: {} };
+  new Function("module", "exports", "require", fs.readFileSync("/app/.agents/skills/wix-vibe-headless/references/bookings/seed/seed-bookings.js", "utf8"))(m, m.exports, require);
+  return m.exports; })();
+const ctx = { token: accessToken, siteId: WIX_METASITE_ID };
+
+// ONE call: install → resolve staff → categories → services → CLASS sessions → images, all in the
+// correct order with ids kept in memory (no hand-threading of scheduleId/resourceId). `category` is
+// a NAME (resolved to an id internally). Free service: set free:true, omit price. CLASS `sessions`
+// are local "YYYY-MM-DDThh:mm:ss".
+const result = await seed.setupBookings(ctx, {
+  services: [
+    // `imageUrl` per service is optional and attached IN this one call. Pass a plain url — the module
+    // imports it into Wix Media for you (bookings binds a service image by the Wix Media file id, not a
+    // url). Use the FINAL https://media.base44.com/... url from the COMPLETED generate_image (it runs in
+    // the background while you build — wait for it), never a still-generating /__generating__/<id>.png.
+    { type: "APPOINTMENT", name: "Consultation", description: "…", tagLine: "…", price: 75, duration: 60, category: "Our Services", imageUrl: "https://media.base44.com/…" },
+    { type: "CLASS", name: "Morning Yoga", description: "…", price: 20, capacity: 20, category: "Our Services",
+      sessions: [{ start: "2026-08-10T09:00:00", end: "2026-08-10T10:00:00" }] },
+  ],
+  // staffResourceId defaults to the fresh install's owner (queryStaff()[0].resourceId).
+});
+// result: { services:[...], categories:[{id,name}], resourceId, sessionsScheduled, imagesAttached }
+
+// fallback (finer control / re-attach): import the url to Wix Media, then patch one service after the fact.
+// const file = await seed.importImage(ctx, imageUrl);   // → { id, url } (Wix Media file id + wixstatic url)
+// await seed.attachServiceImage(ctx, { serviceId: s.id, revision: s.revision, image: { id: file.id, url: file.url, width: 1024, height: 1024 } });
+```
+
+**Seeding is additive — never delete or overwrite existing content.** Don't clean up, don't remove
+"sample" data, don't reset. Just add.
+
+## What the shipped UI renders from this
+
+Pass these and the catalog reads like a real one; omit them and the pages have visible holes:
+
+- **`sessions` on every CLASS.** A class's bookable times ARE its sessions, so a class seeded without
+  them shows "No available times in this range" — which reads as broken, not empty. Schedule a few
+  weeks out. An APPOINTMENT needs none: its slots come from staff working hours, which a fresh
+  install's owner already has.
+- **`duration`** (APPOINTMENT, minutes) → the card's `60 min · 1-to-1` line and the DURATION cell on
+  the service page. A class has no service-level duration and shows CAPACITY instead, so pass
+  `capacity` there.
+- **`tagLine`** → the card's second line. One line about the service, not a copy of `description`.
+- **`price`**, or **`free: true`** for a no-fee service, which the UI labels "Free".
+
+Two things this module can't set, so don't try: **varied pricing** (a "From €85" service needs
+`payment.varied`) and **`conferencing`** (the UI's "Online" location label reads that flag — seeded
+services all sit at the business location, which shows as "In person").
+
+## Escape hatch — individual functions
+Reach for the functions below only when the one-call `setupBookings` doesn't fit (partial re-seed,
+custom staff/ordering). `setupBookings` is built from them, in this order:
+
+```js
+await seed.installBookingsApp(ctx);
+const staff = await seed.queryStaffWithRetry(ctx);                   // → [{resourceId,id,name}]; polls (fresh install provisions the owner async); use resourceId, NOT id
+const cats = await seed.createCategories(ctx, ["Our Services"]);    // → [{id,name}]; every service needs a categoryId
+const services = await seed.createServices(ctx, [                   // → [{id,slug,revision,type,scheduleId}]
+  { type: "APPOINTMENT", name: "Consultation", price: 75, duration: 60, categoryId: cats[0].id, staffMemberIds: [staff[0].resourceId] },
+  { type: "CLASS", name: "Morning Yoga", price: 20, capacity: 20, categoryId: cats[0].id },
+]);
+// CLASS only: schedule sessions with each class's returned scheduleId (local wall-clock times)
+await seed.scheduleClassSessions(ctx, [
+  { scheduleId: services[1].scheduleId, resourceId: staff[0].resourceId, start: "2026-08-10T09:00:00", end: "2026-08-10T10:00:00", capacity: 20 },
+]);
+// images (optional): import the url to Wix Media first (bookings binds by file id), then attach.
+// Use the FINAL https://media.base44.com/... url only (never a /__generating__/ placeholder).
+const file = await seed.importImage(ctx, imageUrl);   // → { id, url } (Wix Media file id + wixstatic url)
+await seed.attachServiceImage(ctx, { serviceId: services[0].id, revision: services[0].revision, image: { id: file.id, url: file.url, width: 1024, height: 1024 } });
+```
+
+## Functions
+| fn | does |
+|---|---|
+| `setupBookings(ctx, {services, staffResourceId?})` | **one-call**: install → staff → categories → services → CLASS sessions → images |
+| `installBookingsApp(ctx)` | install the Wix Bookings app on the site |
+| `queryStaff(ctx)` | `[{resourceId,id,name}]` — one shot; use `resourceId`, not `id` |
+| `queryStaffWithRetry(ctx)` | STEP 1 — same, but polls until the default owner provisions after a fresh install (avoids `MISSING_APPOINTMENT_RESOURCES`) |
+| `createStaff(ctx, [{name,description}])` | create named staff → `[{resourceId,id,name}]` (omit email/phone) |
+| `queryCategories(ctx)` | `[{id,name}]` — reuse a category created earlier this run |
+| `createCategories(ctx, names)` | STEP 2 — every service needs a `category.id` or it's invisible → `[{id,name}]`; reuses an existing same-named category (idempotent, no dupes on re-run) |
+| `createServices(ctx, services)` | STEP 3 — one bulk create (APPOINTMENT/CLASS mixed) → `[{id,slug,revision,type,scheduleId,success,error}]` |
+| `scheduleClassSessions(ctx, sessions)` | STEP 4 (CLASS only) — one bulk Calendar-Events-V3 create → `[{id,success,error}]` |
+| `getService(ctx, serviceId)` | fetch a service (current `revision`; confirm an image landed) |
+| `importImage(ctx, url)` | import an external url into Wix Media → `{id,url}` (file id + wixstatic url); bookings binds by this file id |
+| `attachServiceImage(ctx, {serviceId,revision,image})` | optional — patch `media.mainMedia`/`coverMedia` (revision-checked); `image.id` MUST be a Wix Media file id from `importImage` |
+
+Both bulk calls report per-item `success`/`error` — retry only the failed items **once** with the
+same body; don't loop and don't re-create the ones that already succeeded.
+
+## Reference
+If a call returns a shape you didn't expect, or you need an operation this module doesn't cover,
+use the **`wix-docs`** skill to search + read the live Wix API reference — never guess. The
+authoritative source recipe is `wix-headless/references/inline-recipes/setup-bookings.md`.
+
+Read a method's page before writing its call: it carries the exact body shape, the required
+permission scope, and the response envelope.
+- Install a Wix app onto the site: https://dev.wix.com/docs/api-reference/business-management/app-installation/app-installation/install-app.md
+- Import an image into Wix Media: https://dev.wix.com/docs/api-reference/assets/media/media-manager/files/import-file.md
+- Bulk Create Services: https://dev.wix.com/docs/api-reference/business-solutions/bookings/services/services-v2/bulk-create-services.md
+- Create Category: https://dev.wix.com/docs/api-reference/business-solutions/bookings/services/categories-v2/create-category.md
+- Create Staff Member: https://dev.wix.com/docs/api-reference/business-solutions/bookings/staff-members/staff-members/create-staff-member.md
+- Query Staff Members: https://dev.wix.com/docs/api-reference/business-solutions/bookings/staff-members/staff-members/query-staff-members.md
+- Bulk Create Event (calendar sessions): https://dev.wix.com/docs/api-reference/business-management/calendar/events-v3/bulk-create-event.md

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

@@ -0,0 +1,333 @@
+// Bookings seed helpers — run at BUILD TIME via exec_tool (NOT shipped in the app).
+// The agent requires this and calls the functions with plain data; all Wix Bookings
+// request/response mechanics (the flat Services-V2 payload, the resourceId-vs-staff-id trap,
+// the category-visibility invariant, the { event: {…} } session wrapper, the silent media.image
+// drop) live here, once.
+//
+// **NOT yet live-verified — transcribed from setup-bookings.md.**
+//
+// Usage (build-time exec_tool):
+//   const { accessToken } = await base44.asServiceRole.connectors.getConnection("wix");  // Base44 (generic: use $TOKEN)
+//   const seed = require("/app/.agents/skills/wix-vibe-headless/references/bookings/seed/seed-bookings.js");
+//   const ctx = { token: accessToken, siteId: WIX_METASITE_ID };
+//
+//   await seed.installBookingsApp(ctx);                          // if the site doesn't have Wix Bookings yet
+//
+//   // ORDER MATTERS: resolve a staff resource (STEP 1) and a category (STEP 2) BEFORE services (STEP 3).
+//   const staff = await seed.queryStaffWithRetry(ctx);           // polls: fresh install provisions the owner async
+//   const resourceId = staff[0].resourceId;                      // NB: resourceId, NOT staff id
+//   const cats = await seed.createCategories(ctx, ["Our Services"]);
+//   const services = await seed.createServices(ctx, [
+//     { type: "APPOINTMENT", name: "Consultation", description: "…", tagLine: "…",
+//       price: 75, duration: 60, categoryId: cats[0].id, staffMemberIds: [resourceId] },
+//     { type: "CLASS", name: "Morning Yoga", description: "…", capacity: 20,
+//       price: 20, categoryId: cats[0].id },
+//   ]);
+//   // STEP 4 (CLASS only): needs each class's returned scheduleId.
+//   await seed.scheduleClassSessions(ctx, services.filter(s => s.type === "CLASS").map(s => ({
+//     scheduleId: s.scheduleId, resourceId, start: "2026-08-10T09:00:00", end: "2026-08-10T10:00:00", capacity: 20,
+//   })));
+//   // optional — import the image url to Wix Media first (bookings binds by file id), then patch (revision-checked).
+//   // const file = await seed.importImage(ctx, imageUrl); // → { id, url } (Wix Media file id + wixstatic url)
+//   // await seed.attachServiceImage(ctx, { serviceId: s.id, revision: s.revision, image: { id: file.id, url: file.url, width: 1024, height: 1024 } });
+//
+// If any call fails with a shape the caller didn't expect, or you need an operation this module
+// doesn't cover, fall back to the wix-docs skill (search + read the live Wix API reference) —
+// never guess. Source recipe (authoritative): wix-headless/references/inline-recipes/setup-bookings.md.
+
+const API = "https://www.wixapis.com";
+// Wix Bookings app id (from the recipe's "API surfaces" note).
+const BOOKINGS_APP_ID = "13d21c63-b5ec-5912-8397-c3a5ddb27a97";
+
+async function req(ctx, path, { method = "POST", body } = {}) {
+  const res = await fetch(API + path, {
+    method,
+    headers: {
+      Authorization: `Bearer ${ctx.token}`,
+      "wix-site-id": ctx.siteId,
+      "Content-Type": "application/json",
+    },
+    body: body ? JSON.stringify(body) : undefined,
+  });
+  const json = await res.json().catch(() => ({}));
+  if (!res.ok) throw new Error(`${method} ${path} -> ${res.status}: ${JSON.stringify(json).slice(0, 400)}`);
+  return json;
+}
+
+// name -> url slug fallback when item.mainSlug.name is absent (lowercase, non-alphanumerics -> hyphens, dedupe)
+function slugify(name) {
+  return String(name || "")
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "");
+}
+
+// plain service -> flat Services V2 create object. price omitted / free:true -> NO_FEE.
+// sessionDurations is APPOINTMENT-only; staffMemberIds is required-non-empty for APPOINTMENT, omitted for CLASS.
+function buildService(s) {
+  const isAppointment = s.type === "APPOINTMENT";
+  const free = s.free === true || s.price == null;
+  const out = {
+    type: s.type,
+    name: s.name,
+    description: s.description,
+    tagLine: s.tagLine,
+    defaultCapacity: s.capacity ?? (isAppointment ? 1 : undefined), // required for ALL types
+    onlineBooking: { enabled: true, requireManualApproval: false, allowMultipleRequests: false },
+    payment: free
+      ? { rateType: "NO_FEE", options: { online: false, inPerson: true } }
+      : {
+          rateType: "FIXED",
+          fixed: { price: { value: String(s.price), currency: s.currency ?? "USD" } }, // value is a STRING; site currency wins
+          options: { online: true, inPerson: false },
+        },
+    category: { id: s.categoryId }, // mandatory for live-site visibility
+    locations: [{ type: "BUSINESS" }], // never OWNER_BUSINESS on the services endpoint
+  };
+  if (isAppointment) {
+    out.schedule = { availabilityConstraints: { sessionDurations: [s.duration] } }; // APPOINTMENT only, minutes
+    out.staffMemberIds = s.staffMemberIds; // resourceId(s) from STEP 1 — non-empty or MISSING_APPOINTMENT_RESOURCES
+  }
+  return out;
+}
+
+// ---- exported operations ----
+
+async function installBookingsApp(ctx) {
+  return req(ctx, "/apps-installer-service/v1/app-instance/install", { body: {
+    tenant: { tenantType: "SITE", id: ctx.siteId },
+    appInstance: { appDefId: BOOKINGS_APP_ID, enabled: true },
+  } });
+}
+
+// The default "Business Owner" is a RESOURCE, not a service — it won't appear here.
+async function listServices(ctx) {
+  const r = await req(ctx, "/bookings/v2/services/query", { body: { query: { paging: { limit: 100 } } } });
+  return (r.services ?? []).map((s) => ({ id: s.id, name: s.name }));
+}
+
+// STEP 1: resolve staff resources. Returns [{ resourceId, id, name }].
+// ⚠️ staffMemberIds takes resourceId, NOT the staff id — read staffMember.resourceId.
+async function queryStaff(ctx) {
+  const r = await req(ctx, "/bookings/v1/staff-members/query", {
+    body: { query: {}, fields: ["RESOURCE_DETAILS"] },
+  });
+  return (r.staffMembers ?? []).map((m) => ({ resourceId: m.resourceId, id: m.id, name: m.name }));
+}
+
+// installBookingsApp → provisioning is async (Wix signals completion via the App-Instance-Installed
+// webhook, which an exec script can't receive). The default "Business Owner" resource isn't queryable
+// in the same tick, so queryStaff returns [] (or throws "Business schedule not found") until it lands.
+// Poll so the one-call path resolves the owner instead of failing APPOINTMENT services with
+// MISSING_APPOINTMENT_RESOURCES. Already-provisioned sites return on the first try (no added latency).
+async function queryStaffWithRetry(ctx, { tries = 10, delayMs = 2000 } = {}) {
+  let lastErr;
+  for (let i = 0; i < tries; i++) {
+    try { const s = await queryStaff(ctx); if (s.length) return s; }
+    catch (e) { lastErr = e; }
+    if (i < tries - 1) await new Promise((r) => setTimeout(r, delayMs));
+  }
+  if (lastErr) throw lastErr; // never provisioned → surface the real error rather than a silent []
+  return [];
+}
+
+// STEP 1 (optional): create named staff when the request names stylists/providers. staff: [{ name, description }].
+// ⚠️ Omit email/phone unless you have a real value — V1 rejects empty strings. Returns [{ resourceId, id, name }].
+async function createStaff(ctx, staff) {
+  const out = [];
+  for (const m of staff) {
+    const body = { staffMember: { name: m.name, description: m.description } };
+    const r = await req(ctx, "/bookings/v1/staff-members", { body });
+    out.push({ resourceId: r.staffMember?.resourceId, id: r.staffMember?.id, name: r.staffMember?.name });
+  }
+  return out;
+}
+
+// STEP 2: query existing categories (to reuse one created earlier this run). Returns [{ id, name }].
+async function queryCategories(ctx) {
+  const r = await req(ctx, "/bookings/v2/categories/query", { body: { query: {} } });
+  return (r.categories ?? []).map((c) => ({ id: c.id, name: c.name }));
+}
+
+// STEP 2: create categories — every service needs a category.id or it's invisible on the live site.
+// Independent (no shared revision, unlike Stores categories); looped here one call per category.
+async function createCategories(ctx, names) {
+  // Reuse an existing same-named category instead of creating a duplicate. Bookings categories aren't
+  // unique-by-name, so a re-run (or a partial-failure retry — categories are created before services)
+  // would otherwise pile up dupes. Keeps the seed additive-but-idempotent.
+  const byName = new Map((await queryCategories(ctx)).map((c) => [c.name, c]));
+  const out = [];
+  for (const name of names) {
+    let cat = byName.get(name);
+    if (!cat) {
+      const r = await req(ctx, "/bookings/v2/categories", { body: { category: { name } } });
+      cat = { id: r.category?.id, name };
+      byName.set(name, cat);
+    }
+    out.push(cat);
+  }
+  return out;
+}
+
+/**
+ * STEP 3: bulk-create services (up to 100), one call. APPOINTMENT and CLASS may be mixed.
+ * MUST run AFTER staff (STEP 1) and category (STEP 2) are resolved.
+ * @param services [{ type:"APPOINTMENT"|"CLASS", name, description, tagLine?, categoryId,
+ *   price?, currency?, free?, duration?(APPOINTMENT minutes), capacity?, staffMemberIds?(resourceIds, APPOINTMENT) }]
+ * @returns [{ id, slug, revision, type, scheduleId, index, success, error }]
+ *   scheduleId feeds scheduleClassSessions (CLASS); revision feeds attachServiceImage.
+ *   Retry only the items where success===false, ONCE, with the same body — don't loop, don't re-create successes.
+ */
+async function createServices(ctx, services) {
+  const body = { services: services.map(buildService), returnEntity: true };
+  const r = await req(ctx, "/bookings/v2/bulk/services/create", { body });
+  return (r.results ?? []).map((res, i) => {
+    const item = res.item ?? {};
+    return {
+      id: item.id ?? res.itemMetadata?.id,
+      slug: item.mainSlug?.name ?? slugify(item.name ?? services[i]?.name),
+      revision: item.revision,
+      type: item.type ?? services[i]?.type,
+      scheduleId: item.schedule?.id,
+      index: res.itemMetadata?.originalIndex ?? i,
+      success: res.itemMetadata?.success ?? false,
+      error: res.itemMetadata?.error,
+    };
+  });
+}
+
+/**
+ * STEP 4 (CLASS only): schedule sessions in one bulk Calendar-Events-V3 call. Skip for APPOINTMENT.
+ * @param sessions [{ scheduleId(CLASS item.schedule.id), resourceId(from STEP 1), start, end, capacity? }]
+ *   start/end are LOCAL wall-clock "YYYY-MM-DDThh:mm:ss" (no Z), today-or-future.
+ * @returns [{ id, index, success, error }]  — events send no returnEntity, so ids come from itemMetadata only.
+ *   Retry only failed events once.
+ */
+async function scheduleClassSessions(ctx, sessions) {
+  const body = {
+    events: sessions.map((s) => ({
+      event: {
+        scheduleId: s.scheduleId,
+        type: "CLASS",
+        start: { localDate: s.start },
+        end: { localDate: s.end },
+        resources: [{ id: s.resourceId, permissionRole: "WRITER" }], // non-empty + WRITER, else UNKNOWN_ROLE 400
+        ...(s.capacity != null ? { totalCapacity: s.capacity } : {}),
+      },
+    })),
+  };
+  const r = await req(ctx, "/calendar/v3/bulk/events/create", { body });
+  return (r.results ?? []).map((res, i) => ({
+    id: res.itemMetadata?.id,
+    index: res.itemMetadata?.originalIndex ?? i,
+    success: res.itemMetadata?.success ?? false,
+    error: res.itemMetadata?.error,
+  }));
+}
+
+// Fetch a service (for its current revision before an image patch, or to confirm an image landed).
+async function getService(ctx, serviceId) {
+  return req(ctx, `/bookings/v2/services/${serviceId}`, { method: "GET" });
+}
+
+/**
+ * Import an external image URL into Wix Media → { id, url }. Bookings binds a service image by the
+ * Wix Media file **id** (`mainMedia.image.id`), NOT a url — so an external url (e.g. a base44
+ * generate_image result) MUST be imported first; the raw url as the id stores (200) but renders
+ * nothing. `id` is the wixstatic file id (`<hash>~mv2.png`), `url` the permanent wixstatic url.
+ */
+async function importImage(ctx, url, displayName = "image.png") {
+  const r = await req(ctx, "/site-media/v1/files/import", { body: { url, mimeType: "image/png", displayName } });
+  const f = r.file || r;
+  if (!f?.id) throw new Error(`import-file returned no file id: ${JSON.stringify(r).slice(0, 200)}`);
+  return { id: f.id, url: f.url };
+}
+
+/**
+ * Attach an image (optional). Writes under media.mainMedia + media.coverMedia; revision-checked.
+ * @param it { serviceId, revision, image: { id, url, width, height } } — `image.id` MUST be a Wix
+ *   Media file id (from importImage), never a raw external url.
+ * ⚠️ Writing under media.image (not mainMedia/coverMedia) returns 200 but SILENTLY drops the image — a 200
+ * is not proof; confirm with getService and check media.mainMedia is populated. Never block on failure.
+ */
+async function attachServiceImage(ctx, it) {
+  return req(ctx, `/bookings/v2/services/${it.serviceId}`, {
+    method: "PATCH",
+    body: {
+      service: {
+        id: it.serviceId,
+        revision: it.revision,
+        media: { mainMedia: { image: it.image }, coverMedia: { image: it.image } },
+      },
+    },
+  });
+}
+
+/**
+ * ONE-CALL seed: install → resolve staff → categories → services → CLASS sessions → images, in the
+ * correct order, keeping ids in memory (no hand-threading of scheduleId/resourceId across exec
+ * calls). DEFAULT path — call it once instead of the individual functions.
+ *
+ * @param plan {{
+ *   services: [{ type:"APPOINTMENT"|"CLASS", name, description, tagLine?, price?, free?, duration?,
+ *                capacity?, category?(name), staffMemberIds?,
+ *                sessions?: [{ start, end, capacity? }],  // CLASS only; local "YYYY-MM-DDThh:mm:ss"
+ *                imageUrl? }],                             // a plain image url; imported to Wix Media here, optional
+ *   staffResourceId?: string,   // defaults to the fresh install's owner (queryStaff()[0].resourceId)
+ * }}
+ * @returns { services:[...createServices], categories:[{id,name}], resourceId, sessionsScheduled, imagesAttached }
+ */
+async function setupBookings(ctx, { services = [], staffResourceId } = {}) {
+  await installBookingsApp(ctx);
+
+  let resourceId = staffResourceId;
+  if (!resourceId) {
+    const staff = await queryStaffWithRetry(ctx); // fresh install provisions the default owner async — poll
+    resourceId = staff[0]?.resourceId;
+  }
+
+  const catNames = [...new Set(services.map((s) => s.category).filter(Boolean))];
+  const cats = catNames.length ? await createCategories(ctx, catNames) : [];
+  const catIdByName = new Map(cats.map((c) => [c.name, c.id]));
+
+  const created = await createServices(ctx, services.map((s) => ({
+    type: s.type, name: s.name, description: s.description, tagLine: s.tagLine,
+    price: s.price, free: s.free, duration: s.duration, capacity: s.capacity,
+    categoryId: s.category ? catIdByName.get(s.category) : undefined,
+    staffMemberIds: s.staffMemberIds ?? (s.type === "APPOINTMENT" && resourceId ? [resourceId] : undefined),
+  })));
+
+  const sessions = [];
+  created.forEach((c, i) => {
+    const plan = services[i];
+    if (c.type === "CLASS" && Array.isArray(plan?.sessions)) {
+      for (const ses of plan.sessions) {
+        sessions.push({ scheduleId: c.scheduleId, resourceId, start: ses.start, end: ses.end, capacity: ses.capacity ?? plan.capacity });
+      }
+    }
+  });
+  const scheduled = sessions.length ? await scheduleClassSessions(ctx, sessions) : [];
+
+  let imagesAttached = 0;
+  for (let i = 0; i < created.length; i++) {
+    const url = services[i]?.imageUrl;         // a plain image url (e.g. base44 generate_image) — imported here
+    if (!url || !created[i]?.id) continue;
+    try {
+      const file = await importImage(ctx, url, `${created[i].slug || "service"}.png`);   // → Wix Media file id
+      await attachServiceImage(ctx, {
+        serviceId: created[i].id, revision: created[i].revision,
+        image: { id: file.id, url: file.url, width: 1024, height: 1024 },
+      });
+      imagesAttached++;
+    } catch { /* never block on image failure — leave the service text-only */ }
+  }
+
+  return { services: created, categories: cats, resourceId, sessionsScheduled: scheduled.length, imagesAttached };
+}
+
+module.exports = {
+  setupBookings,
+  installBookingsApp, listServices,
+  queryStaff, queryStaffWithRetry, createStaff, queryCategories, createCategories,
+  createServices, scheduleClassSessions, getService, importImage, attachServiceImage,
+};