@wix/agent-skills 1.20.1 → 1.22.0

package/skills/wix-headless-fast/references/cms/app/wix/cms/item-store.ts

@@ -1,93 +0,0 @@
-// 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-fast/references/cms/app/wix/cms/items-core.ts

@@ -1,177 +0,0 @@
-// 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 references/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;
-
-/** Page size when a query names none. */
-export const DEFAULT_LIMIT = 20;
-/** The size every IMAGE field is resolved at — one URL per item, large enough for a detail page. */
-export const IMAGE_WIDTH = 1200;
-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";
-}
-
-/**
- * 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, imgSrc: ImgSrc): 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://")) return imgSrc(v, IMAGE_WIDTH, IMAGE_HEIGHT);
-  if (Array.isArray(v)) return v.map((x) => toValue(x, imgSrc));
-  if (v && typeof v === "object") {
-    const out: Raw = {};
-    for (const [k, val] of Object.entries(v as Raw)) out[k] = toValue(val, imgSrc);
-    return out;
-  }
-  return v;
-}
-
-export const toItem = (raw: Raw, imgSrc: ImgSrc): CmsItem => toValue(raw, imgSrc) as CmsItem;
-
-export function toPage(items: Raw[], hasNext: boolean, total: number | null | undefined, imgSrc: ImgSrc): CmsPage {
-  return { items: items.map((r) => toItem(r, imgSrc)), hasNext, total: total ?? null };
-}
-
-/**
- * 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.
- */
-export function assertFilterValue(f: CmsFilter): void {
-  if (f.op !== "isEmpty" && f.op !== "isNotEmpty" && 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.`,
-    );
-  }
-}
-
-// ---- 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 on the wire: Date → `{ $date }`, arrays element-wise, everything else as-is. */
-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">, string> = {
-  eq: "$eq",
-  ne: "$ne",
-  gt: "$gt",
-  ge: "$gte",
-  lt: "$lt",
-  le: "$lte",
-  contains: "$contains",
-  startsWith: "$startsWith",
-  hasSome: "$hasSome",
-  hasAll: "$hasAll",
-};
-
-/** One predicate → one filter object `{ field: condition }`. */
-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 } };
-  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 REST spelling of a write ---------------------------------------------------------------
-
-/**
- * Field values for an insert/update body. A DATE field must arrive as `{ $date }` — JSON.stringify
- * turns 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) } }));
-}

package/skills/wix-headless-fast/references/cms/app/wix/cms/items.ts

@@ -1,123 +0,0 @@
-// Wix Data reads/writes (@wix/data `items`) over the SDK — the only file that touches raw data
-// items on this transport. CMS is schema-generic: every function takes the collection id from the
-// seed plan (seed/SEED.md) and returns plain CmsItem DTOs from ./types. The rules and mappers live
-// in ./items-core (shared with the REST twin in references/cms/rest/); this file is the transport
-// only. Copy as-is; extend by adding functions, not by editing these.
-// docs: https://dev.wix.com/docs/sdk/business-solutions/data/items/query.md
-// docs: https://dev.wix.com/docs/sdk/business-solutions/data/items/update.md
-import { items as itemsModule } from "@wix/data";
-import { wixModule } from "../sdk";
-import { imgSrc } from "../media";
-import { DEFAULT_LIMIT, assertFilterValue, toItem, type Raw } from "./items-core";
-import type { CmsFilter, CmsItem, CmsPage, CmsQuery } from "./types";
-
-const items = wixModule(itemsModule);
-
-/**
- * Query one page of a collection. An empty result on a PUBLIC collection is a seed
- * permissions bug (read must be "ANYONE"), not a query bug — never reach for auth.elevate.
- */
-export async function queryItems(collectionId: string, query: CmsQuery = {}): Promise<CmsPage> {
-  const { filters = [], sort = [], limit = DEFAULT_LIMIT, skip = 0, include = [], withTotal = false } = query;
-  let q = items.query(collectionId);
-  for (const f of filters) {
-    assertFilterValue(f);
-    const v = f.value as any;
-    switch (f.op) {
-      case "eq": q = q.eq(f.field, v); break;
-      case "ne": q = q.ne(f.field, v); break;
-      case "gt": q = q.gt(f.field, v); break;
-      case "ge": q = q.ge(f.field, v); break;
-      case "lt": q = q.lt(f.field, v); break;
-      case "le": q = q.le(f.field, v); break;
-      case "contains": q = q.contains(f.field, v); break;
-      case "startsWith": q = q.startsWith(f.field, v); break;
-      case "hasSome": q = q.hasSome(f.field, v); break;
-      case "hasAll": q = q.hasAll(f.field, v); break;
-      case "isEmpty": q = q.isEmpty(f.field); break;
-      case "isNotEmpty": q = q.isNotEmpty(f.field); break;
-    }
-  }
-  for (const s of sort) q = s.direction === "desc" ? q.descending(s.field) : q.ascending(s.field);
-  if (include.length) q = q.include(...include);
-  const res = await q.limit(limit).skip(skip).find(withTotal ? { returnTotalCount: true } : undefined);
-  return {
-    items: (res.items ?? []).map((r: Raw) => toItem(r, imgSrc)),
-    hasNext: res.hasNext(),
-    total: res.totalCount ?? null,
-  };
-}
-
-/** Fetch one item by `_id`. Null when not found. */
-export async function getItemById(
-  collectionId: string,
-  itemId: string,
-  { include = [] }: { include?: string[] } = {},
-): Promise<CmsItem | null> {
-  const raw = await items.get(collectionId, itemId, {
-    ...(include.length ? { includeReferences: include.map((field) => ({ field })) } : {}),
-  });
-  return raw ? toItem(raw as Raw, imgSrc) : null;
-}
-
-/**
- * Fetch the first item whose `field` equals `value` — slug-style routing (Wix Data has no
- * native get-by-slug). Null when not found → render a not-found state, never invent an item.
- */
-export async function getItemBy(
-  collectionId: string,
-  field: string,
-  value: string | number,
-  { include = [] }: { include?: string[] } = {},
-): Promise<CmsItem | null> {
-  const page = await queryItems(collectionId, { filters: [{ field, op: "eq", value }], limit: 1, include });
-  return page.items[0] ?? null;
-}
-
-/** Count items matching the filters — empty-state logic and result counts. */
-export async function countItems(collectionId: string, filters: CmsFilter[] = []): Promise<number> {
-  const page = await queryItems(collectionId, { filters, limit: 1, withTotal: true });
-  return page.total ?? page.items.length;
-}
-
-/**
- * Insert an item (visitor form / member submission). Succeeds only when the collection's
- * insert permission covers the caller (403 otherwise — a seed permissions step, not a code
- * bug). Never set `_owner` — Wix stamps it from the caller's identity.
- * Date fields must be Date objects (an ISO string is stored as text and breaks date queries).
- */
-export async function insertItem(collectionId: string, data: Record<string, unknown>): Promise<CmsItem> {
-  const created = await items.insert(collectionId, data as Raw);
-  return toItem(created as Raw, imgSrc);
-}
-
-/**
- * REPLACE an item — fields omitted from `item` are WIPED (update does not patch). Spread the
- * full item you hold and override; for an id + a few changed fields use patchItemFields.
- * A round-tripped DTO carries dates as ISO strings — wrap each date field back
- * (`new Date(iso)`) before updating, or the DATE field is silently rewritten as text.
- */
-export async function updateItem(collectionId: string, item: CmsItem): Promise<CmsItem> {
-  const updated = await items.update(collectionId, item as Raw & { _id: string });
-  return toItem(updated as Raw, imgSrc);
-}
-
-/** Patch only the named fields — the safe partial change (no replace-wipes-fields footgun). */
-export async function patchItemFields(
-  collectionId: string,
-  itemId: string,
-  fields: Record<string, unknown>,
-): Promise<CmsItem> {
-  const entries = Object.entries(fields);
-  if (!entries.length) throw new Error("cms: patchItemFields called with no fields.");
-  let p = items.patch(collectionId, itemId);
-  for (const [k, v] of entries) p = p.setField(k, v);
-  const patched = await p.run();
-  return toItem(patched as Raw, imgSrc);
-}
-
-/** Remove an item by `_id`. Irreversible. Returns the removed item (null if it didn't exist). */
-export async function removeItem(collectionId: string, itemId: string): Promise<CmsItem | null> {
-  const removed = await items.remove(collectionId, itemId);
-  return removed ? toItem(removed as Raw, imgSrc) : null;
-}

package/skills/wix-headless-fast/references/cms/app/wix/cms/types.ts

@@ -1,75 +0,0 @@
-// CMS DTOs — the serializable shapes every hook, component, and page consumes. CMS is
-// schema-generic: field keys come from the seed plan (seed/SEED.md), so an item is a flat
-// field map rather than a fixed interface. Plain JSON: safe as Astro island props or across
-// server/client boundaries. By the time an item leaves the data layer, Date fields are ISO
-// strings and IMAGE fields are resolved https URLs.
-
-/**
- * One collection item: `_id` plus the collection's fields, flat on the item (there is no
- * `item.data.*` — that is the REST shape and reads undefined here).
- * Field values by type: TEXT/URL/EMAIL → string, NUMBER → number, BOOLEAN → boolean,
- * DATE/DATETIME → ISO string, IMAGE → https URL ("" never happens — absent fields are
- * undefined), RICH_TEXT → the stored HTML string, REFERENCE/MULTI_REFERENCE → id(s), or
- * full CmsItem(s) when the query included the field.
- */
-export interface CmsItem {
-  _id: string;
-  /** ISO string (the SDK's Date objects are serialized by the data layer). */
-  _createdDate?: string;
-  _updatedDate?: string;
-  /** Id of the member who created the row (member-scoped collections). */
-  _owner?: string;
-  [key: string]: unknown;
-}
-
-export type CmsFilterOp =
-  | "eq"
-  | "ne"
-  | "gt"
-  | "ge"
-  | "lt"
-  | "le"
-  | "contains"
-  | "startsWith"
-  | "hasSome"
-  | "hasAll"
-  | "isEmpty"
-  | "isNotEmpty";
-
-/**
- * One query predicate. Comparands must match the field's stored type — a DATE/DATETIME
- * field only matches a Date object (an ISO string compares as text and matches nothing).
- */
-export interface CmsFilter {
-  field: string;
-  op: CmsFilterOp;
-  /** Required except for isEmpty/isNotEmpty; hasSome/hasAll take an array. */
-  value?: string | number | boolean | Date | (string | number | Date)[];
-}
-
-export interface CmsSort {
-  field: string;
-  /** Default "asc". */
-  direction?: "asc" | "desc";
-}
-
-export interface CmsQuery {
-  filters?: CmsFilter[];
-  sort?: CmsSort[];
-  /** Page size (default 20). */
-  limit?: number;
-  /** Items to skip — page N is skip = N * limit. */
-  skip?: number;
-  /** Reference field keys to inline as full items (otherwise the field holds ids). */
-  include?: string[];
-  /** true → the page carries `total` (slower query; for counts/empty-state logic). */
-  withTotal?: boolean;
-}
-
-/** One page of items. Load the next page with skip = items shown so far. */
-export interface CmsPage {
-  items: CmsItem[];
-  hasNext: boolean;
-  /** Total matching items — only when the query asked `withTotal`, else null. */
-  total: number | null;
-}

package/skills/wix-headless-fast/references/cms/app-astro/layouts/SiteLayout.astro

@@ -1,41 +0,0 @@
----
-// The site chrome for every CMS page — THIS file (header/footer/nav) plus the @theme token
-// block in src/styles/global.css are what you brand. Keep the <slot name="seo-tags" /> in
-// <head> and the global.css import. Add one nav link per content surface you build (the
-// routes are yours — CMS ships no fixed pages). (If another vertical is also deployed, its
-// SiteLayout won; merge nav links there instead.)
-import "../styles/global.css";
-
-interface Props {
-  title: string;
-  description?: string;
-}
-const { title, description } = Astro.props;
----
-
-<!doctype html>
-<html lang="en">
-  <head>
-    <meta charset="UTF-8" />
-    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
-    <title>{title}</title>
-    {description && <meta name="description" content={description} />}
-    <slot name="seo-tags" />
-  </head>
-  <body>
-    <header class="sticky top-0 z-40 border-b border-border bg-background/80 backdrop-blur">
-      <div class="mx-auto flex h-16 max-w-6xl items-center justify-between px-6">
-        <a href="/" class="text-base font-bold tracking-tight text-foreground no-underline">Brand Name</a>
-        <nav class="flex items-center gap-6 text-sm">
-          <!-- one link per content surface you build, e.g. <a href="/recipes">Recipes</a> -->
-        </nav>
-      </div>
-    </header>
-    <main class="mx-auto max-w-6xl px-6 pb-24 pt-10">
-      <slot />
-    </main>
-    <footer class="border-t border-border px-6 py-10 text-center text-sm text-muted-foreground">
-      © Brand Name
-    </footer>
-  </body>
-</html>