@tktideai/ai-api-cost-guard 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 TKTIDE (https://tktide.com)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,360 @@
+# api-cost-guard
+
+> **Set a hard stop on your AI API spend — in one line of code.**
+
+Your cloud provider's billing limit doesn't stop mid-request spikes, infinite loops, or per-user abuse. This does.
+
+Built with TypeScript and money-safe decimal arithmetic. Zero floating-point surprises.
+
+---
+
+## The problem
+
+```
+Your app has a bug → infinite loop → 1,000 API calls in 60 seconds
+Your cloud billing limit? It fires an email. After the fact.
+Your credit card? Already charged.
+```
+
+**api-cost-guard** intercepts every request **before** it reaches the provider. If the cost would exceed your limit — it never goes out.
+
+---
+
+## Install
+
+```bash
+npm install @tktideai/ai-api-cost-guard
+```
+
+---
+
+## Quick start
+
+```ts
+import { ApiCostGuard } from '@tktideai/ai-api-cost-guard';
+
+const guard = new ApiCostGuard({
+  hardLimit:       10.00,   // stop all requests at $10
+  softLimit:        8.00,   // warn at $8
+  perRequestLimit:  0.50,   // no single request over $0.50
+});
+
+// Before every API call:
+const check = guard.preflightCheck('gpt-4o', 500, 500);
+if (!check.allowed) return; // blocked — never reaches OpenAI
+
+const response = await openai.chat.completions.create({ ... });
+
+// After — record real usage so future checks stay accurate:
+guard.recordUsage('gpt-4o',
+  response.usage.prompt_tokens,
+  response.usage.completion_tokens,
+);
+```
+
+---
+
+## Simpler: use `wrap()`
+
+```ts
+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,
+    }),
+  },
+);
+// returns null if blocked, result if allowed
+```
+
+---
+
+## Options
+
+```ts
+const guard = new ApiCostGuard({
+  // ── Limits ───────────────────────────────────────────────────────────
+  hardLimit:       10.00,    // $ — block all requests at this cumulative spend
+  softLimit:        8.00,    // $ — fire onWarning (does not block)
+  perRequestLimit:  0.50,    // $ — block any single request above this cost
+
+  // ── Rolling window ───────────────────────────────────────────────────
+  windowMs: 3_600_000,       // only count spend in the last 1 hour (optional)
+
+  // ── Callbacks ────────────────────────────────────────────────────────
+  onWarning: (details) => {
+    console.log(`⚠️ Approaching limit: $${details.projectedTotal}`);
+  },
+  onBlock: (error) => {
+    console.log(`🛑 Blocked: ${error.message}`);
+  },
+
+  // ── Behaviour ────────────────────────────────────────────────────────
+  throwOnBlock: true,        // throw BudgetExceededError when blocked (default: true)
+
+  // ── Custom pricing ───────────────────────────────────────────────────
+  customPricing: {
+    'my-fine-tuned-model': { input: '0.008', output: '0.016', unit: 1000 },
+  },
+});
+```
+
+---
+
+## Supported models
+
+Pricing is built-in and matched by substring — versioned names like `gpt-4o-mini-2024-07-18` work automatically.
+
+### OpenAI
+| Model | Input / 1k | Output / 1k |
+|---|---|---|
+| gpt-4o | $0.0025 | $0.0100 |
+| gpt-4o-mini | $0.00015 | $0.0006 |
+| gpt-4-turbo | $0.0100 | $0.0300 |
+| gpt-4 | $0.0300 | $0.0600 |
+| gpt-3.5-turbo | $0.0005 | $0.0015 |
+| o1 | $0.0150 | $0.0600 |
+| o3 | $0.0100 | $0.0400 |
+| o4-mini | $0.0011 | $0.0044 |
+| o1-pro | $0.1500 | $0.6000 |
+
+### Anthropic
+| Model | Input / 1k | Output / 1k |
+|---|---|---|
+| claude-opus-4 | $0.0150 | $0.0750 |
+| claude-sonnet-4 | $0.0030 | $0.0150 |
+| claude-3-5-sonnet | $0.0030 | $0.0150 |
+| claude-3-5-haiku | $0.0008 | $0.0040 |
+| claude-3-opus | $0.0150 | $0.0750 |
+| claude-3-haiku | $0.00025 | $0.00125 |
+
+### Google Gemini
+| Model | Input / 1k | Output / 1k |
+|---|---|---|
+| gemini-2.5-pro | $0.00125 | $0.0100 |
+| gemini-2.0-flash | $0.0001 | $0.0004 |
+| gemini-1.5-pro | $0.00125 | $0.0050 |
+| gemini-1.5-flash | $0.000075 | $0.0003 |
+
+> Prices may change. Always verify against provider docs and override via `customPricing` if needed.
+
+---
+
+## Check your spend
+
+```ts
+const stats = guard.getStats();
+
+console.log(stats.totalSpend.toFixed(4));     // "3.4200"
+console.log(stats.remainingBudget.toFixed(4)); // "6.5800"
+console.log(stats.percentUsed);               // "34.20"
+console.log(stats.requestCount);              // 47
+```
+
+---
+
+## Express middleware
+
+```ts
+import { ApiCostGuard, createMiddleware } from '@tktideai/ai-api-cost-guard';
+
+const guard = new ApiCostGuard({ hardLimit: 50 });
+
+app.post('/api/chat', createMiddleware(guard), async (req, res) => {
+  // If we reach here, budget is OK
+  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);
+});
+// Returns 429 automatically if budget exceeded
+```
+
+---
+
+## Per-user limits (SaaS)
+
+```ts
+// One guard per user — isolated budgets
+const userGuards = new Map<string, ApiCostGuard>();
+
+function getGuard(userId: string): ApiCostGuard {
+  if (!userGuards.has(userId)) {
+    userGuards.set(userId, new ApiCostGuard({
+      hardLimit: 5.00,           // $5 per user
+      windowMs:  30 * 24 * 60 * 60 * 1000, // per month
+    }));
+  }
+  return userGuards.get(userId)!;
+}
+
+// In your route:
+const guard = getGuard(req.user.id);
+const check = guard.preflightCheck('gpt-4o', 500, 500);
+```
+
+---
+
+## Email alerts (optional)
+
+Get real email notifications when limits are hit. Uses Gmail SMTP — no external API key needed.
+
+### Setup
+
+**1. Get a Gmail app password for your sender address:**
+```
+Google Account → Security → 2-Step Verification → App Passwords → Generate
+```
+
+**2. Add to your `.env`:**
+```env
+GMAIL_FROM=your@gmail.com
+GMAIL_PASS=xxxx xxxx xxxx xxxx
+```
+
+**3. Use in your app:**
+```ts
+import { ApiCostGuard } from '@tktideai/ai-api-cost-guard';
+import { createEmailNotifier } from '@tktideai/ai-api-cost-guard/notifiers';
+
+const notifier = createEmailNotifier({
+  from:     process.env.GMAIL_FROM!,      // your Gmail — used as the sender
+  password: process.env.GMAIL_PASS!,      // your Gmail app password
+  to:       'you@example.com',            // where alerts are delivered
+  message:  'Your AI budget needs attention.',  // optional
+});
+
+const guard = new ApiCostGuard({
+  softLimit: 8,
+  hardLimit: 10,
+  onWarning: notifier,
+  onBlock:   notifier,
+});
+```
+
+### What the email looks like
+
+```
+Subject: ⚠️ API Cost Alert — Budget Warning | TKTIDE
+
+┌─────────────────────────────────────┐
+│  ⚠️  Approaching Budget Limit       │
+├─────────────────────────────────────┤
+│  Your AI budget needs attention.    │  ← your message
+│                                     │
+│  Trigger        Soft Limit Warning  │
+│  Current Spend  $7.9900             │
+│  Projected      $8.0075             │
+│  Limit          $8.0000             │
+├─────────────────────────────────────┤
+│  [TKTIDE logo]                      │
+│  TKTIDE is here to help             │
+│  https://tktide.com                 │
+└─────────────────────────────────────┘
+```
+
+> Email failures are non-fatal — they never crash or block your app.
+
+---
+
+## Why TypeScript + Decimal.js?
+
+Plain JavaScript has a well-known problem with money math:
+
+```js
+// JavaScript — this is real:
+0.1 + 0.2 === 0.30000000000000004  // true
+
+// Your $0.30 hard limit never triggers
+// You get charged $0.30000000000000004
+```
+
+**api-cost-guard** uses [Decimal.js](https://mikemcl.github.io/decimal.js/) for all arithmetic:
+
+```ts
+new Decimal('0.10').plus('0.20').equals('0.30') // always true
+```
+
+Every cost, limit, and comparison is exact.
+
+---
+
+## Error handling
+
+```ts
+import { ApiCostGuard, BudgetExceededError } from '@tktideai/ai-api-cost-guard';
+
+try {
+  guard.preflightCheck('gpt-4o', 5000, 2000);
+} catch (e) {
+  if (e instanceof BudgetExceededError) {
+    console.log(e.details.type);           // 'hard_limit' | 'per_request_limit'
+    console.log(e.details.limit);          // Decimal
+    console.log(e.details.projectedTotal); // Decimal
+    console.log(e.details.currentSpend);   // Decimal
+  }
+}
+```
+
+Or opt out of throwing:
+
+```ts
+const guard = new ApiCostGuard({
+  hardLimit:    10,
+  throwOnBlock: false,  // returns { allowed: false } instead of throwing
+});
+
+const check = guard.preflightCheck('gpt-4o', 5000, 2000);
+if (!check.allowed) {
+  console.log(check.reason); // 'hard_limit' | 'per_request_limit'
+}
+```
+
+---
+
+## Full API reference
+
+### `new ApiCostGuard(options)`
+Creates a new guard instance.
+
+### `guard.preflightCheck(model, inputTokens, outputTokens?)`
+Check if a request is within budget before sending.
+Returns `PreflightResult` — `{ allowed: true }` or `{ allowed: false, reason }`.
+
+### `guard.recordUsage(model, inputTokens, outputTokens, metadata?)`
+Record actual token usage after a successful API response.
+Returns the cost as a `Decimal`.
+
+### `guard.wrap(apiFn, options)`
+Combines preflight + API call + usage recording in one call.
+Returns the API result or `null` if blocked (when `throwOnBlock: false`).
+
+### `guard.getStats()`
+Returns a snapshot of current spend, request count, remaining budget, and the full ledger.
+
+### `guard.reset()`
+Clears all spend records. Useful between billing periods or test runs.
+
+---
+
+## Scripts
+
+```bash
+npm test          # run all 62 tests
+npm run build     # compile TypeScript to dist/
+npm run test:watch # watch mode
+```
+
+---
+
+## License
+
+MIT — built with ❤️ by [TKTIDE](https://tktide.com)

package/dist/errors.d.ts

@@ -0,0 +1,14 @@
+import type { BlockReason } from './types';
+import Decimal from 'decimal.js';
+export interface BudgetExceededDetails {
+    readonly type: BlockReason;
+    readonly projectedTotal: Decimal;
+    readonly currentSpend: Decimal;
+    readonly limit: Decimal;
+    readonly estimatedCost: Decimal | null;
+}
+export declare class BudgetExceededError extends Error {
+    readonly details: BudgetExceededDetails;
+    constructor(message: string, details: BudgetExceededDetails);
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAC3C,OAAO,OAAO,MAAM,YAAY,CAAC;AAEjC,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAC;IAC3B,QAAQ,CAAC,cAAc,EAAE,OAAO,CAAC;IACjC,QAAQ,CAAC,YAAY,EAAE,OAAO,CAAC;IAC/B,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IACxB,QAAQ,CAAC,aAAa,EAAE,OAAO,GAAG,IAAI,CAAC;CACxC;AAED,qBAAa,mBAAoB,SAAQ,KAAK;IAC5C,SAAgB,OAAO,EAAE,qBAAqB,CAAC;gBAEnC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,qBAAqB;CAQ5D"}

package/dist/errors.js

@@ -0,0 +1,14 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BudgetExceededError = void 0;
+class BudgetExceededError extends Error {
+    constructor(message, details) {
+        super(message);
+        this.name = 'BudgetExceededError';
+        this.details = details;
+        // Maintains proper prototype chain in TypeScript
+        Object.setPrototypeOf(this, BudgetExceededError.prototype);
+    }
+}
+exports.BudgetExceededError = BudgetExceededError;
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":";;;AAWA,MAAa,mBAAoB,SAAQ,KAAK;IAG5C,YAAY,OAAe,EAAE,OAA8B;QACzD,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,qBAAqB,CAAC;QAClC,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;QAEvB,iDAAiD;QACjD,MAAM,CAAC,cAAc,CAAC,IAAI,EAAE,mBAAmB,CAAC,SAAS,CAAC,CAAC;IAC7D,CAAC;CACF;AAXD,kDAWC"}

package/dist/guard.d.ts

@@ -0,0 +1,99 @@
+import Decimal from 'decimal.js';
+import type { ApiCostGuardOptions, PreflightResult, GuardStats, WrapOptions } from './types';
+export declare class ApiCostGuard {
+    private readonly hardLimit;
+    private readonly softLimit;
+    private readonly perRequestLimit;
+    private readonly windowMs;
+    private readonly throwOnBlock;
+    private readonly onWarning;
+    private readonly onBlock;
+    private readonly pricing;
+    private ledger;
+    private totalSpend;
+    constructor(options?: ApiCostGuardOptions);
+    /**
+     * Estimate the cost of a request without checking limits.
+     * Returns null if the model is not in the pricing table.
+     */
+    estimateCost(model: string, inputTokens: number, outputTokens?: number): Decimal | null;
+    /**
+     * 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: string, estimatedInputTokens: number, estimatedOutputTokens?: number): PreflightResult;
+    /**
+     * 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: string, inputTokens: number, outputTokens: number, metadata?: Record<string, unknown>): Decimal;
+    /**
+     * 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,
+     *     }),
+     *   },
+     * );
+     */
+    wrap<T>(apiFn: () => Promise<T>, options: WrapOptions<T>): Promise<T | null>;
+    /**
+     * Get a snapshot of current spend and budget status.
+     */
+    getStats(): GuardStats;
+    /**
+     * Reset all spend records. Useful between test runs or billing periods.
+     */
+    reset(): void;
+    private getWindowSpend;
+    private pruneOldEntries;
+    private resolvePricing;
+    private handleBlock;
+    private validateOptions;
+}
+type AnyRequest = any;
+type AnyResponse = any;
+type NextFn = (err?: unknown) => void;
+export interface MiddlewareOptions {
+    /** Extract model name from the request. Default: req.body?.model */
+    getModel?: (req: AnyRequest) => string | undefined;
+    /** Extract estimated token counts. Default: req.body?.max_tokens for both */
+    getTokens?: (req: AnyRequest) => {
+        input: number;
+        output: number;
+    };
+}
+/**
+ * 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);
+ * });
+ */
+export declare function createMiddleware(guard: ApiCostGuard, options?: MiddlewareOptions): (req: AnyRequest, res: AnyResponse, next: NextFn) => void;
+export {};
+//# sourceMappingURL=guard.d.ts.map

package/dist/guard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"guard.d.ts","sourceRoot":"","sources":["../src/guard.ts"],"names":[],"mappings":"AAAA,OAAO,OAAO,MAAM,YAAY,CAAC;AAGjC,OAAO,KAAK,EACV,mBAAmB,EAGnB,eAAe,EAEf,UAAU,EACV,WAAW,EAEZ,MAAM,SAAS,CAAC;AAUjB,qBAAa,YAAY;IAEvB,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAuB;IACjD,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAuB;IACjD,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAiB;IACjD,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAwB;IACjD,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAa;IAG1C,OAAO,CAAC,QAAQ,CAAC,SAAS,CAA6C;IACvE,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAkD;IAG1E,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAa;IAGrC,OAAO,CAAC,MAAM,CAAyB;IACvC,OAAO,CAAC,UAAU,CAAiC;gBAIvC,OAAO,GAAE,mBAAwB;IAiB7C;;;OAGG;IACI,YAAY,CACjB,KAAK,EAAE,MAAM,EACb,WAAW,EAAE,MAAM,EACnB,YAAY,GAAE,MAAU,GACvB,OAAO,GAAG,IAAI;IAiBjB;;;;;OAKG;IACI,cAAc,CACnB,KAAK,EAAE,MAAM,EACb,oBAAoB,EAAE,MAAM,EAC5B,qBAAqB,GAAE,MAAU,GAChC,eAAe;IA+ClB;;;;;OAKG;IACI,WAAW,CAChB,KAAK,EAAE,MAAM,EACb,WAAW,EAAE,MAAM,EACnB,YAAY,EAAE,MAAM,EACpB,QAAQ,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM,GACrC,OAAO;IAqBV;;;;;;;;;;;;;;;;;;;OAmBG;IACU,IAAI,CAAC,CAAC,EACjB,KAAK,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EACvB,OAAO,EAAE,WAAW,CAAC,CAAC,CAAC,GACtB,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC;IAiCpB;;OAEG;IACI,QAAQ,IAAI,UAAU;IAmB7B;;OAEG;IACI,KAAK,IAAI,IAAI;IAOpB,OAAO,CAAC,cAAc;IAStB,OAAO,CAAC,eAAe;IAavB,OAAO,CAAC,cAAc;IActB,OAAO,CAAC,WAAW;IAmBnB,OAAO,CAAC,eAAe;CAiBxB;AAKD,KAAK,UAAU,GAAI,GAAG,CAAC;AAEvB,KAAK,WAAW,GAAG,GAAG,CAAC;AACvB,KAAK,MAAM,GAAQ,CAAC,GAAG,CAAC,EAAE,OAAO,KAAK,IAAI,CAAC;AAE3C,MAAM,WAAW,iBAAiB;IAChC,oEAAoE;IACpE,QAAQ,CAAC,EAAG,CAAC,GAAG,EAAE,UAAU,KAAK,MAAM,GAAG,SAAS,CAAC;IACpD,6EAA6E;IAC7E,SAAS,CAAC,EAAE,CAAC,GAAG,EAAE,UAAU,KAAK;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;CACpE;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,gBAAgB,CAC9B,KAAK,EAAI,YAAY,EACrB,OAAO,GAAE,iBAAsB,IAQvB,KAAK,UAAU,EAAE,KAAK,WAAW,EAAE,MAAM,MAAM,KAAG,IAAI,CAsC/D"}