NikSMS JavaScript SDK

این پکیج برای اتصال آسان به وب‌سرویس پیامک Kendez.NikSms (نسخه REST و gRPC) در JavaScript/TypeScript طراحی شده است.

This package provides an easy-to-use JavaScript/TypeScript SDK for connecting to the Kendez.NikSms SMS web service (REST & gRPC).

نصب / Installation

npm install niksms-sdk

ویژگی‌ها / Features

• اتصال به REST API و gRPC
• قابل استفاده در پروژه‌های Node.js و مرورگر
• استفاده از آدرس‌های ثابت و قابل اعتماد
• پشتیبانی از تمام متدهای ارسال پیامک (تکی، گروهی، PTP، OTP)
• دریافت وضعیت پیامک‌ها و اطلاعات پنل
• TypeScript support
• Error handling
• Retry mechanism
• Input validation

استفاده سریع / Quick Usage

REST Example

const { NiksmsRestClient } = require('niksms-sdk');

const client = new NiksmsRestClient({
  apiKey: 'YOUR_API_KEY'
});

// ارسال پیامک تکی
const result = await client.sendSingle({
  senderNumber: '5000...',
  phone: '0912...',
  message: 'کد تایید شما: 1234'
});
console.log(result);

// دریافت اعتبار
const credit = await client.getCredit();
console.log(credit);

gRPC Example

const { NiksmsGrpcClient } = require('niksms-sdk');

const client = new NiksmsGrpcClient({
  apiKey: 'YOUR_API_KEY'
});

// ارسال پیامک تکی
const result = await client.sendSingle({
  senderNumber: '5000...',
  phone: '0912...',
  message: 'کد تایید شما: 1234'
});
console.log(result);

// دریافت اعتبار
const credit = await client.getCredit();
console.log(credit);

// بستن اتصال gRPC
client.close();

TypeScript Example

import { NiksmsRestClient, SendSingleRequest } from 'niksms-sdk';

const client = new NiksmsRestClient({
  apiKey: 'YOUR_API_KEY',
  timeout: 30000,
  retries: 3
});

const request: SendSingleRequest = {
  SenderNumber: '50004001',
  Phone: '09123456789',
  Message: 'سلام! این یک پیام تست است.',
  MessageId: 'unique_id_123',
  SendType: 1
};

const result = await client.sendSingle(request);
console.log(result);

مستندات کامل / Complete Documentation

متدهای ارسال پیامک / SMS Sending Methods

1. ارسال پیامک تکی / Send Single SMS

REST:

const result = await client.sendSingle({
  SenderNumber: '50004001',           // شماره فرستنده
  Phone: '09123456789',                // شماره گیرنده
  Message: 'سلام! این یک پیام تست است.',  // متن پیام
  MessageId: 'unique_id_123',         // شناسه یکتا (اختیاری)
  SendDate: '2024-01-01T10:30:00',    // تاریخ ارسال (اختیاری)
  SendType: 1                         // نوع ارسال (اختیاری)
});
console.log(result);

gRPC:

const result = await client.sendSingle({
  SenderNumber: '50004001',
  Phone: '09123456789', 
  Message: 'سلام! این یک پیام تست است.',
  MessageId: 'unique_id_123',
  SendDate: '2024-01-01T10:30:00',
  SendType: 1
}, 1); // apiType parameter
console.log(result);

2. ارسال پیامک گروهی / Send Group SMS

REST:

const recipients = [
  { Phone: '09123456789', MessageId: 'msg_001' },
  { Phone: '09123456790', MessageId: 'msg_002' },
  { Phone: '09123456791', MessageId: 'msg_003' }
];

const result = await client.sendGroup({
  SenderNumber: '50004001',
  Message: 'پیام گروهی برای همه کاربران',
  Recipients: recipients,
  SendDate: '2024-01-01T10:30:00',
  SendType: 1
});
console.log(result);

gRPC:

const recipients = [
  { Phone: '09123456789', MessageId: 'msg_001' },
  { Phone: '09123456790', MessageId: 'msg_002' },
  { Phone: '09123456791', MessageId: 'msg_003' }
];

const result = await client.sendGroup({
  SenderNumber: '50004001',
  Message: 'پیام گروهی برای همه کاربران',
  Recipients: recipients,
  SendDate: '2024-01-01T10:30:00',
  SendType: 1
}, 1);
console.log(result);

3. ارسال PTP (هر نفر پیام متفاوت) / Send PTP SMS

REST:

const recipients = [
  { Phone: '09123456789', Message: 'سلام علی', MessageId: 'ptp_001' },
  { Phone: '09123456790', Message: 'سلام رضا', MessageId: 'ptp_002' },
  { Phone: '09123456791', Message: 'سلام مریم', MessageId: 'ptp_003' }
];

const result = await client.sendPtp({
  SenderNumber: '50004001',
  Recipients: recipients,
  SendDate: '2024-01-01T10:30:00',
  SendType: 1
});
console.log(result);

gRPC:

const recipients = [
  { Phone: '09123456789', Message: 'سلام علی', MessageId: 'ptp_001' },
  { Phone: '09123456790', Message: 'سلام رضا', MessageId: 'ptp_002' },
  { Phone: '09123456791', Message: 'سلام مریم', MessageId: 'ptp_003' }
];

const result = await client.sendPtp({
  SenderNumber: '50004001',
  Recipients: recipients,
  SendDate: '2024-01-01T10:30:00',
  SendType: 1
}, 1);
console.log(result);

4. ارسال پیامک OTP / Send OTP SMS

REST:

const result = await client.sendOtp({
  SenderNumber: '50004001',
  Phone: '09123456789',
  Message: 'کد تایید شما: 1234',
  MessageId: 'otp_001',
  SendDate: '2024-01-01T10:30:00',
  SendType: 1
});
console.log(result);

gRPC:

const result = await client.sendOtp({
  SenderNumber: '50004001',
  Phone: '09123456789',
  Message: 'کد تایید شما: 1234',
  MessageId: 'otp_001',
  SendDate: '2024-01-01T10:30:00',
  SendType: 1
}, 1);
console.log(result);

متدهای دریافت اطلاعات / Information Methods

1. دریافت اعتبار / Get Credit

REST:

const creditInfo = await client.getCredit();
console.log(`اعتبار باقی‌مانده: ${creditInfo.Data.Credit}`);

gRPC:

const creditInfo = await client.getCredit(1);
console.log(`اعتبار باقی‌مانده: ${creditInfo.Data.Balance}`);

2. دریافت تاریخ انقضای پنل / Get Panel Expire Date

REST:

const expireDate = await client.getPanelExpireDate();
console.log(`تاریخ انقضای پنل: ${expireDate.Data.ExpireDate}`);

gRPC:

const expireDate = await client.getPanelExpireDate(1);
console.log(`تاریخ انقضای پنل: ${expireDate.Data.ExpiresAt}`);

3. دریافت وضعیت پیامک‌ها / Get SMS Status

REST:

const messageIds = ['msg_001', 'msg_002', 'msg_003'];
const status = await client.getSmsStatus({ MessageIds: messageIds });
console.log(`وضعیت پیامک‌ها: ${JSON.stringify(status.Data)}`);

gRPC:

const messageIds = ['msg_001', 'msg_002', 'msg_003'];
const status = await client.getSmsStatus({ MessageIds: messageIds }, 1);
console.log(`وضعیت پیامک‌ها: ${JSON.stringify(status.Data)}`);

مثال کامل / Complete Example

const { NiksmsRestClient, NiksmsGrpcClient } = require('niksms-sdk');

// تنظیمات
const API_KEY = 'YOUR_API_KEY';
const SENDER_NUMBER = '50004001';

async function completeExample() {
  // استفاده از REST API
  console.log('=== REST API Example ===');
  const restClient = new NiksmsRestClient({
    apiKey: API_KEY,
    timeout: 30000,
    retries: 3
  });

  try {
    // ارسال پیامک تکی
    const singleResult = await restClient.sendSingle({
      SenderNumber: SENDER_NUMBER,
      Phone: '09123456789',
      Message: 'سلام! این یک پیام تست از REST API است.'
    });
    console.log('Single SMS Result:', singleResult);

    // ارسال پیامک گروهی
    const groupRecipients = [
      { Phone: '09123456789', MessageId: 'group_001' },
      { Phone: '09123456790', MessageId: 'group_002' }
    ];
    const groupResult = await restClient.sendGroup({
      SenderNumber: SENDER_NUMBER,
      Message: 'پیام گروهی از REST API',
      Recipients: groupRecipients
    });
    console.log('Group SMS Result:', groupResult);

    // دریافت اعتبار
    const credit = await restClient.getCredit();
    console.log('Credit:', credit);

    // دریافت وضعیت پیامک‌ها
    const status = await restClient.getSmsStatus({
      MessageIds: ['group_001', 'group_002']
    });
    console.log('Status:', status);

  } catch (error) {
    console.error('REST API Error:', error);
  }

  // استفاده از gRPC API
  console.log('\n=== gRPC API Example ===');
  let grpcClient;
  
  try {
    grpcClient = new NiksmsGrpcClient({
      apiKey: API_KEY,
      endpoint: 'grpc.niksms.com:443',
      timeout: 30000,
      retries: 3
    });
    
    // ارسال پیامک OTP
    const otpResult = await grpcClient.sendOtp({
      SenderNumber: SENDER_NUMBER,
      Phone: '09123456789',
      Message: 'کد تایید شما: 1234',
      MessageId: 'otp_001'
    });
    console.log('OTP SMS Result:', otpResult);
    
    // دریافت اطلاعات پنل
    const panelInfo = await grpcClient.getPanelExpireDate();
    console.log('Panel Expire Date:', panelInfo);
    
  } catch (error) {
    console.error('gRPC Error:', error);
  } finally {
    if (grpcClient) {
      grpcClient.close();
    }
  }
}

completeExample();

مدیریت خطا / Error Handling

const { NiksmsRestClient, NiksmsError } = require('niksms-sdk');

const client = new NiksmsRestClient({
  apiKey: 'YOUR_API_KEY'
});

try {
  const result = await client.sendSingle({
    SenderNumber: '50004001',
    Phone: '09123456789',
    Message: 'پیام تست'
  });
  console.log('Success:', result);
  
} catch (error) {
  if (error instanceof NiksmsError) {
    console.error('Niksms Error:', error.message);
    console.error('Error Code:', error.code);
    console.error('Status Code:', error.statusCode);
  } else {
    console.error('General Error:', error.message);
  }
}

تنظیمات پیشرفته / Advanced Configuration

const client = new NiksmsRestClient({
  apiKey: 'YOUR_API_KEY',
  baseUrl: 'https://webservice.niksms.com', // اختیاری
  timeout: 60000,  // 60 ثانیه
  retries: 5       // 5 بار تلاش مجدد
});

// یا برای gRPC
const grpcClient = new NiksmsGrpcClient({
  apiKey: 'YOUR_API_KEY',
  endpoint: 'grpc.niksms.com:443', // اختیاری
  timeout: 60000,  // 60 ثانیه
  retries: 5       // 5 بار تلاش مجدد
});

انواع خطا / Error Types

const { ERROR_CODES } = require('niksms-sdk');

// کدهای خطای رایج
console.log('Invalid API Key:', ERROR_CODES.INVALID_API_KEY);
console.log('Insufficient Credit:', ERROR_CODES.INSUFFICIENT_CREDIT);
console.log('Invalid Sender Number:', ERROR_CODES.INVALID_SENDER_NUMBER);
console.log('Invalid Phone Number:', ERROR_CODES.INVALID_PHONE_NUMBER);
console.log('Invalid Message:', ERROR_CODES.INVALID_MESSAGE);
console.log('Network Error:', ERROR_CODES.NETWORK_ERROR);
console.log('Timeout Error:', ERROR_CODES.TIMEOUT_ERROR);

انواع ارسال / Send Types

const { SEND_TYPES } = require('niksms-sdk');

// انواع ارسال
console.log('Normal SMS:', SEND_TYPES.NORMAL);     // 1
console.log('Flash SMS:', SEND_TYPES.FLASH);       // 2
console.log('Unicode SMS:', SEND_TYPES.UNICODE);   // 3

وضعیت پیامک‌ها / SMS Status

const { SMS_STATUS } = require('niksms-sdk');

// وضعیت‌های پیامک
console.log('Pending:', SMS_STATUS.PENDING);
console.log('Sent:', SMS_STATUS.SENT);
console.log('Delivered:', SMS_STATUS.DELIVERED);
console.log('Failed:', SMS_STATUS.FAILED);
console.log('Expired:', SMS_STATUS.EXPIRED);

نکات مهم / Important Notes

1. API Key: کلید API خود را از پنل کاربری دریافت کنید
2. شماره فرستنده: شماره فرستنده باید از شماره‌های مجاز پنل شما باشد
3. نوع ارسال: مقادیر مختلف SendType برای انواع مختلف پیامک
4. تاریخ ارسال: فرمت تاریخ باید YYYY-MM-DDTHH:MM:SS باشد
5. شناسه پیام: برای پیگیری وضعیت پیامک‌ها، شناسه یکتا تعیین کنید
6. gRPC Connection: همیشه اتصال gRPC را با client.close() ببندید
7. Error Handling: همیشه خطاها را مدیریت کنید
8. Retry Mechanism: SDK به صورت خودکار در صورت خطا تلاش مجدد می‌کند

پشتیبانی / Support

برای پشتیبانی و راهنمایی بیشتر با تیم فنی تماس بگیرید. 021-74552000

نسخه / Version: 1.2.0
آخرین به‌روزرسانی / Last Update: 2024
Node.js Version: >= 14.0.0