Website ·
npm
# @xemahq/api-client-generator
> Central OpenAPI + Orval client generator for Xema services.
## Overview
The single, shared generator that produces typed API clients for every Xema
NestJS service. It extracts one OpenAPI document per API surface
(public / internal / operator) from decorator metadata, then generates one
Orval client package per non-empty surface, each sharing the owning service's
version. Provenance metadata is stamped deterministically into every generated
client's `package.json`. A route ships in a surface only when it — or its
controller — is explicitly classified; there is no heuristic inference.
## When to use it
- Use it to extract a service's OpenAPI document and generate its client
packages instead of maintaining per-service generator scripts.
- Reach for the `xema-openapi` and `xema-client-generate` bins to wire client
generation into a service's build.
## Installation
```bash
pnpm add -D @xemahq/api-client-generator
```
## Usage
```bash
# Extract one OpenAPI document per classified API surface:
xema-openapi
# Generate one Orval client package per non-empty surface:
xema-client-generate
```
### Version movement
Every surface client of a service lands on one derived version. When
regeneration changes the generated output, the version advances by a **bump
class** the generator works out from the published surface: an export removed is
a break, exports added only is additive, and bytes moving without any declaration
moving is a fix. On a `0.x` package the levels shift down by one, because `^0.9.6`
admits `>=0.9.6 <0.10.0` — a break has to move the minor to leave that range and
an addition is a patch because that is what stays inside it.
When the change cannot be classified — a retained export whose declaration
moved, where a request type and a response type have opposite variance — the run
**refuses** rather than guessing the smallest bump, and names what it could not
decide. State the class and re-run:
```bash
xema-client-generate --bump-class=minor
# or, for a whole-repo refresh that reaches each service through turbo:
XEMA_CLIENT_BUMP_CLASS=minor pnpm refresh
```
The flag wins over the environment variable. A stated class below one the
comparison proved is refused, not silently raised; a higher one is always
honoured. Decide it from the PUBLISHED tarball of the current version rather
than from the source tree.
## Peer requirements
- `@nestjs/common`, `@nestjs/core`, `@nestjs/swagger`, `@nestjs/testing` — the
service is bootstrapped to read its route metadata.
- `@xemahq/xema-decorators` — supplies the API-surface classification metadata.
- `orval` — drives client code generation.
- `reflect-metadata`, `ts-node`, `tsconfig-paths`, `typescript` — runtime and
TypeScript toolchain for extraction.
## License
Apache-2.0 © Xema — [xema.dev](https://xema.dev)