@contractkit/plugin-typescript 0.30.0 → 0.31.1

package/tests/codegen-operation.test.ts

@@ -11,6 +11,7 @@ import {
     opRequest,
     opMultiRequest,
     opResponse,
+    opResponseMulti,
     opOperation,
     opRoute,
     opRoot,
@@ -643,8 +644,8 @@ describe('generateOperation', () => {
                             responses: [
                                 {
                                     statusCode: 200,
-                                    contentType: 'application/json',
-                                    bodyType: { kind: 'ref', name: 'Transfer' },
+                                    hasBlock: true,
+                                    bodies: [{ contentType: 'application/json', bodyType: { kind: 'ref', name: 'Transfer' } }],
                                     headers: [
                                         { name: 'preference-applied', optional: true, type: { kind: 'scalar', name: 'string' } },
                                         { name: 'etag', optional: false, type: { kind: 'scalar', name: 'string' } },
@@ -674,6 +675,8 @@ describe('generateOperation', () => {
                             responses: [
                                 {
                                     statusCode: 204,
+                                    hasBlock: true,
+                                    bodies: [],
                                     headers: [{ name: 'x-deleted-at', optional: false, type: { kind: 'scalar', name: 'string' } }],
                                 },
                             ],
@@ -694,6 +697,188 @@ describe('generateOperation', () => {
             expect(output).toContain('ctx.status = 200');
         });
 
+        // ─── Which statuses the service produces ─────────────────────────
+
+        describe('emitted-set dispatch', () => {
+            const artBodies = [
+                { contentType: 'image/png', bodyType: scalarType('binary') },
+                { contentType: 'image/jpeg', bodyType: scalarType('binary') },
+            ];
+
+            it('leaves the common success-plus-bodyless-errors operation alone', () => {
+                const root = opRoot([
+                    opRoute('/pet', [
+                        opOperation('get', {
+                            responses: [opResponse(200, 'Pet', 'application/json'), opResponse(400), opResponse(404)],
+                        }),
+                    ]),
+                ]);
+                const output = generateOp(root);
+                expect(output).toContain('const result: Pet = await service.list();');
+                expect(output).toContain('ctx.status = 200;');
+                expect(output).toContain("ctx.type = 'application/json';");
+                expect(output).toContain('ctx.body = result;');
+                expect(output).not.toContain('switch (result.status)');
+            });
+
+            it('lets the service pick the mime when a status declares several', () => {
+                const root = opRoot([
+                    opRoute('/art', [
+                        opOperation('get', {
+                            responses: [
+                                opResponseMulti(200, artBodies, {
+                                    headers: [{ name: 'etag', optional: true, type: scalarType('string') }],
+                                }),
+                                opResponse(304),
+                            ],
+                        }),
+                    ]),
+                ]);
+                const output = generateOp(root);
+                expect(output).toContain(
+                    "const result: { contentType: 'image/png' | 'image/jpeg'; body: Buffer; headers: { etag?: string } } = await service.list();",
+                );
+                expect(output).toContain('ctx.status = 200;');
+                expect(output).toContain('ctx.type = result.contentType;');
+                expect(output).toContain('ctx.body = result.body;');
+                // The bare 304 is documentation — middleware produces it, not the service.
+                expect(output).not.toContain('switch (result.status)');
+                expect(output).not.toContain('304');
+            });
+
+            it('keeps contentType correlated with body when the mimes carry different types', () => {
+                const root = opRoot([
+                    opRoute('/pet', [
+                        opOperation('get', {
+                            responses: [
+                                opResponseMulti(200, [
+                                    { contentType: 'application/json', bodyType: refType('Pet') },
+                                    { contentType: 'text/csv', bodyType: scalarType('string') },
+                                ]),
+                            ],
+                        }),
+                    ]),
+                ]);
+                const output = generateOp(root);
+                expect(output).toContain(
+                    "const result: { contentType: 'application/json'; body: Pet } | { contentType: 'text/csv'; body: string } = await service.list();",
+                );
+            });
+
+            it('switches on status when the service produces more than one', () => {
+                const root = opRoot([
+                    opRoute('/art', [
+                        opOperation('get', {
+                            responses: [
+                                opResponseMulti(200, artBodies, {
+                                    headers: [{ name: 'etag', optional: true, type: scalarType('string') }],
+                                }),
+                                opResponse(202, 'JobRef', 'application/json'),
+                                opResponse(304),
+                                opResponse(404),
+                            ],
+                        }),
+                    ]),
+                ]);
+                const output = generateOp(root);
+                expect(output).toContain("| { status: 200; contentType: 'image/png' | 'image/jpeg'; body: Buffer; headers: { etag?: string } }");
+                expect(output).toContain("| { status: 202; contentType: 'application/json'; body: JobRef }");
+                expect(output).toContain('ctx.status = result.status;');
+                expect(output).toContain('switch (result.status) {');
+                expect(output).toContain('        case 200:');
+                expect(output).toContain('        case 202:');
+                // Neither the middleware-produced 304 nor the thrown 404 is a case.
+                expect(output).not.toContain('case 304:');
+                expect(output).not.toContain('case 404:');
+            });
+
+            it('returns a body-bearing error status rather than leaving it to be thrown', () => {
+                const root = opRoot([
+                    opRoute('/pet', [
+                        opOperation('get', {
+                            responses: [
+                                opResponse(200, 'Pet', 'application/json'),
+                                opResponse(422, 'Problem', 'application/json'),
+                                opResponse(404),
+                            ],
+                        }),
+                    ]),
+                ]);
+                const output = generateOp(root);
+                expect(output).toContain("| { status: 200; contentType: 'application/json'; body: Pet }");
+                expect(output).toContain("| { status: 422; contentType: 'application/json'; body: Problem }");
+                expect(output).toContain('        case 422:');
+            });
+
+            it('puts a documented status back on the throw path', () => {
+                const root = opRoot([
+                    opRoute('/pet', [
+                        opOperation('get', {
+                            responses: [
+                                opResponse(200, 'Pet', 'application/json'),
+                                { ...opResponse(422, 'Problem', 'application/json'), emit: 'documented' },
+                            ],
+                        }),
+                    ]),
+                ]);
+                const output = generateOp(root);
+                expect(output).toContain('const result: Pet = await service.list();');
+                expect(output).not.toContain('switch (result.status)');
+                expect(output).not.toContain('422');
+            });
+
+            it('emits a bodyless status the service opts into with an empty block', () => {
+                const root = opRoot([
+                    opRoute('/art', [
+                        opOperation('get', {
+                            responses: [opResponse(200, 'Art', 'application/json'), { statusCode: 304, bodies: [], hasBlock: true }],
+                        }),
+                    ]),
+                ]);
+                const output = generateOp(root);
+                expect(output).toContain("| { status: 200; contentType: 'application/json'; body: Art }");
+                expect(output).toContain('| { status: 304 }');
+                expect(output).toContain('        case 304:');
+                // Nothing to write for a bodyless member beyond the status itself.
+                expect(output).toMatch(/case 304:\n\s+break;/);
+            });
+
+            it('gives each status its own schema variable so two complex bodies cannot collide', () => {
+                const root = opRoot([
+                    opRoute('/pet', [
+                        opOperation('get', {
+                            responses: [
+                                opResponse(200, inlineObjectType([field('id', scalarType('int'))]), 'application/json'),
+                                opResponse(422, inlineObjectType([field('detail', scalarType('string'))]), 'application/json'),
+                            ],
+                        }),
+                    ]),
+                ]);
+                const output = generateOp(root);
+                expect(output).toContain('const result200Type = ');
+                expect(output).toContain('const result422Type = ');
+            });
+
+            it('writes only the headers belonging to the status that was returned', () => {
+                const root = opRoot([
+                    opRoute('/art', [
+                        opOperation('get', {
+                            responses: [
+                                opResponse(200, 'Art', 'application/json'),
+                                {
+                                    ...opResponse(202, 'JobRef', 'application/json'),
+                                    headers: [{ name: 'retry-after', optional: false, type: scalarType('string') }],
+                                },
+                            ],
+                        }),
+                    ]),
+                ]);
+                const output = generateOp(root);
+                expect(output).toMatch(/case 202:\n\s+ctx\.set\('retry-after'/);
+                expect(output).not.toMatch(/case 200:\n\s+ctx\.set/);
+            });
+        });
+
         it('uses Output variant for result type when response model has format(output=...)', () => {
             const root = opRoot([
                 opRoute('/auth/token', [
@@ -762,6 +947,32 @@ describe('generateOperation', () => {
                 ]);
                 expect(generateOp(root)).toContain('const result: Buffer[] = await service.list();');
             });
+
+            it('emits no _ZodBinary helper for a binary response body', () => {
+                // A response body is an annotation, not a schema — the handler never validates it,
+                // so declaring the helper would leave it unused and trip `noUnusedLocals`.
+                const root = opRoot([
+                    opRoute('/art', [
+                        opOperation('get', {
+                            responses: [
+                                opResponseMulti(200, [
+                                    { contentType: 'image/png', bodyType: scalarType('binary') },
+                                    { contentType: 'image/jpeg', bodyType: scalarType('binary') },
+                                ]),
+                            ],
+                        }),
+                    ]),
+                ]);
+                const output = generateOp(root);
+                expect(output).toContain('body: Buffer');
+                expect(output).not.toContain('_ZodBinary');
+                expect(output).not.toContain("import { z } from 'zod';");
+            });
+
+            it('still emits _ZodBinary when a request body actually validates binary', () => {
+                const root = opRoot([opRoute('/upload', [opOperation('post', { request: opRequest(scalarType('binary')) })])]);
+                expect(generateOp(root)).toContain('const _ZodBinary =');
+            });
         });
 
         describe('luxon imports cover every scalar that references a luxon class', () => {
@@ -770,13 +981,23 @@ describe('generateOperation', () => {
                 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')] })])]);
+            it('imports Interval and emits the _ZodInterval helper for an interval request body', () => {
+                const root = opRoot([opRoute('/x', [opOperation('post', { request: opRequest(scalarType('interval')) })])]);
                 const output = generateOp(root);
                 expect(output).toContain("import { Interval } from 'luxon';");
                 expect(output).toContain('const _ZodInterval =');
             });
 
+            it('emits neither for an interval response body, which is a plain string on the way out', () => {
+                // _ZodInterval transforms to an ISO string, so a response-side interval needs no
+                // schema and no luxon class — emitting either would leave both unused.
+                const root = opRoot([opRoute('/x', [opOperation('get', { responses: [opResponse(200, scalarType('interval'), 'application/json')] })])]);
+                const output = generateOp(root);
+                expect(output).toContain('const result: string = await service.list();');
+                expect(output).not.toContain('_ZodInterval');
+                expect(output).not.toContain('luxon');
+            });
+
             it('imports DateTime and Duration together when both are used', () => {
                 const root = opRoot([
                     opRoute('/x', [

package/tests/codegen-sdk.test.ts

@@ -14,6 +14,7 @@ import {
     hasPublicOperations,
     generateSdkPackageJson,
     generateSdkTsconfig,
+    generateErrorBodyAliases,
 } from '../src/codegen-sdk.js';
 import { collectPublicTypeNames } from '@contractkit/core';
 import { renderTsType, renderInputTsType } from '../src/ts-render.js';
@@ -25,6 +26,7 @@ import {
     opRequest,
     opMultiRequest,
     opResponse,
+    opResponseMulti,
     scalarType,
     refType,
     arrayType,
@@ -351,8 +353,8 @@ describe('generateSdk', () => {
                             responses: [
                                 {
                                     statusCode: 200,
-                                    contentType: 'application/json',
-                                    bodyType: { kind: 'ref', name: 'Transfer' },
+                                    hasBlock: true,
+                                    bodies: [{ contentType: 'application/json', bodyType: { kind: 'ref', name: 'Transfer' } }],
                                     headers: [
                                         { name: 'preference-applied', optional: true, type: scalarType('string') },
                                         { name: 'etag', optional: false, type: scalarType('string') },
@@ -381,6 +383,8 @@ describe('generateSdk', () => {
                             responses: [
                                 {
                                     statusCode: 204,
+                                    hasBlock: true,
+                                    bodies: [],
                                     headers: [{ name: 'x-deleted-at', optional: false, type: scalarType('string') }],
                                 },
                             ],
@@ -649,7 +653,7 @@ describe('generateSdk', () => {
             expect(out).toContain('baseUrl: string');
             expect(out).toContain('headers?:');
             expect(out).toContain('fetch?: SdkFetch');
-            expect(out).toContain('export class SdkError extends Error');
+            expect(out).toContain('export class SdkError<TBody = unknown> extends Error');
             expect(out).toContain('public readonly headers: Headers');
             expect(out).toContain('throw new SdkError(res.status, res.statusText, body, res.headers)');
         });
@@ -721,12 +725,186 @@ describe('generateSdk', () => {
             const root = opRoot([opRoute('/users', [opOperation('get', { responses: [opResponse(200, 'User', 'application/json')] })])]);
             const out = generateSdk(root);
             expect(out).toContain('export interface SdkOptions');
-            expect(out).toContain('export class SdkError extends Error');
+            expect(out).toContain('export class SdkError<TBody = unknown> extends Error');
             expect(out).toContain('export type SdkFetch');
             expect(out).toContain('export function createSdkFetch(');
             expect(out).toContain('fetch?: SdkFetch');
         });
     });
+
+    // ─── What the client can receive ─────────────────────────────────────
+
+    describe('observable-set returns', () => {
+        const sharedOptions = { sdkOptionsPath: '/x/sdk-options.ts', outPath: '/x/client.ts' };
+        const artBodies = [
+            { contentType: 'image/png', bodyType: scalarType('binary') },
+            { contentType: 'image/jpeg', bodyType: scalarType('binary') },
+        ];
+
+        it('leaves the common success-plus-bodyless-errors method alone', () => {
+            const root = opRoot([
+                opRoute('/pet', [
+                    opOperation('get', {
+                        sdk: 'listPets',
+                        responses: [opResponse(200, 'Pet', 'application/json'), opResponse(400), opResponse(404)],
+                    }),
+                ]),
+            ]);
+            const out = generateSdk(root, sharedOptions);
+            expect(out).toContain('async listPets(): Promise<Pet> {');
+            expect(out).toContain('return await parseJson<Pet>(result);');
+            expect(out).not.toContain('expectStatuses');
+            expect(out).not.toContain('switch (result.status)');
+        });
+
+        it('tells the caller which mime came back when a status declares several', () => {
+            const root = opRoot([
+                opRoute('/art', [opOperation('get', { sdk: 'getArt', responses: [opResponseMulti(200, artBodies)] })]),
+            ]);
+            const out = generateSdk(root, sharedOptions);
+            expect(out).toContain("async getArt(): Promise<{ contentType: 'image/png' | 'image/jpeg'; data: Blob }> {");
+            expect(out).toContain("contentType: readContentType(result) as 'image/png' | 'image/jpeg'");
+            expect(out).toContain('data: await result.blob()');
+            expect(out).toContain("import { readContentType } from '/x/sdk-options.js'".replace('/x/', './'));
+        });
+
+        it('dispatches on the response content type when the mimes read differently', () => {
+            const root = opRoot([
+                opRoute('/pet', [
+                    opOperation('get', {
+                        sdk: 'getPet',
+                        responses: [
+                            opResponseMulti(200, [
+                                { contentType: 'application/json', bodyType: refType('Pet') },
+                                { contentType: 'text/csv', bodyType: scalarType('string') },
+                            ]),
+                        ],
+                    }),
+                ]),
+            ]);
+            const out = generateSdk(root, sharedOptions);
+            expect(out).toContain("| { contentType: 'application/json'; data: Pet }");
+            expect(out).toContain("| { contentType: 'text/csv'; data: string }");
+            expect(out).toContain('switch (readContentType(result)) {');
+            expect(out).toContain("case 'text/csv':");
+        });
+
+        it('returns a union over every status a client can receive, including one middleware produces', () => {
+            const root = opRoot([
+                opRoute('/art', [
+                    opOperation('get', {
+                        sdk: 'getArt',
+                        responses: [opResponse(200, 'Art', 'application/json'), opResponse(304), opResponse(404)],
+                    }),
+                ]),
+            ]);
+            const out = generateSdk(root, sharedOptions);
+            expect(out).toContain("| { status: 200; contentType: 'application/json'; data: Art }");
+            expect(out).toContain('| { status: 304 }');
+            // The bare 404 still throws, so it is not a member.
+            expect(out).not.toContain('status: 404');
+            expect(out).toContain('switch (result.status) {');
+        });
+
+        it('stops throwing for a status declared as a value rather than an error', () => {
+            const root = opRoot([
+                opRoute('/pet', [
+                    opOperation('get', {
+                        sdk: 'getPet',
+                        responses: [opResponse(200, 'Pet', 'application/json'), opResponse(422, 'Problem', 'application/json'), opResponse(404)],
+                    }),
+                ]),
+            ]);
+            const out = generateSdk(root, sharedOptions);
+            expect(out).toContain('expectStatuses: [422]');
+            expect(out).toContain("| { status: 422; contentType: 'application/json'; data: Problem }");
+            expect(out).toContain('case 422:');
+        });
+
+        it('passes expectStatuses so a declared 304 does not surface as SdkError', () => {
+            const root = opRoot([
+                opRoute('/art', [opOperation('get', { sdk: 'getArt', responses: [opResponse(200, 'Art', 'application/json'), opResponse(304)] })]),
+            ]);
+            expect(generateSdk(root, sharedOptions)).toContain('expectStatuses: [304]');
+        });
+
+        it('types the throw path from the statuses that stay errors', () => {
+            const root = opRoot([
+                opRoute('/pet', [
+                    opOperation('get', {
+                        sdk: 'getPet',
+                        responses: [
+                            opResponse(200, 'Pet', 'application/json'),
+                            { ...opResponse(404, refType('Problem'), 'application/json'), emit: 'documented' as const },
+                            opResponse(500),
+                        ],
+                    }),
+                ]),
+            ]);
+            const out = generateSdk(root, sharedOptions);
+            expect(out).toContain('export type GetPetErrorBody = Problem;');
+            expect(out).toContain('/** @throws {SdkError<GetPetErrorBody>} on 404, 500 */');
+            // Documented, so it is not a return-union member.
+            expect(out).toContain('async getPet(): Promise<Pet> {');
+        });
+
+        it('emits no alias when the error statuses declare no body', () => {
+            const root = opRoot([
+                opRoute('/pet', [opOperation('get', { sdk: 'getPet', responses: [opResponse(200, 'Pet', 'application/json'), opResponse(404)] })]),
+            ]);
+            expect(generateSdk(root, sharedOptions)).not.toContain('ErrorBody');
+        });
+    });
+});
+
+describe('generateErrorBodyAliases', () => {
+    it('emits one alias per operation whose thrown statuses declare a body', () => {
+        const root = opRoot([
+            opRoute('/pet', [
+                opOperation('get', {
+                    sdk: 'getPet',
+                    responses: [
+                        opResponse(200, 'Pet', 'application/json'),
+                        { ...opResponse(404, refType('Problem'), 'application/json'), emit: 'documented' as const },
+                    ],
+                }),
+            ]),
+        ]);
+        expect(generateErrorBodyAliases(root, {})).toEqual(['export type GetPetErrorBody = Problem;']);
+    });
+
+    it('merges the bodies of several thrown statuses into one union', () => {
+        const root = opRoot([
+            opRoute('/pet', [
+                opOperation('get', {
+                    sdk: 'getPet',
+                    responses: [
+                        opResponse(200, 'Pet', 'application/json'),
+                        { ...opResponse(404, refType('NotFound'), 'application/json'), emit: 'documented' as const },
+                        { ...opResponse(500, refType('Problem'), 'application/json'), emit: 'documented' as const },
+                    ],
+                }),
+            ]),
+        ]);
+        expect(generateErrorBodyAliases(root, {})).toEqual(['export type GetPetErrorBody = NotFound | Problem;']);
+    });
+
+    it('emits nothing when the thrown statuses are bodyless', () => {
+        const root = opRoot([
+            opRoute('/pet', [opOperation('get', { sdk: 'getPet', responses: [opResponse(200, 'Pet', 'application/json'), opResponse(404)] })]),
+        ]);
+        expect(generateErrorBodyAliases(root, {})).toEqual([]);
+    });
+
+    it('skips internal operations unless asked for them', () => {
+        const responses = [
+            opResponse(200, 'Pet', 'application/json'),
+            { ...opResponse(404, refType('Problem'), 'application/json'), emit: 'documented' as const },
+        ];
+        const root = opRoot([opRoute('/pet', [opOperation('get', { sdk: 'getPet', responses })], undefined, ['internal'])]);
+        expect(generateErrorBodyAliases(root, {})).toEqual([]);
+        expect(generateErrorBodyAliases(root, { includeInternal: true })).toHaveLength(1);
+    });
 });
 
 describe('deriveClientClassName', () => {
@@ -757,9 +935,9 @@ describe('generateSdkOptions', () => {
         expect(out).toContain('headers?:');
         expect(out).toContain('fetch?: SdkFetch');
         expect(out).toContain('requestIdFactory?: () => string');
-        expect(out).toContain('export class SdkError extends Error');
+        expect(out).toContain('export class SdkError<TBody = unknown> extends Error');
         expect(out).toContain('public readonly status: number');
-        expect(out).toContain('public readonly body: unknown');
+        expect(out).toContain('public readonly body: TBody');
         expect(out).toContain('public readonly headers: Headers');
         expect(out).toContain('throw new SdkError(res.status, res.statusText, body, res.headers)');
         expect(out).toContain('export type SdkFetch');

package/tests/helpers.ts

@@ -135,7 +135,26 @@ export function opMultiRequest(entries: Array<[string, string | ContractTypeNode
 export function opResponse(statusCode: number, bodyType?: string | ContractTypeNode, contentType?: string): OpResponseNode {
     const bt: ContractTypeNode | undefined =
         bodyType === undefined ? undefined : typeof bodyType === 'string' ? parseBodyTypeString(bodyType) : bodyType;
-    return { statusCode, contentType, bodyType: bt };
+    const bodies = bt === undefined ? [] : [{ contentType: contentType ?? 'application/json', bodyType: bt }];
+    return { statusCode, bodies, ...(bt !== undefined ? { hasBlock: true } : {}) };
+}
+
+/** A status declaring several mimes, as `200: { image/png: binary, image/jpeg: binary }` parses. */
+export function opResponseMulti(
+    statusCode: number,
+    bodies: { contentType: string; bodyType: string | ContractTypeNode }[],
+    extra?: Partial<OpResponseNode>,
+): OpResponseNode {
+    const resolved = bodies.map(b => ({
+        contentType: b.contentType,
+        bodyType: typeof b.bodyType === 'string' ? parseBodyTypeString(b.bodyType) : b.bodyType,
+    }));
+    return {
+        statusCode,
+        bodies: resolved,
+        hasBlock: true,
+        ...extra,
+    };
 }
 
 function parseBodyTypeString(s: string): ContractTypeNode {