unismsgateway 1.3.0 → 1.3.1

package/README.md

@@ -1,13 +1,8 @@
-# Unified Sms Gateway
+# Unified SMS Gateway
 
-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.
-
-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
+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.
 
+**unismsgateway** exposes a single API for multiple SMS gateways. You implement once, then select or switch the platform; your send flow stays the same.
 
 ## Installation
 
@@ -15,170 +10,372 @@ you just have select or switch your sms platform and your code still works fine
 npm install unismsgateway
 ```
 
-## Supported Gateways
-
-| Platform ID | Provider | Required Params |
-|-------------|----------|-----------------|
-| `route` | routeMobile | username, password, host |
-| `hubtel` | Hubtel SMS (Ghana) | clientId, clientSecret |
-| `nest` | SMSOnlineGH / smsonlinegh | apiKey |
+**Requirements:** Node.js `>= 12.0.0` (see `package.json` `engines`).
 
-## Usage/Examples
+## Module import
 
-### Initialize with Platform
+**CommonJS**
 
 ```javascript
-const unisms = require('unismsgateway')
-
-// For routeMobile
-const routeGateway = unisms.init({
-    platformId: 'route',
-    param: {
-        username: 'your-username',
-        password: 'your-password',
-        host: 'rslr.connectbind.com',
-        protocol: 'http',
-        port: 8080
-    }
-})
-
-// For Hubtel
-const hubtelGateway = unisms.init({
-    platformId: 'hubtel',
-    param: {
-        clientId: 'your-client-id',
-        clientSecret: 'your-client-secret'
-    }
-})
-
-// For SMSOnlineGH (nest)
-const nestGateway = unisms.init({
-    platformId: 'nest',
-    param: {
-        apiKey: 'your-api-key',
-        // Optional: host, protocol (defaults to api.smsonlinegh.com, https)
-    }
-})
+const unisms = require('unismsgateway');
+```
+
+**ESM / TypeScript**
+
+```typescript
+import * as unisms from 'unismsgateway';
+// or named:
+import { init, getSmsPlatform, reset, smsPlatform } from 'unismsgateway';
 ```
 
-### Send SMS 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 unisms = require('unismsgateway');
+
+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
+  }
+};
 
-// Initialize gateway
 const gateway = unisms.init({
-    platformId: 'nest',
-    param: {
-        apiKey: 'your-api-key'
-    }
-})
+  platformId,
+  param: paramByPlatform[platformId]
+});
+```
 
-// Send message
-async function sendSms() {
-    try {
-        const result = await gateway.quickSend({
-            From: 'SenderName',
-            To: '233XXXXXXXXX',  // recipient number
-            Content: 'Hello from unismsgateway!',
-            Type: 0  // optional, defaults to 0
-        })
-        
-        if (result.success) {
-            console.log('Message sent successfully:', result.messageId)
-        } else {
-            console.error('Failed to send:', result.error)
-        }
-    } catch (err) {
-        console.error('Error:', err)
-    }
-}
+---
 
-sendSms()
-```
+## 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.
 
-### With Callback
+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
-gateway.quickSend({
-    From: 'SenderName',
-    To: '233XXXXXXXXX',
-    Content: 'Test message'
-}, (response) => {
-    console.log('Response:', response)
-})
+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' } });
 ```
 
-### Check Balance (SMSOnlineGH/nest only)
+---
+
+## 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: 'nest',
-    param: { apiKey: 'your-api-key' }
-})
-
-// Only available for nest platform
-if (gateway.getGateway) {
-    const nestGateway = gateway.getGateway()
-    const balance = await nestGateway.getBalance()
-    console.log('Balance:', balance)
-}
+  platformId: 'route',
+  param: {
+    username: 'your-username',
+    password: 'your-password',
+    host: 'rslr.connectbind.com',
+    protocol: 'http',
+    port: 8080
+  }
+});
 ```
 
-### Reset Gateway Instance
+### `hubtel` (Hubtel)
+
+**Required `param`:** `clientId`, `clientSecret`.
+
+No `host` / `protocol` in `IgatewayParam` for Hubtel in this library; configuration follows `hubtel-sms-extended`.
 
 ```javascript
-// Clear the current gateway instance
-unisms.reset()
-
-// Initialize with new platform
-const newGateway = unisms.init({
-    platformId: 'hubtel',
-    param: {
-        clientId: 'new-client-id',
-        clientSecret: 'new-secret'
-    }
-})
+const gateway = unisms.init({
+  platformId: 'hubtel',
+  param: {
+    clientId: 'your-client-id',
+    clientSecret: 'your-client-secret'
+  }
+});
 ```
 
-## API Reference
+### `nest` (SMSOnlineGH)
 
-### `init(settings: IgatewaySettings): smsPlatform`
+**Required `param`:** `apiKey`.
 
-Initialize the SMS gateway with your platform configuration.
+**Optional `param`:**
 
-**Parameters:**
-- `platformId`: `'route'` | `'hubtel'` | `'nest'`
-- `param`: Platform-specific configuration object
+| Field | Default if omitted |
+|-------|-------------------|
+| `host` | `api.smsonlinegh.com` |
+| `protocol` | `'https'` |
 
-### `getSmsPlatform(): smsPlatform | null`
+Requests use `POST` to path **`/v5/<endpoint>`** (e.g. send: `message/sms/send`, balance: `account/balance`). Authorization header: `Authorization: key <apiKey>`.
 
-Get the current gateway instance. Returns `null` if not initialized.
+```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);
+```
 
-### `reset(): void`
+---
 
-Clear the current gateway instance.
+## Sending messages
 
-### `quickSend(params: QuickSendParams, callback?: Function): Promise<SendResult>`
+### `QuickSendParams`
 
-Send an SMS message.
+| 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`). |
 
-**Parameters:**
-- `From`: Sender ID/name
-- `To`: Recipient phone number (string or number)
-- `Content`: Message content
-- `Type`: Optional message type (defaults to 0)
+### `quickSend(params, callback?)`
+
+Returns `Promise<SendResult>`. Optional `callback` is invoked with the same result when the promise completes.
+
+**`SendResult`:**
 
-**Returns:**
 ```typescript
 {
-    success: boolean;
-    messageId?: string;
-    data?: any;
-    error?: string;
+  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**
+
+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`.
+
+**Environment variables (live script)**
+
+Variables below match `.env.example` and `scripts/test-live.ts`.
+
+| 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) |
+
+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/)
+[MIT](https://choosealicense.com/licenses/mit/)

package/dist/scripts/test-live.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Live integration test script for unismsgateway.
+ *
+ * Usage:
+ *   1. Copy .env.example to .env and fill in your credentials.
+ *   2. npm run test:live
+ *
+ * Set TEST_SEND=true in .env (or inline) to actually send an SMS.
+ * Without it, only init and balance checks run.
+ */
+export {};

package/dist/scripts/test-live.js

@@ -0,0 +1,188 @@
+"use strict";
+/**
+ * Live integration test script for unismsgateway.
+ *
+ * Usage:
+ *   1. Copy .env.example to .env and fill in your credentials.
+ *   2. npm run test:live
+ *
+ * Set TEST_SEND=true in .env (or inline) to actually send an SMS.
+ * Without it, only init and balance checks run.
+ */
+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 __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || function (mod) {
+    if (mod && mod.__esModule) return mod;
+    var result = {};
+    if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
+    __setModuleDefault(result, mod);
+    return result;
+};
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const dotenv = __importStar(require("dotenv"));
+dotenv.config();
+const lib_1 = require("../src/lib/lib");
+// ─── Colour helpers ──────────────────────────────────────────────────────────
+const GREEN = '\x1b[32m';
+const RED = '\x1b[31m';
+const YELLOW = '\x1b[33m';
+const CYAN = '\x1b[36m';
+const BOLD = '\x1b[1m';
+const RESET = '\x1b[0m';
+const pass = (msg) => console.log(`  ${GREEN}✔${RESET}  ${msg}`);
+const fail = (msg) => console.log(`  ${RED}✖${RESET}  ${msg}`);
+const info = (msg) => console.log(`  ${CYAN}ℹ${RESET}  ${msg}`);
+const warn = (msg) => console.log(`  ${YELLOW}⚠${RESET}  ${msg}`);
+const title = (msg) => console.log(`\n${BOLD}${msg}${RESET}`);
+// ─── Env helpers ─────────────────────────────────────────────────────────────
+function env(key) {
+    return process.env[key] || undefined;
+}
+function requireEnv(key) {
+    const val = process.env[key];
+    if (!val)
+        throw new Error(`Missing required env var: ${key}`);
+    return val;
+}
+// ─── Test counters ───────────────────────────────────────────────────────────
+let passed = 0;
+let failed = 0;
+function runTest(label, fn) {
+    return __awaiter(this, void 0, void 0, function* () {
+        try {
+            yield fn();
+            passed++;
+        }
+        catch (err) {
+            failed++;
+            fail(`${label}: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    });
+}
+// ─── Per-platform tests ───────────────────────────────────────────────────────
+function testPlatform(platformId) {
+    return __awaiter(this, void 0, void 0, function* () {
+        title(`Platform: ${platformId.toUpperCase()}`);
+        let platform;
+        // 1. Initialisation
+        yield runTest('Init / config validation', () => __awaiter(this, void 0, void 0, function* () {
+            const param = {};
+            switch (platformId) {
+                case 'nest':
+                    param.apiKey = requireEnv('NEST_API_KEY');
+                    if (env('NEST_HOST'))
+                        param.host = env('NEST_HOST');
+                    if (env('NEST_PROTOCOL'))
+                        param.protocol = env('NEST_PROTOCOL');
+                    break;
+                case 'hubtel':
+                    param.clientId = requireEnv('HUBTEL_CLIENT_ID');
+                    param.clientSecret = requireEnv('HUBTEL_CLIENT_SECRET');
+                    break;
+                case 'route':
+                    param.username = requireEnv('ROUTE_USERNAME');
+                    param.password = requireEnv('ROUTE_PASSWORD');
+                    if (env('ROUTE_HOST'))
+                        param.host = env('ROUTE_HOST');
+                    if (env('ROUTE_PORT'))
+                        param.port = Number(env('ROUTE_PORT'));
+                    if (env('ROUTE_PROTOCOL'))
+                        param.protocol = env('ROUTE_PROTOCOL');
+                    break;
+            }
+            platform = (0, lib_1.init)({ platformId, param: param });
+            pass(`Initialized ${platformId} platform`);
+        }));
+        // 2. Balance check (only nest and hubtel expose getBalance)
+        if (platformId === 'nest' || platformId === 'hubtel') {
+            yield runTest('getBalance()', () => __awaiter(this, void 0, void 0, function* () {
+                const gateway = platform.getGateway();
+                if (!gateway.getBalance) {
+                    warn('getBalance not implemented — skipped');
+                    return;
+                }
+                const balance = yield gateway.getBalance();
+                pass(`Balance retrieved: ${JSON.stringify(balance)}`);
+            }));
+        }
+        else {
+            warn(`getBalance not supported by '${platformId}' — skipped`);
+        }
+        // 3. Send SMS (opt-in via TEST_SEND=true)
+        const shouldSend = env('TEST_SEND') === 'true';
+        if (!shouldSend) {
+            warn('TEST_SEND is not set to true — skipping live send');
+            return;
+        }
+        yield runTest('quickSend()', () => __awaiter(this, void 0, void 0, function* () {
+            const sendParams = {
+                From: requireEnv('TEST_FROM'),
+                To: requireEnv('TEST_TO'),
+                Content: env('TEST_CONTENT') || 'unismsgateway live test — please ignore.'
+            };
+            info(`Sending from "${sendParams.From}" to "${sendParams.To}"...`);
+            const result = yield platform.quickSend(sendParams);
+            if (!result.success) {
+                throw new Error(result.error || `Send failed: ${JSON.stringify(result)}`);
+            }
+            pass(`Message sent. Result: ${JSON.stringify(result)}`);
+        }));
+    });
+}
+// ─── Entry point ─────────────────────────────────────────────────────────────
+function main() {
+    return __awaiter(this, void 0, void 0, function* () {
+        console.log(`\n${BOLD}═══════════════════════════════════════${RESET}`);
+        console.log(`${BOLD}   unismsgateway  —  live test runner   ${RESET}`);
+        console.log(`${BOLD}═══════════════════════════════════════${RESET}`);
+        const platformArg = env('GATEWAY_PLATFORM');
+        const platforms = platformArg
+            ? [platformArg]
+            : (env('TEST_ALL') === 'true' ? ['nest', 'hubtel', 'route'] : []);
+        if (platforms.length === 0) {
+            console.log(`\n${YELLOW}No platform selected.${RESET}`);
+            console.log('Set GATEWAY_PLATFORM=nest|hubtel|route in your .env file,');
+            console.log('or set TEST_ALL=true to test all configured platforms.\n');
+            process.exit(1);
+        }
+        for (const p of platforms) {
+            try {
+                yield testPlatform(p);
+            }
+            catch (_a) {
+                // individual test errors already captured above
+            }
+        }
+        // ─── Summary ────────────────────────────────────────────────────────────
+        title('Summary');
+        if (passed > 0)
+            pass(`${passed} check(s) passed`);
+        if (failed > 0)
+            fail(`${failed} check(s) failed`);
+        console.log();
+        process.exit(failed > 0 ? 1 : 0);
+    });
+}
+main().catch((err) => {
+    console.error(`\n${RED}Unexpected error:${RESET}`, err);
+    process.exit(1);
+});

package/dist/src/index.d.ts

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

package/dist/src/index.js

@@ -0,0 +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);

package/dist/src/lib/hubtel-gateway.d.ts

@@ -0,0 +1,13 @@
+import { ISmsGatewayDelegate, QuickSendParams, SendResult } from './types';
+export interface HubtelSmsGatewayConfig {
+    clientId: string;
+    clientSecret: string;
+}
+/**
+ * Wraps hubtel-sms-extended and maps API responses to {@link SendResult}.
+ */
+export declare class HubtelSmsGateway implements ISmsGatewayDelegate {
+    private _client;
+    constructor(config: HubtelSmsGatewayConfig);
+    quickSend(params: QuickSendParams, callback?: Function): Promise<SendResult>;
+}

package/dist/src/lib/hubtel-gateway.js

@@ -0,0 +1,57 @@
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HubtelSmsGateway = void 0;
+const hubtel_sms_extended_1 = require("hubtel-sms-extended");
+/**
+ * Wraps hubtel-sms-extended and maps API responses to {@link SendResult}.
+ */
+class HubtelSmsGateway {
+    constructor(config) {
+        this._client = new hubtel_sms_extended_1.HubtelSms({
+            clientId: config.clientId,
+            clientSecret: config.clientSecret
+        });
+    }
+    quickSend(params, callback) {
+        return __awaiter(this, void 0, void 0, function* () {
+            try {
+                const raw = yield this._client.quickSend({
+                    From: params.From,
+                    To: String(params.To),
+                    Content: params.Content
+                });
+                const ok = Number(raw.Status) === 0;
+                const result = {
+                    success: ok,
+                    messageId: String(raw.MessageId),
+                    data: raw,
+                    error: ok ? undefined : `Hubtel Status=${raw.Status}`
+                };
+                if (callback) {
+                    callback(result);
+                }
+                return result;
+            }
+            catch (error) {
+                const result = {
+                    success: false,
+                    error: error instanceof Error ? error.message : String(error)
+                };
+                if (callback) {
+                    callback(result);
+                }
+                return result;
+            }
+        });
+    }
+}
+exports.HubtelSmsGateway = HubtelSmsGateway;

package/dist/src/lib/lib.d.ts

@@ -0,0 +1,5 @@
+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/src/lib/lib.js

@@ -0,0 +1,20 @@
+"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/src/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;
+    }>;
+}

package/dist/src/lib/nest-gateway.js

@@ -0,0 +1,156 @@
+"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 __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || function (mod) {
+    if (mod && mod.__esModule) return mod;
+    var result = {};
+    if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
+    __setModuleDefault(result, mod);
+    return result;
+};
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NestSmsGateway = void 0;
+const https = __importStar(require("https"));
+const http = __importStar(require("http"));
+const DEFAULT_HOST = 'api.smsonlinegh.com';
+const DEFAULT_PROTOCOL = 'https';
+class NestSmsGateway {
+    constructor(config) {
+        this.config = {
+            host: config.host || DEFAULT_HOST,
+            protocol: config.protocol || DEFAULT_PROTOCOL,
+            apiKey: config.apiKey
+        };
+    }
+    init() {
+        return this;
+    }
+    makeRequest(endpoint, data) {
+        return __awaiter(this, void 0, void 0, function* () {
+            return new Promise((resolve, reject) => {
+                var _a;
+                const postData = data ? JSON.stringify(data) : '';
+                const protocol = this.config.protocol || DEFAULT_PROTOCOL;
+                const httpModule = protocol === 'https' ? https : http;
+                const defaultPort = protocol === 'https' ? 443 : 80;
+                const options = {
+                    hostname: this.config.host || DEFAULT_HOST,
+                    port: ((_a = this.config.host) === null || _a === void 0 ? void 0 : _a.includes(':'))
+                        ? parseInt(this.config.host.split(':')[1])
+                        : defaultPort,
+                    path: `/v5/${endpoint}`,
+                    method: 'POST',
+                    headers: {
+                        'Host': this.config.host || DEFAULT_HOST,
+                        'Content-Type': 'application/json',
+                        'Accept': 'application/json',
+                        'Authorization': `key ${this.config.apiKey}`,
+                        'Content-Length': Buffer.byteLength(postData)
+                    }
+                };
+                const req = httpModule.request(options, (res) => {
+                    let responseBody = '';
+                    res.on('data', (chunk) => {
+                        responseBody += chunk;
+                    });
+                    res.on('end', () => {
+                        try {
+                            if (res.statusCode && res.statusCode >= 200 && res.statusCode < 300) {
+                                const parsed = JSON.parse(responseBody);
+                                resolve(parsed);
+                            }
+                            else {
+                                reject(new Error(`HTTP ${res.statusCode}: ${responseBody}`));
+                            }
+                        }
+                        catch (error) {
+                            reject(new Error(`Failed to parse response: ${responseBody}`));
+                        }
+                    });
+                });
+                req.on('error', (error) => {
+                    reject(error);
+                });
+                req.write(postData);
+                req.end();
+            });
+        });
+    }
+    quickSend(params, callback) {
+        var _a, _b, _c, _d, _e;
+        return __awaiter(this, void 0, void 0, function* () {
+            const endpoint = 'message/sms/send';
+            // SMSOnlineGH v5 expects: text, sender, destinations[] (see API docs — not from/to/content).
+            const requestBody = {
+                text: params.Content,
+                type: params.Type || 0,
+                sender: params.From,
+                destinations: [String(params.To)]
+            };
+            try {
+                const response = yield this.makeRequest(endpoint, requestBody);
+                const handshakeOk = Number((_a = response.handshake) === null || _a === void 0 ? void 0 : _a.id) === 0;
+                const data = (_b = response.data) !== null && _b !== void 0 ? _b : null;
+                const batchId = data && typeof data === 'object' ? data.batch : undefined;
+                const firstDest = data && typeof data === 'object'
+                    ? (_c = data.destinations) === null || _c === void 0 ? void 0 : _c[0]
+                    : undefined;
+                const result = {
+                    success: handshakeOk,
+                    data,
+                    messageId: batchId || (firstDest === null || firstDest === void 0 ? void 0 : firstDest.id),
+                    error: handshakeOk
+                        ? undefined
+                        : (((_d = response.handshake) === null || _d === void 0 ? void 0 : _d.label)
+                            || `handshake id ${String((_e = response.handshake) === null || _e === void 0 ? void 0 : _e.id)}`)
+                };
+                if (callback) {
+                    callback(result);
+                }
+                return result;
+            }
+            catch (error) {
+                const errorMessage = error instanceof Error ? error.message : String(error);
+                const result = {
+                    success: false,
+                    error: errorMessage
+                };
+                if (callback) {
+                    callback(result);
+                }
+                return result;
+            }
+        });
+    }
+    getBalance() {
+        var _a, _b;
+        return __awaiter(this, void 0, void 0, function* () {
+            const endpoint = 'account/balance';
+            const response = yield this.makeRequest(endpoint);
+            return {
+                balance: ((_a = response.data) === null || _a === void 0 ? void 0 : _a.balance) || 0,
+                model: ((_b = response.data) === null || _b === void 0 ? void 0 : _b.model) || 'quantity'
+            };
+        });
+    }
+}
+exports.NestSmsGateway = NestSmsGateway;

package/dist/src/lib/platform.d.ts

@@ -0,0 +1,13 @@
+import { IgatewaySettings, IgatewayParam, ISmsGateway, ISmsGatewayDelegate, QuickSendParams, SendResult } from './types';
+export * from './types';
+export declare class smsPlatform implements ISmsGateway {
+    private _settings;
+    private _gateway;
+    constructor(settings: IgatewaySettings);
+    private validateSettings;
+    private createGateway;
+    init(): ISmsGateway;
+    quickSend(param: QuickSendParams, callback?: Function): Promise<SendResult>;
+    getGateway(): ISmsGatewayDelegate;
+}
+export { IgatewaySettings, IgatewayParam };

package/dist/src/lib/platform.js

@@ -0,0 +1,85 @@
+"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 });
+exports.smsPlatform = void 0;
+const nest_gateway_1 = require("./nest-gateway");
+const hubtel_gateway_1 = require("./hubtel-gateway");
+const route_gateway_1 = require("./route-gateway");
+__exportStar(require("./types"), exports);
+const GATEWAY_CONFIGS = {
+    route: { requiresUsernamePassword: true },
+    hubtel: { requiresClientCredentials: true },
+    nest: { requiresApiKey: true }
+};
+class smsPlatform {
+    constructor(settings) {
+        this.validateSettings(settings);
+        this._settings = settings;
+        this._gateway = this.createGateway();
+    }
+    validateSettings(settings) {
+        const validPlatforms = ['route', 'hubtel', 'nest'];
+        if (!validPlatforms.includes(settings.platformId)) {
+            throw new Error(`Invalid platform ID. Supported platforms: ${validPlatforms.join(', ')}`);
+        }
+        const config = GATEWAY_CONFIGS[settings.platformId];
+        const param = settings.param;
+        if (config.requiresApiKey && !param.apiKey) {
+            throw new Error(`Platform '${settings.platformId}' requires 'apiKey' in param`);
+        }
+        if (config.requiresClientCredentials && (!param.clientId || !param.clientSecret)) {
+            throw new Error(`Platform '${settings.platformId}' requires 'clientId' and 'clientSecret' in param`);
+        }
+        if (config.requiresUsernamePassword && (!param.username || !param.password)) {
+            throw new Error(`Platform '${settings.platformId}' requires 'username' and 'password' in param`);
+        }
+    }
+    createGateway() {
+        const { platformId, param } = this._settings;
+        switch (platformId) {
+            case 'route':
+                return new route_gateway_1.RouteSmsGateway({
+                    host: param.host || 'rslr.connectbind.com',
+                    username: param.username,
+                    password: param.password,
+                    protocol: param.protocol || 'http',
+                    port: param.port || 8080
+                });
+            case 'hubtel':
+                return new hubtel_gateway_1.HubtelSmsGateway({
+                    clientId: param.clientId,
+                    clientSecret: param.clientSecret
+                });
+            case 'nest':
+                return new nest_gateway_1.NestSmsGateway({
+                    apiKey: param.apiKey,
+                    host: param.host,
+                    protocol: param.protocol
+                });
+            default:
+                throw new Error(`Unsupported platform: ${platformId}`);
+        }
+    }
+    init() {
+        return this;
+    }
+    quickSend(param, callback) {
+        if (!this._gateway) {
+            throw new Error('Gateway not initialized. Call init() first.');
+        }
+        return this._gateway.quickSend(param, callback);
+    }
+    getGateway() {
+        return this._gateway;
+    }
+}
+exports.smsPlatform = smsPlatform;

package/dist/src/lib/route-gateway.d.ts

@@ -0,0 +1,12 @@
+import { ISmsGatewayDelegate, QuickSendParams, SendResult } from './types';
+export interface RouteSmsGatewayConfig {
+    host: string;
+    username: string;
+    password: string;
+    protocol: 'http' | 'https';
+    port: number;
+}
+export declare class RouteSmsGateway implements ISmsGatewayDelegate {
+    constructor(config: RouteSmsGatewayConfig);
+    quickSend(params: QuickSendParams, callback?: Function): Promise<SendResult>;
+}

package/dist/src/lib/route-gateway.js

@@ -0,0 +1,70 @@
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RouteSmsGateway = void 0;
+const routemobilesms_1 = require("routemobilesms");
+/**
+ * Adapts routemobilesms static `sendAsync` API to {@link ISmsGatewayDelegate}.
+ */
+function toRouteDestination(to) {
+    if (typeof to === 'number') {
+        return to;
+    }
+    const digits = String(to).replace(/\D/g, '');
+    const n = Number(digits);
+    return Number.isNaN(n) ? 0 : n;
+}
+class RouteSmsGateway {
+    constructor(config) {
+        new routemobilesms_1.routeSms({
+            host: config.host,
+            username: config.username,
+            password: config.password,
+            protocol: config.protocol,
+            port: config.port
+        });
+    }
+    quickSend(params, callback) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const sendParams = {
+                From: params.From,
+                To: toRouteDestination(params.To),
+                Content: params.Content
+            };
+            if (params.Type !== undefined) {
+                sendParams.config = { type: params.Type, dlr: 0 };
+            }
+            const raw = yield routemobilesms_1.routeSms.sendAsync(sendParams);
+            let result;
+            if (raw === undefined || raw === null) {
+                result = { success: false, error: 'No response from route SMS gateway' };
+            }
+            else if (Array.isArray(raw) && raw.length > 0) {
+                const first = raw[0];
+                const ok = first.status === 'successful';
+                result = {
+                    success: ok,
+                    messageId: first.id,
+                    data: raw,
+                    error: ok ? undefined : (first.message || first.code || 'Send failed')
+                };
+            }
+            else {
+                result = { success: false, error: 'Unexpected response from route SMS gateway', data: raw };
+            }
+            if (callback) {
+                callback(result);
+            }
+            return result;
+        });
+    }
+}
+exports.RouteSmsGateway = RouteSmsGateway;

package/dist/src/lib/types.d.ts

@@ -0,0 +1,47 @@
+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;
+}
+/** Send surface used by the facade; third-party SDKs may omit `init()`. */
+export interface ISmsGatewayDelegate {
+    quickSend(params: QuickSendParams, callback?: Function): Promise<SendResult>;
+    getBalance?(): Promise<any>;
+}
+export interface ISmsGateway extends ISmsGatewayDelegate {
+    init(): ISmsGateway;
+}
+export interface NestSmsConfig {
+    apiKey: string;
+    host?: string;
+    protocol?: 'http' | 'https';
+}
+export interface NestSendResponse {
+    handshake: {
+        id: number;
+        label: string;
+    };
+    data?: any;
+}

package/dist/src/lib/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/package.json

@@ -1,11 +1,12 @@
 {
   "name": "unismsgateway",
-  "version": "1.3.0",
+  "version": "1.3.1",
   "description": "A unified SMS gateway library that brings access to multiple SMS gateways under a single API",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "scripts": {
-    "test": "echo \"Error: no test specified\" && exit 1",
+    "test": "npm run test:live",
+    "test:live": "ts-node scripts/test-live.ts",
     "build": "tsc",
     "prepublish": "npm run build"
   },
@@ -38,7 +39,10 @@
     "node": ">=12.0.0"
   },
   "devDependencies": {
+    "@types/dotenv": "^6.1.1",
     "@types/node": "^17.0.4",
+    "dotenv": "^17.4.0",
+    "ts-node": "^10.9.2",
     "typescript": "^4.5.4"
   },
   "dependencies": {