O SDK Node.js da CaptchaSonic (`captchasonic`) é uma biblioteca moderna, baseada em Promises e com TypeScript em primeiro lugar, para resolver CAPTCHAs em grande escala. Todos os métodos retornam uma `Promise`, incluem definições de tipos completas e funcionam sobre três transportes intercambiáveis — **gRPC** nativo (o mais rápido, somente Node.js), **ConnectRPC** (funciona em Node.js e navegadores) e **HTTP/JSON** simples. Erros transitórios são repetidos automaticamente com backoff exponencial.

Ele funciona no **Node.js ≥ 18** e em navegadores modernos, e é compatível com Express, Fastify, Next.js, React, Vue e Vite.

---

## Instalação

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

**Requisitos**

| Requisito | Observações |
|---|---|
| Node.js | ≥ 18.0.0 (necessário para o transporte `grpc`) |
| Formato de módulo | ES Module — o pacote inclui `"type": "module"` |
| Navegador | Qualquer navegador moderno com `fetch`; use o transporte `connect` ou `http` |

O pacote é publicado **somente como ESM**. Em um projeto ESM (`"type": "module"` no seu `package.json`, ou um arquivo `.mjs`), importe-o diretamente:

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

A partir de um arquivo CommonJS, carregue-o com um `import()` dinâmico:

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

> [!TIP]
> Se você usa TypeScript, defina `"module": "NodeNext"` (ou `"ESNext"`) e `"moduleResolution": "NodeNext"` no `tsconfig.json` para que as definições de tipos incluídas sejam resolvidas corretamente.

---

## Autenticação

Crie uma API key no [dashboard da CaptchaSonic](https://captchasonic.com) e passe-a como primeiro argumento do construtor:

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

Nunca deixe chaves fixas no controle de versão. Leia a chave do ambiente:

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

---

## Início rápido

Cada tipo de captcha tem um helper `solve*` dedicado que envia a tarefa e resolve com o resultado. Não há uma etapa separada de polling para tarefas de imagem — o SDK cuida disso para você.

<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>

> **Retorno:** os métodos de imagem resolvem com um resultado cuja resposta fica em `typedSolution` (ex.: `typedSolution.grid.objects`, os índices dos blocos selecionados); os métodos de token retornam o token no mapa `solution`.

> [!TIP]
> Os métodos baseados em token (Turnstile, Cloudflare, reCAPTCHA v2/v3 token, popular-captcha token) enviam uma tarefa de automação de navegador e fazem polling internamente até o token estar pronto — por padrão, por até 120 segundos.

---

## Tipos de CAPTCHA suportados

Todos os métodos de imagem recebem um único objeto de opções tipado. As imagens podem ser `Uint8Array`, `Buffer` do Node ou um caminho de arquivo em string (caminhos de arquivo são exclusivos do Node.js).

### reCAPTCHA v2 (imagem)

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

### PopularCaptcha (imagem estilo hCaptcha)

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

### GeeTest

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

Retorno: os tipos de grade/clique ficam em `typedSolution.grid.objects` (ou `typedSolution.click`); o tipo slide retorna `typedSolution.slide.x`.

Aliases aceitos em `type`:

| Canônico | Aliases |
|---|---|
| nine-grid | `"nine"`, `"geetest_nine"`, `"9"` |
| click / icon | `"click"`, `"geetest_click"`, `"icon"` |
| slide | `"slide"`, `"geetest_slide"` |
| match | `"match"`, `"geetest_match"` |
| winlinze | `"winlinze"`, `"geetest_winlinze"` |

### OCR / imagem para texto

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

| Opção | Tipo | Observações |
|---|---|---|
| `module` | `"common"` \| `"mtcaptcha"` \| `"bls"` \| `"morocco"` | Padrão `"common"` |
| `numeric` | `boolean` | Somente dígitos (ativado automaticamente para `"bls"`) |
| `caseSensitive` | `boolean` | Preserva maiúsculas e minúsculas |
| `minLength` / `maxLength` | `number` | Limites de comprimento |

### TikTok

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

Retorno: `click` fica em `typedSolution.click`; `whirl`/`slide` retornam `typedSolution.slide.x`.

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

### Binance

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

Retorno: `grid` fica em `typedSolution.grid.objects`; `slide` retorna `typedSolution.slide.x`.

`type` aceita `"grid"`/`"binance_grid"` e `"slide"`/`"binance_slide"`.

### AWS WAF

`solveAwsWaf` recebe argumentos posicionais. A `question` é formatada como `"type:category:target"`.

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

Retorno: os índices dos blocos selecionados ficam em `typedSolution.grid.objects`.

### Imagem slide (local, sem IA)

Detecta o deslocamento do slide localmente usando detecção de contornos. Aceita uma imagem combinada ou `[background, piece]`.

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

Retorno: o deslocamento do slide em pixels em `typedSolution.slide.x`.

### Métodos de token (automação de navegador)

Esses métodos enviam uma tarefa e fazem polling internamente até que um token seja retornado (até o timeout de polling, 120 s por padrão).

<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>

Retorno: o token fica no mapa `solution` da resposta (por exemplo `result.solution.token` ou `result.solution.gRecaptchaResponse`, conforme o captcha).

---

## Uso com TypeScript

O SDK exporta tipos para cada objeto de opções e resposta. Importe-os com `import type`.

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

**Tipos exportados**

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

`ImageInput` é `Uint8Array | Buffer | string`.

---

## Suporte a proxy

Os métodos de token / automação de navegador aceitam uma string opcional `proxy` no formato `http://user:pass@host:port`:

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

> [!WARNING]
> `solveCloudflare` **sempre exige** um proxy — o campo `proxy` é obrigatório nesse método. Os demais métodos de token rodam sem proxy quando `proxy` é omitido.

Para o hCaptcha corporativo, você também pode passar `metadata` (`rqdata`, `rqtoken`, `fingerprint`) para `solvePopularCaptchaToken`.

---

## Configuração

Passe um objeto de opções como segundo argumento do construtor. Apenas as opções abaixo são suportadas.

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

| Opção | Tipo | Padrão | Descrição |
|---|---|---|---|
| `transport` | `"grpc"` \| `"connect"` \| `"http"` | `"grpc"` | Protocolo de transporte (veja a tabela abaixo) |
| `timeout` / `timeoutMs` | `number` | `30000` por chamada | Timeout da requisição; `timeout` também limita o tempo de espera do polling |
| `pollingInterval` | `number` | `2000` | Frequência com que as tarefas de token são consultadas |
| `url` / `baseUrl` | `string` | por transporte | Substitui o endpoint da API |

**Transportes**

| Transporte | Ambientes | Protocolo |
|---|---|---|
| `grpc` | Somente Node.js | gRPC binário sobre HTTP/2 — menor latência, envia imagens como binário bruto |
| `connect` | Node.js e navegadores | ConnectRPC sobre `fetch` |
| `http` | Node.js e navegadores | REST/JSON simples sobre `fetch` |

> [!TIP]
> No navegador, use `connect` (recomendado) ou `http`. O gRPC nativo requer Node.js. Com `connect`/`http`, as imagens são codificadas automaticamente em base64 antes do envio; com `grpc`, são enviadas como binário bruto, sem overhead.

---

## Tratamento de erros

Todas as falhas no nível da API lançam um `SonicError`, que estende o `Error` nativo. Ele carrega um `errorId` numérico e define `name` com o nome do erro correspondente.

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

<ErrorIdTable />

> [!TIP]
> Erros transitórios de gRPC são repetidos automaticamente com backoff exponencial (até 3 tentativas), então normalmente você só precisa tratar os casos de `SonicError` acima.

---

## Funções auxiliares da conta

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

Métodos de tarefa de baixo nível estão disponíveis se você precisar de controle direto sobre o envio e o polling:

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

---

## Solução de problemas

**`require is not defined` / `Cannot use import statement outside a module`** — o pacote é somente ESM. Use `import` em um projeto ESM, ou `await import("captchasonic")` a partir de CommonJS. Veja [Instalação](#installation).

**O transporte `grpc` falha no navegador** — o gRPC nativo é exclusivo do Node.js. Troque para `transport: "connect"` ou `transport: "http"`.

**`InvalidApiKeyError` em todas as chamadas** — confirme que a chave é passada como primeiro argumento do construtor e não está `undefined` por acidente (por exemplo, uma variável de ambiente ausente).

**Método de token expira por timeout** — tarefas de token fazem polling por até `timeout` ms (padrão 120000). Aumente `timeout` e verifique se `websiteURL` / `websiteKey` correspondem à página alvo. Para o Cloudflare, é obrigatório um `proxy` válido.

**Imagens por caminho de arquivo não carregam** — caminhos de arquivo em string são lidos de forma síncrona e são exclusivos do Node.js; no navegador, passe um `Uint8Array`.

---

## Recursos

*   [Pacote no npm](https://www.npmjs.com/package/captchasonic)
*   [Referência da API](/docs/api)
*   [Dashboard e documentação da CaptchaSonic](https://captchasonic.com)
