@wopr-network/platform-core 1.0.10 → 1.1.0

package/dist/monetization/budget/budget-checker.js

@@ -0,0 +1,183 @@
+import { Credit } from "@wopr-network/platform-core/credits";
+import { and, eq, gte, lte, sql } from "drizzle-orm";
+import { LRUCache } from "lru-cache";
+import { logger } from "../../config/logger.js";
+import { meterEvents, usageSummaries } from "../../db/schema/meter-events.js";
+/**
+ * Pre-call budget checker with in-memory LRU cache.
+ *
+ * Before every upstream API call, this middleware queries the tenant's
+ * accumulated spend from meter_events + usage_summaries and compares it
+ * against caller-provided spend limits. If the budget is exceeded, the
+ * call is rejected with HTTP 429.
+ *
+ * Design:
+ * - Uses an in-memory LRU cache with ~30s TTL to avoid DB queries on every request
+ * - Fail-closed: if DB is unavailable or cache miss fails, reject the call
+ * - Callers pass SpendLimits directly (no more TierStore dependency)
+ */
+export class DrizzleBudgetChecker {
+    db;
+    cache;
+    cacheTtlMs;
+    constructor(db, config = {}) {
+        this.db = db;
+        this.cacheTtlMs = config.cacheTtlMs ?? 30_000; // 30 seconds default
+        this.cache = new LRUCache({
+            max: config.cacheMaxSize ?? 1000,
+            ttl: this.cacheTtlMs,
+        });
+    }
+    /**
+     * Check if a tenant can make an API call given their current spend.
+     *
+     * @param tenant - Tenant identifier
+     * @param limits - Spend limits for this tenant
+     * @returns BudgetCheckResult indicating whether the call is allowed
+     */
+    async check(tenant, limits) {
+        const label = limits.label ?? "current";
+        // Try to get cached data
+        // Include time buckets in the key so cached spend never leaks across billing periods.
+        const hourlyBucket = Math.floor(Date.now() / 3600_000);
+        const monthlyBucket = new Date().toISOString().slice(0, 7); // YYYY-MM
+        const cacheKey = `${tenant}:${hourlyBucket}:${monthlyBucket}`;
+        let cached = this.cache.get(cacheKey);
+        if (!cached) {
+            // Cache miss -- query DB
+            try {
+                cached = await this.queryBudgetData(tenant);
+                this.cache.set(cacheKey, cached);
+            }
+            catch (err) {
+                logger.error("Budget check query failed", { tenant, error: err });
+                // Fail-closed: if DB query fails, reject the call
+                return {
+                    allowed: false,
+                    reason: "Budget check unavailable. Please try again later.",
+                    httpStatus: 503,
+                    currentHourlySpend: 0,
+                    currentMonthlySpend: 0,
+                    maxSpendPerHour: limits.maxSpendPerHour,
+                    maxSpendPerMonth: limits.maxSpendPerMonth,
+                };
+            }
+        }
+        // Check hourly limit first (more urgent)
+        if (limits.maxSpendPerHour !== null && cached.hourlySpend >= limits.maxSpendPerHour) {
+            return {
+                allowed: false,
+                reason: `Hourly spending limit exceeded: $${cached.hourlySpend.toFixed(2)}/$${limits.maxSpendPerHour.toFixed(2)} (${label} tier). Upgrade your plan for higher limits.`,
+                httpStatus: 429,
+                currentHourlySpend: cached.hourlySpend,
+                currentMonthlySpend: cached.monthlySpend,
+                maxSpendPerHour: limits.maxSpendPerHour,
+                maxSpendPerMonth: limits.maxSpendPerMonth,
+            };
+        }
+        // Check monthly limit
+        if (limits.maxSpendPerMonth !== null && cached.monthlySpend >= limits.maxSpendPerMonth) {
+            return {
+                allowed: false,
+                reason: `Monthly spending limit exceeded: $${cached.monthlySpend.toFixed(2)}/$${limits.maxSpendPerMonth.toFixed(2)} (${label} tier). Upgrade your plan for higher limits.`,
+                httpStatus: 429,
+                currentHourlySpend: cached.hourlySpend,
+                currentMonthlySpend: cached.monthlySpend,
+                maxSpendPerHour: limits.maxSpendPerHour,
+                maxSpendPerMonth: limits.maxSpendPerMonth,
+            };
+        }
+        return {
+            allowed: true,
+            currentHourlySpend: cached.hourlySpend,
+            currentMonthlySpend: cached.monthlySpend,
+            maxSpendPerHour: limits.maxSpendPerHour,
+            maxSpendPerMonth: limits.maxSpendPerMonth,
+        };
+    }
+    /**
+     * Query current budget data from the DB.
+     * Combines data from meter_events buffer + usage_summaries.
+     */
+    async queryBudgetData(tenant) {
+        const now = Date.now();
+        const oneHourAgo = now - 60 * 60 * 1000;
+        const monthStart = this.getMonthStart(now);
+        // --- Hourly spend ---
+        // 1. Sum usage_summaries + find latest window_end
+        const hourlySummaries = (await this.db
+            .select({
+            total: sql `COALESCE(SUM(${usageSummaries.totalCharge}), 0)`,
+            // raw SQL: Drizzle cannot express COALESCE(MAX(...), 0) natively
+            latestEnd: sql `COALESCE(MAX(${usageSummaries.windowEnd}), 0)`,
+        })
+            .from(usageSummaries)
+            .where(and(eq(usageSummaries.tenant, tenant), gte(usageSummaries.windowEnd, oneHourAgo), lte(usageSummaries.windowStart, now))))[0];
+        const hourlySummaryTotal = Number(hourlySummaries?.total ?? 0);
+        const hourlyLatestEnd = Number(hourlySummaries?.latestEnd ?? 0);
+        // 2. Only query meter_events newer than the latest summary window end
+        // Assumes contiguous summary windows — gap between windows could under-count spend
+        // (acceptable limitation at current scale; aggregator guarantees gapless windows)
+        const hourlyEventsStart = hourlyLatestEnd > oneHourAgo ? hourlyLatestEnd : oneHourAgo;
+        const hourlyEvents = (await this.db
+            .select({
+            total: sql `COALESCE(SUM(${meterEvents.charge}), 0)`,
+        })
+            .from(meterEvents)
+            .where(and(eq(meterEvents.tenant, tenant), gte(meterEvents.timestamp, hourlyEventsStart))))[0];
+        const hourlyEventTotal = Number(hourlyEvents?.total ?? 0);
+        const hourlySpend = Credit.fromRaw(hourlySummaryTotal + hourlyEventTotal).toDollars();
+        // --- Monthly spend ---
+        const monthlySummaries = (await this.db
+            .select({
+            total: sql `COALESCE(SUM(${usageSummaries.totalCharge}), 0)`,
+            // raw SQL: Drizzle cannot express COALESCE(MAX(...), 0) natively
+            latestEnd: sql `COALESCE(MAX(${usageSummaries.windowEnd}), 0)`,
+        })
+            .from(usageSummaries)
+            .where(and(eq(usageSummaries.tenant, tenant), gte(usageSummaries.windowEnd, monthStart), lte(usageSummaries.windowStart, now))))[0];
+        const monthlySummaryTotal = Number(monthlySummaries?.total ?? 0);
+        const monthlyLatestEnd = Number(monthlySummaries?.latestEnd ?? 0);
+        // Assumes contiguous summary windows — gap between windows could under-count spend
+        // (acceptable limitation at current scale; aggregator guarantees gapless windows)
+        const monthlyEventsStart = monthlyLatestEnd > monthStart ? monthlyLatestEnd : monthStart;
+        const monthlyEvents = (await this.db
+            .select({
+            total: sql `COALESCE(SUM(${meterEvents.charge}), 0)`,
+        })
+            .from(meterEvents)
+            .where(and(eq(meterEvents.tenant, tenant), gte(meterEvents.timestamp, monthlyEventsStart))))[0];
+        const monthlyEventTotal = Number(monthlyEvents?.total ?? 0);
+        const monthlySpend = Credit.fromRaw(monthlySummaryTotal + monthlyEventTotal).toDollars();
+        return {
+            hourlySpend,
+            monthlySpend,
+        };
+    }
+    /**
+     * Get the start of the current month (unix epoch ms).
+     */
+    getMonthStart(now) {
+        const d = new Date(now);
+        return new Date(Date.UTC(d.getUTCFullYear(), d.getUTCMonth(), 1)).getTime();
+    }
+    /**
+     * Invalidate cache for a specific tenant (useful after spend updates).
+     */
+    invalidate(tenant) {
+        const prefix = `${tenant}:`;
+        for (const key of this.cache.keys()) {
+            if (key.startsWith(prefix)) {
+                this.cache.delete(key);
+            }
+        }
+    }
+    /**
+     * Clear the entire cache.
+     */
+    clearCache() {
+        this.cache.clear();
+    }
+}
+// Backward-compat alias.
+export { DrizzleBudgetChecker as BudgetChecker };

package/dist/monetization/budget/budget-checker.test.d.ts

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

package/dist/monetization/budget/budget-checker.test.js

@@ -0,0 +1,355 @@
+import { Credit } from "@wopr-network/platform-core/credits";
+import { afterAll, afterEach, beforeAll, beforeEach, describe, expect, it, vi } from "vitest";
+import { meterEvents, usageSummaries } from "../../db/schema/meter-events.js";
+import { beginTestTransaction, createTestDb, endTestTransaction, rollbackTestTransaction } from "../../test/db.js";
+import { BudgetChecker } from "./budget-checker.js";
+const FREE_LIMITS = {
+    maxSpendPerHour: 0.5,
+    maxSpendPerMonth: 5,
+    label: "free",
+};
+const PRO_LIMITS = {
+    maxSpendPerHour: 10,
+    maxSpendPerMonth: 200,
+    label: "pro",
+};
+const ENTERPRISE_LIMITS = {
+    maxSpendPerHour: null,
+    maxSpendPerMonth: null,
+    label: "enterprise",
+};
+describe("BudgetChecker", () => {
+    let db;
+    let pool;
+    let checker;
+    beforeAll(async () => {
+        ({ db, pool } = await createTestDb());
+        await beginTestTransaction(pool);
+    });
+    afterAll(async () => {
+        await endTestTransaction(pool);
+        await pool.close();
+    });
+    beforeEach(async () => {
+        await rollbackTestTransaction(pool);
+        checker = new BudgetChecker(db, { cacheTtlMs: 1000 });
+    });
+    afterEach(() => {
+        vi.useRealTimers();
+    });
+    describe("check()", () => {
+        it("allows requests when spend is under limit", async () => {
+            const result = await checker.check("tenant-1", FREE_LIMITS);
+            expect(result.allowed).toBe(true);
+            expect(result.currentHourlySpend).toBe(0);
+            expect(result.currentMonthlySpend).toBe(0);
+            expect(result.maxSpendPerHour).toBe(0.5);
+            expect(result.maxSpendPerMonth).toBe(5);
+        });
+        it("blocks requests when hourly limit is exceeded", async () => {
+            const now = Date.now();
+            await db.insert(meterEvents).values({
+                id: "evt-1",
+                tenant: "tenant-1",
+                cost: Credit.fromDollars(0.3).toRaw(),
+                charge: Credit.fromDollars(0.6).toRaw(),
+                capability: "chat",
+                provider: "replicate",
+                timestamp: now,
+            });
+            const result = await checker.check("tenant-1", FREE_LIMITS);
+            expect(result.allowed).toBe(false);
+            expect(result.reason).toContain("Hourly spending limit exceeded");
+            expect(result.httpStatus).toBe(429);
+            expect(result.currentHourlySpend).toBe(0.6);
+        });
+        it("blocks requests when monthly limit is exceeded", async () => {
+            const now = Date.now();
+            await db.insert(meterEvents).values({
+                id: "evt-1",
+                tenant: "tenant-1",
+                cost: Credit.fromDollars(2.5).toRaw(),
+                charge: Credit.fromDollars(5.0).toRaw(),
+                capability: "chat",
+                provider: "replicate",
+                timestamp: now,
+            });
+            const result = await checker.check("tenant-1", FREE_LIMITS);
+            expect(result.allowed).toBe(false);
+            expect(result.reason).toContain("spending limit exceeded");
+            expect(result.httpStatus).toBe(429);
+        });
+        it("allows unlimited spend for enterprise tier", async () => {
+            const result = await checker.check("tenant-ent", ENTERPRISE_LIMITS);
+            expect(result.allowed).toBe(true);
+            expect(result.maxSpendPerHour).toBeNull();
+            expect(result.maxSpendPerMonth).toBeNull();
+        });
+        it("reflects upgraded limits immediately without cache invalidation", async () => {
+            const now = Date.now();
+            // Insert spend that exceeds FREE but is under PRO
+            await db.insert(meterEvents).values({
+                id: crypto.randomUUID(),
+                tenant: "tenant-upgrade",
+                cost: Credit.fromDollars(0.5).toRaw(),
+                charge: Credit.fromDollars(1.0).toRaw(),
+                capability: "chat",
+                provider: "replicate",
+                timestamp: now,
+            });
+            // First check with FREE limits — should be blocked (1.0 >= 0.5)
+            const result1 = await checker.check("tenant-upgrade", FREE_LIMITS);
+            expect(result1.allowed).toBe(false);
+            expect(result1.maxSpendPerHour).toBe(0.5);
+            // Second check with PRO limits — should be allowed (1.0 < 10)
+            // WITHOUT calling invalidate() or clearCache()
+            const result2 = await checker.check("tenant-upgrade", PRO_LIMITS);
+            expect(result2.allowed).toBe(true);
+            expect(result2.maxSpendPerHour).toBe(10);
+            expect(result2.maxSpendPerMonth).toBe(200);
+            expect(result2.currentHourlySpend).toBe(1.0);
+        });
+        it("uses custom per-tenant limits when provided", async () => {
+            const customLimits = {
+                maxSpendPerHour: 1.0,
+                maxSpendPerMonth: 10.0,
+                label: "custom",
+            };
+            checker.clearCache();
+            const result = await checker.check("tenant-1", customLimits);
+            expect(result.allowed).toBe(true);
+            expect(result.maxSpendPerHour).toBe(1.0);
+            expect(result.maxSpendPerMonth).toBe(10.0);
+        });
+        it("caches budget data to avoid repeated DB queries", async () => {
+            const result1 = await checker.check("tenant-1", FREE_LIMITS);
+            expect(result1.allowed).toBe(true);
+            const now = Date.now();
+            await db.insert(meterEvents).values({
+                id: "evt-1",
+                tenant: "tenant-1",
+                cost: Credit.fromDollars(0.3).toRaw(),
+                charge: Credit.fromDollars(0.6).toRaw(),
+                capability: "chat",
+                provider: "replicate",
+                timestamp: now,
+            });
+            const result2 = await checker.check("tenant-1", FREE_LIMITS);
+            expect(result2.allowed).toBe(true);
+            expect(result2.currentHourlySpend).toBe(0);
+            checker.invalidate("tenant-1");
+            const result3 = await checker.check("tenant-1", FREE_LIMITS);
+            expect(result3.allowed).toBe(false);
+            expect(result3.currentHourlySpend).toBe(0.6);
+        });
+        it("aggregates spend from both meter_events and usage_summaries", async () => {
+            const now = Date.now();
+            const oneHourAgo = now - 60 * 60 * 1000;
+            const thirtyMinAgo = now - 30 * 60 * 1000;
+            // Summary covers [1h ago, 30min ago)
+            await db.insert(usageSummaries).values({
+                id: "sum-1",
+                tenant: "tenant-1",
+                capability: "chat",
+                provider: "replicate",
+                eventCount: 1,
+                totalCost: Credit.fromDollars(0.15).toRaw(),
+                totalCharge: Credit.fromDollars(0.3).toRaw(),
+                totalDuration: 0,
+                windowStart: oneHourAgo,
+                windowEnd: thirtyMinAgo,
+            });
+            // New event AFTER summary window
+            await db.insert(meterEvents).values({
+                id: "evt-1",
+                tenant: "tenant-1",
+                cost: Credit.fromDollars(0.1).toRaw(),
+                charge: Credit.fromDollars(0.2).toRaw(),
+                capability: "chat",
+                provider: "replicate",
+                timestamp: now,
+            });
+            const result = await checker.check("tenant-1", FREE_LIMITS);
+            expect(result.allowed).toBe(false); // $0.50 >= $0.50 hourly limit
+            expect(result.currentHourlySpend).toBe(0.5);
+        });
+        it("does not double-count meter_events already rolled into usage_summaries", async () => {
+            const now = Date.now();
+            const oneHourAgo = now - 60 * 60 * 1000;
+            // A meter_event that was already rolled up into a usage_summary
+            await db.insert(meterEvents).values({
+                id: "evt-rolled",
+                tenant: "tenant-1",
+                cost: Credit.fromDollars(0.15).toRaw(),
+                charge: Credit.fromDollars(0.3).toRaw(),
+                capability: "chat",
+                provider: "replicate",
+                timestamp: now - 30 * 60 * 1000, // 30 min ago
+            });
+            // The summary covering that event's window
+            await db.insert(usageSummaries).values({
+                id: "sum-rolled",
+                tenant: "tenant-1",
+                capability: "chat",
+                provider: "replicate",
+                eventCount: 1,
+                totalCost: Credit.fromDollars(0.15).toRaw(),
+                totalCharge: Credit.fromDollars(0.3).toRaw(),
+                totalDuration: 0,
+                windowStart: oneHourAgo,
+                windowEnd: now - 20 * 60 * 1000, // window ended 20 min ago
+            });
+            checker.clearCache();
+            const result = await checker.check("tenant-1", FREE_LIMITS);
+            // Should be $0.30 (from summary only), NOT $0.60 (double-counted)
+            expect(result.currentHourlySpend).toBe(0.3);
+            expect(result.allowed).toBe(true); // $0.30 < $0.50 hourly limit
+        });
+        it("includes unsummarized meter_events after latest summary window", async () => {
+            const now = Date.now();
+            const oneHourAgo = now - 60 * 60 * 1000;
+            // Summary covering [1h ago, 30min ago)
+            await db.insert(usageSummaries).values({
+                id: "sum-old",
+                tenant: "tenant-1",
+                capability: "chat",
+                provider: "replicate",
+                eventCount: 1,
+                totalCost: Credit.fromDollars(0.05).toRaw(),
+                totalCharge: Credit.fromDollars(0.1).toRaw(),
+                totalDuration: 0,
+                windowStart: oneHourAgo,
+                windowEnd: now - 30 * 60 * 1000,
+            });
+            // New event at 10min ago — not yet rolled up
+            await db.insert(meterEvents).values({
+                id: "evt-new",
+                tenant: "tenant-1",
+                cost: Credit.fromDollars(0.1).toRaw(),
+                charge: Credit.fromDollars(0.2).toRaw(),
+                capability: "chat",
+                provider: "replicate",
+                timestamp: now - 10 * 60 * 1000,
+            });
+            checker.clearCache();
+            const result = await checker.check("tenant-1", FREE_LIMITS);
+            // $0.10 summary + $0.20 new event = $0.30
+            expect(result.currentHourlySpend).toBe(0.3);
+        });
+        it("handles edge case: spend exactly at limit", async () => {
+            const now = Date.now();
+            await db.insert(meterEvents).values({
+                id: "evt-1",
+                tenant: "tenant-1",
+                cost: Credit.fromDollars(0.25).toRaw(),
+                charge: Credit.fromDollars(0.5).toRaw(),
+                capability: "chat",
+                provider: "replicate",
+                timestamp: now,
+            });
+            const result = await checker.check("tenant-1", FREE_LIMITS);
+            expect(result.allowed).toBe(false);
+            expect(result.currentHourlySpend).toBe(0.5);
+        });
+        it("handles edge case: spend just under limit", async () => {
+            const now = Date.now();
+            await db.insert(meterEvents).values({
+                id: "evt-1",
+                tenant: "tenant-1",
+                cost: Credit.fromDollars(0.24).toRaw(),
+                charge: Credit.fromDollars(0.49).toRaw(),
+                capability: "chat",
+                provider: "replicate",
+                timestamp: now,
+            });
+            const result = await checker.check("tenant-1", FREE_LIMITS);
+            expect(result.allowed).toBe(true);
+            expect(result.currentHourlySpend).toBe(0.49);
+        });
+        it("does not serve stale spend data across an hour boundary", async () => {
+            // Freeze time at a known point and populate cache
+            const baseNow = new Date("2026-02-15T11:59:00.000Z").getTime();
+            vi.useFakeTimers();
+            vi.setSystemTime(baseNow);
+            const result1 = await checker.check("tenant-boundary", FREE_LIMITS);
+            expect(result1.allowed).toBe(true);
+            expect(result1.currentHourlySpend).toBe(0);
+            // Advance past the hour boundary — new bucket, cache should miss
+            vi.setSystemTime(baseNow + 2 * 60 * 1000); // +2 minutes → into next hour
+            await db.insert(meterEvents).values({
+                id: crypto.randomUUID(),
+                tenant: "tenant-boundary",
+                cost: Credit.fromDollars(0.3).toRaw(),
+                charge: Credit.fromDollars(0.6).toRaw(),
+                capability: "chat",
+                provider: "replicate",
+                timestamp: baseNow + 2 * 60 * 1000,
+            });
+            // Fresh DB query because the hour bucket changed
+            const result2 = await checker.check("tenant-boundary", FREE_LIMITS);
+            expect(result2.allowed).toBe(false);
+            expect(result2.currentHourlySpend).toBe(0.6);
+        });
+        it("ignores events outside the hourly time window", async () => {
+            // Freeze mid-month so twoHoursAgo never crosses a month boundary
+            vi.useFakeTimers();
+            vi.setSystemTime(new Date("2026-02-15T12:00:00.000Z"));
+            const now = Date.now();
+            const twoHoursAgo = now - 2 * 60 * 60 * 1000;
+            await db.insert(meterEvents).values({
+                id: "evt-old",
+                tenant: "tenant-1",
+                cost: Credit.fromDollars(10).toRaw(),
+                charge: Credit.fromDollars(20).toRaw(),
+                capability: "chat",
+                provider: "replicate",
+                timestamp: twoHoursAgo,
+            });
+            checker.clearCache();
+            const result = await checker.check("tenant-1", FREE_LIMITS);
+            expect(result.allowed).toBe(false);
+            expect(result.currentHourlySpend).toBe(0);
+            expect(result.currentMonthlySpend).toBe(20);
+        });
+    });
+    describe("clearCache()", () => {
+        it("clears all cached entries", async () => {
+            await checker.check("tenant-1", FREE_LIMITS);
+            await checker.check("tenant-2", PRO_LIMITS);
+            checker.clearCache();
+            const now = Date.now();
+            await db.insert(meterEvents).values({
+                id: "evt-1",
+                tenant: "tenant-1",
+                cost: Credit.fromDollars(0.3).toRaw(),
+                charge: Credit.fromDollars(0.6).toRaw(),
+                capability: "chat",
+                provider: "replicate",
+                timestamp: now,
+            });
+            const result = await checker.check("tenant-1", FREE_LIMITS);
+            expect(result.currentHourlySpend).toBe(0.6);
+        });
+    });
+    describe("invalidate()", () => {
+        it("invalidates cache for a specific tenant", async () => {
+            await checker.check("tenant-1", FREE_LIMITS);
+            await checker.check("tenant-2", PRO_LIMITS);
+            checker.invalidate("tenant-1");
+            const now = Date.now();
+            await db.insert(meterEvents).values({
+                id: "evt-1",
+                tenant: "tenant-1",
+                cost: Credit.fromDollars(0.3).toRaw(),
+                charge: Credit.fromDollars(0.6).toRaw(),
+                capability: "chat",
+                provider: "replicate",
+                timestamp: now,
+            });
+            const result1 = await checker.check("tenant-1", FREE_LIMITS);
+            expect(result1.currentHourlySpend).toBe(0.6);
+            const result2 = await checker.check("tenant-2", PRO_LIMITS);
+            expect(result2.currentHourlySpend).toBe(0);
+        });
+    });
+});

package/dist/monetization/budget/index.d.ts

@@ -0,0 +1,2 @@
+export type { BudgetCheckerConfig, BudgetCheckResult, IBudgetChecker, SpendLimits } from "./budget-checker.js";
+export { BudgetChecker, DrizzleBudgetChecker } from "./budget-checker.js";

package/dist/monetization/budget/index.js

@@ -0,0 +1 @@
+export { BudgetChecker, DrizzleBudgetChecker } from "./budget-checker.js";

package/dist/monetization/credits/auto-topup-charge.d.ts

@@ -0,0 +1,26 @@
+import type { ITenantCustomerRepository } from "@wopr-network/platform-core/billing";
+import type { Credit, ICreditLedger } from "@wopr-network/platform-core/credits";
+import Stripe from "stripe";
+import type { IAutoTopupEventLogRepository } from "./auto-topup-event-log-repository.js";
+/** After this many consecutive Stripe failures, the auto-topup mode is disabled. */
+export declare const MAX_CONSECUTIVE_FAILURES = 3;
+export interface AutoTopupChargeDeps {
+    stripe: Stripe;
+    tenantRepo: ITenantCustomerRepository;
+    creditLedger: ICreditLedger;
+    eventLogRepo: IAutoTopupEventLogRepository;
+}
+export interface AutoTopupChargeResult {
+    success: boolean;
+    paymentReference?: string;
+    error?: string;
+}
+/**
+ * Charge a tenant's default Stripe payment method off-session and credit their ledger.
+ *
+ * Writes to both `credit_transactions` (type=purchase) and `credit_auto_topup` event log.
+ *
+ * @param source - Descriptive source tag for the credit_transactions description
+ *                 (e.g., "auto_topup_usage" or "auto_topup_schedule")
+ */
+export declare function chargeAutoTopup(deps: AutoTopupChargeDeps, tenantId: string, amount: Credit, source: string): Promise<AutoTopupChargeResult>;