Znalostní báze

Typovaná SDK

Nejdřív TypeScript klient, pak zbytek.

Podrobnosti

Publikováno na npm a v provozu. @openemail/sdk je kompletní TypeScript klient bez závislostí, publikovaný jako ESM i CommonJS, s jednou metodou pro každou zdokumentovanou operaci, kterou API obsluhuje, plus dva neautentizované meta endpointy, které generátor klientů potřebuje, s klíčem čteným z OPENEMAIL_API_KEY, 30sekundovým časovým limitem na každý pokus, dvěma opakováními, přepsáním apiKey pro jednotlivé volání kvůli procesu obsluhujícímu více pracovních prostorů a s emails.iterate() pro stránkování seznamu bez psaní smyčky nad kurzorem. Běží na Node 18 a novějším, Workers, Deno, Bun i v prohlížeči. Klíč se špatným prefixem vyhodí chybu už při vytváření klienta, místo aby vrátil 401 při prvním volání; kontroluje se jen prefix a nic víc, takže správně utvořený klíč, který byl odvolán, stejně selže až na drátě.
U serveru ho drží kontrola parity, která při každém buildu čte dokument OpenAPI a selže, jakmile se oba rozejdou: metoda mířící na operaci, kterou specifikace nemá, zdokumentovaná operace bez metody, seznam oprávnění, který neodpovídá tomu, co operace vyžaduje, jmenný prostor s metodami a bez záznamu v referenci, nebo metoda, která neodesílá požadavek uvedený v jejím vlastním manifestu. Vypíše, co dokázala, a dnes to zní 116 metod SDK pokrývajících všech 104 zdokumentovaných operací. Vedle ní stojí dva generátorové skripty, které odmítnou vypsat operaci, jež je nezařazená nebo napsaná s dlouhou pomlčkou. Proto klient není obal dopsaný dodatečně. Nemůže se za API opozdit o jedno vydání.
Chybí instalatérská práce kolem vydávání. Balíček je na npm, takže bun add @openemail/sdk funguje, ale neexistuje workflow pro vydání: publikování je ruční spuštění preflightu, buildu a bun publish, což znamená, že verze dorazí na npm, když si někdo vzpomene, ne když změna přistane. API, na které klient ve výchozím stavu míří, je zapnuté a odpovídá.
TypeScript je jediný jazyk a dokument OpenAPI je pro zbytek záměrnou odpovědí namísto pěti ručně psaných klientů, kteří zaostávají každý jinou rychlostí. V repozitáři není žádný klient pro Python, Go ani Ruby a nebude, dokud právě ten dokument nebude tím, z čeho se generují.