auto-captcha-solver/README.md

Automatically detect and solve various captcha types in Playwright & Puppeteer with 2Captcha/CapMonster Cloud integration

# Auto Captcha Solver for Playwright/Puppeteer 🤖🔍

[![npm version](https://img.shields.io/npm/v/auto-captcha-solver.svg)](https://www.npmjs.com/package/auto-captcha-solver)
[![License: ISC](https://img.shields.io/badge/License-ISC-blue.svg)](https://opensource.org/licenses/ISC)

Advanced CAPTCHA solving automation with multi-provider fallback support for Playwright/Puppeteer.

## Table of Contents

-   [Features](#features-)
-   [Installation](#installation-)
-   [Usage](#usage-)
-   [Configuration](#configuration-)
-   [Supported CAPTCHAs](#supported-captchas-)
-   [Provider Capabilities](#provider-capabilities-)
-   [Strategy](#strategy-)
-   [Requirements](#requirements-)
-   [License](#license-)

## Features ✨

-   🛡 **Multi-Provider Fallback**: Configure primary and backup solvers
-   🤖 **Smart Detection**: Auto-recognizes 15+ CAPTCHA types
-   🔄 **Priority Routing**: Tries providers in configured order
-   🎯 **Type-Specific Resolution**: Selects optimal solver per CAPTCHA type
-   📊 **Visual Feedback**: Interactive loading indicators
-   🚀 **Playwright/Puppeteer Ready**: Works with modern browser automation

## Installation 📦

```bash
npm install auto-captcha-solver
```

## Usage

### Basic Usage with Fallback

```typescript
import { captchaSolver } from 'auto-captcha-solver';
import { chromium } from 'playwright';

async function solveCaptcha() {
    const browser = await chromium.launch();
    const page = await browser.newPage();

    await page.goto('https://site-with-captcha.com');

    const result = await captchaSolver(page, {
        providers: [
            { name: 'capmonster', apiKey: 'CAPMONSTER_KEY' }, // Primary
            { name: '2captcha', apiKey: '2CAPTCHA_KEY' } // Fallback
        ],
        // optional: required for 'Image To Text' captcha type
        imageSelector: '#captcha-img',
        inputSelector: '#captcha-input'
    });

    if (result.success) {
        await page.click('#submit-form');
    }

    await browser.close();
}
```

### Single Provider Setup

```typescript
// Traditional single provider configuration
const result = await captchaSolver(page, {
    providers: [{ name: '2captcha', apiKey: 'YOUR_KEY' }]
    // Additional options...
});
```

## Configuration ⚙️

```typescript
interface CaptchaConfig {
    // Required provider configuration
    providers: Array<{
        name: 'capmonster' | '2captcha';
        apiKey: string;
    }>;

    // Image CAPTCHA options
    captchaType: 'Image To Text';
    imageSelector?: string; // '#captcha-img',
    inputSelector?: string; // '#captcha-input'
    numericCount?: number; // 2
    minLength?: number; // 5
    maxLength?: number; // 5

    // Text CAPTCHA options
    captchaType: 'Text Captcha';
    textSelector?: string; // '.text-question'
    inputSelector?: string; // '#captcha-input'
    textLanguage?: string; // 'en'

    // Advanced options
    module?: CapMonsterModules;
    caseSensitive?: boolean;
    threshold?: number;
    math?: boolean; // 1 or 0
}
```

## Supported CAPTCHAs 🛡️

| CAPTCHA Type         | Example Sites              |
| -------------------- | -------------------------- |
| reCAPTCHA v2         | Google services            |
| reCAPTCHA v3         | Registration forms         |
| hCaptcha             | Cloudflare-protected sites |
| Image CAPTCHA        | Legacy systems             |
| Cloudflare Turnstile | Secure portals             |
| GeeTest v4           | Financial platforms        |
| Text CAPTCHA         | Comment sections           |
| MTCaptcha            | News websites              |

## Provider Capabilities Matrix 📊

| CAPTCHA Type               | CapMonster | 2Captcha |
| -------------------------- | ---------- | -------- |
| **Image To Text**          | ✓          | ✓        |
| **reCAPTCHA v2**           | ✓          | ✓        |
| **reCAPTCHA v2 Invisible** |            | ✓        |
| **reCAPTCHA v3**           | ✓          | ✓        |
| **hCaptcha**               |            | ✓        |
| **Cloudflare Turnstile**   | ✓          | ✓        |
| **GeeTest v4**             | ✓          |          |
| **Text CAPTCHA**           |            | ✓        |
| **MTCaptcha**              |            | ✓        |

## Resolution Strategy 🧠

1. **Detection**: Automatically identifies CAPTCHA type
2. **Filtering**: Selects providers supporting detected type
3. **Execution**:
    - Tries providers in configured order
    - Uses first successful solution
    - Collects error information for diagnostics
4. **Fallback**: Automatically switches providers if:
    - Current provider doesn't support CAPTCHA type
    - API request fails
    - Solution injection fails

## Requirements 📋

-   Node.js 16+
-   Playwright/Puppeteer
-   Valid API keys for selected providers
-   TypeScript (recommended)

## License 📄

ISC © [Seven Builder](https://github.com/SevenBuilder)

## Support & Issues 🛠️

Report issues at [GitHub Repository](https://github.com/SevenBuilder/auto-captcha-solver/issues)

---

**Pro Tip:** For best results, configure multiple providers to maximize CAPTCHA type coverage and ensure higher success rates! 🚀

```

This README emphasizes the new multi-provider functionality while maintaining all existing documentation. Key improvements:

1. Clear multi-provider configuration examples
2. Provider capability matrix for quick reference
3. Detailed resolution strategy explanation
4. Backward compatibility with single-provider setup
5. Improved visual hierarchy and organization
6. Practical examples for different use cases
7. Clear requirements and support information

The document maintains technical accuracy while being approachable for developers of different experience levels.
```