@spfn/core 0.2.0-beta.67 → 0.2.0-beta.68

package/dist/route/index.d.ts

@@ -1,555 +1,11 @@
-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 { N as NamedMiddleware } from '../define-middleware-DuXD8Hvu.js';
-export { E as ExtractMiddlewareNames, b as NamedMiddlewareFactory, d as defineMiddleware, a as defineMiddlewareFactory } from '../define-middleware-DuXD8Hvu.js';
+import { R as RouteDef, a as Router } from '../router-DhvbMhef.js';
+export { M as MergedInput, P as PaginatedResult, f as RouteAuthProfile, c as RouteBuilderContext, e as RouteContract, d as RouteHandlerFn, b as RouteInput, g as defineRouter, r as route } from '../router-DhvbMhef.js';
+import { Hono, MiddlewareHandler } from 'hono';
 import { HttpMethod } from './types.js';
-
-/**
- * Route Input Types
- *
- * 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;
-};
-
-/**
- * Route Builder
- *
- * Provides tRPC-style chainable API for route definition
- */
-
-/**
- * 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>;
+export { E as ExtractMiddlewareNames, b as NamedMiddleware, N as NamedMiddlewareFactory, d as defineMiddleware, a as defineMiddlewareFactory } from '../define-middleware-B9bFuXVU.js';
+import * as _sinclair_typebox from '@sinclair/typebox';
+import { TSchema, Kind } from '@sinclair/typebox';
+import 'hono/utils/http-status';
 
 /**
  * Route Registration for define-route style routing
@@ -749,4 +205,4 @@ declare function getFileOptions(schema: TSchema): FileSchemaOptions | FileArrayS
  */
 declare function formatFileSize(bytes: number): string;
 
-export { FileArraySchema, type FileArraySchemaOptions, type FileArraySchemaType, FileSchema, type FileSchemaOptions, type FileSchemaType, HttpMethod, type MergedInput, NamedMiddleware, Nullable, OptionalFileSchema, OptionalNullable, type PaginatedResult, type RegisteredRoute, type RouteBuilderContext, type RouteDef, type RouteHandlerFn, type RouteInput, type Router, defineRouter, formatFileSize, getFileOptions, isFileArraySchema, isFileSchema, isHttpMethod, registerRoutes, route };
+export { FileArraySchema, type FileArraySchemaOptions, type FileArraySchemaType, FileSchema, type FileSchemaOptions, type FileSchemaType, HttpMethod, Nullable, OptionalFileSchema, OptionalNullable, type RegisteredRoute, RouteDef, Router, formatFileSize, getFileOptions, isFileArraySchema, isFileSchema, isHttpMethod, registerRoutes };

package/dist/route/index.js

@@ -11,6 +11,7 @@ var RouteBuilder = class _RouteBuilder {
   _interceptor;
   _middlewares;
   _skipMiddlewares;
+  _contract;
   /**
    * Create a new RouteBuilder with copied properties and optional overrides
    */
@@ -22,6 +23,7 @@ var RouteBuilder = class _RouteBuilder {
     builder._interceptor = overrides?.interceptor ?? this._interceptor;
     builder._middlewares = overrides?.middlewares ?? this._middlewares;
     builder._skipMiddlewares = overrides?.skipMiddlewares ?? this._skipMiddlewares;
+    builder._contract = overrides?.contract ?? this._contract;
     return builder;
   }
   /**
@@ -159,6 +161,39 @@ var RouteBuilder = class _RouteBuilder {
   skip(middlewareNames) {
     return this.clone({ skipMiddlewares: middlewareNames });
   }
+  /**
+   * Publish this route as a versioned contract operation
+   *
+   * Marks the route as a promise to clients that are compiled and deployed
+   * separately from the server — a mobile app, an external API consumer.
+   * The `@spfn/core:contract` generator writes every contracted route into
+   * `contracts/current.json`, and the build refuses a change that would break
+   * an already-released client.
+   *
+   * Routes without `.contract()` are unaffected: they simply do not appear in
+   * the contract. A web client needs nothing here — it derives its types from
+   * the router in the same build.
+   *
+   * @example
+   * ```ts
+   * export const getUser = route.get('/users/:id')
+   *   .input({ params: Type.Object({ id: Type.String() }) })
+   *   .contract({
+   *     since: '1.2.0',
+   *     auth: 'clientProofV1',
+   *     requiresSession: true,
+   *     response: Type.Object({
+   *       id: Type.String(),
+   *       name: Type.String(),
+   *       email: Type.Optional(Type.String()),
+   *     }),
+   *   })
+   *   .handler(async (c) => { ... });
+   * ```
+   */
+  contract(contract) {
+    return this.clone({ contract });
+  }
   /**
    * Define handler function
    *
@@ -213,6 +248,7 @@ var RouteBuilder = class _RouteBuilder {
       interceptor: this._interceptor,
       middlewares: this._middlewares,
       skipMiddlewares: this._skipMiddlewares,
+      contract: this._contract,
       handler: fn,
       _input: {},
       _interceptor: {},