@wix/agent-skills 1.26.0 → 1.28.0

package/skills/wix-headless-templates/cms/project/src/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/project/src/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/project/src/wix/config.ts

@@ -0,0 +1,16 @@
+// Wix connection config — written by the skill's deploy step (install/deploy.mjs).
+//
+// WIX_CLIENT_ID = null  → ambient auth (a Wix-managed Astro project: `@wix/astro` authenticates
+//                         every SDK call automatically; there is no client and nothing to set).
+// WIX_CLIENT_ID = "..." → manual visitor client (any other React setup): the public OAuth client id.
+//                         It is NOT a secret — it only mints anonymous visitor tokens — so
+//                         hardcoding and committing it is fine. deploy.mjs copies it from `.env.local`
+//                         (`WIX_CLIENT_ID`, what `wix env pull` writes): the CONTENT site's app — on a
+//                         migration preview the site being migrated, while wix.config.json names
+//                         only the deploy target.
+export const WIX_CLIENT_ID: string | null = null;
+
+// Kept for projects deployed before the Members vertical moved onto the shared seam; the shipped
+// members code no longer reads it (ambient Astro uses the built-in /api/auth routes, manual mode
+// uses the shared client above). deploy.mjs still fills it so older code keeps compiling.
+export const WIX_MEMBERS_CLIENT_ID: string | null = null;

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

@@ -0,0 +1,106 @@
+// Wix media resolution — define once, use on EVERY image render path. Copy as-is.
+//
+// SDK media fields come back either as an already-absolute https URL, or as a
+// `wix:image://v1/<hash>/<file>#originWidth=…` identifier that a browser cannot load
+// (ERR_UNKNOWN_URL_SCHEME). The wix:image:// form must go through the SDK media module;
+// never hand-build a static.wixstatic.com URL (wrong format → 403).
+// docs: https://dev.wix.com/docs/sdk/core-modules/sdk/media.md
+import { media } from "@wix/sdk";
+
+type MediaLike =
+  | string
+  | null
+  | undefined
+  | { image?: unknown; url?: string | null; id?: string | null };
+
+/** A bare Wix media file id (`e6a89e_06cf…~mv2.png`): what REST-shaped media objects carry as `url` and `id`. */
+const BARE_FILE_ID = /^[\w-]+~mv2\.[a-z0-9]+$/i;
+
+function rawOf(value: MediaLike): string {
+  if (!value) return "";
+  if (typeof value === "string") return value;
+  if (value.image != null && typeof value.image === "object") return rawOf(value.image as MediaLike); // { image: { id, url } }
+  return (typeof value.image === "string" ? value.image : null) ?? value.url ?? value.id ?? "";
+}
+
+/** Resolve any Wix media value to a browser-loadable URL ("" when absent). */
+export function imgSrc(value: MediaLike, width = 600, height = 600): string {
+  const v = rawOf(value);
+  if (!v) return "";
+  if (v.startsWith("wix:image://")) {
+    return media.getScaledToFillImageUrl(v, width, height, {});
+  }
+  // A bare file id (what REST-shaped media objects carry) or an absolute Wix media URL (bare, or
+  // already carrying a /v1/fill/ segment at some other size): re-issue it through the scaler at the
+  // requested size, so every image path lands on one shape.
+  const file = BARE_FILE_ID.test(v) ? v : v.match(/^https:\/\/static\.wixstatic\.com\/media\/([^/?#]+)/)?.[1];
+  if (file) return `https://static.wixstatic.com/media/${file}/v1/fill/w_${width},h_${height},al_c,q_90/${file}`;
+  return v;
+}
+
+/**
+ * Responsive candidates for `srcset`: the same image at several widths through Wix's scaler, so a
+ * card never downloads a hero-sized file. Pair with `sizes`:
+ *   <img src={imgSrc(m, 640, 640)} srcSet={imgSrcSet(m)} sizes="(min-width: 1024px) 25vw, 50vw"
+ *        width={640} height={640} loading="lazy" alt={…} />
+ * Accepts every form an image reaches you in: a raw `wix:image://` id, an ALREADY-RESOLVED Wix URL
+ * (what the DTOs carry — `imageUrl`, `gallery[]`; its `/v1/fill/w_…,h_…` segment is rewritten per
+ * width), or any other https URL (returned as the single candidate). `ratio` is height/width
+ * (1 = square). "" only when there is no image at all — still set `src` as well.
+ */
+export function imgSrcSet(value: MediaLike, widths: number[] = [320, 480, 640, 960], ratio = 1): string {
+  const raw = rawOf(value);
+  if (!raw) return "";
+  if (raw.startsWith("wix:image://") || BARE_FILE_ID.test(raw)) {
+    return widths.map((w) => `${imgSrc(value, w, Math.round(w * ratio))} ${w}w`).join(", ");
+  }
+  // A resolved Wix URL: …/v1/fill/w_800,h_800,al_c,… — swap the size for each width.
+  const FILL = /\/v1\/fill\/w_\d+,h_\d+/;
+  if (/static\.wixstatic\.com\//.test(raw) && FILL.test(raw)) {
+    return widths.map((w) => `${raw.replace(FILL, `/v1/fill/w_${w},h_${Math.round(w * ratio)}`)} ${w}w`).join(", ");
+  }
+  return raw; // one candidate, never an empty srcset for a real image
+}
+
+/**
+ * Everything an <img> needs for one Wix image, so a tile can never ship `srcSet` without `src`:
+ *   <img {...imgAttrs(p.imageUrl, "(min-width: 1024px) 25vw, 50vw")} alt={p.name} />
+ * `sizes` is the width the image renders at (a CSS length or media-query list); `ratio` is
+ * height/width. Returns an empty object when there is no image — render your placeholder then.
+ */
+export function imgAttrs(value: MediaLike, sizes: string, ratio = 1): { src: string; srcSet: string; sizes: string; loading: "lazy"; decoding: "async" } | Record<string, never> {
+  const src = imgSrc(value, 640, Math.round(640 * ratio));
+  if (!src) return {};
+  return { src, srcSet: imgSrcSet(value, undefined, ratio), sizes, loading: "lazy", decoding: "async" };
+}
+
+/**
+ * Height/width of a Wix image when the value carries its size: a raw
+ * `wix:image://…#originWidth=W&originHeight=H` id (the natural size) or a resolved `/v1/fill/w_W,h_H/`
+ * URL (the size it was scaled to). null when neither is present. Pass it as `ratio` to keep a
+ * srcset at the image's own aspect instead of the square default:
+ *   <img {...imgAttrs(item.photo, "33vw", imgRatio(item.photo) ?? 1)} alt={…} />
+ */
+export function imgRatio(value: MediaLike): number | null {
+  const v = rawOf(value);
+  if (typeof v !== "string" || !v) return null;
+  const size = v.startsWith("wix:image://")
+    ? [v.match(/[#&]originWidth=(\d+)/)?.[1], v.match(/[#&]originHeight=(\d+)/)?.[1]]
+    : (v.match(/\/v1\/fill\/w_(\d+),h_(\d+)/)?.slice(1) ?? []);
+  const w = Number(size[0]);
+  const h = Number(size[1]);
+  return w > 0 && h > 0 ? h / w : null;
+}
+
+/**
+ * The identity of a media value BEFORE scaling — de-duplicate galleries on this, never on a
+ * resolved URL (two scaled URLs of one photo differ in their size parameters).
+ */
+export function mediaKey(value: MediaLike): string {
+  const v = rawOf(value);
+  if (!v) return "";
+  // The file id, whichever form the value takes — a raw id and a resolved URL of one photo share it.
+  if (v.startsWith("wix:image://")) return v.slice("wix:image://v1/".length).split("/")[0].split("#")[0];
+  const m = v.match(/^https:\/\/static\.wixstatic\.com\/media\/([^/?#]+)/);
+  return m ? m[1] : v;
+}

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

@@ -0,0 +1,24 @@
+// Money formatting for API amounts that carry no formatted string. Copy as-is.
+//
+// Catalog prices come with a ready `formattedAmount` — use that directly. But eCom Cart V2
+// amounts are ConvertedMoney `{ amount, convertedAmount }` with NO formatted string, and the
+// currency lives on the cart, not on the money object. Never hardcode "$" or assume USD.
+export interface ConvertedMoneyLike {
+  amount?: string | null;
+  convertedAmount?: string | null;
+}
+
+/** Format a ConvertedMoney in the given currency, using the visitor's locale. */
+export function formatMoney(
+  money: ConvertedMoneyLike | null | undefined,
+  currencyCode: string | null | undefined,
+): string {
+  const value = money?.convertedAmount ?? money?.amount;
+  if (value == null || value === "") return "";
+  const currency = currencyCode || "USD";
+  try {
+    return new Intl.NumberFormat(undefined, { style: "currency", currency }).format(Number(value));
+  } catch {
+    return `${value} ${currency}`;
+  }
+}

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

@@ -0,0 +1,89 @@
+// The one auth seam for every Wix SDK call in this app. Copy as-is; do not rewrite.
+//
+// Two modes, switched by WIX_CLIENT_ID in ./config:
+//   null (ambient)  — a Wix-managed Astro project: `@wix/astro` authenticates raw SDK module
+//                     calls automatically, server-side AND in client islands. `wixModule()`
+//                     returns the module untouched.
+//   string (manual) — any other React setup (Vite SPA, non-Astro): one shared client is built
+//                     with OAuthStrategy, and `wixModule()` returns the module bound to it.
+//                     The strategy self-manages visitor tokens on every call (mints on first
+//                     use, renews on expiry) and persists them through the storage below.
+//
+// The visitor token IS the identity of the current cart / member session, so in manual mode
+// tokens persist to localStorage — never re-minted per load (a fresh anonymous mint is a NEW
+// visitor and silently empties the cart).
+// docs: https://dev.wix.com/docs/sdk/core-modules/sdk/oauth-strategy.md
+// docs: https://dev.wix.com/docs/go-headless/wix-managed-headless/authentication/about-the-astro-integration.md
+import { createClient, OAuthStrategy, EMPTY_TOKENS } from "@wix/sdk";
+import { fetchWithAuth as ambientFetch } from "@wix/sdk/context";
+import type { IOAuthStrategy, TokenStorage, Tokens } from "@wix/sdk";
+import { WIX_CLIENT_ID } from "./config";
+
+const STORAGE_KEY = `wix-session-${WIX_CLIENT_ID ?? "ambient"}`;
+
+function browserTokenStorage(): TokenStorage {
+  return {
+    getTokens(): Tokens {
+      if (typeof window !== "undefined") {
+        try {
+          const raw = window.localStorage.getItem(STORAGE_KEY);
+          if (raw) return JSON.parse(raw) as Tokens;
+        } catch {
+          /* disabled/corrupt storage — fall through to empty */
+        }
+      }
+      return EMPTY_TOKENS;
+    },
+    setTokens(tokens: Tokens): void {
+      if (typeof window === "undefined") return;
+      try {
+        window.localStorage.setItem(STORAGE_KEY, JSON.stringify(tokens));
+      } catch {
+        /* storage full/disabled — the session just won't survive a reload */
+      }
+    },
+  };
+}
+
+const client = WIX_CLIENT_ID
+  ? createClient({
+      auth: OAuthStrategy({
+        clientId: WIX_CLIENT_ID,
+        tokenStorage: browserTokenStorage(),
+      }),
+    })
+  : null;
+
+/**
+ * Bind an SDK module to this app's auth. Usage (identical in both modes):
+ *   import { productsV3 } from "@wix/stores";
+ *   const products = wixModule(productsV3);
+ *   await products.queryProducts(...)
+ */
+export function wixModule<T>(module: T): T {
+  // The cast bridges the SDK's internal Descriptors constraint; the in/out type is identical.
+  return client
+    ? (client.use(module as unknown as Record<string, unknown>) as unknown as T)
+    : module;
+}
+
+/**
+ * An authenticated fetch of a Wix REST endpoint under the SAME auth as the SDK modules (ambient
+ * on managed Astro, the shared client elsewhere) — for the few APIs whose generated SDK module is
+ * too heavy to bundle (the Forms schema module alone is 15 MB: server-side it pushes a Wix
+ * deploy past its size limit, client-side every visitor downloads it). Same visitor identity,
+ * same token, no second mint. `path` is the wixapis.com path; returns the raw Response.
+ */
+export function wixFetch(path: string, init?: RequestInit): Promise<Response> {
+  const url = path.startsWith("http") ? path : `https://www.wixapis.com${path}`;
+  return client ? client.fetchWithAuth(url, init) : ambientFetch(url, init);
+}
+
+/**
+ * The shared data client's manual-mode auth strategy, or null under ambient auth. The
+ * Members vertical deliberately owns a separate explicit client for its custom in-app login;
+ * app code reads that session through the members hooks instead.
+ */
+export function wixAuth(): IOAuthStrategy | null {
+  return client ? client.auth : null;
+}

package/skills/wix-headless-templates/cms/project/tsconfig.json

@@ -0,0 +1,5 @@
+{
+  "extends": "astro/tsconfigs/strict",
+  "include": [".astro/types.d.ts", "**/*"],
+  "exclude": ["dist"]
+}

package/skills/wix-headless-templates/cms/rest/collections.ts

@@ -0,0 +1,25 @@
+// Collection schema reads over REST — the twin of app/wix/cms/collections.ts. Same export, same
+// DTO; the mapper comes from collections-core (the SAME file the SDK transport uses, deployed flat
+// next to this one by deploy.mjs --stack static), so this file is only the transport.
+// docs: https://dev.wix.com/docs/api-reference/business-solutions/cms/data-collections/create-data-collection.md (the Data Collections API; get is GET /wix-data/v2/collections/{id} per the SDK's route table)
+import { WixApiError, wixRequest } from "./client.js";
+import { toCollectionSchema, type RawCollection } from "./collections-core.js";
+import type { CmsCollectionSchema } from "./types.js";
+
+const unreadable = (e: unknown): boolean => e instanceof WixApiError && (e.status === 404 || e.status === 403);
+
+/**
+ * A collection's schema — field types, reference targets, permissions. Null when the collection
+ * can't be read: it doesn't exist (404), or the caller may not read schemas (403 — confirm once on
+ * a live site that a visitor token is allowed; if it isn't, read it where an elevated call runs).
+ * GET /wix-data/v2/collections/{dataCollectionId}  → { collection: { id, displayName, fields: [{ key, displayName, type, typeMetadata, systemField, required }], permissions: { insert, update, remove, read } } }
+ */
+export async function getCollectionSchema(collectionId: string): Promise<CmsCollectionSchema | null> {
+  try {
+    const res = await wixRequest<RawCollection>(`/wix-data/v2/collections/${encodeURIComponent(collectionId)}`, { method: "GET" });
+    return res?.collection ? toCollectionSchema(res.collection) : null;
+  } catch (e) {
+    if (unreadable(e)) return null;
+    throw e;
+  }
+}