Wissensdatenbank

Typisierte SDKs

Zuerst ein TypeScript-Client, dann der Rest.

Details

Auf npm veröffentlicht und im Einsatz. @openemail/sdk ist ein vollständiger, abhängigkeitsfreier TypeScript-Client, veröffentlicht sowohl als ESM als auch als CommonJS, mit einer Methode für jede dokumentierte Operation, die die API bedient, dazu den beiden nicht authentifizierten Meta-Endpunkten, die ein Client-Generator braucht, dem aus OPENEMAIL_API_KEY gelesenen Schlüssel, einem Timeout von 30 Sekunden pro Versuch, zwei Wiederholungen, einem apiKey-Override pro Aufruf für einen Prozess, der mehrere Workspaces bedient, und emails.iterate(), um eine Liste zu durchblättern, ohne die Cursor-Schleife zu schreiben. Er läuft auf Node 18 und höher, Workers, Deno, Bun und im Browser. Ein Schlüssel mit falschem Präfix wirft schon bei der Konstruktion einen Fehler, statt beim ersten Aufruf mit 401 zu antworten; die Prüfung ist ein Präfix und nichts weiter, ein wohlgeformter, aber widerrufener Schlüssel scheitert also weiterhin erst auf der Leitung.
Er wird durch eine Paritätsprüfung an den Server gebunden, die bei jedem Build das OpenAPI-Dokument liest und fehlschlägt, wenn die beiden auseinanderlaufen: eine Methode, die auf eine Operation zeigt, die die Spezifikation nicht kennt, eine dokumentierte Operation ohne Methode, eine Scope-Liste, die nicht zu der von der Operation geforderten passt, ein Namespace mit Methoden und ohne Eintrag in der Referenz, oder eine Methode, die nicht die Anfrage sendet, die ihr eigenes Manifest nennt. Sie gibt aus, was sie nachgewiesen hat, und heute liest sich das als 116 SDK-Methoden, die alle 104 dokumentierten Operationen abdecken. Zwei Generator-Skripte stehen daneben und weigern sich, eine Operation auszugeben, die nicht klassifiziert oder mit einem Geviertstrich geschrieben ist. Deshalb ist der Client kein nachträglich geschriebener Wrapper. Er kann der API nicht um ein Release hinterherhinken.
Was fehlt, ist die Release-Mechanik. Das Paket liegt auf npm, bun add @openemail/sdk funktioniert also, aber es gibt keinen Release-Workflow: Veröffentlichen ist ein manueller Durchlauf von Preflight, Build und bun publish, eine Version erreicht npm also dann, wenn jemand daran denkt, und nicht, wenn die Änderung landet. Die API, auf die er standardmäßig zeigt, ist aktiv und antwortet.
TypeScript ist die einzige Sprache, und das OpenAPI-Dokument ist für den Rest bewusst die Antwort, statt fünf handgeschriebener Clients, die unterschiedlich schnell zurückfallen. Es gibt keinen Python-, Go- oder Ruby-Client im Repository, und es wird keinen geben, bevor das Dokument das ist, woraus sie erzeugt werden.