@xemahq/api-client-generator

Central OpenAPI + Orval client generator for Xema services.

Overview

Generates typed API clients for NestJS services. It extracts one OpenAPI document per API surface (public, internal, operator) from decorator metadata, then generates one Orval client package per non-empty surface, all sharing one derived version. A route ships in a surface only when it, or its controller, is explicitly classified.

When to use it

• Use it to generate a service's client packages instead of maintaining per-service generator scripts.

Installation

pnpm add -D @xemahq/api-client-generator

Usage

xema-openapi            # one OpenAPI document per classified API surface
xema-client-generate    # one Orval client package per non-empty surface

When regeneration changes the output, the client version advances by a class the generator derives from the published surface (break, additive, fix). If it cannot classify a change it refuses and names what it could not decide; state the class and re-run:

xema-client-generate --bump-class=minor
# or: XEMA_CLIENT_BUMP_CLASS=minor (the flag wins)

A turbo task that runs the generator must pass XEMA_CLIENT_BUMP_CLASS through (passThroughEnv or env).

Configuration

Clients in a customer-owned repository are configured in the client block of tooling/ci/release.config.mjs:

| Option | Meaning | | --- | --- | | client.packageScope | Scope for client names (@acme), or "" for unscoped names. Required outside first-party Xema repositories. | | client.private | true for workspace-only clients: no banner, publish config or changeset. | | client.license | SPDX or reserved licence stated in the generated README. | | client.copyrightHolder | Legal owner stated in the generated README; there is no default. |

Repository layout

• Repository root: the nearest ancestor that is a git checkout (holds .git). A git archive export or tarball tree is not supported.
• Package manager: the root package.json#packageManager (pnpm or npm), else the single lockfile present; a repository that says neither, or holds both lockfiles, is refused. It decides how the client compiles (pnpm exec tsc / npx --no-install tsc), the README install line, and the client's typescript devDependency: catalog: under pnpm, and under npm the range in the repository's own root package.json (refused when absent).
• Changesets: a repository without .changeset/ versions its packages by its own flow, so the generator records no changeset there (it still never writes a version).

Peer requirements

@nestjs/common, @nestjs/core, @nestjs/swagger, @nestjs/testing, @xemahq/xema-decorators, orval, reflect-metadata, ts-node, tsconfig-paths, typescript.

License

Apache-2.0 © Xema — xema.dev