Envoi de SMS en TypeScript : API de la bibliothèque sms-client-ts

Bibliothèque sms-client-ts : envoi de SMS via TypeScript

Dans le développement web moderne, l'envoi de messages SMS reste une fonctionnalité très demandée — de l'authentification à deux facteurs aux notifications de statut de commande. Pour l'écosystème TypeScript, il existe une bibliothèque pratique sms-client-ts, qui fournit une interface typée pour travailler avec les fournisseurs de SMS populaires. Dans cet article, nous allons détailler son API, sa configuration et les scénarios d'utilisation typiques.

Installation et connexion

La bibliothèque est distribuée via npm. Installez-la dans votre projet avec la commande suivante :

npm install sms-client-ts

Après l'installation, importez la classe principale SmsClient :

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

Configuration du client

Pour travailler avec n'importe quel fournisseur, vous devez passer un objet de configuration. La bibliothèque prend en charge plusieurs services : Twilio, Vonage (Nexmo), SMSC.ru et d'autres. Exemple de configuration pour Twilio :

const client = new SmsClient({\n  provider: 'twilio',\n  credentials: {\n    accountSid: process.env.TWILIO_ACCOUNT_SID,\n    authToken: process.env.TWILIO_AUTH_TOKEN,\n    from: '+1234567890' // numéro de l'expéditeur\n  }\n});

Pour le fournisseur russe SMSC.ru, la configuration sera différente :

const clientSMSC = new SmsClient({\n  provider: 'smscru',\n  credentials: {\n    login: 'your_login',\n    password: 'your_password',\n    sender: 'MyBrand' // nom de l'expéditeur\n  }\n});

Méthodes principales de l'API

La bibliothèque fournit trois méthodes clés pour travailler avec les SMS. Examinons chacune d'elles.

1. Envoi d'un seul message

La méthode sendSingle prend le numéro du destinataire et le texte du message. Elle retourne une Promise avec un objet résultat.

async function sendWelcomeSms(phone: string, name: string) {\n  try {\n    const result = await client.sendSingle({\n      to: phone,\n      text: `Bonjour, ${name} ! Bienvenue dans notre service.`\n    });\n    console.log('SMS envoyé :', result.messageId);\n  } catch (error) {\n    console.error('Erreur d\'envoi :', error);\n  }\n}\n\nsendWelcomeSms('+33123456789', 'Jean');

2. Envoi groupé

Pour envoyer le même message à plusieurs destinataires, utilisez la méthode sendBulk. Elle prend un tableau de numéros.

async function sendPromoSms(phones: string[]) {\n  const result = await client.sendBulk({\n    to: phones,\n    text: 'Offre spéciale aujourd\'hui seulement ! -20% sur tous les articles.'\n  });\n  \n  console.log(`Envoyé avec succès : ${result.successCount}`);\n  console.log(`Erreurs : ${result.failCount}`);\n  if (result.errors.length > 0) {\n    result.errors.forEach(err => {\n      console.error(`Erreur pour ${err.phone} : ${err.message}`);\n    });\n  }\n}\n\nsendPromoSms(['+33123456789', '+33176543210']);

3. Vérification du statut de livraison

Après l'envoi, vous pouvez vérifier le statut du message via son ID. La méthode getStatus retourne l'état actuel.

async function checkDelivery(messageId: string) {\n  const status = await client.getStatus(messageId);\n  console.log(`Statut du message ${messageId} : ${status.state}`);\n  // Valeurs possibles : 'pending', 'delivered', 'failed', 'unknown'\n  \n  if (status.state === 'failed') {\n    console.log('Raison de l\'erreur :', status.errorMessage);\n  }\n}\n\ncheckDelivery('SM123456789');

Gestion des erreurs et typage

La bibliothèque fournit ses propres types d'erreurs, ce qui est pratique pour les développeurs TypeScript. Toutes les exceptions héritent de la classe de base SmsError.

import { SmsError, ValidationError, AuthError, ProviderError } from 'sms-client-ts';\n\nasync function safeSend(phone: string, text: string) {\n  try {\n    return await client.sendSingle({ to: phone, text });\n  } catc