kontract 0.1.0

package/dist/runtime/response-helpers.d.ts

@@ -0,0 +1,138 @@
+import type { NormalizedResponses } from './adapter-types.js';
+/**
+ * Default error codes for each HTTP status.
+ */
+export declare const ERROR_CODES: Record<number, string>;
+/**
+ * Create a success helper (just wraps data with status).
+ */
+export declare function createSuccessHelper(status: number): (data: unknown) => {
+    status: number;
+    data: unknown;
+};
+/**
+ * Create an error helper with smart defaults.
+ * - No args: use description from response definition as message
+ * - String passed: use as message, auto-fill status and code
+ * - Object passed: merge with defaults (status, code, and description as message)
+ */
+export declare function createErrorHelper(status: number, defaultCode: string, defaultMessage: string): (dataOrMessage?: unknown) => {
+    status: number;
+    data: {
+        status: number;
+        code: string;
+        message: string;
+    };
+};
+/**
+ * Get the default error message for a status code.
+ * Priority: explicit description > schema description > generic fallback
+ */
+export declare function getErrorMessage(responses: NormalizedResponses, status: number, fallback: string): string;
+/**
+ * Create namespaced response helper functions bound to the route's response schemas.
+ * These helpers don't need the schema passed - they're pre-typed at compile time.
+ *
+ * Returns `{ reply, error }` namespaces:
+ * - `reply` contains success helpers (ok, created, accepted, noContent, list)
+ * - `error` contains error helpers with smart defaults (uses schema description as default message)
+ */
+export declare function createResponseHelpers(responses: NormalizedResponses): {
+    reply: {
+        ok: (data: unknown) => {
+            status: number;
+            data: unknown;
+        };
+        created: (data: unknown) => {
+            status: number;
+            data: unknown;
+        };
+        accepted: (data: unknown) => {
+            status: number;
+            data: unknown;
+        };
+        noContent: () => {
+            status: 204;
+            data: null;
+        };
+        list: (data: unknown) => {
+            status: number;
+            data: unknown;
+        };
+    };
+    error: {
+        badRequest: (dataOrMessage?: unknown) => {
+            status: number;
+            data: {
+                status: number;
+                code: string;
+                message: string;
+            };
+        };
+        unauthorized: (dataOrMessage?: unknown) => {
+            status: number;
+            data: {
+                status: number;
+                code: string;
+                message: string;
+            };
+        };
+        forbidden: (dataOrMessage?: unknown) => {
+            status: number;
+            data: {
+                status: number;
+                code: string;
+                message: string;
+            };
+        };
+        notFound: (dataOrMessage?: unknown) => {
+            status: number;
+            data: {
+                status: number;
+                code: string;
+                message: string;
+            };
+        };
+        conflict: (dataOrMessage?: unknown) => {
+            status: number;
+            data: {
+                status: number;
+                code: string;
+                message: string;
+            };
+        };
+        validationError: (dataOrMessage?: unknown) => {
+            status: number;
+            data: {
+                status: number;
+                code: string;
+                message: string;
+            };
+        };
+        tooManyRequests: (dataOrMessage?: unknown) => {
+            status: number;
+            data: {
+                status: number;
+                code: string;
+                message: string;
+            };
+        };
+        internal: (dataOrMessage?: unknown) => {
+            status: number;
+            data: {
+                status: number;
+                code: string;
+                message: string;
+            };
+        };
+        serviceUnavailable: (dataOrMessage?: unknown) => {
+            status: number;
+            data: {
+                status: number;
+                code: string;
+                message: string;
+            };
+        };
+    };
+};
+//# sourceMappingURL=response-helpers.d.ts.map

package/dist/runtime/response-helpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"response-helpers.d.ts","sourceRoot":"","sources":["../../src/runtime/response-helpers.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAA;AAM7D;;GAEG;AACH,eAAO,MAAM,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAU9C,CAAA;AAMD;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,MAAM,IACxC,MAAM,OAAO;;;EACtB;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM,IACnF,gBAAgB,OAAO;;;;;;;EA2BhC;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAC7B,SAAS,EAAE,mBAAmB,EAC9B,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,MAAM,GACf,MAAM,CAKR;AAED;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CAAC,SAAS,EAAE,mBAAmB;;mBA9DpD,OAAO;;;;wBAAP,OAAO;;;;yBAAP,OAAO;;;;;;;;qBAAP,OAAO;;;;;;qCAUG,OAAO;;;;;;;;uCAAP,OAAO;;;;;;;;oCAAP,OAAO;;;;;;;;mCAAP,OAAO;;;;;;;;mCAAP,OAAO;;;;;;;;0CAAP,OAAO;;;;;;;;0CAAP,OAAO;;;;;;;;mCAAP,OAAO;;;;;;;;6CAAP,OAAO;;;;;;;;;EA4EhC"}

package/dist/runtime/response-helpers.js

@@ -0,0 +1,105 @@
+// ============================================================================
+// Constants
+// ============================================================================
+/**
+ * Default error codes for each HTTP status.
+ */
+export const ERROR_CODES = {
+    400: 'E_BAD_REQUEST',
+    401: 'E_UNAUTHORIZED',
+    403: 'E_FORBIDDEN',
+    404: 'E_NOT_FOUND',
+    409: 'E_CONFLICT',
+    422: 'E_VALIDATION',
+    429: 'E_TOO_MANY_REQUESTS',
+    500: 'E_INTERNAL_SERVER_ERROR',
+    503: 'E_SERVICE_UNAVAILABLE',
+};
+// ============================================================================
+// Helper Functions
+// ============================================================================
+/**
+ * Create a success helper (just wraps data with status).
+ */
+export function createSuccessHelper(status) {
+    return (data) => ({ status, data });
+}
+/**
+ * Create an error helper with smart defaults.
+ * - No args: use description from response definition as message
+ * - String passed: use as message, auto-fill status and code
+ * - Object passed: merge with defaults (status, code, and description as message)
+ */
+export function createErrorHelper(status, defaultCode, defaultMessage) {
+    return (dataOrMessage) => {
+        // No args: error.internal() - use description as default message
+        if (dataOrMessage === undefined) {
+            return {
+                status,
+                data: { status, code: defaultCode, message: defaultMessage },
+            };
+        }
+        // String shorthand: error.badRequest('Invalid token')
+        if (typeof dataOrMessage === 'string') {
+            return {
+                status,
+                data: { status, code: defaultCode, message: dataOrMessage },
+            };
+        }
+        // Object: merge with defaults
+        const data = dataOrMessage;
+        return {
+            status,
+            data: {
+                status,
+                code: defaultCode,
+                message: defaultMessage, // Default from description
+                ...data, // User can override
+            },
+        };
+    };
+}
+/**
+ * Get the default error message for a status code.
+ * Priority: explicit description > schema description > generic fallback
+ */
+export function getErrorMessage(responses, status, fallback) {
+    const response = responses[status];
+    return response?.description
+        ?? response?.schema?.description
+        ?? fallback;
+}
+/**
+ * Create namespaced response helper functions bound to the route's response schemas.
+ * These helpers don't need the schema passed - they're pre-typed at compile time.
+ *
+ * Returns `{ reply, error }` namespaces:
+ * - `reply` contains success helpers (ok, created, accepted, noContent, list)
+ * - `error` contains error helpers with smart defaults (uses schema description as default message)
+ */
+export function createResponseHelpers(responses) {
+    return {
+        // Success responses namespace (2xx)
+        reply: {
+            ok: createSuccessHelper(200),
+            created: createSuccessHelper(201),
+            accepted: createSuccessHelper(202),
+            noContent: () => ({ status: 204, data: null }),
+            list: createSuccessHelper(200),
+        },
+        // Error responses namespace (4xx/5xx) - with smart defaults
+        // Default message: explicit description > schema.description > generic fallback
+        error: {
+            badRequest: createErrorHelper(400, ERROR_CODES[400], getErrorMessage(responses, 400, 'Bad request')),
+            unauthorized: createErrorHelper(401, ERROR_CODES[401], getErrorMessage(responses, 401, 'Unauthorized')),
+            forbidden: createErrorHelper(403, ERROR_CODES[403], getErrorMessage(responses, 403, 'Forbidden')),
+            notFound: createErrorHelper(404, ERROR_CODES[404], getErrorMessage(responses, 404, 'Not found')),
+            conflict: createErrorHelper(409, ERROR_CODES[409], getErrorMessage(responses, 409, 'Conflict')),
+            validationError: createErrorHelper(422, ERROR_CODES[422], getErrorMessage(responses, 422, 'Validation failed')),
+            tooManyRequests: createErrorHelper(429, ERROR_CODES[429], getErrorMessage(responses, 429, 'Too many requests')),
+            internal: createErrorHelper(500, ERROR_CODES[500], getErrorMessage(responses, 500, 'Internal server error')),
+            serviceUnavailable: createErrorHelper(503, ERROR_CODES[503], getErrorMessage(responses, 503, 'Service unavailable')),
+        },
+    };
+}
+//# sourceMappingURL=response-helpers.js.map

package/dist/runtime/response-helpers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"response-helpers.js","sourceRoot":"","sources":["../../src/runtime/response-helpers.ts"],"names":[],"mappings":"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"}

package/dist/runtime/route-utils.d.ts

@@ -0,0 +1,22 @@
+import type { ApiResponse } from '../response/types.js';
+import type { RouteString } from '../metadata/types.js';
+import type { ResponsesConfig, NormalizedResponses } from './adapter-types.js';
+export type { RouteString } from '../metadata/types.js';
+/**
+ * Parse a route string into method and path.
+ */
+export declare function parseRouteString(route: RouteString): [string, string];
+/**
+ * Normalize response definitions to consistent format.
+ * Preserves all fields including headers, examples, and example.
+ */
+export declare function normalizeResponses(responses: ResponsesConfig): NormalizedResponses;
+/**
+ * Check if a value looks like an API response object.
+ */
+export declare function isApiResponse(value: unknown): value is ApiResponse<number, unknown>;
+/**
+ * Return 204 No Content.
+ */
+export declare function noContent(): ApiResponse<204, null>;
+//# sourceMappingURL=route-utils.d.ts.map

package/dist/runtime/route-utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"route-utils.d.ts","sourceRoot":"","sources":["../../src/runtime/route-utils.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAA;AACvD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAA;AACvD,OAAO,KAAK,EAAE,eAAe,EAAsB,mBAAmB,EAAE,MAAM,oBAAoB,CAAA;AAGlG,YAAY,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAA;AAEvD;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,WAAW,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAKrE;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,SAAS,EAAE,eAAe,GAAG,mBAAmB,CAelF;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,WAAW,CAAC,MAAM,EAAE,OAAO,CAAC,CASnF;AAED;;GAEG;AACH,wBAAgB,SAAS,IAAI,WAAW,CAAC,GAAG,EAAE,IAAI,CAAC,CAElD"}

package/dist/runtime/route-utils.js

@@ -0,0 +1,47 @@
+/**
+ * Parse a route string into method and path.
+ */
+export function parseRouteString(route) {
+    const spaceIndex = route.indexOf(' ');
+    const method = route.slice(0, spaceIndex).toLowerCase();
+    const path = route.slice(spaceIndex + 1);
+    return [method, path];
+}
+/**
+ * Normalize response definitions to consistent format.
+ * Preserves all fields including headers, examples, and example.
+ */
+export function normalizeResponses(responses) {
+    const normalized = {};
+    for (const [status, value] of Object.entries(responses)) {
+        if (value === null) {
+            normalized[Number(status)] = { schema: null };
+        }
+        else if (typeof value === 'object' && 'schema' in value) {
+            // Preserve all fields: schema, description, headers, examples, example
+            normalized[Number(status)] = value;
+        }
+        else {
+            normalized[Number(status)] = { schema: value };
+        }
+    }
+    return normalized;
+}
+/**
+ * Check if a value looks like an API response object.
+ */
+export function isApiResponse(value) {
+    return (value !== null
+        && typeof value === 'object'
+        && 'status' in value
+        && typeof value.status === 'number'
+        && 'data' in value
+        && !('binary' in value));
+}
+/**
+ * Return 204 No Content.
+ */
+export function noContent() {
+    return { status: 204, data: null };
+}
+//# sourceMappingURL=route-utils.js.map

package/dist/runtime/route-utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"route-utils.js","sourceRoot":"","sources":["../../src/runtime/route-utils.ts"],"names":[],"mappings":"AAaA;;GAEG;AACH,MAAM,UAAU,gBAAgB,CAAC,KAAkB;IACjD,MAAM,UAAU,GAAG,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,CAAA;IACrC,MAAM,MAAM,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,UAAU,CAAC,CAAC,WAAW,EAAE,CAAA;IACvD,MAAM,IAAI,GAAG,KAAK,CAAC,KAAK,CAAC,UAAU,GAAG,CAAC,CAAC,CAAA;IACxC,OAAO,CAAC,MAAM,EAAE,IAAI,CAAC,CAAA;AACvB,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,kBAAkB,CAAC,SAA0B;IAC3D,MAAM,UAAU,GAAwB,EAAE,CAAA;IAE1C,KAAK,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,EAAE,CAAC;QACxD,IAAI,KAAK,KAAK,IAAI,EAAE,CAAC;YACnB,UAAU,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,CAAA;QAC/C,CAAC;aAAM,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,QAAQ,IAAI,KAAK,EAAE,CAAC;YAC1D,uEAAuE;YACvE,UAAU,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,GAAG,KAA2B,CAAA;QAC1D,CAAC;aAAM,CAAC;YACN,UAAU,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,MAAM,EAAE,KAAgB,EAAE,CAAA;QAC3D,CAAC;IACH,CAAC;IAED,OAAO,UAAU,CAAA;AACnB,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,aAAa,CAAC,KAAc;IAC1C,OAAO,CACL,KAAK,KAAK,IAAI;WACX,OAAO,KAAK,KAAK,QAAQ;WACzB,QAAQ,IAAI,KAAK;WACjB,OAAQ,KAA6B,CAAC,MAAM,KAAK,QAAQ;WACzD,MAAM,IAAI,KAAK;WACf,CAAC,CAAC,QAAQ,IAAI,KAAK,CAAC,CACxB,CAAA;AACH,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,SAAS;IACvB,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,IAAI,EAAE,IAAI,EAAE,CAAA;AACpC,CAAC"}

package/dist/runtime/types.d.ts

@@ -0,0 +1,125 @@
+import type { HttpMethod, EndpointMetadata } from '../metadata/types.js';
+import type { AnyResponse } from '../response/types.js';
+/**
+ * Framework-agnostic request representation.
+ */
+export interface RequestContext {
+    /** HTTP method (lowercase) */
+    method: HttpMethod;
+    /** Request path */
+    path: string;
+    /** Parsed path parameters */
+    params: Record<string, string>;
+    /** Parsed query parameters */
+    query: Record<string, unknown>;
+    /** Request body (parsed) */
+    body: unknown;
+    /** Request headers */
+    headers: Record<string, string | string[] | undefined>;
+    /** Framework-specific request object */
+    raw: unknown;
+}
+/**
+ * User information from authentication.
+ */
+export interface AuthUser {
+    id: string | number;
+    [key: string]: unknown;
+}
+/**
+ * Authentication result.
+ */
+export interface AuthResult {
+    authenticated: boolean;
+    user?: AuthUser;
+}
+/**
+ * Route handler signature for adapter implementations.
+ * @see RouteHandler from builder/define-route.ts for user-facing handler type
+ */
+export type AdapterRouteHandler = (ctx: RequestContext) => Promise<AnyResponse>;
+/**
+ * Router adapter interface.
+ * Implement this to integrate with a web framework.
+ */
+export interface RouterAdapter {
+    /**
+     * Register a route with the framework.
+     */
+    register(method: HttpMethod, path: string, handler: AdapterRouteHandler, metadata: EndpointMetadata): void;
+    /**
+     * Get all registered routes (optional, for debugging).
+     */
+    getRoutes?(): Array<{
+        method: HttpMethod;
+        path: string;
+    }>;
+}
+/**
+ * Authentication adapter interface.
+ * Implement this to integrate with an auth system.
+ */
+export interface AuthAdapter {
+    /**
+     * Authenticate the request.
+     * Should return user info if authenticated, or null/undefined otherwise.
+     */
+    authenticate(ctx: RequestContext): Promise<AuthResult>;
+    /**
+     * Get the authenticated user or throw if not authenticated.
+     */
+    getUserOrFail(ctx: RequestContext): Promise<AuthUser>;
+}
+/**
+ * Container/DI adapter interface.
+ * Implement this to integrate with a dependency injection container.
+ */
+export interface ContainerAdapter {
+    /**
+     * Resolve a class from the container.
+     */
+    resolve<T>(target: new (...args: unknown[]) => T): T;
+    /**
+     * Check if a class is registered in the container.
+     */
+    has(target: new (...args: unknown[]) => unknown): boolean;
+}
+/**
+ * Response adapter interface.
+ * Implement this to send responses through the framework.
+ */
+export interface ResponseAdapter {
+    /**
+     * Send a JSON response.
+     */
+    sendJson(ctx: RequestContext, status: number, data: unknown): void;
+    /**
+     * Send a binary/file response.
+     */
+    sendBinary(ctx: RequestContext, status: number, contentType: string, data: Buffer | string, filename?: string): void;
+    /**
+     * Send an empty response (204 No Content).
+     */
+    sendEmpty(ctx: RequestContext, status: number): void;
+}
+/**
+ * Logger adapter interface.
+ * Implement this to integrate with a logging system.
+ */
+export interface LoggerAdapter {
+    debug(message: string, data?: Record<string, unknown>): void;
+    info(message: string, data?: Record<string, unknown>): void;
+    warn(message: string, data?: Record<string, unknown>): void;
+    error(message: string, data?: Record<string, unknown>): void;
+}
+/**
+ * Complete adapter set for a framework integration.
+ */
+export interface FrameworkAdapters {
+    router: RouterAdapter;
+    auth?: AuthAdapter;
+    container?: ContainerAdapter;
+    response: ResponseAdapter;
+    logger?: LoggerAdapter;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/runtime/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/runtime/types.ts"],"names":[],"mappings":"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"}

package/dist/runtime/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/runtime/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/runtime/types.ts"],"names":[],"mappings":""}

package/dist/validation/index.d.ts

@@ -0,0 +1,3 @@
+export type { Validator, CompiledValidator, ValidatorOptions, } from './types.js';
+export { RequestValidationError, ResponseValidationError, type ValidationErrorDetail, } from '../errors/validation.js';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/validation/index.ts"],"names":[],"mappings":"AAAA,YAAY,EACV,SAAS,EACT,iBAAiB,EACjB,gBAAgB,GACjB,MAAM,YAAY,CAAA;AAGnB,OAAO,EACL,sBAAsB,EACtB,uBAAuB,EACvB,KAAK,qBAAqB,GAC3B,MAAM,yBAAyB,CAAA"}

package/dist/validation/index.js

@@ -0,0 +1,3 @@
+// Re-export validation errors for convenience
+export { RequestValidationError, ResponseValidationError, } from '../errors/validation.js';
+//# sourceMappingURL=index.js.map

package/dist/validation/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/validation/index.ts"],"names":[],"mappings":"AAMA,8CAA8C;AAC9C,OAAO,EACL,sBAAsB,EACtB,uBAAuB,GAExB,MAAM,yBAAyB,CAAA"}

package/dist/validation/types.d.ts

@@ -0,0 +1,55 @@
+import type { TSchema } from '@sinclair/typebox';
+import type { ValidationErrorDetail } from '../errors/validation.js';
+/**
+ * Validator interface for schema validation.
+ * Implement this to use a different validation library.
+ */
+export interface Validator {
+    /**
+     * Validate data against a schema.
+     * @returns Array of errors, or empty array if valid
+     */
+    validate(schema: TSchema, data: unknown): ValidationErrorDetail[];
+    /**
+     * Validate and throw if invalid.
+     * @throws ValidationError if validation fails
+     */
+    validateOrThrow(schema: TSchema, data: unknown): void;
+    /**
+     * Compile a schema for repeated validation.
+     * Optional optimization for validators that support it.
+     */
+    compile?(schema: TSchema): CompiledValidator;
+}
+/**
+ * Pre-compiled validator for performance.
+ */
+export interface CompiledValidator {
+    validate(data: unknown): ValidationErrorDetail[];
+    validateOrThrow(data: unknown): void;
+}
+/**
+ * Options for creating a validator.
+ */
+export interface ValidatorOptions {
+    /**
+     * Whether to remove additional properties not in schema.
+     * @default false
+     */
+    removeAdditional?: boolean;
+    /**
+     * Whether to coerce types (e.g., "123" to 123).
+     * @default false
+     */
+    coerceTypes?: boolean;
+    /**
+     * Whether to use defaults from schema.
+     * @default true
+     */
+    useDefaults?: boolean;
+    /**
+     * Custom formats to register.
+     */
+    formats?: Record<string, (value: string) => boolean>;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/validation/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/validation/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,mBAAmB,CAAA;AAChD,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,yBAAyB,CAAA;AAEpE;;;GAGG;AACH,MAAM,WAAW,SAAS;IACxB;;;OAGG;IACH,QAAQ,CAAC,MAAM,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,GAAG,qBAAqB,EAAE,CAAA;IAEjE;;;OAGG;IACH,eAAe,CAAC,MAAM,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,GAAG,IAAI,CAAA;IAErD;;;OAGG;IACH,OAAO,CAAC,CAAC,MAAM,EAAE,OAAO,GAAG,iBAAiB,CAAA;CAC7C;AAED;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,IAAI,EAAE,OAAO,GAAG,qBAAqB,EAAE,CAAA;IAChD,eAAe,CAAC,IAAI,EAAE,OAAO,GAAG,IAAI,CAAA;CACrC;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B;;;OAGG;IACH,gBAAgB,CAAC,EAAE,OAAO,CAAA;IAE1B;;;OAGG;IACH,WAAW,CAAC,EAAE,OAAO,CAAA;IAErB;;;OAGG;IACH,WAAW,CAAC,EAAE,OAAO,CAAA;IAErB;;OAEG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,CAAA;CACrD"}

package/dist/validation/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/validation/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/validation/types.ts"],"names":[],"mappings":""}

package/package.json

@@ -0,0 +1,93 @@
+{
+  "name": "kontract",
+  "version": "0.1.0",
+  "description": "Framework-agnostic type-safe API contracts with TypeBox schema support",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./response": {
+      "types": "./dist/response/index.d.ts",
+      "import": "./dist/response/index.js"
+    },
+    "./metadata": {
+      "types": "./dist/metadata/index.d.ts",
+      "import": "./dist/metadata/index.js"
+    },
+    "./config": {
+      "types": "./dist/config/index.d.ts",
+      "import": "./dist/config/index.js"
+    },
+    "./errors": {
+      "types": "./dist/errors/index.d.ts",
+      "import": "./dist/errors/index.js"
+    },
+    "./validation": {
+      "types": "./dist/validation/index.d.ts",
+      "import": "./dist/validation/index.js"
+    },
+    "./runtime": {
+      "types": "./dist/runtime/index.d.ts",
+      "import": "./dist/runtime/index.js"
+    },
+    "./builder": {
+      "types": "./dist/builder/index.d.ts",
+      "import": "./dist/builder/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint src/",
+    "lint:fix": "eslint src/ --fix",
+    "clean": "rm -rf dist",
+    "test": "TSX_TSCONFIG_PATH=tsconfig.test.json node --import=tsx bin/test.ts"
+  },
+  "dependencies": {
+    "@sinclair/typebox": "^0.34.33"
+  },
+  "devDependencies": {
+    "@japa/assert": "^4.2.0",
+    "@japa/runner": "^4.4.0",
+    "@types/node": "^22.15.21",
+    "tsx": "^4.19.0",
+    "typescript": "^5.8.3"
+  },
+  "peerDependencies": {
+    "@sinclair/typebox": ">=0.32.0"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "keywords": [
+    "openapi",
+    "swagger",
+    "typescript",
+    "typebox",
+    "api",
+    "rest",
+    "documentation",
+    "type-safe",
+    "contracts"
+  ],
+  "author": "Drew Daniels",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Drew-Daniels/kontract.git",
+    "directory": "packages/kontract"
+  },
+  "homepage": "https://github.com/Drew-Daniels/kontract#readme",
+  "bugs": {
+    "url": "https://github.com/Drew-Daniels/kontract/issues"
+  }
+}