rapidcaptcha

RapidCaptcha JavaScript SDK

Official JavaScript SDK for the RapidCaptcha API - Solve Turnstile and reCAPTCHA with high success rates.

Features

• ✅ Turnstile & reCAPTCHA Support - Solve both Cloudflare Turnstile and Google reCAPTCHA
• ✅ Auto-Detection - Automatically detect sitekeys from target pages
• ✅ TypeScript Ready - Full TypeScript support with complete type definitions
• ✅ Browser & Node.js - Works in both browser and Node.js environments
• ✅ Promise-Based - Modern async/await API
• ✅ Error Handling - Comprehensive error types and handling
• ✅ Concurrent Solving - Handle multiple CAPTCHAs simultaneously
• ✅ Configurable - Timeouts, retries, polling intervals, and more

Installation

NPM

npm install rapidcaptcha

Yarn

yarn add rapidcaptcha

CDN (Browser)

<script src="https://unpkg.com/rapidcaptcha@latest/dist/browser.js"></script>

Quick Start

Node.js / ES Modules

import { RapidCaptchaClient } from "rapidcaptcha";

const client = new RapidCaptchaClient("Rapidcaptcha-your-api-key");

// Solve Turnstile
const result = await client.solveTurnstile("https://example.com", {
  autoDetect: true,
});

if (result.isSuccess) {
  console.log("Token:", result.turnstileValue);
} else {
  console.log("Failed:", result.reason);
}

Browser

<script src="https://unpkg.com/rapidcaptcha@latest/dist/browser.js"></script>
<script>
  const client = new RapidCaptcha.RapidCaptchaClient(
    "Rapidcaptcha-your-api-key"
  );

  client.solveTurnstile("https://example.com").then((result) => {
    if (result.isSuccess) {
      console.log("Token:", result.turnstileValue);
    }
  });
</script>

TypeScript

import { RapidCaptchaClient, CaptchaResult } from "rapidcaptcha";

const client = new RapidCaptchaClient("Rapidcaptcha-your-api-key");

const result: CaptchaResult = await client.solveTurnstile(
  "https://example.com",
  {
    autoDetect: true,
    pollInterval: 2000,
  }
);

API Reference

Client Initialization

const client = new RapidCaptchaClient(apiKey, options);

Options:

• baseUrl (string): API base URL (default: "https://rapidcaptcha.xyz")
• timeout (number): Request timeout in milliseconds (default: 300000)
• maxRetries (number): Maximum retry attempts (default: 3)
• retryDelay (number): Delay between retries in milliseconds (default: 2000)

Solving CAPTCHAs

Turnstile

// Basic usage with auto-detection
const result = await client.solveTurnstile("https://example.com");

// With manual sitekey
const result = await client.solveTurnstile("https://example.com", {
  sitekey: "0x4AAAAAAABkMYinukE8nzKd",
  action: "submit",
  autoDetect: false,
});

reCAPTCHA

// Basic usage
const result = await client.solveRecaptcha("https://example.com");

// With manual sitekey
const result = await client.solveRecaptcha("https://example.com", {
  sitekey: "6Le-wvkSAAAAAPBMRTvw0Q4Muexq9bi0DJwx_mJ-",
});

Manual Task Management

// Submit task
const taskId = await client.submitTurnstile("https://example.com", {
  autoDetect: true,
});

// Get result
const result = await client.getResult(taskId);

// Wait for completion
const result = await client.waitForResult(taskId, 2000); // Poll every 2 seconds

Convenience Functions

import { solveTurnstile, solveRecaptcha } from "rapidcaptcha";

// One-liner solutions
const turnstileResult = await solveTurnstile(
  "Rapidcaptcha-your-key",
  "https://example.com"
);
const recaptchaResult = await solveRecaptcha(
  "Rapidcaptcha-your-key",
  "https://example.com"
);

Examples

Concurrent Solving

const urls = ["https://site1.com", "https://site2.com", "https://site3.com"];

const promises = urls.map((url) =>
  client.solveTurnstile(url, { autoDetect: true })
);

const results = await Promise.allSettled(promises);

results.forEach((result, index) => {
  if (result.status === "fulfilled" && result.value.isSuccess) {
    console.log(`Site ${index + 1}: Success`);
  } else {
    console.log(`Site ${index + 1}: Failed`);
  }
});

Error Handling

import {
  APIKeyError,
  ValidationError,
  RateLimitError,
  TimeoutError,
} from "rapidcaptcha";

try {
  const result = await client.solveTurnstile("https://example.com");

  if (result.isSuccess) {
    console.log("Token:", result.turnstileValue);
  } else {
    console.log("Solve failed:", result.reason);
  }
} catch (error) {
  if (error instanceof APIKeyError) {
    console.error("Invalid API key");
  } else if (error instanceof RateLimitError) {
    console.error("Rate limit exceeded");
  } else if (error instanceof TimeoutError) {
    console.error("Operation timed out");
  } else {
    console.error("Unexpected error:", error.message);
  }
}

Retry Logic

async function solveWithRetry(url, maxRetries = 3) {
  for (let attempt = 1; attempt <= maxRetries; attempt++) {
    try {
      const result = await client.solveTurnstile(url);

      if (result.isSuccess) {
        return result;
      }

      if (attempt === maxRetries) {
        throw new Error(
          `Failed after ${maxRetries} attempts: ${result.reason}`
        );
      }

      console.log(`Attempt ${attempt} failed, retrying...`);
      await new Promise((resolve) => setTimeout(resolve, 2000));
    } catch (error) {
      if (error instanceof RateLimitError && attempt < maxRetries) {
        console.log("Rate limited, waiting before retry...");
        await new Promise((resolve) => setTimeout(resolve, 5000));
        continue;
      }
      throw error;
    }
  }
}

Configuration Management

// Custom configuration
const client = new RapidCaptchaClient("Rapidcaptcha-your-key", {
  timeout: 120000, // 2 minutes
  maxRetries: 5, // More retries
  retryDelay: 3000, // 3 second delay
  baseUrl: "https://rapidcaptcha.xyz",
});

// Health check
const health = await client.healthCheck();
console.log("API Status:", health.status);

Result Object

The CaptchaResult object contains comprehensive information about the solving attempt:

{
  taskId: "task-123",           // Task identifier
  status: "success",            // "pending", "success", or "error"
  token: "abc123...",           // reCAPTCHA token (if applicable)
  turnstileValue: "0.abc...",   // Turnstile token (if applicable)
  elapsedTimeSeconds: 15.2,     // Time taken to solve
  sitekeyUsed: "0x4AAAA...",    // Sitekey that was used
  sitekeysTried: ["0x4A..."],   // All sitekeys attempted
  reason: "Solved successfully", // Error reason (if failed)
  errors: [],                   // Detailed errors (if any)
  completedAt: "2024-01-01T..."  // Completion timestamp
}

// Helper methods
result.isSuccess  // true if solved successfully
result.isError    // true if solving failed
result.isPending  // true if still in progress

Error Types

The SDK provides specific error types for different scenarios:

• APIKeyError - Invalid or missing API key
• ValidationError - Invalid request parameters
• TaskNotFoundError - Task ID not found or expired
• RateLimitError - Rate limit exceeded
• TimeoutError - Operation timed out
• RapidCaptchaError - Base error class

Browser Support

• Chrome 60+
• Firefox 55+
• Safari 12+
• Edge 79+
• IE 11+ (with polyfills)

Node.js Support

• Node.js 14+
• Full ESM and CommonJS support

TypeScript Support

The SDK includes complete TypeScript definitions:

import type {
  CaptchaResult,
  ClientOptions,
  TurnstileOptions,
  RecaptchaOptions,
} from "rapidcaptcha";

Rate Limiting

The RapidCaptcha API has rate limits. The SDK automatically handles rate limit errors and provides appropriate error types. For high-volume usage:

• Implement retry logic with exponential backoff
• Use concurrent solving wisely
• Monitor your API usage
• Consider upgrading your plan for higher limits

Security

• Never expose your API key in client-side code
• Use environment variables for API keys
• Implement proper error handling
• Validate all inputs before sending to the API

Examples Directory

Check out the /examples directory for more comprehensive examples:

• Node.js Examples: /examples/nodejs/
• Browser Examples: /examples/browser/
• TypeScript Examples: /examples/typescript/

Testing

Running Tests

# Install dependencies
npm install

# Run tests
npm test

# Run browser tests
npm run test:browser

# Run with coverage
npm run test:coverage

Manual Testing

• Set your API key: export RAPIDCAPTCHA_API_KEY="Rapidcaptcha-your-key"
• Run examples: npm run example
• Open browser test: open tests/browser.test.html

Building from Source

# Clone repository
git clone https://github.com/RapidCaptcha-SDK/RapidCaptcha-JavaScript.git
cd RapidCaptcha-JavaScript

# Install dependencies
npm install

# Build all formats
npm run build

# Build specific format
npm run build:es     # ES modules
npm run build:cjs    # CommonJS
npm run build:umd    # Browser UMD

Contributing

• Fork the repository
• Create a feature branch: git checkout -b feature-name
• Make your changes
• Add tests for new functionality
• Run tests: npm test
• Commit changes: git commit -am 'Add feature'
• Push to branch: git push origin feature-name
• Create a Pull Request

Development Guidelines

• Follow existing code style
• Add TypeScript types for new features
• Include comprehensive tests
• Update documentation
• Add examples for new functionality

API Documentation

For complete API documentation, visit: https://rapidcaptcha.xyz/docs

Changelog

v1.0.0

• Initial release
• Turnstile and reCAPTCHA support
• TypeScript definitions
• Browser and Node.js compatibility
• Comprehensive error handling
• Auto-detection capabilities

Support

• 📧 Email: [e-mail]
• 📖 Documentation: https://rapidcaptcha.xyz/docs
• 🐛 Issues: GitHub Issues

License

This project is licensed under the MIT License - see the LICENSE file for details.

FAQ

Q: How do I get an API key?

A: Sign up at rapidcaptcha.xyz to get your API key.

Q: What's the difference between auto-detection and manual sitekey?

A: Auto-detection automatically finds the sitekey from the page, while manual mode requires you to specify the sitekey. Auto-detection is more convenient but may be slower.

Q: Can I solve multiple CAPTCHAs simultaneously?

A: Yes! The SDK supports concurrent solving. Use Promise.all() or Promise.allSettled() with multiple solve calls.

Q: How long does it take to solve a CAPTCHA?

A: Typical solve times range from 10-30 seconds, depending on the CAPTCHA complexity and server load.

Q: Is there a rate limit?

A: Yes, rate limits depend on your subscription plan. The SDK automatically handles rate limit errors.

Q: Can I use this in production?

A: Absolutely! The SDK is production-ready with comprehensive error handling, TypeScript support, and extensive testing.

Q: What browsers are supported?

A: All modern browsers are supported. See the Browser Support section for specific versions.

Made with ❤️ by the RapidCaptcha team