AfroMessage Node js SDK

A complete Node js SDK for the AfroMessage SMS and OTP API.
This package makes it easy to send single SMS, bulk SMS, and handle OTP challenges with minimal setup.

🚀 Installation

Install the package via npm:

npm install afro-node

🔑 Quick Start

Create a .env file in your project root:

AFROMESSAGE_TOKEN=your_api_token_here
TEST_PHONE=+2519xxxxxxx
SENDER_ID=your_sender_id
SENDER_NAME=your_sender_name

Then in NOde js:

import 'dotenv/config';
import { AfroMessage } from 'afro-node';
import { SendSMSRequest, BulkSMSRequest, BulkRecipient } from 'afro-node/src/models/smsModels.js';
import { SendOTPRequest, VerifyOTPRequest } from 'afro-node/src/models/otpModels.js';

const token = process.env.AFROMESSAGE_TOKEN;

if (!token) {
  throw new Error('⚠️ Set AFROMESSAGE_TOKEN in your environment variables!');
}

const sdk = new AfroMessage(token);

// --- Single SMS ---
const smsRequest = new SendSMSRequest({
  to: process.env.TEST_PHONE,
  message: "Hello from AfroMessage Node.js SDK!",
  from: process.env.SENDER_ID,
  sender: process.env.SENDER_NAME
});
const response = await sdk.sms.send(smsRequest);
console.log("✅ Single SMS:", response);

// --- Bulk SMS ---
const bulkRequest = new BulkSMSRequest({
  to: [process.env.TEST_PHONE, "+2519yyyyyyy"],
  message: "Hello, bulk users!",
  from: process.env.SENDER_ID,
  sender: process.env.SENDER_NAME,
  campaign: "MyCampaign"
});
const bulkResponse = await sdk.sms.bulkSend(bulkRequest);
console.log("✅ Bulk SMS:", bulkResponse);

// --- Personalized Bulk SMS ---
const personalizedRequest = new BulkSMSRequest({
  to: [
    new BulkRecipient({ to: process.env.TEST_PHONE, message: "Hi Yonas!" }),
    new BulkRecipient({ to: "+2519yyyyyyy", message: "Hi Eshetu!" })
  ],
  from: process.env.SENDER_ID,
  sender: process.env.SENDER_NAME,
  campaign: "PersonalizedCampaign"
});
const personalizedResponse = await sdk.sms.bulkSend(personalizedRequest);
console.log("✅ Personalized Bulk SMS:", personalizedResponse);

// --- OTP Challenge ---
const otpRequest = new SendOTPRequest({
  to: process.env.TEST_PHONE,
  pr: "Your code"
});
const otpResponse = await sdk.otp.send(otpRequest);
console.log("✅ OTP Challenge:", otpResponse);

// --- Verify OTP ---
const verifyRequest = new VerifyOTPRequest({
  to: process.env.TEST_PHONE,
  code: "123456"
});
const verifyResponse = await sdk.otp.verify(verifyRequest);
console.log("✅ OTP Verify:", verifyResponse);

📦 Features

✅ Send single SMS

✅ Send bulk SMS campaigns

✅ Generate OTP challenges

✅ Verify OTP codes

✅ Built-in error handling

✅ Request/response logging for debugging

⚡ API Reference

Single SMS

import { SendSMSRequest } from 'afro-node/src/models/smsModels.js';

const smsRequest = new SendSMSRequest({
  to: "+2519xxxxxxx",
  message: "Hello from AfroMessage!",
  from: "MySender",
  sender: "MyBrand",
  callback: "https://myapp.com/callback" // optional
});

const response = await sdk.sms.send(smsRequest);

Single SMS (GET request)

const response = await sdk.sms.sendGet(smsRequest);

Bulk SMS

import { BulkSMSRequest } from 'afro-node/src/models/smsModels.js';

const bulkRequest = new BulkSMSRequest({
  to: ["+2519xxxxxxx", "+2519yyyyyyy"],
  message: "Hello, everyone!",
  from: "MySender",
  sender: "MyBrand",
  campaign: "MyCampaign"
});

const response = await sdk.sms.bulkSend(bulkRequest);

Bulk SMS (Personalized messages)

import { BulkRecipient, BulkSMSRequest } from 'afro-node/src/models/smsModels.js';

const personalizedRequest = new BulkSMSRequest({
  to: [
    new BulkRecipient({ to: "+2519xxxxxxx", message: "Hi Yonas!" }),
    new BulkRecipient({ to: "+2519yyyyyyy", message: "Hi Eshetu!" })
  ],
  from: "MySender",
  sender: "MyBrand",
  campaign: "PersonalizedCampaign"
});

const response = await sdk.sms.bulkSend(personalizedRequest);

OTP Challenge

import { SendOTPRequest } from 'afro-node/src/models/otpModels.js';

const otpRequest = new SendOTPRequest({
  to: "+2519xxxxxxx",
  pr: "Your code",
  ttl: 300 // time-to-live in seconds (optional)
});

const response = await sdk.otp.send(otpRequest);

Verify OTP

import { VerifyOTPRequest } from 'afro-node/src/models/otpModels.js';

const verifyRequest = new VerifyOTPRequest({
  to: "+2519xxxxxxx",
  code: "123456"
});

const response = await sdk.otp.verify(verifyRequest);

🛠 Error Handling

All errors are wrapped and logged automatically.

Example:

try {
  const response = await sdk.sms.send(smsRequest);
  console.log("✅ Success:", response);
} catch (error) {
  console.error("❌ Error:", error.message);
}

Errors include:

API errors (invalid request, authentication failure, etc.)

Network errors (timeouts, connection issues)

📑 Logging

Requests and responses are logged automatically. Example:

📤 [POST] Request to: send
   Payload: {
     "to": "+2519xxxxxxx",
     "message": "Hello!"
   }

📥 Response from: send
   Data: {
     "acknowledge": "success",
     "response": { "code": "202", "to": "+2519xxxxxxx" }
   }

🧪 Advanced Example (Real Test)

We provide a full interactive test script in examples/realTest.py

.

It shows how to send SMS, bulk SMS, and run OTP challenge + verification with .env loading.

Run it with:

node examples/realTest.js

⚠️ Note: Running this will send real SMS/OTP messages and may incur costs.

🤝 Contributing

Contributions are welcome! To contribute:

1. Fork the repo

2. Create your feature branch (git checkout -b feature/my-feature)

3. Commit your changes (git commit -m 'Add my feature')

4. Push to the branch (git push origin feature/my-feature)

5. Open a Pull Request

Run tests before submitting:

npm test

📜 License

This project is licensed under the MIT License.

See LICENSE

for details.

🙋 Support

For issues or feature requests, open a GitHub Issue