Das CaptchaSonic-Node.js-SDK (`captchasonic`) ist eine moderne, Promise-basierte, TypeScript-first-Bibliothek zum Lösen von CAPTCHAs in großem Maßstab. Jede Methode gibt ein `Promise` zurück, bringt vollständige Typdefinitionen mit und läuft über drei austauschbare Transporte — natives **gRPC** (am schnellsten, nur Node.js), **ConnectRPC** (funktioniert in Node.js und Browsern) und einfaches **HTTP/JSON**. Vorübergehende Fehler werden automatisch mit exponentiellem Backoff erneut versucht.

Es funktioniert in **Node.js ≥ 18** und in modernen Browsern und ist kompatibel mit Express, Fastify, Next.js, React, Vue und Vite.

---

## Installation

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

**Voraussetzungen**

| Voraussetzung | Hinweise |
|---|---|
| Node.js | ≥ 18.0.0 (erforderlich für den `grpc`-Transport) |
| Modulformat | ES-Modul — das Paket wird mit `"type": "module"` ausgeliefert |
| Browser | Jeder moderne Browser mit `fetch`; verwenden Sie den Transport `connect` oder `http` |

Das Paket wird **nur als ESM** veröffentlicht. In einem ESM-Projekt (`"type": "module"` in Ihrer `package.json` oder eine `.mjs`-Datei) importieren Sie es direkt:

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

Aus einer CommonJS-Datei laden Sie es über einen dynamischen `import()`:

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

> [!TIP]
> Wenn Sie TypeScript verwenden, setzen Sie in `tsconfig.json` `"module": "NodeNext"` (oder `"ESNext"`) und `"moduleResolution": "NodeNext"`, damit die mitgelieferten Typdefinitionen korrekt aufgelöst werden.

---

## Authentifizierung

Erstellen Sie einen API-Schlüssel im [CaptchaSonic-Dashboard](https://captchasonic.com) und übergeben Sie ihn als erstes Argument an den Konstruktor:

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

Hinterlegen Sie Schlüssel niemals fest im Quellcode oder in der Versionsverwaltung. Lesen Sie den Schlüssel stattdessen aus der Umgebung:

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

---

## Schnellstart

Jeder CAPTCHA-Typ hat eine eigene `solve*`-Hilfsfunktion, die den Task übermittelt und mit dem Ergebnis aufgelöst wird. Bei Bild-Tasks ist kein separater Abfrageschritt nötig — das SDK übernimmt dies für Sie.

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

> **Rückgabe:** Bildmethoden liefern ein Ergebnis, dessen Antwort unter `typedSolution` liegt (z. B. `typedSolution.grid.objects`, die gewählten Kachel-Indizes); Token-Methoden geben das Token in der `solution`-Map zurück.

> [!TIP]
> Token-basierte Methoden (Turnstile, Cloudflare, reCAPTCHA v2/v3-Token, PopularCaptcha-Token) übermitteln einen Browser-Automatisierungs-Task und fragen intern ab, bis ein Token bereitsteht — standardmäßig bis zu 120 Sekunden.

---

## Unterstützte CAPTCHA-Typen

Alle Bildmethoden nehmen ein einziges typisiertes Optionsobjekt entgegen. Bilder können `Uint8Array`, Node-`Buffer` oder ein String-Dateipfad sein (Dateipfade gibt es nur in Node.js).

### reCAPTCHA v2 (Bild)

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

### PopularCaptcha (hCaptcha-artiges Bild)

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

### GeeTest

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

Rückgabe: Grid- und Click-Typen landen in `typedSolution.grid.objects` (bzw. `typedSolution.click`); Slide liefert `typedSolution.slide.x`.

Akzeptierte `type`-Aliasse:

| Kanonisch | Aliasse |
|---|---|
| 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 / Bild-zu-Text

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

| Option | Typ | Hinweise |
|---|---|---|
| `module` | `"common"` \| `"mtcaptcha"` \| `"bls"` \| `"morocco"` | Standard `"common"` |
| `numeric` | `boolean` | Nur Ziffern (wird für `"bls"` automatisch gesetzt) |
| `caseSensitive` | `boolean` | Groß-/Kleinschreibung beibehalten |
| `minLength` / `maxLength` | `number` | Längengrenzen |

### TikTok

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

Rückgabe: `click` landet in `typedSolution.click`; `whirl`/`slide` liefern `typedSolution.slide.x`.

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

### Binance

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

Rückgabe: `grid` landet in `typedSolution.grid.objects`; `slide` liefert `typedSolution.slide.x`.

`type` akzeptiert `"grid"`/`"binance_grid"` und `"slide"`/`"binance_slide"`.

### AWS WAF

`solveAwsWaf` nimmt Positionsargumente entgegen. Die `question` wird im Format `"type:category:target"` angegeben.

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

Rückgabe: die gewählten Kachel-Indizes in `typedSolution.grid.objects`.

### Slide-Bild (lokal, ohne KI)

Ermittelt den Slide-Versatz lokal per Konturerkennung. Akzeptiert ein kombiniertes Bild oder `[background, piece]`.

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

Rückgabe: der Slide-Versatz in Pixeln unter `typedSolution.slide.x`.

### Token-Methoden (Browser-Automatisierung)

Diese übermitteln einen Task und fragen intern ab, bis ein Token zurückgegeben wird (bis zum Abfrage-Timeout, standardmäßig 120 s).

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

Rückgabe: das Token in der `solution`-Map der Antwort (z. B. `result.solution.token` oder `result.solution.gRecaptchaResponse`, je nach CAPTCHA).

---

## TypeScript-Verwendung

Das SDK exportiert Typen für jedes Optionsobjekt und jede Antwort. Importieren Sie sie mit `import type`.

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

**Exportierte Typen**

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

`ImageInput` ist `Uint8Array | Buffer | string`.

---

## Proxy-Unterstützung

Token-/Browser-Automatisierungsmethoden akzeptieren einen optionalen `proxy`-String im Format `http://user:pass@host:port`:

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

> [!WARNING]
> `solveCloudflare` **benötigt immer** einen Proxy — das Feld `proxy` ist für diese Methode Pflicht. Andere Token-Methoden laufen ohne Proxy, wenn `proxy` weggelassen wird.

Für Enterprise-hCaptcha können Sie zusätzlich `metadata` (`rqdata`, `rqtoken`, `fingerprint`) an `solvePopularCaptchaToken` übergeben.

---

## Konfiguration

Übergeben Sie ein Optionsobjekt als zweites Argument des Konstruktors. Es werden nur die unten genannten Optionen unterstützt.

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

| Option | Typ | Standard | Beschreibung |
|---|---|---|---|
| `transport` | `"grpc"` \| `"connect"` \| `"http"` | `"grpc"` | Wire-Protokoll (siehe Tabelle unten) |
| `timeout` / `timeoutMs` | `number` | `30000` pro Aufruf | Request-Timeout; `timeout` begrenzt auch die Wartezeit beim Abfragen |
| `pollingInterval` | `number` | `2000` | Wie oft Token-Tasks abgefragt werden |
| `url` / `baseUrl` | `string` | je Transport | Überschreibt den API-Endpunkt |

**Transporte**

| Transport | Umgebungen | Protokoll |
|---|---|---|
| `grpc` | nur Node.js | gRPC-Binärprotokoll über HTTP/2 — geringste Latenz, sendet Bilder als rohe Binärdaten |
| `connect` | Node.js und Browser | ConnectRPC über `fetch` |
| `http` | Node.js und Browser | Einfaches REST/JSON über `fetch` |

> [!TIP]
> Im Browser verwenden Sie `connect` (empfohlen) oder `http`. Natives gRPC setzt Node.js voraus. Bei `connect`/`http` werden Bilder vor dem Senden automatisch in Base64 kodiert; bei `grpc` werden sie als rohe Binärdaten ohne Overhead gesendet.

---

## Fehlerbehandlung

Alle API-seitigen Fehler werfen eine `SonicError`, die von dem eingebauten `Error` erbt. Sie trägt einen numerischen `errorId` und setzt `name` auf den passenden Fehlernamen.

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

<ErrorIdTable />

> [!TIP]
> Vorübergehende gRPC-Fehler werden automatisch mit exponentiellem Backoff erneut versucht (bis zu 3 Versuche), sodass Sie in der Regel nur die oben genannten `SonicError`-Fälle behandeln müssen.

---

## Konto-Hilfsfunktionen

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

Low-Level-Task-Methoden stehen zur Verfügung, wenn Sie die Übermittlung und Abfrage direkt steuern möchten:

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

---

## Fehlersuche

**`require is not defined` / `Cannot use import statement outside a module`** — das Paket ist nur als ESM verfügbar. Verwenden Sie `import` in einem ESM-Projekt oder `await import("captchasonic")` aus CommonJS. Siehe [Installation](#installation).

**`grpc`-Transport schlägt im Browser fehl** — natives gRPC funktioniert nur in Node.js. Wechseln Sie auf `transport: "connect"` oder `transport: "http"`.

**`InvalidApiKeyError` bei jedem Aufruf** — prüfen Sie, ob der Schlüssel als erstes Konstruktorargument übergeben wird und nicht versehentlich `undefined` ist (z. B. wegen einer fehlenden Umgebungsvariable).

**Token-Methode läuft in Timeout** — Token-Tasks fragen bis zu `timeout` ms ab (Standard 120000). Erhöhen Sie `timeout` und prüfen Sie, ob `websiteURL` / `websiteKey` zur Zielseite passen. Für Cloudflare ist ein gültiger `proxy` erforderlich.

**Bilder aus Dateipfaden werden nicht geladen** — String-Dateipfade werden synchron gelesen und sind nur in Node.js verfügbar; im Browser übergeben Sie stattdessen ein `Uint8Array`.

---

## Ressourcen

*   [npm-Paket](https://www.npmjs.com/package/captchasonic)
*   [API-Referenz](/docs/api)
*   [CaptchaSonic-Dashboard & Dokumentation](https://captchasonic.com)
