Proposed Auto-generated types library for fal-ai/client

[tombeckenham]

This PR provides a new way of generating types for @fal-ai/client by providing an independent @fal-ai/types library that is auto-generated from live Fal OpenAPI specs. Add a FAL_KEY to .env.local then:

npm run update-types

I researched type safety extensively on the Fal client while building the TanStack AI adapter for Fal. When the TanStack team built the adapters for other providers, they found it was nearly impossible to have a single endpoint type that covered all models for all content types. See their blog post on why they split the adapters.

Likewise in Fal client, having a single EndpointTypeMap for every single model, has already hit the limit of what's possible.

I ran an experiment to see if it was possible to do the same by category of output. I forked the fal-js client library, and created a types library that uses HeyApi to generate types & schemas by category. HeyApi is brilliant for this, and is well maintained.

I found it was possible to generate the EndpointTypeMaps per category by combining OpenAPI specs downloaded from Fal. This gives us an InputType and OutputType by category. I then found it was possible to provide a single InputType and OutputType using long conditionals like this:

export type InputType<T extends EndpointType> = T extends Gen3dModel
  ? Gen3dModelInput<T>
  : T extends AudioModel
    ? AudioModelInput<T>
    : T extends ImageModel
      ? ImageModelInput<T>
      : T extends JsonModel
        ? JsonModelInput<T>
        : T extends LlmModel
          ? LlmModelInput<T>
          : T extends SpeechModel
            ? SpeechModelInput<T>
            : T extends TextModel
              ? TextModelInput<T>
              : T extends TrainingModel
                ? TrainingModelInput<T>
                : T extends UnknownModel
                  ? UnknownModelInput<T>
                  : T extends VideoModel
                    ? VideoModelInput<T>
                    : T extends VisionModel
                      ? VisionModelInput<T>
                      : never;

Key files:

• scripts/fetch-openapi-models.ts - uses a FAL_KEY to download the OpenAPI spec for every model then combine by category into a hidden json folder
• openapi-ts.config.ts - HeyApi config that transforms (corrects) and merges OpenAPI specs - then generates types and zod schemas from those specs. Note, it could generate json schemas as well, but you can generate them from the zod
• scripts/generate-endpoint-maps.ts - Generates the endpoint type maps and discriminatedUnion zod schemas for each category then creates a combined index for the conditional EndpointType

Closes #184
Closes #195

[mrlubos]

@tombeckenham wow what a massive pull request. Let me know if you need anything from @hey-api!