SDK Node.js
Pustaka resmi CaptchaSonic untuk Node.js dan TypeScript — modern, berbasis Promise, multi-transport (gRPC / ConnectRPC / HTTP).
SDK Node.js CaptchaSonic (captchasonic) adalah pustaka modern, berbasis Promise, dan mengutamakan TypeScript untuk menyelesaikan CAPTCHA dalam skala besar. Setiap metode mengembalikan Promise, menyertakan definisi tipe lengkap, dan berjalan di atas tiga transport yang dapat dipertukarkan — gRPC native (tercepat, hanya Node.js), ConnectRPC (berjalan di Node.js dan browser), dan HTTP/JSON biasa. Error sementara dicoba ulang secara otomatis dengan exponential backoff.
SDK ini berjalan di Node.js ≥ 18 dan browser modern, serta kompatibel dengan Express, Fastify, Next.js, React, Vue, dan Vite.
Instalasi
npm install captchasonic
# or
yarn add captchasonic
# or
pnpm add captchasonic
Persyaratan
| Persyaratan | Catatan |
|---|---|
| Node.js | ≥ 18.0.0 (wajib untuk transport grpc) |
| Format modul | ES Module — paket ini menyertakan "type": "module" |
| Browser | Browser modern apa pun dengan fetch; gunakan transport connect atau http |
Paket ini dipublikasikan hanya ESM. Dalam proyek ESM ("type": "module" di package.json, atau file .mjs), impor langsung:
import { CaptchaSonic } from "captchasonic";
Dari file CommonJS, muat dengan import() dinamis:
// CommonJS (.cjs / "type": "commonjs")
const { CaptchaSonic } = await import("captchasonic");
TIP
Jika Anda menggunakan TypeScript, atur "module": "NodeNext" (atau "ESNext") dan "moduleResolution": "NodeNext" di tsconfig.json agar definisi tipe bawaan dapat di-resolve dengan benar.
Autentikasi
Buat API key di dashboard CaptchaSonic lalu berikan sebagai argumen pertama ke constructor:
import { CaptchaSonic } from "captchasonic";
const solver = new CaptchaSonic("YOUR_API_KEY");
Jangan pernah menulis key langsung di kode sumber (source control). Baca key dari environment:
import { CaptchaSonic } from "captchasonic";
const solver = new CaptchaSonic(process.env.CAPTCHASONIC_API_KEY);
Mulai Cepat
Setiap jenis captcha memiliki helper solve* khusus yang mengirim task dan mengembalikan hasilnya. Tidak ada langkah polling terpisah untuk task gambar — SDK menanganinya untuk Anda.
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 fieldMengembalikan: metode gambar menghasilkan hasil yang jawabannya berada di
typedSolution(mis.typedSolution.grid.objects, indeks tile yang dipilih); metode token mengembalikan token di dalam mapsolution.
TIP
Metode berbasis token (Turnstile, Cloudflare, reCAPTCHA v2/v3 token, popular-captcha token) mengirim task otomasi browser dan melakukan polling secara internal hingga token siap — secara default hingga 120 detik.
Jenis CAPTCHA yang Didukung
Semua metode gambar menerima satu objek opsi bertipe. Gambar dapat berupa Uint8Array, Buffer Node, atau path file berupa string (path file hanya untuk Node.js).
reCAPTCHA v2 (gambar)
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 (gambar gaya 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" });
Mengembalikan: tipe grid/click masuk ke typedSolution.grid.objects (atau typedSolution.click); slide mengembalikan typedSolution.slide.x.
Alias type yang diterima:
| Kanonik | Alias |
|---|---|
| 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 / gambar-ke-teks
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]
| Opsi | Tipe | Catatan |
|---|---|---|
module | "common" | "mtcaptcha" | "bls" | "morocco" | Default "common" |
numeric | boolean | Hanya digit (otomatis aktif untuk "bls") |
caseSensitive | boolean | Pertahankan huruf besar/kecil |
minLength / maxLength | number | Batas panjang |
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
Mengembalikan: click masuk ke typedSolution.click; whirl/slide mengembalikan typedSolution.slide.x.
type menerima "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] });
Mengembalikan: grid masuk ke typedSolution.grid.objects; slide mengembalikan typedSolution.slide.x.
type menerima "grid"/"binance_grid" dan "slide"/"binance_slide".
AWS WAF
solveAwsWaf menerima argumen posisional. question diformat sebagai "type:category:target".
await solver.solveAwsWaf(tiles, "grid:vehicles:cars");
Mengembalikan: indeks tile yang dipilih di typedSolution.grid.objects.
Gambar slide (lokal, tanpa AI)
Mendeteksi offset slide secara lokal menggunakan deteksi kontur. Menerima satu gambar gabungan, atau [background, piece].
const r = await solver.solveSlideImage({ images: ["slide_bg.png", "piece.png"] });
console.log(r.typedSolution?.slide?.x); // pixel offset, e.g. 142
Mengembalikan: offset slide dalam piksel di typedSolution.slide.x.
Metode token (otomasi browser)
Metode ini mengirim task dan melakukan polling secara internal hingga token dikembalikan (hingga batas waktu polling, secara default 120 detik).
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 REQUIREDMengembalikan: token ada di map solution dari respons (misalnya result.solution.token atau result.solution.gRecaptchaResponse, tergantung captcha).
Penggunaan TypeScript
SDK mengekspor tipe untuk setiap objek opsi dan respons. Impor dengan import type.
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);
Tipe yang diekspor
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 adalah Uint8Array | Buffer | string.
Dukungan Proxy
Metode token / otomasi browser menerima string proxy opsional dengan format http://user:pass@host:port:
await solver.solveTurnstile({
websiteURL: "https://example.com",
websiteKey: "0x4AAAAAAA...",
proxy: "http://user:[email protected]:8080",
});
WARNING
solveCloudflare selalu memerlukan proxy — field proxy wajib untuk metode tersebut. Metode token lainnya berjalan tanpa proxy jika proxy dihilangkan.
Untuk hCaptcha enterprise, Anda juga dapat meneruskan metadata (rqdata, rqtoken, fingerprint) ke solvePopularCaptchaToken.
Konfigurasi
Berikan objek opsi sebagai argumen kedua constructor. Hanya opsi di bawah ini yang didukung.
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)
});
| Opsi | Tipe | Default | Deskripsi |
|---|---|---|---|
transport | "grpc" | "connect" | "http" | "grpc" | Protokol kabel (lihat tabel di bawah) |
timeout / timeoutMs | number | 30000 per panggilan | Batas waktu permintaan; timeout juga membatasi waktu tunggu polling |
pollingInterval | number | 2000 | Seberapa sering task token di-polling |
url / baseUrl | string | per transport | Mengganti endpoint API |
Transport
| Transport | Lingkungan | Protokol |
|---|---|---|
grpc | Hanya Node.js | gRPC biner di atas HTTP/2 — latensi terendah, mengirim gambar sebagai biner mentah |
connect | Node.js dan browser | ConnectRPC di atas fetch |
http | Node.js dan browser | REST/JSON biasa di atas fetch |
TIP
Di browser gunakan connect (direkomendasikan) atau http. gRPC native memerlukan Node.js. Dengan connect/http, gambar otomatis di-encode ke base64 sebelum dikirim; dengan grpc gambar dikirim sebagai biner mentah tanpa overhead.
Penanganan Error
Semua kegagalan tingkat API melempar SonicError, yang merupakan turunan dari Error bawaan. Error ini membawa errorId numerik dan mengatur name sesuai nama error yang sesuai.
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
Error gRPC sementara dicoba ulang secara otomatis dengan exponential backoff (hingga 3 percobaan), sehingga biasanya Anda hanya perlu menangani kasus SonicError di atas.
Helper Akun
const balance = await solver.getBalance(); // → number (USD)
const health = await solver.healthCheck(); // → { healthy: boolean, version: string }
Metode task tingkat rendah tersedia jika Anda memerlukan kontrol langsung atas pengiriman dan polling:
const created = await solver.createTask(task); // submit a Partial<Task>
const result = await solver.getTaskResult(taskId); // poll for a result
Pemecahan Masalah
require is not defined / Cannot use import statement outside a module — paket ini hanya ESM. Gunakan import di proyek ESM, atau await import("captchasonic") dari CommonJS. Lihat Instalasi.
Transport grpc gagal di browser — gRPC native hanya untuk Node.js. Ganti ke transport: "connect" atau transport: "http".
InvalidApiKeyError pada setiap panggilan — pastikan key diberikan sebagai argumen pertama constructor dan bukan undefined secara tidak sengaja (mis. variabel env yang belum diatur).
Metode token kehabisan waktu — task token di-polling hingga timeout ms (default 120000). Tingkatkan timeout dan pastikan websiteURL / websiteKey sesuai dengan halaman target. Untuk Cloudflare, proxy yang valid wajib diisi.
Gambar dengan path file tidak termuat — path file berupa string dibaca secara sinkron dan hanya untuk Node.js; di browser berikan Uint8Array sebagai gantinya.