ts-procedures 5.3.0 → 5.4.0

package/build/implementations/http/hono-api/index.test.js

@@ -0,0 +1,983 @@
+import { describe, expect, test, vi } from 'vitest';
+import { Hono } from 'hono';
+import { Type } from 'typebox';
+import { Procedures } from '../../../index.js';
+import { HonoAPIAppBuilder } from './index.js';
+/**
+ * HonoAPIAppBuilder Test Suite
+ *
+ * Tests the REST-style Hono integration for ts-procedures.
+ * Uses schema.input for per-channel type-safe input validation.
+ */
+describe('HonoAPIAppBuilder', () => {
+    // --------------------------------------------------------------------------
+    // Constructor Tests
+    // --------------------------------------------------------------------------
+    describe('constructor', () => {
+        test('creates default Hono app', async () => {
+            const builder = new HonoAPIAppBuilder();
+            const API = Procedures();
+            API.Create('GetUser', {
+                path: '/users/:id',
+                method: 'get',
+                schema: {
+                    input: {
+                        pathParams: Type.Object({ id: Type.String() }),
+                    },
+                    returnType: Type.Object({ id: Type.String() }),
+                },
+            }, async (ctx, { pathParams }) => ({ id: pathParams.id }));
+            builder.register(API, () => ({ userId: '123' }));
+            const app = await builder.build();
+            const res = await app.request('/users/abc', { method: 'GET' });
+            expect(res.status).toBe(200);
+            const body = await res.json();
+            expect(body).toEqual({ id: 'abc' });
+        });
+        test('uses provided Hono app', async () => {
+            const customApp = new Hono();
+            customApp.get('/custom', (c) => c.json({ custom: true }));
+            const builder = new HonoAPIAppBuilder({ app: customApp });
+            const API = Procedures();
+            API.Create('Health', { path: '/health', method: 'get' }, async () => ({ ok: true }));
+            builder.register(API, () => ({}));
+            const app = await builder.build();
+            // Custom route still works
+            const customRes = await app.request('/custom');
+            expect(customRes.status).toBe(200);
+            expect(await customRes.json()).toEqual({ custom: true });
+            // API route works
+            const apiRes = await app.request('/health');
+            expect(apiRes.status).toBe(200);
+        });
+        test('handles empty config', () => {
+            const builder = new HonoAPIAppBuilder({});
+            expect(builder.app).toBeDefined();
+            expect(builder.docs).toEqual([]);
+        });
+    });
+    // --------------------------------------------------------------------------
+    // HTTP Methods
+    // --------------------------------------------------------------------------
+    describe('HTTP methods', () => {
+        test('GET endpoint', async () => {
+            const builder = new HonoAPIAppBuilder();
+            const API = Procedures();
+            API.Create('ListUsers', { path: '/users', method: 'get' }, async () => ({ users: [] }));
+            builder.register(API, () => ({}));
+            const app = await builder.build();
+            const res = await app.request('/users');
+            expect(res.status).toBe(200);
+            expect(await res.json()).toEqual({ users: [] });
+        });
+        test('POST endpoint returns 201 by default', async () => {
+            const builder = new HonoAPIAppBuilder();
+            const API = Procedures();
+            API.Create('CreateUser', {
+                path: '/users',
+                method: 'post',
+                schema: {
+                    input: {
+                        body: Type.Object({ name: Type.String() }),
+                    },
+                },
+            }, async (ctx, { body }) => ({ id: '123', name: body.name }));
+            builder.register(API, () => ({}));
+            const app = await builder.build();
+            const res = await app.request('/users', {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify({ name: 'John' }),
+            });
+            expect(res.status).toBe(201);
+            expect(await res.json()).toEqual({ id: '123', name: 'John' });
+        });
+        test('PUT endpoint returns 200 by default', async () => {
+            const builder = new HonoAPIAppBuilder();
+            const API = Procedures();
+            API.Create('UpdateUser', {
+                path: '/users/:id',
+                method: 'put',
+                schema: {
+                    input: {
+                        pathParams: Type.Object({ id: Type.String() }),
+                        body: Type.Object({ name: Type.String() }),
+                    },
+                },
+            }, async (ctx, { pathParams, body }) => ({ id: pathParams.id, name: body.name }));
+            builder.register(API, () => ({}));
+            const app = await builder.build();
+            const res = await app.request('/users/abc', {
+                method: 'PUT',
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify({ name: 'Jane' }),
+            });
+            expect(res.status).toBe(200);
+            expect(await res.json()).toEqual({ id: 'abc', name: 'Jane' });
+        });
+        test('PATCH endpoint', async () => {
+            const builder = new HonoAPIAppBuilder();
+            const API = Procedures();
+            API.Create('PatchUser', {
+                path: '/users/:id',
+                method: 'patch',
+                schema: {
+                    input: {
+                        pathParams: Type.Object({ id: Type.String() }),
+                        body: Type.Object({ name: Type.Optional(Type.String()) }),
+                    },
+                },
+            }, async (ctx, { pathParams, body }) => ({ id: pathParams.id, ...body }));
+            builder.register(API, () => ({}));
+            const app = await builder.build();
+            const res = await app.request('/users/abc', {
+                method: 'PATCH',
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify({ name: 'Updated' }),
+            });
+            expect(res.status).toBe(200);
+            expect(await res.json()).toEqual({ id: 'abc', name: 'Updated' });
+        });
+        test('DELETE endpoint returns 204 by default', async () => {
+            const builder = new HonoAPIAppBuilder();
+            const API = Procedures();
+            API.Create('DeleteUser', {
+                path: '/users/:id',
+                method: 'delete',
+                schema: {
+                    input: {
+                        pathParams: Type.Object({ id: Type.String() }),
+                    },
+                },
+            }, async (ctx, { pathParams }) => undefined);
+            builder.register(API, () => ({}));
+            const app = await builder.build();
+            const res = await app.request('/users/abc', { method: 'DELETE' });
+            expect(res.status).toBe(204);
+            // 204 responses have no body
+            expect(await res.text()).toBe('');
+        });
+        test('custom successStatus overrides default', async () => {
+            const builder = new HonoAPIAppBuilder();
+            const API = Procedures();
+            API.Create('CreateUser', {
+                path: '/users',
+                method: 'post',
+                successStatus: 200, // override default 201
+            }, async () => ({ id: '123' }));
+            builder.register(API, () => ({}));
+            const app = await builder.build();
+            const res = await app.request('/users', {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify({}),
+            });
+            expect(res.status).toBe(200);
+        });
+        test('wrong HTTP method returns 404', async () => {
+            const builder = new HonoAPIAppBuilder();
+            const API = Procedures();
+            API.Create('GetUser', { path: '/users', method: 'get' }, async () => ({ ok: true }));
+            builder.register(API, () => ({}));
+            const app = await builder.build();
+            // POST to a GET-only endpoint
+            const res = await app.request('/users', {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify({}),
+            });
+            expect(res.status).toBe(404);
+        });
+    });
+    // --------------------------------------------------------------------------
+    // schema.input — Multi-Channel Input
+    // --------------------------------------------------------------------------
+    describe('schema.input — multi-channel input', () => {
+        test('pathParams extraction and validation', async () => {
+            const builder = new HonoAPIAppBuilder();
+            const API = Procedures();
+            API.Create('GetUser', {
+                path: '/users/:id',
+                method: 'get',
+                schema: {
+                    input: {
+                        pathParams: Type.Object({ id: Type.String() }),
+                    },
+                },
+            }, async (ctx, { pathParams }) => ({ id: pathParams.id }));
+            builder.register(API, () => ({}));
+            const app = await builder.build();
+            const res = await app.request('/users/user-123');
+            expect(res.status).toBe(200);
+            expect(await res.json()).toEqual({ id: 'user-123' });
+        });
+        test('query params extraction and validation', async () => {
+            const builder = new HonoAPIAppBuilder();
+            const API = Procedures();
+            API.Create('SearchUsers', {
+                path: '/users',
+                method: 'get',
+                schema: {
+                    input: {
+                        query: Type.Object({
+                            page: Type.Number(),
+                            limit: Type.Number(),
+                        }),
+                    },
+                },
+            }, async (ctx, { query }) => ({ page: query.page, limit: query.limit }));
+            builder.register(API, () => ({}));
+            const app = await builder.build();
+            // AJV coerceTypes converts string "2" to number 2
+            const res = await app.request('/users?page=2&limit=10');
+            expect(res.status).toBe(200);
+            expect(await res.json()).toEqual({ page: 2, limit: 10 });
+        });
+        test('body extraction and validation', async () => {
+            const builder = new HonoAPIAppBuilder();
+            const API = Procedures();
+            API.Create('CreateUser', {
+                path: '/users',
+                method: 'post',
+                schema: {
+                    input: {
+                        body: Type.Object({
+                            name: Type.String(),
+                            email: Type.String(),
+                        }),
+                    },
+                },
+            }, async (ctx, { body }) => ({ id: '1', name: body.name, email: body.email }));
+            builder.register(API, () => ({}));
+            const app = await builder.build();
+            const res = await app.request('/users', {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify({ name: 'John', email: 'john@example.com' }),
+            });
+            expect(res.status).toBe(201);
+            expect(await res.json()).toEqual({ id: '1', name: 'John', email: 'john@example.com' });
+        });
+        test('headers extraction and validation', async () => {
+            const builder = new HonoAPIAppBuilder();
+            const API = Procedures();
+            API.Create('WebhookReceiver', {
+                path: '/webhooks',
+                method: 'post',
+                schema: {
+                    input: {
+                        headers: Type.Object({ 'x-webhook-secret': Type.String() }),
+                        body: Type.Object({ event: Type.String() }),
+                    },
+                },
+            }, async (ctx, { headers, body }) => ({
+                received: body.event,
+                secret: headers['x-webhook-secret'],
+            }));
+            builder.register(API, () => ({}));
+            const app = await builder.build();
+            const res = await app.request('/webhooks', {
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/json',
+                    'X-Webhook-Secret': 'my-secret',
+                },
+                body: JSON.stringify({ event: 'user.created' }),
+            });
+            expect(res.status).toBe(201);
+            const body = await res.json();
+            expect(body.received).toBe('user.created');
+            expect(body.secret).toBe('my-secret');
+        });
+        test('combined: pathParams + query + body', async () => {
+            const builder = new HonoAPIAppBuilder();
+            const API = Procedures();
+            API.Create('UpdateUserField', {
+                path: '/users/:id',
+                method: 'put',
+                schema: {
+                    input: {
+                        pathParams: Type.Object({ id: Type.String() }),
+                        query: Type.Object({ notify: Type.Optional(Type.Boolean()) }),
+                        body: Type.Object({ field: Type.String(), value: Type.String() }),
+                    },
+                },
+            }, async (ctx, { pathParams, query, body }) => ({
+                userId: pathParams.id,
+                updated: { [body.field]: body.value },
+                notified: query.notify ?? false,
+            }));
+            builder.register(API, () => ({}));
+            const app = await builder.build();
+            const res = await app.request('/users/u-42?notify=true', {
+                method: 'PUT',
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify({ field: 'name', value: 'Jane' }),
+            });
+            expect(res.status).toBe(200);
+            expect(await res.json()).toEqual({
+                userId: 'u-42',
+                updated: { name: 'Jane' },
+                notified: true,
+            });
+        });
+        test('coerceTypes converts query string values to schema types', async () => {
+            const builder = new HonoAPIAppBuilder();
+            const API = Procedures();
+            API.Create('Search', {
+                path: '/items',
+                method: 'get',
+                schema: {
+                    input: {
+                        query: Type.Object({
+                            page: Type.Number(),
+                            active: Type.Boolean(),
+                        }),
+                    },
+                },
+            }, async (ctx, { query }) => ({
+                page: query.page,
+                active: query.active,
+                pageType: typeof query.page,
+                activeType: typeof query.active,
+            }));
+            builder.register(API, () => ({}));
+            const app = await builder.build();
+            const res = await app.request('/items?page=3&active=true');
+            expect(res.status).toBe(200);
+            const body = await res.json();
+            expect(body.page).toBe(3);
+            expect(body.active).toBe(true);
+            expect(body.pageType).toBe('number');
+            expect(body.activeType).toBe('boolean');
+        });
+        test('removeAdditional strips extra fields from body', async () => {
+            const builder = new HonoAPIAppBuilder();
+            const API = Procedures();
+            API.Create('CreateItem', {
+                path: '/items',
+                method: 'post',
+                schema: {
+                    input: {
+                        body: Type.Object({ name: Type.String() }, { additionalProperties: false }),
+                    },
+                },
+            }, async (ctx, { body }) => body);
+            builder.register(API, () => ({}));
+            const app = await builder.build();
+            const res = await app.request('/items', {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify({ name: 'Widget', extraField: 'should-be-stripped', anotherOne: 42 }),
+            });
+            expect(res.status).toBe(201);
+            const body = await res.json();
+            // AJV removeAdditional strips properties not in schema when additionalProperties: false
+            expect(body).toEqual({ name: 'Widget' });
+            expect(body).not.toHaveProperty('extraField');
+            expect(body).not.toHaveProperty('anotherOne');
+        });
+        test('removeAdditional strips non-declared headers', async () => {
+            const builder = new HonoAPIAppBuilder();
+            const API = Procedures();
+            API.Create('Webhook', {
+                path: '/hook',
+                method: 'post',
+                schema: {
+                    input: {
+                        headers: Type.Object({ 'x-signature': Type.String() }, { additionalProperties: false }),
+                        body: Type.Object({ event: Type.String() }),
+                    },
+                },
+            }, async (ctx, { headers }) => ({ keys: Object.keys(headers) }));
+            builder.register(API, () => ({}));
+            const app = await builder.build();
+            const res = await app.request('/hook', {
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/json',
+                    'X-Signature': 'abc123',
+                    'X-Other-Header': 'should-be-stripped',
+                },
+                body: JSON.stringify({ event: 'test' }),
+            });
+            expect(res.status).toBe(201);
+            const body = await res.json();
+            // Only x-signature should remain after removeAdditional
+            expect(body.keys).toEqual(['x-signature']);
+        });
+        test('validation error includes channel name', async () => {
+            const builder = new HonoAPIAppBuilder();
+            const API = Procedures();
+            API.Create('CreateItem', {
+                path: '/items',
+                method: 'post',
+                schema: {
+                    input: {
+                        body: Type.Object({
+                            name: Type.String(),
+                            price: Type.Number(),
+                        }),
+                    },
+                },
+            }, async (ctx, { body }) => body);
+            builder.register(API, () => ({}));
+            const app = await builder.build();
+            const res = await app.request('/items', {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify({ name: 'Widget' }), // missing required 'price'
+            });
+            expect(res.status).toBe(500);
+            const body = await res.json();
+            expect(body.error).toContain('input.body');
+        });
+    });
+    // --------------------------------------------------------------------------
+    // schema.params — Flat Input (backwards-compatible path)
+    // --------------------------------------------------------------------------
+    describe('schema.params — flat input', () => {
+        test('POST with schema.params reads from body', async () => {
+            const builder = new HonoAPIAppBuilder();
+            const API = Procedures();
+            API.Create('CreateItem', {
+                path: '/items',
+                method: 'post',
+                schema: { params: Type.Object({ name: Type.String() }) },
+            }, async (ctx, params) => ({ name: params.name }));
+            builder.register(API, () => ({}));
+            const app = await builder.build();
+            const res = await app.request('/items', {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify({ name: 'Widget' }),
+            });
+            expect(res.status).toBe(201);
+            expect(await res.json()).toEqual({ name: 'Widget' });
+        });
+        test('GET with schema.params reads from query', async () => {
+            const builder = new HonoAPIAppBuilder();
+            const API = Procedures();
+            API.Create('SearchItems', {
+                path: '/items',
+                method: 'get',
+                schema: {
+                    params: Type.Object({ q: Type.String() }),
+                },
+            }, async (ctx, params) => ({ query: params.q }));
+            builder.register(API, () => ({}));
+            const app = await builder.build();
+            const res = await app.request('/items?q=widget');
+            expect(res.status).toBe(200);
+            expect(await res.json()).toEqual({ query: 'widget' });
+        });
+    });
+    // --------------------------------------------------------------------------
+    // pathPrefix Option
+    // --------------------------------------------------------------------------
+    describe('pathPrefix', () => {
+        test('prepends prefix to all routes', async () => {
+            const builder = new HonoAPIAppBuilder({ pathPrefix: '/api/v1' });
+            const API = Procedures();
+            API.Create('Health', { path: '/health', method: 'get' }, async () => ({ ok: true }));
+            builder.register(API, () => ({}));
+            const app = await builder.build();
+            const res = await app.request('/api/v1/health');
+            expect(res.status).toBe(200);
+            // Without prefix → 404
+            const res2 = await app.request('/health');
+            expect(res2.status).toBe(404);
+        });
+        test('pathPrefix normalizes missing leading slash', async () => {
+            const builder = new HonoAPIAppBuilder({ pathPrefix: 'api' });
+            const API = Procedures();
+            API.Create('Health', { path: '/health', method: 'get' }, async () => ({ ok: true }));
+            builder.register(API, () => ({}));
+            const app = await builder.build();
+            const res = await app.request('/api/health');
+            expect(res.status).toBe(200);
+        });
+        test('pathPrefix appears in docs fullPath', async () => {
+            const builder = new HonoAPIAppBuilder({ pathPrefix: '/api' });
+            const API = Procedures();
+            API.Create('GetUser', { path: '/users/:id', method: 'get' }, async () => ({}));
+            builder.register(API, () => ({}));
+            await builder.build();
+            expect(builder.docs[0].fullPath).toBe('/api/users/:id');
+            expect(builder.docs[0].path).toBe('/users/:id');
+        });
+    });
+    // --------------------------------------------------------------------------
+    // Lifecycle Hooks
+    // --------------------------------------------------------------------------
+    describe('lifecycle hooks', () => {
+        test('onRequestStart and onRequestEnd are called', async () => {
+            const order = [];
+            const builder = new HonoAPIAppBuilder({
+                onRequestStart: () => order.push('start'),
+                onRequestEnd: () => order.push('end'),
+            });
+            const API = Procedures();
+            API.Create('Test', { path: '/test', method: 'get' }, async () => {
+                order.push('handler');
+                return { ok: true };
+            });
+            builder.register(API, () => ({}));
+            const app = await builder.build();
+            await app.request('/test');
+            expect(order).toEqual(['start', 'handler', 'end']);
+        });
+        test('onSuccess is called on successful execution', async () => {
+            const onSuccess = vi.fn();
+            const builder = new HonoAPIAppBuilder({ onSuccess });
+            const API = Procedures();
+            API.Create('Test', { path: '/test', method: 'get' }, async () => ({ ok: true }));
+            builder.register(API, () => ({}));
+            const app = await builder.build();
+            await app.request('/test');
+            expect(onSuccess).toHaveBeenCalledTimes(1);
+            expect(onSuccess.mock.calls[0][0]).toHaveProperty('name', 'Test');
+        });
+        test('onSuccess is NOT called when handler throws', async () => {
+            const onSuccess = vi.fn();
+            const builder = new HonoAPIAppBuilder({ onSuccess });
+            const API = Procedures();
+            API.Create('Test', { path: '/test', method: 'get' }, async () => {
+                throw new Error('oops');
+            });
+            builder.register(API, () => ({}));
+            const app = await builder.build();
+            await app.request('/test');
+            expect(onSuccess).not.toHaveBeenCalled();
+        });
+    });
+    // --------------------------------------------------------------------------
+    // Error Handling
+    // --------------------------------------------------------------------------
+    describe('error handling', () => {
+        test('custom error handler receives procedure, context, and error', async () => {
+            const errorHandler = vi.fn((procedure, c, error) => {
+                return c.json({ customError: error.message }, 400);
+            });
+            const builder = new HonoAPIAppBuilder({ onError: errorHandler });
+            const API = Procedures();
+            API.Create('Test', { path: '/test', method: 'get' }, async () => {
+                throw new Error('Test error');
+            });
+            builder.register(API, () => ({}));
+            const app = await builder.build();
+            const res = await app.request('/test');
+            expect(errorHandler).toHaveBeenCalledTimes(1);
+            expect(res.status).toBe(400);
+            const body = await res.json();
+            expect(body.customError).toContain('Test error');
+        });
+        test('default error handling returns 500 with message', async () => {
+            const builder = new HonoAPIAppBuilder();
+            const API = Procedures();
+            API.Create('Test', { path: '/test', method: 'get' }, async () => {
+                throw new Error('Something broke');
+            });
+            builder.register(API, () => ({}));
+            const app = await builder.build();
+            const res = await app.request('/test');
+            expect(res.status).toBe(500);
+            const body = await res.json();
+            expect(body.error).toContain('Something broke');
+        });
+    });
+    // --------------------------------------------------------------------------
+    // register() Method
+    // --------------------------------------------------------------------------
+    describe('register() method', () => {
+        test('returns this for method chaining', () => {
+            const builder = new HonoAPIAppBuilder();
+            const API1 = Procedures();
+            const API2 = Procedures();
+            const result = builder.register(API1, () => ({})).register(API2, () => ({}));
+            expect(result).toBe(builder);
+        });
+        test('supports multiple factories with different contexts', async () => {
+            const builder = new HonoAPIAppBuilder();
+            const PublicAPI = Procedures();
+            const AuthAPI = Procedures();
+            PublicAPI.Create('GetHealth', { path: '/health', method: 'get' }, async (ctx) => ({ public: ctx.public }));
+            AuthAPI.Create('GetProfile', { path: '/profile', method: 'get' }, async (ctx) => ({ userId: ctx.userId }));
+            builder
+                .register(PublicAPI, () => ({ public: true }))
+                .register(AuthAPI, (c) => ({ userId: c.req.header('x-user-id') || 'anon' }));
+            const app = await builder.build();
+            const healthRes = await app.request('/health');
+            expect(await healthRes.json()).toEqual({ public: true });
+            const profileRes = await app.request('/profile', {
+                headers: { 'X-User-Id': 'user-42' },
+            });
+            expect(await profileRes.json()).toEqual({ userId: 'user-42' });
+        });
+        test('factoryContext can be a static object', async () => {
+            const builder = new HonoAPIAppBuilder();
+            const API = Procedures();
+            API.Create('GetId', { path: '/id', method: 'get' }, async (ctx) => ({ id: ctx.requestId }));
+            builder.register(API, { requestId: 'static-123' });
+            const app = await builder.build();
+            const res = await app.request('/id');
+            expect(await res.json()).toEqual({ id: 'static-123' });
+        });
+        test('factoryContext can be async', async () => {
+            const builder = new HonoAPIAppBuilder();
+            const API = Procedures();
+            API.Create('GetId', { path: '/id', method: 'get' }, async (ctx) => ({ id: ctx.requestId }));
+            builder.register(API, async () => ({ requestId: 'async-456' }));
+            const app = await builder.build();
+            const res = await app.request('/id');
+            expect(await res.json()).toEqual({ id: 'async-456' });
+        });
+    });
+    // --------------------------------------------------------------------------
+    // Path Param Consistency Validation
+    // --------------------------------------------------------------------------
+    describe('path param consistency validation', () => {
+        test('throws when path has params but schema.input.pathParams is missing', async () => {
+            const builder = new HonoAPIAppBuilder();
+            const API = Procedures();
+            API.Create('GetUser', {
+                path: '/users/:id',
+                method: 'get',
+                schema: {
+                    input: {
+                        query: Type.Object({ include: Type.Optional(Type.String()) }),
+                    },
+                },
+            }, async () => ({}));
+            builder.register(API, () => ({}));
+            await expect(builder.build()).rejects.toThrow(/pathParams is not defined/);
+        });
+        test('throws when schema.input.pathParams defined but path has no params', async () => {
+            const builder = new HonoAPIAppBuilder();
+            const API = Procedures();
+            API.Create('ListUsers', {
+                path: '/users',
+                method: 'get',
+                schema: {
+                    input: {
+                        pathParams: Type.Object({ id: Type.String() }),
+                    },
+                },
+            }, async () => ({}));
+            builder.register(API, () => ({}));
+            await expect(builder.build()).rejects.toThrow(/has no path parameters/);
+        });
+        test('no error when path has params and pathParams schema matches', async () => {
+            const builder = new HonoAPIAppBuilder();
+            const API = Procedures();
+            API.Create('GetUser', {
+                path: '/users/:id',
+                method: 'get',
+                schema: {
+                    input: {
+                        pathParams: Type.Object({ id: Type.String() }),
+                    },
+                },
+            }, async (ctx, { pathParams }) => ({ id: pathParams.id }));
+            builder.register(API, () => ({}));
+            await expect(builder.build()).resolves.toBeDefined();
+        });
+        test('throws when pathParams schema keys do not match path param names', async () => {
+            const builder = new HonoAPIAppBuilder();
+            const API = Procedures();
+            // Path has :id but schema declares userId
+            API.Create('GetUser', {
+                path: '/users/:id',
+                method: 'get',
+                schema: {
+                    input: {
+                        pathParams: Type.Object({ userId: Type.String() }),
+                    },
+                },
+            }, async () => ({}));
+            builder.register(API, () => ({}));
+            await expect(builder.build()).rejects.toThrow(/Path param mismatch/);
+        });
+        test('throws when path has multiple params and schema is missing one', async () => {
+            const builder = new HonoAPIAppBuilder();
+            const API = Procedures();
+            API.Create('GetComment', {
+                path: '/users/:userId/posts/:postId/comments/:commentId',
+                method: 'get',
+                schema: {
+                    input: {
+                        // Missing commentId
+                        pathParams: Type.Object({ userId: Type.String(), postId: Type.String() }),
+                    },
+                },
+            }, async () => ({}));
+            builder.register(API, () => ({}));
+            await expect(builder.build()).rejects.toThrow(/commentId/);
+        });
+        test('no validation when schema.input is not used', async () => {
+            const builder = new HonoAPIAppBuilder();
+            const API = Procedures();
+            // Using schema.params (flat mode) with path params — no consistency check
+            API.Create('GetUser', {
+                path: '/users/:id',
+                method: 'get',
+            }, async () => ({ ok: true }));
+            builder.register(API, () => ({}));
+            await expect(builder.build()).resolves.toBeDefined();
+        });
+    });
+    // --------------------------------------------------------------------------
+    // Route Documentation
+    // --------------------------------------------------------------------------
+    describe('route documentation', () => {
+        test('generates docs with per-channel jsonSchema from schema.input', async () => {
+            const builder = new HonoAPIAppBuilder();
+            const API = Procedures();
+            API.Create('UpdateUser', {
+                path: '/users/:id',
+                method: 'put',
+                schema: {
+                    input: {
+                        pathParams: Type.Object({ id: Type.String() }),
+                        body: Type.Object({ name: Type.String() }),
+                    },
+                    returnType: Type.Object({ ok: Type.Boolean() }),
+                },
+            }, async () => ({ ok: true }));
+            builder.register(API, () => ({}));
+            await builder.build();
+            const doc = builder.docs[0];
+            expect(doc.name).toBe('UpdateUser');
+            expect(doc.path).toBe('/users/:id');
+            expect(doc.method).toBe('put');
+            expect(doc.fullPath).toBe('/users/:id');
+            expect(doc.jsonSchema.pathParams).toBeDefined();
+            expect(doc.jsonSchema.body).toBeDefined();
+            expect(doc.jsonSchema.response).toBeDefined();
+            expect(doc.jsonSchema.query).toBeUndefined();
+        });
+        test('generates docs from schema.params (flat mode)', async () => {
+            const builder = new HonoAPIAppBuilder();
+            const API = Procedures();
+            API.Create('CreateItem', {
+                path: '/items',
+                method: 'post',
+                schema: {
+                    params: Type.Object({ name: Type.String() }),
+                    returnType: Type.Object({ id: Type.String() }),
+                },
+            }, async (ctx, params) => ({ id: '1' }));
+            builder.register(API, () => ({}));
+            await builder.build();
+            const doc = builder.docs[0];
+            // POST with schema.params → body in docs
+            expect(doc.jsonSchema.body).toBeDefined();
+            expect(doc.jsonSchema.response).toBeDefined();
+        });
+        test('extendProcedureDoc adds custom properties', async () => {
+            const builder = new HonoAPIAppBuilder();
+            const API = Procedures();
+            API.Create('GetUser', { path: '/users/:id', method: 'get' }, async () => ({}));
+            builder.register(API, () => ({}), ({ base, procedure }) => ({
+                tags: ['users'],
+                summary: `Get user by ID`,
+                operationId: procedure.name,
+            }));
+            await builder.build();
+            const doc = builder.docs[0];
+            expect(doc).toHaveProperty('tags', ['users']);
+            expect(doc).toHaveProperty('summary', 'Get user by ID');
+            expect(doc).toHaveProperty('operationId', 'GetUser');
+        });
+        test('base properties take precedence over extended properties', async () => {
+            const builder = new HonoAPIAppBuilder();
+            const API = Procedures();
+            API.Create('Test', { path: '/test', method: 'get' }, async () => ({}));
+            builder.register(API, () => ({}), () => ({
+                name: 'Overridden',
+                method: 'post',
+                customField: 'custom-value',
+            }));
+            await builder.build();
+            const doc = builder.docs[0];
+            expect(doc.name).toBe('Test');
+            expect(doc.method).toBe('get');
+            expect(doc).toHaveProperty('customField', 'custom-value');
+        });
+    });
+    // --------------------------------------------------------------------------
+    // Query Parser Override
+    // --------------------------------------------------------------------------
+    describe('query parser', () => {
+        test('custom queryParser is used', async () => {
+            const customParser = vi.fn((qs) => {
+                const params = new URLSearchParams(qs);
+                const result = {};
+                for (const [key, value] of params) {
+                    result[key] = value.toUpperCase(); // custom behavior
+                }
+                return result;
+            });
+            const builder = new HonoAPIAppBuilder({ queryParser: customParser });
+            const API = Procedures();
+            API.Create('Search', {
+                path: '/search',
+                method: 'get',
+                schema: {
+                    input: {
+                        query: Type.Object({ q: Type.String() }),
+                    },
+                },
+            }, async (ctx, { query }) => ({ query: query.q }));
+            builder.register(API, () => ({}));
+            const app = await builder.build();
+            const res = await app.request('/search?q=hello');
+            expect(res.status).toBe(200);
+            expect(await res.json()).toEqual({ query: 'HELLO' });
+            expect(customParser).toHaveBeenCalledWith('q=hello');
+        });
+    });
+    // --------------------------------------------------------------------------
+    // Core schema.input Mutual Exclusivity
+    // --------------------------------------------------------------------------
+    describe('core schema.input mutual exclusivity', () => {
+        test('throws when both schema.params and schema.input are defined', () => {
+            const API = Procedures();
+            expect(() => {
+                API.Create('Bad', {
+                    path: '/bad',
+                    method: 'get',
+                    schema: {
+                        params: Type.Object({ a: Type.String() }),
+                        input: {
+                            query: Type.Object({ b: Type.String() }),
+                        },
+                    },
+                }, async () => ({}));
+            }).toThrow(/mutually exclusive/);
+        });
+    });
+    // --------------------------------------------------------------------------
+    // Integration Test
+    // --------------------------------------------------------------------------
+    describe('integration', () => {
+        test('full REST API with multiple endpoints and contexts', async () => {
+            const PublicAPI = Procedures();
+            const AuthAPI = Procedures();
+            PublicAPI.Create('ListProducts', {
+                path: '/products',
+                method: 'get',
+                schema: {
+                    input: {
+                        query: Type.Object({
+                            page: Type.Optional(Type.Number({ default: 1 })),
+                        }),
+                    },
+                    returnType: Type.Object({ products: Type.Array(Type.String()), page: Type.Number() }),
+                },
+            }, async (ctx, { query }) => ({
+                products: ['Widget', 'Gadget'],
+                page: query.page ?? 1,
+            }));
+            AuthAPI.Create('GetProduct', {
+                path: '/products/:id',
+                method: 'get',
+                schema: {
+                    input: {
+                        pathParams: Type.Object({ id: Type.String() }),
+                    },
+                    returnType: Type.Object({ id: Type.String(), viewer: Type.String() }),
+                },
+            }, async (ctx, { pathParams }) => ({
+                id: pathParams.id,
+                viewer: ctx.userId,
+            }));
+            AuthAPI.Create('CreateProduct', {
+                path: '/products',
+                method: 'post',
+                schema: {
+                    input: {
+                        body: Type.Object({
+                            name: Type.String(),
+                            price: Type.Number(),
+                        }),
+                    },
+                    returnType: Type.Object({ id: Type.String(), name: Type.String(), createdBy: Type.String() }),
+                },
+            }, async (ctx, { body }) => ({
+                id: 'prod-new',
+                name: body.name,
+                createdBy: ctx.userId,
+            }));
+            AuthAPI.Create('DeleteProduct', {
+                path: '/products/:id',
+                method: 'delete',
+                schema: {
+                    input: {
+                        pathParams: Type.Object({ id: Type.String() }),
+                    },
+                },
+            }, async (ctx, { pathParams }) => undefined);
+            const events = [];
+            const builder = new HonoAPIAppBuilder({
+                pathPrefix: '/api',
+                onRequestStart: () => events.push('request-start'),
+                onRequestEnd: () => events.push('request-end'),
+                onSuccess: (proc) => events.push(`success:${proc.name}`),
+            });
+            builder
+                .register(PublicAPI, () => ({ source: 'public' }))
+                .register(AuthAPI, (c) => ({
+                source: 'auth',
+                userId: c.req.header('x-user-id') || 'anon',
+            }));
+            const app = await builder.build();
+            // GET /api/products?page=2
+            const listRes = await app.request('/api/products?page=2');
+            expect(listRes.status).toBe(200);
+            expect(await listRes.json()).toEqual({ products: ['Widget', 'Gadget'], page: 2 });
+            // GET /api/products/prod-1
+            const getRes = await app.request('/api/products/prod-1', {
+                headers: { 'X-User-Id': 'user-42' },
+            });
+            expect(getRes.status).toBe(200);
+            expect(await getRes.json()).toEqual({ id: 'prod-1', viewer: 'user-42' });
+            // POST /api/products
+            const createRes = await app.request('/api/products', {
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/json',
+                    'X-User-Id': 'user-42',
+                },
+                body: JSON.stringify({ name: 'New Product', price: 29.99 }),
+            });
+            expect(createRes.status).toBe(201);
+            expect(await createRes.json()).toEqual({
+                id: 'prod-new',
+                name: 'New Product',
+                createdBy: 'user-42',
+            });
+            // DELETE /api/products/prod-1
+            const deleteRes = await app.request('/api/products/prod-1', {
+                method: 'DELETE',
+                headers: { 'X-User-Id': 'user-42' },
+            });
+            expect(deleteRes.status).toBe(204);
+            // Verify docs
+            expect(builder.docs).toHaveLength(4);
+            const paths = builder.docs.map((d) => `${d.method.toUpperCase()} ${d.fullPath}`);
+            expect(paths).toContain('GET /api/products');
+            expect(paths).toContain('GET /api/products/:id');
+            expect(paths).toContain('POST /api/products');
+            expect(paths).toContain('DELETE /api/products/:id');
+            // Verify hooks
+            expect(events).toContain('request-start');
+            expect(events).toContain('success:ListProducts');
+            expect(events).toContain('success:GetProduct');
+            expect(events).toContain('success:CreateProduct');
+            expect(events).toContain('success:DeleteProduct');
+            expect(events).toContain('request-end');
+        });
+    });
+});
+//# sourceMappingURL=index.test.js.map