@wix/agent-skills 1.26.0 → 1.28.0

package/skills/wix-headless-templates/events/project/src/pages/events/[slug].astro

@@ -0,0 +1,104 @@
+---
+// 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. A recurring event lists its other dates (the same series, fetched here).
+import SiteLayout from "../../layouts/SiteLayout.astro";
+import EventRegistrationView from "../../components/events/EventRegistrationView";
+import { fetchEventBySlug, fetchOccurrences } from "../../wix/events/events";
+import type { EventSummary } from "../../wix/events/types";
+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 });
+}
+
+// Other dates of a recurring series (empty for a one-time event); guarded like every SSR read.
+let occurrences: EventSummary[] = [];
+if (event.recurringCategoryId) {
+  try {
+    occurrences = (await fetchOccurrences(event.recurringCategoryId)).filter((o) => o.id !== event.id);
+  } catch {
+    /* the page renders without the date list */
+  }
+}
+---
+
+<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.address && <p class="mt-0.5 text-sm text-muted-foreground">{event.address}</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>
+      ))}
+      {occurrences.length > 0 && (
+        <div class="mt-6">
+          <p class="eyebrow">Other dates</p>
+          <ul class="mt-2 space-y-1">
+            {occurrences.map((o) => (
+              <li>
+                <a href={`/events/${encodeURIComponent(o.slug)}`} class="text-sm text-foreground underline">{o.dateLabel || o.title}</a>
+              </li>
+            ))}
+          </ul>
+        </div>
+      )}
+    </div>
+    <div>
+      <EventRegistrationView client:only="react" event={event} />
+    </div>
+  </div>
+</SiteLayout>

package/skills/wix-headless-templates/events/project/src/pages/events.astro

@@ -0,0 +1,23 @@
+---
+// Events listing — the first page fetched SERVER-SIDE (SEO) and handed to the island as DTO
+// props; the island loads further pages and the category pills itself. Keep this frontmatter;
+// swap the island import to YOUR listing component.
+import SiteLayout from "../layouts/SiteLayout.astro";
+import EventsView from "../components/events/EventsView";
+import { fetchEventsPage } from "../wix/events/events";
+import type { EventSummary } from "../wix/events/types";
+
+let events: EventSummary[] = [];
+let total = 0;
+try {
+  ({ events, total } = await fetchEventsPage());
+} 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} initialTotal={total} />
+</SiteLayout>

package/skills/wix-headless-templates/events/project/src/pages/index.astro

@@ -0,0 +1,8 @@
+---
+import Hero from '../components/Hero.astro';
+import Layout from '../layouts/Layout.astro';
+---
+
+<Layout>
+	<Hero />
+</Layout>

package/skills/wix-headless-templates/events/project/src/styles/global.css

@@ -0,0 +1,57 @@
+@import url('https://fonts.googleapis.com/css2?family=Wix+Madefor+Text:wght@400;500;600;700;800&display=swap');
+@import 'tailwindcss';
+
+/* ─── THE design system ─────────────────────────────────────────────────────────────────
+   Theme the entire store by editing THIS @theme block (same token family as the official
+   Wix headless templates). Every shipped component styles itself from these via Tailwind
+   utilities (bg-primary, text-muted-foreground, text-destructive, rounded-lg, …) — change a token, everything
+   follows. A dark theme is just flipped values (dark background/foreground, adjusted
+   secondary/border). Don't restyle shipped component markup; restyle the tokens.
+
+   Choosing values: argue polarity from the business — light is not "cheap" (wellness/food
+   usually read better light); never dark-by-default for "premium". Palette: one dominant +
+   accents from ADJACENT hues (~30° arc), 2-4 colors total. Every background/foreground pair
+   you set must hit WCAG 4.5:1 (3:1 for text ≥24px); body copy never below 16px/1.5. Derive
+   from THIS brand — a look repeated across projects is a failure, not a shortcut. The user's
+   explicit direction beats all of this except the contrast floor. */
+@theme {
+  --color-background: hsl(0 0% 100%);
+  --color-foreground: hsl(230 24% 14%);
+  --color-primary: hsl(230 24% 14%);
+  --color-primary-foreground: hsl(0 0% 100%);
+  --color-secondary: hsl(228 24% 96%);
+  --color-secondary-foreground: hsl(230 24% 14%);
+  --color-muted-foreground: hsl(228 8% 46%);
+  --color-border: hsl(220 14% 90%);
+  --color-destructive: hsl(0 72% 51%);
+
+  --radius-lg: 12px;
+  --radius-md: 8px;
+  --radius-sm: 6px;
+  /* Buttons, chips, labels, steppers and the progress bar. Follows --radius-md unless the brand
+     wants otherwise: 9999px is the pill, 0 is square. Genuine circles (swatches, avatars, dots)
+     stay rounded-full and do not read this. */
+  --radius-control: var(--radius-md);
+
+  --font-sans: 'Wix Madefor Text', system-ui, sans-serif;
+}
+
+@layer base {
+  body {
+    background-color: var(--color-background);
+    color: var(--color-foreground);
+    font-family: var(--font-sans);
+    -webkit-font-smoothing: antialiased;
+    font-feature-settings: 'cv02', 'cv03', 'cv04', 'cv11';
+  }
+}
+
+@layer utilities {
+  .eyebrow {
+    font-size: 0.8125rem;
+    font-weight: 600;
+    letter-spacing: 0.1em;
+    text-transform: uppercase;
+    color: var(--color-muted-foreground);
+  }
+}

package/skills/wix-headless-templates/events/project/src/wix/config.ts

@@ -0,0 +1,16 @@
+// Wix connection config — written by the skill's deploy step (install/deploy.mjs).
+//
+// WIX_CLIENT_ID = null  → ambient auth (a Wix-managed Astro project: `@wix/astro` authenticates
+//                         every SDK call automatically; there is no client and nothing to set).
+// WIX_CLIENT_ID = "..." → manual visitor client (any other React setup): the public OAuth client id.
+//                         It is NOT a secret — it only mints anonymous visitor tokens — so
+//                         hardcoding and committing it is fine. deploy.mjs copies it from `.env.local`
+//                         (`WIX_CLIENT_ID`, what `wix env pull` writes): the CONTENT site's app — on a
+//                         migration preview the site being migrated, while wix.config.json names
+//                         only the deploy target.
+export const WIX_CLIENT_ID: string | null = null;
+
+// Kept for projects deployed before the Members vertical moved onto the shared seam; the shipped
+// members code no longer reads it (ambient Astro uses the built-in /api/auth routes, manual mode
+// uses the shared client above). deploy.mjs still fills it so older code keeps compiling.
+export const WIX_MEMBERS_CLIENT_ID: string | null = null;

package/skills/wix-headless-templates/events/project/src/wix/events/events-core.ts

@@ -0,0 +1,379 @@
+// Event rules and DTO mapping — transport-agnostic, imported by BOTH transports: ./events.ts (the
+// SDK, managed Astro and React) and the REST twin in templates/events/rest/events.ts (fetch, a
+// static site or a port to another language). Every rule about statuses, fieldsets, prices,
+// dates, images, categories, and the organizer's RSVP form lives HERE, once. A raw event may come
+// from the SDK (`_id`, mainImage as a wix:image string, Date objects) or from REST (`id`, mainImage
+// as { id, url }, ISO strings); the mappers accept both. Imports are type-only so a strip to JS
+// emits no imports.
+import type {
+  EventCategory,
+  EventDetail,
+  EventStatus,
+  EventSummary,
+  RegistrationStatus,
+  RegistrationType,
+  RsvpForm,
+  RsvpFormControl,
+  RsvpFormInput,
+  TaxSettings,
+} 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; FORM the
+// organizer's RSVP form (createRsvp validates submissions against it).
+export const LIST_FIELDS = ["DETAILS", "REGISTRATION", "CATEGORIES"] as const;
+export const DETAIL_FIELDS = ["DETAILS", "TEXTS", "REGISTRATION", "URLS", "CATEGORIES", "FORM"] as const;
+
+/** Default listing: only these are registerable. `past` is ENDED; `all` is the three (never CANCELED/DRAFT). */
+export const LIVE_STATUSES = ["UPCOMING", "STARTED"] as const;
+export const PAST_STATUSES = ["ENDED"] as const;
+export type StatusFilter = "upcoming" | "past" | "all";
+export function statusesFor(status: StatusFilter = "upcoming"): EventStatus[] {
+  if (status === "past") return [...PAST_STATUSES];
+  if (status === "all") return [...LIVE_STATUSES, ...PAST_STATUSES];
+  return [...LIVE_STATUSES];
+}
+
+export const START_DATE_FIELD = "dateAndTimeSettings.startDate";
+/** The stable secondary sort. The SDK spells it `_createdDate` and renames on the wire; REST is `createdDate`. */
+export const CREATED_DATE_FIELD_SDK = "_createdDate";
+export const CREATED_DATE_FIELD_REST = "createdDate";
+/** Server-side category filter field. SDK `categories._id` → REST `categories.id` (the same rename). */
+export const CATEGORY_ID_FIELD_SDK = "categories._id";
+export const CATEGORY_ID_FIELD_REST = "categories.id";
+/** Wix's page size; a listing loads more pages on demand. */
+export const DEFAULT_PAGE_SIZE = 20;
+
+export interface ListOptions {
+  /** Page size, 1..1000 (default 20). */
+  limit?: number;
+  /** Items to skip (default 0). */
+  offset?: number;
+  /** Server-side filter to one category (a manual category or a recurring series' id). */
+  categoryId?: string;
+  status?: StatusFilter;
+}
+
+/**
+ * The Query Events body for the listing in REST spelling: statuses, soonest first then newest
+ * first, a positive limit, an offset. `paging.limit` defaults to 0 — a bare query answers
+ * `total: N, events: []` with no error — so the limit is always sent. The SDK builder spells
+ * the same parts with `_createdDate` / `categories._id`.
+ */
+export function listQuery({ limit = DEFAULT_PAGE_SIZE, offset = 0, categoryId, status }: ListOptions = {}): Raw {
+  if (!Number.isInteger(limit) || limit < 1 || limit > 1000) throw new Error("limit must be between 1 and 1000.");
+  if (!Number.isInteger(offset) || offset < 0) throw new Error("offset must be a non-negative integer.");
+  const filter: Raw = { status: { $in: statusesFor(status) } };
+  if (categoryId) filter[CATEGORY_ID_FIELD_REST] = { $in: [categoryId] };
+  return {
+    filter,
+    sort: [
+      { fieldName: START_DATE_FIELD, order: "ASC" },
+      { fieldName: CREATED_DATE_FIELD_REST, order: "DESC" },
+    ],
+    paging: { limit, offset },
+  };
+}
+
+/** Query Categories body: only MANUAL categories (AUTO / RECURRING_EVENT / HIDDEN never become pills). */
+export const CATEGORY_STATES = ["MANUAL"] as const;
+export function categoriesQuery(): Raw {
+  return { filter: { states: { $hasSome: [...CATEGORY_STATES] } }, paging: { limit: 100 } };
+}
+
+/** How many more pages: a page is the last when offset + page length reaches the total. */
+export function hasMorePages(loaded: number, total: number | undefined | null): boolean {
+  return typeof total === "number" && loaded < total;
+}
+
+/**
+ * Format a decimal amount in a currency with the visitor's locale — the one money formatter for
+ * this vertical. No currency → the bare amount (never a made-up "$"). "" when there is no value.
+ */
+export function formatAmount(value: string | number | null | undefined, currency: string | null | undefined): string {
+  if (value == null || value === "") return "";
+  const n = Number(value);
+  if (!Number.isFinite(n)) return String(value);
+  if (!currency) return n.toFixed(2);
+  try {
+    return new Intl.NumberFormat(undefined, { style: "currency", currency }).format(n);
+  } catch {
+    return `${n.toFixed(2)} ${currency}`;
+  }
+}
+
+/** A Wix Money `{ value, amount (deprecated), currency }` → formatted string (value read before the deprecated amount). */
+export function formatMoney(money: Raw | null | undefined): string {
+  if (!money) return "";
+  return formatAmount(money.value ?? money.amount, money.currency);
+}
+
+/** Any date the API hands back (Date on the SDK, ISO string on REST) → ISO string, "" when absent/invalid. */
+export function isoOf(value: unknown): string {
+  if (!value) return "";
+  const d = new Date(value as string);
+  return Number.isNaN(d.getTime()) ? "" : d.toISOString();
+}
+
+/**
+ * A moment formatted in the EVENT's time zone (medium date + short time) — sale periods,
+ * registration openings. The browser's zone is wrong for a venue event; a missing/invalid zone
+ * falls back to the visitor's.
+ */
+export function formatInZone(value: unknown, timeZoneId: string | null | undefined): string {
+  const iso = isoOf(value);
+  if (!iso) return "";
+  const d = new Date(iso);
+  const opts: Intl.DateTimeFormatOptions = { dateStyle: "medium", timeStyle: "short" };
+  try {
+    return new Intl.DateTimeFormat(undefined, timeZoneId ? { ...opts, timeZone: timeZoneId } : opts).format(d);
+  } catch {
+    return new Intl.DateTimeFormat(undefined, opts).format(d);
+  }
+}
+
+/** "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 ?? lowest.amount ?? 0) === 0) return "Free";
+  const formatted = lowest.formattedValue || formatMoney(lowest);
+  return formatted ? `From ${formatted}` : "";
+}
+
+// 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. A description of one empty PARAGRAPH node (what the dashboard saves
+// for "no description") yields [] here, matching Wix's hasDescription() rule.
+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;
+}
+
+/** A category entity (Categories API or the event's CATEGORIES fieldset) → pill DTO. */
+export function toCategory(raw: Raw): EventCategory {
+  return { id: rawId(raw), name: raw.name ?? "" };
+}
+
+/**
+ * The event's assigned categories that are real, visitor-facing groupings: the CATEGORIES
+ * fieldset also lists the RECURRING_EVENT category every series gets and hidden ones — neither
+ * is a filter pill. (`type` and `hidden` per the SDK's EventCategory.)
+ */
+export function manualCategories(raw: Raw): EventCategory[] {
+  return ((raw.categories?.categories ?? []) as Raw[])
+    .filter((c) => c.type !== "RECURRING_EVENT" && c.hidden !== true)
+    .map(toCategory)
+    .filter((c) => c.id);
+}
+
+/** Categories from Query Categories, MANUAL only (the query already filters; this is the safety net). */
+export function toCategories(list: Raw[] | undefined): EventCategory[] {
+  return (list ?? [])
+    .filter((c) => !Array.isArray(c.states) || c.states.includes("MANUAL"))
+    .map(toCategory)
+    .filter((c) => c.id);
+}
+
+export function toSummary(raw: Raw, imgSrc: ImgSrc): EventSummary {
+  const reg: Raw = raw.registration ?? {};
+  const dts: Raw = raw.dateAndTimeSettings ?? {};
+  const dateTbd = dts.dateAndTimeTbd === true;
+  const registrationType = (reg.type ?? reg.initialType ?? "NONE") as RegistrationType;
+  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 ?? "",
+    status: (raw.status ?? "UPCOMING") as EventStatus,
+    // Wix's server-formatted schedule (site locale, event zone); the organizer's TBD message when there is no date.
+    dateLabel: dateTbd ? dts.dateAndTimeTbdMessage || dts.formatted?.dateAndTime || "" : (dts.formatted?.dateAndTime ?? ""),
+    startDateIso: dateTbd ? "" : isoOf(dts.startDate),
+    endDateIso: dateTbd ? "" : isoOf(dts.endDate),
+    timeZoneId: dts.timeZoneId ?? "",
+    dateTbd,
+    dateTbdMessage: dts.dateAndTimeTbdMessage ?? "",
+    hideEndDate: dts.hideEndDate === true,
+    showTimeZone: dts.showTimeZone !== false,
+    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,
+    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: registrationType === "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: manualCategories(raw),
+    recurrenceStatus: dts.recurrenceStatus ?? "ONE_TIME",
+    recurringCategoryId: dts.recurringEvents?.categoryId ?? "",
+  };
+}
+
+const INPUT_TYPES = new Set(["TEXT", "NUMBER", "TEXT_ARRAY", "DATE_TIME", "ADDRESS"]);
+
+function toFormInput(raw: Raw): RsvpFormInput {
+  const type = INPUT_TYPES.has(raw.type) ? raw.type : raw.array === true ? "TEXT_ARRAY" : "TEXT";
+  return {
+    name: raw.name ?? "",
+    label: raw.label ?? raw.name ?? "",
+    mandatory: raw.mandatory === true,
+    type,
+    options: Array.isArray(raw.options) ? raw.options.map(String) : [],
+    maxLength: Number(raw.maxLength) > 0 ? Number(raw.maxLength) : 0,
+  };
+}
+
+/**
+ * The organizer's RSVP form from the FORM fieldset. createRsvp validates `form.inputValues`
+ * against `form.controls[].inputs`: an unknown input name, a missing mandatory value (for a YES),
+ * or a value outside the predefined options is INVALID_FORM_RESPONSE — so the form is rendered
+ * from this, never hardcoded. Deleted controls are skipped; controls keep `orderIndex` order.
+ * GUEST_CONTROL is lifted out: its answer travels as `additionalGuestDetails`, not as an input
+ * value (the Create RSVP contract). Its max is read from the count input's numeric options, else
+ * the names input's `maxSize`.
+ */
+export function toRsvpForm(form: Raw | undefined | null): RsvpForm | null {
+  if (!form || !Array.isArray(form.controls)) return null;
+  const live = (form.controls as Raw[])
+    .filter((c) => c.deleted !== true)
+    .slice()
+    .sort((a, b) => (a.orderIndex ?? 0) - (b.orderIndex ?? 0));
+  const controls: RsvpFormControl[] = [];
+  let guestControl: RsvpForm["guestControl"] = null;
+  for (const c of live) {
+    const inputs = ((c.inputs ?? []) as Raw[]).map(toFormInput).filter((i) => i.name);
+    if (c.type === "GUEST_CONTROL") {
+      const count = inputs.find((i) => i.type === "NUMBER") ?? inputs[0];
+      const names = inputs.find((i) => i.type === "TEXT_ARRAY");
+      const numeric = (count?.options ?? []).map(Number).filter((n) => Number.isFinite(n));
+      const fromOptions = numeric.length ? Math.max(...numeric) : 0;
+      const rawNames = ((c.inputs ?? []) as Raw[]).find((i) => i.type === "TEXT_ARRAY" || i.array === true);
+      const maxGuests = fromOptions || Number(rawNames?.maxSize ?? 0) || 0;
+      guestControl = { label: count?.label ?? "Guests", maxGuests, namesLabel: names?.label ?? "Guest names" };
+      continue;
+    }
+    controls.push({ id: rawId(c) || c.name || `${controls.length}`, type: c.type ?? "INPUT", system: c.system === true, inputs });
+  }
+  return { controls, guestControl };
+}
+
+/** `registration.tickets.taxSettings` → DTO (null when the organizer configured no tax). */
+export function toTaxSettings(ts: Raw | undefined | null): TaxSettings | null {
+  if (!ts || !ts.type) return null;
+  const rate = Number(ts.rate);
+  return {
+    name: ts.name ?? "Tax",
+    ratePercent: Number.isFinite(rate) ? rate : 0,
+    includedInPrice: ts.type === "INCLUDED_IN_PRICE",
+    appliedToDonations: ts.appliedToDonations === true,
+  };
+}
+
+/** The venue's one-line address: Wix's `formatted` (a runtime field), else the parts joined. */
+export function formattedAddress(address: Raw | undefined | null): string {
+  if (!address) return "";
+  if (typeof address.formatted === "string" && address.formatted) return address.formatted;
+  if (typeof address.formattedAddress === "string" && address.formattedAddress) return address.formattedAddress;
+  return [address.addressLine1 ?? address.addressLine, address.addressLine2, address.city, address.subdivision, address.postalCode, address.country]
+    .filter((p) => typeof p === "string" && p.trim())
+    .join(", ");
+}
+
+/** Coordinates when Wix geocoded the venue (`address.location` on events; `geocode` on ticket definitions). */
+export function coordinatesOf(address: Raw | undefined | null): { lat: number; lng: number } | null {
+  const geo: Raw | undefined = address?.location ?? address?.geocode;
+  const lat = Number(geo?.latitude);
+  const lng = Number(geo?.longitude);
+  return Number.isFinite(lat) && Number.isFinite(lng) && (lat !== 0 || lng !== 0) ? { lat, lng } : null;
+}
+
+/** A Wix PageUrl: the SDK hands a string; REST hands `{ base, path }` (joined the way the SDK does). */
+export function pageUrlOf(value: unknown): string {
+  if (!value) return "";
+  if (typeof value === "string") return value;
+  const v = value as Raw;
+  if (typeof v.base !== "string") return "";
+  const base = /^https?:\/\//.test(v.base) ? v.base : `https://${v.base}`;
+  return `${base}${v.path ?? ""}`;
+}
+
+export function toDetail(raw: Raw, imgSrc: ImgSrc): EventDetail {
+  const summary = toSummary(raw, imgSrc);
+  const reg: Raw = raw.registration ?? {};
+  const status = (typeof reg.status === "string" ? reg.status : "UNKNOWN_REGISTRATION_STATUS") as RegistrationStatus;
+  const paused = reg.registrationPaused === true || reg.registrationDisabled === true;
+  const opensAt = status === "SCHEDULED_RSVP" ? isoOf(reg.rsvp?.startDate) : "";
+  const formatted: Raw = raw.dateAndTimeSettings?.formatted ?? {};
+  const limit = Number(reg.tickets?.ticketLimitPerOrder);
+  return {
+    ...summary,
+    aboutParagraphs: toParagraphs(raw.description, raw.detailedDescription),
+    formatted: {
+      startDate: formatted.startDate ?? "",
+      startTime: formatted.startTime ?? "",
+      endDate: formatted.endDate ?? "",
+      endTime: formatted.endTime ?? "",
+    },
+    address: summary.locationType === "VENUE" ? formattedAddress(raw.location?.address) : "",
+    coordinates: summary.locationType === "VENUE" ? coordinatesOf(raw.location?.address) : null,
+    registrationStatus: status,
+    // Wix: closed is exactly the two CLOSED_* statuses. Open = an OPEN_* status the organizer hasn't paused;
+    // SCHEDULED_RSVP is neither (it opens at rsvp.startDate).
+    registrationOpen: status.startsWith("OPEN_") && !paused && summary.registrationType !== "NONE",
+    registrationClosed: status === "CLOSED_MANUALLY" || status === "CLOSED_AUTOMATICALLY",
+    registrationOpensAtIso: opensAt,
+    registrationOpensAtLabel: formatInZone(opensAt, summary.timeZoneId),
+    registrationPaused: paused && status.startsWith("OPEN_"),
+    waitlistOnly: status === "OPEN_RSVP_WAITLIST_ONLY",
+    membersOnly: reg.allowedGuestTypes === "MEMBER",
+    rsvpResponseType: reg.rsvp?.responseType === "YES_AND_NO" ? "YES_AND_NO" : "YES_ONLY",
+    rsvpForm: summary.registrationType === "RSVP" ? toRsvpForm(raw.form) : null,
+    externalUrl: reg.external?.url ?? "",
+    eventPageUrl: pageUrlOf(raw.eventPageUrl),
+    addToCalendar: { google: raw.calendarUrls?.google ?? "", ics: raw.calendarUrls?.ics ?? "" },
+    taxSettings: toTaxSettings(reg.tickets?.taxSettings),
+    // Wix default 20, max 50 — the reservation rejects a larger order with an opaque error.
+    ticketLimitPerOrder: Number.isInteger(limit) && limit > 0 ? Math.min(limit, 50) : 20,
+  };
+}