إرسال SMS باستخدام TypeScript: مكتبة API sms-client-ts

مكتبة sms-client-ts: إرسال SMS عبر TypeScript

في تطوير الويب الحديث، لا يزال إرسال رسائل SMS ميزة مطلوبة - بدءًا من المصادقة ثنائية العوامل وصولاً إلى الإشعارات بحالة الطلب. للنظام البيئي TypeScript، توجد مكتبة ملائمة sms-client-ts توفر واجهة آمنة من حيث الأنواع للعمل مع مزودي SMS المشهورين. في هذه المقالة، سنشرح واجهة API الخاصة بها، والإعداد، وسيناريوهات الاستخدام النموذجية.

التثبيت والاستيراد

يتم توزيع المكتبة عبر npm. قم بتثبيتها في مشروعك باستخدام الأمر التالي:

npm install sms-client-ts

بعد التثبيت، قم باستيراد الفئة الرئيسية SmsClient:

import { SmsClient } from 'sms-client-ts';

تكوين العميل

للعمل مع أي مزود خدمة، يجب تمرير كائن تكوين. تدعم المكتبة عدة خدمات: Twilio، Vonage (Nexmo)، SMSC.ru وغيرها. مثال على الإعداد لـ Twilio:

const client = new SmsClient({\n  provider: 'twilio',\n  credentials: {\n    accountSid: process.env.TWILIO_ACCOUNT_SID,\n    authToken: process.env.TWILIO_AUTH_TOKEN,\n    from: '+1234567890' // رقم المرسل\n  }\n});

بالنسبة لمزود الخدمة الروسي SMSC.ru، سيكون التكوين مختلفًا:

const clientSMSC = new SmsClient({\n  provider: 'smscru',\n  credentials: {\n    login: 'your_login',\n    password: 'your_password',\n    sender: 'MyBrand' // اسم المرسل\n  }\n});

طرق API الرئيسية

توفر المكتبة ثلاث طرق رئيسية للعمل مع SMS. دعنا نستعرض كلًا منها.

1. إرسال رسالة واحدة

تستقبل طريقة sendSingle رقم المستلم ونص الرسالة. تُرجع Promise مع كائن النتيجة.

async function sendWelcomeSms(phone: string, name: string) {\n  try {\n    const result = await client.sendSingle({\n      to: phone,\n      text: `مرحبًا، ${name}! أهلاً بك في خدمتنا.`\n    });\n    console.log('تم إرسال SMS:', result.messageId);\n  } catch (error) {\n    console.error('خطأ في الإرسال:', error);\n  }\n}\n\nsendWelcomeSms('+79161234567', 'إيفان');

2. الإرسال الجماعي

لإرسال نفس الرسالة إلى عدة مستلمين، استخدم طريقة sendBulk. تستقبل مصفوفة من الأرقام.

async function sendPromoSms(phones: string[]) {\n  const result = await client.sendBulk({\n    to: phones,\n    text: 'عرض خاص اليوم فقط! خصم 20% على جميع المنتجات.'\n  });\n  \n  console.log(`تم الإرسال بنجاح: ${result.successCount}`);\n  console.log(`الأخطاء: ${result.failCount}`);\n  if (result.errors.length > 0) {\n    result.errors.forEach(err => {\n      console.error(`خطأ لـ ${err.phone}: ${err.message}`);\n    });\n  }\n}\n\nsendPromoSms(['+79161234567', '+79167654321']);

3. التحقق من حالة التسليم

بعد الإرسال، يمكنك التحقق من حالة الرسالة باستخدام معرفها. تُرجع طريقة getStatus الحالة الحالية.

async function checkDelivery(messageId: string) {\n  const status = await client.getStatus(messageId);\n  console.log(`حالة الرسالة ${messageId}: ${status.state}`);\n  // القيم المحتملة: 'pending', 'delivered', 'failed', 'unknown'\n  \n  if (status.state === 'failed') {\n    console.log('سبب الخطأ:', status.errorMessage);\n  }\n}\n\ncheckDelivery('SM123456789');

معالجة الأخطاء والتصنيف

توفر المكتبة أنواع أخطاء خاصة بها، وهو أمر مناسب لمطوري TypeScript. جميع الاستثناءات ترث من الفئة الأساسية SmsError.

import { SmsError, ValidationError, AuthError, ProviderError } from 'sms-client-ts';\n\nasync function safeSend(phone: string, text: string) {\n  try {\n    return await client.sendSingle({ to: phone, text });\n  } catc