@wix/agent-skills 1.13.0 → 1.15.0

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

@@ -0,0 +1,173 @@
+---
+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 three 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` |
+
+**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>
+
+---
+
+## 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.
+</content>

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

@@ -0,0 +1,161 @@
+---
+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

@@ -0,0 +1,175 @@
+---
+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.