SDK

الإعداد

ثلاث طرق لإنشاء عميل، وكل خيار متاح، وما يرفضه قبل إرسال أي طلب.

الخيارات

openemail.ts

import OpenEmail, { createOpenEmail, init, openemail } from '@openemail/sdk' init({ apiKey: process.env.OPENEMAIL_API_KEY })await openemail.me.ping() export const billing = createOpenEmail({ apiKey: process.env.BILLING_API_KEY! }) const pinned = new OpenEmail({ apiKey: 'oe_live_…', baseUrl: 'https://api.openemail.uk' }) const quick = new OpenEmail('oe_live_…')

نقطة الدخول	ما الذي يمنحك إياه
`init(options)`	يضبط العميل المشترك ويعيده. يصبح `openemail` هو ذلك العميل منذ تلك اللحظة، في كل وحدة، وكل ما تتركه دون تحديد يُقرأ من بيئة التشغيل.
`openemail`	العميل المشترك. إذا استُخدم قبل `init` فإنه يبني نفسه من `OPENEMAIL_API_KEY` و`OPENEMAIL_BASE_URL` عند أول استدعاء.
`createOpenEmail(options)`	عميل منفصل يعتمد الرجوع نفسه إلى بيئة التشغيل، لمفتاح ثانٍ إلى جانب المفتاح المشترك، أو لبناء النسخة التي تصدّرها وحدتك الخاصة. و`createClient` هي الدالة نفسها بالاسم الذي تستخدمه حزمة envless SDK.
`new OpenEmail(options)` أو `new OpenEmail(apiKey)`	عميل منفصل يُبنى مما تمرّره بالضبط. لا يقرأ بيئة التشغيل، لذا فإن `apiKey` مطلوب. وهو أيضًا التصدير الافتراضي.

options.ts

init({  apiKey: 'oe_live_…',  baseUrl: 'https://api.openemail.uk',  timeoutMs: 30_000,  maxRetries: 2,  fetch: myFetch,  headers: {},  userAgent: 'billing-service/1.4',  disableUpdateNotice: true,})

الخيار	القيمة الافتراضية	ملاحظات
`apiKey`	`OPENEMAIL_API_KEY`	يُقرأ من بيئة التشغيل عبر `init` و`createOpenEmail`. ويجب أن يبدأ بـ `oe_live_` أو `oe_test_`.
`baseUrl`	`https://api.openemail.uk`	أو `OPENEMAIL_BASE_URL`. تُحذف الشرطة المائلة الأخيرة، ويضع `init` و`createOpenEmail` البادئة `https://` أمام اسم مضيف مجرّد، أو `http://` أمام localhost.
`timeoutMs`	30000	لكل محاولة، لا لكل استدعاء. ويشمل قراءة جسم الاستجابة، لا الترويسات وحدها. والقيمة 0 تعطّله.
`maxRetries`	2	محاولات إضافية بعد الأولى، على الاستدعاءات التي يمكن تكرارها بأمان. يُضبط على العميل، لا لكل استدعاء.
`fetch`	الدالة العامة	مربوطة لك مسبقًا. مرّر واحدة عند استخدام وسيط، أو ربط Worker، أو بديل اختباري.
`headers`	`{}`	تُرسل مع كل طلب.
`userAgent`	`openemail-sdk/<version>`	يُرسل من كل بيئة تشغيل عدا المتصفح، الذي لا يسمح بضبطه.
`disableUpdateNotice`	false	يتخطى الفحص الذي يجري مرة واحدة لكل عملية بحثًا عن إصدار أحدث على npm. ولا يعمل هذا الفحص إلا عندما يذهب الإخراج إلى طرفية، كما أن `OPENEMAIL_DISABLE_UPDATE_NOTICE` يوقفه أيضًا.
`dangerouslyAllowBrowser`	false	يسمح للعميل بالعمل حيث يوجد `window` و`document`. مخصص لبيئة اختبار تُعرّفهما، لا لصفحة ويب.

ما يرفضه قبل الإرسال

ترمي هذه الحالات كائن Error عاديًا من السطر الذي حمل القيمة الخاطئة، بدلًا من أن تظهر كفشل محيّر عند أول إرسال. وتوضح الرسالة ما الخطأ وما الذي ينبغي تمريره بدلًا منه.

المرفوض	السبب
لا مفتاح على الإطلاق	لم يُضبط `apiKey` ولا `OPENEMAIL_API_KEY`، فلا يوجد ما يمكن المصادقة به.
ملف تعريف ارتباط جلسة أو رمز جلسة	لا يصادق هنا سوى `oe_live_` و`oe_test_`، وهذا ما تقوله واجهة API أيضًا. والفحص مجرد بادئة لا أكثر، لذا فإن مفتاحًا ملغى يفشل عند الإرسال الفعلي.
قيمة `baseUrl` ليست عنوان http أو https	لا يمكن جلب أي شيء آخر، وقيمة غير مُتحقق منها كانت ستفشل لاحقًا كـ `TypeError` خام قادم من مكان آخر تمامًا.
متصفح	سيكون المفتاح قابلًا للقراءة لأي شخص يفتح أدوات المطور. راجع القسم أدناه.
لا وجود لـ `fetch` في أي مكان	مرّر واحدة عبر `fetch`، أو شغّل على Node 20+.
معرّف فارغ أو مكوّن من نقاط فقط في أي دالة	يُرمى عند استدعاء الدالة. فأي مقطع مسار مكوّن من نقاط يحذفه كل محلل عناوين، فيصل الطلب عندئذ إلى نقطة نهاية مختلفة.

لا يوجد خيار testMode ولن يوجد. فمخطط المفتاح جزء من بيانات الاعتماد نفسها لا مجرد تلميح، ومن ثَم فالوضع خاصية من خصائص المفتاح. وopenemail.mode يقرأ البادئة ولا يقرر شيئًا.

عميل واحد، عدة مفاتيح

أنشئ العميل مرة واحدة وشاركه. فإنشاء نسخة جديدة لكل طلب يهدر ربط fetch والإعدادات دون مقابل، ولا شيء من حالته خاص بمستدعٍ بعينه.

أما الحالة التي كانت ستفرض نسخة لكل مفتاح، مثل مهمة ترسل بالنيابة عن عدة مساحات عمل، فمرّر فيها apiKey مع الاستدعاء. إذ يستبدل ترويسة Authorization لذلك الطلب ولا يترك أثرًا على العميل.

per-call-key.ts

await openemail.emails.send(message) await openemail.emails.send(message, { apiKey: workspace.apiKey }) await openemail.threads.list({ folder: 'inbox', apiKey: workspace.apiKey })await openemail.webhooks.list({ apiKey: workspace.apiKey })

تقبله كل دالة خارج tempMail في وسيطها الأخير، إلى جانب signal، وفي القوائم يكون في الكائن نفسه الذي يحمل المرشِّحات. ويُفحص قبل إرسال الطلب، بالقاعدة نفسها التي يستخدمها المُنشئ، فيؤدي خطأ مطبعي إلى رمي Error يذكر { apiKey } on this call بدلًا من 401 عن بيانات اعتماد عليك البحث عنها بعد ذلك. والاستدعاء المُعاد يحتفظ بالمفتاح الذي أُعطي له.

signal هو AbortSignal. وإلغاؤه يوقف الطلب، وأي إعادة محاولة تنتظر خلفه.

openemail.mode يصف المفتاح الذي أُنشئ به العميل ولا يتبع أي تجاوز لاحق. فما إن يخدم عميل واحد عدة مفاتيح حتى لا يعود هناك وضع واحد يمكن الإبلاغ عنه، لذا اقرأه من المفتاح الذي مرّرته.

من متصفح

يرفض العميل العمل داخل متصفح ويرمي خطأ قبل خروج أي طلب. فالمفتاح في صفحة ويب مفتاح نشرته للعلن: يمكنه إرسال البريد وقراءة صندوق البريد لأي شخص يفتح أدوات المطور. استدعِه من خادم أو دالة serverless أو سكربت بدلًا من ذلك.

صناديق البريد المؤقتة هي الاستثناء. فـ createTempMail() ينشئ عميلًا لا يحمل أي مفتاح API، وهو بذلك آمن داخل الصفحة. ينشئ صناديق بريد بشكل مجهول، وكل قراءة ترسل الرمز الذي أعاده create، إما لكل استدعاء عبر inboxToken أو مرة واحدة عبر createTempMail({ inboxToken }).

temp-mail.ts

import { createTempMail } from '@openemail/sdk' const tempMail = createTempMail() const inbox = await tempMail.create()const { items, expiresAt } = await tempMail.listMessages(inbox.id, { inboxToken: inbox.token })

وحين تمرّر dangerouslyAllowBrowser: true رغم ذلك، تسمح واجهة API بـ Content-Type وAuthorization وIdempotency-Key فقط عبر فحص CORS المسبق، فأي ترويسة إضافية في headers تُفشل الفحص المسبق لا الطلب نفسه، وما يبلّغ عنه المتصفح في تلك الحالة لا يفيد بشيء.