使用 TypeScript 发送短信：sms-client-ts API 库

sms-client-ts 库：通过 TypeScript 发送短信

在现代 Web 开发中，发送短信仍然是一项受欢迎的功能——从双因素认证到订单状态通知。对于 TypeScript 生态系统，有一个方便的库 sms-client-ts，它提供了一个类型安全的接口，用于与流行的短信供应商协作。在本文中，我们将分析其 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 方法

该库提供了三个用于处理短信的关键方法。让我们逐一介绍。

1. 发送单条消息

sendSingle 方法接收收件人号码和消息文本。返回一个包含结果对象的 Promise。

async function sendWelcomeSms(phone: string, name: string) {  try {    const result = await client.sendSingle({      to: phone,      text: `您好，${name}！欢迎使用我们的服务。`    });    console.log('短信已发送：', 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('认证错误：请检查凭据');    } else if (error instanceof ProviderError) {      console.error('供应商错误：', error.providerMessage);    } else {      console.error('未知错误：', error);    }  }}