Node.js SDK

@clearance-rest/sdk, Numbers, Emails ve Captchas API’lerini sarar. Her çağrı API anahtarınızı gönderir, sert bir deadline koyar ve hataları tipli hatalara çevirir.

Kurulum

npm install @clearance-rest/sdk

const clearanceRest = require('@clearance-rest/sdk');

Yapılandırma

API anahtarınızı ortamda tanımlayın. SDK bunu her istekte X-API-Key olarak gönderir.

export CLEARANCE_REST_API_KEY=cr_live_...

Tanımlı değilse hiçbir anahtar gönderilmez ve API 401 döndürür.

Değişken	Amaç
CLEARANCE_REST_API_KEY	Projenizin API anahtarı.
CLEARANCE_REST_NUMBERS_URL	Numbers base URL’ini ezer. Varsayılan https://api.clearance.rest/numbers.
CLEARANCE_REST_EMAILS_URL	Emails base URL’ini ezer. Varsayılan https://api.clearance.rest/emails.
CLEARANCE_REST_CAPTCHAS_URL	Captchas base URL’ini ezer. Varsayılan https://api.clearance.rest/captchas.

Oluşturulacak bir istemci yoktur; servisleri doğrudan çağırın.

Deadline ve iptal

Herhangi bir çağrıya timeout (milisaniye) verin. SDK bunu X-Service-Timeout olarak gönderir ve ayrıca onun biraz üstünde kendi limitini uygular; böylece ölü bir ağ bir çağrıyı sonsuza kadar asılı bırakamaz. SDK yeniden denemez.

Her metot, çağrıyı iptal etmek için signal olarak bir AbortSignal de kabul eder.

const controller = new AbortController();
setTimeout(() => controller.abort(), 5000);

await clearanceRest.emails.wait({ emailAccount: 'a@b.com', timeout: 60000, signal: controller.signal });

Parametreleri camelCase ya da snake_case yazabilirsiniz.

Captchas

const solution = await clearanceRest.captchas.resolve({
  provider: 'capsolver',
  task: { type: 'ImageToTextTask', body: '<base64 image>' },
  timeout: 30000,
});

console.log(solution.value); // hangi çözücü yanıtladıysa token ya da metin
console.log(solution);       // tam yanıt: { jobId, waitedMs, solution: { text }, … }

Çağrı döndüğünde solution.value her zaman doludur. Rehber: Captcha çözme.

Emails

const email = await clearanceRest.emails.wait({
  emailAccount: 'user@domain.com',
  matchRegex: 'Verification',
  codeRegex: '\\d{6}',
  timeout: 45000,
});
console.log(email.code, email.subject, email.text);

codeRegex verirseniz ve kod çıkarılamazsa çağrı code: null döndürmek yerine ChallengeNoResultError fırlatır. Yalnızca e-postaya ihtiyacınız varsa ve kod isteğe bağlıysa requireCode: false verin.

Bir Gmail ya da Outlook posta kutusu bağlama:

const { authorize_url } = await clearanceRest.emails.oauthStart({
  provider: 'gmail',
  returnUrl: 'https://app.example.com/settings/mailboxes',
  clientState: 'user-42',
});

const result = await clearanceRest.emails.oauthResult({ provider: 'gmail', token });
const { accounts } = await clearanceRest.emails.accounts({ provider: 'gmail' });
await clearanceRest.emails.disconnect({ provider: 'gmail', email: 'a@b.com' });

Posta kutusu bağlı değilse disconnect, status değeri 404 olan bir request hatası fırlatır. Rehberler: E-posta bekleme ve Posta kutusu bağlama.

Numbers

const sms = await clearanceRest.numbers.wait({
  number: '+14155550100',
  timestamp: Date.now(),
  sender: '+15559998888',
  codeRegex: '\\d{6}',
  timeout: 30000,
});
console.log(sms.code, sms.body);

Kiralama ve bırakma. rent varsayılan olarak provider: 'herosms' kullanır:

const { number } = await clearanceRest.numbers.rent({ service: 'tg', country: 6 });
const sms = await clearanceRest.numbers.wait({ number: number.phoneNumber, codeRegex: '\\d{4,6}', timeout: 120000 });
await clearanceRest.numbers.release({ sid: number.sid });

const { numbers } = await clearanceRest.numbers.list({ sync: true });

quantity 1’den büyükse sonuç her zaman { numbers: [{ success, number | error }] } olur.

Hero SMS referans verisi ve tek çağrıda “fiyata bak, sonra kirala”:

const { countries } = await clearanceRest.numbers.countries();
const { services }  = await clearanceRest.numbers.services({ country: 6 });
const { prices }    = await clearanceRest.numbers.prices({ country: 6, service: 'tg' });
const { operators } = await clearanceRest.numbers.operators({ country: 6 });

// Perakende fiyatla bir numara kiralar. Stokta hiçbir şey yoksa kiralamadan bir request
// hatası fırlatır.
const cheapest = await clearanceRest.numbers.rentCheapest({ service: 'tg', country: 6 });

await clearanceRest.numbers.resend({ sid: number.sid }); // Hero SMS'ten SMS'i tekrar iste

Twilio:

const { numbers } = await clearanceRest.numbers.availables({ country: 'US', sms: true });
await clearanceRest.numbers.rent({ provider: 'twilio', phoneNumbers: ['+14155550100'] });

Mobil numaralar:

// Tek seferlik token ve QR payload'ı, 30 saniye geçerli.
const { token, qr_payload } = await clearanceRest.numbers.claimToken({ label: 'agency-1' });

// Tek kullanımlık bir bilet almak için HTTP çağrısı yapar ve tarayıcıya vermek güvenli bir
// ws URL'i döndürür: API anahtarınızı değil, bileti taşır.
const socketUrl = await clearanceRest.numbers.claimSocketUrl({ label: 'agency-1' });

// URL'i istek yapmadan oluşturur. Anahtar gerekmez.
const apkUrl = clearanceRest.numbers.downloadApkUrl();

Bilet tek kullanımlıktır; bu yüzden yeniden bağlanmak için yeni bir claimSocketUrl() gerekir. Rehberler: Hero SMS numaraları, Twilio numaraları ve Mobil numaralar.

SDK’da olmayanlar

SDK, kendi kodunuzdan yaptığınız çağrıları kapsar. Başka sistemlerin çağırdığı endpoint’ler (sağlayıcı webhook’ları, SIM Bridge uygulaması) sarılmamıştır. API referansında da yer almazlar.