captcha-solver-client

Captcha Solver Client

A powerful TypeScript/JavaScript client library for interacting with Captcha Solver API. Supports multiple captcha types including Turnstile, reCAPTCHA, hCaptcha, FunCaptcha, GeeTest, and more.

Features

• 🚀 Full TypeScript Support - Complete type definitions for all API methods
• 🔧 Multiple Build Formats - CommonJS, ES Modules, and UMD builds
• 🎯 All Captcha Types - Support for Turnstile, reCAPTCHA, hCaptcha, and more
• ⚡ Promise-based API - Modern async/await support
• 🔄 Automatic Polling - Built-in result polling with customizable intervals
• 🛡️ Error Handling - Comprehensive error types and handling
• 📦 Lightweight - Minimal dependencies (only axios)
• 🌐 Universal - Works in Node.js and browsers

Installation

npm install captcha-solver-client

yarn add captcha-solver-client

pnpm add captcha-solver-client

Quick Start

TypeScript

import CaptchaSolverClient, { createTurnstile } from 'captcha-solver-client';

const client = new CaptchaSolverClient({
    apiKey: 'your-api-key-here',
    baseURL: 'https://your-api.com/api', // optional
});

// Solve a Turnstile captcha
const solution = await client.solveCaptcha({
    type: 'turnstile',
    sitekey: '0x4AAAAAAAa0Ic88byebJ1dj',
    pageurl: 'https://faucets.chain.link/',
});

console.log('Solution:', solution);

JavaScript (CommonJS)

const { CaptchaSolverClient } = require('captcha-solver-client');

const client = new CaptchaSolverClient({
    apiKey: 'your-api-key-here',
});

async function solveCaptcha() {
    try {
        const solution = await client.solveCaptcha({
            type: 'turnstile',
            sitekey: '0x4AAAAAAAa0Ic88byebJ1dj',
            pageurl: 'https://faucets.chain.link/',
        });

        console.log('Solution:', solution);
    } catch (error) {
        console.error('Error:', error.message);
    }
}

solveCaptcha();

Browser (UMD)

<script src="https://unpkg.com/axios/dist/axios.min.js"></script>
<script src="https://unpkg.com/captcha-solver-client/dist/index.umd.min.js"></script>

<script>
    const client = new CaptchaSolverClient({
        apiKey: 'your-api-key-here',
    });

    client
        .solveCaptcha({
            type: 'turnstile',
            sitekey: '0x4AAAAAAAa0Ic88byebJ1dj',
            pageurl: 'https://faucets.chain.link/',
        })
        .then(solution => {
            console.log('Solution:', solution);
        })
        .catch(error => {
            console.error('Error:', error.message);
        });
</script>

API Reference

Constructor

const client = new CaptchaSolverClient({
  apiKey: string;           // Required: Your API key
  baseURL?: string;         // Optional: API base URL (default: http://localhost:3000/api)
  timeout?: number;         // Optional: Request timeout in ms (default: 30000)
  retries?: number;         // Optional: Number of retries (default: 3)
  retryDelay?: number;      // Optional: Delay between retries in ms (default: 1000)
});

Methods

submitCaptcha(data: SubmitCaptchaRequest): Promise<TaskResponse>

Submit a captcha for solving.

const task = await client.submitCaptcha({
    type: 'turnstile',
    sitekey: '0x4AAAAAAAa0Ic88byebJ1dj',
    pageurl: 'https://example.com',
});

console.log('Task ID:', task.taskId);
console.log('Cost:', task.cost);

getTaskResult(taskId: string): Promise<TaskResult>

Get the result of a submitted task.

const result = await client.getTaskResult('task-id-here');

if (result.status === 'completed') {
    console.log('Solution:', result.solution);
} else if (result.status === 'failed') {
    console.log('Error:', result.error);
} else {
    console.log('Status:', result.status); // 'pending' or 'processing'
}

waitForResult(taskId: string, options?): Promise<TaskResult>

Wait for task completion with automatic polling.

const result = await client.waitForResult('task-id-here', {
    maxAttempts: 60, // Maximum polling attempts (default: 60)
    pollInterval: 5000, // Polling interval in ms (default: 5000)
    onProgress: (attempt, status) => {
        console.log(`Attempt ${attempt}: ${status}`);
    },
});

console.log('Final solution:', result.solution);

solveCaptcha(data: SubmitCaptchaRequest, options?): Promise<string>

Convenience method that submits captcha and waits for result.

const solution = await client.solveCaptcha(
    {
        type: 'turnstile',
        sitekey: '0x4AAAAAAAa0Ic88byebJ1dj',
        pageurl: 'https://example.com',
    },
    {
        maxAttempts: 60,
        pollInterval: 5000,
        onProgress: (attempt, status) => {
            console.log(`Solving... ${attempt}/60 - ${status}`);
        },
    }
);

console.log('Solution:', solution);

getBalance(): Promise<UserBalance>

Get your account balance.

const balance = await client.getBalance();
console.log(`Balance: ${balance.balance} ${balance.currency}`);

getTasks(options?): Promise<PaginatedResponse<UserTask>>

Get your task history.

const tasks = await client.getTasks({
    page: 1,
    limit: 20,
    status: 'completed', // optional filter
});

console.log(`Found ${tasks.pagination.total} tasks`);
tasks.items.forEach(task => {
    console.log(`${task.id}: ${task.status} - ${task.type}`);
});

reportIncorrect(taskId: string): Promise<void>

Report an incorrect solution.

await client.reportIncorrect('task-id-here');
console.log('Reported as incorrect');

Supported Captcha Types

Cloudflare Turnstile

await client.solveCaptcha({
    type: 'turnstile',
    sitekey: '0x4AAAAAAAa0Ic88byebJ1dj',
    pageurl: 'https://faucets.chain.link/',
    action: 'login', // optional
    userAgent: 'Mozilla/5.0...', // optional
});

reCAPTCHA v2

await client.solveCaptcha({
    type: 'recaptcha_v2',
    sitekey: 'your-site-key',
    pageurl: 'https://example.com',
    invisible: false, // optional
    enterprise: false, // optional
});

reCAPTCHA v3

await client.solveCaptcha({
    type: 'recaptcha_v3',
    sitekey: 'your-site-key',
    pageurl: 'https://example.com',
    action: 'submit', // optional
    minScore: 0.3, // optional
});

hCaptcha

await client.solveCaptcha({
    type: 'hcaptcha',
    sitekey: 'your-site-key',
    pageurl: 'https://example.com',
    invisible: false, // optional
});

Helper Functions

The library provides helper functions for creating captcha requests:

import {
    createTurnstile,
    createRecaptchaV2,
    createHCaptcha,
    getCaptchaCost,
    validateApiKey,
} from 'captcha-solver-client';

// Using helper functions
const turnstileRequest = createTurnstile({
    sitekey: '0x4AAAAAAAa0Ic88byebJ1dj',
    pageurl: 'https://example.com',
});

const solution = await client.solveCaptcha(turnstileRequest);

// Utility functions
const cost = getCaptchaCost('turnstile'); // 1.0
const isValid = validateApiKey('your-api-key'); // true/false

Error Handling

The library provides specific error types for different scenarios:

import {
    CaptchaSolverError,
    AuthenticationError,
    InsufficientBalanceError,
    RateLimitError,
    TimeoutError,
    ValidationError,
} from 'captcha-solver-client';

try {
    const solution = await client.solveCaptcha({
        type: 'turnstile',
        sitekey: 'invalid-key',
        pageurl: 'https://example.com',
    });
} catch (error) {
    if (error instanceof AuthenticationError) {
        console.error('Invalid API key');
    } else if (error instanceof InsufficientBalanceError) {
        console.error('Not enough balance');
    } else if (error instanceof ValidationError) {
        console.error('Invalid request data');
    } else if (error instanceof TimeoutError) {
        console.error('Request timed out');
    } else {
        console.error('Unknown error:', error.message);
    }
}

Development

Building

# Build development version
npm run build

# Build minified version
npm run build:min

# Build both versions
npm run build:all

File Sizes

Format	Original	Minified	Reduction
CommonJS	15.4 KB	7.0 KB	54.3%
ES Module	14.5 KB	6.9 KB	52.0%
UMD (Browser)	17.7 KB	7.1 KB	60.1%

Testing

npm test
npm run test:watch

Linting

npm run lint
npm run lint:fix

License

MIT License - see LICENSE file for details.

Support

For support, please contact [[e-mail]] or create an issue on GitHub.