@wix/agent-skills 1.13.0 → 1.15.0

package/skills/wix-vibe-headless/references/cms/wix-cms.js

@@ -0,0 +1,186 @@
+import { wixApiRequest } from "./wix-client.js";
+
+/**
+ * Wix CMS (Wix Data) — REST helpers for reading and writing data items in site data collections.
+ *
+ * COLLECTIONS & PERMISSIONS: A collection (e.g. "Tutorials") is identified by its
+ * dataCollectionId — the name set in the dashboard, NOT a GUID. Field keys are also set
+ * in the dashboard. This skill runs as an ANONYMOUS VISITOR — a call only succeeds if the
+ * collection grants that action to "Anyone" (Read for listing, Insert for forms, etc.).
+ * Permission-denied throws HTTP 403 by design. Set permissions in Wix dashboard → CMS → Permissions.
+ * https://dev.wix.com/docs/api-reference/business-solutions/cms/collection-management/data-permissions/data-permissions-object.md
+ *
+ * Data Item — every read helper returns the item's `data` payload:
+ *   _id {string} — GUID (route key, itemId for get/update/remove),
+ *   _createdDate, _updatedDate {string} — ISO 8601 (use { "$date": "..." } in filters),
+ *   _ownerId {string}, ...fields — collection field values keyed by field key
+ * Full reference: https://dev.wix.com/docs/api-reference/business-solutions/cms/data-items/data-item-object.md
+ *
+ * FILTERS & SORT (Wix API Query Language):
+ *   filter: { field: value } for equality; { field: { $op: value } } for operators:
+ *     $eq $ne $gt $gte $lt $lte $in $nin $startsWith $exists $isEmpty $hasSome $hasAll
+ *   Combine with $and / $or / $not. Dates: { "$date": "2026-05-05T00:00:00.000Z" }.
+ *   sort: [{ fieldName: "publishDate", order: "DESC" }]
+ * Full reference: https://dev.wix.com/docs/api-reference/articles/work-with-wix-apis/data-retrieval/about-the-wix-api-query-language.md
+ */
+
+/**
+ * Query one page of items from a collection.
+ * Reference: https://dev.wix.com/docs/api-reference/business-solutions/cms/data-items/query-data-items.md
+ *
+ * Pass `nextCursor` back as `cursor` to load the next page. Define `filter`/`sort`/`fields`
+ * on the FIRST request only — on cursor follow-ups Wix reuses the original query and
+ * ignores them (so this helper omits them when a cursor is supplied).
+ *
+ * @param {string} dataCollectionId  Collection name (e.g. "Tutorials").
+ * @param {{
+ *   filter?: object,
+ *   sort?: Array<{ fieldName: string, order?: "ASC"|"DESC" }>,
+ *   limit?: number,
+ *   cursor?: string,
+ *   fields?: string[],
+ *   includeReferences?: Array<{ field: string, limit?: number }>
+ * }} [options]
+ * @returns {Promise<{ items: object[], nextCursor: string|null }>}  items are `data` payloads (each includes `_id`).
+ */
+export async function queryDataItems(dataCollectionId, { filter, sort, limit = 100, cursor, fields, includeReferences } = {}) {
+  const query = {
+    ...(cursor
+      ? {}
+      : {
+          ...(filter ? { filter } : {}),
+          ...(sort ? { sort } : {}),
+          ...(fields ? { fields } : {}),
+        }),
+    cursorPaging: cursor ? { limit, cursor } : { limit },
+  };
+  const res = await wixApiRequest("/wix-data/v2/items/query", {
+    method: "POST",
+    body: {
+      dataCollectionId,
+      query,
+      ...(includeReferences ? { includeReferences } : {}),
+    },
+  });
+  return {
+    items: (res?.dataItems ?? []).map((d) => d.data),
+    nextCursor: res?.pagingMetadata?.cursors?.next ?? null,
+  };
+}
+
+/**
+ * Get a single item by its `_id`. Returns the `data` payload, or null if not found
+ * (or not readable by an anonymous visitor — see the permissions note up top).
+ * Reference: https://dev.wix.com/docs/api-reference/business-solutions/cms/data-items/get-data-item.md
+ *
+ * @param {string} dataCollectionId
+ * @param {string} itemId            The item's `_id`.
+ * @returns {Promise<object|null>}
+ */
+export async function getDataItem(dataCollectionId, itemId) {
+  try {
+    const res = await wixApiRequest(`/wix-data/v2/items/${encodeURIComponent(itemId)}`, {
+      method: "GET",
+      query: { dataCollectionId },
+    });
+    return res?.dataItem?.data ?? null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Get the first item whose `fieldKey` equals `value`. Use for slug-style routing —
+ * Wix Data has no native get-by-slug, so detail pages keyed off a human-readable field
+ * (e.g. a "slug" or "handle" field) resolve through this. Returns the `data` payload or null.
+ * Built on Query Data Items: https://dev.wix.com/docs/api-reference/business-solutions/cms/data-items/query-data-items.md
+ *
+ * @param {string} dataCollectionId
+ * @param {string} fieldKey   Field to match (e.g. "slug").
+ * @param {unknown} value     Value to match.
+ * @returns {Promise<object|null>}
+ */
+export async function getDataItemBy(dataCollectionId, fieldKey, value) {
+  const { items } = await queryDataItems(dataCollectionId, { filter: { [fieldKey]: value }, limit: 1 });
+  return items[0] ?? null;
+}
+
+/**
+ * Count items in a collection matching an optional filter. Use for empty-state logic
+ * (0 → prompt the user to add items in their Wix dashboard) and result counts.
+ * Reference: https://dev.wix.com/docs/api-reference/business-solutions/cms/data-items/count-data-items.md
+ *
+ * @param {string} dataCollectionId
+ * @param {object} [filter]  Same filter syntax as queryDataItems.
+ * @returns {Promise<number>}
+ */
+export async function countDataItems(dataCollectionId, filter) {
+  const res = await wixApiRequest("/wix-data/v2/items/count", {
+    method: "POST",
+    body: { dataCollectionId, ...(filter ? { filter } : {}) },
+  });
+  return res?.totalCount ?? 0;
+}
+
+/**
+ * Insert a new item (e.g. a public form submission). The collection's Insert permission
+ * must be "Anyone" for this to succeed as a visitor. Returns the inserted `data` payload
+ * (including the assigned `_id`). Throws on failure (e.g. permission denied, validation).
+ * Reference: https://dev.wix.com/docs/api-reference/business-solutions/cms/data-items/insert-data-item.md
+ *
+ * @param {string} dataCollectionId
+ * @param {object} data   Field-keyed values, e.g. { name, email, message }. Omit `_id`
+ *                        to let Wix assign one; supply `_id` only for a custom GUID.
+ * @returns {Promise<object>}  The inserted item's `data` payload.
+ */
+export async function insertDataItem(dataCollectionId, data) {
+  const res = await wixApiRequest("/wix-data/v2/items", {
+    method: "POST",
+    body: { dataCollectionId, dataItem: { data } },
+  });
+  const inserted = res?.dataItem?.data;
+  if (!inserted) throw new Error(`Insert into "${dataCollectionId}" failed (no item returned).`);
+  return inserted;
+}
+
+/**
+ * Update (REPLACE) an existing item by `_id`. Returns the updated `data` payload. Throws
+ * if the item doesn't exist or the visitor lacks Update permission (usually admin/author only).
+ * Reference: https://dev.wix.com/docs/api-reference/business-solutions/cms/data-items/update-data-item.md
+ *
+ * ⚠ This is a FULL REPLACE: the new `data` overwrites the whole item, and any field NOT
+ * included is dropped. To change a few fields, fetch the item first (getDataItem), spread
+ * it, then pass the merged object — or use Patch Data Item for a partial change:
+ * https://dev.wix.com/docs/api-reference/business-solutions/cms/data-items/patch-data-item.md
+ *
+ * @param {string} dataCollectionId
+ * @param {string} itemId   The item's `_id`.
+ * @param {object} data     The complete new field set.
+ * @returns {Promise<object>}  The updated item's `data` payload.
+ */
+export async function updateDataItem(dataCollectionId, itemId, data) {
+  const res = await wixApiRequest(`/wix-data/v2/items/${encodeURIComponent(itemId)}`, {
+    method: "PUT",
+    body: { dataCollectionId, dataItem: { id: itemId, data: { ...data, _id: itemId } } },
+  });
+  const updated = res?.dataItem?.data;
+  if (!updated) throw new Error(`Update of "${itemId}" in "${dataCollectionId}" failed (no item returned).`);
+  return updated;
+}
+
+/**
+ * Remove an item by `_id`. Irreversible. Returns the removed `data` payload. Throws if the
+ * visitor lacks Delete permission (usually admin/author only).
+ * Reference: https://dev.wix.com/docs/api-reference/business-solutions/cms/data-items/remove-data-item.md
+ *
+ * @param {string} dataCollectionId
+ * @param {string} itemId   The item's `_id`.
+ * @returns {Promise<object|null>}  The removed item's `data` payload.
+ */
+export async function removeDataItem(dataCollectionId, itemId) {
+  const res = await wixApiRequest(`/wix-data/v2/items/${encodeURIComponent(itemId)}`, {
+    method: "DELETE",
+    query: { dataCollectionId },
+  });
+  return res?.dataItem?.data ?? null;
+}

package/skills/wix-vibe-headless/references/events/INSTRUCTIONS.md

@@ -0,0 +1,142 @@
+
+# Wix Events Skill
+
+> **Source files (in this skill):** the shared transport `references/shared/wix-client.js` and the helper file(s) you need from `references/events/`. All helpers import from `"./wix-client.js"`, so copy them into the same folder (e.g. `src/rest/`).
+>
+> | Need | Copy |
+> |---|---|
+> | Event listing + detail (always) | `wix-events-browse.js` |
+> | RSVP, ticketing, registration | `wix-events-registration.js` |
+
+Builds a real, client-only Wix Events site. The browser talks to Wix directly over a
+public `WIX_CLIENT_ID`. Never mock events; never hand-build registration or payment URLs —
+register via the RSVP/ticketing APIs, and complete paid tickets on the official Wix-hosted
+ticket form.
+
+## When to use
+- User wants an events site over Wix Events & Tickets, or asks to "connect Wix Events".
+- Replacing placeholder/mock events with live Wix data.
+- Adding event listings, an event detail page, RSVP, or ticket purchase over existing,
+  published Wix events.
+
+## Prerequisites
+1. A Wix site with **Wix Events & Tickets installed and events already published** (this skill
+   does NOT create events — it's read-only over them). Selling **paid** tickets also needs a
+   Wix premium plan + a configured payment method; **free** events and RSVP events work without.
+2. The site's public headless **`WIX_CLIENT_ID`**, provided in the handoff prompt (the Wix
+   Business Manager surfaces a copyable prompt with the id filled in — see the router `SKILL.md`). Paste
+   it into `src/rest/wix-client.js` in place of the placeholder. It is a visitor-facing
+   credential (it only mints anonymous visitor tokens), **not** a secret, so hardcoding/
+   committing it is fine.
+3. For paid tickets the buyer completes payment on the **Wix-hosted ticket form** (the redirect
+   target of `getTicketCheckoutUrl`). The deployed app domain may need to be allow-listed on the
+   OAuth client for that page to return cleanly — a **separate Wix setup the user completes
+   later**, out of this skill's scope. If the return fails before that's done, that's expected;
+   flag it and continue.
+
+## The API (copy as-is; do not re-derive it)
+This skill ships only the REST layer — no UI components. Build the events UI however the
+project wants; wire it to these two snippets. Copy them into the app (e.g. `src/api/`) and only
+adjust import paths:
+- `src/rest/wix-client.js` — visitor-token mint/refresh + transport. Set `WIX_CLIENT_ID` to the
+  id from the prompt (replace the `<YOUR-CLIENT-ID>` placeholder). The visitor refresh token is
+  persisted to localStorage and IS the identity of the visitor's ticket reservation/cart — do
+  not re-mint anonymously per load.
+- `src/rest/wix-events-browse.js` — **Browse & discovery:**
+  `queryEvents`, `getEventBySlug`, `countUpcomingEvents`, `queryEventCategories`, `listEventsByCategory`
+- `src/rest/wix-events-registration.js` — **RSVP & ticketing:**
+  `createRsvp`, `queryTicketDefinitions`, `reserveTickets`, `getTicketCheckoutUrl`, `checkoutTickets`
+
+The `Event`, `TicketDefinition`, and `RSVP`/`Order` shapes are documented as JSDoc comments at
+the top of each helper file. Read the relevant file(s) before building the UI — they describe
+the key fields and link to the full API reference for anything not shown.
+
+## How to wire it (UI is the project's choice)
+- **Event grid** — `queryEvents()` lists live (UPCOMING/STARTED) events, soonest first. Render
+  `title`, `mainImage.url`, `dateAndTimeSettings.formatted.dateAndTime`, `location.name`, and
+  `shortDescription`. Use `offset`/`nextOffset` from the result to page. Link each card by `slug`.
+- **Event detail** — `getEventBySlug(slug)`; returns null on miss — show a not-found state, never
+  invent an event.
+  - **Description fields:** `event.shortDescription` is a **plain string** (safe teaser). The full
+    `event.description` is **Ricos rich content** — an object shaped `{ nodes: [...] }`, **not a string**.
+    Render it with a Ricos viewer (`@wix/ricos`) or walk `nodes` to extract text; **never** call string
+    methods (`.split`/`.slice`/`.substring`) on it — that crashes the page. When you only need text, use
+    `shortDescription`.
+  - Branch the registration UI on `event.registration.type`:
+  - `"RSVP"` → render the RSVP form (fields from `event.form.controls`).
+  - `"TICKETING"` → render the ticket picker.
+  - `"EXTERNAL"` → link out to `event.registration.external.url`.
+  - `"NONE"` → details only, no registration.
+  Only `registration.status` values starting `OPEN_` accept new registrations; otherwise show the
+  closed state.
+- **Categories (optional)** — `queryEventCategories()` for a filter menu (`counts.assignedEventsCount`
+  per category); `listEventsByCategory(categoryId)` to list a category's events (same card fields
+  and paging as `queryEvents`).
+- **RSVP** — `createRsvp(eventId, { firstName, lastName, email, status, additionalGuestNames?, extraFields? })`.
+  `status` defaults to `"YES"`; only offer `"NO"` when `registration.rsvp.responseType` is
+  `"YES_AND_NO"`. If the event is full with a waitlist enabled, the returned RSVP comes back with
+  status `"WAITLIST"` — tell the guest. Completes fully client-side; no redirect.
+- **Ticketing** — show tickets, reserve, then complete on the hosted form:
+  1. `queryTicketDefinitions(eventId)` → render each ticket's `name`, price (`pricing.fixedPrice.amount`
+     + `currency` for standard tickets; `free` boolean for free tickets; `pricing.minPrice` for
+     donation/"pay what you want"; `pricing.pricingOptions.options` for tiered), and filter on
+     `saleStatus === "SALE_STARTED"`. The endpoint already returns only non-hidden, available tickets.
+  2. `reserveTickets([{ ticketDefinitionId, quantity, guestPrice?, pricingOptionId? }])` → holds the
+     tickets; returns `{ id, expirationDate }`. Show a countdown to `expirationDate` if you like.
+  3. `window.location.href = getTicketCheckoutUrl(event, reservation.id)` → the Wix-hosted ticket
+     form collects guest details + payment and returns the buyer to the event. This is the path for
+     **all paid tickets**.
+  - **Free tickets only:** you may instead call `checkoutTickets(eventId, { reservationId, buyer, guests })`
+    to finish in-app — it returns an order with status `"FREE"`, a `ticketsPdf`, and `tickets[]`. It
+    throws for paid orders (status `INITIATED`), telling you to use the hosted form.
+- **Empty state** — if `countUpcomingEvents()` is 0, show an empty state telling the user to publish
+  events in their Wix dashboard. Never invent events.
+
+## Hard rules (do not violate)
+- ✅ Complete paid ticket purchases ONLY via `reserveTickets()` → `getTicketCheckoutUrl()` redirect
+  (the official Wix-hosted ticket form). 
+- ❌ Never hand-build registration, ticket, payment, or checkout URLs — derive the hosted form URL
+  from `event.eventPageUrl` via `getTicketCheckoutUrl`.
+- ❌ Never mock events, tickets, or guest counts — render live Wix data or the empty/closed state.
+- ❌ Never invent reviews, ratings, attendee names, or "X spots left" numbers not returned by the API.
+- ✅ Set `WIX_CLIENT_ID` from the prompt's value (public visitor-facing client id — safe to hardcode).
+- ✅ Branch registration UI on `event.registration.type`; respect `registration.status` (only `OPEN_*`
+  accepts registrations) and ticket `saleStatus`/`salesDetails.soldOut`.
+- ✅ Pass `guestPrice` for donation/"pay what you want" tickets and `pricingOptionId` for tiered tickets
+  to `reserveTickets`.
+- The helpers fail loudly on purpose: `reserveTickets` throws when tickets aren't actually held,
+  `createRsvp` throws on closed/full registration, `checkoutTickets` throws when payment is still owed.
+  A green path means it really worked — don't swallow these.
+
+## Beyond the snippets
+The snippets cover the common RSVP + ticketing paths. If you hit a use case they don't cover
+(coupons/`discount` at checkout, members/auth, schedule/agenda, seating maps, canceling a
+reservation, a field not in the typedefs), make the call yourself with `wixApiRequest` — but look
+up the exact endpoint, HTTP method, and request body in the **official Wix Events API reference**
+first; never guess:
+- Events API reference: https://dev.wix.com/docs/api-reference/business-solutions/events.md
+- Registration (RSVP + ticketing) overview: https://dev.wix.com/docs/api-reference/business-solutions/events/registration/introduction.md
+- Member login + a "my registrations" account view → the **members** vertical (`references/members/INSTRUCTIONS.md`).
+- Ticketing flow (reservations → orders → tickets): https://dev.wix.com/docs/api-reference/business-solutions/events/registration/ticketing/introduction.md
+
+Keep the snippets as the default for everything they already do; reach for the API reference only
+for the gap.
+
+## Point the user to their dashboard
+In some cases, users need to access the Wix dashboard in order to edit the events content for their site. To facilitate this, provide the user with deep links directly to the relevant dashboard pages. For events data those pages are:
+- **Events** — `https://manage.wix.com/dashboard/{metaSiteId}/events` (`Dashboard → Events` → **+ Add Event**; create the event, then set it up as **Ticketed** or **RSVP**; only published events appear in the app)
+
+Substitute the site's `metaSiteId` to complete the links (you have it from the handoff / `ListWixSites`). Include the in-dashboard navigation as a fallback.
+
+## Verification checklist (before declaring done)
+- [ ] `WIX_CLIENT_ID` set to the prompt's value (not the `<YOUR-CLIENT-ID>` placeholder)
+- [ ] Visitor token persists across reload (same visitor identity for reservations)
+- [ ] Event grid renders live events; clicking a card opens the detail page by `slug`
+- [ ] Detail page branches correctly on `registration.type` (RSVP form vs. ticket picker vs. external link)
+- [ ] RSVP submit creates a real RSVP (and surfaces a `WAITLIST` result when the event is full)
+- [ ] Ticket purchase reserves tickets, then redirects via `getTicketCheckoutUrl` (no hand-built URL)
+- [ ] Paid checkout lands on the Wix-hosted ticket form; buyer returns to the event afterward
+- [ ] Closed registration / sold-out tickets show a clear state rather than a dead end
+- [ ] Empty state shown when `countUpcomingEvents()` is 0
+- [ ] No mock events, tickets, or attendee data anywhere
+- [ ] Told the user at least once that they can continue setting up their events in the dashboard and provided deep links.

package/skills/wix-vibe-headless/references/events/wix-events-browse.js

@@ -0,0 +1,135 @@
+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.currency, tickets.lowestPrice, tickets.soldOut,
+ *     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 }
+ * 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/wix-events-registration.js

@@ -0,0 +1,187 @@
+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;
+}