@wix/agent-skills 1.15.0 → 1.16.0

package/skills/wix-vibe-headless/references/events/app/components/EventCard.jsx

@@ -0,0 +1,43 @@
+// Grid tile for one event. Styled with base44 design tokens (shadcn Tailwind classes) — re-skin via
+// those tokens (src/index.css :root/.dark), not this JSX. The date/location/teaser field paths and
+// the TICKETING "from" price are load-bearing: lowestPrice is a Money object { value, currency,
+// formattedValue } — render formattedValue, NEVER the raw object (React "objects are not valid as a
+// child" crash). This is a different shape from the ticket-definition price (pricing.fixedPrice.amount)
+// used in the picker.
+import { Link } from "react-router-dom";
+
+export default function EventCard({ event }) {
+  const when = event.dateAndTimeSettings?.formatted?.dateAndTime;
+  const where = event.location?.name;
+  const isTicketing = event.registration?.type === "TICKETING";
+  const fromPrice = event.registration?.tickets?.lowestPrice?.formattedValue;
+  const soldOut = event.registration?.tickets?.soldOut;
+  const image = event.mainImage?.url;
+
+  return (
+    <Link to={`/events/${event.slug}`}
+      className="flex flex-col no-underline text-foreground bg-card border border-border rounded-lg overflow-hidden shadow-sm">
+      <div className="relative aspect-[3/2] bg-background">
+        {image
+          ? <img src={image} alt={event.title} loading="lazy" className="w-full h-full object-cover" />
+          : <div className="w-full h-full bg-muted flex items-center justify-center" aria-hidden="true"><svg viewBox="0 0 24 24" className="w-8 h-8 text-muted-foreground/40" fill="none" stroke="currentColor" strokeWidth="1.5"><rect x="3" y="3" width="18" height="18" rx="2" /><circle cx="8.5" cy="8.5" r="1.5" /><path d="m21 15-5-5L5 21" /></svg></div>}
+        {isTicketing && soldOut && (
+          <span className="absolute top-2 left-2 py-0.5 px-2 text-xs bg-destructive text-destructive-foreground rounded-sm">Sold out</span>
+        )}
+      </div>
+      <div className="p-3 flex flex-col gap-1">
+        <h3 className="m-0 font-display text-base font-semibold">{event.title}</h3>
+        {when && <span className="text-muted-foreground text-[13px]">{when}</span>}
+        {where && <span className="text-muted-foreground text-[13px]">{where}</span>}
+        {event.shortDescription && (
+          <p className="m-0 mt-1 text-muted-foreground text-sm leading-[1.4]">
+            {event.shortDescription}
+          </p>
+        )}
+        {isTicketing && !soldOut && fromPrice && (
+          <span className="mt-1 font-semibold text-primary">From {fromPrice}</span>
+        )}
+      </div>
+    </Link>
+  );
+}

package/skills/wix-vibe-headless/references/events/app/components/EventGrid.jsx

@@ -0,0 +1,13 @@
+// Responsive event grid + empty state. Styled with base44 design tokens (shadcn Tailwind classes).
+import EventCard from "./EventCard";
+
+export default function EventGrid({ events, empty = "No events yet." }) {
+  if (!events?.length) {
+    return <p className="text-muted-foreground p-4 text-center">{empty}</p>;
+  }
+  return (
+    <div className="grid gap-4 [grid-template-columns:repeat(auto-fill,minmax(280px,1fr))]">
+      {events.map((e) => <EventCard key={e.id} event={e} />)}
+    </div>
+  );
+}

package/skills/wix-vibe-headless/references/events/app/components/EventRegistration.jsx

@@ -0,0 +1,29 @@
+// Registration surface for the detail page — branches on registration.type and respects `open`
+// (only OPEN_* statuses accept new registrations). Pure UI; the RSVP/ticketing logic lives in their
+// own hooks/components. Styled with base44 design tokens (shadcn Tailwind classes).
+import RsvpForm from "./RsvpForm";
+import TicketPicker from "./TicketPicker";
+
+const closed = "text-destructive font-semibold";
+const link = "inline-block py-3 px-6 no-underline bg-primary text-primary-foreground border-none rounded-sm text-[15px] font-semibold";
+
+export default function EventRegistration({ event, type, open, registration }) {
+  if (type === "EXTERNAL") {
+    return registration.external?.url
+      ? <a href={registration.external.url} target="_blank" rel="noopener" className={link}>Register</a>
+      : null;
+  }
+  if (type === "NONE") return null;
+
+  if (type === "RSVP") {
+    return open
+      ? <RsvpForm eventId={event.id} responseType={registration.rsvp?.responseType} />
+      : <p className={closed}>Registration is closed.</p>;
+  }
+  if (type === "TICKETING") {
+    return open
+      ? <TicketPicker event={event} />
+      : <p className={closed}>Ticket sales are closed.</p>;
+  }
+  return null;
+}

package/skills/wix-vibe-headless/references/events/app/components/RsvpForm.jsx

@@ -0,0 +1,57 @@
+// RSVP form for an RSVP-type event. Pure UI over useRsvpForm — no data logic here. Styled with
+// base44 design tokens (shadcn Tailwind classes). Offers a "NO" reply only when responseType is
+// "YES_AND_NO"; a WAITLIST result (event full) is surfaced distinctly from a confirmed YES.
+import { useRsvpForm } from "@/hooks/useRsvpForm";
+
+const input = "w-full px-3 py-2.5 box-border font-body border border-input rounded-sm bg-background text-foreground";
+const label = "block mb-1.5 text-[13px] font-semibold text-muted-foreground";
+const field = "mb-4";
+
+export default function RsvpForm({ eventId, responseType }) {
+  const { form, setField, submit, submitting, canSubmit, result, error } = useRsvpForm(eventId);
+
+  if (result) {
+    const waitlisted = result.status === "WAITLIST";
+    return (
+      <div className="p-4 rounded-lg bg-card border border-border text-foreground">
+        {waitlisted
+          ? "This event is full — you've been added to the waitlist. We'll email you if a spot opens."
+          : "You're on the list! A confirmation is on its way to your email."}
+      </div>
+    );
+  }
+
+  return (
+    <form onSubmit={(e) => { e.preventDefault(); submit(); }} className="max-w-[440px]">
+      <div className={field}>
+        <label className={label}>First name</label>
+        <input className={input} value={form.firstName} onChange={(e) => setField("firstName", e.target.value)} required />
+      </div>
+      <div className={field}>
+        <label className={label}>Last name</label>
+        <input className={input} value={form.lastName} onChange={(e) => setField("lastName", e.target.value)} required />
+      </div>
+      <div className={field}>
+        <label className={label}>Email</label>
+        <input className={input} type="email" value={form.email} onChange={(e) => setField("email", e.target.value)} required />
+      </div>
+
+      {responseType === "YES_AND_NO" && (
+        <div className={field}>
+          <label className={label}>Will you attend?</label>
+          <select className={input} value={form.status} onChange={(e) => setField("status", e.target.value)}>
+            <option value="YES">Yes, I'll be there</option>
+            <option value="NO">No, I can't make it</option>
+          </select>
+        </div>
+      )}
+
+      {error && <p className="text-destructive mb-4">{error}</p>}
+
+      <button type="submit" disabled={!canSubmit}
+        className="py-3 px-6 cursor-pointer bg-primary text-primary-foreground border-none rounded-sm text-[15px] font-semibold disabled:opacity-50 disabled:cursor-not-allowed">
+        {submitting ? "Sending…" : "RSVP"}
+      </button>
+    </form>
+  );
+}

package/skills/wix-vibe-headless/references/events/app/components/TicketPicker.jsx

@@ -0,0 +1,78 @@
+// Ticket picker for a TICKETING event. Pure UI over useTicketing — no data logic here. Styled with
+// base44 design tokens (shadcn Tailwind classes).
+//   • Ticket-definition price is a plain number at pricing.fixedPrice.amount (+ price.currency here).
+//   • FREE-only selection → an in-app buyer form + checkoutTickets (no redirect).
+//   • Any PAID ticket → "Continue to checkout", which reserves then redirects to the Wix-hosted form.
+import { useState } from "react";
+import { useTicketing } from "@/hooks/useTicketing";
+
+const input = "px-3 py-2.5 box-border font-body border border-input rounded-sm bg-background text-foreground";
+
+function ticketPrice(def) {
+  if (def.free) return "Free";
+  const amount = def.price?.amount ?? def.pricing?.fixedPrice?.amount;
+  const currency = def.price?.currency ?? def.pricing?.fixedPrice?.currency ?? "";
+  return amount != null ? `${amount} ${currency}`.trim() : "";
+}
+
+export default function TicketPicker({ event }) {
+  const t = useTicketing(event);
+  const [buyer, setBuyer] = useState({ firstName: "", lastName: "", email: "" });
+  const setBuyerField = (k, v) => setBuyer((b) => ({ ...b, [k]: v }));
+
+  if (t.order) {
+    return (
+      <div className="p-4 rounded-lg bg-card border border-border">
+        Your tickets are confirmed.{" "}
+        {t.order.ticketsPdf && (
+          <a href={t.order.ticketsPdf} target="_blank" rel="noopener" className="text-primary">Download tickets (PDF)</a>
+        )}
+      </div>
+    );
+  }
+
+  if (!t.definitions.length) {
+    return <p className="text-muted-foreground">No tickets are currently on sale.</p>;
+  }
+
+  const buyerReady = buyer.firstName && buyer.lastName && buyer.email;
+
+  return (
+    <div>
+      {t.definitions.map((def) => (
+        <div key={def.id} className="flex items-center justify-between gap-4 py-3 border-b border-border">
+          <div>
+            <div className="font-semibold">{def.name}</div>
+            {def.description && <div className="text-muted-foreground text-sm">{def.description}</div>}
+            <div className="text-primary font-semibold mt-0.5">{ticketPrice(def)}</div>
+          </div>
+          <input type="number" min={0} value={t.selection[def.id]?.quantity ?? 0}
+            onChange={(e) => t.setQuantity(def.id, Number(e.target.value) || 0)}
+            className={`${input} w-[72px] text-center`} />
+        </div>
+      ))}
+
+      {t.error && <p className="text-destructive mt-4">{t.error}</p>}
+
+      {t.hasSelection && t.allFree && (
+        <div className="mt-4 grid gap-2 max-w-[440px]">
+          <input className={`${input} w-full`} placeholder="First name" value={buyer.firstName}
+            onChange={(e) => setBuyerField("firstName", e.target.value)} />
+          <input className={`${input} w-full`} placeholder="Last name" value={buyer.lastName}
+            onChange={(e) => setBuyerField("lastName", e.target.value)} />
+          <input className={`${input} w-full`} type="email" placeholder="Email" value={buyer.email}
+            onChange={(e) => setBuyerField("email", e.target.value)} />
+        </div>
+      )}
+
+      {t.hasSelection && (
+        <button
+          disabled={t.submitting || (t.allFree && !buyerReady)}
+          onClick={() => (t.allFree ? t.checkoutFree(buyer) : t.checkoutPaid())}
+          className="mt-4 py-3 px-6 cursor-pointer bg-primary text-primary-foreground border-none rounded-sm text-[15px] font-semibold disabled:opacity-50 disabled:cursor-not-allowed">
+          {t.submitting ? "Processing…" : t.allFree ? "Get tickets" : "Continue to checkout"}
+        </button>
+      )}
+    </div>
+  );
+}

package/skills/wix-vibe-headless/references/events/app/hooks/useEventDetail.js

@@ -0,0 +1,27 @@
+// useEventDetail — load one event by slug and derive its registration state. No markup.
+//   • getEventBySlug returns null on miss → notFound (never invent an event).
+//   • registration.type is "RSVP" | "TICKETING" | "EXTERNAL" | "NONE" — the detail page branches on it.
+//   • Only registration.status values starting "OPEN_" accept new registrations; otherwise `open` is
+//     false and the page shows the closed state.
+//   • shortDescription is a plain string (safe to render). event.description is Ricos rich content
+//     { nodes: [...] } — NOT a string; render with @wix/ricos or walk nodes, never call string
+//     methods on it (that crashes the page). This hook does not touch description.
+import { useState, useEffect } from "react";
+import { getEventBySlug } from "@/rest/wix-events-browse";
+
+export function useEventDetail(slug) {
+  const [event, setEvent] = useState(null);
+  const [notFound, setNotFound] = useState(false);
+
+  useEffect(() => {
+    setEvent(null);
+    setNotFound(false);
+    getEventBySlug(slug).then((e) => (e ? setEvent(e) : setNotFound(true)));
+  }, [slug]);
+
+  const reg = event?.registration ?? {};
+  const type = reg.type ?? "NONE";
+  const open = typeof reg.status === "string" && reg.status.startsWith("OPEN_");
+
+  return { event, notFound, type, open, registration: reg };
+}

package/skills/wix-vibe-headless/references/events/app/hooks/useEventsList.js

@@ -0,0 +1,54 @@
+// useEventsList — all listing logic, no markup: load the category menu + upcoming count, list
+// events (all or filtered by category), and page with offset "load more". The data shapes here are
+// the bug-prone part — keep them verbatim; the Events page only renders what this returns.
+//   • queryEvents / listEventsByCategory return { events, total, offset, nextOffset } — an OBJECT,
+//     not a bare array; nextOffset is null when there are no more pages.
+//   • queryEventCategories returns { categories, total }; render category.name,
+//     key/filter by category.id, count = counts.assignedEventsCount.
+//   • total === 0 → the whole catalog is empty; show the "publish events" empty state.
+import { useState, useEffect } from "react";
+import {
+  queryEvents, listEventsByCategory, queryEventCategories, countUpcomingEvents,
+} from "@/rest/wix-events-browse";
+
+export function useEventsList({ pageSize = 24 } = {}) {
+  const [events, setEvents] = useState([]);
+  const [nextOffset, setNextOffset] = useState(null); // offset for the next page; null when no more
+  const [categories, setCategories] = useState([]);   // category menu
+  const [active, setActive] = useState(null);          // selected category id, or null for "all"
+  const [total, setTotal] = useState(null);            // upcoming count across the whole catalog
+  const [loading, setLoading] = useState(true);
+
+  useEffect(() => {
+    countUpcomingEvents().then(setTotal);
+    queryEventCategories().then(({ categories }) => setCategories(categories));
+  }, []);
+
+  useEffect(() => {
+    setLoading(true);
+    const load = active
+      ? listEventsByCategory(active, { limit: pageSize })
+      : queryEvents({ limit: pageSize });
+    load.then(({ events, nextOffset }) => {
+      setEvents(events);
+      setNextOffset(nextOffset);
+      setLoading(false);
+    });
+  }, [active, pageSize]);
+
+  const loadMore = () => {
+    if (nextOffset === null) return;
+    const load = active
+      ? listEventsByCategory(active, { limit: pageSize, offset: nextOffset })
+      : queryEvents({ limit: pageSize, offset: nextOffset });
+    load.then(({ events: more, nextOffset: next }) => {
+      setEvents((e) => [...e, ...more]);
+      setNextOffset(next);
+    });
+  };
+
+  return {
+    events, categories, active, setActive,
+    total, loading, hasMore: nextOffset !== null, loadMore,
+  };
+}

package/skills/wix-vibe-headless/references/events/app/hooks/useRsvpForm.js

@@ -0,0 +1,40 @@
+// useRsvpForm — RSVP submission logic for an RSVP-type event, no markup.
+//   • createRsvp(eventId, { firstName, lastName, email, status, additionalGuestNames? }) completes
+//     fully client-side (no redirect) and throws on closed/full registration, guest-limit, duplicate
+//     email, or invalid form — surface the message, don't swallow it.
+//   • Only offer status "NO" when registration.rsvp.responseType === "YES_AND_NO".
+//   • A full-with-waitlist event returns the RSVP with status "WAITLIST" — tell the guest.
+import { useState } from "react";
+import { createRsvp } from "@/rest/wix-events-registration";
+
+export function useRsvpForm(eventId) {
+  const [form, setForm] = useState({ firstName: "", lastName: "", email: "", status: "YES" });
+  const [guests, setGuests] = useState([]); // additional guest names (strings)
+  const [submitting, setSubmitting] = useState(false);
+  const [result, setResult] = useState(null); // the created RSVP (carries .status) on success
+  const [error, setError] = useState(null);
+
+  const setField = (name, value) => setForm((f) => ({ ...f, [name]: value }));
+
+  async function submit() {
+    setSubmitting(true);
+    setError(null);
+    try {
+      const rsvp = await createRsvp(eventId, {
+        firstName: form.firstName,
+        lastName: form.lastName,
+        email: form.email,
+        status: form.status,
+        additionalGuestNames: guests.filter(Boolean),
+      });
+      setResult(rsvp); // rsvp.status is "YES" | "NO" | "WAITLIST"
+    } catch (e) {
+      setError(e.message);
+    } finally {
+      setSubmitting(false);
+    }
+  }
+
+  const canSubmit = !!(form.firstName && form.lastName && form.email) && !submitting;
+  return { form, setField, guests, setGuests, submit, submitting, canSubmit, result, error };
+}

package/skills/wix-vibe-headless/references/events/app/hooks/useTicketing.js

@@ -0,0 +1,81 @@
+// useTicketing — ticket selection + checkout logic for a TICKETING event, no markup.
+//   • queryTicketDefinitions(eventId) already returns only non-hidden, buyable (SALE_STARTED) tickets.
+//   • Ticket-definition price is a PLAIN number at pricing.fixedPrice.amount (+ currency) — a different
+//     shape from the card's registration.tickets.lowestPrice Money object.
+//   • reserveTickets([...]) holds the tickets (status PENDING) and throws if they aren't actually held.
+//   • PAID tickets: reserve → window.location = getTicketCheckoutUrl(event, reservationId) (the Wix-
+//     hosted ticket form collects guest details + payment). NEVER hand-build that URL.
+//   • FREE tickets only: reserve → checkoutTickets(eventId, { reservationId, buyer, guests }) finishes
+//     in-app and returns an order with status "FREE"; it throws for paid orders.
+import { useState, useEffect } from "react";
+import {
+  queryTicketDefinitions, reserveTickets, getTicketCheckoutUrl, checkoutTickets,
+} from "@/rest/wix-events-registration";
+
+export function useTicketing(event) {
+  const eventId = event?.id;
+  const [definitions, setDefinitions] = useState([]);
+  const [selection, setSelection] = useState({}); // { [defId]: { quantity, guestPrice?, pricingOptionId? } }
+  const [submitting, setSubmitting] = useState(false);
+  const [order, setOrder] = useState(null); // free-checkout order on success
+  const [error, setError] = useState(null);
+
+  useEffect(() => {
+    if (!eventId) return;
+    queryTicketDefinitions(eventId).then(setDefinitions);
+  }, [eventId]);
+
+  const setLine = (defId, patch) =>
+    setSelection((s) => ({ ...s, [defId]: { quantity: 0, ...s[defId], ...patch } }));
+  const setQuantity = (defId, quantity) => setLine(defId, { quantity: Math.max(0, quantity) });
+
+  const lines = Object.entries(selection)
+    .filter(([, l]) => l.quantity > 0)
+    .map(([ticketDefinitionId, l]) => ({
+      ticketDefinitionId,
+      quantity: l.quantity,
+      guestPrice: l.guestPrice,
+      pricingOptionId: l.pricingOptionId,
+    }));
+
+  const hasSelection = lines.length > 0;
+  const allFree = hasSelection && lines.every((l) => definitions.find((d) => d.id === l.ticketDefinitionId)?.free);
+
+  // PAID (or mixed): reserve then hand off to the Wix-hosted ticket form.
+  async function checkoutPaid() {
+    setSubmitting(true);
+    setError(null);
+    try {
+      const reservation = await reserveTickets(lines);
+      window.location.href = getTicketCheckoutUrl(event, reservation.id);
+    } catch (e) {
+      setError(e.message);
+      setSubmitting(false);
+    }
+  }
+
+  // FREE tickets only: reserve then finish in-app; buyer = { firstName, lastName, email }.
+  async function checkoutFree(buyer) {
+    setSubmitting(true);
+    setError(null);
+    try {
+      const reservation = await reserveTickets(lines);
+      const created = await checkoutTickets(eventId, {
+        reservationId: reservation.id,
+        buyer,
+        guests: [{ firstName: buyer.firstName, lastName: buyer.lastName, email: buyer.email }],
+      });
+      setOrder(created); // status "FREE"; carries ticketsPdf + tickets[]
+    } catch (e) {
+      setError(e.message);
+    } finally {
+      setSubmitting(false);
+    }
+  }
+
+  return {
+    definitions, selection, setQuantity, setLine,
+    hasSelection, allFree, submitting, order, error,
+    checkoutPaid, checkoutFree,
+  };
+}

package/skills/wix-vibe-headless/references/events/app/pages/EventDetail.jsx

@@ -0,0 +1,48 @@
+// Event detail page — thin view over useEventDetail (all logic lives in the hook). Renders the
+// event summary + the registration surface. Styled with base44 design tokens (shadcn Tailwind classes).
+//
+// shortDescription is a PLAIN string (safe to render). event.description is Ricos rich content
+// { nodes: [...] } — NOT a string; to show the full body render it with @wix/ricos or walk `nodes`.
+// NEVER call string methods (.slice/.substring/.split) on event.description — that crashes the page.
+import { useParams } from "react-router-dom";
+import { useEventDetail } from "@/hooks/useEventDetail";
+import EventRegistration from "@/components/EventRegistration";
+
+export default function EventDetail() {
+  const { slug } = useParams();
+  const d = useEventDetail(slug);
+
+  if (d.notFound) return <Centered>Event not found.</Centered>;
+  if (!d.event) return <Centered>Loading…</Centered>;
+
+  const { event } = d;
+  const when = event.dateAndTimeSettings?.formatted?.dateAndTime;
+  const where = event.location?.name;
+
+  return (
+    <main className="max-w-[1200px] mx-auto p-4 grid gap-8 [grid-template-columns:repeat(auto-fit,minmax(320px,1fr))]">
+      <div className="aspect-[3/2] bg-card rounded-lg overflow-hidden">
+        {event.mainImage?.url &&
+          <img src={event.mainImage.url} alt={event.title} className="w-full h-full object-cover" />}
+      </div>
+
+      <div>
+        <h1 className="font-display m-0 mb-2">{event.title}</h1>
+        {when && <p className="m-0 mb-1 text-muted-foreground">{when}</p>}
+        {where && <p className="m-0 mb-4 text-muted-foreground">{where}</p>}
+
+        {event.shortDescription && (
+          <p className="text-foreground leading-relaxed mb-6">
+            {event.shortDescription}
+          </p>
+        )}
+
+        <EventRegistration event={event} type={d.type} open={d.open} registration={d.registration} />
+      </div>
+    </main>
+  );
+}
+
+function Centered({ children }) {
+  return <div className="p-12 text-center text-muted-foreground">{children}</div>;
+}

package/skills/wix-vibe-headless/references/events/app/pages/Events.jsx

@@ -0,0 +1,36 @@
+// Events listing page — category menu + grid + empty state + load more. Thin view over
+// useEventsList (all logic lives in the hook). Styled with base44 design tokens (shadcn Tailwind classes).
+import { useEventsList } from "@/hooks/useEventsList";
+import CategoryFilter from "@/components/CategoryFilter";
+import EventGrid from "@/components/EventGrid";
+
+export default function Events() {
+  const { events, categories, active, setActive, total, loading, hasMore, loadMore } = useEventsList();
+
+  return (
+    <main className="max-w-[1200px] mx-auto p-4">
+      <h1 className="font-display mb-4">Events</h1>
+
+      {total === 0 ? (
+        <p className="text-muted-foreground p-4 text-center">
+          No events published yet — add and publish events from your Wix dashboard.
+        </p>
+      ) : (
+        <>
+          <CategoryFilter categories={categories} active={active} onSelect={setActive} />
+          {loading
+            ? <p className="text-muted-foreground">Loading…</p>
+            : <EventGrid events={events} empty="No events in this category yet." />}
+          {hasMore && (
+            <div className="text-center mt-6">
+              <button onClick={loadMore}
+                className="py-2.5 px-6 cursor-pointer text-[15px] font-semibold bg-card text-foreground border border-border rounded-sm">
+                Load more
+              </button>
+            </div>
+          )}
+        </>
+      )}
+    </main>
+  );
+}

package/skills/wix-vibe-headless/references/events/{wix-events-browse.js → app/rest/wix-events-browse.js}

@@ -24,13 +24,14 @@ import { wixApiRequest } from "./wix-client.js";
  *     type {string} — "RSVP"|"TICKETING"|"EXTERNAL"|"NONE",
  *     status {string} — only OPEN_* statuses accept new registrations,
  *     rsvp.responseType — "YES_AND_NO" allows a "NO" reply,
- *     tickets.currency, tickets.lowestPrice, tickets.soldOut,
+ *     tickets.lowestPrice {object} — money { value, currency, formattedValue }; render
+ *       formattedValue, not the object (see "Money/price fields" in SKILL.md). tickets.soldOut {boolean},
  *     external.url — link out when type === "EXTERNAL",
  *   eventPageUrl {object} — { base, path } (URLS fieldset) — needed for getTicketCheckoutUrl,
  *   form {object} — registration form controls (FORM fieldset),
  *   calendarUrls {object} — { google, ics } (DETAILS fieldset)
  *
- * Category: { id, label, slug, counts.assignedEventsCount }
+ * Category: { id, name, counts.assignedEventsCount }
  * Full model: https://dev.wix.com/docs/api-reference/business-solutions/events/event-management/categories
  */
 

package/skills/wix-vibe-headless/references/events/seed/SEED.md

@@ -0,0 +1,107 @@
+# Events — seeding
+
+Seed Wix Events (Events V3) by **calling `seed-events.js`** — don't hand-write the REST calls. It's
+a build-time module (run via `exec_tool`, not shipped in the app) that abstracts every Wix Events
+seed operation. `require` it and call the functions with plain data.
+
+> **NOT yet live-verified — transcribed from `setup-events.md`.** Endpoints/fields are as written in
+> the recipe; if a live call disagrees, trust the docs (see Fallback).
+
+Two one-way constraints fix the order: `registration.initialType` (`TICKETING`/`RSVP`) is **immutable**
+after create, and **publishing is one-way**. So per event: create DRAFT → (ticketed) add tiers → publish.
+`setupEvents` **installs the Wix Events app first** (idempotent — a re-install returns 200), so seeding works even if the site doesn't have it yet.
+
+```js
+// build-time exec_tool
+const { accessToken } = await base44.asServiceRole.connectors.getConnection("wix"); // Base44 (generic: use $TOKEN)
+const fs = require("fs");
+// exec_tool's require can return EMPTY exports for these build-time modules — load the file itself:
+const seed = (() => { const m = { exports: {} };
+  new Function("module", "exports", "require", fs.readFileSync("/app/.agents/skills/wix-vibe-headless/references/events/seed/seed-events.js", "utf8"))(m, m.exports, require);
+  return m.exports; })();
+const ctx = { token: accessToken, siteId: WIX_METASITE_ID };
+
+// DEFAULT — one call runs the whole flow per event (create DRAFT → tiers → publish), then resolves
+// category NAMES → ids + assigns and attaches main images. Ids are kept in memory; nothing is
+// hand-threaded across exec calls. Dates MUST be in the future (ISO-8601 UTC); default ~60–90 days
+// out and note it if the request gives none. price is a decimal STRING; ticket name <= 30 chars;
+// omit ticketTiers for RSVP/free, omit imageUrl if you have none.
+const summary = await seed.setupEvents(ctx, {
+  events: [{
+    title: "Summer Synth Festival", shortDescription: "One night of analog sound.",
+    type: "TICKETING", startDate: "2026-10-01T03:30:00.000Z", endDate: "2026-10-01T07:00:00.000Z",
+    timeZoneId: "America/Los_Angeles",
+    location: { name: "The Echo Lot", type: "VENUE", address: { addressLine: "120 Harbor St", city: "Seattle", subdivision: "US-WA", postalCode: "98101", country: "US" } },
+    ticketTiers: [{ name: "General Admission", price: "65.00", initialLimit: 200 }],
+    category: "Talks",
+    // imageUrl is optional and attached IN this one call. Pass a plain url — the module imports it to
+    // Wix Media for you (events binds the main image by file id). Use the FINAL https://media.base44.com/...
+    // url from the COMPLETED generate_image (it runs in the background while you build — wait for it),
+    // never a still-generating /__generating__/<id>.png placeholder. altText defaults to the event slug.
+    imageUrl: "https://media.base44.com/…",
+  }],
+});
+// summary -> { events: [{ id, slug, ticketCount, category }], categories: [{ id, name }], imagesAttached }
+```
+
+**Seeding is additive — never delete or overwrite existing content.** Don't clean up, don't remove
+"sample" data, don't reset. Just add.
+
+## Escape hatch — individual functions
+Reach for the functions below only when the one-call `setupEvents` doesn't fit (re-running a single
+step, a shape it doesn't model). `setupEvents` is built from them, in this order:
+
+```js
+// STEP 1 — create each event as a DRAFT. TICKETING = paid tiers; RSVP = free built-in form (no fields to seed).
+const ev = await seed.createEvent(ctx, {
+  title: "Summer Synth Festival", shortDescription: "One night of analog sound.",
+  type: "TICKETING", startDate: "2026-10-01T03:30:00.000Z", endDate: "2026-10-01T07:00:00.000Z",
+  timeZoneId: "America/Los_Angeles",
+  location: { name: "The Echo Lot", type: "VENUE", address: { addressLine: "120 Harbor St", city: "Seattle", subdivision: "US-WA", postalCode: "98101", country: "US" } },
+});
+
+// STEP 2 — TICKETING only: add tiers BEFORE publish. price is a decimal STRING; name <= 30 chars; omit initialLimit for unlimited.
+const tiers = await seed.createTicketTiers(ctx, ev.id, [{ name: "General Admission", price: "65.00", initialLimit: 200 }]);
+
+// STEP 3 — publish (one-way; ticketed events only after tiers exist)
+await seed.publishEvent(ctx, ev.id);
+
+// STEP 4 (optional) — group by a format/track (v1 Categories)
+const cats = await seed.createEventCategories(ctx, ["Talks"]);
+await seed.assignEventsToCategory(ctx, cats[0].id, [ev.id]);
+
+// Attach images (optional): import the url to Wix Media (events binds by file id), then set mainImage.
+const file = await seed.importImage(ctx, imageUrl);   // → { id, url } (Wix Media file id + wixstatic url)
+await seed.setEventMainImage(ctx, { eventId: ev.id, id: file.id, url: file.url, height: 1024, width: 1024, altText: ev.slug });
+```
+
+**Paid-ticket precondition — record, do NOT block:** seeding succeeds and the event goes live
+regardless of payment setup, but *completing a paid purchase* later needs a premium plan **and** a
+configured payment method in the dashboard. Note it in the kept output; never fail the seed over it.
+Free/RSVP events need neither.
+
+## Functions
+| fn | does |
+|---|---|
+| `setupEvents(ctx, {events})` | **DEFAULT** — one call: per event create DRAFT → tiers → publish, then resolve category names → assign + attach images → `{events, categories, imagesAttached}` |
+| `createEvent(ctx, event)` | STEP 1 — create ONE draft event (no bulk; loop for many) → `{id, slug}` |
+| `createTicketTiers(ctx, eventId, tiers)` | STEP 2 — TICKETING only, parallel batch → `[{id}]` |
+| `publishEvent(ctx, eventId)` | STEP 3 — publish (one-way) |
+| `createEventCategories(ctx, names)` | STEP 4 (opt) — v1 Categories, one call each → `[{id,name}]` |
+| `assignEventsToCategory(ctx, categoryId, eventIds)` | STEP 4 (opt) — path `/{categoryId}/events`, body `{eventId:[…]}` |
+| `importImage(ctx, url)` | import an external url into Wix Media → `{id,url}` (file id + wixstatic url); the main image binds by this file id |
+| `setEventMainImage(ctx, {eventId,id,url,height,width,altText})` | optional — PATCH `mainImage` (no revision); `id` = a Wix Media file id from `importImage` |
+
+## Reference
+If a call returns a shape you didn't expect, or you need an operation this module doesn't cover,
+use the **`wix-docs`** skill to search + read the live Wix API reference — never guess. The
+authoritative source recipe is `wix-headless/references/inline-recipes/setup-events.md`.
+
+Read a method's page before writing its call: it carries the exact body shape, the required
+permission scope, and the response envelope.
+- Install a Wix app onto the site: https://dev.wix.com/docs/api-reference/business-management/app-installation/app-installation/install-app.md
+- Import an image into Wix Media: https://dev.wix.com/docs/api-reference/assets/media/media-manager/files/import-file.md
+- Create Event: https://dev.wix.com/docs/api-reference/business-solutions/events/event-management/events-v3/create-event.md
+- Create Ticket Definition: https://dev.wix.com/docs/api-reference/business-solutions/events/event-management/ticket-definitions-v3/create-ticket-definition.md
+- Create Category: https://dev.wix.com/docs/api-reference/business-solutions/events/event-management/categories/create-category.md
+- Get Site Properties (timezone / currency): https://dev.wix.com/docs/api-reference/business-management/site-properties/properties/get-site-properties.md