Envío de SMS en TypeScript: API de la biblioteca sms-client-ts

Biblioteca sms-client-ts: envío de SMS a través de TypeScript

En el desarrollo web moderno, el envío de mensajes SMS sigue siendo una función demandada, desde la autenticación de dos factores hasta las notificaciones de estado de pedidos. Para el ecosistema TypeScript existe la práctica biblioteca sms-client-ts, que proporciona una interfaz con seguridad de tipos para trabajar con proveedores de SMS populares. En este artículo analizaremos su API, configuración y casos de uso típicos.

Instalación y configuración

La biblioteca se distribuye a través de npm. Instálela en su proyecto con el siguiente comando:

npm install sms-client-ts

Después de la instalación, importe la clase principal SmsClient:

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

Configuración del cliente

Para trabajar con cualquier proveedor, es necesario pasar un objeto de configuración. La biblioteca admite varios servicios: Twilio, Vonage (Nexmo), SMSC.ru y otros. Ejemplo de configuración para Twilio:

const client = new SmsClient({  provider: 'twilio',  credentials: {    accountSid: process.env.TWILIO_ACCOUNT_SID,    authToken: process.env.TWILIO_AUTH_TOKEN,    from: '+1234567890' // número del remitente  }});

Para el proveedor ruso SMSC.ru, la configuración será diferente:

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

Métodos principales de la API

La biblioteca proporciona tres métodos clave para trabajar con SMS. Veamos cada uno de ellos.

1. Envío de un solo mensaje

El método sendSingle recibe el número del destinatario y el texto del mensaje. Devuelve una Promise con un objeto de resultado.

async function sendWelcomeSms(phone: string, name: string) {  try {    const result = await client.sendSingle({      to: phone,      text: `Hola, ${name}! Bienvenido a nuestro servicio.`    });    console.log('SMS enviado:', result.messageId);  } catch (error) {    console.error('Error al enviar:', error);  }}

sendWelcomeSms('+79161234567', 'Iván');

2. Envío masivo

Para enviar el mismo mensaje a varios destinatarios, use el método sendBulk. Recibe un array de números.

async function sendPromoSms(phones: string[]) {  const result = await client.sendBulk({    to: phones,    text: '¡Oferta especial solo hoy! 20% de descuento en todos los productos.'  });    console.log(`Enviados exitosamente: ${result.successCount}`);  console.log(`Errores: ${result.failCount}`);  if (result.errors.length > 0) {    result.errors.forEach(err => {      console.error(`Error para ${err.phone}: ${err.message}`);    });  }}

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

3. Verificación del estado de entrega

Después del envío, puede verificar el estado del mensaje por su ID. El método getStatus devuelve el estado actual.

async function checkDelivery(messageId: string) {  const status = await client.getStatus(messageId);  console.log(`Estado del mensaje ${messageId}: ${status.state}`);  // Valores posibles: 'pending', 'delivered', 'failed', 'unknown'    if (status.state === 'failed') {    console.log('Motivo del error:', status.errorMessage);  }}

checkDelivery('SM123456789');

Manejo de errores y tipificación

La biblioteca proporciona sus propios tipos de error, lo cual es conveniente para los desarrolladores de TypeScript. Todas las excepciones heredan de la clase base 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