@wix/agent-skills 1.17.0 → 1.18.0

package/skills/wix-vibe-headless/references/bookings/app/rest/wix-bookings-rentals.js

@@ -0,0 +1,250 @@
+import { wixApiRequest } from "./wix-client.js";
+import { listAvailableSlots } from "./wix-bookings-services.js";
+
+/**
+ * Wix Rentals — a DELTA on `wix-bookings-services.js`, not a replacement.
+ *
+ * Wix Rentals has no APIs of its own. A rental is a Bookings **service** with rentals-specific
+ * field values, so the catalog read, the booking form, and the whole
+ * `createBooking → cart → checkout` chain in `wix-bookings-checkout.js` are UNCHANGED. Only
+ * three things differ, and they are all here:
+ *
+ *   1. every catalog read filters by the rentals `appId`, or rentals and appointments interleave
+ *   2. the customer picks the LENGTH, so availability is two calls: start times, then the valid
+ *      ends for the chosen start
+ *   3. price is a rate per unit, so the total for a chosen length comes from the server
+ *
+ * What makes a service a rental (from the docs' own mapping — nothing is inferred):
+ *   type      always "APPOINTMENT"
+ *   appId     always RENTALS_APP_ID
+ *   schedule.availabilityConstraints.durationRange   replaces `sessionDurations`
+ *                                                    — MUTUALLY EXCLUSIVE, one or the other
+ *   primaryResourceType   a resource type id, not staff — availability comes from its resources
+ *   payment.rateType      always "FIXED", charged per hour or per day
+ *
+ * ⚠️ Because the two constraint fields are mutually exclusive, `isRental()` below is a reliable
+ * test on the DATA. Never decide "this is a rental" from the brief, the service name, or a
+ * category — a 60-minute yoga class and a meeting room rented for 1–8 hours are told apart by
+ * which constraint the service carries, and nothing else.
+ *
+ * docs: https://dev.wix.com/docs/api-reference/business-solutions/rentals/wix-rentals-and-the-bookings-apis.md
+ * docs: https://dev.wix.com/docs/api-reference/business-solutions/rentals/about-wix-rentals-availability.md
+ */
+
+/** The Wix Rentals app. Used twice: to filter the catalog, and as the cart's catalogReference.appId. */
+export const RENTALS_APP_ID = "ff5d6eb1-65e4-4f9a-8b14-64d34c12cc2e";
+
+/** The Wix Bookings app — the other half of a mixed site. */
+export const BOOKINGS_APP_ID = "13d21c63-b5ec-5912-8397-c3a5ddb27a97";
+
+/**
+ * Is this service a rental? True when it carries a duration RANGE the customer picks within,
+ * rather than a fixed session length. This is the only correct test.
+ * @param {object} service
+ * @returns {boolean}
+ */
+export function isRental(service) {
+  return Boolean(service?.schedule?.availabilityConstraints?.durationRange);
+}
+
+/**
+ * The rental's unit and bounds, or null for an ordinary service.
+ * Hourly bounds are MINUTES (30–1440), daily bounds are DAYS (1–8).
+ * @param {object} service
+ * @returns {{ unit: "HOUR"|"DAY", min: number, max: number, step: number }|null}
+ */
+export function rentalDuration(service) {
+  const range = service?.schedule?.availabilityConstraints?.durationRange;
+  if (!range) return null;
+  if (range.unitType === "DAY") {
+    return {
+      unit: "DAY",
+      min: range.dayOptions?.minDurationInDays ?? 1,
+      max: range.dayOptions?.maxDurationInDays ?? 1,
+      step: 1,
+    };
+  }
+  return {
+    unit: "HOUR",
+    min: range.hourOptions?.minDurationInMinutes ?? 30,
+    max: range.hourOptions?.maxDurationInMinutes ?? 1440,
+    step: 30,
+  };
+}
+
+/**
+ * Query rentals only. On a site that has both apps an unfiltered `queryServices` returns
+ * haircuts next to meeting rooms, so this is not optional — it is the same query with the
+ * rentals `appId` on the filter.
+ *
+ * Pass `appId: BOOKINGS_APP_ID` to get the ordinary services instead, on a mixed site.
+ * @param {{ limit?: number, offset?: number, appId?: string }} [options]
+ * @returns {Promise<{ services: object[], total: number, nextOffset: number|null }>}
+ */
+export async function queryRentals({ limit = 100, offset = 0, appId = RENTALS_APP_ID } = {}) {
+  const res = await wixApiRequest("/bookings/v2/services/query", {
+    method: "POST",
+    body: { query: { filter: { hidden: false, appId }, 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 resource type id(s) a rental's availability comes from — read off `serviceResources`.
+ * Every rental availability call must pass these as `includeResourceTypeIds`, or it returns zero slots.
+ * @param {object} service
+ * @returns {string[]}
+ */
+export function rentalResourceTypeIds(service) {
+  return (service?.serviceResources ?? [])
+    .map((sr) => sr.resourceType?._id ?? sr.resourceType?.id)
+    .filter(Boolean);
+}
+
+/**
+ * Start times for a rental — step 1 of 2.
+ *
+ * A rental is an APPOINTMENT-typed service, so this is the same availability call an appointment
+ * uses; what comes back are the times a rental may START. The customer then picks how long, which is
+ * `listEndOptions` below. Pass the whole `service` so its resource types ride along — the
+ * availability engine reads them to find a resource-driven service's slots.
+ * @param {object} service  A rental service from queryRentals.
+ * @param {{ fromLocalDate: string, toLocalDate: string, timeZone?: string, limit?: number, cursor?: string }} options
+ * @returns {Promise<{ slots: object[], nextCursor: string|null, timeZone: string|null }>}
+ */
+export function listRentalStartSlots(service, options = {}) {
+  const serviceId = service?._id || service?.id;
+  return listAvailableSlots(serviceId, { ...options, includeResourceTypeIds: rentalResourceTypeIds(service) });
+}
+
+/**
+ * The valid END times for a chosen start — step 2 of 2, HOURLY rentals only.
+ *
+ * Each entry is a TimeSlot sharing `localStartDate` with the request and varying only in
+ * `localEndDate`, sorted shortest first. The service's maximum duration always caps the list,
+ * so a `maxLocalEndDate` beyond it is ignored rather than rejected.
+ *
+ * ⚠️ Hourly only. A DAILY rental has no end options — its lengths are whole days, so walk
+ * consecutive days from the chosen start instead (`dailyEndOptions` below).
+ * https://dev.wix.com/docs/api-reference/business-solutions/bookings/time-slots/time-slots-v2/list-availability-time-slot-end-options.md
+ * Pass the chosen start slot's own `location`. It carries `locationType` (and an `id` on a
+ * multi-location site); `{ locationType: "BUSINESS" }` is enough on a single-location site.
+ * @param {string} serviceId
+ * @param {{ localStartDate: string, location: object, maxLocalEndDate?: string, timeZone?: string }} options
+ * @returns {Promise<{ endOptions: object[], timeZone: string|null }>}
+ */
+export async function listEndOptions(serviceId, { localStartDate, location, maxLocalEndDate, timeZone } = {}) {
+  if (!localStartDate) throw new Error("listEndOptions requires localStartDate (local 'YYYY-MM-DDThh:mm:ss').");
+  if (!location) throw new Error("listEndOptions requires the chosen slot's location.");
+  const res = await wixApiRequest("/_api/service-availability/v2/time-slots/end-options", {
+    method: "POST",
+    body: {
+      serviceId,
+      localStartDate,
+      location,
+      ...(maxLocalEndDate ? { maxLocalEndDate } : {}),
+      ...(timeZone ? { timeZone } : {}),
+    },
+  });
+  return { endOptions: res?.endOptions ?? [], timeZone: res?.timeZone ?? null };
+}
+
+/**
+ * The lengths a DAILY rental can run for from a chosen start day — the daily counterpart to
+ * `listEndOptions`. A day's slot list is the availability, so this walks forward from the start
+ * and stops at the first day that has none: a 3-day rental needs all 3 days free, and a gap
+ * means the longer options are not bookable however far out the calendar goes.
+ *
+ * Returns one entry per bookable length, `{ days, localEndDate }`, shortest first.
+ * `localEndDate` is midnight of the day AFTER the last rented day — the end boundary is
+ * exclusive, which is the same convention the catalog's availability window uses.
+ * @param {object} service  A rental service (daily).
+ * @param {{ localStartDate: string, timeZone?: string }} options
+ * @returns {Promise<{ days: number, localEndDate: string }[]>}
+ */
+export async function dailyEndOptions(service, { localStartDate, timeZone } = {}) {
+  const duration = rentalDuration(service);
+  if (!duration || duration.unit !== "DAY") {
+    throw new Error("dailyEndOptions expects a DAY-unit rental — use listEndOptions for hourly.");
+  }
+  const serviceId = service._id || service.id;
+  const includeResourceTypeIds = rentalResourceTypeIds(service);
+  const startDay = localStartDate.slice(0, 10);
+  const dayAfter = (isoDay, n) => {
+    const d = new Date(`${isoDay}T00:00:00Z`);
+    d.setUTCDate(d.getUTCDate() + n);
+    return d.toISOString().slice(0, 10);
+  };
+
+  const out = [];
+  for (let days = 1; days <= duration.max; days++) {
+    const dayToCheck = dayAfter(startDay, days - 1);
+    const { slots } = await listAvailableSlots(serviceId, {
+      fromLocalDate: `${dayToCheck}T00:00:00`,
+      toLocalDate: `${dayAfter(dayToCheck, 1)}T00:00:00`,
+      timeZone,
+      limit: 1,
+      includeResourceTypeIds,
+    });
+    if (!slots.length) break; // a gap — every longer option is unbookable too
+    if (days >= duration.min) out.push({ days, localEndDate: `${dayAfter(startDay, days)}T00:00:00` });
+  }
+  return out;
+}
+
+/**
+ * The price for a chosen length, from the server.
+ *
+ * ⚠️ Never compute this client-side. A rental is charged as a RATE — per hour or per day — and
+ * hourly is calculated at per-minute granularity, so a 90-minute rental of a $10/hour room is
+ * $15. Multiplying a displayed base price by a rounded number of hours quietly disagrees with
+ * what the customer is charged at checkout.
+ *
+ * ⚠️ Omitting the local dates or the time zone does NOT error — it returns a duration-blind
+ * price, which is the same trap in a quieter form.
+ * https://dev.wix.com/docs/api-reference/business-solutions/bookings/pricing/pricing-api/preview-price.md
+ * @param {string} serviceId
+ * @param {{ localStartDate: string, localEndDate: string, timeZone: string, numberOfParticipants?: number }} options
+ * @returns {Promise<{ total: string, currency: string|null, raw: object }>}
+ */
+export async function previewRentalPrice(serviceId, { localStartDate, localEndDate, timeZone, numberOfParticipants = 1 } = {}) {
+  if (!localStartDate || !localEndDate || !timeZone) {
+    throw new Error("previewRentalPrice requires localStartDate, localEndDate and timeZone — without them the price ignores the duration.");
+  }
+  const res = await wixApiRequest("/bookings/v2/pricing/v2/pricing/preview", {
+    method: "POST",
+    body: {
+      bookingLineItems: [{ serviceId, localStartDate, localEndDate, timeZone, numberOfParticipants }],
+    },
+  });
+  const info = res?.priceInfo ?? {};
+  const total = info.totalPrice ?? info.total ?? {};
+  return {
+    total: total.formattedValue ?? (total.value != null ? String(total.value) : ""),
+    currency: total.currency ?? null,
+    raw: info,
+  };
+}
+
+/**
+ * A rental's rate, ready to render — "$10 / hour" or "$120 / day".
+ * `servicePriceLabel` in `lib/serviceFacts.js` renders the same number as a flat price, which
+ * reads as the whole cost of the rental rather than its rate.
+ * @param {object} service
+ * @returns {string}
+ */
+export function rentalRateLabel(service) {
+  const duration = rentalDuration(service);
+  if (!duration) return "";
+  const price = service?.payment?.fixed?.price;
+  const money =
+    price?.formattedValue ||
+    (price?.currency && price?.value != null
+      ? new Intl.NumberFormat(undefined, { style: "currency", currency: price.currency }).format(Number(price.value))
+      : "");
+  if (!money) return "";
+  return `${money} / ${duration.unit === "DAY" ? "day" : "hour"}`;
+}

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

@@ -183,11 +183,13 @@ export async function countServices() {
  * 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
+ * For a rental (a resource-driven service), pass its resource type id(s) as `includeResourceTypeIds`
+ * so the slots come back with their bookable resources; a staff appointment can omit it.
  * @param {string} serviceId
- * @param {{ fromLocalDate: string, toLocalDate: string, timeZone?: string, limit?: number, cursor?: string }} options
+ * @param {{ fromLocalDate: string, toLocalDate: string, timeZone?: string, limit?: number, cursor?: string, includeResourceTypeIds?: string[] }} options
  * @returns {Promise<{ slots: object[], nextCursor: string|null, timeZone: string|null }>}
  */
-export async function listAvailableSlots(serviceId, { fromLocalDate, toLocalDate, timeZone, limit = 1000, cursor } = {}) {
+export async function listAvailableSlots(serviceId, { fromLocalDate, toLocalDate, timeZone, limit = 1000, cursor, includeResourceTypeIds } = {}) {
   if (!cursor && (!fromLocalDate || !toLocalDate)) {
     throw new Error("listAvailableSlots requires fromLocalDate and toLocalDate (local 'YYYY-MM-DDThh:mm:ss').");
   }
@@ -200,6 +202,7 @@ export async function listAvailableSlots(serviceId, { fromLocalDate, toLocalDate
         toLocalDate,
         timeZone: timeZone || defaultTimeZone(),
         cursorPaging: { limit },
+        ...(includeResourceTypeIds?.length ? { includeResourceTypeIds } : {}),
       };
   const res = await wixApiRequest("/_api/service-availability/v2/time-slots", { method: "POST", body });
   return {
@@ -287,7 +290,11 @@ export async function listEventTimeSlots(serviceIds, { fromLocalDate, toLocalDat
 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);
+  if (service?.type === "CLASS" || service?.type === "COURSE") return listEventTimeSlots(serviceId, options);
+  // For a rental, name its resource type(s) so the slots come back; reading them off the service
+  // keeps this call type-agnostic (a staff appointment just yields an empty list here).
+  const includeResourceTypeIds =
+    options.includeResourceTypeIds ??
+    (service?.serviceResources ?? []).map((sr) => sr.resourceType?._id ?? sr.resourceType?.id).filter(Boolean);
+  return listAvailableSlots(serviceId, { ...options, includeResourceTypeIds });
 }

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

@@ -101,6 +101,47 @@ await seed.attachServiceImage(ctx, { serviceId: services[0].id, revision: servic
 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.
 
+## Rentals
+
+`seed-rentals.js` is the rentals half — the same transport, a different create order and payload.
+Wix Rentals has no APIs of its own, so a rental is a Bookings service with rentals-specific
+field values.
+
+```js
+const seed = require("…/references/bookings/seed/seed-rentals.js");
+await seed.setupRentals(ctx, {
+  resourceTypeName: "Meeting rooms",
+  resources: ["Room A", "Room B"],              // parallel capacity = MORE RESOURCES
+  rentals: [
+    { name: "Meeting room, hourly", description: "…", price: 25, unit: "HOUR", min: 60, max: 480 },
+    { name: "Meeting room, daily",  description: "…", price: 180, unit: "DAY", min: 1, max: 5 },
+  ],
+});
+// → { resourceType, resources, services, ok, problems }
+```
+
+`price` is a RATE — per hour or per day — not the cost of a rental.
+Hourly `min`/`max` are MINUTES (30–1440); daily are DAYS (1–8).
+
+**`ok` must be true.** `problems` is the read-back check: a service created without `appId` or
+without `durationRange` still returns 200 and is simply a plain Bookings service from then on.
+
+### The four traps this seed handles
+
+- **Install Rentals ONLY.** It provisions the Bookings infrastructure it runs on; installing
+  Wix Bookings as well is redundant.
+- **`appId` is immutable after create.** A service created without it is a plain Bookings
+  service forever — there is no update that converts it.
+- **Order is load-bearing: resource type → resources → services.** A service whose resource
+  type holds no resources has permanently empty availability, and nothing errors.
+- **Rental services do not use categories.** Unlike bookings, do not create or assign one.
+- **`serviceResources` is required** and the docs' Create Service parameter list omits it.
+  Without it the create fails `MISSING_APPOINTMENT_RESOURCES`, whose message sends you to check
+  the resource type's contents — a dead end, since it fails even when the type is populated.
+
+Resources are seeded **24/7** (no working hours) so a multi-day rental stays one booking rather
+than a multi-service group. Pass `workingHours` only when the brief names opening hours.
+
 ## 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

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

@@ -0,0 +1,267 @@
+// Rentals seed helpers — run at BUILD TIME via exec_tool (NOT shipped in the app).
+// A DELTA on seed-bookings.js: Wix Rentals has no APIs of its own, so a rental is a Bookings
+// service carrying rentals-specific field values. Everything about the transport, images and
+// error handling is the same; only the create order and the service payload differ.
+//
+// Live-verified end to end on fresh headless sites (install → resource type → resources → service →
+// time-slots → end-options).
+//
+// Usage (build-time exec_tool) — prefer `setupRentals`, which runs the whole flow in the one order
+// that works and threads the resource ids into each service for you:
+//   const { accessToken } = await base44.asServiceRole.connectors.getConnection("wix");
+//   const seed = require("/app/.agents/skills/wix-vibe-headless/references/bookings/seed/seed-rentals.js");
+//   const ctx = { token: accessToken, siteId: WIX_METASITE_ID };
+//   await seed.setupRentals(ctx, {
+//     resourceTypeName: "Meeting rooms",
+//     resources: ["Room A", "Room B"],                              // capacity = MORE RESOURCES
+//     rentals: [
+//       { name: "Meeting room, hourly", description: "…", price: 25, unit: "HOUR", min: 60, max: 480 },
+//       { name: "Meeting room, daily",  description: "…", price: 180, unit: "DAY",  min: 1,  max: 5 },
+//     ],
+//   });
+//   // Calling the steps by hand instead? ORDER IS LOAD-BEARING (resource type → resources → service),
+//   // and each rental spec must carry `resourceTypeId` AND `resourceIds` (the ids from createResources).
+//
+// What a bookable rental needs, and setupRentals sets every one:
+//   1. `appId` on the service at create time (it is immutable, so set it here rather than later).
+//   2. Resources created before the service, and their ids listed in `serviceResources[].resourceIds`.
+//   3. No category — a rental is surfaced by its `appId`, not by a Bookings category.
+//
+// Images are reused from seed-bookings.js — require both.
+// Source recipe: wix-headless/references/inline-recipes/setup-rentals.md.
+
+const API = "https://www.wixapis.com";
+
+/** The Wix Rentals app — adds resource types and duration ranges on top of Bookings. */
+const RENTALS_APP_ID = "ff5d6eb1-65e4-4f9a-8b14-64d34c12cc2e";
+
+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;
+}
+
+/**
+ * Install Wix Rentals. Idempotent. Rentals provisions the Bookings infrastructure it runs on, so a
+ * rental's availability comes from a Rentals-only install — Wix Bookings does not need to be added.
+ */
+async function installRentalsApp(ctx) {
+  try {
+    await req(ctx, "/apps-installer-service/v1/app-instance/install", {
+      body: {
+        tenant: { tenantType: "SITE", id: ctx.siteId },
+        appInstance: { appDefId: RENTALS_APP_ID, enabled: true },
+      },
+    });
+  } catch {
+    /* already installed is fine */
+  }
+}
+
+/**
+ * A resource TYPE — the kind of thing being rented ("Meeting rooms", "Vans", "Cameras").
+ * A rental service points at one of these; the individual rentable items live inside it.
+ * @returns {Promise<{ id: string, name: string }>}
+ */
+async function createResourceType(ctx, name) {
+  const res = await req(ctx, "/bookings/v2/resources/resource-types", { body: { resourceType: { name } } });
+  const type = res?.resourceType ?? {};
+  return { id: type.id ?? type._id, name: type.name ?? name };
+}
+
+/** Existing resource types, so a re-run reuses one instead of making a duplicate. */
+async function queryResourceTypes(ctx) {
+  const res = await req(ctx, "/bookings/v2/resources/resource-types/query", { body: { query: {} } });
+  return (res?.resourceTypes ?? []).map((t) => ({ id: t.id ?? t._id, name: t.name }));
+}
+
+/** Get a resource type by name, creating it only if it isn't there. Additive. */
+async function ensureResourceType(ctx, name) {
+  const existing = (await queryResourceTypes(ctx)).find((t) => t.name === name);
+  return existing ?? createResourceType(ctx, name);
+}
+
+/**
+ * The individual rentable items inside a type — Room A, Room B, Van 1.
+ *
+ * ⚠️ PARALLEL CAPACITY COMES FROM MORE RESOURCES, not from a capacity number: two rooms that
+ * can be booked at the same time are two resources.
+ *
+ * ⚠️ Seeded 24/7 on purpose — no `workingHoursSchedules`. A resource with working hours makes a
+ * multi-day rental span several bookable windows, which Wix then models as a multi-service
+ * group booking instead of one booking. Pass `workingHours` only when the brief names opening
+ * hours and you accept that.
+ * @returns {Promise<{ id: string, name: string }[]>}
+ */
+async function createResources(ctx, resourceTypeId, names, { workingHours } = {}) {
+  const out = [];
+  for (const name of names) {
+    const res = await req(ctx, "/bookings/v2/resources", {
+      body: {
+        resource: {
+          name,
+          // Link the resource to its type with a top-level `typeId` (a bare GUID).
+          typeId: resourceTypeId,
+          ...(workingHours ? { workingHoursSchedules: workingHours } : {}),
+        },
+      },
+    });
+    const r = res?.resource ?? {};
+    out.push({ id: r.id ?? r._id, name: r.name ?? name });
+  }
+  return out;
+}
+
+/** The Wix Rentals default booking form. Provisioned by the Rentals app; the id is the same on every site. */
+const RENTALS_FORM_ID = "3a2ea2ce-91f4-4617-ab24-629933c0c31a";
+
+/**
+ * Build one rental service payload.
+ *
+ * Field values that MAKE it a rental (all required together):
+ *   type: "APPOINTMENT"          — rentals are always appointment-typed
+ *   appId: RENTALS_APP_ID        — immutable after create
+ *   durationRange                — replaces sessionDurations; the two are mutually exclusive
+ *   serviceResources +           — which resource type AND which resources supply availability
+ *   primaryResourceType
+ *
+ * Hourly bounds are MINUTES (30–1440); daily bounds are DAYS (1–8). One service = one unit
+ * type: to rent the same room by the hour AND by the day, create two services.
+ * @param {object} s  spec + `resourceTypeId` and `resourceIds` (the ids from createResources).
+ */
+function buildRental(s) {
+  const unit = s.unit === "DAY" ? "DAY" : "HOUR";
+  const durationRange =
+    unit === "DAY"
+      ? { unitType: "DAY", dayOptions: { minDurationInDays: s.min ?? 1, maxDurationInDays: s.max ?? 5 } }
+      : { unitType: "HOUR", hourOptions: { minDurationInMinutes: s.min ?? 60, maxDurationInMinutes: s.max ?? 480 } };
+
+  return {
+    type: "APPOINTMENT",
+    appId: RENTALS_APP_ID,
+    name: s.name,
+    description: s.description ?? "",
+    ...(s.tagLine ? { tagLine: s.tagLine } : {}),
+    hidden: false,
+    defaultCapacity: 1,
+    // Use the Wix Rentals default booking form so checkout collects contact details.
+    form: { id: RENTALS_FORM_ID },
+    // Make the rental bookable online.
+    onlineBooking: { enabled: true, requireManualApproval: false, allowMultipleRequests: false },
+    // A rental is priced as a RATE per unit of time — the number below is per hour or per day,
+    // and Wix multiplies it by the length the customer picks.
+    payment: {
+      rateType: "FIXED",
+      fixed: { price: { value: String(s.price ?? 0), currency: s.currency ?? "USD" } },
+      options: { online: true, inPerson: false },
+    },
+    schedule: { availabilityConstraints: { durationRange } },
+    // Name the resource type AND its concrete resource ids — availability comes from the listed ids.
+    serviceResources: [{ resourceType: { id: s.resourceTypeId }, resourceIds: { values: s.resourceIds ?? [] } }],
+    // The resource type as a bare GUID string, and one of the types named in serviceResources above.
+    primaryResourceType: s.resourceTypeId,
+    locations: [{ type: "BUSINESS" }],
+  };
+}
+
+/**
+ * Create rental services. Additive — an existing service with the same name is left alone.
+ * @returns {Promise<{ id: string, name: string, unit: string, revision: string }[]>}
+ */
+async function createRentals(ctx, rentals) {
+  const existing = await req(ctx, "/bookings/v2/services/query", {
+    body: { query: { filter: { appId: RENTALS_APP_ID } } },
+  }).catch(() => ({ services: [] }));
+  const byName = new Map((existing.services ?? []).map((s) => [s.name, s]));
+
+  const out = [];
+  for (const spec of rentals) {
+    const already = byName.get(spec.name);
+    if (already) {
+      out.push({
+        id: already.id ?? already._id,
+        name: already.name,
+        unit: already.schedule?.availabilityConstraints?.durationRange?.unitType ?? null,
+        revision: already.revision,
+        created: false,
+      });
+      continue;
+    }
+    const res = await req(ctx, "/bookings/v2/services", { body: { service: buildRental(spec) } });
+    const svc = res?.service ?? {};
+    out.push({
+      id: svc.id ?? svc._id,
+      name: svc.name ?? spec.name,
+      unit: svc.schedule?.availabilityConstraints?.durationRange?.unitType ?? null,
+      revision: svc.revision,
+      created: true,
+    });
+  }
+  return out;
+}
+
+/**
+ * Read the rentals back and confirm each one is actually a rental. A service created without
+ * `appId` or without `durationRange` still returns 200 — it is simply a plain Bookings service
+ * from then on, permanently, and this is the only check that catches it.
+ * @returns {Promise<{ ok: boolean, problems: string[] }>}
+ */
+async function verifyRentals(ctx, expectedNames) {
+  const res = await req(ctx, "/bookings/v2/services/query", {
+    body: { query: { filter: { appId: RENTALS_APP_ID } } },
+  });
+  const live = new Map((res?.services ?? []).map((s) => [s.name, s]));
+  const problems = [];
+  for (const name of expectedNames) {
+    const svc = live.get(name);
+    if (!svc) {
+      problems.push(`${name}: not returned by an appId-filtered query — it was not created as a rental`);
+      continue;
+    }
+    if (!svc.schedule?.availabilityConstraints?.durationRange) {
+      problems.push(`${name}: no durationRange — created as a plain service, and appId is immutable`);
+    }
+    if (!svc.primaryResourceType) problems.push(`${name}: no primaryResourceType — availability will be empty`);
+    if (!svc.serviceResources?.some((sr) => sr.resourceIds?.values?.length))
+      problems.push(`${name}: serviceResources carry no resourceIds — availability will be empty`);
+  }
+  return { ok: problems.length === 0, problems };
+}
+
+/**
+ * The whole rentals seed, in the one order that works.
+ * @param {object} ctx
+ * @param {{ resourceTypeName: string, resources: string[], rentals: object[] }} plan
+ */
+async function setupRentals(ctx, { resourceTypeName, resources = [], rentals = [] }) {
+  await installRentalsApp(ctx);
+  const type = await ensureResourceType(ctx, resourceTypeName);
+  const created = await createResources(ctx, type.id, resources);
+  // Every rental service must list the concrete resource ids, or its availability is empty (see buildRental).
+  const resourceIds = created.map((c) => c.id);
+  const services = await createRentals(ctx, rentals.map((r) => ({ ...r, resourceTypeId: type.id, resourceIds })));
+  const check = await verifyRentals(ctx, rentals.map((r) => r.name));
+  return { resourceType: type, resources: created, services, ...check };
+}
+
+module.exports = {
+  RENTALS_APP_ID,
+  installRentalsApp,
+  createResourceType,
+  queryResourceTypes,
+  ensureResourceType,
+  createResources,
+  buildRental,
+  createRentals,
+  verifyRentals,
+  setupRentals,
+};

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

@@ -2,9 +2,12 @@
 
 Unlike the other verticals, CMS ships **no UI**. A CMS is schema-driven — every collection is
 different — so there are no meaningful "list/detail" components to hand you. You **build the UI
-yourself** (list, detail, home, forms) in your own framework and design tokens, calling the shipped
-**utils**. Everything talks to Wix directly over the public `WIX_CLIENT_ID` (anonymous visitor token)
-using the official Wix Data endpoints — never hand-build a Wix Data URL, never mock items.
+yourself** (list, detail, home) in your own framework and design tokens, calling the shipped
+**utils**. **A visitor-fillable form is the `forms` vertical, not `cms`** — come here only when the
+app must read the entries back (a public gallery, a listing, a member's "my submissions"); a visitor
+cannot read Forms submissions. Everything talks to Wix directly over the public `WIX_CLIENT_ID`
+(anonymous visitor token) using the official Wix Data endpoints — never hand-build a Wix Data URL,
+never mock items.
 
 ## What ships (utils only)