Node.js SDK

@clearance-rest/sdk wraps the Numbers, Emails and Captchas APIs. Every call sends your API key, sets a hard deadline, and turns failures into typed errors.

Install

npm install @clearance-rest/sdk

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

Configure

Set your API key in the environment. The SDK sends it as X-API-Key on every request.

export CLEARANCE_REST_API_KEY=cr_live_...

Without it, no key is sent and the API answers 401.

Variable	Purpose
CLEARANCE_REST_API_KEY	Your project’s API key.
CLEARANCE_REST_NUMBERS_URL	Override the Numbers base URL. Default https://api.clearance.rest/numbers.
CLEARANCE_REST_EMAILS_URL	Override the Emails base URL. Default https://api.clearance.rest/emails.
CLEARANCE_REST_CAPTCHAS_URL	Override the Captchas base URL. Default https://api.clearance.rest/captchas.

There is no client to construct; call the services directly.

Deadlines and cancellation

Pass timeout (milliseconds) to any call. The SDK sends it as X-Service-Timeout and also enforces its own limit slightly above it, so a dead network can never hang a call forever. The SDK does not retry.

Every method also accepts an AbortSignal as signal to cancel the call.

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

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

Parameters can be written in camelCase or snake_case.

Captchas

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

console.log(solution.value); // the token or text, whichever solver answered
console.log(solution);       // the full response: { jobId, waitedMs, solution: { text }, … }

solution.value is always set when the call returns. Guide: Solving captchas.

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

If you pass codeRegex and no code can be extracted, the call throws ChallengeNoResultError rather than returning code: null. If you only need the email and the code is optional, pass requireCode: false.

Connecting a Gmail or Outlook mailbox:

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' });

disconnect throws a request error with status 404 if the mailbox was not connected. Guides: Waiting for an email and Connecting a mailbox.

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

Renting and releasing. rent defaults to provider: 'herosms':

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 });

With quantity greater than 1, the result is always { numbers: [{ success, number | error }] }.

Hero SMS reference data, and a one-call “check price then rent”:

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 });

// Rents one number at the retail price. Throws a request error, without renting,
// when nothing is in stock.
const cheapest = await clearanceRest.numbers.rentCheapest({ service: 'tg', country: 6 });

await clearanceRest.numbers.resend({ sid: number.sid }); // ask Hero SMS to resend the SMS

Twilio:

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

Mobile numbers:

// One-off token and QR payload, valid for 30 seconds.
const { token, qr_payload } = await clearanceRest.numbers.claimToken({ label: 'agency-1' });

// Makes an HTTP call to get a single-use ticket, and returns a ws URL that is
// safe to hand to a browser: it carries the ticket, not your API key.
const socketUrl = await clearanceRest.numbers.claimSocketUrl({ label: 'agency-1' });

// Builds the URL without making a request. No key needed.
const apkUrl = clearanceRest.numbers.downloadApkUrl();

A ticket is single-use, so a reconnect needs a fresh claimSocketUrl(). Guides: Hero SMS numbers, Twilio numbers and Mobile numbers.

What is not in the SDK

The SDK covers the calls you make from your own code. The endpoints that other systems call (provider webhooks, the SIM Bridge app) are not wrapped. They are also absent from the API reference.