@haruhimemoe/crowdfund

Crowdfunding state as data: zod schemas for goals, stretch tiers, donations and refunds, and pure functions for totals, goal progress, tiers and donor leaderboards. Money is integer minor units in any currency. Subpaths turn Ko-fi, Stripe, PayPal, GitHub Sponsors and Buy Me a Coffee webhooks into donations and refunds, with no provider SDK. No runtime dependencies besides zod. ESM for Node 22.12+, Bun, Deno, browsers and edge runtimes.

It never moves money. Your payment provider takes the payment; this package records what it reports and adds it up. Storage, routes and UI stay in your app.

bun add @haruhimemoe/crowdfund zodnpm install @haruhimemoe/crowdfund zoddeno add npm:@haruhimemoe/crowdfund npm:zod

zod (4.0.16 or later in 4.x) is a peer dependency, so your app and this package share one copy and the schemas compose with yours.

A Ko-fi webhook route, with any framework:

import { CrowdfundError, hasDonation } from "@haruhimemoe/crowdfund";import { kofiToDonation, parseKofiBody, verifyKofiToken } from "@haruhimemoe/crowdfund/kofi";export const POST = async (request: Request) => {  let donation;  try {    const payload = parseKofiBody(await request.text());    if (!verifyKofiToken(payload.verification_token, process.env.KOFI_TOKEN ?? "")) {      return new Response(null, { status: 401 });    }    donation = kofiToDonation(payload, { id: crypto.randomUUID() });  } catch (error) {    // Every CrowdfundError here is about the payload, so a retry won't help. Answer 400    // without echoing the message: the token hasn't been checked yet.    if (error instanceof CrowdfundError) return new Response(null, { status: 400 });    throw error;  }  if (donation && !hasDonation(await db.donations.all(), donation)) {    await db.donations.insert(donation);  }  return new Response(null, { status: 200 });};

A crowdfund page:

import { goalProgress, nextTier, topDonors, unlockedTiers } from "@haruhimemoe/crowdfund";const progress = goalProgress(goal, donations);// { currency: "USD", goal: 100000, raised: 42500, remaining: 57500, percent: 42, reached: false }unlockedTiers(tiers, progress.raised); // tiers at or under 425.00nextTier(tiers, progress.raised); // { tier, remaining: 7500 } or nulltopDonors(donations, { currency: "USD", limit: 10 }); // anonymous donors show as "Anonymous"

Show amounts with Intl.NumberFormat, dividing by 10 ** currencyExponent(currency).

• Amounts are integers in the currency's minor unit: cents for USD, yen for JPY, fils for KWD. currencyExponent says how many decimals a currency has. No function does float math on money.
• Totals that leave the safe integer range throw overflow.
• A refund is part of a donation (refund: Refund | null). It can be partial. A refund bigger than its donation throws refund-exceeds-amount, so net totals are never negative.
• Totals in one currency count other currencies through the donation's settled value (its worth in another currency, fixed when it was taken) or your convert(amount, from, to). Without either, they're skipped. A converted net is the converted gross scaled by net / amount, rounded down, and the converted refunded is gross minus net, so it can be up to 1 minor unit high per partly refunded donation. convert must return an integer of 0 or more, or it throws bad-convert.

Plain z.objects with no refinements. Functions check amounts they rely on (bad-amount), but parse records from outside with these first, so .extend() adds your own fields (an edition id, a user's osu! id, a banner choice). Ids are strings. Dates are ISO 8601 strings with Z or an offset.

Each has a matching type: FundingGoal, GoalTier, Donation, Refund, Settled.

CrowdfundError has a code: "bad-amount" | "bad-currency" | "refund-exceeds-amount" | "already-refunded" | "overflow" | "bad-convert" | "bad-kofi-body" | "bad-webhook-body".

Ko-fi posts application/x-www-form-urlencoded with one data field holding JSON. These functions are pure; your route reads the body and answers.

A parsed payload still holds the verification token and the donor's email. Don't log or store it raw. kofiToDonation copies neither. Pass your own id: the Ko-fi transaction id can prove who paid, so keep it out of public pages (publicDonation drops it).

Each provider has its own subpath, so you load only the one you use. All of them verify with Web Crypto, need no provider SDK and make no HTTP calls. Each gives you the provider's id as externalId, so dedupeDonations and hasDonation catch redelivered events. Refund helpers return { externalId, refund }: find the donation with that externalId, then call refundDonation(donation, refund, { replace: true }), because Stripe and PayPal report the total refunded so far. None of them copies the payer's email into the donation.

Every parse* function throws CrowdfundError bad-webhook-body for a body that isn't JSON or doesn't match. Verify the signature before you parse.

PayPal signs with a certificate, so this subpath doesn't check the signature itself. Send paypalVerifyBody(...) as JSON to POST https://api-m.paypal.com/v1/notifications/verify-webhook-signature with your access token, and trust the event only when the answer is { "verification_status": "SUCCESS" }.

MIT