ナレッジベース
型付きSDK
まずTypeScriptクライアント、その後に他の言語。
詳細
- npmで公開済みで、実際に使われている。@openemail/sdk は依存関係のない完全なTypeScriptクライアントで、ESMとCommonJSの両方で公開されている。APIが提供する文書化された操作それぞれに1つのメソッドを備え、さらにクライアントジェネレーターが必要とする認証不要のメタエンドポイント2つも持つ。キーは OPENEMAIL_API_KEY から読み取られ、1試行あたり30秒のタイムアウト、2回の再試行、複数のワークスペースを扱うプロセス向けの呼び出し単位の apiKey 上書き、そしてカーソルのループを書かずに一覧をページングできる emails.iterate() を備える。Node 18以降、Workers、Deno、Bun、ブラウザで動作する。プレフィックスが誤っているキーは、最初の呼び出しで401になるのではなく構築時に例外を投げる。チェックはプレフィックスだけなので、形式が正しくても失効したキーは通信時に失敗する。
- SDKはサーバーとの整合性チェックによって結び付けられており、ビルドのたびにOpenAPIドキュメントを読み、両者が乖離していれば失敗する。仕様にない操作を指すメソッド、メソッドのない文書化された操作、操作が必要とするものと一致しないスコープ一覧、メソッドはあるのにリファレンスに項目がない名前空間、自身のマニフェストが示すリクエストを送らないメソッドが対象である。検証した内容も出力され、現時点では116のSDKメソッドが104の文書化された操作すべてを網羅していると表示される。その横には2つのジェネレータースクリプトがあり、分類されていない操作やemダッシュで書かれた操作の出力を拒否する。だからこそ、このクライアントは後付けのラッパーではない。APIに1リリース分遅れることはあり得ない。
- 欠けているのはリリースの仕組みである。パッケージはnpmにあるので
bun add @openemail/sdkは動くが、リリース用のワークフローがない。公開はプリフライト、ビルド、bun publishを手作業で実行することであり、つまりバージョンがnpmに届くのは変更が入ったときではなく、誰かが思い出したときである。既定で参照するAPIは稼働しており、応答している。 - 言語はTypeScriptだけであり、他の言語については、異なる速度で遅れていく5つの手書きクライアントではなく、OpenAPIドキュメントを意図的に答えとしている。リポジトリにはPython、Go、Rubyのクライアントはなく、それらがこのドキュメントから生成されるようになるまで作られることもない。