@smstwins/sdk

Official TypeScript/JavaScript client for the SMSTwins SMS verification API.

• Request virtual numbers for OTP / SMS verification
• Poll activations and wait for codes
• Cancel activations and check balance
• Optional Simple API helper for script-style integrations

Full API reference: smstwins.com/docs · SDK section: smstwins.com/docs#sdks

Install

npm install @smstwins/sdk

Quick start

import { SMSTwinsClient } from '@smstwins/sdk';

const client = new SMSTwinsClient({
  apiKey: process.env.SMSTWINS_API_KEY!,
  // baseUrl: 'https://smstwins.com/v1', // optional; defaults to https://api.smstwins.com/v1
});

const balance = await client.getBalance();
console.log('Balance:', balance);

const activation = await client.requestNumber('tg', 6); // Telegram, Indonesia (catalog id 6)
console.log('Number:', activation.phone);

const code = await client.waitForCode(activation.id);
console.log('OTP:', code);

Create an API key in the customer dashboard (sk_live_… for live purchases).

Authentication

By default, authStyle: 'auto' sends:

• Authorization: Bearer … when the key starts with sk_live_
• Authorization: ApiKey … otherwise

Override with authStyle: 'bearer' | 'apiKey' | 'x-api-key' if needed.

API

| Method | Description | |--------|-------------| | getBalance() | Account balance (USD) | | requestNumber(service, country, options?) | Buy a temporary number | | getActivation(id) | Activation status and SMS payload | | cancelActivation(id) | Cancel if eligible (no code received) | | waitForCode(id, timeoutMs?, intervalMs?) | Poll until OTP arrives | | simple(action, params?) | SMSTwins Simple API (/v1/simple) |

service is a service code (e.g. tg, wa, go). country is the catalog country id from docs/countries.

Simple API example

const text = await client.simple('getBalance');
console.log(text);

Errors

Failed requests throw SMSTwinsError with message and HTTP status.

Development

From the monorepo root:

npm run build --workspace=@smstwins/sdk

License

MIT