Журнал изменений

Первый выпуск. Он охватывает весь TypeScript SDK в том виде, в каком тот был на момент выпуска: 430 методов в 41 пространстве имён, каждый под своим именем из TypeScript, и каждый из них отправляет побайтно тот же запрос, что и его двойник на TypeScript.

• —У OpenEmail\OpenEmail есть свойство для каждого пространства имён, от emails, threads и templates до providerImports, dnsConnections и account, а методы каждого сохраняют свои имена из TypeScript.
• —Тело запроса представляет собой ассоциативный массив, ключи которого сохраняют имена API в camelCase, а параметры передаются именованными аргументами, например idempotencyKey: и apiKey:. Ответ возвращается как декодированный ассоциативный массив.
• —У каждого постраничного ресурса есть list, который возвращает одну Page, listAll, который возвращает все элементы массивом, и iterate, который возвращает Generator, запрашивающий следующую страницу, только когда до неё доходит. PeoplePage, TempMessagesPage, AddressBookPage, AddressBook, BatchResult и TemplateSends несут ответы, в которых есть что-то кроме списка.
• —Отказ API выбрасывает ApiException или его подкласс для типа ошибки с status, type, errorCode, param, docUrl, requestId, retryAfterSeconds, fields и body и с методами вроде isValidation() и isStepUpRequired(). Полное отсутствие ответа выбрасывает NetworkException с isTimeout(), если истёк срок ожидания. Ошибка в самом вызове выбрасывает InvalidArgumentException ещё до отправки. Каждое из них реализует OpenEmailException.
• —new OpenEmail() и OpenEmail::createClient() берут всё, что вы не указали, из OPENEMAIL_API_KEY, OPENEMAIL_ACCESS_TOKEN и OPENEMAIL_BASE_URL, а OpenEmail::init(), OpenEmail::getClient() и OpenEmail::resetClient() управляют одним общим клиентом. OpenEmail::createTempMail() открывает одноразовые ящики без учётных данных.
• —accessToken: принимает токен доступа OAuth или вызываемый объект, который его возвращает и вызывается перед каждым запросом. Каждый метод принимает apiKey:, чтобы действовать с другим ключом в одном вызове, а методы tempMail принимают inboxToken:. Каждый параметр, несущий учётные данные, помечен #[\SensitiveParameter].
• —OpenEmail::verifyWebhookSignature() проверяет доставку за постоянное время, отклоняет доставку старше пяти минут и возвращает декодированное событие. Подпись читается из массива заголовков с именами в любом регистре, из $_SERVER, из header bag Symfony или Laravel или из запроса PSR-7.
• —OpenEmail::toBase64(), isApiKey(), isAccessToken(), isSealed(), resolveLanguage(), languageByCode() и isRtlLanguage() являются вспомогательными функциями TypeScript SDK, а каждый набор значений, который экспортирует корень его пакета, является классом в OpenEmail\Constants.
• —Ему нужен PHP 8.2 или новее с расширениями curl и json, и больше ничего. Запросы идут через один дескриптор cURL на клиент, который держит соединение открытым между запросами и открывает новое после pcntl_fork, а timeout: ограничивает всю попытку целиком. Psr18HttpClient вместо этого отправляет их через Guzzle, Symfony HttpClient или любой другой клиент PSR-18.
• —Чтения, отправки и каждая запись, которую безопасно повторять, повторяются с нарастающей задержкой при 408, 500, 502, 503 и 504, а при 429 только тогда, когда его Retry-After не больше минуты. Каждая отправка несёт ключ идемпотентности, который переиспользуют её повторы.
• —Клиент отказывается отправлять учётные данные по обычному http: куда-либо, кроме этой машины, отклоняет базовый URL на 0.0.0.0, отклоняет заголовок, который разделил бы запрос, и никогда не позволяет raw->request() выйти за пределы источника базового URL.