Prototype OpenAPI proxify

[mmkal]

Summary

Adds an experimental openapiProxify runtime helper that turns an already-loaded OpenAPI 3.x JSON document into the existing noRPC router shape, so createCli can expose OpenAPI operations as fetch-backed CLI commands without codegen or new runtime dependencies.

The prototype supports operation naming from operationId, path/query/header parameters, static or dynamic request headers, JSON request bodies, JSON/text response parsing, and useful non-2xx errors via OpenApiProxifyHttpError.

Usage

import {createCli, openapiProxify} from 'trpc-cli'
import {petstoreOpenApi} from './petstore-openapi.ts'

const router = openapiProxify({
  document: petstoreOpenApi,
  baseUrl: 'https://api.example.com/v1',
  headers: {authorization: `Bearer ${process.env.API_TOKEN}`},
})

await createCli({router, name: 'petstore'}).run()

// operationId: getPet
// petstore get-pet --pet-id fluffy --include toys owner --x-client-id cli

// operationId: createPet
// petstore create-pet --body '{"name":"Nori","age":4}'

OpenAPI Helper Tradeoffs

I kept this dependency-free for the prototype. Current primary-source checks on 2026-05-05:

• openapi-fetch@0.17.0 is still the most attractive small fetch runtime, but the official docs position its core value around generated paths types from openapi-typescript; it is not a runtime OpenAPI document parser. The docs describe it as a 6 kB, near-zero-runtime fetch client, with native fetch, generated paths, Node >=18 support, and path/query/body serializer hooks.
• @hey-api/openapi-ts@0.97.1 is a broader codegen system. Its docs describe production TypeScript output, Fetch/Axios/etc. clients, plugins, and Node.js 22+ support. npm view confirms engines.node: >=22.13.0, which does not fit this package's Node >=18 target as a required dependency.
• npm view openapi-fetch@0.17.0 ... confirmed MIT license, one runtime dependency (openapi-typescript-helpers), and ~229 kB unpacked size. npm view @hey-api/openapi-ts@0.97.1 ... confirmed MIT license, Node >=22.13.0, multiple codegen dependencies, and ~2.6 MB unpacked size.

Sources:

• https://openapi-ts.dev/openapi-fetch/
• https://openapi-ts.dev/openapi-fetch/api
• https://heyapi.dev/openapi-ts/get-started
• https://www.npmjs.com/package/openapi-fetch/v/0.17.0
• https://www.npmjs.com/package/@hey-api/openapi-ts/v/0.97.1

Tests

• pnpm exec vitest run test/openapi-proxify.test.ts
• pnpm compile
• pnpm lint
• pnpm test

Limitations

• Accepts already-loaded OpenAPI 3.x JSON objects only; YAML loading, remote URL loading, and remote refs are caller-owned.
• Resolves local #/... refs only.
• Supports path, query, and header parameters plus application/json request bodies. Cookies, multipart, form-urlencoded, and non-JSON request bodies are out of scope.
• Query arrays serialize as repeated keys. Object-valued query/header params and the full OpenAPI style/explode matrix are not implemented.
• No response validation and no full OpenAPI schema semantics such as discriminators.
• This should stay experimental until the API shape and parameter/body mapping are reviewed against real specs.

[pkg-pr-new]

Open in StackBlitz

npm i https://pkg.pr.new/mmkal/trpc-cli@200

commit: 6dc615b