fitsms 1.0.0

package/README.md

@@ -0,0 +1,106 @@
+# FitSMS Node.js SDK
+
+[![npm version](https://img.shields.io/npm/v/fitsms.svg)](https://www.npmjs.com/package/fitsms)
+[![license](https://img.shields.io/npm/l/fitsms.svg)](https://github.com/yourusername/fitsms)
+[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](https://github.com/yourusername/fitsms/pulls)
+
+A high-performance, Promise-based Node.js wrapper for the [FitSMS.lk](https://fitsms.lk) API. This SDK provides a clean interface for sending SMS, checking delivery status, and managing account balances.
+
+---
+
+## 🚀 Features
+
+- **Multi-Version Support**: Handles v3 (Messaging) and v4 (Account/Profile) endpoints.
+- **Bearer Token Auth**: Secure authentication via headers.
+- **Flexible Recipients**: Supports strings, comma-separated lists, and arrays.
+- **Real-time Status**: Retrieve delivery reports using message UIDs.
+- **Balance Monitoring**: Track remaining SMS units.
+- **Lightweight**: Minimal dependencies.
+
+---
+
+## 📦 Installation
+
+```bash
+npm install fitsms
+```
+
+---
+
+## 🛠 Usage
+
+### Initialization
+
+```js
+const FitSMS = require("fitsms");
+
+const sms = new FitSMS("YOUR_BEARER_TOKEN", "The Change");
+```
+
+---
+
+### Sending SMS
+
+```js
+async function sendAlert() {
+  try {
+    const recipients = ["94761695904", "94771234567"];
+
+    const response = await sms.send(
+      recipients,
+      "This is a test message from FitSMS SDK",
+    );
+
+    console.log("Success:", response.data.uid);
+  } catch (error) {
+    console.error("Error:", error.message);
+  }
+}
+```
+
+---
+
+### Checking Message Status
+
+```js
+const status = await sms.getStatus("606812e63f78b");
+console.log("Delivery Status:", status.data.status);
+```
+
+---
+
+### Checking Balance
+
+```js
+const balance = await sms.getBalance();
+console.log("Remaining Units:", balance.data);
+```
+
+---
+
+## 📖 API Reference
+
+| Method       | Parameters                | Description         |
+| ------------ | ------------------------- | ------------------- |
+| send()       | recipients, message, type | Sends an SMS        |
+| getStatus()  | uid                       | Get delivery status |
+| getBalance() | none                      | Get SMS balance     |
+| getProfile() | none                      | Get account profile |
+
+---
+
+## 📄 License
+
+This project is licensed under the MIT License.
+
+---
+
+## 🤝 Contributing
+
+Contributions, issues, and feature requests are welcome!
+
+---
+
+## 👨‍💻 Maintainer
+
+Maintained by **Danuja Dilanka**

package/index.js

@@ -0,0 +1,104 @@
+const axios = require("axios");
+
+class FitSMS {
+  /**
+   * @param {string} apiToken - Your Bearer Token
+   * @param {string} senderId - Your approved Sender ID (e.g., "The Change")
+   */
+  constructor(apiToken, senderId) {
+    if (!apiToken || !senderId) {
+      throw new Error("FitSMS: API Token and Sender ID are required.");
+    }
+    this.apiToken = apiToken;
+    this.senderId = senderId;
+
+    this.v3Base = "https://app.fitsms.lk/api/v3";
+
+    // Default Headers
+    this.headers = {
+      Authorization: `Bearer ${this.apiToken}`,
+      "Content-Type": "application/json",
+      Accept: "application/json",
+    };
+  }
+
+  /**
+   * Send an SMS (v3 API)
+   * @param {string|string[]} recipients - e.g., "9476111,9476222"
+   * @param {string} message - The SMS body
+   */
+  async send(recipients, message, type = "plain") {
+    const recipientList = Array.isArray(recipients)
+      ? recipients.join(",")
+      : recipients;
+
+    try {
+      const response = await axios.post(
+        `${this.v3Base}/sms/send`,
+        {
+          recipient: recipientList,
+          sender_id: this.senderId,
+          type: type,
+          message: message,
+        },
+        { headers: this.headers },
+      );
+      return response.data;
+    } catch (error) {
+      throw new Error(
+        `FitSMS Send Failed: ${error.response?.data?.message || error.message}`,
+      );
+    }
+  }
+
+  /**
+   * Check status of an existing SMS (v3 API)
+   * @param {string} uid - The unique message ID
+   */
+  async getStatus(uid) {
+    try {
+      const response = await axios.get(`${this.v3Base}/sms/${uid}`, {
+        headers: this.headers,
+      });
+      return response.data;
+    } catch (error) {
+      throw new Error(
+        `FitSMS Status Check Failed: ${error.response?.data?.message || error.message}`,
+      );
+    }
+  }
+
+  /**
+   * Retrieve account balance and SMS units (v4 API)
+   */
+  async getBalance() {
+    try {
+      const response = await axios.get(`${this.v3Base}/balance`, {
+        headers: this.headers,
+      });
+      return response.data;
+    } catch (error) {
+      throw new Error(
+        `FitSMS Balance Check Failed: ${error.response?.data?.message || error.message}`,
+      );
+    }
+  }
+
+  /**
+   * Retrieve full profile information (v4 API)
+   */
+  async getProfile() {
+    try {
+      const response = await axios.get(`${this.v3Base}/me`, {
+        headers: this.headers,
+      });
+      return response.data;
+    } catch (error) {
+      throw new Error(
+        `FitSMS Profile Retrieval Failed: ${error.response?.data?.message || error.message}`,
+      );
+    }
+  }
+}
+
+module.exports = FitSMS;

package/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "fitsms",
+  "version": "1.0.0",
+  "description": "The official-style Node.js SDK for the FitSMS.lk gateway.",
+  "main": "index.js",
+  "scripts": {
+    "test": "node test.js"
+  },
+  "keywords": [
+    "fitsms",
+    "sms",
+    "srilanka",
+    "gateway",
+    "bulk-sms",
+    "947"
+  ],
+  "author": "Danuja Dilanka",
+  "license": "MIT",
+  "dependencies": {
+    "axios": "^1.6.0"
+  }
+}

package/test.js

@@ -0,0 +1,60 @@
+const FitSMS = require("./index.js");
+
+/*
+
+THIS IMPLEMENTATION FOLLOWS FITSMS'S V3 API SPECIFICATION
+
+https://app.fitsms.lk/api/v3
+
+FOR V4 API, WEBHOOKS & FURTHER DOCUMENTATION, SEE:
+https://app.fitsms.lk/developers/docs
+
+DEV. BY GLOBAL CLOUD MEDIA (https://globalcloudmedia.lk)
+REPOSITORY: https://github.com/Global-Cloud-Media-Pvt-Ltd/fitsms-nodejs-sdk
+
+*/
+
+// REPLACE THESE WITH YOUR ACTUAL CREDENTIALS FOR TESTING
+const API_TOKEN = "YOUR_ACTUAL_BEARER_TOKEN_HERE";
+const SENDER_ID = "YOUR_ACTUAL_SENDER_ID_HERE";
+const TEST_MOBILE = "947XXXXXXX";
+
+const sms = new FitSMS(API_TOKEN, SENDER_ID);
+
+async function runTests() {
+  console.log("🚀 Starting FitSMS Module Tests...\n");
+
+  try {
+    // 1. Test Balance (v3 API)
+    console.log("--- Testing getBalance() ---");
+    const balance = await sms.getBalance();
+    console.log("✅ Balance Status:", balance.status);
+    console.log("Remaining Units:", balance.data);
+    console.log("----------------------------\n");
+
+    // 2. Test Sending SMS (v3 API)
+    console.log("--- Testing send() ---");
+    const sendRes = await sms.send(TEST_MOBILE, "Test message from local SDK");
+    console.log("✅ Send Status:", sendRes.status);
+
+    if (sendRes.data[0] && sendRes.data[0].uid) {
+      const uid = sendRes.data[0].uid;
+      console.log("Message UID:", uid);
+      console.log("----------------------------\n");
+
+      // 3. Test Status Check (v3 API)
+      console.log("--- Testing getStatus() ---");
+      const statusRes = await sms.getStatus(uid);
+      console.log("✅ Status Check:", statusRes.status);
+      console.log("Delivery Status:", statusRes.data.status);
+      console.log("----------------------------\n");
+    }
+
+    console.log("🎉 All tests passed successfully!");
+  } catch (error) {
+    console.error("❌ Test Failed!");
+    console.error("Error Message:", error.message);
+  }
+}
+
+runTests();