@contractkit/plugin-typescript 0.28.2 → 0.30.0

package/dist/ts-render.d.ts

@@ -1,5 +1,7 @@
 import type { ContractTypeNode } from '@contractkit/core';
+/** Declaration emitted into generated files that reference the `json` scalar. */
 export declare const JSON_VALUE_TYPE_DECL = "export type JsonValue = string | number | boolean | null | JsonValue[] | { [key: string]: JsonValue };";
+/** Quote a property name unless it is already a valid bare TypeScript identifier. */
 export declare function quoteKey(name: string): string;
 /** Escape text for safe inclusion inside a JSDoc block comment: neutralize the
  *  block-comment terminator sequence and split embedded newlines into separate
@@ -9,18 +11,34 @@ export declare function escapeJsDocLines(text: string): string[];
 export declare function escapeSingleQuoted(s: string): string;
 /** Convert an HTTP header name (e.g. `preference-applied`, `X-Request-ID`, `ETag`) to camelCase for use as a JS property. */
 export declare function headerNameToProperty(name: string): string;
-export declare function renderTsType(type: ContractTypeNode): string;
+/**
+ * Which runtime the emitted types describe. A few scalars have no single correct TypeScript
+ * type: `binary` is a `Blob` in a fetch-based client but a `Buffer` on a Node server. Everything
+ * else renders identically for both targets. Defaults to `'client'`.
+ */
+export type TsRenderTarget = 'client' | 'server';
+/**
+ * Render a contract type as a plain TypeScript type expression. Model refs render as their bare
+ * name; use `renderInputTsType` / `renderOutputTsType` to substitute Input/Output variants.
+ *
+ * @param target Runtime the type describes; only `binary` differs (`Buffer` vs `Blob`).
+ */
+export declare function renderTsType(type: ContractTypeNode, target?: TsRenderTarget): string;
 /**
  * Like renderTsType, but substitutes model refs with their Input variant
  * when the model has visibility modifiers. Used for request-side types
  * (body, params, query, headers).
+ *
+ * @param target Runtime the type describes; only `binary` differs (`Buffer` vs `Blob`).
  */
-export declare function renderInputTsType(type: ContractTypeNode, modelsWithInput?: Set<string>): string;
+export declare function renderInputTsType(type: ContractTypeNode, modelsWithInput?: Set<string>, target?: TsRenderTarget): string;
 /**
  * Like renderTsType, but substitutes model refs with their Output variant
  * (post-transform wire shape) when the model has format(output=...) or
  * transitively references one. Used for response-side types in routers
  * and SDK return types.
+ *
+ * @param target Runtime the type describes; only `binary` differs (`Buffer` vs `Blob`).
  */
-export declare function renderOutputTsType(type: ContractTypeNode, modelsWithOutput?: Set<string>): string;
+export declare function renderOutputTsType(type: ContractTypeNode, modelsWithOutput?: Set<string>, target?: TsRenderTarget): string;
 //# sourceMappingURL=ts-render.d.ts.map

package/dist/ts-render.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ts-render.d.ts","sourceRoot":"","sources":["../src/ts-render.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAA6B,MAAM,mBAAmB,CAAC;AAErF,eAAO,MAAM,oBAAoB,2GAA2G,CAAC;AAE7I,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAE7C;AAED;;sFAEsF;AACtF,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CAEvD;AAED,sFAAsF;AACtF,wBAAgB,kBAAkB,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAEpD;AAED,6HAA6H;AAC7H,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAQzD;AAID,wBAAgB,YAAY,CAAC,IAAI,EAAE,gBAAgB,GAAG,MAAM,CAoC3D;AA+CD;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,gBAAgB,EAAE,eAAe,CAAC,EAAE,GAAG,CAAC,MAAM,CAAC,GAAG,MAAM,CA2B/F;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,gBAAgB,EAAE,gBAAgB,CAAC,EAAE,GAAG,CAAC,MAAM,CAAC,GAAG,MAAM,CA2BjG"}
+{"version":3,"file":"ts-render.d.ts","sourceRoot":"","sources":["../src/ts-render.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAA6B,MAAM,mBAAmB,CAAC;AAErF,iFAAiF;AACjF,eAAO,MAAM,oBAAoB,2GAA2G,CAAC;AAE7I,qFAAqF;AACrF,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAE7C;AAED;;sFAEsF;AACtF,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CAEvD;AAED,sFAAsF;AACtF,wBAAgB,kBAAkB,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAEpD;AAED,6HAA6H;AAC7H,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAQzD;AAID;;;;GAIG;AACH,MAAM,MAAM,cAAc,GAAG,QAAQ,GAAG,QAAQ,CAAC;AAEjD;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,gBAAgB,EAAE,MAAM,GAAE,cAAyB,GAAG,MAAM,CAoC9F;AAgDD;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,gBAAgB,EAAE,eAAe,CAAC,EAAE,GAAG,CAAC,MAAM,CAAC,EAAE,MAAM,GAAE,cAAyB,GAAG,MAAM,CA2BlI;AAED;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,gBAAgB,EAAE,gBAAgB,CAAC,EAAE,GAAG,CAAC,MAAM,CAAC,EAAE,MAAM,GAAE,cAAyB,GAAG,MAAM,CA2BpI"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@contractkit/plugin-typescript",
-  "version": "0.28.2",
+  "version": "0.30.0",
   "description": "ContractKit built-in plugin: TypeScript codegen (SDK clients, Koa routers, Zod schemas, plain types)",
   "author": {
     "name": "Marooned Software",
@@ -26,7 +26,7 @@
     ".": "./dist/index.js"
   },
   "dependencies": {
-    "@contractkit/core": "0.23.0"
+    "@contractkit/core": "0.24.0"
   },
   "devDependencies": {
     "@repo/config-eslint": "0.3.1",

package/src/codegen-contract.ts

@@ -22,6 +22,7 @@ import {
     collectExternalOutputRefs as ckCollectExternalOutputRefs,
 } from '@contractkit/core';
 import { escapeJsDocLines } from './ts-render.js';
+import type { TsRenderTarget } from './ts-render.js';
 
 /**
  * Maps a ContractKit object mode to its Zod constructor name.
@@ -53,6 +54,12 @@ export interface ContractCodegenContext {
     modelsWithOutput?: Set<string>;
     /** If set, import JsonValue from this path instead of re-declaring it (avoids barrel re-export conflicts) */
     jsonValueImportPath?: string;
+    /**
+     * Runtime the emitted plain types describe. Only affects scalars whose TypeScript type differs
+     * per runtime (`binary` → `Buffer` on the server, `Blob` in the client). Ignored by
+     * `generateContract`, whose Zod schemas are server-shaped by construction. Default `'client'`.
+     */
+    target?: TsRenderTarget;
 }
 
 // ─── Public entry point ────────────────────────────────────────────────────

package/src/codegen-operation.ts

@@ -1,11 +1,10 @@
-import type { OpRootNode, OpRouteNode, OpOperationNode, ContractTypeNode, ParamSource, ObjectMode } from '@contractkit/core';
+import type { OpRootNode, OpRouteNode, OpOperationNode, ContractTypeNode, ScalarTypeNode, ParamSource, ObjectMode } from '@contractkit/core';
 import { resolveModifiers, resolveSecurity, SECURITY_NONE, classifyContentType } from '@contractkit/core';
 import {
     renderType,
     renderInputType,
     renderQueryType,
     pascalToDotCase,
-    typeNeedsDateTime,
     typeNeedsScalar,
     modeToWrapper,
 } from './codegen-contract.js';
@@ -126,44 +125,20 @@ export interface OpCodegenOptions {
     includeInternal?: boolean;
 }
 
-/** Generate a Koa router module for every operation in `root`, including the imports, type aliases, and handler list. */
+/**
+ * Generate a Koa router module for every operation in `root`, including the imports, type
+ * aliases, and handler list.
+ *
+ * Imports are derived from the generated body — each candidate symbol is emitted only if it
+ * actually appears in the output. Deciding them from predicates over the AST instead means any
+ * drift between predicate and codegen leaves an unused import in every generated file, which
+ * trips `noUnusedLocals` and lint downstream.
+ */
 export function generateOp(root: OpRootNode, options: OpCodegenOptions = {}): string {
     // Collect all referenced types across all routes
     const types = collectTypes(root, options.modelsWithInput, options.modelsWithOutput);
     const services = collectServices(root);
     const routerName = deriveRouterName(root.file);
-    const needsParseAndValidate = routeNeedsValidation(root);
-
-    // Generate the body first so we can detect whether `z.` is actually referenced
-    // before deciding whether to emit the zod import.
-    const body: string[] = [];
-    const needsSignature = fileNeedsSignature(root);
-    const needsPolicy = fileNeedsPolicy(root);
-    const koaImports = ['ServerKitRouter', 'bodyParserMiddleware'];
-    if (needsPolicy) koaImports.push('requirePolicy');
-    if (needsSignature) koaImports.push('requireSignature');
-    body.push(`import { ${koaImports.join(', ')} } from '@maroonedsoftware/koa';`);
-
-    for (const svc of services) {
-        const modulePath = root.services?.[svc] ?? root.meta[svc] ?? deriveModulePath(svc, options.servicePathTemplate);
-        body.push(`import { ${svc} } from '${modulePath}';`);
-    }
-
-    if (types.length > 0) {
-        body.push(...generateTypeImports(types, root.file, options));
-    }
-
-    if (opNeedsDateTime(root)) {
-        body.push(`import { DateTime } from 'luxon';`);
-    }
-
-    if (needsParseAndValidate) {
-        body.push(`import { parseAndValidate } from '@maroonedsoftware/zod';`);
-    }
-
-    if (fileUsesMultipart(root)) {
-        body.push(`import { MultipartBody } from '@maroonedsoftware/multipart';`);
-    }
 
     const helpers: string[] = [];
     if (opNeedsScalar(root, 'binary')) {
@@ -174,6 +149,11 @@ export function generateOp(root: OpRootNode, options: OpCodegenOptions = {}): st
             `const _ZodDatetime = z.preprocess((val) => typeof val === 'string' ? DateTime.fromISO(val) : val, z.custom<DateTime>((val) => val instanceof DateTime && val.isValid, { message: 'Must be in ISO 8601 format' }));`,
         );
     }
+    if (opNeedsScalar(root, 'interval')) {
+        helpers.push(
+            `const _ZodInterval = z.preprocess((val) => typeof val === 'string' ? Interval.fromISO(val) : val, z.custom<Interval>((val) => val instanceof Interval && val.isValid, { message: 'Must be an ISO 8601 interval' })).transform(val => val.toISO()!);`,
+        );
+    }
     if (opNeedsScalar(root, 'json')) {
         helpers.push(`type _JsonValue = string | number | boolean | null | _JsonValue[] | { [key: string]: _JsonValue };`);
         helpers.push(
@@ -200,6 +180,43 @@ export function generateOp(root: OpRootNode, options: OpCodegenOptions = {}): st
         }
     }
 
+    // Imports are decided from the code we just generated, not from predicates over the AST that
+    // have to be kept in step with it by hand. A predicate that drifts leaves an unused import in
+    // every generated file, which trips `noUnusedLocals` and lint in consuming projects.
+    const generated = [...(helpers.length ? ['', ...helpers] : []), ...lines].join('\n');
+    const uses = (symbol: string) => new RegExp(`\\b${symbol}\\b`).test(generated);
+
+    const body: string[] = [];
+
+    const koaImports = ['ServerKitRouter', 'bodyParserMiddleware', 'requirePolicy', 'requireSignature'].filter(uses);
+    if (koaImports.length > 0) {
+        body.push(`import { ${koaImports.join(', ')} } from '@maroonedsoftware/koa';`);
+    }
+
+    for (const svc of services) {
+        const modulePath = root.services?.[svc] ?? root.meta[svc] ?? deriveModulePath(svc, options.servicePathTemplate);
+        body.push(`import { ${svc} } from '${modulePath}';`);
+    }
+
+    if (types.length > 0) {
+        body.push(...generateTypeImports(types, root.file, options));
+    }
+
+    // luxon is needed for date/time/datetime (DateTime), duration (Duration) and interval (Interval);
+    // the rendered Zod schemas and the service-result annotations both reference these classes.
+    const luxonImports = ['DateTime', 'Duration', 'Interval'].filter(uses);
+    if (luxonImports.length > 0) {
+        body.push(`import { ${luxonImports.join(', ')} } from 'luxon';`);
+    }
+
+    if (uses('parseAndValidate')) {
+        body.push(`import { parseAndValidate } from '@maroonedsoftware/zod';`);
+    }
+
+    if (uses('MultipartBody')) {
+        body.push(`import { MultipartBody } from '@maroonedsoftware/multipart';`);
+    }
+
     const allContent = [...body, ...(helpers.length ? ['', ...helpers] : []), ...lines].join('\n');
     const needsZod = /\bz\./.test(allContent);
     return (needsZod ? `import { z } from 'zod';\n` : '') + allContent;
@@ -317,7 +334,10 @@ function generateHandler(route: OpRouteNode, op: OpOperationNode, root: OpRootNo
     const hasRespHeaders = respHeaders.length > 0;
     const headersAnnotation = hasRespHeaders
         ? `{ ${respHeaders
-              .map(h => `${quoteKey(headerNameToProperty(h.name))}${h.optional ? '?' : ''}: ${renderOutputTsType(h.type, options.modelsWithOutput)}`)
+              .map(
+                  h =>
+                      `${quoteKey(headerNameToProperty(h.name))}${h.optional ? '?' : ''}: ${renderOutputTsType(h.type, options.modelsWithOutput, 'server')}`,
+              )
               .join('; ')} }`
         : '';
 
@@ -442,6 +462,52 @@ export function buildArgs(route: OpRouteNode, op: OpOperationNode): string {
     return args.join(', ');
 }
 
+/**
+ * Map a `.ck` scalar to the TypeScript type a server handler sees, i.e. `z.infer` of the schema
+ * `renderType` emits for that scalar. This is deliberately NOT `renderTsScalar` from ts-render:
+ * that one describes the wire/SDK view (`binary` → `Blob`, dates → `string`), while the router
+ * runs on Node against the parsed Zod output (`binary` → `Buffer`, dates → luxon `DateTime`).
+ */
+function serverTsScalar(name: ScalarTypeNode['name']): string {
+    switch (name) {
+        case 'string':
+        case 'email':
+        case 'url':
+        case 'uuid':
+            return 'string';
+        case 'number':
+        case 'int':
+            return 'number';
+        case 'bigint':
+            return 'bigint';
+        case 'boolean':
+            return 'boolean';
+        case 'date':
+        case 'time':
+        case 'datetime':
+            return 'DateTime';
+        case 'duration':
+            return 'Duration';
+        case 'interval':
+            // _ZodInterval transforms to an ISO string, so the inferred output type is string.
+            return 'string';
+        case 'binary':
+            return 'Buffer';
+        case 'json':
+            return '_JsonValue';
+        case 'object':
+            return 'Record<string, unknown>';
+        case 'null':
+            return 'null';
+        case 'unknown':
+            return 'unknown';
+        default: {
+            const _exhaustive: never = name;
+            throw new Error(`plugin-typescript: unmapped scalar '${String(_exhaustive)}' — add a case`);
+        }
+    }
+}
+
 function formatTypeAnnotation(bodyType: ContractTypeNode, modelsWithOutput?: Set<string>): { annotation: string; prelude?: string } {
     if (bodyType.kind === 'array') {
         const inner = formatTypeAnnotation(bodyType.item, modelsWithOutput);
@@ -451,7 +517,7 @@ function formatTypeAnnotation(bodyType: ContractTypeNode, modelsWithOutput?: Set
         const name = modelsWithOutput?.has(bodyType.name) ? `${bodyType.name}Output` : bodyType.name;
         return { annotation: name };
     }
-    if (bodyType.kind === 'scalar') return { annotation: bodyType.name };
+    if (bodyType.kind === 'scalar') return { annotation: serverTsScalar(bodyType.name) };
     // For complex types, extract schema into a variable so the result line stays readable
     const schema = renderType(bodyType);
     return {
@@ -720,26 +786,7 @@ function collectTypeNodeRefs(type: ContractTypeNode, out: Set<string>): void {
     }
 }
 
-function paramSourceNeedsDateTime(source: ParamSource | undefined): boolean {
-    if (!source) return false;
-    if (source.kind === 'ref') return false;
-    if (source.kind === 'params') return source.nodes.some(p => typeNeedsDateTime(p.type));
-    return typeNeedsDateTime(source.node);
-}
 
-function opNeedsDateTime(root: OpRootNode): boolean {
-    return root.routes.some(
-        route =>
-            paramSourceNeedsDateTime(route.params) ||
-            route.operations.some(
-                op =>
-                    !!op.request?.bodies.some(b => typeNeedsDateTime(b.bodyType)) ||
-                    op.responses.some(r => r.bodyType && typeNeedsDateTime(r.bodyType)) ||
-                    paramSourceNeedsDateTime(op.query) ||
-                    paramSourceNeedsDateTime(op.headers),
-            ),
-    );
-}
 
 function paramSourceNeedsScalar(source: ParamSource | undefined, name: string): boolean {
     if (!source) return false;
@@ -778,32 +825,10 @@ function collectServices(root: OpRootNode): string[] {
     return [...services].sort();
 }
 
-function hasParamSource(source?: ParamSource): boolean {
-    if (!source) return false;
-    if (source.kind === 'ref') return true;
-    if (source.kind === 'params') return source.nodes.length > 0;
-    return true; // type
-}
 
-function routeNeedsValidation(root: OpRootNode): boolean {
-    return root.routes.some(
-        r => hasParamSource(r.params) || r.operations.some(op => !!op.request || hasParamSource(op.query) || hasParamSource(op.headers)),
-    );
-}
 
-function fileNeedsPolicy(root: OpRootNode): boolean {
-    return root.routes.some(route => route.operations.some(op => resolveSecurity(route, op, root) !== SECURITY_NONE));
-}
 
-function fileNeedsSignature(root: OpRootNode): boolean {
-    return root.routes.some(route => route.operations.some(op => !!op.signature));
-}
 
-function fileUsesMultipart(root: OpRootNode): boolean {
-    return root.routes.some(route =>
-        route.operations.some(op => (op.request?.bodies ?? []).some(b => b.contentType === 'multipart/form-data')),
-    );
-}
 
 function isValidIdentifier(name: string): boolean {
     return /^[a-zA-Z_$][a-zA-Z0-9_$]*$/.test(name);

package/src/codegen-plain-types.ts

@@ -11,6 +11,7 @@ import {
     rootNeedsScalar,
 } from './codegen-contract.js';
 import { renderTsType, renderInputTsType, renderOutputTsType, quoteKey, escapeJsDocLines, JSON_VALUE_TYPE_DECL } from './ts-render.js';
+import type { TsRenderTarget } from './ts-render.js';
 
 // ─── Public entry point ────────────────────────────────────────────────────
 
@@ -19,8 +20,12 @@ import { renderTsType, renderInputTsType, renderOutputTsType, quoteKey, escapeJs
  * Unlike `generateContract()` which produces Zod schemas, this emits
  * vanilla TypeScript `interface` and `type` declarations suitable
  * for SDK consumers that don't need runtime validation.
+ *
+ * @param context Import resolution and Input/Output variant sets. `context.target` selects the
+ * runtime the types describe (`'server'` renders `binary` as `Buffer`, `'client'` as `Blob`).
  */
 export function generatePlainTypes(root: ContractRootNode, context?: ContractCodegenContext): string {
+    const target: TsRenderTarget = context?.target ?? 'client';
     const externalRefs = collectExternalRefs(root);
     const lines: string[] = [];
 
@@ -58,7 +63,7 @@ export function generatePlainTypes(root: ContractRootNode, context?: ContractCod
     const modelMap = new Map(root.models.map(m => [m.name, m]));
 
     for (const model of topoSortModels(root.models)) {
-        lines.push(...generateModel(model, context?.currentOutPath, allModelsWithInput, allModelsWithOutput, modelMap));
+        lines.push(...generateModel(model, target, context?.currentOutPath, allModelsWithInput, allModelsWithOutput, modelMap));
         lines.push('');
     }
 
@@ -69,6 +74,7 @@ export function generatePlainTypes(root: ContractRootNode, context?: ContractCod
 
 function generateModel(
     model: ModelNode,
+    target: TsRenderTarget,
     outPath?: string,
     modelsWithInput?: Set<string>,
     modelsWithOutput?: Set<string>,
@@ -76,18 +82,20 @@ function generateModel(
 ): string[] {
     // Type alias: Name : typeExpression
     if (model.type) {
-        return generateTypeAlias(model, outPath, modelsWithInput, modelsWithOutput);
+        return generateTypeAlias(model, target, outPath, modelsWithInput, modelsWithOutput);
     }
 
     // A model needs Input/read split if it has visibility-modified fields OR if it
     // transitively references models that have Input variants (captured in modelsWithInput).
     const needsInputSplit = model.fields.some(f => f.visibility !== 'normal') || (modelsWithInput?.has(model.name) ?? false);
 
-    const lines = needsInputSplit ? generateVisibilityModel(model, outPath, modelsWithInput, modelMap) : generateSimpleModel(model, outPath, modelMap);
+    const lines = needsInputSplit
+        ? generateVisibilityModel(model, target, outPath, modelsWithInput, modelMap)
+        : generateSimpleModel(model, target, outPath, modelMap);
 
     if (modelsWithOutput?.has(model.name)) {
         lines.push('');
-        lines.push(...generateOutputModel(model, modelsWithOutput));
+        lines.push(...generateOutputModel(model, target, modelsWithOutput));
     }
     return lines;
 }
@@ -132,15 +140,21 @@ function generateComments(model: ModelNode, outPath?: string): string[] {
     return lines;
 }
 
-function generateTypeAlias(model: ModelNode, outPath?: string, modelsWithInput?: Set<string>, modelsWithOutput?: Set<string>): string[] {
+function generateTypeAlias(
+    model: ModelNode,
+    target: TsRenderTarget,
+    outPath?: string,
+    modelsWithInput?: Set<string>,
+    modelsWithOutput?: Set<string>,
+): string[] {
     const lines: string[] = [];
     lines.push(...generateComments(model, outPath));
-    lines.push(`export type ${model.name} = ${renderTsType(model.type!)};`);
+    lines.push(`export type ${model.name} = ${renderTsType(model.type!, target)};`);
     if (modelsWithInput?.has(model.name)) {
-        lines.push(`export type ${model.name}Input = ${renderInputTsType(model.type!, modelsWithInput)};`);
+        lines.push(`export type ${model.name}Input = ${renderInputTsType(model.type!, modelsWithInput, target)};`);
     }
     if (modelsWithOutput?.has(model.name)) {
-        lines.push(`export type ${model.name}Output = ${renderOutputTsType(model.type!, modelsWithOutput)};`);
+        lines.push(`export type ${model.name}Output = ${renderOutputTsType(model.type!, modelsWithOutput, target)};`);
     }
     return lines;
 }
@@ -158,7 +172,7 @@ function buildExtendsClause(bases: string[], overrideNames: string[], baseNameRe
     return ` extends ${wrapped.join(', ')}`;
 }
 
-function generateSimpleModel(model: ModelNode, outPath?: string, modelMap?: Map<string, ModelNode>): string[] {
+function generateSimpleModel(model: ModelNode, target: TsRenderTarget, outPath?: string, modelMap?: Map<string, ModelNode>): string[] {
     const lines: string[] = [];
     lines.push(...generateComments(model, outPath));
 
@@ -167,14 +181,20 @@ function generateSimpleModel(model: ModelNode, outPath?: string, modelMap?: Map<
     lines.push(`export interface ${model.name}${buildExtendsClause(bases, overrideNames, b => b)} {`);
 
     for (const field of model.fields) {
-        lines.push(`    ${renderField(field)}`);
+        lines.push(`    ${renderField(field, target)}`);
     }
 
     lines.push('}');
     return lines;
 }
 
-function generateVisibilityModel(model: ModelNode, outPath?: string, modelsWithInput?: Set<string>, modelMap?: Map<string, ModelNode>): string[] {
+function generateVisibilityModel(
+    model: ModelNode,
+    target: TsRenderTarget,
+    outPath?: string,
+    modelsWithInput?: Set<string>,
+    modelMap?: Map<string, ModelNode>,
+): string[] {
     const lines: string[] = [];
     lines.push(...generateComments(model, outPath));
 
@@ -185,7 +205,7 @@ function generateVisibilityModel(model: ModelNode, outPath?: string, modelsWithI
     const readFields = model.fields.filter(f => f.visibility !== 'writeonly');
     lines.push(`export interface ${model.name}${buildExtendsClause(bases, overrideNames, b => b)} {`);
     for (const field of readFields) {
-        lines.push(`    ${renderField(field)}`);
+        lines.push(`    ${renderField(field, target)}`);
     }
     lines.push('}');
     lines.push('');
@@ -196,7 +216,7 @@ function generateVisibilityModel(model: ModelNode, outPath?: string, modelsWithI
     const inputResolver = (b: string) => (modelsWithInput?.has(b) ? `${b}Input` : b);
     lines.push(`export interface ${model.name}Input${buildExtendsClause(bases, overrideNames, inputResolver)} {`);
     for (const field of writeFields) {
-        lines.push(`    ${modelsWithInput ? renderInputField(field, modelsWithInput) : renderField(field)}`);
+        lines.push(`    ${modelsWithInput ? renderInputField(field, modelsWithInput, target) : renderField(field, target)}`);
     }
     lines.push('}');
 
@@ -217,9 +237,9 @@ function withFieldJsDoc(jsdocParts: string[], line: string): string {
     return `/**\n${body}\n     */\n    ${line}`;
 }
 
-function renderField(field: FieldNode): string {
+function renderField(field: FieldNode, target: TsRenderTarget): string {
     const opt = field.optional || field.default !== undefined ? '?' : '';
-    let typeStr = renderTsType(field.type);
+    let typeStr = renderTsType(field.type, target);
     if (field.nullable) typeStr += ' | null';
     const line = `${quoteKey(field.name)}${opt}: ${typeStr};`;
     const jsdocParts: string[] = [];
@@ -228,9 +248,9 @@ function renderField(field: FieldNode): string {
     return withFieldJsDoc(jsdocParts, line);
 }
 
-function renderInputField(field: FieldNode, modelsWithInput: Set<string>): string {
+function renderInputField(field: FieldNode, modelsWithInput: Set<string>, target: TsRenderTarget): string {
     const opt = field.optional || field.default !== undefined ? '?' : '';
-    let typeStr = renderInputTsType(field.type, modelsWithInput);
+    let typeStr = renderInputTsType(field.type, modelsWithInput, target);
     if (field.nullable) typeStr += ' | null';
     const line = `${quoteKey(field.name)}${opt}: ${typeStr};`;
     const jsdocParts: string[] = [];
@@ -264,7 +284,7 @@ function applyOutputCase(name: string, c: 'camel' | 'snake' | 'pascal' | undefin
  * ancestor has format(...) (see `flattenFormatChain` in codegen-contract); we mirror that here
  * so the plain interface matches the wire shape produced by the Zod transform.
  */
-function generateOutputModel(model: ModelNode, modelsWithOutput: Set<string>): string[] {
+function generateOutputModel(model: ModelNode, target: TsRenderTarget, modelsWithOutput: Set<string>): string[] {
     const lines: string[] = [];
     const outputCase = model.outputCase && model.outputCase !== 'camel' ? model.outputCase : undefined;
     const readFields = model.fields.filter(f => f.visibility !== 'writeonly');
@@ -279,7 +299,7 @@ function generateOutputModel(model: ModelNode, modelsWithOutput: Set<string>): s
                   : '';
         lines.push(`export interface ${model.name}Output${baseExt} {`);
         for (const field of readFields) {
-            lines.push(`    ${renderOutputField(field, model.outputCase, modelsWithOutput)}`);
+            lines.push(`    ${renderOutputField(field, model.outputCase, modelsWithOutput, target)}`);
         }
         lines.push('}');
         return lines;
@@ -288,16 +308,21 @@ function generateOutputModel(model: ModelNode, modelsWithOutput: Set<string>): s
     // Direct hit: emit a flat interface with renamed keys.
     lines.push(`export interface ${model.name}Output {`);
     for (const field of readFields) {
-        lines.push(`    ${renderOutputField(field, outputCase, modelsWithOutput)}`);
+        lines.push(`    ${renderOutputField(field, outputCase, modelsWithOutput, target)}`);
     }
     lines.push('}');
     return lines;
 }
 
-function renderOutputField(field: FieldNode, outputCase: 'camel' | 'snake' | 'pascal' | undefined, modelsWithOutput: Set<string>): string {
+function renderOutputField(
+    field: FieldNode,
+    outputCase: 'camel' | 'snake' | 'pascal' | undefined,
+    modelsWithOutput: Set<string>,
+    target: TsRenderTarget,
+): string {
     const opt = field.optional || field.default !== undefined ? '?' : '';
     const key = applyOutputCase(field.name, outputCase);
-    let typeStr = renderOutputTsType(field.type, modelsWithOutput);
+    let typeStr = renderOutputTsType(field.type, modelsWithOutput, target);
     if (field.nullable) typeStr += ' | null';
     const line = `${quoteKey(key)}${opt}: ${typeStr};`;
     const jsdocParts: string[] = [];

package/src/index.ts

@@ -57,6 +57,7 @@ import {
 
 // ─── Sub-config interfaces ─────────────────────────────────────────────────
 
+/** Koa server output: routers, and the type or Zod schema files they import. */
 export interface ServerConfig {
     /** Directory (relative to rootDir) where server files are written. Default: rootDir. */
     baseDir?: string;
@@ -74,6 +75,7 @@ export interface ServerConfig {
     includeInternal?: boolean;
 }
 
+/** TypeScript SDK client output: the client class, per-area operation clients, and their types. */
 export interface SdkConfig {
     baseDir?: string;
     name?: string;
@@ -95,16 +97,25 @@ export interface SdkConfig {
     scaffold?: boolean;
 }
 
+/** Standalone Zod schema output, independent of the server and SDK sub-generators. */
 export interface ZodConfig {
     baseDir?: string;
     output?: string;
 }
 
+/** Standalone plain TypeScript type output, independent of the server and SDK sub-generators. */
 export interface TypesConfig {
     baseDir?: string;
     output?: string;
+    /**
+     * Runtime the emitted types describe. Affects scalars whose TypeScript type is runtime-specific:
+     * `binary` renders as `Buffer` for `'server'` and `Blob` for `'client'`. Default `'client'`.
+     * The `server` and `sdk` sub-generators set this themselves.
+     */
+    target?: 'client' | 'server';
 }
 
+/** MCP tool output: per-op-file handlers, the aggregator, and the optional POST route. */
 export interface McpConfig {
     /** Directory (relative to rootDir) where MCP files are written. Default: rootDir. */
     baseDir?: string;
@@ -132,6 +143,7 @@ export interface McpConfig {
     includeInternal?: boolean;
 }
 
+/** Top-level plugin config. Each sub-config that is present enables its sub-generator. */
 export interface TypescriptPluginConfig {
     server?: ServerConfig;
     sdk?: SdkConfig;
@@ -355,6 +367,8 @@ function collectServerOutput(
                     currentOutPath: typeOutPath,
                     modelsWithInput,
                     modelsWithOutput,
+                    // These types are consumed by Koa handlers, so `binary` is a Buffer, not a Blob.
+                    target: 'server' as const,
                 };
                 const content = config.zod ? generateContract(ast, renderCtx) : generatePlainTypes(ast, renderCtx);
                 return [{ relativePath: typeOutPath, content }];
@@ -861,7 +875,13 @@ function collectTypesOutput(
             render: () => [
                 {
                     relativePath: outPath,
-                    content: generatePlainTypes(ast, { modelOutPaths, currentOutPath: outPath, modelsWithInput, modelsWithOutput }),
+                    content: generatePlainTypes(ast, {
+                        modelOutPaths,
+                        currentOutPath: outPath,
+                        modelsWithInput,
+                        modelsWithOutput,
+                        target: config.target,
+                    }),
                 },
             ],
         });