@wix/agent-skills 1.20.1 → 1.22.0

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

@@ -1,156 +0,0 @@
-// 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,97 +0,0 @@
-// 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
-// docs: https://dev.wix.com/docs/api-reference/business-management/headless/redirects/create-redirect-session.md
-import { orders, rsvpV2, ticketReservations } from "@wix/events";
-import { redirects as redirectsModule } from "@wix/redirects";
-import { wixModule } from "../sdk";
-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);
-
-/**
- * Ticket tiers for a TICKETING event, in display order. Reads the VISITOR-public storefront
- * endpoint (orders.queryAvailableTickets) — never ticketDefinitions*.queryTicketDefinitions:
- * those are the management API and 403 the anonymous visitor (auth.elevate() is the wrong
- * fix — wrong axis, SSR-only).
- */
-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 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, 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,
-  guest: { firstName: string; lastName: string; email: string },
-  status: "YES" | "NO" = "YES",
-): 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(rsvpBody(eventId, guest, status) as any);
-  return rsvpResult(res, status);
-}
-
-/**
- * Ticketed checkout, the exact sequence: reserve the selected tiers (holds them, PENDING,
- * auto-expires), then mint the Wix-hosted checkout redirect and return its URL — the caller
- * navigates to it; Wix collects guest details + payment and emails the tickets. Call from
- * the browser: it needs window.location.origin (the published https host — an http or
- * 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. `paths` overrides the return
- * routes (a static site's `event-confirmation.html`).
- */
-export async function startTicketCheckout(
-  event: CheckoutEvent,
-  selections: { tierId: string; quantity: number }[],
-  paths: CheckoutPaths = {},
-): Promise<RegistrationResult> {
-  const tickets = reservationTickets(selections);
-  let reservation: Raw;
-  try {
-    reservation = await reservations.createTicketReservation({ tickets } as any);
-  } catch (e) {
-    throw reservationError(e);
-  }
-  const origin = typeof window !== "undefined" ? window.location.origin : "";
-  const session: Raw = await redirects.createRedirectSession({
-    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),
-  });
-  return redirectResult(session);
-}

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

@@ -1,61 +0,0 @@
-// Events 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.
-
-/** The current registration flavor — every registration surface branches on this. */
-export type RegistrationType = "RSVP" | "TICKETING" | "EXTERNAL" | "NONE";
-
-/** An event as a listing/grid tile needs it. */
-export interface EventSummary {
-  id: string;
-  slug: string;
-  title: string;
-  /** Plain-text teaser, safe to render directly (the rich description never leaves the data layer). */
-  shortDescription: string;
-  /** Human-formatted date/time from Wix, e.g. "Sep 26, 2026, 7:00 PM" ("" when the date is TBD). */
-  dateLabel: string;
-  /** ISO start instant for custom formatting/grouping ("" when the date is TBD). */
-  startDateIso: string;
-  locationName: string;
-  locationType: "VENUE" | "ONLINE" | "TBD";
-  /** Resolved https URL ("" when the event has no image). */
-  imageUrl: string;
-  registrationType: RegistrationType;
-  /** "From €25.00" (ticketed), "Free" (RSVP / free tickets), "" when nothing applies. */
-  priceLabel: string;
-  soldOut: boolean;
-  /** Assigned category names (the seeded format/track grouping) — filter client-side. */
-  categories: { id: string; name: string }[];
-}
-
-/** An event as the detail/registration page needs it. */
-export interface EventDetail extends EventSummary {
-  /** Long description as plain paragraphs (extracted from the rich content; may be empty). */
-  aboutParagraphs: string[];
-  /** False → registration is closed (sold out / closed / ended) — show a closed state, no form. */
-  registrationOpen: boolean;
-  /** RSVP events: "YES_AND_NO" also allows a "can't make it" reply. */
-  rsvpResponseType: "YES_ONLY" | "YES_AND_NO";
-  /** EXTERNAL events: the outbound registration URL ("" otherwise). */
-  externalUrl: string;
-  addToCalendar: { google: string; ics: string };
-}
-
-/** A purchasable ticket tier (TICKETING events). */
-export interface TicketTier {
-  id: string;
-  name: string;
-  description: string;
-  /** Formatted price (e.g. "€45.00"); "Free" for free tiers. */
-  price: string;
-  free: boolean;
-  /** Max quantity per order for this tier. */
-  limitPerCheckout: number;
-  /** Only "SALE_STARTED" is buyable — gate the picker on this. */
-  saleStatus: "SALE_SCHEDULED" | "SALE_STARTED" | "SALE_ENDED";
-}
-
-/** The outcome of a registration: the browser is redirecting to Wix checkout, or the RSVP is in. */
-export type RegistrationResult =
-  | { kind: "redirect"; url: string }
-  | { kind: "rsvpConfirmed"; status: "YES" | "NO" | "WAITLIST" };

package/skills/wix-headless-fast/references/events/app-astro/layouts/SiteLayout.astro

@@ -1,40 +0,0 @@
----
-// The site chrome for every events 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. (Deploy is fill-only: if another vertical is already
-// deployed, its SiteLayout won — merge an Events nav link 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="/events" class="text-foreground no-underline transition-colors hover:text-muted-foreground">Events</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-fast/references/events/app-astro/pages/event-confirmation.astro

@@ -1,12 +0,0 @@
----
-// Post-checkout thank-you page — the Wix-hosted checkout redirects here with
-// ?orderNumber=&eventId=. KEEP THIS ROUTE: the data layer's checkout callbacks point at
-// /event-confirmation. The island is client:only (it reads the browser URL); swap its
-// import to YOUR confirmation component if you design one.
-import SiteLayout from "../layouts/SiteLayout.astro";
-import EventConfirmationView from "../components/events/EventConfirmationView";
----
-
-<SiteLayout title="Order confirmed">
-  <EventConfirmationView client:only="react" />
-</SiteLayout>

package/skills/wix-headless-fast/references/events/app-astro/pages/events/[slug].astro

@@ -1,80 +0,0 @@
----
-// Event detail + registration 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 registration
-// component. The registration island is client:only — it runs visitor-session calls and
-// redirects.
-import SiteLayout from "../../layouts/SiteLayout.astro";
-import EventRegistrationView from "../../components/events/EventRegistrationView";
-import { fetchEventBySlug } from "../../wix/events/events";
-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.events.id,
-  pageIdentifier: WIX_APPS.events.eventPageMetadata.pageIdentifier,
-  identifiers: {
-    slug: WIX_APPS.events.eventPageMetadata.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 event = null;
-let seoTagsServiceConfig = null;
-try {
-  [event, seoTagsServiceConfig] = await Promise.all([
-    fetchEventBySlug(slug),
-    loadSEOTagsServiceConfig({
-      pageUrl,
-      itemType: seoTags.ItemType.EVENTS_PAGE,
-      itemData: { slug },
-    }).catch(() => null),
-  ]);
-} catch {
-  // Guarded: an unhandled SSR throw truncates the response mid-stream.
-}
-
-if (!event) {
-  return new Response(null, { status: 404 });
-}
----
-
-<SiteLayout title={event.title}>
-  <SEO.Tags seoTagsServiceConfig={seoTagsServiceConfig} slot="seo-tags" />
-
-  <div class="grid gap-10 md:grid-cols-2">
-    <div>
-      {event.imageUrl && (
-        <div class="aspect-[3/2] overflow-hidden rounded-xl bg-secondary">
-          <img src={event.imageUrl} alt={event.title} class="h-full w-full object-cover" />
-        </div>
-      )}
-      {event.dateLabel && <p class="eyebrow mt-5">{event.dateLabel}</p>}
-      <h1 class="mt-1 text-2xl font-semibold tracking-tight">{event.title}</h1>
-      <p class="mt-1 text-sm text-muted-foreground">
-        {event.locationType === "ONLINE" ? "Online event" : event.locationName}
-        {event.priceLabel ? ` · ${event.priceLabel}` : ""}
-      </p>
-      {event.shortDescription && <p class="mt-4 text-sm leading-relaxed text-muted-foreground">{event.shortDescription}</p>}
-      {event.aboutParagraphs.map((p) => (
-        <p class="mt-3 text-sm leading-relaxed text-muted-foreground">{p}</p>
-      ))}
-    </div>
-    <div>
-      <EventRegistrationView client:only="react" event={event} />
-    </div>
-  </div>
-</SiteLayout>

package/skills/wix-headless-fast/references/events/app-astro/pages/events.astro

@@ -1,21 +0,0 @@
----
-// Events listing — data fetched SERVER-SIDE (SEO) and handed to the island as DTO props.
-// Keep this frontmatter; swap the island import to YOUR listing component.
-import SiteLayout from "../layouts/SiteLayout.astro";
-import EventsView from "../components/events/EventsView";
-import { fetchEvents } from "../wix/events/events";
-import type { EventSummary } from "../wix/events/types";
-
-let events: EventSummary[] = [];
-try {
-  events = await fetchEvents();
-} catch {
-  // An unguarded SSR throw truncates the response mid-stream; the island renders the
-  // empty state instead.
-}
----
-
-<SiteLayout title="Events">
-  <h1 class="mb-8 text-2xl font-semibold tracking-tight">Events</h1>
-  <EventsView client:load initialEvents={events} />
-</SiteLayout>