@wix/agent-skills 1.26.0 → 1.27.0

package/skills/wix-headless-templates/events/project/src/wix/events/registration.ts

@@ -0,0 +1,109 @@
+// Ticket tiers, the reserve → hosted-checkout redirect, and RSVP over the SDK. Rules and mappers
+// live in ./registration-core (shared with the REST twin in templates/events/rest/); this file is
+// the transport only. The payload shapes are exact and easy to get subtly wrong — copy as-is;
+// extend by calling these exports, never by editing them. Failures are loud. Everything runs as
+// the anonymous VISITOR — no server route, no elevation, anywhere.
+// 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 { rsvpV2, ticketDefinitionsV2, ticketReservations } from "@wix/events";
+import { redirects as redirectsModule } from "@wix/redirects";
+import { wixModule } from "../sdk";
+import {
+  availableTiersQuery,
+  checkoutCallbacks,
+  redirectResult,
+  reservationError,
+  reservationId,
+  reservationTickets,
+  rsvpBody,
+  rsvpFormOf,
+  rsvpResult,
+  toTiers,
+  type CheckoutEvent,
+  type CheckoutPaths,
+  type RsvpValues,
+  type TierEvent,
+} from "./registration-core";
+import type { Raw } from "./events-core";
+import type { EventDetail, RegistrationResult, TicketSelection, TicketTier } from "./types";
+
+export { type CheckoutPaths, type RsvpValues, type TierEvent };
+
+const ticketDefinitions = wixModule(ticketDefinitionsV2);
+const reservations = wixModule(ticketReservations);
+const rsvps = wixModule(rsvpV2);
+const redirects = wixModule(redirectsModule);
+
+/**
+ * Ticket tiers for a TICKETING event, in the organizer's order, with pricing method, availability,
+ * sale period and the tax/fee lines checkout adds. Reads the VISITOR-public Query Available Ticket
+ * Definitions (V3; hidden tiers excluded server-side) — never queryTicketDefinitions: that is the
+ * management read and 403s the anonymous visitor (auth.elevate() is the wrong fix — wrong axis,
+ * SSR-only). Pass the EventDetail: the sale dates format in its zone and its tax settings price
+ * the notes.
+ */
+export async function fetchTicketTiers(event: TierEvent): Promise<TicketTier[]> {
+  const res: Raw = await ticketDefinitions.queryAvailableTicketDefinitions(availableTiersQuery(event.id) as any);
+  return toTiers(res.ticketDefinitions, event);
+}
+
+/**
+ * RSVP to a free (RSVP-type) event — completes fully client-side: no reservation, no redirect, no
+ * payment. `values` are the answers to the ORGANIZER'S form (event.rsvpForm — the FORM fieldset),
+ * keyed by input name; the built-in name + email inputs are part of it. Create RSVP rejects a
+ * missing mandatory answer, an unknown input name, or a value outside the predefined options
+ * (INVALID_FORM_RESPONSE). `guests` only matters when the form has a guest control. Send "NO" only
+ * when the event's rsvpResponseType is "YES_AND_NO". Throws on closed registration, a guest limit,
+ * or an invalid email — surface the message (a repeat email is accepted by default; the organizer's
+ * settings decide). A full event with a waitlist returns status "WAITLIST" — tell the guest they're
+ * waitlisted, not confirmed.
+ */
+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> {
+  // rsvpV2 takes the rsvp object DIRECTLY as the first arg (never wrapped in { rsvp: … }),
+  // and only rsvpV2 works for visitors — the legacy v1 `rsvp` module 400s on these fields.
+  const res: Raw = await rsvps.createRsvp(rsvpBody(event.id, rsvpFormOf(event), values, status, guests) as any);
+  return rsvpResult(res, status);
+}
+
+/**
+ * Ticketed checkout, the exact sequence: reserve the selected tiers (holds them, PENDING,
+ * auto-expires), then mint the Wix-hosted checkout redirect and return its URL — the caller
+ * navigates 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` on the line
+ * item); pass `tiers` so a missing guest price is refused before the request. Call from the
+ * browser: it needs window.location.origin (the published https host — an http or server-derived
+ * origin isn't on the redirect allowlist and 403s the return), and createRedirectSession must run
+ * as the visitor (it embeds the headless OAuth client and rejects admin/elevated tokens). Never
+ * hand-build the checkout URL — the Wix-site `…/ticket-form?reservationId=` path 404s on a headless
+ * site. `paths` overrides the return routes (a static site's `event-confirmation.html`).
+ */
+export async function startTicketCheckout(
+  event: CheckoutEvent,
+  selections: TicketSelection[],
+  paths: CheckoutPaths = {},
+  tiers: TicketTier[] = [],
+): Promise<RegistrationResult> {
+  const tickets = reservationTickets(event.id, selections, tiers);
+  let reservation: Raw;
+  try {
+    reservation = await reservations.createTicketReservation({ tickets } as any);
+  } catch (e) {
+    throw reservationError(e);
+  }
+  const origin = typeof window !== "undefined" ? window.location.origin : "";
+  const session: Raw = await redirects.createRedirectSession({
+    eventsCheckout: { reservationId: reservationId(reservation), eventSlug: event.slug },
+    // Wix appends ?orderNumber=&eventId= to the thank-you URL — the shipped /event-confirmation page reads them.
+    callbacks: checkoutCallbacks(origin, event.slug, paths),
+  });
+  return redirectResult(session);
+}

package/skills/wix-headless-templates/events/project/src/wix/events/types.ts

@@ -0,0 +1,249 @@
+// Events DTOs — the serializable shapes every hook, component, and page consumes.
+// Plain JSON: safe as Astro island props or across server/client boundaries. Images are
+// resolved https URLs; every displayable price is a ready formatted string; every date label is
+// formatted in the EVENT's time zone (a venue event shown in the browser's zone is wrong).
+
+/** The current registration flavor — every registration surface branches on this. */
+export type RegistrationType = "RSVP" | "TICKETING" | "EXTERNAL" | "NONE";
+
+/** Event lifecycle (Events V3 `status`) — only UPCOMING/STARTED are listed by default. */
+export type EventStatus = "UPCOMING" | "STARTED" | "ENDED" | "CANCELED" | "DRAFT";
+
+/**
+ * Events V3 `registration.status`. Closed means exactly CLOSED_MANUALLY / CLOSED_AUTOMATICALLY;
+ * SCHEDULED_RSVP opens later; OPEN_RSVP_WAITLIST_ONLY accepts registrations onto a waitlist.
+ */
+export type RegistrationStatus =
+  | "OPEN_RSVP"
+  | "OPEN_RSVP_WAITLIST_ONLY"
+  | "OPEN_TICKETS"
+  | "OPEN_EXTERNAL"
+  | "SCHEDULED_RSVP"
+  | "CLOSED_MANUALLY"
+  | "CLOSED_AUTOMATICALLY"
+  | "UNKNOWN_REGISTRATION_STATUS";
+
+/** An event as a listing/grid tile needs it. */
+export interface EventSummary {
+  id: string;
+  slug: string;
+  title: string;
+  /** Plain-text teaser, safe to render directly (the rich description never leaves the data layer). */
+  shortDescription: string;
+  status: EventStatus;
+  /**
+   * Human-formatted date/time from Wix in the event's zone, e.g. "Sep 26, 2026, 7:00 PM"; the
+   * organizer's TBD message when the date is TBD ("" only when both are missing).
+   */
+  dateLabel: string;
+  /** ISO start/end instants for custom formatting/grouping ("" when the date is TBD). */
+  startDateIso: string;
+  endDateIso: string;
+  /** IANA zone of the event ("" when unknown) — pass as `timeZone` to Intl for any date you format yourself. */
+  timeZoneId: string;
+  /** True when the organizer marked the schedule TBD; `dateTbdMessage` is their copy for it. */
+  dateTbd: boolean;
+  dateTbdMessage: string;
+  /** Organizer display flags for the schedule. */
+  hideEndDate: boolean;
+  showTimeZone: boolean;
+  locationName: string;
+  locationType: "VENUE" | "ONLINE" | "TBD";
+  /** Resolved https URL ("" when the event has no image). */
+  imageUrl: string;
+  registrationType: RegistrationType;
+  /** "From €25.00" (ticketed), "Free" (RSVP / free tickets), "" when nothing applies. */
+  priceLabel: string;
+  soldOut: boolean;
+  /** Manual categories only (the per-series RECURRING_EVENT and hidden ones are dropped). */
+  categories: { id: string; name: string }[];
+  /** "RECURRING" / "RECURRING_UPCOMING" for one date of a series; "ONE_TIME" otherwise. */
+  recurrenceStatus: string;
+  /** Every date of a recurring series shares this id ("" for a one-time event) — `fetchOccurrences(id)` lists them. */
+  recurringCategoryId: string;
+}
+
+/** A category as the filter pills need it. */
+export interface EventCategory {
+  id: string;
+  name: string;
+}
+
+/** One field of the organizer's RSVP form (Events V3 `form.controls[].inputs[]`). */
+export interface RsvpFormInput {
+  /** The `inputName` to submit under. */
+  name: string;
+  label: string;
+  mandatory: boolean;
+  /** Wix value type: TEXT (also DROPDOWN/RADIO values), NUMBER, TEXT_ARRAY (CHECKBOX), DATE_TIME, ADDRESS. */
+  type: "TEXT" | "NUMBER" | "TEXT_ARRAY" | "DATE_TIME" | "ADDRESS";
+  /** Predefined choices (DROPDOWN / RADIO / CHECKBOX); the submitted value must be one of them. */
+  options: string[];
+  /** Max characters for text inputs (0 = unlimited). */
+  maxLength: number;
+}
+
+/** One control of the organizer's RSVP form; the built-in name and email controls carry `system: true`. */
+export interface RsvpFormControl {
+  id: string;
+  type:
+    | "INPUT"
+    | "TEXTAREA"
+    | "DROPDOWN"
+    | "RADIO"
+    | "CHECKBOX"
+    | "NAME"
+    | "GUEST_CONTROL"
+    | "ADDRESS_SHORT"
+    | "ADDRESS_FULL"
+    | "DATE";
+  system: boolean;
+  inputs: RsvpFormInput[];
+}
+
+/** The organizer's RSVP form: controls in display order, plus the "+guests" control when enabled. */
+export interface RsvpForm {
+  /** Every non-deleted control except GUEST_CONTROL, in `orderIndex` order. */
+  controls: RsvpFormControl[];
+  /** Present when the organizer lets a guest bring others — rendered as a 0..maxGuests picker plus names. */
+  guestControl: { label: string; maxGuests: number; namesLabel: string } | null;
+}
+
+/** Event-level tax settings (`registration.tickets.taxSettings`) — what the hosted checkout charges. */
+export interface TaxSettings {
+  name: string;
+  /** e.g. 21 for "21%". */
+  ratePercent: number;
+  /** INCLUDED_IN_PRICE → prices already contain it; else it is added at checkout. */
+  includedInPrice: boolean;
+  appliedToDonations: boolean;
+}
+
+/** An event as the detail/registration page needs it. */
+export interface EventDetail extends EventSummary {
+  /** Long description as plain paragraphs (extracted from the rich content; may be empty). */
+  aboutParagraphs: string[];
+  /** Wix's formatted schedule parts ("" for a TBD schedule; end parts "" when the end date is hidden). */
+  formatted: { startDate: string; startTime: string; endDate: string; endTime: string };
+  /** Full formatted street address ("" for ONLINE/TBD). */
+  address: string;
+  /** Venue coordinates when Wix geocoded the address — for a map embed. */
+  coordinates: { lat: number; lng: number } | null;
+  /** The raw Wix registration status — branch on the booleans below, keep this for copy. */
+  registrationStatus: RegistrationStatus;
+  /** Accepting registrations RIGHT NOW (an OPEN_* status, not paused) — the form/picker renders only then. */
+  registrationOpen: boolean;
+  /** CLOSED_MANUALLY / CLOSED_AUTOMATICALLY — the honest closed state (sold out when `soldOut`). */
+  registrationClosed: boolean;
+  /** SCHEDULED_RSVP: when registration opens ("" otherwise), raw and formatted in the event's zone. */
+  registrationOpensAtIso: string;
+  registrationOpensAtLabel: string;
+  /** The organizer paused registration — open status, but nothing is accepted. */
+  registrationPaused: boolean;
+  /** OPEN_RSVP_WAITLIST_ONLY: the guest list is full; an RSVP joins the waitlist. */
+  waitlistOnly: boolean;
+  /** `allowedGuestTypes === "MEMBER"`: only signed-in site members may register. */
+  membersOnly: boolean;
+  /** RSVP events: "YES_AND_NO" also allows a "can't make it" reply. */
+  rsvpResponseType: "YES_ONLY" | "YES_AND_NO";
+  /** RSVP events: the organizer's form (from the FORM fieldset); null for other types. */
+  rsvpForm: RsvpForm | null;
+  /** EXTERNAL events: the outbound registration URL ("" otherwise). */
+  externalUrl: string;
+  /** The event's page on the organizer's Wix site ("" when unavailable). */
+  eventPageUrl: string;
+  addToCalendar: { google: string; ics: string };
+  /** TICKETING: tax the hosted checkout applies (null when none is configured). */
+  taxSettings: TaxSettings | null;
+  /** TICKETING: max tickets in one order (Wix default 20, max 50) — the picker caps the total here. */
+  ticketLimitPerOrder: number;
+}
+
+/** A purchasable ticket tier (TICKETING events, Ticket Definitions V3). */
+export interface TicketTier {
+  id: string;
+  name: string;
+  description: string;
+  /**
+   * FIXED: one price. FREE: no charge. GUEST: the guest names the amount (a donation, at least
+   * `minPrice`). OPTIONS: several named prices, each picked with its own quantity.
+   */
+  pricingType: "FIXED" | "FREE" | "GUEST" | "OPTIONS";
+  /** Formatted: "€45.00" (FIXED), "Free" (FREE), "€10.00 – €25.00" (OPTIONS range), "" (GUEST). */
+  price: string;
+  /** FIXED: the raw decimal ("45.00") behind `price` — for totals only, never displayed ("0" otherwise). */
+  priceValue: string;
+  free: boolean;
+  /** GUEST: formatted minimum ("€5.00") and its raw decimal ("5.00") for validation; "" otherwise. */
+  minPrice: string;
+  minPriceValue: string;
+  /** ISO currency of the tier ("" when unknown). */
+  currency: string;
+  /** OPTIONS: the named prices (`value` is the raw decimal for totals, never displayed); `notes` are that option's tax/fee lines. Empty for other types. */
+  options: { id: string; name: string; price: string; value: string; notes: string[] }[];
+  /** Tax and Wix fee lines the checkout adds, e.g. ["+€9.45 VAT", "+€1.36 ticket service fee"] or ["VAT included"]. */
+  notes: string[];
+  /** Max quantity per order for this tier RIGHT NOW; 0 means sold out (Wix lowers it to the unsold count). */
+  limitPerCheckout: number;
+  soldOut: boolean;
+  /** "SALE_STARTED" is the only buyable status. */
+  saleStatus: "SALE_SCHEDULED" | "SALE_STARTED" | "SALE_ENDED";
+  /** Buyable now: on sale and not sold out — enable the controls on this. */
+  available: boolean;
+  /** SALE_SCHEDULED: "Goes on sale" moment, formatted in the event's zone ("" otherwise). */
+  saleStartsLabel: string;
+  /** Sale end moment, formatted in the event's zone ("" when there is none or the sale hasn't started). */
+  saleEndsLabel: string;
+  /** Wix fee handling: FEE_ADDED_AT_CHECKOUT adds 2.5% at checkout; FEE_INCLUDED/NO_FEE add nothing. */
+  feeType: "FEE_INCLUDED" | "FEE_ADDED_AT_CHECKOUT" | "NO_FEE" | "";
+}
+
+/** One line of the picker's selection: a tier, optionally one of its pricing options, and for GUEST tiers the named price. */
+export interface TicketSelection {
+  tierId: string;
+  quantity: number;
+  optionId?: string;
+  /** GUEST tiers: the decimal the guest typed ("25.00"). */
+  guestPrice?: string;
+}
+
+/** The picker's running totals, mirroring Wix's own picker; the hosted checkout is authoritative. */
+export interface SelectionTotals {
+  subtotal: string;
+  tax: string;
+  fee: string;
+  total: string;
+}
+
+/** The outcome of a registration: the browser is redirecting to Wix checkout, or the RSVP is in. */
+export type RegistrationResult =
+  | { kind: "redirect"; url: string }
+  | { kind: "rsvpConfirmed"; status: "YES" | "NO" | "WAITLIST" };
+
+/** A ticket order as the confirmation page shows it (Orders `getOrder`, TICKETS + DETAILS + INVOICE). */
+export interface OrderSummary {
+  number: string;
+  /** Wix order status: FREE, PAID, PENDING, OFFLINE_PENDING, INITIATED, CANCELED, DECLINED, … */
+  status: string;
+  /** Visitor copy for the status ("Paid", "Awaiting payment", …). */
+  statusLabel: string;
+  /** FREE or PAID — the order is settled. */
+  settled: boolean;
+  email: string;
+  /** "Sep 26, 2026" — the order date. */
+  createdLabel: string;
+  items: { name: string; price: string; quantity: number; total: string }[];
+  subtotal: string;
+  /** "" when no coupon applied. */
+  couponDiscount: string;
+  paidPlanDiscount: { amount: string; ratePercent: number } | null;
+  tax: { name: string; ratePercent: number; amount: string } | null;
+  /** The Wix ticket service fee when it was added at checkout. */
+  fee: { amount: string; ratePercent: number } | null;
+  total: string;
+  /** Download link for the ticket PDF ("" until the tickets are generated). */
+  ticketsPdfUrl: string;
+  ticketCount: number;
+  /** Tickets are generated asynchronously after payment — true once every ticket exists. */
+  ticketsReady: boolean;
+}

package/skills/wix-headless-templates/events/project/src/wix/media.ts

@@ -0,0 +1,106 @@
+// Wix media resolution — define once, use on EVERY image render path. Copy as-is.
+//
+// SDK media fields come back either as an already-absolute https URL, or as a
+// `wix:image://v1/<hash>/<file>#originWidth=…` identifier that a browser cannot load
+// (ERR_UNKNOWN_URL_SCHEME). The wix:image:// form must go through the SDK media module;
+// never hand-build a static.wixstatic.com URL (wrong format → 403).
+// docs: https://dev.wix.com/docs/sdk/core-modules/sdk/media.md
+import { media } from "@wix/sdk";
+
+type MediaLike =
+  | string
+  | null
+  | undefined
+  | { image?: unknown; url?: string | null; id?: string | null };
+
+/** A bare Wix media file id (`e6a89e_06cf…~mv2.png`): what REST-shaped media objects carry as `url` and `id`. */
+const BARE_FILE_ID = /^[\w-]+~mv2\.[a-z0-9]+$/i;
+
+function rawOf(value: MediaLike): string {
+  if (!value) return "";
+  if (typeof value === "string") return value;
+  if (value.image != null && typeof value.image === "object") return rawOf(value.image as MediaLike); // { image: { id, url } }
+  return (typeof value.image === "string" ? value.image : null) ?? value.url ?? value.id ?? "";
+}
+
+/** Resolve any Wix media value to a browser-loadable URL ("" when absent). */
+export function imgSrc(value: MediaLike, width = 600, height = 600): string {
+  const v = rawOf(value);
+  if (!v) return "";
+  if (v.startsWith("wix:image://")) {
+    return media.getScaledToFillImageUrl(v, width, height, {});
+  }
+  // A bare file id (what REST-shaped media objects carry) or an absolute Wix media URL (bare, or
+  // already carrying a /v1/fill/ segment at some other size): re-issue it through the scaler at the
+  // requested size, so every image path lands on one shape.
+  const file = BARE_FILE_ID.test(v) ? v : v.match(/^https:\/\/static\.wixstatic\.com\/media\/([^/?#]+)/)?.[1];
+  if (file) return `https://static.wixstatic.com/media/${file}/v1/fill/w_${width},h_${height},al_c,q_90/${file}`;
+  return v;
+}
+
+/**
+ * Responsive candidates for `srcset`: the same image at several widths through Wix's scaler, so a
+ * card never downloads a hero-sized file. Pair with `sizes`:
+ *   <img src={imgSrc(m, 640, 640)} srcSet={imgSrcSet(m)} sizes="(min-width: 1024px) 25vw, 50vw"
+ *        width={640} height={640} loading="lazy" alt={…} />
+ * Accepts every form an image reaches you in: a raw `wix:image://` id, an ALREADY-RESOLVED Wix URL
+ * (what the DTOs carry — `imageUrl`, `gallery[]`; its `/v1/fill/w_…,h_…` segment is rewritten per
+ * width), or any other https URL (returned as the single candidate). `ratio` is height/width
+ * (1 = square). "" only when there is no image at all — still set `src` as well.
+ */
+export function imgSrcSet(value: MediaLike, widths: number[] = [320, 480, 640, 960], ratio = 1): string {
+  const raw = rawOf(value);
+  if (!raw) return "";
+  if (raw.startsWith("wix:image://") || BARE_FILE_ID.test(raw)) {
+    return widths.map((w) => `${imgSrc(value, w, Math.round(w * ratio))} ${w}w`).join(", ");
+  }
+  // A resolved Wix URL: …/v1/fill/w_800,h_800,al_c,… — swap the size for each width.
+  const FILL = /\/v1\/fill\/w_\d+,h_\d+/;
+  if (/static\.wixstatic\.com\//.test(raw) && FILL.test(raw)) {
+    return widths.map((w) => `${raw.replace(FILL, `/v1/fill/w_${w},h_${Math.round(w * ratio)}`)} ${w}w`).join(", ");
+  }
+  return raw; // one candidate, never an empty srcset for a real image
+}
+
+/**
+ * Everything an <img> needs for one Wix image, so a tile can never ship `srcSet` without `src`:
+ *   <img {...imgAttrs(p.imageUrl, "(min-width: 1024px) 25vw, 50vw")} alt={p.name} />
+ * `sizes` is the width the image renders at (a CSS length or media-query list); `ratio` is
+ * height/width. Returns an empty object when there is no image — render your placeholder then.
+ */
+export function imgAttrs(value: MediaLike, sizes: string, ratio = 1): { src: string; srcSet: string; sizes: string; loading: "lazy"; decoding: "async" } | Record<string, never> {
+  const src = imgSrc(value, 640, Math.round(640 * ratio));
+  if (!src) return {};
+  return { src, srcSet: imgSrcSet(value, undefined, ratio), sizes, loading: "lazy", decoding: "async" };
+}
+
+/**
+ * Height/width of a Wix image when the value carries its size: a raw
+ * `wix:image://…#originWidth=W&originHeight=H` id (the natural size) or a resolved `/v1/fill/w_W,h_H/`
+ * URL (the size it was scaled to). null when neither is present. Pass it as `ratio` to keep a
+ * srcset at the image's own aspect instead of the square default:
+ *   <img {...imgAttrs(item.photo, "33vw", imgRatio(item.photo) ?? 1)} alt={…} />
+ */
+export function imgRatio(value: MediaLike): number | null {
+  const v = rawOf(value);
+  if (typeof v !== "string" || !v) return null;
+  const size = v.startsWith("wix:image://")
+    ? [v.match(/[#&]originWidth=(\d+)/)?.[1], v.match(/[#&]originHeight=(\d+)/)?.[1]]
+    : (v.match(/\/v1\/fill\/w_(\d+),h_(\d+)/)?.slice(1) ?? []);
+  const w = Number(size[0]);
+  const h = Number(size[1]);
+  return w > 0 && h > 0 ? h / w : null;
+}
+
+/**
+ * The identity of a media value BEFORE scaling — de-duplicate galleries on this, never on a
+ * resolved URL (two scaled URLs of one photo differ in their size parameters).
+ */
+export function mediaKey(value: MediaLike): string {
+  const v = rawOf(value);
+  if (!v) return "";
+  // The file id, whichever form the value takes — a raw id and a resolved URL of one photo share it.
+  if (v.startsWith("wix:image://")) return v.slice("wix:image://v1/".length).split("/")[0].split("#")[0];
+  const m = v.match(/^https:\/\/static\.wixstatic\.com\/media\/([^/?#]+)/);
+  return m ? m[1] : v;
+}

package/skills/wix-headless-templates/events/project/src/wix/money.ts

@@ -0,0 +1,24 @@
+// Money formatting for API amounts that carry no formatted string. Copy as-is.
+//
+// Catalog prices come with a ready `formattedAmount` — use that directly. But eCom Cart V2
+// amounts are ConvertedMoney `{ amount, convertedAmount }` with NO formatted string, and the
+// currency lives on the cart, not on the money object. Never hardcode "$" or assume USD.
+export interface ConvertedMoneyLike {
+  amount?: string | null;
+  convertedAmount?: string | null;
+}
+
+/** Format a ConvertedMoney in the given currency, using the visitor's locale. */
+export function formatMoney(
+  money: ConvertedMoneyLike | null | undefined,
+  currencyCode: string | null | undefined,
+): string {
+  const value = money?.convertedAmount ?? money?.amount;
+  if (value == null || value === "") return "";
+  const currency = currencyCode || "USD";
+  try {
+    return new Intl.NumberFormat(undefined, { style: "currency", currency }).format(Number(value));
+  } catch {
+    return `${value} ${currency}`;
+  }
+}

package/skills/wix-headless-templates/events/project/src/wix/sdk.ts

@@ -0,0 +1,89 @@
+// The one auth seam for every Wix SDK call in this app. Copy as-is; do not rewrite.
+//
+// Two modes, switched by WIX_CLIENT_ID in ./config:
+//   null (ambient)  — a Wix-managed Astro project: `@wix/astro` authenticates raw SDK module
+//                     calls automatically, server-side AND in client islands. `wixModule()`
+//                     returns the module untouched.
+//   string (manual) — any other React setup (Vite SPA, non-Astro): one shared client is built
+//                     with OAuthStrategy, and `wixModule()` returns the module bound to it.
+//                     The strategy self-manages visitor tokens on every call (mints on first
+//                     use, renews on expiry) and persists them through the storage below.
+//
+// The visitor token IS the identity of the current cart / member session, so in manual mode
+// tokens persist to localStorage — never re-minted per load (a fresh anonymous mint is a NEW
+// visitor and silently empties the cart).
+// docs: https://dev.wix.com/docs/sdk/core-modules/sdk/oauth-strategy.md
+// docs: https://dev.wix.com/docs/go-headless/wix-managed-headless/authentication/about-the-astro-integration.md
+import { createClient, OAuthStrategy, EMPTY_TOKENS } from "@wix/sdk";
+import { fetchWithAuth as ambientFetch } from "@wix/sdk/context";
+import type { IOAuthStrategy, TokenStorage, Tokens } from "@wix/sdk";
+import { WIX_CLIENT_ID } from "./config";
+
+const STORAGE_KEY = `wix-session-${WIX_CLIENT_ID ?? "ambient"}`;
+
+function browserTokenStorage(): TokenStorage {
+  return {
+    getTokens(): Tokens {
+      if (typeof window !== "undefined") {
+        try {
+          const raw = window.localStorage.getItem(STORAGE_KEY);
+          if (raw) return JSON.parse(raw) as Tokens;
+        } catch {
+          /* disabled/corrupt storage — fall through to empty */
+        }
+      }
+      return EMPTY_TOKENS;
+    },
+    setTokens(tokens: Tokens): void {
+      if (typeof window === "undefined") return;
+      try {
+        window.localStorage.setItem(STORAGE_KEY, JSON.stringify(tokens));
+      } catch {
+        /* storage full/disabled — the session just won't survive a reload */
+      }
+    },
+  };
+}
+
+const client = WIX_CLIENT_ID
+  ? createClient({
+      auth: OAuthStrategy({
+        clientId: WIX_CLIENT_ID,
+        tokenStorage: browserTokenStorage(),
+      }),
+    })
+  : null;
+
+/**
+ * Bind an SDK module to this app's auth. Usage (identical in both modes):
+ *   import { productsV3 } from "@wix/stores";
+ *   const products = wixModule(productsV3);
+ *   await products.queryProducts(...)
+ */
+export function wixModule<T>(module: T): T {
+  // The cast bridges the SDK's internal Descriptors constraint; the in/out type is identical.
+  return client
+    ? (client.use(module as unknown as Record<string, unknown>) as unknown as T)
+    : module;
+}
+
+/**
+ * An authenticated fetch of a Wix REST endpoint under the SAME auth as the SDK modules (ambient
+ * on managed Astro, the shared client elsewhere) — for the few APIs whose generated SDK module is
+ * too heavy to bundle (the Forms schema module alone is 15 MB: server-side it pushes a Wix
+ * deploy past its size limit, client-side every visitor downloads it). Same visitor identity,
+ * same token, no second mint. `path` is the wixapis.com path; returns the raw Response.
+ */
+export function wixFetch(path: string, init?: RequestInit): Promise<Response> {
+  const url = path.startsWith("http") ? path : `https://www.wixapis.com${path}`;
+  return client ? client.fetchWithAuth(url, init) : ambientFetch(url, init);
+}
+
+/**
+ * The shared data client's manual-mode auth strategy, or null under ambient auth. The
+ * Members vertical deliberately owns a separate explicit client for its custom in-app login;
+ * app code reads that session through the members hooks instead.
+ */
+export function wixAuth(): IOAuthStrategy | null {
+  return client ? client.auth : null;
+}

package/skills/wix-headless-templates/events/project/tsconfig.json

@@ -0,0 +1,5 @@
+{
+  "extends": "astro/tsconfigs/strict",
+  "include": [".astro/types.d.ts", "**/*"],
+  "exclude": ["dist"]
+}