@wopr-network/platform-core 0.1.0

package/dist/credits/auto-topup-settings-repository.js

@@ -0,0 +1,184 @@
+import { and, eq, lte, sql } from "drizzle-orm";
+import { creditAutoTopupSettings } from "../db/schema/credit-auto-topup-settings.js";
+import { Credit } from "./credit.js";
+export const ALLOWED_TOPUP_AMOUNTS = [500, 1000, 2000, 5000, 10000, 20000, 50000];
+export const ALLOWED_THRESHOLDS = [200, 500, 1000];
+export const ALLOWED_SCHEDULE_INTERVALS = ["daily", "weekly", "monthly"];
+export function computeNextScheduleAt(interval, now = new Date()) {
+    if (!interval)
+        return null;
+    const next = new Date(now);
+    if (interval === "daily") {
+        next.setUTCDate(next.getUTCDate() + 1);
+        next.setUTCHours(0, 0, 0, 0);
+    }
+    else if (interval === "weekly") {
+        next.setUTCDate(next.getUTCDate() + 7);
+        next.setUTCHours(0, 0, 0, 0);
+    }
+    else {
+        next.setUTCMonth(next.getUTCMonth() + 1);
+        next.setUTCDate(1);
+        next.setUTCHours(0, 0, 0, 0);
+    }
+    return next.toISOString();
+}
+export class DrizzleAutoTopupSettingsRepository {
+    db;
+    constructor(db) {
+        this.db = db;
+    }
+    async getByTenant(tenantId) {
+        const row = (await this.db.select().from(creditAutoTopupSettings).where(eq(creditAutoTopupSettings.tenantId, tenantId)))[0];
+        return row ? mapRow(row) : null;
+    }
+    async upsert(tenantId, settings) {
+        const now = sql `now()`;
+        const values = {
+            tenantId,
+            updatedAt: now,
+        };
+        const updateSet = { updatedAt: now };
+        if (settings.usageEnabled !== undefined) {
+            values.usageEnabled = settings.usageEnabled;
+            updateSet.usageEnabled = values.usageEnabled;
+        }
+        if (settings.usageThreshold !== undefined) {
+            const cents = settings.usageThreshold.toCentsRounded();
+            values.usageThresholdCents = cents;
+            updateSet.usageThresholdCents = cents;
+        }
+        if (settings.usageTopup !== undefined) {
+            const cents = settings.usageTopup.toCentsRounded();
+            values.usageTopupCents = cents;
+            updateSet.usageTopupCents = cents;
+        }
+        if (settings.scheduleEnabled !== undefined) {
+            values.scheduleEnabled = settings.scheduleEnabled;
+            updateSet.scheduleEnabled = values.scheduleEnabled;
+        }
+        if (settings.scheduleAmount !== undefined) {
+            const cents = settings.scheduleAmount.toCentsRounded();
+            values.scheduleAmountCents = cents;
+            updateSet.scheduleAmountCents = cents;
+        }
+        if (settings.scheduleIntervalHours !== undefined) {
+            values.scheduleIntervalHours = settings.scheduleIntervalHours;
+            updateSet.scheduleIntervalHours = settings.scheduleIntervalHours;
+        }
+        if (settings.scheduleNextAt !== undefined) {
+            values.scheduleNextAt = settings.scheduleNextAt;
+            updateSet.scheduleNextAt = settings.scheduleNextAt;
+        }
+        await this.db
+            .insert(creditAutoTopupSettings)
+            .values(values)
+            .onConflictDoUpdate({ target: creditAutoTopupSettings.tenantId, set: updateSet });
+    }
+    async setUsageChargeInFlight(tenantId, inFlight) {
+        await this.db
+            .update(creditAutoTopupSettings)
+            .set({ usageChargeInFlight: inFlight, updatedAt: sql `now()` })
+            .where(eq(creditAutoTopupSettings.tenantId, tenantId));
+    }
+    async tryAcquireUsageInFlight(tenantId) {
+        const rows = await this.db
+            .update(creditAutoTopupSettings)
+            .set({ usageChargeInFlight: true, updatedAt: sql `now()` })
+            .where(and(eq(creditAutoTopupSettings.tenantId, tenantId), eq(creditAutoTopupSettings.usageChargeInFlight, false)))
+            .returning({ tenantId: creditAutoTopupSettings.tenantId });
+        return rows.length > 0;
+    }
+    async incrementUsageFailures(tenantId) {
+        await this.db
+            .update(creditAutoTopupSettings)
+            .set({
+            usageConsecutiveFailures: sql `${creditAutoTopupSettings.usageConsecutiveFailures} + 1`,
+            updatedAt: sql `now()`,
+        })
+            .where(eq(creditAutoTopupSettings.tenantId, tenantId));
+        const row = await this.getByTenant(tenantId);
+        return row?.usageConsecutiveFailures ?? 0;
+    }
+    async resetUsageFailures(tenantId) {
+        await this.db
+            .update(creditAutoTopupSettings)
+            .set({ usageConsecutiveFailures: 0, updatedAt: sql `now()` })
+            .where(eq(creditAutoTopupSettings.tenantId, tenantId));
+    }
+    async disableUsage(tenantId) {
+        await this.db
+            .update(creditAutoTopupSettings)
+            .set({ usageEnabled: false, updatedAt: sql `now()` })
+            .where(eq(creditAutoTopupSettings.tenantId, tenantId));
+    }
+    async incrementScheduleFailures(tenantId) {
+        await this.db
+            .update(creditAutoTopupSettings)
+            .set({
+            scheduleConsecutiveFailures: sql `${creditAutoTopupSettings.scheduleConsecutiveFailures} + 1`,
+            updatedAt: sql `now()`,
+        })
+            .where(eq(creditAutoTopupSettings.tenantId, tenantId));
+        const row = await this.getByTenant(tenantId);
+        return row?.scheduleConsecutiveFailures ?? 0;
+    }
+    async resetScheduleFailures(tenantId) {
+        await this.db
+            .update(creditAutoTopupSettings)
+            .set({ scheduleConsecutiveFailures: 0, updatedAt: sql `now()` })
+            .where(eq(creditAutoTopupSettings.tenantId, tenantId));
+    }
+    async disableSchedule(tenantId) {
+        await this.db
+            .update(creditAutoTopupSettings)
+            .set({ scheduleEnabled: false, updatedAt: sql `now()` })
+            .where(eq(creditAutoTopupSettings.tenantId, tenantId));
+    }
+    async advanceScheduleNextAt(tenantId) {
+        const settings = await this.getByTenant(tenantId);
+        if (!settings?.scheduleNextAt)
+            return;
+        const currentNext = new Date(settings.scheduleNextAt);
+        const newNext = new Date(currentNext.getTime() + settings.scheduleIntervalHours * 60 * 60 * 1000);
+        await this.db
+            .update(creditAutoTopupSettings)
+            .set({ scheduleNextAt: newNext.toISOString(), updatedAt: sql `now()` })
+            .where(eq(creditAutoTopupSettings.tenantId, tenantId));
+    }
+    async getMaxConsecutiveFailures() {
+        const result = await this.db
+            .select({
+            maxFailures: sql `GREATEST(
+          COALESCE(MAX(${creditAutoTopupSettings.usageConsecutiveFailures}), 0),
+          COALESCE(MAX(${creditAutoTopupSettings.scheduleConsecutiveFailures}), 0)
+        )`,
+        })
+            .from(creditAutoTopupSettings);
+        return result[0]?.maxFailures ?? 0;
+    }
+    async listDueScheduled(now) {
+        const rows = await this.db
+            .select()
+            .from(creditAutoTopupSettings)
+            .where(and(eq(creditAutoTopupSettings.scheduleEnabled, true), lte(creditAutoTopupSettings.scheduleNextAt, now)));
+        return rows.map(mapRow);
+    }
+}
+function mapRow(row) {
+    return {
+        tenantId: row.tenantId,
+        usageEnabled: row.usageEnabled,
+        usageThreshold: Credit.fromCents(row.usageThresholdCents),
+        usageTopup: Credit.fromCents(row.usageTopupCents),
+        usageConsecutiveFailures: row.usageConsecutiveFailures,
+        usageChargeInFlight: row.usageChargeInFlight,
+        scheduleEnabled: row.scheduleEnabled,
+        scheduleAmount: Credit.fromCents(row.scheduleAmountCents),
+        scheduleIntervalHours: row.scheduleIntervalHours,
+        scheduleNextAt: row.scheduleNextAt,
+        scheduleConsecutiveFailures: row.scheduleConsecutiveFailures,
+        createdAt: row.createdAt,
+        updatedAt: row.updatedAt,
+    };
+}

package/dist/credits/auto-topup-settings-repository.test.d.ts

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

package/dist/credits/auto-topup-settings-repository.test.js

@@ -0,0 +1,104 @@
+import { afterAll, beforeAll, beforeEach, describe, expect, it } from "vitest";
+import { beginTestTransaction, createTestDb, endTestTransaction, rollbackTestTransaction } from "../test/db.js";
+import { Credit } from "./credit.js";
+import { DrizzleAutoTopupSettingsRepository } from "./auto-topup-settings-repository.js";
+describe("DrizzleAutoTopupSettingsRepository", () => {
+    let pool;
+    let db;
+    let repo;
+    beforeAll(async () => {
+        ({ db, pool } = await createTestDb());
+        await beginTestTransaction(pool);
+    });
+    afterAll(async () => {
+        await endTestTransaction(pool);
+        await pool.close();
+    });
+    beforeEach(async () => {
+        await rollbackTestTransaction(pool);
+        repo = new DrizzleAutoTopupSettingsRepository(db);
+    });
+    it("returns null for unknown tenant", async () => {
+        expect(await repo.getByTenant("unknown")).toBeNull();
+    });
+    it("upsert creates settings and getByTenant retrieves them", async () => {
+        await repo.upsert("t1", {
+            usageEnabled: true,
+            usageThreshold: Credit.fromCents(200),
+            usageTopup: Credit.fromCents(1000),
+        });
+        const s = await repo.getByTenant("t1");
+        expect(s).not.toBeNull();
+        expect(s?.usageEnabled).toBe(true);
+        expect(s?.usageThreshold.toCents()).toBe(200);
+        expect(s?.usageTopup.toCents()).toBe(1000);
+        expect(s?.scheduleEnabled).toBe(false);
+    });
+    it("upsert updates existing settings", async () => {
+        await repo.upsert("t1", { usageEnabled: true });
+        await repo.upsert("t1", { usageThreshold: Credit.fromCents(300) });
+        const s = await repo.getByTenant("t1");
+        expect(s?.usageEnabled).toBe(true);
+        expect(s?.usageThreshold.toCents()).toBe(300);
+    });
+    it("setUsageChargeInFlight toggles the flag", async () => {
+        await repo.upsert("t1", { usageEnabled: true });
+        await repo.setUsageChargeInFlight("t1", true);
+        expect((await repo.getByTenant("t1"))?.usageChargeInFlight).toBe(true);
+        await repo.setUsageChargeInFlight("t1", false);
+        expect((await repo.getByTenant("t1"))?.usageChargeInFlight).toBe(false);
+    });
+    it("incrementUsageFailures increments and returns count", async () => {
+        await repo.upsert("t1", { usageEnabled: true });
+        expect(await repo.incrementUsageFailures("t1")).toBe(1);
+        expect(await repo.incrementUsageFailures("t1")).toBe(2);
+        expect(await repo.incrementUsageFailures("t1")).toBe(3);
+    });
+    it("resetUsageFailures resets to zero", async () => {
+        await repo.upsert("t1", { usageEnabled: true });
+        await repo.incrementUsageFailures("t1");
+        await repo.incrementUsageFailures("t1");
+        await repo.resetUsageFailures("t1");
+        expect((await repo.getByTenant("t1"))?.usageConsecutiveFailures).toBe(0);
+    });
+    it("disableUsage sets usage_enabled to false", async () => {
+        await repo.upsert("t1", { usageEnabled: true });
+        await repo.disableUsage("t1");
+        expect((await repo.getByTenant("t1"))?.usageEnabled).toBe(false);
+    });
+    it("incrementScheduleFailures increments and returns count", async () => {
+        await repo.upsert("t1", { scheduleEnabled: true });
+        expect(await repo.incrementScheduleFailures("t1")).toBe(1);
+        expect(await repo.incrementScheduleFailures("t1")).toBe(2);
+    });
+    it("disableSchedule sets schedule_enabled to false", async () => {
+        await repo.upsert("t1", { scheduleEnabled: true });
+        await repo.disableSchedule("t1");
+        expect((await repo.getByTenant("t1"))?.scheduleEnabled).toBe(false);
+    });
+    it("getMaxConsecutiveFailures returns max across usage and schedule", async () => {
+        await repo.upsert("tenant-a", { usageEnabled: true });
+        await repo.upsert("tenant-b", { usageEnabled: true });
+        await repo.incrementUsageFailures("tenant-a"); // 1
+        await repo.incrementUsageFailures("tenant-a"); // 2
+        await repo.incrementScheduleFailures("tenant-b"); // 1
+        await repo.incrementScheduleFailures("tenant-b"); // 2
+        await repo.incrementScheduleFailures("tenant-b"); // 3
+        const max = await repo.getMaxConsecutiveFailures();
+        expect(max).toBe(3);
+    });
+    it("getMaxConsecutiveFailures returns 0 when no settings exist", async () => {
+        const max = await repo.getMaxConsecutiveFailures();
+        expect(max).toBe(0);
+    });
+    it("listDueScheduled returns tenants with schedule_next_at <= now", async () => {
+        const past = "2026-02-20T00:00:00.000Z";
+        const future = "2026-12-31T00:00:00.000Z";
+        await repo.upsert("t1", { scheduleEnabled: true, scheduleAmount: Credit.fromCents(500), scheduleNextAt: past });
+        await repo.upsert("t2", { scheduleEnabled: true, scheduleAmount: Credit.fromCents(1000), scheduleNextAt: future });
+        await repo.upsert("t3", { scheduleEnabled: false, scheduleNextAt: past });
+        const due = await repo.listDueScheduled("2026-02-22T00:00:00.000Z");
+        expect(due).toHaveLength(1);
+        expect(due[0].tenantId).toBe("t1");
+    });
+});

package/dist/credits/auto-topup-usage.d.ts

@@ -0,0 +1,22 @@
+import type { Credit } from "./credit.js";
+import type { AutoTopupChargeResult } from "./auto-topup-charge.js";
+import type { IAutoTopupSettingsRepository } from "./auto-topup-settings-repository.js";
+import type { ICreditLedger } from "./credit-ledger.js";
+export interface UsageTopupDeps {
+    settingsRepo: IAutoTopupSettingsRepository;
+    creditLedger: ICreditLedger;
+    /** Injected charge function (allows mocking in tests). */
+    chargeAutoTopup: (tenantId: string, amount: Credit, source: string) => Promise<AutoTopupChargeResult>;
+    /** Optional tenant status check. If provided and returns non-null, skip the charge. */
+    checkTenantStatus?: (tenantId: string) => Promise<{
+        error: string;
+        message: string;
+    } | null>;
+}
+/**
+ * Check whether a usage-based auto-topup should fire for a tenant.
+ *
+ * Called async after every credit debit. Fire-and-forget -- caller catches errors.
+ * Idempotent: skips if a charge is already in-flight for this tenant.
+ */
+export declare function maybeTriggerUsageTopup(deps: UsageTopupDeps, tenantId: string): Promise<void>;

package/dist/credits/auto-topup-usage.js

@@ -0,0 +1,56 @@
+import { logger } from "../config/logger.js";
+import { MAX_CONSECUTIVE_FAILURES } from "./auto-topup-charge.js";
+/**
+ * Check whether a usage-based auto-topup should fire for a tenant.
+ *
+ * Called async after every credit debit. Fire-and-forget -- caller catches errors.
+ * Idempotent: skips if a charge is already in-flight for this tenant.
+ */
+export async function maybeTriggerUsageTopup(deps, tenantId) {
+    // 1. Look up settings
+    const settings = await deps.settingsRepo.getByTenant(tenantId);
+    if (!settings || !settings.usageEnabled)
+        return;
+    // 1b. Check tenant status (skip banned/suspended accounts)
+    if (deps.checkTenantStatus) {
+        const statusErr = await deps.checkTenantStatus(tenantId);
+        if (statusErr)
+            return;
+    }
+    // 2. Check balance vs threshold
+    const balance = await deps.creditLedger.balance(tenantId);
+    if (!balance.lessThan(settings.usageThreshold))
+        return;
+    // 3. Atomic in-flight guard — compare-and-swap prevents duplicate charges
+    const acquired = await deps.settingsRepo.tryAcquireUsageInFlight(tenantId);
+    if (!acquired)
+        return;
+    try {
+        // 4. Execute charge
+        const result = await deps.chargeAutoTopup(tenantId, settings.usageTopup, "auto_topup_usage");
+        if (result.success) {
+            await deps.settingsRepo.resetUsageFailures(tenantId);
+        }
+        else {
+            const failureCount = await deps.settingsRepo.incrementUsageFailures(tenantId);
+            if (failureCount >= MAX_CONSECUTIVE_FAILURES) {
+                await deps.settingsRepo.disableUsage(tenantId);
+                logger.warn("Usage auto-topup disabled after consecutive failures", { tenantId, failureCount });
+            }
+        }
+    }
+    catch (err) {
+        const failureCount = await deps.settingsRepo.incrementUsageFailures(tenantId);
+        if (failureCount >= MAX_CONSECUTIVE_FAILURES) {
+            await deps.settingsRepo.disableUsage(tenantId);
+        }
+        logger.error("Usage auto-topup unexpected error", {
+            tenantId,
+            error: err instanceof Error ? err.message : String(err),
+        });
+    }
+    finally {
+        // 6. Clear in-flight flag
+        await deps.settingsRepo.setUsageChargeInFlight(tenantId, false);
+    }
+}

package/dist/credits/auto-topup-usage.test.d.ts

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

package/dist/credits/auto-topup-usage.test.js

@@ -0,0 +1,181 @@
+import { afterAll, beforeAll, beforeEach, describe, expect, it, vi } from "vitest";
+import { createTestDb, truncateAllTables } from "../test/db.js";
+import { Credit } from "./credit.js";
+import { DrizzleAutoTopupSettingsRepository } from "./auto-topup-settings-repository.js";
+import { maybeTriggerUsageTopup } from "./auto-topup-usage.js";
+import { CreditLedger } from "./credit-ledger.js";
+describe("maybeTriggerUsageTopup", () => {
+    let pool;
+    let db;
+    let ledger;
+    let settingsRepo;
+    beforeAll(async () => {
+        ({ db, pool } = await createTestDb());
+    });
+    afterAll(async () => {
+        await pool.close();
+    });
+    beforeEach(async () => {
+        await truncateAllTables(pool);
+        ledger = new CreditLedger(db);
+        settingsRepo = new DrizzleAutoTopupSettingsRepository(db);
+    });
+    it("does nothing when tenant has no auto-topup settings", async () => {
+        const mockCharge = vi.fn();
+        const deps = { settingsRepo, creditLedger: ledger, chargeAutoTopup: mockCharge };
+        await maybeTriggerUsageTopup(deps, "t1");
+        expect(mockCharge).not.toHaveBeenCalled();
+    });
+    it("does nothing when usage_enabled is false", async () => {
+        await settingsRepo.upsert("t1", { usageEnabled: false });
+        await ledger.credit("t1", Credit.fromCents(50), "purchase", "buy", "ref-1", "stripe");
+        const mockCharge = vi.fn();
+        const deps = { settingsRepo, creditLedger: ledger, chargeAutoTopup: mockCharge };
+        await maybeTriggerUsageTopup(deps, "t1");
+        expect(mockCharge).not.toHaveBeenCalled();
+    });
+    it("does nothing when balance is above threshold", async () => {
+        await settingsRepo.upsert("t1", {
+            usageEnabled: true,
+            usageThreshold: Credit.fromCents(100),
+            usageTopup: Credit.fromCents(500),
+        });
+        await ledger.credit("t1", Credit.fromCents(200), "purchase", "buy", "ref-1", "stripe");
+        const mockCharge = vi.fn();
+        const deps = { settingsRepo, creditLedger: ledger, chargeAutoTopup: mockCharge };
+        await maybeTriggerUsageTopup(deps, "t1");
+        expect(mockCharge).not.toHaveBeenCalled();
+    });
+    it("triggers charge when balance drops below threshold", async () => {
+        await settingsRepo.upsert("t1", {
+            usageEnabled: true,
+            usageThreshold: Credit.fromCents(100),
+            usageTopup: Credit.fromCents(500),
+        });
+        await ledger.credit("t1", Credit.fromCents(50), "purchase", "buy", "ref-1", "stripe");
+        const mockCharge = vi.fn().mockResolvedValue({ success: true, paymentReference: "pi_123" });
+        const deps = { settingsRepo, creditLedger: ledger, chargeAutoTopup: mockCharge };
+        await maybeTriggerUsageTopup(deps, "t1");
+        expect(mockCharge).toHaveBeenCalledWith("t1", Credit.fromCents(500), "auto_topup_usage");
+    });
+    it("skips when charge is already in-flight", async () => {
+        await settingsRepo.upsert("t1", { usageEnabled: true, usageThreshold: Credit.fromCents(100) });
+        await settingsRepo.setUsageChargeInFlight("t1", true);
+        await ledger.credit("t1", Credit.fromCents(50), "purchase", "buy", "ref-1", "stripe");
+        const mockCharge = vi.fn();
+        const deps = { settingsRepo, creditLedger: ledger, chargeAutoTopup: mockCharge };
+        await maybeTriggerUsageTopup(deps, "t1");
+        expect(mockCharge).not.toHaveBeenCalled();
+    });
+    it("fires exactly one charge when two concurrent top-up triggers race", async () => {
+        // Setup: usage enabled, balance below threshold
+        await settingsRepo.upsert("t1", {
+            usageEnabled: true,
+            usageThreshold: Credit.fromCents(500),
+            usageTopup: Credit.fromCents(2000),
+        });
+        await ledger.credit("t1", Credit.fromCents(100), "purchase", "buy", "ref-1", "stripe");
+        const mockCharge = vi.fn().mockResolvedValue({ success: true, paymentReference: "pi_race" });
+        const deps = { settingsRepo, creditLedger: ledger, chargeAutoTopup: mockCharge };
+        // Fire two concurrent calls — both see balance < threshold,
+        // but only one wins the atomic tryAcquireUsageInFlight CAS
+        await Promise.all([maybeTriggerUsageTopup(deps, "t1"), maybeTriggerUsageTopup(deps, "t1")]);
+        // Exactly one charge — not zero, not two
+        expect(mockCharge).toHaveBeenCalledTimes(1);
+        expect(mockCharge).toHaveBeenCalledWith("t1", Credit.fromCents(2000), "auto_topup_usage");
+        // Flag should be cleared after the winner's finally block
+        const settings = await settingsRepo.getByTenant("t1");
+        expect(settings?.usageChargeInFlight).toBe(false);
+    });
+    it("clears in-flight flag after successful charge (second call triggers new charge)", async () => {
+        await settingsRepo.upsert("t1", {
+            usageEnabled: true,
+            usageThreshold: Credit.fromCents(100),
+            usageTopup: Credit.fromCents(500),
+        });
+        await ledger.credit("t1", Credit.fromCents(50), "purchase", "buy", "ref-1", "stripe");
+        const mockCharge = vi.fn().mockResolvedValue({ success: true, paymentReference: "pi_123" });
+        const deps = { settingsRepo, creditLedger: ledger, chargeAutoTopup: mockCharge };
+        // First call — triggers charge, flag set then cleared
+        await maybeTriggerUsageTopup(deps, "t1");
+        expect(mockCharge).toHaveBeenCalledTimes(1);
+        // Verify flag is cleared in the database
+        expect((await settingsRepo.getByTenant("t1"))?.usageChargeInFlight).toBe(false);
+        // Second call — if flag was cleared, this triggers another charge
+        await maybeTriggerUsageTopup(deps, "t1");
+        expect(mockCharge).toHaveBeenCalledTimes(2);
+    });
+    it("clears in-flight flag after charge throws error (second call triggers new charge)", async () => {
+        await settingsRepo.upsert("t1", {
+            usageEnabled: true,
+            usageThreshold: Credit.fromCents(100),
+            usageTopup: Credit.fromCents(500),
+        });
+        await ledger.credit("t1", Credit.fromCents(50), "purchase", "buy", "ref-1", "stripe");
+        const mockCharge = vi
+            .fn()
+            .mockRejectedValueOnce(new Error("Stripe network error"))
+            .mockResolvedValueOnce({ success: true, paymentReference: "pi_456" });
+        const deps = { settingsRepo, creditLedger: ledger, chargeAutoTopup: mockCharge };
+        // First call — charge throws, caught by catch block, finally clears flag
+        await maybeTriggerUsageTopup(deps, "t1");
+        expect(mockCharge).toHaveBeenCalledTimes(1);
+        // Verify flag is cleared in the database despite the error
+        expect((await settingsRepo.getByTenant("t1"))?.usageChargeInFlight).toBe(false);
+        // Second call — if flag was cleared, this triggers another charge
+        await maybeTriggerUsageTopup(deps, "t1");
+        expect(mockCharge).toHaveBeenCalledTimes(2);
+    });
+    it("resets failure counter on success", async () => {
+        await settingsRepo.upsert("t1", {
+            usageEnabled: true,
+            usageThreshold: Credit.fromCents(100),
+            usageTopup: Credit.fromCents(500),
+        });
+        await settingsRepo.incrementUsageFailures("t1");
+        await settingsRepo.incrementUsageFailures("t1");
+        await ledger.credit("t1", Credit.fromCents(50), "purchase", "buy", "ref-1", "stripe");
+        const mockCharge = vi.fn().mockResolvedValue({ success: true });
+        const deps = { settingsRepo, creditLedger: ledger, chargeAutoTopup: mockCharge };
+        await maybeTriggerUsageTopup(deps, "t1");
+        expect((await settingsRepo.getByTenant("t1"))?.usageConsecutiveFailures).toBe(0);
+    });
+    it("increments failure counter on charge failure", async () => {
+        await settingsRepo.upsert("t1", {
+            usageEnabled: true,
+            usageThreshold: Credit.fromCents(100),
+            usageTopup: Credit.fromCents(500),
+        });
+        await ledger.credit("t1", Credit.fromCents(50), "purchase", "buy", "ref-1", "stripe");
+        const mockCharge = vi.fn().mockResolvedValue({ success: false, error: "declined" });
+        const deps = { settingsRepo, creditLedger: ledger, chargeAutoTopup: mockCharge };
+        await maybeTriggerUsageTopup(deps, "t1");
+        expect((await settingsRepo.getByTenant("t1"))?.usageConsecutiveFailures).toBe(1);
+    });
+    it("skips charge when tenant status check returns non-null (banned/suspended)", async () => {
+        // Setup: settings exist and balance is below threshold
+        await settingsRepo.upsert("t1", {
+            usageEnabled: true,
+            usageThreshold: Credit.fromCents(1000),
+            usageTopup: Credit.fromCents(2000),
+        });
+        const chargeAutoTopup = vi.fn();
+        const checkTenantStatus = vi.fn().mockResolvedValue({ error: "account_banned", message: "banned" });
+        await maybeTriggerUsageTopup({ settingsRepo, creditLedger: ledger, chargeAutoTopup, checkTenantStatus }, "t1");
+        expect(chargeAutoTopup).not.toHaveBeenCalled();
+    });
+    it("disables usage auto-topup after 3 consecutive failures", async () => {
+        await settingsRepo.upsert("t1", {
+            usageEnabled: true,
+            usageThreshold: Credit.fromCents(100),
+            usageTopup: Credit.fromCents(500),
+        });
+        await settingsRepo.incrementUsageFailures("t1");
+        await settingsRepo.incrementUsageFailures("t1");
+        await ledger.credit("t1", Credit.fromCents(50), "purchase", "buy", "ref-1", "stripe");
+        const mockCharge = vi.fn().mockResolvedValue({ success: false, error: "declined" });
+        const deps = { settingsRepo, creditLedger: ledger, chargeAutoTopup: mockCharge };
+        await maybeTriggerUsageTopup(deps, "t1");
+        expect((await settingsRepo.getByTenant("t1"))?.usageEnabled).toBe(false);
+    });
+});

package/dist/credits/credit-expiry-cron.d.ts

@@ -0,0 +1,19 @@
+import type { ICreditLedger } from "./credit-ledger.js";
+export interface CreditExpiryCronConfig {
+    ledger: ICreditLedger;
+    /** Current time as ISO-8601 string. */
+    now: string;
+}
+export interface CreditExpiryCronResult {
+    processed: number;
+    expired: string[];
+    errors: string[];
+    skippedZeroBalance: number;
+}
+/**
+ * Sweep expired credit grants and debit the original grant amount
+ * (or remaining balance if partially consumed).
+ *
+ * Idempotent: uses `expiry:<original_txn_id>` as referenceId.
+ */
+export declare function runCreditExpiryCron(cfg: CreditExpiryCronConfig): Promise<CreditExpiryCronResult>;

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

@@ -0,0 +1,50 @@
+import { logger } from "../config/logger.js";
+import { InsufficientBalanceError } from "./credit-ledger.js";
+/**
+ * Sweep expired credit grants and debit the original grant amount
+ * (or remaining balance if partially consumed).
+ *
+ * Idempotent: uses `expiry:<original_txn_id>` as referenceId.
+ */
+export async function runCreditExpiryCron(cfg) {
+    const result = {
+        processed: 0,
+        expired: [],
+        errors: [],
+        skippedZeroBalance: 0,
+    };
+    const expiredGrants = await cfg.ledger.expiredCredits(cfg.now);
+    for (const grant of expiredGrants) {
+        try {
+            const balance = await cfg.ledger.balance(grant.tenantId);
+            if (balance.isZero()) {
+                result.skippedZeroBalance++;
+                continue;
+            }
+            // Debit the lesser of the original grant amount or current balance
+            const debitAmount = balance.lessThan(grant.amount) ? balance : grant.amount;
+            await cfg.ledger.debit(grant.tenantId, debitAmount, "credit_expiry", `Expired credit grant reclaimed: ${grant.id}`, `expiry:${grant.id}`);
+            result.processed++;
+            if (!result.expired.includes(grant.tenantId)) {
+                result.expired.push(grant.tenantId);
+            }
+        }
+        catch (err) {
+            if (err instanceof InsufficientBalanceError) {
+                result.skippedZeroBalance++;
+            }
+            else {
+                const msg = err instanceof Error ? err.message : String(err);
+                logger.error("Credit expiry failed", { tenantId: grant.tenantId, txnId: grant.id, error: msg });
+                result.errors.push(`${grant.tenantId}:${grant.id}: ${msg}`);
+            }
+        }
+    }
+    if (result.processed > 0) {
+        logger.info(`Credit expiry cron: reclaimed ${result.processed} expired grants`, {
+            expired: result.expired,
+            skippedZeroBalance: result.skippedZeroBalance,
+        });
+    }
+    return result;
+}

package/dist/credits/credit-expiry-cron.test.d.ts

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