CaptchaSonic Node.js SDK（`captchasonic`）は、大量の CAPTCHA を解決するためのモダンで Promise ベースの TypeScript ファーストのライブラリです。すべてのメソッドは `Promise` を返し、完全な型定義を備えています。3 つの交換可能なトランスポートで動作します。ネイティブの **gRPC**（最速、Node.js のみ）、**ConnectRPC**（Node.js とブラウザの両方で動作）、そして通常の **HTTP/JSON** です。一時的なエラーは、指数バックオフで自動的に再試行されます。

**Node.js ≥ 18** と最新のブラウザで動作し、Express、Fastify、Next.js、React、Vue、Vite と互換性があります。

---

## インストール

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

**要件**

| Requirement | Notes |
|---|---|
| Node.js | ≥ 18.0.0（`grpc` トランスポートに必要） |
| モジュール形式 | ES Module — パッケージは `"type": "module"` を含みます |
| ブラウザ | `fetch` に対応した最新のブラウザ。`connect` または `http` トランスポートを使用してください |

このパッケージは **ESM のみ** で公開されています。ESM のプロジェクト（`package.json` に `"type": "module"` がある、または `.mjs` ファイル）では、直接インポートしてください。

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

CommonJS のファイルからは、動的な `import()` で読み込んでください。

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

> [!TIP]
> TypeScript を使う場合は、同梱の型定義を正しく解決できるように、`tsconfig.json` で `"module": "NodeNext"`（または `"ESNext"`）と `"moduleResolution": "NodeNext"` を設定してください。

---

## 認証

[CaptchaSonic ダッシュボード](https://captchasonic.com) で API キーを作成し、コンストラクターの最初の引数として渡します。

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

キーをソース管理にハードコードしないでください。代わりに環境変数から読み込んでください。

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

---

## クイックスタート

CAPTCHA の種別ごとに専用の `solve*` ヘルパーがあり、タスクを送信して結果を解決します。画像タスクには個別のポーリング手順はありません。SDK が自動で処理します。

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

> **戻り値:** 画像メソッドは、回答が `typedSolution` の下にある結果を返します（例: `typedSolution.grid.objects`、選択したタイルのインデックス）。トークンメソッドは、`solution` のマップにトークンを格納して返します。

> [!TIP]
> トークン型のメソッド（Turnstile、Cloudflare、reCAPTCHA v2/v3 トークン、popular-captcha トークン）は、ブラウザ自動化のタスクを送信し、トークンの準備ができるまで内部でポーリングします。既定では最大 120 秒です。

---

## 対応している CAPTCHA 種別

すべての画像メソッドは、型付きのオプションオブジェクトを 1 つ受け取ります。画像は `Uint8Array`、Node の `Buffer`、または文字列のファイルパスで指定できます（ファイルパスは Node.js でのみ使えます）。

### reCAPTCHA v2（画像）

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

### PopularCaptcha（hCaptcha 形式の画像）

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

### GeeTest

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

戻り値: grid/click の種別は `typedSolution.grid.objects`（または `typedSolution.click`）に入ります。slide は `typedSolution.slide.x` を返します。

受け付ける `type` の別名:

| Canonical | 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 / 画像からテキスト

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

| Option | Type | Notes |
|---|---|---|
| `module` | `"common"` \| `"mtcaptcha"` \| `"bls"` \| `"morocco"` | 既定値は `"common"` |
| `numeric` | `boolean` | 数字のみ（`"bls"` では自動で設定されます） |
| `caseSensitive` | `boolean` | 英字の大文字と小文字を区別します |
| `minLength` / `maxLength` | `number` | 文字列の長さの上限と下限 |

### TikTok

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

戻り値: `click` は `typedSolution.click` に入ります。`whirl` / `slide` は `typedSolution.slide.x` を返します。

`type` には `"click"` / `"tiktok_click"`、`"whirl"` / `"tiktok_whirl"`、`"slide"` / `"tiktok_slide"` を指定できます。

### Binance

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

戻り値: `grid` は `typedSolution.grid.objects` に入ります。`slide` は `typedSolution.slide.x` を返します。

`type` には `"grid"` / `"binance_grid"`、`"slide"` / `"binance_slide"` を指定できます。

### AWS WAF

`solveAwsWaf` は位置引数を受け取ります。`question` は `"type:category:target"` の形式で指定します。

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

戻り値: 選択したタイルのインデックスが `typedSolution.grid.objects` に入ります。

### スライド画像（ローカル処理、AI は使用しません）

輪郭検出を使って、スライドのオフセットをローカルで検出します。1 枚の結合画像、または `[background, piece]` を受け付けます。

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

戻り値: スライドのオフセット（ピクセル）が `typedSolution.slide.x` に入ります。

### トークンメソッド（ブラウザ自動化）

これらはタスクを送信し、トークンが返るまで内部でポーリングします（ポーリングのタイムアウトまで、既定では 120 秒）。

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

戻り値: トークンはレスポンスの `solution` マップに入ります（例: CAPTCHA の種類に応じて `result.solution.token` や `result.solution.gRecaptchaResponse`）。

---

## TypeScript での利用

SDK は、すべてのオプションオブジェクトとレスポンスの型をエクスポートしています。`import type` でインポートしてください。

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

**エクスポートされている型**

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

`ImageInput` は `Uint8Array | Buffer | string` です。

---

## プロキシのサポート

トークン / ブラウザ自動化メソッドは、`http://user:pass@host:port` の形式の任意の `proxy` 文字列を受け付けます。

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

> [!WARNING]
> `solveCloudflare` は **常に** プロキシを必要とします。このメソッドでは `proxy` フィールドは必須です。他のトークンメソッドは、`proxy` を省略するとプロキシなしで実行されます。

エンタープライズ向けの hCaptcha では、`solvePopularCaptchaToken` に `metadata`（`rqdata`、`rqtoken`、`fingerprint`）を渡すこともできます。

---

## 設定

2 番目のコンストラクター引数としてオプションオブジェクトを渡します。以下のオプションのみサポートされています。

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

| Option | Type | Default | Description |
|---|---|---|---|
| `transport` | `"grpc"` \| `"connect"` \| `"http"` | `"grpc"` | 通信プロトコル（下の表を参照） |
| `timeout` / `timeoutMs` | `number` | 呼び出しごとに `30000` | リクエストのタイムアウトです。`timeout` はポーリングの待機時間の上限にもなります。 |
| `pollingInterval` | `number` | `2000` | トークンタスクをポーリングする間隔です。 |
| `url` / `baseUrl` | `string` | トランスポートごとに異なる | API のエンドポイントを上書きします。 |

**トランスポート**

| Transport | Environments | Protocol |
|---|---|---|
| `grpc` | Node.js のみ | HTTP/2 上の gRPC バイナリ — 最も低遅延で、画像を生のバイナリとして送信します |
| `connect` | Node.js とブラウザ | `fetch` 上の ConnectRPC |
| `http` | Node.js とブラウザ | `fetch` 上の通常の REST/JSON |

> [!TIP]
> ブラウザでは `connect`（推奨）または `http` を使ってください。ネイティブの gRPC は Node.js が必要です。`connect` / `http` では、送信前に画像が自動で base64 にエンコードされます。`grpc` では、オーバーヘッドなしで生のバイナリとして送信されます。

---

## エラー処理

API レベルの失敗はすべて `SonicError` を送出します。これは組み込みの `Error` を拡張したものです。数値の `errorId` を持ち、`name` には対応するエラー名が設定されます。

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

<ErrorIdTable />

> [!TIP]
> 一時的な gRPC エラーは、指数バックオフで自動的に再試行されます（最大 3 回）。そのため、通常は上記の `SonicError` のケースだけを扱えば十分です。

---

## アカウントのヘルパー

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

送信とポーリングを直接制御する必要がある場合は、低レベルのタスクメソッドも利用できます。

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

---

## トラブルシューティング

**`require is not defined` / `Cannot use import statement outside a module`** — このパッケージは ESM のみです。ESM のプロジェクトでは `import` を使うか、CommonJS からは `await import("captchasonic")` を使ってください。詳しくは [インストール](#installation) を参照してください。

**ブラウザで `grpc` トランスポートが失敗する** — ネイティブの gRPC は Node.js のみです。`transport: "connect"` または `transport: "http"` に切り替えてください。

**すべての呼び出しで `InvalidApiKeyError` が出る** — キーがコンストラクターの最初の引数として渡されていること、また誤って `undefined` になっていないこと（環境変数の未設定など）を確認してください。

**トークンメソッドがタイムアウトする** — トークンタスクは `timeout` ミリ秒（既定値 120000）までポーリングします。`timeout` を大きくし、`websiteURL` / `websiteKey` が対象ページと一致しているか確認してください。Cloudflare では、有効な `proxy` が必須です。

**ファイルパスの画像が読み込めない** — 文字列のファイルパスは同期的に読み込まれ、Node.js でのみ使えます。ブラウザでは代わりに `Uint8Array` を渡してください。

---

## リソース

*   [npm パッケージ](https://www.npmjs.com/package/captchasonic)
*   [API リファレンス](/docs/api)
*   [CaptchaSonic ダッシュボード & ドキュメント](https://captchasonic.com)
