farazsms 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 FarazSMS
+
+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,61 @@
+# farazsms
+
+Official lightweight client for the [FarazSMS](https://api.iranpayamak.com) web services — send pattern/OTP, simple & bulk SMS, pull reports, manage your phonebook, and reach **all 63 endpoints** through a low-level `request()`.
+
+Zero dependencies. Works on **Node.js 18+** (built-in `fetch`), ESM **and** CommonJS, with TypeScript types.
+
+## Install
+
+```bash
+npm install farazsms
+```
+
+## Quick start
+
+```js
+import FarazSMS from "farazsms";          // ESM
+// const FarazSMS = require("farazsms");   // CommonJS
+
+const sms = new FarazSMS("YOUR_API_KEY"); // key from the FarazSMS panel → Web Service / API Key
+
+console.log(await sms.balance());                                     // verify the key — free
+await sms.sendPattern("SJ3FgPrE0C", "09120000000", { code: "1234" });  // OTP (instant, never queued)
+await sms.sendSimple("Hello!", ["09120000000", "09130000000"]);       // bulk
+console.log(await sms.inbox(1, 20));                                  // inbound replies
+```
+
+> Recipients use the local format `09120000000` (no `+98`). The default sender line is `90008361`.
+
+## Error handling
+
+The client throws a `FarazError` whenever the API returns `{ status: "error" }`, so you don't have to check manually:
+
+```js
+import { FarazError } from "farazsms";
+try {
+  await sms.sendPattern("BAD_CODE", "09120000000", { code: "1" });
+} catch (e) {
+  if (e instanceof FarazError) console.error(e.status, e.body);
+}
+```
+
+## Bundled helpers
+
+| Area | Methods |
+|------|---------|
+| Account | `balance()` · `profile()` · `lines()` |
+| Send | `sendPattern()` · `sendSimple()` · `sendVariable()` |
+| Patterns | `createPattern()` · `patterns()` |
+| Reports | `inbox()` · `sendRequests()` · `sendRequestItems()` |
+| Phonebook | `phonebooks()` · `addContact()` |
+| Reference | `provinces()` · `numberBanks()` |
+
+**Anything else** (tickets, orders, voice, LBS, …) is reachable via the low-level call:
+
+```js
+await sms.request("POST", "/ws/v1/ticket", { department: 1, subject: "Hi" });
+```
+
+## License
+
+MIT

package/index.cjs

@@ -0,0 +1,73 @@
+// FarazSMS — official lightweight client (CommonJS). Node 18+ (built-in fetch).
+"use strict";
+const BASE = "https://api.iranpayamak.com";
+
+class FarazError extends Error {
+  constructor(status, body) {
+    super("[" + status + "] " + (typeof body === "string" ? body : JSON.stringify(body)));
+    this.name = "FarazError";
+    this.status = status;
+    this.body = body;
+  }
+}
+
+class FarazSMS {
+  constructor(apiKey, baseUrl = BASE) {
+    if (!apiKey) throw new Error("FarazSMS: apiKey is required");
+    this.base = String(baseUrl).replace(/\/$/, "");
+    this.key = apiKey;
+  }
+
+  // low-level — reaches every one of the 63 endpoints
+  async request(method, path, body = null, query = null) {
+    const url = new URL(this.base + path);
+    if (query) for (const k in query) if (query[k] != null) url.searchParams.set(k, query[k]);
+    const res = await fetch(url, {
+      method,
+      headers: {
+        "Api-Key": this.key,
+        "Accept": "application/json",
+        ...(body ? { "Content-Type": "application/json" } : {}),
+      },
+      body: body ? JSON.stringify(body) : undefined,
+    });
+    const data = await res.json().catch(() => ({}));
+    if (data && data.status === "error") throw new FarazError(res.status, data.message != null ? data.message : data);
+    return data;
+  }
+
+  balance() { return this.request("GET", "/ws/v1/account/balance"); }
+  profile() { return this.request("GET", "/ws/v1/account/profile"); }
+  lines() { return this.request("GET", "/ws/v1/lines/accessible"); }
+
+  sendPattern(code, recipient, attributes, line = "90008361") {
+    return this.request("POST", "/ws/v1/sms/pattern",
+      { code, recipient, attributes, line_number: line, number_format: "english" });
+  }
+  sendSimple(text, recipients, line = "90008361") {
+    return this.request("POST", "/ws/v1/sms/simple",
+      { text, recipients, line_number: line, number_format: "english" });
+  }
+  sendVariable(text, recipients, line = "90008361") {
+    return this.request("POST", "/ws/v1/sms/keywords",
+      { text, recipients, line_number: line, number_format: "english" });
+  }
+
+  createPattern(payload) { return this.request("POST", "/ws/v1/patterns", payload); }
+  patterns(query = {}) { return this.request("GET", "/ws/v1/patterns", null, query); }
+
+  inbox(page = 1, limit = 20) { return this.request("GET", "/ws/v1/inbox", null, { page, limit }); }
+  sendRequests(query = {}) { return this.request("GET", "/ws/v1/send_request", null, query); }
+  sendRequestItems(id, query = {}) { return this.request("GET", "/ws/v1/send_request/" + id + "/items", null, query); }
+
+  phonebooks() { return this.request("GET", "/ws/v1/phone_book"); }
+  addContact(payload) { return this.request("POST", "/ws/v1/phone_book_data", payload); }
+
+  provinces(query = {}) { return this.request("GET", "/provinces", null, query); }
+  numberBanks(query = {}) { return this.request("GET", "/ws/v1/number_bank", null, query); }
+}
+
+module.exports = FarazSMS;
+module.exports.FarazSMS = FarazSMS;
+module.exports.FarazError = FarazError;
+module.exports.default = FarazSMS;

package/index.d.ts

@@ -0,0 +1,41 @@
+// Type definitions for the FarazSMS client.
+export type Json = any;
+export type Query = Record<string, string | number | boolean | null | undefined>;
+
+export class FarazError extends Error {
+  status: number;
+  body: Json;
+  constructor(status: number, body: Json);
+}
+
+export class FarazSMS {
+  base: string;
+  key: string;
+  constructor(apiKey: string, baseUrl?: string);
+
+  /** Low-level call — reaches every one of the 63 endpoints. Throws FarazError on `status: "error"`. */
+  request(method: string, path: string, body?: Json, query?: Query | null): Promise<Json>;
+
+  balance(): Promise<Json>;
+  profile(): Promise<Json>;
+  lines(): Promise<Json>;
+
+  sendPattern(code: string, recipient: string, attributes: Record<string, string | number>, line?: string): Promise<Json>;
+  sendSimple(text: string, recipients: string[], line?: string): Promise<Json>;
+  sendVariable(text: string, recipients: Json[], line?: string): Promise<Json>;
+
+  createPattern(payload: Json): Promise<Json>;
+  patterns(query?: Query): Promise<Json>;
+
+  inbox(page?: number, limit?: number): Promise<Json>;
+  sendRequests(query?: Query): Promise<Json>;
+  sendRequestItems(id: string | number, query?: Query): Promise<Json>;
+
+  phonebooks(): Promise<Json>;
+  addContact(payload: Json): Promise<Json>;
+
+  provinces(query?: Query): Promise<Json>;
+  numberBanks(query?: Query): Promise<Json>;
+}
+
+export default FarazSMS;

package/index.mjs

@@ -0,0 +1,75 @@
+// FarazSMS — official lightweight client (ESM). Node 18+ (built-in fetch).
+const BASE = "https://api.iranpayamak.com";
+
+export class FarazError extends Error {
+  constructor(status, body) {
+    super("[" + status + "] " + (typeof body === "string" ? body : JSON.stringify(body)));
+    this.name = "FarazError";
+    this.status = status;
+    this.body = body;
+  }
+}
+
+export class FarazSMS {
+  constructor(apiKey, baseUrl = BASE) {
+    if (!apiKey) throw new Error("FarazSMS: apiKey is required");
+    this.base = String(baseUrl).replace(/\/$/, "");
+    this.key = apiKey;
+  }
+
+  // low-level — reaches every one of the 63 endpoints
+  async request(method, path, body = null, query = null) {
+    const url = new URL(this.base + path);
+    if (query) for (const k in query) if (query[k] != null) url.searchParams.set(k, query[k]);
+    const res = await fetch(url, {
+      method,
+      headers: {
+        "Api-Key": this.key,
+        "Accept": "application/json",
+        ...(body ? { "Content-Type": "application/json" } : {}),
+      },
+      body: body ? JSON.stringify(body) : undefined,
+    });
+    const data = await res.json().catch(() => ({}));
+    if (data && data.status === "error") throw new FarazError(res.status, data.message ?? data);
+    return data;
+  }
+
+  // account
+  balance() { return this.request("GET", "/ws/v1/account/balance"); }
+  profile() { return this.request("GET", "/ws/v1/account/profile"); }
+  lines() { return this.request("GET", "/ws/v1/lines/accessible"); }
+
+  // send
+  sendPattern(code, recipient, attributes, line = "90008361") {
+    return this.request("POST", "/ws/v1/sms/pattern",
+      { code, recipient, attributes, line_number: line, number_format: "english" });
+  }
+  sendSimple(text, recipients, line = "90008361") {
+    return this.request("POST", "/ws/v1/sms/simple",
+      { text, recipients, line_number: line, number_format: "english" });
+  }
+  sendVariable(text, recipients, line = "90008361") {
+    return this.request("POST", "/ws/v1/sms/keywords",
+      { text, recipients, line_number: line, number_format: "english" });
+  }
+
+  // patterns
+  createPattern(payload) { return this.request("POST", "/ws/v1/patterns", payload); }
+  patterns(query = {}) { return this.request("GET", "/ws/v1/patterns", null, query); }
+
+  // reports
+  inbox(page = 1, limit = 20) { return this.request("GET", "/ws/v1/inbox", null, { page, limit }); }
+  sendRequests(query = {}) { return this.request("GET", "/ws/v1/send_request", null, query); }
+  sendRequestItems(id, query = {}) { return this.request("GET", "/ws/v1/send_request/" + id + "/items", null, query); }
+
+  // phonebook
+  phonebooks() { return this.request("GET", "/ws/v1/phone_book"); }
+  addContact(payload) { return this.request("POST", "/ws/v1/phone_book_data", payload); }
+
+  // reference
+  provinces(query = {}) { return this.request("GET", "/provinces", null, query); }
+  numberBanks(query = {}) { return this.request("GET", "/ws/v1/number_bank", null, query); }
+}
+
+export default FarazSMS;

package/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "farazsms",
+  "version": "1.0.0",
+  "description": "Official lightweight client for the FarazSMS web services — send pattern/OTP, simple & bulk SMS, reports, phonebook, and all 63 endpoints via a low-level request().",
+  "keywords": ["farazsms", "sms", "otp", "pattern", "iran", "iranpayamak", "پیامک", "اس ام اس"],
+  "license": "MIT",
+  "author": "FarazSMS",
+  "homepage": "https://gitlab.faraz.club/common-service-centres/api-docs",
+  "repository": {
+    "type": "git",
+    "url": "git+https://gitlab.faraz.club/common-service-centres/api-docs.git"
+  },
+  "type": "module",
+  "main": "./index.cjs",
+  "module": "./index.mjs",
+  "types": "./index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "import": "./index.mjs",
+      "require": "./index.cjs"
+    }
+  },
+  "files": ["index.mjs", "index.cjs", "index.d.ts", "README.md"],
+  "engines": { "node": ">=18" }
+}