Перейти к документации
SDK

Типы и вспомогательные функции

Что ещё экспортирует пакет.

Экспорты времени выполнения

ЭкспортЧто это
`init`, `openemail`Настройте общий клиент один раз, а дальше импортируйте openemail где угодно. Если init не вызывался, клиент соберёт себя из OPENEMAIL_API_KEY.
`getClient`, `resetClient`Сам общий клиент и способ его сбросить, чтобы следующий вызов собрал новый, — именно это нужно тесту между случаями.
`createOpenEmail`, `createClient`, `OpenEmail`Отдельный клиент. createOpenEmail берёт из окружения всё, что вы не указали (createClient — та же функция), а new OpenEmail (он же экспорт по умолчанию) принимает только то, что вы передали.
`createTempMail`Клиент одноразового ящика, который не несёт API-ключа, — единственная часть пакета, работающая в браузере.
`OpenEmailApiError`, `OpenEmailNetworkError`Два класса ошибок.
`verifyWebhookSignature`Сравнение за постоянное время, с окном защиты от повторов. Разрешается разобранной полезной нагрузкой и выбрасывает исключение при любом сбое.
`toBase64`С разбиением на части — для байтов вложений.
`isApiKey`Имеет ли строка форму oe_live_ или oe_test_. Это проверка формы, а не доказательство того, что ключ ещё работает.
`isSealed`, `MESSAGE_ENCRYPTION_FORMATS`Является ли тело письма шифротекстом, и пять конвертов, которые может назвать приём почты. isSealed равно false для двух ПОДПИСАННЫХ форматов, тела которых пришли в открытом виде, — потому функция и поставляется, а не оставлена на выведение вызывающим из объединения типов.
`LANGUAGES`, `resolveLanguage`, `languageByCode`, `isRtlLanguage`Встроенная таблица языков и функции поиска, нужные для выбора языка.
`API_SCOPES`Словарь областей — для экрана создания ключа.
`WEBHOOK_EVENTS`, `WEBHOOK_SIGNATURE_HEADERS`События, на которые может подписаться эндпоинт, и имена заголовков, которые несёт доставка.
`RULE_FIELDS`, `RULE_OPERATORS`, `RULE_ACTIONS`Словарь, из которого строятся условия и действия правила.
`PAGE_LIMITS`Максимальный и используемый по умолчанию limit для постраничного списка: 100 и 25.
`ERROR_TYPES`Замороженный словарь ошибок.
`VERSION`Версия пакета.

Типы

У каждого запроса и ответа есть свой тип, и все они экспортируются из корня пакета. Глубоких импортов нет, поэтому раскладка файлов остаётся деталью реализации, которую можно менять без мажорной версии. …Resource — это то, что возвращает API, …Create, …Patch, …Input и …Send — то, что передаёте вы, а …Options содержит фильтры и параметры конкретного вызова.

  • Клиент: ClientOptions, TempMailOptions, TransportOptions, RequestOptions, RequestScope, SendScope, InboxScope, ListOptions, Page, ApiKeyMode, FetchLike.
  • Ошибки: ErrorType, ApiErrorPayload, ApiErrorProps.
  • Письма: EmailSend, EmailListOptions, EmailTranslate, EmailResource, SentEmailResource, EmailRecipientResource, EmailEventResource, EmailStatus, EmailSource, EmailTransport, EmailTrackingSummary, EmailTranslationResource, TranslationResource, RecipientStatus, BatchItemResource, BatchResultResource.
  • Шаблоны: TemplateCreate, TemplatePatch, TemplateContent, TemplateListOptions, TemplatePreviewInput, TemplateSend, TemplateResource, TemplateDetailResource, TemplateVersionResource, TemplatePreviewResource, SentTemplateEmailResource, DeletedTemplateResource, TemplateEngine, TemplateProp, TemplateSlot, TemplateStatus, TemplateValueKind.
  • Отслеживание: TrackingListOptions, TrackingStatsOptions, TrackingHitOptions, TrackingResource, TrackingSummary, TrackingRecipientResource, TrackingLinkResource, TrackingOpenResource, TrackingClickResource, TrackingStatsResource, TrackingGrain.
  • Переписки и черновики: ThreadListOptions, ThreadPatch, ThreadResource, ThreadSummaryResource, UpdatedThreadResource, TrashedThreadResource, SnoozedThreadResource, DraftInput, DraftListOptions, DraftResource, DraftSummaryResource, SavedDraftResource, DeletedDraftResource.
  • Ярлыки, контакты, домены и адреса: LabelInput, LabelColor, LabelResource, SavedLabelResource, DeletedLabelResource, ContactCreate, ContactPatch, ContactListOptions, ContactSource, ContactResource, ContactDetailResource, ContactAudienceResource, DeletedContactResource, DomainPatch, DomainResource, DomainDetailResource, DomainSendingState, DomainTracking, DomainTrackingState, AddressBookResource, AddressResource, SendableDomainResource.
  • Правила: RuleCreate, RulePatch, RuleListOptions, RuleRunListOptions, RuleTestInput, RuleResource, RuleRunResource, RuleTestResource, DeletedRuleResource, RuleCondition, RuleConditionInput, RuleAction, RuleActionType, RuleField, RuleOperator.
  • Вебхуки: WebhookCreate, WebhookPatch, WebhookResource, CreatedWebhookResource, DeletedWebhookResource, WebhookDeliveryResource, WebhookTestResource, WebhookEvent, WebhookPayload, EmailOpenedData, EmailClickedData, EmailDownloadedData, VerifyWebhookProps, WebhookSignatureHeaders.
  • Календарь и настройки: CalendarRangeOptions, CalendarOccurrenceResource, CalendarEventResource, CalendarAttendeeResource, SettingsPatch, SettingsResource.
  • Роли, участники и ключи: RoleCreate, RolePatch, RoleDeleteOptions, RoleResource, DeletedRoleResource, PermissionResource, MemberAdd, MemberPatch, MemberAddressGrant, MemberResource, MemberAddressResource, RemovedMemberResource, MemberAccess, KeyResource, PingResource.
  • Одноразовые ящики: TempInboxCreate, TempMessageListOptions, TempInboxResource, CreatedTempInboxResource, DeletedTempInboxResource, TempDomainResource, TempMessageResource, TempMessagesResource, TempMessageDetailResource, DeletedTempMessageResource.
  • Общие: RecipientInput, AttachmentInput, AttachmentResource, MessageResource, MessageEncryption, MessageEncryptionFormat, TrackingRequest, TranslateOptions, SendTranslateOptions, LanguageResource, ApiScope, Permission, BuiltinRole, HitKind.

Эндпоинт, который пока не обёрнут

Релиз SDK никогда не должен стоять между вами и эндпоинтом, который уже работает. openemail.raw.request() принимает путь и параметры и разрешается разобранным телом, применяя ключ клиента, базовый URL, таймаут и политику повторов.

escape-hatch.ts
const result = await openemail.raw.request<Whatever>('/something-new', {  method: 'POST',  query: { dryRun: true },  body: { name: 'Invoices' },  repeatable: true,})

GET повторяется так же, как любое другое чтение. Любой другой метод отправляется один раз, если вы не передали repeatable: true — ваше утверждение о том, что его можно отправить дважды. query пропускает значения, равные undefined, а signal работает так же, как и во всех остальных методах.

Чего он намеренно не делает

  • Он не проверяет тело запроса. Схема на сервере — единственная копия правил, а вторая копия здесь рано или поздно отвергла бы адрес, который более новый сервер принимает, — в версии, зафиксированной кем-то два года назад.
  • Он не поставляет ни zod, ни каких-либо зависимостей времени выполнения вообще.
  • Он меняет форму ответа ровно одним способом: массив data коллекции вынимается из конверта. Постраничный список отдаёт его как items рядом с hasMore и nextCursor, emails.sendBatch — как items рядом с sent и failed, tempMail.listMessages — как items рядом с expiresAt, а addresses.list — как addresses рядом с unrestricted и domains. Во всех остальных случаях это обычный массив. Каждый ресурс внутри сохраняет задокументированную форму HTTP.

Проверка соответствия в пакете держит это в честных рамках. Она роняет сборку, когда у задокументированной операции нет метода, когда метод указывает на операцию, которой нет в документе OpenAPI, или отправляет другой запрос, и когда метод объявляет области, которых операция не требует.