Вспомогательные функции и константы
Что ещё определяет гем помимо клиента.
Методы модуля
| Метод | Что это |
|---|---|
| OpenEmail.init, OpenEmail.client | Настройте общий клиент один раз и обращайтесь к нему откуда угодно. Если init так и не был вызван, клиент соберёт себя из OPENEMAIL_API_KEY. |
| 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 | Версия гема. |
| 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. Гем строит собственный объект только там, где он придаёт ответу форму, и каждый такой объект является неизменяемым 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]. |
Каждая ошибка, которую гем выбрасывает намеренно, наследуется от OpenEmail::Error: ApiError и его подклассы, NetworkError и WebhookSignatureError. Неверный аргумент вместо этого даёт ArgumentError, потому что это ошибка в вызывающем коде, а не то, что нужно перехватывать.
Эндпоинт, который пока не обёрнут
Выпуск гема никогда не должен стоять между вами и эндпоинтом, который уже работает. client.raw.request принимает путь и именованные параметры и возвращает разобранное тело, применяя учётные данные клиента, базовый URL, таймаут и политику повторов.
result = client.raw.request( "/something-new", method: :post, query: {dryRun: true}, body: {name: "Invoices"}, repeatable: true) p resultGET повторяется, как любое другое чтение. Любой другой метод отправляется один раз, если вы не передадите repeatable: true, то есть не заявите, что его можно отправить дважды. query: пропускает значения nil и пустые, а api_key: работает так же, как в любом другом методе.
Чего он намеренно не делает
- Он не проверяет тело запроса. Схема сервера является единственной копией правил, а вторая копия здесь рано или поздно отклонила бы адрес, который принимает более новый сервер, в версии, которую кто-то закрепил два года назад.
- У него нет зависимостей во время выполнения, нет даже гема для JSON или HTTP сверх стандартной библиотеки.
- Он меняет форму ответа только одним способом: массив
dataколлекции извлекается из конверта в один из объектов выше. Любой другой ответ возвращается так, как его прислал API, с ключами API в camelCase.
Проверка соответствия гема следит за этим. Она роняет сборку, когда у метода TypeScript нет двойника на Ruby, когда он принимает другие параметры или отправляет другой запрос.