@wix/agent-skills 1.26.0 → 1.27.0

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

@@ -0,0 +1,124 @@
+// Event reads (Wix Events V3, the `wixEventsV2` module; Categories v1) over the SDK — the only
+// file that touches raw event entities on this transport. Everything it returns is a plain DTO
+// from ./types. The rules and mappers live in ./events-core (shared with the REST twin in
+// templates/events/rest/); this file is the transport only. Copy as-is; extend by adding
+// functions, not by editing these.
+// 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/categories/query-categories.md
+import { categories as categoriesModule, wixEventsV2 } from "@wix/events";
+import { wixModule } from "../sdk";
+import { imgSrc } from "../media";
+import {
+  CATEGORY_ID_FIELD_SDK,
+  CATEGORY_STATES,
+  CREATED_DATE_FIELD_SDK,
+  DEFAULT_PAGE_SIZE,
+  DETAIL_FIELDS,
+  EVENTS_APP_ID,
+  LIST_FIELDS,
+  START_DATE_FIELD,
+  hasMorePages,
+  listQuery,
+  rawId,
+  statusesFor,
+  toCategories,
+  toDetail,
+  toSummary,
+  type ListOptions,
+  type Raw,
+} from "./events-core";
+import type { EventCategory, EventDetail, EventSummary } from "./types";
+
+export { EVENTS_APP_ID, type ListOptions };
+
+const events = wixModule(wixEventsV2);
+const categories = wixModule(categoriesModule);
+
+/** 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 query builder, never a flat/REST `{ query: {...} }` body (the SDK silently ignores
+ * the unknown key and returns zero events). Always set a positive limit — it defaults to 0, which
+ * also returns zero events with no error.
+ */
+export async function fetchEventsPage(options: ListOptions = {}): Promise<EventsPage> {
+  const { limit = DEFAULT_PAGE_SIZE, offset = 0, categoryId, status } = options;
+  listQuery(options); // one validation of limit/offset for both transports
+  let query = events
+    .queryEvents({ fields: LIST_FIELDS as any })
+    .in("status", statusesFor(status))
+    .ascending(START_DATE_FIELD as any)
+    .descending(CREATED_DATE_FIELD_SDK as any)
+    .limit(limit)
+    .skip(offset);
+  // `categories._id` isn't in the builder's typed field list, but the server filters on it (Wix's own listing does this).
+  if (categoryId) query = (query as any).in(CATEGORY_ID_FIELD_SDK, [categoryId]);
+  const res: Raw = await query.find();
+  const items = ((res.items ?? []) as Raw[]).map((e) => toSummary(e, imgSrc));
+  const total = typeof res.totalCount === "number" ? res.totalCount : 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 (Wix's occurrence list does the same).
+ */
+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), as Wix's listing loads them in the browser.
+ * Runs on the visitor token: Query Categories needs WIX_EVENTS.READ_CATEGORIES, which Wix's own
+ * headless demo calls client-side — but it isn't guaranteed for every site's visitor scope, so
+ * callers catch a failure and fall back to the categories on the loaded events.
+ */
+export async function fetchCategories(): Promise<EventCategory[]> {
+  const res: Raw = await categories
+    .queryCategories()
+    .hasSome("states", [...CATEGORY_STATES])
+    .limit(100)
+    .find();
+  return toCategories(res.items);
+}
+
+/** Fetch one event by its URL slug. Null when not found. */
+export async function fetchEventBySlug(slug: string): Promise<EventDetail | null> {
+  try {
+    // getEventBySlug returns a WRAPPED { event } — unlike getEvent below.
+    const res: Raw = await events.getEventBySlug(slug, { fields: DETAIL_FIELDS as any });
+    const raw = res?.event;
+    return raw ? toDetail(raw as Raw, imgSrc) : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Fetch one event by id — the post-checkout confirmation read (the thank-you URL carries
+ * `?orderNumber=&eventId=`). getEvent returns the Event DIRECTLY (unwrapped) — the one read
+ * that isn't `{ event }`; assuming the wrapper crashes the page.
+ */
+export async function fetchEventById(eventId: string): Promise<EventDetail | null> {
+  try {
+    const raw: Raw = await events.getEvent(eventId, { fields: DETAIL_FIELDS as any });
+    return rawId(raw) ? toDetail(raw, imgSrc) : null;
+  } catch {
+    return null;
+  }
+}

package/skills/wix-headless-templates/events/app/wix/events/order-store.ts

@@ -0,0 +1,143 @@
+// The post-checkout confirmation as a framework-free store — the logic behind
+// useEventConfirmation, usable from React (the hook wraps it), from a static confirmation page,
+// from Vue/Svelte, or as the specification for a port. The Wix-hosted checkout redirects to the
+// thank-you URL with `?orderNumber=&eventId=`; this store fetches the event for context and the
+// order for its details, then polls the order every 2 s for up to 15 s until the tickets are
+// generated (Wix's own thank-you page does the same) so the PDF link can appear.
+//
+// The order read runs on the visitor token, as Wix's headless demo does. It isn't guaranteed for
+// every site's visitor scope: when it is refused, `orderUnavailable` is set and the surface shows
+// the confirmation without order details — landing here IS the success signal (Wix redirects only
+// after checkout completes); the tickets arrive by email regardless.
+import { fetchEventById } from "./events";
+import { fetchOrder } from "./orders";
+import { ORDER_POLL_INTERVAL_MS, ORDER_POLL_TOTAL_MS } from "./orders-core";
+import type { EventDetail, OrderSummary } from "./types";
+
+export interface OrderStoreOptions {
+  /** From the thank-you URL. Empty → the honest "no order" state, nothing is fetched. */
+  orderNumber: string;
+  eventId: string;
+}
+
+export interface OrderState {
+  orderNumber: string;
+  eventId: string;
+  /** The event for context (title, date, calendar link); null until loaded or when unavailable. */
+  event: EventDetail | null;
+  /** The order with invoice and tickets; null while loading or when unavailable. */
+  order: OrderSummary | null;
+  /** The order read was refused or found nothing — render the confirmation without details. */
+  orderUnavailable: boolean;
+  /** Still waiting for Wix to generate the tickets (the PDF link appears when `order.ticketsReady`). */
+  polling: boolean;
+  loading: boolean;
+}
+
+export interface OrderStore {
+  getState(): OrderState;
+  subscribe(listener: () => void): () => void;
+  /** Fetch the event and the order, then poll the order until its tickets exist. Call once when mounted (a browser). */
+  start(): void;
+  /** Stop polling; drop late responses. */
+  stop(): void;
+}
+
+export function createOrderStore({ orderNumber, eventId }: OrderStoreOptions): OrderStore {
+  let event: EventDetail | null = null;
+  let order: OrderSummary | null = null;
+  let orderUnavailable = false;
+  let polling = false;
+  let loading = Boolean(orderNumber && eventId);
+  let started = false;
+  let timer: ReturnType<typeof setTimeout> | null = null;
+  const listeners = new Set<() => void>();
+  let snapshot: OrderState | null = null;
+  const emit = () => {
+    snapshot = null;
+    for (const fn of listeners) fn();
+  };
+
+  function getState(): OrderState {
+    if (snapshot) return snapshot;
+    snapshot = { orderNumber, eventId, event, order, orderUnavailable, polling, loading };
+    return snapshot;
+  }
+
+  async function readOrder(): Promise<boolean> {
+    const next = await fetchOrder(eventId, orderNumber);
+    if (!started) return true;
+    if (!next) {
+      orderUnavailable = order === null;
+      return true; // nothing to poll for
+    }
+    order = next;
+    return next.ticketsReady;
+  }
+
+  function schedule(elapsed: number) {
+    if (!started || elapsed >= ORDER_POLL_TOTAL_MS) {
+      polling = false;
+      emit();
+      return;
+    }
+    polling = true;
+    emit();
+    timer = setTimeout(async () => {
+      timer = null;
+      let ready = true;
+      try {
+        ready = await readOrder();
+      } catch {
+        /* a transient failure: keep the last order, try again until the budget is spent */
+        ready = false;
+      }
+      if (!started) return;
+      if (ready) {
+        polling = false;
+        emit();
+      } else {
+        schedule(elapsed + ORDER_POLL_INTERVAL_MS);
+      }
+    }, ORDER_POLL_INTERVAL_MS);
+  }
+
+  return {
+    getState,
+    subscribe(fn) {
+      listeners.add(fn);
+      return () => listeners.delete(fn);
+    },
+    start() {
+      if (started) return;
+      started = true;
+      if (!orderNumber || !eventId) return;
+      fetchEventById(eventId)
+        .then((e) => {
+          if (!started) return;
+          event = e;
+          emit();
+        })
+        .catch(() => {});
+      readOrder()
+        .then((ready) => {
+          if (!started) return;
+          loading = false;
+          emit();
+          if (!ready) schedule(0);
+        })
+        .catch(() => {
+          if (!started) return;
+          // Refused for this visitor scope (or a transient failure) — degrade, never fake details.
+          orderUnavailable = true;
+          loading = false;
+          emit();
+        });
+    },
+    stop() {
+      started = false;
+      if (timer) clearTimeout(timer);
+      timer = null;
+    },
+  };
+}

package/skills/wix-headless-templates/events/app/wix/events/orders-core.ts

@@ -0,0 +1,86 @@
+// Order rules and DTO mapping for the confirmation page — transport-agnostic, imported by both
+// ./orders.ts (SDK) and the REST twin in templates/events/rest/orders.ts (fetch). The fieldsets,
+// the "tickets are ready" rule, the polling cadence, status copy, and the invoice mapping live
+// HERE, once. Raw orders carry Date objects on the SDK and ISO strings on REST; money is
+// `{ value, amount (deprecated), currency }`. Types are imported type-only; the money/date
+// formatters come from ./events-core (the same file both transports ship).
+import type { OrderSummary } from "./types";
+import { formatMoney, isoOf, type Raw } from "./events-core";
+
+/** Get Order fieldsets: TICKETS (the generated tickets), DETAILS (status, created, email, ticketsPdf), INVOICE. */
+export const ORDER_FIELDSETS = ["TICKETS", "DETAILS", "INVOICE"] as const;
+
+/** Wix polls the order every 2 s for up to 15 s until the tickets exist (they are generated after payment). */
+export const ORDER_POLL_INTERVAL_MS = 2000;
+export const ORDER_POLL_TOTAL_MS = 15000;
+
+/** Visitor copy per Wix order status. */
+export const ORDER_STATUS_COPY: Record<string, string> = {
+  FREE: "Confirmed",
+  PAID: "Paid",
+  PENDING: "Payment pending",
+  OFFLINE_PENDING: "Payment due at the event",
+  INITIATED: "Awaiting payment",
+  AUTHORIZED: "Payment authorized",
+  PARTIALLY_PAID: "Partially paid",
+  CANCELED: "Canceled",
+  DECLINED: "Payment declined",
+  VOIDED: "Voided",
+};
+
+/** Wix's isOrderReady: every ordered ticket has been generated. */
+export function orderReady(raw: Raw | null | undefined): boolean {
+  const quantity = Number(raw?.ticketsQuantity);
+  return Number.isFinite(quantity) && quantity === ((raw?.tickets ?? []) as Raw[]).length;
+}
+
+/** "Sep 26, 2026" — the order date in the visitor's locale (Wix formats it without a zone). */
+export function formatOrderDate(value: unknown): string {
+  const iso = isoOf(value);
+  if (!iso) return "";
+  try {
+    return new Intl.DateTimeFormat(undefined, { dateStyle: "medium" }).format(new Date(iso));
+  } catch {
+    return iso.slice(0, 10);
+  }
+}
+
+const percent = (rate: unknown): number => {
+  const n = Number(rate);
+  return Number.isFinite(n) ? n : 0;
+};
+
+/** A raw Order (TICKETS + DETAILS + INVOICE) → the confirmation DTO. */
+export function toOrder(raw: Raw): OrderSummary {
+  const invoice: Raw = raw.invoice ?? {};
+  const discounts: Raw[] = invoice.discount?.discounts ?? [];
+  const coupon = discounts.find((d) => d.coupon);
+  const paidPlan = discounts.find((d) => d.paidPlan);
+  const tax: Raw | undefined = invoice.tax;
+  const fee: Raw | undefined = ((invoice.fees ?? []) as Raw[]).find((f) => f.type === "FEE_ADDED_AT_CHECKOUT");
+  const status: string = raw.status ?? "";
+  const ticketCount = Number(raw.ticketsQuantity);
+  return {
+    number: raw.orderNumber ?? "",
+    status,
+    statusLabel: ORDER_STATUS_COPY[status] ?? "",
+    settled: status === "FREE" || status === "PAID",
+    email: raw.email ?? "",
+    createdLabel: formatOrderDate(raw.created),
+    items: ((invoice.items ?? []) as Raw[]).map((i) => ({
+      name: i.name ?? "",
+      price: formatMoney(i.price),
+      quantity: Number(i.quantity) || 0,
+      total: formatMoney(i.total),
+    })),
+    subtotal: formatMoney(invoice.subTotal),
+    couponDiscount: coupon ? formatMoney(coupon.amount) : "",
+    paidPlanDiscount: paidPlan ? { amount: formatMoney(paidPlan.amount), ratePercent: percent(paidPlan.paidPlan?.percentDiscount?.rate) } : null,
+    tax: tax?.amount ? { name: tax.name ?? "Tax", ratePercent: percent(tax.rate), amount: formatMoney(tax.amount) } : null,
+    fee: fee?.amount ? { amount: formatMoney(fee.amount), ratePercent: percent(fee.rate) } : null,
+    total: formatMoney(invoice.grandTotal ?? raw.totalPrice),
+    ticketsPdfUrl: typeof raw.ticketsPdf === "string" ? raw.ticketsPdf : "",
+    ticketCount: Number.isFinite(ticketCount) ? ticketCount : ((raw.tickets ?? []) as Raw[]).length,
+    ticketsReady: orderReady(raw),
+  };
+}

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

@@ -0,0 +1,30 @@
+// The ticket order behind the confirmation page, over the SDK (Events Orders, `orders.getOrder`).
+// Rules and mappers live in ./orders-core (shared with the REST twin in templates/events/rest/);
+// this file is the transport only. Runs on the visitor token in the browser, as Wix's own
+// headless demo does — the order was created on this visitor's session by the hosted checkout.
+// That read isn't guaranteed for every site's visitor scope: a permission failure throws here and
+// the confirmation surface degrades to "your tickets are on their way" without order details.
+// docs: https://dev.wix.com/docs/api-reference/business-solutions/events/registration/ticketing/orders/get-order.md
+import { orders as ordersModule } from "@wix/events";
+import { wixModule } from "../sdk";
+import { ORDER_FIELDSETS, toOrder } from "./orders-core";
+import type { Raw } from "./events-core";
+import type { OrderSummary } from "./types";
+
+const orders = wixModule(ordersModule);
+
+/**
+ * One order by the pair the thank-you URL carries (`?orderNumber=&eventId=`), with tickets,
+ * details and invoice. Null when Wix has no such order (404); throws on anything else (a 403 on
+ * a visitor scope without the order read) so the caller can degrade honestly. getOrder returns the
+ * Order DIRECTLY (unwrapped).
+ */
+export async function fetchOrder(eventId: string, orderNumber: string): Promise<OrderSummary | null> {
+  try {
+    const raw: Raw = await orders.getOrder({ eventId, orderNumber }, { fieldset: ORDER_FIELDSETS as any });
+    return raw?.orderNumber ? toOrder(raw) : null;
+  } catch (e) {
+    if ((e as Raw)?.status === 404 || (e as Raw)?.details?.applicationError?.code === "ORDER_NOT_FOUND") return null;
+    throw e;
+  }
+}