Отправка SMS на TypeScript: API библиотеки sms-client-ts |…

Библиотека sms-client-ts: отправка SMS через TypeScript

В современном веб-разработке отправка SMS-сообщений остаётся востребованной функцией — от двухфакторной аутентификации до уведомлений о статусе заказа. Для экосистемы TypeScript существует удобная библиотека sms-client-ts, которая предоставляет типобезопасный интерфейс для работы с популярными SMS-провайдерами. В этой статье мы разберём её API, настройку и типичные сценарии использования.

Установка и подключение

Библиотека распространяется через npm. Установите её в ваш проект следующей командой:

npm install sms-client-ts

После установки импортируйте основной класс SmsClient:

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

Конфигурация клиента

Для работы с любым провайдером необходимо передать объект конфигурации. Библиотека поддерживает несколько сервисов: Twilio, Vonage (Nexmo), SMSC.ru и других. Пример настройки для Twilio:

const client = new SmsClient({
  provider: 'twilio',
  credentials: {
    accountSid: process.env.TWILIO_ACCOUNT_SID,
    authToken: process.env.TWILIO_AUTH_TOKEN,
    from: '+1234567890' // номер отправителя
  }
});

Для российского провайдера SMSC.ru конфигурация будет выглядеть иначе:

const clientSMSC = new SmsClient({
  provider: 'smscru',
  credentials: {
    login: 'your_login',
    password: 'your_password',
    sender: 'MyBrand' // имя отправителя
  }
});

Основные методы API

Библиотека предоставляет три ключевых метода для работы с SMS. Рассмотрим каждый из них.

1. Отправка одного сообщения

Метод sendSingle принимает номер получателя и текст сообщения. Возвращает Promise с объектом результата.

async function sendWelcomeSms(phone: string, name: string) {
  try {
    const result = await client.sendSingle({
      to: phone,
      text: `Здравствуйте, ${name}! Добро пожаловать в наш сервис.`
    });
    console.log('SMS отправлено:', result.messageId);
  } catch (error) {
    console.error('Ошибка отправки:', error);
  }
}

sendWelcomeSms('+79161234567', 'Иван');

2. Массовая рассылка

Для отправки одного и того же сообщения нескольким получателям используйте метод sendBulk. Он принимает массив номеров.

async function sendPromoSms(phones: string[]) {
  const result = await client.sendBulk({
    to: phones,
    text: 'Специальное предложение только сегодня! Скидка 20% на все товары.'
  });
  
  console.log(`Успешно отправлено: ${result.successCount}`);
  console.log(`Ошибок: ${result.failCount}`);
  if (result.errors.length > 0) {
    result.errors.forEach(err => {
      console.error(`Ошибка для ${err.phone}: ${err.message}`);
    });
  }
}

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

3. Проверка статуса доставки

После отправки вы можете проверить статус сообщения по его ID. Метод getStatus возвращает текущее состояние.

async function checkDelivery(messageId: string) {
  const status = await client.getStatus(messageId);
  console.log(`Статус сообщения ${messageId}: ${status.state}`);
  // Возможные значения: 'pending', 'delivered', 'failed', 'unknown'
  
  if (status.state === 'failed') {
    console.log('Причина ошибки:', status.errorMessage);
  }
}

checkDelivery('SM123456789');

Обработка ошибок и типизация

Библиотека предоставляет собственные типы ошибок, что удобно для TypeScript-разработчиков. Все исключения наследуются от базового класса 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 });
  } catch (error) {
    if (error instanceof ValidationError) {
      console.error('Некорректный номер телефона:', error.message);
    } else if (error instanceof AuthError) {
      console.error('Ошибка аутентификации:', error.message);
    } else if (error instanceof ProviderError) {
      console.error('Проблема на стороне провайдера:', error.message);
    } else if (error instanceof SmsError) {
      console.error('Общая ошибка SMS:', error.message);
    } else {
      console.error('Неизвестная ошибка:', error);
    }
  }
}