الأدوات المساعدة والثوابت
ما يعرّفه الـ gem غير العميل.
توابع الوحدة
| الطريقة | ما هي |
|---|---|
| OpenEmail.init, OpenEmail.client | هيّئ العميل المشترك مرة واحدة، ثم صِل إليه من أي مكان. ويبني نفسه من OPENEMAIL_API_KEY إن لم يُنفَّذ init قط. |
| OpenEmail.emails وOpenEmail.threads وكل مساحة أسماء أخرى | اختصارات إلى مساحات أسماء العميل المشترك. |
| OpenEmail.reset_client | يتخلّص من العميل المشترك، فيبني الاستدعاء التالي عميلًا جديدًا، وهو ما يريده الاختبار بين الحالات. |
| OpenEmail.create_client, OpenEmail::Client.new, OpenEmail.new | عميل منفصل. يقرأ create_client من البيئة كل ما تتركه، ويأخذ Client.new (أو OpenEmail.new) ما تمرّره فقط. |
| OpenEmail.create_temp_mail | عميل لصناديق البريد المؤقتة لا يحمل أي مفتاح API. |
| OpenEmail.verify_webhook_signature | يفحص توقيع التسليم بزمن ثابت، مع نافذة لمنع إعادة التشغيل. ويعيد الحدث محلَّلًا، ويرفع OpenEmail::WebhookSignatureError عند أي إخفاق. |
| OpenEmail.to_base64 | ترميز Base64 لبايتات المرفقات، من String ثنائي أو IO أو Pathname. |
| OpenEmail.api_key? | ما إذا كان String يحمل شكل oe_live_ أو oe_test_. وهو فحص شكل، لا دليل على أن المفتاح ما زال يعمل. |
| OpenEmail.access_token? | ما إذا كان String يحمل شكل رمز وصول OAuth: من 1 إلى 512 حرفًا، ولا يبدأ بـ oe_. |
| OpenEmail.sealed? | ما إذا كان متن الرسالة نصًا مشفَّرًا. وتكون القيمة false للصيغتين الموقَّعتين اللتين وصل متنهما مكشوفًا. |
| OpenEmail.resolve_language, OpenEmail.language_by_code, OpenEmail.rtl_language? | عمليات البحث التي تحتاجها أداة اختيار اللغة، على جدول OpenEmail::LANGUAGES المضمَّن. |
الثوابت
كل مجموعة قيم يصدّرها TypeScript SDK هي Hash مجمَّد على OpenEmail، بالأسماء نفسها مفاتيحَ، فقيمة OpenEmail::WEBHOOK_EVENTS[:EMAIL_DELIVERED] هي "email.delivered". استخدم .values حيث تحتاج إلى القائمة، و.value? لفحص قيمة جاءت من الخارج.
events = OpenEmail::WEBHOOK_EVENTS.values scopes = [OpenEmail::API_SCOPES[:EMAILS_SEND], OpenEmail::API_SCOPES[:THREADS_READ]] puts events.size, scopes.join(","), OpenEmail::PAGE_LIMITS[:MAX_LIMIT]| الثابت | ما يحتويه |
|---|---|
| OpenEmail::VERSION | إصدار الـ gem. |
| OpenEmail::API_SCOPES | مفردات النطاقات، من أجل شاشة إنشاء مفتاح. |
| OpenEmail::WEBHOOK_EVENTS, OpenEmail::WEBHOOK_SIGNATURE_HEADERS | الأحداث التي يمكن لنقطة نهاية الاشتراك فيها، وأسماء الترويسات التي يحملها التسليم. |
| OpenEmail::ERROR_TYPES | مفردات الأخطاء التي يأخذها ApiError#type. |
| OpenEmail::PAGE_LIMITS | أكبر قيمة لـ limit: وقيمتها الافتراضية في معظم القوائم المرقّمة: 100 و25. وبعض القوائم تقبل أكثر، ويذكر مرجع كل تابع ذلك. |
| OpenEmail::RULE_FIELDS, OpenEmail::RULE_OPERATORS, OpenEmail::RULE_ACTIONS | المفردات التي تُبنى منها شروط القاعدة وإجراءاتها. |
| OpenEmail::MESSAGE_ENCRYPTION_FORMATS | الأغلفة الخمسة التي يمكن للاستقبال تسميتها. ثلاثة منها مختومة. |
| OpenEmail::CREDENTIAL_KINDS, OpenEmail::STEP_UP_METHODS, OpenEmail::STEP_UP_ERROR_CODES | أي اعتماد يصفه me.get وme.ping، وكيف يُفحص رمز التحقق، والرموز التي قد يفشل بها التحقق. |
| OpenEmail::THREAD_SORTS وOpenEmail::PEOPLE_SORTS وOpenEmail::FILE_SORTS وسائر *_SORTS | الترتيبات التي يمكن ترتيب القائمة بها. |
| OpenEmail::FORM_STATUSES وOpenEmail::BROADCAST_STATUSES وOpenEmail::SUPPRESSION_REASONS وسائر المجموعات | القيم التي يمكن أن يأخذها حقل في مورد. وكل مجموعة مسمّاة باسم ما تحمله. |
الكائنات
الاستجابة هي JSON المحلَّل في صورة Hash بمفاتيح من نوع Symbol. ولا يبني الـ gem كائنًا خاصًا به إلا حيث يشكّل الجواب، وكل منها Data غير قابل للتغيير.
| الصنف | ما يحمله |
|---|---|
| OpenEmail::Page | items وhas_more? وnext_cursor، من كل list مرقّم الصفحات. |
| OpenEmail::PeoplePage | الحقول نفسها مع seen، من contacts.list_people. |
| OpenEmail::TempMessagesPage | الحقول نفسها مع expires_at، من temp_mail.list_messages. |
| OpenEmail::AddressBookPage, OpenEmail::AddressBook | unrestricted وaddresses وdomains، من addresses.list (مع has_more? وnext_cursor) ومن addresses.list_all. |
| OpenEmail::BatchResult | items وsent وfailed، من emails.send_batch. |
| OpenEmail::TemplateSends | items وtotal وpage وpage_size، من templates.list_sends. |
| OpenEmail::HttpRequest, OpenEmail::HttpResponse | ما يستقبله adapter: ويعيده. والطلب يطبع ترويسة Authorization الخاصة به على أنها [redacted]. |
كل خطأ يرفعه الـ gem عمدًا يرث من OpenEmail::Error: ApiError وأصنافه الفرعية، وNetworkError، وWebhookSignatureError. أما الوسيط الخاطئ فيعطي ArgumentError بدلًا من ذلك، لأنه خطأ في الشيفرة المستدعية لا شيء يُلتقط.
نقطة نهاية لا تغلّفها الحزمة بعد
لا ينبغي أبدًا أن يكون إصدار الـ gem هو ما يقف بينك وبين نقطة نهاية تعمل بالفعل. يأخذ client.raw.request مسارًا وخيارات بوسائط مسمّاة ويعيد المتن المحلَّل، مع تطبيق اعتماد العميل وعنوان URL الأساسي والمهلة وسياسة إعادة المحاولة.
result = client.raw.request( "/something-new", method: :post, query: {dryRun: true}, body: {name: "Invoices"}, repeatable: true) p resultتُعاد محاولة GET كأي قراءة أخرى. وأي طريقة HTTP أخرى تُرسل مرة واحدة ما لم تمرّر repeatable: true، وهو تأكيدك أنه يجوز إرسالها مرتين. ويتخطى query: القيم nil أو الفارغة، ويعمل api_key: كما يعمل في كل تابع آخر.
ما لا تفعله عن قصد
- لا يتحقق من أي متن طلب. فمخطط الخادم هو النسخة الوحيدة من القواعد، ونسخة ثانية هنا سترفض في النهاية عنوانًا يقبله خادم أحدث، في إصدار ثبّته أحدهم قبل عامين.
- ليس له تبعيات وقت التشغيل، ولا حتى gem لـ JSON أو HTTP خارج المكتبة القياسية.
- يعيد تشكيل الاستجابة بطريقة واحدة فقط: تُستخرج مصفوفة
dataالخاصة بالمجموعة من غلافها إلى أحد الكائنات أعلاه. وكل استجابة أخرى تعود كما أرسلتها API، بمفاتيح API بصيغة camelCase.
يُبقي فحص التكافؤ في الـ gem هذا صادقًا. فهو يُفشل البناء حين لا يكون لتابع TypeScript توأم في Ruby، أو حين يأخذ خيارات مختلفة، أو يرسل طلبًا مختلفًا.