@wopr-network/platform-core 0.1.0

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

@@ -0,0 +1,242 @@
+import crypto from "node:crypto";
+import Stripe from "stripe";
+import { afterAll, beforeAll, beforeEach, describe, expect, it, vi } from "vitest";
+import { creditAutoTopup } from "../db/schema/credit-auto-topup.js";
+import { createTestDb, truncateAllTables } from "../test/db.js";
+import { Credit } from "./credit.js";
+import { chargeAutoTopup, MAX_CONSECUTIVE_FAILURES } from "./auto-topup-charge.js";
+import { DrizzleAutoTopupEventLogRepository } from "./auto-topup-event-log-repository.js";
+import { CreditLedger } from "./credit-ledger.js";
+function mockStripe(overrides) {
+    const piId = overrides?.paymentIntentId ?? `pi_${crypto.randomUUID()}`;
+    return {
+        paymentIntents: {
+            create: vi.fn().mockImplementation(async () => {
+                if (overrides?.shouldFail) {
+                    if (overrides.failWithStripeError !== false) {
+                        throw new Stripe.errors.StripeCardError({
+                            message: overrides.failMessage ?? "card_declined",
+                            type: "card_error",
+                            code: overrides.failMessage ?? "card_declined",
+                        });
+                    }
+                    throw new Error(overrides.failMessage ?? "card_declined");
+                }
+                return { id: piId, status: "succeeded" };
+            }),
+        },
+        customers: {
+            listPaymentMethods: vi.fn().mockResolvedValue({ data: [{ id: "pm_123" }] }),
+        },
+    };
+}
+function mockTenantStore(stripeCustomerId = "cus_123") {
+    return {
+        getByTenant: vi.fn().mockResolvedValue({ tenant: "t1", processor_customer_id: stripeCustomerId }),
+    };
+}
+describe("chargeAutoTopup", () => {
+    let pool;
+    let db;
+    let ledger;
+    beforeAll(async () => {
+        ({ db, pool } = await createTestDb());
+    });
+    afterAll(async () => {
+        await pool.close();
+    });
+    beforeEach(async () => {
+        await truncateAllTables(pool);
+        ledger = new CreditLedger(db);
+    });
+    it("charges Stripe and credits ledger on success", async () => {
+        const stripe = mockStripe();
+        const tenantRepo = mockTenantStore();
+        const deps = {
+            stripe: stripe,
+            tenantRepo: tenantRepo,
+            creditLedger: ledger,
+            eventLogRepo: new DrizzleAutoTopupEventLogRepository(db),
+        };
+        const result = await chargeAutoTopup(deps, "t1", Credit.fromCents(500), "auto_topup_usage");
+        expect(result.success).toBe(true);
+        expect(result.paymentReference).toEqual(expect.any(String));
+        expect((await ledger.balance("t1")).toCents()).toBe(500);
+        const history = await ledger.history("t1");
+        expect(history[0].type).toBe("purchase");
+        expect(history[0].fundingSource).toBe("stripe");
+    });
+    it("writes success event to credit_auto_topup log", async () => {
+        const stripe = mockStripe();
+        const tenantRepo = mockTenantStore();
+        const deps = {
+            stripe: stripe,
+            tenantRepo: tenantRepo,
+            creditLedger: ledger,
+            eventLogRepo: new DrizzleAutoTopupEventLogRepository(db),
+        };
+        await chargeAutoTopup(deps, "t1", Credit.fromCents(500), "auto_topup_usage");
+        const events = await db
+            .select()
+            .from(creditAutoTopup)
+            .where((await import("drizzle-orm")).eq(creditAutoTopup.tenantId, "t1"));
+        expect(events).toHaveLength(1);
+        expect(events[0].status).toBe("success");
+        expect(events[0].amountCents).toBe(500);
+    });
+    it("returns failure result and writes failure event on Stripe error", async () => {
+        const stripe = mockStripe({ shouldFail: true, failMessage: "card_declined" });
+        const tenantRepo = mockTenantStore();
+        const deps = {
+            stripe: stripe,
+            tenantRepo: tenantRepo,
+            creditLedger: ledger,
+            eventLogRepo: new DrizzleAutoTopupEventLogRepository(db),
+        };
+        const result = await chargeAutoTopup(deps, "t1", Credit.fromCents(500), "auto_topup_usage");
+        expect(result.success).toBe(false);
+        expect(result.error).toContain("Card declined");
+        expect(result.error).toContain("card_declined");
+        expect((await ledger.balance("t1")).toCents()).toBe(0);
+        const events = await db
+            .select()
+            .from(creditAutoTopup)
+            .where((await import("drizzle-orm")).eq(creditAutoTopup.tenantId, "t1"));
+        expect(events).toHaveLength(1);
+        expect(events[0].status).toBe("failed");
+    });
+    it("returns failure when tenant has no Stripe customer", async () => {
+        const stripe = mockStripe();
+        const tenantRepo = { getByTenant: vi.fn().mockResolvedValue(null) };
+        const deps = {
+            stripe: stripe,
+            tenantRepo: tenantRepo,
+            creditLedger: ledger,
+            eventLogRepo: new DrizzleAutoTopupEventLogRepository(db),
+        };
+        const result = await chargeAutoTopup(deps, "t1", Credit.fromCents(500), "auto_topup_usage");
+        expect(result.success).toBe(false);
+        expect(result.error).toContain("No Stripe customer");
+    });
+    it("returns failure when tenant has no payment methods", async () => {
+        const stripe = mockStripe();
+        stripe.customers.listPaymentMethods = vi.fn().mockResolvedValue({ data: [] });
+        const tenantRepo = mockTenantStore();
+        const deps = {
+            stripe: stripe,
+            tenantRepo: tenantRepo,
+            creditLedger: ledger,
+            eventLogRepo: new DrizzleAutoTopupEventLogRepository(db),
+        };
+        const result = await chargeAutoTopup(deps, "t1", Credit.fromCents(500), "auto_topup_usage");
+        expect(result.success).toBe(false);
+        expect(result.error).toContain("No payment method");
+    });
+    it("is idempotent -- referenceId already credited means hasReferenceId returns true", async () => {
+        const piId = `pi_${crypto.randomUUID()}`;
+        const stripe = mockStripe({ paymentIntentId: piId });
+        const tenantRepo = mockTenantStore();
+        const deps = {
+            stripe: stripe,
+            tenantRepo: tenantRepo,
+            creditLedger: ledger,
+            eventLogRepo: new DrizzleAutoTopupEventLogRepository(db),
+        };
+        await chargeAutoTopup(deps, "t1", Credit.fromCents(500), "auto_topup_usage");
+        expect((await ledger.balance("t1")).toCents()).toBe(500);
+        expect(await ledger.hasReferenceId(piId)).toBe(true);
+    });
+    it("exports MAX_CONSECUTIVE_FAILURES as 3", () => {
+        expect(MAX_CONSECUTIVE_FAILURES).toBe(3);
+    });
+    it("logs structured card-decline info when Stripe throws StripeCardError on payment", async () => {
+        const cardError = new Stripe.errors.StripeCardError({
+            message: "Your card was declined.",
+            type: "card_error",
+            code: "card_declined",
+            decline_code: "insufficient_funds",
+        });
+        const stripe = mockStripe();
+        stripe.paymentIntents.create = vi.fn().mockRejectedValue(cardError);
+        const tenantRepo = mockTenantStore();
+        const deps = {
+            stripe: stripe,
+            tenantRepo: tenantRepo,
+            creditLedger: ledger,
+            eventLogRepo: new DrizzleAutoTopupEventLogRepository(db),
+        };
+        const result = await chargeAutoTopup(deps, "t1", Credit.fromCents(500), "auto_topup_usage");
+        expect(result.success).toBe(false);
+        expect(result.error).toContain("Card declined");
+        expect(result.error).toContain("card_declined");
+    });
+    it("logs structured Stripe error info when Stripe throws StripeAPIError on payment", async () => {
+        const apiError = new Stripe.errors.StripeAPIError({
+            message: "Internal Stripe error",
+            type: "api_error",
+        });
+        const stripe = mockStripe();
+        stripe.paymentIntents.create = vi.fn().mockRejectedValue(apiError);
+        const tenantRepo = mockTenantStore();
+        const deps = {
+            stripe: stripe,
+            tenantRepo: tenantRepo,
+            creditLedger: ledger,
+            eventLogRepo: new DrizzleAutoTopupEventLogRepository(db),
+        };
+        const result = await chargeAutoTopup(deps, "t1", Credit.fromCents(500), "auto_topup_usage");
+        expect(result.success).toBe(false);
+        expect(result.error).toContain("Stripe error");
+    });
+    it("re-throws non-Stripe errors from paymentIntents.create", async () => {
+        const stripe = mockStripe();
+        stripe.paymentIntents.create = vi.fn().mockRejectedValue(new TypeError("Cannot read properties of undefined"));
+        const tenantRepo = mockTenantStore();
+        const deps = {
+            stripe: stripe,
+            tenantRepo: tenantRepo,
+            creditLedger: ledger,
+            eventLogRepo: new DrizzleAutoTopupEventLogRepository(db),
+        };
+        await expect(chargeAutoTopup(deps, "t1", Credit.fromCents(500), "auto_topup_usage")).rejects.toThrow(TypeError);
+    });
+    it("returns structured error when StripeCardError thrown by listPaymentMethods", async () => {
+        const cardError = new Stripe.errors.StripeCardError({
+            message: "Card error on list",
+            type: "card_error",
+            code: "card_declined",
+        });
+        const stripe = mockStripe();
+        stripe.customers.listPaymentMethods = vi.fn().mockRejectedValue(cardError);
+        const tenantRepo = mockTenantStore();
+        const deps = {
+            stripe: stripe,
+            tenantRepo: tenantRepo,
+            creditLedger: ledger,
+            eventLogRepo: new DrizzleAutoTopupEventLogRepository(db),
+        };
+        const result = await chargeAutoTopup(deps, "t1", Credit.fromCents(500), "auto_topup_usage");
+        expect(result.success).toBe(false);
+        expect(result.error).toContain("Card declined");
+    });
+    it("propagates error with PaymentIntent ID when credit grant fails after Stripe charge", async () => {
+        const piId = "pi_ledger_fail_test";
+        const stripe = mockStripe({ paymentIntentId: piId });
+        const tenantRepo = mockTenantStore();
+        const deps = {
+            stripe: stripe,
+            tenantRepo: tenantRepo,
+            creditLedger: ledger,
+            eventLogRepo: new DrizzleAutoTopupEventLogRepository(db),
+        };
+        // Make credit() fail after Stripe succeeds
+        vi.spyOn(ledger, "credit").mockRejectedValueOnce(new Error("DB connection lost"));
+        // Error propagates and contains the PI ID for manual reconciliation
+        await expect(chargeAutoTopup(deps, "t1", Credit.fromCents(500), "auto_topup_usage")).rejects.toThrow(piId);
+        // Also verify the original error message is preserved
+        vi.spyOn(ledger, "credit").mockRejectedValueOnce(new Error("DB connection lost"));
+        await expect(chargeAutoTopup(deps, "t1", Credit.fromCents(500), "auto_topup_usage")).rejects.toThrow("DB connection lost");
+        // No credits were silently granted
+        expect((await ledger.balance("t1")).toCents()).toBe(0);
+    });
+});

package/dist/credits/auto-topup-event-log-repository.d.ts

@@ -0,0 +1,16 @@
+import type { PlatformDb } from "../db/index.js";
+export interface AutoTopupEventLogEntry {
+    tenantId: string;
+    amountCents: number;
+    status: "success" | "failed";
+    failureReason?: string | null;
+    paymentReference?: string | null;
+}
+export interface IAutoTopupEventLogRepository {
+    writeEvent(entry: AutoTopupEventLogEntry): Promise<void>;
+}
+export declare class DrizzleAutoTopupEventLogRepository implements IAutoTopupEventLogRepository {
+    private readonly db;
+    constructor(db: PlatformDb);
+    writeEvent(entry: AutoTopupEventLogEntry): Promise<void>;
+}

package/dist/credits/auto-topup-event-log-repository.js

@@ -0,0 +1,18 @@
+import crypto from "node:crypto";
+import { creditAutoTopup } from "../db/schema/credit-auto-topup.js";
+export class DrizzleAutoTopupEventLogRepository {
+    db;
+    constructor(db) {
+        this.db = db;
+    }
+    async writeEvent(entry) {
+        await this.db.insert(creditAutoTopup).values({
+            id: crypto.randomUUID(),
+            tenantId: entry.tenantId,
+            amountCents: entry.amountCents,
+            status: entry.status,
+            failureReason: entry.failureReason ?? null,
+            paymentReference: entry.paymentReference ?? null,
+        });
+    }
+}

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

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

package/dist/credits/auto-topup-event-log-repository.test.js

@@ -0,0 +1,83 @@
+import { eq } from "drizzle-orm";
+import { afterAll, beforeAll, beforeEach, describe, expect, it } from "vitest";
+import { creditAutoTopup } from "../db/schema/credit-auto-topup.js";
+import { beginTestTransaction, createTestDb, endTestTransaction, rollbackTestTransaction } from "../test/db.js";
+import { DrizzleAutoTopupEventLogRepository } from "./auto-topup-event-log-repository.js";
+describe("DrizzleAutoTopupEventLogRepository", () => {
+    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 DrizzleAutoTopupEventLogRepository(db);
+    });
+    it("writes a success event with all fields", async () => {
+        await repo.writeEvent({
+            tenantId: "t1",
+            amountCents: 500,
+            status: "success",
+            failureReason: null,
+            paymentReference: "pi_abc123",
+        });
+        const rows = await db.select().from(creditAutoTopup).where(eq(creditAutoTopup.tenantId, "t1"));
+        expect(rows).toHaveLength(1);
+        expect(rows[0].tenantId).toBe("t1");
+        expect(rows[0].amountCents).toBe(500);
+        expect(rows[0].status).toBe("success");
+        expect(rows[0].failureReason).toBeNull();
+        expect(rows[0].paymentReference).toBe("pi_abc123");
+        expect(rows[0].id).toMatch(/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/);
+        expect(rows[0].createdAt).toMatch(/^\d{4}-\d{2}-\d{2}[T ]\d{2}:\d{2}:\d{2}/);
+    });
+    it("writes a failed event with failure reason", async () => {
+        await repo.writeEvent({
+            tenantId: "t1",
+            amountCents: 1000,
+            status: "failed",
+            failureReason: "card_declined",
+            paymentReference: null,
+        });
+        const rows = await db.select().from(creditAutoTopup).where(eq(creditAutoTopup.tenantId, "t1"));
+        expect(rows).toHaveLength(1);
+        expect(rows[0].status).toBe("failed");
+        expect(rows[0].failureReason).toBe("card_declined");
+        expect(rows[0].paymentReference).toBeNull();
+    });
+    it("defaults optional fields to null when omitted", async () => {
+        await repo.writeEvent({
+            tenantId: "t1",
+            amountCents: 200,
+            status: "success",
+        });
+        const rows = await db.select().from(creditAutoTopup).where(eq(creditAutoTopup.tenantId, "t1"));
+        expect(rows).toHaveLength(1);
+        expect(rows[0].failureReason).toBeNull();
+        expect(rows[0].paymentReference).toBeNull();
+    });
+    it("generates unique ids for each event", async () => {
+        await repo.writeEvent({ tenantId: "t1", amountCents: 100, status: "success" });
+        await repo.writeEvent({ tenantId: "t1", amountCents: 200, status: "success" });
+        const rows = await db.select().from(creditAutoTopup).where(eq(creditAutoTopup.tenantId, "t1"));
+        expect(rows).toHaveLength(2);
+        expect(rows[0].id).not.toBe(rows[1].id);
+    });
+    it("isolates events by tenant", async () => {
+        await repo.writeEvent({ tenantId: "t1", amountCents: 100, status: "success" });
+        await repo.writeEvent({ tenantId: "t2", amountCents: 200, status: "failed", failureReason: "insufficient_funds" });
+        const t1Rows = await db.select().from(creditAutoTopup).where(eq(creditAutoTopup.tenantId, "t1"));
+        const t2Rows = await db.select().from(creditAutoTopup).where(eq(creditAutoTopup.tenantId, "t2"));
+        expect(t1Rows).toHaveLength(1);
+        expect(t1Rows[0].amountCents).toBe(100);
+        expect(t2Rows).toHaveLength(1);
+        expect(t2Rows[0].amountCents).toBe(200);
+        expect(t2Rows[0].failureReason).toBe("insufficient_funds");
+    });
+});

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

@@ -0,0 +1,27 @@
+import type { Credit } from "./credit.js";
+import type { AutoTopupChargeResult } from "./auto-topup-charge.js";
+import type { IAutoTopupSettingsRepository } from "./auto-topup-settings-repository.js";
+export interface ScheduleTopupDeps {
+    settingsRepo: IAutoTopupSettingsRepository;
+    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>;
+}
+export interface ScheduleTopupResult {
+    processed: number;
+    succeeded: string[];
+    failed: string[];
+    errors: string[];
+}
+/**
+ * Run scheduled auto-topup charges for all due tenants.
+ *
+ * Called by an hourly cron job. For each tenant with schedule_next_at <= now:
+ * 1. Charge Stripe
+ * 2. Advance schedule_next_at by interval_hours (even on failure)
+ * 3. Track failures and disable after MAX_CONSECUTIVE_FAILURES
+ */
+export declare function runScheduledTopups(deps: ScheduleTopupDeps): Promise<ScheduleTopupResult>;

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

@@ -0,0 +1,66 @@
+import { logger } from "../config/logger.js";
+import { MAX_CONSECUTIVE_FAILURES } from "./auto-topup-charge.js";
+/**
+ * Run scheduled auto-topup charges for all due tenants.
+ *
+ * Called by an hourly cron job. For each tenant with schedule_next_at <= now:
+ * 1. Charge Stripe
+ * 2. Advance schedule_next_at by interval_hours (even on failure)
+ * 3. Track failures and disable after MAX_CONSECUTIVE_FAILURES
+ */
+export async function runScheduledTopups(deps) {
+    const now = new Date().toISOString();
+    const due = await deps.settingsRepo.listDueScheduled(now);
+    const result = {
+        processed: 0,
+        succeeded: [],
+        failed: [],
+        errors: [],
+    };
+    for (const settings of due) {
+        result.processed++;
+        // Skip banned/suspended tenants
+        if (deps.checkTenantStatus) {
+            const statusErr = await deps.checkTenantStatus(settings.tenantId);
+            if (statusErr) {
+                // Still advance schedule to prevent hammer-retry on reactivation
+                await deps.settingsRepo.advanceScheduleNextAt(settings.tenantId);
+                result.failed.push(settings.tenantId);
+                continue;
+            }
+        }
+        try {
+            const chargeResult = await deps.chargeAutoTopup(settings.tenantId, settings.scheduleAmount, "auto_topup_schedule");
+            // Always advance schedule_next_at (even on failure, to prevent hammer-retry)
+            await deps.settingsRepo.advanceScheduleNextAt(settings.tenantId);
+            if (chargeResult.success) {
+                await deps.settingsRepo.resetScheduleFailures(settings.tenantId);
+                result.succeeded.push(settings.tenantId);
+            }
+            else {
+                const failureCount = await deps.settingsRepo.incrementScheduleFailures(settings.tenantId);
+                if (failureCount >= MAX_CONSECUTIVE_FAILURES) {
+                    await deps.settingsRepo.disableSchedule(settings.tenantId);
+                    logger.warn("Schedule auto-topup disabled after consecutive failures", {
+                        tenantId: settings.tenantId,
+                        failureCount,
+                    });
+                }
+                result.failed.push(settings.tenantId);
+            }
+        }
+        catch (err) {
+            // Advance even on unexpected error
+            await deps.settingsRepo.advanceScheduleNextAt(settings.tenantId);
+            const failureCount = await deps.settingsRepo.incrementScheduleFailures(settings.tenantId);
+            if (failureCount >= MAX_CONSECUTIVE_FAILURES) {
+                await deps.settingsRepo.disableSchedule(settings.tenantId);
+            }
+            const msg = err instanceof Error ? err.message : String(err);
+            logger.error("Schedule auto-topup unexpected error", { tenantId: settings.tenantId, error: msg });
+            result.errors.push(`${settings.tenantId}: ${msg}`);
+            result.failed.push(settings.tenantId);
+        }
+    }
+    return result;
+}

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

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

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

@@ -0,0 +1,145 @@
+import { afterAll, beforeAll, beforeEach, describe, expect, it, vi } from "vitest";
+import { beginTestTransaction, createTestDb, endTestTransaction, rollbackTestTransaction } from "../test/db.js";
+import { Credit } from "./credit.js";
+import { runScheduledTopups } from "./auto-topup-schedule.js";
+import { DrizzleAutoTopupSettingsRepository } from "./auto-topup-settings-repository.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/credits/auto-topup-settings-repository.d.ts

@@ -0,0 +1,54 @@
+import type { PlatformDb } from "../db/index.js";
+import { Credit } from "./credit.js";
+export declare const ALLOWED_TOPUP_AMOUNTS: readonly [500, 1000, 2000, 5000, 10000, 20000, 50000];
+export declare const ALLOWED_THRESHOLDS: readonly [200, 500, 1000];
+export declare const ALLOWED_SCHEDULE_INTERVALS: readonly ["daily", "weekly", "monthly"];
+export declare function computeNextScheduleAt(interval: "daily" | "weekly" | "monthly" | null, now?: Date): string | null;
+export interface AutoTopupSettings {
+    tenantId: string;
+    usageEnabled: boolean;
+    usageThreshold: Credit;
+    usageTopup: Credit;
+    usageConsecutiveFailures: number;
+    usageChargeInFlight: boolean;
+    scheduleEnabled: boolean;
+    scheduleAmount: Credit;
+    scheduleIntervalHours: number;
+    scheduleNextAt: string | null;
+    scheduleConsecutiveFailures: number;
+    createdAt: string;
+    updatedAt: string;
+}
+export interface IAutoTopupSettingsRepository {
+    getByTenant(tenantId: string): Promise<AutoTopupSettings | null>;
+    upsert(tenantId: string, settings: Partial<Omit<AutoTopupSettings, "tenantId" | "createdAt" | "updatedAt">>): Promise<void>;
+    setUsageChargeInFlight(tenantId: string, inFlight: boolean): Promise<void>;
+    /** Atomically set usage_charge_in_flight = true IFF it is currently false. Returns true if acquired. */
+    tryAcquireUsageInFlight(tenantId: string): Promise<boolean>;
+    incrementUsageFailures(tenantId: string): Promise<number>;
+    resetUsageFailures(tenantId: string): Promise<void>;
+    disableUsage(tenantId: string): Promise<void>;
+    incrementScheduleFailures(tenantId: string): Promise<number>;
+    resetScheduleFailures(tenantId: string): Promise<void>;
+    disableSchedule(tenantId: string): Promise<void>;
+    advanceScheduleNextAt(tenantId: string): Promise<void>;
+    listDueScheduled(now: string): Promise<AutoTopupSettings[]>;
+    getMaxConsecutiveFailures(): Promise<number>;
+}
+export declare class DrizzleAutoTopupSettingsRepository implements IAutoTopupSettingsRepository {
+    private readonly db;
+    constructor(db: PlatformDb);
+    getByTenant(tenantId: string): Promise<AutoTopupSettings | null>;
+    upsert(tenantId: string, settings: Partial<Omit<AutoTopupSettings, "tenantId" | "createdAt" | "updatedAt">>): Promise<void>;
+    setUsageChargeInFlight(tenantId: string, inFlight: boolean): Promise<void>;
+    tryAcquireUsageInFlight(tenantId: string): Promise<boolean>;
+    incrementUsageFailures(tenantId: string): Promise<number>;
+    resetUsageFailures(tenantId: string): Promise<void>;
+    disableUsage(tenantId: string): Promise<void>;
+    incrementScheduleFailures(tenantId: string): Promise<number>;
+    resetScheduleFailures(tenantId: string): Promise<void>;
+    disableSchedule(tenantId: string): Promise<void>;
+    advanceScheduleNextAt(tenantId: string): Promise<void>;
+    getMaxConsecutiveFailures(): Promise<number>;
+    listDueScheduled(now: string): Promise<AutoTopupSettings[]>;
+}