smsalert-js 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Xelandru Software SRL
+
+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

@@ -0,0 +1,158 @@
+# smsalert-js
+
+Node.js client for the [SMSAlert](https://smsalert.mobi) API. Send SMS, WhatsApp messages, and push notifications.
+
+## Installation
+
+```bash
+npm install smsalert-js
+```
+
+## Requirements
+
+- Node.js >= 18.0.0
+
+## Quick Start
+
+```js
+const { SmsAlertClient } = require('smsalert-js');
+
+const client = new SmsAlertClient('your_username', 'your_api_key');
+
+const response = await client.sendMessage('0720123456', 'Hello from smsalert-js!');
+console.log(response.id);
+```
+
+## API
+
+### `new SmsAlertClient(username, apiKey)`
+
+Create a new client. Credentials are available in your [SMSAlert dashboard](https://smsalert.mobi).
+
+---
+
+### `sendMessage(phoneNumber, message, options?)`
+
+Send a single message.
+
+```js
+const response = await client.sendMessage('0720123456', 'Hello!', {
+  cleanupUtf8: true,    // default: true
+  autoShortUrl: false,  // default: false
+  onlySmsModems: false, // default: false
+  modemId: null,        // default: null
+});
+// { id: '...', smsCount: 1, status: true }
+```
+
+---
+
+### `sendBulkMessage(phoneList, message, date?)`
+
+Send a message to multiple numbers.
+
+```js
+const { PhoneList } = require('smsalert-js');
+
+const phones = new PhoneList()
+  .addPhoneNumber('0720123456')
+  .addPhoneNumber('0730654321');
+
+const response = await client.sendBulkMessage(phones, 'Bulk message!');
+// { status: true, campaignId: 42 }
+
+// With scheduled delivery:
+const scheduled = await client.sendBulkMessage(phones, 'Scheduled bulk!', '2026-04-01 10:00:00');
+```
+
+---
+
+### `scheduleMessage(phoneNumber, message, date, modemId?)`
+
+Schedule a message for future delivery. Date format: `YYYY-MM-DD HH:mm:ss`.
+
+```js
+const response = await client.scheduleMessage(
+  '0720123456',
+  'Reminder!',
+  '2026-04-01 09:00:00'
+);
+// { id: '...', smsCount: 1, status: true }
+```
+
+---
+
+### `checkMessageStatus(id)`
+
+Check the delivery status of a message.
+
+```js
+const status = await client.checkMessageStatus('message_id_here');
+// { id: '...', modemId: '...', status: 'delivered', reason: '' }
+```
+
+Status values: `delivered`, `terminal_accepted`, `failed`, `pending`, `scheduled`, `rerouted`
+
+---
+
+### `listSentMessages(page?, perPage?)`
+
+List sent messages (paginated).
+
+```js
+const result = await client.listSentMessages(1, 50);
+// { status: true, page: 1, totalPages: 5, totalResults: 230, resultsPerPage: 50, sentMessages: [...] }
+```
+
+---
+
+### `listReceivedMessages(page?, perPage?)`
+
+List received messages (paginated).
+
+```js
+const result = await client.listReceivedMessages(1, 50);
+```
+
+---
+
+### `listDevices(page?, perPage?)`
+
+List connected devices.
+
+```js
+const result = await client.listDevices(1, 50);
+// { status: true, ..., devices: [{ id, nickName, isOnline, lastSeenAt, ... }] }
+```
+
+---
+
+## Error Handling
+
+```js
+const { InvalidCredentials, InvalidParameters, InvalidDate } = require('smsalert-js');
+
+try {
+  await client.sendMessage('0720123456', 'Hello!');
+} catch (err) {
+  if (err instanceof InvalidCredentials) {
+    console.error('Wrong username or API key');
+  } else if (err instanceof InvalidParameters) {
+    console.error('Invalid parameters:', err.message);
+  } else if (err instanceof InvalidDate) {
+    console.error('Invalid date format. Use: YYYY-MM-DD HH:mm:ss');
+  } else {
+    throw err;
+  }
+}
+```
+
+## ESM Support
+
+```js
+import { SmsAlertClient, PhoneList } from 'smsalert-js';
+```
+
+## License
+
+MIT — [smsalert.mobi](https://smsalert.mobi)

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "smsalert-js",
+  "version": "1.0.0",
+  "description": "Node.js client for the SMSAlert API - send SMS, WhatsApp and push notifications",
+  "main": "src/index.js",
+  "types": "src/index.d.ts",
+  "exports": {
+    ".": {
+      "require": "./src/index.js",
+      "import": "./src/index.mjs"
+    }
+  },
+  "files": [
+    "src/",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "node --test"
+  },
+  "keywords": [
+    "sms",
+    "smsalert",
+    "whatsapp",
+    "messaging",
+    "notifications"
+  ],
+  "author": "Alexandru Dinu <contact@smsalert.mobi>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/smsalert-mobi/smsalert-js"
+  },
+  "homepage": "https://smsalert.mobi",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "dependencies": {
+    "axios": "^1.6.0"
+  }
+}

package/src/PhoneList.js

@@ -0,0 +1,18 @@
+'use strict';
+
+class PhoneList {
+  constructor() {
+    this._list = [];
+  }
+
+  addPhoneNumber(phoneNumber) {
+    this._list.push(phoneNumber);
+    return this;
+  }
+
+  getPhoneList() {
+    return this._list;
+  }
+}
+
+module.exports = PhoneList;

package/src/SmsAlertClient.js

@@ -0,0 +1,127 @@
+'use strict';
+
+const axios = require('axios');
+const { InvalidCredentials, InvalidParameters, InvalidDate } = require('./errors');
+
+const BASE_URL = 'https://smsalert.mobi/api/v2';
+const DATE_REGEX = /^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}$/;
+
+class SmsAlertClient {
+  constructor(username, apiKey) {
+    this._http = axios.create({
+      baseURL: BASE_URL,
+      auth: { username, password: apiKey },
+      headers: { 'Content-Type': 'application/json' },
+    });
+
+    this._http.interceptors.response.use(
+      (res) => res,
+      (err) => {
+        if (err.response?.status === 401) throw new InvalidCredentials();
+        if (err.response?.status === 422) throw new InvalidParameters(JSON.stringify(err.response.data));
+        throw err;
+      }
+    );
+  }
+
+  /**
+   * Send a single SMS message.
+   * @param {string} phoneNumber
+   * @param {string} message
+   * @param {object} [options]
+   * @param {boolean} [options.cleanupUtf8=true]
+   * @param {boolean} [options.autoShortUrl=false]
+   * @param {boolean} [options.onlySmsModems=false]
+   * @param {string|null} [options.modemId=null]
+   * @returns {Promise<{id: string, smsCount: number, status: boolean}>}
+   */
+  async sendMessage(phoneNumber, message, options = {}) {
+    const { cleanupUtf8 = true, autoShortUrl = false, onlySmsModems = false, modemId = null } = options;
+
+    const payload = { phoneNumber, message, cleanupUtf8, autoShortUrl, onlySmsModems };
+    if (modemId) payload.modemId = modemId;
+
+    const { data } = await this._http.post('/message/send', payload);
+    return data;
+  }
+
+  /**
+   * Send a message to multiple phone numbers.
+   * @param {import('./PhoneList')} phoneList
+   * @param {string} message
+   * @param {string|null} [date=null] - Format: "YYYY-MM-DD HH:mm:ss"
+   * @returns {Promise<{status: boolean, campaignId: number}>}
+   */
+  async sendBulkMessage(phoneList, message, date = null) {
+    if (date && !DATE_REGEX.test(date)) throw new InvalidDate();
+
+    const payload = { phoneList: phoneList.getPhoneList(), message };
+    if (date) payload.date = date;
+
+    const { data } = await this._http.post('/message/bulk', payload);
+    return data;
+  }
+
+  /**
+   * Schedule a message for future delivery.
+   * @param {string} phoneNumber
+   * @param {string} message
+   * @param {string} date - Format: "YYYY-MM-DD HH:mm:ss"
+   * @param {string|null} [modemId=null]
+   * @returns {Promise<{id: string, smsCount: number, status: boolean}>}
+   */
+  async scheduleMessage(phoneNumber, message, date, modemId = null) {
+    if (!DATE_REGEX.test(date)) throw new InvalidDate();
+
+    const payload = { phoneNumber, message, date };
+    if (modemId) payload.modemId = modemId;
+
+    const { data } = await this._http.post('/message/schedule', payload);
+    return data;
+  }
+
+  /**
+   * Check the delivery status of a message.
+   * @param {string} id - Message ID
+   * @returns {Promise<{id: string, modemId: string, status: string, reason: string}>}
+   */
+  async checkMessageStatus(id) {
+    const { data } = await this._http.post('/message/getStatus', { id });
+    return data;
+  }
+
+  /**
+   * List sent messages (paginated).
+   * @param {number} [page=1]
+   * @param {number} [perPage=50]
+   * @returns {Promise<{status: boolean, page: number, totalPages: number, totalResults: number, resultsPerPage: number, sentMessages: Array}>}
+   */
+  async listSentMessages(page = 1, perPage = 50) {
+    const { data } = await this._http.get('/message/sent/list', { params: { page, perPage } });
+    return data;
+  }
+
+  /**
+   * List received messages (paginated).
+   * @param {number} [page=1]
+   * @param {number} [perPage=50]
+   * @returns {Promise<{status: boolean, page: number, totalPages: number, totalResults: number, resultsPerPage: number, sentMessages: Array}>}
+   */
+  async listReceivedMessages(page = 1, perPage = 50) {
+    const { data } = await this._http.get('/message/list', { params: { page, perPage } });
+    return data;
+  }
+
+  /**
+   * List devices (paginated).
+   * @param {number} [page=1]
+   * @param {number} [perPage=50]
+   * @returns {Promise<{status: boolean, page: number, totalPages: number, totalResults: number, resultsPerPage: number, devices: Array}>}
+   */
+  async listDevices(page = 1, perPage = 50) {
+    const { data } = await this._http.get('/device/list', { params: { page, perPage } });
+    return data;
+  }
+}
+
+module.exports = SmsAlertClient;

package/src/errors.js

@@ -0,0 +1,24 @@
+'use strict';
+
+class InvalidCredentials extends Error {
+  constructor(message = 'Invalid credentials') {
+    super(message);
+    this.name = 'InvalidCredentials';
+  }
+}
+
+class InvalidParameters extends Error {
+  constructor(message = 'Invalid parameters') {
+    super(message);
+    this.name = 'InvalidParameters';
+  }
+}
+
+class InvalidDate extends Error {
+  constructor(message = 'Invalid date format. Use: YYYY-MM-DD HH:mm:ss') {
+    super(message);
+    this.name = 'InvalidDate';
+  }
+}
+
+module.exports = { InvalidCredentials, InvalidParameters, InvalidDate };

package/src/index.d.ts

@@ -0,0 +1,90 @@
+export declare class PhoneList {
+  addPhoneNumber(phoneNumber: string): this;
+  getPhoneList(): string[];
+}
+
+export interface SendMessageOptions {
+  cleanupUtf8?: boolean;
+  autoShortUrl?: boolean;
+  onlySmsModems?: boolean;
+  modemId?: string | null;
+}
+
+export interface SendMessageResponse {
+  id: string;
+  smsCount: number;
+  status: boolean;
+}
+
+export interface SendBulkMessageResponse {
+  status: boolean;
+  campaignId: number;
+}
+
+export interface MessageStatusResponse {
+  id: string;
+  modemId: string;
+  status: string;
+  reason: string;
+}
+
+export interface SentMessage {
+  id: string;
+  message: string;
+  to: string;
+  status: string;
+  failReason?: string;
+  sentAt: string;
+}
+
+export interface ReceivedMessage {
+  id: string;
+  message: string;
+  from: string;
+  seen: boolean;
+  receivedAt: string;
+}
+
+export interface Device {
+  id: string;
+  nickName: string;
+  lastSeenAt?: string;
+  isOnline: boolean;
+  connectionToken?: string;
+  version?: string;
+}
+
+export interface PaginatedResponse<T> {
+  status: boolean;
+  page: number;
+  totalPages: number;
+  totalResults: number;
+  resultsPerPage: number;
+}
+
+export interface ListSentMessagesResponse extends PaginatedResponse<SentMessage> {
+  sentMessages: SentMessage[];
+}
+
+export interface ListReceivedMessagesResponse extends PaginatedResponse<ReceivedMessage> {
+  sentMessages: ReceivedMessage[];
+}
+
+export interface ListDevicesResponse extends PaginatedResponse<Device> {
+  devices: Device[];
+}
+
+export declare class SmsAlertClient {
+  constructor(username: string, apiKey: string);
+  sendMessage(phoneNumber: string, message: string, options?: SendMessageOptions): Promise<SendMessageResponse>;
+  sendBulkMessage(phoneList: PhoneList, message: string, date?: string | null): Promise<SendBulkMessageResponse>;
+  scheduleMessage(phoneNumber: string, message: string, date: string, modemId?: string | null): Promise<SendMessageResponse>;
+  checkMessageStatus(id: string): Promise<MessageStatusResponse>;
+  listSentMessages(page?: number, perPage?: number): Promise<ListSentMessagesResponse>;
+  listReceivedMessages(page?: number, perPage?: number): Promise<ListReceivedMessagesResponse>;
+  listDevices(page?: number, perPage?: number): Promise<ListDevicesResponse>;
+}
+
+export declare class InvalidCredentials extends Error {}
+export declare class InvalidParameters extends Error {}
+export declare class InvalidDate extends Error {}

package/src/index.js

@@ -0,0 +1,13 @@
+'use strict';
+
+const SmsAlertClient = require('./SmsAlertClient');
+const PhoneList = require('./PhoneList');
+const { InvalidCredentials, InvalidParameters, InvalidDate } = require('./errors');
+
+module.exports = {
+  SmsAlertClient,
+  PhoneList,
+  InvalidCredentials,
+  InvalidParameters,
+  InvalidDate,
+};

package/src/index.mjs

@@ -0,0 +1,10 @@
+import { createRequire } from 'module';
+const require = createRequire(import.meta.url);
+const pkg = require('./index.js');
+
+export const SmsAlertClient = pkg.SmsAlertClient;
+export const PhoneList = pkg.PhoneList;
+export const InvalidCredentials = pkg.InvalidCredentials;
+export const InvalidParameters = pkg.InvalidParameters;
+export const InvalidDate = pkg.InvalidDate;
+export default pkg.SmsAlertClient;