@contractkit/plugin-typescript 0.28.2 → 0.29.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.29.0",
   "description": "ContractKit built-in plugin: TypeScript codegen (SDK clients, Koa routers, Zod schemas, plain types)",
   "author": {
     "name": "Marooned Software",

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,4 +1,4 @@
-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,
@@ -153,8 +153,14 @@ export function generateOp(root: OpRootNode, options: OpCodegenOptions = {}): st
         body.push(...generateTypeImports(types, root.file, options));
     }
 
-    if (opNeedsDateTime(root)) {
-        body.push(`import { DateTime } from 'luxon';`);
+    // 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: string[] = [];
+    if (opNeedsDateTime(root)) luxonImports.push('DateTime');
+    if (opNeedsScalar(root, 'duration')) luxonImports.push('Duration');
+    if (opNeedsScalar(root, 'interval')) luxonImports.push('Interval');
+    if (luxonImports.length > 0) {
+        body.push(`import { ${luxonImports.join(', ')} } from 'luxon';`);
     }
 
     if (needsParseAndValidate) {
@@ -174,6 +180,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(
@@ -317,7 +328,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 +456,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 +511,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 {

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,
+                    }),
                 },
             ],
         });

package/src/ts-render.ts

@@ -1,7 +1,9 @@
 import type { ContractTypeNode, FieldNode, ScalarTypeNode } from '@contractkit/core';
 
+/** Declaration emitted into generated files that reference the `json` scalar. */
 export 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 function quoteKey(name: string): string {
     return /^[a-zA-Z_$][a-zA-Z0-9_$]*$/.test(name) ? name : `'${name}'`;
 }
@@ -31,12 +33,25 @@ export function headerNameToProperty(name: string): string {
 
 // ─── TypeScript type rendering ────────────────────────────────────────────
 
-export 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 function renderTsType(type: ContractTypeNode, target: TsRenderTarget = 'client'): string {
     switch (type.kind) {
         case 'scalar':
-            return renderTsScalar(type.name);
+            return renderTsScalar(type.name, target);
         case 'array': {
-            const inner = renderTsType(type.item);
+            const inner = renderTsType(type.item, target);
             const needsParens =
                 type.item.kind === 'union' ||
                 type.item.kind === 'discriminatedUnion' ||
@@ -45,31 +60,31 @@ export function renderTsType(type: ContractTypeNode): string {
             return needsParens ? `(${inner})[]` : `${inner}[]`;
         }
         case 'tuple':
-            return `[${type.items.map(renderTsType).join(', ')}]`;
+            return `[${type.items.map(i => renderTsType(i, target)).join(', ')}]`;
         case 'record':
-            return `Record<${renderTsType(type.key)}, ${renderTsType(type.value)}>`;
+            return `Record<${renderTsType(type.key, target)}, ${renderTsType(type.value, target)}>`;
         case 'enum':
             return type.values.map(v => `'${escapeSingleQuoted(v)}'`).join(' | ');
         case 'literal':
             return typeof type.value === 'string' ? `'${escapeSingleQuoted(type.value)}'` : String(type.value);
         case 'union':
-            return type.members.map(renderTsType).join(' | ');
+            return type.members.map(m => renderTsType(m, target)).join(' | ');
         case 'discriminatedUnion':
-            return type.members.map(renderTsType).join(' | ');
+            return type.members.map(m => renderTsType(m, target)).join(' | ');
         case 'intersection':
-            return type.members.map(renderTsType).join(' & ');
+            return type.members.map(m => renderTsType(m, target)).join(' & ');
         case 'ref':
             return type.name;
         case 'lazy':
-            return renderTsType(type.inner);
+            return renderTsType(type.inner, target);
         case 'inlineObject':
-            return renderTsInlineObject(type.fields);
+            return renderTsInlineObject(type.fields, target);
         default:
             return 'unknown';
     }
 }
 
-function renderTsScalar(name: ScalarTypeNode['name']): string {
+function renderTsScalar(name: ScalarTypeNode['name'], target: TsRenderTarget): string {
     switch (name) {
         case 'string':
         case 'email':
@@ -96,7 +111,8 @@ function renderTsScalar(name: ScalarTypeNode['name']): string {
         case 'object':
             return 'Record<string, unknown>';
         case 'binary':
-            return 'Blob';
+            // Node servers hand the handler a Buffer (matching `_ZodBinary`); fetch clients get a Blob.
+            return target === 'server' ? 'Buffer' : 'Blob';
         case 'json':
             return 'JsonValue';
         default: {
@@ -106,10 +122,10 @@ function renderTsScalar(name: ScalarTypeNode['name']): string {
     }
 }
 
-function renderTsInlineObject(fields: FieldNode[]): string {
+function renderTsInlineObject(fields: FieldNode[], target: TsRenderTarget): string {
     const entries = fields.map(f => {
         const opt = f.optional ? '?' : '';
-        return `${quoteKey(f.name)}${opt}: ${renderTsType(f.type)}`;
+        return `${quoteKey(f.name)}${opt}: ${renderTsType(f.type, target)}`;
     });
     return `{ ${entries.join('; ')} }`;
 }
@@ -118,14 +134,16 @@ function renderTsInlineObject(fields: FieldNode[]): 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 function renderInputTsType(type: ContractTypeNode, modelsWithInput?: Set<string>): string {
-    if (!modelsWithInput || modelsWithInput.size === 0) return renderTsType(type);
+export function renderInputTsType(type: ContractTypeNode, modelsWithInput?: Set<string>, target: TsRenderTarget = 'client'): string {
+    if (!modelsWithInput || modelsWithInput.size === 0) return renderTsType(type, target);
     switch (type.kind) {
         case 'ref':
             return modelsWithInput.has(type.name) ? `${type.name}Input` : type.name;
         case 'array': {
-            const inner = renderInputTsType(type.item, modelsWithInput);
+            const inner = renderInputTsType(type.item, modelsWithInput, target);
             const needsParens =
                 type.item.kind === 'union' ||
                 type.item.kind === 'discriminatedUnion' ||
@@ -134,17 +152,17 @@ export function renderInputTsType(type: ContractTypeNode, modelsWithInput?: Set<
             return needsParens ? `(${inner})[]` : `${inner}[]`;
         }
         case 'intersection':
-            return type.members.map(m => renderInputTsType(m, modelsWithInput)).join(' & ');
+            return type.members.map(m => renderInputTsType(m, modelsWithInput, target)).join(' & ');
         case 'union':
-            return type.members.map(m => renderInputTsType(m, modelsWithInput)).join(' | ');
+            return type.members.map(m => renderInputTsType(m, modelsWithInput, target)).join(' | ');
         case 'discriminatedUnion':
-            return type.members.map(m => renderInputTsType(m, modelsWithInput)).join(' | ');
+            return type.members.map(m => renderInputTsType(m, modelsWithInput, target)).join(' | ');
         case 'inlineObject':
-            return `{ ${type.fields.map(f => `${quoteKey(f.name)}${f.optional ? '?' : ''}: ${renderInputTsType(f.type, modelsWithInput)}`).join('; ')} }`;
+            return `{ ${type.fields.map(f => `${quoteKey(f.name)}${f.optional ? '?' : ''}: ${renderInputTsType(f.type, modelsWithInput, target)}`).join('; ')} }`;
         case 'lazy':
-            return renderInputTsType(type.inner, modelsWithInput);
+            return renderInputTsType(type.inner, modelsWithInput, target);
         default:
-            return renderTsType(type);
+            return renderTsType(type, target);
     }
 }
 
@@ -153,14 +171,16 @@ export function renderInputTsType(type: ContractTypeNode, modelsWithInput?: Set<
  * (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 function renderOutputTsType(type: ContractTypeNode, modelsWithOutput?: Set<string>): string {
-    if (!modelsWithOutput || modelsWithOutput.size === 0) return renderTsType(type);
+export function renderOutputTsType(type: ContractTypeNode, modelsWithOutput?: Set<string>, target: TsRenderTarget = 'client'): string {
+    if (!modelsWithOutput || modelsWithOutput.size === 0) return renderTsType(type, target);
     switch (type.kind) {
         case 'ref':
             return modelsWithOutput.has(type.name) ? `${type.name}Output` : type.name;
         case 'array': {
-            const inner = renderOutputTsType(type.item, modelsWithOutput);
+            const inner = renderOutputTsType(type.item, modelsWithOutput, target);
             const needsParens =
                 type.item.kind === 'union' ||
                 type.item.kind === 'discriminatedUnion' ||
@@ -169,16 +189,16 @@ export function renderOutputTsType(type: ContractTypeNode, modelsWithOutput?: Se
             return needsParens ? `(${inner})[]` : `${inner}[]`;
         }
         case 'intersection':
-            return type.members.map(m => renderOutputTsType(m, modelsWithOutput)).join(' & ');
+            return type.members.map(m => renderOutputTsType(m, modelsWithOutput, target)).join(' & ');
         case 'union':
-            return type.members.map(m => renderOutputTsType(m, modelsWithOutput)).join(' | ');
+            return type.members.map(m => renderOutputTsType(m, modelsWithOutput, target)).join(' | ');
         case 'discriminatedUnion':
-            return type.members.map(m => renderOutputTsType(m, modelsWithOutput)).join(' | ');
+            return type.members.map(m => renderOutputTsType(m, modelsWithOutput, target)).join(' | ');
         case 'inlineObject':
-            return `{ ${type.fields.map(f => `${quoteKey(f.name)}${f.optional ? '?' : ''}: ${renderOutputTsType(f.type, modelsWithOutput)}`).join('; ')} }`;
+            return `{ ${type.fields.map(f => `${quoteKey(f.name)}${f.optional ? '?' : ''}: ${renderOutputTsType(f.type, modelsWithOutput, target)}`).join('; ')} }`;
         case 'lazy':
-            return renderOutputTsType(type.inner, modelsWithOutput);
+            return renderOutputTsType(type.inner, modelsWithOutput, target);
         default:
-            return renderTsType(type);
+            return renderTsType(type, target);
     }
 }