@wix/agent-skills 1.8.0 → 1.10.0

package/skills/wix-headless/references/astro/templates/bookings/BookingForm.tsx

@@ -1,194 +1,136 @@
 import { useState } from "react";
-import { createClient, OAuthStrategy } from "@wix/sdk";
-import { bookings } from "@wix/bookings";
-import type { SelectedSlot } from "./AvailabilityCalendar";
-import { WIX_CLIENT_ID } from "astro:env/client"; // browser client ID, NOT import.meta.env
-
-// BookingForm.tsx — client:only="react" island. Renders after a slot is picked.
-// Flow: createBooking → CREATED holds NO seat, so POST the booking to
-// the elevated /api/confirm-booking to occupy it (and validate availability).
-// A full CLASS session throws SESSION_CAPACITY_EXCEEDED whose message carries the
-// v1 session id → register on the native waitlist via /api/waitlist.
+import { book, navigateToCheckout, BookResultType } from "./bookingDriver";
+import type { SelectedSlot } from "./bookingDriver";
+
+// BookingForm.tsx — client:only="react" island. Renders the service's booking
+// form SCHEMA (from @wix/forms, fetched server-side and passed in as `fields`),
+// collects the values keyed by each field's `target`, and drives the booking
+// sequence in bookingDriver.book(). This is the same schema-driven renderer the
+// forms vertical uses (references/astro/forms/CONTACT_FORM.md) — generic inputs
+// chosen by `componentType` — so it adapts to whatever fields the booking form
+// defines, rather than hardcoding first/last/email/phone.
+//
+// On submit: book() returns CheckoutRequired (paid → hand off to the Wix-hosted
+// checkout) or CheckoutSkipped (free / pay-in-person → straight to confirmation).
+
+export interface BookingFormField {
+  label: string;
+  target: string; // the key createBooking expects in formSubmission
+  required: boolean;
+  componentType: string; // "TEXT_INPUT" | "DROPDOWN" | "PHONE_INPUT"
+  identifier?: string;
+  options?: { value: string; label: string }[];
+}
 
 interface Props {
-  serviceId: string;
+  service: any; // SSR-fetched service — bookingDriver reads payment + bookingPolicy
   serviceName: string;
-  serviceType: "APPOINTMENT" | "CLASS";
   slot: SelectedSlot;
-  onSuccess: (bookingId: string, startDate: string) => void;
+  fields: BookingFormField[];
+  onSuccess: (id: string, startDate?: string) => void;
   onCancel: () => void;
 }
 
-const wixClient = createClient({
-  modules: { bookings },
-  auth: OAuthStrategy({ clientId: WIX_CLIENT_ID }),
-});
-
-const slotDisplay = (slot: SelectedSlot) =>
-  slot.localStartDate
-    ? new Date(slot.localStartDate).toLocaleString([], {
-        weekday: "long", month: "long", day: "numeric", hour: "2-digit", minute: "2-digit",
-      })
-    : "";
-
-export default function BookingForm({ serviceName, serviceType, slot, onSuccess, onCancel }: Props) {
-  const [firstName, setFirstName] = useState("");
-  const [lastName, setLastName] = useState("");
-  const [email, setEmail] = useState("");
-  const [phone, setPhone] = useState("");
-  const [participants, setParticipants] = useState(1);
-  const [submitting, setSubmitting] = useState(false);
+const friendlyError = (err: any): string => {
+  // Surface field validation (e.g. a malformed phone number) rather than crashing.
+  const violations = err?.details?.validationError?.fieldViolations ?? [];
+  const first = violations[0]?.description ?? violations[0]?.data?.errors?.[0]?.errorMessage;
+  if (first) return first;
+  if (typeof err?.message === "string") return err.message;
+  return "Something went wrong completing your booking. Please try again.";
+};
+
+export default function BookingForm({ service, serviceName, slot, fields, onSuccess, onCancel }: Props) {
+  const [values, setValues] = useState<Record<string, string>>({});
+  const [status, setStatus] = useState<"idle" | "submitting">("idle");
   const [error, setError] = useState<string | null>(null);
-  const [waitlisted, setWaitlisted] = useState(false);
 
-  const isWaitlist = serviceType === "CLASS" && !!slot.isFull;
-  // Party size only applies to CLASS (APPOINTMENT is 1-on-1).
-  const maxParty = serviceType === "CLASS" ? Math.max(1, slot.bookableCapacity ?? slot.remainingCapacity ?? 1) : 1;
-  const partyOptions = Array.from({ length: Math.min(maxParty, 8) }, (_, i) => i + 1);
+  const set = (target: string, v: string) =>
+    setValues((prev) => ({ ...prev, [target]: v }));
 
-  const contactDetails = () => ({
-    firstName: firstName.trim(),
-    lastName: lastName.trim() || undefined,
-    email: email.trim(),
-    phone: phone.trim() || undefined,
+  const when = new Date(slot.localStartDate).toLocaleString([], {
+    weekday: "long", month: "long", day: "numeric", hour: "2-digit", minute: "2-digit",
   });
 
-  const buildSlot = () =>
-    serviceType === "CLASS"
-      // CLASS: serviceId + eventId only — Wix derives the rest from the event.
-      ? { serviceId: slot.serviceId, eventId: slot.eventId }
-      // APPOINTMENT: scheduleId + explicit start/end/timezone/location.
-      : {
-          serviceId: slot.serviceId,
-          scheduleId: slot.scheduleId,
-          startDate: slot.localStartDate,
-          endDate: slot.localEndDate,
-          timezone: slot.timezone,
-          ...(slot.locationId
-            ? { location: { _id: slot.locationId, locationType: slot.locationType as any } }
-            : { location: { locationType: "OWNER_BUSINESS" as const } }),
-        };
-
   const handleSubmit = async (e: React.FormEvent) => {
     e.preventDefault();
-    setError(null);
-    if (!firstName.trim() || !email.trim()) {
-      setError("Please enter your first name and email.");
-      return;
-    }
-    setSubmitting(true);
+    setStatus("submitting"); setError(null);
     try {
-      const result = await wixClient.bookings.createBooking({
-        totalParticipants: participants, // party size
-        contactDetails: contactDetails(),
-        selectedPaymentOption: "OFFLINE" as const,
-        bookedEntity: { slot: buildSlot() },
-      } as any);
-
-      const status = result.booking?.status;
-      const bookingId = result.booking?._id ?? "";
-      const revision = result.booking?.revision ?? "";
-
-      // Defensive: if createBooking ever returns a WAITING_LIST booking directly,
-      // treat it as joined. In practice a full session THROWS
-      // SESSION_CAPACITY_EXCEEDED (handled in catch → /api/waitlist) rather than
-      // returning this status — both paths land the user on the waitlist.
-      if (status === "WAITING_LIST") { setWaitlisted(true); setSubmitting(false); return; }
-
-      // CREATED → confirm server-side to hold the seat.
-      const confirmRes = await fetch("/api/confirm-booking", {
-        method: "POST", headers: { "Content-Type": "application/json" },
-        body: JSON.stringify({ bookingId, revision }),
+      const result = await book({
+        service,
+        slot,
+        formSubmission: values, // keyed by each field's `target`
+        timezone: slot.timezone,
       });
-      const confirmJson = await confirmRes.json().catch(() => ({}));
-      if (!confirmRes.ok || confirmJson.ok === false) {
-        setError("This session just filled up — please pick another time.");
-        setSubmitting(false); onCancel(); return;
+      if (result.type === BookResultType.CheckoutRequired) {
+        // Paid: hand the cart to the Wix-hosted checkout; it returns to /booking-confirmation.
+        // Carry service + start time on the return URL so the confirmation can show them
+        // (the in-memory selection is lost across the full-page redirect to Wix and back).
+        await navigateToCheckout(
+          result.cartId,
+          `${window.location.origin}/booking-confirmation?service=${encodeURIComponent(serviceName)}&startDate=${encodeURIComponent(slot.localStartDate)}`,
+        );
+        return; // redirect in progress
       }
-      onSuccess(bookingId, slot.localStartDate);
-    } catch (err: any) {
-      console.error("[booking] createBooking/confirm failed:", err);
-      // Full CLASS session → native waitlist. The error carries the v1 session id.
-      const full = `${err?.message ?? ""} ${JSON.stringify(err?.details ?? {})} ${String(err)}`;
-      if (/SESSION_CAPACITY_EXCEEDED/i.test(full) || /no available spots/i.test(full)) {
-        const sessionId = full.match(/on session ([^\s"}]+)/)?.[1];
-        if (sessionId) {
-          try {
-            const res = await fetch("/api/waitlist", {
-              method: "POST", headers: { "Content-Type": "application/json" },
-              body: JSON.stringify({ sessionId, totalParticipants: participants, contactDetails: contactDetails() }),
-            });
-            const j = await res.json().catch(() => ({}));
-            if (res.ok && j.ok !== false) { setWaitlisted(true); setSubmitting(false); return; }
-          } catch (e) { console.error("[waitlist] failed:", e); }
-        }
-        setError("This class is full and we couldn't add you to the waitlist — please try again later.");
-        setSubmitting(false); return;
-      }
-      setError("This time slot was just taken. Please select another.");
-      setSubmitting(false); onCancel();
+      onSuccess(result.orderId, slot.localStartDate); // free / pay-in-person
+    } catch (err) {
+      console.error("[booking] failed:", err);
+      setError(friendlyError(err));
+      setStatus("idle");
     }
   };
 
-  if (waitlisted) {
-    return (
-      <div className="booking-form">
-        <div className="booking-form-header">
-          <h3 className="booking-form-title">You're on the waitlist</h3>
-          <p className="booking-form-subtitle">{serviceName} · {slotDisplay(slot)}</p>
-        </div>
-        <p>We'll email <strong>{email.trim()}</strong> if a spot opens up.</p>
-        <button type="button" className="booking-cancel" onClick={onCancel}>← Back to available times</button>
-      </div>
-    );
-  }
-
   return (
     <form className="booking-form" onSubmit={handleSubmit}>
-      <div className="booking-form-header">
-        <h3 className="booking-form-title">{isWaitlist ? "Join the waitlist" : "Reserve your spot"}</h3>
-        <p className="booking-form-subtitle">
-          {serviceName} · {slotDisplay(slot)}{slot.instructorName ? ` · with ${slot.instructorName}` : ""}
-        </p>
-        {isWaitlist && <p className="booking-form-note">This session is full — join the waitlist and we'll notify you if a spot opens.</p>}
+      <div className="booking-form-summary">
+        <strong>{serviceName}</strong>
+        <span>{when}</span>
+        <button type="button" className="booking-form-change" onClick={onCancel}>Choose another time</button>
       </div>
 
-      {error && <p className="booking-error">{error}</p>}
-
-      <div className="booking-field-row">
-        <div className="booking-field">
-          <label className="booking-label booking-label--required" htmlFor="bf-first">First name</label>
-          <input id="bf-first" className="booking-input" type="text" value={firstName} onChange={(e) => setFirstName(e.target.value)} required autoComplete="given-name" />
+      {fields.map((field) => (
+        <div key={field.target} className="booking-field">
+          <label className="booking-label">
+            {field.label}
+            {field.required && <span className="booking-required" aria-hidden="true"> *</span>}
+          </label>
+          {field.componentType === "DROPDOWN" && field.options ? (
+            <select
+              className="booking-input"
+              required={field.required}
+              value={values[field.target] ?? ""}
+              onChange={(e) => set(field.target, e.target.value)}
+            >
+              <option value="">Select an option</option>
+              {field.options.map((o) => (
+                <option key={o.value} value={o.value}>{o.label}</option>
+              ))}
+            </select>
+          ) : field.identifier === "TEXT_AREA" || field.target?.includes("message") ? (
+            <textarea
+              className="booking-input"
+              required={field.required}
+              rows={4}
+              value={values[field.target] ?? ""}
+              onChange={(e) => set(field.target, e.target.value)}
+            />
+          ) : (
+            <input
+              className="booking-input"
+              type={field.target === "email" ? "email" : field.componentType === "PHONE_INPUT" ? "tel" : "text"}
+              required={field.required}
+              value={values[field.target] ?? ""}
+              onChange={(e) => set(field.target, e.target.value)}
+            />
+          )}
         </div>
-        <div className="booking-field">
-          <label className="booking-label" htmlFor="bf-last">Last name</label>
-          <input id="bf-last" className="booking-input" type="text" value={lastName} onChange={(e) => setLastName(e.target.value)} autoComplete="family-name" />
-        </div>
-      </div>
+      ))}
 
-      <div className="booking-field">
-        <label className="booking-label booking-label--required" htmlFor="bf-email">Email</label>
-        <input id="bf-email" className="booking-input" type="email" value={email} onChange={(e) => setEmail(e.target.value)} required autoComplete="email" />
-      </div>
-
-      <div className="booking-field">
-        <label className="booking-label" htmlFor="bf-phone">Phone</label>
-        <input id="bf-phone" className="booking-input" type="tel" value={phone} onChange={(e) => setPhone(e.target.value)} autoComplete="tel" />
-      </div>
-
-      {!isWaitlist && maxParty > 1 && (
-        <div className="booking-field">
-          <label className="booking-label" htmlFor="bf-party">Number of spots</label>
-          <select id="bf-party" className="booking-input" value={participants} onChange={(e) => setParticipants(Number(e.target.value))}>
-            {partyOptions.map((n) => <option key={n} value={n}>{n}</option>)}
-          </select>
-        </div>
-      )}
+      {error && <p className="booking-error" role="alert">{error}</p>}
 
-      <button type="submit" className="booking-submit" disabled={submitting}>
-        {submitting ? (isWaitlist ? "Joining…" : "Confirming…") : isWaitlist ? "Join Waitlist" : "Confirm Booking"}
+      <button type="submit" className="booking-cta" disabled={status === "submitting"}>
+        {status === "submitting" ? "Booking…" : "Confirm booking"}
       </button>
-      <button type="button" className="booking-cancel" onClick={onCancel} disabled={submitting}>← Back to available times</button>
     </form>
   );
 }

package/skills/wix-headless/references/astro/templates/bookings/ServiceBookingFlow.tsx

@@ -1,26 +1,44 @@
 import { useState } from "react";
-import AvailabilityCalendar from "./AvailabilityCalendar";
-import type { SelectedSlot } from "./AvailabilityCalendar";
-import BookingForm from "./BookingForm";
+import AvailabilityCalendar, { type StaffMemberOption, type LocationOption } from "./AvailabilityCalendar";
+import BookingForm, { type BookingFormField } from "./BookingForm";
+import type { SelectedSlot } from "./bookingDriver";
 
 // ServiceBookingFlow.tsx — client:only="react" coordinator island. Holds the
-// selected-slot state shared between AvailabilityCalendar and BookingForm,
-// transitions between them, and redirects to the confirmation page on success.
-// serviceType MUST be threaded through so the calendar picks the right time-slots
-// API and the form builds the right createBooking shape.
+// selected-slot state shared between the calendar and the form, transitions
+// between them, and redirects to the confirmation page on success. The SSR
+// detail page passes the full `service` (the driver reads its payment/policy),
+// the booking-form `fields` (the @wix/forms schema), the service's `staffMembers`
+// (for the optional staff picker), the service's business `locations` + the
+// catalog-chosen `locationId` (so the calendar scopes availability to one
+// location — see AvailabilityCalendar) through to the calendar.
+//
+// This is the framework-agnostic flow shape (a step coordinator + shared
+// selection state). On another framework, the same two steps + shared state can
+// be route-driven instead — see references/bookings/FLOW.md.
 
 interface Props {
-  serviceId: string;
+  service: any;
   serviceName: string;
   serviceType: "APPOINTMENT" | "CLASS";
+  fields: BookingFormField[];
+  staffMembers?: StaffMemberOption[];
+  locations?: LocationOption[];
+  locationId?: string;
 }
 
-export default function ServiceBookingFlow({ serviceId, serviceName, serviceType }: Props) {
+export default function ServiceBookingFlow({
+  service,
+  serviceName,
+  serviceType,
+  fields,
+  staffMembers,
+  locations,
+  locationId,
+}: Props) {
   const [selectedSlot, setSelectedSlot] = useState<SelectedSlot | null>(null);
 
-  const handleSuccess = (bookingId: string, startDate?: string) => {
+  const handleSuccess = (_orderId: string, startDate?: string) => {
     const params = new URLSearchParams();
-    if (bookingId) params.set("bookingId", bookingId);
     if (startDate) params.set("startDate", startDate);
     if (serviceName) params.set("service", serviceName);
     window.location.href = `/booking-confirmation?${params.toString()}`;
@@ -29,9 +47,12 @@ export default function ServiceBookingFlow({ serviceId, serviceName, serviceType
   if (!selectedSlot) {
     return (
       <AvailabilityCalendar
-        serviceId={serviceId}
+        serviceId={service._id}
         serviceName={serviceName}
         serviceType={serviceType}
+        staffMembers={staffMembers}
+        locations={locations}
+        locationId={locationId}
         onSlotSelected={setSelectedSlot}
       />
     );
@@ -39,10 +60,10 @@ export default function ServiceBookingFlow({ serviceId, serviceName, serviceType
 
   return (
     <BookingForm
-      serviceId={serviceId}
+      service={service}
       serviceName={serviceName}
-      serviceType={serviceType}
       slot={selectedSlot}
+      fields={fields}
       onSuccess={handleSuccess}
       onCancel={() => setSelectedSlot(null)}
     />

package/skills/wix-headless/references/astro/templates/bookings/ServiceCard.astro

@@ -14,12 +14,21 @@ interface Props {
   currency?: string;
   imageUrl?: string;
   type: "APPOINTMENT" | "CLASS";
+  locationId?: string; // when a location is selected on the catalog, carry it to the detail page
+  locationType?: string;
 }
 
-const { slug, name, tagLine, durationMinutes, price, imageUrl } = Astro.props;
+const { slug, name, tagLine, durationMinutes, price, imageUrl, locationId, locationType } = Astro.props;
+
+// Carry the selected location into the detail page so availability is scoped to it.
+const q = new URLSearchParams();
+if (locationId) q.set("locationId", locationId);
+if (locationType) q.set("locationType", locationType);
+const qs = q.toString();
+const href = qs ? `/services/${slug}?${qs}` : `/services/${slug}`;
 ---
 
-<a href={`/services/${slug}`} class="service-card">
+<a href={href} class="service-card">
   {
     imageUrl ? (
       <div class="service-card-image">

package/skills/wix-headless/references/astro/templates/bookings/booking-confirmation.astro

@@ -1,50 +1,16 @@
 ---
 // src/pages/booking-confirmation.astro — post-booking confirmation.
 //
-// Shows the actual booking status (so the user can see it was actually
-// confirmed/approved — not just an optimistic "you're booked") and lets them
-// cancel inline. It re-fetches the booking with the anonymous action token: the
-// server elevates (app identity) to mint a per-booking token, then reads it with
-// the no-auth `bookingsGetBookingAnonymously`. Falls back to the redirect params
-// if the lookup fails. Cancel is handled by the same <ManageBooking> island used
-// on /manage-booking.
+// Renders from the redirect query params (service name + start date) that the
+// booking step passes through. The Wix-hosted checkout returns here after a paid
+// booking; a free / pay-in-person booking lands here directly. Do not re-fetch a
+// stranger's booking from this public page — show what the flow passed in.
 import Layout from "../layouts/Layout.astro";
-import ManageBooking from "../components/ManageBooking";
-import { auth } from "@wix/essentials";
-import { bookings } from "@wix/bookings";
 
-const bookingId = Astro.url.searchParams.get("bookingId");
+const serviceName = Astro.url.searchParams.get("service") ?? "your service";
 const startDateParam = Astro.url.searchParams.get("startDate");
-const serviceParam = Astro.url.searchParams.get("service") ?? "your service";
-
-let token: string | null = null;
-let booking: any = null;
-let canCancel = false;
-if (bookingId) {
-  try {
-    const tokenRes = await auth.elevate(bookings.getAnonymousActionToken)(bookingId);
-    token = tokenRes.token ?? null;
-    if (token) {
-      const res = await bookings.bookingsGetBookingAnonymously(token);
-      booking = res.booking ?? null;
-      canCancel = !!res.allowedAnonymousActions?.cancel;
-    }
-  } catch (err) {
-    console.error("[booking-confirmation] status lookup failed:", err);
-  }
-}
-
-const status = (booking?.status as string | undefined) ?? null; // CONFIRMED | PENDING | …
-const isPending = status === "PENDING" || status === "PENDING_APPROVAL";
-const serviceName = booking?.bookedEntity?.title ?? serviceParam;
-const startDate =
-  (booking?.startDate as string | undefined) ??
-  booking?.bookedEntity?.slot?.startDate ??
-  startDateParam ??
-  null;
-const revision = (booking?.revision as string | undefined) ?? "";
-const formattedDate = startDate
-  ? new Date(startDate).toLocaleString("en-US", {
+const formattedDate = startDateParam
+  ? new Date(startDateParam).toLocaleString("en-US", {
       weekday: "long", month: "long", day: "numeric", hour: "2-digit", minute: "2-digit",
     })
   : null;
@@ -52,59 +18,31 @@ const formattedDate = startDate
 
 <!-- `max-w-prose` (built-in literal = 65ch), not a bare max-w-<size> that could
      collapse to the spacing scale. -->
-<Layout title={isPending ? "Booking received" : "Booking confirmed"}>
-  <section class="max-w-prose mx-auto px-lg py-4xl text-center">
-    <div class="w-16 h-16 rounded-full flex items-center justify-center mx-auto mb-xl"
-         style="background-color: var(--color-ink);" aria-hidden="true">
-      <span class="text-2xl" style="color: var(--color-paper);">{isPending ? "⏳" : "✓"}</span>
+<Layout title="Booking confirmed">
+  <section class="max-w-prose mx-auto px-6 py-24 text-center">
+    <div class="w-16 h-16 rounded-full flex items-center justify-center mx-auto mb-8"
+         style="background-color: var(--color-accent);" aria-hidden="true">
+      <span class="text-2xl" style="color: var(--color-paper);">✓</span>
     </div>
-    <hr class="editorial-rule w-16 mx-auto mb-lg" />
-    <h1 class="font-display text-4xl md:text-5xl leading-tight mb-md">
-      {isPending ? "Booking received" : "Thank you for booking"}
-    </h1>
+    <hr class="editorial-rule w-16 mx-auto mb-6" />
+    <h1 class="font-display text-4xl md:text-5xl leading-tight mb-4">Thank you for booking</h1>
 
     {
-      isPending ? (
-        <p class="text-lg text-mute leading-relaxed mb-md">
-          Your request for <strong class="text-ink">{serviceName}</strong>
-          {formattedDate ? <> on <strong class="text-ink">{formattedDate}</strong></> : null} is
-          <strong class="text-ink"> awaiting confirmation</strong>. Return here anytime to check status or cancel below.
-        </p>
-      ) : formattedDate ? (
-        <p class="text-lg text-mute leading-relaxed mb-md">
+      formattedDate ? (
+        <p class="text-lg text-mute leading-relaxed mb-4">
           Your spot in <strong class="text-ink">{serviceName}</strong> is <strong class="text-ink">confirmed</strong> for{" "}
-          <strong class="text-ink">{formattedDate}</strong>.
-        </p>
-      ) : bookingId ? (
-        <p class="text-lg text-mute leading-relaxed mb-md">
-          Your spot in <strong class="text-ink">{serviceName}</strong> is <strong class="text-ink">confirmed</strong>.
+          <strong class="text-ink">{formattedDate}</strong>. We've sent the details to your email.
         </p>
       ) : (
-        <p class="text-lg text-mute leading-relaxed mb-md">Looking to book? Browse our services.</p>
-      )
-    }
-
-    {/* Inline cancel via ManageBooking (same anonymous-token flow as /manage-booking). */}
-    {
-      token && bookingId && (
-        <div class="mb-xl flex flex-col items-center gap-md">
-          <ManageBooking
-            token={token}
-            revision={revision}
-            serviceName={serviceName}
-            startDate={startDate}
-            status={status}
-            canCancel={canCancel}
-            showSummary={false}
-            client:only="react"
-          />
-        </div>
+        <p class="text-lg text-mute leading-relaxed mb-4">
+          Your booking for <strong class="text-ink">{serviceName}</strong> is <strong class="text-ink">confirmed</strong>. We've sent the details to your email.
+        </p>
       )
     }
 
-    <div class="flex flex-col gap-md items-center">
-      <a href="/services" class="inline-block font-display text-base px-xl py-md rounded-sm"
-         style="background-color: var(--color-ink); color: var(--color-paper);">Browse more services</a>
+    <div class="flex flex-col gap-4 items-center">
+      <a href="/services" class="inline-block font-display text-base px-8 py-4 rounded-sm"
+         style="background-color: var(--color-accent); color: var(--color-paper);">Browse more services</a>
       <a href="/" class="text-sm text-mute hover:text-ink">Return home</a>
     </div>
   </section>