@redocly/client-generator 0.3.7 → 0.4.0

package/eject-assets/generators/typescript/client.ts

@@ -0,0 +1,254 @@
+// Ejected from @redocly/client-generator@0.4.0 — the built-in "typescript" generator.
+// This file is yours: edit freely; the generated client stays machine-owned and is
+// rebuilt by `redocly generate-client`. Newer generator versions merge in with
+// `redocly eject-generator typescript --update`.
+// Client assembly, shared by both output modes. The generated file embeds the
+// assembled runtime sources (./inline-runtime.ts). Single-file layout:
+// schema types → type guards → `<Op>*` aliases → Ops → OPERATIONS → embedded
+// runtime → (baked setup) → client instance → sugar — the embedded types are
+// already exported in place, so no re-exports. Split mode moves the schema types +
+// guards into a sibling `<stem>.schemas.ts` the entry re-exports (`emitClientSplit`).
+// Text templates throughout — no `typescript` at generate time.
+
+import {
+  allOperations,
+  type ApiModel,
+  type EmitOptions,
+  type OperationModel,
+} from '@redocly/client-generator';
+import { codeString } from '@redocly/client-generator/printers/typescript';
+
+import { banner, HEADER, renderTitleComment } from './banner.ts';
+import { packageIdents, renderDescriptors } from './descriptor.ts';
+import {
+  assembleInlineRuntime,
+  type InlineRuntimeNeeds,
+  runtimeModuleFiles,
+} from './inline-runtime.ts';
+import { isTypedMultipart } from './operation-types.ts';
+import {
+  collectEntrySchemaRefs,
+  type EmitContext,
+  renderAliases,
+  renderOpsType,
+} from './operations.ts';
+import { renderTypeGuards } from './type-guards.ts';
+import { renderTypeAliases } from './types.ts';
+
+export function emitClientSingleFile(model: ApiModel, options: EmitOptions = {}): string {
+  return emitClient(model, options).entry;
+}
+
+/** Which optional runtime capabilities this API needs (drives both distribution modes). */
+export function runtimeNeeds(model: ApiModel, options: EmitOptions): InlineRuntimeNeeds {
+  const ops = allOperations(model.services);
+  return {
+    multipart: ops.some((op) => op.requestBody && isTypedMultipart(op.requestBody)),
+    // Auth sugar needs schemes; `resolveAuth` fires when a descriptor carries
+    // `security` — a valid spec implies the former, but embed on either.
+    auth: model.securitySchemes.length > 0 || ops.some((op) => op.security.length > 0),
+    sse: ops.some((op) => op.sse !== undefined),
+    setup: !!options.setup,
+    paginate: (options.pagination ?? new Map()).size > 0,
+  };
+}
+
+/**
+ * `runtime: 'module'`: the runtime files written into `runtime/` beside the client —
+ * the raw per-needs modules plus the generated factory, each under the standard banner.
+ */
+export function emitRuntimeFiles(
+  model: ApiModel,
+  options: EmitOptions
+): Array<{ name: string; content: string }> {
+  if (options.runtime !== 'module') return [];
+  return runtimeModuleFiles(runtimeNeeds(model, options), options.importExt ?? 'js').map(
+    ({ name, content }) => ({ name, content: `${HEADER}\n\n${content.trim()}\n` })
+  );
+}
+
+/**
+ * The module-mode replacement for the embedded block: the entry imports what its own
+ * code references and re-exports the factory's public surface (the same names the
+ * inline embed leaves in module scope).
+ */
+function runtimeImports(options: EmitOptions, ctx: EmitContext, hasOps: boolean): string {
+  const ext = options.importExt ?? 'js';
+  const typeNames = [
+    'OperationDescriptor',
+    ...(options.setup ? ['ClientConfig', 'Middleware'] : []),
+    ...(ctx.errorMode === 'result' && hasOps ? ['Result'] : []),
+  ].sort();
+  return [
+    `import { createClient${options.setup ? ', mergeSetup' : ''} } from './runtime/factory.${ext}';`,
+    `import type { ${typeNames.join(', ')} } from './runtime/types.${ext}';`,
+    `export * from './runtime/factory.${ext}';`,
+  ].join('\n');
+}
+
+/**
+ * `split` mode: the same client with the schema types + type guards carved out into a
+ * sibling `<stem>.schemas.ts`. The entry file re-exports the schemas module
+ * (`export *`) and type-imports exactly the schema names its own code references, so
+ * both files hold under `noUnusedLocals`. `schemas` is absent when the document
+ * declares no schema statements (the entry is then self-contained).
+ */
+export function emitClientSplit(
+  model: ApiModel,
+  options: EmitOptions,
+  stem: string
+): { entry: string; schemas?: string } {
+  return emitClient(model, options, stem);
+}
+
+/** The shared assembly; `splitStem` (when given) selects the two-file split layout. */
+function emitClient(
+  model: ApiModel,
+  options: EmitOptions,
+  splitStem?: string
+): { entry: string; schemas?: string } {
+  const ops = allOperations(model.services);
+  const idents = packageIdents(model);
+  // Resolved (and VERIFIED) up front: an explicit rule that doesn't fit throws here,
+  // before any statement is built — one aggregated error for the whole model.
+  const pagination = options.pagination ?? new Map();
+  const ctx: EmitContext = {
+    argsStyle: options.argsStyle ?? 'grouped',
+    errorMode: options.errorMode ?? 'throw',
+    dateType: options.dateType ?? 'string',
+    schemaNames: new Set(model.schemas.map((s) => s.name)),
+    schemas: model.schemas,
+    pagination,
+  };
+  const wiring =
+    ops.length > 0
+      ? [
+          renderOpsType(model, idents, ctx),
+          renderDescriptors(model, idents, ctx.dateType, pagination, ctx.argsStyle),
+        ]
+      : // A spec with no operations still gets the uniform wiring shape.
+        [
+          'export type Ops = Record<string, never>;',
+          'export const OPERATIONS = {} as const satisfies Record<string, OperationDescriptor>;',
+        ];
+
+  const runtimeSection =
+    options.runtime === 'module'
+      ? runtimeImports(options, ctx, ops.length > 0)
+      : assembleInlineRuntime(runtimeNeeds(model, options));
+  const schemaSection = [
+    renderTypeAliases(model.schemas, ctx.dateType),
+    renderTypeGuards(model.schemas),
+  ]
+    .filter((section) => section.length > 0)
+    .join('\n\n');
+  const bodySection = [...ops.map((op) => renderAliases(op, ctx)), ...wiring]
+    .filter((section) => section.length > 0)
+    .join('\n\n');
+  const sugar = sugarSection(ops, idents);
+
+  // Layout puts the reader's OWN API first (types → aliases → Ops → OPERATIONS) and the
+  // machinery after it. The runtime block sits between the descriptors and the `client`
+  // initializer — after it for readability, before `client` so every declaration the
+  // module-init call chain touches (hoisted functions AND any future top-level const)
+  // is already evaluated.
+  const moduleMode = options.runtime === 'module';
+  if (splitStem === undefined) {
+    return {
+      entry: banner([
+        HEADER,
+        renderTitleComment(model),
+        ...(moduleMode ? [runtimeSection] : []),
+        [schemaSection, bodySection].filter((section) => section.length > 0).join('\n\n'),
+        ...(moduleMode ? [] : [runtimeSection]),
+        clientSection(options, ctx, model),
+        sugar,
+      ]),
+    };
+  }
+
+  const hasSchemas = schemaSection.length > 0;
+  return {
+    entry: banner([
+      HEADER,
+      renderTitleComment(model),
+      ...(moduleMode ? [runtimeSection] : []),
+      hasSchemas
+        ? schemaLinks(model, ctx, `./${splitStem}.schemas.${options.importExt ?? 'js'}`)
+        : '',
+      bodySection,
+      ...(moduleMode ? [] : [runtimeSection]),
+      clientSection(options, ctx, model),
+      sugar,
+    ]),
+    schemas: hasSchemas ? banner([HEADER, renderTitleComment(model), schemaSection]) : undefined,
+  };
+}
+
+/**
+ * The entry ⇄ schemas linkage of the split layout: a type-only import of exactly the
+ * schema names the entry's own code references (derived from the IR — the same
+ * sources the alias/Ops renderers type), plus the public `export *` re-export.
+ */
+function schemaLinks(model: ApiModel, ctx: EmitContext, specifier: string): string {
+  const names = collectEntrySchemaRefs(model, ctx);
+  const importLine =
+    names.length > 0 ? `import type { ${names.join(', ')} } from '${specifier}';\n` : '';
+  return `${importLine}export * from '${specifier}';`;
+}
+
+/** The (optional) baked setup + the default `client` instance. */
+function clientSection(options: EmitOptions, ctx: EmitContext, model: ApiModel): string {
+  const serverUrl = options.serverUrl ?? model.serverUrl;
+  const fields = [
+    // Always baked when the document declares one: the runtime's fallback is a
+    // relative URL, which Node's fetch rejects.
+    ...(serverUrl !== undefined ? [`serverUrl: ${codeString(serverUrl)}`] : []),
+    ...(ctx.errorMode === 'result' ? ['errorMode: "result"'] : []),
+    // The runtime converts a merged call to the namespaced shape, so it has to know
+    // which style this module's types promise.
+    ...(ctx.argsStyle === 'flat' ? ['argsStyle: "flat"'] : []),
+    // Client identification for API-owner telemetry; the runtime sends it only
+    // outside browsers, and `configure({ clientHeader: false })` disables it.
+    'clientHeader: "redocly-client-generator"',
+  ];
+  const config = fields.length > 0 ? `{ ${fields.join(', ')} }` : '{}';
+  // Precedence, lowest → highest: spec defaults → baked publisher setup → app `configure()`.
+  // The inner merge flattens the setup into a ClientConfig; the outer layers it OVER the
+  // spec defaults (mergeSetup's second argument wins per-field; middleware composes).
+  const configArg = options.setup
+    ? `mergeSetup({ config: ${config} }, mergeSetup(__redoclySetup, {}))`
+    : config;
+  // The trailing type args narrow `ctx.operation` to the spec's literal unions.
+  // `OperationTag` mirrors the descriptor block's gate: derived only when some
+  // operation is tagged (it would otherwise be `never`); zero-ops specs have no
+  // derived unions at all, so they keep the string defaults.
+  const ops = allOperations(model.services);
+  const hasTags = ops.some((op) => op.tags.length > 0);
+  const typeArgs =
+    ops.length > 0
+      ? `<Ops, OperationId, OperationPath, ${hasTags ? 'OperationTag' : 'string'}>`
+      : '<Ops>';
+  const client = `export const client = createClient${typeArgs}(OPERATIONS, ${configArg});`;
+  if (!options.setup) return client;
+  return (
+    '// ─── Baked-in setup (--setup) ───\n' +
+    `const __redoclySetup: { config?: ClientConfig; middleware?: Middleware[] } = ${options.setup};\n` +
+    client
+  );
+}
+
+/** Core destructure + per-scheme auth setters + per-operation call sugar. */
+function sugarSection(ops: OperationModel[], idents: Map<string, string>): string {
+  // Credentials go through `configure({ auth })` or `client.auth.*` — one way per act.
+  // Per-scheme setters used to be exported here too, which gave the same act three
+  // spellings and a name per scheme that operation names then had to avoid.
+  const lines = ['export const { configure, use } = client;'];
+  if (ops.length === 0) return lines.join('\n');
+  // Bindings, never wrappers: `updateOrder` IS `client.updateOrder`, so importing the name
+  // and reaching through the instance cannot disagree about the arguments. `argsStyle`
+  // shapes the method itself, which is why one binding serves both styles.
+  const names = ops.map((op) => idents.get(op.name)!).join(', ');
+  lines.push(`export const { ${names} } = client;`);
+  return lines.join('\n');
+}

package/eject-assets/generators/typescript/descriptor.ts

@@ -0,0 +1,137 @@
+// Ejected from @redocly/client-generator@0.4.0 — the built-in "typescript" generator.
+// This file is yours: edit freely; the generated client stays machine-owned and is
+// rebuilt by `redocly generate-client`. Newer generator versions merge in with
+// `redocly eject-generator typescript --update`.
+// Package-mode descriptor emission: the identifier plan for a generated module that
+// shares scope with the `@redocly/client-generator` wiring, plus the `OPERATIONS`
+// descriptor map (`satisfies Record<string, OperationDescriptor>` — the semver skew
+// guard against the runtime contract in src/runtime/types.ts). Text templates.
+
+import {
+  allOperations,
+  type ApiModel,
+  type ArgsStyle,
+  type DateType,
+  type ModelPagination,
+  type NamedSchemaModel,
+  type OperationModel,
+  securityRequirements,
+  type SecuritySchemeModel,
+  WIRING_NAMES,
+} from '@redocly/client-generator';
+import { codeLiteral, uniqueIdent } from '@redocly/client-generator/printers/typescript';
+
+import { isTypedMultipart } from './operation-types.ts';
+import { flatInputShape, responseText } from './operations.ts';
+import { responseHeaderSpecs } from './response-headers.ts';
+import { tsJsdoc } from './types.ts';
+
+/**
+ * Operation-name → emitted-identifier plan. The full reserved set (wiring + imported
+ * bindings, computed from the model FIRST) is seeded before any operation
+ * is sanitized, so collisions rename the operation (`configure` → `configure_2`)
+ * deterministically regardless of document order.
+ */
+export function packageIdents(model: ApiModel): Map<string, string> {
+  const used = new Set<string>(WIRING_NAMES);
+  const idents = new Map<string, string>();
+  for (const op of allOperations(model.services)) idents.set(op.name, uniqueIdent(op.name, used));
+  return idents;
+}
+
+/** One operation's OperationDescriptor as plain data (only non-default fields present). */
+function descriptorValue(
+  op: OperationModel,
+  schemes: SecuritySchemeModel[],
+  dateType: DateType,
+  pagination?: ModelPagination,
+  schemas: readonly NamedSchemaModel[] = [],
+  argsStyle: ArgsStyle = 'grouped'
+) {
+  const params = [...op.pathParams, ...op.queryParams, ...op.headerParams, ...op.cookieParams].map(
+    (p) => ({
+      name: p.name,
+      in: p.in,
+      ...(p.style !== undefined ? { style: p.style } : {}),
+      ...(p.explode !== undefined ? { explode: p.explode } : {}),
+      ...(p.allowReserved !== undefined ? { allowReserved: p.allowReserved } : {}),
+    })
+  );
+  const security = securityRequirements(op, { securitySchemes: schemes });
+  const sse = op.sse !== undefined;
+  const responseKind = sse ? 'sse' : responseText(op.successResponses, dateType).kind;
+  const responseHeaders = responseHeaderSpecs(op.successResponseHeaders, schemas);
+  return {
+    // The spec's operationId, NOT the (possibly renamed) map key: `id` drives middleware
+    // targeting (`ctx.operation.id`) and must match inline mode's `operationMetaExpr`.
+    // The wire/middleware identity stays the SPEC operationId even when the emitted
+    // function name was renamed away from a collision (`configure` → `configure_2`).
+    id: op.specName ?? op.name,
+    method: op.method.toUpperCase(),
+    path: op.path,
+    ...(op.tags.length > 0 ? { tags: op.tags } : {}),
+    ...(params.length > 0 ? { params } : {}),
+    ...(op.requestBody
+      ? {
+          body: {
+            contentType: op.requestBody.contentType,
+            ...(isTypedMultipart(op.requestBody) ? { multipart: true } : {}),
+          },
+        }
+      : {}),
+    ...(responseKind !== 'json' ? { responseKind } : {}),
+    ...(op.sse === undefined ? {} : { sseDataKind: op.sse.dataKind }),
+    ...(security.length > 0 ? { security } : {}),
+    ...(responseHeaders === undefined ? {} : { responseHeaders }),
+    // The resolved spec is already normalized with stable key order (see pagination.ts).
+    ...(pagination?.has(op.name) ? { pagination: pagination.get(op.name)!.spec } : {}),
+    // A merged call cannot carry one name for two layers, so an operation whose names
+    // collide keeps the namespaced shape — its `<Op>Variables` says so, and the runtime
+    // has to agree or the typed call would be rejected.
+    ...(argsStyle === 'flat' && 'collisions' in flatInputShape(op, schemas)
+      ? { argsStyle: 'grouped' }
+      : {}),
+  };
+}
+
+/** `export const OPERATIONS = {…} as const satisfies …` + the derived unions. */
+export function renderDescriptors(
+  model: ApiModel,
+  idents: Map<string, string>,
+  dateType: DateType,
+  pagination?: ModelPagination,
+  argsStyle: ArgsStyle = 'grouped'
+): string {
+  const ops = allOperations(model.services);
+  if (ops.length === 0) return '';
+  const entryLines = ops.map((op, index) => {
+    const value = codeLiteral(
+      descriptorValue(op, model.securitySchemes, dateType, pagination, model.schemas, argsStyle)
+    );
+    return `    ${idents.get(op.name)!}: ${value}${index === ops.length - 1 ? '' : ','}`;
+  });
+  const blocks = [
+    [
+      ...tsJsdoc(
+        'The wire-shape descriptor for every operation, keyed by operationId — the data the\n' +
+          'runtime routes requests by. Also minification-safe static metadata (method, path,\n' +
+          'tags) for cache keys, tracing span names, and request logging.',
+        undefined,
+        ''
+      ),
+      'export const OPERATIONS = {',
+      ...entryLines,
+      '} as const satisfies Record<string, OperationDescriptor>;',
+    ].join('\n'),
+    'export type OperationId = (typeof OPERATIONS)[keyof typeof OPERATIONS]["id"];',
+    'export type OperationPath = (typeof OPERATIONS)[keyof typeof OPERATIONS]["path"];',
+  ];
+  if (ops.some((op) => op.tags.length > 0)) {
+    blocks.push(
+      'export type OperationTag = Extract<(typeof OPERATIONS)[keyof typeof OPERATIONS], {\n' +
+        '    tags: readonly string[];\n' +
+        '}>["tags"][number];'
+    );
+  }
+  return blocks.join('\n\n');
+}

package/eject-assets/generators/typescript/index.ts

@@ -0,0 +1,101 @@
+// Ejected from @redocly/client-generator@0.4.0 — the built-in "typescript" generator.
+// This file is yours: edit freely; the generated client stays machine-owned and is
+// rebuilt by `redocly generate-client`. Newer generator versions merge in with
+// `redocly eject-generator typescript --update`.
+import {
+  type CodeSample,
+  type Generator,
+  type OperationModel,
+  renderReferencePage,
+  type SampleContext,
+} from '@redocly/client-generator';
+import { join } from 'node:path';
+
+import { emitClientSingleFile, emitClientSplit, emitRuntimeFiles } from './client.ts';
+import { packageIdents } from './descriptor.ts';
+
+/**
+ * The default generator: the full typed client (model types + runtime + endpoints).
+ * Other generators (zod, framework hooks) emit *additional* files alongside.
+ *
+ * `single` mode writes the whole client to the `--output` path. `split` mode derives
+ * two sibling files from that anchor — `<stem>.schemas.ts` (model types, enums,
+ * const-objects, type guards; skipped when the document declares no schemas) and
+ * `<stem>.ts` (everything else, which `export *`s the schemas module).
+ */
+export const typescriptGenerator: Generator = ({ model, output, outputMode, emit }) => {
+  // `runtime: 'module'` adds the per-needs runtime files beside the client.
+  const runtime = emitRuntimeFiles(model, emit).map(({ name, content }) => ({
+    path: join(output.dir, 'runtime', name),
+    content,
+  }));
+  if (outputMode === 'split') {
+    const { dir, stem } = output;
+    const { entry, schemas } = emitClientSplit(model, emit, stem);
+    return [
+      ...(schemas === undefined
+        ? []
+        : [{ path: join(dir, `${stem}.schemas.ts`), content: schemas }]),
+      { path: output.path, content: entry },
+      ...runtime,
+    ];
+  }
+  return [{ path: output.path, content: emitClientSingleFile(model, emit) }, ...runtime];
+};
+
+/**
+ * The client's own reference page, written when `client.docs` is on. Its snippets come from
+ * `typescriptSample` below, so the page shows the calling convention this run generated —
+ * `argsStyle` included.
+ */
+export const typescriptDocs: Generator = ({ model, output, emit, pagination }) => [
+  {
+    path: output.path.replace(/\.[^.\\/]+$/, '.typescript.md'),
+    content: renderReferencePage(model, {
+      title: `${model.title} TypeScript client reference`,
+      frontmatter: emit.docsFrontmatter === true,
+      language: {
+        name: 'typescript',
+        label: 'TypeScript',
+        fence: 'typescript',
+        requires: 'The client has no dependencies.',
+      },
+      sample: (op) => typescriptSample(op, { model, emit, outputPath: output.path }),
+      paginated: new Set(pagination?.keys() ?? []),
+    }),
+  },
+];
+
+/** One idiomatic TS call per operation, for `x-codeSamples` and the SDK reference pages. */
+export function typescriptSample(op: OperationModel, ctx: SampleContext): CodeSample {
+  const ident = packageIdents(ctx.model).get(op.name) ?? op.name;
+  // The module this run writes, with the run's import extension — `./client` would be
+  // both the wrong name for most stems and extensionless under ESM resolution.
+  const stem = ctx.outputPath.replace(/^.*[\\/]/, '').replace(/\.[^.]+$/, '');
+  const specifier = `./${stem}.${ctx.emit.importExt ?? 'js'}`;
+  const requiredQuery = op.queryParams.filter((param) => param.required);
+  const merged = ctx.emit.argsStyle === 'flat';
+  const path = op.pathParams.map((param) => `${param.name}: '<${param.name}>'`);
+  const query = requiredQuery.map((param) => `${param.name}: /* … */`);
+  const parts = merged
+    ? [...path, ...query, ...(op.requestBody ? ['/* body properties */'] : [])]
+    : [
+        ...(path.length > 0 ? [`path: { ${path.join(', ')} }`] : []),
+        ...(query.length > 0 ? [`query: { ${query.join(', ')} }`] : []),
+        ...(op.requestBody ? ['body: { /* … */ }'] : []),
+      ];
+  const args = parts.length > 0 ? [`{ ${parts.join(', ')} }`] : [];
+  return {
+    lang: 'typescript',
+    label: 'TypeScript SDK',
+    source: `import { ${ident} } from '${specifier}';\n\nconst result = await ${ident}(${args.join(', ')});\n`,
+  };
+}
+
+export default {
+  name: 'typescript',
+  run: typescriptGenerator,
+  sample: typescriptSample,
+  docs: typescriptDocs,
+  requiresGenerator: '^0.4.0',
+};

package/eject-assets/generators/typescript/inline-runtime.ts

@@ -0,0 +1,135 @@
+// Ejected from @redocly/client-generator@0.4.0 — the built-in "typescript" generator.
+// This file is yours: edit freely; the generated client stays machine-owned and is
+// rebuilt by `redocly generate-client`. Newer generator versions merge in with
+// `redocly eject-generator typescript --update`.
+// Assembles the embedded runtime block for inline-mode clients: the real
+// `src/runtime/` sources — stripped of module syntax at PREPARE time (see
+// scripts/generate-runtime-sources.mjs, which owns the kept-export surface) — in
+// import-graph order, followed by a local `createClient` factory wiring only the
+// capabilities this API needs. Pure string concatenation: no `typescript` at
+// generate time.
+
+import {
+  RUNTIME_SOURCES,
+  RUNTIME_SOURCES_STRIPPED,
+  type RuntimeModuleName,
+} from '@redocly/client-generator/runtime-sources';
+
+/** Which optional runtime capabilities the generated client must embed. */
+export type InlineRuntimeNeeds = {
+  multipart: boolean;
+  auth: boolean;
+  sse: boolean;
+  setup: boolean;
+  paginate: boolean;
+};
+
+const HEADER =
+  "// ─── Embedded runtime (@redocly/client-generator, assembled per this API's needs) ───";
+
+/** The per-needs module set, in import-graph topological order (both modes share it). */
+function runtimeModules(needs: InlineRuntimeNeeds): RuntimeModuleName[] {
+  // The optional capability modules slot in where the runtime barrel would import
+  // them (core never imports them statically).
+  const modules: RuntimeModuleName[] = ['types.ts', 'errors.ts', 'url.ts', 'parse.ts', 'retry.ts'];
+  if (needs.multipart) modules.push('multipart.ts');
+  if (needs.auth) modules.push('auth.ts');
+  if (needs.setup) modules.push('setup.ts');
+  // paginate.ts has only type imports (types.ts + create-client.ts's OperationArgs),
+  // so it can sit anywhere; keep it with the other capability modules, before send.ts.
+  if (needs.paginate) modules.push('paginate.ts');
+  modules.push('send.ts');
+  if (needs.sse) modules.push('sse.ts');
+  modules.push('create-client.ts');
+  return modules;
+}
+
+/** The embedded runtime source block: stripped modules in dependency order + the factory. */
+export function assembleInlineRuntime(needs: InlineRuntimeNeeds): string {
+  return [
+    HEADER,
+    ...runtimeModules(needs).map((name) => RUNTIME_SOURCES_STRIPPED[name]),
+    clientFactory(needs),
+  ].join('\n\n');
+}
+
+/**
+ * The runtime as real files (`runtime: 'module'`): the same per-needs modules, RAW —
+ * imports intact, exactly as authored — plus `factory.ts`, the per-needs `createClient`
+ * wiring as a module importing what it references from its siblings. `importExt`
+ * rewrites the intra-runtime specifiers for consumers that resolve them literally.
+ */
+export function runtimeModuleFiles(
+  needs: InlineRuntimeNeeds,
+  importExt: 'js' | 'ts' = 'js'
+): Array<{ name: string; content: string }> {
+  const files = [
+    ...runtimeModules(needs).map((name) => ({ name, content: RUNTIME_SOURCES[name] })),
+    { name: 'factory.ts', content: moduleFactory(needs) },
+  ];
+  if (importExt === 'js') return files;
+  return files.map(({ name, content }) => ({
+    name,
+    content: content.replace(/(from '\.\/[a-z-]+)\.js'/g, "$1.ts'"),
+  }));
+}
+
+/** `factory.ts`: the sibling-module equivalent of the inline factory block. */
+function moduleFactory(needs: InlineRuntimeNeeds): string {
+  const imports = [
+    "import { createClientCore } from './create-client.js';",
+    ...(needs.multipart ? ["import { toFormData } from './multipart.js';"] : []),
+    ...(needs.auth ? ["import { resolveAuth } from './auth.js';"] : []),
+    ...(needs.paginate
+      ? ["import { items, itemsByLink, pages, pagesByLink } from './paginate.js';"]
+      : []),
+    ...(needs.sse ? ["import { sse } from './sse.js';"] : []),
+    `import type {
+  Client,
+  ClientConfig,
+  OperationContext,
+  OperationDescriptor,
+  OpsShape,
+} from './types.js';`,
+  ];
+  // The client entry re-exports this module, so the factory carries the same public
+  // surface the inline embed leaves in module scope (the kept-export set).
+  const reexports = [
+    "export { ApiError, TimeoutError } from './errors.js';",
+    "export { defaultRetryOn } from './retry.js';",
+    ...(needs.setup ? ["export { mergeSetup } from './setup.js';"] : []),
+    "export type * from './types.js';",
+  ];
+  return [imports.join('\n'), clientFactory(needs), reexports.join('\n')].join('\n\n');
+}
+
+// The embedded equivalent of the package barrel's `createClient`: `createClientCore`
+// with only the included capabilities wired. EXPORTED — the design spec promises the
+// generated module re-exports `createClient`/`OPERATIONS`/`Ops` so apps can build
+// additional per-tenant instances over the same descriptors.
+function clientFactory(needs: InlineRuntimeNeeds): string {
+  const caps = [
+    ...(needs.multipart ? ['serializeMultipart: toFormData'] : []),
+    ...(needs.auth ? ['resolveAuth'] : []),
+    ...(needs.sse ? ['sse'] : []),
+    ...(needs.paginate ? ['paginate: { pages, items, pagesByLink, itemsByLink }'] : []),
+  ];
+  const wired = caps.length > 0 ? `{ ${caps.join(', ')} }` : '{}';
+  return `/**
+ * The client factory: \`createClientCore\` wired with the capabilities this API needs.
+ * Exported so apps can build additional instances (per-tenant, per-environment) over
+ * the same \`OPERATIONS\`/\`Ops\`. The trailing string params carry the wiring's literal
+ * unions (\`OperationId\`/\`OperationPath\`/\`OperationTag\`) into \`ctx.operation\`.
+ */
+export function createClient<
+  Ops extends OpsShape,
+  Id extends string = string,
+  Path extends string = string,
+  Tag extends string = string,
+>(
+  operations: Record<string, OperationDescriptor>,
+  config?: ClientConfig<OperationContext<Id, Path, Tag>>
+): Client<Ops, OperationContext<Id, Path, Tag>> {
+  return createClientCore<Ops, Id, Path, Tag>(operations, config, ${wired});
+}`;
+}