Base de connaissances

SDK typés

Un client TypeScript d'abord, le reste ensuite.

Détails

Publié sur npm et utilisé. @openemail/sdk est un client TypeScript complet et sans dépendances, publié à la fois en ESM et en CommonJS, avec une méthode pour chaque opération documentée servie par l'API, plus les deux points de terminaison méta non authentifiés dont un générateur de client a besoin, la clé lue depuis OPENEMAIL_API_KEY, un délai de 30 secondes par tentative, deux nouvelles tentatives, une surcharge apiKey par appel pour un processus servant plusieurs espaces de travail, et emails.iterate() pour parcourir une liste sans écrire la boucle de curseur. Il tourne sur Node 18 et au-delà, Workers, Deno, Bun et le navigateur. Une clé au mauvais préfixe lève une erreur à la construction plutôt que de renvoyer 401 au premier appel ; la vérification porte sur le préfixe et rien d'autre, donc une clé bien formée mais révoquée échoue quand même sur le réseau.
Il est tenu au serveur par un contrôle de parité qui lit le document OpenAPI à chaque build et échoue si les deux divergent : une méthode pointant vers une opération absente de la spécification, une opération documentée sans méthode, une liste de scopes ne correspondant pas à celle qu'exige l'opération, un espace de noms avec des méthodes et aucune entrée dans la référence, ou une méthode qui n'envoie pas la requête nommée par son propre manifeste. Il affiche ce qu'il a prouvé, et cela indique aujourd'hui 116 méthodes du SDK couvrant les 104 opérations documentées. Deux scripts de génération l'accompagnent et refusent d'émettre une opération non classée ou écrite avec un tiret cadratin. C'est pourquoi le client n'est pas un habillage écrit après coup. Il ne peut pas prendre une version de retard sur l'API.
Ce qui manque, c'est la tuyauterie de publication. Le paquet est sur npm, donc bun add @openemail/sdk fonctionne, mais il n'y a pas de workflow de publication : publier consiste à lancer manuellement le preflight, le build et bun publish, ce qui veut dire qu'une version arrive sur npm quand quelqu'un y pense plutôt que quand le changement est livré. L'API qu'il vise par défaut est active et répond.
TypeScript est le seul langage, et le document OpenAPI est délibérément la réponse pour le reste, plutôt que cinq clients écrits à la main qui prennent du retard à des rythmes différents. Il n'y a pas de client Python, Go ou Ruby dans le dépôt, et il n'y en aura pas avant que le document ne soit ce à partir de quoi ils sont générés.