@wix/agent-skills 1.26.0 → 1.28.0

package/skills/wix-headless-templates/events/rest/events.ts

@@ -0,0 +1,112 @@
+// Event reads over REST — the twin of app/wix/events/events.ts. Same exports, same DTOs; the rules
+// and mappers come from events-core (the SAME file the SDK transport uses, deployed flat next to
+// this one by deploy.mjs --stack static), so this file is only the transport: one fetch with a
+// literal body per function. Every call here is safe from a browser with a visitor token.
+// Porting: keep the paths, keep the bodies, port the core once.
+// docs: https://dev.wix.com/docs/api-reference/business-solutions/events/event-management/events-v3/query-events.md
+// docs: https://dev.wix.com/docs/api-reference/business-solutions/events/event-management/events-v3/get-event-by-slug.md
+// docs: https://dev.wix.com/docs/api-reference/business-solutions/events/event-management/events-v3/get-event.md
+// docs: https://dev.wix.com/docs/api-reference/business-solutions/events/event-management/categories/query-categories.md
+import { WixApiError, wixRequest } from "./client.js";
+import { imgSrc } from "./media.js";
+import {
+  DEFAULT_PAGE_SIZE,
+  DETAIL_FIELDS,
+  EVENTS_APP_ID,
+  LIST_FIELDS,
+  categoriesQuery,
+  hasMorePages,
+  listQuery,
+  rawId,
+  toCategories,
+  toDetail,
+  toSummary,
+  type ListOptions,
+  type Raw,
+} from "./events-core.js";
+import type { EventCategory, EventDetail, EventSummary } from "./types.js";
+
+export { EVENTS_APP_ID, type ListOptions };
+
+const notFound = (e: unknown): boolean => e instanceof WixApiError && e.status === 404;
+
+/** One page of a listing plus what a "load more" needs. */
+export interface EventsPage {
+  events: EventSummary[];
+  /** Matching events overall (the page is `events`). */
+  total: number;
+  hasMore: boolean;
+}
+
+/**
+ * One page of events: UPCOMING/STARTED by default (`status: "past"` for ENDED, `"all"` for both),
+ * soonest first then newest first, optionally one category (server-side), `limit` (default 20)
+ * from `offset`. The limit is always sent: `paging.limit` defaults to 0 and a bare query answers
+ * `total: N, events: []` with no error.
+ * POST /events/v3/events/query  { query: { filter: { status: { $in }, "categories.id"?: { $in } }, sort, paging: { limit, offset } }, fields }
+ *   → { events, pagingMetadata: { total } }
+ */
+export async function fetchEventsPage(options: ListOptions = {}): Promise<EventsPage> {
+  const { offset = 0 } = options;
+  const res = await wixRequest<Raw>("/events/v3/events/query", { body: { query: listQuery({ limit: DEFAULT_PAGE_SIZE, ...options }), fields: LIST_FIELDS } });
+  const items = ((res?.events ?? []) as Raw[]).map((e) => toSummary(e, imgSrc));
+  const total = typeof res?.pagingMetadata?.total === "number" ? res.pagingMetadata.total : offset + items.length;
+  return { events: items, total, hasMore: hasMorePages(offset + items.length, total) };
+}
+
+/** The events of one page as a plain list (live events, soonest first, by default). */
+export async function fetchEvents(options: ListOptions = {}): Promise<EventSummary[]> {
+  return (await fetchEventsPage(options)).events;
+}
+
+/**
+ * Every live date of a recurring series — the series' `recurringCategoryId` is a category every
+ * occurrence carries, so this is the listing filtered to it.
+ */
+export async function fetchOccurrences(recurringCategoryId: string, { limit = 100 }: { limit?: number } = {}): Promise<EventSummary[]> {
+  if (!recurringCategoryId) return [];
+  return fetchEvents({ categoryId: recurringCategoryId, limit });
+}
+
+/**
+ * The site's MANUAL categories (the filter pills). Runs on the visitor token: needs
+ * WIX_EVENTS.READ_CATEGORIES, which Wix's own headless demo exercises client-side but which isn't
+ * guaranteed for every site — callers catch a failure (403) and fall back to the categories on the
+ * loaded events.
+ * POST /events/v1/categories/query  { query: { filter: { states: { $hasSome: ["MANUAL"] } }, paging: { limit: 100 } } }  → { categories }
+ */
+export async function fetchCategories(): Promise<EventCategory[]> {
+  const res = await wixRequest<Raw>("/events/v1/categories/query", { body: { query: categoriesQuery() } });
+  return toCategories(res?.categories);
+}
+
+/**
+ * One event by URL slug; null when the slug doesn't resolve (EVENT_NOT_FOUND, 404) — a real 404,
+ * never a fallback to another event. The response is WRAPPED: { event }.
+ * GET /events/v3/events/slug/{slug}?fields=DETAILS&fields=TEXTS&fields=REGISTRATION&fields=URLS&fields=CATEGORIES&fields=FORM
+ */
+export async function fetchEventBySlug(slug: string): Promise<EventDetail | null> {
+  try {
+    const res = await wixRequest<Raw>(`/events/v3/events/slug/${encodeURIComponent(slug)}`, { method: "GET", query: { fields: DETAIL_FIELDS } });
+    return res?.event ? toDetail(res.event, imgSrc) : null;
+  } catch (e) {
+    if (notFound(e)) return null;
+    throw e;
+  }
+}
+
+/**
+ * One event by id — the post-checkout confirmation read (the thank-you URL carries
+ * `?orderNumber=&eventId=`). On REST this response is WRAPPED too: { event } (the SDK's getEvent
+ * is the unwrapped one).  GET /events/v3/events/{eventId}?fields=…
+ */
+export async function fetchEventById(eventId: string): Promise<EventDetail | null> {
+  try {
+    const res = await wixRequest<Raw>(`/events/v3/events/${encodeURIComponent(eventId)}`, { method: "GET", query: { fields: DETAIL_FIELDS } });
+    const raw: Raw | undefined = res?.event;
+    return raw && rawId(raw) ? toDetail(raw, imgSrc) : null;
+  } catch (e) {
+    if (notFound(e)) return null;
+    throw e;
+  }
+}

package/skills/wix-headless-templates/events/rest/orders.ts

@@ -0,0 +1,28 @@
+// The ticket order behind the confirmation page over REST — the twin of app/wix/events/orders.ts.
+// Same export, same DTO; the mapper from orders-core (the SAME file the SDK transport uses,
+// deployed flat next to this one). Runs on the visitor token — the hosted checkout created the
+// order on this visitor's session. Not guaranteed for every site's visitor scope: a 403 throws
+// and the confirmation surface degrades to a confirmation without order details.
+// docs: https://dev.wix.com/docs/api-reference/business-solutions/events/registration/ticketing/orders/get-order.md
+import { WixApiError, wixRequest } from "./client.js";
+import { ORDER_FIELDSETS, toOrder } from "./orders-core.js";
+import type { Raw } from "./events-core.js";
+import type { OrderSummary } from "./types.js";
+
+/**
+ * One order by the pair the thank-you URL carries. Null on 404; throws on anything else.
+ * GET /events/v1/events/{eventId}/orders/{orderNumber}?fieldset=TICKETS&fieldset=DETAILS&fieldset=INVOICE  → { order }
+ */
+export async function fetchOrder(eventId: string, orderNumber: string): Promise<OrderSummary | null> {
+  try {
+    const res = await wixRequest<Raw>(`/events/v1/events/${encodeURIComponent(eventId)}/orders/${encodeURIComponent(orderNumber)}`, {
+      method: "GET",
+      query: { fieldset: ORDER_FIELDSETS },
+    });
+    const raw: Raw | undefined = res?.order;
+    return raw?.orderNumber ? toOrder(raw) : null;
+  } catch (e) {
+    if (e instanceof WixApiError && e.status === 404) return null;
+    throw e;
+  }
+}

package/skills/wix-headless-templates/events/rest/registration.ts

@@ -0,0 +1,96 @@
+// Ticket tiers, the reserve → hosted-checkout redirect, and RSVP over REST — the twin of
+// app/wix/events/registration.ts. Same exports, same DTOs; rules and mappers from
+// registration-core (the SAME file the SDK transport uses, deployed flat next to this one). The
+// request shapes are exact and rewriting them is how registrations break. Failures are loud.
+// All calls run with the visitor token — the reservation and the RSVP are the token's.
+// Query Available Ticket Definitions: wix.events.ticketdef.v3.TicketDefinitionManagement.QueryAvailableTicketDefinitions
+//   (POST /events/v3/ticket-definitions/available/query, as the @wix/events SDK issues it; the V3 family's reference:)
+// docs: https://dev.wix.com/docs/api-reference/business-solutions/events/event-management/ticket-definitions-v3/create-ticket-definition.md
+// docs: https://dev.wix.com/docs/api-reference/business-solutions/events/registration/ticketing/ticket-reservations/create-ticket-reservation.md
+// docs: https://dev.wix.com/docs/api-reference/business-solutions/events/registration/rsvp-v2/create-rsvp.md
+// docs: https://dev.wix.com/docs/api-reference/business-management/headless/redirects/create-redirect-session.md
+import { wixRequest } from "./client.js";
+import {
+  availableTiersQuery,
+  checkoutCallbacks,
+  redirectResult,
+  reservationError,
+  reservationId,
+  reservationTickets,
+  rsvpBody,
+  rsvpFormOf,
+  rsvpResult,
+  toTiers,
+  type CheckoutEvent,
+  type CheckoutPaths,
+  type RsvpValues,
+  type TierEvent,
+} from "./registration-core.js";
+import type { Raw } from "./events-core.js";
+import type { EventDetail, RegistrationResult, TicketSelection, TicketTier } from "./types.js";
+
+export { type CheckoutPaths, type RsvpValues, type TierEvent };
+
+/**
+ * Ticket tiers for a TICKETING event, in the organizer's order — the VISITOR-public V3 read (hidden
+ * tiers excluded server-side), never the ticket-definitions management query (403 for a visitor).
+ * Pass the EventDetail: sale dates format in its zone, its tax settings price the notes.
+ * POST /events/v3/ticket-definitions/available/query  { query: { filter: { eventId }, sort: [{ fieldName: "sortIndex", order: "ASC" }] } }  → { ticketDefinitions }
+ */
+export async function fetchTicketTiers(event: TierEvent): Promise<TicketTier[]> {
+  const res = await wixRequest<Raw>("/events/v3/ticket-definitions/available/query", { body: { query: availableTiersQuery(event.id) } });
+  return toTiers(res?.ticketDefinitions, event);
+}
+
+/**
+ * RSVP to a free (RSVP-type) event — completes fully client-side: no reservation, no redirect, no
+ * payment. `values` answer the ORGANIZER'S form (event.rsvpForm), keyed by input name; the body
+ * carries the built-in identity at the top level, the answers as `form.inputValues`, and
+ * `additionalGuestDetails` when the form has a guest control. "NO" only when the event's
+ * rsvpResponseType is "YES_AND_NO". Throws on closed registration, a guest limit, a missing
+ * mandatory answer (INVALID_FORM_RESPONSE), or an invalid email — surface the message. A full
+ * event with a waitlist answers "WAITLIST".
+ * POST /events/v2/rsvps  { rsvp: { eventId, status, firstName, lastName, email, form: { inputValues: [{ inputName, value | values }] }, additionalGuestDetails?: { guestCount, guestNames } } }  → { rsvp: { id, status } }
+ */
+export async function submitRsvp(
+  event: Pick<EventDetail, "id" | "rsvpForm">,
+  values: RsvpValues,
+  status: "YES" | "NO" = "YES",
+  guests: { guestCount: number; guestNames: string[] } = { guestCount: 0, guestNames: [] },
+): Promise<RegistrationResult> {
+  const res = await wixRequest<Raw>("/events/v2/rsvps", { body: { rsvp: rsvpBody(event.id, rsvpFormOf(event), values, status, guests) } });
+  return rsvpResult(res?.rsvp, status);
+}
+
+/**
+ * Ticketed checkout, the exact sequence: reserve the selected tiers (a PENDING hold that
+ * auto-expires), then mint the Wix-hosted checkout redirect and return its URL — the caller
+ * navigates the FULL document to it; Wix collects guest details + payment and emails the tickets.
+ * Selections carry the pricing option or the guest's price where the tier needs one (`ticketInfo`);
+ * pass `tiers` so a missing guest price is refused before the request. `origin` must be the site's
+ * real https origin as registered on the OAuth app's allowed domains (browser:
+ * window.location.origin). Never hand-build the checkout URL. `paths` overrides the return routes —
+ * a static site passes `{ confirmation: "/event-confirmation.html", event: "/event.html?slug=…" }`.
+ * POST /events/v1/ticket-reservations  { ticketReservation: { tickets: [{ eventId, ticketDefinitionId, quantity, ticketInfo?: { pricingOptionId?, guestPrice? } }] } }  → { ticketReservation: { id, status: "PENDING", expirationDate } }
+ * POST /headless/v1/redirect-session   { eventsCheckout: { reservationId, eventSlug }, callbacks: { thankYouPageUrl, postFlowUrl } }
+ */
+export async function startTicketCheckout(
+  event: CheckoutEvent,
+  selections: TicketSelection[],
+  paths: CheckoutPaths = {},
+  tiers: TicketTier[] = [],
+  origin: string = typeof window !== "undefined" ? window.location.origin : "",
+): Promise<RegistrationResult> {
+  const tickets = reservationTickets(event.id, selections, tiers);
+  let reservation: Raw | undefined;
+  try {
+    // Until the site has a premium plan AND a payment method this is a 403 NO_PAYMENT_METHOD_CONFIGURED — a business gate, not a bug.
+    reservation = (await wixRequest<Raw>("/events/v1/ticket-reservations", { body: { ticketReservation: { tickets } } }))?.ticketReservation;
+  } catch (e) {
+    throw reservationError(e);
+  }
+  const session = await wixRequest<Raw>("/headless/v1/redirect-session", {
+    body: { eventsCheckout: { reservationId: reservationId(reservation), eventSlug: event.slug }, callbacks: checkoutCallbacks(origin, event.slug, paths) },
+  });
+  return redirectResult(session);
+}

package/skills/wix-headless-templates/events/seed/SEED.md

@@ -0,0 +1,115 @@
+# Events — seeding
+
+Seed by **running `seed-events.mjs` with a plan file** — don't hand-write the REST calls.
+The script mints its own site token via the Wix CLI (logged-in session + `wix.config.json`
+required), installs the Wix Events app if needed, sets the site currency when the plan names one, and creates
+everything in the one order that works (create DRAFT → tiers → publish — the registration
+type is immutable and publishing is one-way).
+
+```bash
+# from the project root (where wix.config.json lives):
+node <SKILL_ROOT>/templates/events/seed/seed-events.mjs plan.json
+```
+
+`plan.json` is plain data — write it from the brief. **Default to 3 events** (the seed shows
+the shape; the owner adds the rest in the dashboard) and make them exercise the UI: mix
+`TICKETING` and `RSVP` (≥1 of each), give a ticketed event 2 tiers, and give every event an
+image (an events page without images looks broken) — the default is an `imagePrompt`
+(AI-generated, ~1 Wix AI credit per image, account-billed): brand-contextual — subject,
+aesthetic/mood, palette, lighting — always ending "no text, no watermarks". At least one image in the set shows the real subject of the business — the actual product/space/service, not abstract decoration. For an asset the user actually
+supplied use `imagePath` (a file on this machine — uploaded to Wix Media) or `imageUrl`
+(their own hosted URL; verify it with `curl -sI` → 200) — never a stock-photo or guessed URL. Images resolve in parallel and never block the
+seed; a failed image leaves that event text-only.
+
+```json
+{
+  "events": [
+    { "type": "TICKETING", "title": "Summer Synth Festival",
+      "shortDescription": "One night of analog sound under the stars.",
+      "startDate": "2026-11-07T03:30:00.000Z", "endDate": "2026-11-07T07: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": "45.00", "initialLimit": 200 },
+        { "name": "Front Row", "price": "85.00", "description": "First two rows.", "initialLimit": 40 }
+      ],
+      "category": "Concerts", "imageUrl": "https://…" },
+    { "type": "TICKETING", "title": "Vinyl Mixing Workshop",
+      "shortDescription": "Hands-on turntable session, decks provided.",
+      "startDate": "2026-11-14T18:00:00.000Z", "endDate": "2026-11-14T20:00:00.000Z",
+      "timeZoneId": "America/Los_Angeles",
+      "location": { "name": "Studio B", "type": "VENUE",
+        "address": { "addressLine": "9 Pine Ave", "city": "Seattle", "subdivision": "US-WA", "postalCode": "98101", "country": "US" } },
+      "ticketTiers": [{ "name": "Workshop Seat", "price": "30.00", "initialLimit": 16 }],
+      "category": "Workshops", "imageUrl": "https://…" },
+    { "type": "RSVP", "title": "Community Listening Night",
+      "shortDescription": "Free open-deck evening — bring a record.",
+      "startDate": "2026-11-20T19:00:00.000Z", "endDate": "2026-11-20T22:00:00.000Z",
+      "timeZoneId": "America/Los_Angeles",
+      "location": { "name": "The Back Room", "type": "VENUE",
+        "address": { "addressLine": "120 Harbor St", "city": "Seattle", "subdivision": "US-WA", "postalCode": "98101", "country": "US" } },
+      "category": "Community", "imageUrl": "https://…" }
+  ]
+}
+```
+
+- `type` — `TICKETING` (paid tiers; buyers pay on Wix's hosted checkout) or `RSVP` (free;
+  Wix creates the name+email form — the seed adds no fields; the owner extends it in the
+  dashboard and the site renders whatever the form holds). **Immutable after create** —
+  decide from the brief, never plan to convert.
+- **Dates are future ISO-8601 UTC** (`…Z`), `endDate` after `startDate`, `timeZoneId` an
+  IANA tz. A past event isn't registerable and won't show in the live listing; no date in
+  the brief → default ~60–90 days out and say so.
+- `ticketTiers` — TICKETING only, created before publish. `price` is a **decimal STRING**
+  (`"45.00"`, never a number), `name` ≤ 30 chars, omit `initialLimit` for unlimited. Tier
+  currency is the site currency, fixed at creation: a wrong one means deleting the event.
+  `feeType` (optional) says who pays the Wix ticket service fee: `FEE_INCLUDED` (default — out of
+  the price), `FEE_ADDED_AT_CHECKOUT` (the buyer pays 2.5% on top; the event page shows the line),
+  or `NO_FEE` (free tickets; sites that don't require a fee). When Wix answers `INVALID_FEE_TYPE`
+  the seed retries the same tier with `NO_FEE`, then `FEE_ADDED_AT_CHECKOUT`, and reports the one
+  that took in the result's per-event `feeTypes`.
+- `currency` — 3-letter ISO code at the top of the plan, set **only when the brief names one**: a
+  sentence about currency, or a price written with its unit ("9 dollars", "$9", "€20"). Do **not**
+  infer it from a language, a country, or an address. The seed sets the site to it before creating
+  anything, because prices are stored in the site currency at create time; a new site starts in the
+  currency of the account that created it, not the business's.
+- `location` — `{ name, type: "VENUE", address }` (address `subdivision` is ISO-3166-2 like
+  `US-WA`, `country` ISO alpha-2), `{ name, type: "ONLINE" }`, or
+  `{ locationTbd: true, name }`.
+- `category` — a name; created and assigned for you. Skip when the brief has no grouping.
+- `rsvpResponseType` — `"YES_AND_NO"` to let guests decline (default `"YES_ONLY"`).
+- `rsvpLimit` — RSVP only: the number of spots; `waitlist: true` opens a wait list once they are
+  taken (the page then offers "Join the waitlist").
+- `registrationOpensAt` — RSVP only: a future ISO-8601 UTC instant. The event publishes with
+  registration SCHEDULED and the page says when it opens — for a brief like "RSVP opens next week".
+  The API pairs it with a closing instant: `registrationClosesAt` (default: the event's `startDate`).
+- `guests` — RSVP only: how many additional guests one RSVP may bring. Added to the registration
+  form through the Events Forms API after the event is created (a count 0..N and the guests' names);
+  the result's per-event `guestControl` is `true` when it landed. When it did not, the event exists
+  without it and the owner adds the guest control in the dashboard — say so in the closing message.
+
+The result JSON carries a `notes` array — when any event is ticketed it reminds that
+**completing a paid purchase needs a premium plan + a configured payment method** in the
+dashboard. That's an owner step, not a seeding failure; relay it.
+
+**Seeding is additive — never delete or overwrite existing content**; ask first if a cleanup
+seems needed.
+
+## Supplied content
+
+The general rules are in `templates/shared/SUPPLIED-CONTENT.md`. For events, each event the user
+lists is one entry. Its title becomes `title`; its date and time become `startDate` and `endDate` in
+ISO with the `timeZoneId` the user stated; the venue and address become `location`; named tickets
+with prices become `ticketTiers` on a `TICKETING` event, and an event with no tickets is `RSVP`; a
+category becomes `category`; their image becomes `imageUrl`. A date without a year or without a
+time zone is a question for the user, never a guess.
+
+## Escape hatch — individual functions
+`setupEvents` composes exported steps — `installEventsApp`, `getSiteCurrency`, `createEvent`,
+`createTicketTiers`, `publishEvent`, `createEventCategories`, `assignEventsToCategory`,
+`importImage`, `setEventMainImage`, plus `makeCtx()` — import them only for a partial re-seed.
+
+## Reference
+Unexpected shape or an uncovered operation → read the live Wix API reference; every call the script
+makes carries a `docs:` line with its reference page.

package/skills/wix-headless-templates/events/seed/read-site.mjs

@@ -0,0 +1,26 @@
+// What the events site holds: events and their ticket definitions.
+//   node <SKILL_ROOT>/templates/events/seed/read-site.mjs [--site <siteId>] [--limit <n>]
+import { runReader } from "../../shared/seed/read-site.mjs";
+
+const EVENTS_APP_ID = "140603ad-af8d-84a5-2c80-a0f60cb47351";
+const D = "https://dev.wix.com/docs/api-reference/business-solutions/events/event-management";
+
+await runReader({
+  vertical: "events",
+  appId: EVENTS_APP_ID,
+  async read(api, { limit }) {
+    const ev = await api.call({ path: "/events/v3/events/query", body: { query: { filter: { status: { $ne: "CANCELED" } }, paging: { limit } }, fields: ["DETAILS", "REGISTRATION"] }, docs: `${D}/events-v3/query-events` });
+    const td = await api.tryCall({ path: "/events-ticket-definitions/v3/ticket-definitions/query", body: { query: { paging: { limit: 100 } } }, docs: `${D}/ticket-definitions-v3/query-ticket-definitions` });
+    const defs = td?.ticketDefinitions ?? [];
+    return {
+      eventCount: ev.pagingMetadata?.total ?? (ev.events ?? []).length,
+      events: (ev.events ?? []).map((e) => ({
+        title: e.title, slug: e.slug, status: e.status, start: e.dateAndTimeSettings?.startDate ?? null,
+        location: e.location?.name ?? e.location?.type ?? null, registration: e.registration?.type ?? null,
+        tickets: defs.filter((d) => d.eventId === e.id).map((d) => `${d.name}${d.pricingMethod?.fixedPrice?.formattedValue ? " " + d.pricingMethod.fixedPrice.formattedValue : ""}`),
+        image: !!e.mainImage,
+      })),
+      ticketDefinitionCount: defs.length,
+    };
+  },
+});