CaptchaSonic Node.js SDK(`captchasonic`)는 대규모 CAPTCHA 풀이를 위한 최신 Promise 기반 TypeScript 우선 라이브러리입니다. 모든 메서드는 `Promise`를 반환하고, 전체 타입 정의를 포함하며, 세 가지 상호 호환되는 전송 방식으로 동작합니다. 네이티브 **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
```

**요구 사항**

| 요구 사항 | 참고 |
|---|---|
| Node.js | ≥ 18.0.0 (`grpc` 전송 방식에 필요) |
| 모듈 형식 | ES Module — 패키지는 `"type": "module"`로 배포됩니다 |
| 브라우저 | `fetch`를 지원하는 최신 브라우저. `connect` 또는 `http` 전송 방식 사용 |

이 패키지는 **ESM 전용**으로 배포됩니다. ESM 프로젝트(`package.json`에 `"type": "module"`이 있거나 `.mjs` 파일을 사용하는 경우)에서는 직접 import하세요:

<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*` 헬퍼가 있으며, 작업을 제출하고 결과로 resolve됩니다. 이미지 작업에는 별도의 폴링 단계가 없습니다. 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` 아래에 있는 결과로 resolve됩니다(예: 선택한 타일 인덱스인 `typedSolution.grid.objects`). 토큰 메서드는 `solution` 맵에 토큰을 담아 반환합니다.

> [!TIP]
> 토큰 기반 메서드(Turnstile, Cloudflare, reCAPTCHA v2/v3 토큰, popular-captcha 토큰)는 브라우저 자동화 작업을 제출한 뒤 토큰이 준비될 때까지 내부적으로 폴링합니다. 기본 대기 시간은 최대 120초입니다.

---

## 지원 CAPTCHA 유형

모든 이미지 메서드는 단일 타입 옵션 객체를 받습니다. 이미지는 `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` 별칭:

| 정식 이름 | 별칭 |
|---|---|
| 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" />

| 옵션 | 타입 | 참고 |
|---|---|---|
| `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 미사용)

윤곽선 검출로 슬라이드 오프셋을 로컬에서 계산합니다. 결합된 이미지 한 장 또는 `[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`)를 전달할 수도 있습니다.

---

## 설정

생성자의 두 번째 인자로 옵션 객체를 전달하세요. 아래 옵션만 지원됩니다.

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

| 옵션 | 타입 | 기본값 | 설명 |
|---|---|---|---|
| `transport` | `"grpc"` \| `"connect"` \| `"http"` | `"grpc"` | 와이어 프로토콜 (아래 표 참고) |
| `timeout` / `timeoutMs` | `number` | 호출당 `30000` | 요청 제한 시간. `timeout`은 폴링 대기 시간도 제한합니다 |
| `pollingInterval` | `number` | `2000` | 토큰 작업을 폴링하는 주기 |
| `url` / `baseUrl` | `string` | 전송 방식별 상이 | API 엔드포인트 재정의 |

**전송 방식**

| 전송 방식 | 환경 | 프로토콜 |
|---|---|---|
| `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 수준의 모든 실패는 내장 `Error`를 확장한 `SonicError`를 던집니다. 숫자형 `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` ms(기본값 120000)까지 폴링합니다. `timeout`을 늘리고, `websiteURL` / `websiteKey`가 대상 페이지와 일치하는지 확인하세요. Cloudflare는 유효한 `proxy`가 필요합니다.

**파일 경로 이미지가 로드되지 않음** — 문자열 파일 경로는 동기적으로 읽히며 Node.js 전용입니다. 브라우저에서는 대신 `Uint8Array`를 전달하세요.

---

## 리소스

*   [npm 패키지](https://www.npmjs.com/package/captchasonic)
*   [API 레퍼런스](/docs/api)
*   [CaptchaSonic 대시보드 & 문서](https://captchasonic.com)
