@xemahq/api-client-generator 0.4.3 → 0.5.0
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/dist/lib/generate-clients.d.ts.map +1 -1
- package/dist/lib/generate-clients.js +7 -0
- package/dist/lib/generate-clients.js.map +1 -1
- 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
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"generate-clients.d.ts","sourceRoot":"","sources":["../../src/lib/generate-clients.ts"],"names":[],"mappings":"AAKA,OAAO,EAAgB,KAAK,UAAU,EAAE,MAAM,yBAAyB,CAAC;
|
|
1
|
+
{"version":3,"file":"generate-clients.d.ts","sourceRoot":"","sources":["../../src/lib/generate-clients.ts"],"names":[],"mappings":"AAKA,OAAO,EAAgB,KAAK,UAAU,EAAE,MAAM,yBAAyB,CAAC;AA+MxE,wBAAsB,yBAAyB,CAC7C,UAAU,GAAE,MAAsB,GACjC,OAAO,CAAC,UAAU,EAAE,CAAC,CAqDvB;AAGD,wBAAgB,oBAAoB,IAAI,IAAI,CAO3C"}
|
|
@@ -34,6 +34,13 @@ function orvalConfigFor(specPath, clientSrc) {
|
|
|
34
34
|
schemas: `${clientSrc}/models`,
|
|
35
35
|
client: 'fetch',
|
|
36
36
|
override: {
|
|
37
|
+
header: (info) => [
|
|
38
|
+
'Generated by @xemahq/api-client-generator — do not edit manually.',
|
|
39
|
+
...(info.title === undefined ? [] : [info.title]),
|
|
40
|
+
...(info.version === undefined
|
|
41
|
+
? []
|
|
42
|
+
: [`OpenAPI spec version: ${info.version}`]),
|
|
43
|
+
],
|
|
37
44
|
fetch: { includeHttpResponseReturnType: false },
|
|
38
45
|
mutator: {
|
|
39
46
|
path: `${clientSrc}/custom-fetch.ts`,
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"generate-clients.js","sourceRoot":"","sources":["../../src/lib/generate-clients.ts"],"names":[],"mappings":";;
|
|
1
|
+
{"version":3,"file":"generate-clients.js","sourceRoot":"","sources":["../../src/lib/generate-clients.ts"],"names":[],"mappings":"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"}
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@xemahq/api-client-generator",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.5.0",
|
|
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
|
-
}
|