@wix/agent-skills 1.26.0 → 1.27.0

package/skills/wix-headless-templates/cms/app/wix/cms/items.ts

@@ -0,0 +1,182 @@
+// 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 templates/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 { imgRatio, imgSrc } from "../media";
+import { DEFAULT_LIMIT, DISTINCT_LIMIT, assertFilterValue, betweenRange, toItem, toValues, type Media, type Raw } from "./items-core";
+import type { CmsFilter, CmsItem, CmsPage, CmsQuery } from "./types";
+
+const items = wixModule(itemsModule);
+const media: Media = { imgSrc, imgRatio };
+
+/** The query builder with every predicate applied — one place for the op → builder mapping (query, count, distinct). */
+function withFilters(collectionId: string, filters: CmsFilter[]) {
+  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 "endsWith": q = q.endsWith(f.field, v); break;
+      // `in` rides hasSome, as Wix's own CMS components map it: on a scalar field hasSome matches a
+      // value equal to ANY of the list (the builder's own in() is not in its public type).
+      case "in": q = q.hasSome(f.field, v); break;
+      case "hasSome": q = q.hasSome(f.field, v); break;
+      case "hasAll": q = q.hasAll(f.field, v); break;
+      case "between": {
+        // The builder spells between as ge(start) + lt(end): start inclusive, end exclusive.
+        const [start, end] = betweenRange(f);
+        q = q.between(f.field, start as any, end as any);
+        break;
+      }
+      case "isEmpty": q = q.isEmpty(f.field); break;
+      case "isNotEmpty": q = q.isNotEmpty(f.field); break;
+    }
+  }
+  return q;
+}
+
+/**
+ * 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 = withFilters(collectionId, filters);
+  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, media)),
+    hasNext: res.hasNext(),
+    total: res.totalCount ?? null,
+  };
+}
+
+/**
+ * Fetch one item by `_id`. Null when not found. `includeReferences` is the get request's key in the
+ * installed typings (`includeReferencedItems` is the deprecated one) — confirm once on a live site
+ * that get honours it; if the referenced fields come back as ids, route through getItemBy("_id", …).
+ */
+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, media) : 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 — the builder's count(), no items transferred. */
+export async function countItems(collectionId: string, filters: CmsFilter[] = []): Promise<number> {
+  return withFilters(collectionId, filters).count();
+}
+
+/**
+ * The distinct values a field holds across the collection (optionally within `filters`) — filter
+ * chips and selects from live data, not from the page in hand. Values normalized like item values
+ * (a DATE field's → ISO strings); a reference field yields ids.
+ */
+export async function distinctValues(
+  collectionId: string,
+  field: string,
+  { filters = [], limit = DISTINCT_LIMIT }: { filters?: CmsFilter[]; limit?: number } = {},
+): Promise<unknown[]> {
+  const res = await withFilters(collectionId, filters).limit(limit).distinct(field);
+  return toValues(res.items ?? [], media);
+}
+
+/**
+ * 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).
+ * A MULTI_REFERENCE value inside `data` is DROPPED by the insert endpoint (200, no error) — pass
+ * those as `link: { field: [referencedIds] }` and they are linked right after the insert (create,
+ * then link). The returned item predates the links: re-read with `include` to see them.
+ */
+export async function insertItem(
+  collectionId: string,
+  data: Record<string, unknown>,
+  { link = {} }: { link?: Record<string, string[]> } = {},
+): Promise<CmsItem> {
+  const created = await items.insert(collectionId, data as Raw);
+  const item = toItem(created as Raw, media);
+  for (const [field, refIds] of Object.entries(link)) await linkItems(collectionId, field, item._id, refIds);
+  return item;
+}
+
+/**
+ * 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, media);
+}
+
+/** 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, media);
+}
+
+/** 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, media) : null;
+}
+
+/**
+ * Add references to a MULTI_REFERENCE field of `itemId` — the only way a multi-reference is set
+ * (insert/update drop the value silently). Existing references stay; needs the collection's update
+ * permission. A no-op for an empty list.
+ */
+export async function linkItems(collectionId: string, field: string, itemId: string, refIds: string[]): Promise<void> {
+  if (!refIds.length) return;
+  await items.insertReference(collectionId, field, itemId, refIds);
+}
+
+/** Remove references from a MULTI_REFERENCE field of `itemId`. Other references stay. A no-op for an empty list. */
+export async function unlinkItems(collectionId: string, field: string, itemId: string, refIds: string[]): Promise<void> {
+  if (!refIds.length) return;
+  await items.removeReference(collectionId, field, itemId, refIds);
+}

package/skills/wix-headless-templates/cms/app/wix/cms/types.ts

@@ -0,0 +1,138 @@
+// 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, TIME → "hh:mm:ss.SSS" string (text on the wire, passed through),
+ * IMAGE → https URL at the image's natural aspect ("" never happens — absent fields are
+ * undefined), RICH_TEXT → the stored HTML string, ARRAY_STRING (tags) → string[], ADDRESS →
+ * object with `formatted`, MEDIA_GALLERY → array of { src, type, title } (`src` resolved),
+ * REFERENCE/MULTI_REFERENCE → id(s), or full CmsItem(s) when the query included the field.
+ * VIDEO/DOCUMENT identifiers (`wix:video://`, `wix:document://`) and RICH_CONTENT (Ricos JSON)
+ * pass through unresolved.
+ */
+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;
+}
+
+/**
+ * Predicate operators — the SDK query builder's names. `in` matches a scalar field equal to ANY of
+ * the values (an id list; hasSome on the wire, as Wix's own components send it); `between` takes
+ * `[start, end]`, start inclusive, end EXCLUSIVE (the builder spells it ge + lt — a date range
+ * ends at the first excluded day).
+ */
+export type CmsFilterOp =
+  | "eq"
+  | "ne"
+  | "gt"
+  | "ge"
+  | "lt"
+  | "le"
+  | "contains"
+  | "startsWith"
+  | "endsWith"
+  | "in"
+  | "hasSome"
+  | "hasAll"
+  | "between"
+  | "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; in/hasSome/hasAll take an array; between takes `[start, end]`. */
+  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 (0-based) 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, page numbers, 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;
+}
+
+/** A field's type as the collection schema spells it (Wix Data `Type`; open for values added later). */
+export type CmsFieldType =
+  | "TEXT"
+  | "NUMBER"
+  | "BOOLEAN"
+  | "DATE"
+  | "DATETIME"
+  | "TIME"
+  | "URL"
+  | "IMAGE"
+  | "VIDEO"
+  | "DOCUMENT"
+  | "AUDIO"
+  | "RICH_TEXT"
+  | "RICH_CONTENT"
+  | "MEDIA_GALLERY"
+  | "ADDRESS"
+  | "ARRAY_STRING"
+  | "ARRAY"
+  | "OBJECT"
+  | "REFERENCE"
+  | "MULTI_REFERENCE"
+  | (string & {});
+
+/** Who may run a verb on a collection (Wix Data `Role`). */
+export type CmsRole = "ANYONE" | "SITE_MEMBER" | "SITE_MEMBER_AUTHOR" | "ADMIN" | (string & {});
+
+/** One field of a collection's schema. */
+export interface CmsFieldSchema {
+  key: string;
+  displayName: string;
+  type: CmsFieldType;
+  /** `_id`, `_createdDate`, `_updatedDate`, `_owner` — Wix's to stamp, never written. */
+  systemField: boolean;
+  required: boolean;
+  /** REFERENCE/MULTI_REFERENCE: the collection the field points at. */
+  referencedCollectionId?: string;
+}
+
+/**
+ * A collection's schema — field types, reference targets, and permissions at runtime: the
+ * source of truth for a field's type when the seed plan isn't at hand (an imported site).
+ */
+export interface CmsCollectionSchema {
+  id: string;
+  displayName: string;
+  fields: CmsFieldSchema[];
+  permissions: { read: CmsRole; insert: CmsRole; update: CmsRole; remove: CmsRole };
+}

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

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

package/skills/wix-headless-templates/cms/project/README.md

@@ -0,0 +1,15 @@
+# Wix Astro Blank Template
+
+**[Live demo](https://h6s-1a31f9730cd85b-headlessstack.wix-site-host.com)**
+
+Our Astro templates are still in development and subject to change.
+
+To use a template, follow the [Wix CLI for Headless Quick Start](https://dev.wix.com/docs/go-headless/get-started/quick-starts/wix-managed-headless/quick-start-with-the-wix-cli), and select the desired template during the setup process.
+
+## Need help?
+
+For documentation and support, check out:
+
+- [Wix Headless Documentation](https://dev.wix.com/docs/go-headless)
+- [Wix SDK Documentation](https://dev.wix.com/docs/sdk)
+- [Community on Discord](https://discord.gg/n6TBrSnYTp)

package/skills/wix-headless-templates/cms/project/astro.config.mjs

@@ -0,0 +1,22 @@
+import tailwindcss from "@tailwindcss/vite";
+// @ts-check
+import { defineConfig } from 'astro/config';
+import wix from "@wix/astro";
+import wixPages from "@wix/astro-pages";
+
+import react from "@astrojs/react";
+import wixHostingAdapter from "@wix/astro-wix-hosting-adapter";
+
+// https://astro.build/config
+export default defineConfig({
+  vite: { plugins: [tailwindcss()] },
+  integrations: [wix(), wixPages(), react()],
+  security: { checkOrigin: false },
+  adapter: wixHostingAdapter(),
+
+  image: {
+    domains: ["static.wixstatic.com"],
+  },
+
+  output: "server",
+});