تخطَّ إلى المحتوى

الإعداد

أنشئ عميلًا واحدًا لكل عملية وأعد استخدامه. لا يحتفظ العميل بأي حالة اتصال، لذا يمكن مشاركته بين الطلبات بأمان.

client.ts
import { SMSFabric } from '@smsfabric/sdk';
export const sms = new SMSFabric({
apiKey: process.env.SMSFABRIC_API_KEY,
baseUrl: 'https://api.smsfabric.com',
maxRetries: 2,
timeoutMs: 30_000,
});
الخيار النوع القيمة الافتراضية وظيفته
apiKey string SMSFABRIC_API_KEY، فقط إذا لم تمرر accessToken أيضًا مفتاح API بصيغة sf_live_… أو sf_test_…، ويرسل في ترويسة X-Api-Key.
accessToken string لا يوجد رمز وصول لمستخدم مسجل الدخول بدل مفتاح API، ويرسل في Authorization: Bearer …. إذا مررته لا يقرأ العميل SMSFABRIC_API_KEY.
baseUrl string SMSFABRIC_BASE_URL ثم https://api.smsfabric.com أصل الواجهة البرمجية. تحذف الشرطات المائلة في آخره.
maxRetries number 2 عدد المحاولات الإضافية بعد الأولى، للأعطال المذكورة في إعادة المحاولة. القيمة 0 تلغي إعادة المحاولة.
timeoutMs number 30000 مهلة كل محاولة بالمللي ثانية. المحاولة التي تتجاوزها تعامل كخطأ شبكة.
fetch (input: string, init: RequestInit) => Promise<Response> دالة fetch العامة دالة fetch مخصصة للاختبارات أو الوكيل أو المراقبة.

يرمي المنشئ Error('SMSFabric: pass apiKey (or set SMSFABRIC_API_KEY) or accessToken') إذا لم يجد أيًا من بيانات الاعتماد.

استخدم مفتاح API للخوادم والمهام المجدولة والسكربتات. نطاقاته تحدد ما يستطيع العميل فعله؛ راجع المصادقة.

استخدم رمز الوصول فقط لنقاط النهاية القليلة التي ترفض مفاتيح API، حتى لا يستطيع مفتاح مسرب توسيع صلاحياته:

  • مفاتيح API: apiKeys.*
  • إدارة الفريق: org.members.* وorg.invitations.*
  • تغيير اسم المؤسسة: org.update
  • حفظ إعدادات التحقق: verifications.settings.update

رمز الوصول هو الرمز قصير العمر (15 دقيقة) الذي تحصل عليه البوابة عند تسجيل دخول المستخدم. راجع رموز المستخدم.

المتغير استخدامه
SMSFABRIC_API_KEY قيمة apiKey إذا لم تمررها.
SMSFABRIC_BASE_URL قيمة baseUrl إذا لم تمررها. اضبطه على http://localhost:3000 عند العمل مع واجهة محلية.

القيمة الفارغة (SMSFABRIC_BASE_URL=) تعامل كأنها غير مضبوطة، وكذلك الخيارات apiKey وaccessToken وbaseUrl الفارغة.

أبق المفاتيح خارج الكود وخارج نظام التحكم بالإصدارات، وحمّلها من مدير الأسرار أو من البيئة.

إعادة المحاولة والانتظار

Section titled “إعادة المحاولة والانتظار”

يعيد العميل المحاولة عندما يكون تكرار الطلب آمنًا:

  • طلبات GET وPUT وDELETE،
  • وطلبات POST التي تحمل Idempotency-Key (وكل دوال الإنشاء ترسله).

ويعيدها عند خطأ في الشبكة أو تجاوز المهلة، وعند الحالات 408 و425 و429 و500 و502 و503 و504، وعند 409 فقط إذا كان الرمز idempotency_in_progress (طلب بالمفتاح نفسه ما زال قيد التنفيذ). أما بقية استجابات 4xx، ومنها التعارضات مثل 409 contact_exists، فترمى فورًا.

طلب DELETE المعاد ينجح إذا تلقى 404 بعد محاولة سابقة فشلت في الشبكة أو تجاوزت المهلة أو تلقت 5xx، لأن تلك المحاولة حذفت العنصر بالفعل. أما 404 في المحاولة الأولى فيرمى كالمعتاد.

مدة الانتظار قبل كل محاولة:

  1. قيمة ترويسة Retry-After (أو RateLimit-Reset) بالثواني إن وجدت، بحد أقصى 32 ثانية.
  2. وإلا فانتظار متضاعف مع عشوائية: نحو 250 مللي ثانية، ثم 500، ثم ثانية، ويتضاعف حتى 8 ثوان، وتختار كل مدة عشوائيًا بين نصف القيمة وكامل القيمة.

هذه الطلبات لا تعاد محاولتها أبدًا، لأن تكرارها قد يغير النتيجة:

الدالة السبب
verifications.check كل فحص يستهلك واحدة من المحاولات الخمس.
verifications.send عند 429 حدود 429 هنا لكل رقم ولكل دولة وتقاس بالدقائق. أخطاء الشبكة و5xx تعاد محاولتها.
campaigns.start وpause وresume وcancel وestimate تغيّر الحالة دون مفتاح منع تكرار.
apiKeys.rotate التدوير الثاني يستبدل السر الجديد.
webhooks.replay وwebhooks.test كل استدعاء يضيف تسليمًا جديدًا إلى الطابور.
كل دوال update (PATCH) ترسل مرة واحدة.

عندما تنفد المحاولات، يرمى آخر خطأ على شكل SMSFabricError.

كل دالة إنشاء تقبل وسيطًا ثانيًا اختياريًا هو { idempotencyKey }. إذا لم تمرره، يولّد العميل معرف UUID لهذا الاستدعاء ويعيد استخدامه في كل محاولة تلقائية، فلا تؤدي المهلة إلى إنشاء مكرر.

مرّر مفتاحك الخاص عندما قد يكرر كودك الاستدعاء، مثل مهمة قد تعمل مجددًا بعد انهيار. اشتق المفتاح من بياناتك:

idempotent-send.ts
import { SMSFabric } from '@smsfabric/sdk';
const sms = new SMSFabric({ apiKey: process.env.SMSFABRIC_API_KEY });
const orderId = '1042';
// Running this twice sends one SMS: the second call gets the stored response back.
await sms.messages.send(
{ to: '+201001234567', body: `Order ${orderId} has shipped.` },
{ idempotencyKey: `order-${orderId}-shipped` },
);

المفاتيح من 1 إلى 255 حرفًا من A–Z a–z 0–9 _ - : . وتحفظ 24 ساعة لكل مؤسسة. استخدام المفتاح نفسه مع محتوى مختلف يعيد 422 idempotency_key_reused. التفاصيل في منع التكرار.

تنطبق timeoutMs على كل محاولة، فأسوأ حالة لاستدعاء واحد هي نحو (maxRetries + 1) × timeoutMs إضافة إلى مدد الانتظار. في معالج طلبات يجب أن يرد بسرعة، خفّض القيمتين:

fast-client.ts
import { SMSFabric } from '@smsfabric/sdk';
// At most 2 attempts of 5 seconds each.
export const sms = new SMSFabric({ apiKey: process.env.SMSFABRIC_API_KEY, timeoutMs: 5_000, maxRetries: 1 });

مرّر fetch لتسجيل الطلبات أو إضافة ترويسات التتبع أو المرور عبر وكيل. تستقبل الدالة العنوان الكامل وكائن RequestInit الذي بناه العميل.

logging-fetch.ts
import { SMSFabric, type FetchLike } from '@smsfabric/sdk';
const loggingFetch: FetchLike = async (input, init) => {
const started = Date.now();
const res = await fetch(input, init);
console.log(init.method, new URL(input).pathname, res.status, `${Date.now() - started}ms`);
return res;
};
export const sms = new SMSFabric({ apiKey: process.env.SMSFABRIC_API_KEY, fetch: loggingFetch });

سجّل الطريقة والمسار والحالة فقط. محتوى الطلبات يحمل أرقام الهواتف ونصوص الرسائل، والترويسات تحمل مفتاحك.

الطلبات منخفضة المستوى

Section titled “الطلبات منخفضة المستوى”

تستدعي sms.http.request أي نقطة نهاية ببيانات اعتماد العميل وإعادة المحاولة ومعالجة الأخطاء نفسها. استخدمها لنقطة نهاية لا تملك الحزمة دالة لها بعد.

low-level.ts
import { SMSFabric } from '@smsfabric/sdk';
const sms = new SMSFabric({ apiKey: process.env.SMSFABRIC_API_KEY });
const tags = await sms.http.request<{ data: Array<{ tag: string; contacts: number }> }>({
method: 'GET',
path: '/v1/contacts/tags',
query: { q: 'vip' },
});
console.log(tags.data);

تقبل request الحقول method وpath وquery وbody (يرسل بصيغة JSON) وidempotencyKey وresponseText (يعيد المحتوى نصًا بدل تحليله كـ JSON).

تحتوي الحزمة على النسختين. استخدم ما يستخدمه مشروعك:

import { SMSFabric, SMSFabricError } from '@smsfabric/sdk';

الأنواع مضمنة في الحزمة، ولا تحتاج إلى حزمة @types منفصلة. كل شكل استجابة وكل كائن معاملات مصدّر، فيمكنك استخدامه في دوالك:

types.ts
import { SMSFabric, type Message, type SendMessageParams } from '@smsfabric/sdk';
const sms = new SMSFabric({ apiKey: process.env.SMSFABRIC_API_KEY });
export async function notify(params: SendMessageParams): Promise<Message[]> {
return sms.messages.send(params);
}

أصناف الموارد (Messages وVerifications وDevices وغيرها) مصدّرة أيضًا، لتحديد نوع اعتمادية تستقبل موردًا واحدًا. ورقم إصدار الحزمة مصدّر باسم VERSION ويرسل في ترويسة User-Agent بالشكل smsfabric-node/<version>.