@wix/agent-skills 1.7.0 → 1.9.0

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

@@ -0,0 +1,136 @@
+import { useState } from "react";
+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 {
+  service: any; // SSR-fetched service — bookingDriver reads payment + bookingPolicy
+  serviceName: string;
+  slot: SelectedSlot;
+  fields: BookingFormField[];
+  onSuccess: (id: string, startDate?: string) => void;
+  onCancel: () => void;
+}
+
+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 set = (target: string, v: string) =>
+    setValues((prev) => ({ ...prev, [target]: v }));
+
+  const when = new Date(slot.localStartDate).toLocaleString([], {
+    weekday: "long", month: "long", day: "numeric", hour: "2-digit", minute: "2-digit",
+  });
+
+  const handleSubmit = async (e: React.FormEvent) => {
+    e.preventDefault();
+    setStatus("submitting"); setError(null);
+    try {
+      const result = await book({
+        service,
+        slot,
+        formSubmission: values, // keyed by each field's `target`
+        timezone: slot.timezone,
+      });
+      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(result.orderId, slot.localStartDate); // free / pay-in-person
+    } catch (err) {
+      console.error("[booking] failed:", err);
+      setError(friendlyError(err));
+      setStatus("idle");
+    }
+  };
+
+  return (
+    <form className="booking-form" onSubmit={handleSubmit}>
+      <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>
+
+      {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>
+      ))}
+
+      {error && <p className="booking-error" role="alert">{error}</p>}
+
+      <button type="submit" className="booking-cta" disabled={status === "submitting"}>
+        {status === "submitting" ? "Booking…" : "Confirm booking"}
+      </button>
+    </form>
+  );
+}

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

@@ -0,0 +1,25 @@
+---
+// SeoTags.astro — renders Wix-resolved SEO tags into <head> for service pages.
+// Pass `service.seoData.tags` (Services V2) — title/meta/link/script — so the
+// service detail page ships Wix's sitemap/SEO/social tags. Mirrors the stores
+// SeoTags template. Mount inside the Layout's `head` slot on `/services/[slug]`.
+interface SeoTag {
+  type?: string;
+  props?: Record<string, any> | null;
+  children?: string;
+  disabled?: boolean;
+}
+interface Props { tags?: SeoTag[]; }
+const { tags = [] } = Astro.props;
+const visibleTags = tags.filter((t) => !t.disabled);
+---
+{
+  visibleTags.map((tag) => {
+    const props = tag.props ?? {};
+    if (tag.type === "title") return <title set:html={tag.children ?? ""} />;
+    if (tag.type === "meta") return <meta {...props} />;
+    if (tag.type === "link") return <link {...props} />;
+    if (tag.type === "script") return <script {...props} is:inline set:html={tag.children ?? ""} />;
+    return null;
+  })
+}

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

@@ -0,0 +1,54 @@
+import { useState } from "react";
+import AvailabilityCalendar 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 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)
+// and the booking-form `fields` (the @wix/forms schema) through to the form.
+//
+// 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 {
+  service: any;
+  serviceName: string;
+  serviceType: "APPOINTMENT" | "CLASS";
+  fields: BookingFormField[];
+}
+
+export default function ServiceBookingFlow({ service, serviceName, serviceType, fields }: Props) {
+  const [selectedSlot, setSelectedSlot] = useState<SelectedSlot | null>(null);
+
+  const handleSuccess = (_orderId: string, startDate?: string) => {
+    const params = new URLSearchParams();
+    if (startDate) params.set("startDate", startDate);
+    if (serviceName) params.set("service", serviceName);
+    window.location.href = `/booking-confirmation?${params.toString()}`;
+  };
+
+  if (!selectedSlot) {
+    return (
+      <AvailabilityCalendar
+        serviceId={service._id}
+        serviceName={serviceName}
+        serviceType={serviceType}
+        onSlotSelected={setSelectedSlot}
+      />
+    );
+  }
+
+  return (
+    <BookingForm
+      service={service}
+      serviceName={serviceName}
+      slot={selectedSlot}
+      fields={fields}
+      onSuccess={handleSuccess}
+      onCancel={() => setSelectedSlot(null)}
+    />
+  );
+}

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

@@ -0,0 +1,45 @@
+---
+// ServiceCard.astro — static card for the services listing grid.
+// Props in, HTML out; no client-side interactivity. Works for APPOINTMENT and
+// CLASS services. Classes (.service-card, .service-card-image,
+// .service-card-meta, .service-card-price, …) are owned by
+// src/styles/components-bookings.css (pre-copied by the orchestrator).
+interface Props {
+  id: string;
+  slug: string;
+  name: string;
+  tagLine?: string;
+  durationMinutes: number;
+  price?: string; // formatted string, e.g. "$75.00" — already formatted by caller
+  currency?: string;
+  imageUrl?: string;
+  type: "APPOINTMENT" | "CLASS";
+}
+
+const { slug, name, tagLine, durationMinutes, price, imageUrl } = Astro.props;
+---
+
+<a href={`/services/${slug}`} class="service-card">
+  {
+    imageUrl ? (
+      <div class="service-card-image">
+        <img src={imageUrl} alt={name} loading="lazy" />
+      </div>
+    ) : (
+      <div
+        class="service-card-image service-card-image--placeholder"
+        aria-hidden="true"
+        style="background-color: var(--color-surface-secondary, var(--color-paper-warm, var(--color-cream)));"
+      />
+    )
+  }
+
+  <div class="service-card-meta">
+    <h3 class="service-card-name">{name}</h3>
+    {tagLine && <p class="service-card-tagline">{tagLine}</p>}
+    <div class="service-card-price">
+      <span>{durationMinutes} min</span>
+      {price && <span>{price}</span>}
+    </div>
+  </div>
+</a>

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

@@ -0,0 +1,49 @@
+---
+// src/pages/booking-confirmation.astro — post-booking confirmation.
+//
+// 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";
+
+const serviceName = Astro.url.searchParams.get("service") ?? "your service";
+const startDateParam = Astro.url.searchParams.get("startDate");
+const formattedDate = startDateParam
+  ? new Date(startDateParam).toLocaleString("en-US", {
+      weekday: "long", month: "long", day: "numeric", hour: "2-digit", minute: "2-digit",
+    })
+  : null;
+---
+
+<!-- `max-w-prose` (built-in literal = 65ch), not a bare max-w-<size> that could
+     collapse to the spacing scale. -->
+<Layout title="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-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">Thank you for booking</h1>
+
+    {
+      formattedDate ? (
+        <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> for{" "}
+          <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">
+          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-accent); color: var(--color-paper);">Browse more services</a>
+      <a href="/" class="text-sm text-mute hover:text-ink">Return home</a>
+    </div>
+  </section>
+</Layout>

package/skills/wix-headless/references/astro/templates/bookings/bookingDriver.ts

@@ -0,0 +1,245 @@
+// bookingDriver.ts — the booking sequence in plain @wix SDK calls.
+// Framework-agnostic: no React, no signals, no UI. Any framework's booking step
+// imports book()/navigateToCheckout() and drives them; APPOINTMENT and CLASS
+// share the same sequence.
+//
+// Mechanism = ecom Cart V2 on every path: createBooking leaves the booking
+// CREATED, then the cart holds the seat — a paid service hands off to the
+// Wix-hosted checkout, a free / pay-in-person service places the order directly.
+//
+// On @wix/astro the SDK calls run ambiently (the visitor client is provided by
+// @wix/essentials, like the ecom CartView island) — no createClient/OAuthStrategy
+// needed. On an own/own-build SPA, acquire a visitor client with
+// createClient({ modules, auth: OAuthStrategy({ clientId }) }) and call the same
+// functions through it. Keep the SDK calls, payload shapes, and the sequence;
+// adapt only brand copy/styling in the UI that drives this module.
+
+import { bookings } from "@wix/bookings";
+import { createCart, calculateCart, placeOrder } from "@wix/auto_sdk_ecom_cart-v-2";
+import { redirects } from "@wix/redirects";
+
+// ── Constants (C:src/services/constants.ts) ────────────────────────────────
+export const BOOKING_APP_ID = "13d21c63-b5ec-5912-8397-c3a5ddb27a97";
+export const STAFF_MEMBER_RESOURCE_TYPE_ID = "1cd44cf8-756f-41c3-bd90-3e2ffcaf1155";
+
+// ── Types ───────────────────────────────────────────────────────────────────
+// FormValues = the submitted booking-form values, keyed by each field's `target`
+// (NOT hardcoded field names). The default booking form's targets are snake_case
+// `first_name`/`last_name`/`email`/`phone`; read them from the form schema and key
+// the values by `target` — never hardcode the keys here.
+export type FormValues = Record<string, unknown>;
+
+export interface SelectedSlot {
+  serviceType: "APPOINTMENT" | "CLASS";
+  serviceId: string;
+  localStartDate: string; // local "YYYY-MM-DDTHH:mm:ss" (NOT UTC) — maps to slot.startDate
+  localEndDate: string; //   "                            " → slot.endDate
+  timezone: string;
+  // APPOINTMENT:
+  scheduleId?: string;
+  locationId?: string; // from slot.location._id  (the id field is `_id`, not `.id`)
+  locationType?: string; // "BUSINESS" | "CUSTOMER" | "CUSTOM"
+  // CLASS:
+  eventId?: string;
+  // Resource chosen on the slot (flow 5). When absent the driver emits the
+  // ANY_RESOURCE fallback so Wix auto-assigns a bookable staff member.
+  resource?: { _id: string; name?: string };
+}
+
+export interface BookParams {
+  service: any; // the @wix/bookings Service (read payment.options + bookingPolicy)
+  slot: SelectedSlot;
+  formSubmission: FormValues; // values from the @wix/forms Form, keyed by target
+  timezone: string;
+  totalParticipants?: number;
+  /** consumer override; when omitted, derived from service.payment.options */
+  selectedPaymentOption?: "ONLINE" | "OFFLINE";
+}
+
+export const BookResultType = {
+  CheckoutRequired: "checkout_required",
+  CheckoutSkipped: "checkout_skipped",
+} as const;
+export type BookResult =
+  | { type: typeof BookResultType.CheckoutRequired; cartId: string }
+  | { type: typeof BookResultType.CheckoutSkipped; orderId: string };
+
+// ── Payment derivation ───────────────────────────────────────────────────────
+function deriveSelectedPaymentOption(service: any): "ONLINE" | "OFFLINE" {
+  const options = service?.payment?.options;
+  if (options?.online && !options?.inPerson) return "ONLINE";
+  if (!options?.online && options?.inPerson) return "OFFLINE";
+  return "ONLINE"; // both / neither → ONLINE (consumer override wins, see below)
+}
+
+// LocationType maps from the availability slot's type → the booking endpoint enum.
+function mapLocationType(slotType?: string): string {
+  switch (slotType) {
+    case "BUSINESS":
+      return "OWNER_BUSINESS";
+    case "CUSTOMER":
+      return "CUSTOM";
+    case "CUSTOM":
+      return "OWNER_CUSTOM";
+    default:
+      return "OWNER_BUSINESS";
+  }
+}
+
+// ── buildBookingRequest ───────────────────────────────────────────────────────
+function buildBookingRequest(params: BookParams) {
+  const { service, slot, formSubmission, timezone } = params;
+  const resource = slot.resource; // prefer the slot's chosen resource when present
+
+  return {
+    booking: {
+      // Consumer override wins over the service-config heuristic.
+      selectedPaymentOption:
+        params.selectedPaymentOption ?? deriveSelectedPaymentOption(service),
+      totalParticipants: params.totalParticipants || 1,
+      bookedEntity: {
+        slot: {
+          serviceId: slot.serviceId,
+          // APPOINTMENT carries scheduleId; CLASS carries eventId (Wix derives the rest).
+          scheduleId: slot.scheduleId ?? undefined,
+          startDate: slot.localStartDate,
+          endDate: slot.localEndDate,
+          timezone,
+          eventId: slot.eventId ?? undefined,
+          // Resource: use the chosen one, else the ANY_RESOURCE fallback so Wix
+          // auto-assigns a bookable staff member. Appointment availability slots
+          // return availableResources:[] yet book fine via ANY_RESOURCE.
+          ...(resource
+            ? { resource: { _id: resource._id, name: resource.name } }
+            : {
+                resourceSelections: [
+                  {
+                    resourceTypeId: STAFF_MEMBER_RESOURCE_TYPE_ID,
+                    selectionMethod: "ANY_RESOURCE",
+                  },
+                ],
+              }),
+          location:
+            slot.locationId || slot.locationType
+              ? {
+                  ...(slot.locationId ? { _id: slot.locationId } : {}),
+                  locationType: mapLocationType(slot.locationType),
+                }
+              : { locationType: "OWNER_BUSINESS" },
+        },
+      },
+    },
+    participantNotification: {
+      metadata: { channels: "EMAIL,SMS" },
+      notifyParticipants: true,
+    },
+    sendSmsReminder: true,
+    formSubmission,
+  };
+}
+
+// ── buildCartRequest ──────────────────────────────────────────────────────────
+function buildCartRequest(args: {
+  bookingIds: string[];
+  contactDetails?: any;
+  businessLocationId?: string | null;
+}) {
+  const cart: any = { source: { channelType: "WEB" } };
+  if (args.businessLocationId)
+    cart.businessInfo = { locationId: args.businessLocationId };
+  if (args.contactDetails) {
+    cart.customerInfo = args.contactDetails.email
+      ? { email: args.contactDetails.email }
+      : {};
+    if (args.contactDetails.fullAddress?.country) {
+      cart.deliveryInfo = { address: { ...args.contactDetails.fullAddress } };
+      cart.paymentInfo = {
+        billingAddress: { ...args.contactDetails.fullAddress },
+      };
+    }
+  }
+  return {
+    catalogItems: args.bookingIds.map((id) => ({
+      quantity: 1,
+      catalogReference: { catalogItemId: id, appId: BOOKING_APP_ID },
+    })),
+    cart,
+  };
+}
+
+// ── isCheckoutRequired ────────────────────────────────────────────────────────
+function isCheckoutRequired(cart: any, summary: any, service: any): boolean {
+  if (service?.bookingPolicy?.cancellationFeePolicy?.enabled) return true;
+  const total = Number(summary?.priceSummary?.total?.amount ?? 0);
+  if (total === 0) return false;
+  if (cart?.lineItems?.[0]?.paymentConfig?.paymentOption === "FULL_PAYMENT_OFFLINE")
+    return false;
+  return true;
+}
+
+// ── canBook ───────────────────────────────────────────────────────────────────
+function canBook(params: BookParams): boolean {
+  const slotOk =
+    !!params.slot &&
+    !!params.slot.localStartDate &&
+    (params.slot.serviceType === "CLASS"
+      ? !!params.slot.eventId
+      : !!params.slot.scheduleId);
+  return slotOk && params.formSubmission != null;
+}
+
+// ── book — the full sequence ──────────────────────────────────────────────────
+export async function book(params: BookParams): Promise<BookResult> {
+  if (!canBook(params))
+    throw new Error("Cannot book: missing slot or form submission");
+
+  // 1. createBooking → CREATED (the cart holds the seat)
+  const req = buildBookingRequest(params);
+  const created = await bookings.createBooking(req.booking as any, {
+    participantNotification: req.participantNotification,
+    sendSmsReminder: req.sendSmsReminder,
+    formSubmission: req.formSubmission as any,
+  });
+  const bookingId = created?.booking?._id;
+  if (!bookingId) throw new Error("Failed to create booking");
+  const contactDetails = created?.booking?.contactDetails;
+
+  // 2. createCart — one catalog item per booking id (channel WEB, bookings appId)
+  const businessLocationId = params.slot.locationId ?? undefined;
+  const cart = await createCart(
+    buildCartRequest({ bookingIds: [bookingId], contactDetails, businessLocationId }),
+  );
+  const cartId = cart?._id;
+  if (!cartId) throw new Error("Failed to create cart");
+
+  // 3. calculateCart → totals (not stored on the Cart V2 entity)
+  const { cart: calculatedCart, summary } = await calculateCart(cartId);
+  if (!calculatedCart || !summary) throw new Error("Failed to calculate cart");
+
+  // 4. checkout required? → redirect (paid) ; else placeOrder (free/offline)
+  if (isCheckoutRequired(calculatedCart, summary, params.service)) {
+    return { type: BookResultType.CheckoutRequired, cartId };
+  }
+  const order = await placeOrder(cartId);
+  const orderId = order?.orderId;
+  if (!orderId) throw new Error("Failed to place order");
+  return { type: BookResultType.CheckoutSkipped, orderId };
+}
+
+// ── navigateToCheckout ────────────────────────────────────────────────────────
+// Paid services: hand the cart to the Wix-hosted ecom checkout. Same shape on
+// every path — ecomCheckout.checkoutId = the cartId.
+export async function navigateToCheckout(
+  cartId: string,
+  postFlowUrl: string,
+): Promise<void> {
+  const { redirectSession } = await redirects.createRedirectSession({
+    ecomCheckout: { checkoutId: cartId },
+    callbacks: { postFlowUrl },
+  });
+  if (redirectSession?.fullUrl) {
+    window.location.href = redirectSession.fullUrl;
+  } else {
+    throw new Error("Failed to create redirect session");
+  }
+}