unismsgateway 1.2.1 → 1.3.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 RazakAlpha
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,93 +1,381 @@
+# Unified SMS Gateway
 
-# Unified Sms Gateway
+Most projects rely on more than one SMS provider so they can switch if a gateway is unavailable. Each provider’s API differs, so separate integrations are usually required.
 
-Most of the time a single project relies on multiple sms Gateway so it can switched if one goes off.
-However, each sms api specification is different from the other, hence the need to create separate implementation
-for each sms gateway.
+**unismsgateway** exposes a single API for multiple SMS gateways. You implement once, then select or switch the platform; your send flow stays the same.
 
-Unified sms gateway is library that brings most common sms gateways under a Unified api.
-which means you only does one implementation in it works for all supported sms gateway. 
-you just have select or switch your sms platform and your code still works fine like nothing has changed
+## Installation
 
+```bash
+npm install unismsgateway
+```
 
-## Usage/Examples
+**Requirements:** Node.js `>= 12.0.0` (see `package.json` `engines`).
 
-```javascript
-const unisms = require('unismsgateway')
+## Module import
+
+**CommonJS**
 
-const param = { clientId, // hubtel sms client Id **optional
-                clientSecret, // hubtel sms client secret ** optional
-                username, // username for route sms
-                password, // password for route sms
-                host,  // host address eg. rslr.connectbind.....
-                port} // port defaults to 8080
+```javascript
+const unisms = require('unismsgateway');
+```
 
-//init with prefered platform id. route => routemobile, hubtel => hubtel sms
-// more sms services will be added or supported in the future
-const gateway  = unisms.init({platformId:'route', param})
+**ESM / TypeScript**
 
+```typescript
+import * as unisms from 'unismsgateway';
+// or named:
+import { init, getSmsPlatform, reset, smsPlatform } from 'unismsgateway';
 ```
 
-### SEND MESSAGE
+---
+
+## Configuration overview
+
+### `IgatewaySettings`
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `platformId` | `'route' \| 'hubtel' \| 'nest'` | Which gateway to use. |
+| `param` | `IgatewayParam` | Provider-specific options (see below). |
+
+### `IgatewayParam` (all fields optional except what your `platformId` requires)
+
+| Field | Type | Used by | Description |
+|-------|------|---------|-------------|
+| `username` | `string` | `route` | Route Mobile account username. **Required** for `route`. |
+| `password` | `string` | `route` | Route Mobile account password. **Required** for `route`. |
+| `host` | `string` | `route`, `nest` | API host. See per-gateway defaults below. |
+| `port` | `number` | `route` | TCP port for Route Mobile. Default: `8080`. |
+| `protocol` | `'http' \| 'https'` | `route`, `nest` | URL scheme. See defaults per gateway. |
+| `clientId` | `string` | `hubtel` | Hubtel client ID. **Required** for `hubtel`. |
+| `clientSecret` | `string` | `hubtel` | Hubtel client secret. **Required** for `hubtel`. |
+| `apiKey` | `string` | `nest` | SMSOnlineGH API key (`Authorization: key …`). **Required** for `nest`. |
+
+Validation runs in `smsPlatform` when the instance is constructed: missing required fields for the chosen `platformId` throw `Error` with a clear message.
+
+---
+
+## Environment variables
+
+**This library does not read `process.env` or any configuration files.** You pass all credentials and endpoints explicitly in `init({ platformId, param })`.
+
+In your own application it is common to map environment variables into `param`. Suggested names (you define these in `.env` or your host’s secret store):
+
+| Suggested env name | Maps to `param` | Gateways |
+|--------------------|-----------------|----------|
+| `SMS_PLATFORM_ID` | `platformId` | all |
+| `ROUTE_SMS_USERNAME` | `username` | `route` |
+| `ROUTE_SMS_PASSWORD` | `password` | `route` |
+| `ROUTE_SMS_HOST` | `host` | `route` (optional; has default) |
+| `ROUTE_SMS_PORT` | `port` | `route` (optional) |
+| `ROUTE_SMS_PROTOCOL` | `protocol` | `route` (optional) |
+| `HUBTEL_CLIENT_ID` | `clientId` | `hubtel` |
+| `HUBTEL_CLIENT_SECRET` | `clientSecret` | `hubtel` |
+| `SMSONLINEGH_API_KEY` or `NEST_API_KEY` | `apiKey` | `nest` |
+| `SMSONLINEGH_HOST` or `NEST_HOST` | `host` | `nest` (optional) |
+| `SMSONLINEGH_PROTOCOL` or `NEST_PROTOCOL` | `protocol` | `nest` (optional) |
+
+Example wiring (conceptual): branch on `platformId` and build `param` so you do not mix unrelated fields.
+
 ```javascript
+const unisms = require('unismsgateway');
 
-const testSms = async function(){
-  try{
-    // const gateway = unisms.getSmsPlatform();
-     await gateway.quickSend({From:'xxxxx', To: xxxxxxxx, Content: 'Testing unisms', Type: 0}, (response)=>{
-      console.log(response)
-    }).then(r => {
-      console.log(r)
-    }).catch(err => {
-      console.log(err)
-    })
-  }catch(err){
-    console.log(err)
+const platformId = process.env.SMS_PLATFORM_ID;
+
+const paramByPlatform = {
+  route: {
+    username: process.env.ROUTE_SMS_USERNAME,
+    password: process.env.ROUTE_SMS_PASSWORD,
+    host: process.env.ROUTE_SMS_HOST,
+    port: process.env.ROUTE_SMS_PORT ? Number(process.env.ROUTE_SMS_PORT) : undefined,
+    protocol: process.env.ROUTE_SMS_PROTOCOL
+  },
+  hubtel: {
+    clientId: process.env.HUBTEL_CLIENT_ID,
+    clientSecret: process.env.HUBTEL_CLIENT_SECRET
+  },
+  nest: {
+    apiKey: process.env.SMSONLINEGH_API_KEY,
+    host: process.env.SMSONLINEGH_HOST,
+    protocol: process.env.SMSONLINEGH_PROTOCOL
   }
+};
 
+const gateway = unisms.init({
+  platformId,
+  param: paramByPlatform[platformId]
+});
+```
 
-}
+---
+
+## How initialization works
+
+1. **`init(settings: IgatewaySettings): smsPlatform`** (in `src/lib/lib.ts`):
+   - Validates and constructs a new `smsPlatform` with your `settings`.
+   - Stores it as the **module singleton** (`smsPlatformInstance`).
+   - Calls `smsPlatform.init()` on that instance (returns the same facade for chaining).
+   - Returns the `smsPlatform` instance.
+
+2. **`smsPlatform` constructor** (in `src/lib/platform.ts`):
+   - Runs `validateSettings()` (platform id + required `param` fields for that id).
+   - Calls `createGateway()` to instantiate the underlying provider (`routeSms`, `HubtelSms`, or `NestSmsGateway`).
 
+3. **`getSmsPlatform(): smsPlatform | null`**: Returns the current singleton, or `null` if `reset()` was called and no new `init()` has run.
+
+There is **no async bootstrap**; after `init()` returns, `quickSend` is ready.
+
+---
+
+## Re-initializing and reset
+
+- **Switch platform or credentials:** Call **`init(newSettings)`** again. Each call **replaces** the stored singleton with a new `smsPlatform`. You do not have to call `reset()` first.
+- **Clear the singleton:** **`reset()`** sets the internal reference to `null`. `getSmsPlatform()` then returns `null` until the next `init()`. Use this when you want to guarantee nothing holds a gateway instance (e.g. tests or explicit teardown).
+
+```javascript
+const unisms = require('unismsgateway');
+
+const a = unisms.init({ platformId: 'nest', param: { apiKey: 'key-1' } });
+// Later: new config
+const b = unisms.init({ platformId: 'hubtel', param: { clientId: 'x', clientSecret: 'y' } });
+// b replaces a; unisms.getSmsPlatform() === b
+
+unisms.reset();
+// unisms.getSmsPlatform() === null
+
+const c = unisms.init({ platformId: 'nest', param: { apiKey: 'key-2' } });
+```
+
+---
+
+## Supported gateways
+
+| `platformId` | Provider | Package / implementation |
+|----------------|----------|---------------------------|
+| `route` | Route Mobile | `routemobilesms` |
+| `hubtel` | Hubtel SMS (Ghana) | `hubtel-sms-extended` |
+| `nest` | SMSOnlineGH | Built-in REST client (`NestSmsGateway`) |
+
+### `route` (Route Mobile)
+
+**Required `param`:** `username`, `password`.
+
+**Optional `param` (defaults in this library):**
+
+| Field | Default if omitted |
+|-------|-------------------|
+| `host` | `rslr.connectbind.com` |
+| `protocol` | `'http'` |
+| `port` | `8080` |
+
+These are passed into `routeSms` from `routemobilesms`.
+
+```javascript
+const gateway = unisms.init({
+  platformId: 'route',
+  param: {
+    username: 'your-username',
+    password: 'your-password',
+    host: 'rslr.connectbind.com',
+    protocol: 'http',
+    port: 8080
+  }
+});
 ```
 
-### SEND PERSONALIZED MESSAGE
+### `hubtel` (Hubtel)
+
+**Required `param`:** `clientId`, `clientSecret`.
+
+No `host` / `protocol` in `IgatewayParam` for Hubtel in this library; configuration follows `hubtel-sms-extended`.
+
 ```javascript
+const gateway = unisms.init({
+  platformId: 'hubtel',
+  param: {
+    clientId: 'your-client-id',
+    clientSecret: 'your-client-secret'
+  }
+});
+```
+
+### `nest` (SMSOnlineGH)
+
+**Required `param`:** `apiKey`.
+
+**Optional `param`:**
+
+| Field | Default if omitted |
+|-------|-------------------|
+| `host` | `api.smsonlinegh.com` |
+| `protocol` | `'https'` |
 
-const testSms = async function(){
-  try{
-    // const gateway = unisms.getSmsPlatform();
-     await gateway.sendPersonalized({From:'xxxxx', 
-                                    To: {to: 233XXXXXXXXX, values: ['Alpha', 65332]},  // [{to: 233XXXXXXXXX, values: ['Alpha', 65332]}, {to: 211XXXXXXXXX, values: ['James', 2000]}, ]
-                                    Content: 'Testing unisms', 
-                                    Type: 0}).then(r => {
-      console.log(r)
-    }).catch(err => {
-      console.log(err)
-    })
-  }catch(err){
-    console.log(err)
+Requests use `POST` to path **`/v5/<endpoint>`** (e.g. send: `message/sms/send`, balance: `account/balance`). Authorization header: `Authorization: key <apiKey>`.
+
+```javascript
+const gateway = unisms.init({
+  platformId: 'nest',
+  param: {
+    apiKey: 'your-api-key'
+    // optional: host, protocol
   }
+});
+```
+
+**Balance (nest only):** The underlying `NestSmsGateway` implements `getBalance()`. Access it via the facade’s `getGateway()`:
+
+```javascript
+const gateway = unisms.init({
+  platformId: 'nest',
+  param: { apiKey: 'your-api-key' }
+});
+
+const nest = gateway.getGateway();
+const balance = await nest.getBalance();
+console.log(balance.balance, balance.model);
+```
+
+---
+
+## Sending messages
+
+### `QuickSendParams`
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `From` | `string` | yes | Sender ID or label. |
+| `To` | `string \| number` | yes | Recipient number (format as required by the provider). |
+| `Content` | `string` | yes | Message body. |
+| `Type` | `number` | no | Message type; **nest** maps this to request body `type` (default `0`). |
+
+### `quickSend(params, callback?)`
+
+Returns `Promise<SendResult>`. Optional `callback` is invoked with the same result when the promise completes.
+
+**`SendResult`:**
+
+```typescript
+{
+  success: boolean;
+  messageId?: string;
+  data?: any;
+  error?: string;
+}
+```
 
+**Example**
 
+```javascript
+const unisms = require('unismsgateway');
+
+const gateway = unisms.init({
+  platformId: 'nest',
+  param: { apiKey: 'your-api-key' }
+});
+
+async function sendSms() {
+  try {
+    const result = await gateway.quickSend({
+      From: 'SenderName',
+      To: '233XXXXXXXXX',
+      Content: 'Hello from unismsgateway!',
+      Type: 0
+    });
+
+    if (result.success) {
+      console.log('Sent:', result.messageId);
+    } else {
+      console.error('Failed:', result.error);
+    }
+  } catch (err) {
+    console.error(err);
+  }
 }
+```
+
+**With callback**
+
+```javascript
+gateway.quickSend(
+  { From: 'SenderName', To: '233XXXXXXXXX', Content: 'Test' },
+  (response) => {
+    console.log(response);
+  }
+);
+```
+
+---
 
+## Testing (live integration)
+
+There is no unit test suite in this package. For **manual integration checks** against real gateways, use the script in `scripts/test-live.ts`.
+
+**Setup**
+
+1. Clone the repo and install dependencies: `npm install`
+2. Copy `.env.example` to `.env` and fill in credentials for the platform you want to exercise
+3. Run:
+
+```bash
+npm test
+# same as:
+npm run test:live
 ```
 
+**Selecting a platform**
+
+| Env variable | Description |
+|--------------|-------------|
+| `GATEWAY_PLATFORM` | One of `nest`, `hubtel`, or `route`. Required unless you use `TEST_ALL`. |
+| `TEST_ALL` | If set to `true`, runs tests for `nest`, `hubtel`, and `route` in sequence (each needs its env vars set). |
+
+**What runs**
 
-## supported bulk sms gateways
+1. **Init** — Builds `param` from your `.env`, calls `init()`, and checks configuration validation.
+2. **Balance** — For `nest` and `hubtel` only, calls `getBalance()` when the adapter supports it. `route` skips this step.
+3. **Send** — **Opt-in.** By default no SMS is sent. Set `TEST_SEND=true` to call `quickSend()` with `TEST_FROM`, `TEST_TO`, and optional `TEST_CONTENT`.
 
-Hubtel bulk sms (Ghana) using hubtel-sms-extended
-routeMobile sms (India) using routemobilesms
-Nest SMS(Ghana) using nestsms
+**Environment variables (live script)**
 
-## Roadmap
+Variables below match `.env.example` and `scripts/test-live.ts`.
 
-- Additional browser support
+| Variable | Required when | Purpose |
+|----------|----------------|---------|
+| `GATEWAY_PLATFORM` | Unless `TEST_ALL=true` | `nest` \| `hubtel` \| `route` |
+| `TEST_ALL` | Optional | `true` to test all three platforms |
+| `NEST_API_KEY` | `nest` | SMSOnlineGH API key |
+| `NEST_HOST`, `NEST_PROTOCOL` | `nest` | Optional overrides |
+| `HUBTEL_CLIENT_ID`, `HUBTEL_CLIENT_SECRET` | `hubtel` | Hubtel credentials |
+| `ROUTE_USERNAME`, `ROUTE_PASSWORD` | `route` | Route Mobile credentials |
+| `ROUTE_HOST`, `ROUTE_PORT`, `ROUTE_PROTOCOL` | `route` | Optional overrides |
+| `TEST_SEND` | To send SMS | Set to `true` to enable live send |
+| `TEST_FROM`, `TEST_TO` | When `TEST_SEND=true` | Sender and recipient |
+| `TEST_CONTENT` | When `TEST_SEND=true` | Message body (script has a default if omitted) |
 
-- Add more third party sms integrations
+The script loads `.env` via `dotenv` (dev dependency). Exit code is `0` when all checks pass, non-zero if a step fails or no platform is selected.
 
+---
+
+## API reference
+
+| Export | Description |
+|--------|-------------|
+| `init(settings)` | Create and register the singleton `smsPlatform`, return it. |
+| `getSmsPlatform()` | Current `smsPlatform` or `null` after `reset()` and before `init()`. |
+| `reset()` | Clear the singleton. |
+| `smsPlatform` | Class type for typing/advanced use. |
+
+**`smsPlatform` instance methods**
+
+| Method | Returns | Description |
+|--------|---------|-------------|
+| `init()` | `ISmsGateway` | Returns `this` (facade). |
+| `quickSend(params, callback?)` | `Promise<SendResult>` | Delegates to the active gateway. |
+| `getGateway()` | `ISmsGateway` | Underlying adapter (for nest: `getBalance()`). |
+
+---
 
 ## License
 
 [MIT](https://choosealicense.com/licenses/mit/)
-

package/dist/index.d.ts

@@ -1 +1 @@
-export * from './lib/lib';
+export * from './lib/lib';

package/dist/index.js

@@ -1,13 +1,13 @@
-"use strict";
-var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    Object.defineProperty(o, k2, { enumerable: true, get: function() { return m[k]; } });
-}) : (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    o[k2] = m[k];
-}));
-var __exportStar = (this && this.__exportStar) || function(m, exports) {
-    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
-};
-Object.defineProperty(exports, "__esModule", { value: true });
-__exportStar(require("./lib/lib"), exports);
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    Object.defineProperty(o, k2, { enumerable: true, get: function() { return m[k]; } });
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./lib/lib"), exports);

package/dist/lib/j;[ ]p;;;j]/ts

@@ -0,0 +1,44 @@
+export declare type PlatformId = 'route' | 'hubtel' | 'nest';
+export interface QuickSendParams {
+    From: string;
+    To: string | number;
+    Content: string;
+    Type?: number;
+}
+export interface SendResult {
+    success: boolean;
+    messageId?: string;
+    data?: any;
+    error?: string;
+}
+export interface IgatewayParam {
+    host?: string;
+    port?: number;
+    username?: string;
+    password?: string;
+    clientId?: string;
+    clientSecret?: string;
+    apiKey?: string;
+    protocol?: 'http' | 'https';
+}
+export interface IgatewaySettings {
+    platformId: PlatformId;
+    param: IgatewayParam;
+}
+export interface ISmsGateway {
+    init(): ISmsGateway;
+    quickSend(params: QuickSendParams, callback?: Function): Promise<SendResult>;
+    getBalance?(): Promise<any>;
+}
+export interface NestSmsConfig {
+    apiKey: string;
+    host?: string;
+    protocol?: 'http' | 'https';
+}
+export interface NestSendResponse {
+    handshake: {
+        id: number;
+        label: string;
+    };
+    data?: any;
+}

package/dist/lib/lib.d.ts

@@ -1,10 +1,5 @@
-import { smsPlatform, IgatewaySettings, IQuickSendPersonalized } from './platform';
-export declare function init(settings: IgatewaySettings): smsPlatform;
-export declare function getSmsPlatform(): smsPlatform;
-export declare function quickSend(param: {
-    From: string;
-    To: number;
-    Content: string;
-    Type?: number;
-}, callback?: Function): any;
-export declare function sendPersonalized(body: IQuickSendPersonalized): any;
+import { smsPlatform, IgatewaySettings, IgatewayParam, PlatformId, QuickSendParams, SendResult, ISmsGateway } from './platform';
+export declare function init(settings: IgatewaySettings): smsPlatform;
+export declare function getSmsPlatform(): smsPlatform | null;
+export declare function reset(): void;
+export { smsPlatform, IgatewaySettings, IgatewayParam, PlatformId, QuickSendParams, SendResult, ISmsGateway };

package/dist/lib/lib.js

@@ -1,23 +1,20 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.sendPersonalized = exports.quickSend = exports.getSmsPlatform = exports.init = void 0;
-const platform_1 = require("./platform");
-let smsplatform;
-function init(settings) {
-    const smsPlatform_ = new platform_1.smsPlatform(settings);
-    smsplatform = smsPlatform_;
-    return smsPlatform_.init();
-}
-exports.init = init;
-function getSmsPlatform() {
-    return smsplatform;
-}
-exports.getSmsPlatform = getSmsPlatform;
-function quickSend(param, callback) {
-    return smsplatform.quickSend(param, callback);
-}
-exports.quickSend = quickSend;
-function sendPersonalized(body) {
-    return smsplatform.sendPersonalized(body);
-}
-exports.sendPersonalized = sendPersonalized;
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.smsPlatform = exports.reset = exports.getSmsPlatform = exports.init = void 0;
+const platform_1 = require("./platform");
+Object.defineProperty(exports, "smsPlatform", { enumerable: true, get: function () { return platform_1.smsPlatform; } });
+let smsPlatformInstance = null;
+function init(settings) {
+    smsPlatformInstance = new platform_1.smsPlatform(settings);
+    smsPlatformInstance.init();
+    return smsPlatformInstance;
+}
+exports.init = init;
+function getSmsPlatform() {
+    return smsPlatformInstance;
+}
+exports.getSmsPlatform = getSmsPlatform;
+function reset() {
+    smsPlatformInstance = null;
+}
+exports.reset = reset;

package/dist/lib/nest-gateway.d.ts

@@ -0,0 +1,12 @@
+import { ISmsGateway, QuickSendParams, SendResult, NestSmsConfig } from './types';
+export declare class NestSmsGateway implements ISmsGateway {
+    private config;
+    constructor(config: NestSmsConfig);
+    init(): ISmsGateway;
+    private makeRequest;
+    quickSend(params: QuickSendParams, callback?: Function): Promise<SendResult>;
+    getBalance(): Promise<{
+        balance: number;
+        model: string;
+    }>;
+}