Le SDK Node.js de CaptchaSonic (`captchasonic`) est une bibliothèque moderne, basée sur les Promises et orientée TypeScript, pour résoudre des CAPTCHA à grande échelle. Chaque méthode renvoie une `Promise`, fournit des définitions de types complètes et fonctionne avec trois transports interchangeables : **gRPC** natif (le plus rapide, Node.js uniquement), **ConnectRPC** (fonctionne dans Node.js et les navigateurs) et **HTTP/JSON** simple. Les erreurs transitoires sont relancées automatiquement avec un backoff exponentiel.

Il fonctionne avec **Node.js ≥ 18** et les navigateurs modernes, et est compatible avec Express, Fastify, Next.js, React, Vue et Vite.

---

## Installation

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

**Prérequis**

| Prérequis | Remarques |
|---|---|
| Node.js | ≥ 18.0.0 (requis pour le transport `grpc`) |
| Format de module | ES Module — le package embarque `"type": "module"` |
| Navigateur | Tout navigateur moderne disposant de `fetch` ; utilisez le transport `connect` ou `http` |

Le package est publié **uniquement en ESM**. Dans un projet ESM (`"type": "module"` dans votre `package.json`, ou un fichier `.mjs`), importez-le directement :

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

Depuis un fichier CommonJS, chargez-le avec un `import()` dynamique :

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

> [!TIP]
> Si vous utilisez TypeScript, définissez `"module": "NodeNext"` (ou `"ESNext"`) et `"moduleResolution": "NodeNext"` dans `tsconfig.json` pour que les définitions de types incluses se résolvent correctement.

---

## Authentification

Créez une clé API dans le [tableau de bord CaptchaSonic](https://captchasonic.com) et passez-la en premier argument du constructeur :

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

Ne codez jamais les clés en dur dans le contrôle de version. Lisez plutôt la clé depuis l'environnement :

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

---

## Démarrage rapide

Chaque type de CAPTCHA dispose d'une fonction `solve*` dédiée qui soumet la tâche et se résout avec le résultat. Il n'y a pas d'étape d'interrogation séparée pour les tâches d'image : le SDK s'en charge.

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

> **Retourne :** les méthodes d'image se résolvent avec un résultat dont la réponse se trouve sous `typedSolution` (par exemple `typedSolution.grid.objects`, les indices des tuiles sélectionnées) ; les méthodes de jeton renvoient le jeton dans la map `solution`.

> [!TIP]
> Les méthodes à base de jeton (Turnstile, Cloudflare, reCAPTCHA v2/v3 token, jeton popular-captcha) soumettent une tâche d'automatisation de navigateur et interrogent le résultat en interne jusqu'à ce qu'un jeton soit prêt — par défaut pendant 120 secondes au maximum.

---

## Types de CAPTCHA pris en charge

Toutes les méthodes d'image acceptent un unique objet d'options typé. Les images peuvent être des `Uint8Array`, des `Buffer` Node ou un chemin de fichier sous forme de chaîne (les chemins de fichiers ne sont disponibles que dans Node.js).

### reCAPTCHA v2 (image)

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

### PopularCaptcha (image de style hCaptcha)

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

### GeeTest

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

Retourne : les types grid/click arrivent dans `typedSolution.grid.objects` (ou `typedSolution.click`) ; slide renvoie `typedSolution.slide.x`.

Alias de `type` acceptés :

| Forme canonique | Alias |
|---|---|
| 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 / image vers texte

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

| Option | Type | Remarques |
|---|---|---|
| `module` | `"common"` \| `"mtcaptcha"` \| `"bls"` \| `"morocco"` | Par défaut `"common"` |
| `numeric` | `boolean` | Chiffres uniquement (réglé automatiquement pour `"bls"`) |
| `caseSensitive` | `boolean` | Conserve la casse des lettres |
| `minLength` / `maxLength` | `number` | Bornes de longueur |

### TikTok

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

Retourne : `click` arrive dans `typedSolution.click` ; `whirl`/`slide` renvoient `typedSolution.slide.x`.

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

### Binance

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

Retourne : `grid` arrive dans `typedSolution.grid.objects` ; `slide` renvoie `typedSolution.slide.x`.

`type` accepte `"grid"`/`"binance_grid"` et `"slide"`/`"binance_slide"`.

### AWS WAF

`solveAwsWaf` prend des arguments positionnels. La `question` est formatée comme `"type:category:target"`.

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

Retourne : les indices des tuiles sélectionnées dans `typedSolution.grid.objects`.

### Image de glissement (locale, sans IA)

Détecte localement le décalage du curseur par détection de contours. Accepte une image combinée unique, ou `[background, piece]`.

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

Retourne : le décalage en pixels dans `typedSolution.slide.x`.

### Méthodes à jeton (automatisation du navigateur)

Elles soumettent une tâche et interrogent le résultat en interne jusqu'à obtenir un jeton (jusqu'au délai d'interrogation, 120 s par défaut).

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

Retourne : le jeton dans la map `solution` de la réponse (par exemple `result.solution.token` ou `result.solution.gRecaptchaResponse`, selon le CAPTCHA).

---

## Utilisation de TypeScript

Le SDK exporte les types de chaque objet d'options et de réponse. Importez-les avec `import type`.

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

**Types exportés**

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

`ImageInput` est `Uint8Array | Buffer | string`.

---

## Prise en charge des proxys

Les méthodes de jeton / d'automatisation de navigateur acceptent une chaîne `proxy` optionnelle au format `http://user:pass@host:port` :

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

> [!WARNING]
> `solveCloudflare` **exige toujours** un proxy — le champ `proxy` est obligatoire pour cette méthode. Les autres méthodes de jeton s'exécutent sans proxy lorsque `proxy` est omis.

Pour le hCaptcha entreprise, vous pouvez aussi passer `metadata` (`rqdata`, `rqtoken`, `fingerprint`) à `solvePopularCaptchaToken`.

---

## Configuration

Passez un objet d'options comme second argument du constructeur. Seules les options ci-dessous sont prises en charge.

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

| Option | Type | Défaut | Description |
|---|---|---|---|
| `transport` | `"grpc"` \| `"connect"` \| `"http"` | `"grpc"` | Protocole de transport (voir le tableau ci-dessous) |
| `timeout` / `timeoutMs` | `number` | `30000` par appel | Délai d'expiration de la requête ; `timeout` limite aussi l'attente d'interrogation |
| `pollingInterval` | `number` | `2000` | Fréquence d'interrogation des tâches à jeton |
| `url` / `baseUrl` | `string` | selon le transport | Remplace le point d'accès de l'API |

**Transports**

| Transport | Environnements | Protocole |
|---|---|---|
| `grpc` | Node.js uniquement | gRPC binaire sur HTTP/2 — latence la plus faible, envoie les images en binaire brut |
| `connect` | Node.js et navigateurs | ConnectRPC sur `fetch` |
| `http` | Node.js et navigateurs | REST/JSON simple sur `fetch` |

> [!TIP]
> Dans le navigateur, utilisez `connect` (recommandé) ou `http`. Le gRPC natif nécessite Node.js. Avec `connect`/`http`, les images sont automatiquement encodées en base64 avant l'envoi ; avec `grpc`, elles sont envoyées en binaire brut, sans surcharge.

---

## Gestion des erreurs

Toutes les erreurs au niveau de l'API lèvent une `SonicError`, qui étend la classe `Error` native. Elle porte un `errorId` numérique et définit `name` avec le nom d'erreur correspondant.

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

<ErrorIdTable />

> [!TIP]
> Les erreurs gRPC transitoires sont relancées automatiquement avec un backoff exponentiel (jusqu'à 3 tentatives) ; vous n'avez donc généralement qu'à gérer les cas `SonicError` ci-dessus.

---

## Fonctions utilitaires de compte

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

Des méthodes de tâche de bas niveau sont disponibles si vous souhaitez un contrôle direct sur la soumission et l'interrogation :

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

---

## Dépannage

**`require is not defined` / `Cannot use import statement outside a module`** — le package est uniquement ESM. Utilisez `import` dans un projet ESM, ou `await import("captchasonic")` depuis CommonJS. Voir [Installation](#installation).

**Le transport `grpc` échoue dans le navigateur** — le gRPC natif ne fonctionne que dans Node.js. Passez à `transport: "connect"` ou `transport: "http"`.

**`InvalidApiKeyError` à chaque appel** — vérifiez que la clé est passée en premier argument du constructeur et qu'elle n'est pas accidentellement `undefined` (par exemple une variable d'environnement absente).

**La méthode à jeton expire** — les tâches à jeton interrogent jusqu'à `timeout` ms (120000 par défaut). Augmentez `timeout` et vérifiez que `websiteURL` / `websiteKey` correspondent à la page cible. Pour Cloudflare, un `proxy` valide est obligatoire.

**Les images au chemin de fichier ne se chargent pas** — les chemins de fichiers sous forme de chaîne sont lus de façon synchrone et ne fonctionnent que dans Node.js ; dans le navigateur, passez plutôt un `Uint8Array`.

---

## Ressources

*   [Package npm](https://www.npmjs.com/package/captchasonic)
*   [Référence de l'API](/docs/api)
*   [Tableau de bord et documentation CaptchaSonic](https://captchasonic.com)
