Node.js SDK
Node.js ve TypeScript için resmi CaptchaSonic kütüphanesi — modern, Promise tabanlı, çoklu taşıma (gRPC / ConnectRPC / HTTP).
CaptchaSonic Node.js SDK'sı (captchasonic), CAPTCHA'ları büyük ölçekte çözmek için modern, Promise tabanlı ve TypeScript öncelikli bir kütüphanedir. Her metot bir Promise döndürür, tam tip tanımları içerir ve birbiriyle değiştirilebilir üç taşıma üzerinden çalışır: yerel gRPC (en hızlı, yalnızca Node.js), ConnectRPC (Node.js ve tarayıcılarda çalışır) ve düz HTTP/JSON. Geçici hatalar üssel geri çekilmeyle (exponential backoff) otomatik olarak yeniden denenir.
Node.js ≥ 18 ve modern tarayıcılarda çalışır; Express, Fastify, Next.js, React, Vue ve Vite ile uyumludur.
Kurulum
npm install captchasonic
# or
yarn add captchasonic
# or
pnpm add captchasonic
Gereksinimler
| Gereksinim | Notlar |
|---|---|
| Node.js | ≥ 18.0.0 (grpc taşıması için gerekli) |
| Modül biçimi | ES Module — paket "type": "module" ile yayımlanır |
| Tarayıcı | fetch destekleyen her modern tarayıcı; connect veya http taşımasını kullanın |
Paket yalnızca ESM olarak yayımlanır. Bir ESM projesinde (package.json içinde "type": "module" ya da bir .mjs dosyası) doğrudan içe aktarın:
import { CaptchaSonic } from "captchasonic";
CommonJS dosyasından ise dinamik import() ile yükleyin:
// CommonJS (.cjs / "type": "commonjs")
const { CaptchaSonic } = await import("captchasonic");
TIP
TypeScript kullanıyorsanız, paketle gelen tip tanımlarının doğru çözümlenmesi için tsconfig.json içinde "module": "NodeNext" (veya "ESNext") ve "moduleResolution": "NodeNext" ayarlayın.
Kimlik Doğrulama
CaptchaSonic panelinden bir API anahtarı oluşturun ve bunu kurucunun ilk argümanı olarak geçin:
import { CaptchaSonic } from "captchasonic";
const solver = new CaptchaSonic("YOUR_API_KEY");
Anahtarları kaynak kontrolüne asla sabit kodlamayın. Anahtarı bunun yerine ortamdan okuyun:
import { CaptchaSonic } from "captchasonic";
const solver = new CaptchaSonic(process.env.CAPTCHASONIC_API_KEY);
Hızlı Başlangıç
Her CAPTCHA türünün, görevi gönderen ve sonuçla çözülen özel bir solve* yardımcısı vardır. Görsel görevleri için ayrı bir sorgulama adımı yoktur — SDK bunu sizin için yönetir.
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 fieldDönüş: görsel metotlar, yanıtı
typedSolutionaltında bulunan bir sonuç döndürür (ör.typedSolution.grid.objects, seçilen kare indeksleri); token metotları ise token'ısolutionharitasında döndürür.
TIP
Token tabanlı metotlar (Turnstile, Cloudflare, reCAPTCHA v2/v3 token, popular-captcha token) bir tarayıcı otomasyon görevi gönderir ve token hazır olana kadar dahili olarak sorgular — varsayılan olarak 120 saniyeye kadar.
Desteklenen CAPTCHA Türleri
Tüm görsel metotlar tek bir tipli seçenek nesnesi alır. Görseller Uint8Array, Node Buffer veya metin olarak dosya yolu olabilir (dosya yolları yalnızca Node.js'te geçerlidir).
reCAPTCHA v2 (görsel)
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 benzeri görsel)
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" });
Dönüş: grid/click türleri typedSolution.grid.objects (veya typedSolution.click) alanına düşer; slide typedSolution.slide.x döndürür.
Kabul edilen type takma adları:
| Kanonik | Takma adlar |
|---|---|
| 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 / görselden metne
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]
| Seçenek | Tür | Notlar |
|---|---|---|
module | "common" | "mtcaptcha" | "bls" | "morocco" | Varsayılan "common" |
numeric | boolean | Yalnızca rakamlar ("bls" için otomatik ayarlanır) |
caseSensitive | boolean | Harf büyüklüğünü koru |
minLength / maxLength | number | Uzunluk sınırları |
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
Dönüş: click sonucu typedSolution.click alanına düşer; whirl/slide typedSolution.slide.x döndürür.
type değeri "click"/"tiktok_click", "whirl"/"tiktok_whirl", "slide"/"tiktok_slide" kabul eder.
Binance
await solver.solveBinance({ type: "grid", question: "Select the bicycle", images });
await solver.solveBinance({ type: "slide", images: [puzzle], examples: [background] });
Dönüş: grid sonucu typedSolution.grid.objects alanına düşer; slide typedSolution.slide.x döndürür.
type değeri "grid"/"binance_grid" ve "slide"/"binance_slide" kabul eder.
AWS WAF
solveAwsWaf konumsal argümanlar alır. question "type:category:target" biçiminde yazılır.
await solver.solveAwsWaf(tiles, "grid:vehicles:cars");
Dönüş: seçilen kare indeksleri typedSolution.grid.objects içinde.
Slide görseli (yerel, yapay zekâsız)
Kontur tespiti kullanarak kaydırma ofsetini yerel olarak algılar. Tek birleşik bir görsel veya [background, piece] kabul eder.
const r = await solver.solveSlideImage({ images: ["slide_bg.png", "piece.png"] });
console.log(r.typedSolution?.slide?.x); // pixel offset, e.g. 142
Dönüş: kaydırma ofseti piksel cinsinden typedSolution.slide.x içinde.
Token metotları (tarayıcı otomasyonu)
Bunlar bir görev gönderir ve token dönene kadar dahili olarak sorgular (varsayılan sorgulama zaman aşımı 120 sn'ye kadar).
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 REQUIREDDönüş: token, yanıtın solution haritasında yer alır (CAPTCHA'ya göre örneğin result.solution.token veya result.solution.gRecaptchaResponse).
TypeScript Kullanımı
SDK, her seçenek nesnesi ve yanıt için tipleri dışa aktarır. import type ile içe aktarın.
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);
Dışa aktarılan tipler
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 tipindedir.
Proxy Desteği
Token / tarayıcı otomasyonu metotları, http://user:pass@host:port biçiminde isteğe bağlı bir proxy metni kabul eder:
await solver.solveTurnstile({
websiteURL: "https://example.com",
websiteKey: "0x4AAAAAAA...",
proxy: "http://user:[email protected]:8080",
});
WARNING
solveCloudflare her zaman proxy gerektirir — bu metot için proxy alanı zorunludur. Diğer token metotları proxy atlandığında proxysiz çalışır.
Kurumsal hCaptcha için solvePopularCaptchaToken metoduna metadata (rqdata, rqtoken, fingerprint) de geçebilirsiniz.
Yapılandırma
Kurucunun ikinci argümanı olarak bir seçenek nesnesi geçin. Yalnızca aşağıdaki seçenekler desteklenir.
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)
});
| Seçenek | Tür | Varsayılan | Açıklama |
|---|---|---|---|
transport | "grpc" | "connect" | "http" | "grpc" | Tel protokolü (aşağıdaki tabloya bakın) |
timeout / timeoutMs | number | Çağrı başına 30000 | İstek zaman aşımı; timeout sorgu bekleme süresini de sınırlar |
pollingInterval | number | 2000 | Token görevlerinin ne sıklıkla sorgulanacağı |
url / baseUrl | string | taşımaya göre | API uç noktasını geçersiz kıl |
Taşımalar
| Taşıma | Ortamlar | Protokol |
|---|---|---|
grpc | Yalnızca Node.js | HTTP/2 üzerinden gRPC ikili — en düşük gecikme, görselleri ham ikili olarak gönderir |
connect | Node.js ve tarayıcılar | fetch üzerinden ConnectRPC |
http | Node.js ve tarayıcılar | fetch üzerinden düz REST/JSON |
TIP
Tarayıcıda connect (önerilen) veya http kullanın. Yerel gRPC Node.js gerektirir. connect/http ile görseller gönderilmeden önce otomatik olarak base64'e kodlanır; grpc ile ise sıfır ek yükle ham ikili olarak gönderilir.
Hata Yönetimi
API düzeyindeki tüm hatalar, yerleşik Error sınıfını genişleten bir SonicError fırlatır. Sayısal bir errorId taşır ve name alanını eşleşen hata adına ayarlar.
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
Geçici gRPC hataları üssel geri çekilmeyle otomatik olarak yeniden denenir (en fazla 3 deneme); bu yüzden genellikle yalnızca yukarıdaki SonicError durumlarını ele almanız yeterlidir.
Hesap Yardımcıları
const balance = await solver.getBalance(); // → number (USD)
const health = await solver.healthCheck(); // → { healthy: boolean, version: string }
Gönderim ve sorgulama üzerinde doğrudan kontrole ihtiyacınız varsa düşük seviyeli görev metotları da mevcuttur:
const created = await solver.createTask(task); // submit a Partial<Task>
const result = await solver.getTaskResult(taskId); // poll for a result
Sorun Giderme
require is not defined / Cannot use import statement outside a module — paket yalnızca ESM'dir. ESM projesinde import kullanın veya CommonJS'ten await import("captchasonic") çağırın. Bkz. Kurulum.
grpc taşıması tarayıcıda başarısız oluyor — yerel gRPC yalnızca Node.js'tedir. transport: "connect" veya transport: "http" seçeneğine geçin.
Her çağrıda InvalidApiKeyError — anahtarın kurucunun ilk argümanı olarak geçildiğini ve yanlışlıkla undefined olmadığını doğrulayın (ör. eksik bir ortam değişkeni).
Token metodu zaman aşımına uğruyor — token görevleri en fazla timeout ms (varsayılan 120000) sorgulanır. timeout değerini artırın ve websiteURL / websiteKey değerlerinin hedef sayfayla eşleştiğini doğrulayın. Cloudflare için geçerli bir proxy gereklidir.
Dosya yolu olarak verilen görseller yüklenmiyor — metin olarak dosya yolları eşzamanlı okunur ve yalnızca Node.js'te çalışır; tarayıcıda bunun yerine bir Uint8Array geçin.