@xemahq/api-client-generator 0.4.3 → 0.4.4
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/package.json +3 -4
- package/src/bin/xema-client-generate.ts +0 -11
- package/src/bin/xema-openapi.ts +0 -51
- package/src/index.ts +0 -9
- package/src/lib/client-package.ts +0 -220
- package/src/lib/client-readme.ts +0 -124
- package/src/lib/custom-fetch-template.ts +0 -198
- package/src/lib/default-stubs.ts +0 -422
- package/src/lib/extract-openapi.ts +0 -240
- package/src/lib/generate-clients.ts +0 -240
- package/src/lib/overrides.ts +0 -81
- package/src/lib/repo-post-process.ts +0 -106
- package/src/lib/seed-openapi-env.ts +0 -136
- package/src/lib/service-config.ts +0 -170
- package/src/lib/service-nest.ts +0 -58
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@xemahq/api-client-generator",
|
|
3
|
-
"version": "0.4.
|
|
3
|
+
"version": "0.4.4",
|
|
4
4
|
"description": "Layer 1 — the single, central OpenAPI + ORVAL client generator for every Xema NestJS service. Replaces the per-service orval.config.ts / scripts/extract-openapi.ts / scripts/build-client-index.js trio with two bins (xema-openapi, xema-client-generate). Extracts one OpenAPI document per ApiSurface (public/internal/operator) using the @XemaApiSurface decorator metadata, generates one ORVAL client package per non-empty surface (all sharing the owning service's version), and stamps deterministic `xema` provenance metadata into each generated client package.json. No heuristics: a route ships in a surface only if it (or its controller) is explicitly classified.",
|
|
5
5
|
"keywords": [
|
|
6
6
|
"xema",
|
|
@@ -30,8 +30,7 @@
|
|
|
30
30
|
"xema-client-generate": "dist/bin/xema-client-generate.js"
|
|
31
31
|
},
|
|
32
32
|
"files": [
|
|
33
|
-
"dist"
|
|
34
|
-
"src"
|
|
33
|
+
"dist"
|
|
35
34
|
],
|
|
36
35
|
"peerDependencies": {
|
|
37
36
|
"@nestjs/common": "^10 || ^11",
|
|
@@ -63,7 +62,7 @@
|
|
|
63
62
|
"prettier": "3.6.2",
|
|
64
63
|
"reflect-metadata": "0.2.2",
|
|
65
64
|
"typescript": "5.9.3",
|
|
66
|
-
"@xemahq/xema-decorators": "0.5.
|
|
65
|
+
"@xemahq/xema-decorators": "0.5.4"
|
|
67
66
|
},
|
|
68
67
|
"exports": {
|
|
69
68
|
".": {
|
|
@@ -1,11 +0,0 @@
|
|
|
1
|
-
#!/usr/bin/env node
|
|
2
|
-
/**
|
|
3
|
-
* `xema-client-generate` — generate (and compile) one ORVAL client package per
|
|
4
|
-
* surface that has an `openapi.<surface>.json` spec in the current working
|
|
5
|
-
* directory. Run AFTER `xema-openapi`.
|
|
6
|
-
*
|
|
7
|
-
* Service package.json: `"client:generate": "xema-client-generate"`.
|
|
8
|
-
*/
|
|
9
|
-
import { runClientGenerateCli } from '../lib/generate-clients';
|
|
10
|
-
|
|
11
|
-
runClientGenerateCli();
|
package/src/bin/xema-openapi.ts
DELETED
|
@@ -1,51 +0,0 @@
|
|
|
1
|
-
#!/usr/bin/env node
|
|
2
|
-
/**
|
|
3
|
-
* `xema-openapi` — extract one OpenAPI document per ApiSurface from the NestJS
|
|
4
|
-
* service in the current working directory.
|
|
5
|
-
*
|
|
6
|
-
* Run from a service dir (where package.json carries `xema.api`). Self-registers
|
|
7
|
-
* ts-node + tsconfig-paths from the SERVICE's own toolchain so the service's TS
|
|
8
|
-
* `AppModule` compiles on import, then delegates to the generator.
|
|
9
|
-
*
|
|
10
|
-
* Service package.json: `"openapi": "NODE_PATH=node_modules xema-openapi"`.
|
|
11
|
-
*/
|
|
12
|
-
// `node:module` is a side-effect-free builtin, so a static import is
|
|
13
|
-
// equivalent to the `require()` this used to do (the file compiles to
|
|
14
|
-
// CommonJS) — and it drops an inline `import()` type annotation whose only
|
|
15
|
-
// job was to type that `require`. The DYNAMIC requires below are different:
|
|
16
|
-
// they resolve paths computed at runtime, after `ts-node.register()` has
|
|
17
|
-
// patched the require hook, and must stay `require()`.
|
|
18
|
-
import { Module } from 'node:module';
|
|
19
|
-
import { delimiter } from 'node:path';
|
|
20
|
-
|
|
21
|
-
function registerTsNode(cwd: string): void {
|
|
22
|
-
const tsNode = require.resolve('ts-node', { paths: [cwd] });
|
|
23
|
-
|
|
24
|
-
(require(tsNode) as { register: (o: unknown) => void }).register({
|
|
25
|
-
transpileOnly: true,
|
|
26
|
-
});
|
|
27
|
-
try {
|
|
28
|
-
const paths = require.resolve('tsconfig-paths/register', { paths: [cwd] });
|
|
29
|
-
require(paths);
|
|
30
|
-
} catch {
|
|
31
|
-
// tsconfig-paths is optional — services without path aliases don't need it.
|
|
32
|
-
}
|
|
33
|
-
}
|
|
34
|
-
|
|
35
|
-
function ensureNodePath(): void {
|
|
36
|
-
process.env.NODE_PATH = process.env.NODE_PATH
|
|
37
|
-
? `node_modules${delimiter}${process.env.NODE_PATH}`
|
|
38
|
-
: 'node_modules';
|
|
39
|
-
(Module as unknown as { _initPaths: () => void })._initPaths();
|
|
40
|
-
}
|
|
41
|
-
|
|
42
|
-
ensureNodePath();
|
|
43
|
-
registerTsNode(process.cwd());
|
|
44
|
-
|
|
45
|
-
// Require AFTER ts-node is registered so the service's TS modules compile.
|
|
46
|
-
|
|
47
|
-
const { runOpenApiCli } = require('../lib/extract-openapi') as {
|
|
48
|
-
runOpenApiCli: () => void;
|
|
49
|
-
};
|
|
50
|
-
|
|
51
|
-
runOpenApiCli();
|
package/src/index.ts
DELETED
|
@@ -1,9 +0,0 @@
|
|
|
1
|
-
// Public programmatic surface of the central API-client generator.
|
|
2
|
-
export * from './lib/service-config';
|
|
3
|
-
export * from './lib/overrides';
|
|
4
|
-
export * from './lib/seed-openapi-env';
|
|
5
|
-
export * from './lib/default-stubs';
|
|
6
|
-
export * from './lib/extract-openapi';
|
|
7
|
-
export * from './lib/repo-post-process';
|
|
8
|
-
export * from './lib/client-package';
|
|
9
|
-
export * from './lib/generate-clients';
|
|
@@ -1,220 +0,0 @@
|
|
|
1
|
-
import {
|
|
2
|
-
cpSync,
|
|
3
|
-
existsSync,
|
|
4
|
-
mkdirSync,
|
|
5
|
-
readFileSync,
|
|
6
|
-
writeFileSync,
|
|
7
|
-
} from 'node:fs';
|
|
8
|
-
import { join } from 'node:path';
|
|
9
|
-
|
|
10
|
-
import { ApiSurface } from '@xemahq/xema-decorators';
|
|
11
|
-
|
|
12
|
-
import { CANONICAL_CUSTOM_FETCH } from './custom-fetch-template';
|
|
13
|
-
import {
|
|
14
|
-
surfaceClientDir,
|
|
15
|
-
surfaceClientPackageName,
|
|
16
|
-
type ResolvedServiceContext,
|
|
17
|
-
} from './service-config';
|
|
18
|
-
|
|
19
|
-
/** The authoritative package→Xema mapping stamped into each generated client. */
|
|
20
|
-
export interface GeneratedClientXemaBlock {
|
|
21
|
-
readonly kind: 'api-client';
|
|
22
|
-
readonly surface: ApiSurface;
|
|
23
|
-
readonly service: string;
|
|
24
|
-
readonly biome: string;
|
|
25
|
-
readonly target: 'server';
|
|
26
|
-
readonly generator: string;
|
|
27
|
-
readonly source: string;
|
|
28
|
-
}
|
|
29
|
-
|
|
30
|
-
const CLIENT_TSCONFIG = {
|
|
31
|
-
compilerOptions: {
|
|
32
|
-
target: 'ES2022',
|
|
33
|
-
module: 'commonjs',
|
|
34
|
-
lib: ['ES2022', 'DOM'],
|
|
35
|
-
types: [],
|
|
36
|
-
strict: true,
|
|
37
|
-
esModuleInterop: true,
|
|
38
|
-
skipLibCheck: true,
|
|
39
|
-
declaration: true,
|
|
40
|
-
outDir: './dist',
|
|
41
|
-
rootDir: './src',
|
|
42
|
-
},
|
|
43
|
-
include: ['src/**/*.ts'],
|
|
44
|
-
};
|
|
45
|
-
|
|
46
|
-
function generatorTag(): string {
|
|
47
|
-
const pkg = require('../../package.json') as { version: string };
|
|
48
|
-
return `@xemahq/api-client-generator@${pkg.version}`;
|
|
49
|
-
}
|
|
50
|
-
|
|
51
|
-
function recordOrEmpty(value: unknown): Record<string, unknown> {
|
|
52
|
-
return value !== null && typeof value === 'object' && !Array.isArray(value)
|
|
53
|
-
? Object.fromEntries(Object.entries(value))
|
|
54
|
-
: {};
|
|
55
|
-
}
|
|
56
|
-
|
|
57
|
-
/** Parse a release semver core `x.y.z` (any prerelease/build suffix ignored). */
|
|
58
|
-
function parseVersionCore(v: string): [number, number, number] | null {
|
|
59
|
-
const m = /^(\d+)\.(\d+)\.(\d+)/.exec(v.trim());
|
|
60
|
-
return m ? [Number(m[1]), Number(m[2]), Number(m[3])] : null;
|
|
61
|
-
}
|
|
62
|
-
|
|
63
|
-
/**
|
|
64
|
-
* Resolve the client `version` MONOTONICALLY. A published client MUST NEVER be
|
|
65
|
-
* downgraded by regeneration: we keep whichever of the existing client version
|
|
66
|
-
* and the service version is greater. A forward bump happens only when the
|
|
67
|
-
* service version genuinely exceeds the client's (an intentional, monotonic
|
|
68
|
-
* move). If either version is unparseable, the existing version is kept — the
|
|
69
|
-
* fail-safe default is "never downgrade".
|
|
70
|
-
*
|
|
71
|
-
* A fresh client (no existing version) adopts the service version.
|
|
72
|
-
*/
|
|
73
|
-
export function resolveMonotonicVersion(
|
|
74
|
-
existing: unknown,
|
|
75
|
-
serviceVersion: string,
|
|
76
|
-
): string {
|
|
77
|
-
if (typeof existing !== 'string' || existing.trim() === '') {
|
|
78
|
-
return serviceVersion;
|
|
79
|
-
}
|
|
80
|
-
const e = parseVersionCore(existing);
|
|
81
|
-
const s = parseVersionCore(serviceVersion);
|
|
82
|
-
if (!e || !s) {
|
|
83
|
-
return existing;
|
|
84
|
-
}
|
|
85
|
-
const [eMaj, eMin, ePat] = e;
|
|
86
|
-
const [sMaj, sMin, sPat] = s;
|
|
87
|
-
if (sMaj !== eMaj) {
|
|
88
|
-
return sMaj > eMaj ? serviceVersion : existing;
|
|
89
|
-
}
|
|
90
|
-
if (sMin !== eMin) {
|
|
91
|
-
return sMin > eMin ? serviceVersion : existing;
|
|
92
|
-
}
|
|
93
|
-
if (sPat !== ePat) {
|
|
94
|
-
return sPat > ePat ? serviceVersion : existing;
|
|
95
|
-
}
|
|
96
|
-
return existing;
|
|
97
|
-
}
|
|
98
|
-
|
|
99
|
-
/**
|
|
100
|
-
* Ensure the surface client package exists and carries the canonical stable
|
|
101
|
-
* metadata + the authoritative `xema` provenance block. Preserves any
|
|
102
|
-
* pre-existing `dependencies`/`peerDependencies` on an existing client.
|
|
103
|
-
*
|
|
104
|
-
* Returns the absolute client `src` directory (orval's output target).
|
|
105
|
-
*/
|
|
106
|
-
export function ensureClientPackage(
|
|
107
|
-
ctx: ResolvedServiceContext,
|
|
108
|
-
surface: ApiSurface,
|
|
109
|
-
): { clientDir: string; clientSrc: string } {
|
|
110
|
-
const clientDir = surfaceClientDir(ctx, surface);
|
|
111
|
-
const clientSrc = join(clientDir, 'src');
|
|
112
|
-
mkdirSync(clientSrc, { recursive: true });
|
|
113
|
-
|
|
114
|
-
const packageName = surfaceClientPackageName(ctx.api.serviceId, surface);
|
|
115
|
-
const xema: GeneratedClientXemaBlock = {
|
|
116
|
-
kind: 'api-client',
|
|
117
|
-
surface,
|
|
118
|
-
service: ctx.api.serviceId,
|
|
119
|
-
biome: ctx.api.biomeId,
|
|
120
|
-
target: 'server',
|
|
121
|
-
generator: generatorTag(),
|
|
122
|
-
source: `openapi.${surface}.json`,
|
|
123
|
-
};
|
|
124
|
-
|
|
125
|
-
const pkgPath = join(clientDir, 'package.json');
|
|
126
|
-
const existing = existsSync(pkgPath)
|
|
127
|
-
? (JSON.parse(readFileSync(pkgPath, 'utf8')) as Record<string, unknown>)
|
|
128
|
-
: {};
|
|
129
|
-
const existingScripts = recordOrEmpty(existing.scripts);
|
|
130
|
-
const existingDevDeps = recordOrEmpty(existing.devDependencies);
|
|
131
|
-
const existingPublishConfig = recordOrEmpty(existing.publishConfig);
|
|
132
|
-
// Start from the existing (hand-maintained) package and override ONLY the
|
|
133
|
-
// fields the generator is explicitly responsible for. Every other field
|
|
134
|
-
// authored by hand — `dependencies` (e.g. zod), `peerDependencies`, extra
|
|
135
|
-
// scripts (`clean`/`typecheck`), extra devDependencies (`@types/node`),
|
|
136
|
-
// license/repository/exports/etc. — is preserved verbatim. Regeneration is
|
|
137
|
-
// metadata-stable: it never silently drops hand-maintained config and, per
|
|
138
|
-
// {@link resolveMonotonicVersion}, never downgrades the package version.
|
|
139
|
-
const pkg: Record<string, unknown> = {
|
|
140
|
-
...existing,
|
|
141
|
-
name: packageName,
|
|
142
|
-
version: resolveMonotonicVersion(existing.version, ctx.version),
|
|
143
|
-
main: './dist/index.js',
|
|
144
|
-
types: './dist/index.d.ts',
|
|
145
|
-
// Maps ship. They carry position data plus a path string — no source: no
|
|
146
|
-
// tsconfig here sets `inlineSources`, and `--enable-source-maps` resolves a
|
|
147
|
-
// frame to `src/foo.ts:42` from the map alone, without the file on disk.
|
|
148
|
-
// Excluding them, as this briefly did, removed working stack traces from
|
|
149
|
-
// every generated client to fix nothing.
|
|
150
|
-
files: ['dist'],
|
|
151
|
-
scripts: {
|
|
152
|
-
...existingScripts,
|
|
153
|
-
// Generator-owned: the client must build and build-before-publish.
|
|
154
|
-
build: 'tsc -p tsconfig.json',
|
|
155
|
-
prepublishOnly: 'npm run build',
|
|
156
|
-
},
|
|
157
|
-
// This block used to be replaced WHOLESALE, which silently dropped
|
|
158
|
-
// `access: "public"` from every client on every regeneration — contradicting
|
|
159
|
-
// the promise three lines above. npm refuses to publish a SCOPED package
|
|
160
|
-
// without it, so each regeneration quietly armed a publish failure, and the
|
|
161
|
-
// fix (re-adding `access`) had to be re-applied by hand every time.
|
|
162
|
-
//
|
|
163
|
-
// `access` defaults to `public` because every generated @xemahq client is a
|
|
164
|
-
// public package; a hand-authored override still wins. `registry` stays
|
|
165
|
-
// generator-owned.
|
|
166
|
-
publishConfig: {
|
|
167
|
-
access: 'public',
|
|
168
|
-
...existingPublishConfig,
|
|
169
|
-
registry: 'https://registry.npmjs.org/',
|
|
170
|
-
},
|
|
171
|
-
devDependencies: {
|
|
172
|
-
...existingDevDeps,
|
|
173
|
-
// Generator-owned: tsc is required to build the generated client.
|
|
174
|
-
typescript: 'catalog:',
|
|
175
|
-
},
|
|
176
|
-
// Generator-owned: the authoritative provenance block is always rewritten.
|
|
177
|
-
xema,
|
|
178
|
-
};
|
|
179
|
-
writeFileSync(pkgPath, `${JSON.stringify(pkg, null, 2)}\n`, 'utf8');
|
|
180
|
-
|
|
181
|
-
const tsconfigPath = join(clientDir, 'tsconfig.json');
|
|
182
|
-
if (!existsSync(tsconfigPath)) {
|
|
183
|
-
writeFileSync(
|
|
184
|
-
tsconfigPath,
|
|
185
|
-
`${JSON.stringify(CLIENT_TSCONFIG, null, 2)}\n`,
|
|
186
|
-
'utf8',
|
|
187
|
-
);
|
|
188
|
-
}
|
|
189
|
-
|
|
190
|
-
ensureCustomFetch(ctx, clientSrc);
|
|
191
|
-
|
|
192
|
-
return { clientDir, clientSrc };
|
|
193
|
-
}
|
|
194
|
-
|
|
195
|
-
/**
|
|
196
|
-
* custom-fetch.ts is hand-maintained runtime config, identical across all
|
|
197
|
-
* clients. For an existing client it is left untouched. For a freshly
|
|
198
|
-
* scaffolded surface client we copy the service's public-surface sibling's
|
|
199
|
-
* custom-fetch when present (the most authoritative local copy), else write
|
|
200
|
-
* the canonical embedded template.
|
|
201
|
-
*/
|
|
202
|
-
function ensureCustomFetch(
|
|
203
|
-
ctx: ResolvedServiceContext,
|
|
204
|
-
clientSrc: string,
|
|
205
|
-
): void {
|
|
206
|
-
const target = join(clientSrc, 'custom-fetch.ts');
|
|
207
|
-
if (existsSync(target)) {
|
|
208
|
-
return;
|
|
209
|
-
}
|
|
210
|
-
const publicSibling = join(
|
|
211
|
-
surfaceClientDir(ctx, ApiSurface.Public),
|
|
212
|
-
'src',
|
|
213
|
-
'custom-fetch.ts',
|
|
214
|
-
);
|
|
215
|
-
if (existsSync(publicSibling)) {
|
|
216
|
-
cpSync(publicSibling, target);
|
|
217
|
-
return;
|
|
218
|
-
}
|
|
219
|
-
writeFileSync(target, CANONICAL_CUSTOM_FETCH, 'utf8');
|
|
220
|
-
}
|
package/src/lib/client-readme.ts
DELETED
|
@@ -1,124 +0,0 @@
|
|
|
1
|
-
import { existsSync, readFileSync, writeFileSync } from 'node:fs';
|
|
2
|
-
import { join } from 'node:path';
|
|
3
|
-
|
|
4
|
-
import { ApiSurface } from '@xemahq/xema-decorators';
|
|
5
|
-
|
|
6
|
-
/**
|
|
7
|
-
* Generated API clients carry a README emitted from the canonical package-README
|
|
8
|
-
* template (see the `write-package-readme` skill). It is fully generator-owned —
|
|
9
|
-
* never hand-edit a generated client's README; change this emitter and
|
|
10
|
-
* regenerate. The content is derived ONLY from the client's own identity (name,
|
|
11
|
-
* the owning service's title, the repo license) so it never needs updating when
|
|
12
|
-
* other packages change.
|
|
13
|
-
*/
|
|
14
|
-
|
|
15
|
-
/** Teal accent — the banner taxonomy colour for a generated API client. */
|
|
16
|
-
const CLIENT_ACCENT = '#14B8A6';
|
|
17
|
-
|
|
18
|
-
function detectRepoSpdx(repoRoot: string): string {
|
|
19
|
-
const licensePath = join(repoRoot, 'LICENSE');
|
|
20
|
-
if (existsSync(licensePath)) {
|
|
21
|
-
const head = readFileSync(licensePath, 'utf8').slice(0, 200);
|
|
22
|
-
if (/Apache License/i.test(head)) {
|
|
23
|
-
return 'Apache-2.0';
|
|
24
|
-
}
|
|
25
|
-
if (/all rights reserved/i.test(head)) {
|
|
26
|
-
return 'Proprietary';
|
|
27
|
-
}
|
|
28
|
-
}
|
|
29
|
-
return 'Proprietary';
|
|
30
|
-
}
|
|
31
|
-
|
|
32
|
-
function banner(packageName: string, tagline: string): string {
|
|
33
|
-
return [
|
|
34
|
-
`<svg width="680" height="120" viewBox="0 0 680 120" fill="none" xmlns="http://www.w3.org/2000/svg" role="img" aria-label="${packageName}">`,
|
|
35
|
-
` <rect width="680" height="120" rx="14" fill="#0B1020"/>`,
|
|
36
|
-
` <g transform="translate(28,34)">`,
|
|
37
|
-
` <path d="M26 0 L52 15 L52 45 L26 60 L0 45 L0 15 Z" fill="${CLIENT_ACCENT}" opacity="0.18"/>`,
|
|
38
|
-
` <path d="M26 12 L41 21 L41 39 L26 48 L11 39 L11 21 Z" fill="${CLIENT_ACCENT}"/>`,
|
|
39
|
-
` </g>`,
|
|
40
|
-
` <text x="92" y="52" font-family="ui-monospace,SFMono-Regular,Menlo,monospace" font-size="22" fill="#F8FAFC" font-weight="700">${packageName}</text>`,
|
|
41
|
-
` <text x="92" y="80" font-family="ui-sans-serif,system-ui,sans-serif" font-size="15" fill="#94A3B8">${tagline}</text>`,
|
|
42
|
-
` <text x="652" y="105" text-anchor="end" font-family="ui-sans-serif,system-ui,sans-serif" font-size="12" fill="#475569">xema.dev</text>`,
|
|
43
|
-
`</svg>`,
|
|
44
|
-
].join('\n');
|
|
45
|
-
}
|
|
46
|
-
|
|
47
|
-
/**
|
|
48
|
-
* Write `README.md` for a generated client package. Returns nothing; always
|
|
49
|
-
* overwrites (the README is generator-owned).
|
|
50
|
-
*/
|
|
51
|
-
export function ensureClientReadme(params: {
|
|
52
|
-
clientDir: string;
|
|
53
|
-
packageName: string;
|
|
54
|
-
serviceTitle: string;
|
|
55
|
-
surface: ApiSurface;
|
|
56
|
-
repoRoot: string;
|
|
57
|
-
}): void {
|
|
58
|
-
const { clientDir, packageName, serviceTitle, surface, repoRoot } = params;
|
|
59
|
-
const enc = encodeURIComponent(packageName);
|
|
60
|
-
const spdx = detectRepoSpdx(repoRoot);
|
|
61
|
-
const surfaceWord = surface === ApiSurface.Public ? '' : `${surface} `;
|
|
62
|
-
const tagline = `Typed, generated ${surfaceWord}HTTP client for the ${serviceTitle}.`;
|
|
63
|
-
const licenseLine =
|
|
64
|
-
spdx === 'Apache-2.0'
|
|
65
|
-
? 'Apache-2.0 © Xema — [xema.dev](https://xema.dev)'
|
|
66
|
-
: 'Proprietary — © Xema. All rights reserved. — [xema.dev](https://xema.dev)';
|
|
67
|
-
|
|
68
|
-
const md = `<!-- Generated by @xemahq/api-client-generator. Do not edit by hand. -->
|
|
69
|
-
<p align="center">
|
|
70
|
-
${banner(packageName, tagline)}
|
|
71
|
-
</p>
|
|
72
|
-
|
|
73
|
-
<p align="center">
|
|
74
|
-
<a href="https://xema.dev">Website</a> ·
|
|
75
|
-
<a href="https://www.npmjs.com/package/${packageName}">npm</a>
|
|
76
|
-
</p>
|
|
77
|
-
|
|
78
|
-
<p align="center">
|
|
79
|
-
<img alt="npm" src="https://img.shields.io/npm/v/${enc}?color=2563eb&label=npm">
|
|
80
|
-
<img alt="license" src="https://img.shields.io/npm/l/${enc}?color=10b981">
|
|
81
|
-
<img alt="types" src="https://img.shields.io/npm/types/${enc}?color=3178c6">
|
|
82
|
-
</p>
|
|
83
|
-
|
|
84
|
-
# ${packageName}
|
|
85
|
-
|
|
86
|
-
> ${tagline}
|
|
87
|
-
|
|
88
|
-
## Overview
|
|
89
|
-
|
|
90
|
-
Auto-generated TypeScript client for the **${serviceTitle}**. It exports typed
|
|
91
|
-
request functions and response models that mirror the service's OpenAPI surface,
|
|
92
|
-
so callers get end-to-end type safety without hand-writing HTTP calls. This
|
|
93
|
-
package is produced by \`@xemahq/api-client-generator\` and regenerated whenever
|
|
94
|
-
the service's API changes — do not edit it by hand.
|
|
95
|
-
|
|
96
|
-
## When to use it
|
|
97
|
-
|
|
98
|
-
- Use it from any TypeScript service or app that calls the ${serviceTitle} over HTTP.
|
|
99
|
-
- You get compile-time types for every endpoint and payload; regenerate to pick
|
|
100
|
-
up API changes rather than editing the client.
|
|
101
|
-
|
|
102
|
-
## Installation
|
|
103
|
-
|
|
104
|
-
\`\`\`bash
|
|
105
|
-
pnpm add ${packageName}
|
|
106
|
-
\`\`\`
|
|
107
|
-
|
|
108
|
-
## Usage
|
|
109
|
-
|
|
110
|
-
\`\`\`ts
|
|
111
|
-
// Every endpoint function and response model is exported from the package root.
|
|
112
|
-
import * as client from '${packageName}';
|
|
113
|
-
\`\`\`
|
|
114
|
-
|
|
115
|
-
Call the typed endpoint functions; request and response shapes are fully typed
|
|
116
|
-
from the service's OpenAPI spec.
|
|
117
|
-
|
|
118
|
-
## License
|
|
119
|
-
|
|
120
|
-
${licenseLine}
|
|
121
|
-
`;
|
|
122
|
-
|
|
123
|
-
writeFileSync(join(clientDir, 'README.md'), md, 'utf8');
|
|
124
|
-
}
|
|
@@ -1,198 +0,0 @@
|
|
|
1
|
-
/**
|
|
2
|
-
* Canonical `custom-fetch.ts` body, identical to the hand-maintained mutator
|
|
3
|
-
* shipped in every existing client package. Used ONLY as the fallback when a
|
|
4
|
-
* freshly scaffolded surface client has no public-surface sibling to copy from
|
|
5
|
-
* (a pure-internal/operator service). Kept byte-identical to the committed
|
|
6
|
-
* version so all clients share one fetch implementation.
|
|
7
|
-
*/
|
|
8
|
-
export const CANONICAL_CUSTOM_FETCH = `/**
|
|
9
|
-
* Configurable fetch wrapper for Orval-generated clients.
|
|
10
|
-
*
|
|
11
|
-
* Consumers must call \`configureClient()\` before using any endpoint function.
|
|
12
|
-
* The baseUrl is prepended to the relative paths generated by Orval.
|
|
13
|
-
*/
|
|
14
|
-
|
|
15
|
-
export interface ClientConfig {
|
|
16
|
-
/** Static base URL (e.g. 'http://localhost:3140') — no trailing slash. */
|
|
17
|
-
baseUrl?: string;
|
|
18
|
-
/** Per-request base-URL resolver (service-registry-safe). */
|
|
19
|
-
baseUrlResolver?: () => string | Promise<string>;
|
|
20
|
-
/** Optional async callback to get an auth token. */
|
|
21
|
-
getAuthToken?: () => Promise<string>;
|
|
22
|
-
/** Optional callback returning headers to inject on every request. */
|
|
23
|
-
getHeaders?: () => Record<string, string> | Promise<Record<string, string>>;
|
|
24
|
-
/** Optional callback invoked on 401 before a single retry. */
|
|
25
|
-
onUnauthorized?: () => Promise<void>;
|
|
26
|
-
/** Maximum retry attempts for transient failures (default: 3). */
|
|
27
|
-
maxRetries?: number;
|
|
28
|
-
}
|
|
29
|
-
|
|
30
|
-
export class ClientError extends Error {
|
|
31
|
-
constructor(
|
|
32
|
-
public readonly status: number,
|
|
33
|
-
public readonly url: string,
|
|
34
|
-
public readonly body: unknown,
|
|
35
|
-
) {
|
|
36
|
-
super(\`HTTP \${status} from \${url}\`);
|
|
37
|
-
this.name = 'ClientError';
|
|
38
|
-
}
|
|
39
|
-
}
|
|
40
|
-
|
|
41
|
-
let clientConfig: ClientConfig | null = null;
|
|
42
|
-
|
|
43
|
-
export function configureClient(config: ClientConfig): void {
|
|
44
|
-
clientConfig = config;
|
|
45
|
-
}
|
|
46
|
-
|
|
47
|
-
export function getClientConfig(): ClientConfig {
|
|
48
|
-
if (!clientConfig) {
|
|
49
|
-
throw new Error(
|
|
50
|
-
'Client not configured. Call configureClient({ baseUrl }) before using endpoint functions.',
|
|
51
|
-
);
|
|
52
|
-
}
|
|
53
|
-
return clientConfig;
|
|
54
|
-
}
|
|
55
|
-
|
|
56
|
-
const RETRYABLE_STATUSES = [429, 502, 503, 504];
|
|
57
|
-
|
|
58
|
-
async function buildHeaders(
|
|
59
|
-
config: ClientConfig,
|
|
60
|
-
callerHeaders: RequestInit['headers'],
|
|
61
|
-
): Promise<Headers> {
|
|
62
|
-
const headers = new Headers(callerHeaders);
|
|
63
|
-
if (config.getHeaders) {
|
|
64
|
-
const globalHeaders = await Promise.resolve(config.getHeaders());
|
|
65
|
-
for (const [key, value] of Object.entries(globalHeaders)) {
|
|
66
|
-
if (!headers.has(key)) {
|
|
67
|
-
headers.set(key, value);
|
|
68
|
-
}
|
|
69
|
-
}
|
|
70
|
-
}
|
|
71
|
-
if (config.getAuthToken && !headers.has('Authorization')) {
|
|
72
|
-
const token = await config.getAuthToken();
|
|
73
|
-
headers.set('Authorization', \`Bearer \${token}\`);
|
|
74
|
-
}
|
|
75
|
-
return headers;
|
|
76
|
-
}
|
|
77
|
-
|
|
78
|
-
export const customFetch = async <T>(
|
|
79
|
-
url: string,
|
|
80
|
-
options: RequestInit,
|
|
81
|
-
): Promise<T> => {
|
|
82
|
-
const config = getClientConfig();
|
|
83
|
-
const base = config.baseUrlResolver
|
|
84
|
-
? await config.baseUrlResolver()
|
|
85
|
-
: config.baseUrl;
|
|
86
|
-
if (base === undefined) {
|
|
87
|
-
throw new Error(
|
|
88
|
-
'Client not configured: set baseUrl or baseUrlResolver via configureClient().',
|
|
89
|
-
);
|
|
90
|
-
}
|
|
91
|
-
const fullUrl = \`\${base}\${url}\`;
|
|
92
|
-
const maxRetries = config.maxRetries ?? 3;
|
|
93
|
-
|
|
94
|
-
const headers = await buildHeaders(config, options.headers);
|
|
95
|
-
const requestInit: RequestInit = { ...options, headers };
|
|
96
|
-
|
|
97
|
-
let delay = 1000;
|
|
98
|
-
let lastError: Error | undefined;
|
|
99
|
-
|
|
100
|
-
for (let attempt = 0; attempt <= maxRetries; attempt++) {
|
|
101
|
-
try {
|
|
102
|
-
const response = await fetch(fullUrl, requestInit);
|
|
103
|
-
|
|
104
|
-
if (response.status === 401 && config.onUnauthorized && attempt === 0) {
|
|
105
|
-
await config.onUnauthorized();
|
|
106
|
-
const refreshedHeaders = await buildHeaders(config, options.headers);
|
|
107
|
-
const retryResponse = await fetch(fullUrl, { ...options, headers: refreshedHeaders });
|
|
108
|
-
const retryBody = await parseBody(retryResponse);
|
|
109
|
-
if (retryResponse.status >= 400) {
|
|
110
|
-
throw new ClientError(retryResponse.status, fullUrl, retryBody);
|
|
111
|
-
}
|
|
112
|
-
return retryBody as T;
|
|
113
|
-
}
|
|
114
|
-
|
|
115
|
-
if (!RETRYABLE_STATUSES.includes(response.status) || attempt >= maxRetries) {
|
|
116
|
-
const body = await parseBody(response);
|
|
117
|
-
if (response.status >= 400) {
|
|
118
|
-
throw new ClientError(response.status, fullUrl, body);
|
|
119
|
-
}
|
|
120
|
-
return body as T;
|
|
121
|
-
}
|
|
122
|
-
|
|
123
|
-
const retryAfter = parseRetryAfter(response.headers.get('Retry-After'));
|
|
124
|
-
const waitMs = retryAfter ?? addJitter(delay);
|
|
125
|
-
await sleep(waitMs);
|
|
126
|
-
delay = Math.min(delay * 2, 30_000);
|
|
127
|
-
} catch (error) {
|
|
128
|
-
if (error instanceof ClientError) throw error;
|
|
129
|
-
lastError = error instanceof Error ? error : new Error(String(error));
|
|
130
|
-
if (attempt >= maxRetries) throw lastError;
|
|
131
|
-
const waitMs = addJitter(delay);
|
|
132
|
-
await sleep(waitMs);
|
|
133
|
-
delay = Math.min(delay * 2, 30_000);
|
|
134
|
-
}
|
|
135
|
-
}
|
|
136
|
-
|
|
137
|
-
throw lastError ?? new Error(\`All retries exhausted for \${fullUrl}\`);
|
|
138
|
-
};
|
|
139
|
-
|
|
140
|
-
/*
|
|
141
|
-
* THE TRANSPORT RETURNS THE BODY UNCHANGED. Do not reintroduce an unwrap here.
|
|
142
|
-
*
|
|
143
|
-
* Xema services wrap every 2xx payload in a { data: T } envelope via the global
|
|
144
|
-
* ResponseEnvelopeInterceptor (platform-common), and the generator now emits
|
|
145
|
-
* types that describe THAT ENVELOPE — every endpoint returns
|
|
146
|
-
* Promise<XDataEnvelope> or Promise<XPaginatedEnvelope>, never a bare inner
|
|
147
|
-
* T. Consumers read the data property themselves.
|
|
148
|
-
*
|
|
149
|
-
* This template used to peel data, justified by a comment claiming generated
|
|
150
|
-
* types describe the inner T. That stopped being true when the generator moved
|
|
151
|
-
* to envelope-typed returns, and the comment outlived the fact — so the peel
|
|
152
|
-
* then contradicted every type in every package it seeded. Four clients shipped
|
|
153
|
-
* that way (resource-governance x3, workload-runtime-api): declared
|
|
154
|
-
* *DataEnvelope, returned the already-peeled inner object, so .data read
|
|
155
|
-
* undefined at runtime on every non-paginated endpoint. Paginated calls hid
|
|
156
|
-
* it, because the old peel deliberately preserved an envelope carrying
|
|
157
|
-
* pagination.
|
|
158
|
-
*
|
|
159
|
-
* ensureCustomFetch seeds this template into any client that lacks a
|
|
160
|
-
* transport, so a peel here is not one bug — it is re-imported into every new
|
|
161
|
-
* client generated from now on, which is exactly how those four were born after
|
|
162
|
-
* the hand-fix of their siblings.
|
|
163
|
-
*
|
|
164
|
-
* Enforced fleet-wide by check-client-transport-envelope in xema-base, which
|
|
165
|
-
* reads the RETURN SITES rather than banning a name — a rename, an inline
|
|
166
|
-
* .data, or ?? body.data all walk past a string ban.
|
|
167
|
-
*/
|
|
168
|
-
|
|
169
|
-
async function parseBody(response: Response): Promise<unknown> {
|
|
170
|
-
const contentType = response.headers.get('content-type');
|
|
171
|
-
if (contentType?.includes('application/json')) {
|
|
172
|
-
return response.json();
|
|
173
|
-
}
|
|
174
|
-
if (response.status === 204) {
|
|
175
|
-
return undefined;
|
|
176
|
-
}
|
|
177
|
-
return response.text();
|
|
178
|
-
}
|
|
179
|
-
|
|
180
|
-
function parseRetryAfter(value: string | null): number | undefined {
|
|
181
|
-
if (!value) return undefined;
|
|
182
|
-
const seconds = Number(value);
|
|
183
|
-
if (!isNaN(seconds) && seconds >= 0) return seconds * 1000;
|
|
184
|
-
const date = new Date(value);
|
|
185
|
-
if (!isNaN(date.getTime())) return Math.max(0, date.getTime() - Date.now());
|
|
186
|
-
return undefined;
|
|
187
|
-
}
|
|
188
|
-
|
|
189
|
-
function addJitter(delay: number): number {
|
|
190
|
-
return delay + (Math.random() * 2 - 1) * delay * 0.25;
|
|
191
|
-
}
|
|
192
|
-
|
|
193
|
-
function sleep(ms: number): Promise<void> {
|
|
194
|
-
return new Promise(resolve => setTimeout(resolve, ms));
|
|
195
|
-
}
|
|
196
|
-
|
|
197
|
-
export default customFetch;
|
|
198
|
-
`;
|