@wix/agent-skills 1.13.0 → 1.15.0

package/skills/wix-vibe-headless/references/bookings/wix-bookings-checkout.js

@@ -0,0 +1,147 @@
+import { wixApiRequest } from "./wix-client.js";
+
+// Data model reference: see INSTRUCTIONS.md
+// Service and TimeSlot shapes: see wix-bookings-services.js
+
+// Wix Bookings app id — required inside catalogReference for the eCommerce checkout.
+const BOOKINGS_APP_ID = "13d21c63-b5ec-5912-8397-c3a5ddb27a97";
+
+/**
+ * Wix Bookings Booking (Bookings Writer V2) — what createBooking returns.
+ * Full model: https://dev.wix.com/docs/api-reference/business-solutions/bookings/bookings/bookings-writer-v2/create-booking.md
+ *
+ *   id {string}, status "CREATED" (not yet on calendar; confirmed after hosted checkout),
+ *   paymentStatus {string} — "NOT_PAID" until checkout completes,
+ *   bookedEntity.slot {object} — { serviceId, scheduleId, startDate, endDate, timezone, location },
+ *   contactDetails {object}, totalParticipants {number}
+ */
+
+/** Visitor's local IANA time zone — used as default for the booking timezone. */
+function defaultTimeZone() {
+  try {
+    return Intl.DateTimeFormat().resolvedOptions().timeZone || "UTC";
+  } catch {
+    return "UTC";
+  }
+}
+
+/**
+ * Create a booking for a slot. The booking starts as status "CREATED" and is NOT yet on the
+ * calendar — it is confirmed automatically after the buyer completes the hosted checkout (call
+ * checkoutBooking next). selectedPaymentOption is "ONLINE".
+ *
+ * Works for **both** service types — it reads the discriminator off the slot:
+ *  - APPOINTMENT slot (from `listAvailableSlots`/`getAvailableSlot`) carries `scheduleId`.
+ *  - CLASS/COURSE slot (from `listEventTimeSlots`) carries `eventInfo.eventId` and no `scheduleId`;
+ *    Wix derives the session's date/resource/location from that event.
+ * For appointments, call `getAvailableSlot` first to re-validate and get staff (`availableResources`).
+ * Throws on an unbookable slot or missing booking id.
+ * https://dev.wix.com/docs/api-reference/business-solutions/bookings/bookings/bookings-writer-v2/create-booking.md
+ *
+ * @param {object} slot                       A TimeSlot from listAvailableSlots/getAvailableSlot/listEventTimeSlots.
+ * @param {{ firstName?: string, lastName?: string, email: string, phone?: string }} contactDetails
+ * @param {{ totalParticipants?: number, timeZone?: string, title?: string }} [options]
+ * @returns {Promise<object>} The created booking (status "CREATED").
+ */
+export async function createBooking(slot, contactDetails, { totalParticipants = 1, timeZone, title } = {}) {
+  if (!slot || slot.bookable === false) {
+    throw new Error("Cannot book: the selected slot is not bookable. Re-check availability and pick another time.");
+  }
+  // A slot is bound either by scheduleId (appointment) or by eventInfo.eventId (class/course).
+  const eventId = slot.eventInfo?.eventId;
+  if (!slot.serviceId || (!slot.scheduleId && !eventId) || !slot.localStartDate || !slot.localEndDate) {
+    throw new Error("Cannot book: slot is missing serviceId, localStartDate/localEndDate, and a scheduleId (appointment) or eventInfo.eventId (class/course).");
+  }
+  if (!contactDetails?.email) {
+    throw new Error("Cannot book: contactDetails.email is required.");
+  }
+
+  const resource = slot.availableResources?.[0]?.resources?.[0];
+
+  // The availability slot's location uses the SERVICE location enum (e.g. "BUSINESS"), but the
+  // createBooking endpoint expects the BOOKING location enum [UNDEFINED, OWNER_BUSINESS,
+  // OWNER_CUSTOM, CUSTOM]. Passing slot.location straight through 400s
+  // ("slot.location.locationType enum must be in [...]"). Remap before sending.
+  const bookingLocation = (() => {
+    const loc = slot.location;
+    if (!loc) return null;
+    const valid = ["UNDEFINED", "OWNER_BUSINESS", "OWNER_CUSTOM", "CUSTOM"];
+    const map = { BUSINESS: "OWNER_BUSINESS", CUSTOM: "CUSTOM", CUSTOMER: "CUSTOM" };
+    const locationType = map[loc.locationType] || (valid.includes(loc.locationType) ? loc.locationType : "OWNER_BUSINESS");
+    return { ...loc, locationType };
+  })();
+
+  const bookedSlot = {
+    serviceId: slot.serviceId,
+    // Appointment → scheduleId; class/course → eventId. Send exactly one.
+    ...(eventId ? { eventId } : { scheduleId: slot.scheduleId }),
+    startDate: slot.localStartDate,
+    endDate: slot.localEndDate,
+    timezone: timeZone || defaultTimeZone(),
+    ...(bookingLocation ? { location: bookingLocation } : {}),
+    ...(resource ? { resource: { id: resource.id, name: resource.name } } : {}),
+  };
+
+  const res = await wixApiRequest("/bookings/v2/bookings", {
+    method: "POST",
+    body: {
+      booking: {
+        bookedEntity: { slot: bookedSlot, title: title || undefined, tags: ["INDIVIDUAL"] },
+        contactDetails,
+        additionalFields: [],
+        totalParticipants,
+        selectedPaymentOption: "ONLINE",
+      },
+      participantNotification: { notifyParticipants: true },
+    },
+  });
+  const booking = res?.booking;
+  if (!booking?.id) throw new Error("Failed to create the booking (no booking id returned).");
+  return booking;
+}
+
+/**
+ * Create an eCommerce checkout for a created booking and return the hosted checkout URL.
+ * Redirect the buyer there (window.location.href = ...). On return, the booking is confirmed.
+ * Throws if no redirect URL is produced.
+ * https://dev.wix.com/docs/rest/business-solutions/e-commerce/checkout/create-checkout.md
+ * @param {string} bookingId  booking.id from createBooking().
+ * @returns {Promise<string>} The hosted-checkout URL to redirect to.
+ */
+export async function checkoutBooking(bookingId) {
+  if (!bookingId) throw new Error("checkoutBooking requires a bookingId.");
+
+  const checkoutRes = await wixApiRequest("/ecom/v1/checkouts", {
+    method: "POST",
+    body: {
+      channelType: "WEB",
+      lineItems: [
+        { quantity: 1, catalogReference: { appId: BOOKINGS_APP_ID, catalogItemId: bookingId } },
+      ],
+    },
+  });
+  const checkoutId = checkoutRes?.checkout?.id;
+  if (!checkoutId) throw new Error("Failed to create a checkout for the booking.");
+
+  const redirect = await wixApiRequest("/headless/v1/redirect-session", {
+    method: "POST",
+    body: { ecomCheckout: { checkoutId }, callbacks: { postFlowUrl: window.location.href } },
+  });
+  const url = redirect?.redirectSession?.fullUrl;
+  if (!url) throw new Error("Failed to create the checkout redirect session.");
+  return url;
+}
+
+/**
+ * Convenience: create the booking and return the hosted-checkout URL in one call.
+ * Equivalent to createBooking() then checkoutBooking(booking.id). Throws loudly on any failure.
+ * @param {object} slot
+ * @param {{ firstName?: string, lastName?: string, email: string, phone?: string }} contactDetails
+ * @param {{ totalParticipants?: number, timeZone?: string, title?: string }} [options]
+ * @returns {Promise<{ booking: object, checkoutUrl: string }>}
+ */
+export async function bookAndCheckout(slot, contactDetails, options = {}) {
+  const booking = await createBooking(slot, contactDetails, options);
+  const checkoutUrl = await checkoutBooking(booking.id);
+  return { booking, checkoutUrl };
+}

package/skills/wix-vibe-headless/references/bookings/wix-bookings-services.js

@@ -0,0 +1,215 @@
+import { wixApiRequest } from "./wix-client.js";
+
+// Data model reference: see INSTRUCTIONS.md
+
+/**
+ * Wix Bookings Service (Services V2) — key fields for the services list and booking UI.
+ * This skill ships the APPOINTMENT flow; CLASS/COURSE are "Beyond the snippets".
+ * Full model: https://dev.wix.com/docs/api-reference/business-solutions/bookings/services/services-v2/query-services.md
+ *
+ *   id {string}, type "APPOINTMENT"|"CLASS"|"COURSE", name {string}, tagLine {string},
+ *   description {string}, hidden {boolean},
+ *   media.items {array} — [{ image: { id, url, width, height, altText } }]
+ *     (url may be a bare Wix media handle — pass through mediaUrl() before rendering),
+ *   payment.rateType "FIXED"|"CUSTOM"|"VARIED"|"NO_FEE"|"SUBSCRIPTION",
+ *   payment.fixed.price { value, currency, formattedValue },
+ *   payment.options { online, inPerson, deposit, pricingPlan },
+ *   schedule.id {string}, onlineBooking.enabled {boolean},
+ *   category { id, name }, staffMemberIds {string[]}, locations {array},
+ *   bookingPolicy.participantsPolicy { enabled {boolean}, maxParticipantsPerBooking {number} }
+ *     — the MOST participants a single booking may reserve. Cap the participant selector at this
+ *     value (for a CLASS, also bound by the slot's remainingCapacity). It is commonly 1, in which
+ *     case there is no participant choice at all — book exactly 1. Sending totalParticipants above
+ *     this makes createBooking fail.
+ *
+ * TimeSlot (Time Slots V2, appointments):
+ *   serviceId {string}, localStartDate {string}, localEndDate {string} — "YYYY-MM-DDThh:mm:ss" (no zone),
+ *   bookable {boolean}, scheduleId {string},
+ *   location { id, name, formattedAddress, locationType "BUSINESS"|"CUSTOM"|"CUSTOMER" },
+ *   totalCapacity {number}, remainingCapacity {number},
+ *   availableResources {array} — staff (populated by getAvailableSlot, not listAvailableSlots)
+ * Full model: https://dev.wix.com/docs/api-reference/business-solutions/bookings/time-slots/time-slots-v2/list-availability-time-slots.md
+ */
+
+/** The visitor's local IANA time zone — used as the default for availability queries. */
+function defaultTimeZone() {
+  try {
+    return Intl.DateTimeFormat().resolvedOptions().timeZone || "UTC";
+  } catch {
+    return "UTC";
+  }
+}
+
+/**
+ * Resolve a service image to an absolute URL. Wix media fields are sometimes a bare
+ * handle ("abc.jpg") rather than a full URL; this prefixes the Wix static host.
+ * @param {{ url?: string, id?: string }|string} image
+ * @returns {string|null}
+ */
+export function mediaUrl(image) {
+  const raw = typeof image === "string" ? image : image?.url || image?.id;
+  if (!raw) return null;
+  if (raw.startsWith("http")) return raw;
+  if (raw.startsWith("wix:image://")) {
+    const stripped = raw.slice("wix:image://".length).replace(/^v1\//, "");
+    return `https://static.wixstatic.com/media/${stripped.split("#")[0].split("/")[0]}`;
+  }
+  return `https://static.wixstatic.com/media/${raw}`;
+}
+
+/**
+ * Query bookable services (one page). Returns only services visible to visitors (hidden:false).
+ * https://dev.wix.com/docs/api-reference/business-solutions/bookings/services/services-v2/query-services.md
+ * @param {{ limit?: number, offset?: number }} [options]
+ * @returns {Promise<{ services: object[], total: number, nextOffset: number|null }>}
+ */
+export async function queryServices({ limit = 100, offset = 0 } = {}) {
+  const res = await wixApiRequest("/bookings/v2/services/query", {
+    method: "POST",
+    body: {
+      query: {
+        filter: { hidden: false },
+        paging: { limit, offset },
+      },
+    },
+  });
+  const services = res?.services ?? [];
+  const total = res?.pagingMetadata?.total ?? services.length;
+  const loaded = offset + services.length;
+  return { services, total, nextOffset: loaded < total ? loaded : null };
+}
+
+/**
+ * Fetch a single service by its GUID. Returns null if not found.
+ * @param {string} serviceId
+ * @returns {Promise<object|null>}
+ */
+export async function getService(serviceId) {
+  const res = await wixApiRequest("/bookings/v2/services/query", {
+    method: "POST",
+    body: { query: { filter: { id: serviceId }, paging: { limit: 1 } } },
+  });
+  return res?.services?.[0] ?? null;
+}
+
+/**
+ * Total number of visitor-visible services. Used for empty-state logic.
+ * @returns {Promise<number>}
+ */
+export async function countServices() {
+  const res = await wixApiRequest("/bookings/v2/services/query", {
+    method: "POST",
+    body: { query: { filter: { hidden: false }, paging: { limit: 1 } } },
+  });
+  return res?.pagingMetadata?.total ?? (res?.services?.length ?? 0);
+}
+
+/**
+ * List bookable time slots for an **APPOINTMENT** service within a local date range (availability
+ * comes from staff working hours). For **CLASS / COURSE** services (booked against scheduled
+ * sessions) use `listEventTimeSlots` — this endpoint returns an empty list for them, silently.
+ * If you render a mixed catalog, route by `service.type` via `listSlotsForService`.
+ * Dates are LOCAL ("YYYY-MM-DDThh:mm:ss") in timeZone.
+ * https://dev.wix.com/docs/api-reference/business-solutions/bookings/time-slots/time-slots-v2/list-availability-time-slots.md
+ * @param {string} serviceId
+ * @param {{ fromLocalDate: string, toLocalDate: string, timeZone?: string, limit?: number, cursor?: string }} options
+ * @returns {Promise<{ slots: object[], nextCursor: string|null }>}
+ */
+export async function listAvailableSlots(serviceId, { fromLocalDate, toLocalDate, timeZone, limit = 1000, cursor } = {}) {
+  if (!cursor && (!fromLocalDate || !toLocalDate)) {
+    throw new Error("listAvailableSlots requires fromLocalDate and toLocalDate (local 'YYYY-MM-DDThh:mm:ss').");
+  }
+  const body = cursor
+    ? { cursorPaging: { limit, cursor } }
+    : {
+        serviceId,
+        bookable: true,
+        fromLocalDate,
+        toLocalDate,
+        timeZone: timeZone || defaultTimeZone(),
+        cursorPaging: { limit },
+      };
+  const res = await wixApiRequest("/_api/service-availability/v2/time-slots", { method: "POST", body });
+  return {
+    slots: res?.timeSlots ?? [],
+    nextCursor: res?.cursorPagingMetadata?.cursors?.next ?? null,
+  };
+}
+
+/**
+ * Re-validate a specific appointment slot right before booking, and fetch its available
+ * resources (staff). Always re-check before createBooking — slots can be taken between listing
+ * and booking. Returns the slot or null if it's gone.
+ * https://dev.wix.com/docs/api-reference/business-solutions/bookings/time-slots/time-slots-v2/get-availability-time-slot.md
+ * @param {string} serviceId
+ * @param {{ localStartDate: string, localEndDate: string, timeZone?: string, location?: object }} options
+ * @returns {Promise<object|null>}
+ */
+export async function getAvailableSlot(serviceId, { localStartDate, localEndDate, timeZone, location } = {}) {
+  if (!localStartDate || !localEndDate) {
+    throw new Error("getAvailableSlot requires localStartDate and localEndDate.");
+  }
+  const res = await wixApiRequest("/_api/service-availability/v2/time-slots/get", {
+    method: "POST",
+    body: {
+      serviceId,
+      localStartDate,
+      localEndDate,
+      timeZone: timeZone || defaultTimeZone(),
+      ...(location ? { location } : {}),
+    },
+  });
+  return res?.timeSlot ?? null;
+}
+
+/**
+ * List bookable session slots for **CLASS / COURSE** services within a local date range. These
+ * services are booked against scheduled sessions (calendar events), not staff working hours, so
+ * they use a different endpoint than appointments. Each returned slot carries `eventInfo.eventId`
+ * (the session) and has **no** `scheduleId` — `createBooking` reads that `eventId`.
+ * Dates are LOCAL ("YYYY-MM-DDThh:mm:ss") in timeZone.
+ * https://dev.wix.com/docs/api-reference/business-solutions/bookings/time-slots/time-slots-v2/list-event-time-slots.md
+ * @param {string|string[]} serviceIds  One service id or several (the endpoint takes a plural list).
+ * @param {{ fromLocalDate: string, toLocalDate: string, timeZone?: string, limit?: number, cursor?: string }} options
+ * @returns {Promise<{ slots: object[], nextCursor: string|null }>}
+ */
+export async function listEventTimeSlots(serviceIds, { fromLocalDate, toLocalDate, timeZone, limit = 1000, cursor } = {}) {
+  if (!cursor && (!fromLocalDate || !toLocalDate)) {
+    throw new Error("listEventTimeSlots requires fromLocalDate and toLocalDate (local 'YYYY-MM-DDThh:mm:ss').");
+  }
+  const ids = Array.isArray(serviceIds) ? serviceIds : [serviceIds];
+  const body = cursor
+    ? { cursorPaging: { limit, cursor } }
+    : {
+        serviceIds: ids,
+        bookable: true,
+        fromLocalDate,
+        toLocalDate,
+        timeZone: timeZone || defaultTimeZone(),
+        cursorPaging: { limit },
+      };
+  const res = await wixApiRequest("/_api/service-availability/v2/time-slots/event", { method: "POST", body });
+  return {
+    slots: res?.timeSlots ?? [],
+    nextCursor: res?.cursorPagingMetadata?.cursors?.next ?? null,
+  };
+}
+
+/**
+ * Type-agnostic convenience: list bookable slots for a service, routing to the right endpoint by
+ * `service.type` — APPOINTMENT → `listAvailableSlots`, CLASS/COURSE → `listEventTimeSlots`. The
+ * returned slots are shaped the same either way (`localStartDate`/`localEndDate`/`location`/
+ * `availableResources`), and each is bookable via `createBooking`.
+ * NOTE: a **COURSE** is enrolled as a whole (not per session), so it typically returns **no** slots
+ * here — the per-slot booking flow applies to APPOINTMENT and CLASS.
+ * @param {{ _id?: string, id?: string, type?: string }} service  A service from queryServices.
+ * @param {{ fromLocalDate: string, toLocalDate: string, timeZone?: string, limit?: number, cursor?: string }} options
+ * @returns {Promise<{ slots: object[], nextCursor: string|null }>}
+ */
+export async function listSlotsForService(service, options = {}) {
+  const serviceId = service?._id || service?.id;
+  if (!serviceId) throw new Error("listSlotsForService requires a service with an id.");
+  return service?.type === "CLASS" || service?.type === "COURSE"
+    ? listEventTimeSlots(serviceId, options)
+    : listAvailableSlots(serviceId, options);
+}

package/skills/wix-vibe-headless/references/cms/INSTRUCTIONS.md

@@ -0,0 +1,154 @@
+
+# Wix CMS Skill
+
+> **Source files (in this skill):** the shared transport `references/shared/wix-client.js` and this vertical's `references/cms/wix-cms.js`. Copy **both** into your app's `src/rest/` side by side — the helper does `import { wixApiRequest } from "./wix-client.js"`, so they must land in the same folder.
+
+Builds a real, client-only Wix CMS-backed app. The browser talks to Wix Data directly
+over a public `WIX_CLIENT_ID` to read and write items in the site's data collections.
+Never mock data; never hand-build API URLs — always go through the helpers, which call
+the official Wix Data endpoints.
+
+## When to use
+- User wants to display Wix CMS / Content Manager content (a collection of posts,
+  tutorials, recipes, team members, listings, FAQs, etc.) on a site.
+- Replacing placeholder/mock content with live Wix Data items.
+- Adding list pages, detail pages, category/tag filtering, or free-text search over an
+  existing Wix data collection.
+- Wiring a public form (contact, RSVP, review, signup) that writes a row into a collection.
+
+## Prerequisites
+1. A Wix site with **a data collection already created and populated** (this skill does
+   NOT provision collections — it reads/writes existing ones). The merchant creates
+   collections, fields, and items in the Wix dashboard (CMS / Content Manager).
+2. The site's public headless **`WIX_CLIENT_ID`**, provided in the handoff prompt (the
+   Wix Business Manager surfaces a copyable prompt with the id filled in — see
+   the router `SKILL.md`). Paste it into `src/rest/wix-client.js` in place of the placeholder. It is
+   a buyer-facing credential (it only mints anonymous visitor tokens), **not** a secret,
+   so hardcoding/committing it is fine.
+3. **Collection permissions** must match what you're doing. This skill runs as an
+   anonymous visitor, so a call only works if the collection grants that action to
+   "Anyone": Read for listing content, Insert for a public form. Update/Delete are
+   almost always admin- or author-only and will fail for a visitor. The site owner sets
+   these in the Wix dashboard (CMS → collection → Permissions). This is a **separate Wix
+   setup step the user completes** — out of this skill's scope. If a read/insert fails
+   with a permission error (HTTP 403) before that's set, that's expected; flag it and
+   continue.
+4. You need each collection's **collection ID** (its name, e.g. `Tutorials`) and its
+   **field keys** (e.g. `title`, `publishDate`). Read field keys off a fetched item, or
+   from the collection schema (see "Beyond the snippets").
+
+## The API (copy as-is; do not re-derive it)
+This skill ships only the REST layer — no UI components. Build the UI however the project
+wants; wire it to these two snippets. Copy them into the app (e.g. `src/api/`) and only
+adjust import paths:
+- `src/rest/wix-client.js` — visitor-token mint/refresh + transport. Set `WIX_CLIENT_ID`
+  to the id from the prompt (replace the `<YOUR-CLIENT-ID>` placeholder). The visitor
+  refresh token is persisted to localStorage; do not re-mint anonymously per load.
+- `src/rest/wix-cms.js` — exports:
+  - **Read:** `queryDataItems`, `getDataItem`, `getDataItemBy`, `countDataItems`
+  - **Write:** `insertDataItem`, `updateDataItem`, `removeDataItem`
+
+The Data Item shape, the per-collection **permissions model**, and the **filter/sort
+syntax** are documented as JSDoc comments at the top of `wix-cms.js`. Read them before
+building the UI — read helpers return the item's flat `data` payload (which always
+includes `_id`), and writes are bound by collection permissions.
+
+## How to wire it (UI is the project's choice)
+- **Content list** — `queryDataItems(collectionId, { filter?, sort?, limit?, cursor? })`
+  for the listing; render fields directly off each returned item (`item.title`, etc.).
+  Pass the returned `nextCursor` back as `cursor` to load the next page. Define
+  `filter`/`sort` on the first request only — cursor follow-ups reuse the original query.
+- **Detail page** — route by the item's `_id` and call `getDataItem(collectionId, itemId)`;
+  returns null on miss → show a not-found state, never invent an item. For human-readable
+  URLs, add a slug-like field to the collection and route via
+  `getDataItemBy(collectionId, "slug", slugFromUrl)`.
+- **Filter & search** — pass a `filter` to `queryDataItems` using the operators documented
+  in `wix-cms.js` (`$eq`, `$in`, `$gte`, `$startsWith`, `$hasSome`, `$and`/`$or`, …). For a
+  simple text search, `{ title: { $startsWith: term } }`; for richer free-text/fuzzy search
+  across fields, see "Beyond the snippets" (Search Data Items).
+- **Public form** — on submit, `insertDataItem(collectionId, { name, email, message })`
+  (field keys must match the collection). Requires the collection's Insert permission to be
+  "Anyone". Show success/failure from the resolved/thrown result; never fake a success.
+- **Edit / delete (admin/author flows)** — `updateDataItem(collectionId, itemId, data)`
+  (⚠ full replace — fetch + merge first to preserve other fields) and
+  `removeDataItem(collectionId, itemId)`. These need Update/Delete granted to the caller,
+  which visitors normally don't have — expect them to fail unless the collection is opened up.
+- **Empty state** — if `countDataItems(collectionId)` is 0, show an empty state telling
+  the user to add items in their Wix dashboard. Never invent items.
+
+## Hard rules (do not violate)
+- ✅ Read/write ONLY through the helpers in `wix-cms.js` (which call the official Wix Data
+  `/wix-data/v2/items` endpoints).
+- ❌ Never hand-build Wix Data URLs or invent endpoint paths.
+- ❌ Never mock data — render live Wix Data items or the empty state.
+- ❌ Never invent fields, reviews, ratings, or content not present in the collection.
+- ✅ Set `WIX_CLIENT_ID` from the prompt's value (public client id — safe to hardcode).
+- ✅ Use the item's `_id` as the route key and as `itemId` for get/update/remove.
+- ✅ `updateDataItem` REPLACES the whole item — fetch with `getDataItem`, merge your
+  changes, then pass the full object, or use Patch Data Item (see below) for partial edits.
+- ✅ Treat permission errors (HTTP 403) as a configuration step, not a code bug: tell the
+  user which permission to grant in the dashboard. Writes throw on failure — don't swallow
+  the error and show a fake success.
+
+## Beyond the snippets
+The snippets cover the common CMS paths (list, detail, filter, count, insert, update,
+remove). If you hit a use case they don't cover, make the call yourself with
+`wixApiRequest` — but look up the exact endpoint, HTTP method, and request body in the
+**official Wix API reference** first; never guess:
+- CMS / Data Items API reference: https://dev.wix.com/docs/api-reference/business-solutions/cms/data-items.md
+- Data Items sample flows: https://dev.wix.com/docs/api-reference/business-solutions/cms/data-items/sample-flows.md
+- **Partial update** (change some fields, keep the rest): Patch Data Item —
+  https://dev.wix.com/docs/api-reference/business-solutions/cms/data-items/patch-data-item.md
+- **Upsert** (insert or update by id): Save Data Item —
+  https://dev.wix.com/docs/api-reference/business-solutions/cms/data-items/save-data-item.md
+- **Bulk** insert/update/save/remove (many items in one call):
+  https://dev.wix.com/docs/api-reference/business-solutions/cms/data-items.md
+- **Free-text / fuzzy search** across fields: Search Data Items —
+  https://dev.wix.com/docs/api-reference/business-solutions/cms/data-items/search-data-items.md
+- **Aggregations** (counts/averages grouped by a field): Aggregate Data Items —
+  https://dev.wix.com/docs/api-reference/business-solutions/cms/data-items/aggregate-data-items.md
+- **Distinct values** (e.g. all categories for a filter menu): Query Distinct Values —
+  https://dev.wix.com/docs/api-reference/business-solutions/cms/data-items/query-distinct-values.md
+- **Referenced items** (expand a reference field beyond the inline limit): Query Referenced
+  Data Items — https://dev.wix.com/docs/api-reference/business-solutions/cms/data-items/query-referenced-data-items.md
+- **Collection schema / field keys & types**: Get Data Collection —
+  https://dev.wix.com/docs/api-reference/business-solutions/cms/collection-management/data-collections/get-data-collection.md
+- **Member-gated & user-generated content** → the **members** vertical
+  (`references/members/INSTRUCTIONS.md`). A collection whose permissions are `read: Anyone`,
+  `insert: Site Member`, `update/remove: Site Member Author` gives you the classic pattern: anyone
+  reads, only logged-in members write, and each member edits only their own. Sign the member in with
+  custom login (on your own UI), then `insertDataItem` runs as the member and Wix stamps the item's
+  `_owner` automatically — so a **"my items"** view is just
+  `queryDataItems(collectionId, { filter: { _owner: <memberId> } })`, and author-only
+  `updateDataItem`/`removeDataItem` are enforced server-side. (This skill never provisions the
+  collection — the owner creates it with those permissions in the dashboard.)
+  **Prefer Wix for member-generated content, and keep one feature's data and identity together.**
+  Content that belongs to the Wix site (likes, reviews, submissions) is best kept in a Wix collection
+  via these helpers, keyed on the Wix member's server-stamped `_owner`. What breaks is a *split*
+  feature — the row stored in one place while the member is identified from the Wix session elsewhere
+  (or filtered by some other `created_by`/user id): the two ids won't match, so ownership filters
+  miss. Keep them on one side; for Wix-backed rows that's `_owner`.
+
+Keep the snippets as the default for everything they already do; reach for the API
+reference only for the gap.
+
+## Point the user to their dashboard
+In some cases, users need to access the Wix dashboard in order to edit the CMS content for their site. To facilitate this, provide the user with deep links directly to the relevant dashboard pages. For CMS data those pages are:
+- **Collections & items** — `https://manage.wix.com/dashboard/{metaSiteId}/wix-cms` (`Dashboard → CMS`) → **Create Collection**, then open a collection to add items.
+- **Permissions** — no separate deep link; in the same CMS area, open the collection → **More Actions → Permissions & Privacy**. For the headless app to work anonymously, set **Show content** to *Everyone* (visitor reads) and, for a public form, **Collect content** to *Everyone* (visitor inserts). Update/Delete stay admin-only.
+
+Substitute the site's `metaSiteId` to complete the links (you have it from the handoff / `ListWixSites`). Include the in-dashboard navigation as a fallback.
+
+## Verification checklist (before declaring done)
+- [ ] `WIX_CLIENT_ID` set to the prompt's value (not the `<YOUR-CLIENT-ID>` placeholder)
+- [ ] Visitor token persists across reload (same anonymous visitor, no re-mint per load)
+- [ ] `queryDataItems` returns live items; pagination via `nextCursor` loads more
+- [ ] Detail page uses the item's `_id` (or a slug field via `getDataItemBy`) and shows a
+      not-found state on miss — no invented item
+- [ ] Filter/sort produce the expected subset (operators match the field types)
+- [ ] Public form `insertDataItem` succeeds only when Insert is "Anyone"; on a 403 the user
+      is told to grant the permission — no fake success
+- [ ] Update is treated as a full replace (fetch + merge), so no fields are silently dropped
+- [ ] Empty state shown when `countDataItems` is 0
+- [ ] No mock data anywhere; no hand-built Wix Data URLs
+- [ ] Told the user at least once that they can continue setting up their content in the dashboard and provided deep links.