Universal API Key Management Gateway with Provider Presets, Built-in Persistence, and Multi-Provider Vault.
- Provider Presets — One-line setup for
GeminiManager,OpenAIManager, andMultiManager. - 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) andMemoryStorageincluded. - Singleton Pattern — Thread-safe singletons with
getInstance()andResult<T>pattern. - Multi-Provider Vault — Manage multiple providers (
gemini,openai,anthropic) from a single entry point.
- Circuit Breaker — Keys transition through
CLOSED → OPEN → HALF_OPEN → DEAD - Error Classification — Automatic detection of 429 (Quota), 403 (Auth), 5xx (Transient), Timeout, Safety blocks
- Pluggable Strategies —
StandardStrategy,WeightedStrategy,LatencyStrategy 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
- 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
npm install @splashcodex/api-key-managerThe fastest way to get started in any CodeDex repository.
Reads GOOGLE_GEMINI_API_KEY or GEMINI_API_KEY from environment.
import { GeminiManager } from '@splashcodex/api-key-manager/presets/gemini';
const result = GeminiManager.getInstance();
if (!result.success) throw result.error;
const gemini = result.data;
const response = await gemini.execute(async (key) => {
// result.data is the underlying ApiKeyManager
return await callGemini(key, "Hello!");
});Perfect for gateways or complex bots handling multiple models.
import { MultiManager } from '@splashcodex/api-key-manager/presets/multi';
const vault = MultiManager.getInstance({
providers: {
gemini: { envKeys: ['GOOGLE_GEMINI_API_KEY'] },
openai: { envKeys: ['OPENAI_API_KEY'] }
}
}).data!;
// Route by provider
const res = await vault.execute(fn, { provider: 'gemini' });State (cooling down keys, dead keys) now survives application restarts by default.
import { FileStorage } from '@splashcodex/api-key-manager/persistence/file';
const manager = new ApiKeyManager(keys, {
storage: new FileStorage({
filePath: './api_state.json'
})
});To keep your bundles small, you can import only what you need:
import { GeminiManager } from '@splashcodex/api-key-manager/presets/gemini';
import { FileStorage } from '@splashcodex/api-key-manager/persistence/file';Automatically cache API responses by semantic similarity.
const manager = new ApiKeyManager(['key1', 'key2'], {
semanticCache: {
threshold: 0.92,
getEmbedding: async (text) => await myModel.embed(text)
}
});
// 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?' });Real-time response handling with the same resilience as execute().
const stream = await manager.executeStream(async (key) => {
return await gemini.generateContentStream({ prompt: "..." });
}, { prompt: "..." });
for await (const chunk of stream) {
console.log(chunk.text());
}Wraps the entire lifecycle into one method:
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 }
);| 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 |
| Class | Description |
|---|---|
FileStorage |
Persists to a JSON file (recommended for servers) |
MemoryStorage |
In-memory only (best for serverless/short-lived) |
| Method | Description |
|---|---|
execute(fn, opts) |
Standard wrapper |
executeStream(fn, opts) |
Streaming wrapper |
getStats() |
Get pool health |
getKey() |
Manual key rotation |
markFailed(key, err) |
Manual failure reporting |
ISC