@tktideai/ai-api-cost-guard 1.0.0

package/dist/guard.js

@@ -0,0 +1,310 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ApiCostGuard = void 0;
+exports.createMiddleware = createMiddleware;
+const decimal_js_1 = __importDefault(require("decimal.js"));
+const pricing_1 = require("./pricing");
+const errors_1 = require("./errors");
+// ─── Configure Decimal.js for money-safe arithmetic ───────────────────────
+decimal_js_1.default.set({
+    precision: 28, // More than enough for USD amounts
+    rounding: decimal_js_1.default.ROUND_HALF_UP,
+    toExpPos: 18,
+    toExpNeg: -7,
+});
+class ApiCostGuard {
+    // ─────────────────────────────────────────────────────────────────────
+    constructor(options = {}) {
+        // ── Ledger ───────────────────────────────────────────────────────────
+        this.ledger = [];
+        this.totalSpend = new decimal_js_1.default(0);
+        this.hardLimit = options.hardLimit != null ? new decimal_js_1.default(options.hardLimit) : null;
+        this.softLimit = options.softLimit != null ? new decimal_js_1.default(options.softLimit) : null;
+        this.perRequestLimit = options.perRequestLimit != null ? new decimal_js_1.default(options.perRequestLimit) : null;
+        this.windowMs = options.windowMs ?? null;
+        this.throwOnBlock = options.throwOnBlock ?? true;
+        this.onWarning = options.onWarning ?? null;
+        this.onBlock = options.onBlock ?? null;
+        // Merge built-in + custom pricing (custom wins on conflicts)
+        this.pricing = { ...pricing_1.BUILT_IN_PRICING, ...(options.customPricing ?? {}) };
+        this.validateOptions();
+    }
+    // ─── Public: Estimate cost ────────────────────────────────────────────
+    /**
+     * Estimate the cost of a request without checking limits.
+     * Returns null if the model is not in the pricing table.
+     */
+    estimateCost(model, inputTokens, outputTokens = 0) {
+        const p = this.resolvePricing(model);
+        if (!p)
+            return null;
+        const inputCost = new decimal_js_1.default(inputTokens)
+            .div(p.unit)
+            .mul(new decimal_js_1.default(p.input));
+        const outputCost = new decimal_js_1.default(outputTokens)
+            .div(p.unit)
+            .mul(new decimal_js_1.default(p.output));
+        return inputCost.plus(outputCost);
+    }
+    // ─── Public: Preflight check ──────────────────────────────────────────
+    /**
+     * Check whether a request should be allowed based on current spend.
+     * Call this BEFORE making the API request.
+     *
+     * @throws {BudgetExceededError} if blocked and `throwOnBlock` is true
+     */
+    preflightCheck(model, estimatedInputTokens, estimatedOutputTokens = 0) {
+        const estimatedCost = this.estimateCost(model, estimatedInputTokens, estimatedOutputTokens);
+        const currentSpend = this.getWindowSpend();
+        const projectedTotal = estimatedCost
+            ? currentSpend.plus(estimatedCost)
+            : currentSpend;
+        // ── Per-request limit ─────────────────────────────────────────────
+        if (this.perRequestLimit && estimatedCost && estimatedCost.gt(this.perRequestLimit)) {
+            const error = new errors_1.BudgetExceededError(`Request estimated cost $${estimatedCost.toFixed(6)} exceeds per-request limit $${this.perRequestLimit.toFixed(6)}`, {
+                type: 'per_request_limit',
+                projectedTotal,
+                currentSpend,
+                limit: this.perRequestLimit,
+                estimatedCost,
+            });
+            return this.handleBlock(error);
+        }
+        // ── Hard limit ────────────────────────────────────────────────────
+        if (this.hardLimit && projectedTotal.gte(this.hardLimit)) {
+            const error = new errors_1.BudgetExceededError(`Projected spend $${projectedTotal.toFixed(6)} would reach hard limit $${this.hardLimit.toFixed(6)}`, {
+                type: 'hard_limit',
+                projectedTotal,
+                currentSpend,
+                limit: this.hardLimit,
+                estimatedCost,
+            });
+            return this.handleBlock(error);
+        }
+        // ── Soft limit warning ────────────────────────────────────────────
+        if (this.softLimit && projectedTotal.gte(this.softLimit) && this.onWarning) {
+            this.onWarning({ projectedTotal, currentSpend, softLimit: this.softLimit, estimatedCost });
+        }
+        return { allowed: true, estimatedCost, projectedTotal };
+    }
+    // ─── Public: Record actual usage ──────────────────────────────────────
+    /**
+     * Record the actual token usage AFTER a successful API response.
+     * This keeps the spend ledger accurate.
+     *
+     * @returns The actual cost of this request
+     */
+    recordUsage(model, inputTokens, outputTokens, metadata = {}) {
+        const cost = this.estimateCost(model, inputTokens, outputTokens) ?? new decimal_js_1.default(0);
+        const record = {
+            timestamp: Date.now(),
+            cost,
+            model,
+            inputTokens,
+            outputTokens,
+            metadata,
+        };
+        this.ledger.push(record);
+        this.totalSpend = this.totalSpend.plus(cost);
+        this.pruneOldEntries();
+        return cost;
+    }
+    // ─── Public: wrap() ───────────────────────────────────────────────────
+    /**
+     * Wrap any async API call with automatic preflight + usage recording.
+     *
+     * @returns The API result, or null if blocked (when throwOnBlock=false)
+     * @throws {BudgetExceededError} if blocked and throwOnBlock=true
+     *
+     * @example
+     * const response = await guard.wrap(
+     *   () => openai.chat.completions.create({ model: 'gpt-4o', messages }),
+     *   {
+     *     model: 'gpt-4o',
+     *     estimatedInputTokens: 500,
+     *     estimatedOutputTokens: 500,
+     *     extractUsage: (res) => ({
+     *       inputTokens:  res.usage.prompt_tokens,
+     *       outputTokens: res.usage.completion_tokens,
+     *     }),
+     *   },
+     * );
+     */
+    async wrap(apiFn, options) {
+        const { model, estimatedInputTokens = 500, estimatedOutputTokens = 500, extractUsage, metadata = {}, } = options;
+        const check = this.preflightCheck(model, estimatedInputTokens, estimatedOutputTokens);
+        if (!check.allowed) {
+            // throwOnBlock=false path — handleBlock returned a result instead of throwing
+            return null;
+        }
+        const result = await apiFn();
+        // Record actual usage if extractor provided
+        if (extractUsage) {
+            try {
+                const { inputTokens, outputTokens } = extractUsage(result);
+                this.recordUsage(model, inputTokens, outputTokens, metadata);
+            }
+            catch {
+                // Non-fatal: estimation already tracked at preflight
+            }
+        }
+        return result;
+    }
+    // ─── Public: Stats ────────────────────────────────────────────────────
+    /**
+     * Get a snapshot of current spend and budget status.
+     */
+    getStats() {
+        const windowSpend = this.getWindowSpend();
+        const remainingBudget = this.hardLimit ? decimal_js_1.default.max(0, this.hardLimit.minus(windowSpend)) : null;
+        const percentUsed = this.hardLimit
+            ? windowSpend.div(this.hardLimit).mul(100).toFixed(2)
+            : null;
+        return {
+            totalSpend: this.totalSpend,
+            windowSpend,
+            requestCount: this.ledger.length,
+            hardLimit: this.hardLimit,
+            softLimit: this.softLimit,
+            remainingBudget,
+            percentUsed,
+            ledger: [...this.ledger], // defensive copy
+        };
+    }
+    /**
+     * Reset all spend records. Useful between test runs or billing periods.
+     */
+    reset() {
+        this.ledger = [];
+        this.totalSpend = new decimal_js_1.default(0);
+    }
+    // ─── Private helpers ──────────────────────────────────────────────────
+    getWindowSpend() {
+        if (!this.windowMs)
+            return this.totalSpend;
+        const cutoff = Date.now() - this.windowMs;
+        return this.ledger
+            .filter(e => e.timestamp >= cutoff)
+            .reduce((sum, e) => sum.plus(e.cost), new decimal_js_1.default(0));
+    }
+    pruneOldEntries() {
+        if (!this.windowMs)
+            return;
+        const cutoff = Date.now() - this.windowMs;
+        const before = this.ledger.length;
+        this.ledger = this.ledger.filter(e => e.timestamp >= cutoff);
+        const pruned = before - this.ledger.length;
+        // Keep totalSpend consistent when pruning
+        if (pruned > 0) {
+            this.totalSpend = this.ledger.reduce((sum, e) => sum.plus(e.cost), new decimal_js_1.default(0));
+        }
+    }
+    resolvePricing(model) {
+        const key = model.toLowerCase();
+        // Exact match first
+        if (this.pricing[key])
+            return this.pricing[key];
+        // Substring match — longest key wins to avoid 'gpt-4' matching 'gpt-4o'
+        const matches = Object.keys(this.pricing)
+            .filter(k => key.includes(k))
+            .sort((a, b) => b.length - a.length); // longest first
+        return matches.length > 0 ? (this.pricing[matches[0]] ?? null) : null;
+    }
+    handleBlock(error) {
+        if (this.onBlock) {
+            this.onBlock(error);
+        }
+        if (this.throwOnBlock) {
+            throw error;
+        }
+        return {
+            allowed: false,
+            reason: error.details.type,
+            estimatedCost: error.details.estimatedCost,
+            projectedTotal: error.details.projectedTotal,
+            currentSpend: error.details.currentSpend,
+            limit: error.details.limit,
+        };
+    }
+    validateOptions() {
+        if (this.hardLimit && this.hardLimit.lte(0)) {
+            throw new RangeError('hardLimit must be greater than 0');
+        }
+        if (this.softLimit && this.softLimit.lte(0)) {
+            throw new RangeError('softLimit must be greater than 0');
+        }
+        if (this.perRequestLimit && this.perRequestLimit.lte(0)) {
+            throw new RangeError('perRequestLimit must be greater than 0');
+        }
+        if (this.hardLimit && this.softLimit && this.softLimit.gte(this.hardLimit)) {
+            throw new RangeError('softLimit must be less than hardLimit');
+        }
+        if (this.windowMs !== null && this.windowMs <= 0) {
+            throw new RangeError('windowMs must be greater than 0');
+        }
+    }
+}
+exports.ApiCostGuard = ApiCostGuard;
+/**
+ * Express/Connect-compatible middleware.
+ * Runs a preflight check on every incoming request.
+ * Returns 429 with JSON error body if budget is exceeded.
+ *
+ * @example
+ * const guard = new ApiCostGuard({ hardLimit: 50 });
+ * app.post('/api/chat', createMiddleware(guard), async (req, res) => {
+ *   const response = await openai.chat.completions.create(req.body);
+ *   guard.recordUsage(req.body.model,
+ *     response.usage.prompt_tokens,
+ *     response.usage.completion_tokens,
+ *   );
+ *   res.json(response);
+ * });
+ */
+function createMiddleware(guard, options = {}) {
+    const getModel = options.getModel ?? ((req) => req.body?.model);
+    const getTokens = options.getTokens ?? ((req) => ({
+        input: Number(req.body?.max_tokens ?? 500),
+        output: Number(req.body?.max_tokens ?? 500),
+    }));
+    return (req, res, next) => {
+        const model = getModel(req);
+        const { input, output } = getTokens(req);
+        // Works regardless of throwOnBlock setting on the guard:
+        // - throwOnBlock:true  → throws BudgetExceededError → caught here → 429
+        // - throwOnBlock:false → returns { allowed: false }  → caught here → 429
+        try {
+            const check = guard.preflightCheck(model ?? 'unknown', input, output);
+            if (!check.allowed) {
+                res.status(429).json({
+                    error: 'BudgetExceeded',
+                    reason: check.reason,
+                    projectedTotal: check.projectedTotal.toFixed(6),
+                    currentSpend: check.currentSpend.toFixed(6),
+                    limit: check.limit.toFixed(6),
+                });
+                return;
+            }
+        }
+        catch (err) {
+            if (err instanceof errors_1.BudgetExceededError) {
+                res.status(429).json({
+                    error: 'BudgetExceeded',
+                    reason: err.details.type,
+                    projectedTotal: err.details.projectedTotal.toFixed(6),
+                    currentSpend: err.details.currentSpend.toFixed(6),
+                    limit: err.details.limit.toFixed(6),
+                });
+                return;
+            }
+            // Unknown error — let Express handle it
+            next(err);
+            return;
+        }
+        next();
+    };
+}
+//# sourceMappingURL=guard.js.map

package/dist/guard.js.map

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

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export { ApiCostGuard, createMiddleware } from './guard';
+export type { MiddlewareOptions } from './guard';
+export { BudgetExceededError } from './errors';
+export { BUILT_IN_PRICING } from './pricing';
+export type { ApiCostGuardOptions, ModelPricing, PricingMap, PreflightResult, PreflightAllowed, PreflightBlocked, BlockReason, UsageRecord, GuardStats, WrapOptions, WarningDetails, } from './types';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAC;AACzD,YAAY,EAAE,iBAAiB,EAAE,MAAM,SAAS,CAAC;AACjD,OAAO,EAAE,mBAAmB,EAAE,MAAM,UAAU,CAAC;AAC/C,OAAO,EAAE,gBAAgB,EAAE,MAAM,WAAW,CAAC;AAC7C,YAAY,EACV,mBAAmB,EACnB,YAAY,EACZ,UAAU,EACV,eAAe,EACf,gBAAgB,EAChB,gBAAgB,EAChB,WAAW,EACX,WAAW,EACX,UAAU,EACV,WAAW,EACX,cAAc,GACf,MAAM,SAAS,CAAC"}

package/dist/index.js

@@ -0,0 +1,11 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BUILT_IN_PRICING = exports.BudgetExceededError = exports.createMiddleware = exports.ApiCostGuard = void 0;
+var guard_1 = require("./guard");
+Object.defineProperty(exports, "ApiCostGuard", { enumerable: true, get: function () { return guard_1.ApiCostGuard; } });
+Object.defineProperty(exports, "createMiddleware", { enumerable: true, get: function () { return guard_1.createMiddleware; } });
+var errors_1 = require("./errors");
+Object.defineProperty(exports, "BudgetExceededError", { enumerable: true, get: function () { return errors_1.BudgetExceededError; } });
+var pricing_1 = require("./pricing");
+Object.defineProperty(exports, "BUILT_IN_PRICING", { enumerable: true, get: function () { return pricing_1.BUILT_IN_PRICING; } });
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;AAAA,iCAAyD;AAAhD,qGAAA,YAAY,OAAA;AAAE,yGAAA,gBAAgB,OAAA;AAEvC,mCAA+C;AAAtC,6GAAA,mBAAmB,OAAA;AAC5B,qCAA6C;AAApC,2GAAA,gBAAgB,OAAA"}

package/dist/notifiers/email.d.ts

@@ -0,0 +1,36 @@
+import type { WarningDetails } from '../types';
+import { BudgetExceededError } from '../errors';
+export interface EmailNotifierOptions {
+    /** Your Gmail address — used as the sender */
+    from: string;
+    /** Gmail app password for the sender account.
+     *  Google Account → Security → 2-Step Verification → App Passwords
+     */
+    password: string;
+    /** Recipient email address — where alerts are sent */
+    to: string;
+    /** Optional custom message shown at the top of the email */
+    message?: string;
+}
+type NotifierFn = (details: WarningDetails | BudgetExceededError) => Promise<void>;
+/**
+ * Creates an email notifier that sends real Gmail alerts when cost limits are hit.
+ *
+ * @example
+ * const notifier = createEmailNotifier({
+ *   from:     'your@gmail.com',
+ *   password: process.env.GMAIL_PASS!,
+ *   to:       'alerts@yourdomain.com',
+ *   message:  'Your AI spend needs attention.',  // optional
+ * });
+ *
+ * const guard = new ApiCostGuard({
+ *   softLimit: 8,
+ *   hardLimit: 10,
+ *   onWarning: notifier,
+ *   onBlock:   notifier,
+ * });
+ */
+export declare function createEmailNotifier(options: EmailNotifierOptions): NotifierFn;
+export {};
+//# sourceMappingURL=email.d.ts.map

package/dist/notifiers/email.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"email.d.ts","sourceRoot":"","sources":["../../src/notifiers/email.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,UAAU,CAAC;AAC/C,OAAO,EAAE,mBAAmB,EAAE,MAAM,WAAW,CAAC;AAOhD,MAAM,WAAW,oBAAoB;IACnC,8CAA8C;IAC9C,IAAI,EAAE,MAAM,CAAC;IACb;;OAEG;IACH,QAAQ,EAAE,MAAM,CAAC;IACjB,sDAAsD;IACtD,EAAE,EAAE,MAAM,CAAC;IACX,4DAA4D;IAC5D,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,KAAK,UAAU,GAAG,CAAC,OAAO,EAAE,cAAc,GAAG,mBAAmB,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;AA+OnF;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,oBAAoB,GAAG,UAAU,CAiC7E"}