@splashcodex/api-key-manager 4.1.0 → 5.0.2

package/README.md

@@ -1,9 +1,18 @@
-# @splashcodex/ApiKeyManager v4.1 — Mastermind Edition
+# @splashcodex/ApiKeyManager v5.0 — Ecosystem Edition
 
-> Universal API Key Rotation System with Resilience, Load Balancing, Semantic Caching & AI Gateway Features
+> Universal API Key Management Gateway with Provider Presets, Built-in Persistence, and Multi-Provider Vault.
 
 [![npm version](https://img.shields.io/npm/v/@splashcodex/ApiKeyManager)](https://www.npmjs.com/package/@splashcodex/ApiKeyManager)
 
+## New in v5.0 (Ecosystem Edition)
+
+- **Provider Presets** — One-line setup for `GeminiManager`, `OpenAIManager`, and `MultiManager`.
+- **Automatic Env Parsing** — Reads `GOOGLE_GEMINI_API_KEY`, `OPENAI_API_KEY`, etc. (supports JSON arrays and comma-separated strings).
+- **Built-in Persistence** — `FileStorage` (survives restarts) and `MemoryStorage` included.
+- **Singleton Pattern** — Thread-safe singletons with `getInstance()` and `Result<T>` pattern.
+- **Multi-Provider Vault** — Manage multiple providers (`gemini`, `openai`, `anthropic`) from a single entry point.
+- **Centralized API Gateway** — Built-in Fastify proxy server to centralize AI requests for multiple apps securely.
+
 ## Features
 
 - **Circuit Breaker** — Keys transition through `CLOSED → OPEN → HALF_OPEN → DEAD`
@@ -12,16 +21,9 @@
 - **`execute()` Wrapper** — Single method: get key → call → latency → retry → fallback
 - **Event Emitter** — Typed lifecycle hooks for monitoring & alerting
 - **Auto-Retry with Backoff** — Built-in retry loop with exponential backoff + jitter
-- **Request Timeout** — `AbortController`-based timeout per attempt
-- **Fallback Function** — Graceful degradation when all keys fail
-- **Provider Tagging** — Multi-provider routing (`openai`, `gemini`, etc.)
-- **Health Checks** — Periodic key validation and auto-recovery
-- **Bulkhead / Concurrency** — Limits concurrent `execute()` calls
-- **Semantic Cache** *(v4 NEW)* — Cosine-similarity cache with pluggable embeddings
-- **Streaming Support** *(v4.1 NEW)* — `executeStream()` with initial retry + cache replay
-- **Recursion Guard** *(v4 NEW)* — Prevents infinite loops when `getEmbedding` calls `execute()`
-- **State Persistence** — Survives restarts via pluggable storage
-- **100% Backward Compatible** — v1.x, v2.x, and v3.x code works without changes
+- **Semantic Cache** — Cosine-similarity cache with pluggable embeddings
+- **Streaming Support** — `executeStream()` with initial retry + cache replay
+- **100% Backward Compatible** — v1.x through v4.x code works without changes
 
 ## Installation
 
@@ -29,249 +31,175 @@
 npm install @splashcodex/api-key-manager
 ```
 
-## Quick Start
-
-```typescript
-import { ApiKeyManager } from '@splashcodex/api-key-manager';
-
-// Simple (v1/v2 compatible)
-const manager = new ApiKeyManager(['key1', 'key2', 'key3']);
-const key = manager.getKey();
-manager.markSuccess(key!);
-
-// v3+ — Full power
-const result = await manager.execute(
-  (key) => fetch(`https://api.example.com?key=${key}`),
-  { maxRetries: 3, timeoutMs: 5000 }
-);
+### 🚀 Auto-Scaffold (New!)
+The fastest way to get started is to run the `init` command in your project directory:
+```bash
+npx @splashcodex/api-key-manager init
 ```
+This will automatically create a `.env` template and a `demo.ts` file showing the Gemini Preset in action.
 
-## v4.0 — Semantic Cache (Mastermind Edition)
+## Quick Start (v5 Presets)
 
-Automatically cache API responses by semantic similarity. Identical or near-identical prompts return cached results without consuming API quota.
+The fastest way to get started in any CodeDex repository.
 
-```typescript
-import { ApiKeyManager } from '@splashcodex/api-key-manager';
+### Gemini Preset
+Reads `GOOGLE_GEMINI_API_KEY` or `GEMINI_API_KEY` from environment.
 
-const manager = new ApiKeyManager(['key1', 'key2'], {
-  semanticCache: {
-    threshold: 0.92,  // 92% cosine similarity to match
-    ttlMs: 86400000,  // 24-hour TTL (default)
-    getEmbedding: async (text) => {
-      // Your embedding function (e.g. OpenAI, Gemini, local model)
-      return await myEmbeddingModel.embed(text);
-    }
-  }
-});
+```typescript
+import { GeminiManager } from '@splashcodex/api-key-manager/presets/gemini';
 
-// First call → API hit, cached
-const r1 = await manager.execute(apiFn, { prompt: 'What is the weather?' });
+const result = GeminiManager.getInstance();
+if (!result.success) throw result.error;
 
-// Second call → Semantic Cache HIT (no API call)
-const r2 = await manager.execute(apiFn, { prompt: 'How is the weather today?' });
+const gemini = result.data;
+const response = await gemini.execute(async (key) => {
+    // result.data is the underlying ApiKeyManager
+    return await callGemini(key, "Hello!");
+});
 ```
 
-### v4.1 — Streaming Support
+### Centralized API Gateway (New!)
 
-Real-time response handling with the same resilience as `execute()`.
+Run a standalone proxy server that acts as a single point of entry for all your microservices or repositories. It centralizes key management, circuit breaking, and rate limiting across applications.
 
-```typescript
-const stream = await manager.executeStream(async (key) => {
-    return await gemini.generateContentStream({ prompt: "..." });
-}, { prompt: "..." });
+1. Install global/local and export your keys:
+```bash
+export GOOGLE_GEMINI_API_KEY="AIzaSy...1,AIzaSy...2"
+```
 
-for await (const chunk of stream) {
-    console.log(chunk.text()); // Zero-latency interaction
-}
+2. Start the gateway:
+```bash
+npm run gateway
+# Server runs on http://localhost:9000
 ```
 
-- **Smart Retries**: If the initial connection fails, it rotates keys and retries.
-- **Cache Replay**: Semantic cache accumulates stream chunks and replays the full stream on a cache hit.
-- **Event Driven**: Emits `executeSuccess`, `executeFailed`, and `retry` just like the standard wrapper.
+3. Call the proxy from ANY language without managing keys in the client app:
+```bash
+curl -X POST http://localhost:9000/v1/generate \
+  -H "Content-Type: application/json" \
+  -d '{"provider": "gemini", "prompt": "Hello!"}'
+```
+Route supports both `/v1/generate` (Standard JSON) and `/v1/stream` (Server-Sent Events). Monitoring available at `/v1/health` and `/v1/providers`.
 
-> **Recursion Guard**: If your `getEmbedding` callback internally calls `execute()`,
-> the cache automatically skips on nested calls to prevent infinite recursion.
+---
 
-## execute() Wrapper
+### Multi-Provider Vault
 
-Wraps the entire lifecycle into one method:
+Manage ALL your provider keys across your system from one pool.Perfect for gateways or complex bots handling multiple models.
 
 ```typescript
-const manager = new ApiKeyManager(keys, {
-  storage: localStorage,
-  strategy: new WeightedStrategy(),
-  fallbackFn: () => cachedResponse,
-  concurrency: 10
-});
-
-const result = await manager.execute(
-  async (key, signal) => {
-    const res = await fetch(url, { headers: { 'x-api-key': key }, signal });
-    return res.json();
-  },
-  { maxRetries: 3, timeoutMs: 10000 }
-);
-// Handles: key selection → cache → timeout → retry → fallback → latency tracking
-```
-
-## Event Emitter
+import { MultiManager } from '@splashcodex/api-key-manager/presets/multi';
 
-Monitor every state change:
+const vault = MultiManager.getInstance({
+    providers: {
+        gemini: { envKeys: ['GOOGLE_GEMINI_API_KEY'] },
+        openai: { envKeys: ['OPENAI_API_KEY'] }
+    }
+}).data!;
 
-```typescript
-manager.on('keyDead', (key) => alertTeam(`Key ${key} permanently dead`));
-manager.on('circuitOpen', (key) => metrics.increment('circuit_opens'));
-manager.on('keyRecovered', (key) => log(`Key ${key} recovered`));
-manager.on('retry', (key, attempt, delay) => log(`Retry #${attempt} in ${delay}ms`));
-manager.on('fallback', (reason) => log(`Fallback triggered: ${reason}`));
-manager.on('allKeysExhausted', () => alert('No healthy keys!'));
-manager.on('bulkheadRejected', () => metrics.increment('rejected'));
-manager.on('healthCheckPassed', (key) => log(`${key} healthy`));
-manager.on('healthCheckFailed', (key, err) => log(`${key} unhealthy`));
+// Route by provider
+const res = await vault.execute(fn, { provider: 'gemini' });
 ```
 
-## Load Balancing Strategies
+---
 
-### Weighted (Cost Optimization)
+## v5.0 — Architecture & Persistence
 
-```typescript
-import { ApiKeyManager, WeightedStrategy } from '@splashcodex/api-key-manager';
-
-const manager = new ApiKeyManager(
-  [
-    { key: 'free-key-1', weight: 1.0 },
-    { key: 'free-key-2', weight: 1.0 },
-    { key: 'paid-backup', weight: 0.1 },
-  ],
-  { strategy: new WeightedStrategy() }
-);
-```
-
-### Latency (Performance)
+### Built-in Persistence
+State (cooling down keys, dead keys) now survives application restarts by default.
 
 ```typescript
-import { ApiKeyManager, LatencyStrategy } from '@splashcodex/api-key-manager';
+import { FileStorage } from '@splashcodex/api-key-manager/persistence/file';
 
-const manager = new ApiKeyManager(keys, { strategy: new LatencyStrategy() });
-// After execute(), latency is tracked automatically
+const manager = new ApiKeyManager(keys, {
+    storage: new FileStorage({
+        filePath: './api_state.json'
+    })
+});
 ```
 
-## Provider Tagging
-
-Route requests to specific providers:
+### Subpath Imports
+To keep your bundles small, you can import only what you need:
 
 ```typescript
-const manager = new ApiKeyManager([
-  { key: 'sk-openai-1', weight: 1.0, provider: 'openai' },
-  { key: 'sk-openai-2', weight: 1.0, provider: 'openai' },
-  { key: 'AIza-gemini',  weight: 0.5, provider: 'gemini' },
-]);
-
-const openaiKey = manager.getKeyByProvider('openai');
-const geminiKey = manager.getKeyByProvider('gemini');
+import { GeminiManager } from '@splashcodex/api-key-manager/presets/gemini';
+import { FileStorage } from '@splashcodex/api-key-manager/persistence/file';
 ```
 
-## Health Checks
+---
+
+## v4.0 — Semantic Cache
 
-Proactively detect recovered keys:
+Automatically cache API responses by semantic similarity.
 
 ```typescript
-manager.setHealthCheck(async (key) => {
-  const res = await fetch(`https://api.openai.com/v1/models`, {
-    headers: { Authorization: `Bearer ${key}` }
-  });
-  return res.ok;
+const manager = new ApiKeyManager(['key1', 'key2'], {
+  semanticCache: {
+    threshold: 0.92,
+    getEmbedding: async (text) => await myModel.embed(text)
+  }
 });
 
-manager.startHealthChecks(60_000); // Check every 60 seconds
-// manager.stopHealthChecks();     // Stop when done
+// Cache HIT if prompt is semantically similar
+const r1 = await manager.execute(apiFn, { prompt: 'What is the weather?' });
+const r2 = await manager.execute(apiFn, { prompt: 'How is the weather today?' });
 ```
 
-## Error Handling
+### v4.1 — Streaming Support
+Real-time response handling with the same resilience as `execute()`.
 
 ```typescript
-try {
-  const result = await callApi(key);
-  manager.markSuccess(key, duration);
-} catch (error) {
-  const classification = manager.classifyError(error);
-  manager.markFailed(key, classification);
-
-  if (classification.retryable) {
-    const delay = manager.calculateBackoff(attempt);
-    await sleep(delay);
-  }
+const stream = await manager.executeStream(async (key) => {
+    return await gemini.generateContentStream({ prompt: "..." });
+}, { prompt: "..." });
+
+for await (const chunk of stream) {
+    console.log(chunk.text());
 }
 ```
 
-## API Reference
+---
 
-### Constructor
+## execute() Wrapper
+
+Wraps the entire lifecycle into one method:
 
 ```typescript
-// Legacy (v1/v2)
-new ApiKeyManager(keys, storage?, strategy?)
-
-// v3+ Options
-new ApiKeyManager(keys, {
-  storage?,        // Pluggable storage { getItem, setItem }
-  strategy?,       // LoadBalancingStrategy instance
-  fallbackFn?,     // () => any — called when all keys exhausted
-  concurrency?,    // Max concurrent execute() calls
-  semanticCache?,  // v4: { threshold, ttlMs, getEmbedding }
-})
+const result = await manager.execute(
+  async (key, signal) => {
+    const res = await fetch(url, { headers: { 'x-api-key': key }, signal });
+    return res.json();
+  },
+  { maxRetries: 3, timeoutMs: 10000 }
+);
 ```
 
-### Methods
+## API Reference
+
+### Presets
+
+| Class | Env Vars | Description |
+|-------|----------|-------------|
+| `GeminiManager` | `GOOGLE_GEMINI_API_KEY`, `GEMINI_API_KEY` | Gemini-optimized singleton |
+| `OpenAIManager` | `OPENAI_API_KEY` | OpenAI-optimized singleton |
+| `MultiManager` | Custom | Vault for multiple provider pools |
+
+### Persistence
+
+| Class | Description |
+|-------|-------------|
+| `FileStorage` | Persists to a JSON file (recommended for servers) |
+| `MemoryStorage` | In-memory only (best for serverless/short-lived) |
+
+### Core Methods
 
 | Method | Description |
 |--------|-------------|
-| `getKey()` | Returns best available key via strategy |
-| `getKeyByProvider(provider)` | Get key filtered by provider tag |
-| `markSuccess(key, durationMs?)` | Report success + optional latency |
-| `markFailed(key, classification)` | Report failure with error type |
-| `classifyError(error, finishReason?)` | Classify an error automatically |
-| `execute(fn, options?)` | Full lifecycle wrapper with retry/timeout |
-| `executeStream(fn, options?)` | Streaming lifecycle wrapper |
-| `calculateBackoff(attempt)` | Get backoff delay with jitter |
-| `getStats()` | Get pool health statistics |
-| `getKeyCount()` | Count of non-DEAD keys |
-| `setHealthCheck(fn)` | Set health check function |
-| `startHealthChecks(ms)` | Start periodic health checks |
-| `stopHealthChecks()` | Stop health checks |
-
-### Events
-
-| Event | Payload | Trigger |
-|-------|---------|---------|
-| `keyDead` | `key: string` | Key marked as permanently dead |
-| `circuitOpen` | `key: string` | Key circuit opened (cooldown) |
-| `circuitHalfOpen` | `key: string` | Key entering test phase |
-| `keyRecovered` | `key: string` | Key recovered from failure |
-| `fallback` | `reason: string` | Fallback function invoked |
-| `allKeysExhausted` | — | All keys dead, no fallback |
-| `retry` | `key, attempt, delayMs` | Retry attempt starting |
-| `executeSuccess` | `key, durationMs` | execute() completed successfully |
-| `executeFailed` | `key, error` | execute() attempt failed |
-| `bulkheadRejected` | — | Concurrency limit reached |
-| `healthCheckPassed` | `key: string` | Health check succeeded |
-| `healthCheckFailed` | `key, error` | Health check failed |
-
-### Custom Errors
-
-| Error | When |
-|-------|------|
-| `TimeoutError` | Request exceeded `timeoutMs` |
-| `BulkheadRejectionError` | Concurrency limit exceeded |
-| `AllKeysExhaustedError` | All keys dead, no fallback |
-
-### Strategies
-
-| Strategy | Algorithm | Best For |
-|----------|-----------|----------|
-| `StandardStrategy` | Least Failures → LRU | General use |
-| `WeightedStrategy` | Probabilistic by weight | Cost optimization |
-| `LatencyStrategy` | Lowest avg latency | Performance |
+| `execute(fn, opts)` | Standard wrapper |
+| `executeStream(fn, opts)` | Streaming wrapper |
+| `getStats()` | Get pool health |
+| `getKey()` | Manual key rotation |
+| `markFailed(key, err)` | Manual failure reporting |
 
 ## License
 

package/bin/cli.js

@@ -0,0 +1,50 @@
+#!/usr/bin/env node
+const fs = require('fs');
+const path = require('path');
+
+const args = process.argv.slice(2);
+const command = args[0];
+
+function printDocs() {
+    console.log(`\x1b[92m🌟 @splashcodex/api-key-manager v5.0\x1b[0m`);
+    console.log(`\x1b[96m📚 Documentation: https://www.npmjs.com/package/@splashcodex/ApiKeyManager\x1b[0m\n`);
+    console.log(`\x1b[93m🚀 Commands:\x1b[0m`);
+    console.log(`   npx @splashcodex/api-key-manager init   \x1b[90m# Scaffold a demo project in the current directory\x1b[0m`);
+    console.log(`\n\x1b[95m💡 Tip: Need help? Run init to see it in action!\x1b[0m\n`);
+}
+
+function initProject() {
+    const cwd = process.cwd();
+    const envPath = path.join(cwd, '.env');
+    const demoPath = path.join(cwd, 'demo.ts');
+
+    console.log(`\n\x1b[96m🚀 Initializing @splashcodex/api-key-manager environment...\x1b[0m\n`);
+
+    // Create .env
+    if (!fs.existsSync(envPath)) {
+        fs.writeFileSync(envPath, `GOOGLE_GEMINI_API_KEY="your_api_key_1,your_api_key_2"\nOPENAI_API_KEY="sk-..."\n`);
+        console.log(`\x1b[92m[✔] Created .env file\x1b[0m`);
+    } else {
+        console.log(`\x1b[90m[-] .env already exists. Remember to add GOOGLE_GEMINI_API_KEY!\x1b[0m`);
+    }
+
+    // Create demo.ts
+    if (!fs.existsSync(demoPath)) {
+        const tsCode = `import 'dotenv/config';\nimport { GeminiManager } from '@splashcodex/api-key-manager/presets/gemini';\n\nasync function main() {\n    console.log("Initialize GeminiManager...");\n    // Automatically parse GOOGLE_GEMINI_API_KEY from env\n    const result = GeminiManager.getInstance();\n    if (!result.success) {\n        console.error("Failed to initialize:", result.error);\n        return;\n    }\n    \n    const gemini = result.data;\n    \n    console.log("Executing resilient request...");\n    // Automatically handles key rotation and 429 quota limits\n    try {\n        const response = await gemini.execute(async (key) => {\n            console.log(\`[Network] Sending request with key: \${key.substring(0, 8)}...\`);\n            // Replace with actual fetch: await fetch(..., { headers: { 'x-goog-api-key': key } })\n            return "Success: Simulated API Response!";\n        });\n        console.log("Result:", response);\n    } catch (e) {\n        console.error("All keys exhausted or network failed.", e.message);\n    }\n}\n\nmain();\n`;
+        fs.writeFileSync(demoPath, tsCode);
+        console.log(`\x1b[92m[✔] Created demo.ts\x1b[0m`);
+    } else {
+        console.log(`\x1b[90m[-] demo.ts already exists.\x1b[0m`);
+    }
+
+    console.log(`\n\x1b[93m🎉 Setup Complete!\x1b[0m`);
+    console.log(`To run the demo:`);
+    console.log(`\x1b[36m   npm install dotenv\x1b[0m`);
+    console.log(`\x1b[36m   npx ts-node demo.ts\x1b[0m\n`);
+}
+
+if (command === 'init') {
+    initProject();
+} else {
+    printDocs();
+}

package/dist/index.d.ts

@@ -1,11 +1,16 @@
 /**
- * Universal ApiKeyManager v4.0 — Mastermind Edition
+ * Universal ApiKeyManager v5.0 — Ecosystem Edition
  * Implements: Rotation, Circuit Breaker, Persistence, Exponential Backoff, Strategies,
  *             Event Emitter, Fallback, execute(), Timeout, Auto-Retry, Provider Tags,
  *             Health Checks, Bulkhead/Concurrency
+ * NEW in v5.0: Provider Presets (GeminiManager, OpenAIManager, MultiManager),
+ *              Built-in Persistence (FileStorage, MemoryStorage)
  * Gemini-Specific: finishReason handling, Safety blocks, RECITATION detection
  */
 import { EventEmitter } from 'events';
+export { FileStorage } from './persistence/file';
+export type { FileStorageOptions } from './persistence/file';
+export { MemoryStorage } from './persistence/memory';
 export interface KeyState {
     key: string;
     failCount: number;
@@ -103,7 +108,7 @@ export declare class WeightedStrategy implements LoadBalancingStrategy {
     next(candidates: KeyState[]): KeyState | null;
 }
 /**
- * Latency Strategy: Pick lowest average latency
+ * Latency Strategy: Pick lowest average latency with LRU tie-break
  */
 export declare class LatencyStrategy implements LoadBalancingStrategy {
     next(candidates: KeyState[]): KeyState | null;

package/dist/index.js

@@ -1,14 +1,22 @@
 "use strict";
 /**
- * Universal ApiKeyManager v4.0 — Mastermind Edition
+ * Universal ApiKeyManager v5.0 — Ecosystem Edition
  * Implements: Rotation, Circuit Breaker, Persistence, Exponential Backoff, Strategies,
  *             Event Emitter, Fallback, execute(), Timeout, Auto-Retry, Provider Tags,
  *             Health Checks, Bulkhead/Concurrency
+ * NEW in v5.0: Provider Presets (GeminiManager, OpenAIManager, MultiManager),
+ *              Built-in Persistence (FileStorage, MemoryStorage)
  * Gemini-Specific: finishReason handling, Safety blocks, RECITATION detection
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.ApiKeyManager = exports.SemanticCache = exports.LatencyStrategy = exports.WeightedStrategy = exports.StandardStrategy = exports.AllKeysExhaustedError = exports.BulkheadRejectionError = exports.TimeoutError = void 0;
+exports.ApiKeyManager = exports.SemanticCache = exports.LatencyStrategy = exports.WeightedStrategy = exports.StandardStrategy = exports.AllKeysExhaustedError = exports.BulkheadRejectionError = exports.TimeoutError = exports.MemoryStorage = exports.FileStorage = void 0;
 const events_1 = require("events");
+// ─── Re-exports: Persistence ─────────────────────────────────────────────────
+// Persistence adapters can be imported from root or via subpath
+var file_1 = require("./persistence/file");
+Object.defineProperty(exports, "FileStorage", { enumerable: true, get: function () { return file_1.FileStorage; } });
+var memory_1 = require("./persistence/memory");
+Object.defineProperty(exports, "MemoryStorage", { enumerable: true, get: function () { return memory_1.MemoryStorage; } });
 // ─── Config ──────────────────────────────────────────────────────────────────
 const CONFIG = {
     MAX_CONSECUTIVE_FAILURES: 5,
@@ -83,13 +91,17 @@ class WeightedStrategy {
 }
 exports.WeightedStrategy = WeightedStrategy;
 /**
- * Latency Strategy: Pick lowest average latency
+ * Latency Strategy: Pick lowest average latency with LRU tie-break
  */
 class LatencyStrategy {
     next(candidates) {
         if (candidates.length === 0)
             return null;
-        candidates.sort((a, b) => a.averageLatency - b.averageLatency);
+        candidates.sort((a, b) => {
+            if (a.averageLatency !== b.averageLatency)
+                return a.averageLatency - b.averageLatency;
+            return a.lastUsed - b.lastUsed; // LRU tie-break
+        });
         return candidates[0];
     }
 }