CaptchaSonic Node.js SDK (`captchasonic`) बड़े पैमाने पर CAPTCHA हल करने के लिए एक आधुनिक, Promise-आधारित, TypeScript-first लाइब्रेरी है। हर मेथड एक `Promise` लौटाती है, पूरी टाइप परिभाषाएँ देती है, और तीन आपस में बदले जा सकने वाले ट्रांसपोर्ट पर चलती है — नेटिव **gRPC** (सबसे तेज़, केवल Node.js), **ConnectRPC** (Node.js और ब्राउज़र दोनों में काम करता है), और सादा **HTTP/JSON**। अस्थायी त्रुटियों पर exponential backoff के साथ अपने-आप retry होता है।

यह **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 फ़ाइल से, इसे dynamic `import()` से लोड करें:

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

> [!TIP]
> TypeScript का उपयोग कर रहे हैं तो `tsconfig.json` में `"module": "NodeNext"` (या `"ESNext"`) और `"moduleResolution": "NodeNext"` सेट करें, ताकि बंडल की गई टाइप परिभाषाएँ सही तरह resolve हों।

---

## प्रमाणीकरण

[CaptchaSonic dashboard](https://captchasonic.com) में API key बनाएँ और उसे constructor के पहले आर्गुमेंट के रूप में पास करें:

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

Keys को सोर्स कंट्रोल में कभी hard-code न करें। इसके बजाय key को एनवायरनमेंट से पढ़ें:

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

> **लौटाता है:** इमेज मेथड एक ऐसा परिणाम resolve करती हैं जिसका उत्तर `typedSolution` के अंतर्गत होता है (जैसे `typedSolution.grid.objects`, चुने गए टाइल इंडेक्स); टोकन मेथड `solution` मैप में टोकन लौटाती हैं।

> [!TIP]
> टोकन-आधारित मेथड (Turnstile, Cloudflare, reCAPTCHA v2/v3 token, popular-captcha token) एक browser-automation टास्क सबमिट करती हैं और टोकन तैयार होने तक आंतरिक रूप से पोल करती हैं — डिफ़ॉल्ट रूप से 120 सेकंड तक।

---

## समर्थित CAPTCHA प्रकार

सभी इमेज मेथड एक ही टाइप्ड options ऑब्जेक्ट लेती हैं। इमेज `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` positional आर्गुमेंट लेता है। `question` `"type:category:target"` के रूप में फ़ॉर्मेट होता है।

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

लौटाता है: चुने गए टाइल इंडेक्स `typedSolution.grid.objects` में।

### Slide इमेज (लोकल, AI नहीं)

Contour detection से स्लाइड ऑफ़सेट स्थानीय रूप से पहचाना जाता है। एक संयुक्त इमेज, या `[background, piece]` स्वीकार करता है।

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

लौटाता है: `typedSolution.slide.x` पर पिक्सल में स्लाइड ऑफ़सेट।

### टोकन मेथड (browser automation)

ये टास्क सबमिट करते हैं और टोकन मिलने तक आंतरिक रूप से पोल करते हैं (डिफ़ॉल्ट रूप से पोलिंग टाइमआउट, 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 हर options ऑब्जेक्ट और रिस्पॉन्स के लिए टाइप्स export करता है। उन्हें `import type` से import करें।

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

**Exported टाइप्स**

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

`ImageInput` है `Uint8Array | Buffer | string`।

---

## Proxy समर्थन

टोकन / browser-automation मेथड `http://user:pass@host:port` फ़ॉर्मेट में वैकल्पिक `proxy` स्ट्रिंग स्वीकार करती हैं:

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

> [!WARNING]
> `solveCloudflare` को **हमेशा** proxy चाहिए — उस मेथड के लिए `proxy` फ़ील्ड अनिवार्य है। अन्य टोकन मेथड `proxy` छोड़ने पर proxyless चलती हैं।

Enterprise hCaptcha के लिए आप `solvePopularCaptchaToken` को `metadata` (`rqdata`, `rqtoken`, `fingerprint`) भी पास कर सकते हैं।

---

## कॉन्फ़िगरेशन

Constructor के दूसरे आर्गुमेंट के रूप में एक options ऑब्जेक्ट पास करें। केवल नीचे दिए विकल्प समर्थित हैं।

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

| विकल्प | प्रकार | डिफ़ॉल्ट | विवरण |
|---|---|---|---|
| `transport` | `"grpc"` \| `"connect"` \| `"http"` | `"grpc"` | वायर प्रोटोकॉल (नीचे की तालिका देखें) |
| `timeout` / `timeoutMs` | `number` | प्रति कॉल `30000` | अनुरोध टाइमआउट; `timeout` पोलिंग प्रतीक्षा की सीमा भी तय करता है |
| `pollingInterval` | `number` | `2000` | टोकन टास्क कितनी बार पोल किए जाते हैं |
| `url` / `baseUrl` | `string` | ट्रांसपोर्ट के अनुसार | API endpoint को ओवरराइड करें |

**ट्रांसपोर्ट**

| ट्रांसपोर्ट | वातावरण | प्रोटोकॉल |
|---|---|---|
| `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` को extend करती है। इसमें एक संख्यात्मक `errorId` होता है और `name` मिलते-जुलते एरर नाम पर सेट होता है।

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

<ErrorIdTable />

> [!TIP]
> अस्थायी gRPC त्रुटियों पर exponential backoff के साथ अपने-आप retry होता है (अधिकतम 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`** — पुष्टि करें कि key constructor के पहले आर्गुमेंट के रूप में पास हो रही है और गलती से `undefined` नहीं है (जैसे एनवायरनमेंट वेरिएबल गायब होना)।

**टोकन मेथड टाइमआउट** — टोकन टास्क `timeout` ms तक पोल करते हैं (डिफ़ॉल्ट 120000)। `timeout` बढ़ाएँ और जाँचें कि `websiteURL` / `websiteKey` लक्ष्य पेज से मेल खाते हैं। Cloudflare के लिए वैध `proxy` आवश्यक है।

**फ़ाइल-पाथ इमेज लोड नहीं होतीं** — स्ट्रिंग फ़ाइल पाथ सिंक्रोनस पढ़े जाते हैं और केवल Node.js में हैं; ब्राउज़र में इसके बजाय `Uint8Array` पास करें।

---

## संसाधन

*   [npm package](https://www.npmjs.com/package/captchasonic)
*   [API reference](/docs/api)
*   [CaptchaSonic dashboard & docs](https://captchasonic.com)
