@wopr-network/platform-core 0.1.0

package/dist/credits/credit-expiry-cron.test.js

@@ -0,0 +1,67 @@
+import { afterAll, beforeAll, beforeEach, describe, expect, it } from "vitest";
+import { createTestDb, truncateAllTables } from "../test/db.js";
+import { Credit } from "./credit.js";
+import { runCreditExpiryCron } from "./credit-expiry-cron.js";
+import { DrizzleCreditLedger } from "./credit-ledger.js";
+describe("runCreditExpiryCron", () => {
+    let pool;
+    let ledger;
+    beforeAll(async () => {
+        const { db, pool: p } = await createTestDb();
+        pool = p;
+        ledger = new DrizzleCreditLedger(db);
+    });
+    afterAll(async () => {
+        await pool.close();
+    });
+    beforeEach(async () => {
+        await truncateAllTables(pool);
+    });
+    // All tests pass an explicit `now` parameter — hardcoded dates are time-independent
+    // because runCreditExpiryCron never reads the system clock.
+    it("returns empty result when no expired credits exist", async () => {
+        const result = await runCreditExpiryCron({ ledger, now: "2026-01-15T00:00:00Z" });
+        expect(result.processed).toBe(0);
+        expect(result.expired).toEqual([]);
+        expect(result.errors).toEqual([]);
+    });
+    it("debits expired promotional credit grant", async () => {
+        await ledger.credit("tenant-1", Credit.fromCents(500), "promo", "New user bonus", "promo:tenant-1", undefined, undefined, "2026-01-10T00:00:00Z");
+        const result = await runCreditExpiryCron({ ledger, now: "2026-01-15T00:00:00Z" });
+        expect(result.processed).toBe(1);
+        expect(result.expired).toContain("tenant-1");
+        const balance = await ledger.balance("tenant-1");
+        expect(balance.toCents()).toBe(0);
+    });
+    it("does not debit non-expired credits", async () => {
+        await ledger.credit("tenant-1", Credit.fromCents(500), "promo", "Future bonus", "promo:tenant-1-future", undefined, undefined, "2026-02-01T00:00:00Z");
+        const result = await runCreditExpiryCron({ ledger, now: "2026-01-15T00:00:00Z" });
+        expect(result.processed).toBe(0);
+        const balance = await ledger.balance("tenant-1");
+        expect(balance.toCents()).toBe(500);
+    });
+    it("does not debit credits without expires_at", async () => {
+        await ledger.credit("tenant-1", Credit.fromCents(500), "purchase", "Top-up");
+        const result = await runCreditExpiryCron({ ledger, now: "2026-01-15T00:00:00Z" });
+        expect(result.processed).toBe(0);
+        const balance = await ledger.balance("tenant-1");
+        expect(balance.toCents()).toBe(500);
+    });
+    it("only debits up to available balance when partially consumed", async () => {
+        await ledger.credit("tenant-1", Credit.fromCents(500), "promo", "Promo", "promo:partial", undefined, undefined, "2026-01-10T00:00:00Z");
+        await ledger.debit("tenant-1", Credit.fromCents(300), "bot_runtime", "Runtime");
+        const result = await runCreditExpiryCron({ ledger, now: "2026-01-15T00:00:00Z" });
+        expect(result.processed).toBe(1);
+        const balance = await ledger.balance("tenant-1");
+        expect(balance.toCents()).toBe(0);
+    });
+    it("is idempotent -- does not double-debit on second run", async () => {
+        await ledger.credit("tenant-1", Credit.fromCents(500), "promo", "Promo", "promo:idemp", undefined, undefined, "2026-01-10T00:00:00Z");
+        await runCreditExpiryCron({ ledger, now: "2026-01-15T00:00:00Z" });
+        const balanceAfterFirst = await ledger.balance("tenant-1");
+        const result2 = await runCreditExpiryCron({ ledger, now: "2026-01-15T00:00:00Z" });
+        expect(result2.processed).toBe(0);
+        const balanceAfterSecond = await ledger.balance("tenant-1");
+        expect(balanceAfterSecond.toCents()).toBe(balanceAfterFirst.toCents());
+    });
+});

package/dist/credits/credit-ledger-extra.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/credits/credit-ledger-extra.test.js

@@ -0,0 +1,40 @@
+import { afterAll, beforeAll, beforeEach, describe, expect, it } from "vitest";
+import { beginTestTransaction, createTestDb, endTestTransaction, rollbackTestTransaction } from "../test/db.js";
+import { Credit } from "./credit.js";
+import { CreditLedger, InsufficientBalanceError } from "./credit-ledger.js";
+let pool;
+let db;
+beforeAll(async () => {
+    ({ db, pool } = await createTestDb());
+    await beginTestTransaction(pool);
+});
+afterAll(async () => {
+    await endTestTransaction(pool);
+    await pool.close();
+});
+describe("CreditLedger concurrent debit safety", () => {
+    let ledger;
+    beforeEach(async () => {
+        await rollbackTestTransaction(pool);
+        ledger = new CreditLedger(db);
+    });
+    it("concurrent debits do not overdraw — at least one should fail with InsufficientBalanceError", async () => {
+        // Fund with exactly 100 cents
+        await ledger.credit("t1", Credit.fromCents(100), "purchase");
+        // Fire two 100-cent debits concurrently — only one can succeed
+        const results = await Promise.allSettled([
+            ledger.debit("t1", Credit.fromCents(100), "bot_runtime", "debit-1"),
+            ledger.debit("t1", Credit.fromCents(100), "bot_runtime", "debit-2"),
+        ]);
+        const fulfilled = results.filter((r) => r.status === "fulfilled");
+        const rejected = results.filter((r) => r.status === "rejected");
+        // Exactly one succeeds, one fails (PGlite serializes transactions so this is deterministic)
+        expect(fulfilled).toHaveLength(1);
+        expect(rejected).toHaveLength(1);
+        const err = rejected[0].reason;
+        expect(err).toBeInstanceOf(InsufficientBalanceError);
+        // Final balance must be exactly 0, not negative
+        const bal = await ledger.balance("t1");
+        expect(bal.toCents()).toBe(0);
+    });
+});

package/dist/credits/credit-ledger.bench.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/credits/credit-ledger.bench.js

@@ -0,0 +1,33 @@
+import { afterAll, beforeAll, beforeEach, bench, describe } from "vitest";
+import { createTestDb, truncateAllTables } from "../test/db.js";
+import { Credit } from "./credit.js";
+import { CreditLedger } from "./credit-ledger.js";
+let db;
+let pool;
+beforeAll(async () => {
+    ({ db, pool } = await createTestDb());
+});
+afterAll(async () => {
+    await pool.close();
+});
+describe("CreditLedger throughput", () => {
+    let ledger;
+    beforeEach(async () => {
+        await truncateAllTables(pool);
+        ledger = new CreditLedger(db);
+    });
+    let creditIdx = 0;
+    let debitIdx = 0;
+    bench("credit operation", async () => {
+        const tenant = `tenant-${creditIdx++ % 100}`;
+        await ledger.credit(tenant, Credit.fromCents(100), "purchase", "bench");
+    }, { iterations: 1_000 });
+    bench("debit operation", async () => {
+        const tenant = `tenant-${debitIdx++ % 100}`;
+        await ledger.debit(tenant, Credit.fromCents(1), "adapter_usage", "bench");
+    }, { iterations: 1_000 });
+    bench("balance query", async () => {
+        const tenant = `tenant-${debitIdx++ % 100}`;
+        await ledger.balance(tenant);
+    }, { iterations: 5_000 });
+});

package/dist/credits/credit-ledger.d.ts

@@ -0,0 +1,130 @@
+/**
+ * NAMING CONVENTION — cents vs credits (WOP-1058)
+ *
+ * - `_cents` suffix = value denominated in USD cents.
+ *   Used for: Stripe amounts, PayRam amounts, ledger balances, ledger transactions.
+ *   The platform credit unit IS the USD cent (1 credit = 1 cent = $0.01).
+ *
+ * - `_credits` suffix = platform credit count (used in DB columns and raw storage).
+ *   Semantically identical to cents but signals "this is a platform concept stored
+ *   as a Credit.toRaw() nanodollar value in the database."
+ *
+ * - NEVER rename a Stripe/PayRam-facing `_cents` field to `_credits`.
+ *   Stripe's `amount` parameter and `amount_total` response are always USD cents.
+ *   PayRam's `amountUsdCents` is always USD cents.
+ *
+ * - When adding new fields: if it touches a payment processor API, use `_cents`.
+ *   If it's a DB column storing Credit.toRaw() values, use `_credits`.
+ *
+ * The Credit class bridges the two:
+ *   Credit.fromCents(cents)  — converts USD cents → Credit (nanodollar raw units)
+ *   credit.toCents()         — converts Credit → USD cents (for display / API responses)
+ */
+import type { PlatformDb } from "../db/index.js";
+import { Credit } from "./credit.js";
+/** Transaction types that add credits */
+export type CreditType = "signup_grant" | "admin_grant" | "purchase" | "bounty" | "referral" | "promo" | "community_dividend" | "affiliate_bonus" | "affiliate_match" | "correction";
+/** Transaction types that remove credits */
+export type DebitType = "bot_runtime" | "adapter_usage" | "addon" | "refund" | "correction" | "resource_upgrade" | "storage_upgrade" | "onboarding_llm" | "credit_expiry";
+export type TransactionType = CreditType | DebitType;
+export interface CreditTransaction {
+    id: string;
+    tenantId: string;
+    amount: Credit;
+    balanceAfter: Credit;
+    type: string;
+    description: string | null;
+    referenceId: string | null;
+    fundingSource: string | null;
+    attributedUserId: string | null;
+    createdAt: string;
+    expiresAt: string | null;
+}
+export interface HistoryOptions {
+    limit?: number;
+    offset?: number;
+    type?: string;
+}
+export interface MemberUsageSummary {
+    userId: string;
+    totalDebit: Credit;
+    transactionCount: number;
+}
+/** Insufficient balance error — thrown when a debit would make balance negative. */
+export declare class InsufficientBalanceError extends Error {
+    currentBalance: Credit;
+    requestedAmount: Credit;
+    constructor(currentBalance: Credit, requestedAmount: Credit);
+}
+export interface ICreditLedger {
+    credit(tenantId: string, amount: Credit, type: CreditType, description?: string, referenceId?: string, fundingSource?: string, attributedUserId?: string, expiresAt?: string): Promise<CreditTransaction>;
+    expiredCredits(now: string): Promise<Array<{
+        id: string;
+        tenantId: string;
+        amount: Credit;
+    }>>;
+    debit(tenantId: string, amount: Credit, type: DebitType, description?: string, referenceId?: string, allowNegative?: boolean, attributedUserId?: string): Promise<CreditTransaction>;
+    balance(tenantId: string): Promise<Credit>;
+    hasReferenceId(referenceId: string): Promise<boolean>;
+    history(tenantId: string, opts?: HistoryOptions): Promise<CreditTransaction[]>;
+    tenantsWithBalance(): Promise<Array<{
+        tenantId: string;
+        balance: Credit;
+    }>>;
+    memberUsage(tenantId: string): Promise<MemberUsageSummary[]>;
+    lifetimeSpend(tenantId: string): Promise<Credit>;
+    lifetimeSpendBatch(tenantIds: string[]): Promise<Map<string, Credit>>;
+}
+/**
+ * Credit ledger — the single source of truth for credit balances.
+ *
+ * All mutations go through Drizzle transactions to ensure the
+ * creditBalances row is always consistent with the sum of creditTransactions.
+ * Zero raw SQL in application code.
+ */
+export declare class DrizzleCreditLedger implements ICreditLedger {
+    private readonly db;
+    constructor(db: PlatformDb);
+    /**
+     * Read balance with FOR UPDATE row lock. Ensures the row exists first
+     * (upsert with ON CONFLICT DO NOTHING), then locks it for the duration
+     * of the enclosing transaction.
+     */
+    private lockedBalance;
+    /**
+     * Add credits to a tenant's balance.
+     * @returns The created transaction record.
+     */
+    credit(tenantId: string, amount: Credit, type: CreditType, description?: string, referenceId?: string, fundingSource?: string, attributedUserId?: string, expiresAt?: string): Promise<CreditTransaction>;
+    /**
+     * Deduct credits from a tenant's balance.
+     * Throws InsufficientBalanceError if balance would go negative (unless allowNegative is true).
+     * @param allowNegative - If true, allow balance to go negative (for grace buffer debits). Default: false.
+     * @returns The created transaction record.
+     */
+    debit(tenantId: string, amount: Credit, type: DebitType, description?: string, referenceId?: string, allowNegative?: boolean, attributedUserId?: string): Promise<CreditTransaction>;
+    /** Get current balance for a tenant. Returns Credit.ZERO if tenant has no balance row. */
+    balance(tenantId: string): Promise<Credit>;
+    /** Check if a reference ID has already been used (for idempotency). */
+    hasReferenceId(referenceId: string): Promise<boolean>;
+    /** Get transaction history for a tenant with optional filtering and pagination. */
+    history(tenantId: string, opts?: HistoryOptions): Promise<CreditTransaction[]>;
+    /** Aggregate debit totals per attributed user for a tenant. */
+    memberUsage(tenantId: string): Promise<MemberUsageSummary[]>;
+    /** Sum of all debit transactions (absolute value) for a tenant. */
+    lifetimeSpend(tenantId: string): Promise<Credit>;
+    /** Batch version of lifetimeSpend — single query for multiple tenants. */
+    lifetimeSpendBatch(tenantIds: string[]): Promise<Map<string, Credit>>;
+    /** Return expired credit grant transactions not yet processed by the expiry cron. */
+    expiredCredits(now: string): Promise<Array<{
+        id: string;
+        tenantId: string;
+        amount: Credit;
+    }>>;
+    /** List all tenants with positive balance (for cron deduction). */
+    tenantsWithBalance(): Promise<Array<{
+        tenantId: string;
+        balance: Credit;
+    }>>;
+}
+export { DrizzleCreditLedger as CreditLedger };

package/dist/credits/credit-ledger.js

@@ -0,0 +1,293 @@
+/**
+ * NAMING CONVENTION — cents vs credits (WOP-1058)
+ *
+ * - `_cents` suffix = value denominated in USD cents.
+ *   Used for: Stripe amounts, PayRam amounts, ledger balances, ledger transactions.
+ *   The platform credit unit IS the USD cent (1 credit = 1 cent = $0.01).
+ *
+ * - `_credits` suffix = platform credit count (used in DB columns and raw storage).
+ *   Semantically identical to cents but signals "this is a platform concept stored
+ *   as a Credit.toRaw() nanodollar value in the database."
+ *
+ * - NEVER rename a Stripe/PayRam-facing `_cents` field to `_credits`.
+ *   Stripe's `amount` parameter and `amount_total` response are always USD cents.
+ *   PayRam's `amountUsdCents` is always USD cents.
+ *
+ * - When adding new fields: if it touches a payment processor API, use `_cents`.
+ *   If it's a DB column storing Credit.toRaw() values, use `_credits`.
+ *
+ * The Credit class bridges the two:
+ *   Credit.fromCents(cents)  — converts USD cents → Credit (nanodollar raw units)
+ *   credit.toCents()         — converts Credit → USD cents (for display / API responses)
+ */
+import crypto from "node:crypto";
+import { and, desc, eq, inArray, isNotNull, sql } from "drizzle-orm";
+import { creditBalances, creditTransactions } from "../db/schema/credits.js";
+import { Credit } from "./credit.js";
+/** Insufficient balance error — thrown when a debit would make balance negative. */
+export class InsufficientBalanceError extends Error {
+    currentBalance;
+    requestedAmount;
+    constructor(currentBalance, requestedAmount) {
+        super(`Insufficient balance: current ${currentBalance.toDisplayString()}, requested debit ${requestedAmount.toDisplayString()}`);
+        this.name = "InsufficientBalanceError";
+        this.currentBalance = currentBalance;
+        this.requestedAmount = requestedAmount;
+    }
+}
+/**
+ * Credit ledger — the single source of truth for credit balances.
+ *
+ * All mutations go through Drizzle transactions to ensure the
+ * creditBalances row is always consistent with the sum of creditTransactions.
+ * Zero raw SQL in application code.
+ */
+export class DrizzleCreditLedger {
+    db;
+    constructor(db) {
+        this.db = db;
+    }
+    /**
+     * Read balance with FOR UPDATE row lock. Ensures the row exists first
+     * (upsert with ON CONFLICT DO NOTHING), then locks it for the duration
+     * of the enclosing transaction.
+     */
+    async lockedBalance(tx, tenantId) {
+        // raw SQL: Drizzle cannot express INSERT ... ON CONFLICT DO NOTHING for atomic upsert
+        await tx.execute(sql `INSERT INTO credit_balances (tenant_id, balance_credits, last_updated)
+          VALUES (${tenantId}, 0, now())
+          ON CONFLICT (tenant_id) DO NOTHING`);
+        // raw SQL: Drizzle cannot express SELECT FOR UPDATE for row-level locking
+        const rows = (await tx.execute(sql `SELECT balance_credits FROM credit_balances
+          WHERE tenant_id = ${tenantId} FOR UPDATE`));
+        const raw = rows.rows[0]?.balance_credits;
+        return raw != null ? Credit.fromRaw(Number(raw)) : Credit.ZERO;
+    }
+    /**
+     * Add credits to a tenant's balance.
+     * @returns The created transaction record.
+     */
+    async credit(tenantId, amount, type, description, referenceId, fundingSource, attributedUserId, expiresAt) {
+        if (amount.isZero() || amount.isNegative()) {
+            throw new Error("amount must be positive for credits");
+        }
+        return this.db.transaction(async (tx) => {
+            const currentBalance = await this.lockedBalance(tx, tenantId);
+            const newBalance = currentBalance.add(amount);
+            // Row guaranteed to exist after lockedBalance()
+            await tx
+                .update(creditBalances)
+                .set({
+                balance: newBalance,
+                lastUpdated: sql `(now())`,
+            })
+                .where(eq(creditBalances.tenantId, tenantId));
+            // Insert transaction record
+            const id = crypto.randomUUID();
+            const txn = {
+                id,
+                tenantId,
+                amount,
+                balanceAfter: newBalance,
+                type,
+                description: description ?? null,
+                referenceId: referenceId ?? null,
+                fundingSource: fundingSource ?? null,
+                attributedUserId: attributedUserId ?? null,
+                expiresAt: expiresAt ?? null,
+            };
+            await tx.insert(creditTransactions).values(txn);
+            return {
+                id,
+                tenantId: txn.tenantId,
+                amount,
+                balanceAfter: newBalance,
+                type: txn.type,
+                description: txn.description ?? null,
+                referenceId: txn.referenceId ?? null,
+                fundingSource: txn.fundingSource ?? null,
+                attributedUserId: txn.attributedUserId ?? null,
+                createdAt: new Date().toISOString(),
+                expiresAt: expiresAt ?? null,
+            };
+        });
+    }
+    /**
+     * Deduct credits from a tenant's balance.
+     * Throws InsufficientBalanceError if balance would go negative (unless allowNegative is true).
+     * @param allowNegative - If true, allow balance to go negative (for grace buffer debits). Default: false.
+     * @returns The created transaction record.
+     */
+    async debit(tenantId, amount, type, description, referenceId, allowNegative, attributedUserId) {
+        if (amount.isZero() || amount.isNegative()) {
+            throw new Error("amount must be positive for debits");
+        }
+        return this.db.transaction(async (tx) => {
+            const currentBalance = await this.lockedBalance(tx, tenantId);
+            if (!allowNegative && currentBalance.lessThan(amount)) {
+                throw new InsufficientBalanceError(currentBalance, amount);
+            }
+            const newBalance = currentBalance.subtract(amount);
+            // Row guaranteed to exist after lockedBalance()
+            await tx
+                .update(creditBalances)
+                .set({
+                balance: newBalance,
+                lastUpdated: sql `(now())`,
+            })
+                .where(eq(creditBalances.tenantId, tenantId));
+            const id = crypto.randomUUID();
+            const negativeAmount = Credit.fromRaw(-amount.toRaw()); // negative for debits
+            const txn = {
+                id,
+                tenantId,
+                amount: negativeAmount,
+                balanceAfter: newBalance,
+                type,
+                description: description ?? null,
+                referenceId: referenceId ?? null,
+                fundingSource: null,
+                attributedUserId: attributedUserId ?? null,
+            };
+            await tx.insert(creditTransactions).values(txn);
+            return {
+                id,
+                tenantId: txn.tenantId,
+                amount: negativeAmount,
+                balanceAfter: newBalance,
+                type: txn.type,
+                description: txn.description ?? null,
+                referenceId: txn.referenceId ?? null,
+                fundingSource: null,
+                attributedUserId: txn.attributedUserId ?? null,
+                createdAt: new Date().toISOString(),
+                expiresAt: null,
+            };
+        });
+    }
+    /** Get current balance for a tenant. Returns Credit.ZERO if tenant has no balance row. */
+    async balance(tenantId) {
+        const rows = await this.db
+            .select({ balance: creditBalances.balance })
+            .from(creditBalances)
+            .where(eq(creditBalances.tenantId, tenantId));
+        return rows[0]?.balance ?? Credit.ZERO;
+    }
+    /** Check if a reference ID has already been used (for idempotency). */
+    async hasReferenceId(referenceId) {
+        const rows = await this.db
+            .select({ id: creditTransactions.id })
+            .from(creditTransactions)
+            .where(eq(creditTransactions.referenceId, referenceId))
+            .limit(1);
+        return rows.length > 0;
+    }
+    /** Get transaction history for a tenant with optional filtering and pagination. */
+    async history(tenantId, opts = {}) {
+        const limit = Math.min(Math.max(1, opts.limit ?? 50), 250);
+        const offset = Math.max(0, opts.offset ?? 0);
+        const conditions = [eq(creditTransactions.tenantId, tenantId)];
+        if (opts.type) {
+            conditions.push(eq(creditTransactions.type, opts.type));
+        }
+        return this.db
+            .select()
+            .from(creditTransactions)
+            .where(and(...conditions))
+            .orderBy(desc(creditTransactions.createdAt))
+            .limit(limit)
+            .offset(offset);
+    }
+    /** Aggregate debit totals per attributed user for a tenant. */
+    async memberUsage(tenantId) {
+        const rows = await this.db
+            .select({
+            userId: creditTransactions.attributedUserId,
+            totalDebitRaw: sql `COALESCE(SUM(ABS(${creditTransactions.amount})), 0)`,
+            transactionCount: sql `COUNT(*)`,
+        })
+            .from(creditTransactions)
+            .where(and(eq(creditTransactions.tenantId, tenantId), isNotNull(creditTransactions.attributedUserId), sql `${creditTransactions.amount} < 0`))
+            .groupBy(creditTransactions.attributedUserId);
+        return rows
+            .filter((r) => r.userId != null)
+            .map((r) => ({
+            userId: r.userId,
+            totalDebit: Credit.fromRaw(Number(r.totalDebitRaw)),
+            transactionCount: r.transactionCount,
+        }));
+    }
+    /** Sum of all debit transactions (absolute value) for a tenant. */
+    async lifetimeSpend(tenantId) {
+        const rows = await this.db
+            .select({
+            // raw SQL: Drizzle cannot express COALESCE(SUM(ABS(...))) with typed operators
+            totalRaw: sql `COALESCE(SUM(ABS(${creditTransactions.amount})), 0)`,
+        })
+            .from(creditTransactions)
+            .where(and(eq(creditTransactions.tenantId, tenantId), sql `${creditTransactions.amount} < 0`));
+        const raw = BigInt(String(rows[0]?.totalRaw ?? 0));
+        if (raw > BigInt(Number.MAX_SAFE_INTEGER)) {
+            throw new Error(`lifetimeSpend overflow: ${raw}`);
+        }
+        return Credit.fromRaw(Number(raw));
+    }
+    /** Batch version of lifetimeSpend — single query for multiple tenants. */
+    async lifetimeSpendBatch(tenantIds) {
+        if (tenantIds.length === 0)
+            return new Map();
+        const rows = await this.db
+            .select({
+            tenantId: creditTransactions.tenantId,
+            // raw SQL: Drizzle cannot express COALESCE(SUM(ABS(...))) with typed operators
+            totalRaw: sql `COALESCE(SUM(ABS(${creditTransactions.amount})), 0)`,
+        })
+            .from(creditTransactions)
+            .where(and(inArray(creditTransactions.tenantId, tenantIds), sql `${creditTransactions.amount} < 0`))
+            .groupBy(creditTransactions.tenantId);
+        const result = new Map();
+        for (const row of rows) {
+            const raw = BigInt(String(row.totalRaw));
+            if (raw > BigInt(Number.MAX_SAFE_INTEGER)) {
+                throw new Error(`lifetimeSpend overflow: ${raw}`);
+            }
+            result.set(row.tenantId, Credit.fromRaw(Number(raw)));
+        }
+        // Fill zeros for tenants with no debit transactions
+        for (const id of tenantIds) {
+            if (!result.has(id))
+                result.set(id, Credit.ZERO);
+        }
+        return result;
+    }
+    /** Return expired credit grant transactions not yet processed by the expiry cron. */
+    async expiredCredits(now) {
+        const rows = await this.db
+            .select({
+            id: creditTransactions.id,
+            tenantId: creditTransactions.tenantId,
+            amount: creditTransactions.amount,
+        })
+            .from(creditTransactions)
+            .where(and(isNotNull(creditTransactions.expiresAt), sql `${creditTransactions.expiresAt} <= ${now}`, sql `${creditTransactions.amount} > 0`));
+        const result = [];
+        for (const row of rows) {
+            if (await this.hasReferenceId(`expiry:${row.id}`))
+                continue;
+            result.push(row);
+        }
+        return result;
+    }
+    /** List all tenants with positive balance (for cron deduction). */
+    async tenantsWithBalance() {
+        return this.db
+            .select({
+            tenantId: creditBalances.tenantId,
+            balance: creditBalances.balance,
+        })
+            .from(creditBalances)
+            .where(sql `${creditBalances.balance} > 0`);
+    }
+}
+// Backward-compat alias — callers using 'new CreditLedger(db)' continue to work.
+export { DrizzleCreditLedger as CreditLedger };

package/dist/credits/credit-ledger.test.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Tests for CreditLedger — including the allowNegative debit parameter (WOP-821).
+ */
+export {};