ai-cost-controls 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ray Ockenfels
+
+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,222 @@
+# ai-cost-controls
+
+Framework-agnostic AI cost controls: per-user rate limiting, token budget tracking, and response caching with pluggable cache backends.
+
+**Zero runtime dependencies.** Bring your own cache backend (ioredis, @upstash/redis, Cloudflare KV, etc.) or use the built-in in-memory backend.
+
+## Install
+
+```bash
+npm install ai-cost-controls
+```
+
+## Quick Start
+
+```typescript
+import { CostControls } from 'ai-cost-controls';
+
+const controls = new CostControls({
+  config: {
+    rateLimitPerMinute: 20,
+    dailyTokenBudget: 100_000,
+  },
+});
+
+// Check rate limit before making an AI call
+if (!(await controls.checkRateLimit(userId))) {
+  throw new Error('Rate limited');
+}
+
+// Check cache first
+const cached = await controls.getCachedResponse(userId, userMessage);
+if (cached) return cached;
+
+// After getting AI response, cache it and track tokens
+await controls.cacheResponse(userId, userMessage, aiResponse);
+await controls.trackTokenUsage(userId, inputTokens, outputTokens);
+```
+
+## Configuration
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `rateLimitPerMinute` | `20` | Max requests per user per minute |
+| `cacheTtlSeconds` | `300` | Response cache TTL (5 minutes) |
+| `dailyTokenBudget` | `100,000` | Max tokens per user per day |
+| `monthlyTokenBudget` | `2,000,000` | Max tokens per user per month |
+
+### Static Config
+
+```typescript
+const controls = new CostControls({
+  config: {
+    rateLimitPerMinute: 10,
+    dailyTokenBudget: 50_000,
+  },
+});
+```
+
+### Dynamic Config (e.g., from database)
+
+```typescript
+const controls = new CostControls({
+  configLoader: async () => {
+    const row = await db.query('SELECT * FROM ai_config LIMIT 1');
+    return {
+      rateLimitPerMinute: row.rate_limit,
+      dailyTokenBudget: row.daily_budget,
+    };
+  },
+});
+```
+
+## Cache Backends
+
+The package ships with `InMemoryCacheBackend` (single-process only). For production multi-process or serverless deployments, implement the `CacheBackend` interface with your preferred client.
+
+### Interface
+
+```typescript
+interface CacheBackend {
+  get(key: string): Promise<string | null>;
+  set(key: string, value: string, ttlMs: number): Promise<void>;
+}
+```
+
+### ioredis
+
+```typescript
+import Redis from 'ioredis';
+import { CostControls, CacheBackend } from 'ai-cost-controls';
+
+const redis = new Redis();
+
+const redisBackend: CacheBackend = {
+  async get(key) {
+    return redis.get(key);
+  },
+  async set(key, value, ttlMs) {
+    await redis.set(key, value, 'PX', ttlMs);
+  },
+};
+
+const controls = new CostControls({ cacheBackend: redisBackend });
+```
+
+### @upstash/redis
+
+```typescript
+import { Redis } from '@upstash/redis';
+import { CostControls, CacheBackend } from 'ai-cost-controls';
+
+const redis = new Redis({ url: '...', token: '...' });
+
+const upstashBackend: CacheBackend = {
+  async get(key) {
+    return redis.get<string>(key);
+  },
+  async set(key, value, ttlMs) {
+    await redis.set(key, value, { px: ttlMs });
+  },
+};
+
+const controls = new CostControls({ cacheBackend: upstashBackend });
+```
+
+### Cloudflare KV
+
+```typescript
+import { CacheBackend } from 'ai-cost-controls';
+
+// In a Cloudflare Worker
+const kvBackend: CacheBackend = {
+  async get(key) {
+    return env.AI_CACHE.get(key);
+  },
+  async set(key, value, ttlMs) {
+    await env.AI_CACHE.put(key, value, { expirationTtl: Math.ceil(ttlMs / 1000) });
+  },
+};
+```
+
+## Framework Integration
+
+### Vercel AI SDK
+
+```typescript
+import { streamText } from 'ai';
+import { CostControls } from 'ai-cost-controls';
+
+const controls = new CostControls();
+
+async function chat(userId: string, message: string) {
+  if (!(await controls.checkRateLimit(userId))) {
+    return new Response('Rate limited', { status: 429 });
+  }
+
+  const cached = await controls.getCachedResponse(userId, message);
+  if (cached) return new Response(cached);
+
+  const result = await streamText({ model, messages: [{ role: 'user', content: message }] });
+  const text = await result.text;
+
+  await controls.cacheResponse(userId, message, text);
+  await controls.trackTokenUsage(userId, result.usage.promptTokens, result.usage.completionTokens);
+
+  return new Response(text);
+}
+```
+
+### Express Middleware
+
+```typescript
+import express from 'express';
+import { CostControls } from 'ai-cost-controls';
+
+const controls = new CostControls();
+const app = express();
+
+app.use('/ai', async (req, res, next) => {
+  const userId = req.user.id;
+
+  if (!(await controls.checkRateLimit(userId))) {
+    return res.status(429).json({ error: 'Rate limited' });
+  }
+
+  next();
+});
+```
+
+## API Reference
+
+### `new CostControls(options?: CostControlsOptions)`
+
+Creates a new instance.
+
+### `checkRateLimit(userId: string): Promise<boolean>`
+
+Returns `true` if the request is allowed, `false` if rate-limited.
+
+### `getCachedResponse(userId: string, message: string): Promise<string | null>`
+
+Returns a cached response or `null`. Cache keys are case-insensitive and trim-aware.
+
+### `cacheResponse(userId: string, message: string, response: string): Promise<void>`
+
+Stores a response in the cache.
+
+### `trackTokenUsage(userId: string, inputTokens: number, outputTokens: number): Promise<boolean>`
+
+Tracks token usage. Returns `false` if the daily or monthly budget would be exceeded.
+
+### `getTokenUsage(userId: string, period: 'daily' | 'monthly'): Promise<number>`
+
+Returns current token usage for the specified period.
+
+### `getConfig(): Promise<CostControlsConfig>`
+
+Returns the resolved configuration (static defaults merged with `configLoader` result).
+
+## License
+
+MIT

package/dist/cjs/cost-controls.js

@@ -0,0 +1,167 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CostControls = void 0;
+const node_crypto_1 = require("node:crypto");
+const in_memory_backend_1 = require("./in-memory-backend");
+const interfaces_1 = require("./interfaces");
+const NOOP_LOGGER = {
+    debug() { },
+    warn() { }
+};
+/**
+ * Framework-agnostic AI cost controls: rate limiting, response caching,
+ * and token budget tracking with pluggable cache backends.
+ */
+class CostControls {
+    constructor(options) {
+        /** In-memory rate limit store (always local — not backed by CacheBackend). */
+        this.rateLimits = new Map();
+        this.backend = options?.cacheBackend ?? new in_memory_backend_1.InMemoryCacheBackend();
+        this.configLoader = options?.configLoader;
+        this.logger = options?.logger ?? NOOP_LOGGER;
+        this.staticConfig = { ...interfaces_1.DEFAULT_CONFIG, ...options?.config };
+    }
+    /**
+     * Resolve config: static defaults merged with configLoader result (if provided).
+     */
+    async getConfig() {
+        if (!this.configLoader) {
+            return this.staticConfig;
+        }
+        const dynamic = await this.configLoader();
+        return {
+            ...this.staticConfig,
+            ...dynamic
+        };
+    }
+    /**
+     * Check and enforce per-user rate limiting.
+     * Returns true if the request is allowed, false if rate-limited.
+     */
+    async checkRateLimit(userId) {
+        const config = await this.getConfig();
+        const now = Date.now();
+        const windowMs = 60000;
+        let entry = this.rateLimits.get(userId);
+        if (!entry) {
+            entry = { timestamps: [] };
+            this.rateLimits.set(userId, entry);
+        }
+        entry.timestamps = entry.timestamps.filter((ts) => now - ts < windowMs);
+        if (entry.timestamps.length >= config.rateLimitPerMinute) {
+            return false;
+        }
+        entry.timestamps.push(now);
+        return true;
+    }
+    /**
+     * Get a cached response for a query, if one exists within the cache TTL.
+     */
+    async getCachedResponse(userId, message) {
+        const cacheKey = this.buildCacheKey(userId, message);
+        try {
+            const cached = await this.backend.get(cacheKey);
+            if (cached) {
+                this.logger.debug(`Cache hit for user ${userId}`);
+                return cached;
+            }
+        }
+        catch (error) {
+            this.logger.warn(`Cache read failed: ${error instanceof Error ? error.message : String(error)}`);
+        }
+        return null;
+    }
+    /**
+     * Store a response in the cache for future identical queries.
+     */
+    async cacheResponse(userId, message, response) {
+        const config = await this.getConfig();
+        const cacheKey = this.buildCacheKey(userId, message);
+        const ttlMs = config.cacheTtlSeconds * 1000;
+        try {
+            await this.backend.set(cacheKey, response, ttlMs);
+        }
+        catch (error) {
+            this.logger.warn(`Cache write failed: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    /**
+     * Track token usage for a user. Returns false if budget is exceeded.
+     */
+    async trackTokenUsage(userId, inputTokens, outputTokens) {
+        const config = await this.getConfig();
+        const dailyKey = this.buildTokenKey(userId, 'daily');
+        const monthlyKey = this.buildTokenKey(userId, 'monthly');
+        const totalTokens = inputTokens + outputTokens;
+        // Read current usage
+        let dailyUsage = 0;
+        let monthlyUsage = 0;
+        try {
+            const [dailyRaw, monthlyRaw] = await Promise.all([
+                this.backend.get(dailyKey),
+                this.backend.get(monthlyKey)
+            ]);
+            dailyUsage = dailyRaw ? parseInt(dailyRaw, 10) : 0;
+            monthlyUsage = monthlyRaw ? parseInt(monthlyRaw, 10) : 0;
+        }
+        catch (error) {
+            this.logger.warn(`Token usage read failed: ${error instanceof Error ? error.message : String(error)}`);
+        }
+        if (dailyUsage + totalTokens > config.dailyTokenBudget) {
+            this.logger.warn(`Daily token budget exceeded for user ${userId}`);
+            return false;
+        }
+        if (monthlyUsage + totalTokens > config.monthlyTokenBudget) {
+            this.logger.warn(`Monthly token budget exceeded for user ${userId}`);
+            return false;
+        }
+        // Write updated usage with appropriate TTLs
+        const endOfDay = new Date();
+        endOfDay.setHours(23, 59, 59, 999);
+        const dailyTtl = endOfDay.getTime() - Date.now();
+        const endOfMonth = new Date();
+        endOfMonth.setMonth(endOfMonth.getMonth() + 1, 1);
+        endOfMonth.setHours(0, 0, 0, 0);
+        const monthlyTtl = endOfMonth.getTime() - Date.now();
+        try {
+            await Promise.all([
+                this.backend.set(dailyKey, String(dailyUsage + totalTokens), dailyTtl),
+                this.backend.set(monthlyKey, String(monthlyUsage + totalTokens), monthlyTtl)
+            ]);
+        }
+        catch (error) {
+            this.logger.warn(`Token usage write failed: ${error instanceof Error ? error.message : String(error)}`);
+        }
+        return true;
+    }
+    /**
+     * Get current token usage for a user within the specified period.
+     */
+    async getTokenUsage(userId, period) {
+        const key = this.buildTokenKey(userId, period);
+        try {
+            const value = await this.backend.get(key);
+            return value ? parseInt(value, 10) : 0;
+        }
+        catch {
+            return 0;
+        }
+    }
+    // --- Private helpers ---
+    buildCacheKey(userId, message) {
+        const hash = (0, node_crypto_1.createHash)('sha256')
+            .update(message.toLowerCase().trim())
+            .digest('hex')
+            .substring(0, 16);
+        return `ai-cache:${userId}:${hash}`;
+    }
+    buildTokenKey(userId, period) {
+        const now = new Date();
+        if (period === 'daily') {
+            return `ai-tokens:${userId}:daily:${now.toISOString().slice(0, 10)}`;
+        }
+        return `ai-tokens:${userId}:monthly:${now.toISOString().slice(0, 7)}`;
+    }
+}
+exports.CostControls = CostControls;
+//# sourceMappingURL=cost-controls.js.map

package/dist/cjs/cost-controls.js.map

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

package/dist/cjs/in-memory-backend.js

@@ -0,0 +1,48 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.InMemoryCacheBackend = void 0;
+/**
+ * Zero-dependency in-memory cache backend.
+ * Suitable for single-process deployments. For multi-process or serverless,
+ * provide a Redis/KV CacheBackend instead.
+ */
+class InMemoryCacheBackend {
+    constructor(maxSize = 10000) {
+        this.store = new Map();
+        this.maxSize = maxSize;
+    }
+    async get(key) {
+        const entry = this.store.get(key);
+        if (!entry) {
+            return null;
+        }
+        if (entry.expiresAt <= Date.now()) {
+            this.store.delete(key);
+            return null;
+        }
+        return entry.value;
+    }
+    async set(key, value, ttlMs) {
+        // Evict oldest entries if at capacity
+        if (this.store.size >= this.maxSize && !this.store.has(key)) {
+            const firstKey = this.store.keys().next().value;
+            if (firstKey !== undefined) {
+                this.store.delete(firstKey);
+            }
+        }
+        this.store.set(key, {
+            value,
+            expiresAt: Date.now() + ttlMs
+        });
+    }
+    /** Number of entries currently stored (including expired). */
+    get size() {
+        return this.store.size;
+    }
+    /** Remove all entries. */
+    clear() {
+        this.store.clear();
+    }
+}
+exports.InMemoryCacheBackend = InMemoryCacheBackend;
+//# sourceMappingURL=in-memory-backend.js.map

package/dist/cjs/in-memory-backend.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"in-memory-backend.js","sourceRoot":"","sources":["../../src/in-memory-backend.ts"],"names":[],"mappings":";;;AAEA;;;;GAIG;AACH,MAAa,oBAAoB;IAI/B,YAAY,OAAO,GAAG,KAAM;QAHX,UAAK,GAAG,IAAI,GAAG,EAAgD,CAAC;QAI/E,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;IACzB,CAAC;IAED,KAAK,CAAC,GAAG,CAAC,GAAW;QACnB,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QAElC,IAAI,CAAC,KAAK,EAAE,CAAC;YACX,OAAO,IAAI,CAAC;QACd,CAAC;QAED,IAAI,KAAK,CAAC,SAAS,IAAI,IAAI,CAAC,GAAG,EAAE,EAAE,CAAC;YAClC,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;YACvB,OAAO,IAAI,CAAC;QACd,CAAC;QAED,OAAO,KAAK,CAAC,KAAK,CAAC;IACrB,CAAC;IAED,KAAK,CAAC,GAAG,CAAC,GAAW,EAAE,KAAa,EAAE,KAAa;QACjD,sCAAsC;QACtC,IAAI,IAAI,CAAC,KAAK,CAAC,IAAI,IAAI,IAAI,CAAC,OAAO,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC;YAC5D,MAAM,QAAQ,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC;YAChD,IAAI,QAAQ,KAAK,SAAS,EAAE,CAAC;gBAC3B,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;YAC9B,CAAC;QACH,CAAC;QAED,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,EAAE;YAClB,KAAK;YACL,SAAS,EAAE,IAAI,CAAC,GAAG,EAAE,GAAG,KAAK;SAC9B,CAAC,CAAC;IACL,CAAC;IAED,8DAA8D;IAC9D,IAAI,IAAI;QACN,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC;IACzB,CAAC;IAED,0BAA0B;IAC1B,KAAK;QACH,IAAI,CAAC,KAAK,CAAC,KAAK,EAAE,CAAC;IACrB,CAAC;CACF;AA/CD,oDA+CC"}

package/dist/cjs/index.js

@@ -0,0 +1,10 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_CONFIG = exports.InMemoryCacheBackend = exports.CostControls = void 0;
+var cost_controls_1 = require("./cost-controls");
+Object.defineProperty(exports, "CostControls", { enumerable: true, get: function () { return cost_controls_1.CostControls; } });
+var in_memory_backend_1 = require("./in-memory-backend");
+Object.defineProperty(exports, "InMemoryCacheBackend", { enumerable: true, get: function () { return in_memory_backend_1.InMemoryCacheBackend; } });
+var interfaces_1 = require("./interfaces");
+Object.defineProperty(exports, "DEFAULT_CONFIG", { enumerable: true, get: function () { return interfaces_1.DEFAULT_CONFIG; } });
+//# sourceMappingURL=index.js.map

package/dist/cjs/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":";;;AAAA,iDAA+C;AAAtC,6GAAA,YAAY,OAAA;AACrB,yDAA2D;AAAlD,yHAAA,oBAAoB,OAAA;AAC7B,2CAMsB;AAFpB,4GAAA,cAAc,OAAA"}

package/dist/cjs/interfaces.js

@@ -0,0 +1,11 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_CONFIG = void 0;
+/** Default configuration values. */
+exports.DEFAULT_CONFIG = {
+    rateLimitPerMinute: 20,
+    cacheTtlSeconds: 300,
+    dailyTokenBudget: 100000,
+    monthlyTokenBudget: 2000000
+};
+//# sourceMappingURL=interfaces.js.map

package/dist/cjs/interfaces.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"interfaces.js","sourceRoot":"","sources":["../../src/interfaces.ts"],"names":[],"mappings":";;;AAmCA,oCAAoC;AACvB,QAAA,cAAc,GAAuB;IAChD,kBAAkB,EAAE,EAAE;IACtB,eAAe,EAAE,GAAG;IACpB,gBAAgB,EAAE,MAAO;IACzB,kBAAkB,EAAE,OAAS;CAC9B,CAAC"}

package/dist/esm/cost-controls.js

@@ -0,0 +1,163 @@
+import { createHash } from 'node:crypto';
+import { InMemoryCacheBackend } from './in-memory-backend';
+import { DEFAULT_CONFIG } from './interfaces';
+const NOOP_LOGGER = {
+    debug() { },
+    warn() { }
+};
+/**
+ * Framework-agnostic AI cost controls: rate limiting, response caching,
+ * and token budget tracking with pluggable cache backends.
+ */
+export class CostControls {
+    constructor(options) {
+        /** In-memory rate limit store (always local — not backed by CacheBackend). */
+        this.rateLimits = new Map();
+        this.backend = options?.cacheBackend ?? new InMemoryCacheBackend();
+        this.configLoader = options?.configLoader;
+        this.logger = options?.logger ?? NOOP_LOGGER;
+        this.staticConfig = { ...DEFAULT_CONFIG, ...options?.config };
+    }
+    /**
+     * Resolve config: static defaults merged with configLoader result (if provided).
+     */
+    async getConfig() {
+        if (!this.configLoader) {
+            return this.staticConfig;
+        }
+        const dynamic = await this.configLoader();
+        return {
+            ...this.staticConfig,
+            ...dynamic
+        };
+    }
+    /**
+     * Check and enforce per-user rate limiting.
+     * Returns true if the request is allowed, false if rate-limited.
+     */
+    async checkRateLimit(userId) {
+        const config = await this.getConfig();
+        const now = Date.now();
+        const windowMs = 60000;
+        let entry = this.rateLimits.get(userId);
+        if (!entry) {
+            entry = { timestamps: [] };
+            this.rateLimits.set(userId, entry);
+        }
+        entry.timestamps = entry.timestamps.filter((ts) => now - ts < windowMs);
+        if (entry.timestamps.length >= config.rateLimitPerMinute) {
+            return false;
+        }
+        entry.timestamps.push(now);
+        return true;
+    }
+    /**
+     * Get a cached response for a query, if one exists within the cache TTL.
+     */
+    async getCachedResponse(userId, message) {
+        const cacheKey = this.buildCacheKey(userId, message);
+        try {
+            const cached = await this.backend.get(cacheKey);
+            if (cached) {
+                this.logger.debug(`Cache hit for user ${userId}`);
+                return cached;
+            }
+        }
+        catch (error) {
+            this.logger.warn(`Cache read failed: ${error instanceof Error ? error.message : String(error)}`);
+        }
+        return null;
+    }
+    /**
+     * Store a response in the cache for future identical queries.
+     */
+    async cacheResponse(userId, message, response) {
+        const config = await this.getConfig();
+        const cacheKey = this.buildCacheKey(userId, message);
+        const ttlMs = config.cacheTtlSeconds * 1000;
+        try {
+            await this.backend.set(cacheKey, response, ttlMs);
+        }
+        catch (error) {
+            this.logger.warn(`Cache write failed: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    /**
+     * Track token usage for a user. Returns false if budget is exceeded.
+     */
+    async trackTokenUsage(userId, inputTokens, outputTokens) {
+        const config = await this.getConfig();
+        const dailyKey = this.buildTokenKey(userId, 'daily');
+        const monthlyKey = this.buildTokenKey(userId, 'monthly');
+        const totalTokens = inputTokens + outputTokens;
+        // Read current usage
+        let dailyUsage = 0;
+        let monthlyUsage = 0;
+        try {
+            const [dailyRaw, monthlyRaw] = await Promise.all([
+                this.backend.get(dailyKey),
+                this.backend.get(monthlyKey)
+            ]);
+            dailyUsage = dailyRaw ? parseInt(dailyRaw, 10) : 0;
+            monthlyUsage = monthlyRaw ? parseInt(monthlyRaw, 10) : 0;
+        }
+        catch (error) {
+            this.logger.warn(`Token usage read failed: ${error instanceof Error ? error.message : String(error)}`);
+        }
+        if (dailyUsage + totalTokens > config.dailyTokenBudget) {
+            this.logger.warn(`Daily token budget exceeded for user ${userId}`);
+            return false;
+        }
+        if (monthlyUsage + totalTokens > config.monthlyTokenBudget) {
+            this.logger.warn(`Monthly token budget exceeded for user ${userId}`);
+            return false;
+        }
+        // Write updated usage with appropriate TTLs
+        const endOfDay = new Date();
+        endOfDay.setHours(23, 59, 59, 999);
+        const dailyTtl = endOfDay.getTime() - Date.now();
+        const endOfMonth = new Date();
+        endOfMonth.setMonth(endOfMonth.getMonth() + 1, 1);
+        endOfMonth.setHours(0, 0, 0, 0);
+        const monthlyTtl = endOfMonth.getTime() - Date.now();
+        try {
+            await Promise.all([
+                this.backend.set(dailyKey, String(dailyUsage + totalTokens), dailyTtl),
+                this.backend.set(monthlyKey, String(monthlyUsage + totalTokens), monthlyTtl)
+            ]);
+        }
+        catch (error) {
+            this.logger.warn(`Token usage write failed: ${error instanceof Error ? error.message : String(error)}`);
+        }
+        return true;
+    }
+    /**
+     * Get current token usage for a user within the specified period.
+     */
+    async getTokenUsage(userId, period) {
+        const key = this.buildTokenKey(userId, period);
+        try {
+            const value = await this.backend.get(key);
+            return value ? parseInt(value, 10) : 0;
+        }
+        catch {
+            return 0;
+        }
+    }
+    // --- Private helpers ---
+    buildCacheKey(userId, message) {
+        const hash = createHash('sha256')
+            .update(message.toLowerCase().trim())
+            .digest('hex')
+            .substring(0, 16);
+        return `ai-cache:${userId}:${hash}`;
+    }
+    buildTokenKey(userId, period) {
+        const now = new Date();
+        if (period === 'daily') {
+            return `ai-tokens:${userId}:daily:${now.toISOString().slice(0, 10)}`;
+        }
+        return `ai-tokens:${userId}:monthly:${now.toISOString().slice(0, 7)}`;
+    }
+}
+//# sourceMappingURL=cost-controls.js.map

package/dist/esm/cost-controls.js.map

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

package/dist/esm/in-memory-backend.js

@@ -0,0 +1,44 @@
+/**
+ * Zero-dependency in-memory cache backend.
+ * Suitable for single-process deployments. For multi-process or serverless,
+ * provide a Redis/KV CacheBackend instead.
+ */
+export class InMemoryCacheBackend {
+    constructor(maxSize = 10000) {
+        this.store = new Map();
+        this.maxSize = maxSize;
+    }
+    async get(key) {
+        const entry = this.store.get(key);
+        if (!entry) {
+            return null;
+        }
+        if (entry.expiresAt <= Date.now()) {
+            this.store.delete(key);
+            return null;
+        }
+        return entry.value;
+    }
+    async set(key, value, ttlMs) {
+        // Evict oldest entries if at capacity
+        if (this.store.size >= this.maxSize && !this.store.has(key)) {
+            const firstKey = this.store.keys().next().value;
+            if (firstKey !== undefined) {
+                this.store.delete(firstKey);
+            }
+        }
+        this.store.set(key, {
+            value,
+            expiresAt: Date.now() + ttlMs
+        });
+    }
+    /** Number of entries currently stored (including expired). */
+    get size() {
+        return this.store.size;
+    }
+    /** Remove all entries. */
+    clear() {
+        this.store.clear();
+    }
+}
+//# sourceMappingURL=in-memory-backend.js.map

package/dist/esm/in-memory-backend.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"in-memory-backend.js","sourceRoot":"","sources":["../../src/in-memory-backend.ts"],"names":[],"mappings":"AAEA;;;;GAIG;AACH,MAAM,OAAO,oBAAoB;IAI/B,YAAY,OAAO,GAAG,KAAM;QAHX,UAAK,GAAG,IAAI,GAAG,EAAgD,CAAC;QAI/E,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;IACzB,CAAC;IAED,KAAK,CAAC,GAAG,CAAC,GAAW;QACnB,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QAElC,IAAI,CAAC,KAAK,EAAE,CAAC;YACX,OAAO,IAAI,CAAC;QACd,CAAC;QAED,IAAI,KAAK,CAAC,SAAS,IAAI,IAAI,CAAC,GAAG,EAAE,EAAE,CAAC;YAClC,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;YACvB,OAAO,IAAI,CAAC;QACd,CAAC;QAED,OAAO,KAAK,CAAC,KAAK,CAAC;IACrB,CAAC;IAED,KAAK,CAAC,GAAG,CAAC,GAAW,EAAE,KAAa,EAAE,KAAa;QACjD,sCAAsC;QACtC,IAAI,IAAI,CAAC,KAAK,CAAC,IAAI,IAAI,IAAI,CAAC,OAAO,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC;YAC5D,MAAM,QAAQ,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC;YAChD,IAAI,QAAQ,KAAK,SAAS,EAAE,CAAC;gBAC3B,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;YAC9B,CAAC;QACH,CAAC;QAED,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,EAAE;YAClB,KAAK;YACL,SAAS,EAAE,IAAI,CAAC,GAAG,EAAE,GAAG,KAAK;SAC9B,CAAC,CAAC;IACL,CAAC;IAED,8DAA8D;IAC9D,IAAI,IAAI;QACN,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC;IACzB,CAAC;IAED,0BAA0B;IAC1B,KAAK;QACH,IAAI,CAAC,KAAK,CAAC,KAAK,EAAE,CAAC;IACrB,CAAC;CACF"}

package/dist/esm/index.js

@@ -0,0 +1,4 @@
+export { CostControls } from './cost-controls';
+export { InMemoryCacheBackend } from './in-memory-backend';
+export { DEFAULT_CONFIG } from './interfaces';
+//# sourceMappingURL=index.js.map

package/dist/esm/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAC/C,OAAO,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AAC3D,OAAO,EAIL,cAAc,EAEf,MAAM,cAAc,CAAC"}

package/dist/esm/interfaces.js

@@ -0,0 +1,8 @@
+/** Default configuration values. */
+export const DEFAULT_CONFIG = {
+    rateLimitPerMinute: 20,
+    cacheTtlSeconds: 300,
+    dailyTokenBudget: 100000,
+    monthlyTokenBudget: 2000000
+};
+//# sourceMappingURL=interfaces.js.map

package/dist/esm/interfaces.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"interfaces.js","sourceRoot":"","sources":["../../src/interfaces.ts"],"names":[],"mappings":"AAmCA,oCAAoC;AACpC,MAAM,CAAC,MAAM,cAAc,GAAuB;IAChD,kBAAkB,EAAE,EAAE;IACtB,eAAe,EAAE,GAAG;IACpB,gBAAgB,EAAE,MAAO;IACzB,kBAAkB,EAAE,OAAS;CAC9B,CAAC"}

package/dist/types/cost-controls.d.ts

@@ -0,0 +1,42 @@
+import { CostControlsConfig, CostControlsOptions } from './interfaces';
+/**
+ * Framework-agnostic AI cost controls: rate limiting, response caching,
+ * and token budget tracking with pluggable cache backends.
+ */
+export declare class CostControls {
+    private readonly backend;
+    private readonly staticConfig;
+    private readonly configLoader?;
+    private readonly logger;
+    /** In-memory rate limit store (always local — not backed by CacheBackend). */
+    private readonly rateLimits;
+    constructor(options?: CostControlsOptions);
+    /**
+     * Resolve config: static defaults merged with configLoader result (if provided).
+     */
+    getConfig(): Promise<CostControlsConfig>;
+    /**
+     * Check and enforce per-user rate limiting.
+     * Returns true if the request is allowed, false if rate-limited.
+     */
+    checkRateLimit(userId: string): Promise<boolean>;
+    /**
+     * Get a cached response for a query, if one exists within the cache TTL.
+     */
+    getCachedResponse(userId: string, message: string): Promise<string | null>;
+    /**
+     * Store a response in the cache for future identical queries.
+     */
+    cacheResponse(userId: string, message: string, response: string): Promise<void>;
+    /**
+     * Track token usage for a user. Returns false if budget is exceeded.
+     */
+    trackTokenUsage(userId: string, inputTokens: number, outputTokens: number): Promise<boolean>;
+    /**
+     * Get current token usage for a user within the specified period.
+     */
+    getTokenUsage(userId: string, period: 'daily' | 'monthly'): Promise<number>;
+    private buildCacheKey;
+    private buildTokenKey;
+}
+//# sourceMappingURL=cost-controls.d.ts.map

package/dist/types/cost-controls.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cost-controls.d.ts","sourceRoot":"","sources":["../../src/cost-controls.ts"],"names":[],"mappings":"AAGA,OAAO,EAEL,kBAAkB,EAClB,mBAAmB,EAGpB,MAAM,cAAc,CAAC;AAWtB;;;GAGG;AACH,qBAAa,YAAY;IACvB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAe;IACvC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAqB;IAClD,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAC,CAA6C;IAC3E,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAEhC,8EAA8E;IAC9E,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAqC;gBAEpD,OAAO,CAAC,EAAE,mBAAmB;IAOzC;;OAEG;IACG,SAAS,IAAI,OAAO,CAAC,kBAAkB,CAAC;IAa9C;;;OAGG;IACG,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAsBtD;;OAEG;IACG,iBAAiB,CACrB,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,MAAM,GACd,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;IAmBzB;;OAEG;IACG,aAAa,CACjB,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,IAAI,CAAC;IAchB;;OAEG;IACG,eAAe,CACnB,MAAM,EAAE,MAAM,EACd,WAAW,EAAE,MAAM,EACnB,YAAY,EAAE,MAAM,GACnB,OAAO,CAAC,OAAO,CAAC;IA6DnB;;OAEG;IACG,aAAa,CACjB,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,OAAO,GAAG,SAAS,GAC1B,OAAO,CAAC,MAAM,CAAC;IAalB,OAAO,CAAC,aAAa;IASrB,OAAO,CAAC,aAAa;CAYtB"}

package/dist/types/in-memory-backend.d.ts

@@ -0,0 +1,18 @@
+import { CacheBackend } from './interfaces';
+/**
+ * Zero-dependency in-memory cache backend.
+ * Suitable for single-process deployments. For multi-process or serverless,
+ * provide a Redis/KV CacheBackend instead.
+ */
+export declare class InMemoryCacheBackend implements CacheBackend {
+    private readonly store;
+    private readonly maxSize;
+    constructor(maxSize?: number);
+    get(key: string): Promise<string | null>;
+    set(key: string, value: string, ttlMs: number): Promise<void>;
+    /** Number of entries currently stored (including expired). */
+    get size(): number;
+    /** Remove all entries. */
+    clear(): void;
+}
+//# sourceMappingURL=in-memory-backend.d.ts.map

package/dist/types/in-memory-backend.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"in-memory-backend.d.ts","sourceRoot":"","sources":["../../src/in-memory-backend.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAE5C;;;;GAIG;AACH,qBAAa,oBAAqB,YAAW,YAAY;IACvD,OAAO,CAAC,QAAQ,CAAC,KAAK,CAA2D;IACjF,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;gBAErB,OAAO,SAAS;IAItB,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;IAexC,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAenE,8DAA8D;IAC9D,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED,0BAA0B;IAC1B,KAAK,IAAI,IAAI;CAGd"}

package/dist/types/index.d.ts

@@ -0,0 +1,4 @@
+export { CostControls } from './cost-controls';
+export { InMemoryCacheBackend } from './in-memory-backend';
+export { CacheBackend, CostControlsConfig, CostControlsOptions, DEFAULT_CONFIG, Logger } from './interfaces';
+//# sourceMappingURL=index.d.ts.map

package/dist/types/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,MAAM,iBAAiB,CAAC;AAC/C,OAAO,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AAC3D,OAAO,EACL,YAAY,EACZ,kBAAkB,EAClB,mBAAmB,EACnB,cAAc,EACd,MAAM,EACP,MAAM,cAAc,CAAC"}

package/dist/types/interfaces.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Pluggable cache backend interface.
+ * Implement with ioredis, node-redis, @upstash/redis, Cloudflare KV, etc.
+ */
+export interface CacheBackend {
+    get(key: string): Promise<string | null>;
+    set(key: string, value: string, ttlMs: number): Promise<void>;
+}
+/** Cost controls configuration values. */
+export interface CostControlsConfig {
+    rateLimitPerMinute: number;
+    cacheTtlSeconds: number;
+    dailyTokenBudget: number;
+    monthlyTokenBudget: number;
+}
+/** Minimal logger interface — bring your own logger. */
+export interface Logger {
+    debug(msg: string): void;
+    warn(msg: string): void;
+}
+/** Constructor options for CostControls. */
+export interface CostControlsOptions {
+    /** Static config overrides (merged with defaults). */
+    config?: Partial<CostControlsConfig>;
+    /** Cache backend — defaults to InMemoryCacheBackend. */
+    cacheBackend?: CacheBackend;
+    /** Dynamic config loader (e.g., from DB). Called on each operation. */
+    configLoader?: () => Promise<Partial<CostControlsConfig>>;
+    /** Optional logger. */
+    logger?: Logger;
+}
+/** Default configuration values. */
+export declare const DEFAULT_CONFIG: CostControlsConfig;
+//# sourceMappingURL=interfaces.d.ts.map

package/dist/types/interfaces.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"interfaces.d.ts","sourceRoot":"","sources":["../../src/interfaces.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,MAAM,WAAW,YAAY;IAC3B,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IACzC,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC/D;AAED,0CAA0C;AAC1C,MAAM,WAAW,kBAAkB;IACjC,kBAAkB,EAAE,MAAM,CAAC;IAC3B,eAAe,EAAE,MAAM,CAAC;IACxB,gBAAgB,EAAE,MAAM,CAAC;IACzB,kBAAkB,EAAE,MAAM,CAAC;CAC5B;AAED,wDAAwD;AACxD,MAAM,WAAW,MAAM;IACrB,KAAK,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;CACzB;AAED,4CAA4C;AAC5C,MAAM,WAAW,mBAAmB;IAClC,sDAAsD;IACtD,MAAM,CAAC,EAAE,OAAO,CAAC,kBAAkB,CAAC,CAAC;IACrC,wDAAwD;IACxD,YAAY,CAAC,EAAE,YAAY,CAAC;IAC5B,uEAAuE;IACvE,YAAY,CAAC,EAAE,MAAM,OAAO,CAAC,OAAO,CAAC,kBAAkB,CAAC,CAAC,CAAC;IAC1D,uBAAuB;IACvB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,oCAAoC;AACpC,eAAO,MAAM,cAAc,EAAE,kBAK5B,CAAC"}

package/package.json

@@ -0,0 +1,65 @@
+{
+  "name": "ai-cost-controls",
+  "version": "0.1.0",
+  "description": "Framework-agnostic AI cost controls: per-user rate limiting, token budget tracking, and response caching with pluggable backends.",
+  "keywords": [
+    "ai",
+    "cost-controls",
+    "rate-limiting",
+    "token-budget",
+    "caching",
+    "llm",
+    "openai",
+    "anthropic",
+    "vercel-ai-sdk"
+  ],
+  "license": "MIT",
+  "author": "Ray Ockenfels",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/roaming-rockenfels/ai-cost-controls.git"
+  },
+  "bugs": {
+    "url": "https://github.com/roaming-rockenfels/ai-cost-controls/issues"
+  },
+  "homepage": "https://github.com/roaming-rockenfels/ai-cost-controls#readme",
+  "main": "./dist/cjs/index.js",
+  "module": "./dist/esm/index.js",
+  "types": "./dist/types/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/types/index.d.ts",
+        "default": "./dist/esm/index.js"
+      },
+      "require": {
+        "types": "./dist/types/index.d.ts",
+        "default": "./dist/cjs/index.js"
+      }
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "npm run build:cjs && npm run build:esm && npm run build:types",
+    "build:cjs": "tsc -p tsconfig.cjs.json",
+    "build:esm": "tsc -p tsconfig.esm.json",
+    "build:types": "tsc -p tsconfig.types.json",
+    "test": "jest",
+    "lint": "eslint src/ tests/ --ext .ts",
+    "typecheck": "tsc --noEmit",
+    "prepare": "npm run build",
+    "prepublishOnly": "npm test"
+  },
+  "devDependencies": {
+    "@types/jest": "^29.5.0",
+    "@types/node": "^22.0.0",
+    "jest": "^29.7.0",
+    "ts-jest": "^29.1.0",
+    "ts-node": "^10.9.2",
+    "typescript": "^5.4.0"
+  }
+}