@wix/agent-skills 1.26.0 → 1.27.0

package/skills/wix-headless-templates/rentals/project/src/wix/rentals/rentals.ts

@@ -0,0 +1,173 @@
+// Rentals over the SDK — the only file that touches raw Bookings entities on this transport: the
+// rental catalog (Services V2 filtered to the Rentals app), start availability, hourly end options,
+// the daily walk's day list, the price preview, the booking form, and the
+// createBooking → Cart V2 → checkout-or-place sequence. Every body is built in ./rentals-core
+// (shared with the REST twin in templates/rentals/rest/); this file is the transport only. Copy
+// as-is; extend by calling these exports, never by editing them. Failures are loud where a visitor
+// acts (renting) and silent-with-a-default where they only inform (form, preview).
+// docs: https://dev.wix.com/docs/api-reference/business-solutions/bookings/services/services-v2/query-services.md
+// docs: https://dev.wix.com/docs/api-reference/business-solutions/bookings/time-slots/time-slots-v2/list-availability-time-slots.md
+// docs: https://dev.wix.com/docs/api-reference/business-solutions/bookings/time-slots/time-slots-v2/list-availability-time-slot-end-options.md
+// docs: https://dev.wix.com/docs/api-reference/business-solutions/bookings/pricing/pricing-api/preview-price.md
+// docs: https://dev.wix.com/docs/api-reference/business-solutions/bookings/bookings/bookings-writer-v2/create-booking.md
+// docs: https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/purchase-flow/cart-v2/create-cart.md
+// docs: https://dev.wix.com/docs/api-reference/business-management/headless/redirects/create-redirect-session.md
+import { availabilityTimeSlots, bookings as bookingsModule, pricing as pricingModule, services as servicesModule } from "@wix/bookings";
+import { createCart, calculateCart, placeOrder } from "@wix/auto_sdk_ecom_cart-v-2";
+import { redirects as redirectsModule } from "@wix/redirects";
+import { wixFetch, wixModule } from "../sdk";
+import { imgSrc } from "../media";
+import {
+  FALLBACK_FIELDS,
+  RENTALS_APP_ID,
+  RENTALS_FORM_ID,
+  RENTALS_PAGE_SIZE,
+  bookingIdOf,
+  bookingOptions,
+  bookingRequest,
+  cartIdOf,
+  cartRequest,
+  checkoutRedirectRequest,
+  checkoutRequired,
+  confirmedResult,
+  contactOf,
+  dailyEndOptions,
+  defaultTimeZone,
+  endOptionsRequest,
+  friendlyError,
+  isRental,
+  nextSlotsCursor,
+  previewRequest,
+  startsRequest,
+  toDetail,
+  toFormFields,
+  toHourlyEndOptions,
+  toQuote,
+  toStartOptions,
+  toSummary,
+  type Raw,
+  type StartWindow,
+} from "./rentals-core";
+import type { EndOption, RentalDetail, RentalFormField, RentalQuote, RentalResult, RentalSummary, StartOption } from "./types";
+
+export { RENTALS_APP_ID, RENTALS_FORM_ID, RENTALS_PAGE_SIZE, dailyEndOptions, defaultTimeZone };
+
+const services = wixModule(servicesModule);
+const slots = wixModule(availabilityTimeSlots);
+const bookings = wixModule(bookingsModule);
+const pricing = wixModule(pricingModule);
+const cart = wixModule({ createCart, calculateCart, placeOrder });
+const redirects = wixModule(redirectsModule);
+
+export interface RentalsPage {
+  items: RentalSummary[];
+  /** Another page follows — pass `offset + items.length`. */
+  hasMore: boolean;
+}
+
+/**
+ * One page of rentals: Bookings services carrying the Rentals app id (the filter that keeps haircuts
+ * out of a rooms catalog on a site that has both), not hidden, with a duration range.
+ */
+export async function fetchRentals({ limit = RENTALS_PAGE_SIZE, offset = 0 }: { limit?: number; offset?: number } = {}): Promise<RentalsPage> {
+  const res = await services.queryServices().eq("appId", RENTALS_APP_ID).eq("hidden", false).limit(limit).skip(offset).find();
+  return { items: ((res.items ?? []) as Raw[]).filter(isRental).map((r) => toSummary(r, imgSrc)), hasMore: res.hasNext() };
+}
+
+/** One rental by its URL slug (mainSlug.name); null when not found or not a rental. */
+export async function fetchRentalBySlug(slug: string): Promise<RentalDetail | null> {
+  const res = await services.queryServices().eq("mainSlug.name", slug).eq("appId", RENTALS_APP_ID).eq("hidden", false).limit(1).find();
+  const raw = res.items?.[0] as Raw | undefined;
+  return raw && isRental(raw) ? toDetail(raw, imgSrc) : null;
+}
+
+export interface StartsPage {
+  options: StartOption[];
+  /** The zone the server computed in — the one requested, or the business zone when none was sent. */
+  timeZone: string | null;
+}
+
+/**
+ * The starts a customer can pick in [start of `from`'s day, +days): times for an hourly rental, one
+ * per available day for a daily one; follows the cursor until the window is complete. Each start
+ * carries the resource it books.
+ */
+export async function fetchStarts(rental: Pick<RentalDetail, "id" | "unit" | "resourceTypeId">, window: StartWindow = {}): Promise<StartsPage> {
+  const raws: Raw[] = [];
+  let timeZone: string | null = null;
+  let cursor: string | undefined;
+  do {
+    const res: Raw = await slots.listAvailabilityTimeSlots(startsRequest(rental, { ...window, cursor }) as any);
+    raws.push(...((res.timeSlots ?? []) as Raw[]));
+    timeZone ??= res.timeZone ?? null;
+    cursor = nextSlotsCursor(res) ?? undefined;
+  } while (cursor);
+  return { options: toStartOptions(raws, rental.unit), timeZone };
+}
+
+/**
+ * The lengths a customer can pick for a chosen start. HOURLY: the server's end options (capped by the
+ * rental's maximum and by the resource's next booking). DAILY: the consecutive available days from the
+ * start, walked here from the starts already fetched (`availableDayKeys`).
+ */
+export async function fetchEndOptions(rental: Pick<RentalDetail, "id" | "unit" | "minUnits" | "maxUnits">, start: StartOption, { timeZone, availableDayKeys = [] }: { timeZone?: string | null; availableDayKeys?: string[] } = {}): Promise<EndOption[]> {
+  if (rental.unit === "DAY") return dailyEndOptions(start, availableDayKeys, rental);
+  const res: Raw = await slots.listAvailabilityTimeSlotEndOptions(rental.id, endOptionsRequest(start, timeZone, "_id") as any);
+  return toHourlyEndOptions(res, start);
+}
+
+/** The server's price for a start and length; falls back to rate × length when the preview fails. */
+export async function fetchQuote(rental: Pick<RentalDetail, "id" | "rateAmount" | "currency" | "unit">, start: StartOption, end: EndOption, timeZone: string = defaultTimeZone()): Promise<RentalQuote> {
+  try {
+    const res: Raw = await pricing.previewPrice(previewRequest(rental, start, end.endLocal, timeZone) as any);
+    return toQuote(res, rental, end.units);
+  } catch {
+    return toQuote(null, rental, end.units);
+  }
+}
+
+/** The booking form's fields (the Rentals default form on a seeded site); contact basics when unreadable. */
+export async function fetchRentalForm(formId: string | null): Promise<RentalFormField[]> {
+  const id = encodeURIComponent(formId ?? RENTALS_FORM_ID);
+  try {
+    const json = async (path: string): Promise<Raw | null> => {
+      const r = await wixFetch(path);
+      return r.ok ? ((await r.json()) as Raw) : null;
+    };
+    const [summary, form] = await Promise.all([json(`/form-schema-service/v4/forms/${id}/summary`), json(`/form-schema-service/v4/forms/${id}`).catch(() => null)]);
+    return summary ? toFormFields(summary.formSummary, form?.form) : FALLBACK_FIELDS;
+  } catch {
+    return FALLBACK_FIELDS;
+  }
+}
+
+/**
+ * Rent: createBooking (the start's resource, the customer's end) → createCart (holds it, carries the
+ * contact and location, the Rentals app id on the line) → calculateCart → hosted checkout (paid) or
+ * placeOrder (free / pay-in-person). Call from the browser. Throws with a friendly message on refusal.
+ */
+export async function rentResource(rental: RentalDetail, start: StartOption, end: EndOption, formValues: Record<string, unknown>, timeZone: string = defaultTimeZone()): Promise<RentalResult> {
+  let created: Raw;
+  try {
+    created = await bookings.createBooking(bookingRequest(rental, start, end.endLocal, timeZone, "_id") as any, bookingOptions(formValues) as any);
+  } catch (e) {
+    throw new Error(friendlyError(e instanceof Error ? e.message : String(e)));
+  }
+  const bookingId = bookingIdOf(created);
+  if (!bookingId) throw new Error("The rental couldn't be booked — the time may have just been taken.");
+
+  const newCart: Raw = await cart.createCart(cartRequest([bookingId], contactOf(created), start.location?.type === "BUSINESS" ? start.location.id : null) as any);
+  const cartId = cartIdOf(newCart);
+  if (!cartId) throw new Error("The rental couldn't be reserved — please try again.");
+
+  const calc: Raw = await cart.calculateCart(cartId);
+  if (checkoutRequired(rental, calc)) {
+    const origin = typeof window !== "undefined" ? window.location.origin : "";
+    const session: Raw = await redirects.createRedirectSession(checkoutRedirectRequest(cartId, origin));
+    const url = session?.redirectSession?.fullUrl;
+    if (!url) throw new Error("Checkout couldn't start — please try again.");
+    return { kind: "redirect", url };
+  }
+  const order: Raw = await cart.placeOrder(cartId);
+  return confirmedResult(bookingId, order);
+}

package/skills/wix-headless-templates/rentals/project/src/wix/rentals/types.ts

@@ -0,0 +1,113 @@
+// Rentals DTOs — the serializable shapes every hook, component, and page consumes. Plain JSON:
+// safe as Astro island props and across server/client boundaries. Images are resolved https URLs;
+// every displayable price is a ready formatted string ("" when the site sent no currency — the
+// surface omits it, never guesses one).
+//
+// A rental is a Wix Bookings service with rentals-specific values (there is no Rentals API of its
+// own): the thing rented is a RESOURCE (a room, a vehicle, a piece of gear), the customer picks the
+// START and the LENGTH, and the price is per unit — per hour or per day.
+
+/** How a rental is measured and priced: one of the two, never both on one rental. */
+export type RentalUnit = "HOUR" | "DAY";
+
+/** Where the rental is handed over. BUSINESS locations have an id; CUSTOM/CUSTOMER don't. */
+export interface RentalLocation {
+  id: string | null;
+  name: string;
+  type: "BUSINESS" | "CUSTOM" | "CUSTOMER";
+}
+
+/** A rental as a listing tile needs it. */
+export interface RentalSummary {
+  id: string;
+  slug: string;
+  name: string;
+  tagLine: string;
+  unit: RentalUnit;
+  /** Display-ready price per unit: "$40" ("" when unknown). */
+  ratePerUnit: string;
+  /** "$40 / hour" or "$40 / day" ("" when unknown). */
+  rateLabel: string;
+  /** The per-unit amount as a number with its currency — for running totals only; never render these. */
+  rateAmount: number;
+  currency: string;
+  /** Shortest and longest length the customer may pick, in the rental's unit (hours may be fractional: 0.5). */
+  minUnits: number;
+  maxUnits: number;
+  /** "1 to 8 hours" / "1 to 5 days" ("" when unknown). */
+  rangeLabel: string;
+  /** Resolved https URL ("" when the rental has no image). */
+  imageUrl: string;
+  /** The resource type the rental books from, and the concrete resources behind it. */
+  resourceTypeId: string | null;
+  resourceCount: number;
+  locations: RentalLocation[];
+  onlineBookingEnabled: boolean;
+  /** The owner approves each rental by hand: the CTA is "Request to rent". */
+  requiresManualApproval: boolean;
+  /** NO_FEE (or a rate of 0): rents without a checkout. */
+  free: boolean;
+}
+
+/** A rental as the booking page needs it. */
+export interface RentalDetail extends RentalSummary {
+  /** Description text as stored. */
+  description: string;
+  /** The booking form id (the Rentals default form on a seeded site; null → the contact-basics fallback). */
+  formId: string | null;
+  /** Derived payment option the booking must send. */
+  paymentOption: "ONLINE" | "OFFLINE";
+  /** True → checkout is always required regardless of price (cancellation-fee policy). */
+  cancellationFeeEnabled: boolean;
+  scheduleId: string | null;
+}
+
+/** A start the customer can pick: a time (hourly) or a day at midnight (daily). */
+export interface StartOption {
+  /** Identity for React keys: start|location. */
+  key: string;
+  /** Local wall-clock "YYYY-MM-DDThh:mm:ss" (no Z) in the response's time zone. */
+  startLocal: string;
+  /** "YYYY-MM-DD" — for grouping and the daily walk. */
+  dayKey: string;
+  /** "9:00 AM" for hourly; "Mon, Oct 5" for daily. */
+  label: string;
+  bookable: boolean;
+  location: RentalLocation | null;
+  /** The resource this start books (from the slot's available resources); null when the server named none. */
+  resource: { id: string; name: string } | null;
+  scheduleId: string | null;
+}
+
+/** A length the customer can pick for the chosen start. */
+export interface EndOption {
+  /** Local wall-clock end; for a daily rental midnight on the day AFTER the last day. */
+  endLocal: string;
+  /** Length in the rental's unit (hours may be fractional). */
+  units: number;
+  /** "2 hours" / "3 days" / "Until Fri, Oct 9". */
+  label: string;
+}
+
+/** The server's price for a chosen start and length. */
+export interface RentalQuote {
+  /** Formatted total ("" when the currency is unknown). */
+  total: string;
+  totalAmount: number;
+  units: number;
+  unit: RentalUnit;
+}
+
+/** A booking-form field (flat; values are keyed by `target`). */
+export interface RentalFormField {
+  target: string;
+  label: string;
+  type: "STRING" | "EMAIL" | "PHONE" | "NUMBER" | "URL";
+  options?: string[];
+  required: boolean;
+}
+
+/** The outcome of rent(): either the browser is being redirected, or it's done. */
+export type RentalResult =
+  | { kind: "redirect"; url: string }
+  | { kind: "confirmed"; bookingId: string; orderId: string | null };

package/skills/wix-headless-templates/rentals/project/src/wix/sdk.ts

@@ -0,0 +1,89 @@
+// The one auth seam for every Wix SDK call in this app. Copy as-is; do not rewrite.
+//
+// Two modes, switched by WIX_CLIENT_ID in ./config:
+//   null (ambient)  — a Wix-managed Astro project: `@wix/astro` authenticates raw SDK module
+//                     calls automatically, server-side AND in client islands. `wixModule()`
+//                     returns the module untouched.
+//   string (manual) — any other React setup (Vite SPA, non-Astro): one shared client is built
+//                     with OAuthStrategy, and `wixModule()` returns the module bound to it.
+//                     The strategy self-manages visitor tokens on every call (mints on first
+//                     use, renews on expiry) and persists them through the storage below.
+//
+// The visitor token IS the identity of the current cart / member session, so in manual mode
+// tokens persist to localStorage — never re-minted per load (a fresh anonymous mint is a NEW
+// visitor and silently empties the cart).
+// docs: https://dev.wix.com/docs/sdk/core-modules/sdk/oauth-strategy.md
+// docs: https://dev.wix.com/docs/go-headless/wix-managed-headless/authentication/about-the-astro-integration.md
+import { createClient, OAuthStrategy, EMPTY_TOKENS } from "@wix/sdk";
+import { fetchWithAuth as ambientFetch } from "@wix/sdk/context";
+import type { IOAuthStrategy, TokenStorage, Tokens } from "@wix/sdk";
+import { WIX_CLIENT_ID } from "./config";
+
+const STORAGE_KEY = `wix-session-${WIX_CLIENT_ID ?? "ambient"}`;
+
+function browserTokenStorage(): TokenStorage {
+  return {
+    getTokens(): Tokens {
+      if (typeof window !== "undefined") {
+        try {
+          const raw = window.localStorage.getItem(STORAGE_KEY);
+          if (raw) return JSON.parse(raw) as Tokens;
+        } catch {
+          /* disabled/corrupt storage — fall through to empty */
+        }
+      }
+      return EMPTY_TOKENS;
+    },
+    setTokens(tokens: Tokens): void {
+      if (typeof window === "undefined") return;
+      try {
+        window.localStorage.setItem(STORAGE_KEY, JSON.stringify(tokens));
+      } catch {
+        /* storage full/disabled — the session just won't survive a reload */
+      }
+    },
+  };
+}
+
+const client = WIX_CLIENT_ID
+  ? createClient({
+      auth: OAuthStrategy({
+        clientId: WIX_CLIENT_ID,
+        tokenStorage: browserTokenStorage(),
+      }),
+    })
+  : null;
+
+/**
+ * Bind an SDK module to this app's auth. Usage (identical in both modes):
+ *   import { productsV3 } from "@wix/stores";
+ *   const products = wixModule(productsV3);
+ *   await products.queryProducts(...)
+ */
+export function wixModule<T>(module: T): T {
+  // The cast bridges the SDK's internal Descriptors constraint; the in/out type is identical.
+  return client
+    ? (client.use(module as unknown as Record<string, unknown>) as unknown as T)
+    : module;
+}
+
+/**
+ * An authenticated fetch of a Wix REST endpoint under the SAME auth as the SDK modules (ambient
+ * on managed Astro, the shared client elsewhere) — for the few APIs whose generated SDK module is
+ * too heavy to bundle (the Forms schema module alone is 15 MB: server-side it pushes a Wix
+ * deploy past its size limit, client-side every visitor downloads it). Same visitor identity,
+ * same token, no second mint. `path` is the wixapis.com path; returns the raw Response.
+ */
+export function wixFetch(path: string, init?: RequestInit): Promise<Response> {
+  const url = path.startsWith("http") ? path : `https://www.wixapis.com${path}`;
+  return client ? client.fetchWithAuth(url, init) : ambientFetch(url, init);
+}
+
+/**
+ * The shared data client's manual-mode auth strategy, or null under ambient auth. The
+ * Members vertical deliberately owns a separate explicit client for its custom in-app login;
+ * app code reads that session through the members hooks instead.
+ */
+export function wixAuth(): IOAuthStrategy | null {
+  return client ? client.auth : null;
+}

package/skills/wix-headless-templates/rentals/project/tsconfig.json

@@ -0,0 +1,5 @@
+{
+  "extends": "astro/tsconfigs/strict",
+  "include": [".astro/types.d.ts", "**/*"],
+  "exclude": ["dist"]
+}

package/skills/wix-headless-templates/rentals/rest/rentals.ts

@@ -0,0 +1,153 @@
+// Rentals over REST — the twin of app/wix/rentals/rentals.ts. Same exports, same DTOs; every body
+// comes from rentals-core (the SAME file the SDK transport uses, deployed flat next to this one), so
+// this file is only the transport: literal paths, one fetch per step, all with the visitor token
+// (see ./client). Failures are loud where a visitor acts (renting) and silent-with-a-default where
+// they only inform (form, preview).
+// docs: https://dev.wix.com/docs/api-reference/business-solutions/bookings/services/services-v2/query-services.md
+// docs: https://dev.wix.com/docs/api-reference/business-solutions/bookings/time-slots/time-slots-v2/list-availability-time-slots.md
+// docs: https://dev.wix.com/docs/api-reference/business-solutions/bookings/time-slots/time-slots-v2/list-availability-time-slot-end-options.md
+// docs: https://dev.wix.com/docs/api-reference/business-solutions/bookings/pricing/pricing-api/preview-price.md
+// docs: https://dev.wix.com/docs/api-reference/business-solutions/bookings/bookings/bookings-writer-v2/create-booking.md
+// docs: https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/purchase-flow/cart-v2/create-cart.md
+// docs: https://dev.wix.com/docs/api-reference/business-management/headless/redirects/create-redirect-session.md
+import { wixRequest } from "./client.js";
+import { imgSrc } from "./media.js";
+import {
+  FALLBACK_FIELDS,
+  RENTALS_APP_ID,
+  RENTALS_FORM_ID,
+  RENTALS_PAGE_SIZE,
+  bookingIdOf,
+  bookingOptions,
+  bookingRequest,
+  cartIdOf,
+  cartRequest,
+  checkoutRedirectRequest,
+  checkoutRequired,
+  confirmedResult,
+  contactOf,
+  dailyEndOptions,
+  defaultTimeZone,
+  endOptionsRequest,
+  friendlyError,
+  isRental,
+  nextSlotsCursor,
+  previewRequest,
+  startsRequest,
+  toDetail,
+  toFormFields,
+  toHourlyEndOptions,
+  toQuote,
+  toStartOptions,
+  toSummary,
+  type Raw,
+  type StartWindow,
+} from "./rentals-core.js";
+import type { EndOption, RentalDetail, RentalFormField, RentalQuote, RentalResult, RentalSummary, StartOption } from "./types.js";
+
+export { RENTALS_APP_ID, RENTALS_FORM_ID, RENTALS_PAGE_SIZE, dailyEndOptions, defaultTimeZone };
+
+export interface RentalsPage {
+  items: RentalSummary[];
+  hasMore: boolean;
+}
+
+/**
+ * POST /bookings/v2/services/query  { query: { filter: { appId, hidden: false }, paging: { limit, offset } } }
+ */
+export async function fetchRentals({ limit = RENTALS_PAGE_SIZE, offset = 0 }: { limit?: number; offset?: number } = {}): Promise<RentalsPage> {
+  const res = await wixRequest<Raw>("/bookings/v2/services/query", { body: { query: { filter: { appId: RENTALS_APP_ID, hidden: false }, paging: { limit, offset } } } });
+  const items = ((res.services ?? []) as Raw[]).filter(isRental).map((r) => toSummary(r, imgSrc));
+  const total = Number(res.pagingMetadata?.total ?? 0);
+  return { items, hasMore: total ? offset + (res.services?.length ?? 0) < total : false };
+}
+
+/** POST /bookings/v2/services/query  filtered on mainSlug.name — null when not found or not a rental. */
+export async function fetchRentalBySlug(slug: string): Promise<RentalDetail | null> {
+  const res = await wixRequest<Raw>("/bookings/v2/services/query", { body: { query: { filter: { "mainSlug.name": slug, appId: RENTALS_APP_ID, hidden: false }, paging: { limit: 1 } } } });
+  const raw = (res.services ?? [])[0] as Raw | undefined;
+  return raw && isRental(raw) ? toDetail(raw, imgSrc) : null;
+}
+
+export interface StartsPage {
+  options: StartOption[];
+  timeZone: string | null;
+}
+
+/** POST /service-availability/v2/time-slots  (cursor followed) — the starts a customer can pick. */
+export async function fetchStarts(rental: Pick<RentalDetail, "id" | "unit" | "resourceTypeId">, window: StartWindow = {}): Promise<StartsPage> {
+  const raws: Raw[] = [];
+  let timeZone: string | null = null;
+  let cursor: string | undefined;
+  do {
+    const res = await wixRequest<Raw>("/service-availability/v2/time-slots", { body: startsRequest(rental, { ...window, cursor }) });
+    raws.push(...((res.timeSlots ?? []) as Raw[]));
+    timeZone ??= res.timeZone ?? null;
+    cursor = nextSlotsCursor(res) ?? undefined;
+  } while (cursor);
+  return { options: toStartOptions(raws, rental.unit), timeZone };
+}
+
+/**
+ * HOURLY: POST /service-availability/v2/time-slots/end-options  { serviceId, localStartDate, timeZone, location }
+ * (the response field is `endOptions`). DAILY: walked locally from the starts already fetched.
+ */
+export async function fetchEndOptions(rental: Pick<RentalDetail, "id" | "unit" | "minUnits" | "maxUnits">, start: StartOption, { timeZone, availableDayKeys = [] }: { timeZone?: string | null; availableDayKeys?: string[] } = {}): Promise<EndOption[]> {
+  if (rental.unit === "DAY") return dailyEndOptions(start, availableDayKeys, rental);
+  const res = await wixRequest<Raw>("/service-availability/v2/time-slots/end-options", { body: { serviceId: rental.id, ...endOptionsRequest(start, timeZone, "id") } });
+  return toHourlyEndOptions(res, start);
+}
+
+/** POST /bookings/v2/pricing/preview  { bookingLineItems: [...] } — falls back to rate × length. */
+export async function fetchQuote(rental: Pick<RentalDetail, "id" | "rateAmount" | "currency" | "unit">, start: StartOption, end: EndOption, timeZone: string = defaultTimeZone()): Promise<RentalQuote> {
+  try {
+    const res = await wixRequest<Raw>("/bookings/v2/pricing/preview", { body: { bookingLineItems: previewRequest(rental, start, end.endLocal, timeZone) } });
+    return toQuote(res, rental, end.units);
+  } catch {
+    return toQuote(null, rental, end.units);
+  }
+}
+
+/** GET /form-schema-service/v4/forms/{id}/summary (+ the schema for `required`); contact basics when unreadable. */
+export async function fetchRentalForm(formId: string | null): Promise<RentalFormField[]> {
+  const id = encodeURIComponent(formId ?? RENTALS_FORM_ID);
+  try {
+    const [summary, form] = await Promise.all([
+      wixRequest<Raw>(`/form-schema-service/v4/forms/${id}/summary`, { method: "GET" }),
+      wixRequest<Raw>(`/form-schema-service/v4/forms/${id}`, { method: "GET" }).catch(() => null),
+    ]);
+    return toFormFields(summary?.formSummary, form?.form);
+  } catch {
+    return FALLBACK_FIELDS;
+  }
+}
+
+/**
+ * POST /bookings/v2/bookings → POST /ecom/v2/carts → POST /ecom/v2/carts/{id}/calculate →
+ * POST /headless/v1/redirect-session (paid) | POST /ecom/v2/carts/{id}/place-order (free / offline).
+ */
+export async function rentResource(rental: RentalDetail, start: StartOption, end: EndOption, formValues: Record<string, unknown>, timeZone: string = defaultTimeZone()): Promise<RentalResult> {
+  let created: Raw;
+  try {
+    created = await wixRequest<Raw>("/bookings/v2/bookings", { body: { booking: bookingRequest(rental, start, end.endLocal, timeZone, "id"), ...bookingOptions(formValues) } });
+  } catch (e) {
+    throw new Error(friendlyError(e instanceof Error ? e.message : String(e)));
+  }
+  const bookingId = bookingIdOf(created);
+  if (!bookingId) throw new Error("The rental couldn't be booked — the time may have just been taken.");
+
+  const newCart = await wixRequest<Raw>("/ecom/v2/carts", { body: cartRequest([bookingId], contactOf(created), start.location?.type === "BUSINESS" ? start.location.id : null) });
+  const cartId = cartIdOf(newCart);
+  if (!cartId) throw new Error("The rental couldn't be reserved — please try again.");
+
+  const calc = await wixRequest<Raw>(`/ecom/v2/carts/${cartId}/calculate`, { body: {} });
+  if (checkoutRequired(rental, calc)) {
+    const origin = typeof window !== "undefined" ? window.location.origin : "";
+    const session = await wixRequest<Raw>("/headless/v1/redirect-session", { body: checkoutRedirectRequest(cartId, origin) });
+    const url = session?.redirectSession?.fullUrl;
+    if (!url) throw new Error("Checkout couldn't start — please try again.");
+    return { kind: "redirect", url };
+  }
+  const order = await wixRequest<Raw>(`/ecom/v2/carts/${cartId}/place-order`, { body: {} });
+  return confirmedResult(bookingId, order);
+}

package/skills/wix-headless-templates/rentals/seed/SEED.md

@@ -0,0 +1,95 @@
+# Rentals — seeding
+
+Seed by **running `seed-rentals.mjs` with a plan file** — don't hand-write the REST calls. The
+script mints its own site token via the Wix CLI (logged-in session + `wix.config.json` required),
+installs the Wix Rentals app and the Wix Bookings app if needed (Bookings is the availability engine;
+without it an hourly rental with several units answers no availability), creates the resource types
+and their resources, then the
+rental services one at a time with every value that makes a Bookings service a rental, confirms the
+duration range landed, and attaches images.
+
+```bash
+# from the project root (where wix.config.json lives):
+node <SKILL_ROOT>/templates/rentals/seed/seed-rentals.mjs plan.json
+```
+
+`plan.json` is plain data — write it from the brief. **Default to 3–4 rentals** across one or two
+resource types (the seed shows the shape; the owner adds the rest in the dashboard) and make them
+exercise the UI: one hourly and one daily rental when the business allows it, a free or
+approval-gated one where it fits, and an image per rental — the default is an `imagePrompt`
+(AI-generated, ~1 Wix AI credit per image, account-billed): brand-contextual — subject,
+aesthetic/mood, palette, lighting — always ending "no text, no watermarks". At least one image shows
+the real thing being rented. For an asset the user actually supplied use `imagePath` (a file on this
+machine — uploaded to Wix Media) or `imageUrl` (their own hosted URL; verify it with `curl -sI` →
+200) — never a stock-photo or guessed URL. Images resolve in parallel and never block the seed.
+
+```json
+{
+  "resourceTypes": [
+    { "name": "Kayaks", "resources": ["Kayak 1", "Kayak 2", "Kayak 3"] },
+    { "name": "Cabins", "resources": ["Lakeside cabin"] }
+  ],
+  "rentals": [
+    { "name": "Single kayak", "tagLine": "Paddle the bay at your pace", "description": "…",
+      "unit": "HOUR", "rate": 25, "min": 1, "max": 6, "resourceType": "Kayaks", "imagePrompt": "…" },
+    { "name": "Lakeside cabin", "description": "…",
+      "unit": "DAY", "rate": 180, "min": 2, "max": 7, "resourceType": "Cabins", "imagePrompt": "…" },
+    { "name": "Life jacket", "description": "…", "unit": "HOUR", "free": true, "max": 8,
+      "resourceType": "Kayaks", "resources": ["Kayak 1"], "imagePrompt": "…" }
+  ]
+}
+```
+
+- `resourceTypes` — the kinds of things rented (`name`, max 40 characters, unique per site) and
+  the individual units in each (`resources`, by name). Two resources in a type mean two customers
+  can rent in parallel. Resources are created **without working hours**: bookable around the
+  clock, which keeps a multi-day rental to one booking. Opening hours are dashboard work — say so.
+- `rentals` — one entry per rental service. `resourceType` names the type it rents from (every
+  resource of that type unless `resources` narrows it). **The rate lives on the service**, so
+  resources that rent at different prices are separate rentals sharing a type.
+  - `unit` — `HOUR` or `DAY`, never both on one rental (a room by the hour AND by the day is two
+    rentals). `min`/`max` are in that unit: hours from 0.5 to 24 (default 1 to 8), days from 1 to 8
+    (default 1 to 5).
+  - `rate` — a number per unit (per hour or per day); Wix multiplies it out at booking time. Omit
+    it or set `free: true` for a no-fee rental (rents without a checkout, paid in person).
+  - `requireManualApproval: true` — rentals are requests the owner approves (the CTA reads
+    "Request to rent").
+- `currency` — 3-letter ISO code at the top of the plan, set **only when the brief names one**: a
+  sentence about currency, or a price written with its unit ("9 dollars", "$9", "€20"). Do **not**
+  infer it from a language, a country, or an address. The seed sets the site to it before creating
+  anything, because rates are stored in the site currency at create time; a new site starts in the
+  currency of the account that created it, not the business's.
+
+The result carries `durationRangeConfirmed` (the first rental re-read; `"HOUR"`/`"DAY"` means the
+range landed, `null` means it was dropped and the rental would book as a fixed slot — stop and
+read the create-service reference), the created rentals with their slugs, the resource types with
+their resources, `preexisting[]` (rentals the site already listed, see below), `errors` per rental,
+and `dashboardUrl`.
+
+**Seeding is additive — the seed never deletes or overwrites anything on the site, and neither do
+you.** There is no cleanup flag and no cleanup step. The Rentals install adds its own sample rental
+to a new site ("Conference room", $45 an hour, 1 to 8 hours), and the live listing shows it next to
+the owner's rentals, so it is never silent: the result's `preexisting[]` names every rental the run
+did not create and the plan did not name (`{ id, name, slug }`), and the closing message says so
+with the Rentals dashboard link (`dashboardUrl` in the result) so the owner removes it there if they
+want to. Resource types and resources are idempotent by name — a re-run reuses "Kayaks" instead of
+creating a second one.
+
+## Supplied content
+
+The general rules are in `templates/shared/SUPPLIED-CONTENT.md`. For rentals, each thing the user
+rents out is one entry. Its name becomes `name`; "per hour"/"per day" (or a price written that way)
+becomes `unit` and `rate`; a stated shortest or longest rental becomes `min`/`max`; the number of
+units they own becomes that type's `resources` (named "Kayak 1", "Kayak 2" when the user gives no
+names); a group name ("boats", "rooms") becomes the `resourceType`. Their photo becomes `imageUrl`.
+A rental with no unit is a question for the user.
+
+## Escape hatch — individual functions
+`setupRentals` composes exported steps — `installRentalsApp`, `createResourceTypes`,
+`createResources`, `buildRental`, `createRental`, `confirmDurationRange`, `readRentals`, `importImage`,
+`attachRentalImage`, plus `makeCtx()` — import them only for a partial re-seed.
+
+## Reference
+Unexpected shape or an uncovered operation → read the live Wix API reference; every call the script
+makes carries a `docs:` line with its reference page. The Rentals model itself is four pages under
+`https://dev.wix.com/docs/api-reference/business-solutions/rentals/`.