@wix/agent-skills 1.26.0 → 1.27.0

package/skills/wix-headless-templates/rentals/app/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/app/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/app-astro/layouts/SiteLayout.astro

@@ -0,0 +1,40 @@
+---
+// The site chrome for every rentals page — THIS file (header/footer/nav) plus the @theme
+// token block in src/styles/global.css are what you brand. Keep the <slot name="seo-tags" />
+// in <head> and the global.css import. (If another vertical is also deployed, its SiteLayout
+// won; merge nav links there instead.)
+import "../styles/global.css";
+
+interface Props {
+  title: string;
+  description?: string;
+}
+const { title, description } = Astro.props;
+---
+
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>{title}</title>
+    {description && <meta name="description" content={description} />}
+    <slot name="seo-tags" />
+  </head>
+  <body>
+    <header class="sticky top-0 z-40 border-b border-border bg-background/80 backdrop-blur">
+      <div class="mx-auto flex h-16 max-w-6xl items-center justify-between px-6">
+        <a href="/" class="text-base font-bold tracking-tight text-foreground no-underline">Brand Name</a>
+        <nav class="flex items-center gap-6 text-sm">
+          <a href="/rentals" class="text-foreground no-underline transition-colors hover:text-muted-foreground">Rentals</a>
+        </nav>
+      </div>
+    </header>
+    <main class="mx-auto max-w-6xl px-6 pb-24 pt-10">
+      <slot />
+    </main>
+    <footer class="border-t border-border px-6 py-10 text-center text-sm text-muted-foreground">
+      © Brand Name
+    </footer>
+  </body>
+</html>

package/skills/wix-headless-templates/rentals/app-astro/pages/rentals/[slug].astro

@@ -0,0 +1,81 @@
+---
+// Rental detail + booking page.
+//
+// This is a Wix ITEM PAGE: the wixMetadata export + <SEO.Tags> below let the site owner edit
+// this page's title/description/OG in the dashboard and register the route in the sitemap. A
+// rental is a Bookings service, so the Bookings service-page metadata applies. Keep all three SEO
+// pieces and this frontmatter; swap the island import to YOUR rental component. The island is
+// client:only — availability is time-zone/session-specific.
+import SiteLayout from "../../layouts/SiteLayout.astro";
+import RentalBookingView from "../../components/rentals/RentalBookingView";
+import { fetchRentalBySlug } from "../../wix/rentals/rentals";
+import { WIX_APPS } from "@wix/essentials";
+import { SEO } from "@wix/seo/components";
+import { loadSEOTagsServiceConfig } from "@wix/seo/services";
+import { seoTags } from "@wix/seo";
+
+export const wixMetadata = {
+  appDefId: WIX_APPS.bookings.id,
+  pageIdentifier: WIX_APPS.bookings.servicePageMetadata.pageIdentifier,
+  identifiers: {
+    slug: WIX_APPS.bookings.servicePageMetadata.identifiers.slug,
+  },
+};
+
+const slug = Astro.params.slug!;
+
+// Behind Wix's proxy the request URL is internal — the real public page URL arrives on
+// x-wix-forwarded-url; the SEO service needs the public one.
+const forwardedUrl = Astro.request.headers.get("x-wix-forwarded-url");
+const pageUrl =
+  forwardedUrl && URL.canParse(forwardedUrl) && /^https?:$/.test(new URL(forwardedUrl).protocol)
+    ? forwardedUrl
+    : Astro.url.href;
+
+let rental = null;
+let seoTagsServiceConfig = null;
+try {
+  [rental, seoTagsServiceConfig] = await Promise.all([
+    fetchRentalBySlug(slug),
+    loadSEOTagsServiceConfig({
+      pageUrl,
+      itemType: seoTags.ItemType.BOOKINGS_SERVICE,
+      itemData: { slug },
+    }).catch(() => null),
+  ]);
+} catch {
+  // Guarded: an unhandled SSR throw truncates the response mid-stream.
+}
+
+if (!rental) {
+  return new Response(null, { status: 404 });
+}
+---
+
+<SiteLayout title={rental.name}>
+  <SEO.Tags seoTagsServiceConfig={seoTagsServiceConfig} slot="seo-tags" />
+
+  <div class="grid gap-10 md:grid-cols-2">
+    <div>
+      {rental.imageUrl && (
+        <div class="aspect-[4/3] overflow-hidden rounded-xl bg-secondary">
+          <img src={rental.imageUrl} alt={rental.name} class="h-full w-full object-cover" />
+        </div>
+      )}
+      <h1 class="mt-5 text-2xl font-semibold tracking-tight">{rental.name}</h1>
+      {rental.tagLine && <p class="mt-1 text-muted-foreground">{rental.tagLine}</p>}
+      <p class="mt-2 text-sm text-muted-foreground">
+        {rental.rateLabel && <span class="text-foreground">{rental.rateLabel}</span>}
+        {rental.rateLabel && rental.rangeLabel ? " · " : ""}
+        {rental.rangeLabel}
+      </p>
+      {rental.locations.some((l) => l.name) && (
+        <p class="mt-1 text-sm text-muted-foreground">{rental.locations.map((l) => l.name).filter(Boolean).join(" · ")}</p>
+      )}
+      {rental.description && <p class="mt-4 text-sm leading-relaxed text-muted-foreground">{rental.description}</p>}
+    </div>
+    <div>
+      <RentalBookingView client:only="react" rental={rental} />
+    </div>
+  </div>
+</SiteLayout>

package/skills/wix-headless-templates/rentals/app-astro/pages/rentals.astro

@@ -0,0 +1,24 @@
+---
+// Rentals listing — the first page fetched SERVER-SIDE (SEO) and handed to the island as DTO
+// props. Keep this frontmatter; swap the island import to YOUR listing component.
+import SiteLayout from "../layouts/SiteLayout.astro";
+import RentalsView from "../components/rentals/RentalsView";
+import { fetchRentals } from "../wix/rentals/rentals";
+import type { RentalSummary } from "../wix/rentals/types";
+
+let rentals: RentalSummary[] = [];
+let hasMore = false;
+try {
+  const page = await fetchRentals();
+  rentals = page.items;
+  hasMore = page.hasMore;
+} catch {
+  // An unguarded SSR throw truncates the response mid-stream; the island renders the
+  // empty state instead.
+}
+---
+
+<SiteLayout title="Rentals">
+  <h1 class="mb-8 text-2xl font-semibold tracking-tight">Rentals</h1>
+  <RentalsView client:load initialRentals={rentals} initialHasMore={hasMore} />
+</SiteLayout>

package/skills/wix-headless-templates/rentals/project/README.md

@@ -0,0 +1,15 @@
+# Wix Astro Blank Template
+
+**[Live demo](https://h6s-1a31f9730cd85b-headlessstack.wix-site-host.com)**
+
+Our Astro templates are still in development and subject to change.
+
+To use a template, follow the [Wix CLI for Headless Quick Start](https://dev.wix.com/docs/go-headless/get-started/quick-starts/wix-managed-headless/quick-start-with-the-wix-cli), and select the desired template during the setup process.
+
+## Need help?
+
+For documentation and support, check out:
+
+- [Wix Headless Documentation](https://dev.wix.com/docs/go-headless)
+- [Wix SDK Documentation](https://dev.wix.com/docs/sdk)
+- [Community on Discord](https://discord.gg/n6TBrSnYTp)

package/skills/wix-headless-templates/rentals/project/astro.config.mjs

@@ -0,0 +1,22 @@
+import tailwindcss from "@tailwindcss/vite";
+// @ts-check
+import { defineConfig } from 'astro/config';
+import wix from "@wix/astro";
+import wixPages from "@wix/astro-pages";
+
+import react from "@astrojs/react";
+import wixHostingAdapter from "@wix/astro-wix-hosting-adapter";
+
+// https://astro.build/config
+export default defineConfig({
+  vite: { plugins: [tailwindcss()] },
+  integrations: [wix(), wixPages(), react()],
+  security: { checkOrigin: false },
+  adapter: wixHostingAdapter(),
+
+  image: {
+    domains: ["static.wixstatic.com"],
+  },
+
+  output: "server",
+});