/**
 * CAPTCHA Handler (GAP-007)
 *
 * Integrates the challenge-detector with SmartBrowser to provide:
 * 1. Interactive CAPTCHA detection and classification
 * 2. User callback mechanism for manual solving
 * 3. Automatic wait for resolution after user action
 * 4. Challenge state tracking and reporting
 *
 * This builds on the existing challenge-detector.ts which handles
 * the low-level element detection. This module adds the workflow
 * integration and user interaction layer.
 */
import type { Page } from 'playwright';
import type { ChallengeElement, BotDetectionType } from '../types/index.js';
/**
 * Challenge information passed to user callback
 */
export interface ChallengeInfo {
    /** Type of bot detection system */
    type: BotDetectionType;
    /** Domain where challenge occurred */
    domain: string;
    /** Full URL of challenge page */
    url: string;
    /** Interactive elements that may need clicking */
    elements: ChallengeElement[];
    /** Whether auto-solve was attempted */
    autoSolveAttempted: boolean;
    /** Result of auto-solve attempt */
    autoSolveResult?: 'success' | 'failed' | 'no_change' | 'requires_human';
    /** Suggested action for user */
    suggestedAction: string;
    /** Detection timestamp */
    detectedAt: number;
}
/**
 * User callback for CAPTCHA handling
 * Return true if user solved the challenge, false to abort
 */
export type ChallengeCallback = (challenge: ChallengeInfo) => Promise<boolean>;
/**
 * Options for CAPTCHA handling
 */
export interface CaptchaHandlerOptions {
    /** Attempt to auto-solve simple challenges (checkboxes, etc.) */
    autoSolve?: boolean;
    /** Maximum time to wait for user to solve (ms) */
    userSolveTimeout?: number;
    /** Callback when user action is required */
    onChallengeDetected?: ChallengeCallback;
    /** Skip CAPTCHA handling entirely */
    skipCaptchaHandling?: boolean;
}
/**
 * Result of CAPTCHA handling
 */
export interface CaptchaHandlingResult {
    /** Whether a challenge was detected */
    detected: boolean;
    /** Type of challenge if detected */
    challengeType?: BotDetectionType;
    /** Challenge elements found */
    elements?: ChallengeElement[];
    /** Whether challenge was resolved */
    resolved: boolean;
    /** How the challenge was resolved */
    resolutionMethod?: 'auto_wait' | 'auto_solve' | 'user_solved' | 'timeout' | 'skipped';
    /** Time spent handling the challenge (ms) */
    durationMs: number;
    /** Error message if handling failed */
    error?: string;
}
/**
 * Handles CAPTCHA challenges during browsing
 */
export declare class CaptchaHandler {
    private options;
    constructor(options?: CaptchaHandlerOptions);
    /**
     * Handle potential CAPTCHA challenge on a page
     */
    handleChallenge(page: Page, domain: string): Promise<CaptchaHandlingResult>;
    /**
     * Get visible text from page
     */
    private getPageText;
    /**
     * Check if page looks like a challenge page
     */
    private looksLikeChallengePage;
    /**
     * Check if challenge is auto-resolving (no user action needed)
     */
    private isAutoResolvingChallenge;
    /**
     * Wait for automatic challenge resolution
     */
    private waitForAutoResolution;
    /**
     * Build challenge info for user callback
     */
    private buildChallengeInfo;
}
/** Default CAPTCHA handler instance (no callbacks configured) */
export declare const captchaHandler: CaptchaHandler;
/**
 * Create a CAPTCHA handler with specific options
 */
export declare function createCaptchaHandler(options: CaptchaHandlerOptions): CaptchaHandler;
//# sourceMappingURL=captcha-handler.d.ts.map