tokenfirewall 1.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 tokenfirewall
+
+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,312 @@
+# tokenfirewall
+
+Production-grade LLM cost enforcement middleware for Node.js with automatic tracking, budget management, and model discovery.
+
+## Features
+
+- **Multi-provider support**: OpenAI, Anthropic, Gemini, Grok, Kimi
+- **Budget enforcement**: Warn or block when limits exceeded
+- **Automatic cost tracking**: Real-time usage monitoring
+- **Model discovery**: List available models with context limits
+- **Context intelligence**: Budget-aware model selection
+- **Extensible**: Add custom providers easily
+- **Type-safe**: Full TypeScript support
+
+## Installation
+
+```bash
+npm install tokenfirewall
+```
+
+## Quick Start
+
+```javascript
+const { createBudgetGuard, patchGlobalFetch } = require("tokenfirewall");
+
+// Set budget limit
+createBudgetGuard({
+  monthlyLimit: 100,  // $100 USD
+  mode: "block"       // or "warn"
+});
+
+// Enable tracking
+patchGlobalFetch();
+
+// Use any LLM API - tokenfirewall tracks everything
+const response = await fetch("https://api.openai.com/v1/chat/completions", {
+  method: "POST",
+  headers: {
+    "Authorization": `Bearer ${process.env.OPENAI_API_KEY}`,
+    "Content-Type": "application/json"
+  },
+  body: JSON.stringify({
+    model: "gpt-4o",
+    messages: [{ role: "user", content: "Hello!" }]
+  })
+});
+```
+
+## API Reference
+
+### Budget Management
+
+#### `createBudgetGuard(options)`
+
+Initialize budget protection.
+
+```javascript
+createBudgetGuard({
+  monthlyLimit: 100,  // Required: monthly budget in USD
+  mode: "block"       // Optional: "block" (default) or "warn"
+});
+```
+
+#### `getBudgetStatus()`
+
+Get current budget information.
+
+```javascript
+const status = getBudgetStatus();
+// {
+//   totalSpent: 45.23,
+//   limit: 100,
+//   remaining: 54.77,
+//   percentageUsed: 45.23
+// }
+```
+
+#### `resetBudget()`
+
+Reset budget tracking (useful for monthly resets).
+
+```javascript
+resetBudget();
+```
+
+### Interception
+
+#### `patchGlobalFetch()`
+
+Intercept all fetch calls to track LLM usage.
+
+```javascript
+patchGlobalFetch();
+```
+
+#### `patchProvider(providerName)`
+
+Patch specific provider SDK (most use fetch internally).
+
+```javascript
+patchProvider("openai");
+```
+
+### Model Discovery
+
+#### `listAvailableModels(options)`
+
+Discover available models with context limits and budget usage.
+
+```javascript
+const models = await listAvailableModels({
+  provider: "openai",
+  apiKey: process.env.OPENAI_API_KEY,
+  includeBudgetUsage: true  // Optional
+});
+
+// Returns:
+// [
+//   {
+//     model: "gpt-4o",
+//     contextLimit: 128000,
+//     budgetUsagePercentage: 32.4
+//   }
+// ]
+```
+
+### Extensibility
+
+#### `registerAdapter(adapter)`
+
+Add custom LLM provider.
+
+```javascript
+registerAdapter({
+  name: "custom",
+  detect: (response) => /* detection logic */,
+  normalize: (response) => /* normalization logic */
+});
+```
+
+#### `registerPricing(provider, model, pricing)`
+
+Add custom pricing (per 1M tokens).
+
+```javascript
+registerPricing("custom", "model-name", {
+  input: 0.001,
+  output: 0.002
+});
+```
+
+#### `registerContextLimit(provider, model, contextLimit)`
+
+Add custom context limit.
+
+```javascript
+registerContextLimit("custom", "model-name", 131072);
+```
+
+## Supported Providers
+
+| Provider | Models | Context Limits |
+|----------|--------|----------------|
+| OpenAI | gpt-4o, gpt-4o-mini, gpt-3.5-turbo | 16K - 128K |
+| Anthropic | claude-3-5-sonnet, claude-3-5-haiku | 200K |
+| Gemini | gemini-2.5-pro, gemini-2.5-flash | 1M - 2M |
+| Grok | grok-beta, llama-3.3-70b | 131K |
+| Kimi | moonshot-v1-8k/32k/128k | 8K - 128K |
+
+## Usage Examples
+
+### Basic Usage
+
+```javascript
+const { createBudgetGuard, patchGlobalFetch } = require("tokenfirewall");
+
+createBudgetGuard({ monthlyLimit: 100, mode: "block" });
+patchGlobalFetch();
+
+// Make LLM calls as usual - automatically tracked
+```
+
+### Budget-Aware Model Selection
+
+```javascript
+const { listAvailableModels, getBudgetStatus } = require("tokenfirewall");
+
+const models = await listAvailableModels({
+  provider: "openai",
+  apiKey: process.env.OPENAI_API_KEY,
+  includeBudgetUsage: true
+});
+
+const status = getBudgetStatus();
+if (status.remaining < 10) {
+  console.log("Low budget - use cheaper models");
+  const cheapModels = models.filter(m => m.model.includes("mini"));
+}
+```
+
+### Context-Aware Routing
+
+```javascript
+const { listAvailableModels } = require("tokenfirewall");
+
+const models = await listAvailableModels({
+  provider: "openai",
+  apiKey: process.env.OPENAI_API_KEY
+});
+
+// Find model with sufficient context
+const suitable = models.find(m => 
+  m.contextLimit && m.contextLimit >= promptTokens * 1.5
+);
+```
+
+### Custom Provider
+
+```javascript
+const { registerAdapter, registerPricing } = require("tokenfirewall");
+
+// Add Ollama support
+registerAdapter({
+  name: "ollama",
+  detect: (response) => response?.model && response?.prompt_eval_count !== undefined,
+  normalize: (response) => ({
+    provider: "ollama",
+    model: response.model,
+    inputTokens: response.prompt_eval_count || 0,
+    outputTokens: response.eval_count || 0,
+    totalTokens: (response.prompt_eval_count || 0) + (response.eval_count || 0)
+  })
+});
+
+registerPricing("ollama", "llama3.2", { input: 0, output: 0 });
+```
+
+## TypeScript Support
+
+Full type definitions included:
+
+```typescript
+import { 
+  createBudgetGuard,
+  listAvailableModels,
+  BudgetGuardOptions,
+  ModelInfo,
+  ListModelsOptions
+} from "tokenfirewall";
+
+const options: BudgetGuardOptions = {
+  monthlyLimit: 100,
+  mode: "block"
+};
+
+const models: ModelInfo[] = await listAvailableModels({
+  provider: "openai",
+  apiKey: process.env.OPENAI_API_KEY!
+});
+```
+
+## Architecture
+
+```
+tokenfirewall/
+├── core/           # Provider-agnostic logic
+├── adapters/       # Provider-specific normalization
+├── interceptors/   # Request/response capture
+├── introspection/  # Model discovery
+└── registry/       # Adapter management
+```
+
+Adding a new provider requires only creating an adapter file - no core changes needed.
+
+## Examples
+
+See the `examples/` directory for complete working examples:
+
+- `basic-usage.js` - Simple OpenAI example
+- `multiple-providers.js` - Track multiple providers
+- `with-sdk.js` - Use with official SDKs
+- `model-discovery.js` - Model discovery
+- `context-aware-routing.js` - Intelligent routing
+- `custom-provider.js` - Add custom provider
+- `gemini-complete-demo.js` - Complete Gemini demo
+
+## Best Practices
+
+1. **Set realistic budgets**: Start with a conservative limit
+2. **Use warn mode in development**: Switch to block in production
+3. **Reset monthly**: Automate budget resets with cron
+4. **Cache model lists**: Model availability doesn't change often
+5. **Monitor logs**: Review structured JSON output regularly
+
+## Limitations
+
+- In-memory tracking only (no persistence in V1)
+- No streaming support yet
+- Context limits are static (not from provider APIs)
+- Budget tracking is local only (not provider-side billing)
+
+## License
+
+MIT
+
+## Contributing
+
+Contributions welcome! Please open an issue or PR.
+
+## Support
+
+For issues and questions, please open a GitHub issue.

package/dist/adapters/anthropic.d.ts

@@ -0,0 +1,5 @@
+import { ProviderAdapter } from "../core/types";
+/**
+ * Anthropic adapter - normalizes Anthropic API responses
+ */
+export declare const anthropicAdapter: ProviderAdapter;

package/dist/adapters/anthropic.js

@@ -0,0 +1,34 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.anthropicAdapter = void 0;
+/**
+ * Anthropic adapter - normalizes Anthropic API responses
+ */
+exports.anthropicAdapter = {
+    name: "anthropic",
+    detect(response) {
+        if (!response || typeof response !== "object") {
+            return false;
+        }
+        const resp = response;
+        return (typeof resp.id === "string" &&
+            resp.type === "message" &&
+            typeof resp.model === "string" &&
+            resp.usage !== undefined);
+    },
+    normalize(response) {
+        const resp = response;
+        if (!resp.usage || !resp.model) {
+            throw new Error("TokenFirewall: Invalid Anthropic response format");
+        }
+        const inputTokens = resp.usage.input_tokens ?? 0;
+        const outputTokens = resp.usage.output_tokens ?? 0;
+        return {
+            provider: "anthropic",
+            model: resp.model,
+            inputTokens,
+            outputTokens,
+            totalTokens: inputTokens + outputTokens,
+        };
+    },
+};

package/dist/adapters/gemini.d.ts

@@ -0,0 +1,5 @@
+import { ProviderAdapter } from "../core/types";
+/**
+ * Gemini adapter - normalizes Google Gemini API responses
+ */
+export declare const geminiAdapter: ProviderAdapter;

package/dist/adapters/gemini.js

@@ -0,0 +1,42 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.geminiAdapter = void 0;
+/**
+ * Gemini adapter - normalizes Google Gemini API responses
+ */
+exports.geminiAdapter = {
+    name: "gemini",
+    detect(response) {
+        if (!response || typeof response !== "object") {
+            return false;
+        }
+        const resp = response;
+        return (Array.isArray(resp.candidates) &&
+            resp.usageMetadata !== undefined &&
+            typeof resp.usageMetadata === "object");
+    },
+    normalize(response, request) {
+        const resp = response;
+        if (!resp.usageMetadata) {
+            throw new Error("TokenFirewall: Invalid Gemini response format");
+        }
+        // Extract model from request or use default
+        let model = "gemini-1.5-flash";
+        if (request && typeof request === "object") {
+            const req = request;
+            if (req.model) {
+                model = req.model;
+            }
+        }
+        if (resp.modelVersion) {
+            model = resp.modelVersion;
+        }
+        return {
+            provider: "gemini",
+            model,
+            inputTokens: resp.usageMetadata.promptTokenCount ?? 0,
+            outputTokens: resp.usageMetadata.candidatesTokenCount ?? 0,
+            totalTokens: resp.usageMetadata.totalTokenCount ?? 0,
+        };
+    },
+};

package/dist/adapters/grok.d.ts

@@ -0,0 +1,6 @@
+import { ProviderAdapter } from "../core/types";
+/**
+ * Grok adapter - normalizes Grok API responses
+ * Grok uses OpenAI-compatible format and supports both Grok and Llama models
+ */
+export declare const grokAdapter: ProviderAdapter;

package/dist/adapters/grok.js

@@ -0,0 +1,33 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.grokAdapter = void 0;
+/**
+ * Grok adapter - normalizes Grok API responses
+ * Grok uses OpenAI-compatible format and supports both Grok and Llama models
+ */
+exports.grokAdapter = {
+    name: "grok",
+    detect(response) {
+        if (!response || typeof response !== "object") {
+            return false;
+        }
+        const resp = response;
+        return (typeof resp.id === "string" &&
+            typeof resp.model === "string" &&
+            (resp.model.startsWith("grok") || resp.model.includes("llama")) &&
+            resp.usage !== undefined);
+    },
+    normalize(response) {
+        const resp = response;
+        if (!resp.usage || !resp.model) {
+            throw new Error("TokenFirewall: Invalid Grok response format");
+        }
+        return {
+            provider: "grok",
+            model: resp.model,
+            inputTokens: resp.usage.prompt_tokens ?? 0,
+            outputTokens: resp.usage.completion_tokens ?? 0,
+            totalTokens: resp.usage.total_tokens ?? 0,
+        };
+    },
+};

package/dist/adapters/index.d.ts

@@ -0,0 +1,5 @@
+import { ProviderAdapter } from "../core/types";
+/**
+ * Registry of all provider adapters
+ */
+export declare const adapters: ProviderAdapter[];

package/dist/adapters/index.js

@@ -0,0 +1,18 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.adapters = void 0;
+const openai_1 = require("./openai");
+const anthropic_1 = require("./anthropic");
+const gemini_1 = require("./gemini");
+const grok_1 = require("./grok");
+const kimi_1 = require("./kimi");
+/**
+ * Registry of all provider adapters
+ */
+exports.adapters = [
+    openai_1.openaiAdapter,
+    anthropic_1.anthropicAdapter,
+    gemini_1.geminiAdapter,
+    grok_1.grokAdapter,
+    kimi_1.kimiAdapter,
+];

package/dist/adapters/kimi.d.ts

@@ -0,0 +1,6 @@
+import { ProviderAdapter } from "../core/types";
+/**
+ * Kimi adapter - normalizes Kimi (Moonshot AI) API responses
+ * Kimi uses OpenAI-compatible format
+ */
+export declare const kimiAdapter: ProviderAdapter;

package/dist/adapters/kimi.js

@@ -0,0 +1,33 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.kimiAdapter = void 0;
+/**
+ * Kimi adapter - normalizes Kimi (Moonshot AI) API responses
+ * Kimi uses OpenAI-compatible format
+ */
+exports.kimiAdapter = {
+    name: "kimi",
+    detect(response) {
+        if (!response || typeof response !== "object") {
+            return false;
+        }
+        const resp = response;
+        return (typeof resp.id === "string" &&
+            typeof resp.model === "string" &&
+            resp.model.startsWith("moonshot") &&
+            resp.usage !== undefined);
+    },
+    normalize(response) {
+        const resp = response;
+        if (!resp.usage || !resp.model) {
+            throw new Error("TokenFirewall: Invalid Kimi response format");
+        }
+        return {
+            provider: "kimi",
+            model: resp.model,
+            inputTokens: resp.usage.prompt_tokens ?? 0,
+            outputTokens: resp.usage.completion_tokens ?? 0,
+            totalTokens: resp.usage.total_tokens ?? 0,
+        };
+    },
+};

package/dist/adapters/openai.d.ts

@@ -0,0 +1,5 @@
+import { ProviderAdapter } from "../core/types";
+/**
+ * OpenAI adapter - normalizes OpenAI API responses
+ */
+export declare const openaiAdapter: ProviderAdapter;

package/dist/adapters/openai.js

@@ -0,0 +1,46 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.openaiAdapter = void 0;
+/**
+ * OpenAI adapter - normalizes OpenAI API responses
+ */
+exports.openaiAdapter = {
+    name: "openai",
+    detect(response) {
+        if (!response || typeof response !== "object") {
+            return false;
+        }
+        const resp = response;
+        // Check basic OpenAI structure
+        const hasBasicStructure = (typeof resp.id === "string" &&
+            typeof resp.object === "string" &&
+            typeof resp.model === "string" &&
+            resp.usage !== undefined &&
+            typeof resp.usage === "object");
+        if (!hasBasicStructure) {
+            return false;
+        }
+        // Exclude Grok and Llama models (they have their own adapter)
+        if (resp.model && (resp.model.startsWith("grok") || resp.model.includes("llama"))) {
+            return false;
+        }
+        // Exclude Kimi models (they have their own adapter)
+        if (resp.model && resp.model.startsWith("moonshot")) {
+            return false;
+        }
+        return true;
+    },
+    normalize(response) {
+        const resp = response;
+        if (!resp.usage || !resp.model) {
+            throw new Error("TokenFirewall: Invalid OpenAI response format");
+        }
+        return {
+            provider: "openai",
+            model: resp.model,
+            inputTokens: resp.usage.prompt_tokens ?? 0,
+            outputTokens: resp.usage.completion_tokens ?? 0,
+            totalTokens: resp.usage.total_tokens ?? 0,
+        };
+    },
+};

package/dist/core/budgetManager.d.ts

@@ -0,0 +1,40 @@
+import { BudgetGuardOptions, BudgetStatus } from "./types";
+/**
+ * Budget manager - encapsulates all budget tracking state
+ */
+export declare class BudgetManager {
+    private totalSpent;
+    private limit;
+    private mode;
+    private trackingLock;
+    constructor(options: BudgetGuardOptions);
+    /**
+     * Track a new cost and enforce budget limits
+     * Uses locking to prevent race conditions
+     * @throws Error if budget exceeded in block mode
+     */
+    track(cost: number): Promise<void>;
+    /**
+     * Get current budget status
+     */
+    getStatus(): BudgetStatus;
+    /**
+     * Reset budget tracking (useful for monthly resets)
+     */
+    reset(): void;
+    /**
+     * Export budget state for persistence
+     */
+    exportState(): {
+        totalSpent: number;
+        limit: number;
+        mode: string;
+    };
+    /**
+     * Import budget state from persistence
+     * Validates state before importing
+     */
+    importState(state: {
+        totalSpent: number;
+    }): void;
+}