TypeScript / JavaScript

Installation

npm install @capbypass/sdk

pnpm add @capbypass/sdk

yarn add @capbypass/sdk

bun add @capbypass/sdk

Requirements: Node.js 18.12.0 or later.

Quick Start

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

const client = new CapBypassClient({
  apiKey: 'YOUR_API_KEY',
  baseURL: 'https://api.capbypass.pro',
});

// One-step solve (recommended)
const solution = await client.solve({
  type: TaskType.RECAPTCHA_V3_PROXYLESS,
  websiteURL: 'https://example.com',
  websiteKey: '6LdyC2cUAAAAACGuDKpXeDorzUDWXmdqeg-xy696',
  pageAction: 'login',
});

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

Constructor Options

const client = new CapBypassClient({
  apiKey: 'YOUR_API_KEY',           // Required (or set CAPBYPASS_API_KEY env var)
  baseURL: 'https://api.capbypass.pro', // API base URL
  developerKey: 'DEV_KEY',         // Optional, for affiliate tracking
});

Option	Type	Default	Description
`apiKey`	string	`CAPBYPASS_API_KEY` env	Your API key
`baseURL`	string	-	API base URL
`developerKey`	string	`CAPBYPASS_DEVELOPER_KEY` env	Affiliate developer key

Methods

`solve(task, timeout?)` - One-Step Solve

Recommended approach

Use solve() for most integrations. It handles task creation and polling automatically, so you don't need to manage the polling loop yourself.

Creates a task and polls until completion.

const solution = await client.solve({
  type: TaskType.RECAPTCHA_V3_PROXYLESS,
  websiteURL: 'https://example.com',
  websiteKey: '6LdyC2cUAAAAACGuDKpXeDorzUDWXmdqeg-xy696',
  pageAction: 'login',
}, 120); // timeout in seconds (default: 120)

`createTask(task)` - Create Task

Returns a task ID for manual polling.

const taskId = await client.createTask({
  type: TaskType.ANTI_AWS_WAF_PROXYLESS,
  websiteURL: 'https://example.com',
});

`getTaskResult(taskId)` - Get Result

Poll for a task's result.

const result = await client.getTaskResult(taskId);

if (result.status === 'ready') {
  console.log(result.solution);
} else if (result.status === 'processing') {
  // Still working, poll again
}

`getBalance()` - Check Balance

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

`getPricing()` - Get Pricing

Public endpoint, no API key required.

const pricing = await client.getPricing();
// [{ task_type: 'ReCaptchaV3TaskProxyLess', user_cost: 0.0006, status: 'active' }, ...]

Task Types

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

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.ANTI_AWS_WAF                    // 'AntiAwsWafTask'
TaskType.ANTI_AWS_WAF_PROXYLESS          // 'AntiAwsWafTaskProxyLess'
TaskType.GEETEST                         // 'GeetestTask'
TaskType.GEETEST_PROXYLESS               // 'GeetestTaskProxyLess'```

## Error Handling

The SDK throws typed errors you can catch:

```typescript
import {
  CapBypassError,
  AuthenticationError,
  InsufficientBalanceError,
  TimeoutError,
  SolverError,
} from '@capbypass/sdk';

try {
  const solution = await client.solve(task);
} catch (error) {
  if (error instanceof AuthenticationError) {
    // Invalid API key
  } else if (error instanceof InsufficientBalanceError) {
    // Need to top up
  } else if (error instanceof TimeoutError) {
    // Task took too long
  } else if (error instanceof SolverError) {
    // Challenge unsolvable
  } else if (error instanceof CapBypassError) {
    // Other API error
    console.error(error.code, error.message);
  }
}

Full Example - AWS WAF

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

const client = new CapBypassClient({
  apiKey: 'YOUR_API_KEY',
  baseURL: 'https://api.capbypass.pro',
});

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

// Use the cookie in your requests
const cookie = solution.cookie;