Node.js SDK

The CaptchaSonic Node.js SDK is a modern, Promise-based library designed for high-throughput automation. It features first-class TypeScript support and automatic retry logic.

Installation

npm install captchasonic
# or
yarn add captchasonic

Usage Example

Integrate solving logic into your Node.js scripts using async/await.

const { CaptchaSonic } = require('captchasonic');

// Initialize with your API Key
const solver = new CaptchaSonic('YOUR_API_KEY');

async function run() {
  try {
    // 1. Submit the challenge
    const taskId = await solver.createTask({
      type: 'HCaptchaTaskProxyless',
      websiteURL: 'https://mysite.com',
      websiteKey: '00000000-0000-0000-0000-000000000000'
    });

    console.log('Task submitted:', taskId);

    // 2. Poll for the result
    // The SDK handles the polling interval and timeouts internally
    const result = await solver.getTaskResult(taskId);

    if (result.status === 'ready') {
      console.log('Solution found:', result.solution.gRecaptchaResponse);
    }
  } catch (err) {
    console.error('An error occurred:', err.message);
  }
}

run();

TypeScript Integration

The SDK includes built-in types for all task definitions and responses.

import { CaptchaSonic, TaskTypes } from 'captchasonic';

const solver = new CaptchaSonic('YOUR_API_KEY');

const task: TaskTypes.RecaptchaV2Task = {
  type: 'RecaptchaV2TaskProxyless',
  websiteURL: 'https://example.com',
  websiteKey: '...'
};

const taskId: string = await solver.createTask(task);

Configuration Options

You can customize the client behavior during initialization:

const solver = new CaptchaSonic('YOUR_API_KEY', {
  pollingInterval: 5000, // Check every 5 seconds (default: 3000)
  timeout: 180000,       // Global timeout 3 minutes (default: 120000)
  baseUrl: 'https://api.captchasonic.com' // Custom endpoint override
});

Common Methods

`createTask(params: object): Promise<string>`

Submits a task to the CaptchaSonic AI.

`getTaskResult(taskId: string): Promise<TaskResult>`

Wait for completion. Returns an object containing the solution string.

`getBalance(): Promise<number>`

Fetch your current credit balance ($).