@splashcodex/api-key-manager 4.0.0 → 5.0.0

package/dist/presets/multi.js

@@ -0,0 +1,210 @@
+"use strict";
+/**
+ * MultiManager Preset — Multi-Provider Key Vault
+ *
+ * Manages API keys across multiple providers from a single entry point.
+ * Aggregates keys from multiple environment variables and routes
+ * requests to the correct provider pool.
+ *
+ * @module presets/multi
+ *
+ * @example
+ * ```ts
+ * import { MultiManager } from '@splashcodex/api-key-manager/presets/multi';
+ *
+ * const result = MultiManager.getInstance({
+ *   providers: {
+ *     gemini: { envKeys: ['GOOGLE_GEMINI_API_KEY'] },
+ *     openai: { envKeys: ['OPENAI_API_KEY'] },
+ *   }
+ * });
+ *
+ * if (result.success) {
+ *   const vault = result.data;
+ *
+ *   // Route to specific provider
+ *   const text = await vault.execute(async (key) => {
+ *     // key is from the gemini pool
+ *     return callGemini(key, prompt);
+ *   }, { provider: 'gemini', maxRetries: 3 });
+ *
+ *   // Get stats across all providers
+ *   const stats = vault.getMultiStats();
+ * }
+ * ```
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MultiManager = void 0;
+const index_1 = require("../index");
+const file_1 = require("../persistence/file");
+const path_1 = require("path");
+const os_1 = require("os");
+// ─── MultiManager ───────────────────────────────────────────────────────────
+class MultiManager {
+    static instance = null;
+    managers = new Map();
+    logger;
+    constructor(options) {
+        this.logger = options.logger || console;
+        for (const [providerName, config] of Object.entries(options.providers)) {
+            const keys = MultiManager.parseKeysFromEnv(config.envKeys);
+            if (keys.length === 0) {
+                this.logger.warn(`[MultiManager:${providerName}] No API keys found in: ${config.envKeys.join(', ')}`);
+            }
+            const storage = new file_1.FileStorage({
+                filePath: (0, path_1.join)((0, os_1.tmpdir)(), `codedex_multi_${providerName}_state.json`),
+                clearOnInit: true,
+            });
+            const manager = new index_1.ApiKeyManager(keys, {
+                storage,
+                strategy: config.strategy || new index_1.LatencyStrategy(),
+                concurrency: config.concurrency ?? 20,
+                semanticCache: config.semanticCache,
+            });
+            // Wire events
+            manager.on('keyDead', (key) => this.logger.error(`[MultiManager:${providerName}] Key DEAD: ...${key.slice(-4)}`));
+            manager.on('circuitOpen', (key) => this.logger.warn(`[MultiManager:${providerName}] Circuit OPEN: ...${key.slice(-4)}`));
+            manager.on('keyRecovered', (key) => this.logger.info(`[MultiManager:${providerName}] Key RECOVERED: ...${key.slice(-4)}`));
+            manager.on('allKeysExhausted', () => this.logger.error(`[MultiManager:${providerName}] ALL KEYS EXHAUSTED`));
+            // Health checks
+            const interval = options.healthCheckIntervalMs ?? 300_000;
+            if (interval > 0) {
+                manager.startHealthChecks(interval);
+            }
+            this.managers.set(providerName, manager);
+            this.logger.info(`[MultiManager:${providerName}] Initialized with ${keys.length} keys`);
+        }
+    }
+    // ─── Factory ────────────────────────────────────────────────────────────
+    /**
+     * Get or create the singleton MultiManager instance.
+     */
+    static getInstance(options) {
+        if (MultiManager.instance) {
+            return { success: true, data: MultiManager.instance };
+        }
+        try {
+            MultiManager.instance = new MultiManager(options);
+            return { success: true, data: MultiManager.instance };
+        }
+        catch (error) {
+            return {
+                success: false,
+                error: error instanceof Error ? error : new Error(String(error)),
+            };
+        }
+    }
+    /**
+     * Reset the singleton (primarily for testing).
+     */
+    static reset() {
+        if (MultiManager.instance) {
+            MultiManager.instance.destroy();
+            MultiManager.instance = null;
+        }
+    }
+    // ─── Public API ─────────────────────────────────────────────────────────
+    /**
+     * Execute a function with a specific provider's key pool.
+     *
+     * @param fn - The function to execute with a key
+     * @param options - Must include `provider` to select the pool
+     */
+    async execute(fn, options) {
+        const manager = this.managers.get(options.provider);
+        if (!manager) {
+            throw new Error(`[MultiManager] Unknown provider "${options.provider}". ` +
+                `Available: ${[...this.managers.keys()].join(', ')}`);
+        }
+        // Strip `provider` before delegating — each manager only has keys for one provider
+        const { provider, ...delegateOptions } = options;
+        return manager.execute(fn, delegateOptions);
+    }
+    /**
+     * Execute a streaming function with a specific provider's key pool.
+     */
+    async *executeStream(fn, options) {
+        const manager = this.managers.get(options.provider);
+        if (!manager) {
+            throw new Error(`[MultiManager] Unknown provider "${options.provider}". ` +
+                `Available: ${[...this.managers.keys()].join(', ')}`);
+        }
+        const { provider, ...delegateOptions } = options;
+        yield* manager.executeStream(fn, delegateOptions);
+    }
+    /**
+     * Get a raw key from a specific provider pool.
+     */
+    getKey(provider) {
+        const manager = this.managers.get(provider);
+        if (!manager)
+            return null;
+        return manager.getKey();
+    }
+    /**
+     * Get stats for a specific provider.
+     */
+    getStats(provider) {
+        const manager = this.managers.get(provider);
+        if (!manager)
+            return null;
+        return manager.getStats();
+    }
+    /**
+     * Get aggregate stats across ALL providers.
+     */
+    getMultiStats() {
+        const stats = {};
+        for (const [name, manager] of this.managers) {
+            stats[name] = manager.getStats();
+        }
+        return stats;
+    }
+    /**
+     * Get the list of available provider names.
+     */
+    getProviders() {
+        return [...this.managers.keys()];
+    }
+    /**
+     * Get the underlying ApiKeyManager for a specific provider.
+     */
+    getManager(provider) {
+        return this.managers.get(provider);
+    }
+    /**
+     * Stop all health checks and clean up.
+     */
+    destroy() {
+        for (const [, manager] of this.managers) {
+            manager.stopHealthChecks();
+        }
+        this.managers.clear();
+    }
+    // ─── Helpers ────────────────────────────────────────────────────────────
+    static parseKeysFromEnv(envKeys) {
+        const keys = [];
+        for (const envName of envKeys) {
+            const envValue = process.env[envName];
+            if (!envValue)
+                continue;
+            const trimmed = envValue.trim();
+            if (!trimmed)
+                continue;
+            if (trimmed.startsWith('[')) {
+                try {
+                    const parsed = JSON.parse(trimmed);
+                    if (Array.isArray(parsed)) {
+                        keys.push(...parsed.filter((k) => typeof k === 'string' && k.trim()));
+                        continue;
+                    }
+                }
+                catch { /* not JSON */ }
+            }
+            keys.push(...trimmed.split(',').map(k => k.trim()).filter(k => k.length > 0));
+        }
+        return [...new Set(keys)];
+    }
+}
+exports.MultiManager = MultiManager;
+//# sourceMappingURL=multi.js.map

package/dist/presets/multi.js.map

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

package/dist/presets/openai.d.ts

@@ -0,0 +1,45 @@
+/**
+ * OpenAI Preset — One-line OpenAI API key management
+ *
+ * Pre-configured singleton with:
+ * - Reads `OPENAI_API_KEY` from env
+ * - LatencyStrategy for optimal key selection
+ * - File persistence (survives restarts)
+ * - Health checks every 5 minutes
+ * - Concurrency limit of 20
+ *
+ * @module presets/openai
+ *
+ * @example
+ * ```ts
+ * import { OpenAIManager } from '@splashcodex/api-key-manager/presets/openai';
+ *
+ * const result = OpenAIManager.getInstance();
+ * if (!result.success) throw result.error;
+ * const openai = result.data;
+ *
+ * const response = await openai.execute(async (key) => {
+ *   const client = new OpenAI({ apiKey: key });
+ *   const completion = await client.chat.completions.create({
+ *     model: 'gpt-4o',
+ *     messages: [{ role: 'user', content: 'Hello!' }],
+ *   });
+ *   return completion.choices[0].message.content;
+ * }, { maxRetries: 3, timeoutMs: 30000 });
+ * ```
+ */
+import { BasePreset, PresetOptions, Result } from './base';
+export declare class OpenAIManager extends BasePreset {
+    private static readonly PROVIDER;
+    private constructor();
+    private static getDefaultOptions;
+    /**
+     * Get or create the singleton OpenAIManager instance.
+     *
+     * @param overrides - Optional configuration overrides
+     * @returns Result<OpenAIManager>
+     */
+    static getInstance(overrides?: Partial<PresetOptions>): Result<OpenAIManager>;
+    static reset(): void;
+}
+export { Result } from './base';

package/dist/presets/openai.js

@@ -0,0 +1,62 @@
+"use strict";
+/**
+ * OpenAI Preset — One-line OpenAI API key management
+ *
+ * Pre-configured singleton with:
+ * - Reads `OPENAI_API_KEY` from env
+ * - LatencyStrategy for optimal key selection
+ * - File persistence (survives restarts)
+ * - Health checks every 5 minutes
+ * - Concurrency limit of 20
+ *
+ * @module presets/openai
+ *
+ * @example
+ * ```ts
+ * import { OpenAIManager } from '@splashcodex/api-key-manager/presets/openai';
+ *
+ * const result = OpenAIManager.getInstance();
+ * if (!result.success) throw result.error;
+ * const openai = result.data;
+ *
+ * const response = await openai.execute(async (key) => {
+ *   const client = new OpenAI({ apiKey: key });
+ *   const completion = await client.chat.completions.create({
+ *     model: 'gpt-4o',
+ *     messages: [{ role: 'user', content: 'Hello!' }],
+ *   });
+ *   return completion.choices[0].message.content;
+ * }, { maxRetries: 3, timeoutMs: 30000 });
+ * ```
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OpenAIManager = void 0;
+const base_1 = require("./base");
+class OpenAIManager extends base_1.BasePreset {
+    static PROVIDER = 'openai';
+    constructor(keys, options) {
+        super(keys, options);
+    }
+    static getDefaultOptions() {
+        return {
+            envKeys: ['OPENAI_API_KEY'],
+            provider: OpenAIManager.PROVIDER,
+            concurrency: 20,
+            healthCheckIntervalMs: 300_000,
+        };
+    }
+    /**
+     * Get or create the singleton OpenAIManager instance.
+     *
+     * @param overrides - Optional configuration overrides
+     * @returns Result<OpenAIManager>
+     */
+    static getInstance(overrides) {
+        return base_1.BasePreset.createInstance(OpenAIManager, OpenAIManager.getDefaultOptions(), overrides);
+    }
+    static reset() {
+        base_1.BasePreset.resetInstance(OpenAIManager.PROVIDER);
+    }
+}
+exports.OpenAIManager = OpenAIManager;
+//# sourceMappingURL=openai.js.map

package/dist/presets/openai.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"openai.js","sourceRoot":"","sources":["../../src/presets/openai.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;;;AAEH,iCAA2D;AAE3D,MAAa,aAAc,SAAQ,iBAAU;IACjC,MAAM,CAAU,QAAQ,GAAG,QAAQ,CAAC;IAE5C,YAAoB,IAAc,EAAE,OAAsB;QACtD,KAAK,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;IACzB,CAAC;IAEO,MAAM,CAAC,iBAAiB;QAC5B,OAAO;YACH,OAAO,EAAE,CAAC,gBAAgB,CAAC;YAC3B,QAAQ,EAAE,aAAa,CAAC,QAAQ;YAChC,WAAW,EAAE,EAAE;YACf,qBAAqB,EAAE,OAAO;SACjC,CAAC;IACN,CAAC;IAED;;;;;OAKG;IACH,MAAM,CAAC,WAAW,CAAC,SAAkC;QACjD,OAAO,iBAAU,CAAC,cAAc,CAC5B,aAAyF,EACzF,aAAa,CAAC,iBAAiB,EAAE,EACjC,SAAS,CACa,CAAC;IAC/B,CAAC;IAED,MAAM,CAAC,KAAK;QACR,iBAAU,CAAC,aAAa,CAAC,aAAa,CAAC,QAAQ,CAAC,CAAC;IACrD,CAAC;;AAhCL,sCAiCC"}

package/package.json

@@ -1,9 +1,75 @@
 {
     "name": "@splashcodex/api-key-manager",
-    "version": "4.0.0",
-    "description": "Universal API Key Rotation System for rate-limited APIs",
+    "version": "5.0.0",
+    "description": "Universal API Key Management Gateway with provider presets, persistence, and multi-provider vault",
     "main": "dist/index.js",
     "types": "dist/index.d.ts",
+    "exports": {
+        ".": {
+            "require": "./dist/index.js",
+            "types": "./dist/index.d.ts"
+        },
+        "./presets": {
+            "require": "./dist/presets/index.js",
+            "types": "./dist/presets/index.d.ts"
+        },
+        "./presets/gemini": {
+            "require": "./dist/presets/gemini.js",
+            "types": "./dist/presets/gemini.d.ts"
+        },
+        "./presets/openai": {
+            "require": "./dist/presets/openai.js",
+            "types": "./dist/presets/openai.d.ts"
+        },
+        "./presets/multi": {
+            "require": "./dist/presets/multi.js",
+            "types": "./dist/presets/multi.d.ts"
+        },
+        "./presets/base": {
+            "require": "./dist/presets/base.js",
+            "types": "./dist/presets/base.d.ts"
+        },
+        "./persistence": {
+            "require": "./dist/persistence/index.js",
+            "types": "./dist/persistence/index.d.ts"
+        },
+        "./persistence/file": {
+            "require": "./dist/persistence/file.js",
+            "types": "./dist/persistence/file.d.ts"
+        },
+        "./persistence/memory": {
+            "require": "./dist/persistence/memory.js",
+            "types": "./dist/persistence/memory.d.ts"
+        }
+    },
+    "typesVersions": {
+        "*": {
+            "presets": [
+                "dist/presets/index.d.ts"
+            ],
+            "presets/gemini": [
+                "dist/presets/gemini.d.ts"
+            ],
+            "presets/openai": [
+                "dist/presets/openai.d.ts"
+            ],
+            "presets/multi": [
+                "dist/presets/multi.d.ts"
+            ],
+            "presets/base": [
+                "dist/presets/base.d.ts"
+            ],
+            "persistence": [
+                "dist/persistence/index.d.ts"
+            ],
+            "persistence/file": [
+                "dist/persistence/file.d.ts"
+            ],
+            "persistence/memory": [
+                "dist/persistence/memory.d.ts"
+            ]
+        }
+    },
     "files": [
         "dist",
         "src"
@@ -18,6 +84,7 @@
         "key",
         "rotation",
         "gemini",
+        "openai",
         "rate-limit",
         "circuit-breaker",
         "resilience",
@@ -25,7 +92,12 @@
         "timeout",
         "retry",
         "gateway",
-        "load-balancing"
+        "load-balancing",
+        "preset",
+        "persistence",
+        "multi-provider",
+        "semantic-cache",
+        "streaming"
     ],
     "author": "Antigravity",
     "license": "ISC",

package/src/index.ts

@@ -1,13 +1,31 @@
 /**
- * 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';
 
+// ─── Re-exports: Persistence ─────────────────────────────────────────────────
+// Persistence adapters can be imported from root or via subpath
+export { FileStorage } from './persistence/file';
+export type { FileStorageOptions } from './persistence/file';
+export { MemoryStorage } from './persistence/memory';
+
+// ─── Presets ─────────────────────────────────────────────────────────────────
+// Presets are available via subpath imports to avoid circular dependencies:
+//   import { GeminiManager } from '@splashcodex/api-key-manager/presets/gemini';
+//   import { OpenAIManager } from '@splashcodex/api-key-manager/presets/openai';
+//   import { MultiManager } from '@splashcodex/api-key-manager/presets/multi';
+// Or import all at once:
+//   import { GeminiManager, OpenAIManager, MultiManager } from '@splashcodex/api-key-manager/presets';
+
+
+
 // ─── Interfaces & Types ──────────────────────────────────────────────────────
 
 export interface KeyState {
@@ -185,12 +203,15 @@ export class WeightedStrategy implements LoadBalancingStrategy {
 }
 
 /**
- * Latency Strategy: Pick lowest average latency
+ * Latency Strategy: Pick lowest average latency with LRU tie-break
  */
 export class LatencyStrategy implements LoadBalancingStrategy {
     next(candidates: KeyState[]): KeyState | null {
         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];
     }
 }
@@ -664,6 +685,140 @@ export class ApiKeyManager extends EventEmitter {
         }
     }
 
+    /**
+     * Executes a streaming function (AsyncGenerator) with retry logic and semantic caching.
+     *
+     * @example
+     *   const stream = await manager.executeStream(async (key) => {
+     *     return await gemini.generateContentStream({ prompt: "..." });
+     *   }, { prompt: "..." });
+     *
+     *   for await (const chunk of stream) {
+     *     console.log(chunk.text());
+     *   }
+     */
+    public async *executeStream<T>(
+        fn: (key: string, signal?: AbortSignal) => AsyncGenerator<T, any, unknown>,
+        options?: ExecuteOptions & { prompt?: string }
+    ): AsyncGenerator<T, any, unknown> {
+        const maxRetries = options?.maxRetries ?? 0;
+        const timeoutMs = options?.timeoutMs;
+        const finishReason = options?.finishReason;
+        const prompt = options?.prompt;
+        const provider = options?.provider;
+
+        // 1. Semantic Cache Check
+        let currentPromptVector: number[] | null = null;
+        if (this.semanticCache && this.getEmbeddingFn && prompt && !this._isResolvingEmbedding) {
+            try {
+                this._isResolvingEmbedding = true;
+                currentPromptVector = await this.getEmbeddingFn(prompt);
+                const cachedResponse = this.semanticCache.get(currentPromptVector);
+                if (cachedResponse !== null) {
+                    console.log(`[Semantic Cache HIT] Streaming cached response for prompt: "${prompt.slice(0, 30)}..."`);
+                    this.emit('executeSuccess', 'CACHE_HIT_STREAM', 0);
+                    // Replay full response as a single chunk (or iterate if it's an array)
+                    if (Array.isArray(cachedResponse)) {
+                        for (const chunk of cachedResponse) yield chunk as T;
+                    } else {
+                        yield cachedResponse as T;
+                    }
+                    return;
+                }
+            } catch (e) {
+                console.warn('[Semantic Cache Check Failed] Proceeding to live stream', e);
+            } finally {
+                this._isResolvingEmbedding = false;
+            }
+        }
+
+        // 2. Bulkhead check
+        if (this.activeCalls >= this.maxConcurrency) {
+            this.emit('bulkheadRejected');
+            throw new BulkheadRejectionError();
+        }
+
+        this.activeCalls++;
+        const accumulatedChunks: T[] = [];
+        let lastError: any;
+
+        try {
+            for (let attempt = 0; attempt <= maxRetries; attempt++) {
+                const key = provider ? this.getKeyByProvider(provider) : this.getKey();
+
+                if (!key) {
+                    if (this.fallbackFn) {
+                        this.emit('fallback', 'all keys exhausted (stream)');
+                        yield this.fallbackFn();
+                        return;
+                    }
+                    throw new AllKeysExhaustedError();
+                }
+
+                let iterator: AsyncGenerator<T, any, unknown>;
+                try {
+                    // Start the generator
+                    iterator = fn(key);
+
+                    // PRIME THE ITERATOR:
+                    // Try to get the first chunk. This forces the generator body to
+                    // execute until the first 'yield' or until it throws.
+                    const firstResult = await iterator.next();
+
+                    // If we got here, the INITIAL connection/logic succeeded!
+                    if (firstResult.done) return;
+
+                    // Yield first chunk
+                    yield firstResult.value;
+                    if (this.semanticCache && prompt) accumulatedChunks.push(firstResult.value);
+
+                    // Yield rest of chunks
+                    for await (const chunk of iterator) {
+                        yield chunk;
+                        if (this.semanticCache && prompt) accumulatedChunks.push(chunk);
+                    }
+
+                    // Success! Store in cache
+                    if (this.semanticCache && prompt && currentPromptVector && accumulatedChunks.length > 0) {
+                        this.semanticCache.set(prompt, currentPromptVector, accumulatedChunks);
+                    }
+
+                    return; // Full success, exit retry loop
+
+                } catch (error: any) {
+                    lastError = error;
+                    const classification = this.classifyError(error, finishReason);
+
+                    this.markFailed(key, classification);
+                    this.emit('executeFailed', key, error);
+
+                    // Note: If we already yielded the FIRST chunk, we CANNOT retry the connection
+                    // because the user has already received data. Mid-stream failures propagate.
+                    if (accumulatedChunks.length > 0) {
+                        throw error;
+                    }
+
+                    if (!classification.retryable || attempt >= maxRetries) {
+                        if (this.fallbackFn && attempt >= maxRetries) {
+                            this.emit('fallback', 'max retries exceeded (stream)');
+                            yield this.fallbackFn();
+                            return;
+                        }
+                        throw error;
+                    }
+
+                    const delay = this.calculateBackoff(attempt);
+                    this.emit('retry', key, attempt + 1, delay);
+                    await this._sleep(delay);
+                }
+            }
+        } finally {
+            this.activeCalls--;
+        }
+
+        throw lastError;
+    }
+
     private async _executeWithRetry<T>(
         fn: (key: string, signal?: AbortSignal) => Promise<T>,
         maxRetries: number,
@@ -751,7 +906,10 @@ export class ApiKeyManager extends EventEmitter {
     }
 
     private _sleep(ms: number): Promise<void> {
-        return new Promise(resolve => setTimeout(resolve, ms));
+        return new Promise(resolve => {
+            const timer = setTimeout(resolve, ms);
+            if (timer.unref) timer.unref();
+        });
     }
 
     // ─── Health Checks ───────────────────────────────────────────────────────
@@ -770,6 +928,7 @@ export class ApiKeyManager extends EventEmitter {
     public startHealthChecks(intervalMs: number = 60_000) {
         this.stopHealthChecks(); // Clear any existing interval
         this.healthCheckInterval = setInterval(() => this._runHealthChecks(), intervalMs);
+        if (this.healthCheckInterval.unref) this.healthCheckInterval.unref();
     }
 
     /**