@wix/agent-skills 1.25.0 → 1.27.0

package/skills/wix-headless-templates/donations/project/src/layouts/SiteLayout.astro

@@ -0,0 +1,45 @@
+---
+// The site chrome for every donations 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. (Deploy is fill-only: if another vertical is already deployed, its
+// SiteLayout won — merge a Donate nav link there instead.)
+import "../styles/global.css";
+
+interface Props {
+  title: string;
+  description?: string;
+  /** An absolute image URL for social previews (the campaign's cover). */
+  image?: string;
+}
+const { title, description, image } = 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} />}
+    <meta property="og:title" content={title} />
+    {description && <meta property="og:description" content={description} />}
+    {image && <meta property="og:image" content={image} />}
+    <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">
+          <a href="/donate" class="text-foreground no-underline transition-colors hover:text-muted-foreground">Donate</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/donations/project/src/pages/donate/[id].astro

@@ -0,0 +1,28 @@
+---
+// Campaign page, keyed by the campaign id (the entity has no slug).
+//
+// Donations has no owner-editable SEO item type in @wix/seo, so this page carries plain
+// <title>/<meta>/og:image from the DTO — no wixMetadata, no <SEO.Tags>; campaign pages don't
+// appear in the Wix SEO panel or sitemap. A missing or archived campaign is a real 404.
+import SiteLayout from "../../layouts/SiteLayout.astro";
+import CampaignPage from "../../components/donations/CampaignPage.astro";
+import { fetchCampaign } from "../../wix/donations/campaigns";
+import type { CampaignDetail } from "../../wix/donations/types";
+
+const id = Astro.params.id!;
+
+let campaign: CampaignDetail | null = null;
+try {
+  campaign = await fetchCampaign(id);
+} catch {
+  // Guarded: an unhandled SSR throw truncates the response mid-stream.
+}
+
+if (!campaign) {
+  return new Response(null, { status: 404 });
+}
+---
+
+<SiteLayout title={campaign.name} image={campaign.imageUrl || undefined}>
+  <CampaignPage campaign={campaign} />
+</SiteLayout>

package/skills/wix-headless-templates/donations/project/src/pages/donate/index.astro

@@ -0,0 +1,51 @@
+---
+// Donate — the campaigns, fetched SERVER-SIDE and rendered as cards; a site with exactly one
+// campaign renders that campaign's page here directly (the Wix widget's default-campaign rule).
+// Keep this frontmatter; the card markup is yours to redesign (GoalProgress is the shipped part).
+import SiteLayout from "../../layouts/SiteLayout.astro";
+import CampaignPage from "../../components/donations/CampaignPage.astro";
+import GoalProgress from "../../components/donations/GoalProgress";
+import { fetchCampaign, fetchCampaigns } from "../../wix/donations/campaigns";
+import type { CampaignDetail, CampaignSummary } from "../../wix/donations/types";
+
+let campaigns: CampaignSummary[] = [];
+let only: CampaignDetail | null = null;
+try {
+  campaigns = await fetchCampaigns();
+  if (campaigns.length === 1) only = await fetchCampaign(campaigns[0].id);
+} catch {
+  // An unguarded SSR throw truncates the response mid-stream; the page renders its empty state instead.
+}
+---
+
+<SiteLayout title={only ? only.name : "Donate"} image={only?.imageUrl || undefined}>
+  {only ? (
+    <CampaignPage campaign={only} />
+  ) : (
+    <>
+      <h1 class="mb-8 text-2xl font-semibold tracking-tight">Donate</h1>
+      {campaigns.length === 0 ? (
+        <p class="py-16 text-center text-muted-foreground">No campaigns yet — check back soon.</p>
+      ) : (
+        <div class="grid grid-cols-1 gap-6 sm:grid-cols-2 lg:grid-cols-3">
+          {campaigns.map((c) => (
+            <a href={`/donate/${c.id}`} class="flex h-full flex-col overflow-hidden rounded-lg border border-border bg-background no-underline transition-colors hover:bg-secondary">
+              {c.imageUrl && (
+                <div class="aspect-[16/9] bg-secondary">
+                  <img src={c.imageUrl} alt={c.name} loading="lazy" class="h-full w-full object-cover" />
+                </div>
+              )}
+              <div class="flex flex-1 flex-col gap-4 p-6">
+                <p class="text-base font-semibold text-foreground">{c.name}</p>
+                <GoalProgress goal={c.goal} compact />
+                <p class="mt-auto text-sm font-semibold text-foreground">
+                  {c.acceptsDonations ? "Donate" : c.status === "goalReached" ? "Goal reached" : "Ended"}
+                </p>
+              </div>
+            </a>
+          ))}
+        </div>
+      )}
+    </>
+  )}
+</SiteLayout>

package/skills/wix-headless-templates/donations/project/src/pages/donate/thank-you.astro

@@ -0,0 +1,13 @@
+---
+// Post-checkout thank-you page — the Wix-hosted checkout redirects here with ?orderId= after a
+// completed donation. KEEP THIS ROUTE: the data layer's redirect callbacks point at
+// /donate/thank-you. No SSR fetch: the order read runs as the visitor in the browser, so the island
+// is client:only. Swap its import to YOUR thank-you component if you design one — keep its rules
+// (no order facts without the order; never "paid" unless the order says so).
+import SiteLayout from "../../layouts/SiteLayout.astro";
+import DonationReceipt from "../../components/donations/DonationReceipt";
+---
+
+<SiteLayout title="Thank you">
+  <DonationReceipt client:only="react" />
+</SiteLayout>

package/skills/wix-headless-templates/donations/project/src/pages/index.astro

@@ -0,0 +1,8 @@
+---
+import Hero from '../components/Hero.astro';
+import Layout from '../layouts/Layout.astro';
+---
+
+<Layout>
+	<Hero />
+</Layout>

package/skills/wix-headless-templates/donations/project/src/styles/global.css

@@ -0,0 +1,57 @@
+@import url('https://fonts.googleapis.com/css2?family=Wix+Madefor+Text:wght@400;500;600;700;800&display=swap');
+@import 'tailwindcss';
+
+/* ─── THE design system ─────────────────────────────────────────────────────────────────
+   Theme the entire store by editing THIS @theme block (same token family as the official
+   Wix headless templates). Every shipped component styles itself from these via Tailwind
+   utilities (bg-primary, text-muted-foreground, text-destructive, rounded-lg, …) — change a token, everything
+   follows. A dark theme is just flipped values (dark background/foreground, adjusted
+   secondary/border). Don't restyle shipped component markup; restyle the tokens.
+
+   Choosing values: argue polarity from the business — light is not "cheap" (wellness/food
+   usually read better light); never dark-by-default for "premium". Palette: one dominant +
+   accents from ADJACENT hues (~30° arc), 2-4 colors total. Every background/foreground pair
+   you set must hit WCAG 4.5:1 (3:1 for text ≥24px); body copy never below 16px/1.5. Derive
+   from THIS brand — a look repeated across projects is a failure, not a shortcut. The user's
+   explicit direction beats all of this except the contrast floor. */
+@theme {
+  --color-background: hsl(0 0% 100%);
+  --color-foreground: hsl(230 24% 14%);
+  --color-primary: hsl(230 24% 14%);
+  --color-primary-foreground: hsl(0 0% 100%);
+  --color-secondary: hsl(228 24% 96%);
+  --color-secondary-foreground: hsl(230 24% 14%);
+  --color-muted-foreground: hsl(228 8% 46%);
+  --color-border: hsl(220 14% 90%);
+  --color-destructive: hsl(0 72% 51%);
+
+  --radius-lg: 12px;
+  --radius-md: 8px;
+  --radius-sm: 6px;
+  /* Buttons, chips, labels, steppers and the progress bar. Follows --radius-md unless the brand
+     wants otherwise: 9999px is the pill, 0 is square. Genuine circles (swatches, avatars, dots)
+     stay rounded-full and do not read this. */
+  --radius-control: var(--radius-md);
+
+  --font-sans: 'Wix Madefor Text', system-ui, sans-serif;
+}
+
+@layer base {
+  body {
+    background-color: var(--color-background);
+    color: var(--color-foreground);
+    font-family: var(--font-sans);
+    -webkit-font-smoothing: antialiased;
+    font-feature-settings: 'cv02', 'cv03', 'cv04', 'cv11';
+  }
+}
+
+@layer utilities {
+  .eyebrow {
+    font-size: 0.8125rem;
+    font-weight: 600;
+    letter-spacing: 0.1em;
+    text-transform: uppercase;
+    color: var(--color-muted-foreground);
+  }
+}

package/skills/wix-headless-templates/donations/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/donations/project/src/wix/donations/campaigns-store.ts

@@ -0,0 +1,59 @@
+// The campaigns listing as a framework-free store — the logic behind useCampaigns, usable from
+// React (useCampaigns wraps it with useSyncExternalStore), from a static page or Vue/Svelte
+// (subscribe and render), or as the specification for a port.
+//
+// SSR-friendly: seed with `initialCampaigns` and they render at once with no client fetch; without
+// a seed `start()` fetches the non-archived campaigns. A failed load leaves `campaigns: []` with the
+// message in `error`, so the surface renders its empty state and the message, never a skeleton
+// forever. One store per mounted listing: createCampaignsStore(), not a singleton.
+import { fetchCampaigns } from "./campaigns";
+import type { CampaignSummary } from "./types";
+
+export interface CampaignsStoreOptions {
+  initialCampaigns?: CampaignSummary[];
+}
+
+export interface CampaignsState {
+  /** null while the first load is in flight — render skeletons, not an empty state. */
+  campaigns: CampaignSummary[] | null;
+  error: string | null;
+}
+
+export interface CampaignsStore {
+  getState(): CampaignsState;
+  subscribe(listener: () => void): () => void;
+  /** Fetch the campaigns when no `initialCampaigns` were given. Call once when mounted (a browser). */
+  start(): void;
+  /** Stop reacting; drop a late response. */
+  stop(): void;
+}
+
+export function createCampaignsStore({ initialCampaigns }: CampaignsStoreOptions = {}): CampaignsStore {
+  let state: CampaignsState = { campaigns: initialCampaigns ?? null, error: null };
+  let started = false;
+  const listeners = new Set<() => void>();
+
+  function setState(patch: Partial<CampaignsState>): void {
+    state = { ...state, ...patch };
+    for (const fn of listeners) fn();
+  }
+
+  return {
+    getState: () => state,
+    subscribe(fn) {
+      listeners.add(fn);
+      return () => listeners.delete(fn);
+    },
+    start() {
+      if (started) return;
+      started = true;
+      if (initialCampaigns) return;
+      fetchCampaigns()
+        .then((campaigns) => { if (started) setState({ campaigns }); })
+        .catch((e) => { if (started) setState({ campaigns: [], error: e instanceof Error ? e.message : String(e) }); });
+    },
+    stop() {
+      started = false;
+    },
+  };
+}

package/skills/wix-headless-templates/donations/project/src/wix/donations/campaigns.ts

@@ -0,0 +1,83 @@
+// Campaign reads (Wix Donations, Donation Campaigns) over the SDK — the only file that touches raw
+// campaign entities on this transport. Everything it returns is a plain DTO from ./types. The rules
+// and mappers live in ./donations-core (shared with the REST twin in templates/donations/rest/);
+// this file is the transport only. Copy as-is; extend by adding functions, not by editing these.
+//
+// The metrics read (raised total, donation count, the site currency) is guarded: a refusal for the
+// visitor's token leaves `goal.raised` "" and `options.currency` "" — the page still renders from
+// the campaign's own formatted amounts. Whether an anonymous visitor may read metrics is not yet
+// verified against a live site.
+// 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 { donationCampaigns } from "@wix/donations";
+import { ecommerceSettings } from "@wix/ecom";
+import { wixModule } from "../sdk";
+import { imgSrc } from "../media";
+import { currencyOf, isArchived, rawId, toDetail, toSummary, type Raw } from "./donations-core";
+import type { CampaignDetail, CampaignSummary } from "./types";
+
+const campaignsApi = wixModule(donationCampaigns);
+const settingsApi = wixModule(ecommerceSettings);
+
+// The metrics list is EMPTY on a campaign nobody has donated to yet, and the campaign entity carries
+// formatted amounts but no currency code — so a fresh site would format nothing. The site's currency
+// comes from the eCommerce settings then (BUSINESS_INFO), read once per process; "" when refused.
+// 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 ??= settingsApi
+    .getEcommerceSettings(["BUSINESS_INFO"])
+    .then((res: Raw) => 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());
+}
+
+async function metricsOf(campaignId: string): Promise<Raw[]> {
+  try {
+    const res: Raw = await campaignsApi.getDonationCampaignMetrics(campaignId);
+    return (res?.currencyMetricsList ?? []) as Raw[];
+  } catch {
+    return []; // metrics are a nicety — the campaign stays correct without them
+  }
+}
+
+const isNotFound = (e: unknown): boolean => {
+  const err = e as Raw;
+  const code = err?.details?.applicationError?.code ?? err?.code;
+  const msg = String(err?.message ?? "");
+  return code === "NOT_FOUND" || err?.status === 404 || /not.?found|404/i.test(msg);
+};
+
+/** List the non-archived campaigns, oldest first, as card-ready DTOs (goal progress joined per campaign). */
+export async function fetchCampaigns({ limit = 100 } = {}): Promise<CampaignSummary[]> {
+  const res = await campaignsApi.queryDonationCampaigns().eq("archived", false).ascending("_createdDate").limit(limit).find();
+  const items = ((res.items ?? []) 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 or archived. */
+export async function fetchCampaign(campaignId: string): Promise<CampaignDetail | null> {
+  let raw: Raw | undefined;
+  try {
+    raw = (await campaignsApi.getDonationCampaign(campaignId)) as Raw;
+  } catch (e) {
+    if (isNotFound(e)) 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/project/src/wix/donations/donate.ts

@@ -0,0 +1,95 @@
+// The donation flow over the SDK: a visitor's choice → an eCom checkout with one donation line →
+// the Wix-hosted checkout URL; and the thank-you page's order read. Payment, donor details and
+// receipts are Wix's hosted checkout and the eCom order — nothing here creates an order or builds
+// a URL by hand. Bodies and result readers live in ./donations-core (shared with the REST twin);
+// this file is the transport only. Copy as-is.
+//
+// Two routes to a checkout id, both kept:
+//   createDonationCheckout        — Create Checkout with the line (a donation never merges into a
+//                                   storefront visitor's current cart). The default.
+//   createDonationCheckoutViaCart — the Wix widget's own sequence: Create Cart → Create Checkout
+//                                   from the cart, channelType OTHER_PLATFORM. The fallback when
+//                                   the direct route is refused; also reachable by name.
+// Whether the Donations catalog plugin prices a line created directly is not yet verified live,
+// hence the automatic fallback.
+// 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 { cart as cartModule, checkout as checkoutModule, orders as ordersModule } from "@wix/ecom";
+import { redirects as redirectsModule } from "@wix/redirects";
+import { wixModule } from "../sdk";
+import {
+  cartBody,
+  checkoutBody,
+  checkoutError,
+  checkoutIdOf,
+  rawId,
+  redirectBody,
+  redirectUrl,
+  toReceipt,
+  type DonatePaths,
+  type Raw,
+} from "./donations-core";
+import type { DonationInput, DonationReceipt } from "./types";
+
+export type { DonatePaths };
+
+const checkoutApi = wixModule(checkoutModule);
+const cartApi = wixModule(cartModule);
+const ordersApi = wixModule(ordersModule);
+const redirects = wixModule(redirectsModule);
+
+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; defaults are the Astro routes. */
+  paths?: DonatePaths;
+}
+
+/** Create Checkout with the donation line → checkout id. */
+export async function createDonationCheckout(campaignId: string, input: DonationInput): Promise<string> {
+  const checkout: Raw = await checkoutApi.createCheckout(checkoutBody(campaignId, input) as any);
+  return checkoutIdOf(checkout);
+}
+
+/** The Wix widget's route: Create Cart (the note as buyerNote) → Create Checkout from the cart → checkout id. */
+export async function createDonationCheckoutViaCart(campaignId: string, input: DonationInput): Promise<string> {
+  const cart: Raw = await cartApi.createCart(cartBody(campaignId, input) as any);
+  const res: Raw = await cartApi.createCheckout(rawId(cart), { channelType: "OTHER_PLATFORM" });
+  return checkoutIdOf(res);
+}
+
+/**
+ * Start the hosted checkout for a donation; resolves to the URL to navigate the FULL document to.
+ * Direct Create Checkout first, the cart route when that is refused, then one redirect session
+ * whose thank-you callback lands on `/donate/thank-you?orderId=`.
+ */
+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: Raw = await redirects.createRedirectSession(redirectBody(checkoutId, campaignId, site, paths) as any);
+  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 — the page then thanks without order facts.
+ */
+export async function fetchDonationReceipt(orderId: string): Promise<DonationReceipt | null> {
+  if (!orderId) return null;
+  try {
+    const order: Raw = await ordersApi.getOrder(orderId);
+    return order ? toReceipt(order) : null;
+  } catch {
+    return null;
+  }
+}

package/skills/wix-headless-templates/donations/project/src/wix/donations/donation-store.ts

@@ -0,0 +1,163 @@
+// The donate form for one campaign as a framework-free store — the logic behind useDonation,
+// usable from React (the hook wraps it), from a static page's campaign view, from Vue/Svelte, or as
+// the specification for a port. Frequency, preset or custom amount, the fee, the note, validation
+// with the widget's codes, the live button label, and donate() which navigates the FULL document
+// to the Wix-hosted checkout. All correctness (the line item, the checkout, the redirect session)
+// lives in the data layer; every rule (defaults, validation, fee, label) in donations-core.
+//
+// One store per campaign surface: createDonationStore(campaign), not a singleton. A static site
+// passes `paths` so the hosted checkout returns to its files (`thank-you.html`).
+import { donationCheckoutUrl, type DonatePaths } from "./donate";
+import {
+  defaultSelection,
+  donateLabel,
+  errorMessage,
+  feeFor,
+  formatAmount,
+  selectedAmount,
+  toInput,
+  totalFor,
+  validateDonation,
+  type DonationField,
+  type DonationSelection,
+} from "./donations-core";
+import type { CampaignDetail, DonationErrorCode, DonationFrequency } from "./types";
+
+export interface DonationStoreOptions {
+  /** The site's public https origin (default: window.location.origin). */
+  origin?: string;
+  /** Where the hosted checkout returns to; defaults are the Astro routes. */
+  paths?: DonatePaths;
+}
+
+/** Everything a donate form renders from. Read it with getState() or through a subscription. */
+export interface DonationState extends DonationSelection {
+  /** The amount in play: the preset, or the parsed custom text (null when none / unparsable). */
+  amount: number | null;
+  /** The donor's 2.9% fee — only when the owner asks and the donor agreed; null otherwise. */
+  fee: number | null;
+  /** Formatted fee for the checkbox label ("$0.73"); "" when none or the currency is unknown. */
+  feeLabel: string;
+  /** amount + fee. */
+  total: number | null;
+  /** Formatted total; "" when no amount or the currency is unknown. */
+  totalLabel: string;
+  /** "Donate $25 Monthly" — the CTA's text. */
+  buttonLabel: string;
+  errors: Partial<Record<DonationField, DonationErrorCode>>;
+  /** Visitor-facing text per field error. */
+  messages: Partial<Record<DonationField, string>>;
+  /** True after the first donate() attempt — show `messages` only then (the widget's hasSubmitted). */
+  showErrors: boolean;
+  valid: boolean;
+  /** True while the checkout is being created and the browser is leaving; stays true on success. */
+  submitting: boolean;
+  /** The last checkout failure, visitor-facing; a new donate() clears it. */
+  error: string | null;
+  /** campaign.acceptsDonations — false renders the closed state, never the form. */
+  available: boolean;
+}
+
+export interface DonationStore {
+  getState(): DonationState;
+  subscribe(listener: () => void): () => void;
+  /** Pick a preset amount; leaves custom mode and clears the custom text. */
+  selectPreset(amount: number): void;
+  /** Activate "Other amount". */
+  selectCustom(): void;
+  setCustomAmount(text: string): void;
+  setFrequency(frequency: DonationFrequency): void;
+  setCoverFee(coverFee: boolean): void;
+  setNote(note: string): void;
+  /**
+   * Validate, then start the hosted checkout — when it resolves the browser is already navigating
+   * away (or validation failed and `messages` are showing). Rejects (and records `error`) when the
+   * checkout couldn't start or the campaign isn't accepting donations — surface it.
+   */
+  donate(): Promise<void>;
+}
+
+export function createDonationStore(campaign: CampaignDetail, { origin, paths }: DonationStoreOptions = {}): DonationStore {
+  const options = campaign.options;
+  let sel: DonationSelection = defaultSelection(options);
+  let showErrors = false;
+  let submitting = false;
+  let error: string | null = null;
+  const listeners = new Set<() => void>();
+
+  const derive = (): DonationState => {
+    const amount = selectedAmount(sel);
+    const fee = options.askCoverFee && sel.coverFee ? feeFor(amount) : null;
+    const total = totalFor(amount, sel.coverFee, options.askCoverFee);
+    const errors = validateDonation(options, sel);
+    const messages: Partial<Record<DonationField, string>> = {};
+    for (const [field, code] of Object.entries(errors) as [DonationField, DonationErrorCode][]) messages[field] = errorMessage(code, options);
+    return {
+      ...sel,
+      amount,
+      fee,
+      feeLabel: formatAmount(fee, options.currency),
+      total,
+      totalLabel: formatAmount(total, options.currency),
+      buttonLabel: donateLabel(total, sel.frequency, options.currency),
+      errors,
+      messages,
+      showErrors,
+      valid: Object.keys(errors).length === 0,
+      submitting,
+      error,
+      available: campaign.acceptsDonations,
+    };
+  };
+
+  let state = derive();
+  const emit = (): void => {
+    state = derive();
+    for (const fn of listeners) fn();
+  };
+  const update = (patch: Partial<DonationSelection>): void => {
+    if (submitting) return;
+    sel = { ...sel, ...patch };
+    emit();
+  };
+
+  return {
+    getState: () => state,
+    subscribe(fn) {
+      listeners.add(fn);
+      return () => listeners.delete(fn);
+    },
+    selectPreset: (amount) => update({ presetAmount: amount, customMode: false, customAmount: "" }),
+    selectCustom: () => update({ customMode: true, presetAmount: null }),
+    setCustomAmount: (text) => update({ customAmount: text }),
+    setFrequency: (frequency) => update({ frequency }),
+    setCoverFee: (coverFee) => update({ coverFee }),
+    setNote: (note) => update({ note: note.slice(0, options.commentMaxLength) }),
+    async donate() {
+      if (submitting) return; // a second click while the checkout is being created is ignored
+      showErrors = true;
+      error = null;
+      if (!campaign.acceptsDonations) {
+        error = "This campaign isn't accepting donations right now.";
+        emit();
+        throw new Error(error);
+      }
+      const input = toInput(options, sel);
+      if (!input) {
+        emit();
+        return;
+      }
+      submitting = true;
+      emit();
+      try {
+        window.location.href = await donationCheckoutUrl(campaign.id, input, { origin, paths });
+        // stays "submitting" — the browser is leaving for the hosted checkout
+      } catch (e) {
+        submitting = false;
+        error = e instanceof Error ? e.message : String(e);
+        emit();
+        throw e;
+      }
+    },
+  };
+}