@xemahq/api-client-generator 0.2.0 → 0.3.0

package/src/bin/xema-client-generate.ts

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+/**
+ * `xema-client-generate` — generate (and compile) one ORVAL client package per
+ * surface that has an `openapi.<surface>.json` spec in the current working
+ * directory. Run AFTER `xema-openapi`.
+ *
+ * Service package.json: `"client:generate": "xema-client-generate"`.
+ */
+import { runClientGenerateCli } from '../lib/generate-clients';
+
+runClientGenerateCli();

package/src/bin/xema-openapi.ts

@@ -0,0 +1,51 @@
+#!/usr/bin/env node
+/**
+ * `xema-openapi` — extract one OpenAPI document per ApiSurface from the NestJS
+ * service in the current working directory.
+ *
+ * Run from a service dir (where package.json carries `xema.api`). Self-registers
+ * ts-node + tsconfig-paths from the SERVICE's own toolchain so the service's TS
+ * `AppModule` compiles on import, then delegates to the generator.
+ *
+ * Service package.json: `"openapi": "NODE_PATH=node_modules xema-openapi"`.
+ */
+// `node:module` is a side-effect-free builtin, so a static import is
+// equivalent to the `require()` this used to do (the file compiles to
+// CommonJS) — and it drops an inline `import()` type annotation whose only
+// job was to type that `require`. The DYNAMIC requires below are different:
+// they resolve paths computed at runtime, after `ts-node.register()` has
+// patched the require hook, and must stay `require()`.
+import { Module } from 'node:module';
+import { delimiter } from 'node:path';
+
+function registerTsNode(cwd: string): void {
+  const tsNode = require.resolve('ts-node', { paths: [cwd] });
+
+  (require(tsNode) as { register: (o: unknown) => void }).register({
+    transpileOnly: true,
+  });
+  try {
+    const paths = require.resolve('tsconfig-paths/register', { paths: [cwd] });
+    require(paths);
+  } catch {
+    // tsconfig-paths is optional — services without path aliases don't need it.
+  }
+}
+
+function ensureNodePath(): void {
+  process.env.NODE_PATH = process.env.NODE_PATH
+    ? `node_modules${delimiter}${process.env.NODE_PATH}`
+    : 'node_modules';
+  (Module as unknown as { _initPaths: () => void })._initPaths();
+}
+
+ensureNodePath();
+registerTsNode(process.cwd());
+
+// Require AFTER ts-node is registered so the service's TS modules compile.
+
+const { runOpenApiCli } = require('../lib/extract-openapi') as {
+  runOpenApiCli: () => void;
+};
+
+runOpenApiCli();

package/src/index.ts

@@ -0,0 +1,9 @@
+// Public programmatic surface of the central API-client generator.
+export * from './lib/service-config';
+export * from './lib/overrides';
+export * from './lib/seed-openapi-env';
+export * from './lib/default-stubs';
+export * from './lib/extract-openapi';
+export * from './lib/repo-post-process';
+export * from './lib/client-package';
+export * from './lib/generate-clients';

package/src/lib/client-package.ts

@@ -0,0 +1,215 @@
+import {
+  cpSync,
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  writeFileSync,
+} from 'node:fs';
+import { join } from 'node:path';
+
+import { ApiSurface } from '@xemahq/xema-decorators';
+
+import { CANONICAL_CUSTOM_FETCH } from './custom-fetch-template';
+import {
+  surfaceClientDir,
+  surfaceClientPackageName,
+  type ResolvedServiceContext,
+} from './service-config';
+
+/** The authoritative package→Xema mapping stamped into each generated client. */
+export interface GeneratedClientXemaBlock {
+  readonly kind: 'api-client';
+  readonly surface: ApiSurface;
+  readonly service: string;
+  readonly biome: string;
+  readonly target: 'server';
+  readonly generator: string;
+  readonly source: string;
+}
+
+const CLIENT_TSCONFIG = {
+  compilerOptions: {
+    target: 'ES2022',
+    module: 'commonjs',
+    lib: ['ES2022', 'DOM'],
+    types: [],
+    strict: true,
+    esModuleInterop: true,
+    skipLibCheck: true,
+    declaration: true,
+    outDir: './dist',
+    rootDir: './src',
+  },
+  include: ['src/**/*.ts'],
+};
+
+function generatorTag(): string {
+  const pkg = require('../../package.json') as { version: string };
+  return `@xemahq/api-client-generator@${pkg.version}`;
+}
+
+function recordOrEmpty(value: unknown): Record<string, unknown> {
+  return value !== null && typeof value === 'object' && !Array.isArray(value)
+    ? Object.fromEntries(Object.entries(value))
+    : {};
+}
+
+/** Parse a release semver core `x.y.z` (any prerelease/build suffix ignored). */
+function parseVersionCore(v: string): [number, number, number] | null {
+  const m = /^(\d+)\.(\d+)\.(\d+)/.exec(v.trim());
+  return m ? [Number(m[1]), Number(m[2]), Number(m[3])] : null;
+}
+
+/**
+ * Resolve the client `version` MONOTONICALLY. A published client MUST NEVER be
+ * downgraded by regeneration: we keep whichever of the existing client version
+ * and the service version is greater. A forward bump happens only when the
+ * service version genuinely exceeds the client's (an intentional, monotonic
+ * move). If either version is unparseable, the existing version is kept — the
+ * fail-safe default is "never downgrade".
+ *
+ * A fresh client (no existing version) adopts the service version.
+ */
+export function resolveMonotonicVersion(
+  existing: unknown,
+  serviceVersion: string,
+): string {
+  if (typeof existing !== 'string' || existing.trim() === '') {
+    return serviceVersion;
+  }
+  const e = parseVersionCore(existing);
+  const s = parseVersionCore(serviceVersion);
+  if (!e || !s) {
+    return existing;
+  }
+  const [eMaj, eMin, ePat] = e;
+  const [sMaj, sMin, sPat] = s;
+  if (sMaj !== eMaj) {
+    return sMaj > eMaj ? serviceVersion : existing;
+  }
+  if (sMin !== eMin) {
+    return sMin > eMin ? serviceVersion : existing;
+  }
+  if (sPat !== ePat) {
+    return sPat > ePat ? serviceVersion : existing;
+  }
+  return existing;
+}
+
+/**
+ * Ensure the surface client package exists and carries the canonical stable
+ * metadata + the authoritative `xema` provenance block. Preserves any
+ * pre-existing `dependencies`/`peerDependencies` on an existing client.
+ *
+ * Returns the absolute client `src` directory (orval's output target).
+ */
+export function ensureClientPackage(
+  ctx: ResolvedServiceContext,
+  surface: ApiSurface,
+): { clientDir: string; clientSrc: string } {
+  const clientDir = surfaceClientDir(ctx, surface);
+  const clientSrc = join(clientDir, 'src');
+  mkdirSync(clientSrc, { recursive: true });
+
+  const packageName = surfaceClientPackageName(ctx.api.serviceId, surface);
+  const xema: GeneratedClientXemaBlock = {
+    kind: 'api-client',
+    surface,
+    service: ctx.api.serviceId,
+    biome: ctx.api.biomeId,
+    target: 'server',
+    generator: generatorTag(),
+    source: `openapi.${surface}.json`,
+  };
+
+  const pkgPath = join(clientDir, 'package.json');
+  const existing = existsSync(pkgPath)
+    ? (JSON.parse(readFileSync(pkgPath, 'utf8')) as Record<string, unknown>)
+    : {};
+  const existingScripts = recordOrEmpty(existing.scripts);
+  const existingDevDeps = recordOrEmpty(existing.devDependencies);
+  const existingPublishConfig = recordOrEmpty(existing.publishConfig);
+  // Start from the existing (hand-maintained) package and override ONLY the
+  // fields the generator is explicitly responsible for. Every other field
+  // authored by hand — `dependencies` (e.g. zod), `peerDependencies`, extra
+  // scripts (`clean`/`typecheck`), extra devDependencies (`@types/node`),
+  // license/repository/exports/etc. — is preserved verbatim. Regeneration is
+  // metadata-stable: it never silently drops hand-maintained config and, per
+  // {@link resolveMonotonicVersion}, never downgrades the package version.
+  const pkg: Record<string, unknown> = {
+    ...existing,
+    name: packageName,
+    version: resolveMonotonicVersion(existing.version, ctx.version),
+    main: './dist/index.js',
+    types: './dist/index.d.ts',
+    files: ['dist'],
+    scripts: {
+      ...existingScripts,
+      // Generator-owned: the client must build and build-before-publish.
+      build: 'tsc -p tsconfig.json',
+      prepublishOnly: 'npm run build',
+    },
+    // This block used to be replaced WHOLESALE, which silently dropped
+    // `access: "public"` from every client on every regeneration — contradicting
+    // the promise three lines above. npm refuses to publish a SCOPED package
+    // without it, so each regeneration quietly armed a publish failure, and the
+    // fix (re-adding `access`) had to be re-applied by hand every time.
+    //
+    // `access` defaults to `public` because every generated @xemahq client is a
+    // public package; a hand-authored override still wins. `registry` stays
+    // generator-owned.
+    publishConfig: {
+      access: 'public',
+      ...existingPublishConfig,
+      registry: 'https://registry.npmjs.org/',
+    },
+    devDependencies: {
+      ...existingDevDeps,
+      // Generator-owned: tsc is required to build the generated client.
+      typescript: 'catalog:',
+    },
+    // Generator-owned: the authoritative provenance block is always rewritten.
+    xema,
+  };
+  writeFileSync(pkgPath, `${JSON.stringify(pkg, null, 2)}\n`, 'utf8');
+
+  const tsconfigPath = join(clientDir, 'tsconfig.json');
+  if (!existsSync(tsconfigPath)) {
+    writeFileSync(
+      tsconfigPath,
+      `${JSON.stringify(CLIENT_TSCONFIG, null, 2)}\n`,
+      'utf8',
+    );
+  }
+
+  ensureCustomFetch(ctx, clientSrc);
+
+  return { clientDir, clientSrc };
+}
+
+/**
+ * custom-fetch.ts is hand-maintained runtime config, identical across all
+ * clients. For an existing client it is left untouched. For a freshly
+ * scaffolded surface client we copy the service's public-surface sibling's
+ * custom-fetch when present (the most authoritative local copy), else write
+ * the canonical embedded template.
+ */
+function ensureCustomFetch(
+  ctx: ResolvedServiceContext,
+  clientSrc: string,
+): void {
+  const target = join(clientSrc, 'custom-fetch.ts');
+  if (existsSync(target)) {
+    return;
+  }
+  const publicSibling = join(
+    surfaceClientDir(ctx, ApiSurface.Public),
+    'src',
+    'custom-fetch.ts',
+  );
+  if (existsSync(publicSibling)) {
+    cpSync(publicSibling, target);
+    return;
+  }
+  writeFileSync(target, CANONICAL_CUSTOM_FETCH, 'utf8');
+}

package/src/lib/client-readme.ts

@@ -0,0 +1,124 @@
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+import { ApiSurface } from '@xemahq/xema-decorators';
+
+/**
+ * Generated API clients carry a README emitted from the canonical package-README
+ * template (see the `write-package-readme` skill). It is fully generator-owned —
+ * never hand-edit a generated client's README; change this emitter and
+ * regenerate. The content is derived ONLY from the client's own identity (name,
+ * the owning service's title, the repo license) so it never needs updating when
+ * other packages change.
+ */
+
+/** Teal accent — the banner taxonomy colour for a generated API client. */
+const CLIENT_ACCENT = '#14B8A6';
+
+function detectRepoSpdx(repoRoot: string): string {
+  const licensePath = join(repoRoot, 'LICENSE');
+  if (existsSync(licensePath)) {
+    const head = readFileSync(licensePath, 'utf8').slice(0, 200);
+    if (/Apache License/i.test(head)) {
+      return 'Apache-2.0';
+    }
+    if (/all rights reserved/i.test(head)) {
+      return 'Proprietary';
+    }
+  }
+  return 'Proprietary';
+}
+
+function banner(packageName: string, tagline: string): string {
+  return [
+    `<svg width="680" height="120" viewBox="0 0 680 120" fill="none" xmlns="http://www.w3.org/2000/svg" role="img" aria-label="${packageName}">`,
+    `  <rect width="680" height="120" rx="14" fill="#0B1020"/>`,
+    `  <g transform="translate(28,34)">`,
+    `    <path d="M26 0 L52 15 L52 45 L26 60 L0 45 L0 15 Z" fill="${CLIENT_ACCENT}" opacity="0.18"/>`,
+    `    <path d="M26 12 L41 21 L41 39 L26 48 L11 39 L11 21 Z" fill="${CLIENT_ACCENT}"/>`,
+    `  </g>`,
+    `  <text x="92" y="52" font-family="ui-monospace,SFMono-Regular,Menlo,monospace" font-size="22" fill="#F8FAFC" font-weight="700">${packageName}</text>`,
+    `  <text x="92" y="80" font-family="ui-sans-serif,system-ui,sans-serif" font-size="15" fill="#94A3B8">${tagline}</text>`,
+    `  <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>`,
+    `</svg>`,
+  ].join('\n');
+}
+
+/**
+ * Write `README.md` for a generated client package. Returns nothing; always
+ * overwrites (the README is generator-owned).
+ */
+export function ensureClientReadme(params: {
+  clientDir: string;
+  packageName: string;
+  serviceTitle: string;
+  surface: ApiSurface;
+  repoRoot: string;
+}): void {
+  const { clientDir, packageName, serviceTitle, surface, repoRoot } = params;
+  const enc = encodeURIComponent(packageName);
+  const spdx = detectRepoSpdx(repoRoot);
+  const surfaceWord = surface === ApiSurface.Public ? '' : `${surface} `;
+  const tagline = `Typed, generated ${surfaceWord}HTTP client for the ${serviceTitle}.`;
+  const licenseLine =
+    spdx === 'Apache-2.0'
+      ? 'Apache-2.0 &copy; Xema — [xema.dev](https://xema.dev)'
+      : 'Proprietary — &copy; Xema. All rights reserved. — [xema.dev](https://xema.dev)';
+
+  const md = `<!-- Generated by @xemahq/api-client-generator. Do not edit by hand. -->
+<p align="center">
+${banner(packageName, tagline)}
+</p>
+
+<p align="center">
+  <a href="https://xema.dev">Website</a> &middot;
+  <a href="https://www.npmjs.com/package/${packageName}">npm</a>
+</p>
+
+<p align="center">
+  <img alt="npm" src="https://img.shields.io/npm/v/${enc}?color=2563eb&label=npm">
+  <img alt="license" src="https://img.shields.io/npm/l/${enc}?color=10b981">
+  <img alt="types" src="https://img.shields.io/npm/types/${enc}?color=3178c6">
+</p>
+
+# ${packageName}
+
+> ${tagline}
+
+## Overview
+
+Auto-generated TypeScript client for the **${serviceTitle}**. It exports typed
+request functions and response models that mirror the service's OpenAPI surface,
+so callers get end-to-end type safety without hand-writing HTTP calls. This
+package is produced by \`@xemahq/api-client-generator\` and regenerated whenever
+the service's API changes — do not edit it by hand.
+
+## When to use it
+
+- Use it from any TypeScript service or app that calls the ${serviceTitle} over HTTP.
+- You get compile-time types for every endpoint and payload; regenerate to pick
+  up API changes rather than editing the client.
+
+## Installation
+
+\`\`\`bash
+pnpm add ${packageName}
+\`\`\`
+
+## Usage
+
+\`\`\`ts
+// Every endpoint function and response model is exported from the package root.
+import * as client from '${packageName}';
+\`\`\`
+
+Call the typed endpoint functions; request and response shapes are fully typed
+from the service's OpenAPI spec.
+
+## License
+
+${licenseLine}
+`;
+
+  writeFileSync(join(clientDir, 'README.md'), md, 'utf8');
+}

package/src/lib/custom-fetch-template.ts

@@ -0,0 +1,200 @@
+/**
+ * Canonical `custom-fetch.ts` body, identical to the hand-maintained mutator
+ * shipped in every existing client package. Used ONLY as the fallback when a
+ * freshly scaffolded surface client has no public-surface sibling to copy from
+ * (a pure-internal/operator service). Kept byte-identical to the committed
+ * version so all clients share one fetch implementation.
+ */
+export const CANONICAL_CUSTOM_FETCH = `/**
+ * Configurable fetch wrapper for Orval-generated clients.
+ *
+ * Consumers must call \`configureClient()\` before using any endpoint function.
+ * The baseUrl is prepended to the relative paths generated by Orval.
+ */
+
+export interface ClientConfig {
+  /** Static base URL (e.g. 'http://localhost:3140') — no trailing slash. */
+  baseUrl?: string;
+  /** Per-request base-URL resolver (service-registry-safe). */
+  baseUrlResolver?: () => string | Promise<string>;
+  /** Optional async callback to get an auth token. */
+  getAuthToken?: () => Promise<string>;
+  /** Optional callback returning headers to inject on every request. */
+  getHeaders?: () => Record<string, string> | Promise<Record<string, string>>;
+  /** Optional callback invoked on 401 before a single retry. */
+  onUnauthorized?: () => Promise<void>;
+  /** Maximum retry attempts for transient failures (default: 3). */
+  maxRetries?: number;
+}
+
+export class ClientError extends Error {
+  constructor(
+    public readonly status: number,
+    public readonly url: string,
+    public readonly body: unknown,
+  ) {
+    super(\`HTTP \${status} from \${url}\`);
+    this.name = 'ClientError';
+  }
+}
+
+let clientConfig: ClientConfig | null = null;
+
+export function configureClient(config: ClientConfig): void {
+  clientConfig = config;
+}
+
+export function getClientConfig(): ClientConfig {
+  if (!clientConfig) {
+    throw new Error(
+      'Client not configured. Call configureClient({ baseUrl }) before using endpoint functions.',
+    );
+  }
+  return clientConfig;
+}
+
+const RETRYABLE_STATUSES = [429, 502, 503, 504];
+
+async function buildHeaders(
+  config: ClientConfig,
+  callerHeaders: RequestInit['headers'],
+): Promise<Headers> {
+  const headers = new Headers(callerHeaders);
+  if (config.getHeaders) {
+    const globalHeaders = await Promise.resolve(config.getHeaders());
+    for (const [key, value] of Object.entries(globalHeaders)) {
+      if (!headers.has(key)) {
+        headers.set(key, value);
+      }
+    }
+  }
+  if (config.getAuthToken && !headers.has('Authorization')) {
+    const token = await config.getAuthToken();
+    headers.set('Authorization', \`Bearer \${token}\`);
+  }
+  return headers;
+}
+
+export const customFetch = async <T>(
+  url: string,
+  options: RequestInit,
+): Promise<T> => {
+  const config = getClientConfig();
+  const base = config.baseUrlResolver
+    ? await config.baseUrlResolver()
+    : config.baseUrl;
+  if (base === undefined) {
+    throw new Error(
+      'Client not configured: set baseUrl or baseUrlResolver via configureClient().',
+    );
+  }
+  const fullUrl = \`\${base}\${url}\`;
+  const maxRetries = config.maxRetries ?? 3;
+
+  const headers = await buildHeaders(config, options.headers);
+  const requestInit: RequestInit = { ...options, headers };
+
+  let delay = 1000;
+  let lastError: Error | undefined;
+
+  for (let attempt = 0; attempt <= maxRetries; attempt++) {
+    try {
+      const response = await fetch(fullUrl, requestInit);
+
+      if (response.status === 401 && config.onUnauthorized && attempt === 0) {
+        await config.onUnauthorized();
+        const refreshedHeaders = await buildHeaders(config, options.headers);
+        const retryResponse = await fetch(fullUrl, { ...options, headers: refreshedHeaders });
+        const retryBody = await parseBody(retryResponse);
+        if (retryResponse.status >= 400) {
+          throw new ClientError(retryResponse.status, fullUrl, retryBody);
+        }
+        return unwrapEnvelope(retryBody) as T;
+      }
+
+      if (!RETRYABLE_STATUSES.includes(response.status) || attempt >= maxRetries) {
+        const body = await parseBody(response);
+        if (response.status >= 400) {
+          throw new ClientError(response.status, fullUrl, body);
+        }
+        return unwrapEnvelope(body) as T;
+      }
+
+      const retryAfter = parseRetryAfter(response.headers.get('Retry-After'));
+      const waitMs = retryAfter ?? addJitter(delay);
+      await sleep(waitMs);
+      delay = Math.min(delay * 2, 30_000);
+    } catch (error) {
+      if (error instanceof ClientError) throw error;
+      lastError = error instanceof Error ? error : new Error(String(error));
+      if (attempt >= maxRetries) throw lastError;
+      const waitMs = addJitter(delay);
+      await sleep(waitMs);
+      delay = Math.min(delay * 2, 30_000);
+    }
+  }
+
+  throw lastError ?? new Error(\`All retries exhausted for \${fullUrl}\`);
+};
+
+/**
+ * Xema platform services wrap every 2xx payload in a { data: T } envelope via
+ * the global ResponseEnvelopeInterceptor (platform-common). Generated types
+ * describe the INNER T (controllers declare their return type as T, not
+ * { data: T }), so the client must peel data to keep the static types and the
+ * wire shape consistent — otherwise consumers read fields off the envelope and
+ * get undefined.
+ *
+ * Only 2xx bodies reach this helper: non-2xx responses are surfaced as a thrown
+ * ClientError before unwrap, and error envelopes are emitted by the
+ * GlobalExceptionFilter, never wrapped in { data }. Paginated lists arrive as
+ * { data: T[], pagination: {...} }; consumers read both fields, so that envelope
+ * is kept intact (detected by the presence of pagination). Any body without a
+ * top-level data field is returned as-is.
+ */
+function unwrapEnvelope(body: unknown): unknown {
+  if (
+    body === null ||
+    typeof body !== 'object' ||
+    Array.isArray(body) ||
+    !('data' in body)
+  ) {
+    return body;
+  }
+  const envelope = body as { data: unknown; pagination?: unknown };
+  if ('pagination' in envelope) {
+    return envelope;
+  }
+  return envelope.data;
+}
+
+async function parseBody(response: Response): Promise<unknown> {
+  const contentType = response.headers.get('content-type');
+  if (contentType?.includes('application/json')) {
+    return response.json();
+  }
+  if (response.status === 204) {
+    return undefined;
+  }
+  return response.text();
+}
+
+function parseRetryAfter(value: string | null): number | undefined {
+  if (!value) return undefined;
+  const seconds = Number(value);
+  if (!isNaN(seconds) && seconds >= 0) return seconds * 1000;
+  const date = new Date(value);
+  if (!isNaN(date.getTime())) return Math.max(0, date.getTime() - Date.now());
+  return undefined;
+}
+
+function addJitter(delay: number): number {
+  return delay + (Math.random() * 2 - 1) * delay * 0.25;
+}
+
+function sleep(ms: number): Promise<void> {
+  return new Promise(resolve => setTimeout(resolve, ms));
+}
+
+export default customFetch;
+`;