@spfn/core 0.2.0-beta.9 → 0.3.0-beta.2

package/dist/router-Qbssr11H.d.ts

@@ -0,0 +1,676 @@
+import { a as NamedMiddleware } from './define-middleware-DfDP39Nq.js';
+import { Context, MiddlewareHandler } from 'hono';
+import { TSchema, Static } from '@sinclair/typebox';
+import { ContentfulStatusCode, RedirectStatusCode } from 'hono/utils/http-status';
+import { HttpMethod } from './route/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 Contract
+ *
+ * A contract marks a route as a versioned public promise to clients that are
+ * compiled and deployed separately from the server — a mobile app, an external
+ * API consumer. Those clients cannot be fixed by redeploying the server, so the
+ * shape they read has to survive server changes.
+ *
+ * A web client does not need this. `createApi<AppRouter>()` derives its types
+ * from the router in the same build, so a removed response field breaks the
+ * TypeScript compile instead of a running app.
+ *
+ * The response shape is declared here rather than inferred from the handler's
+ * return type: a declared schema exists at runtime, which is what the generator
+ * and the compatibility gate read. `_response` on RouteDef disappears after
+ * compilation.
+ */
+
+/**
+ * Authentication profile a contracted operation is admitted under.
+ *
+ * - `none` — the operation is called before any key exists to sign with
+ *   (enrollment, login), so it carries neither proof nor session headers.
+ * - `clientProofV1` — admitted by the @spfn/auth client-proof admission order.
+ *
+ * The union is deliberately closed. A profile name is part of what the contract
+ * publishes to external clients, so adding one is a change to this file rather
+ * than a string a route can invent.
+ */
+type RouteAuthProfile = 'none' | 'clientProofV1';
+/**
+ * The public promise a contracted route makes.
+ */
+interface RouteContract {
+    /** Contract version this operation first appeared in (e.g. '1.2.0'). */
+    since: string;
+    /**
+     * Response shape. TypeBox schema, declared — not inferred.
+     *
+     * An operation that answers with no body declares `Type.Null()`.
+     */
+    response: TSchema;
+    /** Authentication profile. Defaults to `'none'`. */
+    auth?: RouteAuthProfile;
+    /** Whether the call carries a session. Defaults to `false`. */
+    requiresSession?: boolean;
+    /** Contract version this operation was announced for removal in. */
+    deprecatedIn?: string;
+    /**
+     * Contract version this operation was removed in.
+     *
+     * Set on a route kept alive only to carry the record. A client generated
+     * before the removal still calls it, and this is what tells that client the
+     * operation went and when — a route that simply disappears says nothing.
+     */
+    removedIn?: string;
+}
+
+/**
+ * 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[] | '*';
+    /**
+     * Public promise this route makes to separately deployed clients.
+     *
+     * Present as a runtime value, unlike `_response`: the contract generator and
+     * the compatibility gate read it.
+     */
+    contract?: RouteContract;
+    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[] | '*';
+    _contract?: RouteContract;
+    /**
+     * 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>;
+    /**
+     * 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: RouteContract): 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>[];
+    /** The contract version these routes publish, or null when uncontracted. */
+    _contractVersion: string | null;
+    /**
+     * 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>;
+    /**
+     * Declare the contract version these routes publish.
+     *
+     * A client compiled against this server — a mobile app in a store — is
+     * generated from one version of the contract and cannot be updated when the
+     * server changes. The server announces this version on every response so
+     * that client can tell whether the two ends still agree.
+     *
+     * This is the version's source. A released snapshot is written to
+     * `contracts/released/<version>.json` from what is declared here, so the
+     * filename follows the code rather than the code having to be told what the
+     * filename said.
+     *
+     * Only a server with contracted routes needs it. Without it the contract
+     * generator still writes `current.json` and still runs the compatibility
+     * gate; what it cannot do is cut a release or announce a version.
+     *
+     * @example
+     * ```ts
+     * export const appRouter = defineRouter({ getRoot, listItems })
+     *     .contractVersion('1.2.0')
+     *     .packages([authRouter]);
+     * ```
+     */
+    contractVersion(version: 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 { type MergedInput as M, type PaginatedResult as P, type Router as R, type RouteDef as a, RouteBuilder as b, type RouteAuthProfile as c, type RouteBuilderContext as d, type RouteContract as e, type RouteHandlerFn as f, type RouteInput as g, defineRouter as h, route as r };