Subchapter 16.269

Seed Donations

Pricing Plans

Rentalsstatic

Restaurants

815 more in the appendix

Seed Donations

export async function setCampaignCoverImage

export async function setupDonations

This file

Number: 16.269
Position: 269 of 828
Type: JavaScript
Size: 13 KB
Lines: 252

Nearby

Source

donations/seed/seed-donations.mjs

JavaScript252 lines13 KB

1// Donations seed — a BUILD-TIME script, never shipped in the app. Run from the project root
2// (where wix.config.json lives) with a plan file:
3//
4//   node <SKILL_ROOT>/templates/donations/seed/seed-donations.mjs plan.json
5//
6// It mints its own site token via the Wix CLI, sets the site currency when the plan names one,
7// installs the eCom platform and the Wix Donations app if needed, creates the campaigns (one create
8// call per campaign), verifies each is readable, then imports and attaches cover images in a second
9// pass. Prints a JSON result to stdout.
10//
11// Plan shape (see SEED.md):
12//   { "currency"?: "USD",
13//     "campaigns": [{ "name" (1-65 chars),
14//                     "frequencies"?: ["ONE_TIME"|"WEEK"|"MONTH"|"YEAR"] (1-4, default ["ONE_TIME"]),

seed-donations.mjs on GitHub

// "presets"?: [{ "amount" (decimal string), "impact"? (≤200 chars) }] (≤20),

// "customAmount"?: { "enabled", "min"?, "max"? },

// "goal"?: { "target", "endDate"?, "acceptAfterGoal"?, "acceptAfterEndDate"? },

// "comments"?: false, "askCoverFee"?: false,

// "imageMediaId"? | "imageUrl"? | "imagePath"? | "imagePrompt"? }] }

//

// Seeding is ADDITIVE and idempotent — a non-archived campaign with the same name is reused, never

// duplicated; nothing is deleted or overwritten. Unexpected shapes → read the live API reference;

// every call below carries a docs: line with its reference page.

import { setSiteCurrency } from "../../shared/seed/site.mjs";

import { resolveItemImages } from "../../shared/seed/images.mjs";

import { seedSiteId } from "../../shared/seed/site-context.mjs";

import { wixToken } from "../../shared/seed/wix-cli.mjs";

import { isMain } from "../../shared/seed/main.mjs";

import { readFileSync } from "node:fs";

import { randomUUID } from "node:crypto";

const API = "https://www.wixapis.com";

export const DONATIONS_APP_ID = "333b456e-dd48-4d6b-b32b-9fd48d74e163";

export const ECOM_PLATFORM_APP_ID = "1380b703-ce81-ff05-f115-39571d94dfcd"; // Checkout & Orders — a donation is an eCom checkout

const CAMPAIGNS = "/donation-campaigns/v2/donation-campaigns";

const D = "https://dev.wix.com/docs/api-reference/business-solutions/donations/donation-campaigns";

const FREQUENCIES = ["ONE_TIME", "WEEK", "MONTH", "YEAR"];

export function makeCtx({ cwd = process.cwd() } = {}) {

// The content site: the config's site, or the parent on a migration preview (site-context.mjs stops

// a seed there unless --allow-parent is passed after the user confirmed).

const siteId = seedSiteId({ cwd, argv: process.argv });

const token = wixToken(siteId, cwd);

return { token, siteId };

}

async function req(ctx, path, { method = "POST", body } = {}) {

const res = await fetch(API + path, {

method,

headers: {

Authorization: `Bearer ${ctx.token}`,

"wix-site-id": ctx.siteId,

"Content-Type": "application/json",

},

body: body ? JSON.stringify(body) : undefined,

});

const json = await res.json().catch(() => ({}));

if (!res.ok) {

const e = new Error(`${method} ${path} -> ${res.status}: ${JSON.stringify(json).slice(0, 400)}`);

e.status = res.status;

throw e;

}

return json;

}

const sleep = (ms) => new Promise((r) => setTimeout(r, ms));

const money = (v) => ({ amount: String(v) }); // amounts are decimal STRINGS in the site currency

// ---- plan → create body ----------------------------------------------------------------------------

// The rules the API enforces (the create call rejects otherwise): name 1-65 chars; 1-4 frequencies;

// ≤20 presets, each with a REQUIRED client-supplied GUID id and a ≤200-char description; when the

// custom amount is off at least one preset. Defaults when the plan says nothing: one-time only, no

// note, no fee prompt; a campaign with no presets gets the custom amount enabled with no limits.

export function buildCampaign(c) {

if (!c.name || c.name.length > 65) throw new Error(`campaign name must be 1-65 chars: "${c.name ?? ""}"`);

const frequencies = (c.frequencies?.length ? c.frequencies : ["ONE_TIME"]).map((f) => String(f).toUpperCase());

for (const f of frequencies) if (!FREQUENCIES.includes(f)) throw new Error(`"${c.name}": unknown frequency "${f}" — one of ${FREQUENCIES.join(", ")}`);

if (frequencies.length > 4) throw new Error(`"${c.name}": at most 4 frequencies`);

const presets = (c.presets ?? []).map((p) => {

const amount = typeof p === "object" ? p.amount : p;

const impact = typeof p === "object" ? p.impact ?? p.description : undefined;

if (impact && impact.length > 200) throw new Error(`"${c.name}": impact text over 200 chars`);

return { id: randomUUID(), price: money(amount), ...(impact ? { description: impact } : {}) };

});

if (presets.length > 20) throw new Error(`"${c.name}": at most 20 preset amounts`);

const custom = c.customAmount ?? (presets.length ? { enabled: false } : { enabled: true });

const customEnabled = custom.enabled !== false;

if (!customEnabled && !presets.length) throw new Error(`"${c.name}": needs a preset amount or customAmount.enabled`);

const body = {

name: c.name,

donationFrequencies: frequencies,

predefinedDonationAmounts: presets,

customAmountEnabled: customEnabled,

commentsEnabled: c.comments === true,

askDonorCoverFee: c.askCoverFee === true,

};

if (customEnabled && (custom.min != null || custom.max != null)) {

body.customAmountOptions = {

...(custom.min != null ? { minimum: money(custom.min) } : {}),

...(custom.max != null ? { maximum: money(custom.max) } : {}),

};

}

if (c.goal?.target != null) {

body.campaignGoal = {

targetAmount: money(c.goal.target),

...(c.goal.endDate ? { endDate: c.goal.endDate } : {}),

...(c.goal.acceptAfterGoal != null ? { acceptDonationsAfterGoal: c.goal.acceptAfterGoal } : {}),

...(c.goal.acceptAfterEndDate != null ? { acceptDonationsAfterEndDate: c.goal.acceptAfterEndDate } : {}),

};

}

return body;

}

// ---- operations ------------------------------------------------------------------------------------

// Idempotent: re-installing an already-installed app returns 200. eCom first — a donation is an eCom

// checkout; whether installing Donations provisions eCom by itself is not verified, so both go in.

// docs: https://dev.wix.com/docs/api-reference/articles/work-with-wix-apis/platform/about-apps-created-by-wix.md

export async function installApp(ctx, appDefId) {

try {

await req(ctx, "/apps-installer-service/v1/app-instance/install", { body: {

tenant: { tenantType: "SITE", id: ctx.siteId },

appInstance: { appDefId, enabled: true },

} });

return true;

} catch (e) {

return `not installed here (${String(e.message).slice(0, 160)}) — the owner can add Wix Donations from the dashboard's App Market`;

}

export async function installDonationsApps(ctx) {

return { ecom: await installApp(ctx, ECOM_PLATFORM_APP_ID), donations: await installApp(ctx, DONATIONS_APP_ID) };

}

// A non-archived campaign with this exact name, when one exists (`name` is filterable).

// docs: https://dev.wix.com/docs/api-reference/business-solutions/donations/donation-campaigns/query-donation-campaigns.md

export async function findCampaignByName(ctx, name) {

const r = await req(ctx, `${CAMPAIGNS}/query`, { body: { query: { filter: { name, archived: false }, cursorPaging: { limit: 1 } } } });

return r.donationCampaigns?.[0] ?? null;

}

// docs: https://dev.wix.com/docs/api-reference/business-solutions/donations/donation-campaigns/get-donation-campaign.md

export async function getCampaign(ctx, id) {

return (await req(ctx, `${CAMPAIGNS}/${id}`, { method: "GET" })).donationCampaign;

}

// Create, then verify the campaign reads back (the read side can lag the write by a moment — retry

// the GET a few times, never the POST). Reuses an existing campaign of the same name.

// docs: https://dev.wix.com/docs/api-reference/business-solutions/donations/donation-campaigns/create-donation-campaign.md

export async function createCampaign(ctx, plan) {

const existing = await findCampaignByName(ctx, plan.name).catch(() => null);

if (existing?.id) return { id: existing.id, name: existing.name, status: existing.status, created: false };

const r = await req(ctx, CAMPAIGNS, { body: { donationCampaign: buildCampaign(plan) } });

const id = r.donationCampaign?.id;

if (!id) throw new Error(`Campaign "${plan.name}" was not created — no id returned.`);

let verified = null;

for (let attempt = 0; attempt < 4 && !verified; attempt++) {

verified = await getCampaign(ctx, id).catch(() => null);

if (!verified) await sleep(1000 * (attempt + 1));

}

return { id, name: plan.name, status: verified?.status ?? r.donationCampaign?.status ?? null, created: true, verified: !!verified };

}

export async function createCampaigns(ctx, campaigns) {

const out = [];

for (const c of campaigns) out.push({ ...(await createCampaign(ctx, c)), plan: c });

return out;

}

// Attach a Wix Media file as the cover image. The Image object's shape follows the SDK's transforms

// ({ id, url, height, width, altText }); whether the update needs a field mask is not verified live,

// so a plain PATCH is tried first and one with an explicit mask second. Revision comes from a fresh

// GET (an optimistic-locking field).

// docs: https://dev.wix.com/docs/api-reference/business-solutions/donations/donation-campaigns/update-donation-campaign.md

export async function setCampaignCoverImage(ctx, { campaignId, id, url, height = 1024, width = 1024, altText }) {

const current = await getCampaign(ctx, campaignId);

const donationCampaign = { id: campaignId, revision: current.revision, coverImage: { id, url, height, width, ...(altText ? { altText } : {}) } };

try {

return await req(ctx, `${CAMPAIGNS}/${campaignId}`, { method: "PATCH", body: { donationCampaign } });

} catch (first) {

if (first.status !== 400) throw first;

return req(ctx, `${CAMPAIGNS}/${campaignId}`, { method: "PATCH", body: { donationCampaign, fieldMask: { paths: ["coverImage"] } } });

}

/**

* ONE-CALL seed: site currency (if named) → install eCom + Donations → one create per campaign

* (verified) → images in a second pass. The default path.

*/

export async function setupDonations(ctx, { campaigns = [], currency } = {}) {

if (!campaigns.length) throw new Error("plan.campaigns is empty — nothing to seed");

// Before any campaign exists: every amount is stored in the site currency.

if (currency) await setSiteCurrency(ctx, currency);

const installed = await installDonationsApps(ctx);

const created = await createCampaigns(ctx, campaigns);

// Pass 2 — images: resolve (upload a local file / import by url / generate by prompt) in one

// parallel wave, then attach. Failures leave the campaign text-only; the exit never depends on them.

const wanted = created.filter((c) => c.created && (c.plan.imageMediaId || c.plan.imageUrl || c.plan.imagePath || c.plan.imagePrompt));

const files = await resolveItemImages(ctx, wanted.map((c) => ({

mediaId: c.plan.imageMediaId,

url: c.plan.imageUrl,

path: c.plan.imagePath,

prompt: c.plan.imagePrompt,

displayName: `${c.name.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "") || "campaign"}.png`,

})));

let imagesAttached = 0;

const imageErrors = [];

for (let i = 0; i < wanted.length; i++) {

if (!files[i]) continue;

try {

await setCampaignCoverImage(ctx, { campaignId: wanted[i].id, id: files[i].id, url: files[i].url, altText: wanted[i].name });

imagesAttached++;

} catch (e) {

imageErrors.push(`${wanted[i].name}: ${String(e.message).slice(0, 200)}`); // never block on an image

}

const recurring = created.some((c) => (c.plan.frequencies ?? []).some((f) => String(f).toUpperCase() !== "ONE_TIME"));

return {

installed,

campaigns: created.map(({ id, name, status, created: isNew, verified }) => ({ id, name, status, created: isNew, ...(isNew ? { verified } : {}) })),

imagesAttached,

...(imageErrors.length ? { imageErrors } : {}),

// Completing a donation needs a premium plan + a connected payment method in the dashboard —

// not a seeding failure; surface it to the owner.

notes: [

"Taking real donations requires a premium plan and a connected payment method in the dashboard; until then the hosted checkout refuses the payment.",

...(recurring ? ["Recurring frequencies (WEEK/MONTH/YEAR) also need a payment provider that supports recurring payments."] : []),

],

};

}

// ---- CLI entry ----------------------------------------------------------------------------------

const invokedDirectly = isMain(import.meta.url);

if (invokedDirectly) {

const planPath = process.argv[2];

if (!planPath) {

console.error("usage: node seed-donations.mjs <plan.json> (run from the project root)");

process.exit(1);

}

const plan = JSON.parse(readFileSync(planPath, "utf8"));

const ctx = makeCtx();

setupDonations(ctx, plan)

.then((result) => console.log(JSON.stringify(result, null, 2)))

.catch((e) => {

console.error(e.message);

process.exit(1);

});

}