Node.js SDK
Node.js और TypeScript के लिए आधिकारिक CaptchaSonic लाइब्रेरी — आधुनिक, Promise-आधारित, मल्टी-ट्रांसपोर्ट (gRPC / ConnectRPC / HTTP)।
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 के साथ संगत है।
इंस्टॉलेशन
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 करें:
import { CaptchaSonic } from "captchasonic";
CommonJS फ़ाइल से, इसे dynamic import() से लोड करें:
// CommonJS (.cjs / "type": "commonjs")
const { CaptchaSonic } = await import("captchasonic");
TIP
TypeScript का उपयोग कर रहे हैं तो tsconfig.json में "module": "NodeNext" (या "ESNext") और "moduleResolution": "NodeNext" सेट करें, ताकि बंडल की गई टाइप परिभाषाएँ सही तरह resolve हों।
प्रमाणीकरण
CaptchaSonic dashboard में API key बनाएँ और उसे constructor के पहले आर्गुमेंट के रूप में पास करें:
import { CaptchaSonic } from "captchasonic";
const solver = new CaptchaSonic("YOUR_API_KEY");
Keys को सोर्स कंट्रोल में कभी hard-code न करें। इसके बजाय key को एनवायरनमेंट से पढ़ें:
import { CaptchaSonic } from "captchasonic";
const solver = new CaptchaSonic(process.env.CAPTCHASONIC_API_KEY);
त्वरित शुरुआत
हर CAPTCHA प्रकार का एक समर्पित solve* हेल्पर होता है, जो टास्क सबमिट करता है और परिणाम के साथ resolve होता है। इमेज टास्क के लिए अलग पोलिंग चरण नहीं है — SDK यह आपके लिए संभालता है।
solveRecaptchaV2TokentokenreCAPTCHA v2 (token) — Solve a reCAPTCHA v2 token challenge via browser automation (async — polls until ready).
solveRecaptchaV2Token(…)returnssolution.tokenimport { CaptchaSonic } from "captchasonic";
const solver = new CaptchaSonic(process.env.CAPTCHASONIC_API_KEY);
const result = await solver.solveRecaptchaV2Token({
websiteURL: "https://example.com/login",
websiteKey: "6Le-wvkSAAAAAPBMRTvw0Q4Muexq9bi0DJwx_mJ-",
});
console.log(result.solution.gRecaptchaResponse);
// 03AGdBq25SxXT... ← drop into the g-recaptcha-response fieldfrom captchasonic import CaptchaSonic
solver = CaptchaSonic("YOUR_API_KEY")
result = solver.solve_recaptcha_v2_token(
website_url="https://example.com/login",
website_key="6Le-wvkSAAAAAPBMRTvw0Q4Muexq9bi0DJwx_mJ-",
)
print(result["token"])
# 03AGdBq25SxXT... ← drop this into the g-recaptcha-response fieldलौटाता है: इमेज मेथड एक ऐसा परिणाम 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 (इमेज)
await solver.solveRecaptchaV2({
images: tiles, // typically 9 tiles for a 3×3 grid
question: "traffic lights", // plain text, or a Google class code like "/m/015qff"
});
// → result.typedSolution.grid.objects (number[] — selected tile indices)
PopularCaptcha (hCaptcha-शैली इमेज)
await solver.solvePopularCaptcha({
images: tiles, // 1–64 tiles
question: "Click each image with a cat",
questionType: "objectClassify", // "objectClassify" | "grid" | "objectClick" | "objectDrag"
examples, // optional reference images for objectClick
websiteURL: "https://example.com",
});
// objectClassify/grid → typedSolution.grid.objects
// objectClick → typedSolution.click
// objectDrag → typedSolution.drag
GeeTest
// nine-grid (question + images required)
await solver.solveGeetest({ type: "nine", question: "Select all bicycles", images: tiles });
// click / icon (question + images required)
await solver.solveGeetest({ type: "click", question: "the bear", images: tiles });
// slide puzzle (piece + background)
await solver.solveGeetest({ type: "slide", images: [piece], examples: [background] });
// swap puzzles
await solver.solveGeetest({ type: "match" });
await solver.solveGeetest({ type: "winlinze" });
लौटाता है: 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 / इमेज-से-टेक्स्ट
await solver.solveOcr({ images: [img] }); // general OCR
await solver.solveOcr({ images: [img], module: "mtcaptcha", maxLength: 4 });
await solver.solveOcr({ images: imgs, module: "bls", numeric: true, maxLength: 3 });
// → result.typedSolution.text.texts[0]
| विकल्प | प्रकार | टिप्पणियाँ |
|---|---|---|
module | "common" | "mtcaptcha" | "bls" | "morocco" | डिफ़ॉल्ट "common" |
numeric | boolean | केवल अंक ("bls" के लिए स्वतः सेट) |
caseSensitive | boolean | अक्षरों का केस सुरक्षित रखें |
minLength / maxLength | number | लंबाई सीमाएँ |
TikTok
await solver.solveTikTok({ type: "click", question: "Select the shape", images });
await solver.solveTikTok({ type: "whirl", question: "Rotate to match", images, examples }); // examples required
await solver.solveTikTok({ type: "slide", question: "Slide to fit", images, examples }); // examples required
लौटाता है: click typedSolution.click में आता है; whirl/slide typedSolution.slide.x लौटाते हैं।
type स्वीकार करता है "click"/"tiktok_click", "whirl"/"tiktok_whirl", "slide"/"tiktok_slide"।
Binance
await solver.solveBinance({ type: "grid", question: "Select the bicycle", images });
await solver.solveBinance({ type: "slide", images: [puzzle], examples: [background] });
लौटाता है: grid typedSolution.grid.objects में आता है; slide typedSolution.slide.x लौटाता है।
type स्वीकार करता है "grid"/"binance_grid" और "slide"/"binance_slide"।
AWS WAF
solveAwsWaf positional आर्गुमेंट लेता है। question "type:category:target" के रूप में फ़ॉर्मेट होता है।
await solver.solveAwsWaf(tiles, "grid:vehicles:cars");
लौटाता है: चुने गए टाइल इंडेक्स typedSolution.grid.objects में।
Slide इमेज (लोकल, AI नहीं)
Contour detection से स्लाइड ऑफ़सेट स्थानीय रूप से पहचाना जाता है। एक संयुक्त इमेज, या [background, piece] स्वीकार करता है।
const r = await solver.solveSlideImage({ images: ["slide_bg.png", "piece.png"] });
console.log(r.typedSolution?.slide?.x); // pixel offset, e.g. 142
लौटाता है: typedSolution.slide.x पर पिक्सल में स्लाइड ऑफ़सेट।
टोकन मेथड (browser automation)
ये टास्क सबमिट करते हैं और टोकन मिलने तक आंतरिक रूप से पोल करते हैं (डिफ़ॉल्ट रूप से पोलिंग टाइमआउट, 120 सेकंड तक)।
solveTurnstiletokenCloudflare Turnstile — Solve a Cloudflare Turnstile token challenge (async — polls until ready).
solveTurnstile(…)returnssolution.tokenawait solver.solveTurnstile({ websiteURL, websiteKey, proxy }); // proxy optional
await solver.solveRecaptchaV2Token({ websiteURL, websiteKey, proxy }); // proxy optional
await solver.solveRecaptchaV3Token({ websiteURL, websiteKey, proxy }); // proxy optional
await solver.solvePopularCaptchaToken({ websiteURL, websiteKey, proxy, metadata }); // proxy optional
await solver.solveCloudflare({ websiteURL, websiteKey, proxy }); // proxy REQUIREDsolver.solve_turnstile(website_url=..., website_key=..., proxy=...) # proxy optional
solver.solve_recaptcha_v2_token(website_url=..., website_key=..., proxy=...) # proxy optional
solver.solve_recaptcha_v3_token(website_url=..., website_key=..., proxy=...) # proxy optional
solver.solve_popular_captcha_token(website_url=..., website_key=..., proxy=...) # proxy optional
solver.solve_cloudflare(website_url=..., website_key=..., proxy=...) # proxy REQUIREDलौटाता है: रिस्पॉन्स के solution मैप में टोकन (captcha के अनुसार, जैसे result.solution.token या result.solution.gRecaptchaResponse)।
TypeScript उपयोग
SDK हर options ऑब्जेक्ट और रिस्पॉन्स के लिए टाइप्स export करता है। उन्हें import type से import करें।
import { CaptchaSonic } from "captchasonic";
import type { SolveGeetestOptions, GetTaskResultResponse } from "captchasonic";
const solver = new CaptchaSonic(process.env.CAPTCHASONIC_API_KEY!);
const opts: SolveGeetestOptions = {
type: "nine",
question: "Select all bicycles",
images: tiles,
};
const result = await solver.solveGeetest(opts);
console.log(result.typedSolution?.grid?.objects);
Exported टाइप्स
import type {
CaptchaSonicOptions,
ImageInput,
SolvePopularCaptchaOptions,
SolveRecaptchaV2Options,
SolveGeetestOptions,
SolveOcrOptions,
SolveTikTokOptions,
SolveBinanceOptions,
SolveTurnstileOptions,
SolvePopularCaptchaTokenOptions,
SolveRecaptchaV2TokenOptions,
SolveRecaptchaV3TokenOptions,
SolveCloudflareOptions,
SolveSlideImageOptions,
GeetestSubtype,
TikTokSubtype,
BinanceSubtype,
Task,
CreateTaskResponse,
GetTaskResultResponse,
} from "captchasonic";
ImageInput है Uint8Array | Buffer | string।
Proxy समर्थन
टोकन / browser-automation मेथड http://user:pass@host:port फ़ॉर्मेट में वैकल्पिक proxy स्ट्रिंग स्वीकार करती हैं:
await solver.solveTurnstile({
websiteURL: "https://example.com",
websiteKey: "0x4AAAAAAA...",
proxy: "http://user:[email protected]:8080",
});
WARNING
solveCloudflare को हमेशा proxy चाहिए — उस मेथड के लिए proxy फ़ील्ड अनिवार्य है। अन्य टोकन मेथड proxy छोड़ने पर proxyless चलती हैं।
Enterprise hCaptcha के लिए आप solvePopularCaptchaToken को metadata (rqdata, rqtoken, fingerprint) भी पास कर सकते हैं।
कॉन्फ़िगरेशन
Constructor के दूसरे आर्गुमेंट के रूप में एक options ऑब्जेक्ट पास करें। केवल नीचे दिए विकल्प समर्थित हैं।
const solver = new CaptchaSonic("YOUR_API_KEY", {
transport: "connect", // "grpc" (default) | "connect" | "http"
timeout: 180_000, // max poll wait in ms (alias: timeoutMs); per-call default 30000
pollingInterval: 5_000, // polling frequency in ms (default 2000)
baseUrl: "https://api.captchasonic.com", // override endpoint (alias: url)
});
| विकल्प | प्रकार | डिफ़ॉल्ट | विवरण |
|---|---|---|---|
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 मिलते-जुलते एरर नाम पर सेट होता है।
import { CaptchaSonic, SonicError } from "captchasonic";
try {
const result = await solver.solveGeetest({ type: "nine", question: "bicycles", images });
} catch (err) {
if (err instanceof SonicError) {
console.error(err.errorId); // 1–6
console.error(err.name); // e.g. "InvalidApiKeyError"
console.error(err.message);
} else {
throw err; // network / unexpected
}
}
| id | Python exception | Node errorName | Meaning | Action |
|---|---|---|---|---|
0 | SonicError | SonicError | Base class for every SDK error — catches anything below. | Inspect `error.errorId` (Node) / `err.error_id` (Python) and branch. |
1 | InvalidApiKeyError | InvalidApiKeyError | API key is missing, malformed, or revoked. | Verify the key in your dashboard. |
2 | InsufficientBalanceError | InsufficientBalanceError | Account balance can't cover the task. | Add funds. |
3 | DailyLimitExceededError | DailyLimitExceededError | Daily quota exhausted. | Wait for the daily reset or upgrade your plan. |
4 | MinuteLimitExceededError | MinuteLimitExceededError | Per-minute rate limit hit. | Slow down requests / add exponential backoff. |
5 | QuotaExceededError | QuotaExceededError | Plan quota exhausted. | Upgrade your plan. |
6 | PlanExpiredError | PlanExpiredError | Subscription has expired. | Renew your subscription. |
Every concrete row inherits from SonicError — catch it once to handle all SDK failures, or branch on errorId / exception subclass for granular control. Transient gRPC errors are retried automatically with exponential backoff (up to 3 attempts).
TIP
अस्थायी gRPC त्रुटियों पर exponential backoff के साथ अपने-आप retry होता है (अधिकतम 3 प्रयास), इसलिए आमतौर पर आपको ऊपर के SonicError मामलों को ही संभालना होता है।
खाता सहायक
const balance = await solver.getBalance(); // → number (USD)
const health = await solver.healthCheck(); // → { healthy: boolean, version: string }
यदि आपको सबमिशन और पोलिंग पर सीधा नियंत्रण चाहिए, तो निम्न-स्तर के टास्क मेथड उपलब्ध हैं:
const created = await solver.createTask(task); // submit a Partial<Task>
const result = await solver.getTaskResult(taskId); // poll for a result
समस्या-निवारण
require is not defined / Cannot use import statement outside a module — पैकेज केवल ESM है। ESM प्रोजेक्ट में import उपयोग करें, या CommonJS से await import("captchasonic")। देखें इंस्टॉलेशन।
grpc ट्रांसपोर्ट ब्राउज़र में विफल — नेटिव gRPC केवल Node.js में है। transport: "connect" या transport: "http" पर स्विच करें।
हर कॉल पर InvalidApiKeyError — पुष्टि करें कि key constructor के पहले आर्गुमेंट के रूप में पास हो रही है और गलती से undefined नहीं है (जैसे एनवायरनमेंट वेरिएबल गायब होना)।
टोकन मेथड टाइमआउट — टोकन टास्क timeout ms तक पोल करते हैं (डिफ़ॉल्ट 120000)। timeout बढ़ाएँ और जाँचें कि websiteURL / websiteKey लक्ष्य पेज से मेल खाते हैं। Cloudflare के लिए वैध proxy आवश्यक है।
फ़ाइल-पाथ इमेज लोड नहीं होतीं — स्ट्रिंग फ़ाइल पाथ सिंक्रोनस पढ़े जाते हैं और केवल Node.js में हैं; ब्राउज़र में इसके बजाय Uint8Array पास करें।