@wopr-network/platform-core 1.0.10 → 1.1.0

package/dist/monetization/credits/auto-topup-schedule.test.js

@@ -0,0 +1,144 @@
+import { Credit, DrizzleAutoTopupSettingsRepository } from "@wopr-network/platform-core/credits";
+import { afterAll, beforeAll, beforeEach, describe, expect, it, vi } from "vitest";
+import { beginTestTransaction, createTestDb, endTestTransaction, rollbackTestTransaction } from "../../test/db.js";
+import { runScheduledTopups } from "./auto-topup-schedule.js";
+describe("runScheduledTopups", () => {
+    let pool;
+    let db;
+    let settingsRepo;
+    beforeAll(async () => {
+        ({ db, pool } = await createTestDb());
+        await beginTestTransaction(pool);
+    });
+    afterAll(async () => {
+        await endTestTransaction(pool);
+        await pool.close();
+    });
+    beforeEach(async () => {
+        await rollbackTestTransaction(pool);
+        settingsRepo = new DrizzleAutoTopupSettingsRepository(db);
+    });
+    it("processes no tenants when none are due", async () => {
+        const mockCharge = vi.fn();
+        const deps = { settingsRepo, chargeAutoTopup: mockCharge };
+        const result = await runScheduledTopups(deps);
+        expect(result.processed).toBe(0);
+        expect(result.succeeded).toHaveLength(0);
+        expect(result.failed).toHaveLength(0);
+        expect(mockCharge).not.toHaveBeenCalled();
+    });
+    it("charges tenant whose schedule_next_at is in the past", async () => {
+        const past = "2026-02-20T00:00:00.000Z";
+        await settingsRepo.upsert("t1", {
+            scheduleEnabled: true,
+            scheduleAmount: Credit.fromCents(1000),
+            scheduleNextAt: past,
+        });
+        const mockCharge = vi.fn().mockResolvedValue({ success: true, paymentReference: "pi_abc" });
+        const deps = { settingsRepo, chargeAutoTopup: mockCharge };
+        const result = await runScheduledTopups(deps);
+        expect(result.processed).toBe(1);
+        expect(result.succeeded).toEqual(["t1"]);
+        expect(mockCharge).toHaveBeenCalledWith("t1", Credit.fromCents(1000), "auto_topup_schedule");
+    });
+    it("resets failure counter on success", async () => {
+        const past = "2026-02-20T00:00:00.000Z";
+        await settingsRepo.upsert("t1", {
+            scheduleEnabled: true,
+            scheduleAmount: Credit.fromCents(500),
+            scheduleNextAt: past,
+        });
+        await settingsRepo.incrementScheduleFailures("t1");
+        await settingsRepo.incrementScheduleFailures("t1");
+        const mockCharge = vi.fn().mockResolvedValue({ success: true });
+        const deps = { settingsRepo, chargeAutoTopup: mockCharge };
+        await runScheduledTopups(deps);
+        expect((await settingsRepo.getByTenant("t1"))?.scheduleConsecutiveFailures).toBe(0);
+    });
+    it("advances scheduleNextAt after successful charge", async () => {
+        const past = "2026-02-20T00:00:00.000Z";
+        await settingsRepo.upsert("t1", {
+            scheduleEnabled: true,
+            scheduleAmount: Credit.fromCents(1000),
+            scheduleIntervalHours: 24,
+            scheduleNextAt: past,
+        });
+        const before = (await settingsRepo.getByTenant("t1"))?.scheduleNextAt;
+        const mockCharge = vi.fn().mockResolvedValue({ success: true, paymentReference: "pi_ok" });
+        const deps = { settingsRepo, chargeAutoTopup: mockCharge };
+        await runScheduledTopups(deps);
+        const after = (await settingsRepo.getByTenant("t1"))?.scheduleNextAt;
+        expect(new Date(after ?? "").getTime()).toBeGreaterThan(new Date(before ?? "").getTime());
+    });
+    it("advances scheduleNextAt after charge throws an error", async () => {
+        const past = "2026-02-20T00:00:00.000Z";
+        await settingsRepo.upsert("t1", {
+            scheduleEnabled: true,
+            scheduleAmount: Credit.fromCents(1000),
+            scheduleIntervalHours: 24,
+            scheduleNextAt: past,
+        });
+        const before = (await settingsRepo.getByTenant("t1"))?.scheduleNextAt;
+        const mockCharge = vi.fn().mockRejectedValue(new Error("Stripe network error"));
+        const deps = { settingsRepo, chargeAutoTopup: mockCharge };
+        await runScheduledTopups(deps);
+        const after = (await settingsRepo.getByTenant("t1"))?.scheduleNextAt;
+        expect(new Date(after ?? "").getTime()).toBeGreaterThan(new Date(before ?? "").getTime());
+    });
+    it("disables schedule after 3 consecutive failures", async () => {
+        const past = "2026-02-20T00:00:00.000Z";
+        await settingsRepo.upsert("t1", {
+            scheduleEnabled: true,
+            scheduleAmount: Credit.fromCents(500),
+            scheduleNextAt: past,
+        });
+        await settingsRepo.incrementScheduleFailures("t1");
+        await settingsRepo.incrementScheduleFailures("t1");
+        const mockCharge = vi.fn().mockResolvedValue({ success: false, error: "declined" });
+        const deps = { settingsRepo, chargeAutoTopup: mockCharge };
+        await runScheduledTopups(deps);
+        expect((await settingsRepo.getByTenant("t1"))?.scheduleEnabled).toBe(false);
+    });
+    it("skips tenants where checkTenantStatus returns non-null", async () => {
+        // Setup: one due tenant that is banned
+        await settingsRepo.upsert("t-banned", {
+            scheduleEnabled: true,
+            scheduleAmount: Credit.fromCents(1000),
+            scheduleIntervalHours: 24,
+            scheduleNextAt: new Date(Date.now() - 60_000).toISOString(),
+        });
+        const chargeAutoTopup = vi.fn();
+        const checkTenantStatus = vi.fn().mockResolvedValue({ error: "account_banned", message: "banned" });
+        const result = await runScheduledTopups({
+            settingsRepo,
+            chargeAutoTopup,
+            checkTenantStatus,
+        });
+        expect(chargeAutoTopup).not.toHaveBeenCalled();
+        // The tenant should still be processed (counter incremented) but skipped
+        expect(result.processed).toBe(1);
+        expect(result.failed).toContain("t-banned");
+    });
+    it("processes multiple tenants independently", async () => {
+        const past = "2026-02-20T00:00:00.000Z";
+        await settingsRepo.upsert("t1", {
+            scheduleEnabled: true,
+            scheduleAmount: Credit.fromCents(500),
+            scheduleNextAt: past,
+        });
+        await settingsRepo.upsert("t2", {
+            scheduleEnabled: true,
+            scheduleAmount: Credit.fromCents(1000),
+            scheduleNextAt: past,
+        });
+        const mockCharge = vi
+            .fn()
+            .mockResolvedValueOnce({ success: true })
+            .mockResolvedValueOnce({ success: false, error: "declined" });
+        const deps = { settingsRepo, chargeAutoTopup: mockCharge };
+        const result = await runScheduledTopups(deps);
+        expect(result.processed).toBe(2);
+        expect(result.succeeded).toContain("t1");
+        expect(result.failed).toContain("t2");
+    });
+});

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

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

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

@@ -0,0 +1,103 @@
+import { Credit, DrizzleAutoTopupSettingsRepository } from "@wopr-network/platform-core/credits";
+import { afterAll, beforeAll, beforeEach, describe, expect, it } from "vitest";
+import { beginTestTransaction, createTestDb, endTestTransaction, rollbackTestTransaction } from "../../test/db.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/monetization/credits/auto-topup-usage.d.ts

@@ -0,0 +1,20 @@
+import type { Credit, IAutoTopupSettingsRepository, ICreditLedger } from "@wopr-network/platform-core/credits";
+import type { AutoTopupChargeResult } from "./auto-topup-charge.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/monetization/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/monetization/credits/auto-topup-usage.test.d.ts

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

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

@@ -0,0 +1,179 @@
+import { Credit, CreditLedger, DrizzleAutoTopupSettingsRepository } from "@wopr-network/platform-core/credits";
+import { afterAll, beforeAll, beforeEach, describe, expect, it, vi } from "vitest";
+import { createTestDb, truncateAllTables } from "../../test/db.js";
+import { maybeTriggerUsageTopup } from "./auto-topup-usage.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/monetization/credits/bot-billing.d.ts

@@ -0,0 +1,83 @@
+import type { ICreditLedger } from "@wopr-network/platform-core/credits";
+import { Credit } from "@wopr-network/platform-core/credits";
+import type { IBotInstanceRepository } from "../../fleet/bot-instance-repository.js";
+import type { INodeCommandBus } from "../../fleet/node-command-bus.js";
+/** Billing state literals */
+export type BillingState = "active" | "suspended" | "destroyed";
+/** Number of days before a suspended bot is destroyed. */
+export declare const SUSPENSION_GRACE_DAYS = 30;
+export interface IBotBilling {
+    getActiveBotCount(tenantId: string): Promise<number>;
+    suspendBot(botId: string): Promise<void>;
+    suspendAllForTenant(tenantId: string): Promise<string[]>;
+    reactivateBot(botId: string): Promise<void>;
+    checkReactivation(tenantId: string, ledger: ICreditLedger): Promise<string[]>;
+    destroyBot(botId: string): Promise<void>;
+    destroyExpiredBots(): Promise<string[]>;
+    getBotBilling(botId: string): Promise<unknown>;
+    listForTenant(tenantId: string): Promise<unknown[]>;
+    registerBot(botId: string, tenantId: string, name: string): Promise<void>;
+    getStorageTier(botId: string): Promise<string | null>;
+    setStorageTier(botId: string, tier: string): Promise<void>;
+    getStorageTierCostsForTenant(tenantId: string): Promise<Credit>;
+}
+/**
+ * Bot billing lifecycle manager.
+ *
+ * Handles suspend/reactivate/destroy transitions and provides
+ * active-bot-count queries for the daily runtime cron.
+ */
+export declare class DrizzleBotBilling implements IBotBilling {
+    private readonly botInstanceRepo;
+    private readonly commandBus?;
+    constructor(botInstanceRepo: IBotInstanceRepository, commandBus?: (INodeCommandBus | null) | undefined);
+    /** Send a command to the bot's node. Logs but never throws on failure. */
+    private sendCommand;
+    /** Count active bots for a tenant (used by runtime cron). */
+    getActiveBotCount(tenantId: string): Promise<number>;
+    /**
+     * Suspend a bot: stop billing, set destroy timer.
+     * Sets billingState='suspended', suspendedAt=now, destroyAfter=now+30 days.
+     */
+    suspendBot(botId: string): Promise<void>;
+    /**
+     * Suspend ALL active bots for a tenant.
+     * Returns the IDs of suspended bots.
+     */
+    suspendAllForTenant(tenantId: string): Promise<string[]>;
+    /**
+     * Reactivate a suspended bot: clear suspension, resume billing.
+     * Sets billingState='active', clears suspendedAt and destroyAfter.
+     */
+    reactivateBot(botId: string): Promise<void>;
+    /**
+     * Check if a tenant has suspended bots and reactivate them if balance > 0.
+     * Called after credit purchase (Stripe webhook).
+     *
+     * @returns IDs of reactivated bots.
+     */
+    checkReactivation(tenantId: string, ledger: ICreditLedger): Promise<string[]>;
+    /**
+     * Mark a bot as destroyed.
+     * Sets billingState='destroyed'. Actual Docker cleanup is handled by the caller.
+     */
+    destroyBot(botId: string): Promise<void>;
+    /**
+     * Find and mark as destroyed all bots whose suspension grace period has expired.
+     * Returns IDs of destroyed bots (caller handles Docker rm).
+     */
+    destroyExpiredBots(): Promise<string[]>;
+    /** Get billing info for a single bot. */
+    getBotBilling(botId: string): Promise<unknown>;
+    /** List all bots for a tenant (any billing state). */
+    listForTenant(tenantId: string): Promise<unknown[]>;
+    /** Get storage tier key for a bot. Returns null if bot doesn't exist. */
+    getStorageTier(botId: string): Promise<string | null>;
+    /** Set storage tier for a bot. */
+    setStorageTier(botId: string, tier: string): Promise<void>;
+    /** Sum daily storage tier costs for all active bots for a tenant. */
+    getStorageTierCostsForTenant(tenantId: string): Promise<Credit>;
+    /** Register a new bot instance for billing. */
+    registerBot(botId: string, tenantId: string, name: string): Promise<void>;
+}
+export { DrizzleBotBilling as BotBilling };