@wix/agent-skills 1.19.2 → 1.20.1

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

@@ -1,117 +1,35 @@
-// 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";
+// React binding of the registration store (wix/events/registration-store.ts) — the whole
+// registration state machine for one event lives there, framework-free, 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; you own how it looks. One store per event — a new event id gets a fresh one.
+import { useEffect, useRef, useSyncExternalStore } from "react";
+import {
+  createRegistrationStore,
+  type RegistrationState,
+  type RegistrationStore,
+} from "../../wix/events/registration-store";
+import type { EventDetail } 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 type UseEventRegistration = RegistrationState &
+  Pick<RegistrationStore, "setQuantity" | "setRsvpValue" | "checkout" | "rsvp">;
 
 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);
-
+  const key = `${event.id}:${event.registrationType}`;
+  const ref = useRef<{ key: string; store: RegistrationStore } | null>(null);
+  if (!ref.current || ref.current.key !== key) ref.current = { key, store: createRegistrationStore(event) };
+  const store = ref.current.store;
   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);
-    }
-  }
-
+    store.start();
+    return () => store.stop();
+  }, [store]);
+  const state = useSyncExternalStore(store.subscribe, store.getState, store.getState);
   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,
+    ...state,
+    setQuantity: store.setQuantity,
+    setRsvpValue: store.setRsvpValue,
+    checkout: store.checkout,
+    rsvp: store.rsvp,
   };
 }

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

@@ -1,59 +1,24 @@
-// 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";
+// React binding of the events store (wix/events/events-store.ts) — the listing state machine
+// lives there, framework-free; this hook subscribes to one instance per mounted listing and
+// exposes its state and actions under one name. SSR-friendly: pass server-fetched data as
+// `initialEvents` (Astro frontmatter / server component) and no client fetch happens; a SPA
+// passes nothing. Astro islands and React SPAs use this; a static page, Vue, or Svelte uses the
+// store directly.
+import { useEffect, useRef, useSyncExternalStore } from "react";
+import { createEventsStore, type EventsState, type EventsStore, type EventsStoreOptions } from "../../wix/events/events-store";
 
-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 type UseEventsOptions = EventsStoreOptions;
 
-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);
+export type UseEvents = EventsState & Pick<EventsStore, "setActiveCategoryId">;
 
+export function useEvents(options: UseEventsOptions = {}): UseEvents {
+  const ref = useRef<EventsStore | null>(null);
+  if (!ref.current) ref.current = createEventsStore(options);
+  const store = ref.current;
   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 };
+    store.start();
+    return () => store.stop();
+  }, [store]);
+  const state = useSyncExternalStore(store.subscribe, store.getState, store.getState);
+  return { ...state, setActiveCategoryId: store.setActiveCategoryId };
 }

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

@@ -0,0 +1,130 @@
+// Event rules and DTO mapping — transport-agnostic, imported by BOTH transports: ./events.ts (the
+// SDK, managed Astro and React) and the REST twin in references/events/rest/events.ts (fetch, a
+// static site or a port to another language). Every rule about statuses, fieldsets, prices,
+// dates, images and categories lives HERE, once. A raw event may come from the SDK (`_id`,
+// mainImage as a wix:image string) or from REST (`id`, mainImage as { id, url }); the mappers
+// accept both. Imports are type-only so a strip to JS emits no imports.
+import type { EventDetail, EventSummary, RegistrationType } from "./types";
+
+/** A raw Events V3 entity as either transport returns it. */
+export type Raw = Record<string, any>;
+/** Media value + size → https URL. Injected: the SDK transport scales through @wix/sdk, REST through the URL form. */
+export type ImgSrc = (value: any, width: number, height: number) => string;
+
+/** The Wix Events app id (reference only — frontend calls need no app-id constant). */
+export const EVENTS_APP_ID = "140603ad-af8d-84a5-2c80-a0f60cb47351";
+
+export const rawId = (raw: Raw | undefined | null): string => raw?._id ?? raw?.id ?? "";
+
+// 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; URLS the Wix event page url.
+export const LIST_FIELDS = ["DETAILS", "REGISTRATION", "CATEGORIES"] as const;
+export const DETAIL_FIELDS = ["DETAILS", "TEXTS", "REGISTRATION", "URLS", "CATEGORIES"] as const;
+
+/** Only these are listed and linked — a past or canceled event isn't registerable. */
+export const LIVE_STATUSES = ["UPCOMING", "STARTED"] as const;
+export const START_DATE_FIELD = "dateAndTimeSettings.startDate";
+
+/**
+ * The Query Events body for the listing: live statuses, soonest first, a positive limit.
+ * `paging.limit` defaults to 0 — a bare query answers `total: 2, events: []` with no error — so
+ * the limit is always sent. The SDK builder spells the same three parts.
+ */
+export function listQuery({ limit = 100 } = {}): Raw {
+  if (!Number.isInteger(limit) || limit < 1 || limit > 1000) throw new Error("limit must be between 1 and 1000.");
+  return {
+    filter: { status: { $in: [...LIVE_STATUSES] } },
+    sort: [{ fieldName: START_DATE_FIELD, order: "ASC" }],
+    paging: { limit },
+  };
+}
+
+/** "From €45" (ticketed), "Free" (RSVP / free tickets), "" when nothing applies. */
+export 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.
+export function toParagraphs(rich: Raw | undefined | null, 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;
+}
+
+/**
+ * The main image in the form imgSrc scales: the SDK carries it as a `wix:image://` string; REST
+ * as `{ id, url, altText }` — rebuilt into the id form so both transports resolve one URL shape.
+ */
+export function mainImageOf(raw: Raw): unknown {
+  const m = raw.mainImage;
+  if (m && typeof m === "object" && typeof m.id === "string" && m.id) {
+    return `wix:image://v1/${m.id}/${encodeURIComponent(String(m.altText || "image"))}`;
+  }
+  return m;
+}
+
+export function toSummary(raw: Raw, imgSrc: ImgSrc): EventSummary {
+  const reg: Raw = raw.registration ?? {};
+  const dts: Raw = raw.dateAndTimeSettings ?? {};
+  return {
+    id: rawId(raw), // _id on the SDK, id on REST — never a bare .id on the SDK (undefined there)
+    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(mainImageOf(raw), 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),
+    // The API reports tickets.soldOut true on an RSVP event too (it has no tickets at all) — sold
+    // out is a ticketing signal only.
+    soldOut: (reg.type ?? reg.initialType) === "TICKETING" && 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 ?? []) as Raw[])
+      .map((c) => ({ id: rawId(c), name: c.name ?? "" }))
+      .filter((c) => c.id),
+  };
+}
+
+export function toDetail(raw: Raw, imgSrc: ImgSrc): EventDetail {
+  const summary = toSummary(raw, imgSrc);
+  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 ?? "" },
+  };
+}

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

@@ -0,0 +1,97 @@
+// The events listing as a framework-free store — the logic behind useEvents, usable from React
+// (useEvents wraps it with useSyncExternalStore), from a static page or Vue/Svelte (subscribe and
+// render), or as the specification for a port. State, actions, subscribe/getState, emit after
+// every change.
+//
+// SSR-friendly: seed with `initialEvents` and they render at once with no client fetch; a SPA
+// passes nothing and `start()` fetches. 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
+// over the live list, which is small by definition (only UPCOMING/STARTED events are listed).
+//
+// One store per mounted listing (a page can hold the index and a "next up" rail):
+// createEventsStore(), not a singleton.
+import { fetchEvents } from "./events";
+import type { EventSummary } from "./types";
+
+export interface EventsStoreOptions {
+  initialEvents?: EventSummary[];
+}
+
+/** Everything a listing surface renders from. Read it with getState() or through a subscription. */
+export interface EventsState {
+  /** 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;
+  error: string | null;
+}
+
+export interface EventsStore {
+  getState(): EventsState;
+  subscribe(listener: () => void): () => void;
+  /** Fetch when no `initialEvents` were given. Call once when mounted (a browser). */
+  start(): void;
+  /** Stop reacting; drop a late response. */
+  stop(): void;
+  setActiveCategoryId(id: string | null): void;
+}
+
+export function createEventsStore({ initialEvents }: EventsStoreOptions = {}): EventsStore {
+  let all: EventSummary[] | null = initialEvents ?? null;
+  let activeCategoryId: string | null = null;
+  let error: string | null = null;
+  let started = false;
+  const listeners = new Set<() => void>();
+  let snapshot: EventsState | null = null;
+  const emit = () => {
+    snapshot = null;
+    for (const fn of listeners) fn();
+  };
+
+  function getState(): EventsState {
+    if (snapshot) return snapshot;
+    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);
+    snapshot = {
+      events: all === null ? null : activeCategoryId ? all.filter((e) => e.categories.some((c) => c.id === activeCategoryId)) : all,
+      categories: [...seen.entries()].map(([id, name]) => ({ id, name })),
+      activeCategoryId,
+      error,
+    };
+    return snapshot;
+  }
+
+  return {
+    getState,
+    subscribe(fn) {
+      listeners.add(fn);
+      return () => listeners.delete(fn);
+    },
+    start() {
+      if (started) return;
+      started = true;
+      if (initialEvents) return;
+      fetchEvents()
+        .then((list) => {
+          if (!started) return;
+          all = list;
+          emit();
+        })
+        .catch((e) => {
+          if (!started) return;
+          all = [];
+          error = e instanceof Error ? e.message : String(e);
+          emit();
+        });
+    },
+    stop() {
+      started = false;
+    },
+    setActiveCategoryId(id) {
+      if (id === activeCategoryId) return;
+      activeCategoryId = id;
+      emit();
+    },
+  };
+}

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

@@ -1,99 +1,18 @@
-// 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.
+// Event reads (Wix Events V3, the `wixEventsV2` module) over the SDK — the only file that touches
+// raw event entities on this transport. Everything it returns is a plain DTO from ./types. The
+// rules and mappers live in ./events-core (shared with the REST twin in references/events/rest/);
+// this file is the transport only. 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";
+import { DETAIL_FIELDS, EVENTS_APP_ID, LIST_FIELDS, LIVE_STATUSES, START_DATE_FIELD, rawId, toDetail, toSummary, type Raw } from "./events-core";
+import type { EventDetail, EventSummary } 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;
-}
+export { EVENTS_APP_ID };
 
-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 ?? "" },
-  };
-}
+const events = wixModule(wixEventsV2);
 
 /** List live (UPCOMING/STARTED) events, soonest first, mapped to grid-ready DTOs. */
 export async function fetchEvents({ limit = 100 } = {}): Promise<EventSummary[]> {
@@ -102,11 +21,11 @@ export async function fetchEvents({ limit = 100 } = {}): Promise<EventSummary[]>
   // 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")
+    .in("status", [...LIVE_STATUSES]) // never list or link a past event — it isn't registerable
+    .ascending(START_DATE_FIELD as any)
     .limit(limit)
     .find();
-  return (res.items ?? []).map((e: Raw) => toSummary(e));
+  return (res.items ?? []).map((e: Raw) => toSummary(e, imgSrc));
 }
 
 /** Fetch one event by its URL slug. Null when not found. */
@@ -115,7 +34,7 @@ export async function fetchEventBySlug(slug: string): Promise<EventDetail | null
     // 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;
+    return raw ? toDetail(raw as Raw, imgSrc) : null;
   } catch {
     return null;
   }
@@ -129,7 +48,7 @@ export async function fetchEventBySlug(slug: string): Promise<EventDetail | null
 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;
+    return rawId(raw) ? toDetail(raw, imgSrc) : null;
   } catch {
     return null;
   }