Base de conhecimento

SDK tipados

Primeiro um cliente TypeScript, depois os restantes.

Detalhes

Publicado no npm e em uso. O @openemail/sdk é um cliente TypeScript completo e sem dependências, publicado em ESM e em CommonJS, com um método para cada operação documentada que a API serve, mais os dois endpoints meta sem autenticação de que um gerador de clientes precisa, e com a chave lida de OPENEMAIL_API_KEY, um tempo-limite de 30 segundos por tentativa, duas repetições, uma substituição de apiKey por chamada para um processo que sirva vários espaços de trabalho, e emails.iterate() para percorrer uma lista sem escrever o ciclo do cursor. Corre em Node 18 e acima, Workers, Deno, Bun e no navegador. Uma chave com o prefixo errado lança um erro na construção em vez de dar 401 na primeira chamada; a verificação é um prefixo e nada mais, pelo que uma chave bem formada que tenha sido revogada continua a falhar na rede.
Está preso ao servidor por uma verificação de paridade que lê o documento OpenAPI em cada build e falha se os dois divergirem: um método a apontar para uma operação que a especificação não tem, uma operação documentada sem método, uma lista de âmbitos que não corresponde à que a operação exige, um espaço de nomes com métodos e sem entrada na referência, ou um método que não envia o pedido que o seu próprio manifesto indica. Imprime o que provou, e hoje isso lê-se como 116 métodos do SDK a cobrir as 104 operações documentadas. Dois scripts geradores estão ao lado dele e recusam-se a emitir uma operação que esteja por classificar ou escrita com um travessão. É por isso que o cliente não é um invólucro escrito à posteriori. Não pode ficar uma versão atrás da API.
O que falta é a canalização de lançamento. O pacote está no npm, pelo que bun add @openemail/sdk funciona, mas não há fluxo de lançamento: publicar é uma execução manual do preflight, da build e de bun publish, o que significa que uma versão chega ao npm quando alguém se lembra e não quando a alteração entra. A API que usa por predefinição está ligada e a responder.
TypeScript é a única linguagem, e o documento OpenAPI é deliberadamente a resposta para as restantes, em vez de cinco clientes escritos à mão que ficam para trás a ritmos diferentes. Não há cliente Python, Go nem Ruby no repositório, e não haverá antes de o documento ser aquilo a partir do qual são gerados.