import type { OAuthController, OAuthCredentials } from "./types";
export type CallbackResult = {
    code: string;
    state: string;
};
export interface OAuthCallbackFlowOptions {
    preferredPort: number;
    callbackPath?: string;
    callbackHostname?: string;
    /** Exact redirect URI advertised to the provider; disables port fallback. */
    redirectUri?: string;
    /**
     * Whether the flow may bind to a random port when {@link preferredPort} is
     * unavailable. Defaults to `true` so historical AI-provider flows (which
     * pick uncommon ports and tolerate any loopback callback) keep working.
     *
     * Set to `false` for providers that validate the redirect URI against a
     * registered callback — silently advertising a random-port URI would be
     * rejected by the authorization server, leaving the browser on an opaque
     * 500 page and the local callback waiting until the 5-minute timeout fires.
     * With fallback disabled, {@link OAuthCallbackFlow.login} throws a
     * {@link AIError.ConfigurationError} immediately so the caller can surface
     * an actionable message before opening the browser.
     */
    allowPortFallback?: boolean;
}
/**
 * Abstract base class for OAuth flows with local callback servers.
 */
export declare abstract class OAuthCallbackFlow {
    #private;
    ctrl: OAuthController;
    preferredPort: number;
    callbackPath: string;
    callbackHostname: string;
    redirectUri?: string;
    allowPortFallback: boolean;
    constructor(ctrl: OAuthController, preferredPortOrOptions: number | OAuthCallbackFlowOptions, callbackPath?: string);
    /**
     * Generate provider-specific authorization URL.
     * @param state - CSRF state token
     * @param redirectUri - The actual redirect URI to use (may differ from expected if port fallback occurred)
     * @returns Authorization URL and optional instructions
     */
    abstract generateAuthUrl(state: string, redirectUri: string): Promise<{
        url: string;
        instructions?: string;
    }>;
    /**
     * Exchange authorization code for OAuth tokens.
     * @param code - Authorization code from callback
     * @param state - CSRF state token
     * @param redirectUri - The actual redirect URI used (must match authorization request)
     * @returns OAuth credentials
     */
    abstract exchangeToken(code: string, state: string, redirectUri: string): Promise<OAuthCredentials>;
    /**
     * Generate CSRF state token. Override if provider needs custom state generation.
     */
    generateState(): string;
    /**
     * Execute the OAuth login flow.
     */
    login(): Promise<OAuthCredentials>;
}
/**
 * Parse a redirect URL or code string to extract code and state.
 */
export declare function parseCallbackInput(input: string): {
    code?: string;
    state?: string;
};