CaptchaSonic Node.js SDK'sı (`captchasonic`), CAPTCHA'ları büyük ölçekte çözmek için modern, Promise tabanlı ve TypeScript öncelikli bir kütüphanedir. Her metot bir `Promise` döndürür, tam tip tanımları içerir ve birbiriyle değiştirilebilir üç taşıma üzerinden çalışır: yerel **gRPC** (en hızlı, yalnızca Node.js), **ConnectRPC** (Node.js ve tarayıcılarda çalışır) ve düz **HTTP/JSON**. Geçici hatalar üssel geri çekilmeyle (exponential backoff) otomatik olarak yeniden denenir.

**Node.js ≥ 18** ve modern tarayıcılarda çalışır; Express, Fastify, Next.js, React, Vue ve Vite ile uyumludur.

---

## Kurulum

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

**Gereksinimler**

| Gereksinim | Notlar |
|---|---|
| Node.js | ≥ 18.0.0 (`grpc` taşıması için gerekli) |
| Modül biçimi | ES Module — paket `"type": "module"` ile yayımlanır |
| Tarayıcı | `fetch` destekleyen her modern tarayıcı; `connect` veya `http` taşımasını kullanın |

Paket yalnızca **ESM** olarak yayımlanır. Bir ESM projesinde (`package.json` içinde `"type": "module"` ya da bir `.mjs` dosyası) doğrudan içe aktarın:

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

CommonJS dosyasından ise dinamik `import()` ile yükleyin:

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

> [!TIP]
> TypeScript kullanıyorsanız, paketle gelen tip tanımlarının doğru çözümlenmesi için `tsconfig.json` içinde `"module": "NodeNext"` (veya `"ESNext"`) ve `"moduleResolution": "NodeNext"` ayarlayın.

---

## Kimlik Doğrulama

[CaptchaSonic panelinden](https://captchasonic.com) bir API anahtarı oluşturun ve bunu kurucunun ilk argümanı olarak geçin:

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

Anahtarları kaynak kontrolüne asla sabit kodlamayın. Anahtarı bunun yerine ortamdan okuyun:

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

---

## Hızlı Başlangıç

Her CAPTCHA türünün, görevi gönderen ve sonuçla çözülen özel bir `solve*` yardımcısı vardır. Görsel görevleri için ayrı bir sorgulama adımı yoktur — SDK bunu sizin için yönetir.

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

> **Dönüş:** görsel metotlar, yanıtı `typedSolution` altında bulunan bir sonuç döndürür (ör. `typedSolution.grid.objects`, seçilen kare indeksleri); token metotları ise token'ı `solution` haritasında döndürür.

> [!TIP]
> Token tabanlı metotlar (Turnstile, Cloudflare, reCAPTCHA v2/v3 token, popular-captcha token) bir tarayıcı otomasyon görevi gönderir ve token hazır olana kadar dahili olarak sorgular — varsayılan olarak 120 saniyeye kadar.

---

## Desteklenen CAPTCHA Türleri

Tüm görsel metotlar tek bir tipli seçenek nesnesi alır. Görseller `Uint8Array`, Node `Buffer` veya metin olarak dosya yolu olabilir (dosya yolları yalnızca Node.js'te geçerlidir).

### reCAPTCHA v2 (görsel)

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

### PopularCaptcha (hCaptcha benzeri görsel)

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

### GeeTest

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

Dönüş: grid/click türleri `typedSolution.grid.objects` (veya `typedSolution.click`) alanına düşer; slide `typedSolution.slide.x` döndürür.

Kabul edilen `type` takma adları:

| Kanonik | Takma adlar |
|---|---|
| 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 / görselden metne

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

| Seçenek | Tür | Notlar |
|---|---|---|
| `module` | `"common"` \| `"mtcaptcha"` \| `"bls"` \| `"morocco"` | Varsayılan `"common"` |
| `numeric` | `boolean` | Yalnızca rakamlar (`"bls"` için otomatik ayarlanır) |
| `caseSensitive` | `boolean` | Harf büyüklüğünü koru |
| `minLength` / `maxLength` | `number` | Uzunluk sınırları |

### TikTok

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

Dönüş: `click` sonucu `typedSolution.click` alanına düşer; `whirl`/`slide` `typedSolution.slide.x` döndürür.

`type` değeri `"click"`/`"tiktok_click"`, `"whirl"`/`"tiktok_whirl"`, `"slide"`/`"tiktok_slide"` kabul eder.

### Binance

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

Dönüş: `grid` sonucu `typedSolution.grid.objects` alanına düşer; `slide` `typedSolution.slide.x` döndürür.

`type` değeri `"grid"`/`"binance_grid"` ve `"slide"`/`"binance_slide"` kabul eder.

### AWS WAF

`solveAwsWaf` konumsal argümanlar alır. `question` `"type:category:target"` biçiminde yazılır.

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

Dönüş: seçilen kare indeksleri `typedSolution.grid.objects` içinde.

### Slide görseli (yerel, yapay zekâsız)

Kontur tespiti kullanarak kaydırma ofsetini yerel olarak algılar. Tek birleşik bir görsel veya `[background, piece]` kabul eder.

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

Dönüş: kaydırma ofseti piksel cinsinden `typedSolution.slide.x` içinde.

### Token metotları (tarayıcı otomasyonu)

Bunlar bir görev gönderir ve token dönene kadar dahili olarak sorgular (varsayılan sorgulama zaman aşımı 120 sn'ye kadar).

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

Dönüş: token, yanıtın `solution` haritasında yer alır (CAPTCHA'ya göre örneğin `result.solution.token` veya `result.solution.gRecaptchaResponse`).

---

## TypeScript Kullanımı

SDK, her seçenek nesnesi ve yanıt için tipleri dışa aktarır. `import type` ile içe aktarın.

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

**Dışa aktarılan tipler**

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

`ImageInput`, `Uint8Array | Buffer | string` tipindedir.

---

## Proxy Desteği

Token / tarayıcı otomasyonu metotları, `http://user:pass@host:port` biçiminde isteğe bağlı bir `proxy` metni kabul eder:

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

> [!WARNING]
> `solveCloudflare` **her zaman** proxy gerektirir — bu metot için `proxy` alanı zorunludur. Diğer token metotları `proxy` atlandığında proxysiz çalışır.

Kurumsal hCaptcha için `solvePopularCaptchaToken` metoduna `metadata` (`rqdata`, `rqtoken`, `fingerprint`) de geçebilirsiniz.

---

## Yapılandırma

Kurucunun ikinci argümanı olarak bir seçenek nesnesi geçin. Yalnızca aşağıdaki seçenekler desteklenir.

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

| Seçenek | Tür | Varsayılan | Açıklama |
|---|---|---|---|
| `transport` | `"grpc"` \| `"connect"` \| `"http"` | `"grpc"` | Tel protokolü (aşağıdaki tabloya bakın) |
| `timeout` / `timeoutMs` | `number` | Çağrı başına `30000` | İstek zaman aşımı; `timeout` sorgu bekleme süresini de sınırlar |
| `pollingInterval` | `number` | `2000` | Token görevlerinin ne sıklıkla sorgulanacağı |
| `url` / `baseUrl` | `string` | taşımaya göre | API uç noktasını geçersiz kıl |

**Taşımalar**

| Taşıma | Ortamlar | Protokol |
|---|---|---|
| `grpc` | Yalnızca Node.js | HTTP/2 üzerinden gRPC ikili — en düşük gecikme, görselleri ham ikili olarak gönderir |
| `connect` | Node.js ve tarayıcılar | `fetch` üzerinden ConnectRPC |
| `http` | Node.js ve tarayıcılar | `fetch` üzerinden düz REST/JSON |

> [!TIP]
> Tarayıcıda `connect` (önerilen) veya `http` kullanın. Yerel gRPC Node.js gerektirir. `connect`/`http` ile görseller gönderilmeden önce otomatik olarak base64'e kodlanır; `grpc` ile ise sıfır ek yükle ham ikili olarak gönderilir.

---

## Hata Yönetimi

API düzeyindeki tüm hatalar, yerleşik `Error` sınıfını genişleten bir `SonicError` fırlatır. Sayısal bir `errorId` taşır ve `name` alanını eşleşen hata adına ayarlar.

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

<ErrorIdTable />

> [!TIP]
> Geçici gRPC hataları üssel geri çekilmeyle otomatik olarak yeniden denenir (en fazla 3 deneme); bu yüzden genellikle yalnızca yukarıdaki `SonicError` durumlarını ele almanız yeterlidir.

---

## Hesap Yardımcıları

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

Gönderim ve sorgulama üzerinde doğrudan kontrole ihtiyacınız varsa düşük seviyeli görev metotları da mevcuttur:

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

---

## Sorun Giderme

**`require is not defined` / `Cannot use import statement outside a module`** — paket yalnızca ESM'dir. ESM projesinde `import` kullanın veya CommonJS'ten `await import("captchasonic")` çağırın. Bkz. [Kurulum](#installation).

**`grpc` taşıması tarayıcıda başarısız oluyor** — yerel gRPC yalnızca Node.js'tedir. `transport: "connect"` veya `transport: "http"` seçeneğine geçin.

**Her çağrıda `InvalidApiKeyError`** — anahtarın kurucunun ilk argümanı olarak geçildiğini ve yanlışlıkla `undefined` olmadığını doğrulayın (ör. eksik bir ortam değişkeni).

**Token metodu zaman aşımına uğruyor** — token görevleri en fazla `timeout` ms (varsayılan 120000) sorgulanır. `timeout` değerini artırın ve `websiteURL` / `websiteKey` değerlerinin hedef sayfayla eşleştiğini doğrulayın. Cloudflare için geçerli bir `proxy` gereklidir.

**Dosya yolu olarak verilen görseller yüklenmiyor** — metin olarak dosya yolları eşzamanlı okunur ve yalnızca Node.js'te çalışır; tarayıcıda bunun yerine bir `Uint8Array` geçin.

---

## Kaynaklar

*   [npm paketi](https://www.npmjs.com/package/captchasonic)
*   [API başvurusu](/docs/api)
*   [CaptchaSonic paneli ve dokümanları](https://captchasonic.com)
