Metadata-Version: 2.4
Name: browser-captcha-solver
Version: 1.0.2
Summary: A Python library for browser-based captcha solving
Author-email: xAffan <affanquddus1122@gmail.com>
License: MIT License
        
        Copyright (c) 2025 Browser Captcha Solver
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Project-URL: Homepage, https://github.com/xAffan/browser-captcha-solver
Project-URL: Bug Tracker, https://github.com/xAffan/browser-captcha-solver/issues
Project-URL: Documentation, https://github.com/xAffan/browser-captcha-solver
Project-URL: Source Code, https://github.com/xAffan/browser-captcha-solver
Keywords: captcha,recaptcha,hcaptcha,browser,automation,solving,web-scraping,bot-protection
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Topic :: Internet :: WWW/HTTP :: Browsers
Classifier: Topic :: Security
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Operating System :: OS Independent
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests>=2.25.0
Provides-Extra: dev
Requires-Dist: pytest>=6.0; extra == "dev"
Requires-Dist: pytest-asyncio; extra == "dev"
Requires-Dist: pytest-cov; extra == "dev"
Requires-Dist: black; extra == "dev"
Requires-Dist: flake8; extra == "dev"
Requires-Dist: twine; extra == "dev"
Requires-Dist: wheel; extra == "dev"
Dynamic: license-file

# Browser Captcha Solver

[![PyPI version](https://badge.fury.io/py/browser-captcha-solver.svg)](https://badge.fury.io/py/browser-captcha-solver)
[![Python versions](https://img.shields.io/pypi/pyversions/browser-captcha-solver.svg)](https://pypi.org/project/browser-captcha-solver/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

A robust Python library for solving captchas through browser automation, providing seamless integration between web captcha services and Python applications.

## Features

- **🌐 Browser Integration**: Automatically opens captchas in your browser for solving
- **🔄 Real-time Communication**: Handles browser-server communication seamlessly  
- **🎯 Multiple Captcha Types**: Supports ReCaptcha v2, hCaptcha, and custom challenges
- **⚡ Threaded HTTP Server**: Non-blocking server for handling multiple requests
- **🛡️ Secure**: Local-only server with automatic cleanup
- **🎨 Easy API**: Simple, intuitive interface for developers

## Installation

```bash
pip install browser-captcha-solver
```

## Quick Start

### Basic Usage

```python
from browser_captcha_solver import CaptchaSolver

# Create solver and start server
with CaptchaSolver() as solver:
    # Create a ReCaptcha challenge
    challenge = solver.create_challenge(
        challenge_type="RecaptchaV2Challenge",
        site_key="6LeIxAcTAAAAAJcZVRqyHh71UMIEGNQ_MXjiZKhI",  # Test key
        site_domain="example.com",
        host="example.com",
        explain="Please solve this captcha to continue",
        timeout=300
    )
    
    # Solve the challenge (opens browser automatically)
    result = solver.solve_challenge(challenge, timeout=300)
    
    if result:
        print(f"Success! Token: {result}")
    else:
        print("Failed to solve captcha")
```

### Advanced Usage with Callbacks

```python
from browser_captcha_solver import CaptchaSolver

def on_captcha_solved(challenge):
    print(f"Captcha {challenge.id} solved!")
    print(f"Token: {challenge.result}")

with CaptchaSolver(port=8080) as solver:
    challenge = solver.create_challenge(
        challenge_type="HCaptchaChallenge", 
        site_key="10000000-ffff-ffff-ffff-000000000001",  # Test key
        site_domain="example.com",
        host="example.com"
    )
    
    # Solve with callback
    result = solver.solve_challenge(
        challenge, 
        timeout=300,
        callback=on_captcha_solved
    )
```

### Command Line Interface

The package also provides a CLI for testing and server management:

```bash
# Start the server
browser-captcha-solver start --port 8080

# Test ReCaptcha solving  
browser-captcha-solver test --type recaptcha

# Test hCaptcha solving
browser-captcha-solver test --type hcaptcha
```

## API Reference

### CaptchaSolver

Main class for managing captcha challenges and browser communication.

#### Constructor

```python
CaptchaSolver(port=0, browser_command=None)
```

- `port` (int): HTTP server port (0 for auto-select)
- `browser_command` (str, optional): Custom browser command

#### Methods

##### `create_challenge(challenge_type, site_key, site_domain, host, **kwargs)`

Creates a new captcha challenge.

**Parameters:**
- `challenge_type` (str): Type of captcha ("RecaptchaV2Challenge", "HCaptchaChallenge")
- `site_key` (str): Site key for the captcha service
- `site_domain` (str): Domain where the captcha will be solved
- `host` (str): Host identifier for the challenge
- `**kwargs`: Additional parameters (timeout, explain, type_id, etc.)

**Returns:** `CaptchaChallenge` object

##### `solve_challenge(challenge, timeout=None, callback=None)`

Solves a captcha challenge by opening it in the browser.

**Parameters:**
- `challenge` (CaptchaChallenge): The challenge to solve
- `timeout` (int, optional): Timeout in seconds
- `callback` (callable, optional): Callback function when solved

**Returns:** Solution token (str) or None if failed

##### `list_challenges()`

Returns a list of active challenges.

**Returns:** List of `CaptchaJob` objects

##### `cleanup_expired_challenges()`

Removes expired challenges from memory.

### CaptchaChallenge

Represents a captcha challenge.

#### Attributes

- `id` (str): Unique challenge identifier
- `challenge_type` (str): Type of captcha
- `site_key` (str): Site key for the captcha service
- `site_domain` (str): Domain for the challenge
- `host` (str): Host identifier
- `timeout` (int): Timeout in seconds
- `created` (datetime): Creation timestamp
- `solved` (bool): Whether the challenge is solved
- `result` (str): Solution token

#### Methods

- `get_remaining_timeout()`: Returns remaining timeout in seconds
- `is_expired()`: Returns True if the challenge has expired

## Architecture

```
┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   Application   │◄──►│  CaptchaSolver  │◄──►│  HTTP Server    │
│   (Your Code)   │    │                 │    │  (Port 8080)    │
└─────────────────┘    └─────────────────┘    └─────────────────┘
                                ▲                       ▲
                                │                       │
                                ▼                       ▼
                       ┌─────────────────┐    ┌─────────────────┐
                       │ Challenge Store │    │   Web Browser   │
                       │ (In Memory)     │    │  (User Opens)   │
                       └─────────────────┘    └─────────────────┘
```

## Supported Captcha Types

### ReCaptcha v2

```python
challenge = solver.create_challenge(
    challenge_type="RecaptchaV2Challenge",
    site_key="your-recaptcha-site-key",
    site_domain="example.com",
    host="example.com"
)
```

### hCaptcha

```python
challenge = solver.create_challenge(
    challenge_type="HCaptchaChallenge", 
    site_key="your-hcaptcha-site-key",
    site_domain="example.com",
    host="example.com"
)
```

### Generic/Manual Captcha

```python
challenge = solver.create_challenge(
    challenge_type="ManualChallenge",
    site_key="",
    site_domain="example.com", 
    host="example.com",
    explain="Please solve the captcha shown in the image"
)
```

## Examples

### Web Scraping Integration

```python
from browser_captcha_solver import CaptchaSolver
import requests

def scrape_with_captcha():
    session = requests.Session()
    
    # Detect captcha on page
    response = session.get("https://example.com/protected")
    if "recaptcha" in response.text.lower():
        # Extract site key from HTML
        site_key = extract_site_key(response.text)
        
        # Solve captcha
        with CaptchaSolver() as solver:
            challenge = solver.create_challenge(
                challenge_type="RecaptchaV2Challenge",
                site_key=site_key,
                site_domain="example.com",
                host="example.com"
            )
            
            token = solver.solve_challenge(challenge)
            
            if token:
                # Submit with captcha token
                data = {"g-recaptcha-response": token}
                response = session.post("https://example.com/submit", data=data)
                return response
    
    return None
```

### Batch Processing

```python
from browser_captcha_solver import CaptchaSolver

def process_multiple_captchas():
    with CaptchaSolver() as solver:
        challenges = []
        
        # Create multiple challenges
        for i in range(3):
            challenge = solver.create_challenge(
                challenge_type="RecaptchaV2Challenge",
                site_key="6LeIxAcTAAAAAJcZVRqyHh71UMIEGNQ_MXjiZKhI",
                site_domain="example.com",
                host=f"host-{i}",
                timeout=300
            )
            challenges.append(challenge)
        
        # Solve them sequentially
        results = []
        for challenge in challenges:
            result = solver.solve_challenge(challenge, timeout=120)
            results.append(result)
        
        return results
```

## Error Handling

```python
from browser_captcha_solver import CaptchaSolver

try:
    with CaptchaSolver() as solver:
        challenge = solver.create_challenge(
            challenge_type="RecaptchaV2Challenge",
            site_key="invalid-key",
            site_domain="example.com",
            host="example.com"
        )
        
        result = solver.solve_challenge(challenge, timeout=60)
        
        if not result:
            print("Captcha solving failed or timed out")
            
except Exception as e:
    print(f"Error: {e}")
```

## Development

### Setting up for Development

```bash
# Clone the repository
git clone https://github.com/xAffan/browser-captcha-solver.git
cd browser-captcha-solver

# Install in development mode
pip install -e ".[dev]"

# Run tests
pytest

# Format code
black .

# Type checking
mypy browser_captcha_solver/
```

### Building and Publishing

```bash
# Build the package
python -m build

# Upload to PyPI (requires authentication)
twine upload dist/*
```

## Requirements

- Python 3.8+
- requests >= 2.25.0

## License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

## Support

If you encounter any issues or have questions, please file an issue on the [GitHub repository](https://github.com/xAffan/browser-captcha-solver/issues).
