مكتبة خادم إيصالات لـ Node.js

التثبيت

npm install esaalat

أنشئ الجلسة

import { createEsaalatServer } from "esaalat/server";

// Reads ESAALAT_CLIENT_ID, ESAALAT_CLIENT_SECRET and ESAALAT_WEBHOOK_SECRET.
const esaalat = createEsaalatServer();

// Your server fixes the amount; the browser only ever receives the token.
const session = await esaalat.sessions.create({
  orderId: "order-12345",
  amount: 5000, // whole riyals, as a number or a string
});

// session.session_token → open the checkout from your page
// session.portal_url    → or redirect the buyer straight to it

تحقق من الـ Webhook

// Keep the raw body: a parsed-and-restringified object will not match.
app.post(
  "/esaalat/webhooks",
  express.raw({ type: "application/json" }),
  async (req, res) => {
    try {
      const { payload } = await esaalat.webhooks.verify(
        req.body,
        req.header("X-Esaalat-Signature") ?? ""
      );

      if (payload.event === "payment.verified") {
        releaseOrder(payload.order_id); // idempotent on intent_id
      }
      res.sendStatus(200);
    } catch {
      res.sendStatus(400); // anything but 2xx schedules a retry
    }
  }
);

ما تتولاه الحزمة عنك

• •رمز الوصول مخزّن — رمز واحد لكل عملية، يُجدَّد قبل دقيقة من exp داخل الـ JWT، فلا تبدأ طلباتك بالفشل عند انتهاء الساعة.
• •مفتاح التكرار تلقائي — مفتاح واحد لكل إنشاء، يُستخدم نفسه في كل محاولة إعادة: لا يمكن لـ 429 أو انتهاء المهلة أن ينشئ الطلب مرتين.
• •إعادة المحاولة — على 429 و5xx وفشل الشبكة، مع احترام Retry-After.
• •أخطاء مصنّفة — كل خطأ يحمل رمزاً وحالة HTTP والحقل المتسبب وأخطاء الحقول التي يعيدها الـ API.
• •لخادمك فقط — لا يصل إلى المتصفح إلا رمز الجلسة. أما سر العميل فيبقى على خادمك حيث يجب أن يكون.

الإعدادات

قبل أن تنطلق

• •الحزمة ترفض العمل إذا وُجد window، فلا يمكن لأداة تجميع أن تُرسلها إلى صفحة.
• •المبالغ بالريال اليمني كأرقام صحيحة، والكسر يُرفض قبل أن يخرج الطلب من عمليتك.
• •حزمة واحدة بمدخلين: esaalat للمتصفح وesaalat/server لهذا الخادم.