@wix/agent-skills 1.33.0 → 1.34.0

package/skills/wix-headless-templates/donations/app/components/donations/DonationReceipt.tsx

@@ -1,7 +1,7 @@
 // The hosted checkout's thank-you island — wire as-is on /donate/thank-you (mount client:only: it
 // reads the browser URL). It owns the honesty rules: landing here with `?orderId=` is Wix's
 // success redirect, so it thanks the donor; the order's facts (name, amount, order number, paid or
-// pending) appear only when the order could be read; a direct visit with no order id gets a neutral
+// unconfirmed) appear only when the order could be read; a direct visit with no order id gets a neutral
 // thank-you and a link back — never an invented receipt, never "paid" unless the order says PAID.
 import { useDonationReceipt } from "../../hooks/donations/useDonationReceipt";
 
@@ -17,7 +17,8 @@ export default function DonationReceipt({ campaignsHref = "/donate", className =
   if (!orderId) {
     return (
       <div className={className}>
-        <h1 className="text-2xl font-semibold tracking-tight">Thank you for your support</h1>
+        <h1 className="text-2xl font-semibold tracking-tight">Your support matters</h1>
+        <p className="mt-3 text-sm text-muted-foreground">This page alone is not a payment confirmation. Explore a campaign to give, or check your checkout confirmation if you just returned.</p>
         <a href={campaignsHref} className="mt-6 inline-block text-sm text-foreground underline">
           See the campaigns
         </a>
@@ -29,15 +30,15 @@ export default function DonationReceipt({ campaignsHref = "/donate", className =
     <div className={className} aria-busy={loading}>
       {receipt?.orderNumber && <p className="eyebrow">Order {receipt.orderNumber}</p>}
       <h1 className="mt-2 text-2xl font-semibold tracking-tight">
-        {receipt?.donorFirstName ? `Thank you, ${receipt.donorFirstName}` : "Thank you for your donation"}
+        {receipt?.donorFirstName ? `Thank you, ${receipt.donorFirstName}` : receipt ? "Thank you for your support" : loading ? "Checking your donation" : "Your support matters"}
       </h1>
       {receipt && (
         <p className="mt-3 text-sm text-muted-foreground">
           {receipt.amount ? `Your donation of ${receipt.amount} ` : "Your donation "}
-          {receipt.paid ? "has been received." : "is being processed — payment is pending."}
+          {receipt.paid ? "has been received." : "is not confirmed as paid. Please check your checkout confirmation."}
         </p>
       )}
-      {!receipt && !loading && <p className="mt-3 text-sm text-muted-foreground">Your donation has been submitted.</p>}
+      {!receipt && !loading && <p className="mt-3 text-sm text-muted-foreground">Donation details could not be verified here. If you completed checkout, check its confirmation before trying again.</p>}
       <a href={campaignsHref} className="mt-6 inline-block text-sm text-muted-foreground underline">
         Back to campaigns
       </a>

package/skills/wix-headless-templates/donations/app/components/donations/GoalProgress.tsx

@@ -33,14 +33,14 @@ export default function GoalProgress({ goal, className = "", compact = false }:
             {goal.target}
           </span>
         </p>
-        <p className="text-sm font-semibold text-foreground">{goal.percent}%</p>
+        {goal.raised && <p className="text-sm font-semibold text-foreground">{goal.percent}%</p>}
       </div>
-      <div className="mt-2 h-2 w-full overflow-hidden rounded-control bg-secondary" role="progressbar" aria-valuemin={0} aria-valuemax={100} aria-valuenow={width} aria-label="Progress toward the goal">
+      {goal.raised && <div className="mt-2 h-2 w-full overflow-hidden rounded-control bg-secondary" role="progressbar" aria-valuemin={0} aria-valuemax={100} aria-valuenow={width} aria-label="Progress toward the goal">
         <div className="h-full rounded-control bg-primary transition-[width]" style={{ width: `${width}%` }} />
-      </div>
-      {(!compact || timeLeft) && (
+      </div>}
+      {((!compact && goal.raised) || timeLeft) && (
         <p className="mt-2 flex justify-between text-xs text-muted-foreground">
-          {!compact && <span>{goal.donationCount === 1 ? "1 donation" : `${goal.donationCount} donations`}</span>}
+          {!compact && goal.raised && <span>{goal.donationCount === 1 ? "1 donation" : `${goal.donationCount} donations`}</span>}
           {timeLeft && <span>{timeLeft}</span>}
         </p>
       )}

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

@@ -33,16 +33,16 @@ function siteCurrency(): Promise<string> {
 }
 
 /** The campaign's currency: the metrics' when a donation exists, else the site's. */
-async function currencyFor(metrics: Raw[]): Promise<string> {
+async function currencyFor(metrics: Raw[] | null): Promise<string> {
   return currencyOf(metrics) || (await siteCurrency());
 }
 
-async function metricsOf(campaignId: string): Promise<Raw[]> {
+async function metricsOf(campaignId: string): Promise<Raw[] | null> {
   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
+    return null; // unavailable is not a successfully-read zero total
   }
 }
 
@@ -72,7 +72,7 @@ export async function fetchCampaign(campaignId: string): Promise<CampaignDetail
     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);
+  const metrics = raw.campaignGoal ? await metricsOf(campaignId) : [];
   return toDetail(raw, metrics, await currencyFor(metrics), imgSrc);
 }
 

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

@@ -47,10 +47,14 @@ export async function donationCheckoutUrl(campaignId: string, input: DonationInp
     const cart: Raw = await cartV2Api.createCart(cartBody(campaignId, input) as any);
     cartId = cartIdOf(cart);
   } catch (e) {
-    throw checkoutError(e);
+    throw checkoutError(e, "cart");
+  }
+  try {
+    const session: Raw = await redirects.createRedirectSession(redirectBody(cartId, campaignId, site, paths) as any);
+    return redirectUrl(session);
+  } catch (e) {
+    throw checkoutError(e, "redirect", cartId);
   }
-  const session: Raw = await redirects.createRedirectSession(redirectBody(cartId, campaignId, site, paths) as any);
-  return redirectUrl(session);
 }
 
 /**

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

@@ -154,9 +154,9 @@ export function createDonationStore(campaign: CampaignDetail, { origin, paths }:
         // stays "submitting" — the browser is leaving for the hosted checkout
       } catch (e) {
         submitting = false;
-        error = e instanceof Error ? e.message : String(e);
+        error = "We couldn't open checkout. Please try again.";
         emit();
-        throw e;
+        throw e; // the caller retains the original API status/body; never replace the cause
       }
     },
   };

package/skills/wix-headless-templates/donations/app/wix/donations/donations-core.ts

@@ -163,7 +163,7 @@ export function toGoal(campaignGoal: Raw | null | undefined, metrics: Raw[] | nu
   const ended = hasEnd && end!.getTime() < now.getTime();
   const left = hasEnd && !ended ? end!.getTime() - now.getTime() : 0;
   return {
-    raised: m.totalAmount ? formatMoney(m.totalAmount, currency) : formatAmount(0, currency),
+    raised: metrics == null ? "" : m.totalAmount ? formatMoney(m.totalAmount, currency) : formatAmount(0, currency),
     target: formatMoney(campaignGoal.targetAmount, currency),
     raisedAmount,
     targetAmount,
@@ -360,12 +360,16 @@ export function toInput(options: DonationOptions, sel: DonationSelection): Donat
  */
 export function donationLineItem(campaignId: string, input: DonationInput): Raw {
   if (!campaignId) throw new Error("A campaign id is required to donate.");
+  if ((typeof input.amount !== "number" && typeof input.amount !== "string") || String(input.amount).trim() === "") throw new Error("Enter a positive donation amount.");
+  const amount = Number(input.amount);
+  if (!Number.isFinite(amount) || amount <= 0) throw new Error("Enter a positive donation amount.");
+  if (!FREQUENCIES.includes(input.frequency)) throw new Error("Choose a supported donation frequency.");
   return {
     quantity: 1,
     catalogReference: {
       appId: DONATIONS_APP_ID,
       catalogItemId: campaignId,
-      options: { amount: input.amount, frequency: input.frequency, ...(input.coverFee ? { donorCoveringFees: true } : {}) },
+      options: { amount, ...(input.frequency !== "ONE_TIME" ? { frequency: input.frequency } : {}), ...(input.coverFee ? { donorCoveringFees: true } : {}) },
     },
   };
 }
@@ -424,13 +428,12 @@ export function redirectUrl(session: Raw | null | undefined): string {
   return url;
 }
 
-/** A checkout failure as the visitor should read it; the raw message is kept when no rule applies. */
-export function checkoutError(e: unknown): Error {
-  const msg = e instanceof Error ? e.message : String(e);
-  if (/premium|payment method|payments? (is|are) not (set up|enabled)|PAYMENT_METHOD/i.test(msg)) {
-    return new Error("Donations aren't switched on yet — the site owner needs a premium plan and a connected payment method.");
-  }
-  return e instanceof Error ? e : new Error(msg || "Checkout couldn't start — please try again.");
+/** Preserve diagnostic status/body/cause; payment setup must not be guessed from a generic failure. */
+export function checkoutError(e: unknown, stage?: "cart" | "redirect", cartId?: string): Error & { stage?: string; cartId?: string } {
+  const error: Error & { stage?: string; cartId?: string } = e instanceof Error ? e : new Error(String(e) || "Checkout couldn't start — please try again.", { cause: e });
+  if (stage) error.stage = stage;
+  if (cartId) error.cartId = cartId;
+  return error;
 }
 
 // ---- the receipt ----------------------------------------------------------------------------------

package/skills/wix-headless-templates/donations/project/src/components/donations/DonateForm.tsx

@@ -8,7 +8,7 @@
 // donations (goal reached / expired) it renders `children` — your closing message — or nothing.
 // The redirect itself is useDonation → donationCheckoutUrl; nothing here builds a URL or marks
 // anything paid.
-import type { ReactNode } from "react";
+import { useId, type ReactNode } from "react";
 import { useDonation, type UseDonationOptions } from "../../hooks/donations/useDonation";
 import type { CampaignDetail } from "../../wix/donations/types";
 
@@ -23,7 +23,7 @@ export interface DonateFormProps {
 }
 
 const choice = (selected: boolean) =>
-  `cursor-pointer rounded-md border px-4 py-3 text-sm transition-colors ${
+  `relative block cursor-pointer rounded-md border px-4 py-3 text-sm transition-colors focus-within:outline-2 focus-within:outline-offset-2 focus-within:outline-primary ${
     selected ? "border-primary bg-primary text-primary-foreground" : "border-border bg-background text-foreground hover:bg-secondary"
   }`;
 
@@ -36,10 +36,10 @@ export default function DonateForm({
 }: DonateFormProps) {
   const d = useDonation(campaign, options);
   const o = campaign.options;
+  const fid = `donate-${campaign.id}-${useId()}`;
   if (!d.available) return children ? <>{children}</> : null;
 
   const show = (field: keyof typeof d.messages) => (d.showErrors && d.messages[field] ? d.messages[field] : null);
-  const fid = `donate-${campaign.id}`;
 
   return (
     <form
@@ -47,43 +47,65 @@ export default function DonateForm({
       noValidate
       onSubmit={(e) => {
         e.preventDefault();
-        void d.donate().catch(() => {});
+        const form = e.currentTarget;
+        void d.donate().then(() => {
+          if (!d.valid) {
+            // Wait for the store's validation state to render; do not steal focus while typing.
+            requestAnimationFrame(() => form.querySelector<HTMLElement>('[aria-invalid="true"]')?.focus());
+          }
+        }).catch((error) => {
+          // The store shows a recoverable message; keep safe diagnostics, not donor data or tokens.
+          console.error("Donation checkout failed", {
+            stage: error?.stage ?? "checkout",
+            status: error?.status,
+            code: error?.body?.details?.applicationError?.code ?? error?.details?.applicationError?.code ?? error?.body?.code,
+          });
+        });
       }}
     >
       {o.frequencies.length > 1 && (
-        <fieldset>
+        <fieldset disabled={d.submitting}>
           <legend className="eyebrow mb-2">How often</legend>
-          <div className="grid grid-cols-2 gap-2 sm:grid-cols-4" role="radiogroup">
+          <div className="grid grid-cols-2 gap-2 sm:grid-cols-4">
             {o.frequencies.map((f) => (
-              <button key={f.value} type="button" role="radio" aria-checked={d.frequency === f.value} className={choice(d.frequency === f.value)} onClick={() => d.setFrequency(f.value)}>
+              <label key={f.value} className={choice(d.frequency === f.value)}>
+                <input type="radio" name={`${fid}-frequency`} value={f.value} checked={d.frequency === f.value}
+                  onChange={() => d.setFrequency(f.value)} className="sr-only"
+                  aria-invalid={!!show("frequency")} aria-describedby={show("frequency") ? `${fid}-frequency-error` : undefined} />
                 {f.label}
-              </button>
+              </label>
             ))}
           </div>
-          {show("frequency") && <p className="mt-2 text-sm text-destructive" role="alert">{show("frequency")}</p>}
+          {show("frequency") && <p id={`${fid}-frequency-error`} className="mt-2 text-sm text-destructive" role="alert">{show("frequency")}</p>}
         </fieldset>
       )}
 
       {(o.presets.length > 0 || o.customAmount.enabled) && (
-        <fieldset>
+        <fieldset disabled={d.submitting}>
           <legend className="eyebrow mb-2">Amount</legend>
-          <div className="grid grid-cols-2 gap-2 sm:grid-cols-3" role="radiogroup">
+          <div className="grid grid-cols-2 gap-2 sm:grid-cols-3">
             {o.presets.map((p) => {
               const selected = !d.customMode && d.presetAmount === p.amount;
               return (
-                <button key={p.amount} type="button" role="radio" aria-checked={selected} className={`${choice(selected)} text-left`} onClick={() => d.selectPreset(p.amount)}>
+                <label key={p.amount} className={`${choice(selected)} text-left`}>
+                  <input type="radio" name={`${fid}-amount-choice`} value={p.amount} checked={selected}
+                    onChange={() => d.selectPreset(p.amount)} className="sr-only"
+                    aria-invalid={!!show("amount")} aria-describedby={show("amount") ? `${fid}-amount-error` : undefined} />
                   <span className="block text-base font-semibold">{p.label}</span>
                   {p.impact && <span className={`mt-0.5 block text-xs ${selected ? "opacity-80" : "text-muted-foreground"}`}>{p.impact}</span>}
-                </button>
+                </label>
               );
             })}
             {o.customAmount.enabled && o.presets.length > 0 && (
-              <button type="button" role="radio" aria-checked={d.customMode} className={choice(d.customMode)} onClick={() => d.selectCustom()}>
+              <label className={choice(d.customMode)}>
+                <input type="radio" name={`${fid}-amount-choice`} value="custom" checked={d.customMode}
+                  onChange={() => d.selectCustom()} className="sr-only"
+                  aria-invalid={!!show("amount")} aria-describedby={show("amount") ? `${fid}-amount-error` : undefined} />
                 Other amount
-              </button>
+              </label>
             )}
           </div>
-          {show("amount") && <p className="mt-2 text-sm text-destructive" role="alert">{show("amount")}</p>}
+          {show("amount") && <p id={`${fid}-amount-error`} className="mt-2 text-sm text-destructive" role="alert">{show("amount")}</p>}
           {d.customMode && (
             <div className="mt-3">
               <label htmlFor={`${fid}-amount`} className="sr-only">
@@ -95,19 +117,20 @@ export default function DonateForm({
                   id={`${fid}-amount`}
                   inputMode="decimal"
                   autoComplete="off"
-                  className="w-full bg-transparent py-3 text-base text-foreground outline-none"
+                  className="min-w-0 flex-1 bg-transparent py-3 text-base text-foreground outline-none focus-visible:ring-2 focus-visible:ring-primary"
                   placeholder={o.customAmount.minLabel ? `${o.customAmount.minLabel} or more` : "Enter an amount"}
                   value={d.customAmount}
                   onChange={(e) => d.setCustomAmount(e.target.value)}
                   aria-invalid={!!show("customAmount")}
+                  aria-describedby={show("customAmount") || o.customAmount.minLabel || o.customAmount.maxLabel ? `${fid}-custom-help` : undefined}
                 />
               </div>
               {(o.customAmount.minLabel || o.customAmount.maxLabel) && !show("customAmount") && (
-                <p className="mt-1 text-xs text-muted-foreground">
+                <p id={`${fid}-custom-help`} className="mt-1 text-xs text-muted-foreground">
                   {[o.customAmount.minLabel && `Minimum ${o.customAmount.minLabel}`, o.customAmount.maxLabel && `Maximum ${o.customAmount.maxLabel}`].filter(Boolean).join(" · ")}
                 </p>
               )}
-              {show("customAmount") && <p className="mt-1 text-sm text-destructive" role="alert">{show("customAmount")}</p>}
+              {show("customAmount") && <p id={`${fid}-custom-help`} className="mt-1 text-sm text-destructive" role="alert">{show("customAmount")}</p>}
             </div>
           )}
         </fieldset>
@@ -115,7 +138,7 @@ export default function DonateForm({
 
       {o.askCoverFee && (
         <label className="flex items-start gap-3 text-sm text-foreground">
-          <input type="checkbox" className="mt-0.5" checked={d.coverFee} onChange={(e) => d.setCoverFee(e.target.checked)} />
+          <input type="checkbox" className="mt-0.5" checked={d.coverFee} disabled={d.submitting} onChange={(e) => d.setCoverFee(e.target.checked)} />
           <span>
             {d.feeLabel ? `Add ${d.feeLabel} to cover the processing fees` : "Cover the processing fees (2.9%)"}
             {d.frequency && d.frequency !== "ONE_TIME" && <span className="text-muted-foreground"> — on every payment</span>}
@@ -132,14 +155,17 @@ export default function DonateForm({
             id={`${fid}-note`}
             rows={3}
             maxLength={o.commentMaxLength}
-            className="w-full rounded-md border border-border bg-background px-3 py-2 text-sm text-foreground outline-none"
+            className="w-full rounded-md border border-border bg-background px-3 py-2 text-sm text-foreground outline-none focus-visible:ring-2 focus-visible:ring-primary"
             value={d.note}
             onChange={(e) => d.setNote(e.target.value)}
+            disabled={d.submitting}
+            aria-invalid={!!show("note")}
+            aria-describedby={`${fid}-note-hint${show("note") ? ` ${fid}-note-error` : ""}`}
           />
-          <p className="mt-1 text-right text-xs text-muted-foreground">
+          <p id={`${fid}-note-hint`} className="mt-1 text-right text-xs text-muted-foreground">
             {d.note.length}/{o.commentMaxLength}
           </p>
-          {show("note") && <p className="text-sm text-destructive" role="alert">{show("note")}</p>}
+          {show("note") && <p id={`${fid}-note-error`} className="text-sm text-destructive" role="alert">{show("note")}</p>}
         </div>
       )}
 

package/skills/wix-headless-templates/donations/project/src/components/donations/DonationReceipt.tsx

@@ -1,7 +1,7 @@
 // The hosted checkout's thank-you island — wire as-is on /donate/thank-you (mount client:only: it
 // reads the browser URL). It owns the honesty rules: landing here with `?orderId=` is Wix's
 // success redirect, so it thanks the donor; the order's facts (name, amount, order number, paid or
-// pending) appear only when the order could be read; a direct visit with no order id gets a neutral
+// unconfirmed) appear only when the order could be read; a direct visit with no order id gets a neutral
 // thank-you and a link back — never an invented receipt, never "paid" unless the order says PAID.
 import { useDonationReceipt } from "../../hooks/donations/useDonationReceipt";
 
@@ -17,7 +17,8 @@ export default function DonationReceipt({ campaignsHref = "/donate", className =
   if (!orderId) {
     return (
       <div className={className}>
-        <h1 className="text-2xl font-semibold tracking-tight">Thank you for your support</h1>
+        <h1 className="text-2xl font-semibold tracking-tight">Your support matters</h1>
+        <p className="mt-3 text-sm text-muted-foreground">This page alone is not a payment confirmation. Explore a campaign to give, or check your checkout confirmation if you just returned.</p>
         <a href={campaignsHref} className="mt-6 inline-block text-sm text-foreground underline">
           See the campaigns
         </a>
@@ -29,15 +30,15 @@ export default function DonationReceipt({ campaignsHref = "/donate", className =
     <div className={className} aria-busy={loading}>
       {receipt?.orderNumber && <p className="eyebrow">Order {receipt.orderNumber}</p>}
       <h1 className="mt-2 text-2xl font-semibold tracking-tight">
-        {receipt?.donorFirstName ? `Thank you, ${receipt.donorFirstName}` : "Thank you for your donation"}
+        {receipt?.donorFirstName ? `Thank you, ${receipt.donorFirstName}` : receipt ? "Thank you for your support" : loading ? "Checking your donation" : "Your support matters"}
       </h1>
       {receipt && (
         <p className="mt-3 text-sm text-muted-foreground">
           {receipt.amount ? `Your donation of ${receipt.amount} ` : "Your donation "}
-          {receipt.paid ? "has been received." : "is being processed — payment is pending."}
+          {receipt.paid ? "has been received." : "is not confirmed as paid. Please check your checkout confirmation."}
         </p>
       )}
-      {!receipt && !loading && <p className="mt-3 text-sm text-muted-foreground">Your donation has been submitted.</p>}
+      {!receipt && !loading && <p className="mt-3 text-sm text-muted-foreground">Donation details could not be verified here. If you completed checkout, check its confirmation before trying again.</p>}
       <a href={campaignsHref} className="mt-6 inline-block text-sm text-muted-foreground underline">
         Back to campaigns
       </a>

package/skills/wix-headless-templates/donations/project/src/components/donations/GoalProgress.tsx

@@ -33,14 +33,14 @@ export default function GoalProgress({ goal, className = "", compact = false }:
             {goal.target}
           </span>
         </p>
-        <p className="text-sm font-semibold text-foreground">{goal.percent}%</p>
+        {goal.raised && <p className="text-sm font-semibold text-foreground">{goal.percent}%</p>}
       </div>
-      <div className="mt-2 h-2 w-full overflow-hidden rounded-control bg-secondary" role="progressbar" aria-valuemin={0} aria-valuemax={100} aria-valuenow={width} aria-label="Progress toward the goal">
+      {goal.raised && <div className="mt-2 h-2 w-full overflow-hidden rounded-control bg-secondary" role="progressbar" aria-valuemin={0} aria-valuemax={100} aria-valuenow={width} aria-label="Progress toward the goal">
         <div className="h-full rounded-control bg-primary transition-[width]" style={{ width: `${width}%` }} />
-      </div>
-      {(!compact || timeLeft) && (
+      </div>}
+      {((!compact && goal.raised) || timeLeft) && (
         <p className="mt-2 flex justify-between text-xs text-muted-foreground">
-          {!compact && <span>{goal.donationCount === 1 ? "1 donation" : `${goal.donationCount} donations`}</span>}
+          {!compact && goal.raised && <span>{goal.donationCount === 1 ? "1 donation" : `${goal.donationCount} donations`}</span>}
           {timeLeft && <span>{timeLeft}</span>}
         </p>
       )}

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

@@ -33,16 +33,16 @@ function siteCurrency(): Promise<string> {
 }
 
 /** The campaign's currency: the metrics' when a donation exists, else the site's. */
-async function currencyFor(metrics: Raw[]): Promise<string> {
+async function currencyFor(metrics: Raw[] | null): Promise<string> {
   return currencyOf(metrics) || (await siteCurrency());
 }
 
-async function metricsOf(campaignId: string): Promise<Raw[]> {
+async function metricsOf(campaignId: string): Promise<Raw[] | null> {
   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
+    return null; // unavailable is not a successfully-read zero total
   }
 }
 
@@ -72,7 +72,7 @@ export async function fetchCampaign(campaignId: string): Promise<CampaignDetail
     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);
+  const metrics = raw.campaignGoal ? await metricsOf(campaignId) : [];
   return toDetail(raw, metrics, await currencyFor(metrics), imgSrc);
 }
 

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

@@ -47,10 +47,14 @@ export async function donationCheckoutUrl(campaignId: string, input: DonationInp
     const cart: Raw = await cartV2Api.createCart(cartBody(campaignId, input) as any);
     cartId = cartIdOf(cart);
   } catch (e) {
-    throw checkoutError(e);
+    throw checkoutError(e, "cart");
+  }
+  try {
+    const session: Raw = await redirects.createRedirectSession(redirectBody(cartId, campaignId, site, paths) as any);
+    return redirectUrl(session);
+  } catch (e) {
+    throw checkoutError(e, "redirect", cartId);
   }
-  const session: Raw = await redirects.createRedirectSession(redirectBody(cartId, campaignId, site, paths) as any);
-  return redirectUrl(session);
 }
 
 /**

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

@@ -154,9 +154,9 @@ export function createDonationStore(campaign: CampaignDetail, { origin, paths }:
         // stays "submitting" — the browser is leaving for the hosted checkout
       } catch (e) {
         submitting = false;
-        error = e instanceof Error ? e.message : String(e);
+        error = "We couldn't open checkout. Please try again.";
         emit();
-        throw e;
+        throw e; // the caller retains the original API status/body; never replace the cause
       }
     },
   };

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

@@ -163,7 +163,7 @@ export function toGoal(campaignGoal: Raw | null | undefined, metrics: Raw[] | nu
   const ended = hasEnd && end!.getTime() < now.getTime();
   const left = hasEnd && !ended ? end!.getTime() - now.getTime() : 0;
   return {
-    raised: m.totalAmount ? formatMoney(m.totalAmount, currency) : formatAmount(0, currency),
+    raised: metrics == null ? "" : m.totalAmount ? formatMoney(m.totalAmount, currency) : formatAmount(0, currency),
     target: formatMoney(campaignGoal.targetAmount, currency),
     raisedAmount,
     targetAmount,
@@ -360,12 +360,16 @@ export function toInput(options: DonationOptions, sel: DonationSelection): Donat
  */
 export function donationLineItem(campaignId: string, input: DonationInput): Raw {
   if (!campaignId) throw new Error("A campaign id is required to donate.");
+  if ((typeof input.amount !== "number" && typeof input.amount !== "string") || String(input.amount).trim() === "") throw new Error("Enter a positive donation amount.");
+  const amount = Number(input.amount);
+  if (!Number.isFinite(amount) || amount <= 0) throw new Error("Enter a positive donation amount.");
+  if (!FREQUENCIES.includes(input.frequency)) throw new Error("Choose a supported donation frequency.");
   return {
     quantity: 1,
     catalogReference: {
       appId: DONATIONS_APP_ID,
       catalogItemId: campaignId,
-      options: { amount: input.amount, frequency: input.frequency, ...(input.coverFee ? { donorCoveringFees: true } : {}) },
+      options: { amount, ...(input.frequency !== "ONE_TIME" ? { frequency: input.frequency } : {}), ...(input.coverFee ? { donorCoveringFees: true } : {}) },
     },
   };
 }
@@ -424,13 +428,12 @@ export function redirectUrl(session: Raw | null | undefined): string {
   return url;
 }
 
-/** A checkout failure as the visitor should read it; the raw message is kept when no rule applies. */
-export function checkoutError(e: unknown): Error {
-  const msg = e instanceof Error ? e.message : String(e);
-  if (/premium|payment method|payments? (is|are) not (set up|enabled)|PAYMENT_METHOD/i.test(msg)) {
-    return new Error("Donations aren't switched on yet — the site owner needs a premium plan and a connected payment method.");
-  }
-  return e instanceof Error ? e : new Error(msg || "Checkout couldn't start — please try again.");
+/** Preserve diagnostic status/body/cause; payment setup must not be guessed from a generic failure. */
+export function checkoutError(e: unknown, stage?: "cart" | "redirect", cartId?: string): Error & { stage?: string; cartId?: string } {
+  const error: Error & { stage?: string; cartId?: string } = e instanceof Error ? e : new Error(String(e) || "Checkout couldn't start — please try again.", { cause: e });
+  if (stage) error.stage = stage;
+  if (cartId) error.cartId = cartId;
+  return error;
 }
 
 // ---- the receipt ----------------------------------------------------------------------------------

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

@@ -26,17 +26,17 @@ function siteCurrency(): Promise<string> {
 }
 
 /** The campaign's currency: the metrics' when a donation exists, else the site's. */
-async function currencyFor(metrics: Raw[]): Promise<string> {
+async function currencyFor(metrics: Raw[] | null): 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[]> {
+async function metricsOf(campaignId: string): Promise<Raw[] | null> {
   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
+    return null; // unavailable is not a successfully-read zero total
   }
 }
 
@@ -65,7 +65,7 @@ export async function fetchCampaign(campaignId: string): Promise<CampaignDetail
     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);
+  const metrics = raw.campaignGoal ? await metricsOf(campaignId) : [];
   return toDetail(raw, metrics, await currencyFor(metrics), imgSrc);
 }
 

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

@@ -42,10 +42,14 @@ export async function donationCheckoutUrl(campaignId: string, input: DonationInp
     const res = await wixRequest<Raw>("/ecom/v2/carts", { body: cartBody(campaignId, input) });
     cartId = cartIdOf(res);
   } catch (e) {
-    throw checkoutError(e);
+    throw checkoutError(e, "cart");
+  }
+  try {
+    const session = await wixRequest<Raw>("/headless/v1/redirect-session", { body: redirectBody(cartId, campaignId, site, paths) });
+    return redirectUrl(session);
+  } catch (e) {
+    throw checkoutError(e, "redirect", cartId);
   }
-  const session = await wixRequest<Raw>("/headless/v1/redirect-session", { body: redirectBody(cartId, campaignId, site, paths) });
-  return redirectUrl(session);
 }
 
 /**

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

@@ -10,10 +10,14 @@ if needed, creates the campaigns, verifies each reads back, then attaches cover
 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
+`plan.json` is plain data — write it from the brief. Read existing campaigns and confirm the target
+site and proposed changes before seeding. For a new setup, default to one approved cause; add more
+only when the brief names them. Suggest a small set of amounts and custom-giving rules for approval;
+do not invent impact claims, a goal or a deadline just to exercise form branches. Configure recurring
+giving, notes and fee coverage as intended by the owner. A frontend-only request never reseeds.
+The example below illustrates fields, not organization facts or mandatory settings.
+For ongoing campaign edits, use the [management recipe](../../../wix-manage/references/donations/create-and-update-donation-campaigns.md).
+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 `imageMediaId` (a file already in the site's Media Manager, such as one the user uploaded there: used as it is, no copy; a `static.wixstatic.com/media/<file id>` URL of a site file counts as one), `imagePath` (a file on this machine) or
@@ -72,9 +76,10 @@ images only (`imagePath` / `imageUrl`) — never an `imagePrompt` beside supplie
 
 ## 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.
+- **Accepting real payments needs a payments-capable plan and a connected eligible provider**
+  (dashboard → Accept Payments). Creating a campaign, cart or redirect session is not proof that a
+  charge can succeed. Do not blame malformed cart options on premium. Recurring frequencies also
+  need a 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