@vfarcic/dot-ai 1.0.2 → 1.1.0

package/dist/interfaces/rest-registry.d.ts

@@ -13,7 +13,7 @@ export interface ToolMetadata {
     name: string;
     description: string;
     inputSchema: Record<string, z.ZodSchema>;
-    handler: (...args: any[]) => Promise<any>;
+    handler: (...args: unknown[]) => Promise<unknown>;
     category?: string;
     tags?: string[];
 }
@@ -22,12 +22,12 @@ export interface ToolMetadata {
  */
 export interface JsonSchema {
     type?: string;
-    properties?: Record<string, any>;
+    properties?: Record<string, unknown>;
     required?: string[];
     description?: string;
     $ref?: string;
-    definitions?: Record<string, any>;
-    [key: string]: any;
+    definitions?: Record<string, unknown>;
+    [key: string]: unknown;
 }
 /**
  * Tool information exposed via discovery endpoint

package/dist/interfaces/rest-registry.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"rest-registry.d.ts","sourceRoot":"","sources":["../../src/interfaces/rest-registry.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,EAAE,MAAM,EAAE,MAAM,wBAAwB,CAAC;AAEhD;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC,SAAS,CAAC,CAAC;IACzC,OAAO,EAAE,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,OAAO,CAAC,GAAG,CAAC,CAAC;IAC1C,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;CACjB;AAED;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IACjC,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IACpB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IAClC,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,CAAC;CACpB;AAED;;GAEG;AACH,MAAM,WAAW,QAAQ;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,UAAU,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;CACjB;AAED;;GAEG;AACH,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,KAAK,CAAwC;IACrD,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,WAAW,CAAsC;gBAE7C,MAAM,EAAE,MAAM;IAI1B;;OAEG;IACH,YAAY,CAAC,QAAQ,EAAE,YAAY,GAAG,IAAI;IAa1C;;OAEG;IACH,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,YAAY,GAAG,SAAS;IAI/C;;OAEG;IACH,YAAY,IAAI,MAAM,EAAE;IAIxB;;OAEG;IACH,WAAW,IAAI,QAAQ,EAAE;IAazB;;OAEG;IACH,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;IAI9B;;OAEG;IACH,YAAY,IAAI,MAAM;IAItB;;OAEG;IACH,KAAK,IAAI,IAAI;IAMb;;OAEG;IACH,OAAO,CAAC,4BAA4B;IAyDpC;;OAEG;IACH,gBAAgB,CAAC,OAAO,GAAE;QACxB,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,GAAG,CAAC,EAAE,MAAM,CAAC;QACb,MAAM,CAAC,EAAE,MAAM,CAAC;KACZ,GAAG,QAAQ,EAAE;IAsBnB;;OAEG;IACH,aAAa,IAAI,MAAM,EAAE;IAUzB;;OAEG;IACH,OAAO,IAAI,MAAM,EAAE;IAUnB;;OAEG;IACH,QAAQ,IAAI;QACV,UAAU,EAAE,MAAM,CAAC;QACnB,UAAU,EAAE,MAAM,EAAE,CAAC;QACrB,IAAI,EAAE,MAAM,EAAE,CAAC;QACf,SAAS,EAAE,MAAM,CAAC;KACnB;CAQF"}
+{"version":3,"file":"rest-registry.d.ts","sourceRoot":"","sources":["../../src/interfaces/rest-registry.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,EAAE,MAAM,EAAE,MAAM,wBAAwB,CAAC;AAEhD;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC,SAAS,CAAC,CAAC;IACzC,OAAO,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IAClD,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;CACjB;AAED;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACrC,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IACpB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACtC,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED;;GAEG;AACH,MAAM,WAAW,QAAQ;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,UAAU,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;CACjB;AAED;;GAEG;AACH,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,KAAK,CAAwC;IACrD,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,WAAW,CAAsC;gBAE7C,MAAM,EAAE,MAAM;IAI1B;;OAEG;IACH,YAAY,CAAC,QAAQ,EAAE,YAAY,GAAG,IAAI;IAa1C;;OAEG;IACH,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,YAAY,GAAG,SAAS;IAI/C;;OAEG;IACH,YAAY,IAAI,MAAM,EAAE;IAIxB;;OAEG;IACH,WAAW,IAAI,QAAQ,EAAE;IAazB;;OAEG;IACH,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;IAI9B;;OAEG;IACH,YAAY,IAAI,MAAM;IAItB;;OAEG;IACH,KAAK,IAAI,IAAI;IAMb;;OAEG;IACH,OAAO,CAAC,4BAA4B;IA0DpC;;OAEG;IACH,gBAAgB,CAAC,OAAO,GAAE;QACxB,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,GAAG,CAAC,EAAE,MAAM,CAAC;QACb,MAAM,CAAC,EAAE,MAAM,CAAC;KACZ,GAAG,QAAQ,EAAE;IAsBnB;;OAEG;IACH,aAAa,IAAI,MAAM,EAAE;IAUzB;;OAEG;IACH,OAAO,IAAI,MAAM,EAAE;IAUnB;;OAEG;IACH,QAAQ,IAAI;QACV,UAAU,EAAE,MAAM,CAAC;QACnB,UAAU,EAAE,MAAM,EAAE,CAAC;QACrB,IAAI,EAAE,MAAM,EAAE,CAAC;QACf,SAAS,EAAE,MAAM,CAAC;KACnB;CAQF"}

package/dist/interfaces/rest-registry.js

@@ -92,20 +92,21 @@ class RestToolRegistry {
             // Create a Zod object schema from the individual field schemas
             const zodObjectSchema = zod_1.z.object(zodSchemas);
             // Convert to JSON Schema using OpenAPI3 conventions, inlining all subschemas
-            // Type cast needed for Zod v4 compatibility with zod-to-json-schema
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any -- Zod type compatibility workaround
             const jsonSchema = (0, zod_to_json_schema_1.zodToJsonSchema)(zodObjectSchema, {
                 name: `${toolName}Request`,
                 target: 'openApi3',
-                // Place definitions where OpenAPI expects them  
+                // Place definitions where OpenAPI expects them
                 definitionPath: 'components.schemas',
                 $refStrategy: 'none' // inline sub-schemas to avoid unresolved refs
             });
             let result = jsonSchema;
             // Extract the actual schema from components.schemas if it's using $ref
-            if (result.$ref && result['components.schemas']) {
+            const jsonSchemaWithComponents = jsonSchema;
+            if (result.$ref && jsonSchemaWithComponents['components.schemas']) {
                 const refKey = result.$ref.replace('#/components.schemas/', '');
-                if (result['components.schemas'][refKey]) {
-                    result = result['components.schemas'][refKey];
+                if (jsonSchemaWithComponents['components.schemas'][refKey]) {
+                    result = jsonSchemaWithComponents['components.schemas'][refKey];
                 }
             }
             this.schemaCache.set(toolName, result);

package/dist/interfaces/rest-route-registry.d.ts

@@ -0,0 +1,165 @@
+/**
+ * REST API Route Registry
+ *
+ * Central registry for all REST API routes with their metadata and schemas.
+ * Provides single source of truth for routing, OpenAPI generation, and fixture validation.
+ *
+ * PRD #354: REST API Route Registry with Auto-Generated OpenAPI and Test Fixtures
+ */
+import { z } from 'zod';
+import { Logger } from '../core/error-handling';
+/**
+ * HTTP methods supported by the REST API
+ */
+export type HttpMethod = 'GET' | 'POST' | 'PUT' | 'DELETE';
+/**
+ * Route handler function type
+ */
+export type RouteHandler<TParams, TQuery, TBody, TResponse> = (context: {
+    params: TParams;
+    query: TQuery;
+    body: TBody;
+    requestId: string;
+}) => Promise<TResponse>;
+/**
+ * Route definition with full metadata for routing, documentation, and validation
+ */
+export interface RouteDefinition<TParams = unknown, TQuery = unknown, TBody = unknown, TResponse = unknown> {
+    /** Route path with optional parameters (e.g., "/api/v1/visualize/:sessionId") */
+    path: string;
+    /** HTTP method */
+    method: HttpMethod;
+    /** Human-readable description for OpenAPI documentation */
+    description: string;
+    /** OpenAPI tags for grouping endpoints */
+    tags: string[];
+    /** Zod schema for path parameters */
+    params?: z.ZodSchema<TParams>;
+    /** Zod schema for query string parameters */
+    query?: z.ZodSchema<TQuery>;
+    /** Zod schema for request body */
+    body?: z.ZodSchema<TBody>;
+    /** Zod schema for successful response */
+    response: z.ZodSchema<TResponse>;
+    /** Zod schemas for error responses by HTTP status code */
+    errorResponses?: Record<number, z.ZodSchema<unknown>>;
+    /** Route handler function (optional - can be set during migration) */
+    handler?: RouteHandler<TParams, TQuery, TBody, TResponse>;
+}
+/**
+ * Result of matching a request path against registered routes
+ */
+export interface RouteMatch {
+    /** The matched route definition */
+    route: RouteDefinition<unknown, unknown, unknown, unknown>;
+    /** Extracted path parameters */
+    params: Record<string, string>;
+}
+/**
+ * Registry for managing REST API routes
+ *
+ * Provides:
+ * - Route registration with Zod schemas
+ * - Path matching with parameter extraction
+ * - Route discovery for OpenAPI generation
+ * - Schema access for fixture validation
+ */
+export declare class RestRouteRegistry {
+    private routes;
+    private logger;
+    constructor(logger: Logger);
+    /**
+     * Generate a unique key for a route based on method and path pattern
+     */
+    private getRouteKey;
+    /**
+     * Compile a path pattern into a regex for matching
+     *
+     * Converts path parameters like :sessionId into capture groups
+     * Example: "/api/v1/visualize/:sessionId" -> /^\/api\/v1\/visualize\/([^/]+)$/
+     */
+    private compilePath;
+    /**
+     * Register a route in the registry
+     *
+     * @param route - Route definition with path, method, schemas, and metadata
+     * @throws Error if route with same method and path is already registered
+     */
+    register<TParams, TQuery, TBody, TResponse>(route: RouteDefinition<TParams, TQuery, TBody, TResponse>): void;
+    /**
+     * Find a matching route for the given method and path
+     *
+     * Checks routes in order:
+     * 1. Exact matches (no parameters)
+     * 2. Parameterized routes (extracts parameter values)
+     *
+     * @param method - HTTP method
+     * @param path - Request path to match
+     * @returns RouteMatch with route and extracted params, or null if no match
+     */
+    findRoute(method: string, path: string): RouteMatch | null;
+    /**
+     * Find allowed methods for a path (ignoring method)
+     *
+     * Used to return METHOD_NOT_ALLOWED with proper Allow header
+     * when a path matches but method doesn't.
+     *
+     * @param path - Request path to match
+     * @returns Array of allowed methods, or empty array if path doesn't match any route
+     */
+    findAllowedMethods(path: string): HttpMethod[];
+    /**
+     * Get all registered route definitions
+     *
+     * Used by OpenAPI generator to document all endpoints
+     */
+    getAllRoutes(): RouteDefinition<unknown, unknown, unknown, unknown>[];
+    /**
+     * Get the response schema for a specific route
+     *
+     * Used by fixture validator to validate fixture data
+     *
+     * @param method - HTTP method
+     * @param pathPattern - Route path pattern (e.g., "/api/v1/visualize/:sessionId")
+     * @returns Zod schema for the response, or null if route not found
+     */
+    getResponseSchema(method: string, pathPattern: string): z.ZodSchema<unknown> | null;
+    /**
+     * Get the error response schema for a specific route and status code
+     *
+     * @param method - HTTP method
+     * @param pathPattern - Route path pattern
+     * @param statusCode - HTTP status code
+     * @returns Zod schema for the error response, or null if not defined
+     */
+    getErrorResponseSchema(method: string, pathPattern: string, statusCode: number): z.ZodSchema<unknown> | null;
+    /**
+     * Check if a route is registered
+     */
+    hasRoute(method: string, pathPattern: string): boolean;
+    /**
+     * Get the number of registered routes
+     */
+    getRouteCount(): number;
+    /**
+     * Get all unique tags from registered routes
+     */
+    getTags(): string[];
+    /**
+     * Get routes filtered by tag
+     */
+    getRoutesByTag(tag: string): RouteDefinition<unknown, unknown, unknown, unknown>[];
+    /**
+     * Clear all registered routes
+     */
+    clear(): void;
+    /**
+     * Get registry statistics
+     */
+    getStats(): {
+        totalRoutes: number;
+        tags: string[];
+        routesByMethod: Record<HttpMethod, number>;
+    };
+}
+//# sourceMappingURL=rest-route-registry.d.ts.map

package/dist/interfaces/rest-route-registry.d.ts.map

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

package/dist/interfaces/rest-route-registry.js

@@ -0,0 +1,230 @@
+"use strict";
+/**
+ * REST API Route Registry
+ *
+ * Central registry for all REST API routes with their metadata and schemas.
+ * Provides single source of truth for routing, OpenAPI generation, and fixture validation.
+ *
+ * PRD #354: REST API Route Registry with Auto-Generated OpenAPI and Test Fixtures
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RestRouteRegistry = void 0;
+/**
+ * Registry for managing REST API routes
+ *
+ * Provides:
+ * - Route registration with Zod schemas
+ * - Path matching with parameter extraction
+ * - Route discovery for OpenAPI generation
+ * - Schema access for fixture validation
+ */
+class RestRouteRegistry {
+    routes = new Map();
+    logger;
+    constructor(logger) {
+        this.logger = logger;
+    }
+    /**
+     * Generate a unique key for a route based on method and path pattern
+     */
+    getRouteKey(method, path) {
+        return `${method}:${path}`;
+    }
+    /**
+     * Compile a path pattern into a regex for matching
+     *
+     * Converts path parameters like :sessionId into capture groups
+     * Example: "/api/v1/visualize/:sessionId" -> /^\/api\/v1\/visualize\/([^/]+)$/
+     */
+    compilePath(path) {
+        const paramNames = [];
+        // Escape special regex characters except for parameter placeholders
+        const regexPattern = path
+            .replace(/[.*+?^${}()|[\]\\]/g, '\\$&') // Escape special chars
+            .replace(/:([a-zA-Z_][a-zA-Z0-9_]*)/g, (_match, paramName) => {
+            paramNames.push(paramName);
+            return '([^/]+)'; // Capture group for parameter value
+        });
+        const regex = new RegExp(`^${regexPattern}$`);
+        return { regex, paramNames };
+    }
+    /**
+     * Register a route in the registry
+     *
+     * @param route - Route definition with path, method, schemas, and metadata
+     * @throws Error if route with same method and path is already registered
+     */
+    register(route) {
+        const key = this.getRouteKey(route.method, route.path);
+        if (this.routes.has(key)) {
+            throw new Error(`Route already registered: ${route.method} ${route.path}`);
+        }
+        const { regex, paramNames } = this.compilePath(route.path);
+        this.routes.set(key, {
+            definition: route,
+            regex,
+            paramNames,
+        });
+        this.logger.debug('Route registered in REST route registry', {
+            method: route.method,
+            path: route.path,
+            tags: route.tags,
+            paramNames,
+        });
+    }
+    /**
+     * Find a matching route for the given method and path
+     *
+     * Checks routes in order:
+     * 1. Exact matches (no parameters)
+     * 2. Parameterized routes (extracts parameter values)
+     *
+     * @param method - HTTP method
+     * @param path - Request path to match
+     * @returns RouteMatch with route and extracted params, or null if no match
+     */
+    findRoute(method, path) {
+        const upperMethod = method.toUpperCase();
+        // First pass: try exact match (more efficient for non-parameterized routes)
+        const exactKey = this.getRouteKey(upperMethod, path);
+        const exactMatch = this.routes.get(exactKey);
+        if (exactMatch) {
+            return {
+                route: exactMatch.definition,
+                params: {},
+            };
+        }
+        // Second pass: try parameterized routes
+        for (const [key, compiled] of this.routes) {
+            // Skip if method doesn't match
+            if (!key.startsWith(`${upperMethod}:`)) {
+                continue;
+            }
+            const match = compiled.regex.exec(path);
+            if (match) {
+                // Extract parameter values from capture groups
+                const params = {};
+                compiled.paramNames.forEach((name, index) => {
+                    params[name] = match[index + 1]; // +1 because match[0] is full match
+                });
+                return {
+                    route: compiled.definition,
+                    params,
+                };
+            }
+        }
+        return null;
+    }
+    /**
+     * Find allowed methods for a path (ignoring method)
+     *
+     * Used to return METHOD_NOT_ALLOWED with proper Allow header
+     * when a path matches but method doesn't.
+     *
+     * @param path - Request path to match
+     * @returns Array of allowed methods, or empty array if path doesn't match any route
+     */
+    findAllowedMethods(path) {
+        const methods = [];
+        for (const compiled of this.routes.values()) {
+            const match = compiled.regex.exec(path);
+            if (match) {
+                methods.push(compiled.definition.method);
+            }
+        }
+        return methods;
+    }
+    /**
+     * Get all registered route definitions
+     *
+     * Used by OpenAPI generator to document all endpoints
+     */
+    getAllRoutes() {
+        return Array.from(this.routes.values()).map((r) => r.definition);
+    }
+    /**
+     * Get the response schema for a specific route
+     *
+     * Used by fixture validator to validate fixture data
+     *
+     * @param method - HTTP method
+     * @param pathPattern - Route path pattern (e.g., "/api/v1/visualize/:sessionId")
+     * @returns Zod schema for the response, or null if route not found
+     */
+    getResponseSchema(method, pathPattern) {
+        const key = this.getRouteKey(method.toUpperCase(), pathPattern);
+        const route = this.routes.get(key);
+        return route?.definition.response ?? null;
+    }
+    /**
+     * Get the error response schema for a specific route and status code
+     *
+     * @param method - HTTP method
+     * @param pathPattern - Route path pattern
+     * @param statusCode - HTTP status code
+     * @returns Zod schema for the error response, or null if not defined
+     */
+    getErrorResponseSchema(method, pathPattern, statusCode) {
+        const key = this.getRouteKey(method.toUpperCase(), pathPattern);
+        const route = this.routes.get(key);
+        return route?.definition.errorResponses?.[statusCode] ?? null;
+    }
+    /**
+     * Check if a route is registered
+     */
+    hasRoute(method, pathPattern) {
+        const key = this.getRouteKey(method.toUpperCase(), pathPattern);
+        return this.routes.has(key);
+    }
+    /**
+     * Get the number of registered routes
+     */
+    getRouteCount() {
+        return this.routes.size;
+    }
+    /**
+     * Get all unique tags from registered routes
+     */
+    getTags() {
+        const tags = new Set();
+        for (const compiled of this.routes.values()) {
+            for (const tag of compiled.definition.tags) {
+                tags.add(tag);
+            }
+        }
+        return Array.from(tags).sort();
+    }
+    /**
+     * Get routes filtered by tag
+     */
+    getRoutesByTag(tag) {
+        return this.getAllRoutes().filter((route) => route.tags.includes(tag));
+    }
+    /**
+     * Clear all registered routes
+     */
+    clear() {
+        this.routes.clear();
+        this.logger.debug('REST route registry cleared');
+    }
+    /**
+     * Get registry statistics
+     */
+    getStats() {
+        const routesByMethod = {
+            GET: 0,
+            POST: 0,
+            PUT: 0,
+            DELETE: 0,
+        };
+        for (const compiled of this.routes.values()) {
+            routesByMethod[compiled.definition.method]++;
+        }
+        return {
+            totalRoutes: this.routes.size,
+            tags: this.getTags(),
+            routesByMethod,
+        };
+    }
+}
+exports.RestRouteRegistry = RestRouteRegistry;

package/dist/interfaces/routes/index.d.ts

@@ -0,0 +1,22 @@
+/**
+ * REST API Route Definitions
+ *
+ * Central registration of all REST API routes with their Zod schemas.
+ * This is the single source of truth for routing, OpenAPI generation, and fixture validation.
+ *
+ * PRD #354: REST API Route Registry with Auto-Generated OpenAPI and Test Fixtures
+ */
+import { RestRouteRegistry, RouteDefinition } from '../rest-route-registry';
+/**
+ * All route definitions for the REST API
+ */
+export declare const routeDefinitions: RouteDefinition<unknown, unknown, unknown, unknown>[];
+/**
+ * Register all routes with the provided registry
+ */
+export declare function registerAllRoutes(registry: RestRouteRegistry): void;
+/**
+ * Get route count - useful for validation
+ */
+export declare function getRouteCount(): number;
+//# sourceMappingURL=index.d.ts.map

package/dist/interfaces/routes/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/interfaces/routes/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,EAAE,iBAAiB,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AA6I5E;;GAEG;AACH,eAAO,MAAM,gBAAgB,EAAE,eAAe,CAAC,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,CAAC,EAsPjF,CAAC;AAEF;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,iBAAiB,GAAG,IAAI,CAInE;AAED;;GAEG;AACH,wBAAgB,aAAa,IAAI,MAAM,CAEtC"}