@capbypass/sdk 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 CapBypass Development
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,274 @@
+# CapBypass TypeScript/JavaScript SDK
+
+[![npm version](https://badge.fury.io/js/@capbypass%2Fsdk.svg)](https://www.npmjs.com/package/@capbypass/sdk)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.3-blue.svg)](https://www.typescriptlang.org/)
+
+Official TypeScript/JavaScript SDK for the CapBypass CAPTCHA solving service. Supports reCAPTCHA v2, reCAPTCHA v3, and AWS WAF challenges.
+
+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 with exponential backoff
+- 🛡️ **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
+
+```bash
+npm install @capbypass/sdk
+```
+
+## Quick Start
+
+### TypeScript
+
+```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)
+
+```javascript
+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)
+
+```javascript
+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
+
+```typescript
+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:
+
+```typescript
+const solution = await client.solve(task, timeout);
+```
+
+- `task`: Task configuration (see Task Types below)
+- `timeout`: Maximum wait time in seconds (default: 120)
+- Returns: Promise<Solution>
+
+### Advanced API
+
+For full control over task lifecycle:
+
+```typescript
+// Create task
+const taskId = await client.createTask(task);
+
+// Poll for result
+const result = await client.getTaskResult(taskId);
+
+// Check balance
+const balance = await client.getBalance();
+```
+
+## Task Types
+
+### reCAPTCHA v2
+
+```typescript
+const solution = await client.solve({
+  type: TaskType.RECAPTCHA_V2_PROXYLESS,
+  websiteURL: 'https://example.com',
+  websiteKey: '6Le-wvkSAAAAAPBMRTvw0Q4Muexq9bi0DJwx_mJ-',
+}, 120);
+```
+
+**Invisible reCAPTCHA v2:**
+
+```typescript
+const solution = await client.solve({
+  type: TaskType.RECAPTCHA_V2_PROXYLESS,
+  websiteURL: 'https://example.com',
+  websiteKey: '6Le-wvkSAAAAAPBMRTvw0Q4Muexq9bi0DJwx_mJ-',
+  isInvisible: true,
+}, 120);
+```
+
+### reCAPTCHA v3
+
+```typescript
+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
+
+```typescript
+const solution = await client.solve({
+  type: TaskType.ANTI_AWS_WAF_PROXYLESS,
+  websiteURL: 'https://example.com',
+  awsChallengeJS: 'https://[...].awswaf.com/[...]/challenge.js',
+}, 120);
+```
+
+### With Proxy
+
+All task types support proxy configuration:
+
+```typescript
+const solution = await client.solve({
+  type: TaskType.RECAPTCHA_V2,
+  websiteURL: 'https://example.com',
+  websiteKey: '6Le-wvkSAAAAAPBMRTvw0Q4Muexq9bi0DJwx_mJ-',
+  proxyType: 'http',
+  proxyAddress: 'proxy.example.com',
+  proxyPort: 8080,
+  proxyLogin: 'username',
+  proxyPassword: 'password',
+}, 120);
+```
+
+## Error Handling
+
+The SDK uses typed errors for precise error handling:
+
+```typescript
+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
+
+```typescript
+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
+```
+
+## Examples
+
+See the [examples](examples/) directory for complete examples:
+- [recaptcha-v2.ts](examples/recaptcha-v2.ts) - reCAPTCHA v2 solving
+- [recaptcha-v3.ts](examples/recaptcha-v3.ts) - reCAPTCHA v3 solving
+- [aws-waf.ts](examples/aws-waf.ts) - AWS WAF challenge solving
+
+## Testing
+
+```bash
+# Run tests
+npm test
+
+# Run tests with coverage
+npm run test:coverage
+
+# Run tests in watch mode
+npm run test:watch
+```
+
+## Building
+
+```bash
+# 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](LICENSE) file for details.
+
+## Links
+
+- [Documentation](https://capbypass.dev/docs/sdks/typescript)
+- [npm Package](https://www.npmjs.com/package/@capbypass/sdk)
+- [GitHub Repository](https://github.com/CapBypass-Development/capbypass-sdk-typescript)
+- [Bug Reports](https://github.com/CapBypass-Development/capbypass-sdk-typescript/issues)

package/dist/index.d.mts

@@ -0,0 +1,187 @@
+/**
+ * Task type constants for CapBypass API
+ */
+declare const TaskType: {
+    readonly ANTI_AWS_WAF: "AntiAwsWafTask";
+    readonly ANTI_AWS_WAF_PROXYLESS: "AntiAwsWafTaskProxyLess";
+    readonly RECAPTCHA_V2: "ReCaptchaV2Task";
+    readonly RECAPTCHA_V2_PROXYLESS: "ReCaptchaV2TaskProxyLess";
+    readonly RECAPTCHA_V3: "ReCaptchaV3Task";
+    readonly RECAPTCHA_V3_PROXYLESS: "ReCaptchaV3TaskProxyLess";
+    readonly RECAPTCHA_V3_ENTERPRISE: "ReCaptchaV3EnterpriseTask";
+    readonly RECAPTCHA_V3_ENTERPRISE_PROXYLESS: "ReCaptchaV3EnterpriseTaskProxyLess";
+};
+type TaskTypeValue = typeof TaskType[keyof typeof TaskType];
+/**
+ * Base task configuration
+ */
+interface BaseTask {
+    type: TaskTypeValue;
+    [key: string]: any;
+}
+/**
+ * Proxy configuration for tasks
+ */
+interface ProxyConfig {
+    proxyType: 'http' | 'https' | 'socks4' | 'socks5';
+    proxyAddress: string;
+    proxyPort: number;
+    proxyLogin?: string;
+    proxyPassword?: string;
+}
+/**
+ * Task result from getTaskResult
+ */
+interface TaskResult {
+    errorId: number;
+    errorCode?: string;
+    errorDescription?: string;
+    status?: 'processing' | 'ready' | 'failed';
+    solution?: Record<string, any>;
+}
+/**
+ * Client configuration options
+ */
+interface ClientOptions {
+    apiKey?: string;
+    baseURL?: string;
+}
+
+/**
+ * CapBypass API Client
+ */
+declare class CapBypassClient {
+    private apiKey;
+    private httpClient;
+    /**
+     * Create a new CapBypass client
+     * @param options - Client configuration options
+     */
+    constructor(options?: ClientOptions);
+    /**
+     * Make HTTP request with retry logic
+     */
+    private makeRequest;
+    /**
+     * Sleep for specified milliseconds
+     */
+    private sleep;
+    /**
+     * Create a new CAPTCHA solving task
+     * @param task - Task configuration
+     * @returns Task ID
+     */
+    createTask(task: BaseTask): Promise<string>;
+    /**
+     * Get the result of a task
+     * @param taskId - Task ID from createTask
+     * @returns Task result
+     */
+    getTaskResult(taskId: string): Promise<TaskResult>;
+    /**
+     * Get account balance
+     * @returns Account balance
+     */
+    getBalance(): Promise<number>;
+    /**
+     * Create a task and poll until solved or timeout
+     * @param task - Task configuration
+     * @param timeout - Maximum wait time in seconds (default: 120)
+     * @returns Solution object
+     */
+    solve(task: BaseTask, timeout?: number): Promise<Record<string, any>>;
+}
+
+/**
+ * Base CapBypass error with Capsolver-compatible structure
+ */
+declare class CapBypassError extends Error {
+    readonly errorId?: number;
+    readonly errorCode?: string;
+    readonly errorDescription?: string;
+    constructor(errorCode?: string, errorDescription?: string, errorId?: number);
+}
+/**
+ * Capsolver API Errors
+ */
+/**
+ * Authentication error - invalid API key
+ */
+declare class AuthenticationError extends CapBypassError {
+    constructor(errorCode: string, errorDescription: string);
+}
+/**
+ * Insufficient balance error
+ */
+declare class InsufficientBalanceError extends CapBypassError {
+    constructor(errorCode: string, errorDescription: string);
+}
+/**
+ * Validation error - invalid task data
+ */
+declare class ValidationError extends CapBypassError {
+    constructor(errorCode: string, errorDescription: string);
+}
+/**
+ * Task not found error
+ */
+declare class TaskNotFoundError extends CapBypassError {
+    constructor(errorCode: string, errorDescription: string);
+}
+/**
+ * Solver error - CAPTCHA could not be solved
+ */
+declare class SolverError extends CapBypassError {
+    constructor(errorDescription: string);
+}
+/**
+ * Timeout error - task solving exceeded timeout
+ */
+declare class TimeoutError extends CapBypassError {
+    constructor();
+}
+/**
+ * Internal server error
+ */
+declare class InternalError extends CapBypassError {
+    constructor(errorCode: string, errorDescription: string);
+}
+/**
+ * HTTP-Layer Errors
+ */
+/**
+ * Network connection error
+ */
+declare class NetworkError extends Error {
+    readonly cause?: Error | undefined;
+    constructor(message: string, cause?: Error | undefined);
+}
+/**
+ * Gateway error (HTTP 502/503/504)
+ */
+declare class GatewayError extends Error {
+    readonly statusCode: number;
+    constructor(statusCode: number, message: string);
+}
+/**
+ * Server error (HTTP 500)
+ */
+declare class ServerError extends Error {
+    readonly statusCode: number;
+    constructor(statusCode: number, message: string);
+}
+/**
+ * Rate limit error (HTTP 429)
+ */
+declare class RateLimitError extends Error {
+    constructor(message: string);
+}
+/**
+ * Parse error - JSON parsing failed
+ */
+declare class ParseError extends Error {
+    readonly cause?: Error | undefined;
+    constructor(message: string, cause?: Error | undefined);
+}
+
+export { AuthenticationError, type BaseTask, CapBypassClient, CapBypassError, type ClientOptions, GatewayError, InsufficientBalanceError, InternalError, NetworkError, ParseError, type ProxyConfig, RateLimitError, ServerError, SolverError, TaskNotFoundError, type TaskResult, TaskType, type TaskTypeValue, TimeoutError, ValidationError };

package/dist/index.d.ts

@@ -0,0 +1,187 @@
+/**
+ * Task type constants for CapBypass API
+ */
+declare const TaskType: {
+    readonly ANTI_AWS_WAF: "AntiAwsWafTask";
+    readonly ANTI_AWS_WAF_PROXYLESS: "AntiAwsWafTaskProxyLess";
+    readonly RECAPTCHA_V2: "ReCaptchaV2Task";
+    readonly RECAPTCHA_V2_PROXYLESS: "ReCaptchaV2TaskProxyLess";
+    readonly RECAPTCHA_V3: "ReCaptchaV3Task";
+    readonly RECAPTCHA_V3_PROXYLESS: "ReCaptchaV3TaskProxyLess";
+    readonly RECAPTCHA_V3_ENTERPRISE: "ReCaptchaV3EnterpriseTask";
+    readonly RECAPTCHA_V3_ENTERPRISE_PROXYLESS: "ReCaptchaV3EnterpriseTaskProxyLess";
+};
+type TaskTypeValue = typeof TaskType[keyof typeof TaskType];
+/**
+ * Base task configuration
+ */
+interface BaseTask {
+    type: TaskTypeValue;
+    [key: string]: any;
+}
+/**
+ * Proxy configuration for tasks
+ */
+interface ProxyConfig {
+    proxyType: 'http' | 'https' | 'socks4' | 'socks5';
+    proxyAddress: string;
+    proxyPort: number;
+    proxyLogin?: string;
+    proxyPassword?: string;
+}
+/**
+ * Task result from getTaskResult
+ */
+interface TaskResult {
+    errorId: number;
+    errorCode?: string;
+    errorDescription?: string;
+    status?: 'processing' | 'ready' | 'failed';
+    solution?: Record<string, any>;
+}
+/**
+ * Client configuration options
+ */
+interface ClientOptions {
+    apiKey?: string;
+    baseURL?: string;
+}
+
+/**
+ * CapBypass API Client
+ */
+declare class CapBypassClient {
+    private apiKey;
+    private httpClient;
+    /**
+     * Create a new CapBypass client
+     * @param options - Client configuration options
+     */
+    constructor(options?: ClientOptions);
+    /**
+     * Make HTTP request with retry logic
+     */
+    private makeRequest;
+    /**
+     * Sleep for specified milliseconds
+     */
+    private sleep;
+    /**
+     * Create a new CAPTCHA solving task
+     * @param task - Task configuration
+     * @returns Task ID
+     */
+    createTask(task: BaseTask): Promise<string>;
+    /**
+     * Get the result of a task
+     * @param taskId - Task ID from createTask
+     * @returns Task result
+     */
+    getTaskResult(taskId: string): Promise<TaskResult>;
+    /**
+     * Get account balance
+     * @returns Account balance
+     */
+    getBalance(): Promise<number>;
+    /**
+     * Create a task and poll until solved or timeout
+     * @param task - Task configuration
+     * @param timeout - Maximum wait time in seconds (default: 120)
+     * @returns Solution object
+     */
+    solve(task: BaseTask, timeout?: number): Promise<Record<string, any>>;
+}
+
+/**
+ * Base CapBypass error with Capsolver-compatible structure
+ */
+declare class CapBypassError extends Error {
+    readonly errorId?: number;
+    readonly errorCode?: string;
+    readonly errorDescription?: string;
+    constructor(errorCode?: string, errorDescription?: string, errorId?: number);
+}
+/**
+ * Capsolver API Errors
+ */
+/**
+ * Authentication error - invalid API key
+ */
+declare class AuthenticationError extends CapBypassError {
+    constructor(errorCode: string, errorDescription: string);
+}
+/**
+ * Insufficient balance error
+ */
+declare class InsufficientBalanceError extends CapBypassError {
+    constructor(errorCode: string, errorDescription: string);
+}
+/**
+ * Validation error - invalid task data
+ */
+declare class ValidationError extends CapBypassError {
+    constructor(errorCode: string, errorDescription: string);
+}
+/**
+ * Task not found error
+ */
+declare class TaskNotFoundError extends CapBypassError {
+    constructor(errorCode: string, errorDescription: string);
+}
+/**
+ * Solver error - CAPTCHA could not be solved
+ */
+declare class SolverError extends CapBypassError {
+    constructor(errorDescription: string);
+}
+/**
+ * Timeout error - task solving exceeded timeout
+ */
+declare class TimeoutError extends CapBypassError {
+    constructor();
+}
+/**
+ * Internal server error
+ */
+declare class InternalError extends CapBypassError {
+    constructor(errorCode: string, errorDescription: string);
+}
+/**
+ * HTTP-Layer Errors
+ */
+/**
+ * Network connection error
+ */
+declare class NetworkError extends Error {
+    readonly cause?: Error | undefined;
+    constructor(message: string, cause?: Error | undefined);
+}
+/**
+ * Gateway error (HTTP 502/503/504)
+ */
+declare class GatewayError extends Error {
+    readonly statusCode: number;
+    constructor(statusCode: number, message: string);
+}
+/**
+ * Server error (HTTP 500)
+ */
+declare class ServerError extends Error {
+    readonly statusCode: number;
+    constructor(statusCode: number, message: string);
+}
+/**
+ * Rate limit error (HTTP 429)
+ */
+declare class RateLimitError extends Error {
+    constructor(message: string);
+}
+/**
+ * Parse error - JSON parsing failed
+ */
+declare class ParseError extends Error {
+    readonly cause?: Error | undefined;
+    constructor(message: string, cause?: Error | undefined);
+}
+
+export { AuthenticationError, type BaseTask, CapBypassClient, CapBypassError, type ClientOptions, GatewayError, InsufficientBalanceError, InternalError, NetworkError, ParseError, type ProxyConfig, RateLimitError, ServerError, SolverError, TaskNotFoundError, type TaskResult, TaskType, type TaskTypeValue, TimeoutError, ValidationError };

package/dist/index.js

@@ -0,0 +1,360 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  AuthenticationError: () => AuthenticationError,
+  CapBypassClient: () => CapBypassClient,
+  CapBypassError: () => CapBypassError,
+  GatewayError: () => GatewayError,
+  InsufficientBalanceError: () => InsufficientBalanceError,
+  InternalError: () => InternalError,
+  NetworkError: () => NetworkError,
+  ParseError: () => ParseError,
+  RateLimitError: () => RateLimitError,
+  ServerError: () => ServerError,
+  SolverError: () => SolverError,
+  TaskNotFoundError: () => TaskNotFoundError,
+  TaskType: () => TaskType,
+  TimeoutError: () => TimeoutError,
+  ValidationError: () => ValidationError
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/client.ts
+var import_axios = __toESM(require("axios"));
+
+// src/errors.ts
+var CapBypassError = class extends Error {
+  constructor(errorCode, errorDescription, errorId) {
+    super(errorDescription || errorCode || "Unknown error");
+    this.name = this.constructor.name;
+    this.errorId = errorId;
+    this.errorCode = errorCode;
+    this.errorDescription = errorDescription;
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+};
+var AuthenticationError = class extends CapBypassError {
+  constructor(errorCode, errorDescription) {
+    super(errorCode, errorDescription, 1);
+  }
+};
+var InsufficientBalanceError = class extends CapBypassError {
+  constructor(errorCode, errorDescription) {
+    super(errorCode, errorDescription, 1);
+  }
+};
+var ValidationError = class extends CapBypassError {
+  constructor(errorCode, errorDescription) {
+    super(errorCode, errorDescription, 1);
+  }
+};
+var TaskNotFoundError = class extends CapBypassError {
+  constructor(errorCode, errorDescription) {
+    super(errorCode, errorDescription, 16);
+  }
+};
+var SolverError = class extends CapBypassError {
+  constructor(errorDescription) {
+    super("SOLVER_FAILED", errorDescription, 0);
+  }
+};
+var TimeoutError = class extends CapBypassError {
+  constructor() {
+    super("TIMEOUT", "Task solving timed out", 0);
+  }
+};
+var InternalError = class extends CapBypassError {
+  constructor(errorCode, errorDescription) {
+    super(errorCode, errorDescription, 1);
+  }
+};
+var NetworkError = class _NetworkError extends Error {
+  constructor(message, cause) {
+    super(`Network error: ${message}`);
+    this.cause = cause;
+    this.name = "NetworkError";
+    Object.setPrototypeOf(this, _NetworkError.prototype);
+  }
+};
+var GatewayError = class _GatewayError extends Error {
+  constructor(statusCode, message) {
+    super(`Gateway error: HTTP ${statusCode} - ${message}`);
+    this.statusCode = statusCode;
+    this.name = "GatewayError";
+    Object.setPrototypeOf(this, _GatewayError.prototype);
+  }
+};
+var ServerError = class _ServerError extends Error {
+  constructor(statusCode, message) {
+    super(`Server error: HTTP ${statusCode} - ${message}`);
+    this.statusCode = statusCode;
+    this.name = "ServerError";
+    Object.setPrototypeOf(this, _ServerError.prototype);
+  }
+};
+var RateLimitError = class _RateLimitError extends Error {
+  constructor(message) {
+    super(`Rate limit exceeded: ${message}`);
+    this.name = "RateLimitError";
+    Object.setPrototypeOf(this, _RateLimitError.prototype);
+  }
+};
+var ParseError = class _ParseError extends Error {
+  constructor(message, cause) {
+    super(`Parse error: ${message}`);
+    this.cause = cause;
+    this.name = "ParseError";
+    Object.setPrototypeOf(this, _ParseError.prototype);
+  }
+};
+function parseError(errorCode, errorDescription) {
+  switch (errorCode) {
+    case "ERROR_KEY_DOES_NOT_EXIST":
+    case "ERROR_KEY_DENIED_ACCESS":
+      throw new AuthenticationError(errorCode, errorDescription);
+    case "ERROR_ZERO_BALANCE":
+    case "ERROR_NO_SLOT_AVAILABLE":
+      throw new InsufficientBalanceError(errorCode, errorDescription);
+    case "ERROR_INVALID_TASK_DATA":
+    case "ERROR_TASK_ABSENT":
+    case "ERROR_TASK_NOT_SUPPORTED":
+      throw new ValidationError(errorCode, errorDescription);
+    case "ERROR_TASK_NOT_FOUND":
+      throw new TaskNotFoundError(errorCode, errorDescription);
+    default:
+      throw new InternalError(errorCode, errorDescription);
+  }
+}
+
+// src/client.ts
+var DEFAULT_BASE_URL = "https://gateway.strayder.io";
+var SDK_VERSION = "1.0.0";
+var USER_AGENT = `capbypass-sdk-typescript/${SDK_VERSION}`;
+var CapBypassClient = class {
+  /**
+   * Create a new CapBypass client
+   * @param options - Client configuration options
+   */
+  constructor(options = {}) {
+    this.apiKey = options.apiKey || process.env.CAPBYPASS_API_KEY || "";
+    if (!this.apiKey) {
+      throw new Error(
+        "API key is required. Provide via constructor or CAPBYPASS_API_KEY environment variable."
+      );
+    }
+    this.httpClient = import_axios.default.create({
+      baseURL: options.baseURL || DEFAULT_BASE_URL,
+      timeout: 3e4,
+      headers: {
+        "Content-Type": "application/json",
+        "User-Agent": USER_AGENT
+      }
+    });
+  }
+  /**
+   * Make HTTP request with retry logic
+   */
+  async makeRequest(endpoint, payload, maxRetries = 3) {
+    let lastError;
+    for (let attempt = 0; attempt <= maxRetries; attempt++) {
+      try {
+        const response = await this.httpClient.post(endpoint, payload);
+        return response.data;
+      } catch (error) {
+        const axiosError = error;
+        if (axiosError.response && [502, 503, 504].includes(axiosError.response.status)) {
+          if (attempt < maxRetries) {
+            const backoff = Math.min(10, Math.pow(2, attempt)) + Math.random();
+            await this.sleep(backoff * 1e3);
+            continue;
+          }
+          throw new GatewayError(
+            axiosError.response.status,
+            axiosError.response.data
+          );
+        }
+        if (axiosError.response) {
+          if (axiosError.response.status === 429) {
+            throw new RateLimitError(axiosError.response.data);
+          }
+          if (axiosError.response.status === 500) {
+            throw new ServerError(
+              axiosError.response.status,
+              axiosError.response.data
+            );
+          }
+          if (axiosError.response.status >= 400) {
+            throw new NetworkError(
+              `HTTP ${axiosError.response.status}: ${axiosError.response.data}`,
+              axiosError
+            );
+          }
+        }
+        if (axiosError.code === "ECONNREFUSED" || axiosError.code === "ETIMEDOUT") {
+          if (attempt < maxRetries) {
+            const backoff = Math.min(10, Math.pow(2, attempt)) + Math.random();
+            await this.sleep(backoff * 1e3);
+            lastError = new NetworkError("Connection failed", axiosError);
+            continue;
+          }
+          throw new NetworkError("Connection failed", axiosError);
+        }
+        throw new NetworkError(axiosError.message, axiosError);
+      }
+    }
+    throw lastError;
+  }
+  /**
+   * Sleep for specified milliseconds
+   */
+  sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+  }
+  /**
+   * Create a new CAPTCHA solving task
+   * @param task - Task configuration
+   * @returns Task ID
+   */
+  async createTask(task) {
+    const request = {
+      clientKey: this.apiKey,
+      task
+    };
+    const response = await this.makeRequest(
+      "/createTask",
+      request
+    );
+    if (response.errorId !== 0) {
+      parseError(response.errorCode, response.errorDescription);
+    }
+    return response.taskId;
+  }
+  /**
+   * Get the result of a task
+   * @param taskId - Task ID from createTask
+   * @returns Task result
+   */
+  async getTaskResult(taskId) {
+    const request = {
+      clientKey: this.apiKey,
+      taskId
+    };
+    const response = await this.makeRequest(
+      "/getTaskResult",
+      request
+    );
+    if (response.errorId !== 0) {
+      parseError(response.errorCode, response.errorDescription);
+    }
+    return response;
+  }
+  /**
+   * Get account balance
+   * @returns Account balance
+   */
+  async getBalance() {
+    const request = {
+      clientKey: this.apiKey
+    };
+    const response = await this.makeRequest(
+      "/getBalance",
+      request
+    );
+    if (response.errorId !== 0) {
+      parseError(response.errorCode, response.errorDescription);
+    }
+    return response.balance;
+  }
+  /**
+   * Create a task and poll until solved or timeout
+   * @param task - Task configuration
+   * @param timeout - Maximum wait time in seconds (default: 120)
+   * @returns Solution object
+   */
+  async solve(task, timeout = 120) {
+    const taskId = await this.createTask(task);
+    const startTime = Date.now();
+    let attempt = 0;
+    while (true) {
+      const elapsed = (Date.now() - startTime) / 1e3;
+      if (elapsed > timeout) {
+        throw new TimeoutError();
+      }
+      const result = await this.getTaskResult(taskId);
+      if (result.status === "ready") {
+        return result.solution;
+      }
+      if (result.status === "failed") {
+        throw new SolverError(
+          result.errorDescription || "Task failed"
+        );
+      }
+      attempt++;
+      const pollInterval = Math.min(5, Math.ceil(attempt / 2));
+      await this.sleep(pollInterval * 1e3);
+    }
+  }
+};
+
+// src/types.ts
+var TaskType = {
+  // AWS WAF
+  ANTI_AWS_WAF: "AntiAwsWafTask",
+  ANTI_AWS_WAF_PROXYLESS: "AntiAwsWafTaskProxyLess",
+  // reCAPTCHA v2
+  RECAPTCHA_V2: "ReCaptchaV2Task",
+  RECAPTCHA_V2_PROXYLESS: "ReCaptchaV2TaskProxyLess",
+  // reCAPTCHA v3
+  RECAPTCHA_V3: "ReCaptchaV3Task",
+  RECAPTCHA_V3_PROXYLESS: "ReCaptchaV3TaskProxyLess",
+  // reCAPTCHA v3 Enterprise
+  RECAPTCHA_V3_ENTERPRISE: "ReCaptchaV3EnterpriseTask",
+  RECAPTCHA_V3_ENTERPRISE_PROXYLESS: "ReCaptchaV3EnterpriseTaskProxyLess"
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  AuthenticationError,
+  CapBypassClient,
+  CapBypassError,
+  GatewayError,
+  InsufficientBalanceError,
+  InternalError,
+  NetworkError,
+  ParseError,
+  RateLimitError,
+  ServerError,
+  SolverError,
+  TaskNotFoundError,
+  TaskType,
+  TimeoutError,
+  ValidationError
+});

package/dist/index.mjs

@@ -0,0 +1,309 @@
+// src/client.ts
+import axios from "axios";
+
+// src/errors.ts
+var CapBypassError = class extends Error {
+  constructor(errorCode, errorDescription, errorId) {
+    super(errorDescription || errorCode || "Unknown error");
+    this.name = this.constructor.name;
+    this.errorId = errorId;
+    this.errorCode = errorCode;
+    this.errorDescription = errorDescription;
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+};
+var AuthenticationError = class extends CapBypassError {
+  constructor(errorCode, errorDescription) {
+    super(errorCode, errorDescription, 1);
+  }
+};
+var InsufficientBalanceError = class extends CapBypassError {
+  constructor(errorCode, errorDescription) {
+    super(errorCode, errorDescription, 1);
+  }
+};
+var ValidationError = class extends CapBypassError {
+  constructor(errorCode, errorDescription) {
+    super(errorCode, errorDescription, 1);
+  }
+};
+var TaskNotFoundError = class extends CapBypassError {
+  constructor(errorCode, errorDescription) {
+    super(errorCode, errorDescription, 16);
+  }
+};
+var SolverError = class extends CapBypassError {
+  constructor(errorDescription) {
+    super("SOLVER_FAILED", errorDescription, 0);
+  }
+};
+var TimeoutError = class extends CapBypassError {
+  constructor() {
+    super("TIMEOUT", "Task solving timed out", 0);
+  }
+};
+var InternalError = class extends CapBypassError {
+  constructor(errorCode, errorDescription) {
+    super(errorCode, errorDescription, 1);
+  }
+};
+var NetworkError = class _NetworkError extends Error {
+  constructor(message, cause) {
+    super(`Network error: ${message}`);
+    this.cause = cause;
+    this.name = "NetworkError";
+    Object.setPrototypeOf(this, _NetworkError.prototype);
+  }
+};
+var GatewayError = class _GatewayError extends Error {
+  constructor(statusCode, message) {
+    super(`Gateway error: HTTP ${statusCode} - ${message}`);
+    this.statusCode = statusCode;
+    this.name = "GatewayError";
+    Object.setPrototypeOf(this, _GatewayError.prototype);
+  }
+};
+var ServerError = class _ServerError extends Error {
+  constructor(statusCode, message) {
+    super(`Server error: HTTP ${statusCode} - ${message}`);
+    this.statusCode = statusCode;
+    this.name = "ServerError";
+    Object.setPrototypeOf(this, _ServerError.prototype);
+  }
+};
+var RateLimitError = class _RateLimitError extends Error {
+  constructor(message) {
+    super(`Rate limit exceeded: ${message}`);
+    this.name = "RateLimitError";
+    Object.setPrototypeOf(this, _RateLimitError.prototype);
+  }
+};
+var ParseError = class _ParseError extends Error {
+  constructor(message, cause) {
+    super(`Parse error: ${message}`);
+    this.cause = cause;
+    this.name = "ParseError";
+    Object.setPrototypeOf(this, _ParseError.prototype);
+  }
+};
+function parseError(errorCode, errorDescription) {
+  switch (errorCode) {
+    case "ERROR_KEY_DOES_NOT_EXIST":
+    case "ERROR_KEY_DENIED_ACCESS":
+      throw new AuthenticationError(errorCode, errorDescription);
+    case "ERROR_ZERO_BALANCE":
+    case "ERROR_NO_SLOT_AVAILABLE":
+      throw new InsufficientBalanceError(errorCode, errorDescription);
+    case "ERROR_INVALID_TASK_DATA":
+    case "ERROR_TASK_ABSENT":
+    case "ERROR_TASK_NOT_SUPPORTED":
+      throw new ValidationError(errorCode, errorDescription);
+    case "ERROR_TASK_NOT_FOUND":
+      throw new TaskNotFoundError(errorCode, errorDescription);
+    default:
+      throw new InternalError(errorCode, errorDescription);
+  }
+}
+
+// src/client.ts
+var DEFAULT_BASE_URL = "https://gateway.strayder.io";
+var SDK_VERSION = "1.0.0";
+var USER_AGENT = `capbypass-sdk-typescript/${SDK_VERSION}`;
+var CapBypassClient = class {
+  /**
+   * Create a new CapBypass client
+   * @param options - Client configuration options
+   */
+  constructor(options = {}) {
+    this.apiKey = options.apiKey || process.env.CAPBYPASS_API_KEY || "";
+    if (!this.apiKey) {
+      throw new Error(
+        "API key is required. Provide via constructor or CAPBYPASS_API_KEY environment variable."
+      );
+    }
+    this.httpClient = axios.create({
+      baseURL: options.baseURL || DEFAULT_BASE_URL,
+      timeout: 3e4,
+      headers: {
+        "Content-Type": "application/json",
+        "User-Agent": USER_AGENT
+      }
+    });
+  }
+  /**
+   * Make HTTP request with retry logic
+   */
+  async makeRequest(endpoint, payload, maxRetries = 3) {
+    let lastError;
+    for (let attempt = 0; attempt <= maxRetries; attempt++) {
+      try {
+        const response = await this.httpClient.post(endpoint, payload);
+        return response.data;
+      } catch (error) {
+        const axiosError = error;
+        if (axiosError.response && [502, 503, 504].includes(axiosError.response.status)) {
+          if (attempt < maxRetries) {
+            const backoff = Math.min(10, Math.pow(2, attempt)) + Math.random();
+            await this.sleep(backoff * 1e3);
+            continue;
+          }
+          throw new GatewayError(
+            axiosError.response.status,
+            axiosError.response.data
+          );
+        }
+        if (axiosError.response) {
+          if (axiosError.response.status === 429) {
+            throw new RateLimitError(axiosError.response.data);
+          }
+          if (axiosError.response.status === 500) {
+            throw new ServerError(
+              axiosError.response.status,
+              axiosError.response.data
+            );
+          }
+          if (axiosError.response.status >= 400) {
+            throw new NetworkError(
+              `HTTP ${axiosError.response.status}: ${axiosError.response.data}`,
+              axiosError
+            );
+          }
+        }
+        if (axiosError.code === "ECONNREFUSED" || axiosError.code === "ETIMEDOUT") {
+          if (attempt < maxRetries) {
+            const backoff = Math.min(10, Math.pow(2, attempt)) + Math.random();
+            await this.sleep(backoff * 1e3);
+            lastError = new NetworkError("Connection failed", axiosError);
+            continue;
+          }
+          throw new NetworkError("Connection failed", axiosError);
+        }
+        throw new NetworkError(axiosError.message, axiosError);
+      }
+    }
+    throw lastError;
+  }
+  /**
+   * Sleep for specified milliseconds
+   */
+  sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+  }
+  /**
+   * Create a new CAPTCHA solving task
+   * @param task - Task configuration
+   * @returns Task ID
+   */
+  async createTask(task) {
+    const request = {
+      clientKey: this.apiKey,
+      task
+    };
+    const response = await this.makeRequest(
+      "/createTask",
+      request
+    );
+    if (response.errorId !== 0) {
+      parseError(response.errorCode, response.errorDescription);
+    }
+    return response.taskId;
+  }
+  /**
+   * Get the result of a task
+   * @param taskId - Task ID from createTask
+   * @returns Task result
+   */
+  async getTaskResult(taskId) {
+    const request = {
+      clientKey: this.apiKey,
+      taskId
+    };
+    const response = await this.makeRequest(
+      "/getTaskResult",
+      request
+    );
+    if (response.errorId !== 0) {
+      parseError(response.errorCode, response.errorDescription);
+    }
+    return response;
+  }
+  /**
+   * Get account balance
+   * @returns Account balance
+   */
+  async getBalance() {
+    const request = {
+      clientKey: this.apiKey
+    };
+    const response = await this.makeRequest(
+      "/getBalance",
+      request
+    );
+    if (response.errorId !== 0) {
+      parseError(response.errorCode, response.errorDescription);
+    }
+    return response.balance;
+  }
+  /**
+   * Create a task and poll until solved or timeout
+   * @param task - Task configuration
+   * @param timeout - Maximum wait time in seconds (default: 120)
+   * @returns Solution object
+   */
+  async solve(task, timeout = 120) {
+    const taskId = await this.createTask(task);
+    const startTime = Date.now();
+    let attempt = 0;
+    while (true) {
+      const elapsed = (Date.now() - startTime) / 1e3;
+      if (elapsed > timeout) {
+        throw new TimeoutError();
+      }
+      const result = await this.getTaskResult(taskId);
+      if (result.status === "ready") {
+        return result.solution;
+      }
+      if (result.status === "failed") {
+        throw new SolverError(
+          result.errorDescription || "Task failed"
+        );
+      }
+      attempt++;
+      const pollInterval = Math.min(5, Math.ceil(attempt / 2));
+      await this.sleep(pollInterval * 1e3);
+    }
+  }
+};
+
+// src/types.ts
+var TaskType = {
+  // AWS WAF
+  ANTI_AWS_WAF: "AntiAwsWafTask",
+  ANTI_AWS_WAF_PROXYLESS: "AntiAwsWafTaskProxyLess",
+  // reCAPTCHA v2
+  RECAPTCHA_V2: "ReCaptchaV2Task",
+  RECAPTCHA_V2_PROXYLESS: "ReCaptchaV2TaskProxyLess",
+  // reCAPTCHA v3
+  RECAPTCHA_V3: "ReCaptchaV3Task",
+  RECAPTCHA_V3_PROXYLESS: "ReCaptchaV3TaskProxyLess",
+  // reCAPTCHA v3 Enterprise
+  RECAPTCHA_V3_ENTERPRISE: "ReCaptchaV3EnterpriseTask",
+  RECAPTCHA_V3_ENTERPRISE_PROXYLESS: "ReCaptchaV3EnterpriseTaskProxyLess"
+};
+export {
+  AuthenticationError,
+  CapBypassClient,
+  CapBypassError,
+  GatewayError,
+  InsufficientBalanceError,
+  InternalError,
+  NetworkError,
+  ParseError,
+  RateLimitError,
+  ServerError,
+  SolverError,
+  TaskNotFoundError,
+  TaskType,
+  TimeoutError,
+  ValidationError
+};

package/package.json

@@ -0,0 +1,68 @@
+{
+  "name": "@capbypass/sdk",
+  "version": "1.0.0",
+  "description": "Official TypeScript/JavaScript SDK for CapBypass CAPTCHA solving service",
+  "main": "dist/index.js",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsup src/index.ts --format cjs,esm --dts --clean",
+    "test": "jest",
+    "test:watch": "jest --watch",
+    "test:coverage": "jest --coverage",
+    "lint": "eslint src/**/*.ts",
+    "format": "prettier --write \"src/**/*.ts\"",
+    "prepublishOnly": "npm run build && npm test"
+  },
+  "keywords": [
+    "captcha",
+    "recaptcha",
+    "aws-waf",
+    "automation",
+    "solver",
+    "typescript",
+    "javascript"
+  ],
+  "author": {
+    "name": "CapBypass Development",
+    "email": "dev@capbypass.dev"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/CapBypass-Development/capbypass-sdk-typescript.git"
+  },
+  "bugs": {
+    "url": "https://github.com/CapBypass-Development/capbypass-sdk-typescript/issues"
+  },
+  "homepage": "https://capbypass.dev/docs/sdks/typescript",
+  "dependencies": {
+    "axios": "^1.6.7"
+  },
+  "devDependencies": {
+    "@types/jest": "^29.5.12",
+    "@types/node": "^20.11.19",
+    "@typescript-eslint/eslint-plugin": "^7.0.1",
+    "@typescript-eslint/parser": "^7.0.1",
+    "axios-mock-adapter": "^1.22.0",
+    "eslint": "^8.56.0",
+    "jest": "^29.7.0",
+    "prettier": "^3.2.5",
+    "ts-jest": "^29.1.2",
+    "tsup": "^8.0.2",
+    "typescript": "^5.3.3"
+  },
+  "engines": {
+    "node": ">=16"
+  }
+}