@spfn/core 0.1.0-alpha.88 → 0.2.0-beta.10

package/dist/route/index.d.ts

@@ -1,40 +1,894 @@
-export { A as AutoRouteLoader, R as RouteInfo, a as RouteStats, l as loadRoutes } from '../auto-loader-JFaZ9gON.js';
-import { Context, Hono, MiddlewareHandler } from 'hono';
-import { a as RouteContract, R as RouteContext, b as RouteHandler } from '../types-BXibIEyj.js';
-export { c as HeaderRecord, H as HttpMethod, I as InferContract, d as RouteMeta, i as isHttpMethod } from '../types-BXibIEyj.js';
-export { ApiErrorResponse, ApiErrorSchema, ApiResponse, ApiResponseSchema, ApiSuccessResponse, ApiSuccessSchema } from '../types/index.js';
-import 'hono/utils/http-status';
-import '@sinclair/typebox';
+import * as _sinclair_typebox from '@sinclair/typebox';
+import { TSchema, Static, Kind } from '@sinclair/typebox';
+import { Context, MiddlewareHandler, Hono } from 'hono';
+import { ContentfulStatusCode, RedirectStatusCode } from 'hono/utils/http-status';
+import { HttpMethod } from './types.js';
 
 /**
- * Contract-based Route Handler Wrapper
+ * Route Input Types
  *
- * Binds a contract to a route handler, providing automatic validation
- * and type-safe context creation.
+ * Defines the structure for route input validation schemas
+ */
+
+/**
+ * Route input schemas
+ *
+ * Defines validation schemas for different parts of an HTTP request
+ */
+type RouteInput = {
+    /** Path parameters (e.g., /users/:id) */
+    params?: TSchema;
+    /** Query string parameters (e.g., ?page=1&limit=20) */
+    query?: TSchema;
+    /** Request body (JSON) */
+    body?: TSchema;
+    /** Form data (multipart/form-data) for file uploads */
+    formData?: TSchema;
+    /** HTTP headers */
+    headers?: TSchema;
+    /** Cookies */
+    cookies?: TSchema;
+};
+
+/**
+ * Route Builder Context
+ *
+ * Provides structured input access and response helpers for route handlers
+ */
+
+/**
+ * Paginated response structure
+ */
+type PaginatedResult<T> = {
+    items: T[];
+    pagination: {
+        page: number;
+        limit: number;
+        total: number;
+        totalPages: number;
+    };
+};
+/**
+ * Merge input with interceptor-injected fields
+ * Server receives both client input and interceptor-injected fields
+ *
+ * @example
+ * ```ts
+ * type ClientInput = { body: { email: string, password: string } };
+ * type InterceptorInput = { body: { publicKey: string, keyId: string } };
+ * // MergedInput = { body: { email: string, password: string, publicKey: string, keyId: string } }
+ * ```
+ */
+type MergedInput<TInput extends RouteInput, TInterceptor extends RouteInput> = {
+    params: (TInput['params'] extends TSchema ? Static<TInput['params']> : {}) & (TInterceptor['params'] extends TSchema ? Static<TInterceptor['params']> : {});
+    query: (TInput['query'] extends TSchema ? Static<TInput['query']> : {}) & (TInterceptor['query'] extends TSchema ? Static<TInterceptor['query']> : {});
+    body: (TInput['body'] extends TSchema ? Static<TInput['body']> : {}) & (TInterceptor['body'] extends TSchema ? Static<TInterceptor['body']> : {});
+    formData: (TInput['formData'] extends TSchema ? Static<TInput['formData']> : {}) & (TInterceptor['formData'] extends TSchema ? Static<TInterceptor['formData']> : {});
+    headers: (TInput['headers'] extends TSchema ? Static<TInput['headers']> : {}) & (TInterceptor['headers'] extends TSchema ? Static<TInterceptor['headers']> : {});
+    cookies: (TInput['cookies'] extends TSchema ? Static<TInput['cookies']> : {}) & (TInterceptor['cookies'] extends TSchema ? Static<TInterceptor['cookies']> : {});
+};
+/**
+ * RouteBuilderContext - define-route dedicated context
+ *
+ * Provides structured input access through data() method
+ */
+type RouteBuilderContext<TInput extends RouteInput = RouteInput, TInterceptor extends RouteInput = {}> = {
+    /**
+     * Get structured input data
+     *
+     * Returns an object with separate params, query, body, headers, cookies
+     * If interceptor fields are defined, they are merged with input fields
+     *
+     * @example
+     * ```ts
+     * // GET /users/:id?page=1
+     * const { params, query } = await c.data();
+     * // params = { id: string }
+     * // query = { page: number }
+     *
+     * // POST /users with headers
+     * const { body, headers } = await c.data();
+     * // body = { name: string }
+     * // headers = { authorization: string }
+     *
+     * // With interceptor-injected fields
+     * const { body } = await c.data();
+     * // body = { email: string, password: string, publicKey: string, keyId: string }
+     * ```
+     */
+    data(): Promise<MergedInput<TInput, TInterceptor>>;
+    /**
+     * Return JSON response with custom status and headers
+     *
+     * @example
+     * ```ts
+     * return c.json({ message: 'Custom response' }, 200);
+     * ```
+     */
+    json(data: unknown, status?: ContentfulStatusCode, headers?: Record<string, string | string[]>): Response;
+    /**
+     * Return 201 Created response with optional Location header
+     * Returns data directly for type inference
+     *
+     * @example
+     * ```ts
+     * const user = await createUser(body);
+     * return c.created(user, `/users/${user.id}`);
+     * // Response: 201 Created
+     * // Header: Location: /users/123
+     * // Body: { id: '123', name: 'John' }
+     * // Type: User (inferred from data)
+     * ```
+     */
+    created<T>(data: T, location?: string): T;
+    /**
+     * Return 202 Accepted response
+     * Returns data directly for type inference
+     *
+     * @example
+     * ```ts
+     * // With data
+     * return c.accepted({ jobId: '123' });
+     * // Response: 202 Accepted, Body: { jobId: '123' }
+     * // Type: { jobId: string }
+     *
+     * // Without data
+     * return c.accepted();
+     * // Response: 202 Accepted, Body: (empty)
+     * // Type: void
+     * ```
+     */
+    accepted(): void;
+    accepted<T>(data: T): T;
+    /**
+     * Return 204 No Content response (empty body)
+     *
+     * @example
+     * ```ts
+     * await deleteUser(id);
+     * return c.noContent();
+     * // Response: 204 No Content, Body: (empty)
+     * // Type: void
+     * ```
+     */
+    noContent(): void;
+    /**
+     * Return 304 Not Modified response (empty body)
+     *
+     * @example
+     * ```ts
+     * if (etag === requestEtag) {
+     *   return c.notModified();
+     * }
+     * // Response: 304 Not Modified, Body: (empty)
+     * // Type: void
+     * ```
+     */
+    notModified(): void;
+    /**
+     * Return paginated response with metadata
+     * Returns `{ items: [...], pagination: {...} }` format with type inference
+     *
+     * @example
+     * ```ts
+     * const users = await getUsers(page, limit);
+     * const total = await countUsers();
+     * return c.paginated(users, page, limit, total);
+     * // Response: {
+     * //   items: [...],
+     * //   pagination: {
+     * //     page: 1,
+     * //     limit: 20,
+     * //     total: 100,
+     * //     totalPages: 5
+     * //   }
+     * // }
+     * // Type: PaginatedResult<User>
+     * ```
+     */
+    paginated<T>(data: T[], page: number, limit: number, total: number): PaginatedResult<T>;
+    /**
+     * Redirect to another URL
+     *
+     * @param url - Target URL to redirect to
+     * @param status - HTTP status code (301, 302, 303, 307, 308). Default: 302
+     *
+     * @example
+     * ```ts
+     * // Temporary redirect (302)
+     * return c.redirect('/login');
+     *
+     * // Permanent redirect (301)
+     * return c.redirect('/new-path', 301);
+     *
+     * // See Other (303) - useful after POST
+     * return c.redirect('/success', 303);
+     * ```
+     */
+    redirect(url: string, status?: RedirectStatusCode): Response;
+    raw: Context;
+};
+
+/**
+ * Middleware Definition Helper
+ *
+ * Provides type-safe middleware definition with name inference
+ */
+
+/**
+ * Named middleware with type inference
+ *
+ * @example
+ * ```ts
+ * export const authMiddleware = defineMiddleware('auth', async (c, next) => {
+ *   // auth logic
+ *   c.set('user', { id: 1 });
+ *   await next();
+ * });
+ *
+ * export const rateLimitMiddleware = defineMiddleware('rateLimit', async (c, next) => {
+ *   // rate limit logic
+ *   await next();
+ * });
+ * ```
+ */
+type NamedMiddleware<TName extends string = string> = {
+    name: TName;
+    handler: MiddlewareHandler;
+    _name: TName;
+};
+/**
+ * Named middleware factory with type inference
+ *
+ * Factory function that creates middleware instances with parameters
+ *
+ * @example
+ * ```ts
+ * export const requirePermissions = defineMiddleware('permission',
+ *   (...permissions: string[]) => async (c, next) => {
+ *     // permission check logic
+ *     await next();
+ *   }
+ * );
+ * ```
+ */
+type NamedMiddlewareFactory<TName extends string = string, TArgs extends any[] = any[]> = {
+    name: TName;
+    _name: TName;
+} & ((...args: TArgs) => MiddlewareHandler);
+/**
+ * Define a named middleware
+ *
+ * Creates a middleware with a unique name that can be referenced
+ * in route-level skip() calls with full type safety.
+ *
+ * Supports two patterns:
+ * 1. Regular middleware: Direct middleware handler
+ * 2. Factory middleware: Function that creates middleware with parameters
+ *
+ * @param name - Unique middleware name
+ * @param handler - Middleware handler function
+ * @returns Named middleware with type inference
+ *
+ * @example
+ * ```ts
+ * // Regular middleware
+ * export const authMiddleware = defineMiddleware('auth', async (c, next) => {
+ *   const token = c.req.header('authorization');
+ *   if (!token) {
+ *     return c.json({ error: 'Unauthorized' }, 401);
+ *   }
+ *   c.set('user', await verifyToken(token));
+ *   await next();
+ * });
+ *
+ * // Factory middleware
+ * export const requirePermissions = defineMiddleware('permission',
+ *   (...permissions: string[]) => async (c, next) => {
+ *     const user = c.get('user');
+ *     if (!hasPermissions(user, permissions)) {
+ *       return c.json({ error: 'Forbidden' }, 403);
+ *     }
+ *     await next();
+ *   }
+ * );
+ *
+ * // server.config.ts
+ * export default defineServerConfig()
+ *   .middlewares([authMiddleware])
+ *   .routes(appRouter)
+ *   .build();
+ *
+ * // routes.ts - skip by name
+ * export const publicRoute = route.get('/health')
+ *   .skip(['auth'])  // ✅ Type-safe! Autocomplete!
+ *   .handler(async (c) => c.success({ status: 'ok' }));
+ *
+ * // Use factory middleware inline
+ * export const protectedRoute = route.get('/admin')
+ *   .use([requirePermissions('admin:write')])
+ *   .handler(async (c) => { ... });
+ * ```
+ */
+declare function defineMiddleware<TName extends string>(name: TName, handler: MiddlewareHandler): NamedMiddleware<TName>;
+declare function defineMiddleware<TName extends string, TArgs extends any[]>(name: TName, factory: (...args: TArgs) => MiddlewareHandler): NamedMiddlewareFactory<TName, TArgs>;
+/**
+ * Define a middleware factory explicitly
+ *
+ * Use this when your factory function has exactly 2 parameters,
+ * which would be incorrectly detected as a regular middleware handler.
  *
- * Features:
- * - Automatic params/query/body validation using TypeBox
- * - Type-safe RouteContext with contract-based inference
- * - Clean separation: bind() for validation, Hono for middleware
+ * @param name - Unique middleware name
+ * @param factory - Factory function that returns a middleware handler
+ * @returns Named middleware factory with type inference
+ *
+ * @example
+ * ```ts
+ * // Factory with 2 params (would be misdetected by defineMiddleware)
+ * export const rateLimiter = defineMiddlewareFactory('rateLimit',
+ *   (limit: number, window: number) => async (c, next) => {
+ *     // rate limit logic using limit and window
+ *     await next();
+ *   }
+ * );
+ *
+ * // Usage
+ * route.get('/api')
+ *   .use([rateLimiter(100, 60000)])  // 100 requests per minute
+ *   .handler(...)
+ * ```
+ */
+declare function defineMiddlewareFactory<TName extends string, TArgs extends unknown[]>(name: TName, factory: (...args: TArgs) => MiddlewareHandler): NamedMiddlewareFactory<TName, TArgs>;
+/**
+ * Extract middleware names from an array of named middlewares
+ *
+ * @example
+ * ```ts
+ * type Middlewares = [
+ *   NamedMiddleware<'auth'>,
+ *   NamedMiddleware<'rateLimit'>
+ * ];
+ * type Names = ExtractMiddlewareNames<Middlewares>;  // 'auth' | 'rateLimit'
+ * ```
  */
-declare function bind<TContract extends RouteContract>(contract: TContract, handler: (c: RouteContext<TContract>) => Response | Promise<Response>): (rawContext: Context) => Promise<Response>;
+type ExtractMiddlewareNames<T extends readonly NamedMiddleware<string>[]> = T[number]['_name'];
 
 /**
- * Create App - Hono Wrapper for Contract-based Routing
+ * Route Builder
  *
- * Provides a cleaner API for registering routes with contracts
+ * Provides tRPC-style chainable API for route definition
  */
 
-type SPFNApp = Hono & {
-    bind<TContract extends RouteContract>(contract: TContract, handler: RouteHandler<TContract>): void;
-    bind<TContract extends RouteContract>(contract: TContract, middlewares: MiddlewareHandler[], handler: RouteHandler<TContract>): void;
-    _contractMetas?: Map<string, RouteContract['meta']>;
+/**
+ * Route handler function
+ */
+type RouteHandlerFn<TInput extends RouteInput = RouteInput, TInterceptor extends RouteInput = {}, TResponse = unknown> = (c: RouteBuilderContext<TInput, TInterceptor>) => Response | Promise<Response> | TResponse | Promise<TResponse>;
+/**
+ * Route definition result
+ *
+ * Contains all information needed for type inference and registration
+ */
+type RouteDef<TInput extends RouteInput = RouteInput, TInterceptor extends RouteInput = {}, TResponse = unknown> = {
+    method?: HttpMethod;
+    path?: string;
+    input?: TInput;
+    interceptor?: TInterceptor;
+    middlewares?: (MiddlewareHandler | NamedMiddleware<string>)[];
+    skipMiddlewares?: string[] | '*';
+    handler: RouteHandlerFn<TInput, TInterceptor, TResponse>;
+    _input: TInput;
+    _interceptor: TInterceptor;
+    _response: TResponse;
+};
+/**
+ * Route builder with chainable API (tRPC-style)
+ */
+declare class RouteBuilder<TInput extends RouteInput = {}, TInterceptor extends RouteInput = {}, TResponse = never> {
+    _method?: HttpMethod;
+    _path?: string;
+    _input?: TInput;
+    _interceptor?: TInterceptor;
+    _middlewares?: (MiddlewareHandler | NamedMiddleware<string>)[];
+    _skipMiddlewares?: string[] | '*';
+    /**
+     * Create a new RouteBuilder with copied properties and optional overrides
+     */
+    private clone;
+    /**
+     * Define input schemas
+     *
+     * @example
+     * ```ts
+     * route.get('/users/:id')
+     *   .input({
+     *     params: Type.Object({ id: Type.String() }),
+     *     query: Type.Object({ page: Type.Number() }),
+     *     headers: Type.Object({ authorization: Type.String() })
+     *   })
+     *   .handler(async (c) => {
+     *     const { params, query, headers } = await c.data();
+     *     // params = { id: string }
+     *     // query = { page: number }
+     *     // headers = { authorization: string }
+     *   })
+     * ```
+     */
+    input<TNewInput extends RouteInput>(input: TNewInput): RouteBuilder<TNewInput, TInterceptor, TResponse>;
+    /**
+     * Define fields injected by interceptors
+     *
+     * These fields are:
+     * - Available in the handler (merged with input)
+     * - Excluded from client types (codegen uses only input)
+     * - Not validated by route input schema (injected by middleware)
+     *
+     * Use this when middleware/interceptors add fields to the request
+     * before it reaches the handler.
+     *
+     * @example
+     * ```ts
+     * // Auth interceptor injects crypto key fields
+     * route.post('/_auth/login')
+     *   .input({
+     *     body: Type.Object({
+     *       email: Type.String(),
+     *       password: Type.String()
+     *     })
+     *   })
+     *   .interceptor({
+     *     body: Type.Object({
+     *       publicKey: Type.String(),
+     *       keyId: Type.String(),
+     *       fingerprint: Type.String()
+     *     })
+     *   })
+     *   .handler(async (c) => {
+     *     const { body } = await c.data();
+     *     // body type: { email, password, publicKey, keyId, fingerprint }
+     *     // Client only sees: { email, password }
+     *     return loginService(body);
+     *   });
+     * ```
+     */
+    interceptor<TNewInterceptor extends RouteInput>(interceptor: TNewInterceptor): RouteBuilder<TInput, TNewInterceptor, TResponse>;
+    /**
+     * Add middlewares to the route
+     *
+     * Accepts both regular middleware handlers and named middlewares (NamedMiddleware).
+     * Named middlewares that are already registered globally will be automatically
+     * deduplicated to prevent double execution.
+     *
+     * @example
+     * ```ts
+     * import { authenticate } from '@spfn/auth/server/middleware';
+     *
+     * // With NamedMiddleware (auto-deduped if registered globally)
+     * route.get('/users')
+     *   .use([authenticate, RateLimitMiddleware()])
+     *
+     * // With regular middleware handlers
+     * route.get('/users')
+     *   .use([AuthMiddleware(), RateLimitMiddleware()])
+     * ```
+     */
+    middleware(middlewares: (MiddlewareHandler | NamedMiddleware<string>)[]): RouteBuilder<TInput, TInterceptor, TResponse>;
+    /**
+     * Add middlewares to the route (alias for `.middleware()`)
+     *
+     * Accepts both regular middleware handlers and named middlewares (NamedMiddleware).
+     * Named middlewares that are already registered globally will be automatically
+     * deduplicated to prevent double execution.
+     *
+     * @example
+     * ```ts
+     * import { authenticate } from '@spfn/auth/server/middleware';
+     *
+     * // With NamedMiddleware (auto-deduped if registered globally)
+     * route.get('/users')
+     *   .use([authenticate, RateLimitMiddleware()])
+     *
+     * // With regular middleware handlers
+     * route.get('/users')
+     *   .use([AuthMiddleware(), RateLimitMiddleware()])
+     * ```
+     */
+    use(middlewares: (MiddlewareHandler | NamedMiddleware<string>)[]): RouteBuilder<TInput, TInterceptor, TResponse>;
+    /**
+     * Skip server-level named middlewares
+     *
+     * Useful for public endpoints that should bypass auth or rate limiting
+     *
+     * @param middlewareNames - Array of middleware names to skip, or '*' to skip all
+     *
+     * @example
+     * ```ts
+     * // Skip specific middlewares
+     * route.get('/health')
+     *   .skip(['auth', 'rateLimit'])
+     *   .handler(async (c) => c.json({ status: 'ok' }));
+     *
+     * // Skip only auth (still apply rate limiting)
+     * route.get('/public-data')
+     *   .skip(['auth'])
+     *   .handler(async (c) => { ... });
+     *
+     * // Skip all middlewares
+     * route.get('/public-health')
+     *   .skip('*')
+     *   .handler(async (c) => c.json({ status: 'ok' }));
+     * ```
+     */
+    skip(middlewareNames: string[] | '*'): RouteBuilder<TInput, TInterceptor, TResponse>;
+    /**
+     * Define handler function
+     *
+     * Response type is automatically inferred from the return value.
+     * Use helper methods like `c.created()`, `c.paginated()` for proper type inference.
+     *
+     * @example
+     * ```ts
+     * // Direct return - type inferred from data
+     * route.get('/users/:id')
+     *   .input({ params: Type.Object({ id: Type.String() }) })
+     *   .handler(async (c) => {
+     *     const { params } = await c.data();
+     *     return await getUser(params.id); // Type: User
+     *   })
+     *
+     * // Using c.created() - returns data with 201 status, type preserved
+     * route.post('/users')
+     *   .input({ body: Type.Object({ name: Type.String() }) })
+     *   .handler(async (c) => {
+     *     const { body } = await c.data();
+     *     return c.created(await createUser(body)); // Type: User
+     *   })
+     *
+     * // Using c.paginated() - returns PaginatedResult<T>
+     * route.get('/users')
+     *   .handler(async (c) => {
+     *     const users = await getUsers();
+     *     return c.paginated(users, 1, 20, 100); // Type: PaginatedResult<User>
+     *   })
+     *
+     * // Using c.noContent() - returns void
+     * route.delete('/users/:id')
+     *   .handler(async (c) => {
+     *     await deleteUser(params.id);
+     *     return c.noContent(); // Type: void
+     *   })
+     *
+     * // Using c.json() - returns Response (type inference lost)
+     * // Use only when you need custom status codes not covered by helpers
+     * route.get('/custom')
+     *   .handler(async (c) => {
+     *     return c.json({ data }, 418); // Type: Response
+     *   })
+     * ```
+     */
+    handler<THandlerResponse>(fn: RouteHandlerFn<TInput, TInterceptor, THandlerResponse>): RouteDef<TInput, TInterceptor, THandlerResponse>;
+}
+/**
+ * Route builder entry point
+ *
+ * @example
+ * ```ts
+ * // GET request
+ * export const getUser = route.get('/users/:id')
+ *   .input({ params: Type.Object({ id: Type.String() }) })
+ *   .handler(async (c) => {
+ *     const { params } = await c.data();
+ *     return await db.user.findUnique({ where: { id: params.id } });
+ *   });
+ *
+ * // POST request
+ * export const createUser = route.post('/users')
+ *   .input({ body: Type.Object({ name: Type.String(), email: Type.String() }) })
+ *   .handler(async (c) => {
+ *     const { body } = await c.data();
+ *     return c.created(await db.user.create({ data: body }));
+ *   });
+ * ```
+ */
+declare const route: {
+    get: (path: string) => RouteBuilder;
+    post: (path: string) => RouteBuilder;
+    put: (path: string) => RouteBuilder;
+    patch: (path: string) => RouteBuilder;
+    delete: (path: string) => RouteBuilder;
 };
+
+/**
+ * Router Definition
+ *
+ * Provides router composition and middleware management
+ */
+
+/**
+ * Router definition - holds all routes
+ */
+interface Router<TRoutes extends Record<string, RouteDef<any, any, any> | Router<any>>> {
+    routes: TRoutes;
+    _routes: TRoutes;
+    _packageRouters: Router<any>[];
+    _globalMiddlewares: NamedMiddleware<string>[];
+    /**
+     * Register package routers (type-hidden)
+     *
+     * Package routes are:
+     * - Recognized by RPC proxy and backend
+     * - NOT exposed in client types (use package's own API like authApi, cmsApi)
+     *
+     * @example
+     * ```ts
+     * import { authRouter } from '@spfn/auth/server';
+     * import { cmsAppRouter } from '@spfn/cms/server';
+     *
+     * export const appRouter = defineRouter({
+     *     getRoot,
+     *     getHealth,
+     * })
+     * .packages([authRouter, cmsAppRouter]);
+     *
+     * // Client usage:
+     * // api.getRoot.call({})     - app routes
+     * // authApi.login.call({})   - package API
+     * ```
+     */
+    packages(routers: Router<any>[]): Router<TRoutes>;
+    /**
+     * Register global middlewares
+     *
+     * Applied to all routes unless explicitly skipped via .skip()
+     *
+     * @example
+     * ```ts
+     * import { authMiddleware, loggingMiddleware } from './middlewares';
+     *
+     * export const appRouter = defineRouter({
+     *     getRoot,
+     *     getHealth,
+     * })
+     * .packages([authRouter])
+     * .use([authMiddleware, loggingMiddleware]);
+     * ```
+     */
+    use(middlewares: NamedMiddleware<string>[]): Router<TRoutes>;
+}
+/**
+ * Define a router with multiple routes (tRPC-style)
+ *
+ * Supports chainable API for packages and middlewares:
+ *
+ * @example
+ * ```ts
+ * // Basic usage
+ * export const appRouter = defineRouter({
+ *     getRoot,
+ *     getHealth,
+ *     listExamples,
+ * });
+ *
+ * // With package routers (type-hidden)
+ * export const appRouter = defineRouter({
+ *     getRoot,
+ *     getHealth,
+ * })
+ * .packages([authRouter, cmsAppRouter]);
+ *
+ * // With global middlewares
+ * export const appRouter = defineRouter({
+ *     getRoot,
+ *     getHealth,
+ * })
+ * .packages([authRouter])
+ * .use([authMiddleware, loggingMiddleware]);
+ *
+ * export type AppRouter = typeof appRouter;
+ * ```
+ *
+ * Package routes:
+ * - Recognized by RPC proxy and backend for routing
+ * - NOT included in AppRouter type (use authApi, cmsApi instead)
+ * - Prevents confusion between app API and package APIs
+ */
+declare function defineRouter<TRoutes extends Record<string, RouteDef<any, any, any> | Router<any>>>(routes: TRoutes): Router<TRoutes>;
+
+/**
+ * Route Registration for define-route style routing
+ *
+ * Registers routes defined with route.get()...handler() to Hono app
+ */
+
+/**
+ * Registered route information for logging
+ */
+interface RegisteredRoute {
+    method: HttpMethod;
+    path: string;
+    name: string;
+}
+/**
+ * Register routes from defineRouter() to Hono app
+ *
+ * @param app - Hono app instance
+ * @param router - Router definition
+ * @param namedMiddlewares - Optional server-level named middlewares
+ *
+ * @param collectedRoutes
+ * @example
+ * ```ts
+ * const appRouter = defineRouter({
+ *   getUser: route.get('/users/:id')...
+ *   createUser: route.post('/users')...
+ * });
+ *
+ * const app = new Hono();
+ * const namedMiddlewares = [
+ *   { name: 'auth', handler: AuthMiddleware() },
+ *   { name: 'rateLimit', handler: RateLimitMiddleware() },
+ * ];
+ * registerRoutes(app, appRouter, namedMiddlewares);
+ * ```
+ */
+declare function registerRoutes<TRoutes extends Record<string, RouteDef<any> | Router<any>>>(app: Hono, router: Router<TRoutes>, namedMiddlewares?: ReadonlyArray<{
+    name: string;
+    handler: MiddlewareHandler;
+}>, collectedRoutes?: RegisteredRoute[]): RegisteredRoute[];
+
+/**
+ * Type guard for HttpMethod
+ */
+declare function isHttpMethod(value: unknown): value is HttpMethod;
+/**
+ * Nullable - Creates a union of T | null
+ *
+ * @example
+ * ```typescript
+ * // string | null
+ * firstName: Nullable(Type.String())
+ * ```
+ */
+declare const Nullable: <T extends TSchema>(schema: T) => _sinclair_typebox.TUnion<[T, _sinclair_typebox.TNull]>;
+/**
+ * OptionalNullable - Creates a union of T | null | undefined
+ *
+ * @example
+ * ```typescript
+ * // string | null | undefined
+ * lastName: OptionalNullable(Type.String())
+ * ```
+ */
+declare const OptionalNullable: <T extends TSchema>(schema: T) => _sinclair_typebox.TOptional<_sinclair_typebox.TUnion<[T, _sinclair_typebox.TNull]>>;
+
+/**
+ * File Schema Helpers for TypeBox
+ *
+ * Provides TypeBox schema definitions for file upload handling
+ * with optional validation constraints.
+ */
+
+/**
+ * File validation options
+ */
+interface FileSchemaOptions {
+    /**
+     * Maximum file size in bytes
+     *
+     * @example 5 * 1024 * 1024 // 5MB
+     */
+    maxSize?: number;
+    /**
+     * Allowed MIME types
+     *
+     * @example ['image/jpeg', 'image/png', 'image/webp']
+     */
+    allowedTypes?: string[];
+    /**
+     * Minimum file size in bytes (optional)
+     *
+     * @example 1024 // 1KB minimum
+     */
+    minSize?: number;
+}
+/**
+ * File array validation options
+ */
+interface FileArraySchemaOptions extends FileSchemaOptions {
+    /**
+     * Maximum number of files
+     *
+     * @example 5
+     */
+    maxFiles?: number;
+    /**
+     * Minimum number of files (optional)
+     *
+     * @example 1
+     */
+    minFiles?: number;
+}
+/**
+ * Internal schema type with file validation metadata
+ */
+interface FileSchemaType extends TSchema {
+    [Kind]: 'File';
+    fileOptions?: FileSchemaOptions;
+}
+interface FileArraySchemaType extends TSchema {
+    [Kind]: 'FileArray';
+    fileOptions?: FileArraySchemaOptions;
+}
 /**
- * Create SPFN app instance
+ * Create a File schema with optional validation
  *
- * Wraps Hono with contract-based routing support
+ * @example
+ * ```ts
+ * // Basic usage (no validation)
+ * formData: Type.Object({
+ *     file: FileSchema()
+ * })
+ *
+ * // With validation
+ * formData: Type.Object({
+ *     avatar: FileSchema({
+ *         maxSize: 5 * 1024 * 1024,  // 5MB
+ *         allowedTypes: ['image/jpeg', 'image/png', 'image/webp']
+ *     })
+ * })
+ * ```
+ */
+declare function FileSchema(options?: FileSchemaOptions): FileSchemaType;
+/**
+ * Create a File array schema with optional validation
+ *
+ * @example
+ * ```ts
+ * // Basic usage (no validation)
+ * formData: Type.Object({
+ *     files: FileArraySchema()
+ * })
+ *
+ * // With validation
+ * formData: Type.Object({
+ *     documents: FileArraySchema({
+ *         maxSize: 10 * 1024 * 1024,  // 10MB per file
+ *         maxFiles: 5,
+ *         allowedTypes: ['application/pdf', 'application/msword']
+ *     })
+ * })
+ * ```
+ */
+declare function FileArraySchema(options?: FileArraySchemaOptions): FileArraySchemaType;
+/**
+ * Create an optional File schema with validation
+ *
+ * @example
+ * ```ts
+ * formData: Type.Object({
+ *     name: Type.String(),
+ *     avatar: OptionalFileSchema({
+ *         maxSize: 2 * 1024 * 1024,
+ *         allowedTypes: ['image/jpeg', 'image/png']
+ *     })
+ * })
+ * ```
+ */
+declare function OptionalFileSchema(options?: FileSchemaOptions): TSchema;
+/**
+ * Check if a schema is a File schema
+ */
+declare function isFileSchema(schema: TSchema): schema is FileSchemaType;
+/**
+ * Check if a schema is a FileArray schema
+ */
+declare function isFileArraySchema(schema: TSchema): schema is FileArraySchemaType;
+/**
+ * Get file options from schema
+ */
+declare function getFileOptions(schema: TSchema): FileSchemaOptions | FileArraySchemaOptions | undefined;
+/**
+ * Format file size for error messages
  */
-declare function createApp(): SPFNApp;
+declare function formatFileSize(bytes: number): string;
 
-export { RouteContext, RouteContract, RouteHandler, type SPFNApp, bind, createApp };
+export { type ExtractMiddlewareNames, FileArraySchema, type FileArraySchemaOptions, type FileArraySchemaType, FileSchema, type FileSchemaOptions, type FileSchemaType, HttpMethod, type MergedInput, type NamedMiddleware, type NamedMiddlewareFactory, Nullable, OptionalFileSchema, OptionalNullable, type PaginatedResult, type RegisteredRoute, type RouteBuilderContext, type RouteDef, type RouteHandlerFn, type RouteInput, type Router, defineMiddleware, defineMiddlewareFactory, defineRouter, formatFileSize, getFileOptions, isFileArraySchema, isFileSchema, isHttpMethod, registerRoutes, route };