База знаний
Типизированные SDK
Сначала клиент на TypeScript, потом остальные.
Подробности
- Опубликован на npm и используется. @openemail/sdk — полный клиент на TypeScript без зависимостей, опубликованный и как ESM, и как CommonJS, с одним методом на каждую документированную операцию, которую отдаёт API, плюс два неаутентифицированных мета-эндпоинта, нужных генератору клиентов, а также с ключом, читаемым из OPENEMAIL_API_KEY, таймаутом 30 секунд на попытку, двумя повторами, переопределением apiKey на вызов для процесса, обслуживающего несколько рабочих пространств, и emails.iterate() для постраничного обхода списка без написания цикла по курсору. Он работает на Node 18 и выше, Workers, Deno, Bun и в браузере. Ключ с неправильным префиксом выбрасывает ошибку при создании, а не отвечает 401 на первом вызове; проверка — это префикс и ничего больше, поэтому корректно оформленный, но отозванный ключ всё равно отвалится уже на проводе.
- Он привязан к серверу проверкой соответствия, которая читает документ OpenAPI при каждой сборке и падает, если эти двое разошлись: метод, указывающий на операцию, которой нет в спецификации, документированная операция без метода, список скоупов, не совпадающий с тем, который требует операция, пространство имён с методами и без записи в справочнике или метод, отправляющий не тот запрос, который называет его собственный манифест. Она печатает, что именно доказала, и сегодня это читается как 116 методов SDK, покрывающих все 104 документированные операции. Рядом стоят два скрипта-генератора, которые отказываются выдавать операцию, если она не классифицирована или написана с длинным тире. Поэтому клиент — не обёртка, написанная задним числом. Он не может отставать от API на релиз.
- Не хватает обвязки для релизов. Пакет есть на npm, поэтому
bun add @openemail/sdkработает, но релизного процесса нет: публикация — это ручной запуск преflight-проверки, сборки иbun publish, а значит, версия попадает на npm, когда кто-то про это вспомнил, а не когда изменение приехало. API, на который он ссылается по умолчанию, включён и отвечает. - TypeScript — единственный язык, и документ OpenAPI намеренно является ответом для остальных, вместо пяти написанных вручную клиентов, отстающих с разной скоростью. В репозитории нет клиентов на Python, Go или Ruby, и не будет, пока документ не станет тем, из чего их генерируют.