SDK Node.js của CaptchaSonic (`captchasonic`) là thư viện hiện đại, dựa trên Promise và ưu tiên TypeScript, dùng để giải CAPTCHA ở quy mô lớn. Mọi phương thức đều trả về một `Promise`, đi kèm đầy đủ định nghĩa kiểu, và chạy trên ba phương thức truyền tải có thể thay thế cho nhau — **gRPC** gốc (nhanh nhất, chỉ dành cho Node.js), **ConnectRPC** (chạy được trên Node.js và trình duyệt), và **HTTP/JSON** thuần. Các lỗi tạm thời được tự động thử lại với thời gian chờ tăng dần theo cấp số nhân.

SDK chạy được trên **Node.js ≥ 18** và các trình duyệt hiện đại, tương thích với Express, Fastify, Next.js, React, Vue và Vite.

---

## Cài đặt

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

**Yêu cầu**

| Yêu cầu | Ghi chú |
|---|---|
| Node.js | ≥ 18.0.0 (bắt buộc với truyền tải `grpc`) |
| Định dạng module | ES Module — gói được phát hành với `"type": "module"` |
| Trình duyệt | Mọi trình duyệt hiện đại có `fetch`; dùng truyền tải `connect` hoặc `http` |

Gói này chỉ phát hành dưới dạng **ESM**. Trong dự án ESM (có `"type": "module"` trong `package.json`, hoặc tệp `.mjs`), hãy import trực tiếp:

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

Từ tệp CommonJS, hãy tải bằng `import()` động:

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

> [!TIP]
> Nếu bạn dùng TypeScript, hãy đặt `"module": "NodeNext"` (hoặc `"ESNext"`) và `"moduleResolution": "NodeNext"` trong `tsconfig.json` để các định nghĩa kiểu đi kèm được phân giải đúng.

---

## Xác thực

Tạo API key trong [bảng điều khiển CaptchaSonic](https://captchasonic.com) và truyền nó làm tham số đầu tiên của constructor:

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

Không bao giờ ghi cứng key vào mã nguồn. Hãy đọc key từ biến môi trường:

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

---

## Bắt đầu nhanh

Mỗi loại captcha có một hàm trợ giúp `solve*` riêng, gửi tác vụ và trả về kết quả. Với tác vụ ảnh không cần bước thăm dò riêng — SDK tự xử lý.

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

> **Trả về:** các phương thức ảnh cho kết quả có đáp án nằm dưới `typedSolution` (ví dụ `typedSolution.grid.objects`, các chỉ số ô được chọn); các phương thức token trả về token trong map `solution`.

> [!TIP]
> Các phương thức dựa trên token (Turnstile, Cloudflare, reCAPTCHA v2/v3 token, popular-captcha token) gửi một tác vụ tự động hóa trình duyệt và thăm dò nội bộ cho đến khi token sẵn sàng — mặc định tối đa 120 giây.

---

## Các loại CAPTCHA được hỗ trợ

Mọi phương thức ảnh đều nhận một đối tượng tùy chọn có kiểu duy nhất. Ảnh có thể là `Uint8Array`, `Buffer` của Node, hoặc đường dẫn tệp dạng chuỗi (đường dẫn tệp chỉ dùng được trên Node.js).

### reCAPTCHA v2 (ảnh)

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

### PopularCaptcha (ảnh kiểu hCaptcha)

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

### GeeTest

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

Trả về: các loại grid/click nằm trong `typedSolution.grid.objects` (hoặc `typedSolution.click`); loại slide trả về `typedSolution.slide.x`.

Các bí danh `type` được chấp nhận:

| Chuẩn | Bí danh |
|---|---|
| lưới chín ô | `"nine"`, `"geetest_nine"`, `"9"` |
| click / biểu tượng | `"click"`, `"geetest_click"`, `"icon"` |
| slide | `"slide"`, `"geetest_slide"` |
| match | `"match"`, `"geetest_match"` |
| winlinze | `"winlinze"`, `"geetest_winlinze"` |

### OCR / ảnh sang văn bản

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

| Tùy chọn | Kiểu | Ghi chú |
|---|---|---|
| `module` | `"common"` \| `"mtcaptcha"` \| `"bls"` \| `"morocco"` | Mặc định `"common"` |
| `numeric` | `boolean` | Chỉ chữ số (tự động bật với `"bls"`) |
| `caseSensitive` | `boolean` | Giữ nguyên chữ hoa/thường |
| `minLength` / `maxLength` | `number` | Giới hạn độ dài |

### TikTok

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

Trả về: `click` nằm trong `typedSolution.click`; `whirl`/`slide` trả về `typedSolution.slide.x`.

`type` chấp nhận `"click"`/`"tiktok_click"`, `"whirl"`/`"tiktok_whirl"`, `"slide"`/`"tiktok_slide"`.

### Binance

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

Trả về: `grid` nằm trong `typedSolution.grid.objects`; `slide` trả về `typedSolution.slide.x`.

`type` chấp nhận `"grid"`/`"binance_grid"` và `"slide"`/`"binance_slide"`.

### AWS WAF

`solveAwsWaf` nhận các tham số theo vị trí. `question` có định dạng `"type:category:target"`.

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

Trả về: các chỉ số ô được chọn trong `typedSolution.grid.objects`.

### Ảnh trượt (cục bộ, không dùng AI)

Phát hiện độ lệch trượt cục bộ bằng phát hiện đường viền. Nhận một ảnh ghép hoặc `[background, piece]`.

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

Trả về: độ lệch trượt tính bằng pixel tại `typedSolution.slide.x`.

### Các phương thức token (tự động hóa trình duyệt)

Các phương thức này gửi tác vụ và thăm dò nội bộ cho đến khi nhận được token (tối đa thời gian thăm dò, mặc định 120 giây).

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

Trả về: token nằm trong map `solution` của phản hồi (ví dụ `result.solution.token` hoặc `result.solution.gRecaptchaResponse`, tùy loại captcha).

---

## Sử dụng TypeScript

SDK xuất ra các kiểu cho mọi đối tượng tùy chọn và phản hồi. Hãy import chúng bằng `import type`.

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

**Các kiểu được xuất**

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

`ImageInput` là `Uint8Array | Buffer | string`.

---

## Hỗ trợ proxy

Các phương thức token / tự động hóa trình duyệt nhận một chuỗi `proxy` tùy chọn theo dạng `http://user:pass@host:port`:

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

> [!WARNING]
> `solveCloudflare` **luôn yêu cầu** proxy — trường `proxy` là bắt buộc với phương thức này. Các phương thức token khác chạy không proxy khi bỏ qua `proxy`.

Với hCaptcha doanh nghiệp, bạn cũng có thể truyền `metadata` (`rqdata`, `rqtoken`, `fingerprint`) cho `solvePopularCaptchaToken`.

---

## Cấu hình

Truyền một đối tượng tùy chọn làm tham số thứ hai của constructor. Chỉ các tùy chọn bên dưới được hỗ trợ.

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

| Tùy chọn | Kiểu | Mặc định | Mô tả |
|---|---|---|---|
| `transport` | `"grpc"` \| `"connect"` \| `"http"` | `"grpc"` | Giao thức truyền dữ liệu (xem bảng bên dưới) |
| `timeout` / `timeoutMs` | `number` | `30000` mỗi lệnh gọi | Thời gian chờ yêu cầu; `timeout` cũng giới hạn thời gian chờ thăm dò |
| `pollingInterval` | `number` | `2000` | Tần suất thăm dò các tác vụ token |
| `url` / `baseUrl` | `string` | theo từng phương thức truyền tải | Ghi đè endpoint API |

**Phương thức truyền tải**

| Phương thức truyền tải | Môi trường | Giao thức |
|---|---|---|
| `grpc` | Chỉ Node.js | gRPC nhị phân qua HTTP/2 — độ trễ thấp nhất, gửi ảnh dưới dạng nhị phân thô |
| `connect` | Node.js và trình duyệt | ConnectRPC qua `fetch` |
| `http` | Node.js và trình duyệt | REST/JSON thuần qua `fetch` |

> [!TIP]
> Trong trình duyệt, hãy dùng `connect` (khuyến nghị) hoặc `http`. gRPC gốc chỉ chạy trên Node.js. Với `connect`/`http`, ảnh được tự động mã hóa base64 trước khi gửi; với `grpc`, ảnh được gửi dưới dạng nhị phân thô không tốn thêm chi phí.

---

## Xử lý lỗi

Mọi lỗi ở mức API đều ném ra `SonicError`, kế thừa từ `Error` có sẵn. Lỗi này mang một `errorId` dạng số và đặt `name` thành tên lỗi tương ứng.

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

<ErrorIdTable />

> [!TIP]
> Các lỗi gRPC tạm thời được tự động thử lại với thời gian chờ tăng dần theo cấp số nhân (tối đa 3 lần), nên thường bạn chỉ cần xử lý các trường hợp `SonicError` ở trên.

---

## Các hàm hỗ trợ tài khoản

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

Nếu bạn cần kiểm soát trực tiếp việc gửi và thăm dò, có sẵn các phương thức tác vụ mức thấp:

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

---

## Khắc phục sự cố

**`require is not defined` / `Cannot use import statement outside a module`** — gói này chỉ dùng ESM. Hãy dùng `import` trong dự án ESM, hoặc `await import("captchasonic")` từ CommonJS. Xem [Cài đặt](#installation).

**Truyền tải `grpc` lỗi trong trình duyệt** — gRPC gốc chỉ dùng được trên Node.js. Hãy chuyển sang `transport: "connect"` hoặc `transport: "http"`.

**`InvalidApiKeyError` ở mọi lệnh gọi** — xác nhận key được truyền làm tham số đầu tiên của constructor và không vô tình là `undefined` (ví dụ do thiếu biến môi trường).

**Phương thức token bị hết thời gian chờ** — tác vụ token thăm dò tối đa `timeout` mili giây (mặc định 120000). Hãy tăng `timeout` và kiểm tra `websiteURL` / `websiteKey` khớp với trang đích. Với Cloudflare, bắt buộc phải có `proxy` hợp lệ.

**Ảnh đường dẫn tệp không tải được** — đường dẫn tệp dạng chuỗi được đọc đồng bộ và chỉ dùng được trên Node.js; trong trình duyệt, hãy truyền `Uint8Array` thay thế.

---

## Tài nguyên

*   [Gói npm](https://www.npmjs.com/package/captchasonic)
*   [Tham chiếu API](/docs/api)
*   [Bảng điều khiển & tài liệu CaptchaSonic](https://captchasonic.com)
