Currently, our OpenAPI client is used everywhere. It's "the way™️" to access our API in all of our JavaScript Node.js projects. Like build, CLI, etc...

Sadly the client we expose don't have any types as it's a JavaScript class that generates the functions on the fly based on the @netlify/open-api package which is the swagger.json we are generating.

Thorough that we don't have any type safety when working with this package.

As a lot of types in the CLI and the build are based on the return types of the API methods we end up not having a proper type safety throughout the whole codebase which puts of in a brittle position when working with any all the time. To fix our upstream types in the CLI or the build it is required to get proper types from the API return methods.

Proposal

To fix our types we should autogenerate the functions on build time before releasing the package. This means we should generate all the JS methods as static functions in code as generating them on the fly in a constructor call. This is not only speeding up the API access (as we don't have to generate all the functions during runtime), furthermore, it helps us troubleshoot issues as we have an actual code generated we can inspect. When generating the code we can generate typescript with proper types by leveraging the typescript AST.

This should ultimately help us work with our API by having types available and should enable customers the same if they want to use the API inside build plugins where currently no documentation is available.