@wix/agent-skills 1.19.2 → 1.20.1

package/skills/wix-headless-fast/references/events/app/wix/events/registration-core.ts

@@ -0,0 +1,113 @@
+// Registration rules and DTO mapping — transport-agnostic, imported by both ./registration.ts
+// (SDK) and the REST twin in references/events/rest/registration.ts (fetch). Tier mapping, the
+// reservation line items, the payment gate, the checkout callbacks, and the RSVP body live HERE,
+// once. Raw ticket definitions carry `_id` (SDK) or `id` (REST). Type-only imports so a strip
+// to JS emits none.
+import type { EventDetail, RegistrationResult, TicketTier } from "./types";
+import type { Raw } from "./events-core";
+
+const tierId = (raw: Raw | undefined | null): string => raw?._id ?? raw?.id ?? "";
+
+export function formatTierPrice(price: Raw | undefined): string {
+  const value = price?.amount ?? price?.value;
+  if (value == null || value === "") return "";
+  try {
+    return new Intl.NumberFormat(undefined, { style: "currency", currency: price?.currency || "USD" }).format(Number(value));
+  } catch {
+    return `${value} ${price?.currency ?? ""}`.trim();
+  }
+}
+
+export function toTier(raw: Raw): TicketTier {
+  const free = raw.free === true || Number(raw.price?.amount ?? raw.price?.value ?? 0) === 0;
+  return {
+    id: tierId(raw),
+    name: raw.name ?? "",
+    description: raw.description ?? "",
+    price: free ? "Free" : formatTierPrice(raw.price),
+    free,
+    limitPerCheckout: raw.limitPerCheckout ?? 20,
+    saleStatus: (raw.saleStatus ?? "SALE_STARTED") as TicketTier["saleStatus"],
+  };
+}
+
+/** Tiers in display order (orderIndex), skipping any without an id. */
+export function toTiers(definitions: Raw[] | undefined): TicketTier[] {
+  return (definitions ?? [])
+    .slice()
+    .sort((a, b) => (a.orderIndex ?? 0) - (b.orderIndex ?? 0))
+    .map(toTier)
+    .filter((t) => t.id);
+}
+
+/** The reservation's line items from the picker's selections; throws when nothing is picked. */
+export function reservationTickets(selections: { tierId: string; quantity: number }[]): { ticketDefinitionId: string; quantity: number }[] {
+  const tickets = selections
+    .filter((s) => s.quantity > 0)
+    .map((s) => ({ ticketDefinitionId: s.tierId, quantity: s.quantity }));
+  if (!tickets.length) throw new Error("Pick at least one ticket first.");
+  return tickets;
+}
+
+/**
+ * The real gate on paid tickets: until the site has a premium plan AND a configured payment
+ * method, reserving fails 403 NO_PAYMENT_METHOD_CONFIGURED. Not a permissions bug — don't
+ * elevate (that just creates an unpayable order); surface it softly.
+ */
+export function reservationError(e: unknown): Error {
+  const msg = e instanceof Error ? e.message : String(e);
+  if (/payment method|not configured|premium/i.test(msg)) {
+    return new Error("Ticket sales aren't switched on yet — the organizer needs to connect a payment method in the dashboard.");
+  }
+  return e instanceof Error ? e : new Error(msg);
+}
+
+/** The reservation id out of either transport's response; throws when the hold didn't happen. */
+export function reservationId(reservation: Raw | null | undefined): string {
+  const id = tierId(reservation);
+  if (!id) throw new Error("Those tickets couldn't be reserved — they may have just sold out.");
+  return id;
+}
+
+/** Where the hosted checkout returns to. Defaults are the Astro routes; a static site passes its file paths. */
+export interface CheckoutPaths {
+  /** Success landing — Wix appends `?orderNumber=&eventId=`. Default `/event-confirmation`. */
+  confirmation?: string;
+  /** Back here on abandon. Default `/events/<slug>`. */
+  event?: string;
+}
+
+/**
+ * The redirect session's callbacks. `origin` is the published https host (window.location.origin
+ * in a browser) — an http or server-derived origin isn't on the redirect allowlist and 403s the
+ * return; {} when unknown (SSR).
+ */
+export function checkoutCallbacks(origin: string, slug: string, paths: CheckoutPaths = {}): Raw {
+  if (!origin) return {};
+  return {
+    thankYouPageUrl: `${origin}${paths.confirmation ?? "/event-confirmation"}`,
+    postFlowUrl: `${origin}${paths.event ?? `/events/${slug}`}`,
+  };
+}
+
+/** The redirect result; throws when Wix returned no URL. */
+export function redirectResult(session: Raw | null | undefined): RegistrationResult {
+  const url = session?.redirectSession?.fullUrl;
+  if (!url) throw new Error("Checkout couldn't start — please try again.");
+  return { kind: "redirect", url };
+}
+
+/**
+ * The RSVP body: the built-in form is exactly firstName + lastName + email — never a fetched
+ * schema, never extra fields. "NO" only when the event's rsvpResponseType is "YES_AND_NO".
+ */
+export function rsvpBody(eventId: string, guest: { firstName: string; lastName: string; email: string }, status: "YES" | "NO"): Raw {
+  return { eventId, firstName: guest.firstName, lastName: guest.lastName, email: guest.email, status };
+}
+
+/** A full event with a waitlist answers status "WAITLIST" — tell the guest they're waitlisted, not confirmed. */
+export function rsvpResult(rsvp: Raw | null | undefined, sent: "YES" | "NO"): RegistrationResult {
+  return { kind: "rsvpConfirmed", status: (rsvp?.status ?? sent) as "YES" | "NO" | "WAITLIST" };
+}
+
+export type CheckoutEvent = Pick<EventDetail, "id" | "slug">;

package/skills/wix-headless-fast/references/events/app/wix/events/registration-store.ts

@@ -0,0 +1,156 @@
+// The registration flow for one event as a framework-free store — the logic behind
+// useEventRegistration, usable from React (the hook wraps it), from a static page's event view,
+// from Vue/Svelte, or as the specification for a port. Branched on event.registrationType:
+// TICKETING loads the tier picker and checkout() reserves → redirects to Wix's hosted checkout;
+// RSVP is the built-in name+email form submitted in place. All correctness (the visitor-public
+// tier read, the reservation payload, the redirect callbacks, rsvpV2) lives in the data layer —
+// this store orchestrates; the page owns how it looks.
+//
+// One store per event surface: createRegistrationStore(event), not a singleton. A static site
+// passes `paths` so the hosted checkout returns to its files (`event-confirmation.html`).
+import { fetchTicketTiers, startTicketCheckout, submitRsvp, type CheckoutPaths } from "./registration";
+import type { EventDetail, RegistrationResult, TicketTier } from "./types";
+
+export type RsvpField = "firstName" | "lastName" | "email";
+
+export interface RegistrationStoreOptions {
+  /** Where the hosted checkout returns to; defaults are the Astro routes. */
+  paths?: CheckoutPaths;
+}
+
+export interface RegistrationState {
+  /** TICKETING: tiers for the picker — null while loading (skeletons), [] honest empty. Other types: []. */
+  tiers: TicketTier[] | null;
+  /** Selected quantity per tier id (0 when untouched). */
+  quantities: Record<string, number>;
+  ticketCount: number;
+  /** True when ≥ 1 ticket is selected — gate the checkout CTA on this. */
+  canCheckout: boolean;
+  /** RSVP form state — the built-in fields, exactly these. */
+  rsvpValues: { firstName: string; lastName: string; email: string };
+  /** True when every RSVP field is filled — gate the RSVP CTA on this. */
+  canRsvp: boolean;
+  submitting: boolean;
+  /** Set after an RSVP completes (kind "rsvpConfirmed"; status may be "WAITLIST"). */
+  confirmed: RegistrationResult | null;
+  error: string | null;
+}
+
+export interface RegistrationStore {
+  getState(): RegistrationState;
+  subscribe(listener: () => void): () => void;
+  /** Load the tiers of a TICKETING event. Call once when mounted (a browser). */
+  start(): void;
+  /** Stop reacting; drop a late response. */
+  stop(): void;
+  /** Clamped to 0..limitPerCheckout; ignored for tiers not on sale (saleStatus gate). */
+  setQuantity(tierId: string, quantity: number): void;
+  setRsvpValue(field: RsvpField, value: string): void;
+  /** Reserves + redirects to the Wix-hosted checkout. On "redirect" the browser is navigating. Throws (and sets .error) on refusal. */
+  checkout(): Promise<RegistrationResult>;
+  /** attending=false only when event.rsvpResponseType is "YES_AND_NO". Throws (and sets .error) on refusal. */
+  rsvp(attending?: boolean): Promise<RegistrationResult>;
+}
+
+export function createRegistrationStore(event: EventDetail, { paths }: RegistrationStoreOptions = {}): RegistrationStore {
+  const ticketed = event.registrationType === "TICKETING";
+  let tiers: TicketTier[] | null = ticketed ? null : [];
+  let quantities: Record<string, number> = {};
+  let rsvpValues = { firstName: "", lastName: "", email: "" };
+  let submitting = false;
+  let confirmed: RegistrationResult | null = null;
+  let error: string | null = null;
+  let started = false;
+  const listeners = new Set<() => void>();
+  let snapshot: RegistrationState | null = null;
+  const emit = () => {
+    snapshot = null;
+    for (const fn of listeners) fn();
+  };
+
+  function getState(): RegistrationState {
+    if (snapshot) return snapshot;
+    const ticketCount = Object.values(quantities).reduce((sum, q) => sum + q, 0);
+    snapshot = {
+      tiers,
+      quantities,
+      ticketCount,
+      canCheckout: ticketCount > 0,
+      rsvpValues,
+      canRsvp: (["firstName", "lastName", "email"] as const).every((f) => rsvpValues[f].trim().length > 0),
+      submitting,
+      confirmed,
+      error,
+    };
+    return snapshot;
+  }
+
+  async function run(op: () => Promise<RegistrationResult>): Promise<RegistrationResult> {
+    submitting = true;
+    error = null;
+    emit();
+    try {
+      const result = await op();
+      if (result.kind === "redirect") {
+        if (typeof window !== "undefined") window.location.href = result.url;
+      } else {
+        confirmed = result;
+      }
+      return result;
+    } catch (e) {
+      error = e instanceof Error ? e.message : String(e);
+      throw e;
+    } finally {
+      submitting = false;
+      emit();
+    }
+  }
+
+  return {
+    getState,
+    subscribe(fn) {
+      listeners.add(fn);
+      return () => listeners.delete(fn);
+    },
+    start() {
+      if (started) return;
+      started = true;
+      if (!ticketed) return;
+      fetchTicketTiers(event.id)
+        .then((t) => {
+          if (!started) return;
+          tiers = t;
+          emit();
+        })
+        .catch((e) => {
+          if (!started) return;
+          tiers = [];
+          error = e instanceof Error ? e.message : String(e);
+          emit();
+        });
+    },
+    stop() {
+      started = false;
+    },
+    setQuantity(tierId, quantity) {
+      const tier = (tiers ?? []).find((t) => t.id === tierId);
+      if (!tier || tier.saleStatus !== "SALE_STARTED") return;
+      const clamped = Math.max(0, Math.min(quantity, tier.limitPerCheckout || 20));
+      quantities = { ...quantities, [tierId]: clamped };
+      emit();
+    },
+    setRsvpValue(field, value) {
+      rsvpValues = { ...rsvpValues, [field]: value };
+      emit();
+    },
+    checkout: () =>
+      run(() =>
+        startTicketCheckout(
+          event,
+          Object.entries(quantities).map(([tierId, quantity]) => ({ tierId, quantity })),
+          paths,
+        ),
+      ),
+    rsvp: (attending = true) => run(() => submitRsvp(event.id, rsvpValues, attending ? "YES" : "NO")),
+  };
+}

package/skills/wix-headless-fast/references/events/app/wix/events/registration.ts

@@ -1,7 +1,8 @@
-// Ticket tiers, the reserve → hosted-checkout redirect, and RSVP. The payload shapes here
-// are exact and easy to get subtly wrong — copy as-is; extend by calling these exports,
-// never by editing them. Failures are loud. Everything runs as the anonymous VISITOR —
-// no server route, no elevation, anywhere.
+// Ticket tiers, the reserve → hosted-checkout redirect, and RSVP over the SDK. Rules and mappers
+// live in ./registration-core (shared with the REST twin in references/events/rest/); this file is
+// the transport only. The payload shapes are exact and easy to get subtly wrong — copy as-is;
+// extend by calling these exports, never by editing them. Failures are loud. Everything runs as
+// the anonymous VISITOR — no server route, no elevation, anywhere.
 // docs: https://dev.wix.com/docs/api-reference/business-solutions/events/registration/ticketing/orders/query-available-tickets.md
 // docs: https://dev.wix.com/docs/api-reference/business-solutions/events/registration/ticketing/ticket-reservations/create-ticket-reservation.md
 // docs: https://dev.wix.com/docs/api-reference/business-solutions/events/registration/rsvp-v2/create-rsvp.md
@@ -9,38 +10,28 @@
 import { orders, rsvpV2, ticketReservations } from "@wix/events";
 import { redirects as redirectsModule } from "@wix/redirects";
 import { wixModule } from "../sdk";
-import type { EventDetail, RegistrationResult, TicketTier } from "./types";
+import {
+  checkoutCallbacks,
+  redirectResult,
+  reservationError,
+  reservationId,
+  reservationTickets,
+  rsvpBody,
+  rsvpResult,
+  toTiers,
+  type CheckoutEvent,
+  type CheckoutPaths,
+} from "./registration-core";
+import type { Raw } from "./events-core";
+import type { RegistrationResult, TicketTier } from "./types";
+
+export { type CheckoutPaths };
 
 const availableTickets = wixModule(orders);
 const reservations = wixModule(ticketReservations);
 const rsvps = wixModule(rsvpV2);
 const redirects = wixModule(redirectsModule);
 
-type Raw = Record<string, any>;
-
-function formatTierPrice(price: Raw | undefined): string {
-  const value = price?.amount ?? price?.value;
-  if (value == null || value === "") return "";
-  try {
-    return new Intl.NumberFormat(undefined, { style: "currency", currency: price?.currency || "USD" }).format(Number(value));
-  } catch {
-    return `${value} ${price?.currency ?? ""}`.trim();
-  }
-}
-
-function toTier(raw: Raw): TicketTier {
-  const free = raw.free === true || Number(raw.price?.amount ?? raw.price?.value ?? 0) === 0;
-  return {
-    id: raw._id ?? "", // _id, never .id
-    name: raw.name ?? "",
-    description: raw.description ?? "",
-    price: free ? "Free" : formatTierPrice(raw.price),
-    free,
-    limitPerCheckout: raw.limitPerCheckout ?? 20,
-    saleStatus: (raw.saleStatus ?? "SALE_STARTED") as TicketTier["saleStatus"],
-  };
-}
-
 /**
  * Ticket tiers for a TICKETING event, in display order. Reads the VISITOR-public storefront
  * endpoint (orders.queryAvailableTickets) — never ticketDefinitions*.queryTicketDefinitions:
@@ -50,20 +41,17 @@ function toTier(raw: Raw): TicketTier {
 export async function fetchTicketTiers(eventId: string): Promise<TicketTier[]> {
   // limit is REQUIRED: it defaults to 0, which returns metadata only — zero tiers, no error.
   const res: Raw = await availableTickets.queryAvailableTickets({ filter: { eventId }, limit: 100 });
-  return (res.definitions ?? [])
-    .slice()
-    .sort((a: Raw, b: Raw) => (a.orderIndex ?? 0) - (b.orderIndex ?? 0))
-    .map((d: Raw) => toTier(d))
-    .filter((t: TicketTier) => t.id);
+  return toTiers(res.definitions);
 }
 
 /**
  * RSVP to a free (RSVP-type) event — completes fully client-side: no reservation, no
  * redirect, no payment. The registration form is BUILT-IN: exactly firstName + lastName +
  * email; never fetch a form schema or add fields. Send "NO" only when the event's
- * rsvpResponseType is "YES_AND_NO". Throws on closed registration / duplicate email —
- * surface the message. A full event with a waitlist returns status "WAITLIST" — tell the
- * guest they're waitlisted, not confirmed.
+ * rsvpResponseType is "YES_AND_NO". Throws on closed registration, a guest limit, or an
+ * invalid email — surface the message (a repeat email is accepted by default; the organizer's
+ * settings decide). A full event with a waitlist returns status "WAITLIST" — tell the guest
+ * they're waitlisted, not confirmed.
  */
 export async function submitRsvp(
   eventId: string,
@@ -72,8 +60,8 @@ export async function submitRsvp(
 ): Promise<RegistrationResult> {
   // rsvpV2 takes the rsvp object DIRECTLY as the first arg (never wrapped in { rsvp: … }),
   // and only rsvpV2 works for visitors — the legacy v1 `rsvp` module 400s on these fields.
-  const res: Raw = await rsvps.createRsvp({ eventId, ...guest, status } as any);
-  return { kind: "rsvpConfirmed", status: (res?.status ?? status) as "YES" | "NO" | "WAITLIST" };
+  const res: Raw = await rsvps.createRsvp(rsvpBody(eventId, guest, status) as any);
+  return rsvpResult(res, status);
 }
 
 /**
@@ -84,45 +72,26 @@ export async function submitRsvp(
  * server-derived origin isn't on the redirect allowlist and 403s the return), and
  * createRedirectSession must run as the visitor (it embeds the headless OAuth client and
  * rejects admin/elevated tokens). Never hand-build the checkout URL — the Wix-site
- * `…/ticket-form?reservationId=` path 404s on a headless site.
+ * `…/ticket-form?reservationId=` path 404s on a headless site. `paths` overrides the return
+ * routes (a static site's `event-confirmation.html`).
  */
 export async function startTicketCheckout(
-  event: Pick<EventDetail, "id" | "slug">,
+  event: CheckoutEvent,
   selections: { tierId: string; quantity: number }[],
+  paths: CheckoutPaths = {},
 ): Promise<RegistrationResult> {
-  const tickets = selections
-    .filter((s) => s.quantity > 0)
-    .map((s) => ({ ticketDefinitionId: s.tierId, quantity: s.quantity }));
-  if (!tickets.length) throw new Error("Pick at least one ticket first.");
-
+  const tickets = reservationTickets(selections);
   let reservation: Raw;
   try {
     reservation = await reservations.createTicketReservation({ tickets } as any);
   } catch (e) {
-    // The real gate on paid tickets: until the site has a premium plan AND a configured
-    // payment method, reserving fails 403 "No payment method configured". Not a permissions
-    // bug — don't elevate (that just creates an unpayable order); surface it softly.
-    const msg = e instanceof Error ? e.message : String(e);
-    if (/payment method|not configured|premium/i.test(msg)) {
-      throw new Error(
-        "Ticket sales aren't switched on yet — the organizer needs to connect a payment method in the dashboard.",
-      );
-    }
-    throw e;
+    throw reservationError(e);
   }
-  const reservationId: string | undefined = reservation?._id; // _id, never .id
-  if (!reservationId) throw new Error("Those tickets couldn't be reserved — they may have just sold out.");
-
   const origin = typeof window !== "undefined" ? window.location.origin : "";
   const session: Raw = await redirects.createRedirectSession({
-    eventsCheckout: { reservationId, eventSlug: event.slug },
-    callbacks: {
-      // Wix appends ?orderNumber=&eventId= — the shipped /event-confirmation page reads them.
-      thankYouPageUrl: origin ? `${origin}/event-confirmation` : undefined,
-      postFlowUrl: origin ? `${origin}/events/${event.slug}` : undefined, // back here on abandon
-    },
+    eventsCheckout: { reservationId: reservationId(reservation), eventSlug: event.slug },
+    // Wix appends ?orderNumber=&eventId= to the thank-you URL — the shipped /event-confirmation page reads them.
+    callbacks: checkoutCallbacks(origin, event.slug, paths),
   });
-  const url = session?.redirectSession?.fullUrl;
-  if (!url) throw new Error("Checkout couldn't start — please try again.");
-  return { kind: "redirect", url };
+  return redirectResult(session);
 }

package/skills/wix-headless-fast/references/events/rest/events.ts

@@ -0,0 +1,57 @@
+// Event reads over REST — the twin of app/wix/events/events.ts. Same exports, same DTOs; the rules
+// and mappers come from events-core (the SAME file the SDK transport uses, deployed flat next to
+// this one by deploy.mjs --stack static), so this file is only the transport: one fetch with a
+// literal body per function. Every call here is safe from a browser with a visitor token.
+// Porting: keep the paths, keep the bodies, port the core once.
+// docs: https://dev.wix.com/docs/api-reference/business-solutions/events/event-management/events-v3/query-events.md
+// docs: https://dev.wix.com/docs/api-reference/business-solutions/events/event-management/events-v3/get-event-by-slug.md
+// docs: https://dev.wix.com/docs/api-reference/business-solutions/events/event-management/events-v3/get-event.md
+import { WixApiError, wixRequest } from "./client.js";
+import { imgSrc } from "./media.js";
+import { DETAIL_FIELDS, EVENTS_APP_ID, LIST_FIELDS, listQuery, rawId, toDetail, toSummary, type Raw } from "./events-core.js";
+import type { EventDetail, EventSummary } from "./types.js";
+
+export { EVENTS_APP_ID };
+
+const notFound = (e: unknown): boolean => e instanceof WixApiError && e.status === 404;
+
+/**
+ * Live (UPCOMING/STARTED) events, soonest first. The limit is always sent: `paging.limit`
+ * defaults to 0 and a bare query answers `total: N, events: []` with no error.
+ * POST /events/v3/events/query  { query: { filter: { status: { $in } }, sort, paging: { limit } }, fields }
+ */
+export async function fetchEvents({ limit = 100 } = {}): Promise<EventSummary[]> {
+  const res = await wixRequest<Raw>("/events/v3/events/query", { body: { query: listQuery({ limit }), fields: LIST_FIELDS } });
+  return ((res?.events ?? []) as Raw[]).map((e) => toSummary(e, imgSrc));
+}
+
+/**
+ * One event by URL slug; null when the slug doesn't resolve (EVENT_NOT_FOUND, 404) — a real 404,
+ * never a fallback to another event. The response is WRAPPED: { event }.
+ * GET /events/v3/events/slug/{slug}?fields=DETAILS&fields=TEXTS&fields=REGISTRATION&fields=URLS&fields=CATEGORIES
+ */
+export async function fetchEventBySlug(slug: string): Promise<EventDetail | null> {
+  try {
+    const res = await wixRequest<Raw>(`/events/v3/events/slug/${encodeURIComponent(slug)}`, { method: "GET", query: { fields: DETAIL_FIELDS } });
+    return res?.event ? toDetail(res.event, imgSrc) : null;
+  } catch (e) {
+    if (notFound(e)) return null;
+    throw e;
+  }
+}
+
+/**
+ * One event by id — the post-checkout confirmation read (the thank-you URL carries
+ * `?orderNumber=&eventId=`). On REST this response is WRAPPED too: { event } (the SDK's getEvent
+ * is the unwrapped one).  GET /events/v3/events/{eventId}?fields=…
+ */
+export async function fetchEventById(eventId: string): Promise<EventDetail | null> {
+  try {
+    const res = await wixRequest<Raw>(`/events/v3/events/${encodeURIComponent(eventId)}`, { method: "GET", query: { fields: DETAIL_FIELDS } });
+    const raw: Raw | undefined = res?.event;
+    return raw && rawId(raw) ? toDetail(raw, imgSrc) : null;
+  } catch (e) {
+    if (notFound(e)) return null;
+    throw e;
+  }
+}

package/skills/wix-headless-fast/references/events/rest/registration.ts

@@ -0,0 +1,83 @@
+// Ticket tiers, the reserve → hosted-checkout redirect, and RSVP over REST — the twin of
+// app/wix/events/registration.ts. Same exports, same DTOs; rules and mappers from
+// registration-core (the SAME file the SDK transport uses, deployed flat next to this one). The
+// request shapes are exact and rewriting them is how registrations break. Failures are loud.
+// All calls run with the visitor token — the reservation and the RSVP are the token's.
+// docs: https://dev.wix.com/docs/api-reference/business-solutions/events/registration/ticketing/orders/query-available-tickets.md
+// docs: https://dev.wix.com/docs/api-reference/business-solutions/events/registration/ticketing/ticket-reservations/create-ticket-reservation.md
+// docs: https://dev.wix.com/docs/api-reference/business-solutions/events/registration/rsvp-v2/create-rsvp.md
+// docs: https://dev.wix.com/docs/api-reference/business-management/headless/redirects/create-redirect-session.md
+import { wixRequest } from "./client.js";
+import {
+  checkoutCallbacks,
+  redirectResult,
+  reservationError,
+  reservationId,
+  reservationTickets,
+  rsvpBody,
+  rsvpResult,
+  toTiers,
+  type CheckoutEvent,
+  type CheckoutPaths,
+} from "./registration-core.js";
+import type { Raw } from "./events-core.js";
+import type { RegistrationResult, TicketTier } from "./types.js";
+
+export { type CheckoutPaths };
+
+/**
+ * Ticket tiers for a TICKETING event, in display order — the VISITOR-public storefront read, never
+ * the ticket-definitions management API (403 for a visitor). `limit` is REQUIRED: it defaults to 0
+ * and returns metadata only.  POST /events/v1/checkout/available-tickets/query  { filter: { eventId }, limit }
+ */
+export async function fetchTicketTiers(eventId: string): Promise<TicketTier[]> {
+  const res = await wixRequest<Raw>("/events/v1/checkout/available-tickets/query", { body: { filter: { eventId }, limit: 100 } });
+  return toTiers(res?.definitions);
+}
+
+/**
+ * RSVP to a free (RSVP-type) event — completes fully client-side: no reservation, no redirect, no
+ * payment. The form is BUILT-IN: exactly firstName + lastName + email. "NO" only when the event's
+ * rsvpResponseType is "YES_AND_NO". Throws on closed registration, a guest limit, or an invalid
+ * email — surface the message (a repeat email is accepted by default). A full event with a waitlist
+ * answers "WAITLIST".
+ * POST /events/v2/rsvps  { rsvp: { eventId, firstName, lastName, email, status } }  → { rsvp: { id, status } }
+ */
+export async function submitRsvp(
+  eventId: string,
+  guest: { firstName: string; lastName: string; email: string },
+  status: "YES" | "NO" = "YES",
+): Promise<RegistrationResult> {
+  const res = await wixRequest<Raw>("/events/v2/rsvps", { body: { rsvp: rsvpBody(eventId, guest, status) } });
+  return rsvpResult(res?.rsvp, status);
+}
+
+/**
+ * Ticketed checkout, the exact sequence: reserve the selected tiers (a PENDING hold that
+ * auto-expires), then mint the Wix-hosted checkout redirect and return its URL — the caller
+ * navigates the FULL document to it; Wix collects guest details + payment and emails the tickets.
+ * `origin` must be the site's real https origin as registered on the OAuth app's allowed domains
+ * (browser: window.location.origin). Never hand-build the checkout URL. `paths` overrides the
+ * return routes — a static site passes `{ confirmation: "/event-confirmation.html", event: "/event.html?slug=…" }`.
+ * POST /events/v1/ticket-reservations  { ticketReservation: { tickets: [{ ticketDefinitionId, quantity }] } }  → { ticketReservation: { id, status: "PENDING", expirationDate } }
+ * POST /headless/v1/redirect-session   { eventsCheckout: { reservationId, eventSlug }, callbacks: { thankYouPageUrl, postFlowUrl } }
+ */
+export async function startTicketCheckout(
+  event: CheckoutEvent,
+  selections: { tierId: string; quantity: number }[],
+  paths: CheckoutPaths = {},
+  origin: string = typeof window !== "undefined" ? window.location.origin : "",
+): Promise<RegistrationResult> {
+  const tickets = reservationTickets(selections);
+  let reservation: Raw | undefined;
+  try {
+    // Until the site has a premium plan AND a payment method this is a 403 NO_PAYMENT_METHOD_CONFIGURED — a business gate, not a bug.
+    reservation = (await wixRequest<Raw>("/events/v1/ticket-reservations", { body: { ticketReservation: { tickets } } }))?.ticketReservation;
+  } catch (e) {
+    throw reservationError(e);
+  }
+  const session = await wixRequest<Raw>("/headless/v1/redirect-session", {
+    body: { eventsCheckout: { reservationId: reservationId(reservation), eventSlug: event.slug }, callbacks: checkoutCallbacks(origin, event.slug, paths) },
+  });
+  return redirectResult(session);
+}

package/skills/wix-headless-fast/references/events/seed/SEED.md

@@ -76,6 +76,15 @@ dashboard. That's an owner step, not a seeding failure; relay it.
 **Seeding is additive — never delete or overwrite existing content**; ask first if a cleanup
 seems needed.
 
+## Supplied content
+
+The general rules are in `references/shared/SUPPLIED-CONTENT.md`. For events, each event the user
+lists is one entry. Its title becomes `title`; its date and time become `startDate` and `endDate` in
+ISO with the `timeZoneId` the user stated; the venue and address become `location`; named tickets
+with prices become `ticketTiers` on a `TICKETING` event, and an event with no tickets is `RSVP`; a
+category becomes `category`; their image becomes `imageUrl`. A date without a year or without a
+time zone is a question for the user, never a guess.
+
 ## Escape hatch — individual functions
 `setupEvents` composes exported steps — `installEventsApp`, `getSiteCurrency`, `createEvent`,
 `createTicketTiers`, `publishEvent`, `createEventCategories`, `assignEventsToCategory`,