Kennisbank

Getypeerde SDK's

Eerst een TypeScript-client, daarna de rest.

Details

Gepubliceerd op npm en in gebruik. @openemail/sdk is een complete TypeScript-client zonder afhankelijkheden, gepubliceerd als zowel ESM als CommonJS, met één methode voor elke gedocumenteerde operatie die de API serveert, plus de twee niet-geauthenticeerde meta-endpoints die een clientgenerator nodig heeft, met de sleutel gelezen uit OPENEMAIL_API_KEY, een time-out van 30 seconden per poging, twee nieuwe pogingen, een apiKey-override per aanroep voor een proces dat meerdere workspaces bedient, en emails.iterate() om een lijst door te bladeren zonder de cursorlus te schrijven. Hij draait op Node 18 en hoger, Workers, Deno, Bun en in de browser. Een sleutel met het verkeerde voorvoegsel gooit al bij de constructie een fout in plaats van bij de eerste aanroep een 401 te geven; de controle is niet meer dan een voorvoegsel, dus een keurig gevormde sleutel die is ingetrokken faalt nog steeds op de lijn.
Hij wordt aan de server gehouden door een pariteitscontrole die bij elke build het OpenAPI-document leest en faalt zodra de twee uit elkaar lopen: een methode die wijst naar een operatie die de spec niet heeft, een gedocumenteerde operatie zonder methode, een scopelijst die niet overeenkomt met wat de operatie vereist, een namespace met methoden en zonder vermelding in de referentie, of een methode die niet het verzoek stuurt dat haar eigen manifest noemt. Hij drukt af wat hij heeft bewezen, en vandaag staat daar 116 SDK-methoden die alle 104 gedocumenteerde operaties dekken. Er staan twee generatorscripts naast die weigeren een operatie uit te geven die niet geclassificeerd is of met een em dash is geschreven. Daarom is de client geen wrapper die achteraf is geschreven. Hij kan niet een release achterlopen op de API.
Wat ontbreekt is het releasegereedschap. Het pakket staat op npm, dus bun add @openemail/sdk werkt, maar er is geen release-workflow: publiceren is een handmatige run van de preflight, de build en bun publish, wat betekent dat een versie npm bereikt wanneer iemand eraan denkt in plaats van wanneer de wijziging landt. De API waar hij standaard naartoe wijst staat aan en antwoordt.
TypeScript is de enige taal, en het OpenAPI-document is bewust het antwoord voor de rest, in plaats van vijf handgeschreven clients die elk in een ander tempo achterop raken. Er is geen Python-, Go- of Ruby-client in de repo, en die komt er niet voordat het document datgene is waaruit ze worden gegenereerd.