@wix/agent-skills 1.36.0 → 1.36.1

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

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

@@ -1,48 +0,0 @@
-// 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 "@/lib/nav";
-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

@@ -1,36 +0,0 @@
-// 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/app/rest/wix-events-browse.js

@@ -1,136 +0,0 @@
-import { wixApiRequest } from "./wix-client.js";
-
-// Data model reference: see INSTRUCTIONS.md
-
-/**
- * Wix Events V3 Event — key fields for list cards and the detail page.
- * Full model: https://dev.wix.com/docs/api-reference/business-solutions/events/event-management/events-v3/event-object.md
- *
- *   id {string}, title {string}, slug {string},
- *   status {string} — "UPCOMING"|"STARTED"|"ENDED"|"CANCELED"|"DRAFT" (only UPCOMING/STARTED are live),
- *   shortDescription {string} — PLAIN-TEXT teaser, safe to render directly (DETAILS fieldset),
- *   description {object} — RICH CONTENT (Ricos), shape { nodes: [...] } — NOT a string (TEXTS fieldset,
- *     returned by getEventBySlug). Render it with a Ricos viewer (@wix/ricos) or walk `nodes` to extract
- *     text; NEVER call string methods (.split/.slice/.substring/.trim) on it — that crashes the page.
- *     For a plain-string teaser use shortDescription instead.
- *   detailedDescription {string} — legacy plain/HTML description (TEXTS fieldset); prefer description/shortDescription,
- *   mainImage {object} — { id, url, width, height, altText } (DETAILS fieldset),
- *   dateAndTimeSettings {object}:
- *     startDate, endDate {string} — ISO-8601; absent when dateAndTimeTbd is true,
- *     timeZoneId {string} — IANA tz,
- *     formatted.dateAndTime {string} — ready-to-render human string,
- *   location {object}: type "VENUE"|"ONLINE", name {string}, address {object}, locationTbd {boolean},
- *   registration {object} (REGISTRATION fieldset):
- *     type {string} — "RSVP"|"TICKETING"|"EXTERNAL"|"NONE",
- *     status {string} — only OPEN_* statuses accept new registrations,
- *     rsvp.responseType — "YES_AND_NO" allows a "NO" reply,
- *     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, name, counts.assignedEventsCount }
- * Full model: https://dev.wix.com/docs/api-reference/business-solutions/events/event-management/categories
- */
-
-const LIST_FIELDS = ["DETAILS", "REGISTRATION", "URLS"];
-const DETAIL_FIELDS = ["DETAILS", "TEXTS", "REGISTRATION", "URLS", "FORM"];
-
-/**
- * Query live (UPCOMING/STARTED) events for a listing grid, one page. Sorted soonest first.
- * Uses offset paging — response carries total for empty state and "load more" math.
- * https://dev.wix.com/docs/api-reference/business-solutions/events/event-management/events-v3/query-events.md
- * @param {{ limit?: number, offset?: number, status?: string[] }} [options]
- * @returns {Promise<{ events: object[], total: number, offset: number, nextOffset: number|null }>}
- */
-export async function queryEvents({ limit = 50, offset = 0, status = ["UPCOMING", "STARTED"] } = {}) {
-  const res = await wixApiRequest("/events/v3/events/query", {
-    method: "POST",
-    body: {
-      query: {
-        filter: { status: { $in: status } },
-        sort: [{ fieldName: "dateAndTimeSettings.startDate", order: "ASC" }],
-        paging: { limit, offset },
-      },
-      fields: LIST_FIELDS,
-    },
-  });
-  const events = res?.events ?? [];
-  const total = res?.pagingMetadata?.total ?? events.length;
-  const nextOffset = offset + events.length < total ? offset + events.length : null;
-  return { events, total, offset, nextOffset };
-}
-
-/**
- * Fetch a single event by its URL slug, with full detail-page fields (description, form, page URL).
- * Returns null if not found — show a not-found state, never invent an event.
- * https://dev.wix.com/docs/api-reference/business-solutions/events/event-management/events-v3/get-event-by-slug.md
- * @param {string} slug
- * @returns {Promise<object|null>}
- */
-export async function getEventBySlug(slug) {
-  try {
-    const res = await wixApiRequest(`/events/v3/events/slug/${encodeURIComponent(slug)}`, {
-      method: "GET",
-      query: { fields: DETAIL_FIELDS },
-    });
-    return res?.event ?? null;
-  } catch {
-    return null;
-  }
-}
-
-/**
- * Total number of live events. Used for empty-state logic (0 → prompt user to publish events).
- * @param {string[]} [status]
- * @returns {Promise<number>}
- */
-export async function countUpcomingEvents(status = ["UPCOMING", "STARTED"]) {
-  const res = await wixApiRequest("/events/v3/events/query", {
-    method: "POST",
-    body: { query: { filter: { status: { $in: status } }, paging: { limit: 1, offset: 0 } } },
-  });
-  return res?.pagingMetadata?.total ?? 0;
-}
-
-/**
- * Query event categories for a category menu/filter. counts.assignedEventsCount tells you
- * how many events are in each category.
- * https://dev.wix.com/docs/api-reference/business-solutions/events/event-management/categories/query-categories.md
- * @param {{ limit?: number, offset?: number }} [options]
- * @returns {Promise<{ categories: object[], total: number }>}
- */
-export async function queryEventCategories({ limit = 100, offset = 0 } = {}) {
-  const res = await wixApiRequest("/events/v1/categories/query", {
-    method: "POST",
-    body: { query: { paging: { limit, offset } }, fieldset: ["COUNTS"] },
-  });
-  return {
-    categories: res?.categories ?? [],
-    total: res?.metaData?.total ?? (res?.categories?.length ?? 0),
-  };
-}
-
-/**
- * List live events assigned to a category, one page. Same card fields as queryEvents.
- * https://dev.wix.com/docs/api-reference/business-solutions/events/event-management/events-v3/list-events-by-category.md
- * @param {string} categoryId  Category GUID from queryEventCategories.
- * @param {{ limit?: number, offset?: number }} [options]
- * @returns {Promise<{ events: object[], total: number, offset: number, nextOffset: number|null }>}
- */
-export async function listEventsByCategory(categoryId, { limit = 50, offset = 0 } = {}) {
-  const res = await wixApiRequest(`/events/v3/events/category/${encodeURIComponent(categoryId)}`, {
-    method: "GET",
-    query: {
-      fields: LIST_FIELDS,
-      "paging.limit": String(limit),
-      "paging.offset": String(offset),
-    },
-  });
-  const events = res?.events ?? [];
-  const total = res?.pagingMetadata?.total ?? events.length;
-  const nextOffset = offset + events.length < total ? offset + events.length : null;
-  return { events, total, offset, nextOffset };
-}

package/skills/wix-vibe-headless/references/events/app/rest/wix-events-registration.js

@@ -1,187 +0,0 @@
-import { wixApiRequest } from "./wix-client.js";
-
-// Data model reference: see INSTRUCTIONS.md
-// Event shape (for getEventBySlug): see wix-events-browse.js
-
-/**
- * Wix Events Ticket Definition — a ticket type returned by the checkout/available-tickets endpoint.
- * Full model: https://dev.wix.com/docs/api-reference/business-solutions/events/registration/ticketing/orders/list-available-tickets
- *
- *   id {string}, eventId {string}, name {string}, description {string},
- *   free {boolean} — true when the ticket is free,
- *   price { amount, currency } — the display price (use pricing.* for full detail),
- *   pricing ONE-OF:
- *     fixedPrice { amount, currency } — same price for everyone,
- *     minPrice { amount, currency } — minimum for "pay what you want" (donation); pass chosen amount as ticketInfo.guestPrice,
- *     pricingOptions.options [{ id, name, price { amount, currency } }] — tiered; pass chosen option id as ticketInfo.pricingOptionId,
- *   pricingType {string} — "STANDARD" | "DONATION" | "OPTIONS",
- *   saleStatus {string} — "SALE_STARTED" is the only buyable state,
- *   limitPerCheckout {number},
- *   orderIndex {number} — display order
- *
- * RSVP: { id, eventId, status ("YES"|"NO"|"WAITLIST"), totalGuests, firstName, lastName, email }
- *   status "WAITLIST" when the event is full and waitlist is enabled.
- * Order: { orderNumber, status, totalPrice, ticketsPdf, tickets[] }
- *   status "FREE" → confirmed. status "INITIATED" → redirect to getTicketCheckoutUrl.
- */
-
-/**
- * Submit an RSVP for an RSVP-type event (registration.type === "RSVP"). Completes client-side.
- *
- * Pass status "NO" only when event.registration.rsvp.responseType is "YES_AND_NO".
- * If the event is full with a waitlist enabled, the RSVP comes back with status "WAITLIST".
- * Throws on closed registration, guest-limit exceeded, duplicate email, or invalid form.
- * https://dev.wix.com/docs/api-reference/business-solutions/events/registration/rsvp-v2/create-rsvp.md
- *
- * @param {string} eventId
- * @param {{ firstName: string, lastName: string, email: string, status?: "YES"|"NO",
- *           additionalGuestNames?: string[], extraFields?: Record<string,string|string[]> }} guest
- * @returns {Promise<object>} The created RSVP.
- */
-export async function createRsvp(eventId, { firstName, lastName, email, status = "YES", additionalGuestNames = [], extraFields = {} } = {}) {
-  if (!firstName || !lastName || !email) throw new Error("createRsvp requires firstName, lastName, and email.");
-
-  // The built-in fields go TOP-LEVEL on rsvp — the API rejects them inside form.inputValues
-  // (400 "rsvp.firstName must not be empty"). form.inputValues is ONLY for the event's extra
-  // custom fields; sending a built-in-only form, or additionalGuestDetails when the event has no
-  // guest fields, throws INVALID_FORM_RESPONSE ("input additionalGuests/guestNames is unexpected").
-  const rsvp = { eventId, firstName, lastName, email, status };
-
-  const inputValues = [];
-  for (const [inputName, value] of Object.entries(extraFields)) {
-    inputValues.push(Array.isArray(value) ? { inputName, values: value } : { inputName, value });
-  }
-  if (inputValues.length) rsvp.form = { inputValues };
-  if (additionalGuestNames.length) {
-    rsvp.additionalGuestDetails = { guestCount: additionalGuestNames.length, guestNames: additionalGuestNames };
-  }
-
-  const res = await wixApiRequest("/events/v2/rsvps", { method: "POST", body: { rsvp } });
-  return res?.rsvp;
-}
-
-/**
- * Query the buyable ticket definitions for a ticketed event (with availability).
- *
- * Uses GET /events/v1/checkout/available-tickets (WIX_EVENTS.READ_CHECKOUT) — the visitor-facing
- * checkout endpoint. The V3 /ticket-definitions/query endpoint requires WIX_EVENTS.READ_TICKET_DEFINITIONS
- * (scope SCOPE.DC-EVENTS.MANAGE-TICKET-DEF), an admin-only scope that anonymous visitor tokens do
- * not carry, so it 403s in a headless SPA context.
- *
- * This endpoint already filters to non-hidden, SALE_STARTED tickets, so the result is ready to
- * render directly. Pass includeSoldOut: false to additionally drop sold-out tiers.
- *
- * https://dev.wix.com/docs/api-reference/business-solutions/events/registration/ticketing/orders/list-available-tickets
- * @param {string} eventId
- * @param {{ includeSoldOut?: boolean }} [options]
- * @returns {Promise<object[]>}
- */
-export async function queryTicketDefinitions(eventId, { includeSoldOut = true } = {}) {
-  const res = await wixApiRequest("/events/v1/checkout/available-tickets", {
-    method: "GET",
-    query: { eventId, limit: "100" },
-  });
-  let defs = res?.definitions ?? [];
-  if (!includeSoldOut) defs = defs.filter((d) => !d.salesDetails?.soldOut);
-  return defs;
-}
-
-/**
- * Reserve tickets for a limited time (typically 5–30 min) while the buyer completes checkout.
- * Returns a reservation with status "PENDING" and an expirationDate.
- * Throws if the reservation doesn't come back PENDING (e.g. tickets unavailable).
- * https://dev.wix.com/docs/api-reference/business-solutions/events/registration/ticketing/ticket-reservations/create-ticket-reservation.md
- *
- * @param {Array<{ ticketDefinitionId: string, quantity: number, guestPrice?: string, pricingOptionId?: string }>} tickets
- * @returns {Promise<object>} The created reservation (id, expirationDate, tickets[], status).
- */
-export async function reserveTickets(tickets) {
-  if (!Array.isArray(tickets) || !tickets.length) throw new Error("reserveTickets requires at least one ticket line.");
-
-  const lines = tickets.map(({ ticketDefinitionId, quantity, guestPrice, pricingOptionId }) => {
-    if (!ticketDefinitionId || !quantity) throw new Error("Each ticket line needs a ticketDefinitionId and quantity.");
-    const ticketInfo = {};
-    if (guestPrice !== undefined) ticketInfo.guestPrice = String(guestPrice);
-    if (pricingOptionId) ticketInfo.pricingOptionId = pricingOptionId;
-    const line = { ticketDefinitionId, quantity };
-    if (Object.keys(ticketInfo).length) line.ticketInfo = ticketInfo;
-    return line;
-  });
-
-  const res = await wixApiRequest("/events/v1/ticket-reservations", {
-    method: "POST",
-    body: { ticketReservation: { tickets: lines } },
-  });
-  const reservation = res?.ticketReservation;
-  if (!reservation?.id || reservation.status !== "PENDING") {
-    throw new Error(`Could not reserve tickets (status: ${reservation?.status ?? "unknown"}). They may be sold out.`);
-  }
-  return reservation;
-}
-
-/**
- * Build the URL of the Wix-hosted ticket form for a reservation. Use this for ALL paid tickets
- * (and free tickets too). The buyer fills in guest details and pays on Wix's page, then returns.
- * Redirect with: window.location.href = getTicketCheckoutUrl(event, reservation.id)
- *
- * event must have been fetched with the URLS fieldset (getEventBySlug already does this).
- * https://dev.wix.com/docs/api-reference/business-solutions/events/registration/ticketing/orders/checkout.md
- *
- * @param {object} event          Event from getEventBySlug (needs eventPageUrl).
- * @param {string} reservationId  From reserveTickets.
- * @returns {string} Absolute hosted ticket-form URL.
- */
-export function getTicketCheckoutUrl(event, reservationId) {
-  const base = event?.eventPageUrl?.base;
-  const path = event?.eventPageUrl?.path;
-  if (!base || !path) throw new Error("Event is missing eventPageUrl — fetch it with getEventBySlug (URLS fieldset).");
-  if (!reservationId) throw new Error("getTicketCheckoutUrl requires a reservationId from reserveTickets.");
-  return `${base}${path}/ticket-form?reservationId=${encodeURIComponent(reservationId)}`;
-}
-
-/**
- * Check out a reservation via REST — creates the order and assigns guests.
- * Use this ONLY for FREE ticket orders (no redirect needed): the returned order has
- * status "FREE", a ticketsPdf, and generated tickets[].
- *
- * For PAID tickets, this throws and tells you to redirect to getTicketCheckoutUrl instead.
- * https://dev.wix.com/docs/api-reference/business-solutions/events/registration/ticketing/orders/checkout.md
- *
- * @param {string} eventId
- * @param {{ reservationId: string,
- *           buyer?: { firstName: string, lastName: string, email: string },
- *           guests: Array<{ firstName: string, lastName: string, email: string, extraFields?: Record<string,string|string[]> }> }} details
- * @returns {Promise<object>} The created order (orderNumber, status, ticketsPdf, tickets[]).
- */
-export async function checkoutTickets(eventId, { reservationId, buyer, guests } = {}) {
-  if (!eventId || !reservationId) throw new Error("checkoutTickets requires eventId and reservationId.");
-  if (!Array.isArray(guests) || !guests.length) throw new Error("checkoutTickets requires at least one guest.");
-
-  const toForm = ({ firstName, lastName, email, extraFields = {} }) => {
-    const inputValues = [
-      { inputName: "firstName", value: firstName },
-      { inputName: "lastName", value: lastName },
-      { inputName: "email", value: email },
-    ];
-    for (const [inputName, value] of Object.entries(extraFields)) {
-      inputValues.push(Array.isArray(value) ? { inputName, values: value } : { inputName, value });
-    }
-    return { form: { inputValues } };
-  };
-
-  const body = { reservationId, guests: guests.map(toForm) };
-  if (buyer) body.buyer = buyer;
-
-  const res = await wixApiRequest(`/events/v1/events/${encodeURIComponent(eventId)}/tickets/checkout`, {
-    method: "POST",
-    body,
-  });
-  const order = res?.order;
-  const status = order?.status;
-  if (status === "INITIATED" || status === "PENDING") {
-    throw new Error(
-      `Order ${order?.orderNumber ?? ""} needs payment (status: ${status}). Redirect the buyer to getTicketCheckoutUrl(event, reservationId) to pay on the hosted ticket form.`,
-    );
-  }
-  return order;
-}

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

@@ -1,103 +0,0 @@
-# Events — seeding
-
-Seed Wix Events (Events V3) by **calling `seed-events.cjs`** — 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");
-const seed = require(require("path").resolve(".agents/skills/wix-vibe-headless/references/events/seed/seed-events.cjs"));
-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 documentation skill available in your environment 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