@wix/agent-skills 1.16.3 → 1.18.0

package/skills/wix-headless-fast/references/events/app/components/events/EventRegistrationView.tsx

@@ -0,0 +1,176 @@
+// REFERENCE registration surface: branches on event.registrationType — TICKETING renders
+// the tier picker (quantity steppers → checkout CTA), RSVP the built-in name+email form,
+// EXTERNAL a link out, NONE/closed an honest closed state — on the @theme tokens. Correct
+// and complete; per the skill's model you design and build your own on useEventRegistration.
+// Mount client:only — it runs visitor-session SDK calls and redirects.
+import { useEventRegistration } from "../../hooks/events/useEventRegistration";
+import type { EventDetail } from "../../wix/events/types";
+
+const input =
+  "w-full rounded-md border border-border bg-background px-3 py-2 text-sm text-foreground outline-none transition-shadow focus:ring-2 focus:ring-primary";
+const cta =
+  "mt-5 rounded-full bg-primary px-8 py-3 text-sm font-semibold text-primary-foreground transition-opacity hover:opacity-90 disabled:opacity-50";
+
+export default function EventRegistrationView({ event }: { event: EventDetail }) {
+  const {
+    tiers,
+    quantities,
+    setQuantity,
+    ticketCount,
+    canCheckout,
+    checkout,
+    rsvpValues,
+    setRsvpValue,
+    canRsvp,
+    rsvp,
+    submitting,
+    confirmed,
+    error,
+  } = useEventRegistration(event);
+
+  if (confirmed && confirmed.kind === "rsvpConfirmed") {
+    return (
+      <div className="rounded-lg border border-border bg-secondary p-8 text-center">
+        <p className="text-lg font-semibold">
+          {confirmed.status === "WAITLIST"
+            ? "You're on the waitlist"
+            : confirmed.status === "NO"
+              ? "Thanks for letting us know"
+              : "You're in! 🎉"}
+        </p>
+        <p className="mt-2 text-sm text-muted-foreground">
+          {confirmed.status === "WAITLIST"
+            ? `${event.title} is full — we'll email you if a spot opens up.`
+            : confirmed.status === "NO"
+              ? "We've recorded that you can't make it."
+              : `See you at ${event.title}${event.dateLabel ? ` — ${event.dateLabel}` : ""}. A confirmation email is on its way.`}
+        </p>
+      </div>
+    );
+  }
+
+  if (!event.registrationOpen) {
+    return (
+      <div className="rounded-lg border border-border p-6 text-sm text-muted-foreground">
+        {event.soldOut ? "This event is sold out." : "Registration for this event is closed."}
+      </div>
+    );
+  }
+
+  if (event.registrationType === "EXTERNAL") {
+    return (
+      <a href={event.externalUrl} className={`${cta} inline-block no-underline`} target="_blank" rel="noreferrer">
+        Register ↗
+      </a>
+    );
+  }
+
+  if (event.registrationType === "TICKETING") {
+    return (
+      <div>
+        <p className="mb-3 text-xs font-semibold uppercase tracking-wider text-muted-foreground">Tickets</p>
+        {tiers === null ? (
+          <div className="space-y-3" aria-busy="true">
+            {Array.from({ length: 2 }, (_, i) => (
+              <div key={i} className="h-16 animate-pulse rounded-lg bg-secondary" />
+            ))}
+          </div>
+        ) : tiers.length === 0 ? (
+          <p className="rounded-md border border-border p-4 text-sm text-muted-foreground">
+            Tickets aren't available right now.
+          </p>
+        ) : (
+          <div className="space-y-3">
+            {tiers.map((t) => {
+              const onSale = t.saleStatus === "SALE_STARTED";
+              const qty = quantities[t.id] ?? 0;
+              return (
+                <div key={t.id} className="flex items-center justify-between gap-4 rounded-lg border border-border p-4">
+                  <div>
+                    <p className="text-sm font-medium text-foreground">{t.name}</p>
+                    {t.description && <p className="mt-0.5 text-xs text-muted-foreground">{t.description}</p>}
+                    <p className="mt-1 text-sm text-foreground">{t.price}</p>
+                    {!onSale && (
+                      <p className="mt-1 text-xs text-muted-foreground">
+                        {t.saleStatus === "SALE_SCHEDULED" ? "Sale hasn't started yet" : "Sale ended"}
+                      </p>
+                    )}
+                  </div>
+                  <div className="flex items-center gap-2">
+                    <button
+                      type="button"
+                      aria-label={`Fewer ${t.name}`}
+                      disabled={!onSale || qty === 0}
+                      onClick={() => setQuantity(t.id, qty - 1)}
+                      className="h-8 w-8 rounded-full border border-border text-foreground transition-colors hover:bg-secondary disabled:opacity-40"
+                    >
+                      −
+                    </button>
+                    <span className="w-6 text-center text-sm tabular-nums">{qty}</span>
+                    <button
+                      type="button"
+                      aria-label={`More ${t.name}`}
+                      disabled={!onSale || qty >= t.limitPerCheckout}
+                      onClick={() => setQuantity(t.id, qty + 1)}
+                      className="h-8 w-8 rounded-full border border-border text-foreground transition-colors hover:bg-secondary disabled:opacity-40"
+                    >
+                      +
+                    </button>
+                  </div>
+                </div>
+              );
+            })}
+          </div>
+        )}
+        {error && <p className="mt-3 text-sm text-red-600">{error}</p>}
+        <button type="button" disabled={!canCheckout || submitting} onClick={() => checkout().catch(() => {})} className={cta}>
+          {submitting ? "Reserving…" : ticketCount > 0 ? `Get ${ticketCount} ticket${ticketCount > 1 ? "s" : ""}` : "Get tickets"}
+        </button>
+      </div>
+    );
+  }
+
+  if (event.registrationType === "RSVP") {
+    return (
+      <div>
+        <p className="mb-3 text-xs font-semibold uppercase tracking-wider text-muted-foreground">RSVP</p>
+        <div className="grid max-w-md gap-3">
+          <label className="block">
+            <span className="mb-1 block text-xs font-semibold uppercase tracking-wider text-muted-foreground">First name</span>
+            <input type="text" value={rsvpValues.firstName} onChange={(e) => setRsvpValue("firstName", e.target.value)} className={input} />
+          </label>
+          <label className="block">
+            <span className="mb-1 block text-xs font-semibold uppercase tracking-wider text-muted-foreground">Last name</span>
+            <input type="text" value={rsvpValues.lastName} onChange={(e) => setRsvpValue("lastName", e.target.value)} className={input} />
+          </label>
+          <label className="block">
+            <span className="mb-1 block text-xs font-semibold uppercase tracking-wider text-muted-foreground">Email</span>
+            <input type="email" value={rsvpValues.email} onChange={(e) => setRsvpValue("email", e.target.value)} className={input} />
+          </label>
+        </div>
+        {error && <p className="mt-3 text-sm text-red-600">{error}</p>}
+        <div className="flex items-center gap-3">
+          <button type="button" disabled={!canRsvp || submitting} onClick={() => rsvp(true).catch(() => {})} className={cta}>
+            {submitting ? "Sending…" : "Count me in"}
+          </button>
+          {event.rsvpResponseType === "YES_AND_NO" && (
+            <button
+              type="button"
+              disabled={!canRsvp || submitting}
+              onClick={() => rsvp(false).catch(() => {})}
+              className="mt-5 rounded-full border border-border px-6 py-3 text-sm font-medium text-foreground transition-colors hover:bg-secondary disabled:opacity-50"
+            >
+              Can't make it
+            </button>
+          )}
+        </div>
+      </div>
+    );
+  }
+
+  return (
+    <div className="rounded-lg border border-border p-6 text-sm text-muted-foreground">
+      Registration isn't open for this event.
+    </div>
+  );
+}

package/skills/wix-headless-fast/references/events/app/components/events/EventsView.tsx

@@ -0,0 +1,118 @@
+// REFERENCE listing surface: category filter + events grid on the @theme tokens.
+// Correct and complete; per the skill's model you design and build your own on useEvents.
+import type { ComponentType, ReactNode } from "react";
+import { useEvents } from "../../hooks/events/useEvents";
+import type { EventSummary } from "../../wix/events/types";
+
+export interface LinkLikeProps {
+  href: string;
+  className?: string;
+  children?: ReactNode;
+}
+
+const PlainLink = ({ href, className, children }: LinkLikeProps) => (
+  <a href={href} className={className}>
+    {children}
+  </a>
+);
+
+export interface EventCardProps {
+  event: EventSummary;
+  eventHref?: (slug: string) => string;
+  LinkComponent?: ComponentType<LinkLikeProps>;
+}
+
+export function EventCard({
+  event,
+  eventHref = (slug) => `/events/${slug}`,
+  LinkComponent = PlainLink,
+}: EventCardProps) {
+  return (
+    <LinkComponent href={eventHref(event.slug)} className="group block no-underline">
+      <div className="relative aspect-[3/2] overflow-hidden rounded-lg bg-secondary">
+        {event.imageUrl && (
+          <img
+            src={event.imageUrl}
+            alt={event.title}
+            loading="lazy"
+            className="h-full w-full object-cover transition-transform duration-300 group-hover:scale-[1.03]"
+          />
+        )}
+        {event.soldOut && (
+          <span className="absolute left-3 top-3 rounded-full bg-background/90 px-3 py-1 text-xs font-semibold text-foreground backdrop-blur">
+            Sold out
+          </span>
+        )}
+      </div>
+      {event.dateLabel && <p className="eyebrow mt-3">{event.dateLabel}</p>}
+      <p className="mt-1 text-sm font-medium text-foreground">{event.title}</p>
+      <p className="mt-0.5 text-xs text-muted-foreground">
+        {event.locationType === "ONLINE" ? "Online" : event.locationName}
+        {event.priceLabel ? ` · ${event.priceLabel}` : ""}
+      </p>
+    </LinkComponent>
+  );
+}
+
+export interface EventsViewProps {
+  initialEvents?: EventSummary[];
+  emptyMessage?: string;
+  eventHref?: EventCardProps["eventHref"];
+  LinkComponent?: ComponentType<LinkLikeProps>;
+  CardComponent?: ComponentType<EventCardProps>;
+}
+
+const pill = (active: boolean) =>
+  `rounded-full border px-4 py-1.5 text-sm font-medium transition-colors ${
+    active
+      ? "border-primary bg-primary text-primary-foreground"
+      : "border-border text-foreground hover:bg-secondary"
+  }`;
+
+export default function EventsView({
+  initialEvents,
+  emptyMessage = "No upcoming events — check back soon.",
+  eventHref,
+  LinkComponent,
+  CardComponent = EventCard,
+}: EventsViewProps) {
+  const { events, categories, activeCategoryId, setActiveCategoryId, error } = useEvents({
+    initialEvents,
+  });
+
+  return (
+    <div>
+      {categories.length > 1 && (
+        <div className="mb-8 flex flex-wrap gap-2" role="group" aria-label="Categories">
+          <button type="button" className={pill(activeCategoryId === null)} onClick={() => setActiveCategoryId(null)}>
+            All
+          </button>
+          {categories.map((c) => (
+            <button key={c.id} type="button" className={pill(activeCategoryId === c.id)} onClick={() => setActiveCategoryId(c.id)}>
+              {c.name}
+            </button>
+          ))}
+        </div>
+      )}
+      {error && <p className="mb-4 text-sm text-red-600">{error}</p>}
+      {events === null ? (
+        <div className="grid grid-cols-1 gap-8 sm:grid-cols-2 lg:grid-cols-3" aria-busy="true">
+          {Array.from({ length: 6 }, (_, i) => (
+            <div key={i}>
+              <div className="aspect-[3/2] animate-pulse rounded-lg bg-secondary" />
+              <div className="mt-3 h-3.5 w-2/3 animate-pulse rounded bg-secondary" />
+            </div>
+          ))}
+        </div>
+      ) : events.length === 0 ? (
+        <p className="py-16 text-center text-muted-foreground">{emptyMessage}</p>
+      ) : (
+        <div className="grid grid-cols-1 gap-8 sm:grid-cols-2 lg:grid-cols-3">
+          {events.map((e) => (
+            <CardComponent key={e.id} event={e} eventHref={eventHref} LinkComponent={LinkComponent} />
+          ))}
+        </div>
+      )}
+    </div>
+  );
+}

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

@@ -0,0 +1,117 @@
+// The whole registration state machine for one event, 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 hook orchestrates; you own how it looks.
+import { useEffect, useMemo, useState } from "react";
+import { fetchTicketTiers, startTicketCheckout, submitRsvp } from "../../wix/events/registration";
+import type { EventDetail, RegistrationResult, TicketTier } from "../../wix/events/types";
+
+export interface UseEventRegistration {
+  /** 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>;
+  /** Clamped to 0..limitPerCheckout; ignored for tiers not on sale (saleStatus gate). */
+  setQuantity: (tierId: string, quantity: number) => void;
+  ticketCount: number;
+  /** True when ≥ 1 ticket is selected — gate the checkout CTA on this. */
+  canCheckout: boolean;
+  /** Reserves + redirects to the Wix-hosted checkout. On "redirect" the browser is navigating. */
+  checkout: () => Promise<RegistrationResult>;
+  /** RSVP form state — the built-in fields, exactly these. */
+  rsvpValues: { firstName: string; lastName: string; email: string };
+  setRsvpValue: (field: "firstName" | "lastName" | "email", value: string) => void;
+  /** True when every RSVP field is filled — gate the RSVP CTA on this. */
+  canRsvp: boolean;
+  /** attending=false only when event.rsvpResponseType is "YES_AND_NO". */
+  rsvp: (attending?: boolean) => Promise<RegistrationResult>;
+  submitting: boolean;
+  /** Set after an RSVP completes (kind "rsvpConfirmed"; status may be "WAITLIST"). */
+  confirmed: RegistrationResult | null;
+  error: string | null;
+}
+
+export function useEventRegistration(event: EventDetail): UseEventRegistration {
+  const ticketed = event.registrationType === "TICKETING";
+  const [tiers, setTiers] = useState<TicketTier[] | null>(ticketed ? null : []);
+  const [quantities, setQuantities] = useState<Record<string, number>>({});
+  const [rsvpValues, setRsvpValues] = useState({ firstName: "", lastName: "", email: "" });
+  const [submitting, setSubmitting] = useState(false);
+  const [confirmed, setConfirmed] = useState<RegistrationResult | null>(null);
+  const [error, setError] = useState<string | null>(null);
+
+  useEffect(() => {
+    if (!ticketed) return;
+    let alive = true;
+    setTiers(null);
+    setQuantities({});
+    fetchTicketTiers(event.id)
+      .then((t) => alive && setTiers(t))
+      .catch((e) => {
+        if (!alive) return;
+        setTiers([]);
+        setError(e instanceof Error ? e.message : String(e));
+      });
+    return () => {
+      alive = false;
+    };
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [event.id, ticketed]);
+
+  const setQuantity = (tierId: string, quantity: number) => {
+    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));
+    setQuantities((q) => ({ ...q, [tierId]: clamped }));
+  };
+
+  const ticketCount = useMemo(
+    () => Object.values(quantities).reduce((sum, q) => sum + q, 0),
+    [quantities],
+  );
+  const canRsvp = (["firstName", "lastName", "email"] as const).every(
+    (f) => rsvpValues[f].trim().length > 0,
+  );
+
+  async function run(op: () => Promise<RegistrationResult>): Promise<RegistrationResult> {
+    setSubmitting(true);
+    setError(null);
+    try {
+      const result = await op();
+      if (result.kind === "redirect") {
+        window.location.href = result.url;
+      } else {
+        setConfirmed(result);
+      }
+      return result;
+    } catch (e) {
+      setError(e instanceof Error ? e.message : String(e));
+      throw e;
+    } finally {
+      setSubmitting(false);
+    }
+  }
+
+  return {
+    tiers,
+    quantities,
+    setQuantity,
+    ticketCount,
+    canCheckout: ticketCount > 0,
+    checkout: () =>
+      run(() =>
+        startTicketCheckout(
+          event,
+          Object.entries(quantities).map(([tierId, quantity]) => ({ tierId, quantity })),
+        ),
+      ),
+    rsvpValues,
+    setRsvpValue: (field, value) => setRsvpValues((v) => ({ ...v, [field]: value })),
+    canRsvp,
+    rsvp: (attending = true) => run(() => submitRsvp(event.id, rsvpValues, attending ? "YES" : "NO")),
+    submitting,
+    confirmed,
+    error,
+  };
+}

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

@@ -0,0 +1,59 @@
+// Events listing + category filter. SSR-friendly: pass server-fetched data as `initialEvents`
+// (Astro frontmatter / server component) and no client fetch happens; a SPA passes nothing.
+// The category menu is DERIVED from the loaded events (the categories management API is
+// admin-scope — visitors can't query it); filtering is client-side.
+import { useEffect, useMemo, useState } from "react";
+import { fetchEvents } from "../../wix/events/events";
+import type { EventSummary } from "../../wix/events/types";
+
+export interface UseEventsOptions {
+  initialEvents?: EventSummary[];
+}
+
+export interface UseEvents {
+  /** null while the first load is in flight — render skeletons, not an empty state. */
+  events: EventSummary[] | null;
+  /** Unique assigned categories in listing order — render a filter bar only when > 1. */
+  categories: { id: string; name: string }[];
+  activeCategoryId: string | null;
+  setActiveCategoryId: (id: string | null) => void;
+  error: string | null;
+}
+
+export function useEvents({ initialEvents }: UseEventsOptions = {}): UseEvents {
+  const [all, setAll] = useState<EventSummary[] | null>(initialEvents ?? null);
+  const [activeCategoryId, setActiveCategoryId] = useState<string | null>(null);
+  const [error, setError] = useState<string | null>(null);
+
+  useEffect(() => {
+    let alive = true;
+    if (!initialEvents) {
+      fetchEvents()
+        .then((e) => alive && setAll(e))
+        .catch((e) => {
+          if (!alive) return;
+          setAll([]);
+          setError(e instanceof Error ? e.message : String(e));
+        });
+    }
+    return () => {
+      alive = false;
+    };
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, []);
+
+  const categories = useMemo(() => {
+    const seen = new Map<string, string>();
+    for (const e of all ?? []) for (const c of e.categories) if (!seen.has(c.id)) seen.set(c.id, c.name);
+    return [...seen.entries()].map(([id, name]) => ({ id, name }));
+  }, [all]);
+
+  const events = useMemo(() => {
+    if (all === null) return null;
+    return activeCategoryId
+      ? all.filter((e) => e.categories.some((c) => c.id === activeCategoryId))
+      : all;
+  }, [all, activeCategoryId]);
+
+  return { events, categories, activeCategoryId, setActiveCategoryId, error };
+}

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

@@ -0,0 +1,136 @@
+// Event reads (Wix Events V3, the `wixEventsV2` module) — the only file that touches raw
+// event entities. Everything it returns is a plain DTO from ./types. Copy as-is; extend by
+// adding functions, not by editing these.
+// 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
+import { wixEventsV2 } from "@wix/events";
+import { wixModule } from "../sdk";
+import { imgSrc } from "../media";
+import type { EventDetail, EventSummary, RegistrationType } from "./types";
+
+const events = wixModule(wixEventsV2);
+
+/** The Wix Events app id (reference only — frontend calls need no app-id constant). */
+export const EVENTS_APP_ID = "140603ad-af8d-84a5-2c80-a0f60cb47351";
+
+type Raw = Record<string, any>;
+
+// Fieldsets are opt-in: without REGISTRATION there's no registration type to branch on;
+// without CATEGORIES the category names never arrive; DETAILS carries the formatted date
+// and mainImage; TEXTS carries the long description.
+const LIST_FIELDS = ["DETAILS", "REGISTRATION", "CATEGORIES"];
+const DETAIL_FIELDS = ["DETAILS", "TEXTS", "REGISTRATION", "URLS", "CATEGORIES"];
+
+function lowestPriceLabel(reg: Raw): string {
+  const type = reg.type ?? reg.initialType;
+  if (type === "RSVP") return "Free";
+  if (type !== "TICKETING") return "";
+  const lowest: Raw | undefined = reg.tickets?.lowestPrice;
+  if (!lowest) return "";
+  if (Number(lowest.value ?? 0) === 0) return "Free";
+  if (lowest.formattedValue) return `From ${lowest.formattedValue}`;
+  try {
+    return `From ${new Intl.NumberFormat(undefined, { style: "currency", currency: lowest.currency || "USD" }).format(Number(lowest.value))}`;
+  } catch {
+    return `From ${lowest.value} ${lowest.currency ?? ""}`.trim();
+  }
+}
+
+// event.description is Ricos rich content ({ nodes: [...] }), NOT a string — calling string
+// methods on it crashes the page. Extract plain paragraphs; detailedDescription (legacy plain
+// text) is the fallback.
+function toParagraphs(rich: Raw | undefined, legacy: string | undefined): string[] {
+  const collect = (nodes: Raw[] | undefined): string =>
+    (nodes ?? [])
+      .map((n: Raw) => (typeof n.textData?.text === "string" ? n.textData.text : collect(n.nodes)))
+      .join("");
+  const out: string[] = [];
+  for (const node of rich?.nodes ?? []) {
+    const text = collect([node]).trim();
+    if (text) out.push(text);
+  }
+  if (!out.length && legacy) out.push(legacy);
+  return out;
+}
+
+function toSummary(raw: Raw): EventSummary {
+  const reg: Raw = raw.registration ?? {};
+  const dts: Raw = raw.dateAndTimeSettings ?? {};
+  return {
+    id: raw._id ?? "", // _id, never .id — `id` is a REST-view field and is undefined here
+    slug: raw.slug ?? "",
+    title: raw.title ?? "",
+    shortDescription: raw.shortDescription ?? "",
+    dateLabel: dts.formatted?.dateAndTime ?? "",
+    startDateIso: dts.startDate ? new Date(dts.startDate).toISOString() : "",
+    locationName: raw.location?.name ?? "",
+    locationType: raw.location?.locationTbd
+      ? "TBD"
+      : ((raw.location?.type as "VENUE" | "ONLINE") ?? "TBD"),
+    imageUrl: imgSrc(raw.mainImage, 1200, 800),
+    // `type` is the current flavor (can become EXTERNAL later); initialType is the immutable
+    // seeded one — read type first.
+    registrationType: (reg.type ?? reg.initialType ?? "NONE") as RegistrationType,
+    priceLabel: lowestPriceLabel(reg),
+    soldOut: reg.tickets?.soldOut === true,
+    // `categories` is absent on the typed Event (an SDK type gap) — the Raw boundary reads
+    // the runtime field the CATEGORIES fieldset populates.
+    categories: (raw.categories?.categories ?? [])
+      .map((c: Raw) => ({ id: c._id ?? "", name: c.name ?? "" }))
+      .filter((c: { id: string }) => c.id),
+  };
+}
+
+function toDetail(raw: Raw): EventDetail {
+  const summary = toSummary(raw);
+  const reg: Raw = raw.registration ?? {};
+  return {
+    ...summary,
+    aboutParagraphs: toParagraphs(raw.description, raw.detailedDescription),
+    // Only OPEN_* statuses (OPEN_RSVP, OPEN_TICKETS, OPEN_EXTERNAL, …) accept registrations.
+    registrationOpen: typeof reg.status === "string" && reg.status.startsWith("OPEN_"),
+    rsvpResponseType: reg.rsvp?.responseType === "YES_AND_NO" ? "YES_AND_NO" : "YES_ONLY",
+    externalUrl: reg.external?.url ?? "",
+    addToCalendar: { google: raw.calendarUrls?.google ?? "", ics: raw.calendarUrls?.ics ?? "" },
+  };
+}
+
+/** List live (UPCOMING/STARTED) events, soonest first, mapped to grid-ready DTOs. */
+export async function fetchEvents({ limit = 100 } = {}): Promise<EventSummary[]> {
+  // The query builder, never a flat/REST `{ query: {...} }` body (the SDK silently ignores
+  // the unknown key and returns zero events). Always set a positive limit — it defaults to 0,
+  // which also returns zero events with no error.
+  const res = await events
+    .queryEvents({ fields: LIST_FIELDS as any })
+    .in("status", ["UPCOMING", "STARTED"]) // never list or link a past event — it isn't registerable
+    .ascending("dateAndTimeSettings.startDate")
+    .limit(limit)
+    .find();
+  return (res.items ?? []).map((e: Raw) => toSummary(e));
+}
+
+/** Fetch one event by its URL slug. Null when not found. */
+export async function fetchEventBySlug(slug: string): Promise<EventDetail | null> {
+  try {
+    // getEventBySlug returns a WRAPPED { event } — unlike getEvent below.
+    const res: Raw = await events.getEventBySlug(slug, { fields: DETAIL_FIELDS as any });
+    const raw = res?.event;
+    return raw ? toDetail(raw as Raw) : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Fetch one event by id — the post-checkout confirmation read (the thank-you URL carries
+ * `?orderNumber=&eventId=`). getEvent returns the Event DIRECTLY (unwrapped) — the one read
+ * that isn't `{ event }`; assuming the wrapper crashes the page.
+ */
+export async function fetchEventById(eventId: string): Promise<EventDetail | null> {
+  try {
+    const raw: Raw = await events.getEvent(eventId, { fields: DETAIL_FIELDS as any });
+    return raw?._id ? toDetail(raw) : null;
+  } catch {
+    return null;
+  }
+}