@splashcodex/api-key-manager 5.2.0 → 5.4.0

package/bin/cli.js

@@ -1,180 +1,180 @@
-#!/usr/bin/env node
-const fs = require('fs');
-const path = require('path');
-const os = require('os');
-
-const args = process.argv.slice(2);
-const command = args[0];
-
-const ENV_DIR = path.join(os.homedir(), 'codedex', 'env');
-
-function printDocs() {
-    console.log(`\x1b[92m@splashcodex/api-key-manager v5.1\x1b[0m`);
-    console.log(`\x1b[96mDocs: https://www.npmjs.com/package/@splashcodex/ApiKeyManager\x1b[0m\n`);
-    console.log(`\x1b[93mCommands:\x1b[0m`);
-    console.log(`   npx @splashcodex/api-key-manager init    \x1b[90m# Scaffold demo + central env directory\x1b[0m`);
-    console.log(`   npx @splashcodex/api-key-manager setup   \x1b[90m# Create ~/codedex/env/ with template files\x1b[0m`);
-    console.log(`   npx @splashcodex/api-key-manager status  \x1b[90m# Show which env files are loaded\x1b[0m`);
-    console.log('');
-}
-
-function setupEnvDir() {
-    console.log(`\n\x1b[96mSetting up centralized env directory...\x1b[0m\n`);
-
-    if (!fs.existsSync(ENV_DIR)) {
-        fs.mkdirSync(ENV_DIR, { recursive: true });
-        console.log(`\x1b[92m[+] Created ${ENV_DIR}\x1b[0m`);
-    } else {
-        console.log(`\x1b[90m[-] ${ENV_DIR} already exists\x1b[0m`);
-    }
-
-    const templates = {
-        'common.env': [
-            '# Common environment variables shared across all projects',
-            '# DATABASE_URL="postgresql://user:pass@localhost:5432/mydb"',
-            '# REDIS_URL="redis://localhost:6379"',
-            '# SUPABASE_URL="https://your-project.supabase.co"',
-            '# SUPABASE_ANON_KEY="your-anon-key"',
-            '',
-        ].join('\n'),
-        'llm.env': [
-            '# LLM API keys — supports comma-separated or JSON arrays',
-            '# GOOGLE_GEMINI_API_KEY="key1,key2,key3"',
-            '# OPENAI_API_KEY="sk-..."',
-            '# ANTHROPIC_API_KEY="sk-ant-..."',
-            '',
-        ].join('\n'),
-        'stripe.env': [
-            '# Stripe payment keys',
-            '# STRIPE_SECRET_KEY="sk_test_..."',
-            '# STRIPE_WEBHOOK_SECRET="whsec_..."',
-            '',
-        ].join('\n'),
-    };
-
-    for (const [name, content] of Object.entries(templates)) {
-        const filePath = path.join(ENV_DIR, name);
-        if (!fs.existsSync(filePath)) {
-            fs.writeFileSync(filePath, content);
-            console.log(`\x1b[92m[+] Created ${name}\x1b[0m`);
-        } else {
-            console.log(`\x1b[90m[-] ${name} already exists\x1b[0m`);
-        }
-    }
-
-    console.log(`\n\x1b[93mNext steps:\x1b[0m`);
-    console.log(`  1. Add your real keys to the files in ${ENV_DIR}`);
-    console.log(`  2. Back up the folder to Google Drive for portability`);
-    console.log(`  3. In your projects, add at the entry point:`);
-    console.log(`\x1b[36m     import { loadCentralEnv } from '@splashcodex/api-key-manager/env';\x1b[0m`);
-    console.log(`\x1b[36m     loadCentralEnv();\x1b[0m\n`);
-}
-
-function showStatus() {
-    console.log(`\n\x1b[96mCentralized env status\x1b[0m\n`);
-    console.log(`  Directory: ${ENV_DIR}`);
-
-    if (!fs.existsSync(ENV_DIR)) {
-        console.log(`  \x1b[31mNot found.\x1b[0m Run: npx @splashcodex/api-key-manager setup\n`);
-        return;
-    }
-
-    const files = fs.readdirSync(ENV_DIR).filter(f => f.endsWith('.env')).sort();
-    if (files.length === 0) {
-        console.log(`  \x1b[33mNo .env files found.\x1b[0m\n`);
-        return;
-    }
-
-    let totalVars = 0;
-    for (const file of files) {
-        const content = fs.readFileSync(path.join(ENV_DIR, file), 'utf-8');
-        const vars = content.split('\n')
-            .filter(l => l.trim() && !l.trim().startsWith('#'))
-            .filter(l => l.includes('='));
-        totalVars += vars.length;
-
-        const icon = vars.length > 0 ? '\x1b[92m' : '\x1b[90m';
-        console.log(`  ${icon}${file}\x1b[0m — ${vars.length} variable(s)`);
-        for (const v of vars) {
-            const key = v.split('=')[0].trim();
-            console.log(`    \x1b[90m${key}\x1b[0m`);
-        }
-    }
-
-    console.log(`\n  Total: ${files.length} file(s), ${totalVars} variable(s)\n`);
-}
-
-function initProject() {
-    const cwd = process.cwd();
-    const demoPath = path.join(cwd, 'demo.ts');
-
-    console.log(`\n\x1b[96mInitializing @splashcodex/api-key-manager...\x1b[0m\n`);
-
-    // Ensure central env directory exists
-    setupEnvDir();
-
-    // Create demo.ts
-    if (!fs.existsSync(demoPath)) {
-        const tsCode = `/**
- * Demo: @splashcodex/api-key-manager v5.1
- *
- * Shows the two-layer pattern:
- *   Layer 1: loadCentralEnv() loads keys from ~/codedex/env/
- *   Layer 2: GeminiManager handles rotation, retries, circuit breaking
- */
-import { loadCentralEnv } from '@splashcodex/api-key-manager/env';
-import { GeminiManager } from '@splashcodex/api-key-manager/presets/gemini';
-
-// Layer 1: Load centralized environment
-const envResult = loadCentralEnv();
-console.log(\`Loaded \${envResult.varsSet} env vars from \${envResult.filesLoaded.length} files\`);
-
-async function main() {
-    // Layer 2: Initialize key manager (reads from process.env)
-    const result = GeminiManager.getInstance();
-    if (!result.success) {
-        console.error("Failed:", result.error.message);
-        console.error("Add your Gemini key to ~/codedex/env/llm.env");
-        return;
-    }
-
-    const gemini = result.data;
-    console.log(\`GeminiManager ready: \${gemini.getKeyCount()} key(s)\`);
-
-    try {
-        const response = await gemini.execute(async (key) => {
-            console.log(\`Using key: \${key.substring(0, 8)}...\`);
-            // Replace with actual API call
-            return "Simulated API Response";
-        }, { maxRetries: 3, timeoutMs: 30000 });
-        console.log("Result:", response);
-    } catch (e: any) {
-        console.error("Failed:", e.message);
-    }
-}
-
-main();
-`;
-        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[93mTo run the demo:\x1b[0m`);
-    console.log(`\x1b[36m   npx ts-node demo.ts\x1b[0m\n`);
-}
-
-switch (command) {
-    case 'init':
-        initProject();
-        break;
-    case 'setup':
-        setupEnvDir();
-        break;
-    case 'status':
-        showStatus();
-        break;
-    default:
-        printDocs();
-}
+#!/usr/bin/env node
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+const args = process.argv.slice(2);
+const command = args[0];
+
+const ENV_DIR = path.join(os.homedir(), 'codedex', 'env');
+
+function printDocs() {
+    console.log(`\x1b[92m@splashcodex/api-key-manager v5.1\x1b[0m`);
+    console.log(`\x1b[96mDocs: https://www.npmjs.com/package/@splashcodex/ApiKeyManager\x1b[0m\n`);
+    console.log(`\x1b[93mCommands:\x1b[0m`);
+    console.log(`   npx @splashcodex/api-key-manager init    \x1b[90m# Scaffold demo + central env directory\x1b[0m`);
+    console.log(`   npx @splashcodex/api-key-manager setup   \x1b[90m# Create ~/codedex/env/ with template files\x1b[0m`);
+    console.log(`   npx @splashcodex/api-key-manager status  \x1b[90m# Show which env files are loaded\x1b[0m`);
+    console.log('');
+}
+
+function setupEnvDir() {
+    console.log(`\n\x1b[96mSetting up centralized env directory...\x1b[0m\n`);
+
+    if (!fs.existsSync(ENV_DIR)) {
+        fs.mkdirSync(ENV_DIR, { recursive: true });
+        console.log(`\x1b[92m[+] Created ${ENV_DIR}\x1b[0m`);
+    } else {
+        console.log(`\x1b[90m[-] ${ENV_DIR} already exists\x1b[0m`);
+    }
+
+    const templates = {
+        'common.env': [
+            '# Common environment variables shared across all projects',
+            '# DATABASE_URL="postgresql://user:pass@localhost:5432/mydb"',
+            '# REDIS_URL="redis://localhost:6379"',
+            '# SUPABASE_URL="https://your-project.supabase.co"',
+            '# SUPABASE_ANON_KEY="your-anon-key"',
+            '',
+        ].join('\n'),
+        'llm.env': [
+            '# LLM API keys — supports comma-separated or JSON arrays',
+            '# GOOGLE_GEMINI_API_KEY="key1,key2,key3"',
+            '# OPENAI_API_KEY="sk-..."',
+            '# ANTHROPIC_API_KEY="sk-ant-..."',
+            '',
+        ].join('\n'),
+        'stripe.env': [
+            '# Stripe payment keys',
+            '# STRIPE_SECRET_KEY="sk_test_..."',
+            '# STRIPE_WEBHOOK_SECRET="whsec_..."',
+            '',
+        ].join('\n'),
+    };
+
+    for (const [name, content] of Object.entries(templates)) {
+        const filePath = path.join(ENV_DIR, name);
+        if (!fs.existsSync(filePath)) {
+            fs.writeFileSync(filePath, content);
+            console.log(`\x1b[92m[+] Created ${name}\x1b[0m`);
+        } else {
+            console.log(`\x1b[90m[-] ${name} already exists\x1b[0m`);
+        }
+    }
+
+    console.log(`\n\x1b[93mNext steps:\x1b[0m`);
+    console.log(`  1. Add your real keys to the files in ${ENV_DIR}`);
+    console.log(`  2. Back up the folder to Google Drive for portability`);
+    console.log(`  3. In your projects, add at the entry point:`);
+    console.log(`\x1b[36m     import { loadCentralEnv } from '@splashcodex/api-key-manager/env';\x1b[0m`);
+    console.log(`\x1b[36m     loadCentralEnv();\x1b[0m\n`);
+}
+
+function showStatus() {
+    console.log(`\n\x1b[96mCentralized env status\x1b[0m\n`);
+    console.log(`  Directory: ${ENV_DIR}`);
+
+    if (!fs.existsSync(ENV_DIR)) {
+        console.log(`  \x1b[31mNot found.\x1b[0m Run: npx @splashcodex/api-key-manager setup\n`);
+        return;
+    }
+
+    const files = fs.readdirSync(ENV_DIR).filter(f => f.endsWith('.env')).sort();
+    if (files.length === 0) {
+        console.log(`  \x1b[33mNo .env files found.\x1b[0m\n`);
+        return;
+    }
+
+    let totalVars = 0;
+    for (const file of files) {
+        const content = fs.readFileSync(path.join(ENV_DIR, file), 'utf-8');
+        const vars = content.split('\n')
+            .filter(l => l.trim() && !l.trim().startsWith('#'))
+            .filter(l => l.includes('='));
+        totalVars += vars.length;
+
+        const icon = vars.length > 0 ? '\x1b[92m' : '\x1b[90m';
+        console.log(`  ${icon}${file}\x1b[0m — ${vars.length} variable(s)`);
+        for (const v of vars) {
+            const key = v.split('=')[0].trim();
+            console.log(`    \x1b[90m${key}\x1b[0m`);
+        }
+    }
+
+    console.log(`\n  Total: ${files.length} file(s), ${totalVars} variable(s)\n`);
+}
+
+function initProject() {
+    const cwd = process.cwd();
+    const demoPath = path.join(cwd, 'demo.ts');
+
+    console.log(`\n\x1b[96mInitializing @splashcodex/api-key-manager...\x1b[0m\n`);
+
+    // Ensure central env directory exists
+    setupEnvDir();
+
+    // Create demo.ts
+    if (!fs.existsSync(demoPath)) {
+        const tsCode = `/**
+ * Demo: @splashcodex/api-key-manager v5.1
+ *
+ * Shows the two-layer pattern:
+ *   Layer 1: loadCentralEnv() loads keys from ~/codedex/env/
+ *   Layer 2: GeminiManager handles rotation, retries, circuit breaking
+ */
+import { loadCentralEnv } from '@splashcodex/api-key-manager/env';
+import { GeminiManager } from '@splashcodex/api-key-manager/presets/gemini';
+
+// Layer 1: Load centralized environment
+const envResult = loadCentralEnv();
+console.log(\`Loaded \${envResult.varsSet} env vars from \${envResult.filesLoaded.length} files\`);
+
+async function main() {
+    // Layer 2: Initialize key manager (reads from process.env)
+    const result = GeminiManager.getInstance();
+    if (!result.success) {
+        console.error("Failed:", result.error.message);
+        console.error("Add your Gemini key to ~/codedex/env/llm.env");
+        return;
+    }
+
+    const gemini = result.data;
+    console.log(\`GeminiManager ready: \${gemini.getKeyCount()} key(s)\`);
+
+    try {
+        const response = await gemini.execute(async (key) => {
+            console.log(\`Using key: \${key.substring(0, 8)}...\`);
+            // Replace with actual API call
+            return "Simulated API Response";
+        }, { maxRetries: 3, timeoutMs: 30000 });
+        console.log("Result:", response);
+    } catch (e: any) {
+        console.error("Failed:", e.message);
+    }
+}
+
+main();
+`;
+        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[93mTo run the demo:\x1b[0m`);
+    console.log(`\x1b[36m   npx ts-node demo.ts\x1b[0m\n`);
+}
+
+switch (command) {
+    case 'init':
+        initProject();
+        break;
+    case 'setup':
+        setupEnvDir();
+        break;
+    case 'status':
+        showStatus();
+        break;
+    default:
+        printDocs();
+}

package/dist/env/loader.js

@@ -45,43 +45,27 @@ exports.getCentralEnvVar = getCentralEnvVar;
 const fs_1 = require("fs");
 const path_1 = require("path");
 const os_1 = require("os");
+const dotenv_1 = require("dotenv");
 // ─── Parser ──────────────────────────────────────────────────────────────────
 /**
- * Parse a .env file into key-value pairs.
- * Supports:
+ * Parse a .env file content string into key-value pairs.
+ *
+ * Delegates to `dotenv.parse()` for battle-tested parsing that handles:
  *   KEY=value
- *   KEY="quoted value"
+ *   KEY="quoted value with spaces"
  *   KEY='single quoted'
- *   # comments
- *   empty lines
+ *   KEY=`backtick quoted`
+ *   MULTILINE="line1\nline2"  (real newlines inside double quotes)
+ *   KEY=value # inline comment
  *   export KEY=value (bash-style)
+ *   # full-line comments
+ *   \n, \r, \t escape sequences
+ *
+ * Returns a Map<string, string> for compatibility with the rest of the loader.
  */
 function parseEnvFile(content) {
-    const vars = new Map();
-    for (const rawLine of content.split('\n')) {
-        const line = rawLine.trim();
-        // Skip empty lines and comments
-        if (!line || line.startsWith('#'))
-            continue;
-        // Strip optional 'export ' prefix
-        const stripped = line.startsWith('export ') ? line.slice(7) : line;
-        // Find the first '=' that separates key from value
-        const eqIndex = stripped.indexOf('=');
-        if (eqIndex === -1)
-            continue;
-        const key = stripped.slice(0, eqIndex).trim();
-        let value = stripped.slice(eqIndex + 1).trim();
-        // Strip surrounding quotes
-        if ((value.startsWith('"') && value.endsWith('"')) ||
-            (value.startsWith("'") && value.endsWith("'"))) {
-            value = value.slice(1, -1);
-        }
-        // Skip empty keys
-        if (!key)
-            continue;
-        vars.set(key, value);
-    }
-    return vars;
+    const parsed = (0, dotenv_1.parse)(content);
+    return new Map(Object.entries(parsed));
 }
 // ─── Loader ──────────────────────────────────────────────────────────────────
 /**

package/dist/env/loader.js.map

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

package/dist/index.d.ts

@@ -6,8 +6,10 @@
  * NEW in v5.0: Provider Presets (GeminiManager, OpenAIManager, MultiManager),
  *              Built-in Persistence (FileStorage, MemoryStorage)
  * Gemini-Specific: finishReason handling, Safety blocks, RECITATION detection
+ * Infrastructure: cockatiel (Bulkhead queueing + ExponentialBackoff w/ decorrelated jitter)
  */
 import { EventEmitter } from 'events';
+import { z } from 'zod';
 export { FileStorage } from './persistence/file';
 export type { FileStorageOptions } from './persistence/file';
 export { MemoryStorage } from './persistence/memory';
@@ -48,17 +50,19 @@ export interface ExecuteOptions {
     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 declare const ApiKeyManagerOptionsSchema: z.ZodObject<{
+    storage: z.ZodOptional<z.ZodAny>;
+    strategy: z.ZodOptional<z.ZodAny>;
+    fallbackFn: z.ZodOptional<z.ZodCustom<() => any, () => any>>;
+    concurrency: z.ZodOptional<z.ZodNumber>;
+    concurrencyQueueSize: z.ZodOptional<z.ZodNumber>;
+    semanticCache: z.ZodOptional<z.ZodObject<{
+        threshold: z.ZodOptional<z.ZodNumber>;
+        ttlMs: z.ZodOptional<z.ZodNumber>;
+        getEmbedding: z.ZodCustom<(text: string) => Promise<number[]>, (text: string) => Promise<number[]>>;
+    }, z.core.$strip>>;
+}, z.core.$loose>;
+export type ApiKeyManagerOptions = z.infer<typeof ApiKeyManagerOptionsSchema>;
 export interface CacheEntry {
     vector: number[];
     prompt: string;
@@ -135,8 +139,7 @@ export declare class ApiKeyManager extends EventEmitter {
     private storage;
     private strategy;
     private fallbackFn?;
-    private maxConcurrency;
-    private activeCalls;
+    private bulkheadPolicy;
     private healthCheckFn?;
     private healthCheckInterval?;
     private _saveTimer?;
@@ -177,6 +180,15 @@ export declare class ApiKeyManager extends EventEmitter {
     markSuccess(key: string, durationMs?: number): void;
     markFailed(key: string, classification: ErrorClassification): void;
     markFailedLegacy(key: string, isQuota?: boolean): void;
+    /**
+     * Calculate exponential backoff with decorrelated jitter using cockatiel.
+     * Decorrelated jitter avoids thundering-herd by randomizing retry intervals
+     * independent of the previous delay, which is statistically superior to
+     * simple `random * exponential` jitter.
+     *
+     * @param attempt - Zero-indexed attempt number
+     */
+    private readonly _backoffFactory;
     calculateBackoff(attempt: number): number;
     getStats(): ApiKeyManagerStats;
     _getKeys(): KeyState[];
@@ -207,6 +219,11 @@ export declare class ApiKeyManager extends EventEmitter {
     executeStream<T>(fn: (key: string, signal?: AbortSignal) => AsyncGenerator<T, any, unknown>, options?: ExecuteOptions & {
         prompt?: string;
     }): AsyncGenerator<T, any, unknown>;
+    /**
+     * Helper: stores result in semantic cache then returns it.
+     * Called by the bulkhead execute() callback and the no-bulkhead path.
+     */
+    private _executeWithSemanticAndRetry;
     private _executeWithRetry;
     private _executeWithTimeout;
     private _sleep;