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)`	کلاینتی جدا با همان بازگشت به محیط، برای کلیدی دوم در کنار کلید مشترک، یا برای ساختن نمونه‌ای که ماژول خودتان آن را export می‌کند. `createClient` همین تابع است با نامی که SDK مربوط به envless به کار می‌برد.
`new OpenEmail(options)` یا `new OpenEmail(apiKey)`	کلاینتی جدا که دقیقاً از آنچه می‌دهید ساخته می‌شود. هیچ چیزی از محیط نمی‌خواند، پس `apiKey` الزامی است. export پیش‌فرض هم همین است.

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://` می‌گذارند، یا جلوی localhost `http://`.
`timeoutMs`	30000	برای هر تلاش، نه برای هر فراخوانی. خواندن بدنه را هم در بر می‌گیرد، نه فقط سرآیندها را. 0 آن را غیرفعال می‌کند.
`maxRetries`	2	تلاش‌های اضافی پس از تلاش نخست، روی فراخوانی‌هایی که تکرارشان بی‌خطر است. روی کلاینت تنظیم می‌شود، نه برای هر فراخوانی.
`fetch`	نمونهٔ سراسری	برای شما bind شده است. برای یک proxy، یک binding در 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` ای که یک URL با http یا https نیست	چیز دیگری قابل fetch نیست، و مقدار اعتبارسنجی‌نشده بعداً به‌صورت یک `TypeError` خام از جایی کاملاً دیگر شکست می‌خورد.
یک مرورگر	کلید برای هرکسی که devtools را باز کند خواندنی می‌شد. بخش پایین را ببینید.
هیچ `fetch` ای در دسترس نیست	یکی را به‌عنوان `fetch` بدهید، یا روی Node 20+ اجرا کنید.
id خالی یا تماماً نقطه در هر متدی	هنگام فراخوانی متد پرتاب می‌شود. بخشی از مسیر که فقط نقطه باشد را هر تجزیه‌گر URL حذف می‌کند، پس درخواست به نقطهٔ پایانی دیگری می‌رسید.

گزینه‌ای به نام testMode وجود ندارد و نخواهد داشت. طرح کلید بخشی از خودِ اعتبارنامه است نه یک اشاره، پس حالت، ویژگیِ کلید است. openemail.mode پیشوند را می‌خواند و دربارهٔ چیزی تصمیم نمی‌گیرد.

یک کلاینت، چند کلید

کلاینت را یک بار بسازید و به اشتراک بگذارید. نمونهٔ تازه برای هر درخواست، بی‌هیچ سودی bind مربوط به 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، می‌گیرد، و روی یک فهرست همان شیئی است که فیلترها هستند. پیش از فرستادن درخواست و با همان قاعده‌ای که سازنده به کار می‌برد بررسی می‌شود، پس یک غلط تایپی به‌جای 401 دربارهٔ اعتبارنامه‌ای که باید بگردید و پیدایش کنید، یک Error پرتاب می‌کند که { apiKey } on this call را نام می‌برد. فراخوانی‌ای که دوباره تلاش می‌شود همان کلیدی را نگه می‌دارد که به آن داده شده بود.

signal یک AbortSignal است. لغو آن درخواست را متوقف می‌کند، و هر تلاش دوباره‌ای را هم که پشت آن منتظر است.

openemail.mode کلیدی را توصیف می‌کند که کلاینت با آن ساخته شده و از بازنویسی‌های موردی پیروی نمی‌کند. وقتی یک کلاینت به چند کلید خدمت می‌کند دیگر یک حالت یکتا برای گزارش وجود ندارد، پس آن را از روی کلیدی که داده‌اید بخوانید.

از یک مرورگر

کلاینت از آغازشدن در مرورگر سر باز می‌زند و پیش از بیرون‌رفتن هر درخواستی خطا پرتاب می‌کند. کلیدی در یک صفحهٔ وب، کلیدی است که منتشر کرده‌اید: برای هرکسی که devtools را باز کند می‌تواند ایمیل بفرستد و صندوق پستی را بخواند. به‌جای آن از یک سرور، یک تابع 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 در preflight مربوط به CORS دقیقاً Content-Type، Authorization و Idempotency-Key را عبور می‌دهد، پس سرآیند اضافی در headers به‌جای خود درخواست، preflight را شکست می‌دهد، و آنچه مرورگر دربارهٔ آن گزارش می‌کند چیز به‌دردبخوری نمی‌گوید.