@wix/agent-skills 1.14.0 → 1.15.0

package/skills/wix-headless/references/inline-recipes/how-to-code-cms.md

@@ -0,0 +1,163 @@
+---
+name: "How to Code CMS"
+description: The frontend read/write contract for Wix CMS (Wix Data) — the `@wix/data` `items.query` builder, the `_id`-and-fields-on-the-item shape (not `item.data.field`), why public-read collections need no `auth.elevate`, how to resolve images and render Ricos rich text, and the visitor-write path for collaborative collections (`items.insert`/`update`/`remove`, the update-replaces-whole-item footgun, shared/unscoped data). Specifies the *how* (module + exact calls + the failure modes the docs omit); which collections to render/write come from the request.
+---
+**RECIPE**: How to Code a Wix CMS Frontend (`@wix/data`, Wix Data v2)
+
+A concise contract for writing the **frontend code** that reads Wix CMS collections: listing items, filtering, following references, and rendering images and rich text. **This recipe is the *how* (which module, which calls, which fields), not the *what*** — which collections to show, how the page looks, and the framework are decided by the request you're fulfilling.
+
+> **This recipe is for CODING the frontend, not for seeding it.** It assumes the collections and items already exist and are **public-read** (created by `setup-cms.md`). It says nothing about creating collections or inserting data — only how to read them from frontend code.
+
+> **⚠️ Reading rule — always append `.md?apiView=SDK` to every doc link below.** The Wix docs render two views of the same page. The **bare / REST view** describes the REST shape — items nested under `item.data.<field>` and queried via a `POST /items/query` body. The **`?apiView=SDK` view** describes the SDK shape — items with **fields on the item itself** and a chainable `items.query(...)` builder. The SDK is what your frontend calls; reading the REST view by mistake is the source of the `item.data.title`-returns-`undefined` bug below. Fetch the `.md?apiView=SDK` form directly.
+
+---
+
+## The module and the client (read this first)
+
+**⚠️ CRITICAL: the Wix Data items API is the `items` named export of `@wix/data`** — `import { items } from "@wix/data"`, then `items.query` / `items.get` / `items.insert` / `items.update` / `items.remove` (plus `items.bulkInsert` / `items.queryReferenced`). Do **not** import from the internal `@wix/wix-data-items-sdk` — `@wix/data` is the single documented package.
+
+| Need | Package | Module / export |
+|---|---|---|
+| Read collection items (query, get, filter, references) | `@wix/data` | `items` |
+| Resolve `wix:image://` URIs to URLs | `@wix/sdk` | `media` |
+
+**Collection id has NO namespace.** A native collection's id is just the name the seed created (`"team-members"`, `"faq"`, `"Projects"`) — pass it straight to `items.query("team-members")`. The `<namespace>/<name>` form is only for Wix App collections. Stay consistent with the `collectionId` the seed recipe kept.
+
+**Auth / client — framework split:**
+- **Astro (Wix-managed):** authentication is ambient. Call `items.query(...)` directly from server components and backend routes (`src/pages/api/*.ts`) — **no `createClient`, no `OAuthStrategy`, no `clientId`.**
+- **Non-Astro (Vite/React/Vue/static):** build one manual visitor client and reuse it:
+  ```js
+  import { createClient, OAuthStrategy } from '@wix/sdk';
+  import { items } from '@wix/data';
+
+  const client = createClient({
+    modules: { items },
+    auth: OAuthStrategy({ clientId: /* the project's PUBLIC OAuth client id */ }),
+  });
+  // then: client.items.query('team-members').find()
+  ```
+  The `clientId` is public, not a secret.
+
+**⚠️ CRITICAL: do NOT call `auth.elevate` — public collections are public-read, and member-scoped ones use the member token.** `setup-cms.md` creates a public collection with `read: "ANYONE"`, so the visitor token reads it directly. A pure SPA/static frontend has **no server and cannot elevate** at all; even on Astro the read is visitor-scoped and needs no elevation. (Elevation is only for collections that genuinely can't be public — not the case here.) **If a query on a PUBLIC collection comes back empty, it wasn't seeded public-read — that's a permissions bug in the seed, not a query bug** (re-check the collection's `read` permission); don't reach for `elevate` to paper over it.
+
+**Member-scoped collections (only when the run includes members login).** A collection seeded member-scoped (`setup-cms.md` → `SITE_MEMBER_AUTHOR` for per-user-private, or `SITE_MEMBER` for member-only) is read/written with the **logged-in member's token** — the same client, just after the member has logged in (see `how-to-code-members-astro.md` / `how-to-code-members-non-astro.md`). Key rules:
+- **Still NO `auth.elevate`.** The member token carries the identity; the platform scopes the rows server-side. Reaching for elevate here is the wrong axis (it's for admin/site-wide reads, not a member's own data).
+- **`SITE_MEMBER_AUTHOR` returns only the caller's OWN rows automatically** (matched on the item's `_owner`) — you don't filter by owner in the query, and you **must not** set `_owner` on insert (the platform stamps it from the member identity). `items.query('my-notes').find()` as member A returns A's notes; as member B, B's.
+- **An anonymous / not-yet-logged-in read returns ZERO items — that's the gate, not a bug.** Don't render a member-scoped surface to anonymous visitors: gate the route/page behind login first (bounce to the login flow), *then* query. An empty result after a confirmed login on a `SITE_MEMBER_AUTHOR` collection just means that member has no rows yet (show an empty state), not a permissions error.
+
+---
+
+## The shape you read (field cheat-sheet)
+
+```jsonc
+// items.query("CollectionId").find()  →  result.items[]
+item = {
+  _id,                                  // the item id (SDK normalizes to _id, NOT id)
+  _createdDate, _updatedDate, _owner,   // system fields
+  name, role, bio, order,               // YOUR fields — directly on the item (NOT item.data.name)
+}
+// result also has: result.length, result.hasNext(), result.pageSize
+```
+
+`result.items[]` is the array; paging via `result.hasNext()` / a follow-up `.find()`. A `wix:image://` value in an IMAGE field and a Ricos object in a RICH_TEXT/RICH_CONTENT field both need resolving before render (see below).
+
+---
+
+## The features (build the ones the site needs)
+
+Each section is a **self-contained feature** — implement only what the site uses, in any order.
+
+### Listing / reading (and the field-access rule)
+
+Query a collection with the chainable builder; `.find()` resolves to `{ items, ... }`.
+Doc: <https://dev.wix.com/docs/sdk/business-solutions/data/items/query.md?apiView=SDK>
+
+```js
+const { items: rows } = await items.query('team-members')
+  .ascending('order')
+  .limit(50)
+  .find();
+// rows[0] === { _id, name, role, bio, order, _createdDate, ... }
+```
+
+**⚠️ CRITICAL: fields are on the item itself — `item.name`, NOT `item.data.name`.** The SDK returns each field as a top-level property of the item (the API was revised to match the Velo `wix-data` shape). `item.data.name` is the **REST** response shape and reads `undefined` in SDK code — the silent "every field is blank" bug. If you're reaching through `.data`, you're reading the REST doc view; re-open it with `?apiView=SDK`.
+
+**⚠️ CRITICAL: the id is `_id`, never `id`.** `item.id` is `undefined`; use `item._id` for keys, links, and reference lookups.
+
+**⚠️ `items.queryDataItems(...)` does NOT exist in the SDK.** The chainable entry point is `items.query("collectionId")` — `queryDataItems` is a REST/method name. Don't mix the two.
+
+### Filtering and single-item lookup
+
+Chain filter/sort/page methods on the query builder, then `.find()`:
+
+```js
+// by slug (detail page)
+const { items: [post] } = await items.query('articles').eq('slug', slug).limit(1).find();
+// compound filter + sort
+const { items: rows } = await items.query('products')
+  .eq('inStock', true).gt('price', 25).ascending('title').limit(50).find();
+```
+
+Builder methods: `.eq` / `.ne` / `.gt` / `.ge` / `.lt` / `.le` / `.contains` / `.startsWith` / `.hasSome` / `.ascending` / `.descending` / `.limit` / `.skip`. (No `$`-operator JSON body — that's the REST `/items/query` shape; in the SDK the operators are builder methods.)
+
+### Following references
+
+A `REFERENCE` / `MULTI_REFERENCE` field stores only ids by default. To inline the referenced items, add `.include("<fieldKey>")`:
+
+```js
+const { items: rows } = await items.query('projects').include('teamMembers').find();
+// rows[0].teamMembers is now an array of full team-member items, not ids
+```
+Doc: <https://dev.wix.com/docs/sdk/business-solutions/data/items/query-referenced.md?apiView=SDK> (for `items.queryReferenced`, the alternative when a multi-reference set is large). Without `.include(...)`, the field is just ids — resolve them yourself or use `include`.
+
+### Rendering images (IMAGE fields)
+
+An `IMAGE` field comes back as a **`wix:image://v1/<hash>/<file>#…` identifier, not a ready URL** — putting it straight into `<img src>` shows nothing (`ERR_UNKNOWN_URL_SCHEME`). Resolve it with the SDK media module, and reuse one helper on every render path:
+
+```js
+import { media } from '@wix/sdk';
+function imgSrc(v, w = 800, h = 600) {
+  if (!v) return '';
+  if (typeof v === 'string' && v.startsWith('wix:image://')) return media.getScaledToFillImageUrl(v, w, h, {});
+  return typeof v === 'string' ? v : (v?.url ?? '');   // an already-absolute https URL passes through
+}
+```
+
+**Never hand-build a `static.wixstatic.com/.../v1/fit/...` URL** — the format is easy to get wrong and the image then **403s**. Only `wix:image://` values need resolving; an already-absolute `https://` URL (e.g. an Unsplash placeholder seeded when imagery was off) goes straight into `<img src>`. Doc: <https://dev.wix.com/docs/sdk/core-modules/sdk/media>
+
+**⚠️ When imagery is OFF (the seed default), IMAGE fields are EMPTY — fall back, don't render a broken `<img>`.** The seed is text-only unless imagery is on, so a `photo`/`coverImage`/`headshot` field is often **absent or empty** on every item. Guard the render: only emit `<img>` when the field resolves to a real URL, otherwise show a graceful fallback (an initials avatar, a colored placeholder, or simply omit the image) — never an empty/broken `<img src="">`. A missing image is expected content state here, not an error.
+
+### Rendering rich text (RICH_TEXT / RICH_CONTENT fields)
+
+Wix CMS stores `RICH_TEXT` / `RICH_CONTENT` as **Ricos JSON** — a structured node tree (PARAGRAPH, HEADING, BULLETED_LIST…), not HTML and not a string.
+
+**⚠️ Do NOT `set:html={item.bio}` or `String(item.bio)` directly.** That dumps `[object Object]` or `{"nodes":...}` into the page. Render the Ricos node tree — either with a small SSR Ricos→HTML walker (covers PARAGRAPH, HEADING, lists, BLOCKQUOTE, BOLD/ITALIC/LINK; renders anything else defensively as a `<p>`), or with `@wix/ricos`'s React `RicosViewer` as a client island when the content carries the full feature set (galleries, embeds). For short bound fields a plain-text variant is fine; for a body field, render it **formatted**.
+
+### Writing from the frontend (only to a visitor-writable collection)
+
+Most collections are **read-only** from the visitor client — admin-owned content (catalog, team, articles) the site only displays. **Fire-and-forget visitor input** (contact, signup, lead capture) goes through **Wix Forms**, not CMS — don't `items.insert` for those.
+
+But when the site is built around **shared, visitor-editable data** — a guestbook, a community board, a collaborative list anyone can add to and edit — that collection is seeded **visitor-writable** (`insert`/`update`/`remove: ANYONE`, see `setup-cms.md`), and the client does full CRUD with the same `items` module:
+
+```js
+const created = await items.insert('community-board', { title, note, status: 'open' }); // → item with _id
+await items.update('community-board', { ...item, status: 'claimed' });                  // see footgun below
+await items.remove('community-board', item._id);
+```
+
+**⚠️ CRITICAL: `items.update()` REPLACES the whole item — it does NOT patch.** Per the docs: *"If the existing item had fields with values and those fields aren't included in the updated item, the values in those properties are lost."* So `update('c', { _id, status })` **wipes `title`, `note`, and every other field** — the classic "toggling status erases the row" bug. **Always pass the FULL item** on update (spread the record you already hold in state: `{ ...item, status }`). If you only have the id + one changed field and not the whole record, use **`items.bulkPatch('c', [id]).setField('status', v).run()`** instead — `bulkPatch` modifies only the named fields. Doc: <https://dev.wix.com/docs/sdk/business-solutions/data/items/update.md?apiView=SDK>
+
+**⚠️ A write needs the collection seeded with the matching open permission — else it 403s.** `items.insert`/`update`/`remove` only succeed if the collection was created with that verb at `ANYONE` (`setup-cms.md`). A write to an `ADMIN`-write collection 403s from the visitor client (there's no `auth.elevate` on this path to get around it). If writes 403, fix the seed permission, not the call.
+
+**⚠️ On the ANONYMOUS path the data is SHARED and unscoped — no per-user identity.** The visitor token has no per-user identity, so an `ANYONE`-writable collection is **global/shared across all visitors** (not per-user, not cross-device) and **any visitor can edit or delete any row**. That's the intended model for a collaborative board; surface it as such. **For per-user-private data, that's the member-scoped path** (`SITE_MEMBER_AUTHOR`, see the member-scoped note above): the same `items.insert`/`update`/`remove` calls, but run under a **logged-in member's token**, and each member touches only their own `_owner`-matched rows. On Astro you may route writes through a backend `src/pages/api/*` endpoint, but the permission facts are identical — no `_owner` set by hand, no elevate.
+
+---
+
+## Conclusion
+A correct Wix CMS frontend:
+- imports the **`items`** export of **`@wix/data`** (never `@wix/wix-data-items-sdk`), and `media` from `@wix/sdk` for images;
+- queries with **`items.query("collectionId")` + builder methods + `.find()`** (no namespace on the id; `queryDataItems` doesn't exist);
+- reads fields **on the item** (`item.name`) and the id as **`item._id`** — never `item.data.name`, never `item.id`;
+- does **no `auth.elevate`** — a public collection is read on the visitor token (an empty result there is a seed permissions bug, not a query bug), and a **member-scoped** collection (opt-in, `SITE_MEMBER_AUTHOR`/`SITE_MEMBER`) is read on the **logged-in member's token** with the same no-elevate rule (an anonymous read returning empty is the gate, not a bug);
+- resolves `wix:image://` via `media.getScaledToFillImageUrl` and renders Ricos rich text formatted (never raw `set:html`/`String`);
+- treats CMS as **read-only by default** (fire-and-forget input → Forms); writes to a **visitor-writable** collection use `items.insert`/`update`/`remove` — always passing the **full item** on `update` (it replaces, not patches), expecting the data to be **shared/unscoped**, and relying on the collection's seeded `ANYONE` write permission (no `auth.elevate`). For **per-user-private** data (opt-in, members login in the run) the same calls run under the **member token** against a `SITE_MEMBER_AUTHOR` collection — each member sees/edits only their own `_owner`-matched rows, `_owner` is never set by hand, and the surface is gated behind login.

package/skills/wix-headless/references/inline-recipes/how-to-code-events.md

@@ -0,0 +1,203 @@
+---
+name: "How to Code Events"
+description: The frontend read/registration contract for a Wix Events (Events V3) site — which SDK modules to import, how to list upcoming events, read one by slug, list ticket tiers, and run the two registration paths (ticketed = reserve → redirect to Wix's hosted checkout; free = createRsvp). Specifies the *how* (modules + exact calls + the failure modes the docs omit); which events to render and how the page looks come from the request.
+---
+**RECIPE**: How to Code a Wix Events Frontend (Events V3 + hosted-checkout redirect)
+
+A concise contract for writing the **frontend code** of an events site: a listing, per-event detail pages, ticketed checkout (reserve the tickets, then redirect to Wix's hosted checkout), and free RSVP registration. **This recipe is the *how* (which modules, which calls, which fields), not the *what*** — which events to show, how the page looks, and the framework are decided by the request you're fulfilling.
+
+> **This recipe is for CODING the registration flow, not for seeding it.** It assumes an Events V3 backend already exists (published events with future dates, ticket definitions for ticketed events). It says nothing about creating events — only how to read and register for them from frontend code.
+
+> **The whole flow is a site-visitor operation — no server route, no elevation.** Reserving tickets, minting the checkout redirect, and creating an RSVP all run under the **anonymous visitor** identity (the Events Checkout scope is granted to visitors), the same client-side model as the bookings pack. If you reach for a `src/pages/api/*` route or `auth.elevate()` to make a reservation work, **stop** — that masks the real gate (the payment-method precondition below) and the redirect call actively **fails** when elevated.
+
+> **⚠️ Reading rule — always append `.md?apiView=SDK` to every doc link below.** The Wix docs render two views of the same page. The **bare / REST view shows `id`**; the **`?apiView=SDK` view shows `_id`** — and the SDK is what your frontend calls. Reading the REST view by mistake is the most common source of the `event.id`-is-`undefined` bug. If a field name surprises you, you're probably reading the REST view — re-open it with `?apiView=SDK`. Discover any shape not pinned here with `SearchWixSDKDocumentation`, not by guessing a URL.
+
+---
+
+## The modules and the client (read this first)
+
+No app-id constant is needed in frontend code — the only id the client needs is the public **`clientId`** (non-Astro only; see below). Ticketed checkout hands off to Wix's hosted checkout via the Redirects API, so there is **no on-site cart and no `catalogReference`**.
+
+| Need | Package | Module |
+|---|---|---|
+| List events / get one by slug | `@wix/events` | `wixEventsV2` (`queryEvents`, `getEventBySlug`) |
+| Ticket tiers (ticketed) | `@wix/events` | `orders` (`queryAvailableTickets`) — the visitor-public storefront read |
+| Reserve tickets (ticketed) | `@wix/events` | `ticketReservations` (`createTicketReservation`) |
+| Create an RSVP (free) | `@wix/events` | **`rsvpV2`** (`createRsvp`) — NOT the legacy `rsvp` module (v1 → 400) |
+| Redirect to hosted checkout (ticketed) | `@wix/redirects` | `redirects` (`createRedirectSession`) |
+
+- **The events query/get namespace is `wixEventsV2`** (despite the name, this is the current Events V3 module from `@wix/events`). Import `wixEventsV2`, `orders`, `ticketReservations`, `rsvpV2` from `@wix/events`.
+- **⚠️ CRITICAL: read ticket tiers with `orders.queryAvailableTickets`, NOT `ticketDefinitions(V2).queryTicketDefinitions`.** The `ticketDefinitions*` namespaces are the **management** API (`TicketDefinitionManagement`, a manage scope) — the **anonymous visitor is `403`-denied** on every one of them (`queryTicketDefinitions`, `queryTicketDefinitionsV2`, `listTicketDefinitions`), so a storefront that reads tiers that way gets an empty picker. **Do NOT work around it with `auth.elevate()`** — that's the wrong axis (an app/admin permission elevation), it's SSR-only (useless on a non-Astro SPA), and it's unnecessary: the **visitor-public storefront read** is `orders.queryAvailableTickets({ filter: { eventId }, limit })` → `{ definitions }` (visitor-public — works for the anonymous visitor on Astro *and* SPA). The event read (`queryEvents`/`getEventBySlug`) is visitor-public too — **no elevation anywhere in this recipe.**
+- **Never use the deprecated `orders.createReservation`** — reserve with `ticketReservations.createTicketReservation`.
+- **Never complete a paid purchase with `orders.checkout` (inline payment)** — that path leaves orders unpaid without a payment integration. The supported headless completion is the **hosted redirect** (below).
+
+**Auth / client — framework split:**
+- **Astro (Wix-managed):** authentication is ambient. Call the modules directly — from server components for the SSR reads (listing/detail) and from browser islands for the visitor-session writes (reserve / redirect / rsvp) via the `@wix/astro` visitor client — **no `createClient`, no `OAuthStrategy`, no `clientId`.** Nothing here needs elevation (every read and write runs as the visitor — "no elevation anywhere"); a public-env `clientId` read in `.astro` SSR is `undefined` at server render → 500, so don't build an `OAuthStrategy` client there.
+- **Non-Astro (Vite/React/Vue/static):** build one manual visitor client and reuse it:
+  ```js
+  import { createClient, OAuthStrategy } from '@wix/sdk';
+  import { wixEventsV2, orders, ticketReservations, rsvpV2 } from '@wix/events';
+  import { redirects } from '@wix/redirects';
+
+  const client = createClient({
+    modules: { wixEventsV2, orders, ticketReservations, rsvpV2, redirects },
+    auth: OAuthStrategy({ clientId: /* the project's PUBLIC OAuth client id */ }),
+  });
+  ```
+  The `clientId` is public, not a secret. A mis-wired public env var inlines as `undefined` and 400s every call.
+
+---
+
+## The shapes you read (field cheat-sheet)
+
+```jsonc
+// wixEventsV2.getEventBySlug(slug, { fields: [...] })  →  { event }
+// wixEventsV2.queryEvents(...)                          →  result.events[]
+event = {
+  _id,                                                  // routes · reserve/rsvp bind to it   (NOT .id → undefined)
+  slug,                                                 // the URL slug — checkout redirect needs it
+  title, shortDescription,
+  mainImage,                                            // image ref (render via the media helper)
+  dateAndTimeSettings: { formatted: { dateAndTime } },  // human-formatted date string
+  location: { name, type },                             // "VENUE" | "ONLINE" | TBD
+  registration: { initialType },                        // "TICKETING" | "RSVP" — BRANCH on this
+  // categories?: { categories: [{ _id, name }] }        // runtime shape when fields:['CATEGORIES'] is requested — but NOT on the typed Event (SDK gap): read via a cast, see below
+}
+
+// orders.queryAvailableTickets({ filter: { eventId }, limit })  →  { definitions }   (VISITOR-public)
+tier = {
+  _id,                                                  // reserve by this   (NOT .id)
+  name, description,
+  price: { value, currency },                           // value is a STRING (e.g. "45.00"); also at pricing.fixedPrice.value
+  free,                                                 // boolean
+  saleStatus,                                           // "SALE_STARTED" | "SALE_ENDED" | "SALE_SCHEDULED" — gate the picker on this
+  limitPerCheckout,                                     // max qty per order for this tier
+}
+```
+
+**⚠️ CRITICAL: entity ids are `_id`, NOT `id`.** `event._id`, `tier._id`. `event.id` is `undefined` in SDK code — a surprise `id`/`undefined` means you're reading the REST doc view; re-open it with `?apiView=SDK`.
+
+**Filtering by event format/track (talk/workshop/social)** — if the site groups events by a format, the seed models it as **Event Categories** (`setup-events.md` STEP 4). Read the assigned category off the event and filter **client-side** — two gotchas:
+- **Request `CATEGORIES` as the 2nd positional arg**, not inside the flat query: `queryEvents({ filter, sort, paging }, { fields: ['CATEGORIES'] })` and `getEventBySlug(slug, { fields: ['CATEGORIES'] })`. (`fields` lives on the options arg, not on `EventQuery`.)
+- **`categories` is NOT on the typed `Event` (an SDK type gap** — the `CATEGORIES` enum and `EventCategory`/`EventCategories` types ship, but `Event` omits the property, so a direct `event.categories` read fails `tsc`/`astro check`). **Read it through a cast:** `const cats = (event as any).categories?.categories ?? []` — each entry is `{ _id, name }`; map `cats[].name` → your format enum.
+- **Do NOT call the management categories endpoints** (`/events/v1/categories*`, `listEventsByCategory`) from the frontend — they're admin-scope; the visitor read is just the cast `CATEGORIES` field on the event.
+
+---
+
+## The registration features (build the ones the site needs)
+
+Each section is a **self-contained feature** — implement only what the site uses. **Branch on the event's `registration.initialType`:** `TICKETING` → ticket picker (tiers + quantities → reserve → redirect); `RSVP` → the built-in name+email form → `createRsvp`. Never render an RSVP event with a ticket picker (or a ticketed event with an RSVP form).
+
+### Listing events (upcoming only, and the `_id` rule)
+
+```js
+const { events } = await wixEventsV2.queryEvents({
+  filter: { status: { $in: ['UPCOMING', 'STARTED'] } },     // exclude DRAFT / ENDED / CANCELED
+  sort: [{ fieldName: 'dateAndTimeSettings.startDate', order: 'ASC' }],
+  paging: { limit: 100 },                                   // ⚠️ MUST be > 0
+});                                                          // → result.events[]
+```
+Doc: <https://dev.wix.com/docs/api-reference/business-solutions/events/event-management/events-v3/query-events.md?apiView=SDK>
+
+- **⚠️ CRITICAL: `queryEvents` takes the query object FLAT as its first arg — `queryEvents({ filter, sort, paging })`, NOT `queryEvents({ query: { … } })`.** The signature is `queryEvents(query, options)` where `query` *is* `{ filter, sort, paging }`. Wrapping it in an extra `{ query: … }` (the REST body shape, and the `.queryServices({ query })` builder shape from other verticals) is **not** rejected — the SDK silently ignores the unrecognized `query` key, so `paging` never applies, `limit` defaults to **0**, and you get **`events: []` with no error**. This is the #1 "my listing is empty even though events are published" trap. (The flat form returns the events; the nested form returns zero.)
+- **⚠️ `paging.limit` MUST be > 0.** Even with the flat shape, `queryEvents` defaults `paging.limit` to **`0`, which returns zero events**. Always set a positive limit.
+- The result array is **`result.events`** (not `.items`).
+- **Filter to upcoming/published and never list or link a past event** — a past event isn't purchasable/registerable (the seed uses future dates). Filter by `status` (above) or by a future `startDate`.
+- Read `event._id` / `event.slug` / `event.title`. A **single-event** site collapses the listing — lead the home page straight into the one event's detail. **Still drive that homepage from the listing query** (take the first/only result), never a hardcoded lone slug — so a second event the owner adds later automatically brings the listing back instead of staying invisible.
+
+### One event by slug + its ticket tiers
+
+```js
+const { event } = await wixEventsV2.getEventBySlug(slug, {
+  fields: ['DETAILS', 'TEXTS', 'REGISTRATION', 'URLS'],   // REGISTRATION carries initialType — you branch on it
+});
+
+// ticketed only — list the tiers (VISITOR-public; NOT ticketDefinitions* — those 403 the visitor):
+const { definitions: tiers } = await orders.queryAvailableTickets({
+  filter: { eventId: event._id }, limit: 20,
+});
+```
+Docs: <https://dev.wix.com/docs/api-reference/business-solutions/events/event-management/events-v3/get-event-by-slug.md?apiView=SDK> · <https://dev.wix.com/docs/api-reference/business-solutions/events/registration/ticketing/orders/query-available-tickets.md?apiView=SDK>
+
+- **Request `REGISTRATION` in `fields`** so `event.registration.initialType` is populated — that's the value you branch on.
+- Per tier read `tier._id`, `tier.name`, `tier.price.value` (a **string**) + `tier.price.currency`, `tier.free`, and `tier.saleStatus` (gate the picker on `SALE_STARTED`).
+- **⚠️ The confirmation page (post-checkout) reads the event by ID, and the return envelope DIFFERS from `getEventBySlug`.** After the hosted checkout redirects back to your `postFlowUrl` (carrying `?eventId=…`), look the event up with **`wixEventsV2.getEvent(eventId, { fields: ['TEXTS', 'URLS'] })`** — this returns the **`Event` object DIRECTLY (unwrapped)**: read `event.title` / `event.slug`, **not** `{ event }`. This is the one read that isn't wrapped (`getEventBySlug` *is* `{ event }`); assume the wrapper and the page crashes. Use this exact call — don't inspect the installed `.d.ts` to rediscover it.
+
+### Ticketed checkout — reserve → redirect (the exact sequence)
+
+Two steps, both as the visitor. **Use as-is — the payload shapes are easy to get subtly wrong.**
+
+```js
+// 1 · Reserve the selected tiers (PENDING; auto-expires after the event's reservation window).
+const reservation = await ticketReservations.createTicketReservation({
+  tickets: selections           // one entry per chosen tier, quantity ≥ 1
+    .filter((s) => s.quantity > 0)
+    .map((s) => ({ ticketDefinitionId: s.ticketDefinitionId, quantity: s.quantity })),
+});
+const reservationId = reservation._id;          // ⚠️ _id, not id
+
+// 2 · Mint the hosted-checkout redirect and hand off.
+const origin = window.location.origin;          // ⚠️ the published https:// host — see below
+const { redirectSession } = await redirects.createRedirectSession({
+  eventsCheckout: { reservationId, eventSlug: event.slug },
+  callbacks: {
+    thankYouPageUrl: `${origin}/event-confirmation`,   // Wix appends ?orderNumber=&eventId=
+    postFlowUrl:     `${origin}/events/${event.slug}`,  // back to the event on abandon
+  },
+});
+window.location.href = redirectSession.fullUrl;  // Wix collects guest details + payment, emails the PDF/QR ticket
+```
+Docs: <https://dev.wix.com/docs/api-reference/business-solutions/events/registration/ticketing/ticket-reservations/create-ticket-reservation.md?apiView=SDK> · <https://dev.wix.com/docs/api-reference/business-management/headless/redirects/create-redirect-session.md?apiView=SDK>
+
+- **⚠️ CRITICAL: don't hand-build the checkout URL.** `{base}/event-details/{slug}/ticket-form?reservationId=…` **404s on a headless site** (there's no Wix-hosted event page). The Redirects API mints a checkout URL on Wix's own domain — `eventsCheckout: { reservationId, eventSlug }` → `redirectSession.fullUrl` is the **only** path that works headless.
+- **⚠️ CRITICAL: the redirect call must run in the VISITOR (headless-OAuth) context — never elevated/admin.** `createRedirectSession` embeds the headless app's `clientId`; an admin/elevated token fails with *"client Id does not correspond to a headless oauth app."* On Astro the **browser island** calls it (ambient visitor client), never a server endpoint; on non-Astro it's the `OAuthStrategy` client. Don't elevate it.
+- **⚠️ CRITICAL: `origin` MUST be the published `https://` host — from `window.location.origin`, never a server-derived `new URL(request.url).origin`.** The Headless redirect allowlist registers the `https://` host and treats `http://<same host>` as a different, unlisted origin; an `http://` `postFlowUrl` makes the return ("Continue Browsing") **403** with *"… isn't listed as an allowed redirect domain."* Pass `window.location.origin` from the client. Doc: <https://dev.wix.com/docs/go-headless/getting-started/setup/manage-urls/add-allowed-redirect-domains>.
+- **⚠️ Handle the paid-ticket precondition softly.** Reserving a **paid** ticket as a visitor fails with **`403 "No payment method configured"`** until the site has a premium plan **and** a configured payment method (a dashboard step the seed already flagged). This is the **real gate** — not a permissions bug, and **not** something elevation should paper over (elevating just creates an unpayable `INITIATED` order). Catch the error; if its message matches `/payment method|not configured|premium/i`, show *"Ticket sales aren't switched on yet — the organizer needs to connect a payment method."* Free / RSVP events are unaffected.
+- Wrap both calls in try/catch (sold out, sale ended, no payment method) and surface a friendly message; don't crash the page.
+
+### Free RSVP — the built-in form
+
+```js
+await rsvpV2.createRsvp({
+  eventId: event._id,
+  firstName, lastName, email,    // the built-in form fields — collect EXACTLY these
+  status: 'YES',                 // 'NO' only for YES_AND_NO events
+});
+// then show an inline confirmation — no reservation, no redirect, no payment
+```
+Doc: <https://dev.wix.com/docs/api-reference/business-solutions/events/registration/rsvp-v2/create-rsvp.md?apiView=SDK>
+
+- **⚠️ CRITICAL: use the `rsvpV2` module, NOT `rsvp`.** The legacy `rsvp.createRsvp` posts to `/events/v1/rsvp` and **400s** with `"rsvp.firstName/lastName/email must not be empty"` even when you pass those fields — that v1 surface expects a different form-response body. Import **`rsvpV2`** from `@wix/events` and call `rsvpV2.createRsvp(rsvp)` with the rsvp object **directly as the first arg** (not wrapped in `{ rsvp: … }`, which is the elevated/`@wix/essentials` style). The flat `{ eventId, firstName, lastName, email, status }` object is correct for `rsvpV2` and **works for the anonymous visitor**.
+- **The RSVP registration form is built-in** (firstName, lastName, email) — add exactly those fields; **don't fetch a form schema** or hand-build extra fields.
+- Wrap in try/catch — a duplicate email or closed registration rejects; surface a friendly message.
+
+### Rendering & mounting
+
+- **Date**: `event.dateAndTimeSettings.formatted.dateAndTime` (already human-formatted) — request the `DETAILS` field to populate it.
+- **Image**: `event.mainImage` is a Wix media ref — render it via the media helper (`@wix/sdk` `media.getScaledToFillImageUrl` / `getImageUrl`); **never** hand-build a `static.wixstatic.com` URL (→ 403).
+- **Price**: `tier.price.value` (string) + `tier.price.currency` (the event's stored currency — format from it, don't assume USD).
+- **Mount the ticket picker / RSVP form in a `client:only="react"` island** (Astro) — they run visitor-session SDK calls and redirect. **SSR only the read pages** (listing/detail) for SEO.
+
+### SEO on item pages (Astro, Wix-managed)
+
+An **event detail** page is a Wix **item page**: its `<title>`/description/OG/canonical come from what the owner sets in the dashboard. On the Astro (Wix-managed) frontend, wire it per the canonical guide — **[Add SEO Support to Item Pages](https://dev.wix.com/docs/go-headless/wix-managed-headless/seo/add-seo-support-to-item-pages.md)** — which covers the three steps: export `wixMetadata` (registers the route → sitemap + dashboard SEO editor), call `loadSEOTagsServiceConfig(...)`, and render `<SEO.Tags>` (from `@wix/seo`; deps + `@wix/essentials ≥ 1.0.10` are in the guide's "Before you begin").
+
+For an event page use:
+- **`wixMetadata`** from `WIX_APPS.events.eventPageMetadata` — referenced **directly** in the export (module scope). Route param `slug` → `identifiers.slug`.
+- **`itemType`**: `seoTags.ItemType.EVENTS_PAGE`.
+
+Fold `loadSEOTagsServiceConfig` into the same `Promise.all` as the ambient `getEventBySlug` read, with `.catch(() => null)` (it needs only the slug — still a visitor-safe ambient call), so a SEO hiccup falls back to the layout's default title. Optional: render an `Event` schema.org JSON-LD `<script>` from the fetched event (see the guide's structured-data step).
+
+### Out of scope
+Assigned seating / seat maps (display + reserve flat ticket definitions only); coupons & gift cards at checkout (Wix's hosted checkout handles those — don't build a discount UI); on-site order management / cancel / refund (handled by the hosted flow + the buyer's email); manual `orders.checkout` inline payment (use the hosted redirect).
+
+---
+
+## Conclusion
+A correct Events V3 registration frontend:
+- imports **`wixEventsV2` / `orders` / `ticketReservations` / `rsvpV2`** from `@wix/events` plus **`redirects`** from `@wix/redirects` — and never inline `orders.checkout` or the legacy `rsvp` (v1 → 400) module;
+- uses **`event._id` / `tier._id`** (never `.id`) and reads the flat fields (`event.slug`, `registration.initialType`, `tier.price.value`);
+- lists with **`queryEvents({ filter, sort, paging })` FLAT** (never `{ query: { … } }` — that silently returns `events: []`) and **`paging.limit > 0`**, filtered to **upcoming/published** events, never past ones;
+- reads ticket tiers with the **visitor-public `orders.queryAvailableTickets({ filter: { eventId }, limit })`** (→ `definitions`) — **never** the management `ticketDefinitions*` query (visitor 403s) and **never** `auth.elevate()` (wrong axis, SSR-only); no elevation anywhere;
+- **branches on `registration.initialType`**: `TICKETING` → reserve (`createTicketReservation` → `reservation._id`) → **`createRedirectSession({ eventsCheckout })`** → `redirectSession.fullUrl`; `RSVP` → **`rsvpV2.createRsvp`** with the built-in firstName/lastName/email and an inline confirmation;
+- runs the reserve/redirect/rsvp **client-side as the visitor** (no server route, no elevation), uses `window.location.origin` (the `https://` host) for the callbacks, and **fails soft** on the `403 "No payment method configured"` paid-ticket precondition.