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:

``

bash

npm install afro-node



🔑 Quick Start

Create a .env file in your project root:

bash

AFROMESSAGE_TOKEN=your_api_token_here

TEST_PHONE=+2519xxxxxxx

SENDER_ID=your_sender_id

SENDER_NAME=your_sender_name



Then in NOde js:

bash

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

bash

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)

bash

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



Bulk SMS

bash

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)

bash

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

bash

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

bash

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:

bash

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:

bash

📤 [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:

bash

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:

bash

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

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:

``

bash

npm install afro-node



🔑 Quick Start

Create a .env file in your project root:

bash

AFROMESSAGE_TOKEN=your_api_token_here

TEST_PHONE=+2519xxxxxxx

SENDER_ID=your_sender_id

SENDER_NAME=your_sender_name



Then in NOde js:

bash

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

bash

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)

bash

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



Bulk SMS

bash

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)

bash

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

bash

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

bash

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:

bash

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:

bash

📤 [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:

bash

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:

bash

npm test