@wix/agent-skills 1.33.0 → 1.34.0

package/skills/wix-vibe-headless/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: wix-vibe-headless
-description: "Client-only, dependency-free REST scaffolds for connecting an already-built front end (a vibe-coded app, an HTML/JSX/Vite project, a design-tool export) to a live Wix site over the site's public WIX_CLIENT_ID — the browser talks to Wix directly, no SDK, no backend, no build step. One skill covering every Wix business solution: Stores/eCommerce storefront (products, cart, checkout), Bookings (services, slots, appointments), Blog (posts, categories, tags), Events & Tickets (browse, RSVP, ticketing), Portfolio (collections, projects, galleries), Restaurants (menu, online ordering, reservations), Forms (any visitor-fillable form — contact/enquiry, signup, waitlist, application, survey, quote request; schema-driven render + submit), CMS / Wix Data (list, detail, filter, CRUD), Pricing Plans (memberships, subscriptions, checkout), and Members (custom login — email+password, Google/Facebook, and custom SSO — plus account areas and member-gated content). Each vertical ships a copy-as-is REST layer plus wiring instructions. Read-only over the owner's content — never provisions, never mocks data. Triggers: connect my Wix store/shop, build a storefront over Wix, add a cart and checkout, connect Wix Bookings, take appointments/reservations, show my Wix blog, list my Wix events, sell tickets, take RSVPs, build a portfolio from Wix Portfolio, show my restaurant menu / order online / book a table, display my Wix CMS collection, wire a contact form to Wix, add a contact/enquiry form, build a signup or application form, take survey responses, sell membership/subscription plans, add member login / sign up, let members log in with Google or Facebook, custom login page, account / profile page, gate content behind login, sign in with SSO/Okta, 'here is my WIX_CLIENT_ID', connect this app to my Wix site over REST. Use this for CLIENT-ONLY REST integration over an existing site; use `wix-headless` instead for SDK + Wix CLI builds, hosting, and one-prompt new-site creation."
+description: "Connect an existing front end to a live Wix site using client-only REST and its public WIX_CLIENT_ID, without an SDK or backend. Covers Stores/cart/checkout, Bookings and Rentals, Blog, Events and tickets, Portfolio, Restaurants, Donations, Forms, CMS, Pricing Plans, and Members with login, social/SSO and gated content. Use when wiring Wix business data and buyer flows into a vibe-coded app, HTML/JSX/Vite project or design export: shopping, appointments, donations, form submissions, memberships, restaurant orders/reservations and member accounts. Ships dependency-free helpers and wiring guides; never provisions or changes owner content and never mocks data. Use wix-headless instead for SDK integration, Wix CLI builds, hosting or new-site creation."
 ---
 
 # Wix Vibe Headless — client-only REST connectors
@@ -46,6 +46,8 @@ This skill is the deliberately **client-only, REST-only** path. It is independen
   formattedValue }`. Render **`formattedValue`** (it already includes the currency symbol), or
   fall back to building from `value` + `currency`. **Never** drop the object straight into the UI
   or treat it as a number/string — that renders `[object Object]` or a bare unformatted number.
+  **Donations exception:** campaign prices use `{ amount, formattedAmount }`, with a decimal-string
+  `amount`; donation cart `options.amount` must instead be a JSON number. Follow the Donations recipe.
 - **Visitor token = identity.** `wix-client.js` mints an anonymous visitor token, persists the
   **refresh token to `localStorage`**, and refreshes on expiry. That token IS the identity of
   the cart / reservation / member session — **never re-mint anonymously per load** or the cart
@@ -120,18 +122,19 @@ Each vertical's integration files ship in `references/<vertical>/app/`; copy tha
 | The user wants… | Vertical | Read |
 |---|---|---|
 | Online store: products, categories, cart, checkout | **storefront** | `references/storefront/INSTRUCTIONS.md` |
+| Donations: fundraising campaigns, one-time or recurring giving, hosted checkout | **donations** | `references/donations/INSTRUCTIONS.md` |
 | Appointments: services, time slots, booking, checkout — **and the form attached to a bookable service** | **bookings** | `references/bookings/INSTRUCTIONS.md` |
 | Rentals: an item hired for a length **the customer picks** (by the hour or by the day) — Wix Rentals runs on the Bookings APIs, so it is the same vertical | **bookings** | `references/bookings/INSTRUCTIONS.md` ("Rentals") |
 | Blog/news: post feed, post pages, categories, tags | **blog** | `references/blog/INSTRUCTIONS.md` |
 | Events: browse, event page, RSVP, ticketing — **an RSVP is here, not `forms`**, even for one occasion with no tickets | **events** | `references/events/INSTRUCTIONS.md` |
 | Portfolio/showcase: collections, projects, media galleries | **portfolio** | `references/portfolio/INSTRUCTIONS.md` |
 | Restaurant: menu, online ordering, table reservations | **restaurants** | `references/restaurants/INSTRUCTIONS.md` |
-| Any visitor-fillable form: contact/enquiry, lead, signup, waitlist, application, feedback/survey, quote request, intake or registration. **Not** an event RSVP (`events`) or a per-service booking form (`bookings`) | **forms** | `references/forms/INSTRUCTIONS.md` |
+| Any visitor-fillable form: contact/enquiry, lead, signup, waitlist, application, feedback/survey, quote request, intake or registration. **Not** an event RSVP (`events`), per-service booking form (`bookings`) or donation contribution (`donations`) | **forms** | `references/forms/INSTRUCTIONS.md` |
 | CMS content: list/detail, filter/search, data CRUD. **A visitor-fillable form is `forms`** — cms only when the app must read the entries back | **cms** | `references/cms/INSTRUCTIONS.md` |
 | Plans & pricing: memberships/subscriptions, subscribe, my plans | **pricing-plans** | `references/pricing-plans/INSTRUCTIONS.md` |
 | Member accounts: custom login/sign-up (email+password, Google/Facebook, SSO), account area, gated content | **members** | `references/members/INSTRUCTIONS.md` |
 
-**⚠️ Anything a visitor fills in and submits is `forms` — with three exceptions:**
+**⚠️ Anything a visitor fills in and submits is `forms` — with four exceptions:**
 
 1. **The app must read the entries back → `cms`.** A public gallery, a listing, a member's "my
    submissions". A visitor cannot read Forms submissions, so those need a collection. Submit-only is
@@ -142,6 +145,7 @@ Each vertical's integration files ship in `references/<vertical>/app/`; copy tha
    events ships a built-in RSVP registration form. Route there even for a single occasion with no
    tickets.
 3. **A form attached to a bookable service → `bookings`.**
+4. **A contribution to a donation campaign → `donations`.** Recurring giving is not a Pricing Plans purchase; the donation form must preserve the campaign's amount/frequency rules and use its catalog reference.
 
 ### When the request doesn't name a Wix Business Solution — ask, or check the site
 

package/skills/wix-vibe-headless/install/deploy.cjs

@@ -1,6 +1,6 @@
 // Post-install deploy — run by base44.md STEP 1 with the vertical(s) the app needs:
 //   node deploy.cjs <vertical> [<vertical> …] --client-id <id> --metasite-id <id>
-//   (storefront | bookings | blog | cms | forms | portfolio | pricing-plans | events | members | restaurants)
+//   (storefront | bookings | blog | cms | forms | portfolio | pricing-plans | events | members | restaurants | donations)
 // Pass the two ids from the prompt and this writes src/rest/wix-config.js for you — see WRITE below.
 // Retyping those ids into the file by hand is how a storefront ships with a dead client id.
 // ONE mechanism: recursively copy `app/` -> /app/src. The shared transport (app/rest/wix-client.js,
@@ -16,17 +16,36 @@
 // NOTE: .cjs on purpose — the app is an ESM package ("type":"module"); a .js here would load as ESM
 // and require()/module.exports would throw.
 const { existsSync, cpSync, mkdirSync, readFileSync, writeFileSync } = require('fs');
+const { createHash } = require('crypto');
 
 const REF = '/app/.agents/skills/wix-vibe-headless/references';
 const WIX_CONFIG = '/app/src/rest/wix-config.js';
 const NAV_ADAPTER = '/app/src/lib/nav.js';
-const VERTICALS = ['storefront', 'bookings', 'blog', 'cms', 'forms', 'portfolio', 'pricing-plans', 'events', 'members', 'restaurants'];
+const VERTICALS = ['storefront', 'bookings', 'blog', 'cms', 'forms', 'portfolio', 'pricing-plans', 'events', 'members', 'restaurants', 'donations'];
 
 // force:false + errorOnExist:false — fill in only files that AREN'T there yet; never overwrite.
 // A re-run (e.g. the "files missing? re-run" fallback) then restores what's missing without
 // clobbering the agent's edits (wired App.jsx, home/header components) from the first deploy.
 const COPY = { recursive: true, force: false, errorOnExist: false };
 
+// Only this exact shipped legacy transport is safe to replace. Any customization needs a merge.
+const LEGACY_TRANSPORT_SHA256 = '10d53e5e06ac3da62f93d41cfd618b6169c5bb1a5ba07fb58ec7700aad42889e';
+function prepareDonationsTransport() {
+  const src = `${REF}/shared/app/rest/wix-client.js`;
+  const dest = '/app/src/rest/wix-client.js';
+  if (!existsSync(src)) return { error: 'Donations needs the shared Wix transport. Reinstall the skill and retry deployment.' };
+  if (!existsSync(dest)) return { status: 'from_shared_tree' };
+  const existing = readFileSync(dest, 'utf8');
+  if (/^export const WIX_API_SUPPORTS_STRICT_PAYMENT_ERRORS = true;$/m.test(existing)) {
+    return { status: 'already_supported' };
+  }
+  if (createHash('sha256').update(existing).digest('hex') === LEGACY_TRANSPORT_SHA256) {
+    cpSync(src, dest, { force: true });
+    return { status: 'upgraded_unmodified_legacy' };
+  }
+  return { error: 'Donations was not deployed: src/rest/wix-client.js is customized or incompatible and was left unchanged. Merge strict payment-error support and the WIX_API_SUPPORTS_STRICT_PAYMENT_ERRORS export from the shared transport, then re-run deployment.' };
+}
+
 // --- members vertical only: replace leftover Base44 auth pages -------------------------------
 //
 // Base44 seeds src/pages/Login.jsx + src/pages/Register.jsx into every custom-auth-enrolled app
@@ -155,40 +174,48 @@ const deployed = { verticals: [] };
 const aliased = [...new Set(positional.filter((a) => ALIASES[a]))].map((a) => `${a} -> ${ALIASES[a]}`);
 if (aliased.length) deployed.aliased = aliased;
 
-// Nav adapter — before the shared copy, which carries the react-router default at the same path.
-deployed.template = detectTemplate();
-deployed.navAdapter = installNavAdapter(deployed.template);
-
-// Shared transport — always (app/rest/wix-client.js, wix-config.js -> src/rest/, lib/nav.js).
-if (existsSync(`${REF}/shared/app`)) cpSync(`${REF}/shared/app`, '/app/src', COPY);
-
-// Each named vertical — its app/ (UI + app/rest/ helpers) -> src/.
-const unknown = requested.filter((v) => !VERTICALS.includes(v));
-for (const vertical of requested.filter((v) => VERTICALS.includes(v))) {
-  if (!existsSync(`${REF}/${vertical}/app`)) continue;
-  cpSync(`${REF}/${vertical}/app`, '/app/src', COPY);
-  deployed.verticals.push(vertical);
-  if (vertical === 'members') deployed.authPagesFixed = replaceMembersAuthLeftovers();
-}
-
-if (unknown.length) {
-  deployed.error = `unknown vertical(s) ${unknown.map((v) => `"${v}"`).join(', ')} — expected: ${VERTICALS.join(', ')}`;
-}
-if (!requested.length) {
-  deployed.note = 'no vertical given — deployed the shared transport only; re-run: node deploy.cjs <vertical> [<vertical> …]';
-}
+const donationsTransport = requested.includes('donations') ? prepareDonationsTransport() : null;
+if (donationsTransport?.error) {
+  deployed.error = donationsTransport.error;
+  process.exitCode = 1;
+} else {
+  if (donationsTransport) deployed.donationsTransport = donationsTransport.status;
+
+  // Nav adapter — before the shared copy, which carries the react-router default at the same path.
+  deployed.template = detectTemplate();
+  deployed.navAdapter = installNavAdapter(deployed.template);
+
+  // Shared transport — always (app/rest/wix-client.js, wix-config.js -> src/rest/, lib/nav.js).
+  if (existsSync(`${REF}/shared/app`)) cpSync(`${REF}/shared/app`, '/app/src', COPY);
+
+  // Each named vertical — its app/ (UI + app/rest/ helpers) -> src/.
+  const unknown = requested.filter((v) => !VERTICALS.includes(v));
+  for (const vertical of requested.filter((v) => VERTICALS.includes(v))) {
+    if (!existsSync(`${REF}/${vertical}/app`)) continue;
+    cpSync(`${REF}/${vertical}/app`, '/app/src', COPY);
+    deployed.verticals.push(vertical);
+    if (vertical === 'members') deployed.authPagesFixed = replaceMembersAuthLeftovers();
+  }
 
-const onDisk = readWixConfig();
-const finalClientId = onDisk.clientId || clientId;
-const finalMetaSiteId = onDisk.metaSiteId || metaSiteId;
+  if (unknown.length) {
+    deployed.error = `unknown vertical(s) ${unknown.map((v) => `"${v}"`).join(', ')} — expected: ${VERTICALS.join(', ')}`;
+  }
+  if (!requested.length) {
+    deployed.note = 'no vertical given — deployed the shared transport only; re-run: node deploy.cjs <vertical> [<vertical> …]';
+  }
 
-if (!finalClientId || !finalMetaSiteId) {
-  deployed.wixConfig = 'skipped — no ids provided';
-} else if (finalClientId === onDisk.clientId && finalMetaSiteId === onDisk.metaSiteId) {
-  deployed.wixConfig = 'already_set';
-} else {
-  writeWixConfig(finalClientId, finalMetaSiteId);
-  deployed.wixConfig = 'written';
+  const onDisk = readWixConfig();
+  const finalClientId = onDisk.clientId || clientId;
+  const finalMetaSiteId = onDisk.metaSiteId || metaSiteId;
+
+  if (!finalClientId || !finalMetaSiteId) {
+    deployed.wixConfig = 'skipped — no ids provided';
+  } else if (finalClientId === onDisk.clientId && finalMetaSiteId === onDisk.metaSiteId) {
+    deployed.wixConfig = 'already_set';
+  } else {
+    writeWixConfig(finalClientId, finalMetaSiteId);
+    deployed.wixConfig = 'written';
+  }
 }
 
 console.log(JSON.stringify(deployed));

package/skills/wix-vibe-headless/platforms/base44.md

@@ -25,6 +25,7 @@ Run this through exec_tool, exactly as written — installs all three skills, de
 | vertical | pick it when the app needs to |
 |---|---|
 | `storefront` | sell products |
+| `donations` | accept one-time or recurring contributions to Wix Donations campaigns — not a generic form or membership plan |
 | `bookings` | take appointments or service bookings |
 | `rentals` | rent out an item for a length the customer picks (by the hour or by the day) |
 | `blog` | publish articles |

package/skills/wix-vibe-headless/references/donations/INSTRUCTIONS.md

@@ -0,0 +1,88 @@
+# Wix Donations — client-only REST
+
+Connect the existing site's campaigns to the donor UI. No SDK, backend, Editor widget or replacement
+site. The public `WIX_CLIENT_ID` and shared visitor transport select the content site; never put owner
+credentials in the app. Do not gate donating behind member login.
+
+Read [How to Code Donations](../../../wix-headless/references/inline-recipes/how-to-code-donations.md)
+for the exact contract/troubleshooting/verification, and
+[Donations experience](../../../wix-headless/references/inline-recipes/experience-donations.md) for the donor journey.
+If a sibling skill is absent, read the same path under `https://www.wix.com/skills/`.
+
+## Shipped helper, presentation yours
+
+Copy `app/` and `../shared/app/` into the app's `src/` (the platform deploy step does this for you).
+The added file is `src/rest/wix-donations.js`; the shared transport/config stay shared with any other
+vertical. Keep the existing theme and routing system; this vertical ships no page or provider.
+On an existing app, deploy upgrades only the exact unmodified legacy transport. If it reports a
+customized/incompatible transport, merge the shared transport's strict-error support and capability
+export into that file before retrying; do not overwrite custom auth or silently ignore the warning.
+
+| Export | Returns / behavior |
+| --- | --- |
+| `queryDonationCampaigns({ limit?, cursor? })` | `{ campaigns, nextCursor }`; raw REST entities, IDs are `id`. Continue paging; do not hardcode seed IDs. |
+| `getDonationCampaign(id)` | The raw campaign, or null for missing/archived. Other failures throw. |
+| `getDonationCampaignMetrics(id)` | `currencyMetricsList`; call only with a goal. A denied/unavailable read is not zero fundraising. |
+| `donationCartBody(campaign, selection)` | Validates the choice and creates the numeric, one-time-omitting Cart V2 body; does not call Wix. |
+| `donationCheckoutUrl(id, selection, { origin?, campaignPath?, thankYouPath? }?)` | Rereads the campaign, creates a standalone cart, then a redirect session. Returns the hosted URL; does not navigate or mark anything paid. Errors retain `status`, `body`, `stage`, and a known `cartId`. |
+
+`selection` is `{ amount, frequency: 'ONE_TIME'|'WEEK'|'MONTH'|'YEAR', coverFee, note }`.
+Use fields from the actual campaign: `predefinedDonationAmounts[].price` (decimal string amounts,
+formatted display values), preset `.description` (impact), `donationFrequencies`,
+`customAmountEnabled` / `customAmountOptions`, `commentsEnabled`, `askDonorCoverFee`, optional
+`campaignGoal`. There is no campaign story or slug field. Keep story copy in the site, not in fake data.
+
+## Wire the donor surfaces
+
+Build the cause-led home/navigation, `/donate` discovery (or the single cause's form), a campaign
+route `/donate/:id`, and `/donate/thank-you` in the existing router. Make direct links/refresh work;
+wire the static thank-you route before a catch-all ID route. Unknown/archived is a real not-found
+state. Active status is `COLLECTING`; a reached goal does not necessarily stop collection.
+
+The presentation owns giving-intent routing and short-lived per-campaign draft recovery, as defined
+in the shared recipe: preserve choices through discovery, refresh and checkout cancellation. The
+helper does not persist a form. Save before leaving, restore/revalidate on return, and keep notes out
+of URLs and logs; do not infer completion or clear a draft from the callback alone.
+
+The form offers configured frequencies/presets/custom bounds, impact text, optional note and optional
+fee choice. Explain the recurring commitment and fee beside the action. Fee coverage is the catalog's
+2.9% option, not an arbitrary surcharge; the helper sends the base amount and flag. Render prices in
+the verified site currency; do not assume `$` because the API amount is a string. Preserve validation
+and choices, disable repeated submits, and show a recoverable inline failure without leaking raw donor
+data. Use a distinct loading, empty and failed-query state. Source real progress only where readable.
+
+```js
+import { donationCheckoutUrl } from '@/rest/wix-donations';
+
+// In the form's one submit handler, after client validation; pending blocks repeat activation.
+setPending(true);
+try {
+  const url = await donationCheckoutUrl(campaign.id, { amount, frequency, coverFee, note });
+  window.location.assign(url); // full document, exact URL — not the app router
+} catch (error) {
+  console.error('Donation checkout failed', { // safe diagnostic fields; original response is error.body
+    stage: error.stage, status: error.status,
+    code: error.body?.details?.applicationError?.code ?? error.body?.code,
+  });
+  setError('We could not open checkout. Please check your selection and try again.');
+} finally {
+  setPending(false);
+}
+```
+
+Use your host's actual paths/origin in the optional callback parameters when these routes differ.
+The deployed origin must be allowed on the OAuth client. The return page cannot claim payment from
+`orderId` alone; if an authorized order read is unavailable, acknowledge without amount/name/paid
+claims. Donor history and subscription management are not shipped here; do not invent controls.
+
+## Completion
+
+Follow the integration recipe's anonymous API smoke test and verify desktop/phone form states and
+the hosted checkout's cause/amount/cadence before calling the flow complete. API creation is not a
+paid donation. Do not take a real payment without explicit authorization. Report setup/verification
+limits, including payment-enabled plan/provider and allowed origins; do not explain an
+`ITEM_NOT_FOUND_IN_CATALOG` away as premium or reinstall apps before checking the option types.
+
+Campaign changes require owner authorization and the [management recipe](../../../wix-manage/references/donations/create-and-update-donation-campaigns.md).
+Preserve existing campaigns when only connecting the front. The canonical campaign dashboard route
+is the app-ID fallback: `https://manage.wix.com/dashboard/<SITE_ID>/app/333b456e-dd48-4d6b-b32b-9fd48d74e163`.

package/skills/wix-vibe-headless/references/donations/app/rest/wix-donations.js

@@ -0,0 +1,112 @@
+// Public REST only. Configure the public client id in the shared wix-config.js.
+// docs: https://dev.wix.com/docs/api-reference/business-solutions/donations/donation-campaigns/e-commerce-integration-with-donation-campaigns
+// docs: https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/purchase-flow/cart-v2/create-cart
+// docs: https://dev.wix.com/docs/api-reference/business-management/headless/redirects/create-redirect-session
+import * as wixClient from './wix-client.js';
+
+export const DONATIONS_APP_ID = '333b456e-dd48-4d6b-b32b-9fd48d74e163';
+const CAMPAIGNS = '/donation-campaigns/v2/donation-campaigns';
+const RECURRING = ['WEEK', 'MONTH', 'YEAR'];
+const request = (path, options = {}) => {
+  if (wixClient.WIX_API_SUPPORTS_STRICT_PAYMENT_ERRORS !== true) {
+    const error = new Error('Donations needs the updated Wix transport. Re-run the Donations deploy step; for a customized src/rest/wix-client.js, merge strict payment-error support from the shared transport before retrying.');
+    error.code = 'DONATIONS_TRANSPORT_UPGRADE_REQUIRED';
+    throw error;
+  }
+  return wixClient.wixApiRequest(path, { ...options, throwOnPaymentRequired: true });
+};
+
+/** Raw REST campaigns; page until nextCursor is null. Failures never become an empty result. */
+export async function queryDonationCampaigns({ limit = 100, cursor } = {}) {
+  const data = await request(`${CAMPAIGNS}/query`, { body: {
+    query: { filter: { archived: false }, cursorPaging: { limit, ...(cursor ? { cursor } : {}) } },
+  } });
+  return { campaigns: data.donationCampaigns ?? [], nextCursor: data.pagingMetadata?.cursors?.next ?? null };
+}
+
+/** null only for an absent/archived campaign; authorization and transport errors propagate. */
+export async function getDonationCampaign(id) {
+  try {
+    const { donationCampaign } = await request(`${CAMPAIGNS}/${encodeURIComponent(id)}`, { method: 'GET' });
+    return donationCampaign && !donationCampaign.archived ? donationCampaign : null;
+  } catch (error) {
+    if (error.status === 404) return null;
+    throw error;
+  }
+}
+
+/** Call only for a campaign with a goal. A failed read must not be displayed as zero fundraising. */
+export async function getDonationCampaignMetrics(id) {
+  const data = await request(`${CAMPAIGNS}/${encodeURIComponent(id)}/metrics`, { method: 'GET' });
+  return data.currencyMetricsList ?? [];
+}
+
+/** Pure, independently testable conversion from a live campaign and donor selection to Cart V2. */
+export function donationCartBody(campaign, { amount: chosen, frequency = 'ONE_TIME', coverFee = false, note = '' } = {}) {
+  if (!campaign?.id || campaign.archived || campaign.status !== 'COLLECTING') {
+    throw new Error('This campaign is not accepting donations.');
+  }
+  if ((typeof chosen !== 'string' && typeof chosen !== 'number') || String(chosen).trim() === '') {
+    throw new Error('Enter a positive donation amount.');
+  }
+  const amount = Number(chosen);
+  if (!Number.isFinite(amount) || amount <= 0) throw new Error('Enter a positive donation amount.');
+  if (!['ONE_TIME', ...RECURRING].includes(frequency) || !campaign.donationFrequencies?.includes(frequency)) {
+    throw new Error('Choose a frequency offered by this campaign.');
+  }
+  const isPreset = campaign.predefinedDonationAmounts?.some(preset => Number(preset.price?.amount) === amount);
+  if (!isPreset) {
+    if (!campaign.customAmountEnabled) throw new Error('Choose one of the suggested amounts.');
+    const { minimum, maximum } = campaign.customAmountOptions ?? {};
+    if (minimum && amount < Number(minimum.amount)) throw new Error(`The minimum donation is ${minimum.formattedAmount ?? minimum.amount}.`);
+    if (maximum && amount > Number(maximum.amount)) throw new Error(`The maximum donation is ${maximum.formattedAmount ?? maximum.amount}.`);
+  }
+  if (coverFee && !campaign.askDonorCoverFee) throw new Error('Fee coverage is not offered by this campaign.');
+  const message = String(note).trim();
+  if (message && !campaign.commentsEnabled) throw new Error('Notes are not enabled for this campaign.');
+  if (message.length > 1000) throw new Error('Keep your note within 1,000 characters.');
+  return {
+    cart: { source: { channelType: 'WEB' }, ...(message ? { note: message } : {}) },
+    catalogItems: [{ quantity: 1, catalogReference: {
+      appId: DONATIONS_APP_ID,
+      catalogItemId: campaign.id,
+      options: { amount, ...(frequency !== 'ONE_TIME' ? { frequency } : {}), ...(coverFee ? { donorCoveringFees: true } : {}) },
+    } }],
+  };
+}
+
+/** Read current settings → one standalone Cart V2 → one hosted session. Never merges the current cart. */
+export async function donationCheckoutUrl(campaignId, selection, {
+  origin = typeof window !== 'undefined' ? window.location.origin : '',
+  campaignPath = `/donate/${encodeURIComponent(campaignId)}`,
+  thankYouPath = '/donate/thank-you',
+} = {}) {
+  const site = new URL(origin);
+  if (!['https:', 'http:'].includes(site.protocol)) throw new Error('A valid site origin is required.');
+  const back = new URL(campaignPath, site.origin);
+  const thanks = new URL(thankYouPath, site.origin);
+  if (back.origin !== site.origin || thanks.origin !== site.origin) throw new Error('Checkout callbacks must use this site origin.');
+  let stage = 'campaign';
+  let cartId;
+  try {
+    const campaign = await getDonationCampaign(campaignId);
+    const body = donationCartBody(campaign, selection);
+    stage = 'cart';
+    const result = await request('/ecom/v2/carts', { body });
+    cartId = result.cart?.id;
+    if (!cartId) throw new Error('Checkout could not start: no cart id returned.');
+    stage = 'redirect';
+    const session = await request('/_api/redirects-api/v1/redirect-session', { body: {
+      ecomCheckout: { checkoutId: cartId },
+      callbacks: { postFlowUrl: back.href, thankYouPageUrl: thanks.href },
+    } });
+    const url = session.redirectSession?.fullUrl;
+    if (!url) throw new Error('Checkout could not start: no redirect URL returned.');
+    return url;
+  } catch (error) {
+    // Preserve the original HTTP status/body; stage and known cart id let the caller diagnose safely.
+    error.stage = stage;
+    if (cartId) error.cartId = cartId;
+    throw error;
+  }
+}

package/skills/wix-vibe-headless/references/donations/seed/SEED.md

@@ -0,0 +1,11 @@
+# Donations setup
+
+When the user asks for campaign setup, use the owner-authorized
+[Create and Update Donation Campaigns](../../../../wix-manage/references/donations/create-and-update-donation-campaigns.md)
+recipe. If it is not installed, read
+`https://www.wix.com/skills/wix-manage/references/donations/create-and-update-donation-campaigns.md`.
+This vertical has no second seed implementation. Confirm the site and changes, read first, preserve
+existing campaigns, and never run owner operations using the browser's visitor credentials.
+
+For a frontend-only request, do not seed at all. Report missing campaign/payment setup rather than
+creating mock causes, fundraising figures or a replacement site.