@omnicross/core 0.1.1 → 0.1.3

package/dist/ApiKeyPoolService-BmMkau07.d.ts

@@ -1,170 +0,0 @@
-import { ApiKeyEntry } from '@omnicross/contracts/llm-config';
-
-/**
- * `Logger` — core-owned port for the structured logger the serving core uses.
- *
- * The serving core MUST depend on THIS interface, never on the concrete host
- * `LoggerService` class as a type. The host (`LoggerService`) already exposes a
- * superset of this surface, so it is passed directly with NO adapter.
- *
- * `error` uses the WIDEST signature `(message, error?, meta?)` so every core
- * call site — `error(msg)`, `error(msg, errInstance)`, `error(msg, err, meta)` —
- * stays assignable (design Q2). `info`/`warn`/`debug` take an optional `meta`
- * bag matching the host's `Record<string, unknown> | Error | object`.
- *
- * @module ports/logger
- */
-interface Logger {
-    info(message: string, meta?: Record<string, unknown> | Error | object): void;
-    warn(message: string, meta?: Record<string, unknown> | Error | object): void;
-    error(message: string, error?: unknown, meta?: Record<string, unknown> | object): void;
-    debug(message: string, meta?: Record<string, unknown> | Error | object): void;
-}
-
-/**
- * ApiKeyPoolService - Multi-API-key load balancing with session affinity
- *
- * Manages a pool of API keys per provider, selecting keys via weighted
- * round-robin and maintaining session-level key affinity to preserve
- * prompt cache across requests within the same session.
- */
-
-/** Live health snapshot for a single key currently in cooldown. */
-interface KeyHealthEntry {
-    /** Epoch-ms when the cooldown expires */
-    until: number;
-    /** Number of consecutive errors */
-    errors: number;
-    /** HTTP status that triggered the most recent cooldown */
-    lastStatus: number | null;
-}
-/** Provider-scoped map of keyId → live cooldown health (cooling keys only). */
-type KeyHealthMap = Record<string, KeyHealthEntry>;
-/** Function type for loading API keys from the database */
-type ApiKeysLoader = (providerId: string) => Promise<ApiKeyEntry[]>;
-/** Function type for disabling a key in the database (on auth failure) */
-type ApiKeyDisabler = (keyId: string) => Promise<boolean>;
-/**
- * Function type for auto-disabling a key in the database on auth failure,
- * persisting the offending status + timestamp so the client UI can surface
- * a per-key health indicator. Preferred over {@link ApiKeyDisabler} when set.
- */
-type ApiKeyAutoDisabler = (keyId: string, status: number, at: number) => Promise<void>;
-/** Function type for resolving environment variable references in API keys */
-type ApiKeyResolver = (rawKey: string) => string;
-declare class ApiKeyPoolService {
-    private loadKeys;
-    private resolveKey;
-    private logger;
-    private disableKey?;
-    private markAutoDisabled?;
-    /** Session 鈫?key binding (session affinity) */
-    private sessionBindings;
-    /** Provider 鈫?round-robin index */
-    private rrIndex;
-    /** Provider 鈫?cached key list */
-    private keyCache;
-    /** Key ID 鈫?cooldown state */
-    private cooldowns;
-    /** Cleanup interval handle */
-    private cleanupTimer;
-    private readonly DEFAULT_COOLDOWN_MS;
-    private readonly MAX_COOLDOWN_MS;
-    private readonly COOLDOWN_MULTIPLIER;
-    constructor(loadKeys: ApiKeysLoader, resolveKey: ApiKeyResolver, logger: Logger, disableKey?: ApiKeyDisabler | undefined, markAutoDisabled?: ApiKeyAutoDisabler | undefined);
-    /**
-     * Get the API key for a session. Implements session affinity.
-     *
-     * First call for a session binds it to a key via weighted round-robin.
-     * Subsequent calls return the same key (preserves prompt cache).
-     *
-     * @returns Resolved API key string, or empty string if no keys available
-     */
-    /**
-     * Read which key id is currently bound to the given session, if any.
-     * Returns null when the session has not yet been bound (first call hasn't
-     * happened) or when the binding is for a different provider.
-     *
-     * Used by the usage-recorder attribution path: after `getKeyForSession`
-     * completes the caller looks up the keyId so the recorded usage
-     * row can attribute spend to a specific pool key.
-     */
-    getKeyIdForSession(providerId: string, sessionId: string): string | null;
-    getKeyForSession(providerId: string, sessionId: string): Promise<string>;
-    /**
-     * Get a key without session affinity (for one-shot calls like testConnection).
-     *
-     * @returns Resolved API key string, or empty string if no keys available
-     */
-    getKey(providerId: string): Promise<string>;
-    /**
-     * Report an error for the current session's key.
-     *
-     * - 429/529 (rate limit / overload): puts key in cooldown with exponential backoff
-     * - 401/403 (auth failure): permanently disables the key in the database
-     *
-     * In both cases, re-binds the session to a different key if available.
-     *
-     * @param statusCode HTTP status code
-     * @returns New resolved API key if re-binding succeeded, null if no keys available
-     */
-    reportError(providerId: string, sessionId: string, statusCode: number): Promise<string | null>;
-    /**
-     * Report a successful request — resets cooldown counter for the session's key.
-     */
-    reportSuccess(sessionId: string): void;
-    /**
-     * Release session binding (call when session ends or is deleted).
-     */
-    releaseSession(sessionId: string): void;
-    /**
-     * Invalidate the key cache. Call after CRUD operations on API keys.
-     */
-    invalidateCache(providerId?: string): void;
-    /**
-     * Check if a provider has any keys in the pool.
-     */
-    hasKeys(providerId: string): Promise<boolean>;
-    /**
-     * Get the live (in-memory) rate-limit cooldown health for a provider's keys.
-     *
-     * Returns ONLY keys that are currently cooling down (cooldown `until` is in
-     * the future). A key absent from the returned map is not cooling. This is a
-     * pure read of the in-memory cooldown map — auth-failure auto-disable state
-     * is persisted on the key row itself (getApiKeys) and is NOT included here.
-     */
-    getKeyHealth(providerId: string): Promise<KeyHealthMap>;
-    /**
-     * Dispose of the service (stop cleanup timer).
-     */
-    dispose(): void;
-    /**
-     * Handle auth failure (401/403): disable the key in DB permanently.
-     */
-    private handleAuthFailure;
-    /**
-     * Apply cooldown with exponential backoff for rate-limit errors (429/529).
-     */
-    private applyCooldown;
-    /**
-     * Get all keys for a provider (with caching).
-     */
-    private getAllKeys;
-    /**
-     * Get available keys: enabled AND not in cooldown.
-     */
-    private getAvailableKeys;
-    /**
-     * Weighted round-robin selection.
-     *
-     * Each key's weight determines how many "slots" it occupies in the rotation.
-     * The round-robin index advances by 1 on each call per provider.
-     */
-    private selectWeightedRoundRobin;
-    /**
-     * Clean up expired cooldowns.
-     */
-    private cleanupExpiredCooldowns;
-}
-
-export { ApiKeyPoolService as A, type KeyHealthEntry as K, type Logger as L, type ApiKeyAutoDisabler as a, type ApiKeyDisabler as b, type ApiKeyResolver as c, type ApiKeysLoader as d, type KeyHealthMap as e };