@contractkit/plugin-typescript 0.28.1 → 0.29.0

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);
     }
 }

package/tests/codegen-mcp.test.ts

@@ -0,0 +1,246 @@
+import { describe, it, expect } from 'vitest';
+import type { McpConfigNode } from '@contractkit/core';
+import {
+    generateMcpFile,
+    generateMcpAggregator,
+    generateMcpRouter,
+    hasMcpOperations,
+    deriveMcpRegisterFnName,
+} from '../src/codegen-mcp.js';
+import { opRoot, opRoute, opOperation, opParam, opRequest, opResponse, scalarType, loc } from './helpers.js';
+
+function mcpBlock(over: Partial<McpConfigNode>): McpConfigNode {
+    return { loc: loc(), ...over };
+}
+
+describe('hasMcpOperations', () => {
+    it('is false when no op is flagged', () => {
+        const root = opRoot([opRoute('/users', [opOperation('get', { responses: [opResponse(200, 'User', 'application/json')] })])]);
+        expect(hasMcpOperations(root)).toBe(false);
+    });
+
+    it('is true when an op is flagged', () => {
+        const root = opRoot([opRoute('/users', [opOperation('get', { mcp: true, responses: [opResponse(200, 'User', 'application/json')] })])]);
+        expect(hasMcpOperations(root)).toBe(true);
+    });
+
+    it('excludes internal ops unless includeInternal', () => {
+        const root = opRoot([
+            opRoute('/users', [opOperation('get', { mcp: true, responses: [opResponse(200, 'User', 'application/json')] })], undefined, ['internal']),
+        ]);
+        expect(hasMcpOperations(root)).toBe(false);
+        expect(hasMcpOperations(root, true)).toBe(true);
+    });
+});
+
+describe('generateMcpFile', () => {
+    describe('op selection', () => {
+        it('emits a tool class only for flagged ops', () => {
+            const root = opRoot([
+                opRoute('/users', [
+                    opOperation('get', { sdk: 'listUsers', mcp: true, responses: [opResponse(200, 'User', 'application/json')] }),
+                    opOperation('post', { sdk: 'createUser', request: opRequest('User'), responses: [opResponse(201, 'User', 'application/json')] }),
+                ]),
+            ]);
+            const out = generateMcpFile(root);
+            expect(out).toContain('export class ListUsersMcpTool');
+            expect(out).not.toContain('CreateUserMcpTool');
+        });
+
+        it('skips mcp: false', () => {
+            const root = opRoot([opRoute('/users', [opOperation('get', { sdk: 'listUsers', mcp: false, responses: [opResponse(200, 'User', 'application/json')] })])]);
+            const out = generateMcpFile(root);
+            expect(out).not.toContain('implements McpToolHandler');
+        });
+
+        it('skips internal ops unless includeInternal', () => {
+            const root = opRoot([
+                opRoute('/users', [opOperation('get', { sdk: 'listUsers', mcp: true, responses: [opResponse(200, 'User', 'application/json')] })], undefined, [
+                    'internal',
+                ]),
+            ]);
+            expect(generateMcpFile(root)).not.toContain('ListUsersMcpTool');
+            expect(generateMcpFile(root, { includeInternal: true })).toContain('ListUsersMcpTool');
+        });
+    });
+
+    describe('tool name + class name', () => {
+        it('uses explicit mcp.name verbatim', () => {
+            const root = opRoot([
+                opRoute('/routes', [opOperation('post', { mcp: mcpBlock({ name: 'searchRoutes' }), request: opRequest('Query'), responses: [opResponse(200, 'RouteList', 'application/json')] })]),
+            ]);
+            const out = generateMcpFile(root);
+            expect(out).toContain("name: 'searchRoutes'");
+            expect(out).toContain('export class SearchRoutesMcpTool');
+        });
+
+        it('snake_cases the sdk field', () => {
+            const root = opRoot([opRoute('/users', [opOperation('get', { sdk: 'listAllUsers', mcp: true, responses: [opResponse(200, 'User', 'application/json')] })])]);
+            const out = generateMcpFile(root);
+            expect(out).toContain("name: 'list_all_users'");
+            expect(out).toContain('export class ListAllUsersMcpTool');
+        });
+
+        it('snake_cases the name field', () => {
+            const root = opRoot([opRoute('/users', [opOperation('get', { name: 'Get User', mcp: true, responses: [opResponse(200, 'User', 'application/json')] })])]);
+            expect(generateMcpFile(root)).toContain("name: 'get_user'");
+        });
+
+        it('infers snake_case name from method + path', () => {
+            const root = opRoot([
+                opRoute('/payments/{id}', [opOperation('get', { mcp: true, responses: [opResponse(200, 'Payment', 'application/json')] })], [opParam('id', scalarType('uuid'))]),
+            ]);
+            expect(generateMcpFile(root)).toContain("name: 'get_payments_by_id'");
+        });
+    });
+
+    describe('definition metadata', () => {
+        it('emits title, description, and only the defined annotations', () => {
+            const root = opRoot([
+                opRoute('/payments/{id}', [
+                    opOperation('get', {
+                        mcp: mcpBlock({ title: 'Get Payment', description: 'Fetch a payment by id.', readOnlyHint: true, idempotentHint: true, destructiveHint: false }),
+                        responses: [opResponse(200, 'Payment', 'application/json')],
+                    }),
+                ], [opParam('id', scalarType('uuid'))]),
+            ]);
+            const out = generateMcpFile(root);
+            expect(out).toContain("title: 'Get Payment'");
+            expect(out).toContain("description: 'Fetch a payment by id.'");
+            expect(out).toContain('annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true }');
+            expect(out).not.toContain('openWorldHint');
+        });
+
+        it('omits annotations when no hints set', () => {
+            const root = opRoot([opRoute('/users', [opOperation('get', { mcp: true, responses: [opResponse(200, 'User', 'application/json')] })])]);
+            expect(generateMcpFile(root)).not.toContain('annotations:');
+        });
+
+        it('falls back to op description', () => {
+            const root = opRoot([opRoute('/users', [opOperation('get', { mcp: true, description: 'List users.', responses: [opResponse(200, 'User', 'application/json')] })])]);
+            expect(generateMcpFile(root)).toContain("description: 'List users.'");
+        });
+    });
+
+    describe('input schema + validation', () => {
+        it('folds path params into a shared args const used for schema and validation', () => {
+            const root = opRoot([
+                opRoute('/payments/{id}', [opOperation('get', { mcp: true, responses: [opResponse(200, 'Payment', 'application/json')] })], [opParam('id', scalarType('uuid'))]),
+            ]);
+            const out = generateMcpFile(root);
+            expect(out).toContain('const GetPaymentsByIdArgs = z.object({ id: z.uuid() });');
+            expect(out).toContain("inputSchema: z.toJSONSchema(GetPaymentsByIdArgs, { unrepresentable: 'any' }) as Tool['inputSchema']");
+            expect(out).toContain('const { id } = await parseAndValidate(args, GetPaymentsByIdArgs);');
+        });
+
+        it('nests the request body under a body field', () => {
+            const root = opRoot([
+                opRoute('/payments', [opOperation('post', { sdk: 'createPayment', mcp: true, request: opRequest('PaymentInput'), responses: [opResponse(201, 'Payment', 'application/json')] })]),
+            ]);
+            const out = generateMcpFile(root);
+            expect(out).toContain('const CreatePaymentArgs = z.object({ body: PaymentInput });');
+            expect(out).toContain('const { body } = await parseAndValidate(args, CreatePaymentArgs);');
+        });
+    });
+
+    describe('service call + result', () => {
+        it('injects the declared service and calls it', () => {
+            const root = opRoot([
+                opRoute('/payments/{id}', [opOperation('get', { mcp: true, service: 'PaymentsService.getById', responses: [opResponse(200, 'Payment', 'application/json')] })], [opParam('id', scalarType('uuid'))]),
+            ]);
+            const out = generateMcpFile(root);
+            expect(out).toContain('constructor(private readonly service: PaymentsService) {}');
+            expect(out).toContain('const result = await this.service.getById(id);');
+            expect(out).toContain('structuredContent: result');
+        });
+
+        it('returns bare content (no structuredContent / outputSchema) for a void response', () => {
+            const root = opRoot([
+                opRoute('/payments/{id}', [opOperation('delete', { mcp: true, service: 'PaymentsService.remove', responses: [opResponse(204)] })], [opParam('id', scalarType('uuid'))]),
+            ]);
+            const out = generateMcpFile(root);
+            expect(out).toContain('await this.service.remove(id);');
+            expect(out).toContain("return { content: [{ type: 'text', text: 'OK' }] };");
+            expect(out).not.toContain('structuredContent');
+            expect(out).not.toContain('outputSchema');
+        });
+
+        it('emits outputSchema for an object response', () => {
+            const root = opRoot([
+                opRoute('/payments/{id}', [opOperation('get', { mcp: true, service: 'PaymentsService.getById', responses: [opResponse(200, 'Payment', 'application/json')] })], [opParam('id', scalarType('uuid'))]),
+            ]);
+            expect(generateMcpFile(root)).toContain("outputSchema: z.toJSONSchema(Payment, { unrepresentable: 'any' }) as Tool['outputSchema']");
+        });
+    });
+
+    describe('imports + registration', () => {
+        it('imports the MCP + injectkit primitives and emits a per-file register fn', () => {
+            const root = opRoot(
+                [opRoute('/payments/{id}', [opOperation('get', { mcp: true, service: 'PaymentsService.getById', responses: [opResponse(200, 'Payment', 'application/json')] })], [opParam('id', scalarType('uuid'))])],
+                'payments.op',
+            );
+            const out = generateMcpFile(root);
+            expect(out).toContain("import { Injectable, type Container } from 'injectkit';");
+            expect(out).toContain("import type { McpToolHandler, McpToolHandlerMap, McpToolContext } from '@maroonedsoftware/mcp';");
+            expect(out).toContain("import { parseAndValidate } from '@maroonedsoftware/zod';");
+            expect(out).toContain('export function registerPaymentsMcpTools(map: McpToolHandlerMap, container: Container): void {');
+            expect(out).toContain("map.set('get_payments_by_id', container.get(GetPaymentsByIdMcpTool));");
+        });
+
+        it('resolves service + schema imports via modelOutPaths', () => {
+            const root = opRoot(
+                [opRoute('/payments', [opOperation('post', { sdk: 'createPayment', mcp: true, service: 'PaymentsService.create', request: opRequest('PaymentInput'), responses: [opResponse(201, 'Payment', 'application/json')] })])],
+                'payments.op',
+            );
+            const modelOutPaths = new Map<string, string>([
+                ['Payment', '/api/src/types/payment.ts'],
+                ['PaymentInput', '/api/src/types/payment.ts'],
+            ]);
+            const out = generateMcpFile(root, {
+                outPath: '/api/src/mcp/payments.mcp.ts',
+                modelOutPaths,
+                modelsWithInput: new Set(['Payment']),
+                servicePathTemplate: '#modules/{kebab}/{kebab}.service.js',
+            });
+            expect(out).toContain("import { PaymentsService } from '#modules/payments/payments.service.js';");
+            expect(out).toContain("import { Payment, PaymentInput } from '../types/payment.js';");
+        });
+    });
+});
+
+describe('generateMcpAggregator', () => {
+    it('imports each register fn and assembles one map', () => {
+        const out = generateMcpAggregator([
+            { registerFn: 'registerPaymentsMcpTools', importPath: './payments.mcp.js' },
+            { registerFn: 'registerUsersMcpTools', importPath: './users.mcp.js' },
+        ]);
+        expect(out).toContain("import { McpToolHandlerMap } from '@maroonedsoftware/mcp';");
+        expect(out).toContain("import { registerPaymentsMcpTools } from './payments.mcp.js';");
+        expect(out).toContain('export function registerMcpTools(container: Container): McpToolHandlerMap {');
+        expect(out).toContain('const map = new McpToolHandlerMap();');
+        expect(out).toContain('registerPaymentsMcpTools(map, container);');
+        expect(out).toContain('registerUsersMcpTools(map, container);');
+        expect(out).toContain('container.register(McpToolHandlerMap, { useValue: map });');
+    });
+});
+
+describe('generateMcpRouter', () => {
+    it('emits a ServerKit route wired to the dispatcher at the configured path', () => {
+        const out = generateMcpRouter({ path: '/mcp' });
+        expect(out).toContain("import { McpDispatcher, createMcpRequestContext, MCP_AUTH_POLICY } from '@maroonedsoftware/mcp';");
+        expect(out).toContain("router.post('/mcp'");
+        expect(out).toContain('ctx.container.get(McpDispatcher)');
+        expect(out).toContain("dispatcher.sessionMode === 'stateful'");
+    });
+
+    it('defaults the mount path to /mcp', () => {
+        expect(generateMcpRouter()).toContain("router.post('/mcp'");
+    });
+});
+
+describe('deriveMcpRegisterFnName', () => {
+    it('derives from the op-root filename', () => {
+        expect(deriveMcpRegisterFnName('payments.op')).toBe('registerPaymentsMcpTools');
+        expect(deriveMcpRegisterFnName('ledger.categories.op')).toBe('registerLedgerCategoriesMcpTools');
+    });
+});

package/tests/codegen-operation.test.ts

@@ -103,6 +103,24 @@ describe('generateOperation', () => {
         });
     });
 
+    // ─── Handler signature ─────────────────────────────────────────
+
+    describe('handler signature', () => {
+        it('emits a single-parameter handler without the unused next argument', () => {
+            const root = opRoot([opRoute('/users', [opOperation('get', { security: SECURITY_NONE })])]);
+            const output = generateOp(root);
+            expect(output).toContain(".get('/users', async ctx => {");
+            expect(output).not.toContain('ctx, next');
+        });
+
+        it('omits next on handlers that carry middleware', () => {
+            const root = opRoot([opRoute('/users', [opOperation('post', { request: opRequest('CreateUser') })])]);
+            const output = generateOp(root);
+            expect(output).toContain('async ctx => {');
+            expect(output).not.toContain('ctx, next');
+        });
+    });
+
     // ─── Handler generation — GET ──────────────────────────────────
 
     describe('GET handlers', () => {
@@ -640,6 +658,77 @@ describe('generateOperation', () => {
             const output = generateOp(root, { modelsWithOutput: new Set(['AuthToken']) });
             expect(output).toContain('result: AuthTokenOutput[]');
         });
+
+        // Scalar response bodies used to emit the .ck scalar name verbatim (`result: binary`),
+        // which only happened to compile for `string`.
+        describe('scalar response bodies map to the server-side TypeScript type', () => {
+            const cases: Array<[string, string]> = [
+                ['binary', 'Buffer'],
+                ['int', 'number'],
+                ['number', 'number'],
+                ['bigint', 'bigint'],
+                ['boolean', 'boolean'],
+                ['string', 'string'],
+                ['uuid', 'string'],
+                ['email', 'string'],
+                ['url', 'string'],
+                ['datetime', 'DateTime'],
+                ['date', 'DateTime'],
+                ['time', 'DateTime'],
+                ['duration', 'Duration'],
+                ['interval', 'string'],
+                ['json', '_JsonValue'],
+                ['object', 'Record<string, unknown>'],
+                ['unknown', 'unknown'],
+                ['null', 'null'],
+            ];
+
+            for (const [scalar, tsType] of cases) {
+                it(`renders ${scalar} as ${tsType}`, () => {
+                    const root = opRoot([
+                        opRoute('/x', [
+                            opOperation('get', {
+                                responses: [opResponse(200, scalarType(scalar as never), 'application/octet-stream')],
+                            }),
+                        ]),
+                    ]);
+                    expect(generateOp(root)).toContain(`const result: ${tsType} = await service.list();`);
+                });
+            }
+
+            it('renders an array of binary as Buffer[]', () => {
+                const root = opRoot([
+                    opRoute('/x', [opOperation('get', { responses: [opResponse(200, arrayType(scalarType('binary')), 'application/json')] })]),
+                ]);
+                expect(generateOp(root)).toContain('const result: Buffer[] = await service.list();');
+            });
+        });
+
+        describe('luxon imports cover every scalar that references a luxon class', () => {
+            it('imports Duration for a duration response body', () => {
+                const root = opRoot([opRoute('/x', [opOperation('get', { responses: [opResponse(200, scalarType('duration'), 'application/json')] })])]);
+                expect(generateOp(root)).toContain("import { Duration } from 'luxon';");
+            });
+
+            it('imports Interval and emits the _ZodInterval helper for an interval body', () => {
+                const root = opRoot([opRoute('/x', [opOperation('get', { responses: [opResponse(200, scalarType('interval'), 'application/json')] })])]);
+                const output = generateOp(root);
+                expect(output).toContain("import { Interval } from 'luxon';");
+                expect(output).toContain('const _ZodInterval =');
+            });
+
+            it('imports DateTime and Duration together when both are used', () => {
+                const root = opRoot([
+                    opRoute('/x', [
+                        opOperation('post', {
+                            request: opRequest(scalarType('datetime')),
+                            responses: [opResponse(200, scalarType('duration'), 'application/json')],
+                        }),
+                    ]),
+                ]);
+                expect(generateOp(root)).toContain("import { DateTime, Duration } from 'luxon';");
+            });
+        });
     });
 
     // ─── Service inference ────────────────────────────────────────

package/tests/codegen-plain-types.test.ts

@@ -98,6 +98,54 @@ describe('generatePlainTypes', () => {
             expect(output).toContain('o: Record<string, unknown>;');
             expect(output).toContain('bin: Blob;');
         });
+
+        // `binary` is the one scalar with no runtime-independent TypeScript type: a fetch client
+        // sees a Blob, a Koa handler sees the Buffer that _ZodBinary validates.
+        describe('binary follows the render target', () => {
+            const ctx = (target: 'client' | 'server') => ({
+                modelOutPaths: new Map<string, string>(),
+                currentOutPath: 'out.ts',
+                target,
+            });
+
+            it('renders Buffer for the server target', () => {
+                const root = contractRoot([model('M', [field('bin', scalarType('binary'))])]);
+                expect(generatePlainTypes(root, ctx('server'))).toContain('bin: Buffer;');
+            });
+
+            it('renders Blob for the client target', () => {
+                const root = contractRoot([model('M', [field('bin', scalarType('binary'))])]);
+                expect(generatePlainTypes(root, ctx('client'))).toContain('bin: Blob;');
+            });
+
+            it('defaults to the client target when unset', () => {
+                const root = contractRoot([model('M', [field('bin', scalarType('binary'))])]);
+                expect(generatePlainTypes(root)).toContain('bin: Blob;');
+            });
+
+            it('applies to nested and compound positions', () => {
+                const root = contractRoot([
+                    model('M', [
+                        field('list', arrayType(scalarType('binary'))),
+                        field('nested', inlineObjectType([field('bin', scalarType('binary'))])),
+                        field('map', recordType(scalarType('string'), scalarType('binary'))),
+                    ]),
+                ]);
+                const output = generatePlainTypes(root, ctx('server'));
+                expect(output).toContain('list: Buffer[];');
+                expect(output).toContain('nested: { bin: Buffer };');
+                expect(output).toContain('map: Record<string, Buffer>;');
+            });
+
+            it('applies to type aliases and their Input variants', () => {
+                const root = contractRoot([
+                    model('Blob1', [field('bin', scalarType('binary')), field('secret', scalarType('binary'), { visibility: 'readonly' })]),
+                ]);
+                const output = generatePlainTypes(root, { ...ctx('server'), modelsWithInput: new Set(['Blob1']) });
+                expect(output).toContain('bin: Buffer;');
+                expect(output).not.toContain('Blob;');
+            });
+        });
     });
 
     // ─── Compound types ───────────────────────────────────────────

package/tests/codegen-server.test.ts

@@ -120,6 +120,43 @@ describe('createTypescriptPlugin (server)', () => {
             expect(typeContent).not.toContain('z.');
             expect(typeContent).toContain('export interface User');
         });
+
+        it('renders binary as Buffer in server plain types', async () => {
+            const plugin = createTypescriptPlugin({ server: { output: { types: 'src/types/{filename}.ts' } } }, '/project');
+            const ctx = makeCtx('/project');
+            const contractRoots = [contractRoot([model('Upload', [field('data', scalarType('binary'))])], '/project/contracts/uploads.ck')];
+            await plugin.generateTargets!(inputs([], contractRoots as any), ctx);
+            const typeContent = [...ctx.emitted.values()][0]!;
+            expect(typeContent).toContain('data: Buffer;');
+            expect(typeContent).not.toContain('Blob');
+        });
+
+        it('renders binary as Blob in SDK plain types', async () => {
+            const plugin = createTypescriptPlugin({ sdk: { output: { types: 'src/types/{filename}.ts' } } }, '/project');
+            const ctx = makeCtx('/project');
+            const contractRoots = [contractRoot([model('Upload', [field('data', scalarType('binary'))])], '/project/contracts/uploads.ck')];
+            await plugin.generateTargets!(inputs([], contractRoots as any), ctx);
+            const typeContent = [...ctx.emitted.values()].find(c => c.includes('interface Upload'))!;
+            expect(typeContent).toContain('data: Blob;');
+        });
+
+        it('honors types.target on the standalone types sub-generator', async () => {
+            const contractRoots = [contractRoot([model('Upload', [field('data', scalarType('binary'))])], '/project/contracts/uploads.ck')];
+
+            const serverCtx = makeCtx('/project');
+            await createTypescriptPlugin({ types: { output: 'src/{filename}.types.ts', target: 'server' } }, '/project').generateTargets!(
+                inputs([], contractRoots as any),
+                serverCtx,
+            );
+            expect([...serverCtx.emitted.values()][0]!).toContain('data: Buffer;');
+
+            const defaultCtx = makeCtx('/project');
+            await createTypescriptPlugin({ types: { output: 'src/{filename}.types.ts' } }, '/project').generateTargets!(
+                inputs([], contractRoots as any),
+                defaultCtx,
+            );
+            expect([...defaultCtx.emitted.values()][0]!).toContain('data: Blob;');
+        });
     });
 
     describe('generated content', () => {