// npm install @token-gesture/billing   —   Node 20+, no dependencies
import { BillingClient } from "@token-gesture/billing";

const billing = new BillingClient({
  baseUrl: process.env.BILLING_API_URL!,
  apiKey:  process.env.BILLING_API_KEY!,
  subject: "organisation",   // or "user" — see below
  product: ["free", "pro", "team"],
});

const plans = await billing.plans.list();
const team  = plans.find((p) => p.slug === "team-monthly");

const { checkout_url } = await billing.checkout.create({
  organisationId,
  plan: team!,             // the object, so a free plan is caught here
  currency: "AUD",       // AUD · NZD · USD · EUR · JPY
});

redirect(checkout_url);

import { verifyWebhook } from "@token-gesture/billing/webhooks";

app.post("/webhooks/billing", express.raw({ type: "*/*" }), (req, res) => {
  let event;
  try {
    event = verifyWebhook({
      body: req.body,                            // the bytes, not a parsed object
      signature: req.headers["x-webhook-signature"],
      secret: process.env.BILLING_WEBHOOK_SECRET!,
    });
  } catch (err) {
    // reason: missing_signature | bad_signature | stale | malformed
    return res.sendStatus(400);
  }

  switch (event.type) {
    case "subscription.activated": grantAccess(event.data); break;
    case "subscription.renewed":   extendPeriod(event.data); break;
    case "subscription.expired":   revokeAccess(event.data); break;
    case "payment.charged_back":   flagForReview(event.data); break;
  }

  res.sendStatus(200);   // delivery is one attempt — 200 fast, work after
});

# Create a checkout for a customer
curl -X POST https://payments.token-gesture.com/api/service/checkout \
  -H "X-API-Key: $BILLING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id":   "org_7f3a91",
    "plan_slug": "team-monthly",
    "currency":  "AUD"
  }'

# → 200 OK
# {
#   "checkout_url":    "https://secure.tg-pay.com/fp/s/48812?sign=…",
#   "subscription_id": "sub_01JQ8M2X",
#   "expires_at":      "2026-09-13T04:22:11Z"
# }

# Read one customer's subscription
curl https://payments.token-gesture.com/api/service/subscriptions/org_7f3a91 \
  -H "X-API-Key: $BILLING_API_KEY"

// A page of accounts is one request, not one request per account.
// Answers a Map holding only the subjects that have a subscription.
const found  = await billing.subscriptions.bulk(organisationIds);
const paying = organisationIds.filter((id) => found.has(id));

// The server refuses more than 200 distinct subjects rather than
// truncating: an answer about the first 200 of your 300 would report
// the rest as unsubscribed and you could not tell. Page instead.
for (const page of chunk(organisationIds, 200)) {
  const found = await billing.subscriptions.bulk(page);
  …
}