@wix/agent-skills 1.35.1 → 1.36.1

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

@@ -1,213 +0,0 @@
----
-name: "How to Code Restaurant Reservations"
-description: The frontend contract for a Wix Table Reservations site — which SDK modules to import, how to read the reservation location, get available time slots, and make a reservation via the hold→reserve flow (or single create). Specifies the *how* (modules + exact calls + failure modes); the restaurant/party details come from the visitor.
----
-**RECIPE**: How to Code a Wix Table-Reservations Frontend (Table Reservations)
-
-A contract for the **frontend code** that lets a visitor **book a table**: reading the reservation location, fetching available time slots for a date + party size, and creating a reservation. **This recipe is the *how* (which modules, which calls, which fields), not the *what*** — the restaurant, the party size, and the page design come from the request / the visitor's input.
-
-> **This recipe is for CODING reservations, not seeding them.** It assumes the backend already exists — the Table Reservations app installed and a reservation location configured with **online reservations enabled** (see `setup-restaurant-reservations.md`). It says nothing about creating or configuring the location — only how visitors read availability and book from frontend code.
-
-> **⚠️ Reading rule — always append `.md?apiView=SDK` to every doc link below.** The bare / REST view shows `id`; the `?apiView=SDK` view shows `_id` — and the SDK is what your frontend calls. Reading the REST view is the most common source of the `entity.id`-is-`undefined` bug. Fetch the `.md?apiView=SDK` form directly.
-
-> **⚠️ ONLINE RESERVATIONS MUST BE ENABLED (premium) for this flow to work.** The visitor flow reads/creates against a location whose `onlineReservationsEnabled` is `true` — and (per `setup-restaurant-reservations.md`) that toggle is **premium-only** (`428 PREMIUM_ONLY` on a free site). On a non-premium site the location exists and you can *read* it, but time-slot availability / booking won't function. If bookings fail on a site you know is configured, check the site is premium and the toggle is on — it's a provisioning precondition, not a code bug.
-
----
-
-## The modules and the client (read this first)
-
-**One package: `@wix/table-reservations`** — a **distinct** package from `@wix/restaurants` (menus) and from the Orders app. It exposes the namespaces you use:
-
-| Need | Package | Module (namespace) |
-|---|---|---|
-| The reservation location (id, party-size bounds) | `@wix/table-reservations` | `reservationLocations` |
-| Available time slots for a date + party size | `@wix/table-reservations` | `timeSlots` |
-| Create / hold / reserve a reservation | `@wix/table-reservations` | `reservations` |
-| **Experiences** — special dining occasions guests reserve (only when experiences are in the run) | `@wix/table-reservations` | `experiences` |
-
-> **Experiences** ride on this same package and booking mechanism — see the **Booking an experience** feature below. Skip that section entirely if the run has no experiences.
-
-**No cart, no `@wix/ecom`, no `@wix/redirects`.** A basic table reservation is a **hold**, not a purchase — there's no checkout in this flow. (Deposit/prepayment reservations exist — status `PAYMENT_INFORMATION_PENDING` — but they're out of scope for the standard book-a-table flow.)
-
-**Auth / client — framework split:**
-- **Astro (Wix-managed):** authentication is ambient. Call `reservationLocations` / `timeSlots` / `reservations` directly from server components and backend routes (`src/pages/api/*.ts`) — **no `createClient`, no `OAuthStrategy`, no `clientId`.**
-  ```js
-  import { reservationLocations, timeSlots, reservations } from '@wix/table-reservations';
-  const { reservationLocations: locs = [] } = await reservationLocations.listReservationLocations();
-  ```
-- **Non-Astro (Vite/React/Vue/static):** build one manual visitor client and reuse it:
-  ```js
-  import { createClient, OAuthStrategy } from '@wix/sdk';
-  import { reservationLocations, timeSlots, reservations } from '@wix/table-reservations';
-
-  const client = createClient({
-    modules: { reservationLocations, timeSlots, reservations },
-    auth: OAuthStrategy({ clientId: /* the project's PUBLIC OAuth client id */ }),
-  });
-  // then: await client.timeSlots.getTimeSlots(locationId, new Date(date), partySize)
-  ```
-  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)
-
-SDK read shapes (`?apiView=SDK`), so entity ids are **`_id`**.
-
-```jsonc
-// reservationLocations.listReservationLocations()  →  { reservationLocations: [...] }   (no arguments)
-reservationLocation = {
-  _id,                         // → the reservationLocationId every call below needs   (NOT .id)
-  default,                     // the auto-provisioned location has default: true
-  configuration: { onlineReservations: {
-    partySize: { min, max },   // bound the party-size input to this range
-    onlineReservationsEnabled, // must be true for the flow to work (premium)
-    approval: { mode },        // "AUTOMATIC" → reserve confirms immediately; manual → status REQUESTED
-  } },
-}
-
-// timeSlots.getTimeSlots(reservationLocationId, date, partySize, options?)  →  { timeSlots: [...] }
-//   NOTE: the SDK types `date` as a Date (NOT the ISO string the REST doc shows) — pass new Date(...)
-timeSlot = {
-  startDate,                   // a Date — pass THIS into createHeldReservation
-  duration,                    // minutes
-  status,                      // "AVAILABLE" | "UNAVAILABLE" | "NON_WORKING_HOURS" — book only AVAILABLE
-  manualApproval,              // whether this slot needs staff approval
-}
-
-// reservations.createHeldReservation({ reservationLocationId, startDate, partySize })  →  { reservation: {...} }
-// reservations.reserveReservation(reservationId, reservee, revision)  →  { reservation: {...} }
-reservation = {
-  _id, revision,               // keep BOTH from the held reservation — reserve needs the revision
-  status,                      // "HELD" after create → "RESERVED" (auto) or "REQUESTED" (manual approval) after reserve
-}
-```
-
----
-
-## The features (build the ones the site needs)
-
-Each subsection is a **self-contained feature**. The only ordering is the booking chain itself (location → slots → hold → reserve).
-
-### Reading the reservation location (and the `_id` rule)
-
-Get the location so you have its **`_id`** and the party-size bounds for your form. `listReservationLocations()` takes **no arguments**.
-
-```js
-const { reservationLocations: locs = [] } = await reservationLocations.listReservationLocations();
-const loc = locs.find((l) => l.default) ?? locs[0];
-const reservationLocationId = loc._id;
-const { min, max } = loc.configuration?.onlineReservations?.partySize ?? { min: 1, max: 20 };
-```
-Doc: <https://dev.wix.com/docs/api-reference/business-solutions/restaurants/reservations/reservation-locations/list-reservation-locations.md?apiView=SDK>
-
-**⚠️ CRITICAL: the entity id is `_id`, NOT `id`.** `location.id` / `reservation.id` are `undefined` in SDK code — use `_id`. (A surprising `id` field means you're on the REST doc view — re-open with `?apiView=SDK`.)
-
-**⚠️ Default the array (`= []`).** `listReservationLocations()` types the returned array as optional, so destructuring `{ reservationLocations: locs }` and calling `locs.find(...)` directly errors under `strict` / `astro check` (`'locs' is possibly 'undefined'`). Default it, exactly as with the restaurants `list*` methods.
-
-### Getting available time slots
-
-Call `getTimeSlots` with **positional** args: the location id, a **`Date` object** (`new Date(selectedDate)` — NOT the ISO string the doc shows; see the CRITICAL note below), the party size, and optional `{ slotsBefore, slotsAfter, duration }`. Then keep the `AVAILABLE` slots.
-
-```js
-const { timeSlots: slots = [] } = await timeSlots.getTimeSlots(
-  reservationLocationId,
-  new Date(selectedDate),                 // a Date — the SDK types this param as Date (see callout)
-  partySize,
-  { slotsBefore: 4, slotsAfter: 4 },
-);
-const available = slots.filter((s) => s.status === 'AVAILABLE');
-```
-Doc: <https://dev.wix.com/docs/api-reference/business-solutions/restaurants/reservations/time-slots/get-time-slots.md?apiView=SDK>
-
-**⚠️ CRITICAL: `getTimeSlots` takes POSITIONAL args, not a single options object.** The signature is `getTimeSlots(reservationLocationId, date, partySize, options?)` — passing one object (`getTimeSlots({ reservationLocationId, date, partySize })`) does not type-check. Only `slotsBefore`/`slotsAfter`/`duration` go in the 4th `options` arg.
-
-**⚠️ CRITICAL: the `date` param is a `Date`, NOT the ISO-8601 string the doc shows (doc/SDK drift).** The REST/SDK doc describes `date` as an ISO-8601 string, but the shipped `@wix/table-reservations` type is **`Date`** — passing `new Date(...).toISOString()` fails to compile (`TS2345: 'string' is not assignable to 'Date'`). Pass a **`Date` object** (`new Date(selectedDate)`). Both the `date` arg you send and each `slot.startDate` you read back are `Date`s — so pass the chosen slot's `startDate` straight into `createHeldReservation`, no conversion.
-
-**⚠️ Book only `status === 'AVAILABLE'`.** `UNAVAILABLE` (can't seat that party then) and `NON_WORKING_HOURS` (closed) are also returned — filter them out before presenting slots, or the hold will fail.
-
-### Making a reservation (hold → reserve)
-
-The two-step flow from the sample: **hold** the slot (10-minute temporary reservation) while the visitor enters details, then **reserve** it with their name + phone.
-
-```js
-// 1 · hold the slot — startDate is the Date from the chosen AVAILABLE time slot
-const held = await reservations.createHeldReservation({
-  reservationLocationId,
-  startDate: chosenSlot.startDate,
-  partySize,
-});
-// ⚠️ `held.reservation` is OPTIONAL and its `_id`/`revision` are `string | null` in the SDK type —
-// narrow before use or the strict/`astro check` build fails (TS18048 / TS2345).
-if (!held.reservation?._id || !held.reservation.revision) throw new Error('hold failed');
-const reservationId = held.reservation._id;
-const revision = held.reservation.revision;   // reserve needs this
-
-// 2 · reserve it — reservee needs firstName + phone at minimum
-const done = await reservations.reserveReservation(
-  reservationId,
-  { firstName, lastName, email, phone },
-  revision,
-);
-// done.reservation.status === 'RESERVED'  (auto-approval)  |  'REQUESTED'  (manual approval on)
-```
-Docs: <https://dev.wix.com/docs/api-reference/business-solutions/restaurants/reservations/reservations/create-held-reservation.md?apiView=SDK> · <https://dev.wix.com/docs/api-reference/business-solutions/restaurants/reservations/reservations/reserve-reservation.md?apiView=SDK>
-
-**⚠️ CRITICAL: `reserveReservation(reservationId, reservee, revision)` takes THREE positional args** — the reservation id, the `reservee` object, and the **`revision`** from the held reservation. Omitting the revision (or wrapping the three in one object) does not type-check. Keep `held.reservation.revision` from step 1.
-
-**⚠️ CRITICAL: `reservee.firstName` and `reservee.phone` are required.** A reservation from any `source` other than `WALK_IN` (i.e. every online booking) requires at least `firstName` and `phone` — omitting them returns an error. Collect them in the details form before calling reserve.
-
-**⚠️ A `HELD` reservation expires in 10 MINUTES.** If the visitor takes longer than 10 min to confirm, `reserveReservation` returns an error — start a fresh hold. And **do not** call `updateReservation` to move a reservation off `HELD` (it errors); the only way forward from `HELD` is `reserveReservation`.
-
-**Result status:** with the seeded default (`approval.mode: "AUTOMATIC"`, manual approval off) the reservation becomes **`RESERVED`** immediately — confirm to the visitor. If the location requires manual approval it becomes **`REQUESTED`** (staff must approve) — tell the visitor it's pending.
-
-**Single-shot alternative:** if you collect all details up front (no "hold while they type" step), call `reservations.createReservation({ details: { reservationLocationId, startDate, partySize }, reservee })` instead — same `firstName`/`phone` requirement; it returns `RESERVED`/`REQUESTED` directly, skipping the `HELD` phase. **⚠️ The location/time/party go under a nested `details` object (NOT top-level), and this method returns the `Reservation` DIRECTLY — not wrapped in `{ reservation }`** (unlike `createHeldReservation`/`reserveReservation`). Top-level fields or reading `.reservation` off the result fails to type-check.
-Doc: <https://dev.wix.com/docs/api-reference/business-solutions/restaurants/reservations/reservations/create-reservation.md?apiView=SDK>
-
-### Booking an experience (only when experiences are in the run)
-
-An **experience** is a reservation that *is* a curated dining occasion (chef's table, tasting menu). It uses the **same** booking mechanism as a table, with two differences: you **list experiences** to show and choose from, and you offer bookable times **projected from the experience's own schedule** (there is *no* experience-scoped slot API — see Gotcha C) rather than from `getScheduledTimeSlots`, then stamp the chosen `experienceId` onto the reservation. Read the shapes from the docs (`.md?apiView=SDK`); the earned drift gotchas below are what the docs won't tell you.
-
-Flow (mirrors the docs' sample flow — <https://dev.wix.com/docs/api-reference/business-solutions/restaurants/reservations/experiences/sample-flows.md>):
-
-```js
-import { experiences, reservations } from '@wix/table-reservations';
-
-// 1 · list experiences to display (name, price, schedule) — see gotcha A
-const { items: exps = [] } = await experiences.queryExperiences().find();
-const exp = exps.find((e) => e._id === chosenId);
-
-// 2 · offer bookable times from the EXPERIENCE'S OWN schedule — do NOT call
-//     getScheduledTimeSlots for an experience (it can't scope to one — Gotcha C).
-//     queryExperiences() already returned the schedule; project the next occurrences yourself.
-const sched = exp.configuration?.onlineReservations?.businessSchedule; // { durationInMinutes, entries[] }
-// entries[].weeklyOptions.startDaysAndTimes[{ day, time }]  →  next N dates matching each weekday+time
-// (ONE_TIME entries carry oneTimeOptions.{startDate,startTime}). Build the option list from these.
-
-// 3 · book it — experienceId rides in details (see gotcha B); firstName + phone required
-const done = await reservations.createReservation({
-  details: { reservationLocationId, experienceId, startDate: chosenOccurrence, partySize },
-  reservee: { firstName, lastName, email, phone },
-});
-```
-Docs: <https://dev.wix.com/docs/api-reference/business-solutions/restaurants/reservations/experiences/query-experiences.md?apiView=SDK> · <https://dev.wix.com/docs/api-reference/business-solutions/restaurants/reservations/reservations/create-reservation.md?apiView=SDK>
-
-**⚠️ Gotcha A — `queryExperiences()` is a QUERY BUILDER, not an object-arg method.** Call `experiences.queryExperiences().find()` (chain `.eq()`/`.limit()` etc. before `.find()` if needed) and read the array from the **result's `.items`**. Passing a query object — `queryExperiences({})` — does not type-check and returns no data; `await`-ing the un-`.find()`ed builder gives you the builder, not the results.
-
-**⚠️ Gotcha B — `details.experienceId` is a valid REST field but the SDK `Details` type may OMIT it (version drift).** The REST API accepts `experienceId` inside `details` (the Experiences intro and the reservation's own `meta` confirm `details.experienceId`), but an installed `@wix/table-reservations` older than the Experiences feature ships a `Details` type without it — so TypeScript rejects the property. Build the reservation object and **pass it through an `any` cast** (or `// @ts-expect-error`) so `experienceId` reaches the request body; it works at runtime. Don't drop the field to satisfy the compiler — a reservation without it books a plain table, not the experience.
-
-**⚠️ Gotcha C — there is NO experience-scoped slot fetch; project times from the experience's own `businessSchedule` instead.** The upstream `get-scheduled-time-slots` doc prose says "pass the GUID of that experience to this method," but **no such parameter exists at any layer**: the SDK (`@wix/auto_sdk_table-reservations_time-slots` ≤ 1.0.47, pulled by `@wix/table-reservations`) field-picks only `{ reservationLocationId, partySize, timeRange }`, and the REST body is those same three fields — so an `experienceId` option is **silently dropped** (an `as any` cast is a **no-op** here, unlike Gotcha B). Calling `getScheduledTimeSlots` for an experience returns the **location's default slots** (wrong day/time/duration), presented to guests as the experience's — and it **fails silently**: a populated-but-wrong list looks healthy, and the premium gate (below) stops live verification before you'd notice. Instead, **derive upcoming occurrences from the experience's own `configuration.onlineReservations.businessSchedule`** — `entries[].weeklyOptions.startDaysAndTimes[{ day, time }]` (or `oneTimeOptions`) + `durationInMinutes`, already returned by `queryExperiences()`. Treat that as a **display projection**; real capacity/conflict enforcement happens server-side when `createReservation` runs.
-
-**⚠️ Same premium precondition** as online reservations: **creating** experiences is free, but **booking** one needs a premium site with online reservations enabled (`428 PREMIUM_ONLY` otherwise — `setup-restaurant-experiences.md`). Build the flow; treat a booking failure on a non-premium site as a provisioning precondition, not a code bug.
-
----
-
-## Conclusion
-A correct Table-Reservations frontend:
-- imports **`reservationLocations` / `timeSlots` / `reservations` from `@wix/table-reservations`** — one package, three namespaces; **no cart / ecom / redirects** (a reservation is a hold, not a purchase);
-- uses **`_id`** (never `id`) for the location and reservation, and **defaults the `list*` array** (`= []`) so strict/`astro check` passes;
-- calls **`getTimeSlots(locationId, new Date(date), partySize, options?)`** with **positional** args — the `date` param is a **`Date`** (not the ISO string the doc shows) — and books only **`status === 'AVAILABLE'`** slots (passing the slot's `Date` `startDate` onward);
-- books via **`createHeldReservation({...})` → `reserveReservation(id, reservee, revision)`** (three positional args; `firstName` + `phone` required; 10-minute hold; `reserveReservation` is the only exit from `HELD`);
-- treats **`onlineReservationsEnabled` (premium)** as a precondition — the read/book flow only works once it's on;
-- **for experiences** (when in the run): lists via **`queryExperiences().find()`** (builder → `.items`); offers times **projected from the experience's own `businessSchedule`** — there is **no** experience-scoped `getScheduledTimeSlots` (Gotcha C: the `experienceId` option is silently dropped, so that call returns the location's slots); and books via `createReservation` with **`details.experienceId`** (an `any` cast past the SDK `Details` type — Gotcha B) — same premium precondition.
-</content>

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

@@ -1,161 +0,0 @@
----
-name: "How to Code Restaurants"
-description: The frontend read contract for a Wix Restaurants Menus site — which SDK modules to import, how to list menus/sections/items, how to re-order them by the parent's id arrays, how to read prices from priceInfo, and the _id / image gotchas the docs omit. Specifies the *how* (modules + exact calls + failure modes); which menu to render comes from the request.
----
-**RECIPE**: How to Code a Wix Restaurants Frontend (Menus V1 — display-only)
-
-A concise contract for writing the **frontend code** that renders a Wix Restaurants **menu**: listing the menu, its sections, and their items, assembling the hierarchy in display order, and reading each item's price. **This recipe is the *how* (which modules, which calls, which fields), not the *what*** — which menu to show and how the page looks are decided by the request you're fulfilling.
-
-> **This recipe is for CODING the menu display, not for seeding it.** It assumes a Restaurants Menus backend already exists (a menu, its sections, its items). It says nothing about creating them — only how to read and render them from frontend code.
-
-> **Menus are DISPLAY-ONLY here.** The Wix Restaurants **Menus** app is a catalog for *showing* a menu — there is no cart, no checkout, no `variantId`, no `@wix/ecom` in this recipe. **Online ordering** (add-to-cart / checkout) and **table reservations** are **separate apps** (`@wix/restaurants` Orders / the distinct `@wix/table-reservations` package, installed only if the request calls for them) and are out of scope. If the site only shows a menu, you import one package and make read calls — nothing else.
-
-> **⚠️ 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 `entity.id`-is-`undefined` bug. Fetch the `.md?apiView=SDK` form directly; don't re-discover these with search.
-
----
-
-## The modules and the client (read this first)
-
-**One package for menu display: `@wix/restaurants`.** It exposes three namespaces you read from — one per level of the hierarchy:
-
-| Need | Package | Module (namespace) |
-|---|---|---|
-| Menus (list / get) | `@wix/restaurants` | `menus` |
-| Sections (list / get) | `@wix/restaurants` | `sections` |
-| Items (list / get) | `@wix/restaurants` | `items` |
-
-The hierarchy is **Menu → Sections → Items**, wired by **id arrays**: a `menu.sectionIds[]` points at its sections, a `section.itemIds[]` points at its items. You read each level separately and stitch them together (see *Assembling the menu*).
-
-**Auth / client — framework split:**
-- **Astro (Wix-managed):** authentication is ambient. Call `menus` / `sections` / `items` directly from server components and backend routes (`src/pages/api/*.ts`) — **no `createClient`, no `OAuthStrategy`, no `clientId`.**
-  ```js
-  import { menus, sections, items } from '@wix/restaurants';
-  const { menus: menuList } = await menus.listMenus({ onlyVisible: true });
-  ```
-- **Non-Astro (Vite/React/Vue/static):** build one manual visitor client and reuse it:
-  ```js
-  import { createClient, OAuthStrategy } from '@wix/sdk';
-  import { menus, sections, items } from '@wix/restaurants';
-
-  const client = createClient({
-    modules: { menus, sections, items },
-    auth: OAuthStrategy({ clientId: /* the project's PUBLIC OAuth client id */ }),
-  });
-  // then: await client.menus.listMenus({ onlyVisible: true })
-  ```
-  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)
-
-The exact field paths the frontend reads. These are **SDK read shapes** (`?apiView=SDK`), so ids are **`_id`**. Price is a decimal **string**.
-
-```jsonc
-// menus.listMenus({ onlyVisible: true })  →  { menus: [...] }
-menu = {
-  _id,                       // entity id (NOT .id → undefined in SDK code)
-  name, description, visible,
-  sectionIds,                // ORDERED array of section _ids — the section display order lives HERE
-  urlQueryParam,             // slug fragment for the menu URL
-}
-
-// sections.listSections({ onlyVisible: true })  →  { sections: [...] }
-section = {
-  _id, name, description, visible,
-  itemIds,                   // ORDERED array of item _ids — the item display order lives HERE
-  image,                     // OPTIONAL media id STRING (wix:image://…) or absent — see Rendering images
-}
-
-// items.listItems({ onlyVisible: true })  →  { items: [...] }
-item = {
-  _id, name, description, visible,
-  priceInfo: { price },      // PRICE. price is a decimal STRING ("9.50"), NO currency symbol. The SDK `PriceInfo` type carries ONLY `price` — there is no `formattedPrice`
-  image,                     // OPTIONAL — a media id STRING (wix:image://…) or absent (text-only seed). NOT an object: resolve it, never read image.url
-}
-```
-
----
-
-## The features (build the ones the site needs)
-
-Each section below is a **self-contained feature** — implement only what the site uses. The only ordering is *within* the assembly (fetch levels before you stitch them).
-
-### Listing menus / sections / items (and the `_id` rule)
-
-Use the `list*` methods — they take a simple options object and return a plain array, with no query-builder ceremony:
-
-```js
-const { menus: menuList }    = await menus.listMenus({ onlyVisible: true });
-const { sections: allSecs }  = await sections.listSections({ onlyVisible: true });
-const { items: allItems }    = await items.listItems({ onlyVisible: true });
-```
-Docs: <https://dev.wix.com/docs/api-reference/business-solutions/restaurants/menus/menus/list-menus.md?apiView=SDK> · <https://dev.wix.com/docs/api-reference/business-solutions/restaurants/menus/sections/list-sections.md?apiView=SDK> · <https://dev.wix.com/docs/api-reference/business-solutions/restaurants/menus/items/items/list-items.md?apiView=SDK>
-
-**✅ PREFER `list*` over `query*` for reads.** `listMenus` / `listSections` / `listItems` take an options object (`{ onlyVisible, paging, menuIds/sectionIds/itemIds }`) and are unambiguous. The `queryMenus` / `queryItems` methods exist but their argument shape (object-param vs. fluent builder) is a known SDK-doc drift hotspot across Wix packages — avoid them for simple reads. To fetch a specific subset by id, pass the id array to the list method: `items.listItems({ itemIds: section.itemIds })`.
-
-**⚠️ CRITICAL: the entity id is `_id`, NOT `id`.** The SDK normalizes every entity's id to **`_id`**. `menu.id` / `section.id` / `item.id` are `undefined` in SDK code. Use `_id` everywhere — when following `sectionIds` / `itemIds`, when building links, and as React keys. (If a field name surprises you, you are probably reading the REST doc view — re-open it with `?apiView=SDK`.)
-
-**Visibility:** pass `onlyVisible: true`, and note only entities seeded `visible: true` are returned to a visitor token anyway — a missing section/item usually means it wasn't seeded visible, not a query bug (ties back to the seed recipe).
-
-### Assembling the menu (follow the id arrays — and preserve their order)
-
-The three `list*` calls return **flat, unordered** arrays. The display structure and order live in the parent's id arrays (`menu.sectionIds`, `section.itemIds`), so stitch by looking entities up by `_id` **in id-array order** — do **not** render the raw `list*` order.
-
-```js
-const byId = (arr) => new Map(arr.map((e) => [e._id, e]));
-const secById  = byId(allSecs);
-const itemById = byId(allItems);
-
-const menu = menuList[0];  // or match by urlQueryParam / name per the request
-const structured = {
-  ...menu,
-  sections: (menu.sectionIds ?? [])
-    .map((sid) => secById.get(sid))
-    .filter(Boolean)                                  // a stale id (deleted section) → skip, don't crash
-    .map((sec) => ({
-      ...sec,
-      items: (sec.itemIds ?? [])
-        .map((iid) => itemById.get(iid))
-        .filter(Boolean),
-    })),
-};
-```
-
-**⚠️ CRITICAL: order comes from `sectionIds` / `itemIds`, NOT from the `list*` response order.** `listSections` / `listItems` return entities in arbitrary (creation/internal) order. If you render `allSecs` / `allItems` directly, the menu shows "Desserts" before "Starters" and items in a scrambled order. Always map over the parent's ordered id array and look each child up by `_id`. **`.filter(Boolean)`** after each lookup so a dangling id (a child deleted out from under the menu) is skipped rather than rendering `undefined`.
-
-### Reading the price
-
-Read **`item.priceInfo.price`** — a decimal **string** (`"9.50"`) with **no currency symbol**. Render it directly, or `Number(item.priceInfo.price)` if you need arithmetic, and prefix your site's currency in the UI.
-
-**⚠️ CRITICAL: price is under `priceInfo.price`, not a top-level `price` field — and there is NO `formattedPrice` on the SDK type.** Two traps here:
-- The old top-level `item.price` is **deprecated** and reads `undefined` against seeded data → `$NaN` on the page. Always read `item.priceInfo.price`.
-- The SDK's `PriceInfo` type is **`{ price?: string }`** only. `item.priceInfo.formattedPrice` **does not type-check** (`TS2339`) — even though the REST response happens to include a `formattedPrice`, the SDK type omits it, and the frontend calls the SDK. Do **not** read `formattedPrice`; format the currency yourself from `price` (the amount carries no symbol).
-
-### Rendering images (only when imagery is on)
-
-Menus are seeded **text-only by default**, so `section.image` / `item.image` are usually **absent** — guard for that and render a text-only card when missing. **`image` is a bare STRING** (the SDK types both `Section.image` and `Item.image` as `image?: string`) — a media identifier, usually a `wix:image://…`, occasionally an already-absolute URL. It is **not** an object, so **never read `image.url`** (`TS2339` — the recipe's earlier draft got this wrong). Resolve a `wix:image://` string through the helper (never put it straight into `<img src>` — it fails with `ERR_UNKNOWN_URL_SCHEME`):
-
-```js
-import { media } from '@wix/sdk';
-function imgSrc(image, w = 600, h = 600) {
-  if (!image) return '';                                   // absent (text-only) → caller renders a text card
-  if (image.startsWith('wix:image://')) return media.getScaledToFillImageUrl(image, w, h, {});  // 4th arg REQUIRED
-  return image;                                            // already an absolute https URL
-}
-```
-
-**⚠️ `media.getScaledToFillImageUrl` takes FOUR arguments** in `@wix/sdk` — `(wixMediaIdentifier, width, height, options)`. The `options` object is **required** (unlike `getCroppedImageUrl`, whose `options?` is optional); a 3-arg call fails with `TS2554: Expected 4 arguments, but got 3`. Pass `{}` when you have no transform options.
-
-Never hand-build a `static.wixstatic.com/.../v1/fit/...` URL — the format is easy to get wrong and the image then 403s. Doc: <https://dev.wix.com/docs/sdk/core-modules/sdk/media>
-
----
-
-## Conclusion
-A correct Restaurants Menus frontend:
-- imports **`menus` / `sections` / `items` from `@wix/restaurants`** — one package, three read namespaces; **no cart / checkout / ecom** (menus are display-only; ordering & reservations are separate apps);
-- uses **`_id`** (never `id`) as every entity's id and when following `sectionIds` / `itemIds`;
-- prefers the **`list*`** methods (option-object) over the drift-prone `query*` builders for reads;
-- **assembles menu → sections → items in the order of the parent's `sectionIds` / `itemIds` arrays** (not the `list*` response order), `.filter(Boolean)` to drop dangling ids;
-- reads price from **`item.priceInfo.price`** (a decimal string, no currency; **no `formattedPrice` on the SDK type**) — never the deprecated top-level `price`;
-- treats `image` as an **optional string** (never `image.url`) and resolves `wix:image://` values through **`media.getScaledToFillImageUrl(id, w, h, {})`** (4 args), never raw.

package/skills/wix-headless/references/inline-recipes/setup-blog.md

@@ -1,175 +0,0 @@
----
-name: "Setup Blog"
-description: Initializes a Wix Blog with Blog V3 — fetches an author memberId, then bulk-creates published posts with Ricos rich content (text-only), and optionally creates + assigns categories/tags. Specifies the *how* (calls + format); how many posts, their topics, and which categories come from the request being fulfilled.
----
-**RECIPE**: Business Recipe – Initial Setup for a Wix Blog (Blog V3)
-
-> **Standard call shape (every curl below).** The `<AUTH>` placeholder is shorthand for `Authorization: Bearer <TOKEN>` only. Body-bearing requests also need `Content-Type: application/json`.
-
-A concise checklist for populating any new Wix site that has the Blog app installed with Blog V3.
-**Notice** that this recipe is **NOT** meant for coding purposes and is **ONLY** meant for initial blog content setup.
-
-> **This recipe is the *how*, not the *what*.** What to seed — how many posts, which topics, whether to group them into categories/tags — is determined by the request you're fulfilling. This recipe only specifies the calls and the request format; it does not decide quantities or topics.
-
-> **API surfaces:** posts use Blog V3 (`https://www.wixapis.com/blog/v3/...`). The author lookup is the exception — it lives on the Members API (`https://www.wixapis.com/members/v1/members`). Don't mix in any pre-V3 blog endpoints.
-
----
-
-## Article: Steps for Setting Up a Wix Blog
-**YOU MUST** complete all the following steps **in the given order** (1-3), then **Attach images** when `imagery` is on, without skipping any and **without requiring additional user input**.
-
-**⚠️ CRITICAL ORDER REQUIREMENT: Fetch the author `memberId` FIRST — every post create needs it. Create the posts. Categories/tags are optional and only created if the request names them. Covers are added in the **Attach images** step, only when `imagery` is on.**
-
-### STEP 1: Get an author `memberId` (required for 3rd-party callers)
-
-When calling the Blog API as a 3rd-party app (headless, not the site owner in the dashboard), every post create needs `memberId` — the post's author. Omitting it fails with `"Missing post owner information"`.
-
-**⚠️ `memberId` is *author attribution*, not the caller.** Two identities are in play and they are NOT the same: the **caller** is the **APP** (your admin/CLI token — `CreateDraftPost` is an admin-only method, `applicableIdentities: [APP]`), while `memberId` is a **body field** meaning *"the draft post owner's member ID"* — whom to credit as author. The dashboard supplies the author implicitly (the logged-in human); a headless APP token isn't a person, so it must **name** one — that's the whole reason for this lookup. Consequence: this does **not** mean a logged-in member can author posts from their own session — every draft-post write/query method is APP-only. (Member-native blog features are **likes** and **comments**; see `how-to-code-a-blog.md`.)
-
-List the first site member and keep its id:
-
-```bash
-curl -sS -X GET "https://www.wixapis.com/members/v1/members?fieldsets=PUBLIC&paging.limit=1" \
-  -H "Authorization: <AUTH>"
-```
-
-Read `members[0].id` (a.k.a. `_id`) from the response — that's the `memberId` you pass to every post in Step 2.
-
-**⚠️ CRITICAL: the `memberId` must belong to a real site member/collaborator** — never fabricate one (a made-up id fails the create with `"memberIds ... do not exist"`). A provisioned site normally has the owner as a member, so this GET returns at least one id. **If the list comes back empty**, the documented fallback is to **create a member first** (find the Members API create method via `DOC_DISCOVERY.md` — don't guess its URL/body) and use that id, or use the site owner's member id. Only if neither is possible, **fail loudly** with the empty-members response.
-
-### STEP 2: Bulk-create the posts (published, with Ricos content)
-
-Create the posts in a **single bulk request** to `POST https://www.wixapis.com/blog/v3/bulk/draft-posts/create` with `"publish": true` so they go live immediately. **How many posts and their topics are set by the request you're fulfilling — this step only gives the call and the required format.** Each post is **text-only** (no cover image — imagery is attached later in the dedicated images step only when `imagery` is on; `SEED.md` § "Entity images").
-
-> **Use the bulk endpoint whenever `postCount ≥ 2`** — one call replaces N single-post calls, each of which costs ~25–30 s of latency. For exactly one post, use the single-post endpoint shown at the end of this step.
-
-**⚠️ CRITICAL: the correct URL is `/blog/v3/bulk/draft-posts/create`** — `bulk` is a path segment **between** `v3` and `draft-posts`, not a suffix. Both `/blog/v3/draft-posts/bulk` and `/blog/v3/draft-posts/bulk-create` return **404**.
-
-**⚠️ CRITICAL: each item in `draftPosts` is a FLAT post object — do NOT wrap it in a `draftPost` field.** The single-post endpoint uses the `{ "draftPost": {…} }` envelope because the request *is* one post; the bulk endpoint flattens that envelope away because the array itself is the envelope. Wrapping each item in `draftPost` returns `400 "draftPosts[i].title must not be empty"` (the API looks for `draftPosts[i].title` directly and finds it nested). Put `title` / `memberId` / `richContent` **directly** inside each array element.
-
-**Request body shape** (one representative post shown — repeat post objects inside the `draftPosts` array):
-
-```json
-{
-  "draftPosts": [
-    {
-      "title": "How We Roast Our Single-Origin Beans",
-      "memberId": "<memberId-from-step-1>",
-      "richContent": {
-        "nodes": [
-          {
-            "type": "HEADING",
-            "id": "n1",
-            "nodes": [
-              { "type": "TEXT", "id": "", "nodes": [], "textData": { "text": "From farm to cup", "decorations": [] } }
-            ],
-            "headingData": { "level": 2 }
-          },
-          {
-            "type": "PARAGRAPH",
-            "id": "n2",
-            "nodes": [
-              { "type": "TEXT", "id": "", "nodes": [], "textData": { "text": "Every batch starts with beans sourced from a single estate.", "decorations": [] } }
-            ],
-            "paragraphData": {}
-          },
-          {
-            "type": "BLOCKQUOTE",
-            "id": "n3",
-            "nodes": [
-              {
-                "type": "PARAGRAPH",
-                "id": "n4",
-                "nodes": [
-                  { "type": "TEXT", "id": "", "nodes": [], "textData": { "text": "Great coffee is grown, not made.", "decorations": [] } }
-                ],
-                "paragraphData": {}
-              }
-            ],
-            "blockquoteData": { "indentation": 1 }
-          }
-        ]
-      }
-    }
-  ],
-  "publish": true
-}
-```
-
-**⚠️ CRITICAL RICOS NESTING — `richContent` is Ricos JSON, not a string or HTML.** A plain string or an HTML blob is rejected. Build a `{ "nodes": [...] }` tree following these rules, or you get `"Expected a paragraph node but found TEXT"`:
-- **`TEXT` is always a leaf** inside a container — never a direct child of `BLOCKQUOTE`, `LIST_ITEM`, `CODE_BLOCK`, or the root.
-- **`BLOCKQUOTE` and `LIST_ITEM` contain `PARAGRAPH` nodes**, which then contain the `TEXT`.
-- **`BULLETED_LIST` / `ORDERED_LIST` contain `LIST_ITEM` nodes**, which contain `PARAGRAPH` → `TEXT`.
-- **Container nodes (`PARAGRAPH`, `HEADING`, `BLOCKQUOTE`, …) need a unique `id`** (any string, e.g. `"n1"`, `"n2"`); `TEXT` leaves may use `"id": ""`.
-- Common node types: `PARAGRAPH` (body), `HEADING` (`headingData.level` 2–4), `CODE_BLOCK` (`codeBlockData.language`), `BULLETED_LIST`/`ORDERED_LIST` + `LIST_ITEM`, `BLOCKQUOTE`. Mix at least a few per post for visual variety.
-
-**⚠️ CRITICAL: omit `media` — seed text-only.** Cover/inline images are attached in the dedicated **Attach images** step **only when `imagery` is on** (`SEED.md` § "Entity images"). Do not pass external image URLs into `media` or `richContent` `IMAGE` nodes here — external URLs don't work directly (they must first be imported to Wix Media), and imagery is opt-in.
-
-**⚠️ Reading the response — bulk results carry only ids, not slugs.** A successful bulk create returns `200` with:
-
-```json
-{ "results": [
-  { "itemMetadata": { "id": "<postId>", "originalIndex": 0, "success": true } }
-] }
-```
-
-The bulk call returns `200` **even if some items fail** — check each `results[i].itemMetadata.success` individually; it does **not** throw on partial failure. If part of the batch fails, retry **only the failed items** **once** with the exact same format; do not loop. (You need only confirm each post was created — the frontend links posts by **slug read from a live `queryPosts` result / the URL**, so there's no need to collect slugs at seed time.)
-
-**⚠️ CRITICAL: a transient `401 "No identity found"` on draft-post creation is a known server-side async-identity defect, NOT a body error.** It is not caused by your token or payload (categories/members/CMS calls succeed with the same token). If you hit it, **retry the create once**; do not rewrite the body and do not retry-spiral — a spiralling retry is a wasted headless run.
-
-#### Single-post endpoint (only when `postCount = 1`)
-
-`POST https://www.wixapis.com/blog/v3/draft-posts` with the **nested** envelope and `publish: true`:
-
-```json
-{
-  "draftPost": {
-    "title": "How We Roast Our Single-Origin Beans",
-    "memberId": "<memberId-from-step-1>",
-    "richContent": { "nodes": [ /* same Ricos tree as above */ ] }
-  },
-  "publish": true
-}
-```
-
-### STEP 3: Group posts into categories / tags (optional — only if the request names them)
-
-Only create categories or tags **if the request explicitly groups the posts** (e.g. "a blog with Recipes and Brewing-Tips sections"). If it doesn't, **create none** — skip this step entirely (skill policy; overrides any docs default).
-
-- **Categories:** `POST https://www.wixapis.com/blog/v3/categories` per category; keep each returned category `id`.
-- **Tags:** `POST https://www.wixapis.com/blog/v3/tags` per tag; keep each returned tag `id`.
-- **Assign:** include the resolved ids in each post's `categoryIds` / `tagIds` array — set them **in the Step-2 create body** when you already know the grouping, or PATCH the post afterward via **`PATCH https://www.wixapis.com/blog/v3/draft-posts/{draftPostId}`** (body wrapped in `draftPost`). **⚠️ NOT `POST …/draft-posts/{id}/update`** — that path 404s for a single post; `/update` exists only as the bulk method.
-
-**⚠️ CRITICAL: re-publish after any PATCH.** Updating an already-published post sets `hasUnpublishedChanges: true` — the live site keeps showing the old version until you call `POST https://www.wixapis.com/blog/v3/draft-posts/{draftPostId}/publish` again. (Seeding categoryIds/tagIds directly in the Step-2 create body avoids this round-trip.)
-
-> **Comments (a Required site feature, conditional).** If the request's blog needs reader comments, comments are typically available once the Blog app is installed — record it as **available** so the Handoff tells the host to surface the comment UI (the coding recipe wires read-public / write-authenticated). Only if comments are off by default for this site, enable the feature — find the check/enable method via `DOC_DISCOVERY.md` — before relying on it. Don't seed comment *content*.
-
-### Attach images (imagery ON only)
-
-**Runs only when `imagery` is on** (`SEED.md` § "Entity images"). If imagery is off, **skip this step entirely** — the posts were seeded text-only in the bulk-create step and stay that way. This is the pass-2 "attach the image" step for blog posts (the create is pass-1, text-first).
-
-For each post that should get a cover:
-
-1. **Generate + import** per `references/IMAGE_GENERATION.md` (§1 Generate, §2 Import). From the imported `file` object keep **`file.id`** — the WixMedia file id (e.g. `<hash>~mv2.jpg`). Blog binds the cover **by this id** (not by `file.url`).
-2. **Attach the cover** via **`PATCH https://www.wixapis.com/blog/v3/draft-posts/{draftPostId}`** (body wrapped in a `draftPost` object), writing the cover under `media`:
-
-   ```json
-   { "draftPost": { "media": { "displayed": true, "custom": true, "wixMedia": { "image": { "id": "<file.id>" } } } } }
-   ```
-
-   **⚠️ CRITICAL: the endpoint is `PATCH …/draft-posts/{draftPostId}` — NOT `POST …/draft-posts/{draftPostId}/update`.** The `/update` path **404s** for a single post (it exists only as the *bulk* update method); use the bare `PATCH` on the id.
-   **⚠️ CRITICAL: `media.wixMedia.image.id` ALONE is a silent no-op.** The PATCH returns `200` but the response comes back `media: { "displayed": false, "custom": false }` with no `wixMedia`, and **no cover attaches**. You MUST also set **`media.displayed: true`** and **`media.custom: true`** for the cover to persist. A `200` is therefore **not** proof — re-query the post's `media` and confirm `wixMedia.image` populated.
-3. **⚠️ Re-publish after the PATCH.** Updating an already-published post sets `hasUnpublishedChanges: true` / unpublishes it, so the live site keeps showing the old cover-less version until you call `POST https://www.wixapis.com/blog/v3/draft-posts/{draftPostId}/publish` again. (Same re-publish rule as the categories/tags step — don't let the two drift.)
-
-**Never block the run on image failure** — on a generation/import/attach failure, skip that cover and leave the post text-only (`IMAGE_GENERATION.md` § "Never block the run on image failure").
-
----
-
-## Conclusion
-Following these steps **in order** populates a new Blog V3 site:
-- Every post is authored by a **real `memberId`** (fetched first) and created **`publish: true`**, so it appears live immediately.
-- Posts carry valid **Ricos `richContent`** (correct `TEXT`-in-`PARAGRAPH` nesting), in the count and on the topics called for by the request.
-- The **bulk** endpoint is used for `postCount ≥ 2` (flat per-item shape), the single endpoint for one post.
-- Posts are seeded **text-only**; covers are attached by the **Attach images** step, only when `imagery` is on (`PATCH …/draft-posts/{id}` with `media.wixMedia.image.id = file.id` **plus `media.displayed:true` + `media.custom:true`**, then re-publish), otherwise they stay text-only.
-- Categories/tags exist **only if** the request named them, with posts assigned and re-published after any PATCH.
-- Posts are then discovered **live** by the frontend (`queryPosts`, `[...slug]` routes) — no per-post ids/slugs need to be carried into the coding handoff.