@wix/agent-skills 1.13.0 → 1.15.0

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

@@ -0,0 +1,236 @@
+---
+name: "How to Code a Store"
+description: The frontend read/cart contract for a Catalog V3 storefront — which SDK modules to import, how to resolve the mandatory variantId, the exact add-to-cart shape, how to filter by category, and how to read inventory. Specifies the *how* (modules + exact calls + the failure modes the docs omit); which products/categories to render come from the catalog the storefront reads.
+---
+**RECIPE**: How to Code a Wix Online Store Frontend (Catalog V3 + eCommerce cart)
+
+A concise contract for writing the **frontend code** of a storefront against a Catalog V3 store: listing products, filtering by category, adding to cart, and checking out. **This recipe is the *how* (which modules, which calls, which fields), not the *what*** — which products to show, how the page looks, and the framework are decided by the request you're fulfilling.
+
+> **This recipe is for CODING the storefront, not for seeding it.** It assumes a Catalog V3 store already exists (products, variants, categories, inventory). It says nothing about creating products — only how to read and purchase 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 shows `id`**; the **`?apiView=SDK` view shows `_id`** — and the SDK is what your frontend calls. Reading the REST view by mistake is the single most common source of the cart-killing `product.id` bug (see the `_id` rule under *Listing products*). Fetch the `.md?apiView=SDK` form directly; don't re-discover these with search.
+
+---
+
+## The modules and the client (read this first)
+
+**Stores app id** (a constant you will need for the cart's `catalogReference`):
+`215238eb-22a5-4c36-9e7b-e7c08025e04e`
+
+**⚠️ CRITICAL: use the V3 SDK modules, never the V1 ones.** The store is seeded with Catalog **V3** data. The legacy V1 `products` / `collections` modules read a different shape against the same data and fail in ways the SDK swallows silently (empty category pages, unresolved variants, `400`s on server-side filters). Import only:
+
+| Need | Package | Module |
+|---|---|---|
+| Products (list, get, search, filter) | `@wix/stores` | `productsV3` |
+| Variants (to resolve `variantId`) | `@wix/stores` | `readOnlyVariantsV3` |
+| Categories | `@wix/stores` | `categories` |
+| Cart (add / get / checkout) | `@wix/ecom` | `currentCart` |
+| Redirect to hosted checkout | `@wix/redirects` | `redirects` |
+
+**Never** import the V1 `products` or `collections` modules from `@wix/stores`.
+
+**Auth / client — framework split:**
+- **Astro (Wix-managed):** authentication is ambient. Call `currentCart` / `productsV3` / `readOnlyVariantsV3` 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 { productsV3, readOnlyVariantsV3 } from '@wix/stores';
+  import { currentCart } from '@wix/ecom';
+  import { redirects } from '@wix/redirects';
+
+  const client = createClient({
+    modules: { productsV3, readOnlyVariantsV3, currentCart, redirects },
+    auth: OAuthStrategy({ clientId: /* the project's PUBLIC OAuth client id */ }),
+  });
+  ```
+  The `clientId` is public, not a secret.
+
+---
+
+## The shapes you read (field cheat-sheet)
+
+The exact field paths the storefront reads, and the **plausible-wrong sibling** each is mistaken for — the sections below reference these instead of re-describing them. All `amount`s are **strings**. These are **read** shapes; the cart-add body (under *Adding to cart*) is a separate **write** shape, and the `_id` rule applies to read **entities**, not to method-return wrappers (note `checkoutId`).
+
+```jsonc
+// productsV3.queryProducts() / .searchProducts()  →  result.items[]
+product = {
+  _id,                                            // links · cart catalogItemId · variant filter   (NOT .id → empty → HTTP 500)
+  slug, name, visible,                            // only visible:true is returned to a visitor token
+  actualPriceRange:    { minValue: { amount } },  // PRICE   (NOT price.actualPrice.amount — that's the seed/WRITE shape → $NaN)
+  compareAtPriceRange: { minValue: { amount } },  // strike-through price
+  inventory: { availabilityStatus },              // product-level stock, "IN_STOCK"
+  media: { main: { image } },                     // image is a wix:image:// id → resolve it (see Rendering images)
+  plainDescription,                               // plain string; description.nodes is the rich-text form
+}
+
+// readOnlyVariantsV3.queryVariants().eq('productData.productId', product._id).find()  →  result.items[]
+// variants are a SEPARATE resource — queryProducts / getProduct return variantsInfo: null
+variant = {
+  variantId,                                      // → cart options.variantId   (use variant.variantId ?? variant._id)
+  optionChoices: [{ optionChoiceNames: { optionName, choiceName } }],  // match the buyer's Size/Color selection
+  inventoryStatus: { inStock },                   // variant-level stock (boolean)
+}
+
+// currentCart.getCurrentCart()  →  { lineItems: [...] }
+lineItem = { quantity, price: { amount }, image }  // price is HERE (NOT actualPriceRange); image is wix:image:// too → resolve
+
+// currentCart.createCheckoutFromCurrentCart({ channelType })  →  { checkoutId }   // a STRING — NOT { checkout }, NOT _id
+// redirects.createRedirectSession({ ecomCheckout: { checkoutId }, callbacks })  →  { redirectSession: { fullUrl } }
+```
+
+---
+
+## The storefront features (build the ones the site needs)
+
+Each section below is a **self-contained storefront feature** — implement only the ones the site uses; they don't have to be built in order, and some sites need just a few of them. The only ordering is *within* a feature (e.g. resolve the variant before adding it to the cart).
+
+### Listing products (and the `_id` rule)
+
+Query products with `productsV3.queryProducts()` / `.searchProducts()`.
+Doc: <https://dev.wix.com/docs/api-reference/business-solutions/stores/catalog-v3/products-v3/query-products.md?apiView=SDK>
+
+**⚠️ `queryProducts()` takes NO arguments — it returns a builder, not a Promise.** Chain `.eq(...)`/`.limit(...)`/`.find()` on it (e.g. `await productsV3.queryProducts().limit(50).find()`). Passing a query object (`queryProducts({...})`) does **not** type-check and returns a `Promise` that has no `.limit`/`.eq`/`.find` to chain — if the SDK reference page shows a `(query, options)→Promise` signature, trust the installed no-arg builder over that example. (`searchProducts` is the one that *does* take a query — see category filtering below.)
+
+**⚠️ CRITICAL: the entity id is `_id`, NOT `id`.** The SDK normalizes every entity's id to **`_id`**. `product.id` is `undefined` in SDK code. This is the cart-killer: feeding `product.id` into the cart's `catalogItemId` sends an empty string and the add returns **HTTP 500** (`"catalogItemId" has size 0`). Use `product._id` everywhere — in links, as the cart `catalogItemId`, and as the variant-query filter value. (If a field name surprises you, you are probably reading the REST doc view — re-open it with `?apiView=SDK`.)
+
+**Scope of the `_id` rule — entity reads only.** `_id` is the id of a read **entity** (product, variant, cart line item). It is **not** a universal "every id field is `_id`" rule: method results name their own fields (e.g. `createCheckoutFromCurrentCart` returns `checkoutId`, *not* `_id` — see Checkout). Don't assume a method's return wrapper exposes `_id`.
+
+**Visibility:** only `visible: true` products are returned to a visitor token, so a missing product usually means it wasn't seeded visible — not a query bug.
+
+**Price** comes from `actualPriceRange.minValue.amount` (see the cheat-sheet) — **not** `price.actualPrice.amount` (the seed/write shape), which reads `undefined` → `$NaN`.
+
+### Category navigation — list categories live
+
+**Build the category nav/rail from a live `categories` query (`@wix/categories`), never from a seeded category list** — a category the owner adds later then self-registers in the nav with no code change. Query at render time and read each `{ _id, name, slug }`; render the bar only when it returns **more than one** category, and treat it as **non-fatal** (wrap in try/catch, render without the bar if it fails).
+
+```js
+import { categories } from '@wix/categories';
+const res = await categories.queryCategories({
+  treeReference: { appNamespace: '@wix/stores' },
+}).exists('name', true).find();   // read the returned array per the SDK doc; ids are `_id`; link each to /category/<slug>
+```
+
+**⚠️ The query MUST carry a filter condition — chain `.exists('name', true)` (as above), do NOT call a bare `.find()`.** A `.find()` with no chained filter serializes an empty `"filter": {}`, which `categories/v1/categories/query` rejects with `400 INVALID_FILTER` ("Filter expression cannot contain an empty condition"). **This is fatal on the visitor/manual-client (non-Astro) path** — the call throws and the nav never renders; managed-Astro's server-side transport happens to tolerate the empty filter, so a bare `.find()` *looks* fine there but breaks the moment the same code runs client-side. `.exists('name', true)` is a tautology (every category has a `name`), so it matches **all** categories and is accepted on **both** paths — use this one shape everywhere. **Do NOT filter on `visible`** (`.eq('visible', true)`): unlike `name`, `visible` is **not declared filterable** on `queryCategories`, so it triggers a silently-swallowed `400` and the nav renders blank; if you ever need to hide a category, filter the returned array **client-side**. (`getCategoryBySlug(slug, { appNamespace: '@wix/stores' })` on the category page is unaffected — it takes no query filter.) This is a **distinct API from bookings' `categoriesV2`** — don't copy that module's query shape here; read the exact result-array key + field names from the `@wix/categories` SDK doc: <https://dev.wix.com/docs/sdk/business-solutions/categories/introduction.md?apiView=SDK>.
+
+### Filtering products by category
+
+**Filter server-side by the live `categoryId` — keyed on the stable category id, so products the owner adds to a category later appear with no code change or re-publish.** This is the **prescribed** approach; do **not** freeze a seed-time `category→productIds` map into the code and filter client-side against it (a product added to that category in the backoffice would never appear on its category page — the exact "owner edit is lost" failure this recipe exists to prevent).
+
+**⚠️ CRITICAL: category filtering MUST use `searchProducts`, NOT `queryProducts`.** `directCategoriesInfo.categories` is **not declared as filterable in `queryProducts`** — passing it there returns HTTP `400 "... is not declared as filterable"`, which the SDK **swallows silently**, leaving an empty category page that looks like "no products". This is the #1 way this breaks. Use Search Products:
+
+```js
+const { items } = await productsV3.searchProducts({
+  filter: { 'directCategoriesInfo.categories': { $matchItems: [{ id: categoryId }] } },
+});
+```
+
+- **`categoryId`** is the stable id from the live `categories.queryCategories()` result above (a category's `_id`) — read it from the render context, never a hardcoded seed-time id list.
+- **Method:** `searchProducts`, never `queryProducts` (the field is only filterable in search).
+- **Operator:** `$matchItems`, never `$hasSome` (the natural-looking guess returns nothing).
+- **Inner key:** `id` (the category GUID), inside `$matchItems: [{ id: … }]`.
+- **Never** the V1 `collectionIds` / `collections.id` paths — they return empty against V3 data.
+
+Docs: <https://dev.wix.com/docs/api-reference/business-solutions/stores/catalog-v3/products-v3/search-products.md?apiView=SDK> · <https://dev.wix.com/docs/api-reference/business-solutions/stores/catalog-v3/products-v3/supported-filters-and-sorting.md?apiView=SDK>
+
+### Adding to cart — the V3 cart contract
+
+Adding to cart is two parts of **one feature**: resolve the variant first, then add it. The variant resolution is not a standalone concern — it exists only to feed the add call.
+
+**1 · Resolve the `variantId` (mandatory).** Variants are a **separate read-only resource** — `queryProducts` / `getProduct` do **not** return variant data (this is documented; `variantsInfo` comes back `null`). Resolve the variant yourself:
+
+```js
+const { items } = await readOnlyVariantsV3
+  .queryVariants()
+  .eq('productData.productId', product._id)   // NOTE: productData.productId is the filter field
+  .find();
+```
+Doc: <https://dev.wix.com/docs/api-reference/business-solutions/stores/catalog-v3/read-only-variants-v3/query-variants.md?apiView=SDK>
+
+Each `variant` carries `variant.optionChoices[].optionChoiceNames` — `{ optionName, choiceName }`. Match the buyer's selected options (Size = "Small", Color = "Red", …) against those names to pick the variant. For a **single-variant** product, use the only item. Fall back to `items[0]` if matching yields nothing. The id to send to the cart is **`variant.variantId ?? variant._id`**.
+
+**2 · Add it.** Doc: <https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/purchase-flow/cart/add-to-current-cart.md?apiView=SDK> · catalogReference contract: <https://dev.wix.com/docs/api-reference/business-solutions/stores/catalog-v3/e-commerce-integration.md?apiView=SDK>
+
+```js
+await currentCart.addToCurrentCart({
+  lineItems: [{
+    quantity,
+    catalogReference: {
+      catalogItemId: product._id,                 // the product's _id (the `_id` rule above)
+      appId: '215238eb-22a5-4c36-9e7b-e7c08025e04e',
+      options: { variantId },                     // the resolved variantId from part 1
+    },
+  }],
+});
+```
+
+**⚠️ CRITICAL: `options.variantId` is MANDATORY for any product that has variants.** Adding by `catalogItemId` alone returns **HTTP 200 but adds nothing** — the silent empty cart. The cart method's required-params list omits `variantId`, so this fails quietly and looks like success. Always resolve and include it (part 1 above).
+
+**⚠️ CRITICAL: `options.options` is for MODIFIERS, not variant selection.** Product option selections (Size/Color) are resolved to a **variant** and referenced by `variantId`. `options.options` is only for free-text / TEXT_CHOICES add-on **modifiers**. Do **not** encode Size/Color as `options.options` — that is the coffee-grind bug (`200` + empty cart).
+
+### Checkout
+
+Create a checkout from the current cart, then redirect the buyer to the hosted checkout.
+Docs: <https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/purchase-flow/cart/create-checkout-from-current-cart.md?apiView=SDK> · <https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/purchase-flow/cart/get-current-cart.md?apiView=SDK>
+
+```js
+const checkout = await currentCart.createCheckoutFromCurrentCart({ channelType: currentCart.ChannelType.WEB });
+const session = await redirects.createRedirectSession({
+  ecomCheckout: { checkoutId: checkout.checkoutId },   // checkout.checkoutId — NOT checkout._id
+  callbacks: { postFlowUrl: `${origin}/`, thankYouPageUrl: `${origin}/` },
+});
+window.location.href = session.redirectSession.fullUrl; // the hosted-checkout URL
+```
+
+**⚠️ Return shapes are in the cheat-sheet** — `createCheckoutFromCurrentCart` gives **`checkout.checkoutId`** (a string), not `checkout._id`. Reading `checkout._id` (over-applying the `_id` rule) throws *"Cannot read properties of undefined (reading '_id')"* — the silent checkout crash.
+
+**⚠️ CRITICAL: `origin` for `postFlowUrl`/`thankYouPageUrl` MUST be the `https://` published host — derive it from `window.location.origin`, NEVER `new URL(request.url).origin`.** The Headless redirect allowlist registers the site's **`https://`** host and treats **`http://<same host>` as a different, unlisted origin**. When the buyer returns from the hosted checkout (e.g. clicks "Continue Browsing"), the redirect goes through the allowlist — and an `http://` `postFlowUrl` **403s** with *"… isn't listed as an allowed redirect domain."* If you build the redirect session in a **server route** (`src/pages/api/*`), `new URL(request.url).origin` resolves to **`http://`** behind Wix's TLS-terminating proxy → guaranteed 403 on return. So **pass `window.location.origin` from the client** into the route (don't read the origin off the request), or force the scheme to `https`. Doc: <https://dev.wix.com/docs/go-headless/getting-started/setup/manage-urls/add-allowed-redirect-domains>.
+
+### Showing stock state
+
+Read the **V3** inventory fields: product-level in-stock is `product.inventory.availabilityStatus` (`"IN_STOCK"`); variant-level is `variant.inventoryStatus.inStock`. Reading the V1 inventory field on V3 data returns `undefined` → everything renders out-of-stock (the all-OOS bug). These come from `productsV3` / `readOnlyVariantsV3`, not the V1 module.
+
+### Rendering product images
+
+Product media may come back as a **`wix:image://v1/<hash>/<file>#originWidth=…` identifier, not a ready URL** — this is what the SDK returns for images stored in Wix Media (e.g. once brand imagery is attached). Putting that string straight into `<img src>` shows nothing. `media.main` may carry **either** an already-absolute `.url` (e.g. an Unsplash placeholder seeded when imagery is off) **or** an `.image` that is a `wix:image://` id needing resolution — handle both with **one** helper and reuse it on every page that renders an image:
+
+```js
+import { media } from '@wix/sdk';
+function imgSrc(mediaMain, w = 600, h = 600) {
+  const v = mediaMain?.image ?? mediaMain?.url ?? mediaMain;   // the value can be a string or {url}
+  if (!v) return '';
+  if (typeof v === 'string' && v.startsWith('wix:image://')) return media.getScaledToFillImageUrl(v, w, h);
+  return typeof v === 'string' ? v : (v.url ?? '');            // already an absolute https URL
+}
+```
+
+**⚠️ Do NOT write `m.url ?? m.image` (or `image?.url ?? image`).** That returns the bare **`wix:image://` string** whenever `.url` is absent — which is exactly the Wix-Media case — and the browser fails it with **`ERR_UNKNOWN_URL_SCHEME`** (blank image). The `wix:image://` branch must go through `media.getScaledToFillImageUrl`; never return it raw. Define the helper **once** and call it from every render path (home, listing, product, cart) — resolving on some pages but not others is the common partial failure.
+
+**Never hand-build a `static.wixstatic.com/.../v1/fit/...` URL** either — the format is easy to get wrong and the image then **403s**. Only `wix:image://` values need resolving; an already-absolute `https://` URL goes straight into `<img src>`. Doc: <https://dev.wix.com/docs/sdk/core-modules/sdk/media>
+
+**This applies to cart line-item images too, not just product reads.** A cart `lineItem.image` is the same `wix:image://` identifier — run it through the same `imgSrc()` helper before `<img src>`. (If you build the cart over an API route, resolve there and return a ready URL so the component never sees a `wix:image://`.)
+
+### Rendering product descriptions
+
+Don't print the raw node object. A product description is rich text (`description.nodes`). Render the rich-text nodes, or use `plainDescription` for a plain string. Printing the raw node object dumps literal `<p>…</p>` into the page.
+
+### SEO on item pages (Astro, Wix-managed)
+
+A **product 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 a product page use:
+- **`wixMetadata`** from `WIX_APPS.checkoutAndOrders.productPageMetadata` — referenced **directly** in the export (module scope). ⚠️ It's `WIX_APPS.checkoutAndOrders`, **not** `WIX_APPS.stores` (`stores.id` is the catalog id for `catalogReference`, a different value). The `identifiers` key is your route param; the token is `…productPageMetadata.identifiers.handle`.
+- **`itemType`**: `seoTags.ItemType.STORES_PRODUCT`.
+
+**If you build a dedicated category route** (e.g. `/category/[slug]` or `/search/[collection]`), wire it the same way with `WIX_APPS.checkoutAndOrders.categoryPageMetadata` + `seoTags.ItemType.STORES_CATEGORY`. (A category rendered only as a query-string *filter* on the products listing is a main page — it gets its SEO from automatic injection, no `wixMetadata` needed.)
+
+Optional: render a `Product` schema.org JSON-LD `<script>` from the fetched product for rich results (see the guide's structured-data step).
+
+---
+
+## Conclusion
+A correct Catalog V3 storefront frontend:
+- imports **`productsV3` / `readOnlyVariantsV3` / `categories` / `currentCart` / `redirects`** — never the V1 `products`/`collections` modules;
+- uses **`product._id`** (never `product.id`) as the cart's `catalogItemId`;
+- resolves the **mandatory `variantId`** via `readOnlyVariantsV3` and passes it as `options.variantId` (not `options.options`);
+- builds its category nav from a **live `categories.queryCategories()`** and filters category pages server-side with **`searchProducts` + `$matchItems: [{ id: categoryId }]`** keyed on the live `categoryId` — never a frozen seed-time `productIds` map, never `queryProducts` for category filtering, never `$hasSome`, never V1 `collectionIds`;
+- reads inventory from the **V3** shape and renders rich-text descriptions, not raw nodes.

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

@@ -0,0 +1,279 @@
+---
+name: "How to Code Bookings"
+description: The frontend read/booking contract for a Wix Bookings (Services V2) site — which SDK modules to import, how to list services, fetch appointment vs class availability, render the schema-driven booking form, and run the createBooking → ecom Cart V2 → checkout-or-place sequence. Specifies the *how* (modules + exact calls + the failure modes the docs omit); which services to render and how the page looks come from the request.
+---
+**RECIPE**: How to Code a Wix Bookings Frontend (Services V2 + ecom Cart V2 checkout)
+
+A concise contract for writing the **frontend code** of a Bookings site: listing services, picking an availability slot, collecting the booking form, and completing the booking. **This recipe is the *how* (which modules, which calls, which fields), not the *what*** — which services to show, how the page looks, and the framework are decided by the request you're fulfilling.
+
+> **This recipe is for CODING the booking flow, not for seeding it.** It assumes a Services V2 backend already exists (services with a category, staff resources, durations/prices, and — for classes — scheduled sessions). It says nothing about creating services — only how to read and book 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 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 `service.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)
+
+**Constants** (a frontend file, e.g. `src/services/constants.ts`):
+- **Wix Bookings app id** (the cart's `catalogReference.appId`): `13d21c63-b5ec-5912-8397-c3a5ddb27a97`
+- **Staff-member resource type id** (the ANY_RESOURCE fallback + staff filtering): `1cd44cf8-756f-41c3-bd90-3e2ffcaf1155`
+
+**⚠️ CRITICAL: there is NO `availability` namespace.** `import { availability }` / `availability.queryAvailability` does not exist and fails. Appointment availability is `availabilityTimeSlots.listAvailabilityTimeSlots`; class availability is `eventTimeSlots.listEventTimeSlots` — two different namespaces. Import only:
+
+| Need | Package | Module |
+|---|---|---|
+| Services (list, query by slug) | `@wix/bookings` | `services` |
+| Appointment availability | `@wix/bookings` | `availabilityTimeSlots` |
+| Class availability | `@wix/bookings` | `eventTimeSlots` |
+| Categories (optional filter) | `@wix/bookings` | `categoriesV2` |
+| Locations (optional filter) | `@wix/bookings` | `services` (`queryLocations`) |
+| Create the booking | `@wix/bookings` | `bookings` (`createBooking`) |
+| Cart that holds the seat (add / calc / place) | `@wix/auto_sdk_ecom_cart-v-2` | `createCart`, `calculateCart`, `placeOrder` |
+| Redirect to hosted checkout | `@wix/redirects` | `redirects` |
+| Booking-form schema | `@wix/forms` | `forms` (`getFormSummary`) |
+
+**Never** use `confirmBooking` (see *Creating the booking*) — the ecom cart confirms the seat here, not a server-side confirm.
+
+**Auth / client — framework split:**
+- **Astro (Wix-managed):** authentication is ambient. Call the modules directly from server components / backend routes and from browser islands (the `@wix/astro` visitor client) — **no `createClient`, no `OAuthStrategy`, no `clientId`.** Nothing here needs elevation (the reads below all run as the visitor); 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 { services, availabilityTimeSlots, eventTimeSlots, categoriesV2, bookings } from '@wix/bookings';
+  import { createCart, calculateCart, placeOrder } from '@wix/auto_sdk_ecom_cart-v-2';
+  import { redirects } from '@wix/redirects';
+  import { forms } from '@wix/forms';
+
+  const client = createClient({
+    modules: { services, availabilityTimeSlots, eventTimeSlots, categoriesV2, bookings, createCart, calculateCart, placeOrder, redirects, forms },
+    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)
+
+V2 service objects are **flat**. The exact paths the frontend reads, and the plausible-wrong sibling each is mistaken for:
+
+```jsonc
+// services.queryServices(...).find()  →  result.items[]   (filter out s.hidden)
+service = {
+  _id,                                              // links · cart catalogItemId base   (NOT .id → undefined)
+  name, description, tagLine,
+  type,                                             // "APPOINTMENT" | "CLASS"
+  hidden,                                           // skip hidden services
+  mainSlug: { name },                               // the URL slug   (NOT service.slug; fallback supportedSlugs[0].name)
+  schedule: { id, availabilityConstraints: { sessionDurations: [60] } },  // duration = sessionDurations[0] (minutes)
+  payment: { fixed: { price: { value, currency } } },                     // value is a STRING; currency is the site's
+  media: { mainMedia: { image } },                  // image is a "wix:image://…" string — resolve via media.getImageUrl()
+  category: { _id },                                // the service's category
+  form: { _id },                                    // the booking form (fetch via @wix/forms)
+  bookingPolicy: { cancellationFeePolicy: { enabled } },  // drives the checkout-vs-place decision
+  staffMemberDetails: { staffMembers: [{ staffMemberId, name }] },  // STAFF_MEMBER_DETAILS conditional field
+}
+
+// availabilityTimeSlots.listAvailabilityTimeSlots(...)  →  result.timeSlots[]   (APPOINTMENT)
+apptSlot = { localStartDate, localEndDate, scheduleId, location, availableResources }  // fields at TOP level (NOT slot.startDate); availableResources may be []
+//   availableResources[] = { resources: [{ _id, name }] }   // NESTED; each resource id is _id NOT id — this is what you read to label/group a slot by its staff/instructor
+
+// eventTimeSlots.listEventTimeSlots(...)  →  result.timeSlots[]   (CLASS)
+classSlot = { localStartDate, localEndDate, eventInfo: { eventId } }  // carries eventId; NO scheduleId
+```
+
+**⚠️ CRITICAL: entity ids are `_id`, NOT `id`.** `service._id`, `booking._id`. `service.id` is `undefined` in SDK code. This includes the **resource objects nested under a slot** — `slot.availableResources[].resources[]._id` (NOT `.id`); reading `.id` there silently yields `undefined`, so grouping/labeling/filtering slots by staff or instructor breaks with no error (an image-led class site rendering blank instructor names/photos is the tell). **`staffMemberDetails.staffMembers[].staffMemberId`** is the exception — despite the name it **IS the resource GUID** (it matches the seed's staff `resourceId`), and it's the value you filter availability and book by.
+
+---
+
+## The booking features (build the ones the site needs)
+
+Each section is a **self-contained feature** — implement only the ones the site uses; the only ordering is *within* the flow (pick a slot → collect the form → book). The minimal path is: list services → pick a slot → submit the form → book.
+
+### Listing services (and the `_id` rule)
+
+Always filter by `appId`, request `STAFF_MEMBER_DETAILS`, and call `.find()`:
+
+```js
+// Catalog (list):
+const { items } = await services
+  .queryServices({ conditionalFields: ['STAFF_MEMBER_DETAILS'] })
+  .eq('appId', BOOKING_APP_ID).limit(100).find();   // filter out items where s.hidden
+
+// Single service by slug — the same .eq() builder chain:
+const { items: [service] } = await services
+  .queryServices({ conditionalFields: ['STAFF_MEMBER_DETAILS'] })
+  .eq('mainSlug.name', slug).eq('appId', BOOKING_APP_ID).limit(1).find();
+```
+Doc: <https://dev.wix.com/docs/api-reference/business-solutions/bookings/services/services-v2/query-services.md?apiView=SDK>
+
+- **⚠️ `queryServices` is a fluent builder — its only argument is `QueryServicesOptions` (`conditionalFields`, etc.), NOT a `{ query: { filter, paging } }` object.** Apply the `appId` filter and paging as `.eq(...)` / `.limit(...)` chain calls, then `.find()`. The `{query:{filter,paging}}` form is the REST body shape; it does **not** type-check against the SDK (`'query' does not exist in type 'QueryServicesOptions'`) — if the SDK reference page shows an object-param form, trust the installed builder, not that doc example.
+
+- **`appId` filter is required** — omitting it returns services from other apps / nothing useful.
+- **Read V2 flat fields** (cheat-sheet): slug `mainSlug.name` (**not** `service.slug`), `name`/`description`/`tagLine`, duration `schedule.availabilityConstraints.sessionDurations[0]`, price `payment.fixed.price.value` (a **string**). A missing service usually means it wasn't seeded **with a category** (the visibility invariant), not a query bug.
+
+### Filtering — location & category (both auto-skip)
+
+Both filter the **catalog query** and re-render. **Show each filter only when there is more than one choice.**
+
+- **Category:** `categoriesV2.queryCategories().find()` → `result.items[{ _id, name }]`. **Non-fatal** — wrap in try/catch and render without the bar if it fails. Show the bar only when `items.length > 1` (the seed creates at least one category, so a single-category site shows no bar). Filter: `filter['category.id'] = { $eq: categoryId }`; a service's category is `service.category._id`.
+- **Location:** `services.queryLocations()` → `{ businessLocations, customLocations: { exists }, customerLocations: { exists } }`. Show the selector only when the total count > 1. A real business id → `filter['locations.business.id'] = { $hasSome: [id] }`; the synthetic `"custom"`/`"customer"` → `filter['locations.type'] = { $hasSome: ['CUSTOM'|'CUSTOMER'] }`. Carry the chosen location to the slots step so availability is scoped too (next section).
+
+### Availability (the slots step) — appointment vs class
+
+**⚠️ CRITICAL: APPOINTMENT and CLASS use different namespaces, and the slot fields are at the TOP level.**
+
+```js
+// APPOINTMENT — serviceId is a single GUID STRING:
+const { timeSlots } = await availabilityTimeSlots.listAvailabilityTimeSlots({
+  serviceId, fromLocalDate, toLocalDate, timeZone, bookable: true, cursorPaging: { limit: 100 },
+  // staff (optional):    resourceTypes: [{ resourceTypeId: STAFF_MEMBER_RESOURCE_TYPE_ID, resourceIds: [staffMemberId] }],
+  //                      includeResourceTypeIds: [STAFF_MEMBER_RESOURCE_TYPE_ID],
+  // one business location: locations: [{ _id: locationId, locationType: 'BUSINESS' }],
+});                                          // slots: result.timeSlots[] — localStartDate/localEndDate/scheduleId at TOP level
+
+// CLASS — different namespace, PLURAL serviceIds; slots carry eventInfo.eventId, NO scheduleId:
+const { timeSlots } = await eventTimeSlots.listEventTimeSlots({
+  serviceIds: [serviceId], fromLocalDate, toLocalDate, timeZone, includeNonBookable: false,
+  // staff/location (optional): eventFilter: { 'resources.id': { $hasSome: [staffMemberId] }, 'location.id': [locationId] },
+});
+```
+Docs: <https://dev.wix.com/docs/api-reference/business-solutions/bookings/time-slots/time-slots-v2/list-availability-time-slots.md?apiView=SDK> · <https://dev.wix.com/docs/api-reference/business-solutions/bookings/time-slots/time-slots-v2/list-event-time-slots.md?apiView=SDK>
+
+- **`fromLocalDate`/`toLocalDate` are LOCAL strings `YYYY-MM-DDThh:mm:ss` (no `Z`)** plus a separate `timeZone`. Passing UTC ISO strings with `Z` returns the wrong window.
+- **Slot fields are top-level** — read `timeSlot.localStartDate` / `.localEndDate` / `.scheduleId`, NOT `timeSlot.slot.startDate`. CLASS slots carry `eventInfo.eventId` and have **no** `scheduleId`.
+- **⚠️ Scope availability to exactly ONE business location on a multi-location service.** Unscoped, `listAvailabilityTimeSlots` returns **one slot per location** per time → every time appears N× (duplicated rows). Build the location list from `queryLocations()` intersected with the service's location ids (a `service.locations` id alone can be one the availability engine doesn't recognize → 0 slots). Staff does **not** multiply rows — one slot carries many `availableResources`.
+- **Staff picker auto-skips ≤1 staff** (`service.staffMemberDetails.staffMembers`). Filter by `staffMemberId` (the resource GUID). When a slot is picked with a specific staff, record `resource = { _id: staffMemberId, name }`; with "any staff", leave it unset (the booking emits the ANY_RESOURCE fallback below).
+- **Group slots by day** — don't render a flat time-only grid (the visitor can't tell which day a slot is on). Week / month / N-day is your choice.
+
+### The booking form — schema-driven (`@wix/forms`)
+
+The booking form is a `@wix/forms` form attached to the service at `service.form._id`. Render it **schema-driven** — never hardcode field names.
+
+**⚠️ CRITICAL: use `getFormSummary`, NOT `getForm`.** `getForm` returns the full nested schema (`form.formFields[].inputOptions.stringOptions.componentType…`), and hand-parsing that deep shape is the #1 source of a **silently empty form** — when your guess at the nested path is wrong, the parse yields zero fields and the form renders no inputs (→ empty `formSubmission` → `createBooking` 400 `first_name must have required property`) or hangs on a "loading" state. Use the **flat** summary instead:
+
+```js
+const { formSummary } = await forms.getFormSummary(service.form._id);
+// formSummary.fields[] = { target, label, type, options?, deleted, _id }   ← FLAT, no nesting
+const fields = (formSummary?.fields ?? [])
+  .filter(f => !f.deleted)
+  .filter(f => f.type && ['STRING', 'EMAIL', 'PHONE', 'NUMBER', 'URL'].includes(f.type));  // simple text-like only (`f.type` is optional on the summary field — guard it or strict build errors)
+```
+Doc: <https://dev.wix.com/docs/api-reference/crm/forms/form-schemas/get-form-summary.md?apiView=SDK> · bookings↔forms: <https://dev.wix.com/docs/api-reference/business-solutions/bookings/wix-forms-integration.md?apiView=SDK>
+
+- **`target` is the submission key** (top-level on each field — no `inputOptions` digging). `type` is a clean enum: render `EMAIL`→`type=email`, `PHONE`→`type=tel`, `NUMBER`→`type=number`, else text; a field with `options[]`→a `<select>`.
+- Each input **writes straight into one values object keyed by `target`** (`{ [target]: value }`). **That object IS the `formSubmission`** — pass it directly to `createBooking`. Do **not** rebuild a second object by looping the schema at submit time.
+
+**⚠️ CRITICAL: render the contact-basics fallback whenever the parsed list is EMPTY — not only on a thrown error.** A successful `getFormSummary` that yields zero usable fields (all filtered out, or an unexpected shape) must still produce a working form. Default to `first_name` / `last_name` / `email` (the booking enforces exactly these) so the form always renders and submits:
+```js
+const formFields = fields.length ? fields : [
+  { target: 'first_name', label: 'First Name', type: 'STRING' },
+  { target: 'last_name',  label: 'Last Name',  type: 'STRING' },
+  { target: 'email',      label: 'Email',      type: 'EMAIL'  },
+];
+```
+**Never gate the form's render on a loading flag that can't resolve** (e.g. showing "Loading form…" while `formFields.length === 0`) — with the fallback above the list is never empty, so render directly.
+
+**⚠️ Skip complex, object-valued field types** — `MULTILINE_ADDRESS`, `OBJECT`, `ARRAY`, `WIX_FILE`, `SIGNATURE`, `PAYMENT`, `DATE`/`TIME` (the filter above already keeps only the simple text-like types). Rendering one as a text input sends a string where the API wants an object and `createBooking` rejects it with **"must be object"**. Only the contact basics are enforced, so dropping optional complex fields is safe.
+
+### Creating the booking — the createBooking → ecom Cart V2 sequence
+
+This is one feature with a fixed sequence. **Use it as-is — the payload shapes are exact and easy to get subtly wrong.** APPOINTMENT and CLASS share the same sequence; they differ only in the slot fields.
+
+```
+createBooking(...)          // booking lands CREATED — the cart holds the seat (no confirmBooking)
+createCart(...)             // one catalogItem per bookingId, appId = BOOKING_APP_ID, channelType WEB
+calculateCart(cartId)       // → { cart, summary }; totals on summary.priceSummary.total.amount
+isCheckoutRequired ?  redirect to hosted checkout (paid)  :  placeOrder(cartId) (free / pay-in-person)
+```
+
+**1 · createBooking.** Doc: <https://dev.wix.com/docs/api-reference/business-solutions/bookings/bookings/bookings-writer-v2/create-booking.md?apiView=SDK>
+
+```js
+const created = await bookings.createBooking({
+  selectedPaymentOption,                 // derive from service.payment.options — see below
+  totalParticipants: 1,
+  bookedEntity: {
+    slot: {
+      serviceId,
+      scheduleId: slot.scheduleId ?? undefined, // APPOINTMENT only — the SELECTED SLOT's own scheduleId, NOT service.schedule.id (the availability slot types it `string | null`; `?? undefined` to satisfy the `string | undefined` param under strict)
+      eventId: slot.eventInfo?.eventId,   // CLASS only (Wix derives startDate/endDate/resource/location from it)
+      startDate: slot.localStartDate,     // local "YYYY-MM-DDThh:mm:ss"
+      endDate:   slot.localEndDate,
+      timezone,
+      // specific staff: resource: { _id: staffMemberId, name }
+      // any staff:      resourceSelections: [{ resourceTypeId: STAFF_MEMBER_RESOURCE_TYPE_ID, selectionMethod: 'ANY_RESOURCE' }]
+      location: { locationType: 'OWNER_BUSINESS' },   // map BUSINESS→OWNER_BUSINESS, CUSTOMER→CUSTOM
+    },
+  },
+}, { formSubmission });                   // the form values keyed by `target`
+const bookingId = created.booking._id;
+```
+
+- **⚠️ `scheduleId` MUST come from the SELECTED SLOT (`slot.scheduleId`), not from the service.** The APPOINTMENT slot carries its own top-level `scheduleId` (cheat-sheet) — carry it from the slots step into the booking. The service object *also* has a `schedule.id` (you read it for duration), but it is a **different value**: sending `service.schedule.id` (or an empty `scheduleId` prop) makes `createBooking` 400 with `VALIDATION_FAILURE: "…startDate, endDate, location.locationType, resource.id, and scheduleId must be set"`. (CLASS sends `slot.eventInfo.eventId` instead — no `scheduleId`.)
+- **⚠️ Pass `formSubmission`, NOT `contactDetails`.** `contactDetails` is what Wix derives back onto the response; sending it instead of `formSubmission` drops the visitor's input.
+- **⚠️ `formSubmission` is the object your inputs wrote to (values keyed by `target`) — send it DIRECTLY; do NOT rebuild it by iterating the parsed form-field schema.** If you re-derive the submission by looping over the schema array and your render falls back to a hardcoded field list when the schema parse comes back empty, the rebuild loop reads the empty schema and sends an **empty body** → `createBooking` 400s with `INVALID_ARGUMENT: "first_name must have required property 'first_name'…"` even though the form looked filled. Keep the typed-values object (`{ [target]: value }`) as the single source and pass that.
+- **⚠️ ANY_RESOURCE fallback (staff).** With no specific staff chosen, send `resourceSelections: [{ resourceTypeId: STAFF_MEMBER_RESOURCE_TYPE_ID, selectionMethod: 'ANY_RESOURCE' }]` and Wix auto-assigns a bookable resource — appointment slots can return `availableResources: []` yet book fine this way. A specific choice sends `resource: { _id, name }` instead.
+- **⚠️ Derive `selectedPaymentOption` from the service — do NOT hardcode `"ONLINE"`.** `online && !inPerson → "ONLINE"`; `!online && inPerson → "OFFLINE"`; else `"ONLINE"`. A **free / pay-in-person** service booked `ONLINE` makes the cart reject it with **`INSUFFICIENT_INVENTORY`** (`available_quantity: 0`).
+- **`locationType` on the booking slot is `OWNER_BUSINESS`** (the booking endpoint's enum), NOT `BUSINESS` (which is the *services* endpoint's enum). Map the slot's `BUSINESS`→`OWNER_BUSINESS`, `CUSTOMER`→`CUSTOM`.
+- **Wrap in try/catch** — `createBooking` can reject (slot taken between fetch and submit, strict phone validation). Surface a friendly message; don't crash.
+
+**2 · Cart holds the seat → checkout or place.**
+
+```js
+const cart = await createCart({
+  catalogItems: [{ quantity: 1, catalogReference: { catalogItemId: bookingId, appId: BOOKING_APP_ID } }],
+  cart: { source: { channelType: 'WEB' } },
+});
+if (!cart._id) throw new Error('cart creation failed');   // Cart V2 types `_id` as `string | undefined`; narrow once so the strict build accepts it downstream
+const cartId = cart._id;
+const { cart: calc, summary } = await calculateCart(cartId);   // totals are NOT stored on the Cart V2 entity
+
+// checkout required? cancellation-fee policy → yes; total 0 → no; FULL_PAYMENT_OFFLINE → no; else yes
+if (checkoutRequired) {
+  const { redirectSession } = await redirects.createRedirectSession({
+    ecomCheckout: { checkoutId: cartId },          // the cartId IS the checkoutId here
+    callbacks: { postFlowUrl: `${origin}/booking-confirmation` },
+  });
+  window.location.href = redirectSession.fullUrl;  // Wix-hosted checkout
+} else {
+  const order = await placeOrder(cartId);          // free / pay-in-person → confirmation
+}
+```
+
+- **⚠️ No `confirmBooking`.** The classic server-side confirm step is not used — the **ecom Cart V2** holds the seat: `placeOrder` (free/offline) or the hosted checkout (paid) drives confirmation, so a client-only site completes the whole flow with no server elevation.
+- **⚠️ CRITICAL: `origin` in `postFlowUrl` MUST be the `https://` published host — from `window.location.origin`, NEVER `new URL(request.url).origin`.** The Headless redirect allowlist registers the `https://` host and treats `http://<same host>` as a different, unlisted origin; a `http://` `postFlowUrl` makes the return ("Continue Browsing") **403** with *"… isn't listed as an allowed redirect domain."* Server-derived `new URL(request.url).origin` is `http://` behind Wix's proxy → pass `window.location.origin` from the client, or force `https`. Doc: <https://dev.wix.com/docs/go-headless/getting-started/setup/manage-urls/add-allowed-redirect-domains>.
+- **⚠️ CRITICAL: the confirmation page must reflect REAL status — do NOT hardcode `?status=success` in `postFlowUrl`, and do NOT default the page to success.** The buyer lands on `postFlowUrl` whether they completed payment **or** clicked "Continue Browsing" to abandon the hosted checkout. A confirmation page that reads `status ?? 'success'` (or trusts a `?status=success` you baked into the URL) renders "confirmed" for an **unpaid, abandoned** booking. Drive the confirmation from the actual order/booking — look up the booking (it's `CREATED` after `createBooking`; payment is a separate state) or the order — and don't present an unconfirmed booking as confirmed. For the free/offline branch, `placeOrder` having returned an `orderId` is a real success signal; for the paid branch, returning from the redirect is **not**.
+- **⚠️ Read the booking back as the anonymous visitor — `getBooking` is a manage-scope read that `403`s the visitor (same axis as the events `ticketDefinitions` trap; do NOT `auth.elevate`).** The visitor-public path is a two-step token handoff, both exports on `@wix/bookings` — use these exact calls, don't hunt the installed `.d.ts` for them:
+  1. **At booking time** (right after `createBooking` returns `booking._id`) mint a one-shot read token: `const { token } = await bookings.getAnonymousActionToken(bookingId)` — **`bookingId` is a POSITIONAL string arg, not `{ bookingId }`** (the object form fails `tsc`). Append the token to your `postFlowUrl` (e.g. `?bookingId=…&token=…`).
+  2. **On the confirmation page** read it back: `const { booking } = await bookings.bookingsGetBookingAnonymously(token)` — the response is **wrapped** (`{ booking }`). Drive the UI off **`booking.status`** (`CREATED` = seat held / payment pending; `CONFIRMED`/`PENDING` = done) and the time off **`booking.bookedEntity.slot.startDate`**.
+- The cart's `catalogReference.catalogItemId` is the **`booking._id`** and `appId` is the **Bookings app id** (a booking id is automatically valid as an ecom catalog item).
+
+### Rendering & mounting
+
+- **Price**: `service.payment.fixed.price.value` (string) + `.currency` (the site's stored currency — format from it, don't assume USD).
+- **Image**: `service.media.mainMedia.image` is a **string**, not an object (the installed type is `image?: string`, so `.image.url` fails `tsc`) — but its value is a Wix media URI like `wix:image://v1/…`, **not** an absolute URL (`.startsWith("https://")` is `false`). Putting it straight into `<img src>` ships broken images. Resolve it first: `import { media } from "@wix/sdk"`, then `media.getImageUrl(service.media.mainMedia.image).url` → `https://static.wixstatic.com/media/…`. Guard for services with no image.
+- **Mount slots + form + book in a `client:only="react"` island** (Astro) — availability is timezone/session-specific. SSR only the read pages (catalog/detail) for SEO.
+
+### SEO on item pages (Astro, Wix-managed)
+
+A **service 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 a service page use:
+- **`wixMetadata`** from `WIX_APPS.bookings.servicePageMetadata` — referenced **directly** in the export (module scope). Route param `slug` → `identifiers.slug`.
+- **`itemType`**: `seoTags.ItemType.BOOKINGS_SERVICE`.
+
+Run `loadSEOTagsServiceConfig` in the same `Promise.all` as the service read, with `.catch(() => null)`, so a SEO hiccup falls back to the layout's default title instead of failing the page. Optional: render a `Service` schema.org JSON-LD `<script>` from the fetched service (see the guide's structured-data step).
+
+### Out of scope
+Waitlist, on-site manage/cancel, payment/deposit breakdown, multi-service packages, and COURSE bookings. Waitlist and manage/cancel have **no headless source of truth** — don't invent them on the anonymous-token layer; post-booking self-service is the Wix-hosted flow / member area.
+
+---
+
+## Conclusion
+A correct Services V2 booking frontend:
+- imports **`services` / `availabilityTimeSlots` / `eventTimeSlots` / `bookings`** from `@wix/bookings`, plus **Cart V2** (`@wix/auto_sdk_ecom_cart-v-2`), `@wix/redirects`, and `@wix/forms` — and never the nonexistent `availability` namespace or `confirmBooking`;
+- uses **`service._id`** (never `service.id`) and reads the **flat V2 fields** (`mainSlug.name`, `payment.fixed.price.value`, `schedule.availabilityConstraints.sessionDurations[0]`);
+- fetches availability per type (**`availabilityTimeSlots`** for APPOINTMENT, **`eventTimeSlots`** for CLASS) with **local date strings**, reads slot fields at the **top level**, and scopes to one location to avoid duplicate rows;
+- renders the booking form **schema-driven via `getFormSummary`** (the flat `formSummary.fields[].target`, never `getForm`/`formFields`), **falls back to `first_name`/`last_name`/`email` whenever the parsed list is empty** (so the form never renders blank or hangs), keys values by `target`, skips complex field types, and passes that object as **`formSubmission`** (not `contactDetails`);
+- runs **createBooking → createCart → calculateCart → checkout-or-place**, deriving `selectedPaymentOption` from the service (free/offline → `OFFLINE`, else `ONLINE` — the wrong choice rejects the cart with `INSUFFICIENT_INVENTORY`) and using the **ANY_RESOURCE** fallback when no staff is chosen.