@splashcodex/api-key-manager 4.1.0 → 5.0.0

package/dist/persistence/file.js

@@ -0,0 +1,82 @@
+"use strict";
+/**
+ * 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
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FileStorage = void 0;
+const fs_1 = require("fs");
+const path_1 = require("path");
+const os_1 = require("os");
+/**
+ * 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' })
+ * });
+ * ```
+ */
+class FileStorage {
+    filePath;
+    constructor(options = {}) {
+        this.filePath = options.filePath || (0, path_1.join)((0, os_1.tmpdir)(), 'codedex_api_key_state.json');
+        if (options.clearOnInit !== false) {
+            this.clear();
+        }
+    }
+    getItem(_key) {
+        try {
+            if ((0, fs_1.existsSync)(this.filePath)) {
+                return (0, fs_1.readFileSync)(this.filePath, 'utf-8');
+            }
+        }
+        catch {
+            // Silently fail — state will be rebuilt from scratch
+        }
+        return null;
+    }
+    setItem(_key, value) {
+        try {
+            const dir = (0, path_1.dirname)(this.filePath);
+            if (!(0, fs_1.existsSync)(dir)) {
+                (0, fs_1.mkdirSync)(dir, { recursive: true });
+            }
+            (0, fs_1.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() {
+        try {
+            if ((0, fs_1.existsSync)(this.filePath)) {
+                (0, fs_1.unlinkSync)(this.filePath);
+            }
+        }
+        catch {
+            // Silently fail
+        }
+    }
+    /** Get the path to the state file (for debugging/logging) */
+    getFilePath() {
+        return this.filePath;
+    }
+}
+exports.FileStorage = FileStorage;
+//# sourceMappingURL=file.js.map

package/dist/persistence/file.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"file.js","sourceRoot":"","sources":["../../src/persistence/file.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;GAUG;;;AAEH,2BAAoF;AACpF,+BAAqC;AACrC,2BAA4B;AAS5B;;;;;;;;;;;;GAYG;AACH,MAAa,WAAW;IACZ,QAAQ,CAAS;IAEzB,YAAY,UAA8B,EAAE;QACxC,IAAI,CAAC,QAAQ,GAAG,OAAO,CAAC,QAAQ,IAAI,IAAA,WAAI,EAAC,IAAA,WAAM,GAAE,EAAE,4BAA4B,CAAC,CAAC;QAEjF,IAAI,OAAO,CAAC,WAAW,KAAK,KAAK,EAAE,CAAC;YAChC,IAAI,CAAC,KAAK,EAAE,CAAC;QACjB,CAAC;IACL,CAAC;IAED,OAAO,CAAC,IAAY;QAChB,IAAI,CAAC;YACD,IAAI,IAAA,eAAU,EAAC,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC;gBAC5B,OAAO,IAAA,iBAAY,EAAC,IAAI,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;YAChD,CAAC;QACL,CAAC;QAAC,MAAM,CAAC;YACL,qDAAqD;QACzD,CAAC;QACD,OAAO,IAAI,CAAC;IAChB,CAAC;IAED,OAAO,CAAC,IAAY,EAAE,KAAa;QAC/B,IAAI,CAAC;YACD,MAAM,GAAG,GAAG,IAAA,cAAO,EAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;YACnC,IAAI,CAAC,IAAA,eAAU,EAAC,GAAG,CAAC,EAAE,CAAC;gBACnB,IAAA,cAAS,EAAC,GAAG,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;YACxC,CAAC;YACD,IAAA,kBAAa,EAAC,IAAI,CAAC,QAAQ,EAAE,KAAK,EAAE,OAAO,CAAC,CAAC;QACjD,CAAC;QAAC,MAAM,CAAC;YACL,gDAAgD;QACpD,CAAC;IACL,CAAC;IAED;;;OAGG;IACH,KAAK;QACD,IAAI,CAAC;YACD,IAAI,IAAA,eAAU,EAAC,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC;gBAC5B,IAAA,eAAU,EAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;YAC9B,CAAC;QACL,CAAC;QAAC,MAAM,CAAC;YACL,gBAAgB;QACpB,CAAC;IACL,CAAC;IAED,6DAA6D;IAC7D,WAAW;QACP,OAAO,IAAI,CAAC,QAAQ,CAAC;IACzB,CAAC;CACJ;AApDD,kCAoDC"}

package/dist/persistence/index.d.ts

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

package/dist/persistence/index.js

@@ -0,0 +1,12 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MemoryStorage = exports.FileStorage = void 0;
+/**
+ * Persistence Adapters
+ * @module persistence
+ */
+var file_1 = require("./file");
+Object.defineProperty(exports, "FileStorage", { enumerable: true, get: function () { return file_1.FileStorage; } });
+var memory_1 = require("./memory");
+Object.defineProperty(exports, "MemoryStorage", { enumerable: true, get: function () { return memory_1.MemoryStorage; } });
+//# sourceMappingURL=index.js.map

package/dist/persistence/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/persistence/index.ts"],"names":[],"mappings":";;;AAAA;;;GAGG;AACH,+BAAqC;AAA5B,mGAAA,WAAW,OAAA;AAEpB,mCAAyC;AAAhC,uGAAA,aAAa,OAAA"}

package/dist/persistence/memory.d.ts

@@ -0,0 +1,30 @@
+/**
+ * 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 declare class MemoryStorage {
+    private store;
+    getItem(key: string): string | null;
+    setItem(key: string, value: string): void;
+    /** Clear all stored state */
+    clear(): void;
+    /** Get the number of stored entries */
+    get size(): number;
+}

package/dist/persistence/memory.js

@@ -0,0 +1,43 @@
+"use strict";
+/**
+ * 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
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MemoryStorage = void 0;
+/**
+ * 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()
+ * });
+ * ```
+ */
+class MemoryStorage {
+    store = new Map();
+    getItem(key) {
+        return this.store.get(key) ?? null;
+    }
+    setItem(key, value) {
+        this.store.set(key, value);
+    }
+    /** Clear all stored state */
+    clear() {
+        this.store.clear();
+    }
+    /** Get the number of stored entries */
+    get size() {
+        return this.store.size;
+    }
+}
+exports.MemoryStorage = MemoryStorage;
+//# sourceMappingURL=memory.js.map

package/dist/persistence/memory.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory.js","sourceRoot":"","sources":["../../src/persistence/memory.ts"],"names":[],"mappings":";AAAA;;;;;;;GAOG;;;AAEH;;;;;;;;;;;;GAYG;AACH,MAAa,aAAa;IACd,KAAK,GAAwB,IAAI,GAAG,EAAE,CAAC;IAE/C,OAAO,CAAC,GAAW;QACf,OAAO,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,IAAI,CAAC;IACvC,CAAC;IAED,OAAO,CAAC,GAAW,EAAE,KAAa;QAC9B,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;IAC/B,CAAC;IAED,6BAA6B;IAC7B,KAAK;QACD,IAAI,CAAC,KAAK,CAAC,KAAK,EAAE,CAAC;IACvB,CAAC;IAED,uCAAuC;IACvC,IAAI,IAAI;QACJ,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC;IAC3B,CAAC;CACJ;AApBD,sCAoBC"}

package/dist/presets/base.d.ts

@@ -0,0 +1,138 @@
+/**
+ * BasePreset — Shared foundation for all provider presets
+ *
+ * Provides the "batteries included" pattern:
+ * - Singleton lifecycle management
+ * - Environment variable parsing (single key or JSON array)
+ * - File-based persistence (survives restarts)
+ * - Event-to-logger wiring
+ * - Health check scheduling
+ * - Result<T> pattern for safe initialization
+ *
+ * @module presets/base
+ */
+import { ApiKeyManager, ExecuteOptions, ApiKeyManagerOptions, LoadBalancingStrategy } from '../index';
+/**
+ * A discriminated union for safe error handling without exceptions.
+ * Used by `getInstance()` to avoid crashing on missing env vars.
+ */
+export type Result<T> = {
+    success: true;
+    data: T;
+} | {
+    success: false;
+    error: Error;
+};
+export interface PresetOptions {
+    /** Environment variable name(s) to read API keys from. */
+    envKeys: string[];
+    /** Provider name for logging and file state isolation. Default: 'default' */
+    provider?: string;
+    /** Load balancing strategy. Default: LatencyStrategy */
+    strategy?: LoadBalancingStrategy;
+    /** Max concurrent execute() calls. Default: 20 */
+    concurrency?: number;
+    /** Health check interval in ms. Set to 0 to disable. Default: 300_000 (5 min) */
+    healthCheckIntervalMs?: number;
+    /** Custom health check function. If not set, health checks are disabled. */
+    healthCheckFn?: (key: string) => Promise<boolean>;
+    /** Semantic cache config. Optional. */
+    semanticCache?: ApiKeyManagerOptions['semanticCache'];
+    /** Custom logger. Defaults to console. */
+    logger?: PresetLogger;
+    /** Fallback function when all keys are exhausted. */
+    fallbackFn?: () => any;
+    /** Custom state file path. Defaults to `os.tmpdir()/codedex_{provider}_state.json` */
+    stateFilePath?: string;
+}
+export interface PresetLogger {
+    info(message: string, ...args: any[]): void;
+    warn(message: string, ...args: any[]): void;
+    error(message: string, ...args: any[]): void;
+}
+/**
+ * Abstract base class for provider presets.
+ * Subclasses only need to define `getDefaultOptions()` with provider-specific
+ * defaults (env var name, health check function, etc.).
+ *
+ * @example
+ * ```ts
+ * // Creating a custom preset:
+ * class MyProviderPreset extends BasePreset {
+ *   protected static getDefaultOptions(): Partial<PresetOptions> {
+ *     return {
+ *       envKeys: ['MY_PROVIDER_API_KEY'],
+ *       provider: 'my-provider',
+ *     };
+ *   }
+ * }
+ * ```
+ */
+export declare abstract class BasePreset {
+    private static instances;
+    protected manager: ApiKeyManager;
+    protected logger: PresetLogger;
+    protected options: Required<Pick<PresetOptions, 'provider' | 'concurrency' | 'healthCheckIntervalMs'>> & PresetOptions;
+    protected constructor(apiKeys: string[], options: PresetOptions);
+    /**
+     * Wire all manager events to the logger.
+     */
+    private wireEvents;
+    /**
+     * Execute a function with automatic key rotation, retries, timeout, and caching.
+     */
+    execute<T>(fn: (key: string, signal?: AbortSignal) => Promise<T>, options?: ExecuteOptions & {
+        prompt?: string;
+    }): Promise<T>;
+    /**
+     * Execute a streaming function with retry on initial connection failure.
+     */
+    executeStream<T>(fn: (key: string, signal?: AbortSignal) => AsyncGenerator<T, any, unknown>, options?: ExecuteOptions & {
+        prompt?: string;
+    }): AsyncGenerator<T, any, unknown>;
+    /**
+     * Get the best available API key directly (low-level).
+     */
+    getKey(): string | null;
+    /**
+     * Get the number of non-dead keys.
+     */
+    getKeyCount(): number;
+    /**
+     * Get pool health statistics.
+     */
+    getStats(): import("../index").ApiKeyManagerStats;
+    /**
+     * Get the underlying ApiKeyManager instance for advanced use.
+     */
+    getManager(): ApiKeyManager;
+    /**
+     * Stop health checks and clean up. Call when shutting down.
+     */
+    destroy(): void;
+    /**
+     * Parse API keys from environment variables.
+     * Supports:
+     * - Single key: `"AIza..."`
+     * - JSON array: `'["AIza...", "AIzb..."]'`
+     * - Comma-separated: `"AIza...,AIzb..."`
+     */
+    protected static parseKeysFromEnv(envKeys: string[]): string[];
+    /**
+     * Get or create the singleton instance for a preset.
+     * This is the core factory used by all preset subclasses.
+     *
+     * @param PresetClass - The preset class to instantiate
+     * @param overrides - Optional overrides for preset options
+     * @returns Result<T> — either `{ success: true, data: instance }` or `{ success: false, error }`
+     */
+    protected static createInstance<T extends BasePreset>(PresetClass: new (keys: string[], options: PresetOptions) => T, defaultOptions: Partial<PresetOptions>, overrides?: Partial<PresetOptions>): Result<T>;
+    /**
+     * Reset a singleton instance (primarily for testing).
+     */
+    protected static resetInstance(provider: string): void;
+    /**
+     * Reset ALL singleton instances (primarily for testing).
+     */
+    static resetAll(): void;
+}

package/dist/presets/base.js

@@ -0,0 +1,227 @@
+"use strict";
+/**
+ * BasePreset — Shared foundation for all provider presets
+ *
+ * Provides the "batteries included" pattern:
+ * - Singleton lifecycle management
+ * - Environment variable parsing (single key or JSON array)
+ * - File-based persistence (survives restarts)
+ * - Event-to-logger wiring
+ * - Health check scheduling
+ * - Result<T> pattern for safe initialization
+ *
+ * @module presets/base
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BasePreset = void 0;
+const index_1 = require("../index");
+const file_1 = require("../persistence/file");
+const path_1 = require("path");
+const os_1 = require("os");
+// ─── Base Preset Class ──────────────────────────────────────────────────────
+/**
+ * Abstract base class for provider presets.
+ * Subclasses only need to define `getDefaultOptions()` with provider-specific
+ * defaults (env var name, health check function, etc.).
+ *
+ * @example
+ * ```ts
+ * // Creating a custom preset:
+ * class MyProviderPreset extends BasePreset {
+ *   protected static getDefaultOptions(): Partial<PresetOptions> {
+ *     return {
+ *       envKeys: ['MY_PROVIDER_API_KEY'],
+ *       provider: 'my-provider',
+ *     };
+ *   }
+ * }
+ * ```
+ */
+class BasePreset {
+    static instances = new Map();
+    manager;
+    logger;
+    options;
+    constructor(apiKeys, options) {
+        this.logger = options.logger || console;
+        this.options = {
+            provider: options.provider || 'default',
+            concurrency: options.concurrency ?? 20,
+            healthCheckIntervalMs: options.healthCheckIntervalMs ?? 300_000,
+            ...options,
+        };
+        const stateFile = this.options.stateFilePath ||
+            (0, path_1.join)((0, os_1.tmpdir)(), `codedex_${this.options.provider}_state.json`);
+        const storage = new file_1.FileStorage({
+            filePath: stateFile,
+            clearOnInit: true, // Fresh start each session to clear stale DEAD keys
+        });
+        this.manager = new index_1.ApiKeyManager(apiKeys, {
+            storage,
+            strategy: this.options.strategy || new index_1.LatencyStrategy(),
+            fallbackFn: this.options.fallbackFn,
+            concurrency: this.options.concurrency,
+            semanticCache: this.options.semanticCache,
+        });
+        this.wireEvents();
+        if (this.options.healthCheckFn && this.options.healthCheckIntervalMs > 0) {
+            this.manager.setHealthCheck(this.options.healthCheckFn);
+            this.manager.startHealthChecks(this.options.healthCheckIntervalMs);
+        }
+        this.logger.info(`[${this.options.provider}] ApiKeyManager initialized with ${apiKeys.length} keys ` +
+            `(Strategy: ${this.options.strategy?.constructor.name || 'LatencyStrategy'}, ` +
+            `Concurrency: ${this.options.concurrency}, ` +
+            `HealthChecks: ${this.options.healthCheckIntervalMs > 0 ? `every ${this.options.healthCheckIntervalMs / 1000}s` : 'disabled'})`);
+    }
+    /**
+     * Wire all manager events to the logger.
+     */
+    wireEvents() {
+        const tag = this.options.provider;
+        this.manager.on('keyDead', (key) => this.logger.error(`[${tag}] Key PERMANENTLY DEAD: ...${key.slice(-4)}`));
+        this.manager.on('circuitOpen', (key) => this.logger.warn(`[${tag}] Circuit OPEN (cooldown): ...${key.slice(-4)}`));
+        this.manager.on('keyRecovered', (key) => this.logger.info(`[${tag}] Key RECOVERED: ...${key.slice(-4)}`));
+        this.manager.on('retry', (key, attempt, delay) => this.logger.info(`[${tag}] Retry with ...${key.slice(-4)} (Attempt ${attempt}, Delay ${delay}ms)`));
+        this.manager.on('fallback', (reason) => this.logger.warn(`[${tag}] Triggering FALLBACK: ${reason}`));
+        this.manager.on('allKeysExhausted', () => this.logger.error(`[${tag}] ALL KEYS EXHAUSTED! No fallback available.`));
+        this.manager.on('bulkheadRejected', () => this.logger.warn(`[${tag}] Bulkhead rejected request (concurrency limit reached)`));
+        this.manager.on('healthCheckPassed', (key) => this.logger.info(`[${tag}] Health check PASSED: ...${key.slice(-4)}`));
+        this.manager.on('healthCheckFailed', (key) => this.logger.warn(`[${tag}] Health check FAILED: ...${key.slice(-4)}`));
+    }
+    // ─── Public API ─────────────────────────────────────────────────────────
+    /**
+     * Execute a function with automatic key rotation, retries, timeout, and caching.
+     */
+    async execute(fn, options) {
+        return this.manager.execute(fn, options);
+    }
+    /**
+     * Execute a streaming function with retry on initial connection failure.
+     */
+    async *executeStream(fn, options) {
+        yield* this.manager.executeStream(fn, options);
+    }
+    /**
+     * Get the best available API key directly (low-level).
+     */
+    getKey() {
+        return this.manager.getKey();
+    }
+    /**
+     * Get the number of non-dead keys.
+     */
+    getKeyCount() {
+        return this.manager.getKeyCount();
+    }
+    /**
+     * Get pool health statistics.
+     */
+    getStats() {
+        return this.manager.getStats();
+    }
+    /**
+     * Get the underlying ApiKeyManager instance for advanced use.
+     */
+    getManager() {
+        return this.manager;
+    }
+    /**
+     * Stop health checks and clean up. Call when shutting down.
+     */
+    destroy() {
+        this.manager.stopHealthChecks();
+    }
+    // ─── Static Factory ─────────────────────────────────────────────────────
+    /**
+     * Parse API keys from environment variables.
+     * Supports:
+     * - Single key: `"AIza..."`
+     * - JSON array: `'["AIza...", "AIzb..."]'`
+     * - Comma-separated: `"AIza...,AIzb..."`
+     */
+    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;
+            // Try JSON array
+            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 valid JSON, fall through to comma split
+                }
+            }
+            // Comma-separated or single key
+            keys.push(...trimmed.split(',').map(k => k.trim()).filter(k => k.length > 0));
+        }
+        return [...new Set(keys)]; // Deduplicate
+    }
+    /**
+     * Get or create the singleton instance for a preset.
+     * This is the core factory used by all preset subclasses.
+     *
+     * @param PresetClass - The preset class to instantiate
+     * @param overrides - Optional overrides for preset options
+     * @returns Result<T> — either `{ success: true, data: instance }` or `{ success: false, error }`
+     */
+    static createInstance(PresetClass, defaultOptions, overrides) {
+        const mergedOptions = { ...defaultOptions, ...overrides };
+        const instanceKey = mergedOptions.provider || PresetClass.name;
+        // Return existing singleton
+        const existing = BasePreset.instances.get(instanceKey);
+        if (existing) {
+            return { success: true, data: existing };
+        }
+        // Parse keys
+        const envKeys = mergedOptions.envKeys || [];
+        const keys = BasePreset.parseKeysFromEnv(envKeys);
+        if (keys.length === 0) {
+            const logger = mergedOptions.logger || console;
+            logger.warn(`[${instanceKey}] No API keys found in env vars: ${envKeys.join(', ')}. ` +
+                `AI features will be disabled.`);
+            // Still create the instance with empty keys — allows graceful degradation
+        }
+        try {
+            const instance = new PresetClass(keys, mergedOptions);
+            BasePreset.instances.set(instanceKey, instance);
+            return { success: true, data: instance };
+        }
+        catch (error) {
+            return {
+                success: false,
+                error: error instanceof Error ? error : new Error(String(error)),
+            };
+        }
+    }
+    /**
+     * Reset a singleton instance (primarily for testing).
+     */
+    static resetInstance(provider) {
+        const existing = BasePreset.instances.get(provider);
+        if (existing) {
+            existing.destroy();
+            BasePreset.instances.delete(provider);
+        }
+    }
+    /**
+     * Reset ALL singleton instances (primarily for testing).
+     */
+    static resetAll() {
+        for (const [, instance] of BasePreset.instances) {
+            instance.destroy();
+        }
+        BasePreset.instances.clear();
+    }
+}
+exports.BasePreset = BasePreset;
+//# sourceMappingURL=base.js.map

package/dist/presets/base.js.map

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

package/dist/presets/gemini.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Gemini Preset — One-line Gemini API key management
+ *
+ * Pre-configured singleton with:
+ * - Reads `GOOGLE_GEMINI_API_KEY` or `GEMINI_API_KEY` from env
+ * - LatencyStrategy for optimal key selection
+ * - File persistence (survives restarts)
+ * - Health checks every 5 minutes
+ * - Concurrency limit of 20
+ *
+ * @module presets/gemini
+ *
+ * @example
+ * ```ts
+ * import { GeminiManager } from '@splashcodex/api-key-manager/presets/gemini';
+ *
+ * // Initialize once (reads keys from process.env automatically)
+ * const result = GeminiManager.getInstance();
+ * if (!result.success) throw result.error;
+ * const gemini = result.data;
+ *
+ * // Use the execute() wrapper for automatic key rotation + retries
+ * const response = await gemini.execute(async (key) => {
+ *   const genAI = new GoogleGenerativeAI(key);
+ *   const model = genAI.getGenerativeModel({ model: 'gemini-2.0-flash' });
+ *   const res = await model.generateContent('Hello, world!');
+ *   return res.response.text();
+ * }, { maxRetries: 3, timeoutMs: 30000 });
+ * ```
+ */
+import { BasePreset, PresetOptions, Result } from './base';
+export declare class GeminiManager extends BasePreset {
+    private static readonly PROVIDER;
+    private constructor();
+    /**
+     * Default configuration for Gemini presets.
+     */
+    private static getDefaultOptions;
+    /**
+     * Get or create the singleton GeminiManager instance.
+     *
+     * @param overrides - Optional configuration overrides
+     * @returns Result<GeminiManager> — safely check `.success` before using `.data`
+     *
+     * @example
+     * ```ts
+     * const result = GeminiManager.getInstance();
+     * if (result.success) {
+     *   const gemini = result.data;
+     *   const text = await gemini.execute(apiCall, { maxRetries: 3 });
+     * }
+     * ```
+     */
+    static getInstance(overrides?: Partial<PresetOptions>): Result<GeminiManager>;
+    /**
+     * Reset the singleton instance. Primarily for testing.
+     */
+    static reset(): void;
+}
+export { Result } from './base';