@wix/agent-skills 1.16.3 → 1.18.0

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

@@ -0,0 +1,128 @@
+// 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.
+// 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 type { EventDetail, RegistrationResult, TicketTier } from "./types";
+
+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:
+ * 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 (res.definitions ?? [])
+    .slice()
+    .sort((a: Raw, b: Raw) => (a.orderIndex ?? 0) - (b.orderIndex ?? 0))
+    .map((d: Raw) => toTier(d))
+    .filter((t: TicketTier) => t.id);
+}
+
+/**
+ * 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.
+ */
+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({ eventId, ...guest, status } as any);
+  return { kind: "rsvpConfirmed", status: (res?.status ?? status) as "YES" | "NO" | "WAITLIST" };
+}
+
+/**
+ * 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.
+ */
+export async function startTicketCheckout(
+  event: Pick<EventDetail, "id" | "slug">,
+  selections: { tierId: string; quantity: number }[],
+): 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.");
+
+  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;
+  }
+  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
+    },
+  });
+  const url = session?.redirectSession?.fullUrl;
+  if (!url) throw new Error("Checkout couldn't start — please try again.");
+  return { kind: "redirect", url };
+}

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

@@ -0,0 +1,61 @@
+// 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

@@ -0,0 +1,40 @@
+---
+// 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

@@ -0,0 +1,12 @@
+---
+// 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

@@ -0,0 +1,80 @@
+---
+// 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

@@ -0,0 +1,21 @@
+---
+// 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>