@1st-flock/donations-embed-node

Server-side Node SDK for the 1st Flock Donations Embed API. Typed client for donations and recurring schedules, plus a constant-time HMAC-SHA256 webhook verifier. Zero runtime dependencies; ships ESM and CJS.

Install

npm install @1st-flock/donations-embed-node
# or
pnpm add @1st-flock/donations-embed-node
# or
yarn add @1st-flock/donations-embed-node

Requires Node 18.17 or newer (Bun and Deno work too with their Node-compat shims). No third-party runtime dependencies — just Node's built-in fetch and crypto.

Quickstart

import { Client } from "@1st-flock/donations-embed-node";

const client = new Client({ apiKey: process.env.FLOCK_SECRET_KEY! });

// List the most recent 25 donations.
const page = await client.listDonations({ limit: 25 });
for (const donation of page.donations) {
  console.log(donation.id, donation.gross_amount_cents, donation.status);
}

Run this against a sandbox key (sk_test_…) and any donation made through the embed (e.g. with sandbox card 4111 1111 1111 1111, exp 10/29, CVV 123) shows up here within a few seconds.

Configuration

Generate keys in the 1st Flock account portal under Donations Setup → Embed Keys (full guide). The server SDK requires a secret key:

• Secret keys (sk_live_…, sk_test_…) — server-only. Never ship a secret key to a browser or any client-rendered code. Treat them like any other production credential — store in a secrets manager, rotate on suspicion of compromise.
• Webhook signing secret — issued separately when you create or rotate a webhook endpoint. Used by verifyWebhook to authenticate inbound deliveries. Store alongside the secret key.

The constructor rejects publishable keys (pk_…) at construction time with a clear TypeError so misconfiguration surfaces synchronously rather than as a confusing 401.

const client = new Client({
  apiKey: process.env.FLOCK_SECRET_KEY!,
  // Optional overrides:
  baseUrl: "https://api.sandbox.1stflock.com", // also auto-resolved by sk_test_ prefix
  retries: 3,        // retries on 5xx + network errors (default 3)
  timeout: 30_000,   // per-request timeout in ms (default 30_000)
  logger: console,   // anything with debug(message, ...args)
});

Test mode

Pass a sandbox key (sk_test_…) — the SDK routes to the sandbox cluster automatically based on the _test_ prefix. No real money moves. Same code path, same wire format, same webhook events. Donations show up in the hub with a TEST badge and never appear in the production ledger.

Common tasks

List + paginate donations

let cursor: string | undefined;
do {
  const page = await client.listDonations({ cursor, limit: 200 });
  for (const donation of page.donations) {
    await syncToLedger(donation);
  }
  cursor = page.next_cursor ?? undefined;
} while (cursor);

Filter by fund or donor email:

const buildingFundOnly = await client.listDonations({ fundId: "general" });
const samsHistory = await client.listDonations({ donorEmail: "[email protected]" });

Fetch a single donation

const donation = await client.getDonation("8a1b9c4d-1234-4321-9abc-def012345678");
console.log(donation.confirmation_id, donation.gross_amount_cents);

Cross-organization access deliberately collapses to 404 (NotFoundError) so you cannot use the API to confirm whether a UUID belongs to another tenant.

Refund a donation

import { Client, idempotencyKey } from "@1st-flock/donations-embed-node";

// Full refund:
await client.refundDonation(donationId);

// Partial refund with an idempotency key (safe to retry on network blip):
const refund = await client.refundDonation(
  donationId,
  { amountCents: 1000, reason: "Donor adjustment" },
  { idempotencyKey: idempotencyKey("refund") },
);
console.log(refund.processor_refund_id, refund.refund_amount_cents);

The idempotencyKey() helper returns a tagged UUID like "refund:1f2dab36-2a55-4f11-bdc8-2a2a4a95b001". Replays of the same key return the original response without re-contacting the gateway.

List + cancel recurring schedules

const page = await client.listRecurring({ status: "active", limit: 100 });
for (const recurring of page.recurring) {
  if (donorOptedOut(recurring.donor_email)) {
    await client.cancelRecurring(recurring.id, {
      idempotencyKey: idempotencyKey("cancel-recurring"),
    });
  }
}

Fire a synthetic webhook (integration test)

const result = await client.testWebhook("donation.completed");
console.log("test event id:", result.event_id);

The synthetic event's data.object.synthetic flag is set so downstream code can branch on it.

Webhook verification

Verify every inbound delivery with verifyWebhook — constant-time HMAC-SHA256 comparison plus a 5-minute timestamp tolerance to defeat replays.

import express from "express";
import { verifyWebhook, WebhookError } from "@1st-flock/donations-embed-node";

const app = express();

app.post(
  "/webhooks/donations",
  express.raw({ type: "application/json" }), // give us the raw body bytes
  (req, res) => {
    const signature = req.header("Flock-Signature") ?? "";
    try {
      const event = verifyWebhook(req.body, signature, process.env.FLOCK_WEBHOOK_SECRET!);
      switch (event.type) {
        case "donation.completed":
          enqueueReceipt(event.data.object);
          break;
        case "donation.refunded":
          reverseReceipt(event.data.object);
          break;
        case "key.frozen":
          alertOnCall(event.data.object);
          break;
      }
      res.status(204).end();
    } catch (err) {
      // Always 401 — never confirm which check failed.
      if (err instanceof WebhookError) {
        return res.status(401).send("invalid signature");
      }
      throw err;
    }
  },
);

Pass the exact body bytes the platform delivered. Re-serializing the JSON before verifying will invalidate the signature.

verifyWebhook raises typed exceptions on failure (WebhookFormatError, WebhookTimestampError, WebhookSignatureError — all inherit from WebhookError) so you can log distinct failure modes even though the HTTP response is the same 401 in every case.

For consumers that need only the verifier (and don't want to load the API client surface), import from the dedicated subpath:

import { verifyWebhook } from "@1st-flock/donations-embed-node/webhooks";

Errors

Every API call raises a typed exception on a non-2xx response.

| HTTP status | Class | | --- | --- | | 400 / 422 | ValidationError | | 401 | AuthError | | 403 | ForbiddenError | | 404 | NotFoundError | | 409 | ConflictError | | 410 | GoneError | | 429 | RateLimitError (carries retryAfterSeconds) | | 502 | BadGatewayError | | 503 | ServiceUnavailableError | | Other | ApiError |

All inherit from ApiError and expose statusCode, code, message, details, and requestId.

import { ApiError, RateLimitError, ConflictError } from "@1st-flock/donations-embed-node";

try {
  await client.refundDonation(donationId, { amountCents: 1000 });
} catch (err) {
  if (err instanceof RateLimitError) {
    await sleep((err.retryAfterSeconds ?? 1) * 1000);
    return retry();
  }
  if (err instanceof ConflictError) {
    return console.warn("Already refunded:", donationId);
  }
  if (err instanceof ApiError) {
    console.error(`API error ${err.statusCode} ${err.code}: ${err.message}`);
  }
  throw err;
}

Full documentation

The full reference — every endpoint, every error code, the webhook event catalogue with payload schemas, and operations guidance — lives at 1stflock.com/developers/donations-embed/.

Vendor neutrality

This SDK never names the underlying payment processor, bank-link service, or any other third-party vendor in customer-facing strings. Donations carry vendor-neutral identifiers (processor_transaction_id, processor_refund_id, processor_subscription_id); errors route through 1st Flock's own taxonomy. The underlying integrations are an implementation detail and may change without notice — your code never has to.

License

MIT — see LICENSE.

Reporting issues

File issues at gitlab.com/1st-flock/donations/-/issues with the label donations-embed-node.