sms-typescript

SMS.ir TypeScript SDK

Official TypeScript/JavaScript SDK for SMS.ir API - Send SMS, verification codes, and bulk messages with full TypeScript support.

Features

✅ Full TypeScript Support - Complete type definitions for all APIs
✅ Multiple Module Formats - Works with CommonJS, ES Modules, and TypeScript
✅ Modern & Legacy Support - Class-based (v1.x compatible) and functional APIs
✅ Tree Shakeable - Import only what you need
✅ Zero Dependencies - Uses native fetch API (Node.js 18+)
✅ Comprehensive Documentation - JSDoc comments for IntelliSense

Installation

npm install sms-typescript

Quick Start

Class-Based API (Recommended for OOP)

import { Smsir } from "sms-typescript";

const sms = new Smsir("your-api-key", 30007732000000);

// Send bulk SMS
const result = await sms.sendBulk("Hello!", ["09123456789"]);
console.log("Pack ID:", result.data.packId);

// Send verification code
await sms.sendVerifyCode("09123456789", 12345, [
  { name: "Code", value: "123456" },
]);

// Get account credit
const credit = await sms.getCredit();
console.log("Credit:", credit.data);

Functional API (Recommended for Functional Programming)

import { smsBuilder } from "sms-typescript";

const sms = smsBuilder({
  apiKey: "your-api-key",
  lineNumber: 30007732000000,
});

// Same methods as class-based API
const result = await sms.sendBulk("Hello!", ["09123456789"]);

Note: The functional API does not include deprecated v1.x methods.

CommonJS (Node.js)

// Class-based (backward compatible with v1.x)
const { Smsir } = require("sms-typescript");
const sms = new Smsir("your-api-key", 30007732000000);

// Functional
const smsBuilder = require("sms-typescript").default;
const sms = smsBuilder({ apiKey: "your-api-key", lineNumber: 30007732000000 });

API Reference

Send Methods

sendBulk(messageText, mobiles, sendDateTime?, customLineNumber?)

Send the same message to multiple recipients.

const result = await sms.sendBulk(
  "Hello World!",
  ["09123456789", "09987654321"],
  Date.now() + 3600000, // Optional: schedule for 1 hour later
  30007732000000 // Optional: custom line number
);

sendLikeToLike(messageTexts, mobiles, sendDateTime?, customLineNumber?)

Send different messages to different recipients (1-to-1 pairing).

await sms.sendLikeToLike(
  ["Hello Ali", "Hello Sara"],
  ["09121111111", "09122222222"]
);

sendVerifyCode(mobile, templateId, parameters)

Send verification code using a predefined template.

await sms.sendVerifyCode("09123456789", 12345, [
  { name: "Code", value: "123456" },
  { name: "Name", value: "John" },
]);

deleteScheduled(packId)

Delete a scheduled SMS pack.

await sms.deleteScheduled("pack-id-here");

sendByURL(username, mobile, text, customLine?)

Legacy URL-based sending method (for backward compatibility).

await sms.sendByURL("username", "09123456789", "Hello World!");

Report Methods

reportMessage(messageId)

Get delivery status of a specific message.

const report = await sms.reportMessage("876240022");
console.log("Delivery State:", report.data.deliveryState);

reportPackById(packId)

Get all messages in a specific pack.

const pack = await sms.reportPackById("pack-id");

reportDailyPack(pageNumber, pageSize)

Get daily pack statistics with pagination.

const dailyPack = await sms.reportDailyPack(1, 10);

reportTodayLive(pageNumber, pageSize)

Get today's sent messages with pagination.

const today = await sms.reportTodayLive(1, 10);

reportArchive(fromDate, toDate, pageNumber, pageSize)

Get archived sent messages within a date range.

const archived = await sms.reportArchive(
  Date.now() - 86400000, // Yesterday
  Date.now(),
  1,
  10
);

reportLatestReceive(count)

Get latest received messages.

const received = await sms.reportLatestReceive(100);

reportReceiveLive(pageNumber, pageSize, sortByNewest)

Get live received messages with pagination.

const live = await sms.reportReceiveLive(1, 10, true);

reportReceiveArchive(fromDate, toDate, pageNumber, pageSize)

Get archived received messages.

const archived = await sms.reportReceiveArchive(
  Date.now() - 86400000,
  Date.now(),
  1,
  10
);

Settings Methods

getCredit()

Get current account credit balance.

const credit = await sms.getCredit();
console.log("Credit:", credit.data);

getLineNumbers()

Get all available line numbers for your account.

const lines = await sms.getLineNumbers();
console.log("Lines:", lines.data);

Backward Compatibility (v1.x Deprecated Methods)

For users migrating from v1.x, all old method names are still supported via the class-based API:

Deprecated Methods (Class-based API Only)

These methods are deprecated but still functional for backward compatibility. Use the new camelCase methods instead.

// ⚠️ Deprecated - Use sendBulk() instead
await sms.SendBulk("message", ["09123456789"]);

// ⚠️ Deprecated - Use sendLikeToLike() instead
await sms.SendLikeToLike(["msg1", "msg2"], ["09121111111", "09122222222"]);

// ⚠️ Deprecated - Use sendVerifyCode() instead
await sms.SendVerifyCode("09123456789", 12345, [
  { name: "Code", value: "123456" },
]);

// ⚠️ Deprecated - Use reportMessage() instead
await sms.ReportMessage(876240022);

// ⚠️ Deprecated - Use reportPackById() instead
await sms.ReportPack("pack-id");

// ⚠️ Deprecated - Use reportTodayLive() instead
await sms.ReportToday(1, 10);

// ⚠️ Deprecated - Use reportArchive() instead
await sms.ReportArchived(fromDate, toDate, 1, 10);

// ⚠️ Deprecated - Use reportLatestReceive() instead
await sms.ReportLatestReceived(100);

// ⚠️ Deprecated - Use reportReceiveLive() instead
await sms.ReportTodayReceived(1, 10);

// ⚠️ Deprecated - Use reportReceiveArchive() instead
await sms.ReportArchivedReceived(fromDate, toDate, 1, 10);

Note: Deprecated methods are only available in the Smsir class, not in the functional smsBuilder API.

Usage Examples

For detailed examples including Angular, React, Vue.js, and various use cases, see USAGE_EXAMPLES.md.

TypeScript Support

Full TypeScript support with comprehensive type definitions:

import {
  Smsir,
  SendBulkResponse,
  ResponseModel,
  SmsConfig,
} from "sms-typescript";

const config: SmsConfig = {
  apiKey: "your-api-key",
  lineNumber: 30007732000000,
};

const sms = new Smsir(config.apiKey, config.lineNumber);

const result: ResponseModel<SendBulkResponse> = await sms.sendBulk("Hello!", [
  "09123456789",
]);

// TypeScript knows the structure:
console.log(result.data.packId); // string
console.log(result.data.messageIds); // number[]
console.log(result.data.cost); // number

Migration from v1.x

The SDK is fully backward compatible! Your existing code will continue to work:

// v1.x code - Still works!
const { Smsir } = require("sms-typescript");
const sms = new Smsir("api-key", lineNumber);

// Old PascalCase methods still work (but are deprecated)
sms.SendBulk("Hello", ["09123456789"]).then((result) => console.log(result));

// New camelCase methods (recommended)
sms.sendBulk("Hello", ["09123456789"]).then((result) => console.log(result));

Migration recommendations:

• ✅ Update to new camelCase method names (e.g., SendBulk → sendBulk)
• ✅ Add TypeScript for better IDE support
• ✅ Consider using the functional smsBuilder API for cleaner code
• ⚠️ Old PascalCase methods will be removed in v3.0.0

Requirements

• Node.js >= 18.0.0 (uses native fetch API)
• TypeScript >= 4.5 (if using TypeScript)

Module System Support

• CommonJS (require): ✅ Fully supported - works out of the box in Node.js
• ES Modules (import): ⚠️ Requires a bundler (Webpack, Vite, Rollup, esbuild, etc.)
  • Direct Node.js ESM usage is not currently supported due to missing .js extensions
  • Works perfectly with any bundler or build tool
  • If you need native Node.js ESM support, please open an issue

Recommendation: Use CommonJS (require) for Node.js projects, or use a bundler for ESM projects.

Framework Integration

Angular

import { Smsir } from "sms-typescript";

export class AppComponent implements OnInit {
  private smsService: Smsir;

  constructor() {
    this.smsService = new Smsir("your-api-key", 30007732000000);
  }

  async sendMessage() {
    const result = await this.smsService.sendBulk("Hello!", ["09123456789"]);
    console.log("Sent!", result.data.packId);
  }
}

React

import { Smsir } from "sms-typescript";

const sms = new Smsir("your-api-key", 30007732000000);

function MyComponent() {
  const handleSend = async () => {
    const result = await sms.sendBulk("Hello!", ["09123456789"]);
    console.log("Sent!", result.data);
  };

  return <button onClick={handleSend}>Send SMS</button>;
}

Vue.js

import { Smsir } from "sms-typescript";

export default {
  data() {
    return {
      sms: new Smsir("your-api-key", 30007732000000),
    };
  },
  methods: {
    async sendMessage() {
      const result = await this.sms.sendBulk("Hello!", ["09123456789"]);
      console.log("Sent!", result.data);
    },
  },
};

Error Handling

All methods return promises. Handle errors appropriately:

try {
  const result = await sms.sendBulk("Hello", ["09123456789"]);
  console.log("Success:", result.data);
} catch (error) {
  console.error("Error:", error.message);
  // Handle error (retry, show message to user, etc.)
}

Contributing

We welcome contributions from the community! Whether you want to report a bug, suggest a feature, or submit code improvements, your help is appreciated.

How to Contribute

• Report Issues: Found a bug or have a feature request? Open an issue on GitHub
• Submit Pull Requests: Have a fix or improvement? Create a pull request
• Improve Documentation: Help us improve docs by suggesting edits or additions
• Share Feedback: Let us know how we can make this SDK better

Guidelines

• Fork the repository and create your branch from main
• Write clear commit messages describing your changes
• Add tests for new functionality when applicable
• Update documentation if you're changing functionality
• Follow the existing code style (TypeScript, JSDoc comments, etc.)

We review all contributions and will provide feedback. Thank you for helping make this SDK better!

Credits

• IPE Company
• Hadi Zare Irani

License

The MIT License (MIT). Please see License File for more information.