@capbypass/sdk
v1.0.11
Published
Official TypeScript/JavaScript SDK for CapBypass CAPTCHA solving service
Maintainers
Readme
CapBypass TypeScript/JavaScript SDK
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 advancedcreateTask()/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/sdkQuick 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 // TurnstileTaskProxyLessDocumentation
📚 Core Documentation
🔧 Advanced Guides
- Proxy Configuration — HTTP, HTTPS, SOCKS5 proxy support with rotation strategies
- Error Handling — Retry strategies, circuit breakers, production alerting
- Performance Optimization — Concurrent solving, connection pooling, token caching
- Production Deployment — Kubernetes, AWS Lambda, monitoring, security
🔄 Migration
- Migrating from Capsolver — 100% API compatible, drop-in replacement
Examples
Basic Examples
See the examples directory for complete runnable examples:
- recaptcha-v2.ts - reCAPTCHA v2 solving
- recaptcha-v3.ts - reCAPTCHA v3 solving
- aws-waf.ts - AWS WAF challenge solving
- turnstile.ts - Cloudflare Turnstile solving
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:watchBuilding
# 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.
