@splashcodex/api-key-manager 5.2.0 → 5.4.0

package/src/persistence/file.ts

@@ -1,89 +1,96 @@
-/**
- * File-Based Storage Adapter
- *
- * Persists API key state to a JSON file on disk.
- * Survives process restarts so keys don't reset to CLOSED
- * when an app reboots.
- *
- * Extracted from the proven WhatsDeX adapter pattern.
- *
- * @module persistence/file
- */
-
-import { writeFileSync, readFileSync, existsSync, mkdirSync, unlinkSync } from 'fs';
-import { dirname, join } from 'path';
-import { tmpdir } from 'os';
-
-export interface FileStorageOptions {
-    /** Full path to the state file. Defaults to `os.tmpdir()/codedex_api_key_state.json` */
-    filePath?: string;
-    /** If true, clears any existing state file on construction (fresh start). Default: true */
-    clearOnInit?: boolean;
-}
-
-/**
- * File-based storage adapter for ApiKeyManager.
- *
- * @example
- * ```ts
- * import { ApiKeyManager } from '@splashcodex/api-key-manager';
- * import { FileStorage } from '@splashcodex/api-key-manager/persistence/file';
- *
- * const manager = new ApiKeyManager(keys, {
- *   storage: new FileStorage({ filePath: './state.json' })
- * });
- * ```
- */
-export class FileStorage {
-    private filePath: string;
-
-    constructor(options: FileStorageOptions = {}) {
-        this.filePath = options.filePath || join(tmpdir(), 'codedex_api_key_state.json');
-
-        if (options.clearOnInit !== false) {
-            this.clear();
-        }
-    }
-
-    getItem(_key: string): string | null {
-        try {
-            if (existsSync(this.filePath)) {
-                return readFileSync(this.filePath, 'utf-8');
-            }
-        } catch {
-            // Silently fail — state will be rebuilt from scratch
-        }
-        return null;
-    }
-
-    setItem(_key: string, value: string): void {
-        try {
-            const dir = dirname(this.filePath);
-            if (!existsSync(dir)) {
-                mkdirSync(dir, { recursive: true });
-            }
-            writeFileSync(this.filePath, value, 'utf-8');
-        } catch {
-            // Silently fail — state will be lost on restart
-        }
-    }
-
-    /**
-     * Delete the persisted state file.
-     * Useful for clearing stale dead-key states from a previous session.
-     */
-    clear(): void {
-        try {
-            if (existsSync(this.filePath)) {
-                unlinkSync(this.filePath);
-            }
-        } catch {
-            // Silently fail
-        }
-    }
-
-    /** Get the path to the state file (for debugging/logging) */
-    getFilePath(): string {
-        return this.filePath;
-    }
-}
+/**
+ * File-Based Storage Adapter
+ *
+ * Persists API key state to a JSON file on disk.
+ * Survives process restarts so keys don't reset to CLOSED
+ * when an app reboots.
+ *
+ * Extracted from the proven WhatsDeX adapter pattern.
+ *
+ * @module persistence/file
+ */
+
+import { writeFileSync, readFileSync, existsSync, mkdirSync, unlinkSync, renameSync } from 'fs';
+import { dirname, join } from 'path';
+import { tmpdir } from 'os';
+
+export interface FileStorageOptions {
+    /** Full path to the state file. Defaults to `os.tmpdir()/codedex_api_key_state.json` */
+    filePath?: string;
+    /** If true, clears any existing state file on construction (fresh start). Default: true */
+    clearOnInit?: boolean;
+}
+
+/**
+ * File-based storage adapter for ApiKeyManager.
+ *
+ * @example
+ * ```ts
+ * import { ApiKeyManager } from '@splashcodex/api-key-manager';
+ * import { FileStorage } from '@splashcodex/api-key-manager/persistence/file';
+ *
+ * const manager = new ApiKeyManager(keys, {
+ *   storage: new FileStorage({ filePath: './state.json' })
+ * });
+ * ```
+ */
+export class FileStorage {
+    private filePath: string;
+
+    constructor(options: FileStorageOptions = {}) {
+        this.filePath = options.filePath || join(tmpdir(), 'codedex_api_key_state.json');
+
+        if (options.clearOnInit !== false) {
+            this.clear();
+        }
+    }
+
+    getItem(_key: string): string | null {
+        try {
+            if (existsSync(this.filePath)) {
+                return readFileSync(this.filePath, 'utf-8');
+            }
+        } catch {
+            // Silently fail — state will be rebuilt from scratch
+        }
+        return null;
+    }
+
+    setItem(_key: string, value: string): void {
+        const tmpPath = this.filePath + '.tmp';
+        try {
+            const dir = dirname(this.filePath);
+            if (!existsSync(dir)) {
+                mkdirSync(dir, { recursive: true });
+            }
+            // Write to a temp file first, then atomically rename to the target.
+            // renameSync() is a single syscall — the file is never in a
+            // half-written state if the process crashes mid-write.
+            writeFileSync(tmpPath, value, 'utf-8');
+            renameSync(tmpPath, this.filePath);
+        } catch {
+            // Clean up temp file if rename failed
+            try { if (existsSync(tmpPath)) unlinkSync(tmpPath); } catch { /* silent */ }
+            // Silently fail — state will be lost on restart
+        }
+    }
+
+    /**
+     * Delete the persisted state file.
+     * Useful for clearing stale dead-key states from a previous session.
+     */
+    clear(): void {
+        try {
+            if (existsSync(this.filePath)) {
+                unlinkSync(this.filePath);
+            }
+        } catch {
+            // Silently fail
+        }
+    }
+
+    /** Get the path to the state file (for debugging/logging) */
+    getFilePath(): string {
+        return this.filePath;
+    }
+}

package/src/persistence/index.ts

@@ -1,7 +1,7 @@
-/**
- * Persistence Adapters
- * @module persistence
- */
-export { FileStorage } from './file';
-export type { FileStorageOptions } from './file';
-export { MemoryStorage } from './memory';
+/**
+ * Persistence Adapters
+ * @module persistence
+ */
+export { FileStorage } from './file';
+export type { FileStorageOptions } from './file';
+export { MemoryStorage } from './memory';

package/src/persistence/memory.ts

@@ -1,43 +1,43 @@
-/**
- * In-Memory Storage Adapter
- *
- * Simple key-value storage that lives only for the process lifetime.
- * Useful for testing, serverless functions, or when persistence isn't needed.
- *
- * @module persistence/memory
- */
-
-/**
- * In-memory storage adapter for ApiKeyManager.
- *
- * @example
- * ```ts
- * import { ApiKeyManager } from '@splashcodex/api-key-manager';
- * import { MemoryStorage } from '@splashcodex/api-key-manager/persistence/memory';
- *
- * const manager = new ApiKeyManager(keys, {
- *   storage: new MemoryStorage()
- * });
- * ```
- */
-export class MemoryStorage {
-    private store: Map<string, string> = new Map();
-
-    getItem(key: string): string | null {
-        return this.store.get(key) ?? null;
-    }
-
-    setItem(key: string, value: string): void {
-        this.store.set(key, value);
-    }
-
-    /** Clear all stored state */
-    clear(): void {
-        this.store.clear();
-    }
-
-    /** Get the number of stored entries */
-    get size(): number {
-        return this.store.size;
-    }
-}
+/**
+ * In-Memory Storage Adapter
+ *
+ * Simple key-value storage that lives only for the process lifetime.
+ * Useful for testing, serverless functions, or when persistence isn't needed.
+ *
+ * @module persistence/memory
+ */
+
+/**
+ * In-memory storage adapter for ApiKeyManager.
+ *
+ * @example
+ * ```ts
+ * import { ApiKeyManager } from '@splashcodex/api-key-manager';
+ * import { MemoryStorage } from '@splashcodex/api-key-manager/persistence/memory';
+ *
+ * const manager = new ApiKeyManager(keys, {
+ *   storage: new MemoryStorage()
+ * });
+ * ```
+ */
+export class MemoryStorage {
+    private store: Map<string, string> = new Map();
+
+    getItem(key: string): string | null {
+        return this.store.get(key) ?? null;
+    }
+
+    setItem(key: string, value: string): void {
+        this.store.set(key, value);
+    }
+
+    /** Clear all stored state */
+    clear(): void {
+        this.store.clear();
+    }
+
+    /** Get the number of stored entries */
+    get size(): number {
+        return this.store.size;
+    }
+}

package/src/presets/anthropic.ts

@@ -1,78 +1,78 @@
-/**
- * Anthropic Preset — One-line Claude API key management
- *
- * Pre-configured singleton with:
- * - Reads `ANTHROPIC_API_KEY` from env
- * - LatencyStrategy for optimal key selection
- * - File persistence (survives restarts)
- * - Health checks every 5 minutes
- * - Concurrency limit of 20
- *
- * @module presets/anthropic
- *
- * @example
- * ```ts
- * import { AnthropicManager } from '@splashcodex/api-key-manager/presets/anthropic';
- *
- * const result = AnthropicManager.getInstance();
- * if (!result.success) throw result.error;
- * const claude = result.data;
- *
- * const response = await claude.execute(async (key) => {
- *   const res = await fetch('https://api.anthropic.com/v1/messages', {
- *     method: 'POST',
- *     headers: {
- *       'x-api-key': key,
- *       'anthropic-version': '2023-06-01',
- *       'content-type': 'application/json',
- *     },
- *     body: JSON.stringify({
- *       model: 'claude-sonnet-4-20250514',
- *       max_tokens: 1024,
- *       messages: [{ role: 'user', content: 'Hello!' }],
- *     }),
- *   });
- *   const data = await res.json();
- *   return data.content[0].text;
- * }, { maxRetries: 3, timeoutMs: 60000 });
- * ```
- */
-
-import { BasePreset, PresetOptions, Result } from './base';
-
-export class AnthropicManager extends BasePreset {
-    private static readonly PROVIDER = 'anthropic';
-
-    private constructor(keys: string[], options: PresetOptions) {
-        super(keys, options);
-    }
-
-    private static getDefaultOptions(): Partial<PresetOptions> {
-        return {
-            envKeys: ['ANTHROPIC_API_KEY'],
-            provider: AnthropicManager.PROVIDER,
-            concurrency: 20,
-            healthCheckIntervalMs: 300_000,
-        };
-    }
-
-    /**
-     * Get or create the singleton AnthropicManager instance.
-     *
-     * @param overrides - Optional configuration overrides
-     * @returns Result<AnthropicManager>
-     */
-    static getInstance(overrides?: Partial<PresetOptions>): Result<AnthropicManager> {
-        return BasePreset.createInstance(
-            AnthropicManager as unknown as new (keys: string[], options: PresetOptions) => AnthropicManager,
-            AnthropicManager.getDefaultOptions(),
-            overrides
-        ) as Result<AnthropicManager>;
-    }
-
-    static reset(): void {
-        BasePreset.resetInstance(AnthropicManager.PROVIDER);
-    }
-}
-
-export { Result } from './base';
+/**
+ * Anthropic Preset — One-line Claude API key management
+ *
+ * Pre-configured singleton with:
+ * - Reads `ANTHROPIC_API_KEY` from env
+ * - LatencyStrategy for optimal key selection
+ * - File persistence (survives restarts)
+ * - Health checks every 5 minutes
+ * - Concurrency limit of 20
+ *
+ * @module presets/anthropic
+ *
+ * @example
+ * ```ts
+ * import { AnthropicManager } from '@splashcodex/api-key-manager/presets/anthropic';
+ *
+ * const result = AnthropicManager.getInstance();
+ * if (!result.success) throw result.error;
+ * const claude = result.data;
+ *
+ * const response = await claude.execute(async (key) => {
+ *   const res = await fetch('https://api.anthropic.com/v1/messages', {
+ *     method: 'POST',
+ *     headers: {
+ *       'x-api-key': key,
+ *       'anthropic-version': '2023-06-01',
+ *       'content-type': 'application/json',
+ *     },
+ *     body: JSON.stringify({
+ *       model: 'claude-sonnet-4-20250514',
+ *       max_tokens: 1024,
+ *       messages: [{ role: 'user', content: 'Hello!' }],
+ *     }),
+ *   });
+ *   const data = await res.json();
+ *   return data.content[0].text;
+ * }, { maxRetries: 3, timeoutMs: 60000 });
+ * ```
+ */
+
+import { BasePreset, PresetOptions, Result } from './base';
+
+export class AnthropicManager extends BasePreset {
+    private static readonly PROVIDER = 'anthropic';
+
+    private constructor(keys: string[], options: PresetOptions) {
+        super(keys, options);
+    }
+
+    private static getDefaultOptions(): Partial<PresetOptions> {
+        return {
+            envKeys: ['ANTHROPIC_API_KEY'],
+            provider: AnthropicManager.PROVIDER,
+            concurrency: 20,
+            healthCheckIntervalMs: 300_000,
+        };
+    }
+
+    /**
+     * Get or create the singleton AnthropicManager instance.
+     *
+     * @param overrides - Optional configuration overrides
+     * @returns Result<AnthropicManager>
+     */
+    static getInstance(overrides?: Partial<PresetOptions>): Result<AnthropicManager> {
+        return BasePreset.createInstance(
+            AnthropicManager as unknown as new (keys: string[], options: PresetOptions) => AnthropicManager,
+            AnthropicManager.getDefaultOptions(),
+            overrides
+        ) as Result<AnthropicManager>;
+    }
+
+    static reset(): void {
+        BasePreset.resetInstance(AnthropicManager.PROVIDER);
+    }
+}
+
+export { Result } from './base';