kontract 0.1.0

package/dist/decorators/controller.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Options for the @Controller class decorator.
+ */
+export interface ControllerOptions {
+    /** OpenAPI tag for grouping routes */
+    tag: string;
+    /** Description of the controller/API group */
+    description?: string;
+    /** Optional path prefix for all routes in this controller */
+    prefix?: string;
+}
+/**
+ * Class decorator that marks a controller for OpenAPI documentation.
+ *
+ * The tag is used to group routes in the OpenAPI spec.
+ * The optional prefix is prepended to all route paths in this controller.
+ *
+ * @example Basic usage
+ * ```typescript
+ * @Controller({ tag: 'Users', description: 'User management routes' })
+ * export class UsersController {
+ *   // routes...
+ * }
+ * ```
+ *
+ * @example With prefix
+ * ```typescript
+ * @Controller({ tag: 'Admin', description: 'Admin routes', prefix: '/admin' })
+ * export class AdminController {
+ *   // All routes in this controller will be prefixed with /admin
+ * }
+ * ```
+ */
+export declare function Controller(options: ControllerOptions): ClassDecorator;
+//# sourceMappingURL=controller.d.ts.map

package/dist/decorators/controller.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"controller.d.ts","sourceRoot":"","sources":["../../src/decorators/controller.ts"],"names":[],"mappings":"AAGA;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,sCAAsC;IACtC,GAAG,EAAE,MAAM,CAAA;IACX,8CAA8C;IAC9C,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,6DAA6D;IAC7D,MAAM,CAAC,EAAE,MAAM,CAAA;CAChB;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,UAAU,CAAC,OAAO,EAAE,iBAAiB,GAAG,cAAc,CASrE"}

package/dist/decorators/controller.js

@@ -0,0 +1,34 @@
+import { setApiMetadata } from '../metadata/storage.js';
+/**
+ * Class decorator that marks a controller for OpenAPI documentation.
+ *
+ * The tag is used to group routes in the OpenAPI spec.
+ * The optional prefix is prepended to all route paths in this controller.
+ *
+ * @example Basic usage
+ * ```typescript
+ * @Controller({ tag: 'Users', description: 'User management routes' })
+ * export class UsersController {
+ *   // routes...
+ * }
+ * ```
+ *
+ * @example With prefix
+ * ```typescript
+ * @Controller({ tag: 'Admin', description: 'Admin routes', prefix: '/admin' })
+ * export class AdminController {
+ *   // All routes in this controller will be prefixed with /admin
+ * }
+ * ```
+ */
+export function Controller(options) {
+    return function (target) {
+        const metadata = {
+            tag: options.tag,
+            description: options.description,
+            prefix: options.prefix,
+        };
+        setApiMetadata(target, metadata);
+    };
+}
+//# sourceMappingURL=controller.js.map

package/dist/decorators/controller.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"controller.js","sourceRoot":"","sources":["../../src/decorators/controller.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAA;AAevD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,UAAU,UAAU,CAAC,OAA0B;IACnD,OAAO,UAAU,MAAM;QACrB,MAAM,QAAQ,GAAgB;YAC5B,GAAG,EAAE,OAAO,CAAC,GAAG;YAChB,WAAW,EAAE,OAAO,CAAC,WAAW;YAChC,MAAM,EAAE,OAAO,CAAC,MAAM;SACvB,CAAA;QACD,cAAc,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAA;IAClC,CAAC,CAAA;AACH,CAAC"}

package/dist/decorators/endpoint.d.ts

@@ -0,0 +1,93 @@
+import type { TSchema } from '@sinclair/typebox';
+import type { RouteString, FileUploadConfig } from '../metadata/types.js';
+/**
+ * Options for the @Endpoint method decorator.
+ */
+export interface EndpointOptions {
+    /** Short summary for OpenAPI docs */
+    summary?: string;
+    /** Detailed description for OpenAPI docs */
+    description?: string;
+    /** Unique operation ID for OpenAPI (auto-generated if not provided) */
+    operationId?: string;
+    /** Mark endpoint as deprecated */
+    deprecated?: boolean;
+    /** Authentication requirement */
+    auth?: 'required' | 'optional' | 'none';
+    /** Request body schema (TypeBox) */
+    body?: TSchema;
+    /** Query parameters schema (TypeBox) */
+    query?: TSchema;
+    /** Path parameters schema (TypeBox) */
+    params?: TSchema;
+    /** File upload configuration for multipart/form-data */
+    file?: FileUploadConfig;
+    /**
+     * Response definitions by status code.
+     * Value can be:
+     * - A TypeBox schema
+     * - null (for no body, e.g., 204)
+     * - An object with schema and optional description
+     */
+    responses: Record<number, TSchema | null | {
+        schema: TSchema | null;
+        description?: string;
+    }>;
+    /**
+     * Framework-specific middleware.
+     * This is opaque to the core library - adapters interpret it.
+     */
+    middleware?: unknown[];
+}
+/**
+ * Method decorator that defines an API endpoint with full OpenAPI metadata.
+ *
+ * This decorator captures all information needed to:
+ * 1. Register the route with a framework
+ * 2. Validate request body, query, and path parameters
+ * 3. Generate OpenAPI documentation
+ *
+ * @param route Route string in format "METHOD /path"
+ * @param options Endpoint configuration
+ *
+ * @example Basic GET endpoint
+ * ```typescript
+ * @Endpoint('GET /api/v1/users', {
+ *   summary: 'List all users',
+ *   responses: {
+ *     200: { schema: UserListResponse, description: 'List of users' },
+ *   },
+ * })
+ * async index() { ... }
+ * ```
+ *
+ * @example POST with body and auth
+ * ```typescript
+ * @Endpoint('POST /api/v1/users', {
+ *   summary: 'Create a user',
+ *   auth: 'required',
+ *   body: CreateUserRequest,
+ *   responses: {
+ *     201: { schema: User, description: 'User created' },
+ *     422: { schema: ValidationError },
+ *   },
+ * })
+ * async store(ctx: Context, body: Static<typeof CreateUserRequest>) { ... }
+ * ```
+ *
+ * @example DELETE with no response body
+ * ```typescript
+ * @Endpoint('DELETE /api/v1/users/:id', {
+ *   summary: 'Delete a user',
+ *   auth: 'required',
+ *   params: UserIdParams,
+ *   responses: {
+ *     204: null,
+ *     404: { schema: NotFoundError },
+ *   },
+ * })
+ * async destroy(ctx: Context) { ... }
+ * ```
+ */
+export declare function Endpoint(route: RouteString, options: EndpointOptions): MethodDecorator;
+//# sourceMappingURL=endpoint.d.ts.map

package/dist/decorators/endpoint.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"endpoint.d.ts","sourceRoot":"","sources":["../../src/decorators/endpoint.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,mBAAmB,CAAA;AAEhD,OAAO,KAAK,EACV,WAAW,EAGX,gBAAgB,EAEjB,MAAM,sBAAsB,CAAA;AAE7B;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,qCAAqC;IACrC,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,4CAA4C;IAC5C,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,uEAAuE;IACvE,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,kCAAkC;IAClC,UAAU,CAAC,EAAE,OAAO,CAAA;IACpB,iCAAiC;IACjC,IAAI,CAAC,EAAE,UAAU,GAAG,UAAU,GAAG,MAAM,CAAA;IACvC,oCAAoC;IACpC,IAAI,CAAC,EAAE,OAAO,CAAA;IACd,wCAAwC;IACxC,KAAK,CAAC,EAAE,OAAO,CAAA;IACf,uCAAuC;IACvC,MAAM,CAAC,EAAE,OAAO,CAAA;IAChB,wDAAwD;IACxD,IAAI,CAAC,EAAE,gBAAgB,CAAA;IACvB;;;;;;OAMG;IACH,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,GAAG,IAAI,GAAG;QAAE,MAAM,EAAE,OAAO,GAAG,IAAI,CAAC;QAAC,WAAW,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,CAAA;IAC5F;;;OAGG;IACH,UAAU,CAAC,EAAE,OAAO,EAAE,CAAA;CACvB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiDG;AACH,wBAAgB,QAAQ,CACtB,KAAK,EAAE,WAAW,EAClB,OAAO,EAAE,eAAe,GACvB,eAAe,CAwCjB"}

package/dist/decorators/endpoint.js

@@ -0,0 +1,108 @@
+import { addEndpointMetadata } from '../metadata/storage.js';
+/**
+ * Method decorator that defines an API endpoint with full OpenAPI metadata.
+ *
+ * This decorator captures all information needed to:
+ * 1. Register the route with a framework
+ * 2. Validate request body, query, and path parameters
+ * 3. Generate OpenAPI documentation
+ *
+ * @param route Route string in format "METHOD /path"
+ * @param options Endpoint configuration
+ *
+ * @example Basic GET endpoint
+ * ```typescript
+ * @Endpoint('GET /api/v1/users', {
+ *   summary: 'List all users',
+ *   responses: {
+ *     200: { schema: UserListResponse, description: 'List of users' },
+ *   },
+ * })
+ * async index() { ... }
+ * ```
+ *
+ * @example POST with body and auth
+ * ```typescript
+ * @Endpoint('POST /api/v1/users', {
+ *   summary: 'Create a user',
+ *   auth: 'required',
+ *   body: CreateUserRequest,
+ *   responses: {
+ *     201: { schema: User, description: 'User created' },
+ *     422: { schema: ValidationError },
+ *   },
+ * })
+ * async store(ctx: Context, body: Static<typeof CreateUserRequest>) { ... }
+ * ```
+ *
+ * @example DELETE with no response body
+ * ```typescript
+ * @Endpoint('DELETE /api/v1/users/:id', {
+ *   summary: 'Delete a user',
+ *   auth: 'required',
+ *   params: UserIdParams,
+ *   responses: {
+ *     204: null,
+ *     404: { schema: NotFoundError },
+ *   },
+ * })
+ * async destroy(ctx: Context) { ... }
+ * ```
+ */
+export function Endpoint(route, options) {
+    return function (_target, propertyKey, descriptor) {
+        const [method, path] = parseRoute(route);
+        // Normalize responses to consistent format
+        const responses = {};
+        for (const [status, value] of Object.entries(options.responses)) {
+            if (value === null) {
+                responses[Number(status)] = { schema: null };
+            }
+            else if (typeof value === 'object' && 'schema' in value) {
+                responses[Number(status)] = value;
+            }
+            else {
+                responses[Number(status)] = { schema: value };
+            }
+        }
+        const metadata = {
+            method,
+            path,
+            methodName: String(propertyKey),
+            summary: options.summary,
+            description: options.description,
+            operationId: options.operationId,
+            deprecated: options.deprecated,
+            auth: options.auth ?? 'none',
+            body: options.body,
+            query: options.query,
+            params: options.params,
+            file: options.file,
+            responses,
+            middleware: options.middleware,
+        };
+        // Store metadata on the constructor (class), not the prototype
+        // This allows us to retrieve it when scanning controllers
+        const constructor = _target.constructor;
+        addEndpointMetadata(constructor, metadata);
+        return descriptor;
+    };
+}
+/**
+ * Parse a route string into method and path.
+ * @throws Error if route format is invalid
+ */
+function parseRoute(route) {
+    const spaceIndex = route.indexOf(' ');
+    if (spaceIndex === -1) {
+        throw new Error(`Invalid route format: "${route}". Expected "METHOD /path"`);
+    }
+    const methodStr = route.slice(0, spaceIndex).toLowerCase();
+    const path = route.slice(spaceIndex + 1);
+    const validMethods = ['get', 'post', 'put', 'patch', 'delete'];
+    if (!validMethods.includes(methodStr)) {
+        throw new Error(`Invalid HTTP method: "${methodStr}". Expected one of: ${validMethods.join(', ')}`);
+    }
+    return [methodStr, path];
+}
+//# sourceMappingURL=endpoint.js.map

package/dist/decorators/endpoint.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"endpoint.js","sourceRoot":"","sources":["../../src/decorators/endpoint.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,mBAAmB,EAAE,MAAM,wBAAwB,CAAA;AA8C5D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiDG;AACH,MAAM,UAAU,QAAQ,CACtB,KAAkB,EAClB,OAAwB;IAExB,OAAO,UAAU,OAAO,EAAE,WAAW,EAAE,UAAU;QAC/C,MAAM,CAAC,MAAM,EAAE,IAAI,CAAC,GAAG,UAAU,CAAC,KAAK,CAAC,CAAA;QAExC,2CAA2C;QAC3C,MAAM,SAAS,GAAuC,EAAE,CAAA;QACxD,KAAK,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC,SAAS,CAAC,EAAE,CAAC;YAChE,IAAI,KAAK,KAAK,IAAI,EAAE,CAAC;gBACnB,SAAS,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,CAAA;YAC9C,CAAC;iBAAM,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,QAAQ,IAAI,KAAK,EAAE,CAAC;gBAC1D,SAAS,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,GAAG,KAA2B,CAAA;YACzD,CAAC;iBAAM,CAAC;gBACN,SAAS,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,MAAM,EAAE,KAAgB,EAAE,CAAA;YAC1D,CAAC;QACH,CAAC;QAED,MAAM,QAAQ,GAAqB;YACjC,MAAM;YACN,IAAI;YACJ,UAAU,EAAE,MAAM,CAAC,WAAW,CAAC;YAC/B,OAAO,EAAE,OAAO,CAAC,OAAO;YACxB,WAAW,EAAE,OAAO,CAAC,WAAW;YAChC,WAAW,EAAE,OAAO,CAAC,WAAW;YAChC,UAAU,EAAE,OAAO,CAAC,UAAU;YAC9B,IAAI,EAAE,OAAO,CAAC,IAAI,IAAI,MAAM;YAC5B,IAAI,EAAE,OAAO,CAAC,IAAI;YAClB,KAAK,EAAE,OAAO,CAAC,KAAK;YACpB,MAAM,EAAE,OAAO,CAAC,MAAM;YACtB,IAAI,EAAE,OAAO,CAAC,IAAI;YAClB,SAAS;YACT,UAAU,EAAE,OAAO,CAAC,UAAU;SAC/B,CAAA;QAED,+DAA+D;QAC/D,0DAA0D;QAC1D,MAAM,WAAW,GAAI,OAAkB,CAAC,WAAW,CAAA;QACnD,mBAAmB,CAAC,WAAW,EAAE,QAAQ,CAAC,CAAA;QAE1C,OAAO,UAAU,CAAA;IACnB,CAAC,CAAA;AACH,CAAC;AAED;;;GAGG;AACH,SAAS,UAAU,CAAC,KAAkB;IACpC,MAAM,UAAU,GAAG,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,CAAA;IACrC,IAAI,UAAU,KAAK,CAAC,CAAC,EAAE,CAAC;QACtB,MAAM,IAAI,KAAK,CAAC,0BAA0B,KAAK,4BAA4B,CAAC,CAAA;IAC9E,CAAC;IAED,MAAM,SAAS,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,UAAU,CAAC,CAAC,WAAW,EAAE,CAAA;IAC1D,MAAM,IAAI,GAAG,KAAK,CAAC,KAAK,CAAC,UAAU,GAAG,CAAC,CAAC,CAAA;IAExC,MAAM,YAAY,GAAiB,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,QAAQ,CAAC,CAAA;IAC5E,IAAI,CAAC,YAAY,CAAC,QAAQ,CAAC,SAAuB,CAAC,EAAE,CAAC;QACpD,MAAM,IAAI,KAAK,CAAC,yBAAyB,SAAS,uBAAuB,YAAY,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAA;IACrG,CAAC;IAED,OAAO,CAAC,SAAuB,EAAE,IAAI,CAAC,CAAA;AACxC,CAAC"}

package/dist/decorators/index.d.ts

@@ -0,0 +1,5 @@
+export { Controller, type ControllerOptions } from './controller.js';
+export { Route, type RouteOptions } from './route.js';
+export type { HttpMethod, AuthLevel, RouteString, ResponseDefinition, FileUploadConfig, ApiMetadata, EndpointMetadata, } from '../metadata/types.js';
+export { getApiMetadata, getEndpointMetadata, getRegisteredControllers, getControllerMetadata, getAllControllerMetadata, } from '../metadata/storage.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/decorators/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/decorators/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,UAAU,EAAE,KAAK,iBAAiB,EAAE,MAAM,iBAAiB,CAAA;AACpE,OAAO,EAAE,KAAK,EAAE,KAAK,YAAY,EAAE,MAAM,YAAY,CAAA;AAGrD,YAAY,EACV,UAAU,EACV,SAAS,EACT,WAAW,EACX,kBAAkB,EAClB,gBAAgB,EAChB,WAAW,EACX,gBAAgB,GACjB,MAAM,sBAAsB,CAAA;AAG7B,OAAO,EACL,cAAc,EACd,mBAAmB,EACnB,wBAAwB,EACxB,qBAAqB,EACrB,wBAAwB,GACzB,MAAM,wBAAwB,CAAA"}

package/dist/decorators/index.js

@@ -0,0 +1,6 @@
+// Decorators
+export { Controller } from './controller.js';
+export { Route } from './route.js';
+// Re-export metadata accessors
+export { getApiMetadata, getEndpointMetadata, getRegisteredControllers, getControllerMetadata, getAllControllerMetadata, } from '../metadata/storage.js';
+//# sourceMappingURL=index.js.map

package/dist/decorators/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/decorators/index.ts"],"names":[],"mappings":"AAAA,aAAa;AACb,OAAO,EAAE,UAAU,EAA0B,MAAM,iBAAiB,CAAA;AACpE,OAAO,EAAE,KAAK,EAAqB,MAAM,YAAY,CAAA;AAarD,+BAA+B;AAC/B,OAAO,EACL,cAAc,EACd,mBAAmB,EACnB,wBAAwB,EACxB,qBAAqB,EACrB,wBAAwB,GACzB,MAAM,wBAAwB,CAAA"}

package/dist/decorators/route.d.ts

@@ -0,0 +1,93 @@
+import type { TSchema } from '@sinclair/typebox';
+import type { RouteString, FileUploadConfig } from '../metadata/types.js';
+/**
+ * Options for the @Route method decorator.
+ */
+export interface RouteOptions {
+    /** Short summary for OpenAPI docs */
+    summary?: string;
+    /** Detailed description for OpenAPI docs */
+    description?: string;
+    /** Unique operation ID for OpenAPI (auto-generated if not provided) */
+    operationId?: string;
+    /** Mark route as deprecated */
+    deprecated?: boolean;
+    /** Authentication requirement */
+    auth?: 'required' | 'optional' | 'none';
+    /** Request body schema (TypeBox) */
+    body?: TSchema;
+    /** Query parameters schema (TypeBox) */
+    query?: TSchema;
+    /** Path parameters schema (TypeBox) */
+    params?: TSchema;
+    /** File upload configuration for multipart/form-data */
+    file?: FileUploadConfig;
+    /**
+     * Response definitions by status code.
+     * Value can be:
+     * - A TypeBox schema
+     * - null (for no body, e.g., 204)
+     * - An object with schema and optional description
+     */
+    responses: Record<number, TSchema | null | {
+        schema: TSchema | null;
+        description?: string;
+    }>;
+    /**
+     * Framework-specific middleware.
+     * This is opaque to the core library - adapters interpret it.
+     */
+    middleware?: unknown[];
+}
+/**
+ * Method decorator that defines an API route with full OpenAPI metadata.
+ *
+ * This decorator captures all information needed to:
+ * 1. Register the route with a framework
+ * 2. Validate request body, query, and path parameters
+ * 3. Generate OpenAPI documentation
+ *
+ * @param route Route string in format "METHOD /path"
+ * @param options Route configuration
+ *
+ * @example Basic GET route
+ * ```typescript
+ * @Route('GET /api/v1/users', {
+ *   summary: 'List all users',
+ *   responses: {
+ *     200: { schema: UserListResponse, description: 'List of users' },
+ *   },
+ * })
+ * async index() { ... }
+ * ```
+ *
+ * @example POST with body and auth
+ * ```typescript
+ * @Route('POST /api/v1/users', {
+ *   summary: 'Create a user',
+ *   auth: 'required',
+ *   body: CreateUserRequest,
+ *   responses: {
+ *     201: { schema: User, description: 'User created' },
+ *     422: { schema: ValidationError },
+ *   },
+ * })
+ * async store(ctx: Context, body: Static<typeof CreateUserRequest>) { ... }
+ * ```
+ *
+ * @example DELETE with no response body
+ * ```typescript
+ * @Route('DELETE /api/v1/users/:id', {
+ *   summary: 'Delete a user',
+ *   auth: 'required',
+ *   params: UserIdParams,
+ *   responses: {
+ *     204: null,
+ *     404: { schema: NotFoundError },
+ *   },
+ * })
+ * async destroy(ctx: Context) { ... }
+ * ```
+ */
+export declare function Route(route: RouteString, options: RouteOptions): MethodDecorator;
+//# sourceMappingURL=route.d.ts.map

package/dist/decorators/route.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"route.d.ts","sourceRoot":"","sources":["../../src/decorators/route.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,mBAAmB,CAAA;AAEhD,OAAO,KAAK,EACV,WAAW,EAGX,gBAAgB,EAEjB,MAAM,sBAAsB,CAAA;AAE7B;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,qCAAqC;IACrC,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,4CAA4C;IAC5C,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,uEAAuE;IACvE,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,+BAA+B;IAC/B,UAAU,CAAC,EAAE,OAAO,CAAA;IACpB,iCAAiC;IACjC,IAAI,CAAC,EAAE,UAAU,GAAG,UAAU,GAAG,MAAM,CAAA;IACvC,oCAAoC;IACpC,IAAI,CAAC,EAAE,OAAO,CAAA;IACd,wCAAwC;IACxC,KAAK,CAAC,EAAE,OAAO,CAAA;IACf,uCAAuC;IACvC,MAAM,CAAC,EAAE,OAAO,CAAA;IAChB,wDAAwD;IACxD,IAAI,CAAC,EAAE,gBAAgB,CAAA;IACvB;;;;;;OAMG;IACH,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,GAAG,IAAI,GAAG;QAAE,MAAM,EAAE,OAAO,GAAG,IAAI,CAAC;QAAC,WAAW,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,CAAA;IAC5F;;;OAGG;IACH,UAAU,CAAC,EAAE,OAAO,EAAE,CAAA;CACvB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiDG;AACH,wBAAgB,KAAK,CACnB,KAAK,EAAE,WAAW,EAClB,OAAO,EAAE,YAAY,GACpB,eAAe,CAwCjB"}

package/dist/decorators/route.js

@@ -0,0 +1,108 @@
+import { addEndpointMetadata } from '../metadata/storage.js';
+/**
+ * Method decorator that defines an API route with full OpenAPI metadata.
+ *
+ * This decorator captures all information needed to:
+ * 1. Register the route with a framework
+ * 2. Validate request body, query, and path parameters
+ * 3. Generate OpenAPI documentation
+ *
+ * @param route Route string in format "METHOD /path"
+ * @param options Route configuration
+ *
+ * @example Basic GET route
+ * ```typescript
+ * @Route('GET /api/v1/users', {
+ *   summary: 'List all users',
+ *   responses: {
+ *     200: { schema: UserListResponse, description: 'List of users' },
+ *   },
+ * })
+ * async index() { ... }
+ * ```
+ *
+ * @example POST with body and auth
+ * ```typescript
+ * @Route('POST /api/v1/users', {
+ *   summary: 'Create a user',
+ *   auth: 'required',
+ *   body: CreateUserRequest,
+ *   responses: {
+ *     201: { schema: User, description: 'User created' },
+ *     422: { schema: ValidationError },
+ *   },
+ * })
+ * async store(ctx: Context, body: Static<typeof CreateUserRequest>) { ... }
+ * ```
+ *
+ * @example DELETE with no response body
+ * ```typescript
+ * @Route('DELETE /api/v1/users/:id', {
+ *   summary: 'Delete a user',
+ *   auth: 'required',
+ *   params: UserIdParams,
+ *   responses: {
+ *     204: null,
+ *     404: { schema: NotFoundError },
+ *   },
+ * })
+ * async destroy(ctx: Context) { ... }
+ * ```
+ */
+export function Route(route, options) {
+    return function (_target, propertyKey, descriptor) {
+        const [method, path] = parseRoute(route);
+        // Normalize responses to consistent format
+        const responses = {};
+        for (const [status, value] of Object.entries(options.responses)) {
+            if (value === null) {
+                responses[Number(status)] = { schema: null };
+            }
+            else if (typeof value === 'object' && 'schema' in value) {
+                responses[Number(status)] = value;
+            }
+            else {
+                responses[Number(status)] = { schema: value };
+            }
+        }
+        const metadata = {
+            method,
+            path,
+            methodName: String(propertyKey),
+            summary: options.summary,
+            description: options.description,
+            operationId: options.operationId,
+            deprecated: options.deprecated,
+            auth: options.auth ?? 'none',
+            body: options.body,
+            query: options.query,
+            params: options.params,
+            file: options.file,
+            responses,
+            middleware: options.middleware,
+        };
+        // Store metadata on the constructor (class), not the prototype
+        // This allows us to retrieve it when scanning controllers
+        const constructor = _target.constructor;
+        addEndpointMetadata(constructor, metadata);
+        return descriptor;
+    };
+}
+/**
+ * Parse a route string into method and path.
+ * @throws Error if route format is invalid
+ */
+function parseRoute(route) {
+    const spaceIndex = route.indexOf(' ');
+    if (spaceIndex === -1) {
+        throw new Error(`Invalid route format: "${route}". Expected "METHOD /path"`);
+    }
+    const methodStr = route.slice(0, spaceIndex).toLowerCase();
+    const path = route.slice(spaceIndex + 1);
+    const validMethods = ['get', 'post', 'put', 'patch', 'delete'];
+    if (!validMethods.includes(methodStr)) {
+        throw new Error(`Invalid HTTP method: "${methodStr}". Expected one of: ${validMethods.join(', ')}`);
+    }
+    return [methodStr, path];
+}
+//# sourceMappingURL=route.js.map

package/dist/decorators/route.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"route.js","sourceRoot":"","sources":["../../src/decorators/route.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,mBAAmB,EAAE,MAAM,wBAAwB,CAAA;AA8C5D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiDG;AACH,MAAM,UAAU,KAAK,CACnB,KAAkB,EAClB,OAAqB;IAErB,OAAO,UAAU,OAAO,EAAE,WAAW,EAAE,UAAU;QAC/C,MAAM,CAAC,MAAM,EAAE,IAAI,CAAC,GAAG,UAAU,CAAC,KAAK,CAAC,CAAA;QAExC,2CAA2C;QAC3C,MAAM,SAAS,GAAuC,EAAE,CAAA;QACxD,KAAK,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC,SAAS,CAAC,EAAE,CAAC;YAChE,IAAI,KAAK,KAAK,IAAI,EAAE,CAAC;gBACnB,SAAS,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,CAAA;YAC9C,CAAC;iBAAM,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,QAAQ,IAAI,KAAK,EAAE,CAAC;gBAC1D,SAAS,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,GAAG,KAA2B,CAAA;YACzD,CAAC;iBAAM,CAAC;gBACN,SAAS,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,MAAM,EAAE,KAAgB,EAAE,CAAA;YAC1D,CAAC;QACH,CAAC;QAED,MAAM,QAAQ,GAAqB;YACjC,MAAM;YACN,IAAI;YACJ,UAAU,EAAE,MAAM,CAAC,WAAW,CAAC;YAC/B,OAAO,EAAE,OAAO,CAAC,OAAO;YACxB,WAAW,EAAE,OAAO,CAAC,WAAW;YAChC,WAAW,EAAE,OAAO,CAAC,WAAW;YAChC,UAAU,EAAE,OAAO,CAAC,UAAU;YAC9B,IAAI,EAAE,OAAO,CAAC,IAAI,IAAI,MAAM;YAC5B,IAAI,EAAE,OAAO,CAAC,IAAI;YAClB,KAAK,EAAE,OAAO,CAAC,KAAK;YACpB,MAAM,EAAE,OAAO,CAAC,MAAM;YACtB,IAAI,EAAE,OAAO,CAAC,IAAI;YAClB,SAAS;YACT,UAAU,EAAE,OAAO,CAAC,UAAU;SAC/B,CAAA;QAED,+DAA+D;QAC/D,0DAA0D;QAC1D,MAAM,WAAW,GAAI,OAAkB,CAAC,WAAW,CAAA;QACnD,mBAAmB,CAAC,WAAW,EAAE,QAAQ,CAAC,CAAA;QAE1C,OAAO,UAAU,CAAA;IACnB,CAAC,CAAA;AACH,CAAC;AAED;;;GAGG;AACH,SAAS,UAAU,CAAC,KAAkB;IACpC,MAAM,UAAU,GAAG,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,CAAA;IACrC,IAAI,UAAU,KAAK,CAAC,CAAC,EAAE,CAAC;QACtB,MAAM,IAAI,KAAK,CAAC,0BAA0B,KAAK,4BAA4B,CAAC,CAAA;IAC9E,CAAC;IAED,MAAM,SAAS,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,UAAU,CAAC,CAAC,WAAW,EAAE,CAAA;IAC1D,MAAM,IAAI,GAAG,KAAK,CAAC,KAAK,CAAC,UAAU,GAAG,CAAC,CAAC,CAAA;IAExC,MAAM,YAAY,GAAiB,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,QAAQ,CAAC,CAAA;IAC5E,IAAI,CAAC,YAAY,CAAC,QAAQ,CAAC,SAAuB,CAAC,EAAE,CAAC;QACpD,MAAM,IAAI,KAAK,CAAC,yBAAyB,SAAS,uBAAuB,YAAY,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAA;IACrG,CAAC;IAED,OAAO,CAAC,SAAuB,EAAE,IAAI,CAAC,CAAA;AACxC,CAAC"}

package/dist/errors/base.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Base error class for all kontract errors.
+ */
+export declare class OpenApiDecoratorError extends Error {
+    readonly code: string;
+    constructor(code: string, message: string);
+}
+//# sourceMappingURL=base.d.ts.map

package/dist/errors/base.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"base.d.ts","sourceRoot":"","sources":["../../src/errors/base.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,qBAAa,qBAAsB,SAAQ,KAAK;IAC9C,SAAgB,IAAI,EAAE,MAAM,CAAA;gBAEhB,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM;CAM1C"}

package/dist/errors/base.js

@@ -0,0 +1,13 @@
+/**
+ * Base error class for all kontract errors.
+ */
+export class OpenApiDecoratorError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = 'OpenApiDecoratorError';
+        this.code = code;
+        Error.captureStackTrace?.(this, this.constructor);
+    }
+}
+//# sourceMappingURL=base.js.map

package/dist/errors/base.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"base.js","sourceRoot":"","sources":["../../src/errors/base.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,MAAM,OAAO,qBAAsB,SAAQ,KAAK;IAC9B,IAAI,CAAQ;IAE5B,YAAY,IAAY,EAAE,OAAe;QACvC,KAAK,CAAC,OAAO,CAAC,CAAA;QACd,IAAI,CAAC,IAAI,GAAG,uBAAuB,CAAA;QACnC,IAAI,CAAC,IAAI,GAAG,IAAI,CAAA;QAChB,KAAK,CAAC,iBAAiB,EAAE,CAAC,IAAI,EAAE,IAAI,CAAC,WAAW,CAAC,CAAA;IACnD,CAAC;CACF"}

package/dist/errors/configuration.d.ts

@@ -0,0 +1,22 @@
+import { OpenApiDecoratorError } from './base.js';
+/**
+ * Error thrown when configuration is invalid or missing.
+ */
+export declare class ConfigurationError extends OpenApiDecoratorError {
+    constructor(message: string);
+}
+/**
+ * Error thrown when a required adapter is not registered.
+ */
+export declare class AdapterNotFoundError extends OpenApiDecoratorError {
+    readonly adapterType: string;
+    constructor(adapterType: string);
+}
+/**
+ * Error thrown when a serializer is not found for a type.
+ */
+export declare class SerializerNotFoundError extends OpenApiDecoratorError {
+    readonly typeName: string;
+    constructor(typeName: string);
+}
+//# sourceMappingURL=configuration.d.ts.map

package/dist/errors/configuration.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"configuration.d.ts","sourceRoot":"","sources":["../../src/errors/configuration.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,qBAAqB,EAAE,MAAM,WAAW,CAAA;AAEjD;;GAEG;AACH,qBAAa,kBAAmB,SAAQ,qBAAqB;gBAC/C,OAAO,EAAE,MAAM;CAI5B;AAED;;GAEG;AACH,qBAAa,oBAAqB,SAAQ,qBAAqB;IAC7D,SAAgB,WAAW,EAAE,MAAM,CAAA;gBAEvB,WAAW,EAAE,MAAM;CAKhC;AAED;;GAEG;AACH,qBAAa,uBAAwB,SAAQ,qBAAqB;IAChE,SAAgB,QAAQ,EAAE,MAAM,CAAA;gBAEpB,QAAQ,EAAE,MAAM;CAK7B"}

package/dist/errors/configuration.js

@@ -0,0 +1,33 @@
+import { OpenApiDecoratorError } from './base.js';
+/**
+ * Error thrown when configuration is invalid or missing.
+ */
+export class ConfigurationError extends OpenApiDecoratorError {
+    constructor(message) {
+        super('E_CONFIGURATION', message);
+        this.name = 'ConfigurationError';
+    }
+}
+/**
+ * Error thrown when a required adapter is not registered.
+ */
+export class AdapterNotFoundError extends OpenApiDecoratorError {
+    adapterType;
+    constructor(adapterType) {
+        super('E_ADAPTER_NOT_FOUND', `No ${adapterType} adapter registered. Did you forget to configure it?`);
+        this.name = 'AdapterNotFoundError';
+        this.adapterType = adapterType;
+    }
+}
+/**
+ * Error thrown when a serializer is not found for a type.
+ */
+export class SerializerNotFoundError extends OpenApiDecoratorError {
+    typeName;
+    constructor(typeName) {
+        super('E_SERIALIZER_NOT_FOUND', `No serializer registered for type: ${typeName}`);
+        this.name = 'SerializerNotFoundError';
+        this.typeName = typeName;
+    }
+}
+//# sourceMappingURL=configuration.js.map

package/dist/errors/configuration.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"configuration.js","sourceRoot":"","sources":["../../src/errors/configuration.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,qBAAqB,EAAE,MAAM,WAAW,CAAA;AAEjD;;GAEG;AACH,MAAM,OAAO,kBAAmB,SAAQ,qBAAqB;IAC3D,YAAY,OAAe;QACzB,KAAK,CAAC,iBAAiB,EAAE,OAAO,CAAC,CAAA;QACjC,IAAI,CAAC,IAAI,GAAG,oBAAoB,CAAA;IAClC,CAAC;CACF;AAED;;GAEG;AACH,MAAM,OAAO,oBAAqB,SAAQ,qBAAqB;IAC7C,WAAW,CAAQ;IAEnC,YAAY,WAAmB;QAC7B,KAAK,CAAC,qBAAqB,EAAE,MAAM,WAAW,sDAAsD,CAAC,CAAA;QACrG,IAAI,CAAC,IAAI,GAAG,sBAAsB,CAAA;QAClC,IAAI,CAAC,WAAW,GAAG,WAAW,CAAA;IAChC,CAAC;CACF;AAED;;GAEG;AACH,MAAM,OAAO,uBAAwB,SAAQ,qBAAqB;IAChD,QAAQ,CAAQ;IAEhC,YAAY,QAAgB;QAC1B,KAAK,CAAC,wBAAwB,EAAE,sCAAsC,QAAQ,EAAE,CAAC,CAAA;QACjF,IAAI,CAAC,IAAI,GAAG,yBAAyB,CAAA;QACrC,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAA;IAC1B,CAAC;CACF"}

package/dist/errors/index.d.ts

@@ -0,0 +1,4 @@
+export { OpenApiDecoratorError } from './base.js';
+export { RequestValidationError, ResponseValidationError, type ValidationErrorDetail, } from './validation.js';
+export { ConfigurationError, AdapterNotFoundError, SerializerNotFoundError, } from './configuration.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/errors/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/errors/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,qBAAqB,EAAE,MAAM,WAAW,CAAA;AAEjD,OAAO,EACL,sBAAsB,EACtB,uBAAuB,EACvB,KAAK,qBAAqB,GAC3B,MAAM,iBAAiB,CAAA;AAExB,OAAO,EACL,kBAAkB,EAClB,oBAAoB,EACpB,uBAAuB,GACxB,MAAM,oBAAoB,CAAA"}

package/dist/errors/index.js

@@ -0,0 +1,4 @@
+export { OpenApiDecoratorError } from './base.js';
+export { RequestValidationError, ResponseValidationError, } from './validation.js';
+export { ConfigurationError, AdapterNotFoundError, SerializerNotFoundError, } from './configuration.js';
+//# sourceMappingURL=index.js.map

package/dist/errors/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/errors/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,qBAAqB,EAAE,MAAM,WAAW,CAAA;AAEjD,OAAO,EACL,sBAAsB,EACtB,uBAAuB,GAExB,MAAM,iBAAiB,CAAA;AAExB,OAAO,EACL,kBAAkB,EAClB,oBAAoB,EACpB,uBAAuB,GACxB,MAAM,oBAAoB,CAAA"}