plexisms 1.0.0

package/README.md

@@ -0,0 +1,91 @@
+# PlexiSMS Node.js SDK
+
+The official Node.js library for the [PlexiSMS](https://plexisms.com) API. Send SMS, manage OTPs, and check detailed analytics with our reliable Tier-1 network.
+
+## Installation
+
+```bash
+npm install plexisms
+# or
+yarn add plexisms
+```
+
+## Usage
+
+### 1. Initialize the Client
+
+```typescript
+import { Client } from 'plexisms';
+
+// Option 1: Pass API Key directly
+const client = new Client('your_api_key_here');
+
+// Option 2: Use environment variable 'PLEXISMS_API_KEY'
+// const client = new Client();
+```
+
+### 2. Send an SMS
+
+```typescript
+try {
+  const result = await client.messages.create({
+    to: '+243970000000', // Replace with your phone number
+    body: 'Hello from Node.js! 🚀',
+    senderId: 'MyApp' // Replace with your sender ID
+  });
+  
+  console.log('SMS Sent! ID:', result.message_id);
+} catch (error) {
+  console.error('Error:', error.message);
+}
+```
+
+### 3. Send Bulk SMS
+
+```typescript
+const result = await client.messages.createBulk({
+  phoneNumbers: ['+243970000000', '+243810000000'],
+  body: 'Bulk message test',
+  senderId: 'MyApp'
+});
+console.log(`Queued ${result.queued} messages`);
+```
+
+### 4. OTP Verification
+
+```typescript
+// Step 1: Send OTP
+const otpRes = await client.otp.send('+243970000000', 'MyService');
+const verificationId = otpRes.verification_id;
+
+// Step 2: Verify Code
+const verifyRes = await client.otp.verify(verificationId, '123456');
+
+if (verifyRes.verified) {
+  console.log('User verified successfully!');
+} else {
+  console.log('Invalid code');
+}
+```
+
+## Error Handling
+
+```typescript
+import { AuthenticationError, BalanceError } from 'plexisms';
+
+try {
+  await client.messages.create({...});
+} catch (error) {
+  if (error instanceof AuthenticationError) {
+    console.error('Check your API Key');
+  } else if (error instanceof BalanceError) {
+    console.error('Top up your account');
+  } else {
+    console.error('Unknown error:', error);
+  }
+}
+```
+
+## License
+
+MIT

package/dist/client.d.ts

@@ -0,0 +1,51 @@
+import { AxiosInstance } from 'axios';
+import { SendSMSOptions, SMSResponse, SendBulkSMSOptions, BulkSMSResponse, OTPRequestResponse, OTPVerifyResponse, BalanceResponse, MessageStatusResponse } from './types';
+export declare class Client {
+    private client;
+    private readonly DEFAULT_BASE_URL;
+    messages: Messages;
+    otp: OTP;
+    account: Account;
+    /**
+     * @param apiKey Your PlexiSMS API Key.
+     * @param baseUrl Optional override for API URL.
+     */
+    constructor(apiKey?: string, baseUrl?: string);
+}
+declare class Resource {
+    protected client: AxiosInstance;
+    constructor(client: AxiosInstance);
+    protected request<T>(method: 'get' | 'post', endpoint: string, data?: Record<string, unknown>, params?: Record<string, unknown>): Promise<T>;
+    protected handleError(error: unknown): void;
+}
+export declare class Messages extends Resource {
+    /**
+     * Send a single SMS
+     */
+    create(options: SendSMSOptions): Promise<SMSResponse>;
+    /**
+     * Send bulk SMS
+     */
+    createBulk(options: SendBulkSMSOptions): Promise<BulkSMSResponse>;
+    /**
+     * Get SMS status
+     */
+    get(messageId: string | number): Promise<MessageStatusResponse>;
+}
+export declare class OTP extends Resource {
+    /**
+     * Send an OTP code
+     */
+    send(to: string, brand?: string): Promise<OTPRequestResponse>;
+    /**
+     * Verify an OTP code
+     */
+    verify(verificationId: string, code: string): Promise<OTPVerifyResponse>;
+}
+export declare class Account extends Resource {
+    /**
+     * Check account balance
+     */
+    balance(): Promise<BalanceResponse>;
+}
+export {};

package/dist/client.js

@@ -0,0 +1,138 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Account = exports.OTP = exports.Messages = exports.Client = void 0;
+const axios_1 = __importDefault(require("axios"));
+const exceptions_1 = require("./exceptions");
+class Client {
+    /**
+     * @param apiKey Your PlexiSMS API Key.
+     * @param baseUrl Optional override for API URL.
+     */
+    constructor(apiKey, baseUrl) {
+        this.DEFAULT_BASE_URL = "https://server.plexisms.com";
+        const token = apiKey || process.env.PLEXISMS_API_KEY;
+        if (!token) {
+            throw new exceptions_1.AuthenticationError("API Key is required. Pass it to the constructor or set PLEXISMS_API_KEY environment variable.");
+        }
+        this.client = axios_1.default.create({
+            baseURL: (baseUrl || process.env.PLEXISMS_BASE_URL || this.DEFAULT_BASE_URL).replace(/\/$/, ""),
+            headers: {
+                'Authorization': `Token ${token}`,
+                'Content-Type': 'application/json',
+                'User-Agent': 'plexisms-node/1.0.0'
+            }
+        });
+        this.messages = new Messages(this.client);
+        this.otp = new OTP(this.client);
+        this.account = new Account(this.client);
+    }
+}
+exports.Client = Client;
+class Resource {
+    constructor(client) {
+        this.client = client;
+    }
+    async request(method, endpoint, data, params) {
+        try {
+            const response = await this.client.request({
+                method,
+                url: endpoint,
+                data,
+                params
+            });
+            return response.data;
+        }
+        catch (error) {
+            this.handleError(error);
+            throw error; // Should be unreachable given handleError throws
+        }
+    }
+    handleError(error) {
+        var _a, _b;
+        if (axios_1.default.isAxiosError(error)) {
+            const status = (_a = error.response) === null || _a === void 0 ? void 0 : _a.status;
+            const data = (_b = error.response) === null || _b === void 0 ? void 0 : _b.data;
+            const message = ((data === null || data === void 0 ? void 0 : data.error) || (data === null || data === void 0 ? void 0 : data.detail) || error.message);
+            if (status === 401 || status === 403) {
+                throw new exceptions_1.AuthenticationError(`Unauthorized: ${message}`);
+            }
+            else if (status === 402) {
+                throw new exceptions_1.BalanceError(`Insufficient funds: ${message}`);
+            }
+            else if (status && status >= 500) {
+                throw new exceptions_1.APIError(`Server Error (${status}): ${message}`, status, data);
+            }
+            else if (status) {
+                throw new exceptions_1.APIError(`API Error (${status}): ${message}`, status, data);
+            }
+            else {
+                throw new exceptions_1.PlexismsError(`Network Error: ${error.message}`);
+            }
+        }
+        throw new exceptions_1.PlexismsError(`Unexpected Error: ${error}`);
+    }
+}
+class Messages extends Resource {
+    /**
+     * Send a single SMS
+     */
+    async create(options) {
+        return this.request('post', '/api/sms/send/', {
+            phone_number: options.to,
+            message: options.body,
+            sender_id: options.senderId,
+            sms_type: options.smsType || 'transactional'
+        });
+    }
+    /**
+     * Send bulk SMS
+     */
+    async createBulk(options) {
+        return this.request('post', '/api/sms/send-bulk/', {
+            phone_numbers: options.phoneNumbers,
+            message: options.body,
+            sender_id: options.senderId,
+            sms_type: options.smsType || 'transactional'
+        });
+    }
+    /**
+     * Get SMS status
+     */
+    async get(messageId) {
+        return this.request('get', `/api/sms/${messageId}/status/`);
+    }
+}
+exports.Messages = Messages;
+class OTP extends Resource {
+    /**
+     * Send an OTP code
+     */
+    async send(to, brand = "PlexiSMS") {
+        return this.request('post', '/api/sms/send-otp/', {
+            phone_number: to,
+            brand
+        });
+    }
+    /**
+     * Verify an OTP code
+     */
+    async verify(verificationId, code) {
+        return this.request('post', '/api/sms/verify-otp/', {
+            verification_id: verificationId,
+            otp_code: code
+        });
+    }
+}
+exports.OTP = OTP;
+class Account extends Resource {
+    /**
+     * Check account balance
+     */
+    async balance() {
+        return this.request('get', '/api/sms/balance/');
+    }
+}
+exports.Account = Account;

package/dist/exceptions.d.ts

@@ -0,0 +1,14 @@
+export declare class PlexismsError extends Error {
+    constructor(message: string);
+}
+export declare class AuthenticationError extends PlexismsError {
+    constructor(message: string);
+}
+export declare class BalanceError extends PlexismsError {
+    constructor(message: string);
+}
+export declare class APIError extends PlexismsError {
+    statusCode?: number;
+    responseBody?: Record<string, unknown>;
+    constructor(message: string, statusCode?: number, responseBody?: Record<string, unknown>);
+}

package/dist/exceptions.js

@@ -0,0 +1,33 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.APIError = exports.BalanceError = exports.AuthenticationError = exports.PlexismsError = void 0;
+class PlexismsError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'PlexismsError';
+    }
+}
+exports.PlexismsError = PlexismsError;
+class AuthenticationError extends PlexismsError {
+    constructor(message) {
+        super(message);
+        this.name = 'AuthenticationError';
+    }
+}
+exports.AuthenticationError = AuthenticationError;
+class BalanceError extends PlexismsError {
+    constructor(message) {
+        super(message);
+        this.name = 'BalanceError';
+    }
+}
+exports.BalanceError = BalanceError;
+class APIError extends PlexismsError {
+    constructor(message, statusCode, responseBody) {
+        super(message);
+        this.name = 'APIError';
+        this.statusCode = statusCode;
+        this.responseBody = responseBody;
+    }
+}
+exports.APIError = APIError;

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export * from './client';
+export * from './exceptions';
+export * from './types';

package/dist/index.js

@@ -0,0 +1,19 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (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("./client"), exports);
+__exportStar(require("./exceptions"), exports);
+__exportStar(require("./types"), exports);

package/dist/types.d.ts

@@ -0,0 +1,56 @@
+export interface SMSResponse {
+    id: number;
+    message_id: string;
+    status: 'pending' | 'sent' | 'delivered' | 'failed';
+    phone_number: string;
+    parts: number;
+    cost_usd: string;
+    balance: {
+        remaining_usd: string;
+        remaining_sms: number;
+    };
+}
+export interface BulkSMSResponse {
+    total: number;
+    queued: number;
+    task_id: string;
+    message: string;
+}
+export interface OTPRequestResponse {
+    verification_id: string;
+    status: string;
+    phone_number: string;
+    expires_in: number;
+}
+export interface OTPVerifyResponse {
+    verified: boolean;
+    phone_number?: string;
+    error?: string;
+}
+export interface BalanceResponse {
+    amount: string;
+    currency: string;
+    provider: string;
+}
+export interface SendSMSOptions {
+    to: string;
+    body: string;
+    senderId?: string;
+    smsType?: 'transactional' | 'promotional';
+}
+export interface SendBulkSMSOptions {
+    phoneNumbers: string[];
+    body: string;
+    senderId?: string;
+    smsType?: 'transactional' | 'promotional';
+}
+export interface MessageStatusResponse {
+    id: number;
+    message_id: string;
+    status: 'pending' | 'sent' | 'delivered' | 'failed';
+    phone_number: string;
+    parts: number;
+    cost_usd: string;
+    created_at: string;
+    updated_at: string;
+}

package/dist/types.js

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

package/eslint.config.js

@@ -0,0 +1,12 @@
+const tseslint = require('typescript-eslint');
+
+module.exports = tseslint.config(
+  {
+    files: ['**/*.ts'],
+    extends: [
+      ...tseslint.configs.recommended,
+    ],
+    rules: {
+    },
+  },
+);

package/jest.config.js

@@ -0,0 +1,4 @@
+module.exports = {
+  preset: 'ts-jest',
+  testEnvironment: 'node',
+};

package/package.json

@@ -0,0 +1,47 @@
+{
+    "name": "plexisms",
+    "version": "1.0.0",
+    "description": "Official Node.js SDK for PlexiSMS API",
+    "main": "dist/index.js",
+    "types": "dist/index.d.ts",
+    "scripts": {
+        "build": "tsc",
+        "lint": "eslint 'src/**/*.ts'",
+        "prepublishOnly": "npm run build",
+        "test": "jest"
+    },
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/plexisms/sdk-plexisms-js.git"
+    },
+    "keywords": [
+        "sms",
+        "plexisms",
+        "sms rdc",
+        "sms congo",
+        "sms kinshasa",
+        "otp",
+        "api",
+        "sdk"
+    ],
+    "author": "PlexiSMS Team <dev@plexisms.com>",
+    "license": "MIT",
+    "bugs": {
+        "url": "https://github.com/plexisms/sdk-plexisms-js/issues"
+    },
+    "homepage": "https://plexisms.com/developers",
+    "devDependencies": {
+        "@types/jest": "^30.0.0",
+        "@types/node": "^18.0.0",
+        "@typescript-eslint/eslint-plugin": "^8.54.0",
+        "@typescript-eslint/parser": "^8.54.0",
+        "eslint": "^9.39.2",
+        "jest": "^30.2.0",
+        "ts-jest": "^29.4.6",
+        "typescript": "^5.0.0",
+        "typescript-eslint": "^8.54.0"
+    },
+    "dependencies": {
+        "axios": "^1.6.0"
+    }
+}

package/src/client.ts

@@ -0,0 +1,159 @@
+import axios, { AxiosInstance } from 'axios';
+import {
+    AuthenticationError,
+    BalanceError,
+    APIError,
+    PlexismsError
+} from './exceptions';
+import {
+    SendSMSOptions,
+    SMSResponse,
+    SendBulkSMSOptions,
+    BulkSMSResponse,
+    OTPRequestResponse,
+    OTPVerifyResponse,
+    BalanceResponse,
+    MessageStatusResponse
+} from './types';
+
+export class Client {
+    private client: AxiosInstance;
+    private readonly DEFAULT_BASE_URL = "https://server.plexisms.com";
+
+    public messages: Messages;
+    public otp: OTP;
+    public account: Account;
+
+    /**
+     * @param apiKey Your PlexiSMS API Key.
+     * @param baseUrl Optional override for API URL.
+     */
+    constructor(apiKey?: string, baseUrl?: string) {
+        const token = apiKey || process.env.PLEXISMS_API_KEY;
+
+        if (!token) {
+            throw new AuthenticationError("API Key is required. Pass it to the constructor or set PLEXISMS_API_KEY environment variable.");
+        }
+
+        this.client = axios.create({
+            baseURL: (baseUrl || process.env.PLEXISMS_BASE_URL || this.DEFAULT_BASE_URL).replace(/\/$/, ""),
+            headers: {
+                'Authorization': `Token ${token}`,
+                'Content-Type': 'application/json',
+                'User-Agent': 'plexisms-node/1.0.0'
+            }
+        });
+
+        this.messages = new Messages(this.client);
+        this.otp = new OTP(this.client);
+        this.account = new Account(this.client);
+    }
+}
+
+class Resource {
+    protected client: AxiosInstance;
+
+    constructor(client: AxiosInstance) {
+        this.client = client;
+    }
+
+    protected async request<T>(method: 'get' | 'post', endpoint: string, data?: Record<string, unknown>, params?: Record<string, unknown>): Promise<T> {
+        try {
+            const response = await this.client.request<T>({
+                method,
+                url: endpoint,
+                data,
+                params
+            });
+            return response.data;
+        } catch (error: unknown) {
+            this.handleError(error);
+            throw error; // Should be unreachable given handleError throws
+        }
+    }
+
+    protected handleError(error: unknown): void {
+        if (axios.isAxiosError(error)) {
+            const status = error.response?.status;
+            const data = error.response?.data as Record<string, unknown>;
+            const message = (data?.error || data?.detail || error.message) as string;
+
+            if (status === 401 || status === 403) {
+                throw new AuthenticationError(`Unauthorized: ${message}`);
+            } else if (status === 402) {
+                throw new BalanceError(`Insufficient funds: ${message}`);
+            } else if (status && status >= 500) {
+                throw new APIError(`Server Error (${status}): ${message}`, status, data);
+            } else if (status) {
+                throw new APIError(`API Error (${status}): ${message}`, status, data);
+            } else {
+                throw new PlexismsError(`Network Error: ${error.message}`);
+            }
+        }
+        throw new PlexismsError(`Unexpected Error: ${error}`);
+    }
+}
+
+export class Messages extends Resource {
+    /**
+     * Send a single SMS
+     */
+    async create(options: SendSMSOptions): Promise<SMSResponse> {
+        return this.request<SMSResponse>('post', '/api/sms/send/', {
+            phone_number: options.to,
+            message: options.body,
+            sender_id: options.senderId,
+            sms_type: options.smsType || 'transactional'
+        });
+    }
+
+    /**
+     * Send bulk SMS
+     */
+    async createBulk(options: SendBulkSMSOptions): Promise<BulkSMSResponse> {
+        return this.request<BulkSMSResponse>('post', '/api/sms/send-bulk/', {
+            phone_numbers: options.phoneNumbers,
+            message: options.body,
+            sender_id: options.senderId,
+            sms_type: options.smsType || 'transactional'
+        });
+    }
+
+    /**
+     * Get SMS status
+     */
+    async get(messageId: string | number): Promise<MessageStatusResponse> {
+        return this.request('get', `/api/sms/${messageId}/status/`);
+    }
+}
+
+export class OTP extends Resource {
+    /**
+     * Send an OTP code
+     */
+    async send(to: string, brand: string = "PlexiSMS"): Promise<OTPRequestResponse> {
+        return this.request<OTPRequestResponse>('post', '/api/sms/send-otp/', {
+            phone_number: to,
+            brand
+        });
+    }
+
+    /**
+     * Verify an OTP code
+     */
+    async verify(verificationId: string, code: string): Promise<OTPVerifyResponse> {
+        return this.request<OTPVerifyResponse>('post', '/api/sms/verify-otp/', {
+            verification_id: verificationId,
+            otp_code: code
+        });
+    }
+}
+
+export class Account extends Resource {
+    /**
+     * Check account balance
+     */
+    async balance(): Promise<BalanceResponse> {
+        return this.request<BalanceResponse>('get', '/api/sms/balance/');
+    }
+}

package/src/exceptions.ts

@@ -0,0 +1,32 @@
+export class PlexismsError extends Error {
+    constructor(message: string) {
+        super(message);
+        this.name = 'PlexismsError';
+    }
+}
+
+export class AuthenticationError extends PlexismsError {
+    constructor(message: string) {
+        super(message);
+        this.name = 'AuthenticationError';
+    }
+}
+
+export class BalanceError extends PlexismsError {
+    constructor(message: string) {
+        super(message);
+        this.name = 'BalanceError';
+    }
+}
+
+export class APIError extends PlexismsError {
+    statusCode?: number;
+    responseBody?: Record<string, unknown>;
+
+    constructor(message: string, statusCode?: number, responseBody?: Record<string, unknown>) {
+        super(message);
+        this.name = 'APIError';
+        this.statusCode = statusCode;
+        this.responseBody = responseBody;
+    }
+}

package/src/index.ts

@@ -0,0 +1,3 @@
+export * from './client';
+export * from './exceptions';
+export * from './types';

package/src/types.ts

@@ -0,0 +1,63 @@
+export interface SMSResponse {
+    id: number;
+    message_id: string;
+    status: 'pending' | 'sent' | 'delivered' | 'failed';
+    phone_number: string;
+    parts: number;
+    cost_usd: string;
+    balance: {
+        remaining_usd: string;
+        remaining_sms: number;
+    };
+}
+
+export interface BulkSMSResponse {
+    total: number;
+    queued: number;
+    task_id: string;
+    message: string;
+}
+
+export interface OTPRequestResponse {
+    verification_id: string;
+    status: string;
+    phone_number: string;
+    expires_in: number;
+}
+
+export interface OTPVerifyResponse {
+    verified: boolean;
+    phone_number?: string;
+    error?: string;
+}
+
+export interface BalanceResponse {
+    amount: string;
+    currency: string;
+    provider: string;
+}
+
+export interface SendSMSOptions {
+    to: string;
+    body: string;
+    senderId?: string;
+    smsType?: 'transactional' | 'promotional';
+}
+
+export interface SendBulkSMSOptions {
+    phoneNumbers: string[];
+    body: string;
+    senderId?: string;
+    smsType?: 'transactional' | 'promotional';
+}
+
+export interface MessageStatusResponse {
+    id: number;
+    message_id: string;
+    status: 'pending' | 'sent' | 'delivered' | 'failed';
+    phone_number: string;
+    parts: number;
+    cost_usd: string;
+    created_at: string;
+    updated_at: string;
+}

package/tests/client.test.ts

@@ -0,0 +1,5 @@
+describe('PlexiSMS Client', () => {
+  it('should be true', () => {
+    expect(true).toBe(true);
+  });
+});

package/tsconfig.json

@@ -0,0 +1,24 @@
+{
+    "compilerOptions": {
+        "target": "es2018",
+        "module": "commonjs",
+        "lib": [
+            "es2018",
+            "dom"
+        ],
+        "declaration": true,
+        "strict": true,
+        "esModuleInterop": true,
+        "skipLibCheck": true,
+        "forceConsistentCasingInFileNames": true,
+        "outDir": "./dist",
+        "rootDir": "./src"
+    },
+    "include": [
+        "src/**/*"
+    ],
+    "exclude": [
+        "node_modules",
+        "**/*.spec.ts"
+    ]
+}