Capstone: a production SaaS

import { createConfigManager, createDefaultsConfigSource, createEnvironmentConfigSource } from "@zudojs/config";
import { ConfigurationError } from "@zudojs/errors";
import { isSchemaValidationError, schema, type Infer } from "@zudojs/schema";

const ConfigSchema = schema.object({
  node_env: schema.enum(["development", "test", "production"]),
  port: schema.coerce.number().int().min(0).max(65535),
  provider_url: schema.string().url(),
  provider_secret: schema.string().min(16).max(256),
  provider_timeout_ms: schema.coerce.number().int().min(50).max(30_000),
  receipts_dir: schema.string().min(1),
});

export type AppConfig = Readonly<Infer<typeof ConfigSchema>>;

/** Reads FEESDESK_* variables over safe defaults; refuses to start on anything invalid. */
export async function loadConfig(env: Record<string, string | undefined>): Promise<AppConfig> {
  const manager = createConfigManager({
    sources: [
      createDefaultsConfigSource({ node_env: "development", port: 3000, provider_timeout_ms: 2000 }),
      createEnvironmentConfigSource({ prefix: "FEESDESK_", env, priority: 20 }),
    ],
  });
  await manager.load();
  try {
    return Object.freeze(ConfigSchema.parse(manager.toObject()));
  } catch (error) {
    if (!isSchemaValidationError(error)) throw error;
    const problems = error.issues.map((issue) => `${issue.path.join(".").toUpperCase()}: ${issue.message}`);
    throw new ConfigurationError(`Invalid configuration. ${problems.join("; ")}`);
  }
}

import { loadConfig } from "./config.js";

try {
  await loadConfig({ FEESDESK_PORT: "80a", FEESDESK_PROVIDER_URL: "kobopay", FEESDESK_PROVIDER_SECRET: "sk_test_1" });
} catch (error) {
  console.log((error as Error).name);
  for (const problem of (error as Error).message.split(/\. |; /)) console.log("  " + problem);
}

const config = await loadConfig({
  FEESDESK_PROVIDER_URL: "https://api.kobopay.test",
  FEESDESK_PROVIDER_SECRET: "sk_live_0123456789abcdef",
  FEESDESK_RECEIPTS_DIR: "/var/lib/feesdesk/receipts",
});
console.log(config.node_env, config.port, config.provider_timeout_ms, Object.isFrozen(config));

ConfigurationError
  Invalid configuration
  PORT: Cannot coerce string to number
  PROVIDER_URL: Invalid url format
  PROVIDER_SECRET: String must be at least 16 characters
  RECEIPTS_DIR: Required field missing: receipts_dir
development 3000 2000 true

import { PGlite, type Transaction as PgTransaction } from "@electric-sql/pglite";
import { createTransactionContext, createTransactionManager, type Transaction, type TransactionAdapter } from "@zudojs/transactions";

interface Handle {
  readonly tx: PgTransaction;
  readonly finish: (commit: boolean) => void;
  readonly done: Promise<unknown>;
}

/** Runs @zudojs/transactions on PGlite's own transaction, which makes other queries wait. */
function pgliteAdapter(pg: PGlite): TransactionAdapter {
  return {
    capabilities: { savepoints: false, nestedTransactions: false, isolationLevels: [], readOnlyTransactions: false, timeouts: true },
    begin: () =>
      new Promise<Handle>((resolve) => {
        let finish: (commit: boolean) => void = () => {};
        const decided = new Promise<boolean>((settle) => (finish = settle));
        const done = pg.transaction(async (tx) => {
          resolve({ tx, finish, done });
          if (!(await decided)) await tx.rollback();
        });
      }),
    commit: async (handle) => {
      (handle as Handle).finish(true);
      await (handle as Handle).done;
    },
    rollback: async (handle) => {
      (handle as Handle).finish(false);
      await (handle as Handle).done;
    },
  };
}

const SCHEMA = `
  CREATE TABLE schools (id TEXT PRIMARY KEY, name TEXT NOT NULL, status TEXT NOT NULL DEFAULT 'active');
  CREATE TABLE users (id TEXT PRIMARY KEY, email TEXT UNIQUE NOT NULL, name TEXT NOT NULL, password_hash TEXT NOT NULL);
  CREATE TABLE memberships (school_id TEXT NOT NULL REFERENCES schools, user_id TEXT NOT NULL REFERENCES users,
    role TEXT NOT NULL CHECK (role IN ('bursar', 'parent')), PRIMARY KEY (school_id, user_id));
  CREATE TABLE sessions (token_hash TEXT PRIMARY KEY, user_id TEXT NOT NULL REFERENCES users,
    school_id TEXT NOT NULL REFERENCES schools, expires_at TIMESTAMPTZ NOT NULL);
  CREATE TABLE students (id SERIAL PRIMARY KEY, school_id TEXT NOT NULL REFERENCES schools, name TEXT NOT NULL,
    guardian_id TEXT NOT NULL REFERENCES users);
  CREATE TABLE bills (id SERIAL PRIMARY KEY, school_id TEXT NOT NULL REFERENCES schools,
    student_id INT NOT NULL REFERENCES students, term TEXT NOT NULL, due_date DATE NOT NULL,
    amount_kobo INT NOT NULL CHECK (amount_kobo > 0),
    paid_kobo INT NOT NULL DEFAULT 0 CHECK (paid_kobo >= 0 AND paid_kobo <= amount_kobo));
  CREATE TABLE payments (id SERIAL PRIMARY KEY, school_id TEXT NOT NULL REFERENCES schools,
    bill_id INT NOT NULL REFERENCES bills, amount_kobo INT NOT NULL CHECK (amount_kobo > 0),
    status TEXT NOT NULL CHECK (status IN ('pending', 'succeeded', 'declined')),
    idempotency_key TEXT NOT NULL, charge_id TEXT, receipt_key TEXT,
    created_at TIMESTAMPTZ NOT NULL DEFAULT now(), UNIQUE (school_id, idempotency_key));
  CREATE TABLE ledger (id SERIAL PRIMARY KEY, school_id TEXT NOT NULL, payment_id INT NOT NULL REFERENCES payments,
    account TEXT NOT NULL, amount_kobo INT NOT NULL);
`;

export type Queryable = Pick<PGlite, "query">;

/** The database, its transaction manager, and `sql()`: the connection of the current transaction, if any. */
export async function createDatabase() {
  const pg = new PGlite();
  await pg.exec(SCHEMA);
  const context = createTransactionContext();
  const transactions = createTransactionManager({ adapter: pgliteAdapter(pg), context });
  const sql = (): Queryable => transactions.getCurrentHandle<Handle>()?.tx ?? pg;
  /** Runs `work` after `tx` commits, outside it: work started there must not inherit a finished transaction. */
  const afterCommit = (tx: Transaction, work: () => Promise<void>) => tx.afterCommit(() => context.exit(work));
  return { pg, transactions, sql, afterCommit, close: () => pg.close() };
}

export type Database = Awaited<ReturnType<typeof createDatabase>>;

import { createTransactionContext, createTransactionManager, type TransactionAdapter, type TransactionManagerOptions } from "@zudojs/transactions";

// A stand-in adapter: begin, commit and rollback do nothing, so only the context logic runs.
const adapter: TransactionAdapter = {
  capabilities: { savepoints: false, nestedTransactions: false, isolationLevels: [], readOnlyTransactions: false, timeouts: false },
  begin: async () => ({}),
  commit: async () => {},
  rollback: async () => {},
};

async function publishAfterCommit(label: string, options: Partial<TransactionManagerOptions>, wrap = (work: () => Promise<void>) => work()) {
  const manager = createTransactionManager({ adapter, ...options });
  let receiptJob: Promise<void> = Promise.resolve();
  await manager.run(async (payment) => {
    payment.afterCommit(() => wrap(async () => {
      // "publish fee.paid": a handler queues a job that runs a little later and opens its own transaction
      receiptJob = new Promise((resolve) => setTimeout(async () => {
        await manager.run(async (job) => console.log(`${label.padEnd(26)} job sees: ${job.kind}, same transaction as the payment: ${job.id === payment.id}`));
        resolve();
      }, 5));
    }));
  });
  await receiptJob;
}

await publishAfterCommit("plain afterCommit", {});
const context = createTransactionContext();
await publishAfterCommit("afterCommit + context.exit", { context }, (work) => context.exit(work));

plain afterCommit          job sees: participant, same transaction as the payment: true
afterCommit + context.exit job sees: root, same transaction as the payment: false

import { hashPassword, verifyPassword } from "@zudojs/auth";
import { generateSessionToken, hashToken } from "@zudojs/crypto";
import { AuthenticationError } from "@zudojs/errors";
import { schema } from "@zudojs/schema";
import {
  createContextManager,
  createTenantContextStorage,
  createTenantId,
  createTenantManager,
  type Tenant,
  type TenantRepository,
} from "@zudojs/tenancy";

import type { Database } from "./db.js";

/** Who is calling, and for which school. Built only from the session, never from the request body. */
export interface Caller {
  readonly userId: string;
  readonly email: string;
  readonly role: "bursar" | "parent";
  readonly schoolId: string;
}

const Login = schema.object({
  school: schema.string().trim().toLowerCase().min(1).max(40),
  email: schema.string().trim().toLowerCase().email(),
  password: schema.string().min(12).max(128),
});

export function createIdentity(db: Database) {
  const schools: TenantRepository = {
    async findById(id) {
      const { rows } = await db.sql().query<{ id: string; name: string; status: "active" | "suspended" }>(
        "SELECT id, name, status FROM schools WHERE id = $1", [id]);
      const row = rows[0];
      return row && { id: createTenantId(row.id), name: row.name, status: row.status, metadata: {} };
    },
  };
  const tenants = createTenantManager({ repository: schools, storage: createTenantContextStorage() });
  const tenantContext = createContextManager({ storage: createTenantContextStorage() });
  const decoyHash = hashPassword(crypto.randomUUID());

  return {
    tenantContext,
    /** The school of the request in progress; throws outside a request. */
    currentSchool: (): Tenant => tenantContext.requireCurrentTenant(),
    /** Runs background work (a job, a schedule) as one school, the way a request would. */
    async runAs<T>(schoolId: string, work: () => Promise<T>): Promise<T> {
      const school = await tenants.requireActive(createTenantId(schoolId));
      return tenantContext.run(school, work);
    },

    async login(input: unknown): Promise<string> {
      const { school, email, password } = Login.parse(input);
      const { rows } = await db.sql().query<{ id: string; password_hash: string; role: string | null }>(
        `SELECT u.id, u.password_hash, m.role FROM users u
         LEFT JOIN memberships m ON m.user_id = u.id AND m.school_id = $2 WHERE u.email = $1`, [email, school]);
      const valid = await verifyPassword(password, rows[0]?.password_hash ?? (await decoyHash));
      if (!rows[0] || !valid || !rows[0].role) throw new AuthenticationError("Wrong school, e-mail or password");
      const token = await generateSessionToken();
      await db.sql().query("INSERT INTO sessions VALUES ($1, $2, $3, now() + interval '8 hours')",
        [await hashToken(token), rows[0].id, school]);
      return token;
    },

    /** The caller for a bearer token, and the school to run the request in. Suspended schools are refused. */
    async authenticate(token: string | undefined): Promise<{ caller: Caller; school: Tenant }> {
      if (!token) throw new AuthenticationError("Log in first");
      const { rows } = await db.sql().query<Caller>(
        `SELECT u.id AS "userId", u.email, m.role, s.school_id AS "schoolId" FROM sessions s
         JOIN users u ON u.id = s.user_id
         JOIN memberships m ON m.user_id = s.user_id AND m.school_id = s.school_id
         WHERE s.token_hash = $1 AND s.expires_at > now()`, [await hashToken(token)]);
      if (!rows[0]) throw new AuthenticationError("Session expired, log in again");
      return { caller: rows[0], school: await tenants.requireActive(createTenantId(rows[0].schoolId)) };
    },
  };
}

export type Identity = ReturnType<typeof createIdentity>;

/** Seeds a user; used by setup scripts and tests, never by the public API. */
export async function addUser(db: Database, user: { id: string; email: string; name: string; password: string }) {
  await db.sql().query("INSERT INTO users VALUES ($1, $2, $3, $4)",
    [user.id, user.email, user.name, await hashPassword(user.password)]);
}

import { AuthorizationError, NotFoundError } from "@zudojs/errors";
import { allOf, createPermissionActor, createPermissionEngine, isOwner, tenantIsolation } from "@zudojs/permissions";

import type { Caller } from "./identity.js";

/** Parents may read and pay their own children's bills; bursars may read every bill of their school. */
const engine = createPermissionEngine({
  roles: [
    {
      name: "parent",
      permissions: [],
      rules: [{
        effect: "allow", resource: "bill", action: ["read", "pay"],
        condition: allOf(isOwner("guardianId"), tenantIsolation("schoolId", "schoolId")),
      }],
    },
    {
      name: "bursar",
      permissions: [],
      rules: [{ effect: "allow", resource: "bill", action: ["read"], condition: tenantIsolation("schoolId", "schoolId") }],
    },
  ],
});

function can(caller: Caller, permission: string, resource: object): Promise<boolean> {
  const actor = createPermissionActor(caller.userId, { roles: [caller.role] });
  return engine.can(actor, permission, resource, { metadata: { schoolId: caller.schoolId } });
}

/** 404 when the caller may not even see the bill (so ids cannot be probed), 403 when they see it but may not act. */
export async function requireAccess(caller: Caller, action: "read" | "pay", bill: { id: number }): Promise<void> {
  if (!(await can(caller, "bill:read", bill))) throw new NotFoundError(`Bill ${bill.id} was not found`);
  if (action !== "read" && !(await can(caller, `bill:${action}`, bill))) throw new AuthorizationError(`Not allowed to ${action} bill ${bill.id}`);
}

import { requireAccess } from "./access.js";
import type { Caller } from "./identity.js";

const ada: Caller = { userId: "u-ada", email: "ada@example.com", role: "parent", schoolId: "greenfield" };
const bola: Caller = { userId: "u-bola", email: "bola@greenfield.test", role: "bursar", schoolId: "greenfield" };
const tunde: Caller = { userId: "u-tunde", email: "tunde@example.com", role: "parent", schoolId: "unity" };
const chidisBill = { id: 1, schoolId: "greenfield", guardianId: "u-ada" };
const zainabsBill = { id: 2, schoolId: "greenfield", guardianId: "u-kemi" };

const cases: Array<[string, Caller, "read" | "pay", { id: number }]> = [
  ["ada pays her son's bill", ada, "pay", chidisBill],
  ["ada pays another child's", ada, "pay", zainabsBill],
  ["bola reads any bill", bola, "read", zainabsBill],
  ["bola pays a bill", bola, "pay", zainabsBill],
  ["tunde (unity) reads it", tunde, "read", chidisBill],
];
for (const [label, caller, action, bill] of cases) {
  const outcome = await requireAccess(caller, action, bill).then(() => "allowed", (error: { statusCode: number; name: string }) => `${error.statusCode} ${error.name}`);
  console.log(label.padEnd(26), outcome);
}

ada pays her son's bill    allowed
ada pays another child's   404 NotFoundError
bola reads any bill        allowed
bola pays a bill           403 AuthorizationError
tunde (unity) reads it     404 NotFoundError

import { createServer } from "node:http";
import type { AddressInfo } from "node:net";

/**
 * "KoboPay", a pretend card provider running in this process on a random port.
 * Tests steer it with `controls`: add latency, fail the next N calls with 503.
 */
export async function startKoboPay(secretKey: string) {
  const charges = new Map<string, object>();
  const controls = { latencyMs: 0, failNext: 0, chargeCalls: 0 };

  const server = createServer(async (req, res) => {
    const send = (status: number, body: object) =>
      res.writeHead(status, { "content-type": "application/json", connection: "close" }).end(JSON.stringify(body));
    let raw = "";
    for await (const chunk of req) raw += chunk;
    await new Promise((resolve) => setTimeout(resolve, controls.latencyMs));
    if (req.headers.authorization !== `Bearer ${secretKey}`) return send(401, { error: "invalid_api_key" });
    if (req.url === "/v1/health") return send(200, { ok: true });
    if (controls.failNext > 0) {
      controls.failNext -= 1;
      return send(503, { error: "temporarily_unavailable" });
    }
    const key = String(req.headers["idempotency-key"] ?? "");
    const previous = charges.get(key);
    if (previous) return send(200, previous);
    controls.chargeCalls += 1;
    const input = JSON.parse(raw) as { amount: number; source: string };
    const charge = input.source === "tok_declined"
      ? { id: `ch_${charges.size + 1}`, status: "failed", amount: input.amount, failure_message: "insufficient_funds" }
      : { id: `ch_${charges.size + 1}`, status: "succeeded", amount: input.amount, failure_message: null };
    charges.set(key, charge);
    send(200, charge);
  });

  await new Promise<void>((resolve) => server.listen(0, "127.0.0.1", resolve));
  return {
    url: `http://127.0.0.1:${(server.address() as AddressInfo).port}`,
    controls,
    async stop(): Promise<void> {
      server.closeAllConnections();
      await new Promise((resolve) => server.close(resolve));
    },
  };
}

import { createHealthyHealth, createUnhealthyHealth, type AdapterHealth, type LifecycleAdapter } from "@zudojs/adapters";
import { ServiceUnavailableError } from "@zudojs/errors";
import { retry, runWithTimeout } from "@zudojs/rpc";

export interface ChargeRequest {
  /** Our payment reference; the provider treats it as an idempotency key. */
  readonly reference: string;
  readonly amountKobo: number;
  readonly cardToken: string;
}

export type ChargeResult =
  | { readonly status: "succeeded"; readonly chargeId: string }
  | { readonly status: "declined"; readonly reason: string };

/** What FeesDesk needs from any card provider. Nothing here is KoboPay-specific. */
export interface PaymentProvider extends LifecycleAdapter {
  charge(request: ChargeRequest, signal: AbortSignal): Promise<ChargeResult>;
}

export class KoboPayAdapter implements PaymentProvider {
  readonly name = "kobopay";
  readonly version = "1.0.0";
  readonly capabilities = { http: true, abortSignal: true };

  constructor(private readonly baseUrl: string, private readonly secretKey: string) {}

  private call(path: string, signal: AbortSignal, init: RequestInit = {}) {
    return fetch(`${this.baseUrl}${path}`, {
      ...init, signal, headers: { authorization: `Bearer ${this.secretKey}`, "content-type": "application/json", ...init.headers },
    });
  }

  async charge(request: ChargeRequest, signal: AbortSignal): Promise<ChargeResult> {
    const response = await this.call("/v1/charges", signal, {
      method: "POST",
      headers: { "idempotency-key": request.reference },
      body: JSON.stringify({ amount: request.amountKobo, currency: "NGN", source: request.cardToken }),
    });
    if (response.status >= 500) throw new ServiceUnavailableError(`KoboPay answered ${response.status}`);
    if (!response.ok) throw new Error(`KoboPay refused the request with ${response.status}`);
    const body = (await response.json()) as { id: string; status: string; failure_message: string | null };
    return body.status === "succeeded"
      ? { status: "succeeded", chargeId: body.id }
      : { status: "declined", reason: body.failure_message ?? "declined" };
  }

  async health(): Promise<AdapterHealth> {
    try {
      const response = await this.call("/v1/health", AbortSignal.timeout(1000));
      return response.ok ? createHealthyHealth() : createUnhealthyHealth(`status ${response.status}`);
    } catch (error) {
      return createUnhealthyHealth((error as Error).message);
    }
  }
}

const transient = (error: unknown) =>
  error instanceof ServiceUnavailableError || (error as Error).name === "RPCTimeoutError";

/** Every attempt has its own deadline; only failures that may succeed later are retried. */
export function chargeWithRetry(provider: PaymentProvider, request: ChargeRequest, timeoutMs: number,
  onRetry: (error: unknown, attempt: number) => void = () => {}): Promise<ChargeResult> {
  return retry(
    () => runWithTimeout((signal) => provider.charge(request, signal), timeoutMs, `${provider.name}.charge`),
    { attempts: 3, delay: 50, backoff: "exponential", maxDelay: 500, retryIf: transient, onRetry },
  );
}

import { startKoboPay } from "./kobopay-server.js";
import { chargeWithRetry, KoboPayAdapter } from "./payment-provider.js";

const secret = `sk_test_${crypto.randomUUID()}`;
const kobopay = await startKoboPay(secret);
const provider = new KoboPayAdapter(kobopay.url, secret);
const retries: string[] = [];
const charge = (reference: string, cardToken = "tok_visa") =>
  chargeWithRetry(provider, { reference, amountKobo: 45_000_000, cardToken }, 1000,
    (error, attempt) => retries.push(`${reference} attempt ${attempt}: ${(error as Error).name}`))
    .then((result) => JSON.stringify(result), (error: Error) => `${error.name}: ${error.message}`);

console.log("health:", (await provider.health()).status);
console.log("normal:        ", await charge("fd_greenfield_1"));
console.log("same reference:", await charge("fd_greenfield_1"));
kobopay.controls.failNext = 2;
console.log("two 503s:      ", await charge("fd_greenfield_2"));
console.log("declined:      ", await charge("fd_unity_3", "tok_declined"));
kobopay.controls.latencyMs = 1500;
console.log("too slow:      ", await charge("fd_unity_4"));
console.log(retries.join("\n"));
await new Promise((resolve) => setTimeout(resolve, 1700));
console.log("charges KoboPay made:", kobopay.controls.chargeCalls);
await kobopay.stop();

health: healthy
normal:         {"status":"succeeded","chargeId":"ch_1"}
same reference: {"status":"succeeded","chargeId":"ch_1"}
two 503s:       {"status":"succeeded","chargeId":"ch_2"}
declined:       {"status":"declined","reason":"insufficient_funds"}
too slow:       RPCTimeoutError: RPC operation timed out after 1000ms.
fd_greenfield_2 attempt 1: ServiceUnavailableError
fd_greenfield_2 attempt 2: ServiceUnavailableError
fd_unity_4 attempt 1: RPCTimeoutError
fd_unity_4 attempt 2: RPCTimeoutError
charges KoboPay made: 4

import type { CacheService } from "@zudojs/cache";
import { ConflictError, NotFoundError, ValidationError } from "@zudojs/errors";
import type { EventBus } from "@zudojs/events";
import type { FeatureFlags } from "@zudojs/feature-flags";
import { withSpan, type Observability } from "@zudojs/observability";
import { schema } from "@zudojs/schema";

import { requireAccess } from "./access.js";
import type { Database } from "./db.js";
import type { Caller, Identity } from "./identity.js";
import { chargeWithRetry, type PaymentProvider } from "./payment-provider.js";

export interface Bill {
  readonly id: number;
  readonly schoolId: string;
  readonly studentName: string;
  readonly guardianId: string;
  readonly term: string;
  readonly dueDate: string;
  readonly amountKobo: number;
  readonly paidKobo: number;
}
export interface Payment {
  readonly id: number;
  readonly billId: number;
  readonly amountKobo: number;
  readonly status: "pending" | "succeeded" | "declined";
  readonly receiptKey: string | null;
}
export interface FeePaid {
  readonly schoolId: string;
  readonly paymentId: number;
  readonly amountKobo: number;
}

export const PayBillBody = schema.object({
  amountKobo: schema.number().int().min(100).max(100_000_000),
  cardToken: schema.string().min(4).max(64),
});

const BILLS = `SELECT b.id, b.school_id AS "schoolId", st.name AS "studentName", st.guardian_id AS "guardianId", b.term,
  b.due_date::text AS "dueDate", b.amount_kobo AS "amountKobo", b.paid_kobo AS "paidKobo"
  FROM bills b JOIN students st ON st.id = b.student_id`;
const PAYMENTS = `SELECT id, bill_id AS "billId", amount_kobo AS "amountKobo", status, receipt_key AS "receiptKey" FROM payments`;

export interface BillingDeps {
  readonly db: Database;
  readonly identity: Identity;
  readonly flags: FeatureFlags;
  readonly provider: PaymentProvider;
  readonly events: EventBus;
  readonly cache: CacheService;
  readonly obs: Observability;
  readonly providerTimeoutMs: number;
}

export function createBilling({ db, identity, flags, provider, events, cache, obs, providerTimeoutMs }: BillingDeps) {
  const schoolId = () => identity.currentSchool().id;

  async function findBill(id: number, lock = ""): Promise<Bill> {
    const { rows } = await db.sql().query<Bill>(`${BILLS} WHERE b.id = $1 AND b.school_id = $2 ${lock}`, [id, schoolId()]);
    if (!rows[0]) throw new NotFoundError(`Bill ${id} was not found`);
    return rows[0];
  }

  async function paymentByKey(key: string): Promise<Payment | undefined> {
    const { rows } = await db.sql().query<Payment>(`${PAYMENTS} WHERE school_id = $1 AND idempotency_key = $2`, [schoolId(), key]);
    return rows[0];
  }

  /** Step 1, in one transaction: lock the bill, check what is left to pay, record a pending payment. */
  async function reserve(caller: Caller, billId: number, amountKobo: number, key: string): Promise<Payment> {
    return db.transactions.run(async () => {
      const bill = await findBill(billId, "FOR UPDATE OF b");
      await requireAccess(caller, "pay", bill);
      const { rows: [pending] } = await db.sql().query<{ kobo: number }>(
        "SELECT coalesce(sum(amount_kobo), 0)::int AS kobo FROM payments WHERE bill_id = $1 AND status = 'pending'", [billId]);
      const outstanding = bill.amountKobo - bill.paidKobo - (pending?.kobo ?? 0);
      if (amountKobo > outstanding) throw new ValidationError(`Only ${outstanding} kobo is left to pay on bill ${billId}`);
      const partAllowed = await flags.isEnabled("installments", { tenantId: bill.schoolId, userId: caller.userId });
      if (amountKobo < outstanding && !partAllowed) throw new ValidationError("This school does not accept part payments");
      const { rows } = await db.sql().query<Payment>(
        `INSERT INTO payments (school_id, bill_id, amount_kobo, status, idempotency_key) VALUES ($1, $2, $3, 'pending', $4)
         RETURNING id, bill_id AS "billId", amount_kobo AS "amountKobo", status, receipt_key AS "receiptKey"`,
        [bill.schoolId, billId, amountKobo, key]);
      return rows[0]!;
    });
  }

  /** Step 3, in one transaction: the outcome, the bill, the ledger; the event only after commit. */
  async function settle(payment: Payment, chargeId: string | undefined): Promise<Payment> {
    return db.transactions.run(async (tx) => {
      const status = chargeId ? "succeeded" : "declined";
      await db.sql().query("UPDATE payments SET status = $1, charge_id = $2 WHERE id = $3", [status, chargeId ?? null, payment.id]);
      if (chargeId) {
        await db.sql().query("UPDATE bills SET paid_kobo = paid_kobo + $1 WHERE id = $2", [payment.amountKobo, payment.billId]);
        await db.sql().query(
          "INSERT INTO ledger (school_id, payment_id, account, amount_kobo) VALUES ($1, $2, 'kobopay-clearing', $3), ($1, $2, 'fees-receivable', $4)",
          [schoolId(), payment.id, payment.amountKobo, -payment.amountKobo]);
        const paid: FeePaid = { schoolId: schoolId(), paymentId: payment.id, amountKobo: payment.amountKobo };
        db.afterCommit(tx, async () => void (await events.publishEvent({ type: "fee.paid", payload: paid })));
      }
      return { ...payment, status };
    });
  }

  return {
    async listBills(caller: Caller): Promise<readonly Bill[]> {
      const school = schoolId();
      const load = async () => {
        const mine = caller.role === "parent" ? "AND st.guardian_id = $2" : "";
        const params = caller.role === "parent" ? [school, caller.userId] : [school];
        return (await db.sql().query<Bill>(`${BILLS} WHERE b.school_id = $1 ${mine} ORDER BY b.id`, params)).rows;
      };
      return (await cache.getOrSet(`bills.${school}.${caller.userId}`, load, { tags: [`bills.${school}`] })).value;
    },

    async payBill(caller: Caller, billId: number, key: string, body: unknown): Promise<Payment> {
      const { amountKobo, cardToken } = PayBillBody.parse(body);
      const replay = await paymentByKey(key);
      if (replay) {
        await requireAccess(caller, "read", await findBill(replay.billId));
        if (replay.billId !== billId || replay.amountKobo !== amountKobo) throw new ConflictError("Idempotency-Key reused for a different payment");
        return replay;
      }
      const payment = await reserve(caller, billId, amountKobo, key);
      const reference = `fd_${schoolId()}_${payment.id}`;
      try {
        const result = await withSpan(obs.tracer, "kobopay.charge", () =>
          chargeWithRetry(provider, { reference, amountKobo, cardToken }, providerTimeoutMs,
            (error, attempt) => {
              obs.metrics.counter("kobopay.retries").increment();
              obs.logger.warn("charge retry", { reference, attempt, error: (error as Error).name });
            }));
        return await settle(payment, result.status === "succeeded" ? result.chargeId : undefined);
      } catch (error) {
        obs.logger.error("charge outcome unknown, left pending", { reference, error: (error as Error).message });
        return payment;
      }
    },

    async payment(caller: Caller, paymentId: number): Promise<Payment> {
      const { rows } = await db.sql().query<Payment>(`${PAYMENTS} WHERE id = $1 AND school_id = $2`, [paymentId, schoolId()]);
      if (!rows[0]) throw new NotFoundError(`Payment ${paymentId} was not found`);
      await requireAccess(caller, "read", await findBill(rows[0].billId)).catch((error: unknown) => {
        throw error instanceof NotFoundError ? new NotFoundError(`Payment ${paymentId} was not found`) : error;
      });
      return rows[0];
    },
  };
}

export type Billing = ReturnType<typeof createBilling>;

import { createRPCMemoryTransport, createRPCProcedure, RPCClient, RPCServer } from "@zudojs/rpc";
import type { Queue } from "@zudojs/queue";
import { schema } from "@zudojs/schema";
import type { ObjectStorage } from "@zudojs/storage";

import type { Database } from "./db.js";
import type { Identity } from "./identity.js";

export interface Notice {
  readonly to: string;
  readonly subject: string;
  readonly text: string;
}
export interface ReceiptJob {
  readonly schoolId: string;
  readonly paymentId: number;
}

const NoticeSchema = schema.object({
  to: schema.string().email(),
  subject: schema.string().min(1).max(120),
  text: schema.string().min(1).max(5000),
});

const naira = new Intl.NumberFormat("en-NG", { style: "currency", currency: "NGN" });

/** The notifications service, reached over RPC. In-process today; over HTTP once it is its own service. */
export function createNotifications() {
  const sent: Notice[] = [];
  const server = new RPCServer();
  server.register(createRPCProcedure("notifications.send", async (notice: Notice) => {
    sent.push(notice);
    return { queued: true };
  }, { input: NoticeSchema }));
  const client = new RPCClient(createRPCMemoryTransport(server), { timeout: 2_000 });
  return { sent, send: (notice: Notice) => client.call<Notice, { queued: boolean }>("notifications.send", notice) };
}
export type Notifications = ReturnType<typeof createNotifications>;

/** Renders a receipt, stores it, e-mails the guardian. Safe to run twice: the key is fixed per payment. */
export function registerReceiptWorker(deps: {
  queue: Queue<ReceiptJob>; db: Database; identity: Identity; storage: ObjectStorage; notifications: Notifications;
}): void {
  const { queue, db, identity, storage, notifications } = deps;
  queue.process("render-receipt", async (job) => {
    await identity.runAs(job.data.schoolId, async () => {
      const { rows } = await db.sql().query<{ school: string; student: string; term: string; kobo: number; email: string }>(
        `SELECT sc.name AS school, st.name AS student, b.term, p.amount_kobo AS kobo, u.email FROM payments p
         JOIN bills b ON b.id = p.bill_id JOIN students st ON st.id = b.student_id
         JOIN schools sc ON sc.id = p.school_id JOIN users u ON u.id = st.guardian_id
         WHERE p.id = $1 AND p.school_id = $2 AND p.status = 'succeeded'`, [job.data.paymentId, job.data.schoolId]);
      const row = rows[0];
      if (!row) throw new Error(`payment ${job.data.paymentId} is not a settled payment of ${job.data.schoolId}`);
      const text = `${row.school}\nReceipt FD-${job.data.paymentId}\n${row.student}, ${row.term}\nPaid: ${naira.format(row.kobo / 100)}\n`;
      const key = `schools/${job.data.schoolId}/receipts/FD-${job.data.paymentId}.txt`;
      await storage.put(key, new TextEncoder().encode(text), { contentType: "text/plain" });
      await db.sql().query("UPDATE payments SET receipt_key = $1 WHERE id = $2", [key, job.data.paymentId]);
      await notifications.send({ to: row.email, subject: `Receipt FD-${job.data.paymentId}`, text });
    });
  });
}

/** The daily reminder: every unpaid bill past its due date, one notice per guardian and bill. */
export async function sendOverdueReminders(db: Database, notifications: Notifications, today: string): Promise<number> {
  const { rows } = await db.sql().query<{ email: string; student: string; term: string; owed: number; school: string }>(
    `SELECT u.email, st.name AS student, b.term, b.amount_kobo - b.paid_kobo AS owed, sc.name AS school
     FROM bills b JOIN students st ON st.id = b.student_id JOIN users u ON u.id = st.guardian_id
     JOIN schools sc ON sc.id = b.school_id
     WHERE b.paid_kobo < b.amount_kobo AND b.due_date < $1::date AND sc.status = 'active' ORDER BY b.id`, [today]);
  for (const row of rows) {
    await notifications.send({
      to: row.email, subject: `${row.school}: school fees overdue`,
      text: `${row.student}, ${row.term}: ${naira.format(row.owed / 100)} is overdue.`,
    });
  }
  return rows.length;
}

import type { CommandBus, CommandOf, QueryBus, QueryOf } from "@zudojs/cqrs";
import { RateLimitError, ValidationError } from "@zudojs/errors";
import {
  createResponseContext, createRouter, HttpMiddlewarePipeline, mountOpenAPI,
  type HttpMiddleware, type HttpRouterContext,
} from "@zudojs/http";
import { SpanKind, withSpan, type Observability } from "@zudojs/observability";
import { schema } from "@zudojs/schema";
import { createRateLimiter, generateSecurityHeaders } from "@zudojs/security";
import type { ObjectStorage } from "@zudojs/storage";

import type { Bill, Payment } from "./billing.js";
import { PayBillBody } from "./billing.js";
import type { Caller, Identity } from "./identity.js";

export type PayBill = CommandOf<"PayBill", { caller: Caller; billId: number; idempotencyKey: string; body: unknown }>;
export type ListBills = QueryOf<"ListBills", { caller: Caller }>;
export type GetPayment = QueryOf<"GetPayment", { caller: Caller; paymentId: number }>;

const Id = schema.object({ id: schema.coerce.number().int().min(1) });
const IdempotencyKey = schema.string().regex(/^[A-Za-z0-9_-]{8,100}$/);
const STATUS = { succeeded: 201, pending: 202, declined: 402 } as const;

function body(ctx: HttpRouterContext): unknown {
  const text = new TextDecoder().decode(ctx.request.body as Uint8Array | undefined);
  try {
    return text ? JSON.parse(text) : {};
  } catch {
    throw new ValidationError("The body must be JSON");
  }
}

export interface HttpDeps {
  readonly identity: Identity;
  readonly commands: CommandBus;
  readonly queries: QueryBus;
  readonly storage: ObjectStorage;
  readonly obs: Observability;
  readonly readiness: () => Promise<{ ready: boolean; checks: Record<string, string> }>;
}

export function createHttpPipeline({ identity, commands, queries, storage, obs, readiness }: HttpDeps) {
  const router = createRouter();
  const logins = createRateLimiter({ windowMs: 60_000, max: 5 });

  /** Authenticates the bearer token, then runs the handler as the caller's school. */
  const asCaller = <T>(ctx: HttpRouterContext, handler: (caller: Caller) => Promise<T>): Promise<T> =>
    identity.authenticate(ctx.request.getHeader("authorization")?.replace(/^Bearer /, "")).then(({ caller, school }) =>
      identity.tenantContext.run(school, () => handler(caller)));

  router.post("/v1/sessions", async (ctx) => {
    if (!logins.check({ ip: ctx.request.remoteAddress ?? "unknown" }).allowed) throw new RateLimitError("Too many login attempts");
    return createResponseContext({ status: 201 }).json({ token: await identity.login(body(ctx)) });
  }, { openapi: { summary: "Log in to one school", tags: ["sessions"] } });

  router.get("/v1/bills", (ctx) => asCaller(ctx, async (caller) =>
    createResponseContext().json(await queries.execute<ListBills, readonly Bill[]>({ type: "ListBills", caller }))),
  { openapi: { summary: "Bills the caller may see", tags: ["bills"] } });

  router.post("/v1/bills/:id/payments", (ctx) => asCaller(ctx, async (caller) => {
    const { id } = Id.parse(ctx.params);
    const idempotencyKey = IdempotencyKey.parse(ctx.request.getHeader("idempotency-key") ?? "");
    const payment = await commands.execute<PayBill, Payment>({ type: "PayBill", caller, billId: id, idempotencyKey, body: body(ctx) });
    return createResponseContext({ status: STATUS[payment.status] }).json(payment);
  }), { openapi: { summary: "Pay a bill by card", tags: ["bills"], params: Id, body: PayBillBody } });

  router.get("/v1/payments/:id/receipt", (ctx) => asCaller(ctx, async (caller) => {
    const payment = await queries.execute<GetPayment, Payment>({ type: "GetPayment", caller, paymentId: Id.parse(ctx.params).id });
    const file = payment.receiptKey ? await storage.get(payment.receiptKey) : null;
    if (!file) return createResponseContext({ status: 404 }).json({ error: "The receipt is not ready yet" });
    return createResponseContext().setHeader("content-type", "text/plain; charset=utf-8")
      .text(new TextDecoder().decode(await file.arrayBuffer()));
  }), { openapi: { summary: "Download a payment's receipt", tags: ["payments"], params: Id } });

  router.get("/health", async () => createResponseContext().json({ status: "alive" }), { openapi: false });
  router.get("/ready", async () => {
    const report = await readiness();
    return createResponseContext({ status: report.ready ? 200 : 503 }).json(report);
  }, { openapi: false });
  mountOpenAPI(router, { info: { title: "FeesDesk API", version: "1.0.0" } });

  const headers = Object.entries(generateSecurityHeaders());
  /** Security headers, a trace span and a request counter for every request; unexpected errors are logged. */
  const edge: HttpMiddleware = async (ctx, next) =>
    withSpan(obs.tracer, `${ctx.request.method} ${ctx.request.path}`, async () => {
      let status = 500;
      try {
        const response = (await next()).clone();
        status = response.status;
        const present = new Set(Object.keys(response.headers).map((name) => name.toLowerCase()));
        for (const [name, value] of headers) if (!present.has(name.toLowerCase())) response.setHeader(name, value);
        return response;
      } catch (error) {
        const exposed = error as { expose?: boolean; statusCode?: number };
        status = exposed.expose && exposed.statusCode ? exposed.statusCode : 500;
        if (status >= 500) obs.logger.error("request failed", { path: ctx.request.path }, error as Error);
        throw error;
      } finally {
        obs.metrics.counter("http.requests", { method: ctx.request.method, status: String(status) }).increment();
      }
    }, { kind: SpanKind.SERVER });
  const dispatch: HttpMiddleware = async (ctx) => (await router.dispatch(ctx.request, { signal: ctx.signal })).response;

  return { pipeline: new HttpMiddlewarePipeline({ middlewares: [edge, dispatch] }), close: () => logins.destroy() };
}

import { createCacheService, createMemoryCacheAdapter } from "@zudojs/cache";
import { ContainerScope, createContainer, createToken } from "@zudojs/container";
import { createCommandBus, createQueryBus } from "@zudojs/cqrs";
import { createEventBus, type Event } from "@zudojs/events";
import { createFeatureFlags, createMemoryProvider } from "@zudojs/feature-flags";
import { createHttpServer, createNodeHttpAdapter, createResponseContext, type HttpRequestContext } from "@zudojs/http";
import { createLifecycleManager } from "@zudojs/lifecycle";
import { createObservability, type Observability } from "@zudojs/observability";
import { createExponentialBackoff, createInMemoryQueue, createQueueName, createWorker } from "@zudojs/queue";
import { Scheduler } from "@zudojs/scheduler";
import { LocalObjectStorage } from "@zudojs/storage";

import { createBilling, type FeePaid } from "./billing.js";
import type { AppConfig } from "./config.js";
import { createDatabase } from "./db.js";
import { createHttpPipeline, type GetPayment, type ListBills, type PayBill } from "./http.js";
import { createIdentity } from "./identity.js";
import { createNotifications, registerReceiptWorker, sendOverdueReminders, type ReceiptJob } from "./notices.js";
import { KoboPayAdapter } from "./payment-provider.js";

const singleton = { scope: ContainerScope.SINGLETON };
const T = {
  config: createToken<AppConfig>("Config"),
  obs: createToken<Observability>("Observability"),
  db: createToken<Awaited<ReturnType<typeof createDatabase>>>("Database"),
  identity: createToken<ReturnType<typeof createIdentity>>("Identity"),
  provider: createToken<KoboPayAdapter>("PaymentProvider"),
  billing: createToken<ReturnType<typeof createBilling>>("Billing"),
};

/** The composition root: every object is built here, once, and started and stopped in dependency order. */
export async function createFeesDesk(config: AppConfig, options: { obs?: Observability; today?: () => string } = {}) {
  const today = options.today ?? (() => new Date().toLocaleDateString("en-CA", { timeZone: "Africa/Lagos" }));
  const container = createContainer();
  container.registerValue(T.config, config);
  container.registerValue(T.obs, options.obs ?? createObservability({ serviceName: "feesdesk", environment: config.node_env }));
  container.registerValue(T.db, await createDatabase());
  container.registerFactory(T.identity, (db) => createIdentity(db), [T.db], singleton);
  container.registerFactory(T.provider, (c) => new KoboPayAdapter(c.provider_url, c.provider_secret), [T.config], singleton);

  const events = createEventBus();
  const cache = createCacheService({ adapter: createMemoryCacheAdapter({ maxEntries: 10_000 }), config: { defaultTtl: 60_000 } });
  const flags = createFeatureFlags({ provider: createMemoryProvider([
    { key: "installments", enabled: true, defaultValue: false, rules: [{ type: "tenant", tenants: ["greenfield"], value: true }] },
  ]) });
  container.registerFactory(T.billing, (db, identity, provider, obs, c) =>
    createBilling({ db, identity, provider, obs, flags, events, cache, providerTimeoutMs: c.provider_timeout_ms }),
  [T.db, T.identity, T.provider, T.obs, T.config], singleton);

  const [db, identity, billing, obs] = [container.resolve(T.db), container.resolve(T.identity), container.resolve(T.billing), container.resolve(T.obs)];
  const storage = new LocalObjectStorage(config.receipts_dir, { maxObjectBytes: 64 * 1024 });
  const notifications = createNotifications();
  const receipts = createInMemoryQueue<ReceiptJob>(createQueueName("receipts"), {
    autoProcess: false,
    defaultJobOptions: { attempts: 5, backoff: createExponentialBackoff(100, { maxDelay: 5_000 }) },
  });
  registerReceiptWorker({ queue: receipts, db, identity, storage, notifications });
  const worker = createWorker("receipts-1", receipts, { concurrency: 2, pollInterval: 20 });

  events.on<Event<FeePaid>>("fee.paid", async ({ payload }) => {
    obs.metrics.counter("fees.paid_kobo", { school: payload.schoolId }).increment(payload.amountKobo);
    await cache.invalidateByTag([`bills.${payload.schoolId}`]);
    await receipts.add("render-receipt", { schoolId: payload.schoolId, paymentId: payload.paymentId });
  });

  const commands = createCommandBus().register<PayBill, unknown>("PayBill", (c) => billing.payBill(c.caller, c.billId, c.idempotencyKey, c.body));
  const queries = createQueryBus()
    .register<ListBills, unknown>("ListBills", (q) => billing.listBills(q.caller))
    .register<GetPayment, unknown>("GetPayment", (q) => billing.payment(q.caller, q.paymentId));

  const scheduler = new Scheduler();
  scheduler.define({ id: "overdue-reminders", name: "Remind guardians of overdue fees", handler: async () => void (await sendOverdueReminders(db, notifications, today())) });
  // 08:00 in Lagos is 07:00 UTC (no daylight saving); cron accepts only UTC or the server's own zone.
  const reminders = scheduler.cron("0 7 * * 1-5", "overdue-reminders", { timezone: "UTC" });

  const lifecycle = createLifecycleManager({ handleSignals: false, shutdownTimeout: 10_000 });
  const readiness = async () => {
    const provider = await container.resolve(T.provider).health();
    const database = await db.pg.query("SELECT 1").then(() => "up", () => "down");
    const checks = { lifecycle: lifecycle.state, database, kobopay: provider.status };
    return { ready: lifecycle.state === "ready" && database === "up" && provider.status === "healthy", checks };
  };
  const web = createHttpPipeline({ identity, commands, queries, storage, obs, readiness });
  const server = createHttpServer({
    adapter: createNodeHttpAdapter({ host: "127.0.0.1", port: config.port }),
    handler: (request: HttpRequestContext) => web.pipeline.execute(request, createResponseContext()),
  });

  lifecycle.register({ name: "database", dispose: () => db.close() });
  lifecycle.register({ name: "receipts", start: () => worker.start(), stop: () => worker.stop() }, { dependsOn: ["database"] });
  lifecycle.register({ name: "scheduler", start: async () => scheduler.start(), stop: () => scheduler.stop({ drain: true }) }, { dependsOn: ["database"] });
  lifecycle.register({ name: "http", start: async () => void (await server.start()), stop: async () => { await server.stop(); web.close(); } },
    { dependsOn: ["receipts", "scheduler"] });

  return {
    db, obs, notifications, receipts, reminders, lifecycle,
    start: () => lifecycle.start(),
    stop: () => lifecycle.shutdown(),
    url: () => `http://127.0.0.1:${server.address?.port}`,
    runReminders: () => sendOverdueReminders(db, notifications, today()),
  };
}

export type FeesDesk = Awaited<ReturnType<typeof createFeesDesk>>;

import type { Database } from "./db.js";
import { addUser } from "./identity.js";

/** Two schools, a bursar, three parents and their children's first-term bills. Passwords are new every run. */
export async function seed(db: Database) {
  const password = () => crypto.randomUUID();
  const people = {
    bola: { id: "u-bola", email: "bola@greenfield.test", name: "Bola (bursar)", password: password() },
    ada: { id: "u-ada", email: "ada@example.com", name: "Ada Okafor", password: password() },
    kemi: { id: "u-kemi", email: "kemi@example.com", name: "Kemi Bello", password: password() },
    tunde: { id: "u-tunde", email: "tunde@example.com", name: "Tunde Ade", password: password() },
  };
  await db.pg.exec(`INSERT INTO schools (id, name) VALUES ('greenfield', 'Greenfield Academy, Lekki'), ('unity', 'Unity College, Ibadan')`);
  await Promise.all(Object.values(people).map((person) => addUser(db, person)));
  await db.pg.exec(`
    INSERT INTO memberships VALUES ('greenfield', 'u-bola', 'bursar'), ('greenfield', 'u-ada', 'parent'),
      ('greenfield', 'u-kemi', 'parent'), ('unity', 'u-tunde', 'parent');
    INSERT INTO students (school_id, name, guardian_id) VALUES
      ('greenfield', 'Chidi Okafor', 'u-ada'), ('greenfield', 'Zainab Bello', 'u-kemi'), ('unity', 'Ife Ade', 'u-tunde');
    INSERT INTO bills (school_id, student_id, term, due_date, amount_kobo) VALUES
      ('greenfield', 1, 'First term 2026/27', '2026-09-15', 45000000),
      ('greenfield', 2, 'First term 2026/27', '2026-09-15', 45000000),
      ('unity', 3, 'First term 2026/27', '2026-10-10', 28000000);
  `);
  return people;
}

import { mkdtemp, rm } from "node:fs/promises";
import { tmpdir } from "node:os";
import { join } from "node:path";
import { createObservability } from "@zudojs/observability";

import { createFeesDesk } from "./app.js";
import { loadConfig } from "./config.js";
import { startKoboPay } from "./kobopay-server.js";
import { seed } from "./seed.js";

/** A whole FeesDesk on random ports: fake KoboPay, fresh PGlite, temp receipts folder. For demos and tests. */
export async function startFeesDesk(today = "2026-09-25") {
  const secret = `sk_test_${crypto.randomUUID()}`;
  const kobopay = await startKoboPay(secret);
  const receiptsDir = await mkdtemp(join(tmpdir(), "feesdesk-"));
  const config = await loadConfig({
    FEESDESK_PORT: "0", FEESDESK_PROVIDER_URL: kobopay.url, FEESDESK_PROVIDER_SECRET: secret,
    FEESDESK_PROVIDER_TIMEOUT_MS: "1000", FEESDESK_RECEIPTS_DIR: receiptsDir,
  });
  const obs = createObservability({ serviceName: "feesdesk", useConsoleExporters: false });
  const app = await createFeesDesk(config, { obs, today: () => today });
  const people = await seed(app.db);
  await app.start();

  async function call(method: string, path: string, options: { token?: string; key?: string; body?: unknown } = {}) {
    const response = await fetch(app.url() + path, {
      method,
      headers: {
        "content-type": "application/json",
        ...(options.token ? { authorization: `Bearer ${options.token}` } : {}),
        ...(options.key ? { "idempotency-key": options.key } : {}),
      },
      body: options.body === undefined ? undefined : JSON.stringify(options.body),
    });
    const text = await response.text();
    const json = /^[[{]/.test(text) ? JSON.parse(text) : undefined;
    return { status: response.status, text, json };
  }
  const login = async (school: string, who: { email: string; password: string }): Promise<string> =>
    (await call("POST", "/v1/sessions", { body: { school, email: who.email, password: who.password } })).json.token;

  return {
    app, kobopay, obs, people, call, login,
    async stop() {
      await app.stop();
      await obs.shutdown();
      await kobopay.stop();
      await rm(receiptsDir, { recursive: true, force: true });
    },
  };
}