@splashcodex/api-key-manager 2.0.0 → 4.0.0

package/README.md

@@ -1,19 +1,26 @@
-# @splashcodex/api-key-manager
+# @splashcodex/ApiKeyManager v4.0 — Mastermind Edition
 
-> Universal API Key Rotation System with Load Balancing Strategies
+> Universal API Key Rotation System with Resilience, Load Balancing, Semantic Caching & AI Gateway Features
 
-[![npm version](https://img.shields.io/npm/v/@splashcodex/api-key-manager)](https://www.npmjs.com/package/@splashcodex/api-key-manager)
+[![npm version](https://img.shields.io/npm/v/@splashcodex/ApiKeyManager)](https://www.npmjs.com/package/@splashcodex/ApiKeyManager)
 
 ## Features
 
 - **Circuit Breaker** — Keys transition through `CLOSED → OPEN → HALF_OPEN → DEAD`
-- **Error Classification** — Automatic detection of 429 (Quota), 403 (Auth), 5xx (Transient), Safety blocks
+- **Error Classification** — Automatic detection of 429 (Quota), 403 (Auth), 5xx (Transient), Timeout, Safety blocks
 - **Pluggable Strategies** — `StandardStrategy`, `WeightedStrategy`, `LatencyStrategy`
-- **Retry-After Parsing** — Respects server-provided cooldown headers
-- **Exponential Backoff with Jitter** — Prevents thundering herd
+- **`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
+- **Recursion Guard** *(v4 NEW)* — Prevents infinite loops when `getEmbedding` calls `execute()`
 - **State Persistence** — Survives restarts via pluggable storage
-- **Latency Tracking** — Track average response times per key
-- **100% Backward Compatible** — v1.x code works without changes
+- **100% Backward Compatible** — v1.x, v2.x, and v3.x code works without changes
 
 ## Installation
 
@@ -21,61 +28,151 @@
 npm install @splashcodex/api-key-manager
 ```
 
-## Quick Start (v1.x Compatible)
+## 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!);
 
-const key = manager.getKey(); // Returns best available key
-manager.markSuccess(key!);    // Report success
+// v3+ — Full power
+const result = await manager.execute(
+  (key) => fetch(`https://api.example.com?key=${key}`),
+  { maxRetries: 3, timeoutMs: 5000 }
+);
+```
+
+## v4.0 — Semantic Cache (Mastermind Edition)
+
+Automatically cache API responses by semantic similarity. Identical or near-identical prompts return cached results without consuming API quota.
+
+```typescript
+import { ApiKeyManager } from '@splashcodex/api-key-manager';
+
+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);
+    }
+  }
+});
+
+// First call → API hit, cached
+const r1 = await manager.execute(apiFn, { prompt: 'What is the weather?' });
+
+// Second call → Semantic Cache HIT (no API call)
+const r2 = await manager.execute(apiFn, { prompt: 'How is the weather today?' });
+```
+
+> **Recursion Guard**: If your `getEmbedding` callback internally calls `execute()`,
+> the cache automatically skips on nested calls to prevent infinite recursion.
+
+## execute() Wrapper
+
+Wraps the entire lifecycle into one method:
+
+```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
 ```
 
-## v2.0 — Strategies
+## Event Emitter
+
+Monitor every state change:
+
+```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`));
+```
 
-### Weighted Strategy (Cost Optimization)
+## Load Balancing Strategies
 
-Prioritize cheap/free-tier keys. Expensive keys are only used as fallback.
+### Weighted (Cost Optimization)
 
 ```typescript
 import { ApiKeyManager, WeightedStrategy } from '@splashcodex/api-key-manager';
 
 const manager = new ApiKeyManager(
   [
-    { key: 'free-tier-key-1', weight: 1.0 },   // High priority
-    { key: 'free-tier-key-2', weight: 1.0 },   // High priority
-    { key: 'paid-key-backup',  weight: 0.1 },  // Emergency only
+    { key: 'free-key-1', weight: 1.0 },
+    { key: 'free-key-2', weight: 1.0 },
+    { key: 'paid-backup', weight: 0.1 },
   ],
-  undefined,          // storage (null = in-memory)
-  new WeightedStrategy()
+  { strategy: new WeightedStrategy() }
 );
+```
+
+### Latency (Performance)
 
-const key = manager.getKey(); // Heavily favors free-tier keys
+```typescript
+import { ApiKeyManager, LatencyStrategy } from '@splashcodex/api-key-manager';
+
+const manager = new ApiKeyManager(keys, { strategy: new LatencyStrategy() });
+// After execute(), latency is tracked automatically
 ```
 
-### Latency Strategy (Performance Optimization)
+## Provider Tagging
 
-Automatically picks the key with the lowest average response time.
+Route requests to specific providers:
 
 ```typescript
-import { ApiKeyManager, LatencyStrategy } from '@splashcodex/api-key-manager';
+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');
+```
 
-const manager = new ApiKeyManager(['key1', 'key2'], undefined, new LatencyStrategy());
+## Health Checks
 
-// After each request, report duration:
-const start = Date.now();
-await callApi(key);
-manager.markSuccess(key, Date.now() - start); // Records latency
+Proactively detect recovered keys:
 
-// Next call automatically picks the fastest key
+```typescript
+manager.setHealthCheck(async (key) => {
+  const res = await fetch(`https://api.openai.com/v1/models`, {
+    headers: { Authorization: `Bearer ${key}` }
+  });
+  return res.ok;
+});
+
+manager.startHealthChecks(60_000); // Check every 60 seconds
+// manager.stopHealthChecks();     // Stop when done
 ```
 
-### Error Handling
+## Error Handling
 
 ```typescript
 try {
-  const result = await callGeminiApi(key);
+  const result = await callApi(key);
   manager.markSuccess(key, duration);
 } catch (error) {
   const classification = manager.classifyError(error);
@@ -84,31 +181,71 @@ try {
   if (classification.retryable) {
     const delay = manager.calculateBackoff(attempt);
     await sleep(delay);
-    // retry with manager.getKey()
   }
 }
 ```
 
-### Health Monitoring
+## API Reference
+
+### Constructor
 
 ```typescript
-const stats = manager.getStats();
-// { total: 5, healthy: 3, cooling: 1, dead: 1 }
+// 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 }
+})
 ```
 
-## API Reference
+### 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 |
 | `calculateBackoff(attempt)` | Get backoff delay with jitter |
 | `getStats()` | Get pool health statistics |
 | `getKeyCount()` | Count of non-DEAD keys |
-
-## Strategies
+| `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 |
 |----------|-----------|----------|

package/dist/index.d.ts

@@ -1,8 +1,11 @@
 /**
- * Universal ApiKeyManager v2.0
- * Implements: Rotation, Circuit Breaker, Persistence, Exponential Backoff, Strategies
+ * Universal ApiKeyManager v4.0 — Mastermind Edition
+ * Implements: Rotation, Circuit Breaker, Persistence, Exponential Backoff, Strategies,
+ *             Event Emitter, Fallback, execute(), Timeout, Auto-Retry, Provider Tags,
+ *             Health Checks, Bulkhead/Concurrency
  * Gemini-Specific: finishReason handling, Safety blocks, RECITATION detection
  */
+import { EventEmitter } from 'events';
 export interface KeyState {
     key: string;
     failCount: number;
@@ -18,8 +21,9 @@ export interface KeyState {
     averageLatency: number;
     totalLatency: number;
     latencySamples: number;
+    provider: string;
 }
-export type ErrorType = 'QUOTA' | 'TRANSIENT' | 'AUTH' | 'BAD_REQUEST' | 'SAFETY' | 'RECITATION' | 'UNKNOWN';
+export type ErrorType = 'QUOTA' | 'TRANSIENT' | 'AUTH' | 'BAD_REQUEST' | 'SAFETY' | 'RECITATION' | 'TIMEOUT' | 'UNKNOWN';
 export interface ErrorClassification {
     type: ErrorType;
     retryable: boolean;
@@ -33,6 +37,52 @@ export interface ApiKeyManagerStats {
     cooling: number;
     dead: number;
 }
+export interface ExecuteOptions {
+    timeoutMs?: number;
+    maxRetries?: number;
+    finishReason?: string;
+    provider?: string;
+}
+export interface ApiKeyManagerOptions {
+    storage?: any;
+    strategy?: LoadBalancingStrategy;
+    fallbackFn?: () => any;
+    concurrency?: number;
+    semanticCache?: {
+        threshold?: number;
+        ttlMs?: number;
+        getEmbedding: (text: string) => Promise<number[]>;
+    };
+}
+export interface CacheEntry {
+    vector: number[];
+    prompt: string;
+    response: any;
+    timestamp: number;
+}
+export interface ApiKeyManagerEventMap {
+    keyDead: (key: string) => void;
+    circuitOpen: (key: string) => void;
+    circuitHalfOpen: (key: string) => void;
+    keyRecovered: (key: string) => void;
+    fallback: (reason: string) => void;
+    allKeysExhausted: () => void;
+    retry: (key: string, attempt: number, delayMs: number) => void;
+    healthCheckFailed: (key: string, error: any) => void;
+    healthCheckPassed: (key: string) => void;
+    executeSuccess: (key: string, durationMs: number) => void;
+    executeFailed: (key: string, error: any) => void;
+    bulkheadRejected: () => void;
+}
+export declare class TimeoutError extends Error {
+    constructor(ms: number);
+}
+export declare class BulkheadRejectionError extends Error {
+    constructor();
+}
+export declare class AllKeysExhaustedError extends Error {
+    constructor();
+}
 /**
  * Strategy Interface for selecting the next key
  */
@@ -58,15 +108,49 @@ export declare class WeightedStrategy implements LoadBalancingStrategy {
 export declare class LatencyStrategy implements LoadBalancingStrategy {
     next(candidates: KeyState[]): KeyState | null;
 }
-export declare class ApiKeyManager {
+/**
+ * High-performance Vanilla Semantic Cache
+ * Implements Cosine Similarity math from scratch.
+ */
+export declare class SemanticCache {
+    private entries;
+    private threshold;
+    private ttlMs;
+    constructor(threshold?: number, ttlMs?: number);
+    set(prompt: string, vector: number[], response: any): void;
+    get(vector: number[]): any | null;
+    /**
+     * Vanilla Cosine Similarity: (A·B) / (||A|| * ||B||)
+     */
+    private calculateCosineSimilarity;
+}
+export declare class ApiKeyManager extends EventEmitter {
     private keys;
     private storageKey;
     private storage;
     private strategy;
+    private fallbackFn?;
+    private maxConcurrency;
+    private activeCalls;
+    private healthCheckFn?;
+    private healthCheckInterval?;
+    private semanticCache?;
+    private getEmbeddingFn?;
+    private _isResolvingEmbedding;
+    /**
+     * Constructor supports both legacy positional args and new options object.
+     *
+     * @example Legacy (v1/v2 — still works):
+     *   new ApiKeyManager(['key1', 'key2'], storage, strategy)
+     *
+     * @example New (v3):
+     *   new ApiKeyManager(keys, { storage, strategy, fallbackFn, concurrency })
+     */
     constructor(initialKeys: string[] | {
         key: string;
         weight?: number;
-    }[], storage?: any, strategy?: LoadBalancingStrategy);
+        provider?: string;
+    }[], storageOrOptions?: any | ApiKeyManagerOptions, strategy?: LoadBalancingStrategy);
     /**
      * CLASSIFIES an error to determine handling strategy
      */
@@ -74,6 +158,10 @@ export declare class ApiKeyManager {
     private parseRetryAfter;
     private isOnCooldown;
     getKey(): string | null;
+    /**
+     * Get a key filtered by provider tag
+     */
+    getKeyByProvider(provider: string): string | null;
     getKeyCount(): number;
     /**
      * Mark success AND update latency stats
@@ -85,6 +173,35 @@ export declare class ApiKeyManager {
     calculateBackoff(attempt: number): number;
     getStats(): ApiKeyManagerStats;
     _getKeys(): KeyState[];
+    /**
+     * Wraps the entire API call lifecycle into a single method.
+     *
+     * @example
+     *   const result = await manager.execute(
+     *     (key) => fetch(`https://api.example.com?key=${key}`),
+     *     { maxRetries: 3, timeoutMs: 5000 }
+     *   );
+     */
+    execute<T>(fn: (key: string, signal?: AbortSignal) => Promise<T>, options?: ExecuteOptions & {
+        prompt?: string;
+    }): Promise<T>;
+    private _executeWithRetry;
+    private _executeWithTimeout;
+    private _sleep;
+    /**
+     * Set a health check function that tests if a key is operational
+     */
+    setHealthCheck(fn: (key: string) => Promise<boolean>): void;
+    /**
+     * Start periodic health checks
+     * @param intervalMs How often to run health checks (default: 60s)
+     */
+    startHealthChecks(intervalMs?: number): void;
+    /**
+     * Stop periodic health checks
+     */
+    stopHealthChecks(): void;
+    private _runHealthChecks;
     private saveState;
     private loadState;
 }