@wix/agent-skills 1.25.0 → 1.27.0

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

@@ -0,0 +1,49 @@
+// Goal progress for one campaign — wire as-is on cards, the campaign page, a home strip. Every
+// figure comes from the DTO (the metrics API and the owner's goal): raised of target, the bar at
+// Wix's rounded percent (capped visually at 100, the number may exceed it), the donation count,
+// and the time left ("3 days left"; hours on the last day; "Ended" once past). Renders nothing
+// for a campaign without a goal. Purely presentational — no hooks, so it renders on the server too.
+import type { GoalProgress as Goal } from "../../wix/donations/types";
+
+export interface GoalProgressProps {
+  goal: Goal | null;
+  className?: string;
+  /** Hide the donation count (a compact card). */
+  compact?: boolean;
+}
+
+export function timeLeftLabel(goal: Goal): string {
+  if (!goal.endDate) return "";
+  if (goal.ended) return "Ended";
+  if (goal.lastDay) return goal.hoursLeft === 1 ? "1 hour left" : `${goal.hoursLeft} hours left`;
+  return goal.daysLeft === 1 ? "1 day left" : `${goal.daysLeft} days left`;
+}
+
+export default function GoalProgress({ goal, className = "", compact = false }: GoalProgressProps) {
+  if (!goal) return null;
+  const width = Math.max(0, Math.min(100, goal.percent));
+  const timeLeft = timeLeftLabel(goal);
+  return (
+    <div className={className}>
+      <div className="flex items-baseline justify-between gap-4">
+        <p className="text-foreground">
+          {goal.raised && <span className="text-2xl font-bold tracking-tight">{goal.raised}</span>}
+          <span className={`text-sm text-muted-foreground ${goal.raised ? "ml-1.5" : ""}`}>
+            {goal.raised ? "raised of " : "Goal: "}
+            {goal.target}
+          </span>
+        </p>
+        <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">
+        <div className="h-full rounded-control bg-primary transition-[width]" style={{ width: `${width}%` }} />
+      </div>
+      {(!compact || timeLeft) && (
+        <p className="mt-2 flex justify-between text-xs text-muted-foreground">
+          {!compact && <span>{goal.donationCount === 1 ? "1 donation" : `${goal.donationCount} donations`}</span>}
+          {timeLeft && <span>{timeLeft}</span>}
+        </p>
+      )}
+    </div>
+  );
+}

package/skills/wix-headless-templates/donations/app/hooks/donations/useCampaigns.ts

@@ -0,0 +1,21 @@
+// React binding of the campaigns store (wix/donations/campaigns-store.ts) — the listing logic lives
+// there, framework-free; this hook subscribes to one instance per mounted listing. SSR-friendly:
+// pass server-fetched data as `initialCampaigns` (Astro frontmatter / server component) and no
+// client fetch happens; a SPA passes nothing.
+import { useEffect, useRef, useSyncExternalStore } from "react";
+import { createCampaignsStore, type CampaignsState, type CampaignsStore, type CampaignsStoreOptions } from "../../wix/donations/campaigns-store";
+
+export type UseCampaignsOptions = CampaignsStoreOptions;
+
+export type UseCampaigns = CampaignsState;
+
+export function useCampaigns(options: UseCampaignsOptions = {}): UseCampaigns {
+  const ref = useRef<CampaignsStore | null>(null);
+  if (!ref.current) ref.current = createCampaignsStore(options);
+  const store = ref.current;
+  useEffect(() => {
+    store.start();
+    return () => store.stop();
+  }, [store]);
+  return useSyncExternalStore(store.subscribe, store.getState, store.getState);
+}

package/skills/wix-headless-templates/donations/app/hooks/donations/useDonation.ts

@@ -0,0 +1,27 @@
+// React binding of the donation store (wix/donations/donation-store.ts) — the donate form's state
+// and actions for one campaign. All correctness (defaults, validation, the fee, the checkout line,
+// the hosted redirect) lives in the data layer; you own how it looks. One store per campaign
+// surface; a new campaign id gets a fresh store.
+import { useMemo, useSyncExternalStore } from "react";
+import { createDonationStore, type DonationState, type DonationStore, type DonationStoreOptions } from "../../wix/donations/donation-store";
+import type { CampaignDetail } from "../../wix/donations/types";
+
+export type UseDonationOptions = DonationStoreOptions;
+
+export type UseDonation = DonationState & Omit<DonationStore, "getState" | "subscribe">;
+
+export function useDonation(campaign: CampaignDetail, options: UseDonationOptions = {}): UseDonation {
+  // eslint-disable-next-line react-hooks/exhaustive-deps
+  const store = useMemo(() => createDonationStore(campaign, options), [campaign.id]);
+  const state = useSyncExternalStore(store.subscribe, store.getState, store.getState);
+  return {
+    ...state,
+    selectPreset: store.selectPreset,
+    selectCustom: store.selectCustom,
+    setCustomAmount: store.setCustomAmount,
+    setFrequency: store.setFrequency,
+    setCoverFee: store.setCoverFee,
+    setNote: store.setNote,
+    donate: store.donate,
+  };
+}

package/skills/wix-headless-templates/donations/app/hooks/donations/useDonationReceipt.ts

@@ -0,0 +1,19 @@
+// React binding of the receipt store (wix/donations/receipt-store.ts) — the thank-you page's order
+// read. Reads `?orderId=` (or `?orderid=`) from the browser URL when no id is passed, so mount the
+// consuming island client:only. `receipt` null once `loading` is false is a normal outcome (the
+// order may not be readable by the visitor) — thank without order facts then.
+import { useEffect, useRef, useSyncExternalStore } from "react";
+import { createReceiptStore, type ReceiptState, type ReceiptStore } from "../../wix/donations/receipt-store";
+
+export type UseDonationReceipt = ReceiptState;
+
+export function useDonationReceipt(orderId?: string): UseDonationReceipt {
+  const ref = useRef<ReceiptStore | null>(null);
+  if (!ref.current) ref.current = createReceiptStore(orderId);
+  const store = ref.current;
+  useEffect(() => {
+    store.start();
+    return () => store.stop();
+  }, [store]);
+  return useSyncExternalStore(store.subscribe, store.getState, store.getState);
+}

package/skills/wix-headless-templates/donations/app/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/app/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/app/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/app/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;
+      }
+    },
+  };
+}