import type { Provider } from "../types.js"; import type { CredentialRankingContext, CredentialRankingStrategy, PlanGate, UsageReport } from "../usage.js"; import type { RankingStrategyResolver } from "../usage/registry.js"; import type { SessionAffinity } from "./affinity.js"; import { type CredentialBlocks } from "./blocks.js"; import type { AccountPolicies } from "./policy.js"; import { type CredentialPool } from "./pool.js"; import { type ApiKeySelection, type OAuthSelection } from "./rank.js"; import { type OAuthRefresher } from "./refresh.js"; import type { AuthCredentialStore } from "./store.js"; import { type ApiKeyCredential, type AuthApiKeyOptions, type AuthCredential, type OAuthCredential } from "./types.js"; import type { UsageService } from "./usage.js"; /** Temporary block after a transient OAuth refresh failure. */ export declare const OAUTH_REFRESH_FAILURE_BACKOFF_MS: number; /** OAuth bearer and credential chosen for a request, with its durable row id when available. */ export type OAuthResolutionResult = { apiKey: string; credential: OAuthCredential; credentialId?: number; }; /** Options for CredentialSelector.tryOAuth when evaluating one OAuth credential. */ export type TryOAuthOptions = { checkUsage: boolean; allowBlocked: boolean; prefetchedUsage?: UsageReport | null; usagePrechecked?: boolean; planGate?: PlanGate; enforcePlanRequirement?: boolean; strategy?: CredentialRankingStrategy; rankingContext?: CredentialRankingContext; blockScope?: string; blockScopes?: readonly string[]; /** When false, a definitive failure of THIS credential returns undefined instead of falling back to the ranked/round-robin selector (target-only resolution). */ allowFallback?: boolean; /** Receives a non-definitive refresh failure that left this credential unusable; the caller filters for retryable ones. */ onTransientRefreshFailure?: (error: unknown) => void; }; /** Services consulted by CredentialSelector for policy, usage, blocks, refresh, and session affinity. */ export interface CredentialSelectorDeps { store: AuthCredentialStore; pool: CredentialPool; policies: AccountPolicies; blocks: CredentialBlocks; affinity: SessionAffinity; usage: UsageService; refresher: OAuthRefresher; strategies: RankingStrategyResolver; } /** Picks which stored credential serves a request: ordering, usage ranking, OAuth refresh ladder. */ export declare class CredentialSelector { #private; constructor(deps: CredentialSelectorDeps); /** Restart round-robin assignments after a provider's credential set changes. */ resetRoundRobin(provider: string): void; /** * Selects a credential of the specified type for a provider. * Returns both the credential and its index in the original array (for updates/removal). * With `sessionId` the scan starts at the session's hashed index; without one it starts at the * first stored credential and never advances round-robin. Model discovery peeks through this, * and credential-scoped catalogs (e.g. GitHub Copilot) key their cache rows on the credential * picked, so a rotating pick would read another account's cache namespace on every pass. * Blocked credentials are skipped when possible. */ selectByType(provider: string, type: T, sessionId?: string, filter?: (credential: AuthCredential) => boolean): { credential: Extract; index: number; } | undefined; selectApiKey(provider: string, sessionId: string | undefined, options: AuthApiKeyOptions | undefined, filter?: (credential: ApiKeyCredential) => boolean): Promise; /** Warm exactly the usage fetches a fresh, unpinned OAuth ranking pass needs. */ prefetchUsage(provider: string, sessionId?: string, options?: AuthApiKeyOptions): Promise; /** * Resolves an OAuth credential, trying credentials in priority order. * * Resolution ladder — a request in hand always beats "no API key": * 1. strict: unblocked credentials only, usage limits respected, plan * filter enforced (when any account is confirmed eligible); * 2. plan-fitting last resort: same plan filter, but blocked/exhausted * accounts are allowed (an explicit session pin first, then blocked * candidates earliest-unblocking first) so the caller gets real * usage-limit semantics from the wire instead of a missing key; * 3. unfiltered last resort: the plan filter matched nothing usable — * skip it and try every account once; the server is the final arbiter * of model access. * * Returns both the API key bytes for outbound requests AND the refreshed * {@link OAuthCredential} so callers needing identity metadata (account id, * project id, etc.) do not have to dereference the snapshot themselves. */ resolveOAuth(provider: string, sessionId?: string, options?: AuthApiKeyOptions): Promise; /** Attempts to use a single OAuth credential, checking usage and refreshing token. */ tryOAuth(provider: Provider, selection: OAuthSelection, providerKey: string, sessionId: string | undefined, options: AuthApiKeyOptions | undefined, usageOptions: TryOAuthOptions): Promise; }