npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

@capbypass/sdk

v1.0.11

Published

Official TypeScript/JavaScript SDK for CapBypass CAPTCHA solving service

Readme

CapBypass TypeScript/JavaScript SDK

npm version License: MIT TypeScript

Official TypeScript/JavaScript SDK for the CapBypass CAPTCHA solving service. Supports reCAPTCHA v2, reCAPTCHA v3, AWS WAF challenges, and Cloudflare Turnstile.

Works in both Node.js and browser environments.

Features

  • ✅ Simple API: One-line solve() method or advanced createTask()/getTaskResult() control
  • 🔄 Automatic Polling: Built-in adaptive polling (first poll after 1 s, then every 1-3 s)
  • 🛡️ Robust Error Handling: Typed errors for all API and network failures
  • 🔁 Smart Retry Logic: Automatic retry on network/gateway errors
  • 🎯 Full TypeScript Support: Complete type definitions for excellent IDE support
  • 🌐 Universal: Works in Node.js and browser environments

Installation

npm install @capbypass/sdk

Quick Start

TypeScript

import { CapBypassClient, TaskType } from '@capbypass/sdk';

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

const solution = await client.solve({
  type: TaskType.RECAPTCHA_V2_PROXYLESS,
  websiteURL: 'https://www.google.com/recaptcha/api2/demo',
  websiteKey: '6Le-wvkSAAAAAPBMRTvw0Q4Muexq9bi0DJwx_mJ-',
}, 120);

console.log('Token:', solution.gRecaptchaResponse);

JavaScript (CommonJS)

const { CapBypassClient, TaskType } = require('@capbypass/sdk');

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

client.solve({
  type: TaskType.RECAPTCHA_V2_PROXYLESS,
  websiteURL: 'https://www.google.com/recaptcha/api2/demo',
  websiteKey: '6Le-wvkSAAAAAPBMRTvw0Q4Muexq9bi0DJwx_mJ-',
}, 120).then(solution => {
  console.log('Token:', solution.gRecaptchaResponse);
});

JavaScript (ES Modules)

import { CapBypassClient, TaskType } from '@capbypass/sdk';

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

const solution = await client.solve({
  type: TaskType.RECAPTCHA_V2_PROXYLESS,
  websiteURL: 'https://www.google.com/recaptcha/api2/demo',
  websiteKey: '6Le-wvkSAAAAAPBMRTvw0Q4Muexq9bi0DJwx_mJ-',
}, 120);

console.log('Token:', solution.gRecaptchaResponse);

API Reference

Client Creation

import { CapBypassClient } from '@capbypass/sdk';

// With API key parameter
const client = new CapBypassClient({ apiKey: 'your-api-key' });

// From CAPBYPASS_API_KEY environment variable
const client = new CapBypassClient();

// With custom base URL
const client = new CapBypassClient({
  apiKey: 'your-api-key',
  baseURL: 'https://custom-gateway.example.com'
});

Simple API (Recommended)

solve() - One-step CAPTCHA solving:

const solution = await client.solve(task, timeout);
  • task: Task configuration (see Task Types below)
  • timeout: Maximum wait time in seconds (default: 120)
  • Returns: Promise

solve() waits 1 s after creating the task before its first getTaskResult request, then waits 1, 1, 2 and 2 s between the next requests, and 3 s between requests from then on. These are waits between requests: the time a request itself takes comes on top. timeout is counted from the end of createTask and is not changed by the waiting schedule.

Advanced API

For full control over task lifecycle:

// Create task
const taskId = await client.createTask(task);

// Poll for result. getTaskResult does not wait by itself: wait 1 s after
// createTask, then 1 to 3 s between calls (not faster), until the task is
// ready or failed, and give up after your own deadline.
const sleep = (ms: number) => new Promise((r) => setTimeout(r, ms));
const deadline = Date.now() + 120_000;
await sleep(1000);
while (true) {
  const result = await client.getTaskResult(taskId);
  if (result.status === 'ready') {
    console.log(result.solution);
    break;
  }
  if (result.status === 'failed') {
    throw new Error(result.errorDescription || 'Task failed');
  }
  if (Date.now() > deadline) {
    throw new Error('Task not ready in time');
  }
  await sleep(2000);
}

// Check balance
const balance = await client.getBalance();

Task Types

reCAPTCHA v2

const solution = await client.solve({
  type: TaskType.RECAPTCHA_V2_PROXYLESS,
  websiteURL: 'https://example.com',
  websiteKey: '6Le-wvkSAAAAAPBMRTvw0Q4Muexq9bi0DJwx_mJ-',
}, 120);

Invisible reCAPTCHA v2:

const solution = await client.solve({
  type: TaskType.RECAPTCHA_V2_PROXYLESS,
  websiteURL: 'https://example.com',
  websiteKey: '6Le-wvkSAAAAAPBMRTvw0Q4Muexq9bi0DJwx_mJ-',
  isInvisible: true,
}, 120);

reCAPTCHA v3

const solution = await client.solve({
  type: TaskType.RECAPTCHA_V3_PROXYLESS,
  websiteURL: 'https://example.com',
  websiteKey: '6LcR_okUAAAAAPYrPe-HK_0RULO1aZM15ENyM-Mf',
  pageAction: 'submit',
}, 120);

AWS WAF Challenge

const solution = await client.solve({
  type: TaskType.ANTI_AWS_WAF_PROXYLESS,
  websiteURL: 'https://example.com',
  awsChallengeJS: 'https://[...].awswaf.com/[...]/challenge.js',
}, 120);

Cloudflare Turnstile

websiteURL and websiteKey are required. action (1 to 32 characters of A-Z a-z 0-9 _ -) and cData (1 to 255 characters of the same set) are optional and replace the page's data-action / data-cdata. The solution holds token (the cf-turnstile-response value) and timing.solveMs; Turnstile returns no userAgent.

const solution = await client.solve({
  type: TaskType.TURNSTILE_PROXYLESS,
  websiteURL: 'https://example.com/login',
  websiteKey: '0x4AAAAAAAxxxxxxxxxxxxxx',
}, 120);
const token = solution.token;

With your own proxy (TurnstileTask requires one): a single http(s) URL in the proxy field, no socks:

const solution = await client.solve({
  type: TaskType.TURNSTILE,
  websiteURL: 'https://example.com/login',
  websiteKey: '0x4AAAAAAAxxxxxxxxxxxxxx',
  action: 'login',
  cData: 'session-42',
  proxy: 'http://user:pass@host:port',
}, 120);

With Proxy

Every task type with a proxy (the non-ProxyLess variants) takes it as one string in the proxy field. The SDK sends it unchanged; the API validates it when the task is created, before anything is billed. Supported protocols: http, https, socks4, socks5 (http when omitted). Some task types accept http(s) proxies only, as their page says (Turnstile and Cloudflare, for example).

| Form | Pattern | |------|---------| | URL | protocol://user:pass@host:port | | Colon | host:port:user:pass or host:port | | Protocol + colon | protocol:host:port:user:pass or protocol:host:port |

Send only the proxy itself: no spaces or other text (a whole line copied from a proxy list is refused), a port from 1 to 65535, and percent-encode any @, /, :, # or ? in the user or password of the URL form. The host must be public. A malformed proxy is refused with ERROR_PROXY_FORMAT (ValidationError) and an internal or reserved address with ERROR_BLOCKED_TARGET (ValidationError). See Proxy Format in the API reference.

const solution = await client.solve({
  type: TaskType.RECAPTCHA_V2,
  websiteURL: 'https://example.com',
  websiteKey: '6Le-wvkSAAAAAPBMRTvw0Q4Muexq9bi0DJwx_mJ-',
  proxy: 'http://username:[email protected]:8080',
}, 120);

Error Handling

The SDK uses typed errors for precise error handling:

import {
  AuthenticationError,
  InsufficientBalanceError,
  ValidationError,
  TimeoutError,
  SolverError,
  NetworkError,
  GatewayError,
} from '@capbypass/sdk';

try {
  const solution = await client.solve(task, 120);
} catch (error) {
  if (error instanceof AuthenticationError) {
    // Invalid API key
  } else if (error instanceof InsufficientBalanceError) {
    // No balance
  } else if (error instanceof ValidationError) {
    // Invalid task parameters
  } else if (error instanceof TimeoutError) {
    // Task took too long
  } else if (error instanceof SolverError) {
    // CAPTCHA could not be solved
  } else if (error instanceof NetworkError) {
    // Network/connection error
  } else if (error instanceof GatewayError) {
    // Gateway error (502/503/504)
  }
}

Task Type Constants

TaskType.ANTI_AWS_WAF                    // AntiAwsWafTask
TaskType.ANTI_AWS_WAF_PROXYLESS          // AntiAwsWafTaskProxyLess
TaskType.RECAPTCHA_V2                    // ReCaptchaV2Task
TaskType.RECAPTCHA_V2_PROXYLESS          // ReCaptchaV2TaskProxyLess
TaskType.RECAPTCHA_V3                    // ReCaptchaV3Task
TaskType.RECAPTCHA_V3_PROXYLESS          // ReCaptchaV3TaskProxyLess
TaskType.RECAPTCHA_V3_ENTERPRISE         // ReCaptchaV3EnterpriseTask
TaskType.RECAPTCHA_V3_ENTERPRISE_PROXYLESS  // ReCaptchaV3EnterpriseTaskProxyLess
TaskType.TURNSTILE                       // TurnstileTask
TaskType.TURNSTILE_PROXYLESS             // TurnstileTaskProxyLess

Documentation

📚 Core Documentation

🔧 Advanced Guides

🔄 Migration

Examples

Basic Examples

See the examples directory for complete runnable examples:

Advanced Examples

Full integration examples in the documentation:

  • E-commerce checkout automation
  • Social media automation
  • Web scraping with CAPTCHA handling
  • Microservice integration patterns

Testing

# Run tests
npm test

# Run tests with coverage
npm run test:coverage

# Run tests in watch mode
npm run test:watch

Building

# Build the package
npm run build

# This generates:
# - dist/index.js (CommonJS)
# - dist/index.mjs (ES Module)
# - dist/index.d.ts (TypeScript declarations)

License

MIT License - see LICENSE file for details.

Links