ugly-app 0.1.0

package/dist/server/billing/BillingLedger.js

@@ -0,0 +1,214 @@
+const HOUR_MS = 3_600_000;
+// ---------------------------------------------------------------------------
+// BillingLedger
+// ---------------------------------------------------------------------------
+export class BillingLedger {
+    db;
+    reconcileIntervalMs;
+    pending = [];
+    timer = null;
+    constructor(db, reconcileIntervalMs = 300_000) {
+        this.db = db;
+        this.reconcileIntervalMs = reconcileIntervalMs;
+    }
+    /** Expose pending buffer size (for testing). */
+    pendingCount() {
+        return this.pending.length;
+    }
+    /** Synchronously append a record to the in-memory buffer. */
+    add(record) {
+        const stored = {
+            id: record.id,
+            version: 1,
+            created: new Date(record.timestamp),
+            updated: new Date(record.timestamp),
+            userId: record.userId,
+            provider: record.provider,
+            model: record.model,
+            type: record.type,
+            costUsd: record.costUsd,
+            inputTokens: record.inputTokens,
+            outputTokens: record.outputTokens,
+            imageCount: record.imageCount,
+            imageWidth: record.imageWidth,
+            imageHeight: record.imageHeight,
+            imageSteps: record.imageSteps,
+            audioSeconds: record.audioSeconds,
+            timestamp: record.timestamp,
+        };
+        this.pending.push(stored);
+    }
+    /**
+     * Sum costUsd for records in [now-windowMs, now], combining DB + in-memory pending.
+     * Pending records are NOT in DB yet — no double-counting.
+     */
+    async getWindowSpend(windowMs, filters) {
+        const now = Date.now();
+        const from = filters?.from ?? now - windowMs;
+        const to = filters?.to ?? now;
+        const filter = {
+            timestamp: { $gte: from, $lte: to },
+        };
+        if (filters?.userId !== undefined)
+            filter.userId = filters.userId;
+        if (filters?.provider !== undefined)
+            filter.provider = filters.provider;
+        if (filters?.type !== undefined)
+            filter.type = filters.type;
+        const dbRecords = await this.db.getDocs(filter, {});
+        const dbTotal = dbRecords.reduce((sum, r) => sum + r.costUsd, 0);
+        const pendingTotal = this.pending
+            .filter((r) => {
+            if (r.timestamp < from || r.timestamp > to)
+                return false;
+            if (filters?.userId !== undefined && r.userId !== filters.userId)
+                return false;
+            if (filters?.provider !== undefined && r.provider !== filters.provider)
+                return false;
+            if (filters?.type !== undefined && r.type !== filters.type)
+                return false;
+            return true;
+        })
+            .reduce((sum, r) => sum + r.costUsd, 0);
+        return dbTotal + pendingTotal;
+    }
+    /**
+     * Upsert all pending records to MongoDB, then clear the buffer.
+     * Atomic snapshot: concurrent adds after the snapshot are safe.
+     * On failure: failed records are prepended back to pending.
+     */
+    async reconcile() {
+        if (this.pending.length === 0)
+            return;
+        // Atomic snapshot
+        const toWrite = this.pending;
+        this.pending = [];
+        const failed = [];
+        for (const record of toWrite) {
+            try {
+                await this.db.setDoc(record.id, record);
+            }
+            catch (err) {
+                failed.push(record);
+                console.error('[BillingLedger] Failed to reconcile record', record.id, err);
+            }
+        }
+        if (failed.length > 0) {
+            // Prepend failed records so they're retried first next cycle
+            this.pending = [...failed, ...this.pending];
+        }
+        if (this.pending.length > 1000) {
+            console.warn('[BillingLedger] pending buffer exceeds 1000 records', {
+                pendingCount: this.pending.length,
+            });
+        }
+    }
+    /**
+     * Query billing history merging DB records and in-memory pending.
+     * Sorted by timestamp DESC, id ASC. Limit/skip applied to merged result.
+     */
+    async getHistory(filters = {}) {
+        const limit = Math.min(filters.limit ?? 100, 1000);
+        const skip = filters.skip ?? 0;
+        const filter = {};
+        if (filters.from !== undefined || filters.to !== undefined) {
+            filter.timestamp = {};
+            if (filters.from !== undefined)
+                filter.timestamp['$gte'] = filters.from;
+            if (filters.to !== undefined)
+                filter.timestamp['$lte'] = filters.to;
+        }
+        if (filters.userId !== undefined)
+            filter.userId = filters.userId;
+        if (filters.provider !== undefined)
+            filter.provider = filters.provider;
+        if (filters.type !== undefined)
+            filter.type = filters.type;
+        // Fetch more from DB than requested to account for pending records shifting pagination
+        const dbRecords = await this.db.getDocs(filter, {
+            sort: { timestamp: -1, id: 1 },
+            limit: limit + this.pending.length + skip,
+        });
+        const pendingMatched = this.pending.filter((r) => {
+            if (filters.from !== undefined && r.timestamp < filters.from)
+                return false;
+            if (filters.to !== undefined && r.timestamp > filters.to)
+                return false;
+            if (filters.userId !== undefined && r.userId !== filters.userId)
+                return false;
+            if (filters.provider !== undefined && r.provider !== filters.provider)
+                return false;
+            if (filters.type !== undefined && r.type !== filters.type)
+                return false;
+            return true;
+        });
+        // Merge DB + pending: DB records don't include pending (not yet written)
+        const all = [
+            ...dbRecords.map(storedToPublic),
+            ...pendingMatched.map(storedToPublic),
+        ];
+        // Sort by timestamp DESC, then id ASC as tiebreaker
+        all.sort((a, b) => {
+            const tsDiff = b.timestamp - a.timestamp;
+            if (tsDiff !== 0)
+                return tsDiff;
+            return a.id < b.id ? -1 : a.id > b.id ? 1 : 0;
+        });
+        return all.slice(skip, skip + limit);
+    }
+    /** Start the periodic reconcile timer. */
+    start() {
+        if (this.timer)
+            return;
+        this.timer = setInterval(() => {
+            void this.reconcile();
+        }, this.reconcileIntervalMs);
+    }
+    /** Stop the timer and flush pending records to DB. */
+    async shutdown() {
+        if (this.timer) {
+            clearInterval(this.timer);
+            this.timer = null;
+        }
+        await this.reconcile();
+    }
+}
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+function storedToPublic(r) {
+    const record = {
+        id: r.id,
+        provider: r.provider,
+        model: r.model,
+        type: r.type,
+        costUsd: r.costUsd,
+        timestamp: r.timestamp,
+    };
+    if (r.userId !== undefined)
+        record.userId = r.userId;
+    if (r.inputTokens !== undefined)
+        record.inputTokens = r.inputTokens;
+    if (r.outputTokens !== undefined)
+        record.outputTokens = r.outputTokens;
+    if (r.imageCount !== undefined)
+        record.imageCount = r.imageCount;
+    if (r.imageWidth !== undefined)
+        record.imageWidth = r.imageWidth;
+    if (r.imageHeight !== undefined)
+        record.imageHeight = r.imageHeight;
+    if (r.imageSteps !== undefined)
+        record.imageSteps = r.imageSteps;
+    if (r.audioSeconds !== undefined)
+        record.audioSeconds = r.audioSeconds;
+    return record;
+}
+// ---------------------------------------------------------------------------
+// Convenience: how many ms in each window
+// ---------------------------------------------------------------------------
+export const WINDOW_MS = {
+    HOUR: HOUR_MS,
+    DAY: 24 * HOUR_MS,
+    WEEK: 7 * 24 * HOUR_MS,
+};
+//# sourceMappingURL=BillingLedger.js.map

package/dist/server/billing/BillingLedger.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"BillingLedger.js","sourceRoot":"","sources":["../../../src/server/billing/BillingLedger.ts"],"names":[],"mappings":"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"}

package/dist/server/billing/CreditStore.d.ts

@@ -0,0 +1,58 @@
+import type { UserCredit } from './types.js';
+export interface CreditDB {
+    /** Atomically increment balanceUsd by delta (may be negative). Returns new balance. */
+    incrementCredit(userId: string, deltaUsd: number): Promise<number>;
+    /** Get current balance. Returns 0 if no record exists. */
+    getCredit(userId: string): Promise<number>;
+}
+/**
+ * Manages pre-paid credit balances for users.
+ *
+ * Credits are stored in MongoDB (`userCredits` collection) and cached in-memory
+ * with a short TTL. Deductions use optimistic in-memory decrement + async DB write;
+ * grants are written directly to DB and then invalidate the cache.
+ */
+export declare class CreditStore {
+    private readonly db;
+    private readonly cache;
+    private readonly ttlMs;
+    private readonly maxSize;
+    constructor(db: CreditDB, ttlMs?: number, // 1 hour
+    maxSize?: number);
+    /**
+     * Grant credits to a user (additive). Writes directly to DB; invalidates cache.
+     * Safe to call multiple times — amounts are accumulated.
+     */
+    grant(userId: string, amountUsd: number): Promise<void>;
+    /**
+     * Get current credit balance (cached with TTL).
+     */
+    getBalance(userId: string): Promise<number>;
+    /**
+     * Attempt to deduct costUsd from the user's credit balance.
+     * Returns true if deducted successfully, false if balance is insufficient.
+     * Uses optimistic in-memory decrement; DB write is async (fire-and-forget with logging).
+     */
+    tryDeduct(userId: string, costUsd: number): Promise<boolean>;
+    /** Invalidate cached balance for a user (e.g. after external grant). */
+    invalidate(userId: string): void;
+    private setCache;
+}
+export interface CreditDocDB {
+    /** Upsert a userCredits document. */
+    setDoc(id: string, doc: UserCredit): Promise<void>;
+    /** Get a userCredits document by id. */
+    getDoc(id: string): Promise<UserCredit | null>;
+}
+/**
+ * MongoDB-backed CreditDB implementation.
+ * Uses findOneAndUpdate-style atomic increment via a helper that performs
+ * a read-modify-write with the document's balanceUsd field.
+ */
+export declare class MongoCreditDB implements CreditDB {
+    private readonly db;
+    constructor(db: CreditDocDB);
+    incrementCredit(userId: string, deltaUsd: number): Promise<number>;
+    getCredit(userId: string): Promise<number>;
+}
+//# sourceMappingURL=CreditStore.d.ts.map

package/dist/server/billing/CreditStore.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"CreditStore.d.ts","sourceRoot":"","sources":["../../../src/server/billing/CreditStore.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAM7C,MAAM,WAAW,QAAQ;IACvB,uFAAuF;IACvF,eAAe,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IACnE,0DAA0D;IAC1D,SAAS,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;CAC5C;AAWD;;;;;;GAMG;AACH,qBAAa,WAAW;IAMpB,OAAO,CAAC,QAAQ,CAAC,EAAE;IALrB,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAiC;IACvD,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAS;IAC/B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;gBAGd,EAAE,EAAE,QAAQ,EAC7B,KAAK,SAAY,EAAE,SAAS;IAC5B,OAAO,SAAS;IAMlB;;;OAGG;IACG,KAAK,CAAC,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAY7D;;OAEG;IACG,UAAU,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAUjD;;;;OAIG;IACG,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IA4BlE,wEAAwE;IACxE,UAAU,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI;IAQhC,OAAO,CAAC,QAAQ;CAQjB;AAMD,MAAM,WAAW,WAAW;IAC1B,qCAAqC;IACrC,MAAM,CAAC,EAAE,EAAE,MAAM,EAAE,GAAG,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACnD,wCAAwC;IACxC,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC,CAAC;CAChD;AAED;;;;GAIG;AACH,qBAAa,aAAc,YAAW,QAAQ;IAChC,OAAO,CAAC,QAAQ,CAAC,EAAE;gBAAF,EAAE,EAAE,WAAW;IAEtC,eAAe,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAalE,SAAS,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;CAIjD"}

package/dist/server/billing/CreditStore.js

@@ -0,0 +1,112 @@
+/**
+ * Manages pre-paid credit balances for users.
+ *
+ * Credits are stored in MongoDB (`userCredits` collection) and cached in-memory
+ * with a short TTL. Deductions use optimistic in-memory decrement + async DB write;
+ * grants are written directly to DB and then invalidate the cache.
+ */
+export class CreditStore {
+    db;
+    cache = new Map();
+    ttlMs;
+    maxSize;
+    constructor(db, ttlMs = 3_600_000, // 1 hour
+    maxSize = 10_000) {
+        this.db = db;
+        this.ttlMs = ttlMs;
+        this.maxSize = maxSize;
+    }
+    /**
+     * Grant credits to a user (additive). Writes directly to DB; invalidates cache.
+     * Safe to call multiple times — amounts are accumulated.
+     */
+    async grant(userId, amountUsd) {
+        if (!Number.isFinite(amountUsd) || amountUsd <= 0) {
+            throw new Error(`[CreditStore] amountUsd must be finite positive, got ${String(amountUsd)}`);
+        }
+        const newBalance = await this.db.incrementCredit(userId, amountUsd);
+        this.setCache(userId, newBalance);
+    }
+    /**
+     * Get current credit balance (cached with TTL).
+     */
+    async getBalance(userId) {
+        const cached = this.cache.get(userId);
+        if (cached && Date.now() - cached.fetchedAt < this.ttlMs) {
+            return cached.balanceUsd;
+        }
+        const balance = await this.db.getCredit(userId);
+        this.setCache(userId, balance);
+        return balance;
+    }
+    /**
+     * Attempt to deduct costUsd from the user's credit balance.
+     * Returns true if deducted successfully, false if balance is insufficient.
+     * Uses optimistic in-memory decrement; DB write is async (fire-and-forget with logging).
+     */
+    async tryDeduct(userId, costUsd) {
+        const balance = await this.getBalance(userId);
+        if (balance < costUsd)
+            return false;
+        // Optimistic: update cache immediately to prevent concurrent over-deduction
+        const newBalance = Math.max(0, balance - costUsd);
+        this.setCache(userId, newBalance);
+        // Persist to DB asynchronously
+        this.db
+            .incrementCredit(userId, -costUsd)
+            .then((dbBalance) => {
+            // Reconcile: if DB says something different, trust DB
+            this.setCache(userId, Math.max(0, dbBalance));
+        })
+            .catch((err) => {
+            console.error('[CreditStore] Failed to persist deduction', { userId, costUsd }, err);
+            // Roll back optimistic decrement on failure
+            this.setCache(userId, balance);
+        });
+        return true;
+    }
+    /** Invalidate cached balance for a user (e.g. after external grant). */
+    invalidate(userId) {
+        this.cache.delete(userId);
+    }
+    // ---------------------------------------------------------------------------
+    // Private
+    // ---------------------------------------------------------------------------
+    setCache(userId, balanceUsd) {
+        // Simple LRU eviction: if at capacity and key is new, evict oldest entry
+        if (!this.cache.has(userId) && this.cache.size >= this.maxSize) {
+            const oldest = this.cache.keys().next().value;
+            if (oldest !== undefined)
+                this.cache.delete(oldest);
+        }
+        this.cache.set(userId, { balanceUsd, fetchedAt: Date.now() });
+    }
+}
+/**
+ * MongoDB-backed CreditDB implementation.
+ * Uses findOneAndUpdate-style atomic increment via a helper that performs
+ * a read-modify-write with the document's balanceUsd field.
+ */
+export class MongoCreditDB {
+    db;
+    constructor(db) {
+        this.db = db;
+    }
+    async incrementCredit(userId, deltaUsd) {
+        const existing = await this.db.getDoc(userId);
+        const current = existing?.balanceUsd ?? 0;
+        const newBalance = Math.max(0, current + deltaUsd);
+        const now = Date.now();
+        await this.db.setDoc(userId, {
+            id: userId,
+            balanceUsd: newBalance,
+            updated: now,
+        });
+        return newBalance;
+    }
+    async getCredit(userId) {
+        const doc = await this.db.getDoc(userId);
+        return doc?.balanceUsd ?? 0;
+    }
+}
+//# sourceMappingURL=CreditStore.js.map

package/dist/server/billing/CreditStore.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"CreditStore.js","sourceRoot":"","sources":["../../../src/server/billing/CreditStore.ts"],"names":[],"mappings":"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"}

package/dist/server/billing/LimitEnforcer.d.ts

@@ -0,0 +1,73 @@
+import type { BillingLedger } from './BillingLedger.js';
+import type { CreditStore } from './CreditStore.js';
+import type { BillingConfig, ChargeParams, GlobalThresholdCallback, UserThresholdCallback } from './types.js';
+import type { UserLimitCache } from './UserLimitCache.js';
+/**
+ * Checks all billing limits and fires threshold callbacks.
+ *
+ * Global and provider hourly limits use a synchronous in-memory rolling
+ * accumulator — race-free within a single Node.js process.
+ *
+ * Per-user hourly/daily/weekly limits perform async DB queries via BillingLedger.
+ *
+ * Known limitations (documented):
+ * - Multi-server: each server's accumulator is independent; limits are eventually
+ *   consistent up to the reconciliation interval.
+ * - TOCTOU for per-user async checks: concurrent charges for the same userId can
+ *   both pass under very high concurrent load. Mitigable with per-userId mutex (v2).
+ */
+export declare class LimitEnforcer {
+    private readonly ledger;
+    private readonly userLimits;
+    private readonly config;
+    private readonly credits;
+    private readonly accumulators;
+    private readonly firedThresholds;
+    private userThresholdCb;
+    private globalThresholdCb;
+    constructor(ledger: BillingLedger, userLimits: UserLimitCache, config: BillingConfig, credits?: CreditStore | null);
+    setUserThresholdCallback(fn: UserThresholdCallback): void;
+    setGlobalThresholdCallback(fn: GlobalThresholdCallback): void;
+    /**
+     * Load current-window spend from DB to warm the in-memory accumulators.
+     * Called by BillingGateway.start() before serving traffic.
+     */
+    init(): Promise<void>;
+    /**
+     * Check all applicable limits for a charge.
+     *
+     * Check order (observable — documented):
+     *   1. global-hourly
+     *   2. provider-hourly
+     *   3. user-hourly
+     *   4. user-daily
+     *   5. user-weekly
+     *
+     * Throws BillingLimitError on first violation.
+     * Throws BillingValidationError on invalid input.
+     */
+    check(params: ChargeParams): Promise<void>;
+    private addToAccumulator;
+    /** Remove the most recent entry that matches cost+ts (rollback of optimistic add). */
+    private removeFromAccumulator;
+    private pruneAccumulator;
+    private sumAccumulator;
+    private checkUserLimits;
+    /**
+     * If a CreditStore is configured and the user has sufficient balance, deduct and return.
+     * Otherwise throw the original limit error.
+     */
+    private tryCreditsOrThrow;
+    /**
+     * Fire the global/provider threshold callback if the charge crosses the threshold.
+     * Fires at most once per window per threshold ratio (deduplicated by firedThresholds map).
+     * Window reset is detected when the accumulator for that key becomes empty after pruning.
+     */
+    private maybeFireGlobalThreshold;
+    /**
+     * Fire the user threshold callback if the charge crosses a per-user window threshold.
+     * User threshold state is tracked per (userId, limitType) key.
+     */
+    private maybeFireUserThreshold;
+}
+//# sourceMappingURL=LimitEnforcer.d.ts.map

package/dist/server/billing/LimitEnforcer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"LimitEnforcer.d.ts","sourceRoot":"","sources":["../../../src/server/billing/LimitEnforcer.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAExD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AACpD,OAAO,KAAK,EACV,aAAa,EACb,YAAY,EACZ,uBAAuB,EAEvB,qBAAqB,EACtB,MAAM,YAAY,CAAC;AAEpB,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAW1D;;;;;;;;;;;;;GAaG;AACH,qBAAa,aAAa;IAQtB,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,UAAU;IAC3B,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,OAAO;IAV1B,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAyC;IAEtE,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAkC;IAClE,OAAO,CAAC,eAAe,CAAsC;IAC7D,OAAO,CAAC,iBAAiB,CAAwC;gBAG9C,MAAM,EAAE,aAAa,EACrB,UAAU,EAAE,cAAc,EAC1B,MAAM,EAAE,aAAa,EACrB,OAAO,GAAE,WAAW,GAAG,IAAW;IAGrD,wBAAwB,CAAC,EAAE,EAAE,qBAAqB,GAAG,IAAI;IAIzD,0BAA0B,CAAC,EAAE,EAAE,uBAAuB,GAAG,IAAI;IAI7D;;;OAGG;IACG,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAgB3B;;;;;;;;;;;;OAYG;IACG,KAAK,CAAC,MAAM,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC;IAsFhD,OAAO,CAAC,gBAAgB;IAMxB,sFAAsF;IACtF,OAAO,CAAC,qBAAqB;IAW7B,OAAO,CAAC,gBAAgB;IAYxB,OAAO,CAAC,cAAc;YAUR,eAAe;IAuE7B;;;OAGG;YACW,iBAAiB;IAgB/B;;;;OAIG;IACH,OAAO,CAAC,wBAAwB;IAiChC;;;OAGG;IACH,OAAO,CAAC,sBAAsB;CAiC/B"}