@suluk/credits 0.1.0

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@suluk/credits",
+  "version": "0.1.0",
+  "description": "A metered CREDIT LEDGER: append-only transactions, balance, the ATOMIC debit-if-covers (a single conditional INSERT that can never drive the ledger negative under concurrency), the idempotent debit (INSERT OR IGNORE — the money-OUT double-spend guard for partial refunds), per-key spend attribution, the recent-transactions + activity-log query, and aggregate stats. The package OWNS the credit tables; the app injects a Drizzle handle (D1 in prod, bun:sqlite in tests). The money-correctness core, extracted verbatim from a real app (C046). CANDIDATE tooling.",
+  "publishConfig": {
+    "access": "public"
+  },
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/MahmoodKhalil57/suluk.git",
+    "directory": "tooling/ts/packages/credits"
+  },
+  "homepage": "https://github.com/MahmoodKhalil57/suluk#readme",
+  "bugs": "https://github.com/MahmoodKhalil57/suluk/issues",
+  "type": "module",
+  "main": "src/index.ts",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "dependencies": {
+    "@suluk/drizzle": "^0.1.6",
+    "drizzle-orm": "^0.45.2"
+  },
+  "devDependencies": {
+    "@types/bun": "latest"
+  },
+  "scripts": {
+    "test": "bun test",
+    "typecheck": "tsc --noEmit -p ."
+  }
+}

package/src/credits.ts

@@ -0,0 +1,244 @@
+/**
+ * The credit ledger (C046) — the money-correctness core, extracted verbatim. The package owns the schema; the app injects
+ * a Drizzle handle (`DrizzleD1Database` in prod; bun:sqlite bridged to it in tests — the query builders + raw SQL are
+ * compatible). The two atomic primitives are the point: `debitIfCovers` (a single conditional INSERT that can never drive
+ * the ledger negative under concurrency) and `debitOnceIfCovers` (INSERT OR IGNORE — the money-OUT double-spend guard for
+ * partial refunds). The app-specific payment-alert kinds + the user-table count are NOT here (they stay in the app).
+ */
+import { and, desc, eq, lt, sql } from "drizzle-orm";
+import type { DrizzleD1Database } from "drizzle-orm/d1";
+import { rowsChanged } from "@suluk/drizzle";
+import { creditTransaction, creditAmount, creditKey } from "./schema";
+
+/** The injected DB handle. Prod is drizzle/d1; tests bridge drizzle/bun-sqlite to this type (a runtime-identity narrow). */
+export type CreditsDB = DrizzleD1Database;
+
+export class InsufficientCreditsError extends Error {
+  constructor(
+    public readonly balance: number,
+    public readonly needed: number,
+  ) {
+    super(`Insufficient credits: have ${balance}, need ${needed}.`);
+    this.name = "InsufficientCreditsError";
+  }
+}
+
+/** Current balance = sum of all ledger deltas for the user. */
+export async function getBalance(db: CreditsDB, userId: string): Promise<number> {
+  const rows = await db
+    .select({ bal: sql<number>`coalesce(sum(${creditTransaction.delta}), 0)` })
+    .from(creditTransaction)
+    .where(eq(creditTransaction.userId, userId));
+  return Number(rows[0]?.bal ?? 0);
+}
+
+/** Append one ledger row (the single writer); returns the new row id. `delta` is + on grant/top-up, − on debit. */
+export async function record(db: CreditsDB, userId: string, delta: number, reason: string): Promise<string> {
+  const id = crypto.randomUUID();
+  await db.insert(creditTransaction).values({ id, userId, delta, reason, createdAt: new Date() });
+  return id;
+}
+
+/** Attribute a debit row to the API KEY that spent it (per-key usage + limit join). Best-effort + idempotent (PK on
+ *  txnId) — attribution is reporting, NOT the money path, so a failure here must never break the debit it rode in on. */
+export async function recordKey(db: CreditsDB, txnId: string, keyId: string | null | undefined): Promise<void> {
+  if (!keyId) return;
+  try {
+    await db.insert(creditKey).values({ txnId, keyId }).onConflictDoNothing().run();
+  } catch (e) {
+    console.warn(`[credit-key] couldn't attribute ${txnId} to ${keyId}:`, e instanceof Error ? e.message : String(e));
+  }
+}
+
+/**
+ * ATOMIC metered debit — append `-amount` ONLY IF the balance still covers it, in ONE conditional INSERT (atomic on both
+ * bun:sqlite and D1), then best-effort attribute it. Returns true when debited, false when the balance raced below the
+ * cost. Closes the read-then-write window where K concurrent charges each read the same balance, all pass `cost <=
+ * balance`, and all append — driving the ledger NEGATIVE. The self-guard rejects a non-positive/non-integer `amount`
+ * (a negative would compute delta=+amount and trivially pass the WHERE, MINTING credits).
+ */
+export async function debitIfCovers(db: CreditsDB, userId: string, amount: number, reason: string, keyId?: string | null): Promise<boolean> {
+  if (!Number.isInteger(amount) || amount <= 0) return false;
+  const id = crypto.randomUUID();
+  const createdAt = Math.floor(Date.now() / 1000); // integer({mode:"timestamp"}) stores epoch SECONDS
+  const res = await db.run(
+    sql`INSERT INTO credit_transaction (id, userId, delta, reason, createdAt)
+        SELECT ${id}, ${userId}, ${-amount}, ${reason}, ${createdAt}
+        WHERE (SELECT coalesce(sum(delta), 0) FROM credit_transaction WHERE userId = ${userId}) >= ${amount}`,
+  );
+  if (rowsChanged(res) === 0) return false; // the balance raced below the cost → no debit, no negative ledger
+  await recordKey(db, id, keyId);
+  return true;
+}
+
+/** Total credits a key has spent — SUM(abs(delta)) over its attributed DEBITS (delta < 0). Drives the per-key cap + the
+ *  keys-page usage column. */
+export async function keySpend(db: CreditsDB, keyId: string): Promise<number> {
+  const rows = await db
+    .select({ spent: sql<number>`coalesce(sum(-${creditTransaction.delta}), 0)` })
+    .from(creditKey)
+    .innerJoin(creditTransaction, eq(creditTransaction.id, creditKey.txnId))
+    .where(and(eq(creditKey.keyId, keyId), lt(creditTransaction.delta, 0)));
+  return Number(rows[0]?.spent ?? 0);
+}
+
+/** The outcome of an idempotent debit attempt (see {@link debitOnceIfCovers}). */
+export type DebitOutcome = { outcome: "debited" | "replayed" | "insufficient"; nonce: string };
+
+/** The DETERMINISTIC ledger row id an idempotent operation maps to — exported so a caller can pre-check existence at the
+ *  SAME id {@link debitOnceIfCovers} will use, without re-deriving the format and risking drift. */
+export function nonceFor(reason: string, idemKey: string): string {
+  return `${reason}:${idemKey}`;
+}
+
+/**
+ * Idempotent atomic debit: debit `amount` ONLY if the balance covers it AND this exact logical operation (identified by
+ * `idemKey`) hasn't already been debited. The row id is DERIVED from the key (`${reason}:${idemKey}`), so a retry/duplicate
+ * collides on the primary key and is IGNORED — it can never mint a second debit. The money-OUT double-spend guard a
+ * per-call random nonce lacks for PARTIAL refunds. One statement (INSERT OR IGNORE … WHERE SUM(delta) >= amount), atomic
+ * on both engines. Returns `debited` (fresh — `nonce` anchors the downstream Stripe idempotency key), `replayed` (already
+ * debited — caller MUST NOT move money again), or `insufficient` (balance no longer covers it).
+ */
+export async function debitOnceIfCovers(db: CreditsDB, userId: string, amount: number, reason: string, idemKey: string): Promise<DebitOutcome> {
+  const nonce = nonceFor(reason, idemKey);
+  if (!Number.isInteger(amount) || amount <= 0) return { outcome: "insufficient", nonce };
+  const createdAt = Math.floor(Date.now() / 1000);
+  const res = await db.run(
+    sql`INSERT OR IGNORE INTO credit_transaction (id, userId, delta, reason, createdAt)
+        SELECT ${nonce}, ${userId}, ${-amount}, ${reason}, ${createdAt}
+        WHERE (SELECT coalesce(sum(delta), 0) FROM credit_transaction WHERE userId = ${userId}) >= ${amount}`,
+  );
+  if (rowsChanged(res) > 0) return { outcome: "debited", nonce };
+  // No row inserted: EITHER the id existed (duplicate/retry → replay) OR the balance didn't cover it. Disambiguate by existence.
+  const existing = await db.select({ id: creditTransaction.id }).from(creditTransaction).where(eq(creditTransaction.id, nonce)).limit(1);
+  return { outcome: existing.length > 0 ? "replayed" : "insufficient", nonce };
+}
+
+/**
+ * Idempotent debit + per-key ATTRIBUTION — the money primitive a per-item bulk charge needs ({@link debitOnceIfCovers}
+ * itself does NOT attribute). On a FRESH `debited` it records the spend against `keyId` (the row id is the stable nonce);
+ * a `replayed`/`insufficient` attributes nothing.
+ */
+export async function debitOnceAttributed(db: CreditsDB, userId: string, amount: number, reason: string, idemKey: string, keyId?: string | null): Promise<DebitOutcome> {
+  const outcome = await debitOnceIfCovers(db, userId, amount, reason, idemKey);
+  if (outcome.outcome === "debited") await recordKey(db, outcome.nonce, keyId);
+  return outcome;
+}
+
+/** The signed credit `delta` + recorded `amountCents` for ONE ledger row id, or null if absent. Lets an idempotent replay
+ *  report the ORIGINAL operation's amounts — never the retry's (possibly tampered) request. */
+export async function ledgerRow(db: CreditsDB, id: string): Promise<{ delta: number; amountCents: number | null } | null> {
+  const rows = await db
+    .select({ delta: creditTransaction.delta, amountCents: creditAmount.amountCents })
+    .from(creditTransaction)
+    .leftJoin(creditAmount, eq(creditAmount.txnId, creditTransaction.id))
+    .where(eq(creditTransaction.id, id))
+    .limit(1);
+  const r = rows[0];
+  return r ? { delta: r.delta, amountCents: r.amountCents ?? null } : null;
+}
+
+/** One ledger row as a panel shows it (`createdAt` epoch-ms). `amountCents` is the SIGNED cash that moved (+ in, − out),
+ *  or null for credits-only rows (usage debits, free grants). */
+export interface LedgerEntry {
+  id: string;
+  delta: number;
+  reason: string;
+  createdAt: number;
+  amountCents: number | null;
+}
+
+/** Annotate a ledger row with the CASH that moved (signed). Idempotent (PK on txnId), best-effort (purely cosmetic). No-op on 0/null. */
+export async function recordAmount(db: CreditsDB, txnId: string, amountCents: number | null | undefined): Promise<void> {
+  if (!amountCents) return;
+  try {
+    await db.insert(creditAmount).values({ txnId, amountCents }).onConflictDoNothing().run();
+  } catch (e) {
+    console.warn(`[credit-amount] couldn't record ${amountCents}¢ for ${txnId}:`, e instanceof Error ? e.message : String(e));
+  }
+}
+
+/** The user's recent ledger rows (grants + debits) with the cash that moved, newest first — the "recent transactions" +
+ *  the activity log. `limit` is generous (effectively "all" for a normal account). */
+export async function listTransactions(db: CreditsDB, userId: string, limit = 250): Promise<LedgerEntry[]> {
+  const rows = await db
+    .select({ id: creditTransaction.id, delta: creditTransaction.delta, reason: creditTransaction.reason, createdAt: creditTransaction.createdAt, amountCents: creditAmount.amountCents })
+    .from(creditTransaction)
+    .leftJoin(creditAmount, eq(creditAmount.txnId, creditTransaction.id))
+    .where(eq(creditTransaction.userId, userId))
+    .orderBy(desc(creditTransaction.createdAt))
+    .limit(limit);
+  return rows.map((r) => ({ id: r.id, delta: r.delta, reason: r.reason, createdAt: r.createdAt.getTime(), amountCents: r.amountCents ?? null }));
+}
+
+export interface LedgerStats {
+  creditsIssued: number;
+  creditsSpent: number;
+  balanceOutstanding: number;
+}
+
+/** Aggregate ledger stats (granted vs spent, outstanding) — the generic part of an admin dashboard. The user COUNT is the
+ *  app's (it owns the user table); compose it on top. */
+export async function ledgerStats(db: CreditsDB): Promise<LedgerStats> {
+  const ledger = await db
+    .select({
+      issued: sql<number>`coalesce(sum(case when ${creditTransaction.delta} > 0 then ${creditTransaction.delta} else 0 end), 0)`,
+      spent: sql<number>`coalesce(sum(case when ${creditTransaction.delta} < 0 then -${creditTransaction.delta} else 0 end), 0)`,
+      balance: sql<number>`coalesce(sum(${creditTransaction.delta}), 0)`,
+    })
+    .from(creditTransaction);
+  return { creditsIssued: Number(ledger[0]?.issued ?? 0), creditsSpent: Number(ledger[0]?.spent ?? 0), balanceOutstanding: Number(ledger[0]?.balance ?? 0) };
+}
+
+/**
+ * Idempotent money-IN grant — credit `amount` exactly once, keyed on the ledger row id `idemKey` (a STABLE per-payment
+ * anchor: `pi:<id>` / `inv:<id>` / `cs:<id>`), so a webhook redelivery or dashboard "Resend" can NEVER double-credit. The
+ * money-IN twin of {@link debitOnceIfCovers} (which guards money-OUT). `legacyKey`, when given, is an ADDITIONAL anchor
+ * honoured: if a row already exists under it the money is already credited and we skip — so MOVING the idempotency key
+ * across a deploy (e.g. event-id → session-id) can't re-grant an in-flight payment. This is the LEDGER-INTEGRITY
+ * chokepoint for every grant: it rejects a non-finite / non-integer / non-positive delta, so an upstream
+ * `Number(metadata.credits)` can never let "Infinity" (which would poison every later balance read) or "500.9" (which
+ * would break balance == SUM(int delta)) reach the ledger. Returns true ONLY on a FRESH grant; on a fresh grant the cash
+ * `amountCents` (when given) is annotated for the $ detail. Use this for Stripe webhook crediting (top-up / subscription).
+ */
+export async function grantOnce(
+  db: CreditsDB,
+  userId: string,
+  amount: number,
+  idemKey: string,
+  reason = "grant",
+  amountCents?: number | null,
+  legacyKey?: string,
+): Promise<boolean> {
+  if (!Number.isFinite(amount) || !Number.isInteger(amount) || amount <= 0) {
+    console.warn(`[credit] rejected non-finite/non-integer/non-positive amount ${amount} for user ${userId} (${idemKey})`);
+    return false;
+  }
+  if (legacyKey) {
+    const prior = await db.select({ id: creditTransaction.id }).from(creditTransaction).where(eq(creditTransaction.id, legacyKey)).limit(1);
+    if (prior.length > 0) return false; // already credited under the pre-deploy key → never grant twice across the key move
+  }
+  const res = await db.insert(creditTransaction).values({ id: idemKey, userId, delta: amount, reason, createdAt: new Date() }).onConflictDoNothing().run();
+  const credited = rowsChanged(res) > 0;
+  if (credited) await recordAmount(db, idemKey, amountCents); // cosmetic $ annotation, only on a real (idempotent) grant
+  return credited;
+}
+
+/** Grant/top-up credits. Returns the new balance. */
+export async function addCredits(db: CreditsDB, userId: string, amount: number, reason: string): Promise<number> {
+  if (!Number.isInteger(amount) || amount <= 0) throw new Error("amount must be a positive integer");
+  await record(db, userId, amount, reason);
+  return getBalance(db, userId);
+}
+
+/**
+ * Debit credits if the balance covers it; throws InsufficientCreditsError otherwise. Returns the new balance.
+ * NOTE: read-then-write — fine at low concurrency; use {@link debitIfCovers} for the concurrency-safe atomic path.
+ */
+export async function debitCredits(db: CreditsDB, userId: string, amount: number, reason: string): Promise<number> {
+  if (!Number.isInteger(amount) || amount <= 0) throw new Error("amount must be a positive integer");
+  const balance = await getBalance(db, userId);
+  if (balance < amount) throw new InsufficientCreditsError(balance, amount);
+  await record(db, userId, -amount, reason);
+  return balance - amount;
+}

package/src/index.ts

@@ -0,0 +1,18 @@
+/**
+ * @suluk/credits — a metered credit ledger (C046, extracted verbatim). The package OWNS the schema (`credit_transaction`
+ * + the `credit_amount`/`credit_key` sidecars); the app injects a Drizzle handle (D1 in prod, bun:sqlite in tests). The
+ * money-correctness core: the ATOMIC `debitIfCovers` (a conditional INSERT that can't drive the ledger negative under
+ * concurrency) + the idempotent `debitOnceIfCovers` (the partial-refund double-spend guard) + per-key spend + the
+ * activity-log query. App-specific payment-alert kinds + the user-table count stay in the app.
+ */
+export {
+  type CreditsDB,
+  InsufficientCreditsError,
+  getBalance, record, recordKey,
+  debitIfCovers, keySpend,
+  nonceFor, debitOnceIfCovers, debitOnceAttributed, type DebitOutcome,
+  ledgerRow, recordAmount, listTransactions, type LedgerEntry,
+  ledgerStats, type LedgerStats,
+  grantOnce, addCredits, debitCredits,
+} from "./credits";
+export { creditTransaction, creditAmount, creditKey } from "./schema";

package/src/schema.ts

@@ -0,0 +1,32 @@
+/**
+ * The credit-ledger schema (C046) — owned by @suluk/credits, applied by the app's migrations. The ledger is the single
+ * writer of truth: an append-only `credit_transaction` (signed `delta`), a `credit_amount` sidecar for the cash that
+ * moved (cosmetic), and a `credit_key` sidecar attributing a debit to the API key that spent it (for per-key headroom).
+ *
+ * `userId` is a plain column (the app owns the `user` table + any FK / cascade); the two sidecars FK the transaction id.
+ * Extracted verbatim from the source schema.
+ */
+import { sqliteTable, text, integer } from "drizzle-orm/sqlite-core";
+
+export const creditTransaction = sqliteTable("credit_transaction", {
+  id: text("id").primaryKey(),
+  /** the principal / user id (the app owns the user table; add the FK in your migration if you want the cascade). */
+  userId: text("userId").notNull(),
+  /** + on grant/top-up/subscription, − on debit. */
+  delta: integer("delta").notNull(),
+  /** the ledger reason, e.g. "signup_grant" | "topup" | "transcribe" — free text (the app's taxonomy). */
+  reason: text("reason").notNull(),
+  createdAt: integer("createdAt", { mode: "timestamp" }).notNull(),
+});
+
+export const creditAmount = sqliteTable("credit_amount", {
+  txnId: text("txnId").primaryKey().references(() => creditTransaction.id, { onDelete: "cascade" }),
+  /** the SIGNED cash that moved with this row (+ paid in, − refunded out), in cents. */
+  amountCents: integer("amountCents").notNull(),
+});
+
+export const creditKey = sqliteTable("credit_key", {
+  txnId: text("txnId").primaryKey().references(() => creditTransaction.id, { onDelete: "cascade" }),
+  /** the API key / connection id that spent this debit (an apikey.id, or e.g. `mcp:<userId>:<clientId>`). */
+  keyId: text("keyId").notNull(),
+});

package/test/credits.test.ts

@@ -0,0 +1,137 @@
+import { test, expect, describe, beforeEach } from "bun:test";
+import { Database } from "bun:sqlite";
+import { drizzle } from "drizzle-orm/bun-sqlite";
+import {
+  getBalance, addCredits, debitIfCovers, debitCredits, debitOnceIfCovers, debitOnceAttributed,
+  recordKey, keySpend, listTransactions, ledgerStats, nonceFor, grantOnce, InsufficientCreditsError, type CreditsDB,
+} from "../src/index";
+
+/**
+ * C046 — the credit ledger, witnessed against a REAL bun:sqlite (the whole point is the atomic SQL). The package owns the
+ * schema; we apply it here and bridge bun:sqlite → CreditsDB (a runtime-identity narrow, as the source app does in tests).
+ */
+function freshDb(): CreditsDB {
+  const sqlite = new Database(":memory:");
+  sqlite.run(`CREATE TABLE credit_transaction (id TEXT PRIMARY KEY, userId TEXT NOT NULL, delta INTEGER NOT NULL, reason TEXT NOT NULL, createdAt INTEGER NOT NULL)`);
+  sqlite.run(`CREATE TABLE credit_amount (txnId TEXT PRIMARY KEY REFERENCES credit_transaction(id), amountCents INTEGER NOT NULL)`);
+  sqlite.run(`CREATE TABLE credit_key (txnId TEXT PRIMARY KEY REFERENCES credit_transaction(id), keyId TEXT NOT NULL)`);
+  return drizzle(sqlite) as unknown as CreditsDB;
+}
+
+let db: CreditsDB;
+const U = "user_1";
+beforeEach(() => {
+  db = freshDb();
+});
+
+describe("ledger basics", () => {
+  test("addCredits → balance is the sum of deltas", async () => {
+    expect(await getBalance(db, U)).toBe(0);
+    expect(await addCredits(db, U, 100, "topup")).toBe(100);
+    expect(await addCredits(db, U, 50, "topup")).toBe(150);
+    expect(await getBalance(db, U)).toBe(150);
+  });
+
+  test("addCredits rejects a non-positive / non-integer amount", async () => {
+    await expect(addCredits(db, U, 0, "x")).rejects.toThrow();
+    await expect(addCredits(db, U, 1.5, "x")).rejects.toThrow();
+  });
+});
+
+describe("debitIfCovers — the atomic floor (never negative)", () => {
+  test("debits when covered; rejects when it would go below zero; balance never negative", async () => {
+    await addCredits(db, U, 100, "topup");
+    expect(await debitIfCovers(db, U, 30, "transcribe")).toBe(true);
+    expect(await getBalance(db, U)).toBe(70);
+    expect(await debitIfCovers(db, U, 100, "transcribe")).toBe(false); // 100 > 70 → no debit
+    expect(await getBalance(db, U)).toBe(70); // unchanged — the conditional INSERT didn't fire
+  });
+
+  test("self-guard: a negative amount can't MINT credits", async () => {
+    await addCredits(db, U, 10, "topup");
+    expect(await debitIfCovers(db, U, -50, "evil")).toBe(false);
+    expect(await getBalance(db, U)).toBe(10);
+  });
+
+  test("attributes the debit to a key (keySpend)", async () => {
+    await addCredits(db, U, 100, "topup");
+    await debitIfCovers(db, U, 40, "transcribe", "key_abc");
+    expect(await keySpend(db, "key_abc")).toBe(40);
+    expect(await keySpend(db, "key_other")).toBe(0);
+  });
+});
+
+describe("debitCredits — read-then-write, throws when short", () => {
+  test("throws InsufficientCreditsError with balance + needed", async () => {
+    await addCredits(db, U, 20, "topup");
+    expect(await debitCredits(db, U, 15, "use")).toBe(5);
+    await expect(debitCredits(db, U, 99, "use")).rejects.toBeInstanceOf(InsufficientCreditsError);
+  });
+});
+
+describe("debitOnceIfCovers — idempotent double-spend guard", () => {
+  test("a fresh debit, then a replay of the SAME idemKey does NOT debit again", async () => {
+    await addCredits(db, U, 100, "topup");
+    const first = await debitOnceIfCovers(db, U, 30, "refund", "stripe_re_1");
+    expect(first.outcome).toBe("debited");
+    expect(first.nonce).toBe(nonceFor("refund", "stripe_re_1"));
+    expect(await getBalance(db, U)).toBe(70);
+
+    const replay = await debitOnceIfCovers(db, U, 30, "refund", "stripe_re_1"); // retry
+    expect(replay.outcome).toBe("replayed");
+    expect(await getBalance(db, U)).toBe(70); // NOT 40 — no second debit
+  });
+
+  test("insufficient when the balance no longer covers a NEW idemKey", async () => {
+    await addCredits(db, U, 10, "topup");
+    const r = await debitOnceIfCovers(db, U, 50, "refund", "stripe_re_2");
+    expect(r.outcome).toBe("insufficient");
+    expect(await getBalance(db, U)).toBe(10);
+  });
+
+  test("debitOnceAttributed attributes only the fresh debit", async () => {
+    await addCredits(db, U, 100, "topup");
+    await debitOnceAttributed(db, U, 25, "bulk", "item_1", "key_x");
+    await debitOnceAttributed(db, U, 25, "bulk", "item_1", "key_x"); // replay → no new spend
+    expect(await keySpend(db, "key_x")).toBe(25);
+  });
+});
+
+describe("grantOnce — idempotent money-IN (the webhook credit point)", () => {
+  test("a fresh grant credits; a replay of the SAME idemKey does NOT credit again", async () => {
+    expect(await grantOnce(db, U, 600, "pi:abc", "topup", 2000)).toBe(true);
+    expect(await getBalance(db, U)).toBe(600);
+    expect(await grantOnce(db, U, 600, "pi:abc", "topup", 2000)).toBe(false); // redelivery / Resend
+    expect(await getBalance(db, U)).toBe(600); // NOT 1200 — keyed on pi:abc
+  });
+
+  test("legacyKey honoured: a grant already recorded under the OLD key is never re-granted under a new one", async () => {
+    expect(await grantOnce(db, U, 100, "stripe:evt_1", "topup", 500)).toBe(true); // the pre-deploy grant
+    expect(await grantOnce(db, U, 100, "cs:sess_1", "topup", 500, "stripe:evt_1")).toBe(false); // key moved → skip
+    expect(await getBalance(db, U)).toBe(100);
+  });
+
+  test("rejects a non-finite / fractional / non-positive amount (ledger stays integer-by-construction)", async () => {
+    expect(await grantOnce(db, U, Infinity, "pi:x1", "topup")).toBe(false);
+    expect(await grantOnce(db, U, 500.9, "pi:x2", "topup")).toBe(false);
+    expect(await grantOnce(db, U, -100, "pi:x3", "topup")).toBe(false);
+    expect(await getBalance(db, U)).toBe(0);
+  });
+
+  test("annotates the cash that landed (amountCents) on a fresh grant", async () => {
+    await grantOnce(db, U, 600, "pi:amt", "topup", 2000);
+    const txns = await listTransactions(db, U);
+    expect(txns.find((t) => t.id === "pi:amt")?.amountCents).toBe(2000);
+  });
+});
+
+describe("listTransactions + ledgerStats", () => {
+  test("recent transactions newest-first; aggregate stats", async () => {
+    await addCredits(db, U, 100, "topup");
+    await debitIfCovers(db, U, 30, "transcribe");
+    const txns = await listTransactions(db, U);
+    expect(txns.length).toBe(2);
+    expect(txns.map((t) => t.delta).sort((a, b) => a - b)).toEqual([-30, 100]);
+    expect(await ledgerStats(db)).toEqual({ creditsIssued: 100, creditsSpent: 30, balanceOutstanding: 70 });
+  });
+});

package/tsconfig.json

@@ -0,0 +1 @@
+{ "extends": "../../tsconfig.base.json", "compilerOptions": { "types": ["bun"] }, "include": ["src", "test"] }