luosimao-sms (Luosimao Node.js SDK)

Luosimao 短信服务的 Node.js SDK。提供短信发送、批量发送、余额查询等功能，并内置了自动重试机制与完善的错误码处理。

特性

• 自动重试: 仅对幂等请求（GET，如查询余额）遭遇网络抖动或 5xx 错误时自动进行指数退避重试；POST 发短信请求不自动重试，避免重复发送。
• 签名封装: 自动处理 Basic Auth 认证逻辑，开发者只需提供 API Key，无需手动拼接 api:key- 字符串。
• 统一错误处理: 提供详细的错误枚举类和自定义 LuosimaoError，方便业务层捕获处理。
• 高覆盖率测试: 提供单元测试保证核心逻辑的可靠性。

安装

npm install luosimao-sms

快速开始

初始化

const { LuosimaoClient, LuosimaoError } = require('luosimao-sms');

// 使用你的 API_KEY 初始化客户端,api key可在官网后台获取
const client = new LuosimaoClient('your_api_key_here', {
  timeout: 5000, // 可选：请求超时时间，默认 5000ms，传入 0 可禁用超时
  retries: 3     // 可选：失败重试次数，默认 3 次（仅对 GET 查询请求生效）
});

1. 单条发送短信

async function sendSingleSMS() {
  try {
    const res = await client.send('13761528267', '验证码：321123【铁壳测试】');
    console.log('发送成功:', res);
  } catch (err) {
    if (err instanceof LuosimaoError) {
      console.error(`发送失败，错误码: ${err.code}, 原因: ${err.message}`);
    } else {
      console.error('未知错误:', err);
    }
  }
}

// 定时发送（可选）
async function sendScheduledSMS() {
  const res = await client.send('13761528267', '验证码：321123【铁壳测试】', '2026-04-01 12:30:00');
  console.log('定时发送成功:', res);
}

2. 批量发送短信

async function sendBatchSMS() {
  try {
    // 手机号支持数组或逗号分隔的字符串
    const mobiles = ['13761528267', '18521513391']; 
    const message = '提醒：您的账号即将到期，请及时充值【铁壳测试】';
    // const time = '2026-04-01 12:30:00'; // 可选的定时发送时间
    
    const res = await client.sendBatch(mobiles, message);
    console.log('批量发送成功，批次号:', res.batch_id);
  } catch (err) {
    console.error('批量发送失败:', err);
  }
}

3. 查询账户余额

async function checkStatus() {
  try {
    const res = await client.getStatus();
    console.log(`当前余额: ${res.deposit} 条`);
  } catch (err) {
    console.error('查询余额失败:', err);
  }
}

错误码说明

所有的 API 级错误均会抛出 LuosimaoError。您可以通过 err.code 捕获以下错误：

| 错误码 | 错误描述 | 解决方案 | |---|---|---| | -10 | 验证信息失败 | 检查 api key 是否和各种中心内的一致，调用传入是否正确 | | -11 | 用户接口被禁用 | 滥发违规内容，验证码被刷等，请联系客服解除 | | -12 | 余额冻结 | 长期未使用或其他原因，冻结触发接口，可在后台解冻 | | -20 | 短信余额不足 | 进入个人中心购买充值 | | -30 | 短信内容为空 | 检查调用传入参数：message | | -31 | 短信内容存在敏感词 | LuosimaoError 会包含 err.hit 属性提供敏感词说明 | | -32 | 短信内容缺少签名信息 | 短信内容末尾增加签名信息 eg.【公司名称】 | | -33 | 短信过长 | 超过300字（含签名），调整短信内容或拆分 | | -34 | 签名不可用 | 在后台 短信->签名管理下进行添加签名 | | -35 | 测试签名受限 | 测试签名使用达到上限，请在短信后台添加签名并进行替换 | | -40 | 错误的手机号 | 检查手机号是否正确 | | -41 | 号码在黑名单中 | 号码因频繁发送或其他原因暂停发送，请联系客服确认 | | -42 | 验证码类短信发送频率过快 | 前台增加60秒获取限制 | | -50 | 请求发送IP不在白名单内 | 查看触发短信IP白名单的设置 |

运行测试

克隆代码仓库后，您可以运行以下命令执行单元测试：

npm install
npm run test

参考文档

Luosimao API 官方文档: https://luosimao.com/docs/api/