@wix/agent-skills 1.26.0 → 1.27.0

package/skills/wix-headless-templates/bookings/app/wix/bookings/types.ts

@@ -0,0 +1,236 @@
+// Bookings DTOs — the serializable shapes every hook, component, and page consumes.
+// Plain JSON: safe as Astro island props or 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).
+
+/** The three Wix Bookings service types. Anything else never becomes a DTO. */
+export type ServiceType = "APPOINTMENT" | "CLASS" | "COURSE";
+
+/** How the service is priced (Services V2 `payment.rateType`). */
+export type RateType = "FIXED" | "VARIED" | "CUSTOM" | "NO_FEE" | "SUBSCRIPTION";
+
+/** What the one CTA does: book now, send a request the owner approves, or (a full/ended course) only view. */
+export type CtaState = "book" | "requestToBook" | "viewCourse";
+
+export type Weekday = "MONDAY" | "TUESDAY" | "WEDNESDAY" | "THURSDAY" | "FRIDAY" | "SATURDAY" | "SUNDAY";
+
+/** Where a service (or one slot) takes place. BUSINESS locations have an id; CUSTOM/CUSTOMER don't. */
+export interface ServiceLocation {
+  id: string | null;
+  name: string;
+  type: "BUSINESS" | "CUSTOM" | "CUSTOMER";
+}
+
+/** A staff member as the service lists them; `id` is the resource GUID used for filtering and booking. */
+export interface StaffSummary {
+  id: string;
+  name: string;
+  /** Resolved https URL ("" when the staff member has no photo). */
+  imageUrl: string;
+}
+
+/** Deposit terms when the service takes one; null otherwise. */
+export interface Deposit {
+  /** Formatted deposit amount ("" when the deposit is a percentage — the server resolves it at booking). */
+  amount: string;
+  /** True when the visitor may choose to pay the full price upfront instead. */
+  fullUpfrontAllowed: boolean;
+}
+
+/** A service as a listing/grid tile needs it. */
+export interface ServiceSummary {
+  id: string;
+  slug: string;
+  name: string;
+  tagLine: string;
+  type: ServiceType;
+  rateType: RateType;
+  /**
+   * Display-ready price: FIXED → "€75"; VARIED → the lowest price (render "From €30", see `priceFrom`);
+   * CUSTOM → the owner's text ("Ask for a quote"); NO_FEE → "Free"; "" when nothing can be shown.
+   */
+  price: string;
+  /** True for VARIED pricing — `price` is the minimum, prefix it ("From €30"). */
+  priceFrom: boolean;
+  /** The pre-discount price when a discount applies to a FIXED price ("" otherwise) — render struck through. */
+  basePrice: string;
+  /** The discount's name when one applies ("" otherwise). */
+  discountName: string;
+  /** True when a discount applies but the amount is only known at checkout (VARIED, add-ons). */
+  calculatedAtCheckout: boolean;
+  /** True when the service can be paid with a pricing plan / membership. */
+  hasPricingPlans: boolean;
+  /** NO_FEE (or a FIXED price of 0): books without a checkout. */
+  free: boolean;
+  /** Session length in minutes (appointments; classes and courses may have none). */
+  durationMinutes: number | null;
+  /** "1 hr 30 min" / "45 min" ("" when unknown). */
+  durationLabel: string;
+  /** Resolved https URL ("" when the service has no image). */
+  imageUrl: string;
+  categoryId: string | null;
+  categoryName: string;
+  /** The service's schedule id — classes/courses hang their sessions on it; a COURSE books this whole schedule. */
+  scheduleId: string | null;
+  staff: StaffSummary[];
+  locations: ServiceLocation[];
+  /** Sessions carry a video-conference link. */
+  conferencing: boolean;
+  /** The service offers add-ons (next-availability is not shown for these; the add-ons load on the booking page). */
+  hasAddOns: boolean;
+  /** The owner approves each booking by hand: the CTA is "Request to book", and success is a sent request. */
+  requiresManualApproval: boolean;
+  onlineBookingEnabled: boolean;
+  /** Late/after-start booking policy already forbids booking (courses: the course started or ended). */
+  tooLateToBook: boolean;
+  /** CTA state from the policy alone; a course's fullness is folded in by the booking flow (`ctaState` there). */
+  ctaState: CtaState;
+  /** Seats per session (classes/courses) — 1 for appointments; null when unknown. */
+  defaultCapacity: number | null;
+  /** Policy cap on participants per booking; null when the policy sets none. */
+  maxParticipantsPerBooking: number | null;
+  deposit: Deposit | null;
+  /** Weekly days a class/course meets (from its recurring sessions) — filled by the listing store, [] until then. */
+  offeredDays: Weekday[];
+}
+
+/** The fixed span of a COURSE (its sessions' first start and last end). */
+export interface CourseSpan {
+  /** ISO instants; null when the course has no sessions yet. */
+  startDate: string | null;
+  endDate: string | null;
+  /** True once the last session is over (or none exists) — the course can't be booked. */
+  ended: boolean;
+}
+
+/** A service as the booking page needs it. */
+export interface ServiceDetail extends ServiceSummary {
+  /** Description HTML/text as stored. */
+  description: string;
+  /** The @wix/forms booking-form id (null → the contact-basics fallback form). */
+  formId: string | null;
+  /** Derived payment option the booking must send ("ONLINE" | "OFFLINE"). */
+  paymentOption: "ONLINE" | "OFFLINE";
+  /** True → checkout is always required regardless of price (cancellation-fee policy). */
+  cancellationFeeEnabled: boolean;
+  /** COURSE only; null for appointments and classes. */
+  course: CourseSpan | null;
+}
+
+export interface BookingCategory {
+  id: string;
+  name: string;
+}
+
+/** A business location that hosts at least one bookable service (a listing filter option). */
+export interface LocationOption {
+  id: string;
+  name: string;
+}
+
+/** Bookings settings the visitor-facing surfaces need. */
+export interface BookingsSettings {
+  /** Which zone times are shown in by default: the business's (the Wix default) or the visitor's. */
+  displayTimeZone: "BUSINESS" | "CUSTOMER";
+  /** The owner lets visitors switch between the two. */
+  customerCanChange: boolean;
+}
+
+/** One time slot, appointment or class session. */
+export interface Slot {
+  /** Identity: start|end|location — two staff at the same time are ONE slot; React keys go here. */
+  key: string;
+  /** Local wall-clock strings "YYYY-MM-DDThh:mm:ss" (no Z) in the response's `timeZone`. */
+  startLocal: string;
+  endLocal: string;
+  /** "YYYY-MM-DD" — for grouping slots by day. */
+  dayKey: string;
+  /** Display label, e.g. "9:00 AM". */
+  label: string;
+  /** False for a full class session or a policy-blocked time — render disabled ("Full"). */
+  bookable: boolean;
+  /** Seats: total and left (classes); null for appointments. */
+  totalCapacity: number | null;
+  remainingCapacity: number | null;
+  /** Waitlist seats left when the class has a waitlist and the session is full; null otherwise. */
+  waitlistCapacity: number | null;
+  /** APPOINTMENT slots carry their own scheduleId; CLASS slots carry an eventId (+ title) instead. */
+  scheduleId: string | null;
+  eventId: string | null;
+  eventTitle: string;
+  location: ServiceLocation | null;
+  /** Staff able to take this slot (may be empty — ANY_RESOURCE still books). */
+  staff: { id: string; name: string }[];
+}
+
+/** A window of slots plus the IANA zone their local times are expressed in. */
+export interface SlotsPage {
+  slots: Slot[];
+  /** The zone the server computed in — the one requested, or the business zone when none was sent. */
+  timeZone: string | null;
+}
+
+/** One upcoming session of a class or course (informational — booking goes through a Slot / the course). */
+export interface Session {
+  id: string;
+  title: string;
+  startLocal: string;
+  endLocal: string;
+  dayKey: string;
+  /** "Mon, Sep 7 · 9:00 AM" style label pieces: the day and the start time. */
+  dayLabel: string;
+  label: string;
+  durationMinutes: number;
+  staff: { id: string; name: string }[];
+  totalCapacity: number | null;
+  spotsLeft: number | null;
+  isFullyBooked: boolean;
+  isCancelled: boolean;
+}
+
+/** Seats on a COURSE, from its recurring sessions; null once the course has ended or has no sessions. */
+export interface CourseAvailability {
+  totalCapacity: number | null;
+  spotsLeft: number | null;
+  full: boolean;
+}
+
+/** An optional extra the visitor can add to a booking. */
+export interface AddOn {
+  id: string;
+  name: string;
+  /** Formatted price ("" when the add-on is free or the currency is unknown). */
+  price: string;
+  /** The same amount as a number (0 when none) with its currency — for totals; never render these. */
+  priceAmount: number;
+  currency: string;
+  /** Extra minutes the add-on adds to the session; null for quantity-based add-ons. */
+  durationMinutes: number | null;
+  /** Max units of this add-on per booking; null when it is a one-off (0/1). */
+  maxQuantity: number | null;
+}
+
+export interface AddOnGroup {
+  id: string;
+  name: string;
+  /** The owner's question for this group ("Add a scalp massage?"). */
+  prompt: string;
+  /** Max distinct add-ons the visitor may pick from this group; null = unlimited. */
+  maxSelectable: number | null;
+  addOns: AddOn[];
+}
+
+/** A booking-form field (flat, from the form summary + schema; values are keyed by `target`). */
+export interface BookingFormField {
+  target: string;
+  label: string;
+  type: "STRING" | "EMAIL" | "PHONE" | "NUMBER" | "URL";
+  options?: string[];
+  /** The form marks it required — the only fields that gate `canBook`; the rest may stay empty. */
+  required: boolean;
+}
+
+/** The outcome of book(): either the browser is being redirected, or it's done. */
+export type BookingResult =
+  | { kind: "redirect"; url: string }
+  | { kind: "confirmed"; bookingId: string; orderId: string | null };

package/skills/wix-headless-templates/bookings/app-astro/layouts/SiteLayout.astro

@@ -0,0 +1,40 @@
+---
+// The site chrome for every bookings 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 the storefront 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="/services" class="text-foreground no-underline transition-colors hover:text-muted-foreground">Services</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/bookings/app-astro/pages/services/[slug].astro

@@ -0,0 +1,81 @@
+---
+// Service 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.
+// Keep all three SEO pieces and this frontmatter; swap the island import to YOUR booking
+// component. The booking island is client:only — availability is timezone/session-specific.
+import SiteLayout from "../../layouts/SiteLayout.astro";
+import ServiceBookingView from "../../components/bookings/ServiceBookingView";
+import { fetchServiceBySlug } from "../../wix/bookings/services";
+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 service = null;
+let seoTagsServiceConfig = null;
+try {
+  [service, seoTagsServiceConfig] = await Promise.all([
+    fetchServiceBySlug(slug),
+    loadSEOTagsServiceConfig({
+      pageUrl,
+      itemType: seoTags.ItemType.BOOKINGS_SERVICE,
+      itemData: { slug },
+    }).catch(() => null),
+  ]);
+} catch {
+  // Guarded: an unhandled SSR throw truncates the response mid-stream.
+}
+
+if (!service) {
+  return new Response(null, { status: 404 });
+}
+---
+
+<SiteLayout title={service.name}>
+  <SEO.Tags seoTagsServiceConfig={seoTagsServiceConfig} slot="seo-tags" />
+
+  <div class="grid gap-10 md:grid-cols-2">
+    <div>
+      {service.imageUrl && (
+        <div class="aspect-[4/3] overflow-hidden rounded-xl bg-secondary">
+          <img src={service.imageUrl} alt={service.name} class="h-full w-full object-cover" />
+        </div>
+      )}
+      <h1 class="mt-5 text-2xl font-semibold tracking-tight">{service.name}</h1>
+      {service.tagLine && <p class="mt-1 text-muted-foreground">{service.tagLine}</p>}
+      <p class="mt-2 text-sm text-muted-foreground">
+        {service.durationLabel ? `${service.durationLabel} · ` : ""}
+        {service.price && <span class="text-foreground">{service.priceFrom ? "From " : ""}{service.price}</span>}
+        {service.basePrice && <s class="ml-1">{service.basePrice}</s>}
+        {service.discountName && <span class="ml-1 text-xs">{service.discountName}</span>}
+      </p>
+      {service.locations.some((l) => l.name) && (
+        <p class="mt-1 text-sm text-muted-foreground">{service.locations.map((l) => l.name).filter(Boolean).join(" · ")}</p>
+      )}
+      {service.description && <p class="mt-4 text-sm leading-relaxed text-muted-foreground">{service.description}</p>}
+    </div>
+    <div>
+      <ServiceBookingView client:only="react" service={service} />
+    </div>
+  </div>
+</SiteLayout>

package/skills/wix-headless-templates/bookings/app-astro/pages/services.astro

@@ -0,0 +1,40 @@
+---
+// Services listing — the first page fetched SERVER-SIDE (SEO) with the URL's filter (`?category=`,
+// `?location=`) and handed to the island as DTO props; the island pages and re-filters from there.
+// Keep this frontmatter; swap the island import to YOUR listing component.
+import SiteLayout from "../layouts/SiteLayout.astro";
+import ServicesView from "../components/bookings/ServicesView";
+import { fetchServices, fetchBookingCategories, fetchLocations } from "../wix/bookings/services";
+import type { BookingCategory, LocationOption, ServiceSummary } from "../wix/bookings/types";
+
+const categoryId = Astro.url.searchParams.get("category") || null;
+const locationId = Astro.url.searchParams.get("location") || null;
+
+let services: ServiceSummary[] = [];
+let hasMore = false;
+let categories: BookingCategory[] = [];
+let locations: { locations: LocationOption[]; hasOtherLocations: boolean } = { locations: [], hasOtherLocations: false };
+try {
+  const [page, cats, locs] = await Promise.all([fetchServices({ categoryId, locationId }), fetchBookingCategories(), fetchLocations()]);
+  services = page.items;
+  hasMore = page.hasMore;
+  categories = cats;
+  locations = locs;
+} catch {
+  // An unguarded SSR throw truncates the response mid-stream; the island renders the
+  // empty state instead.
+}
+---
+
+<SiteLayout title="Services">
+  <h1 class="mb-8 text-2xl font-semibold tracking-tight">Services</h1>
+  <ServicesView
+    client:load
+    initialServices={services}
+    initialHasMore={hasMore}
+    initialCategories={categories}
+    initialLocations={locations}
+    initialCategoryId={categoryId}
+    initialLocationId={locationId}
+  />
+</SiteLayout>

package/skills/wix-headless-templates/bookings/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/bookings/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",
+});