@quartix/sms 1.1.0

package/README.md

@@ -0,0 +1,83 @@
+# @quartix/sms
+
+The official Node.js SDK for the Quartix SMS Gateway. Send SMS messages programmatically through your own Android devices.
+
+## Installation
+
+```bash
+npm install @quartix/sms
+```
+
+## Quick Start (ID-only Auth)
+
+```typescript
+import { QuartixSms } from '@quartix/sms';
+
+// Use your Gateway ID as the API Key for simplified setup
+const sms = new QuartixSms({
+  apiKey: 'YOUR_GATEWAY_ID', 
+  baseUrl: 'https://api.quartix.in' // Optional
+});
+
+async function main() {
+  try {
+    const result = await sms.send({
+      to: '+919876543210',
+      message: 'Hello from Quartix SDK!'
+    });
+    
+    console.log('Message sent! ID:', result.messageId);
+  } catch (error) {
+    console.error('Failed to send SMS:', error.message);
+  }
+}
+
+main();
+```
+
+## Batch Sending
+
+Send multiple messages in a single API call for maximum efficiency.
+
+```typescript
+const batchResult = await sms.sendBatch({
+  messages: [
+    { to: '+919000000001', message: 'Alert 1' },
+    { to: '+919000000002', message: 'Alert 2' },
+  ]
+});
+
+console.log(`Successfully queued ${batchResult.totalSent} messages.`);
+```
+
+## Features
+
+- **Simplified Auth**: Use your Gateway ID directly as the token.
+- **Send SMS**: Queue messages to be sent by your connected Android devices.
+- **Batch Operations**: Send messages to multiple recipients in one go.
+- **Message Status**: Track if your message is PENDING, SENT, or DELIVERED.
+- **TypeScript Support**: Full type safety out of the box.
+
+## API Reference
+
+### `new QuartixSms(options)`
+- `apiKey`: Your Gateway ID or Account API Key.
+- `baseUrl`: The API endpoint (defaults to production).
+- `timeout`: Request timeout in ms (default: 30000).
+
+### `sms.send(options)`
+- `to`: Recipient phone number.
+- `message`: Text content.
+- `simIndex`: (Optional) Use specific SIM slot (0 or 1).
+- `gatewayId`: (Optional) Override targeted gateway.
+
+### `sms.sendBatch(options)`
+- `messages`: Array of message objects (to, message, simIndex).
+- `gatewayId`: (Optional) Global gateway override for the batch.
+
+### `sms.getMessageStatus(id)`
+- Returns the current status of a message.
+
+## License
+
+MIT

package/dist/index.cjs

@@ -0,0 +1,147 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  AuthenticationError: () => AuthenticationError,
+  QuartixSms: () => QuartixSms,
+  QuartixSmsError: () => QuartixSmsError,
+  ValidationError: () => ValidationError
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/errors.ts
+var QuartixSmsError = class extends Error {
+  constructor(message, statusCode, response) {
+    super(message);
+    this.statusCode = statusCode;
+    this.response = response;
+    this.name = "QuartixSmsError";
+  }
+  statusCode;
+  response;
+};
+var AuthenticationError = class extends QuartixSmsError {
+  constructor(message = "Invalid API Key") {
+    super(message, 401);
+    this.name = "AuthenticationError";
+  }
+};
+var ValidationError = class extends QuartixSmsError {
+  constructor(message) {
+    super(message, 400);
+    this.name = "ValidationError";
+  }
+};
+
+// src/client.ts
+var QuartixSms = class {
+  options;
+  constructor(options) {
+    if (!options.apiKey) {
+      throw new ValidationError("API Key is required");
+    }
+    this.options = {
+      apiKey: options.apiKey,
+      baseUrl: options.baseUrl || "https://api.quartix.in",
+      timeout: options.timeout || 3e4
+    };
+  }
+  async request(path, init) {
+    const url = new URL(path, this.options.baseUrl.endsWith("/") ? this.options.baseUrl : `${this.options.baseUrl}/`);
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), this.options.timeout);
+    try {
+      const response = await fetch(url.toString(), {
+        ...init,
+        headers: {
+          "Content-Type": "application/json",
+          "x-gateway-api-key": this.options.apiKey,
+          "Authorization": `Bearer ${this.options.apiKey}`,
+          "User-Agent": "QuartixSmsSDK/1.0.0 (Node.js)",
+          ...init?.headers
+        },
+        signal: controller.signal
+      });
+      const data = await response.json().catch(() => ({}));
+      if (!response.ok) {
+        if (response.status === 401) throw new AuthenticationError(data.message);
+        if (response.status === 400) throw new ValidationError(data.message);
+        throw new QuartixSmsError(data.message || "API Request Failed", response.status, data);
+      }
+      return data;
+    } catch (error) {
+      if (error.name === "AbortError") {
+        throw new QuartixSmsError("Request Timeout", 408);
+      }
+      if (error instanceof QuartixSmsError) throw error;
+      throw new QuartixSmsError(error.message || "Network Error");
+    } finally {
+      clearTimeout(timeoutId);
+    }
+  }
+  /**
+   * Sends a single SMS message.
+   */
+  async send(options) {
+    const { to, message, simIndex = 0, externalId } = options;
+    if (!to || !message) {
+      throw new ValidationError("Recipient and message body are required");
+    }
+    const data = await this.request("api/sms/send", {
+      method: "POST",
+      body: JSON.stringify({
+        recipient: to,
+        body: message,
+        sim_index: simIndex,
+        external_id: externalId
+      })
+    });
+    return {
+      success: true,
+      messageId: data.id,
+      status: data.status || "PENDING"
+    };
+  }
+  /**
+   * Retrieves the status of a specific message.
+   */
+  async getMessageStatus(messageId) {
+    const data = await this.request(`api/sms/messages/${messageId}`);
+    return {
+      success: true,
+      messageId: data.id,
+      status: data.status
+    };
+  }
+  /**
+   * Retrieves overall statistics for the account/gateway.
+   */
+  async getStats() {
+    return this.request("api/sms/stats");
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  AuthenticationError,
+  QuartixSms,
+  QuartixSmsError,
+  ValidationError
+});

package/dist/index.d.cts

@@ -0,0 +1,81 @@
+interface QuartixSmsOptions {
+    /**
+     * Your Quartix API Key.
+     * Can be an Account-level API Key or a Gateway-specific API Key.
+     */
+    apiKey: string;
+    /**
+     * The base URL of the Quartix SMS Gateway backend.
+     * @default "https://api.quartix.in"
+     */
+    baseUrl?: string;
+    /**
+     * Optional timeout for requests in milliseconds.
+     * @default 30000
+     */
+    timeout?: number;
+}
+interface SendSmsOptions {
+    /**
+     * The recipient phone number in E.164 format (e.g., +919876543210).
+     */
+    to: string;
+    /**
+     * The message content.
+     */
+    message: string;
+    /**
+     * Optional SIM index to use (0 or 1).
+     * @default 0
+     */
+    simIndex?: number;
+    /**
+     * Optional custom ID to track this message in your own system.
+     */
+    externalId?: string;
+}
+interface SmsResponse {
+    success: boolean;
+    messageId?: string;
+    status: 'PENDING' | 'SENT' | 'DELIVERED' | 'FAILED';
+    error?: string;
+}
+interface GatewayStats {
+    totalSent: number;
+    totalPending: number;
+    totalFailed: number;
+    isActive: boolean;
+    lastSeen?: string;
+}
+
+declare class QuartixSms {
+    private options;
+    constructor(options: QuartixSmsOptions);
+    private request;
+    /**
+     * Sends a single SMS message.
+     */
+    send(options: SendSmsOptions): Promise<SmsResponse>;
+    /**
+     * Retrieves the status of a specific message.
+     */
+    getMessageStatus(messageId: string): Promise<SmsResponse>;
+    /**
+     * Retrieves overall statistics for the account/gateway.
+     */
+    getStats(): Promise<GatewayStats>;
+}
+
+declare class QuartixSmsError extends Error {
+    statusCode?: number | undefined;
+    response?: any | undefined;
+    constructor(message: string, statusCode?: number | undefined, response?: any | undefined);
+}
+declare class AuthenticationError extends QuartixSmsError {
+    constructor(message?: string);
+}
+declare class ValidationError extends QuartixSmsError {
+    constructor(message: string);
+}
+
+export { AuthenticationError, type GatewayStats, QuartixSms, QuartixSmsError, type QuartixSmsOptions, type SendSmsOptions, type SmsResponse, ValidationError };

package/dist/index.d.ts

@@ -0,0 +1,81 @@
+interface QuartixSmsOptions {
+    /**
+     * Your Quartix API Key.
+     * Can be an Account-level API Key or a Gateway-specific API Key.
+     */
+    apiKey: string;
+    /**
+     * The base URL of the Quartix SMS Gateway backend.
+     * @default "https://api.quartix.in"
+     */
+    baseUrl?: string;
+    /**
+     * Optional timeout for requests in milliseconds.
+     * @default 30000
+     */
+    timeout?: number;
+}
+interface SendSmsOptions {
+    /**
+     * The recipient phone number in E.164 format (e.g., +919876543210).
+     */
+    to: string;
+    /**
+     * The message content.
+     */
+    message: string;
+    /**
+     * Optional SIM index to use (0 or 1).
+     * @default 0
+     */
+    simIndex?: number;
+    /**
+     * Optional custom ID to track this message in your own system.
+     */
+    externalId?: string;
+}
+interface SmsResponse {
+    success: boolean;
+    messageId?: string;
+    status: 'PENDING' | 'SENT' | 'DELIVERED' | 'FAILED';
+    error?: string;
+}
+interface GatewayStats {
+    totalSent: number;
+    totalPending: number;
+    totalFailed: number;
+    isActive: boolean;
+    lastSeen?: string;
+}
+
+declare class QuartixSms {
+    private options;
+    constructor(options: QuartixSmsOptions);
+    private request;
+    /**
+     * Sends a single SMS message.
+     */
+    send(options: SendSmsOptions): Promise<SmsResponse>;
+    /**
+     * Retrieves the status of a specific message.
+     */
+    getMessageStatus(messageId: string): Promise<SmsResponse>;
+    /**
+     * Retrieves overall statistics for the account/gateway.
+     */
+    getStats(): Promise<GatewayStats>;
+}
+
+declare class QuartixSmsError extends Error {
+    statusCode?: number | undefined;
+    response?: any | undefined;
+    constructor(message: string, statusCode?: number | undefined, response?: any | undefined);
+}
+declare class AuthenticationError extends QuartixSmsError {
+    constructor(message?: string);
+}
+declare class ValidationError extends QuartixSmsError {
+    constructor(message: string);
+}
+
+export { AuthenticationError, type GatewayStats, QuartixSms, QuartixSmsError, type QuartixSmsOptions, type SendSmsOptions, type SmsResponse, ValidationError };

package/dist/index.js

@@ -0,0 +1,117 @@
+// src/errors.ts
+var QuartixSmsError = class extends Error {
+  constructor(message, statusCode, response) {
+    super(message);
+    this.statusCode = statusCode;
+    this.response = response;
+    this.name = "QuartixSmsError";
+  }
+  statusCode;
+  response;
+};
+var AuthenticationError = class extends QuartixSmsError {
+  constructor(message = "Invalid API Key") {
+    super(message, 401);
+    this.name = "AuthenticationError";
+  }
+};
+var ValidationError = class extends QuartixSmsError {
+  constructor(message) {
+    super(message, 400);
+    this.name = "ValidationError";
+  }
+};
+
+// src/client.ts
+var QuartixSms = class {
+  options;
+  constructor(options) {
+    if (!options.apiKey) {
+      throw new ValidationError("API Key is required");
+    }
+    this.options = {
+      apiKey: options.apiKey,
+      baseUrl: options.baseUrl || "https://api.quartix.in",
+      timeout: options.timeout || 3e4
+    };
+  }
+  async request(path, init) {
+    const url = new URL(path, this.options.baseUrl.endsWith("/") ? this.options.baseUrl : `${this.options.baseUrl}/`);
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), this.options.timeout);
+    try {
+      const response = await fetch(url.toString(), {
+        ...init,
+        headers: {
+          "Content-Type": "application/json",
+          "x-gateway-api-key": this.options.apiKey,
+          "Authorization": `Bearer ${this.options.apiKey}`,
+          "User-Agent": "QuartixSmsSDK/1.0.0 (Node.js)",
+          ...init?.headers
+        },
+        signal: controller.signal
+      });
+      const data = await response.json().catch(() => ({}));
+      if (!response.ok) {
+        if (response.status === 401) throw new AuthenticationError(data.message);
+        if (response.status === 400) throw new ValidationError(data.message);
+        throw new QuartixSmsError(data.message || "API Request Failed", response.status, data);
+      }
+      return data;
+    } catch (error) {
+      if (error.name === "AbortError") {
+        throw new QuartixSmsError("Request Timeout", 408);
+      }
+      if (error instanceof QuartixSmsError) throw error;
+      throw new QuartixSmsError(error.message || "Network Error");
+    } finally {
+      clearTimeout(timeoutId);
+    }
+  }
+  /**
+   * Sends a single SMS message.
+   */
+  async send(options) {
+    const { to, message, simIndex = 0, externalId } = options;
+    if (!to || !message) {
+      throw new ValidationError("Recipient and message body are required");
+    }
+    const data = await this.request("api/sms/send", {
+      method: "POST",
+      body: JSON.stringify({
+        recipient: to,
+        body: message,
+        sim_index: simIndex,
+        external_id: externalId
+      })
+    });
+    return {
+      success: true,
+      messageId: data.id,
+      status: data.status || "PENDING"
+    };
+  }
+  /**
+   * Retrieves the status of a specific message.
+   */
+  async getMessageStatus(messageId) {
+    const data = await this.request(`api/sms/messages/${messageId}`);
+    return {
+      success: true,
+      messageId: data.id,
+      status: data.status
+    };
+  }
+  /**
+   * Retrieves overall statistics for the account/gateway.
+   */
+  async getStats() {
+    return this.request("api/sms/stats");
+  }
+};
+export {
+  AuthenticationError,
+  QuartixSms,
+  QuartixSmsError,
+  ValidationError
+};

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@quartix/sms",
+  "version": "1.1.0",
+  "description": "Quartix SMS SDK for Node.js and Browser",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsup src/index.ts --format cjs,esm --dts --clean",
+    "dev": "tsup src/index.ts --format cjs,esm --watch --dts",
+    "lint": "eslint src/**/*.ts",
+    "test": "vitest run"
+  },
+  "keywords": [
+    "sms",
+    "gateway",
+    "quartix",
+    "sdk",
+    "messaging"
+  ],
+  "author": "Quartix Engineering",
+  "license": "MIT",
+  "devDependencies": {
+    "tsup": "^8.0.2",
+    "typescript": "^5.4.5",
+    "vitest": "^1.6.0",
+    "@types/node": "^20.12.7"
+  },
+  "dependencies": {}
+}