El SDK de Node.js de CaptchaSonic (`captchasonic`) es una biblioteca moderna, basada en Promises y orientada a TypeScript, para resolver CAPTCHAs a gran escala. Cada método devuelve una `Promise`, incluye definiciones de tipos completas y funciona con tres transportes intercambiables: **gRPC** nativo (el más rápido, solo Node.js), **ConnectRPC** (funciona en Node.js y en navegadores) y **HTTP/JSON** sencillo. Los errores transitorios se reintentan automáticamente con retroceso exponencial.

Funciona en **Node.js ≥ 18** y en navegadores modernos, y es compatible con Express, Fastify, Next.js, React, Vue y Vite.

---

## Instalación

```bash
npm install captchasonic
# or
yarn add captchasonic
# or
pnpm add captchasonic
```

**Requisitos**

| Requisito | Notas |
|---|---|
| Node.js | ≥ 18.0.0 (necesario para el transporte `grpc`) |
| Formato de módulo | ES Module: el paquete incluye `"type": "module"` |
| Navegador | Cualquier navegador moderno con `fetch`; usa el transporte `connect` o `http` |

El paquete se publica **solo como ESM**. En un proyecto ESM (`"type": "module"` en tu `package.json`, o un archivo `.mjs`), impórtalo directamente:

<Snippet sdk="typescript" region="importEsm" />

Desde un archivo CommonJS, cárgalo con un `import()` dinámico:

<Snippet sdk="typescript" region="importCommonJS" />

> [!TIP]
> Si usas TypeScript, define `"module": "NodeNext"` (o `"ESNext"`) y `"moduleResolution": "NodeNext"` en `tsconfig.json` para que las definiciones de tipos incluidas se resuelvan correctamente.

---

## Autenticación

Crea una clave API en el [panel de CaptchaSonic](https://captchasonic.com) y pásala como primer argumento del constructor:

<Snippet sdk="typescript" region="createClientApiKey" />

Nunca incluyas claves en el código fuente del control de versiones. Léela desde el entorno:

<Snippet sdk="typescript" region="createClientEnv" />

---

## Inicio rápido

Cada tipo de CAPTCHA tiene un ayudante `solve*` dedicado que envía la tarea y se resuelve con el resultado. No hay un paso de sondeo aparte para las tareas de imagen: el SDK lo gestiona por ti.

<MethodRef name="solveRecaptchaV2Token" lang="node" />

<LangTabs>
  <LangTabs.Tab label="Node">

<Snippet sdk="typescript" region="solveRecaptchaV2Token" />

  </LangTabs.Tab>
  <LangTabs.Tab label="Python">

<Snippet sdk="python" region="solveRecaptchaV2Token_quickstart" />

  </LangTabs.Tab>
</LangTabs>

> **Devuelve:** los métodos de imagen resuelven un resultado cuya respuesta está en `typedSolution` (p. ej., `typedSolution.grid.objects`, los índices de las casillas seleccionadas); los métodos de token devuelven el token en el mapa `solution`.

> [!TIP]
> Los métodos basados en token (Turnstile, Cloudflare, reCAPTCHA v2/v3 token, token de popular-captcha) envían una tarea de automatización de navegador y sondean internamente hasta que el token está listo; por defecto, hasta 120 segundos.

---

## Tipos de CAPTCHA compatibles

Todos los métodos de imagen reciben un único objeto de opciones tipado. Las imágenes pueden ser `Uint8Array`, `Buffer` de Node o una ruta de archivo en forma de cadena (las rutas de archivo solo funcionan en Node.js).

### reCAPTCHA v2 (imagen)

<Snippet sdk="typescript" region="solveRecaptchaV2" />

### PopularCaptcha (imagen estilo hCaptcha)

<Snippet sdk="typescript" region="solvePopularCaptcha" />

### GeeTest

<Snippet sdk="typescript" region="solveGeetest" />

Devuelve: los tipos grid/click van a `typedSolution.grid.objects` (o `typedSolution.click`); slide devuelve `typedSolution.slide.x`.

Alias aceptados en `type`:

| Canónico | Alias |
|---|---|
| cuadrícula de 9 | `"nine"`, `"geetest_nine"`, `"9"` |
| click / icono | `"click"`, `"geetest_click"`, `"icon"` |
| deslizar | `"slide"`, `"geetest_slide"` |
| coincidencia | `"match"`, `"geetest_match"` |
| winlinze | `"winlinze"`, `"geetest_winlinze"` |

### OCR / imagen a texto

<Snippet sdk="typescript" region="solveOcr" />

| Opción | Tipo | Notas |
|---|---|---|
| `module` | `"common"` \| `"mtcaptcha"` \| `"bls"` \| `"morocco"` | Predeterminado `"common"` |
| `numeric` | `boolean` | Solo dígitos (se activa automáticamente para `"bls"`) |
| `caseSensitive` | `boolean` | Conserva las mayúsculas y minúsculas |
| `minLength` / `maxLength` | `number` | Límites de longitud |

### TikTok

<Snippet sdk="typescript" region="solveTikTok" />

Devuelve: `click` va a `typedSolution.click`; `whirl`/`slide` devuelven `typedSolution.slide.x`.

`type` acepta `"click"`/`"tiktok_click"`, `"whirl"`/`"tiktok_whirl"`, `"slide"`/`"tiktok_slide"`.

### Binance

<Snippet sdk="typescript" region="solveBinance" />

Devuelve: `grid` va a `typedSolution.grid.objects`; `slide` devuelve `typedSolution.slide.x`.

`type` acepta `"grid"`/`"binance_grid"` y `"slide"`/`"binance_slide"`.

### AWS WAF

`solveAwsWaf` recibe argumentos posicionales. La `question` tiene el formato `"type:category:target"`.

<Snippet sdk="typescript" region="solveAwsWaf" />

Devuelve: los índices de las casillas seleccionadas en `typedSolution.grid.objects`.

### Imagen de slide (local, sin IA)

Detecta el desplazamiento del slide localmente mediante detección de contornos. Acepta una imagen combinada o `[background, piece]`.

<Snippet sdk="typescript" region="solveSlideImage" />

Devuelve: el desplazamiento del slide en píxeles en `typedSolution.slide.x`.

### Métodos de token (automatización de navegador)

Estos envían una tarea y sondean internamente hasta que se devuelve un token (hasta el tiempo límite de sondeo, 120 s por defecto).

<MethodRef name="solveTurnstile" lang="node" />

<LangTabs>
  <LangTabs.Tab label="Node">

<Snippet sdk="typescript" region="solveTokenMethods" />

  </LangTabs.Tab>
  <LangTabs.Tab label="Python">

<Snippet sdk="python" region="solveTokenMethods" />

  </LangTabs.Tab>
</LangTabs>

Devuelve: el token en el mapa `solution` de la respuesta (por ejemplo, `result.solution.token` o `result.solution.gRecaptchaResponse`, según el CAPTCHA).

---

## Uso con TypeScript

El SDK exporta tipos para cada objeto de opciones y de respuesta. Impórtalos con `import type`.

<Snippet sdk="typescript" region="typescriptUsage" />

**Tipos exportados**

<Snippet sdk="typescript" region="typescriptExportedTypes" />

`ImageInput` es `Uint8Array | Buffer | string`.

---

## Compatibilidad con proxy

Los métodos de token y de automatización de navegador aceptan una cadena `proxy` opcional con el formato `http://user:pass@host:port`:

<Snippet sdk="typescript" region="solveTurnstile" />

> [!WARNING]
> `solveCloudflare` **siempre requiere** un proxy: el campo `proxy` es obligatorio para ese método. Los demás métodos de token se ejecutan sin proxy cuando se omite `proxy`.

Para hCaptcha empresarial también puedes pasar `metadata` (`rqdata`, `rqtoken`, `fingerprint`) a `solvePopularCaptchaToken`.

---

## Configuración

Pasa un objeto de opciones como segundo argumento del constructor. Solo se admiten las opciones siguientes.

<Snippet sdk="typescript" region="configureClient" />

| Opción | Tipo | Predeterminado | Descripción |
|---|---|---|---|
| `transport` | `"grpc"` \| `"connect"` \| `"http"` | `"grpc"` | Protocolo de transmisión (ver la tabla siguiente) |
| `timeout` / `timeoutMs` | `number` | `30000` por llamada | Tiempo límite de la petición; `timeout` también limita la espera del sondeo |
| `pollingInterval` | `number` | `2000` | Frecuencia con la que se sondean las tareas de token |
| `url` / `baseUrl` | `string` | según el transporte | Sustituye el endpoint de la API |

**Transportes**

| Transporte | Entornos | Protocolo |
|---|---|---|
| `grpc` | Solo Node.js | gRPC binario sobre HTTP/2: menor latencia, envía las imágenes como binario sin procesar |
| `connect` | Node.js y navegadores | ConnectRPC sobre `fetch` |
| `http` | Node.js y navegadores | REST/JSON sencillo sobre `fetch` |

> [!TIP]
> En el navegador usa `connect` (recomendado) o `http`. El gRPC nativo requiere Node.js. Con `connect`/`http`, las imágenes se codifican automáticamente en base64 antes de enviarse; con `grpc` se envían como binario sin procesar, sin sobrecarga.

---

## Manejo de errores

Todos los fallos a nivel de API lanzan un `SonicError`, que extiende el `Error` integrado. Incluye un `errorId` numérico y asigna a `name` el nombre del error correspondiente.

<Snippet sdk="typescript" region="errorHandling" />

<ErrorIdTable />

> [!TIP]
> Los errores transitorios de gRPC se reintentan automáticamente con retroceso exponencial (hasta 3 intentos), así que normalmente solo necesitas gestionar los casos de `SonicError` de arriba.

---

## Ayudantes de cuenta

<Snippet sdk="typescript" region="accountHelpers" />

Los métodos de tarea de bajo nivel están disponibles si necesitas control directo sobre el envío y el sondeo:

<Snippet sdk="typescript" region="lowLevelTask" />

---

## Solución de problemas

**`require is not defined` / `Cannot use import statement outside a module`**: el paquete es solo ESM. Usa `import` en un proyecto ESM, o `await import("captchasonic")` desde CommonJS. Consulta [Instalación](#installation).

**El transporte `grpc` falla en el navegador**: el gRPC nativo es solo para Node.js. Cambia a `transport: "connect"` o `transport: "http"`.

**`InvalidApiKeyError` en cada llamada**: confirma que la clave se pasa como primer argumento del constructor y que no es `undefined` por accidente (por ejemplo, una variable de entorno que falta).

**El método de token agota el tiempo de espera**: las tareas de token sondean hasta `timeout` ms (por defecto 120000). Aumenta `timeout` y verifica que `websiteURL` / `websiteKey` coincidan con la página de destino. En Cloudflare es obligatorio un `proxy` válido.

**Las imágenes con ruta de archivo no se cargan**: las rutas de archivo en forma de cadena se leen de forma síncrona y solo son válidas en Node.js; en el navegador pasa un `Uint8Array` en su lugar.

---

## Recursos

*   [Paquete en npm](https://www.npmjs.com/package/captchasonic)
*   [Referencia de la API](/docs/api)
*   [Panel y documentación de CaptchaSonic](https://captchasonic.com)
