import type { LimitsApi, OAuthAccess, OAuthApi, OAuthRequestIdentity } from "./auth/types.js";
import { isAuthRetryableError } from "./error/auth-classify.js";
/**
 * Context passed to an {@link ApiKeyResolver} on each resolution attempt.
 *
 * The `error`/`lastChance` pair preserves the legacy a/b/c resolver contract
 * shared by streaming ({@link streamSimple}) and non-streaming ({@link withAuth})
 * drivers:
 * - `error === undefined` → **initial resolve** (no force-refresh; cheap, may
 *   return a locally-cached not-yet-expired token).
 * - `error !== undefined && !lastChance` → **step (b): refresh the SAME
 *   account** (force a token re-mint / await an in-flight broker refresh).
 * - `error !== undefined && lastChance` → **step (c): switch account**
 *   (invalidate/usage-limit the current credential and rotate to a sibling).
 *
 * Current drivers give an ordinary 401/auth failure one step (b) before
 * repeating step (c) through distinct siblings. Account-scoped policy denials,
 * 403s, and usage-limit failures skip refresh. Rotation stops when the resolver
 * returns `undefined`, cycles, or hits {@link AUTH_RETRY_MAX_ATTEMPTS}.
 */
export interface ApiKeyResolveContext {
    /** True when the resolver should rotate to a sibling credential. */
    lastChance: boolean;
    /** The auth error that triggered this re-resolution, or `undefined` on the initial resolve. */
    error: unknown;
    /** Bearer used by the failed attempt, when the caller can expose it. */
    previousKey?: string;
    /** Caller cancel signal, threaded into any credential refresh / rotation work. */
    signal?: AbortSignal;
}
/**
 * Resolves the API key to send for a request, retried through the a/b/c policy
 * described on {@link ApiKeyResolveContext}.
 */
export interface ResolvedApiKey {
    apiKey: string;
    /** Durable row id of the credential that supplied this bearer, when known. */
    credentialId?: number;
    /**
     * Resolved after `LimitsApi.rotate` slept out a sibling's short block
     * (`afterSiblingWait`): the driver accepts this bearer even if the request
     * already sent it before that block.
     */
    afterSiblingWait?: boolean;
    /** Non-secret request scope belonging to this bearer, replaced on account rotation. */
    oauthIdentity?: OAuthRequestIdentity;
}
export type ApiKeyResolution = string | ResolvedApiKey | undefined;
export type ApiKeyResolver = (ctx: ApiKeyResolveContext) => Promise<ApiKeyResolution> | ApiKeyResolution;
/** Extract the bearer while preserving optional credential provenance for streaming callers. */
export declare function resolvedApiKeyBearer(resolved: ApiKeyResolution): string | undefined;
/**
 * Mark a post-rotation resolution as following a sibling-unblock wait so the
 * retry driver may resend a bearer it already tried. Used by the rotating
 * resolvers (`KeyCascade.resolver`, coding-agent `createApiKeyResolver`).
 */
export declare function markAfterSiblingWait(resolved: ApiKeyResolution): ApiKeyResolution;
/** A static bearer string, or a {@link ApiKeyResolver} that mints/rotates one. */
export type ApiKey = string | ApiKeyResolver;
/** Keyless-provider credential marker; transports must not send it in authentication headers. */
export declare const NO_AUTH_SENTINEL = "N/A";
/** Narrows {@link ApiKey} to its resolver form. */
export declare function isApiKeyResolver(key: ApiKey | undefined): key is ApiKeyResolver;
/**
 * Performs the initial resolve of an {@link ApiKey} (`error: undefined`,
 * `lastChance: false`). Static keys pass through unchanged.
 */
export declare function resolveApiKeyOnce(key: ApiKey | undefined, signal?: AbortSignal, onResolved?: (resolved: ApiKeyResolution) => void): Promise<string | undefined>;
/**
 * Wraps a resolver with a credential already selected for this request.
 *
 * Callers that preflight credentials can pass the returned resolver to the
 * auth-retry driver without making the driver know about that preflight: the
 * first initial resolution reuses `seed` (including its credential identity),
 * and all later resolutions delegate to `resolver`.
 */
export declare function seedApiKeyResolver(seed: ApiKeyResolution, resolver: ApiKeyResolver): ApiKeyResolver;
export { isAuthRetryableError };
/**
 * Legacy a/b/c retry sequence retained for public compatibility:
 * `false` → refresh-same, `true` → rotate/switch. Current drivers may repeat
 * sibling rotation until a termination guard fires.
 */
export declare const AUTH_RETRY_STEPS: readonly boolean[];
export declare const AUTH_RETRY_MAX_ATTEMPTS = 64;
/** Resolve a single retry step, swallowing resolver failures into `undefined`. */
export declare function resolveRetryKey(resolver: ApiKeyResolver, lastChance: boolean, error: unknown, signal?: AbortSignal, previousKey?: string, onResolved?: (resolved: ApiKeyResolution) => void): Promise<string | undefined>;
export interface AuthRetryKeyState {
    /** Bearer strings already sent during this logical operation. */
    attemptedKeys: Set<string>;
    /** Bearer used by the most recent failed attempt. */
    lastKey: string;
    /** Whether the current credential already consumed its 401 refresh-same retry. */
    refreshedCurrent: boolean;
    /** Whether this operation already replayed once after an explicit token-refresh request. */
    tokenRefreshReplayUsed?: boolean;
    /** Total outbound attempts accepted for this logical operation, including the initial request. */
    attempts: number;
}
export declare function createAuthRetryKeyState(initialKey: string): AuthRetryKeyState;
export declare function resolveNextAuthRetryKey(state: AuthRetryKeyState, resolver: ApiKeyResolver, error: unknown, signal?: AbortSignal, onResolved?: (resolved: ApiKeyResolution) => void): Promise<string | undefined>;
/**
 * Runs an auth-protected operation through the central a/b/c retry policy.
 *
 * - A static string key (or any non-resolver) → a single `attempt` with no
 *   retry (identical to the legacy static-key path).
 * - A resolver → initial `attempt`, then resolver-driven retries until the
 *   applicable policy is exhausted, the resolver declines or cycles, or the
 *   operation reaches {@link AUTH_RETRY_MAX_ATTEMPTS}. An explicit typed
 *   token-refresh request gets exactly one refresh-current replay and never
 *   enters sibling rotation. Ordinary 401/auth failures get one refresh-same,
 *   then rotate through distinct siblings; 403/usage-limit failures skip the
 *   refresh and rotate directly.
 *
 * Used by non-streaming consumers (image generation, web search, completion
 * helpers). The streaming driver in `stream.ts` implements the same policy with
 * its replay-safe buffering machinery.
 */
export declare function withAuth<T>(key: ApiKey | undefined, attempt: (key: string) => Promise<T>, opts?: {
    isAuthError?: (error: unknown) => boolean;
    signal?: AbortSignal;
    missingKeyMessage?: string;
}): Promise<T>;
/**
 * Minimal structural slice of `AuthStorage` consumed by {@link withOAuthAccess}.
 * Typed structurally (type-only imports) so this module never takes a runtime
 * dependency on `./auth-storage`.
 */
export interface OAuthAccessSource {
    readonly oauth: Pick<OAuthApi, "access">;
    readonly limits: Pick<LimitsApi, "rotate">;
}
export interface WithOAuthAccessOptions {
    /** Session id for credential stickiness, threaded into every resolve. */
    sessionId?: string;
    signal?: AbortSignal;
    /** Override the retryable-error classifier (default {@link isAuthRetryableError}). */
    isAuthError?: (error: unknown) => boolean;
    /**
     * Pre-resolved access used for the initial attempt. Callers that already
     * resolved access for an availability gate pass it here so the helper
     * doesn't double-resolve (mirrors the gateway resolver's `initialKey`).
     */
    seed?: OAuthAccess;
    missingAccessMessage?: string;
}
/**
 * {@link withAuth} for OAuth-access consumers: runs an auth-protected
 * operation through the central a/b/c retry policy, handing the attempt the
 * full {@link OAuthAccess} (bearer + identity metadata: `accountId`,
 * `projectId`, `enterpriseUrl`) instead of bare API-key bytes.
 *
 * - initial → `getOAuthAccess` (or `opts.seed`).
 * - typed token-refresh request → one forced refresh-current replay, then stop.
 * - 401/auth failure → one `getOAuthAccess` with `forceRefresh: true` for the
 *   current account, then sibling rotation through distinct credentials.
 * - 403/usage-limit failure → `rotateSessionCredential` directly, without a
 *   force-refresh detour.
 *
 * A refresh-same step may retry a new bearer for the same credential identity;
 * sibling rotation stops when it yields a credential identity
 * (`credentialId ?? accessToken`) or bearer already attempted in this turn.
 * All OAuth attempts share the {@link AUTH_RETRY_MAX_ATTEMPTS} ceiling.
 * Non-auth errors propagate immediately. Use this instead of hand-rolled
 * `getOAuthAccess` + fetch flows so 401s and usage-limits rotate credentials
 * instead of failing the call.
 */
export declare function withOAuthAccess<T>(storage: OAuthAccessSource, provider: string, attempt: (access: OAuthAccess) => Promise<T>, opts?: WithOAuthAccessOptions): Promise<T>;