@xyz/sms

A unified library to send SMS - Choose your own SMS provider.

Features

• 🔌 Unified interface for multiple SMS providers
• 📝 TypeScript support with full type definitions
• 🔄 Easy to switch between providers without changing your code
• 🚀 Works with Node.js, Bun, Deno, and Cloudflare Workers

Supported Providers

| Provider | Environment Variables | |----------|----------------------| | Twilio | TWILIO_ACCOUNT_SID, TWILIO_AUTH_TOKEN | | Vonage | VONAGE_API_KEY, VONAGE_API_SECRET | | MessageBird | MESSAGEBIRD_API_KEY | | Plivo | PLIVO_AUTH_ID, PLIVO_AUTH_TOKEN | | BulkSMS | BULKSMS_TOKEN, BULKSMS_SENDER_ID, BULKSMS_API_URL (optional) | | Console | (none - logs to console) | | Custom | (implement your own) |

Installation

# npm
npm install @xyz/sms

# pnpm
pnpm add @xyz/sms

# yarn
yarn add @xyz/sms

# bun
bun add @xyz/sms

Environment Variables

Create a .env file with the appropriate variables for your chosen provider:

# Twilio
TWILIO_ACCOUNT_SID=ACxxxxxxxxxxxx
TWILIO_AUTH_TOKEN=xxxxxxxxxxxx

# Vonage (formerly Nexmo)
VONAGE_API_KEY=xxxxxxxxxxxx
VONAGE_API_SECRET=xxxxxxxxxxxx

# MessageBird
MESSAGEBIRD_API_KEY=xxxxxxxxxxxx

# Plivo
PLIVO_AUTH_ID=xxxxxxxxxxxx
PLIVO_AUTH_TOKEN=xxxxxxxxxxxx

# BulkSMS
BULKSMS_TOKEN=xxxxxxxxxxxx
BULKSMS_SENDER_ID=YourSenderID
BULKSMS_API_URL=https://api.bulksms.com/v1/messages  # optional

Usage

import { useSMS } from "@xyz/sms";

// Choose your provider
const smsService = useSMS("twilio");

// Send an SMS
await smsService.send({
  from: "+1234567890",
  to: "+0987654321",
  text: "Hello from @xyz/sms!",
});

Sending to Multiple Recipients

await useSMS("messagebird").send({
  from: "+1234567890",
  to: ["+1111111111", "+2222222222"],
  text: "Hello team!",
});

Switching Providers

const twilio = useSMS("twilio");
const vonage = useSMS("vonage");
const messagebird = useSMS("messagebird");
const plivo = useSMS("plivo");
const bulksms = useSMS("bulksms");
const consoleLogger = useSMS("console"); // For development

API Reference

useSMS(provider: SMSProviderName)

Creates an SMS service instance for the specified provider.

Parameters:

• provider: One of "twilio" | "vonage" | "messagebird" | "plivo" | "bulksms" | "console" | "custom"

Returns:

• An SMS service instance with a send method

send(options: SendSMSParams)

Sends an SMS using the configured provider.

Parameters:

| Property | Type | Required | Description | |----------|------|----------|-------------| | from | string | ✅ | Sender phone number or ID | | to | string \| string[] | ✅ | Recipient phone number(s) | | text | string | ✅ | Message content |

Returns:

• Promise<void>

Error Handling

try {
  await useSMS("twilio").send({
    from: "+1234567890",
    to: "+0987654321",
    text: "Hello World",
  });
  console.log("SMS sent successfully");
} catch (error) {
  console.error("Failed to send SMS:", error);
}

TypeScript Support

This package is written in TypeScript and provides type definitions out of the box.

import { useSMS, type SendSMSParams, type SMSProviderName } from "@xyz/sms";

const provider: SMSProviderName = "twilio";
const options: SendSMSParams = {
  from: "+1234567890",
  to: "+0987654321",
  text: "Hello!",
};

await useSMS(provider).send(options);

License

MIT