Cheerkit

Add one-off support payments to an app you already run. Your UI. Your database. Your payment provider. No hosted service in between.

Cheerkit is the payment layer underneath: it records each contribution, confirms it only from the provider's signed webhooks, and gives the owner the tools to check, recover, and export it. It came out of Baseband, which wanted people to support the app inside its own experience instead of sending them to another platform; Baseband's support flow is built on it.

Supported provider: Bachs. More are planned; see the overview.

• Your UI. Cheerkit is headless: a JSON API you build on, or optional ready-made templates (<cheerkit-support>, <cheerkit-admin>) you can restyle.
• Your data. Tables live in your own Postgres or SQLite database, created by migrations you apply. Payer details from the provider are never stored.
• Correct payments. Exact decimal amounts, no double counting, no confirmation from browser redirects, and a review queue for anything that does not match.
• No service. Each website runs its own copy with its own provider account. Nothing is sent anywhere else.

Requirements

• Node.js 24 or later.
• Postgres (through your pg pool) or SQLite (node:sqlite).
• A payment provider account. For Bachs: an API key with payments:write and payments:read, and a webhook endpoint with its signing secret.

Install

npm install @dalgoridim/cheerkit

Quick start

1. Apply the migrations with your own migration tool:

   import { cheerkitMigrations } from "@dalgoridim/cheerkit/server";
   
   for (const { version, sql } of cheerkitMigrations()) {
     // Save each as a migration file, in order.
   }

2. Create the service once, on the server:

   import {
     createBachsCheckoutClient,
     createBachsWebhookVerifier,
   } from "@dalgoridim/cheerkit/bachs";
   import { postgresDatabase } from "@dalgoridim/cheerkit/postgres";
   import {
     createSupportHandler,
     createSupportService,
     openStore,
     startPendingWorker,
   } from "@dalgoridim/cheerkit/server";
   
   const scope = {
     organizationId: env.BACHS_ACCOUNT_ID,
     environment: "live",
   } as const;
   
   const store = await openStore({
     ...scope,
     installationId: "my-site",
     database: postgresDatabase(pool),
   });
   await store.syncContext({
     id: "coffee",
     name: "Coffee",
     collectName: true,
     collectMessage: true,
     currencies: [
       {
         currency: "NGN",
         fractionDigits: 2,
         minimum: "1500",
         suggestedAmounts: ["1500", "3000"],
       },
     ],
   });
   
   const service = createSupportService({
     store,
     checkout: createBachsCheckoutClient({
       ...scope,
       secretKey: env.BACHS_SECRET_KEY,
       successUrl: "https://my-site.example/coffee?return=1",
       cancelUrl: "https://my-site.example/coffee",
     }),
     webhooks: createBachsWebhookVerifier({
       ...scope,
       secret: env.BACHS_WEBHOOK_SECRET,
     }),
     resultSecret: env.CHEERKIT_RESULT_SECRET,
     retention: { supporterDataDays: 30 },
   });
   
   export const handle = createSupportHandler(service, {
     basePath: "/api/support",
     allowedOrigins: ["https://my-site.example"],
     clientKey: (request) => trustedClientAddress(request),
   });
   
   startPendingWorker(service, {
     intervalMs: 60_000,
     pageSize: 50,
     maxPages: 20,
   });

3. Route /api/support/* to handle (it takes a Request and returns a Response), and register https://my-site.example/api/support/webhooks/bachs as the webhook URL in Bachs.

4. From your page, start a contribution and send the supporter to the provider's checkout:

   const submissionKey = crypto.randomUUID(); // keep it for retries
   const response = await fetch("/api/support/contributions", {
     method: "POST",
     headers: { "Content-Type": "application/json" },
     body: JSON.stringify({
       contextId: "coffee",
       submissionKey,
       submission: { amount: "3000", currency: "NGN" },
     }),
   });
   const { contribution, resultToken } = await response.json();
   location.assign(contribution.checkoutUrl);

   When they come back, poll POST /api/support/contributions/status with { contributionId, resultToken } until the outcome is confirmed.

env, pool, and trustedClientAddress are yours. A runnable version with a fake Bachs is in examples/.

Package

| Import | For | In browsers | | ----------------------------------------- | ----------------------------------------------------------------------------------------------------- | ----------- | | @dalgoridim/cheerkit | Contexts, amounts, intents, metadata validation | Yes | | @dalgoridim/cheerkit/bachs | Bachs provider: clients and webhook verification | No | | @dalgoridim/cheerkit/postgres | Adapter for a pg pool (no dependency on pg) | No | | @dalgoridim/cheerkit/sqlite | Adapter for a node:sqlite database | No | | @dalgoridim/cheerkit/server | Migrations, store, services, HTTP handlers, background worker | No | | @dalgoridim/cheerkit/server/local-admin | Local loopback-only admin runner (startLocalAdmin) | No | | @dalgoridim/cheerkit/ui | Ready-made templates (<cheerkit-support>, <cheerkit-admin>), createSupport, createOwnerClient | Only |

The cheerkit-admin executable starts the local admin from a host-owned config module; see the guide.

Documentation

• Overview: what Cheerkit does, where it stands, and what is planned.
• Guide: setting up, taking payments, building an owner admin, and running in production.
• Reference: every export, option, route, status, and error code.
• Changelog.

Licence

MIT