@wopr-network/platform-core 0.1.0

package/src/credits/auto-topup-schedule.test.ts

@@ -0,0 +1,179 @@
+import type { PGlite } from "@electric-sql/pglite";
+import { afterAll, beforeAll, beforeEach, describe, expect, it, vi } from "vitest";
+import type { PlatformDb } from "../db/index.js";
+import { beginTestTransaction, createTestDb, endTestTransaction, rollbackTestTransaction } from "../test/db.js";
+import { Credit } from "./credit.js";
+import { runScheduledTopups, type ScheduleTopupDeps } from "./auto-topup-schedule.js";
+import { DrizzleAutoTopupSettingsRepository } from "./auto-topup-settings-repository.js";
+
+describe("runScheduledTopups", () => {
+  let pool: PGlite;
+  let db: PlatformDb;
+  let settingsRepo: DrizzleAutoTopupSettingsRepository;
+
+  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: ScheduleTopupDeps = { 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: ScheduleTopupDeps = { 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: ScheduleTopupDeps = { 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: ScheduleTopupDeps = { 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: ScheduleTopupDeps = { 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: ScheduleTopupDeps = { 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: ScheduleTopupDeps = { settingsRepo, chargeAutoTopup: mockCharge };
+
+    const result = await runScheduledTopups(deps);
+    expect(result.processed).toBe(2);
+    expect(result.succeeded).toContain("t1");
+    expect(result.failed).toContain("t2");
+  });
+});

package/src/credits/auto-topup-schedule.ts

@@ -0,0 +1,93 @@
+import { logger } from "../config/logger.js";
+import type { Credit } from "./credit.js";
+import type { AutoTopupChargeResult } from "./auto-topup-charge.js";
+import { MAX_CONSECUTIVE_FAILURES } 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 async function runScheduledTopups(deps: ScheduleTopupDeps): Promise<ScheduleTopupResult> {
+  const now = new Date().toISOString();
+  const due = await deps.settingsRepo.listDueScheduled(now);
+
+  const result: ScheduleTopupResult = {
+    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/src/credits/auto-topup-settings-repository.test.ts

@@ -0,0 +1,123 @@
+import type { PGlite } from "@electric-sql/pglite";
+import { afterAll, beforeAll, beforeEach, describe, expect, it } from "vitest";
+import type { PlatformDb } from "../db/index.js";
+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: PGlite;
+  let db: PlatformDb;
+  let repo: DrizzleAutoTopupSettingsRepository;
+
+  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/src/credits/auto-topup-settings-repository.ts

@@ -0,0 +1,245 @@
+import { and, eq, lte, sql } from "drizzle-orm";
+import type { PlatformDb } from "../db/index.js";
+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] as const;
+export const ALLOWED_THRESHOLDS = [200, 500, 1000] as const;
+export const ALLOWED_SCHEDULE_INTERVALS = ["daily", "weekly", "monthly"] as const;
+
+export function computeNextScheduleAt(
+  interval: "daily" | "weekly" | "monthly" | null,
+  now: Date = new Date(),
+): string | null {
+  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 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 class DrizzleAutoTopupSettingsRepository implements IAutoTopupSettingsRepository {
+  constructor(private readonly db: PlatformDb) {}
+
+  async getByTenant(tenantId: string): Promise<AutoTopupSettings | null> {
+    const row = (
+      await this.db.select().from(creditAutoTopupSettings).where(eq(creditAutoTopupSettings.tenantId, tenantId))
+    )[0];
+    return row ? mapRow(row) : null;
+  }
+
+  async upsert(
+    tenantId: string,
+    settings: Partial<Omit<AutoTopupSettings, "tenantId" | "createdAt" | "updatedAt">>,
+  ): Promise<void> {
+    const now = sql`now()` as unknown as string;
+    const values: typeof creditAutoTopupSettings.$inferInsert = {
+      tenantId,
+      updatedAt: now,
+    };
+    const updateSet: Record<string, unknown> = { 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: string, inFlight: boolean): Promise<void> {
+    await this.db
+      .update(creditAutoTopupSettings)
+      .set({ usageChargeInFlight: inFlight, updatedAt: sql`now()` })
+      .where(eq(creditAutoTopupSettings.tenantId, tenantId));
+  }
+
+  async tryAcquireUsageInFlight(tenantId: string): Promise<boolean> {
+    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: string): Promise<number> {
+    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: string): Promise<void> {
+    await this.db
+      .update(creditAutoTopupSettings)
+      .set({ usageConsecutiveFailures: 0, updatedAt: sql`now()` })
+      .where(eq(creditAutoTopupSettings.tenantId, tenantId));
+  }
+
+  async disableUsage(tenantId: string): Promise<void> {
+    await this.db
+      .update(creditAutoTopupSettings)
+      .set({ usageEnabled: false, updatedAt: sql`now()` })
+      .where(eq(creditAutoTopupSettings.tenantId, tenantId));
+  }
+
+  async incrementScheduleFailures(tenantId: string): Promise<number> {
+    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: string): Promise<void> {
+    await this.db
+      .update(creditAutoTopupSettings)
+      .set({ scheduleConsecutiveFailures: 0, updatedAt: sql`now()` })
+      .where(eq(creditAutoTopupSettings.tenantId, tenantId));
+  }
+
+  async disableSchedule(tenantId: string): Promise<void> {
+    await this.db
+      .update(creditAutoTopupSettings)
+      .set({ scheduleEnabled: false, updatedAt: sql`now()` })
+      .where(eq(creditAutoTopupSettings.tenantId, tenantId));
+  }
+
+  async advanceScheduleNextAt(tenantId: string): Promise<void> {
+    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(): Promise<number> {
+    const result = await this.db
+      .select({
+        maxFailures: sql<number>`GREATEST(
+          COALESCE(MAX(${creditAutoTopupSettings.usageConsecutiveFailures}), 0),
+          COALESCE(MAX(${creditAutoTopupSettings.scheduleConsecutiveFailures}), 0)
+        )`,
+      })
+      .from(creditAutoTopupSettings);
+    return result[0]?.maxFailures ?? 0;
+  }
+
+  async listDueScheduled(now: string): Promise<AutoTopupSettings[]> {
+    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: typeof creditAutoTopupSettings.$inferSelect): AutoTopupSettings {
+  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,
+  };
+}