SDK Node.js CaptchaSonic (`captchasonic`) adalah pustaka modern, berbasis Promise, dan mengutamakan TypeScript untuk menyelesaikan CAPTCHA dalam skala besar. Setiap metode mengembalikan `Promise`, menyertakan definisi tipe lengkap, dan berjalan di atas tiga transport yang dapat dipertukarkan — **gRPC** native (tercepat, hanya Node.js), **ConnectRPC** (berjalan di Node.js dan browser), dan **HTTP/JSON** biasa. Error sementara dicoba ulang secara otomatis dengan exponential backoff.

SDK ini berjalan di **Node.js ≥ 18** dan browser modern, serta kompatibel dengan Express, Fastify, Next.js, React, Vue, dan Vite.

---

## Instalasi

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

**Persyaratan**

| Persyaratan | Catatan |
|---|---|
| Node.js | ≥ 18.0.0 (wajib untuk transport `grpc`) |
| Format modul | ES Module — paket ini menyertakan `"type": "module"` |
| Browser | Browser modern apa pun dengan `fetch`; gunakan transport `connect` atau `http` |

Paket ini dipublikasikan **hanya ESM**. Dalam proyek ESM (`"type": "module"` di `package.json`, atau file `.mjs`), impor langsung:

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

Dari file CommonJS, muat dengan `import()` dinamis:

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

> [!TIP]
> Jika Anda menggunakan TypeScript, atur `"module": "NodeNext"` (atau `"ESNext"`) dan `"moduleResolution": "NodeNext"` di `tsconfig.json` agar definisi tipe bawaan dapat di-resolve dengan benar.

---

## Autentikasi

Buat API key di [dashboard CaptchaSonic](https://captchasonic.com) lalu berikan sebagai argumen pertama ke constructor:

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

Jangan pernah menulis key langsung di kode sumber (source control). Baca key dari environment:

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

---

## Mulai Cepat

Setiap jenis captcha memiliki helper `solve*` khusus yang mengirim task dan mengembalikan hasilnya. Tidak ada langkah polling terpisah untuk task gambar — SDK menanganinya untuk Anda.

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

> **Mengembalikan:** metode gambar menghasilkan hasil yang jawabannya berada di `typedSolution` (mis. `typedSolution.grid.objects`, indeks tile yang dipilih); metode token mengembalikan token di dalam map `solution`.

> [!TIP]
> Metode berbasis token (Turnstile, Cloudflare, reCAPTCHA v2/v3 token, popular-captcha token) mengirim task otomasi browser dan melakukan polling secara internal hingga token siap — secara default hingga 120 detik.

---

## Jenis CAPTCHA yang Didukung

Semua metode gambar menerima satu objek opsi bertipe. Gambar dapat berupa `Uint8Array`, `Buffer` Node, atau path file berupa string (path file hanya untuk Node.js).

### reCAPTCHA v2 (gambar)

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

### PopularCaptcha (gambar gaya hCaptcha)

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

### GeeTest

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

Mengembalikan: tipe grid/click masuk ke `typedSolution.grid.objects` (atau `typedSolution.click`); slide mengembalikan `typedSolution.slide.x`.

Alias `type` yang diterima:

| Kanonik | 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 / gambar-ke-teks

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

| Opsi | Tipe | Catatan |
|---|---|---|
| `module` | `"common"` \| `"mtcaptcha"` \| `"bls"` \| `"morocco"` | Default `"common"` |
| `numeric` | `boolean` | Hanya digit (otomatis aktif untuk `"bls"`) |
| `caseSensitive` | `boolean` | Pertahankan huruf besar/kecil |
| `minLength` / `maxLength` | `number` | Batas panjang |

### TikTok

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

Mengembalikan: `click` masuk ke `typedSolution.click`; `whirl`/`slide` mengembalikan `typedSolution.slide.x`.

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

### Binance

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

Mengembalikan: `grid` masuk ke `typedSolution.grid.objects`; `slide` mengembalikan `typedSolution.slide.x`.

`type` menerima `"grid"`/`"binance_grid"` dan `"slide"`/`"binance_slide"`.

### AWS WAF

`solveAwsWaf` menerima argumen posisional. `question` diformat sebagai `"type:category:target"`.

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

Mengembalikan: indeks tile yang dipilih di `typedSolution.grid.objects`.

### Gambar slide (lokal, tanpa AI)

Mendeteksi offset slide secara lokal menggunakan deteksi kontur. Menerima satu gambar gabungan, atau `[background, piece]`.

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

Mengembalikan: offset slide dalam piksel di `typedSolution.slide.x`.

### Metode token (otomasi browser)

Metode ini mengirim task dan melakukan polling secara internal hingga token dikembalikan (hingga batas waktu polling, secara default 120 detik).

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

Mengembalikan: token ada di map `solution` dari respons (misalnya `result.solution.token` atau `result.solution.gRecaptchaResponse`, tergantung captcha).

---

## Penggunaan TypeScript

SDK mengekspor tipe untuk setiap objek opsi dan respons. Impor dengan `import type`.

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

**Tipe yang diekspor**

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

`ImageInput` adalah `Uint8Array | Buffer | string`.

---

## Dukungan Proxy

Metode token / otomasi browser menerima string `proxy` opsional dengan format `http://user:pass@host:port`:

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

> [!WARNING]
> `solveCloudflare` **selalu memerlukan** proxy — field `proxy` wajib untuk metode tersebut. Metode token lainnya berjalan tanpa proxy jika `proxy` dihilangkan.

Untuk hCaptcha enterprise, Anda juga dapat meneruskan `metadata` (`rqdata`, `rqtoken`, `fingerprint`) ke `solvePopularCaptchaToken`.

---

## Konfigurasi

Berikan objek opsi sebagai argumen kedua constructor. Hanya opsi di bawah ini yang didukung.

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

| Opsi | Tipe | Default | Deskripsi |
|---|---|---|---|
| `transport` | `"grpc"` \| `"connect"` \| `"http"` | `"grpc"` | Protokol kabel (lihat tabel di bawah) |
| `timeout` / `timeoutMs` | `number` | `30000` per panggilan | Batas waktu permintaan; `timeout` juga membatasi waktu tunggu polling |
| `pollingInterval` | `number` | `2000` | Seberapa sering task token di-polling |
| `url` / `baseUrl` | `string` | per transport | Mengganti endpoint API |

**Transport**

| Transport | Lingkungan | Protokol |
|---|---|---|
| `grpc` | Hanya Node.js | gRPC biner di atas HTTP/2 — latensi terendah, mengirim gambar sebagai biner mentah |
| `connect` | Node.js dan browser | ConnectRPC di atas `fetch` |
| `http` | Node.js dan browser | REST/JSON biasa di atas `fetch` |

> [!TIP]
> Di browser gunakan `connect` (direkomendasikan) atau `http`. gRPC native memerlukan Node.js. Dengan `connect`/`http`, gambar otomatis di-encode ke base64 sebelum dikirim; dengan `grpc` gambar dikirim sebagai biner mentah tanpa overhead.

---

## Penanganan Error

Semua kegagalan tingkat API melempar `SonicError`, yang merupakan turunan dari `Error` bawaan. Error ini membawa `errorId` numerik dan mengatur `name` sesuai nama error yang sesuai.

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

<ErrorIdTable />

> [!TIP]
> Error gRPC sementara dicoba ulang secara otomatis dengan exponential backoff (hingga 3 percobaan), sehingga biasanya Anda hanya perlu menangani kasus `SonicError` di atas.

---

## Helper Akun

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

Metode task tingkat rendah tersedia jika Anda memerlukan kontrol langsung atas pengiriman dan polling:

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

---

## Pemecahan Masalah

**`require is not defined` / `Cannot use import statement outside a module`** — paket ini hanya ESM. Gunakan `import` di proyek ESM, atau `await import("captchasonic")` dari CommonJS. Lihat [Instalasi](#installation).

**Transport `grpc` gagal di browser** — gRPC native hanya untuk Node.js. Ganti ke `transport: "connect"` atau `transport: "http"`.

**`InvalidApiKeyError` pada setiap panggilan** — pastikan key diberikan sebagai argumen pertama constructor dan bukan `undefined` secara tidak sengaja (mis. variabel env yang belum diatur).

**Metode token kehabisan waktu** — task token di-polling hingga `timeout` ms (default 120000). Tingkatkan `timeout` dan pastikan `websiteURL` / `websiteKey` sesuai dengan halaman target. Untuk Cloudflare, `proxy` yang valid wajib diisi.

**Gambar dengan path file tidak termuat** — path file berupa string dibaca secara sinkron dan hanya untuk Node.js; di browser berikan `Uint8Array` sebagai gantinya.

---

## Sumber Daya

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