@wix/agent-skills 1.26.0 → 1.27.0

package/skills/wix-headless-templates/donations/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/donations/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/donations/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/donations/project/tsconfig.json

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

package/skills/wix-headless-templates/donations/rest/campaigns.ts

@@ -0,0 +1,76 @@
+// Campaign reads over REST — the twin of app/wix/donations/campaigns.ts. Same exports, same DTOs;
+// the rules and mappers come from donations-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: one
+// fetch with a literal body per function. Every call here runs with the visitor token; the metrics
+// read is guarded (a refusal leaves the raised total and the currency "").
+// Porting: keep the path, keep the body, port the core once.
+// docs: https://dev.wix.com/docs/api-reference/business-solutions/donations/donation-campaigns/query-donation-campaigns.md
+// docs: https://dev.wix.com/docs/api-reference/business-solutions/donations/donation-campaigns/get-donation-campaign-metrics.md
+import { WixApiError, wixRequest } from "./client.js";
+import { imgSrc } from "./media.js";
+import { campaignsQuery, currencyOf, isArchived, rawId, toDetail, toSummary, type Raw } from "./donations-core.js";
+import type { CampaignDetail, CampaignSummary } from "./types.js";
+
+const BASE = "/donation-campaigns/v2/donation-campaigns";
+
+// A campaign nobody has donated to yet has no metrics entry, and the entity carries no currency code:
+// the site's currency then comes from the eCommerce settings, read once.
+// GET /_api/ecommerce-settings/v1/ecommerce-settings?fields=BUSINESS_INFO → { ecommerceSettings: { businessInfo: { currency } } }
+// docs: https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/purchase-flow/ecommerce-settings/get-ecommerce-settings.md
+let siteCurrencyPromise: Promise<string> | null = null;
+function siteCurrency(): Promise<string> {
+  siteCurrencyPromise ??= wixRequest<Raw>("/_api/ecommerce-settings/v1/ecommerce-settings", { method: "GET", query: { fields: ["BUSINESS_INFO"] } })
+    .then((res) => String(res?.ecommerceSettings?.businessInfo?.currency ?? ""))
+    .catch(() => { siteCurrencyPromise = null; return ""; });
+  return siteCurrencyPromise;
+}
+
+/** The campaign's currency: the metrics' when a donation exists, else the site's. */
+async function currencyFor(metrics: Raw[]): Promise<string> {
+  return currencyOf(metrics) || (await siteCurrency());
+}
+
+// GET /donation-campaigns/v2/donation-campaigns/{id}/metrics → { currencyMetricsList: [{ currencyCode, donationCount, totalAmount }] }
+async function metricsOf(campaignId: string): Promise<Raw[]> {
+  try {
+    const res = await wixRequest<Raw>(`${BASE}/${campaignId}/metrics`, { method: "GET" });
+    return (res?.currencyMetricsList ?? []) as Raw[];
+  } catch {
+    return []; // metrics are a nicety — the campaign stays correct without them
+  }
+}
+
+/**
+ * The non-archived campaigns, oldest first, as card-ready DTOs.
+ * POST /donation-campaigns/v2/donation-campaigns/query  { query: { filter: { archived: false }, sort: [{ fieldName: "createdDate", order: "ASC" }], cursorPaging: { limit } } }
+ */
+export async function fetchCampaigns({ limit = 100 } = {}): Promise<CampaignSummary[]> {
+  const res = await wixRequest<Raw>(`${BASE}/query`, { body: { query: campaignsQuery({ limit }) } });
+  const items = ((res?.donationCampaigns ?? []) as Raw[]).filter((raw) => !isArchived(raw));
+  const metrics = await Promise.all(items.map((raw) => (raw.campaignGoal ? metricsOf(rawId(raw)) : Promise.resolve([] as Raw[]))));
+  const currencies = await Promise.all(metrics.map(currencyFor));
+  return items.map((raw, i) => toSummary(raw, metrics[i], currencies[i], imgSrc));
+}
+
+/**
+ * One campaign by id with its goal progress and form options; null when not found (404) or archived.
+ * GET /donation-campaigns/v2/donation-campaigns/{id}  → { donationCampaign }
+ */
+export async function fetchCampaign(campaignId: string): Promise<CampaignDetail | null> {
+  let raw: Raw | undefined;
+  try {
+    raw = (await wixRequest<Raw>(`${BASE}/${campaignId}`, { method: "GET" }))?.donationCampaign;
+  } catch (e) {
+    if (e instanceof WixApiError && e.status === 404) return null;
+    throw e;
+  }
+  if (!raw || isArchived(raw)) return null; // an archived campaign is reachable by id but never shows a form
+  const metrics = await metricsOf(campaignId);
+  return toDetail(raw, metrics, await currencyFor(metrics), imgSrc);
+}
+
+/** The Wix widget's default: the first campaign by creation date. Null when the site has none. */
+export async function fetchDefaultCampaign(): Promise<CampaignDetail | null> {
+  const [first] = await fetchCampaigns({ limit: 1 });
+  return first ? fetchCampaign(first.id) : null;
+}

package/skills/wix-headless-templates/donations/rest/donate.ts

@@ -0,0 +1,90 @@
+// The donation flow over REST — the twin of app/wix/donations/donate.ts. Same exports, same
+// signatures; the bodies and result readers come from donations-core (the SAME file the SDK
+// transport uses). A donation is an eCom checkout with one catalog line; the hosted checkout takes
+// payment and donor details. Never create the order yourself, never hand-build a checkout URL.
+// Two routes to a checkout id, both kept: Create Checkout directly (default), and the Wix widget's
+// Create Cart → Create Checkout from the cart (the fallback when the direct route is refused).
+// docs: https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/purchase-flow/checkout/create-checkout.md
+// docs: https://dev.wix.com/docs/api-reference/business-management/headless/redirects/create-redirect-session.md
+// docs: https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/purchase-flow/orders/get-order.md
+import { wixRequest } from "./client.js";
+import {
+  cartBody,
+  checkoutBody,
+  checkoutError,
+  checkoutIdOf,
+  rawId,
+  redirectBody,
+  redirectUrl,
+  toReceipt,
+  type DonatePaths,
+  type Raw,
+} from "./donations-core.js";
+import type { DonationInput, DonationReceipt } from "./types.js";
+
+export type { DonatePaths };
+
+export interface DonateOptions {
+  /** The site's public https origin (default: window.location.origin — call from the browser). */
+  origin?: string;
+  /** Where the hosted checkout returns to; a static site passes its file paths. */
+  paths?: DonatePaths;
+}
+
+/**
+ * Create Checkout with the donation line → checkout id.
+ * POST /ecom/v1/checkouts  { lineItems: [{ quantity: 1, catalogReference: { appId, catalogItemId, options: { amount, frequency, donorCoveringFees? } } }], channelType: "WEB", checkoutInfo?: { buyerNote } }  → { checkout: { id } }
+ */
+export async function createDonationCheckout(campaignId: string, input: DonationInput): Promise<string> {
+  const res = await wixRequest<Raw>("/ecom/v1/checkouts", { body: checkoutBody(campaignId, input) });
+  return checkoutIdOf(res);
+}
+
+/**
+ * The Wix widget's route → checkout id.
+ * POST /ecom/v1/carts  { lineItems, cartInfo?: { buyerNote } }  → { cart: { id } }
+ * POST /ecom/v1/carts/{id}/create-checkout  { channelType: "OTHER_PLATFORM" }  → { checkoutId }
+ */
+export async function createDonationCheckoutViaCart(campaignId: string, input: DonationInput): Promise<string> {
+  const created = await wixRequest<Raw>("/ecom/v1/carts", { body: cartBody(campaignId, input) });
+  const cartId = rawId(created?.cart);
+  if (!cartId) throw new Error("Checkout couldn't start: no cart id returned.");
+  const res = await wixRequest<Raw>(`/ecom/v1/carts/${cartId}/create-checkout`, { body: { channelType: "OTHER_PLATFORM" } });
+  return checkoutIdOf(res);
+}
+
+/**
+ * Start the hosted checkout for a donation; resolves to the URL to navigate the FULL document to.
+ * `origin` must be the site's real https origin as registered on the OAuth app's allowed domains.
+ * POST /headless/v1/redirect-session  { ecomCheckout: { checkoutId }, callbacks: { postFlowUrl, thankYouPageUrl } }  → { redirectSession: { fullUrl } }
+ */
+export async function donationCheckoutUrl(campaignId: string, input: DonationInput, { origin, paths }: DonateOptions = {}): Promise<string> {
+  const site = origin ?? (typeof window !== "undefined" ? window.location.origin : "");
+  let checkoutId: string;
+  try {
+    checkoutId = await createDonationCheckout(campaignId, input);
+  } catch (direct) {
+    try {
+      checkoutId = await createDonationCheckoutViaCart(campaignId, input);
+    } catch {
+      throw checkoutError(direct);
+    }
+  }
+  const session = await wixRequest<Raw>("/headless/v1/redirect-session", { body: redirectBody(checkoutId, campaignId, site, paths) });
+  return redirectUrl(session);
+}
+
+/**
+ * The order behind a completed donation, for the thank-you page; null on any failure (the order may
+ * not be readable with the visitor's token — thank without order facts then).
+ * GET /ecom/v1/orders/{id}  → { order }
+ */
+export async function fetchDonationReceipt(orderId: string): Promise<DonationReceipt | null> {
+  if (!orderId) return null;
+  try {
+    const res = await wixRequest<Raw>(`/ecom/v1/orders/${orderId}`, { method: "GET" });
+    return res?.order ? toReceipt(res.order) : null;
+  } catch {
+    return null;
+  }
+}

package/skills/wix-headless-templates/donations/seed/SEED.md

@@ -0,0 +1,90 @@
+# Donations — seeding
+
+Seed by **running `seed-donations.mjs` with a plan file** — don't hand-write the REST calls. The
+script mints its own site token via the Wix CLI (logged-in session + `wix.config.json` required),
+sets the site currency when the plan names one, installs the eCom platform and the Wix Donations app
+if needed, creates the campaigns, verifies each reads back, then attaches cover images.
+
+```bash
+# from the project root (where wix.config.json lives):
+node <SKILL_ROOT>/templates/donations/seed/seed-donations.mjs plan.json
+```
+
+`plan.json` is plain data — write it from the brief. **Default to one campaign** that exercises every
+form branch: 3 preset amounts with impact text, one-time + monthly, a goal with an end date, a custom
+amount with a minimum, the note and the cover-fee prompt on. A second campaign (say, without a goal)
+only when the brief lists several causes. Every campaign gets a cover image — the default is an
+`imagePrompt` (AI-generated, ~1 Wix AI credit per image, account-billed): brand-contextual — subject,
+mood, palette, lighting — always ending "no text, no watermarks"; a real subject of the cause, not
+abstract decoration. For an asset the user supplied use `imagePath` (a file on this machine) or
+`imageUrl` (their own hosted URL; verify with `curl -sI` → 200) — never a stock or guessed URL.
+Images resolve in parallel and never block the seed; a failed image leaves the campaign text-only.
+
+```json
+{
+  "currency": "USD",
+  "campaigns": [
+    {
+      "name": "Clean Water for Kibera",
+      "frequencies": ["ONE_TIME", "MONTH"],
+      "presets": [
+        { "amount": "25", "impact": "Filters for one family" },
+        { "amount": "50", "impact": "Filters for two families" },
+        { "amount": "100" }
+      ],
+      "customAmount": { "enabled": true, "min": "5", "max": "10000" },
+      "goal": { "target": "20000", "endDate": "2026-12-31T23:59:59Z", "acceptAfterGoal": true, "acceptAfterEndDate": false },
+      "comments": true,
+      "askCoverFee": true,
+      "imagePrompt": "children filling water containers at a village well, warm evening light, documentary photo, no text, no watermarks"
+    }
+  ]
+}
+```
+
+- `name` — 1–65 characters. The campaign has **no description field**: the story copy on the campaign
+  page is the site's own text, written into the page, never seeded.
+- `frequencies` — 1–4 of `ONE_TIME`, `WEEK`, `MONTH`, `YEAR` (default `["ONE_TIME"]`). The form shows a
+  picker only when there is more than one.
+- `presets` — up to 20 `{ amount, impact? }` (a bare `"25"` works too); `amount` a decimal string in the
+  site currency, `impact` ≤ 200 chars — the line shown under the amount. With no presets the custom
+  amount is enabled automatically (custom-only campaign).
+- `customAmount` — `{ enabled, min?, max? }`; a missing limit means none. `enabled: false` needs ≥ 1 preset.
+- `goal` — `{ target, endDate? (ISO), acceptAfterGoal? (default true), acceptAfterEndDate? (default false) }`.
+  Omit for a campaign without a goal (no progress bar). With `acceptAfterGoal: false` the campaign
+  closes at the target; with `acceptAfterEndDate: false` it closes at the deadline.
+- `comments` — the donor note (default false). `askCoverFee` — the "cover the 2.9% fee" prompt (default false).
+- `currency` — 3-letter ISO code at the top of the plan, set **only when the brief names one**: a
+  sentence about currency, or an amount written with its unit ("$25", "€20"). Do **not** infer it from
+  a language, a country, or an address. The seed sets the site to it before creating anything, because
+  every amount is stored in the site currency at create time.
+
+**Seeding is additive and idempotent** — a non-archived campaign with the same name is reused, not
+duplicated; nothing is deleted or overwritten. Ask first if a cleanup seems needed.
+
+## Supplied content
+
+The general rules are in `templates/shared/SUPPLIED-CONTENT.md`. For donations, each cause the user
+lists is one campaign. Its name becomes `name`; listed amounts become `presets` (a sentence beside an
+amount becomes its `impact`); "monthly" / "weekly" / "yearly" adds that frequency; a target becomes
+`goal.target`; a deadline becomes `goal.endDate`; "let people write a message" sets `comments`. Their
+images only (`imagePath` / `imageUrl`) — never an `imagePrompt` beside supplied content.
+
+## What the seed cannot do — tell the owner
+
+- **Completing a donation needs a premium plan and a connected payment method** (dashboard → Accept
+  Payments). The seed creates campaigns on any site; the hosted checkout refuses the payment until
+  then. Recurring frequencies additionally need a payment provider that supports recurring payments.
+- The result JSON's `installed` field says whether each app install succeeded; a Donations install that
+  is refused through the installer API is added from the dashboard's App Market instead.
+- Cover images: the update's Image shape and field-mask requirement were inferred from the SDK, not
+  seen live — a failed attach is listed under `imageErrors`; the owner adds the image in the dashboard.
+
+## Escape hatch — individual functions
+`setupDonations` composes exported steps — `installDonationsApps` (`installApp`), `createCampaigns`
+(`createCampaign`, `findCampaignByName`, `getCampaign`), `setCampaignCoverImage`, `buildCampaign`,
+plus `makeCtx()` — import them only for a partial re-seed.
+
+## Reference
+Unexpected shape or an uncovered operation → read the live Wix API reference; every call the script
+makes carries a `docs:` line with its reference page.

package/skills/wix-headless-templates/donations/seed/read-site.mjs

@@ -0,0 +1,33 @@
+// What the site collects for: non-archived donation campaigns and their goal progress.
+//   node <SKILL_ROOT>/templates/donations/seed/read-site.mjs [--site <siteId>] [--limit <n>]
+import { runReader } from "../../shared/seed/read-site.mjs";
+
+const DONATIONS_APP_ID = "333b456e-dd48-4d6b-b32b-9fd48d74e163";
+const D = "https://dev.wix.com/docs/api-reference/business-solutions/donations/donation-campaigns";
+
+await runReader({
+  vertical: "donations",
+  appId: DONATIONS_APP_ID,
+  async read(api, { limit }) {
+    const r = await api.call({ path: "/donation-campaigns/v2/donation-campaigns/query", body: { query: { filter: { archived: false }, cursorPaging: { limit } } }, docs: `${D}/query-donation-campaigns` });
+    const campaigns = r.donationCampaigns ?? [];
+    const metrics = await Promise.all(campaigns.map((c) => api.tryCall({ method: "GET", path: `/donation-campaigns/v2/donation-campaigns/${c.id}/metrics`, docs: `${D}/get-donation-campaign-metrics` })));
+    return {
+      campaignCount: r.pagingMetadata?.count ?? campaigns.length,
+      campaigns: campaigns.map((c, i) => {
+        const m = metrics[i]?.currencyMetricsList?.[0];
+        return {
+          id: c.id, name: c.name, status: c.status ?? null,
+          frequencies: c.donationFrequencies ?? [],
+          presets: (c.predefinedDonationAmounts ?? []).map((p) => p.price?.formattedAmount ?? p.price?.amount ?? null),
+          customAmount: c.customAmountEnabled ? { min: c.customAmountOptions?.minimum?.amount ?? null, max: c.customAmountOptions?.maximum?.amount ?? null } : false,
+          goal: c.campaignGoal ? { target: c.campaignGoal.targetAmount?.formattedAmount ?? c.campaignGoal.targetAmount?.amount ?? null, endDate: c.campaignGoal.endDate ?? null } : null,
+          raised: m?.totalAmount?.formattedAmount ?? m?.totalAmount?.amount ?? null,
+          donationCount: m?.donationCount ?? null,
+          comments: c.commentsEnabled === true, askCoverFee: c.askDonorCoverFee === true,
+          image: !!c.coverImage,
+        };
+      }),
+    };
+  },
+});