devcode-sms

Official Node.js client for the DevCode SMS API.

Send single or bulk SMS messages and check your account balance — zero external dependencies, full TypeScript support.

Features

• ✉️ Send a single SMS to any phone number
• 📦 Bulk SMS — send to multiple recipients in parallel
• 💳 Check balance — query remaining SMS credits
• 🔒 Zero dependencies — uses Node.js built-in https
• 📘 Full TypeScript — bundled .d.ts definitions
• 🧪 Testable — injectable base URL for unit tests

Installation

npm install devcode-sms

Quick start

CommonJS

const { DevcodeSms } = require('devcode-sms');

const sms = new DevcodeSms({ apiKey: 'YOUR_API_KEY' });

ESM / TypeScript

import { DevcodeSms, DevcodeSmsError } from 'devcode-sms';

const sms = new DevcodeSms({ apiKey: 'YOUR_API_KEY' });

Usage

Send a single SMS

try {
  const result = await sms.sendSms({
    sender: 'MyApp',         // Sender ID (max ~11 alphanumeric chars)
    phone: '+237659373726',  // International format
    message: 'Hello from Node.js!',
  });

  if (result.isSuccess) {
    console.log('SMS sent!', result.message);
  } else {
    console.warn('API error:', result.message);
  }
} catch (err) {
  if (err instanceof DevcodeSmsError) {
    console.error(`[${err.statusCode}] ${err.message}`);
  }
}

Send bulk SMS

const results = await sms.sendBulkSms({
  sender: 'MyApp',
  phones: ['+237659000001', '+237659000002', '+237659000003'],
  message: 'Promotional offer just for you!',
});

const sent = results.filter(r => r.isSuccess).length;
console.log(`${sent} / ${results.length} SMS delivered.`);

Check balance

const balance = await sms.getBalance();

if (balance.isSuccess) {
  console.log(`Remaining credits: ${balance.balance} SMS`);
}

API Reference

new DevcodeSms(options)

| Option | Type | Required | Default | Description | |-----------|----------|----------|------------------------------------------------|--------------------------| | apiKey | string | ✅ | — | Your DevCode SMS API key | | baseUrl | string | No | https://devcodesms.com/developpeur | Override for testing |

sms.sendSms({ sender, phone, message })

Returns Promise<SmsResponse>.

sms.sendBulkSms({ sender, phones, message })

Returns Promise<SmsResponse[]>. Individual failures resolve with isSuccess: false.

sms.getBalance()

Returns Promise<BalanceResponse>.

Response shapes

SmsResponse

{
  status: number;    // 200 = success
  code: string;      // "Success" | "Erreur" | ...
  message: string;   // Human-readable result
  isSuccess: boolean;
}

BalanceResponse

{
  status: number;
  code: string;
  balance: number;   // Remaining SMS credits
  message: string;
  isSuccess: boolean;
}

Error handling

All methods throw DevcodeSmsError on failure:

import { DevcodeSmsError } from 'devcode-sms';

try {
  await sms.sendSms({ ... });
} catch (err) {
  if (err instanceof DevcodeSmsError) {
    console.error(err.message);      // Human-readable description
    console.error(err.statusCode);   // HTTP code or null
    console.error(err.rawResponse);  // Raw server body (for debugging)
  }
}

Testing

Run the built-in test suite (no extra tools needed):

npm test

Get your API key

1. Create an account at devcodesms.com
2. Subscribe to an SMS plan
3. Generate your key in the API Key section

Support

• 📧 [email protected]
• 📞 (+237) 659 373 726
• 🌐 devcodesms.com

License

BSD-3-Clause © 2024 DevCode SMS