Sending SMS in TypeScript: API of the sms-client-ts Library

sms-client-ts Library: Sending SMS via TypeScript

In modern web development, sending SMS messages remains a popular feature — from two-factor authentication to order status notifications. For the TypeScript ecosystem, there is a convenient library sms-client-ts that provides a type-safe interface for working with popular SMS providers. In this article, we will break down its API, setup, and typical usage scenarios.

Installation and Import

The library is distributed via npm. Install it into your project with the following command:

npm install sms-client-ts

After installation, import the main class SmsClient:

import { SmsClient } from 'sms-client-ts';

Client Configuration

To work with any provider, you need to pass a configuration object. The library supports several services: Twilio, Vonage (Nexmo), SMSC.ru, and others. Example setup for Twilio:

const client = new SmsClient({  provider: 'twilio',  credentials: {    accountSid: process.env.TWILIO_ACCOUNT_SID,    authToken: process.env.TWILIO_AUTH_TOKEN,    from: '+1234567890' // sender number  }});

For the Russian provider SMSC.ru, the configuration will look different:

const clientSMSC = new SmsClient({  provider: 'smscru',  credentials: {    login: 'your_login',    password: 'your_password',    sender: 'MyBrand' // sender name  }});

Main API Methods

The library provides three key methods for working with SMS. Let's look at each of them.

1. Sending a Single Message

The sendSingle method takes the recipient's number and the message text. It returns a Promise with a result object.

async function sendWelcomeSms(phone: string, name: string) {  try {    const result = await client.sendSingle({      to: phone,      text: `Hello, ${name}! Welcome to our service.`    });    console.log('SMS sent:', result.messageId);  } catch (error) {    console.error('Sending error:', error);  }}

sendWelcomeSms('+79161234567', 'Ivan');

2. Bulk Sending

To send the same message to multiple recipients, use the sendBulk method. It accepts an array of numbers.

async function sendPromoSms(phones: string[]) {  const result = await client.sendBulk({    to: phones,    text: 'Special offer only today! 20% discount on all products.'  });    console.log(`Successfully sent: ${result.successCount}`);  console.log(`Errors: ${result.failCount}`);  if (result.errors.length > 0) {    result.errors.forEach(err => {      console.error(`Error for ${err.phone}: ${err.message}`);    });  }}

sendPromoSms(['+79161234567', '+79167654321']);

3. Checking Delivery Status

After sending, you can check the status of a message by its ID. The getStatus method returns the current state.

async function checkDelivery(messageId: string) {  const status = await client.getStatus(messageId);  console.log(`Status of message ${messageId}: ${status.state}`);  // Possible values: 'pending', 'delivered', 'failed', 'unknown'    if (status.state === 'failed') {    console.log('Error reason:', status.errorMessage);  }}

checkDelivery('SM123456789');

Error Handling and Typing

The library provides its own error types, which is convenient for TypeScript developers. All exceptions inherit from the base class SmsError.

import { SmsError, ValidationError, AuthError, ProviderError } from 'sms-client-ts';

async function safeSend(phone: string, text: string) {  try {    return await client.sendSingle({ to: phone, text });  } catc