google-react-recaptcha-v3/dist/index.d.mts

React component for Google reCAPTCHA v3 with advanced features and optimizations

import * as react from 'react';

interface RecaptchaV3Props {
    siteKey: string;
    action: string;
    hl?: string;
    onVerify?: (token: string) => void;
    onError?: (error: unknown) => void;
    /** Enable loading with Trusted Types support */
    trustedTypes?: boolean;
    /** Custom timeout for script loading (default: 5000ms) */
    timeout?: number;
    /** Execute reCAPTCHA automatically on mount */
    autoExecute?: boolean;
}
interface RecaptchaV3Ref {
    execute: () => Promise<string | null>;
    /** Get the current readiness state */
    isReady: () => boolean;
    /** Reset the reCAPTCHA instance */
    reset: () => void;
    /** Get the current loading state */
    isLoading: () => boolean;
}
interface RecaptchaV3Response {
    success: boolean;
    score: number;
    action: string;
    challenge_ts: string;
    hostname: string;
    "error-codes"?: string[];
}

/**
 * Componente ReCAPTCHA v3 con arquitectura limpia
 *
 * Este componente es una capa de presentación delgada que delega toda la lógica
 * al hook personalizado useRecaptcha, siguiendo principios de arquitectura limpia.
 *
 * @example
 * ```tsx
 * // Uso básico
 * <RecaptchaV3
 *   siteKey="your-site-key"
 *   action="page_view"
 *   onVerify={(token) => console.log(token)}
 * />
 *
 * // Con auto-ejecución para analytics
 * <RecaptchaV3
 *   siteKey="your-site-key"
 *   action="analytics"
 *   autoExecute={true}
 *   onVerify={(token) => sendAnalytics(token)}
 * />
 *
 * // Con referencia para ejecución manual
 * const recaptchaRef = useRef<RecaptchaV3Ref>(null);
 *
 * const handleSubmit = async () => {
 *   const token = await recaptchaRef.current?.execute();
 *   if (token) {
 *     // Enviar formulario con token
 *   }
 * };
 *
 * <ReCaptchaV3
 *   ref={recaptchaRef}
 *   siteKey="your-site-key"
 *   action="form_submit"
 *   onVerify={(token) => setFormToken(token)}
 * />
 * ```
 */
declare const ReCaptchaV3: react.ForwardRefExoticComponent<RecaptchaV3Props & react.RefAttributes<RecaptchaV3Ref>>;

interface RecaptchaConfig {
    siteKey: string;
    action: string;
    hl?: string;
    trustedTypes?: boolean;
}
interface RecaptchaExecutionResult {
    success: boolean;
    token?: string;
    error?: Error;
}
interface RecaptchaServiceInterface {
    execute(config: RecaptchaConfig): Promise<RecaptchaExecutionResult>;
    isReady(): boolean;
    reset(): void;
    validateAction(action: string): {
        isValid: boolean;
        warning?: string;
    };
}
declare class RecaptchaService implements RecaptchaServiceInterface {
    private grecaptcha;
    constructor(grecaptchaInstance?: any);
    execute(config: RecaptchaConfig): Promise<RecaptchaExecutionResult>;
    isReady(): boolean;
    reset(): void;
    validateAction(action: string): {
        isValid: boolean;
        warning?: string;
    };
    setGrecaptcha(grecaptchaInstance: any): void;
}
declare const recaptchaService: RecaptchaService;
declare const createRecaptchaService: (grecaptchaInstance?: any) => RecaptchaService;

interface UseRecaptchaOptions extends RecaptchaConfig {
    timeout?: number;
    autoExecute?: boolean;
    onVerify?: (token: string) => void;
    onError?: (error: Error) => void;
}
interface UseRecaptchaReturn {
    isReady: boolean;
    execute: () => Promise<string | null>;
    reset: () => void;
    isLoading: boolean;
}
declare function useReCaptcha(options: UseRecaptchaOptions): UseRecaptchaReturn;

interface ScriptConfig {
    siteKey: string;
    hl?: string;
    trustedTypes?: boolean;
}
interface ScriptLoadResult {
    success: boolean;
    error?: Error;
}
interface ScriptLoaderOptions {
    timeout?: number;
    onLoad?: () => void;
    onError?: (error: Error) => void;
}
declare class ScriptLoader {
    private static buildScriptUrl;
    static isScriptLoaded(): boolean;
    static loadScript(config: ScriptConfig, options?: ScriptLoaderOptions): Promise<ScriptLoadResult>;
    static waitForGrecaptcha(timeout?: number): Promise<boolean>;
}
declare const loadRecaptchaScript: (config: ScriptConfig, options?: ScriptLoaderOptions) => Promise<ScriptLoadResult>;
declare const waitForRecaptcha: (timeout?: number) => Promise<boolean>;

declare enum TRANSACTIONAL_ACTIONS {
    LOGIN = "login",
    REGISTER = "register",
    PURCHASE = "purchase",
    PAYMENT = "payment",
    SUBMIT = "submit",
    CHECKOUT = "checkout",
    ORDER = "order",
    SIGNUP = "signup",
    SIGNIN = "signin",
    TRANSACTION = "transaction"
}

export { ReCaptchaV3, type RecaptchaConfig, type RecaptchaExecutionResult, type RecaptchaServiceInterface, type RecaptchaV3Props, type RecaptchaV3Ref, type RecaptchaV3Response, type ScriptConfig, type ScriptLoadResult, ScriptLoader, type ScriptLoaderOptions, TRANSACTIONAL_ACTIONS, type UseRecaptchaOptions, type UseRecaptchaReturn, createRecaptchaService, loadRecaptchaScript, recaptchaService, useReCaptcha, waitForRecaptcha };