Skip to content

Conversation

@kent13n
Copy link
Contributor

@kent13n kent13n commented Nov 25, 2025

Add CaptchaSolver Plugin - Multi-Vendor CAPTCHA Solving

Overview

This PR introduces a new CaptchaSolver plugin providing a unified interface for detecting and solving CAPTCHAs across multiple vendors. It consolidates and extends the previous RecaptchaPlugin while maintaining full backward compatibility.

Supported Vendors

  • Google reCAPTCHA (v2, v3, Enterprise)
  • GeeTest (v3, v4)
  • Cloudflare Turnstile
  • 🔍 hCaptcha (detection only)

Supported Providers

  • CapSolver
  • 2Captcha

The plugin is designed with an extensible provider interface, making it straightforward to integrate additional solvers in the future.

Key Features

  • Modular vendor handler architecture
  • Smart CAPTCHA filtering (viewport, score-based, invisible challenges)
  • Automatic detection via JavaScript injection
  • Per-vendor configuration options
  • Comprehensive test coverage

Usage

    var captchaSolver = new CaptchaSolverPlugin(
      new CapSolver("YOUR_API_KEY")
    );

    extra.Use(captchaSolver);
    var browser = await extra.LaunchAsync(new LaunchOptions { Headless = false });
    var page = await browser.NewPageAsync();

    await page.GoToAsync("https://example.com/captcha");
    var result = await captchaSolver.SolveCaptchaAsync(page);

Notes

  • No breaking changes
  • This plugin acts as the successor to RecaptchaPlugin, which remains available for backward compatibility.
  • All tests passing

Credits

Inspired by https://github.com/berstend/puppeteer-extra/tree/master/packages/puppeteer-extra-plugin-recaptcha.

- Introduced `CaptchaSolverPlugin` to handle various CAPTCHA solving scenarios.
- Implemented `CapSolver` as a provider for solving reCAPTCHAs, with support for V2 and V3.
- Added models, enums, and helper methods for better CAPTCHA management.
- Included support for configurable options like timeouts and polling attempts.
- Provided initial integration scripts for Google reCAPTCHA handling.
- Moved Google CAPTCHA task creation logic to a dedicated method.
- Added support check and exception handling for unsupported CAPTCHA vendors.
- Introduced `GoogleOptions` class with customizable properties for solving Google reCAPTCHAs (e.g., `MinV3RecaptchaScore`, `CaptchaWaitTimeout`).
- Updated default vendor configuration to use `GoogleOptions` for Google reCAPTCHAs.
- Enhanced Google handler to include vendor-specific options in task creation.
- Introduced `HCaptchaHandler` to detect hCaptcha challenges and handle related operations.
- Added initial hCaptcha integration in CapSolver API with dedicated task creation.
- Updated scripts for hCaptcha detection and visual feedback.
- Disabled hCaptcha solving support temporarily due to compliance and reliability issues.
- Included unit tests for validating hCaptcha detection functionality.
- Introduced `CloudflareHandler` to detect and solve Cloudflare Turnstile challenges.
- Added Cloudflare Turnstile task creation in CapSolver API.
- Developed content scripts for widget detection, visual feedback, and solution handling.
- Included unit tests for Cloudflare Turnstile CAPTCHA solving verification.
- Updated related scripts and APIs to integrate with the new vendor.
- Updated method names in `CloudflareHandler` and `CloudflareScript` to replace "Turnstile" with "Captcha".
- Ensured uniform terminology across detection and solution handling functions.
- Added support for Cloudflare Turnstile and GeeTest in the README.
- Updated provider examples to include CapSolver.
- Replaced `RecaptchaPlugin` references with `CaptchaSolverPlugin`.
- Revised code samples to reflect changes in option naming and initialization.
…d add response processing hooks

- Updated handlers (`CloudflareHandler`, `GoogleHandler`, `HCaptchaHandler`) to simplify method signatures by removing redundant `IPage` arguments.
- Added `ProcessResponseAsync` hooks to enable response-based CAPTCHA management.
- Modified `CreateHandler` helper to include `IPage` in handler initialization.
- Updated `CaptchaSolverPlugin` to connect response hooks for supported vendors.
…d signatures, and enhance error handling across handlers and scripts
- Introduced `GeeTestHandler` for detecting and solving GeeTest CAPTCHAs.
- Added GeeTest task creation logic in CapSolver API with required fields (`gt`, `challenge`, `captchaId`).
- Developed GeeTest content scripts for widget detection, visual feedback, and solution handling.
- Extended CAPTCHA models to include GeeTest-specific properties (`Gt`, `Challenge`, `CaptchaId`).
- Added unit tests to validate GeeTest CAPTCHA solving functionality.
- Implemented `TwoCaptcha` provider with task creation and solution retrieval logic.
- Developed helper methods for handling Google, hCaptcha, GeeTest, and Cloudflare Turnstile task structures.
- Added error handling and response validation for API interactions.
- Introduced models for TwoCaptcha responses (`TwoCaptchaCreateTaskResponse`, `TwoCaptchaGetTaskResult`).
- Introduced `GeeTestV4` support with updated logic in `GeeTestHandler` and CapSolver API.
- Added `Version` property to the `Captcha` model for version-specific handling.
- Refactored handlers (`CloudflareHandler`, `GoogleHandler`, `HCaptchaHandler`) with `HandleOnPageCreatedAsync` implementation.
- Improved GeeTest content script for better challenge tracking and efficiency.
- Enhanced unit tests to validate `GeeTestV4` solving functionality.
- Renamed `RecaptchaTests` class to `GoogleTests` for consistency with naming conventions.
- Added new unit tests to validate solving for various Google CAPTCHA scenarios, including invisible and v3 challenges.
- Updated test logic to include additional assertions and reduced delays for improved efficiency.
- Improved `GeeTestHandler` to handle cases where CAPTCHA selectors are not found, adding fallback return logic for better reliability.
- Added unit tests for solving CAPTCHAs with TwoCaptcha, covering scenarios for Google, Cloudflare, hCaptcha, and GeeTest.
- Improved task creation and request handling in `TwoCaptchaApi`, including support for GeeTest v4 and Turnstile challenges.
- Refined error handling, renamed task types for consistency, and enhanced API parameter validation.
… handling, and enhance hCaptcha unit tests

- Introduced `FindCaptchaAsync` method, separating CAPTCHA discovery from solving for improved modularity.
- Enhanced error handling in `SolveCaptchaAsync` and `FindCaptchaAsync` to validate response integrity and streamline fallback behavior.
- Updated hCaptcha tests to include assertions for detected CAPTCHAs and error handling scenarios.
- Revised `readme.md` to reflect updates in plugin architecture, vendor support, and usage examples.
- Optimized vendor handlers and method signatures for consistency across CAPTCHA types.
…tchaAsync` with `FindCaptchaAsync`, add assertions, and cleanup comments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant