@contractkit/plugin-typescript 0.23.1 → 0.25.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@contractkit/plugin-typescript",
-  "version": "0.23.1",
+  "version": "0.25.0",
   "description": "ContractKit built-in plugin: TypeScript codegen (SDK clients, Koa routers, Zod schemas, plain types)",
   "author": {
     "name": "Marooned Software",
@@ -26,11 +26,11 @@
     ".": "./dist/index.js"
   },
   "dependencies": {
-    "@contractkit/core": "0.17.0"
+    "@contractkit/core": "0.18.0"
   },
   "devDependencies": {
-    "@repo/config-typescript": "0.1.0",
-    "@repo/config-eslint": "0.3.1"
+    "@repo/config-eslint": "0.3.1",
+    "@repo/config-typescript": "0.1.0"
   },
   "scripts": {
     "build": "tsup src/index.ts --format esm --sourcemap --dts && tsc --emitDeclarationOnly --declaration",

package/src/codegen-contract.ts

@@ -300,8 +300,17 @@ function generateSimpleModel(model: ModelNode, outPath?: string): string[] {
         for (const field of model.fields) {
             const inputKey = applyCase(field.name, inputCase);
             const outputKey = applyCase(field.name, outputCase);
-            const val = field.optional ? `data.${inputKey} ?? undefined` : `data.${inputKey}`;
-            lines.push(`    ${quoteKey(outputKey)}: ${val},`);
+            if (field.optional) {
+                // Conditional spread keeps the field optional (`k?: T`) in the inferred
+                // z.output / z.input type, instead of widening to required-nullable (`k: T | undefined`).
+                // Consumer code built with `...(x ? { k: x } : {})` is only assignable to the optional form.
+                // When inputCase is set, the input schema uses `.nullish()` so the guard must reject both
+                // null and undefined; otherwise `.optional()` only allows undefined.
+                const guard = hasInputTransform ? `data.${inputKey} != null` : `data.${inputKey} !== undefined`;
+                lines.push(`    ...(${guard} ? { ${quoteKey(outputKey)}: data.${inputKey} } : {}),`);
+            } else {
+                lines.push(`    ${quoteKey(outputKey)}: data.${inputKey},`);
+            }
         }
         lines.push(`}));`);
         // When only outputCase is set, the developer-facing type is the schema's
@@ -739,9 +748,13 @@ function renderInlineObject(o: InlineObjectTypeNode, parseCaseTransform?: 'snake
         const transformEntries = o.fields
             .map(f => {
                 const snakeKey = camelToSnake(f.name);
-                // Optional fields use .nullish() on input; coerce null → undefined in output
-                const val = f.optional ? `data.${snakeKey} ?? undefined` : `data.${snakeKey}`;
-                return `    ${quoteKey(f.name)}: ${val},`;
+                // Optional fields use .nullish() on input. Conditional spread (instead of `?? undefined`)
+                // keeps the key optional in the inferred output type (`k?: T`) rather than widening to
+                // required-nullable (`k: T | undefined`).
+                if (f.optional) {
+                    return `    ...(data.${snakeKey} != null ? { ${quoteKey(f.name)}: data.${snakeKey} } : {}),`;
+                }
+                return `    ${quoteKey(f.name)}: data.${snakeKey},`;
             })
             .join('\n');
         return `${wrapper}({\n${joined}\n}).transform(data => ({\n${transformEntries}\n}))`;
@@ -752,8 +765,10 @@ function renderInlineObject(o: InlineObjectTypeNode, parseCaseTransform?: 'snake
         const transformEntries = o.fields
             .map(f => {
                 const pascalKey = camelToPascal(f.name);
-                const val = f.optional ? `data.${pascalKey} ?? undefined` : `data.${pascalKey}`;
-                return `    ${quoteKey(f.name)}: ${val},`;
+                if (f.optional) {
+                    return `    ...(data.${pascalKey} != null ? { ${quoteKey(f.name)}: data.${pascalKey} } : {}),`;
+                }
+                return `    ${quoteKey(f.name)}: data.${pascalKey},`;
             })
             .join('\n');
         return `${wrapper}({\n${joined}\n}).transform(data => ({\n${transformEntries}\n}))`;

package/src/codegen-operation.ts

@@ -137,9 +137,9 @@ export function generateOp(root: OpRootNode, options: OpCodegenOptions = {}): st
     // before deciding whether to emit the zod import.
     const body: string[] = [];
     const needsSignature = fileNeedsSignature(root);
-    const needsSecurity = fileNeedsSecurity(root);
+    const needsPolicy = fileNeedsPolicy(root);
     const koaImports = ['ServerKitRouter', 'bodyParserMiddleware'];
-    if (needsSecurity) koaImports.push('requireSecurity');
+    if (needsPolicy) koaImports.push('requirePolicy');
     if (needsSignature) koaImports.push('requireSignature');
     body.push(`import { ${koaImports.join(', ')} } from '@maroonedsoftware/koa';`);
 
@@ -241,8 +241,14 @@ function generateHandler(route: OpRouteNode, op: OpOperationNode, root: OpRootNo
     // Middleware list
     const middlewares: string[] = [];
     if (effectiveSecurity !== SECURITY_NONE) {
-        const args = effectiveSecurity && effectiveSecurity.requireMfa !== undefined ? `{ requireMfa: ${effectiveSecurity.requireMfa} }` : '';
-        middlewares.push(`requireSecurity(${args})`);
+        const policy = effectiveSecurity?.policy;
+        const args =
+            policy === undefined
+                ? ''
+                : policy === false
+                  ? '{ policy: false }'
+                  : `{ policy: '${policy}' }`;
+        middlewares.push(`requirePolicy(${args})`);
     }
     if (hasBody) {
         const parserTokens = Array.from(new Set(bodies.map(b => bodyParserToken(b.contentType))));
@@ -761,7 +767,7 @@ function routeNeedsValidation(root: OpRootNode): boolean {
     );
 }
 
-function fileNeedsSecurity(root: OpRootNode): boolean {
+function fileNeedsPolicy(root: OpRootNode): boolean {
     return root.routes.some(route => route.operations.some(op => resolveSecurity(route, op, root) !== SECURITY_NONE));
 }
 

package/tests/codegen-contract.test.ts

@@ -1060,12 +1060,15 @@ describe('generateContract', () => {
                 /export const Child = z\.strictObject\(\{[\s\S]*grant_type:[\s\S]*client_id:[\s\S]*client_secret:[\s\S]*\}\)\.transform/,
             );
             expect(output).toContain('grantType: data.grant_type');
-            expect(output).toContain('clientId: data.client_id ?? undefined');
+            expect(output).toContain('clientId: data.client_id,');
             expect(output).toContain('clientSecret: data.client_secret');
             expect(output).toContain('export type Child = z.output<typeof Child>');
         });
 
-        it('input=snake: optional fields coerce null → undefined in the transform', () => {
+        it('input=snake: optional fields use conditional spread guarded by `!= null`', () => {
+            // .nullish() on input accepts null and undefined; conditional spread keeps the field
+            // optional in the inferred output type (`k?: T`) instead of widening to required-nullable
+            // (`k: T | undefined`). The `!= null` guard omits the key for both null and undefined.
             const root = contractRoot([
                 model(
                     'User',
@@ -1076,7 +1079,40 @@ describe('generateContract', () => {
             const output = generateContract(root);
             expect(output).toContain('client_id: z.uuid().nullish()');
             expect(output).toContain('firstName: data.first_name,');
-            expect(output).toContain('clientId: data.client_id ?? undefined,');
+            expect(output).toContain('...(data.client_id != null ? { clientId: data.client_id } : {}),');
+            expect(output).not.toContain('?? undefined');
+        });
+
+        it('output=snake: optional fields use conditional spread guarded by `!== undefined`', () => {
+            // With only outputCase set, input is `.optional()` (undefined-only). Conditional spread keeps
+            // the field optional in the inferred z.input type so consumers building values with
+            // `...(x ? { k: x } : {})` are assignable.
+            const root = contractRoot([
+                model('Token', [field('accessToken', scalarType('string')), field('refreshToken', scalarType('string'), { optional: true })], {
+                    outputCase: 'snake',
+                }),
+            ]);
+            const output = generateContract(root);
+            expect(output).toContain('refreshToken: z.string().optional()');
+            expect(output).toContain('access_token: data.accessToken,');
+            expect(output).toContain('...(data.refreshToken !== undefined ? { refresh_token: data.refreshToken } : {}),');
+            expect(output).not.toContain('?? undefined');
+        });
+
+        it('input=pascal: inline-object optional fields use conditional spread guarded by `!= null`', () => {
+            const dataType = inlineObjectType([
+                field('id', scalarType('uuid')),
+                field('amount', scalarType('number'), { optional: true }),
+            ]);
+            const root = contractRoot([
+                model('Webhook', [field('event', scalarType('string')), field('data', dataType)], { inputCase: 'pascal' }),
+            ]);
+            const output = generateContract(root);
+            // Inline object emits its own transform inside the Webhook input shape.
+            expect(output).toContain('Amount: z.coerce.number().nullish()');
+            expect(output).toContain('id: data.Id,');
+            expect(output).toContain('...(data.Amount != null ? { amount: data.Amount } : {}),');
+            expect(output).not.toContain('?? undefined');
         });
     });
 });

package/tests/codegen-operation.test.ts

@@ -807,9 +807,9 @@ describe('generateOp — route modifiers JSDoc', () => {
             expect(out).toContain('anonymous access, no security required');
         });
 
-        it('emits no annotation for security with requireMfa', () => {
+        it('emits no annotation for security with policy', () => {
             const op = opOperation('get', {
-                security: { requireMfa: true, loc: { file: 'test.op', line: 1 } },
+                security: { policy: 'paymentsWrite', loc: { file: 'test.op', line: 1 } },
             });
             const root = opRoot([opRoute('/users', [op])]);
             const out = generateOp(root);
@@ -845,7 +845,7 @@ describe('generateOp — route modifiers JSDoc', () => {
             });
             const root = opRoot([opRoute('/webhooks', [op])]);
             const out = generateOp(root);
-            expect(out).toContain(`import { ServerKitRouter, bodyParserMiddleware, requireSecurity, requireSignature }`);
+            expect(out).toContain(`import { ServerKitRouter, bodyParserMiddleware, requirePolicy, requireSignature }`);
             expect(out).toContain(`requireSignature('MODERN_TREASURY_WEBHOOK')`);
         });
 
@@ -867,63 +867,63 @@ describe('generateOp — route modifiers JSDoc', () => {
 
         it('does not import requireSignature when no signature is set', () => {
             const op = opOperation('get', {
-                security: { requireMfa: true, loc: { file: 'test.op', line: 1 } },
+                security: { policy: 'paymentsWrite', loc: { file: 'test.op', line: 1 } },
             });
             const root = opRoot([opRoute('/users', [op])]);
             const out = generateOp(root);
             expect(out).not.toContain('requireSignature');
-            expect(out).toContain(`import { ServerKitRouter, bodyParserMiddleware, requireSecurity }`);
+            expect(out).toContain(`import { ServerKitRouter, bodyParserMiddleware, requirePolicy }`);
         });
     });
 
-    // ─── Security (requireMfa) middleware ───────────────────────────
+    // ─── Policy middleware ──────────────────────────────────────────
 
-    describe('security middleware', () => {
-        it('injects requireSecurity() with no args for unannotated routes', () => {
+    describe('policy middleware', () => {
+        it('injects requirePolicy() with no args for unannotated routes', () => {
             const op = opOperation('get');
             const root = opRoot([opRoute('/users', [op])]);
             const out = generateOp(root);
-            expect(out).toContain(`import { ServerKitRouter, bodyParserMiddleware, requireSecurity }`);
-            expect(out).toContain(`requireSecurity()`);
+            expect(out).toContain(`import { ServerKitRouter, bodyParserMiddleware, requirePolicy }`);
+            expect(out).toContain(`requirePolicy()`);
         });
 
-        it('injects requireSecurity with requireMfa: true when set', () => {
+        it('injects requirePolicy with a named policy when set', () => {
             const op = opOperation('get', {
-                security: { requireMfa: true, loc: { file: 'test.op', line: 1 } },
+                security: { policy: 'paymentsWrite', loc: { file: 'test.op', line: 1 } },
             });
             const root = opRoot([opRoute('/users', [op])]);
             const out = generateOp(root);
-            expect(out).toContain(`requireSecurity({ requireMfa: true })`);
+            expect(out).toContain(`requirePolicy({ policy: 'paymentsWrite' })`);
         });
 
-        it('injects requireSecurity with requireMfa: false when set', () => {
+        it('injects requirePolicy with policy: false when explicitly bypassed', () => {
             const op = opOperation('get', {
-                security: { requireMfa: false, loc: { file: 'test.op', line: 1 } },
+                security: { policy: false, loc: { file: 'test.op', line: 1 } },
             });
             const routeLine = generateOp(opRoot([opRoute('/users', [op])]))
                 .split('\n')
                 .find(l => l.includes('.get('));
-            expect(routeLine).toContain(`requireSecurity({ requireMfa: false })`);
+            expect(routeLine).toContain(`requirePolicy({ policy: false })`);
         });
 
-        it('does not inject requireSecurity for public (security: none) routes', () => {
+        it('does not inject requirePolicy for public (security: none) routes', () => {
             const op = opOperation('get', { security: SECURITY_NONE });
             const root = opRoot([opRoute('/health', [op])]);
             const out = generateOp(root);
-            expect(out).not.toContain('requireSecurity');
+            expect(out).not.toContain('requirePolicy');
         });
 
-        it('does not import requireSecurity when all routes are public', () => {
+        it('does not import requirePolicy when all routes are public', () => {
             const op = opOperation('get', { security: SECURITY_NONE });
             const root = opRoot([opRoute('/health', [op])]);
             const out = generateOp(root);
             expect(out).toContain(`import { ServerKitRouter, bodyParserMiddleware }`);
-            expect(out).not.toContain('requireSecurity');
+            expect(out).not.toContain('requirePolicy');
         });
 
-        it('places requireSecurity before bodyParserMiddleware in the route line', () => {
+        it('places requirePolicy before bodyParserMiddleware in the route line', () => {
             const op = opOperation('post', {
-                security: { requireMfa: true, loc: { file: 'test.op', line: 1 } },
+                security: { policy: 'paymentsWrite', loc: { file: 'test.op', line: 1 } },
                 request: opRequest('Payload'),
             });
             const root = opRoot([opRoute('/users', [op])]);
@@ -931,16 +931,16 @@ describe('generateOp — route modifiers JSDoc', () => {
                 .split('\n')
                 .find(l => l.includes('.post('));
             expect(routeLine).toBeDefined();
-            const secIdx = routeLine!.indexOf(`requireSecurity`);
+            const polIdx = routeLine!.indexOf(`requirePolicy`);
             const bodyIdx = routeLine!.indexOf(`bodyParserMiddleware`);
-            expect(secIdx).toBeGreaterThan(-1);
-            expect(bodyIdx).toBeGreaterThan(secIdx);
+            expect(polIdx).toBeGreaterThan(-1);
+            expect(bodyIdx).toBeGreaterThan(polIdx);
         });
 
-        it('places requireSecurity before requireSignature when both are set', () => {
+        it('places requirePolicy before requireSignature when both are set', () => {
             const op = opOperation('post', {
                 signature: 'MY_KEY',
-                security: { requireMfa: true, loc: { file: 'test.op', line: 1 } },
+                security: { policy: 'paymentsWrite', loc: { file: 'test.op', line: 1 } },
                 request: opRequest('Payload'),
             });
             const root = opRoot([opRoute('/webhooks', [op])]);
@@ -948,30 +948,30 @@ describe('generateOp — route modifiers JSDoc', () => {
                 .split('\n')
                 .find(l => l.includes('.post('));
             expect(routeLine).toBeDefined();
-            const secIdx = routeLine!.indexOf(`requireSecurity`);
+            const polIdx = routeLine!.indexOf(`requirePolicy`);
             const sigIdx = routeLine!.indexOf(`requireSignature`);
-            expect(secIdx).toBeGreaterThan(-1);
-            expect(sigIdx).toBeGreaterThan(secIdx);
+            expect(polIdx).toBeGreaterThan(-1);
+            expect(sigIdx).toBeGreaterThan(polIdx);
         });
 
-        it('imports both requireSecurity and requireSignature when both are set', () => {
+        it('imports both requirePolicy and requireSignature when both are set', () => {
             const op = opOperation('post', {
                 signature: 'MY_KEY',
-                security: { requireMfa: true, loc: { file: 'test.op', line: 1 } },
+                security: { policy: 'paymentsWrite', loc: { file: 'test.op', line: 1 } },
                 request: opRequest('Payload'),
             });
             const root = opRoot([opRoute('/webhooks', [op])]);
             const out = generateOp(root);
-            expect(out).toContain(`import { ServerKitRouter, bodyParserMiddleware, requireSecurity, requireSignature }`);
+            expect(out).toContain(`import { ServerKitRouter, bodyParserMiddleware, requirePolicy, requireSignature }`);
         });
 
-        it('works with route-level requireMfa security', () => {
+        it('works with route-level policy security', () => {
             const op = opOperation('get');
             const route = opRoute('/users', [op]);
-            route.security = { requireMfa: true, loc: { file: 'test.op', line: 1 } };
+            route.security = { policy: 'paymentsWrite', loc: { file: 'test.op', line: 1 } };
             const root = opRoot([route]);
             const out = generateOp(root);
-            expect(out).toContain(`requireSecurity({ requireMfa: true })`);
+            expect(out).toContain(`requirePolicy({ policy: 'paymentsWrite' })`);
         });
     });
 });