Envio de SMS em TypeScript: API da biblioteca sms-client-ts

Biblioteca sms-client-ts: envio de SMS via TypeScript

No desenvolvimento web moderno, o envio de mensagens SMS continua sendo uma funcionalidade muito requisitada — desde a autenticação de dois fatores até notificações de status de pedidos. Para o ecossistema TypeScript, existe uma biblioteca conveniente chamada sms-client-ts, que fornece uma interface type-safe para trabalhar com provedores de SMS populares. Neste artigo, vamos analisar sua API, configuração e cenários de uso típicos.

Instalação e importação

A biblioteca é distribuída via npm. Instale-a em seu projeto com o seguinte comando:

npm install sms-client-ts

Após a instalação, importe a classe principal SmsClient:

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

Configuração do cliente

Para trabalhar com qualquer provedor, é necessário passar um objeto de configuração. A biblioteca suporta vários serviços: Twilio, Vonage (Nexmo), SMSC.ru e outros. Exemplo de configuração 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 do remetente  }});

Para o provedor russo SMSC.ru, a configuração será diferente:

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

Principais métodos da API

A biblioteca fornece três métodos principais para trabalhar com SMS. Vamos analisar cada um deles.

1. Envio de uma única mensagem

O método sendSingle recebe o número do destinatário e o texto da mensagem. Retorna uma Promise com um objeto de resultado.

async function sendWelcomeSms(phone: string, name: string) {  try {    const result = await client.sendSingle({      to: phone,      text: `Olá, ${name}! Bem-vindo ao nosso serviço.`    });    console.log('SMS enviado:', result.messageId);  } catch (error) {    console.error('Erro ao enviar:', error);  }}

sendWelcomeSms('+5511912345678', 'João');

2. Envio em massa

Para enviar a mesma mensagem para vários destinatários, use o método sendBulk. Ele recebe um array de números.

async function sendPromoSms(phones: string[]) {  const result = await client.sendBulk({    to: phones,    text: 'Oferta especial apenas hoje! 20% de desconto em todos os produtos.'  });    console.log(`Enviados com sucesso: ${result.successCount}`);  console.log(`Erros: ${result.failCount}`);  if (result.errors.length > 0) {    result.errors.forEach(err => {      console.error(`Erro para ${err.phone}: ${err.message}`);    });  }}

sendPromoSms(['+5511912345678', '+5511976543210']);

3. Verificação do status de entrega

Após o envio, você pode verificar o status da mensagem pelo seu ID. O método getStatus retorna o estado atual.

async function checkDelivery(messageId: string) {  const status = await client.getStatus(messageId);  console.log(`Status da mensagem ${messageId}: ${status.state}`);  // Valores possíveis: 'pending', 'delivered', 'failed', 'unknown'    if (status.state === 'failed') {    console.log('Motivo do erro:', status.errorMessage);  }}

checkDelivery('SM123456789');

Tratamento de erros e tipagem

A biblioteca fornece seus próprios tipos de erro, o que é conveniente para desenvolvedores TypeScript. Todas as exceções herdam da classe 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