@wix/agent-skills 1.26.0 → 1.28.0

package/skills/wix-headless-templates/cms/project/src/wix/cms/collection-store.ts

@@ -0,0 +1,220 @@
+// One collection as list state, framework-free — the logic behind useCollection, usable from React
+// (useCollection wraps it with useSyncExternalStore), from a static page or Vue/Svelte (subscribe
+// and render), or as the specification for a port. Same shape as the storefront stores: state,
+// actions, subscribe/getState, emit after every change.
+//
+// The query (collection, filters, sort, page size, includes) is identified BY VALUE; a changed
+// query refetches from the first page, a late response from a superseded query is dropped.
+// Stale-while-refetch: once items are on screen they STAY there while a new query, page, or
+// refresh runs — `fetching` flips instead of `items` going null; only the very first load shows
+// skeletons (`loading`). Two ways to page, both at the source: loadMore() appends the next page
+// (skip = items shown so far); goToPage(n) replaces the list with page n (0-based; `hasPrev`,
+// `page`, and — with `withTotal` — `total`/`pageCount` drive a numbered pager). refresh() re-reads
+// what is on screen after a write.
+//
+// SSR-friendly: seed with `initialItems` from the SAME query and no client fetch happens for the
+// first page. One store per mounted listing (a page can hold two collections): createCollectionStore(),
+// not a singleton.
+import { queryItems } from "./items";
+import type { CmsFilter, CmsItem, CmsSort } from "./types";
+
+export interface CollectionQuery {
+  collectionId?: string;
+  filters?: CmsFilter[];
+  sort?: CmsSort[];
+  /** Page size (default 20). */
+  limit?: number;
+  /** Reference field keys to inline as full items. */
+  include?: string[];
+}
+
+export interface CollectionStoreOptions extends CollectionQuery {
+  collectionId: string;
+  /** Server-fetched first page — must come from the SAME query (filters/sort/limit/include). */
+  initialItems?: CmsItem[];
+  /** The server fetch's hasNext. Omitted → inferred (a full first page ⇒ assume more). */
+  initialHasNext?: boolean;
+  /** true → every query asks Wix for the total; `total` and `pageCount` fill in (a slower query). */
+  withTotal?: boolean;
+  /** The server fetch's total (it queried withTotal). */
+  initialTotal?: number | null;
+}
+
+/** Everything a listing surface renders from. Read it with getState() or through a subscription. */
+export interface CollectionState {
+  /** null while the FIRST load is in flight — render skeletons, not an empty state. Never null again after. */
+  items: CmsItem[] | null;
+  hasNext: boolean;
+  /** A page before the one shown exists (page > 0). */
+  hasPrev: boolean;
+  /** 0-based index of the first page on screen (loadMore appends after it). */
+  page: number;
+  /** Matching items across the collection — only with `withTotal`, else null. */
+  total: number | null;
+  /** ceil(total / limit) — only with `withTotal`, else null. */
+  pageCount: number | null;
+  /** True while items is null and a load is running (the same condition, named). */
+  loading: boolean;
+  /** True while a new query, page, or refresh runs BEHIND the items on screen — dim them, don't drop them. */
+  fetching: boolean;
+  loadingMore: boolean;
+  error: string | null;
+}
+
+export interface CollectionStore {
+  getState(): CollectionState;
+  subscribe(listener: () => void): () => void;
+  /** Run the first query unless the seed already answered it. Call once when mounted (a browser). */
+  start(): void;
+  /** Stop reacting; drop late responses. */
+  stop(): void;
+  /** Change the query by value — same values keep the page, a change refetches page 0 (items stay on screen, `fetching`). */
+  setQuery(query: CollectionQuery): void;
+  /** Append the next page (skip = items shown so far). No-op while loading or when there is none. */
+  loadMore(): Promise<void>;
+  /** Replace the list with page n (0-based; skip = n × limit). No-op for a negative n or the page already shown. */
+  goToPage(n: number): void;
+  /** Re-read what is on screen (same query, same window) — after insertItem / patchItemFields / linkItems. */
+  refresh(): void;
+  /** Re-run the current query from page 0 after an error (skeletons again). */
+  retry(): void;
+}
+
+const queryKey = (q: Required<Pick<CollectionQuery, "collectionId" | "limit">> & CollectionQuery): string =>
+  // Dates in filters serialize to ISO, so this is stable.
+  JSON.stringify([q.collectionId, q.filters ?? null, q.sort ?? null, q.limit, q.include ?? null]);
+
+export function createCollectionStore(options: CollectionStoreOptions): CollectionStore {
+  let collectionId = options.collectionId;
+  let filters = options.filters;
+  let sort = options.sort;
+  let limit = options.limit ?? 20;
+  let include = options.include;
+  const withTotal = options.withTotal ?? false;
+  const key = () => queryKey({ collectionId, filters, sort, limit, include });
+
+  let items: CmsItem[] | null = options.initialItems ?? null;
+  let hasNext = options.initialHasNext ?? (options.initialItems ? options.initialItems.length >= limit : false);
+  let page = 0;
+  let total: number | null = withTotal ? (options.initialTotal ?? null) : null;
+  let loadingMore = false;
+  let fetching = false;
+  let error: string | null = null;
+  // The query the latest request targets (null = nothing requested yet).
+  let pageKey: string | null = options.initialItems ? key() : null;
+  let inflight = false;
+  let started = false;
+  let generation = 0;
+  const listeners = new Set<() => void>();
+  let snapshot: CollectionState | null = null;
+  const emit = () => { snapshot = null; for (const fn of listeners) fn(); };
+
+  function getState(): CollectionState {
+    if (snapshot) return snapshot;
+    snapshot = {
+      items,
+      hasNext,
+      hasPrev: page > 0,
+      page,
+      total,
+      pageCount: total === null ? null : Math.ceil(total / limit),
+      loading: items === null,
+      fetching,
+      loadingMore,
+      error,
+    };
+    return snapshot;
+  }
+
+  /**
+   * Load page `nextPage` of the current query (`window` items wide — the page size, or the whole
+   * shown list on a refresh). Items already on screen stay while it runs (fetching); the first load
+   * has none, so it shows skeletons (loading).
+   */
+  function load(nextPage: number, window = limit): void {
+    if (!started) return;
+    const k = key();
+    const id = ++generation;
+    pageKey = k; inflight = true;
+    error = null; loadingMore = false;
+    fetching = items !== null; // something is on screen → it stays, dimmed; nothing yet → skeletons (loading)
+    emit();
+    queryItems(collectionId, { filters, sort, limit: window, skip: nextPage * limit, include, withTotal })
+      .then((res) => {
+        if (generation !== id) return; // superseded — drop it
+        items = res.items; hasNext = res.hasNext; page = nextPage;
+        if (withTotal) total = res.total;
+        inflight = false; fetching = false;
+        emit();
+      })
+      .catch((e) => {
+        if (generation !== id) return;
+        // A first load that fails shows the error with an empty list; a refetch keeps what was on screen.
+        if (items === null) { items = []; hasNext = false; }
+        inflight = false; fetching = false;
+        error = e instanceof Error ? e.message : String(e);
+        emit();
+      });
+  }
+
+  return {
+    getState,
+    subscribe(fn) {
+      listeners.add(fn);
+      return () => listeners.delete(fn);
+    },
+    start() {
+      if (started) return;
+      started = true;
+      // The SSR seed answered this exact query — no fetch; a dropped first load reruns.
+      if (pageKey !== key() || (items === null && !inflight)) load(0);
+    },
+    stop() {
+      started = false;
+      generation++;
+      inflight = false;
+      fetching = false;
+    },
+    setQuery(q) {
+      if (q.collectionId !== undefined) collectionId = q.collectionId;
+      filters = q.filters; sort = q.sort; include = q.include;
+      if (q.limit !== undefined) limit = q.limit;
+      if (key() === pageKey) return; // same values — same page
+      if (started) load(0);
+    },
+    async loadMore() {
+      const current = items;
+      if (!current || loadingMore || inflight) return;
+      const id = generation;
+      loadingMore = true; emit();
+      try {
+        const res = await queryItems(collectionId, { filters, sort, limit, include, withTotal, skip: page * limit + current.length });
+        if (generation !== id) return;
+        items = [...(items ?? []), ...res.items];
+        hasNext = res.hasNext;
+        if (withTotal) total = res.total;
+      } catch (e) {
+        if (generation !== id) return;
+        error = e instanceof Error ? e.message : String(e);
+      } finally {
+        if (generation === id) { loadingMore = false; emit(); }
+      }
+    },
+    goToPage(n) {
+      if (n < 0) return;
+      // Already showing exactly that page of this query (appended pages collapse back to one).
+      const shown = n === page && key() === pageKey && items !== null && !inflight && items.length <= limit;
+      if (shown) return;
+      load(n);
+    },
+    refresh() {
+      // The whole shown window (several appended pages read as one), or the page size before any answer.
+      load(page, items && items.length > limit ? items.length : limit);
+    },
+    retry() {
+      pageKey = null;
+      items = null; page = 0;
+      load(0);
+    },
+  };
+}

package/skills/wix-headless-templates/cms/project/src/wix/cms/collections-core.ts

@@ -0,0 +1,41 @@
+// Collection schema rules and DTO mapping — transport-agnostic, imported by BOTH transports:
+// ./collections.ts (the SDK) and the REST twin in templates/cms/rest/collections.ts. A raw
+// DataCollection comes from the SDK (`_id`) or from REST (`id`, wrapped as `{ collection }` by the
+// caller); the mapper accepts both. Imports are type-only so a strip to JS emits no imports.
+import type { CmsCollectionSchema, CmsFieldSchema, CmsFieldType, CmsRole } from "./types";
+
+/** A raw DataCollection / Field as either transport returns it. */
+export type RawCollection = Record<string, any>;
+
+/** A verb's role as the API spells it; ADMIN (the most restrictive reading) when absent. */
+const role = (r: unknown): CmsRole => (typeof r === "string" && r ? r : "ADMIN");
+
+/** One raw field → DTO. The reference target sits under typeMetadata.reference | .multiReference. */
+export function toFieldSchema(f: RawCollection): CmsFieldSchema {
+  const ref = f.typeMetadata?.reference?.referencedCollectionId ?? f.typeMetadata?.multiReference?.referencedCollectionId;
+  return {
+    key: f.key ?? "",
+    displayName: f.displayName ?? f.key ?? "",
+    type: f.type ?? "TEXT",
+    systemField: f.systemField === true,
+    required: f.required === true,
+    ...(ref ? { referencedCollectionId: ref } : {}),
+  };
+}
+
+/** A raw DataCollection → the schema DTO (id, display name, fields, the four verbs' roles). */
+export function toCollectionSchema(raw: RawCollection): CmsCollectionSchema {
+  const id = raw._id ?? raw.id ?? "";
+  const p = raw.permissions ?? {};
+  return {
+    id,
+    displayName: raw.displayName ?? id,
+    fields: ((raw.fields ?? []) as RawCollection[]).map(toFieldSchema),
+    permissions: { read: role(p.read), insert: role(p.insert), update: role(p.update), remove: role(p.remove) },
+  };
+}
+
+/** The fields of one type — e.g. every MULTI_REFERENCE to link after an insert, every IMAGE to guard. */
+export function fieldsOfType(schema: CmsCollectionSchema, type: CmsFieldType): CmsFieldSchema[] {
+  return schema.fields.filter((f) => f.type === type);
+}

package/skills/wix-headless-templates/cms/project/src/wix/cms/collections.ts

@@ -0,0 +1,28 @@
+// Collection schema reads (@wix/data `collections`) over the SDK — field types, reference targets,
+// and permissions at runtime. The mapper lives in ./collections-core (shared with the REST twin in
+// templates/cms/rest/collections.ts); this file is the transport only.
+// SDK: collections.getDataCollection(dataCollectionId) → DataCollection
+//      (com.wixpress.cloud.data.api.collectionservice.DataCollectionService.GetDataCollection)
+import { collections as collectionsModule } from "@wix/data";
+import { wixModule } from "../sdk";
+import { toCollectionSchema, type RawCollection } from "./collections-core";
+import type { CmsCollectionSchema } from "./types";
+
+const collections = wixModule(collectionsModule);
+
+/**
+ * A collection's schema — the source of truth for a field's type when the seed plan isn't at
+ * hand (an imported site), and for which fields are MULTI_REFERENCEs to link after an insert.
+ * Null when the collection can't be read: it doesn't exist, or the caller may not read schemas
+ * (Wix's own headless CMS components read it client-side as the visitor and tolerate a null the
+ * same way — confirm once on a live site that a visitor token is allowed; if it isn't, read the
+ * schema server-side in the page's frontmatter and pass what the island needs).
+ */
+export async function getCollectionSchema(collectionId: string): Promise<CmsCollectionSchema | null> {
+  try {
+    const raw = await collections.getDataCollection(collectionId);
+    return raw ? toCollectionSchema(raw as RawCollection) : null;
+  } catch {
+    return null;
+  }
+}

package/skills/wix-headless-templates/cms/project/src/wix/cms/item-store.ts

@@ -0,0 +1,93 @@
+// One item as a framework-free store — the logic behind useItem: by `_id` or by a field match
+// (slug routing), usable from React (useItem wraps it), from a static page's item view, from
+// Vue/Svelte, or as the specification for a port.
+//
+// SSR-friendly: pass the server-fetched item as `initialItem` and start() fetches nothing.
+// One store per item surface: createItemStore(), not a singleton.
+import { getItemBy, getItemById } from "./items";
+import type { CmsItem } from "./types";
+
+/** Exactly one of `id` / `by`. */
+export interface ItemRef {
+  id?: string;
+  by?: { field: string; value: string | number };
+}
+
+export interface ItemStoreOptions {
+  collectionId: string;
+  ref: ItemRef;
+  initialItem?: CmsItem;
+  /** Reference field keys to inline as full items. */
+  include?: string[];
+}
+
+export interface ItemState {
+  /** null while loading OR when not found — branch on notFound for the miss state. */
+  item: CmsItem | null;
+  notFound: boolean;
+  error: string | null;
+  /** True until the fetch settles (false at once with an initialItem). */
+  loading: boolean;
+}
+
+export interface ItemStore {
+  getState(): ItemState;
+  subscribe(listener: () => void): () => void;
+  /** Fetch by ref when no `initialItem` was given. Call once when mounted. */
+  start(): void;
+  stop(): void;
+  /** Fetch again (after an error, or when the item may have changed). */
+  retry(): void;
+}
+
+export function createItemStore({ collectionId, ref, initialItem, include }: ItemStoreOptions): ItemStore {
+  let item: CmsItem | null = initialItem ?? null;
+  let notFound = false;
+  let error: string | null = null;
+  let loading = !initialItem;
+  let started = false;
+  let generation = 0;
+  const listeners = new Set<() => void>();
+  let snapshot: ItemState | null = null;
+  const emit = () => { snapshot = null; for (const fn of listeners) fn(); };
+
+  function getState(): ItemState {
+    if (snapshot) return snapshot;
+    snapshot = { item, notFound, error, loading };
+    return snapshot;
+  }
+
+  function load(): void {
+    const id = ++generation;
+    loading = true; error = null; emit();
+    const fetching = ref.id
+      ? getItemById(collectionId, ref.id, { include })
+      : ref.by
+        ? getItemBy(collectionId, ref.by.field, ref.by.value, { include })
+        : Promise.reject(new Error("useItem: pass ref.id or ref.by"));
+    fetching
+      .then((found) => {
+        if (generation !== id || !started) return;
+        item = found; notFound = found === null; loading = false;
+        emit();
+      })
+      .catch((e) => {
+        if (generation !== id || !started) return;
+        error = e instanceof Error ? e.message : String(e); loading = false;
+        emit();
+      });
+  }
+
+  return {
+    getState,
+    subscribe(fn) { listeners.add(fn); return () => listeners.delete(fn); },
+    start() {
+      if (started) return;
+      started = true;
+      if (initialItem) return;
+      load();
+    },
+    stop() { started = false; generation++; },
+    retry() { if (started) load(); },
+  };
+}

package/skills/wix-headless-templates/cms/project/src/wix/cms/items-core.ts

@@ -0,0 +1,259 @@
+// Wix Data rules and DTO mapping — transport-agnostic, imported by BOTH transports: ./items.ts
+// (the SDK, managed Astro and React) and the REST twin in templates/cms/rest/items.ts (fetch, a
+// static site or a port to another language). Every rule about normalizing an item, validating a
+// filter, and spelling a query for the wire lives HERE, once. A raw item may come from the SDK
+// (dates as Date objects) or from REST (dates as `{ "$date": iso }`); the mappers accept both.
+// Imports are type-only so a strip to JS emits no imports.
+import type { CmsFilter, CmsItem, CmsPage, CmsQuery, CmsSort } from "./types";
+
+/** A raw data item's payload as either transport returns it (fields flat, `_id` included). */
+export type Raw = Record<string, any>;
+/** Media value + size → https URL. Injected: the SDK transport scales through @wix/sdk, REST through the URL form. */
+export type ImgSrc = (value: any, width: number, height: number) => string;
+/** Media value → height/width read from its `#originWidth=…&originHeight=…` fragment; null when it carries none. */
+export type ImgRatio = (value: any) => number | null;
+/** The media seams a transport injects — `imgSrc` and `imgRatio` from its media.ts. */
+export interface Media {
+  imgSrc: ImgSrc;
+  imgRatio: ImgRatio;
+}
+
+/** Page size when a query names none. */
+export const DEFAULT_LIMIT = 20;
+/** Distinct values returned when a call names no limit. */
+export const DISTINCT_LIMIT = 100;
+/** The width every IMAGE field is resolved at — one URL per item, large enough for a detail page. */
+export const IMAGE_WIDTH = 1200;
+/** The height when the identifier carries no size (an image imported without its dimensions): 4:3. */
+export const IMAGE_HEIGHT = 900;
+
+// ---- DTO normalization ---------------------------------------------------------------------------
+
+/** REST spells DATE/DATETIME fields as `{ "$date": "<iso>" }`; the SDK decodes them into Date objects. */
+function isDateWrapper(v: unknown): v is { $date: string } {
+  if (!v || typeof v !== "object" || Array.isArray(v)) return false;
+  const keys = Object.keys(v as Raw);
+  return keys.length === 1 && keys[0] === "$date" && typeof (v as Raw).$date === "string";
+}
+
+/**
+ * The size an IMAGE field resolves at: IMAGE_WIDTH wide, at the image's own aspect when the
+ * `wix:image://` id carries `#originWidth/#originHeight` (a fill at another aspect would crop it),
+ * IMAGE_WIDTH × IMAGE_HEIGHT otherwise. The resolved URL carries the size (`/w_1200,h_800/`), so
+ * media.ts `imgRatio(url)` reads the aspect back for srcsets.
+ */
+export function imageSize(ratio: number | null): { width: number; height: number } {
+  return { width: IMAGE_WIDTH, height: ratio ? Math.round(IMAGE_WIDTH * ratio) : IMAGE_HEIGHT };
+}
+
+/**
+ * Raw → DTO value: dates become ISO strings (Date objects aren't serializable as island props;
+ * `{ $date }` wrappers aren't dates at all), IMAGE fields holding a `wix:image://` identifier
+ * become https URLs a browser can load. Recursive — included reference items too.
+ */
+export function toValue(v: unknown, media: Media): unknown {
+  if (v instanceof Date) return v.toISOString();
+  if (isDateWrapper(v)) {
+    // Same spelling as the SDK path (REST omits the milliseconds: "…T00:00:00Z").
+    const t = new Date(v.$date);
+    return Number.isNaN(t.getTime()) ? v.$date : t.toISOString();
+  }
+  if (typeof v === "string" && v.startsWith("wix:image://")) {
+    const { width, height } = imageSize(media.imgRatio(v));
+    return media.imgSrc(v, width, height);
+  }
+  if (Array.isArray(v)) return v.map((x) => toValue(x, media));
+  if (v && typeof v === "object") {
+    const out: Raw = {};
+    for (const [k, val] of Object.entries(v as Raw)) out[k] = toValue(val, media);
+    return out;
+  }
+  return v;
+}
+
+export const toItem = (raw: Raw, media: Media): CmsItem => toValue(raw, media) as CmsItem;
+
+export function toPage(items: Raw[], hasNext: boolean, total: number | null | undefined, media: Media): CmsPage {
+  return { items: items.map((r) => toItem(r, media)), hasNext, total: total ?? null };
+}
+
+/** Distinct values of a field, normalized like item values (a DATE field's values → ISO strings). */
+export const toValues = (values: unknown[], media: Media): unknown[] => values.map((v) => toValue(v, media));
+
+/**
+ * A DATE/DATETIME field for display — the DTO carries an ISO string; this is the one place it
+ * becomes copy. "" for an absent or unparseable value (never "Invalid Date", never the raw ISO).
+ *   formatDate(item.publishDate)                       → "August 20, 2026"
+ *   formatDate(item.publishDate, "en-GB", { dateStyle: "medium" })
+ */
+export function formatDate(iso: unknown, locale = "en-US", options: Intl.DateTimeFormatOptions = { dateStyle: "long" }): string {
+  if (typeof iso !== "string" || !iso) return "";
+  const t = new Date(iso);
+  return Number.isNaN(t.getTime()) ? "" : new Intl.DateTimeFormat(locale, options).format(t);
+}
+
+// ---- filter rules --------------------------------------------------------------------------------
+
+/**
+ * An undefined comparand silently changes what a query matches (every row, or none) with no
+ * server error — the classic "my items shows everyone's items" bug. Throw at the call site;
+ * omit the filter entirely when you don't hold a value yet. A `between` needs its two bounds.
+ */
+export function assertFilterValue(f: CmsFilter): void {
+  if (f.op === "isEmpty" || f.op === "isNotEmpty") return;
+  if (f.value === undefined) {
+    throw new Error(
+      `cms: filter on "${f.field}" (${f.op}) has an undefined value — pass a real value or omit the filter.`,
+    );
+  }
+  if (f.op === "between" && !(Array.isArray(f.value) && f.value.length === 2)) {
+    throw new Error(`cms: filter on "${f.field}" (between) takes [start, end].`);
+  }
+}
+
+/** The validated `[start, end]` of a between filter — start inclusive, end exclusive on both transports. */
+export function betweenRange(f: CmsFilter): [unknown, unknown] {
+  assertFilterValue(f);
+  const [start, end] = f.value as unknown[];
+  return [start, end];
+}
+
+// ---- the REST spelling of a query ---------------------------------------------------------------
+// The SDK's query builder serializes these itself; the REST twin sends them literally. Proven live:
+// a DATE comparand must travel as `{ "$date": iso }` (a plain ISO string compares as text and
+// matches nothing); isEmpty is `{ field: null }` and isNotEmpty `{ field: { $ne: null } }` — the
+// `$isEmpty` keyword is rejected (WDE0076).
+
+/**
+ * A comparand or field value on the wire: Date → `{ $date }`, arrays element-wise, everything else
+ * as-is. DATE and DATETIME fields BOTH travel as `{ "$date": iso }` (the SDK sends a Date the same
+ * way) — proven live: the seed writes DATE fields so, reads them back as dates, and date filters
+ * match them. Wix's headless-components write a DATE field as a "YYYY-MM-DD" string instead; that
+ * form is not copied here (their formatter is also a month off: getUTCMonth() without +1). A TIME
+ * field is a "hh:mm:ss.SSS" string and passes through as text.
+ */
+export function restValue(v: unknown): unknown {
+  if (v instanceof Date) return { $date: v.toISOString() };
+  if (Array.isArray(v)) return v.map(restValue);
+  return v;
+}
+
+const REST_OPS: Record<Exclude<CmsFilter["op"], "isEmpty" | "isNotEmpty" | "between">, string> = {
+  eq: "$eq",
+  ne: "$ne",
+  gt: "$gt",
+  ge: "$gte",
+  lt: "$lt",
+  le: "$lte",
+  contains: "$contains",
+  startsWith: "$startsWith",
+  endsWith: "$endsWith",
+  // `in` is spelled $hasSome on the wire, the same predicate the SDK transport sends (on a scalar
+  // field: equal to any of the values) — one behaviour on both transports.
+  in: "$hasSome",
+  hasSome: "$hasSome",
+  hasAll: "$hasAll",
+};
+
+/** One predicate → one filter object `{ field: condition }`. `between` is the builder's ge + lt pair. */
+export function restCondition(f: CmsFilter): Raw {
+  assertFilterValue(f);
+  if (f.op === "isEmpty") return { [f.field]: null };
+  if (f.op === "isNotEmpty") return { [f.field]: { $ne: null } };
+  if (f.op === "between") {
+    const [start, end] = betweenRange(f);
+    return { [f.field]: { $gte: restValue(start), $lt: restValue(end) } };
+  }
+  return { [f.field]: { [REST_OPS[f.op]]: restValue(f.value) } };
+}
+
+/** All predicates AND-ed: `{}` for none, the one object for one, `{ $and: [...] }` otherwise. */
+export function restFilter(filters: CmsFilter[] = []): Raw {
+  const conditions = filters.map(restCondition);
+  if (conditions.length === 0) return {};
+  if (conditions.length === 1) return conditions[0];
+  return { $and: conditions };
+}
+
+export function restSort(sort: CmsSort[] = []): { fieldName: string; order: "ASC" | "DESC" }[] {
+  return sort.map((s) => ({ fieldName: s.field, order: s.direction === "desc" ? "DESC" : "ASC" }));
+}
+
+/**
+ * The full Query Data Items body. Offset paging (`skip` = page N × limit) so every page can carry
+ * its own filter/sort and `returnTotalCount` works; `includeReferences[].field` inlines reference
+ * items.  POST /wix-data/v2/items/query
+ */
+export function queryBody(collectionId: string, query: CmsQuery = {}): Raw {
+  const { filters = [], sort = [], limit = DEFAULT_LIMIT, skip = 0, include = [], withTotal = false } = query;
+  return {
+    dataCollectionId: collectionId,
+    query: {
+      filter: restFilter(filters),
+      ...(sort.length ? { sort: restSort(sort) } : {}),
+      paging: { limit, offset: skip },
+    },
+    ...(include.length ? { includeReferences: include.map((field) => ({ field })) } : {}),
+    ...(withTotal ? { returnTotalCount: true } : {}),
+  };
+}
+
+/** Whether another page follows — the response says so; the arithmetic is the fallback. */
+export function restHasNext(pagingMetadata: Raw | undefined, offset: number, limit: number): boolean {
+  if (typeof pagingMetadata?.hasNext === "boolean") return pagingMetadata.hasNext;
+  if (typeof pagingMetadata?.total === "number") return offset + (pagingMetadata.count ?? 0) < pagingMetadata.total;
+  return (pagingMetadata?.count ?? 0) >= limit;
+}
+
+/**
+ * The Count Data Items body — the filter in the same spelling a query carries, top-level.
+ * POST /wix-data/v2/items/count  → { totalCount }
+ */
+export function countBody(collectionId: string, filters: CmsFilter[] = []): Raw {
+  return { dataCollectionId: collectionId, filter: restFilter(filters) };
+}
+
+/**
+ * The Query Distinct Values body — `fieldName` and `filter` sit top-level (not under `query`).
+ * POST /wix-data/v2/items/query-distinct-values  → { distinctValues: [...], pagingMetadata }
+ */
+export function distinctBody(collectionId: string, field: string, filters: CmsFilter[] = [], limit = DISTINCT_LIMIT): Raw {
+  return { dataCollectionId: collectionId, fieldName: field, filter: restFilter(filters), paging: { limit, offset: 0 } };
+}
+
+// ---- the REST spelling of a write ---------------------------------------------------------------
+
+/**
+ * Field values for an insert/update body — restValue per field (dates → `{ $date }`; JSON.stringify
+ * would turn a Date into a plain ISO string, which Wix stores as TEXT and never matches a date
+ * query). The read-only system fields are Wix's to stamp, never sent.
+ */
+export function restWriteData(data: Record<string, unknown>): Raw {
+  const out: Raw = {};
+  for (const [k, v] of Object.entries(data)) {
+    if (k === "_createdDate" || k === "_updatedDate" || k === "_owner") continue;
+    out[k] = restValue(v);
+  }
+  return out;
+}
+
+/** The Patch Data Item modifications for "set these fields" — one SET_FIELD per key.  PATCH /wix-data/v2/items/{id} */
+export function patchModifications(fields: Record<string, unknown>): Raw[] {
+  const entries = Object.entries(fields);
+  if (!entries.length) throw new Error("cms: patchItemFields called with no fields.");
+  return entries.map(([fieldPath, value]) => ({ fieldPath, action: "SET_FIELD", setFieldOptions: { value: restValue(value) } }));
+}
+
+/**
+ * The Bulk Insert / Bulk Remove Data Item References body: one entry per referenced id. The key is
+ * `dataItemReferences` with `referringItemFieldName` / `referringItemId` / `referencedItemId` — the
+ * natural-looking `references` shape is rejected (400 WDE0080).
+ * POST /wix-data/v2/bulk/items/insert-references · POST /wix-data/v2/bulk/items/remove-references
+ */
+export function referencesBody(collectionId: string, field: string, itemId: string, refIds: string[]): Raw {
+  if (!refIds.length) throw new Error("cms: linkItems/unlinkItems called with no referenced ids.");
+  return {
+    dataCollectionId: collectionId,
+    dataItemReferences: refIds.map((referencedItemId) => ({ referringItemFieldName: field, referringItemId: itemId, referencedItemId })),
+  };
+}