import { ContentType, HttpMethod } from '../types';
import { ApiFileType, ScannedApiRoute } from './route-scanner';
/**
 * Generated endpoint with full configuration
 */
export interface GeneratedEndpoint {
    /** Unique endpoint identifier */
    readonly id: string;
    /** HTTP method */
    readonly method: HttpMethod;
    /** URL path pattern (with :params) */
    readonly path: string;
    /** Display name for documentation */
    readonly displayName: string;
    /** Endpoint description */
    readonly description: string;
    /** Source file path */
    readonly sourceFile: string;
    /** Handler configuration */
    readonly handler: EndpointHandler;
    /** Computed access control */
    readonly access: ComputedAccess;
    /** Request schema (if available) */
    readonly requestSchema?: EndpointSchema;
    /** Response schema (if available) */
    readonly responseSchema?: EndpointSchema;
    /** Path parameters */
    readonly pathParams: readonly PathParameter[];
    /** Query parameters (if defined) */
    readonly queryParams?: readonly QueryParameter[];
    /** Middleware chain */
    readonly middleware: readonly MiddlewareConfig[];
    /** Rate limiting configuration */
    readonly rateLimit?: RateLimitConfig;
    /** Caching configuration */
    readonly cache?: EndpointCacheConfig;
    /** Tags for documentation grouping */
    readonly tags: readonly string[];
    /** Deprecation info */
    readonly deprecated?: DeprecationInfo;
    /** OpenAPI operation ID */
    readonly operationId: string;
}
/**
 * Endpoint handler configuration
 */
export interface EndpointHandler {
    /** Source file path */
    readonly file: string;
    /** Export name in the file */
    readonly exportName: string;
    /** Handler function (resolved) */
    readonly fn?: EndpointHandlerFn;
    /** Loader for lazy loading */
    readonly loader?: () => Promise<EndpointHandlerFn>;
    /** Whether handler is async */
    readonly isAsync: boolean;
}
/**
 * Endpoint handler function signature
 */
export type EndpointHandlerFn = (context: EndpointContext) => unknown | Promise<unknown>;
/**
 * Context passed to endpoint handlers
 */
export interface EndpointContext {
    /** HTTP request */
    readonly request: EndpointRequest;
    /** Path parameters */
    readonly params: Record<string, string>;
    /** Query parameters */
    readonly query: Record<string, string | string[]>;
    /** Request body */
    readonly body: unknown;
    /** Request headers */
    readonly headers: Record<string, string>;
    /** User context (from auth) */
    readonly user?: UserContext;
    /** Request metadata */
    readonly meta: RequestMetadata;
}
/**
 * Endpoint request abstraction
 */
export interface EndpointRequest {
    /** HTTP method */
    readonly method: HttpMethod;
    /** Request URL */
    readonly url: string;
    /** URL path */
    readonly path: string;
    /** Content type */
    readonly contentType?: ContentType;
    /** Accept header */
    readonly accept?: string;
}
/**
 * User context from authentication
 */
export interface UserContext {
    /** User ID */
    readonly id: string;
    /** Is authenticated */
    readonly isAuthenticated: boolean;
    /** User roles */
    readonly roles: readonly string[];
    /** User permissions */
    readonly permissions: readonly string[];
    /** Additional user attributes */
    readonly attributes?: Record<string, unknown>;
}
/**
 * Request metadata
 */
export interface RequestMetadata {
    /** Request ID */
    readonly requestId: string;
    /** Correlation ID */
    readonly correlationId?: string;
    /** Request timestamp */
    readonly timestamp: number;
    /** Client IP */
    readonly clientIp?: string;
    /** User agent */
    readonly userAgent?: string;
}
/**
 * Computed access control for endpoint
 */
export interface ComputedAccess {
    /** Is publicly accessible */
    readonly isPublic: boolean;
    /** Requires authentication */
    readonly requiresAuth: boolean;
    /** Required roles */
    readonly requiredRoles: readonly string[];
    /** Required permissions */
    readonly requiredPermissions: readonly string[];
    /** Permission match strategy */
    readonly permissionStrategy: 'any' | 'all';
    /** Role match strategy */
    readonly roleStrategy: 'any' | 'all';
    /** Permission scope */
    readonly scope?: PermissionScope;
    /** Resource ownership check */
    readonly ownershipCheck?: ResourceOwnershipCheck;
    /** Inherited access from parent groups */
    readonly inheritedFrom: readonly string[];
    /** Explicit overrides applied */
    readonly overrides: readonly AccessOverride[];
}
/**
 * Permission scope levels
 */
export type PermissionScope = 'own' | 'team' | 'org' | 'global';
/**
 * Resource ownership check configuration
 */
export interface ResourceOwnershipCheck {
    /** Resource type */
    readonly resourceType: string;
    /** Field containing owner ID */
    readonly ownerField: string;
    /** Path parameter for resource ID */
    readonly resourceIdParam: string;
    /** Field to compare against user ID */
    readonly userIdField?: string;
}
/**
 * Access control override
 */
export interface AccessOverride {
    /** Override source */
    readonly source: 'file' | 'directory' | 'config';
    /** Override path */
    readonly path: string;
    /** Overridden fields */
    readonly fields: Partial<Omit<ComputedAccess, 'inheritedFrom' | 'overrides'>>;
}
/**
 * Endpoint schema definition
 */
export interface EndpointSchema {
    /** JSON Schema */
    readonly schema: JSONSchemaLike;
    /** Content type */
    readonly contentType: ContentType;
    /** Example value */
    readonly example?: unknown;
    /** Multiple examples */
    readonly examples?: Record<string, unknown>;
}
/**
 * Simplified JSON Schema type
 */
export interface JSONSchemaLike {
    readonly type?: string;
    readonly properties?: Record<string, JSONSchemaLike>;
    readonly items?: JSONSchemaLike;
    readonly required?: readonly string[];
    readonly [key: string]: unknown;
}
/**
 * Path parameter definition
 */
export interface PathParameter {
    /** Parameter name */
    readonly name: string;
    /** Parameter description */
    readonly description?: string;
    /** Parameter schema */
    readonly schema: JSONSchemaLike;
    /** Is required */
    readonly required: boolean;
    /** Example value */
    readonly example?: string;
}
/**
 * Query parameter definition
 */
export interface QueryParameter {
    /** Parameter name */
    readonly name: string;
    /** Parameter description */
    readonly description?: string;
    /** Parameter schema */
    readonly schema: JSONSchemaLike;
    /** Is required */
    readonly required: boolean;
    /** Allow multiple values */
    readonly allowMultiple: boolean;
    /** Default value */
    readonly defaultValue?: unknown;
    /** Example value */
    readonly example?: unknown;
}
/**
 * Middleware configuration
 */
export interface MiddlewareConfig {
    /** Middleware name */
    readonly name: string;
    /** Middleware function */
    readonly fn?: MiddlewareFn;
    /** Middleware loader */
    readonly loader?: () => Promise<MiddlewareFn>;
    /** Priority (lower runs first) */
    readonly priority: number;
    /** Middleware options */
    readonly options?: Record<string, unknown>;
}
/**
 * Middleware function signature
 */
export type MiddlewareFn = (context: EndpointContext, next: () => Promise<unknown>) => unknown | Promise<unknown>;
/**
 * Rate limit configuration
 */
export interface RateLimitConfig {
    /** Max requests per window */
    readonly maxRequests: number;
    /** Time window in milliseconds */
    readonly windowMs: number;
    /** Key generator (default: IP-based) */
    readonly keyGenerator?: 'ip' | 'user' | 'custom';
    /** Custom key generator function */
    readonly customKeyGenerator?: (context: EndpointContext) => string;
    /** Skip rate limiting for certain conditions */
    readonly skip?: (context: EndpointContext) => boolean;
}
/**
 * Endpoint cache configuration
 */
export interface EndpointCacheConfig {
    /** Cache TTL in milliseconds */
    readonly ttl: number;
    /** Cache strategy */
    readonly strategy: 'cache-first' | 'network-first' | 'stale-while-revalidate';
    /** Vary by headers */
    readonly varyBy?: readonly string[];
    /** Invalidation tags */
    readonly tags?: readonly string[];
}
/**
 * Deprecation information
 */
export interface DeprecationInfo {
    /** Is deprecated */
    readonly deprecated: boolean;
    /** Deprecation reason */
    readonly reason?: string;
    /** Replacement endpoint */
    readonly replacement?: string;
    /** Sunset date */
    readonly sunsetDate?: string;
}
/**
 * Generator configuration
 */
export interface ApiGeneratorConfig {
    /** Base URL for all endpoints */
    readonly baseUrl: string;
    /** Handler resolver function */
    readonly handlerResolver?: (filePath: string, exportName: string) => Promise<EndpointHandlerFn | undefined>;
    /** Schema resolver function */
    readonly schemaResolver?: (filePath: string) => Promise<EndpointSchemaDefinition | undefined>;
    /** Middleware resolver function */
    readonly middlewareResolver?: (filePath: string) => Promise<MiddlewareFn[]>;
    /** Access resolver function (for _access.ts files) */
    readonly accessResolver?: (filePath: string) => Promise<Partial<ComputedAccess> | undefined>;
    /** Default rate limit configuration */
    readonly defaultRateLimit?: RateLimitConfig;
    /** Default cache configuration */
    readonly defaultCache?: EndpointCacheConfig;
    /** Generate operation IDs */
    readonly generateOperationIds: boolean;
    /** Enable lazy loading of handlers */
    readonly lazyLoadHandlers: boolean;
}
/**
 * Schema definition from _schema.ts files
 */
export interface EndpointSchemaDefinition {
    readonly [method: string]: {
        readonly request?: JSONSchemaLike;
        readonly response?: JSONSchemaLike;
        readonly pathParams?: Record<string, JSONSchemaLike>;
        readonly queryParams?: Record<string, JSONSchemaLike>;
    };
}
/**
 * Default generator configuration
 */
export declare const DEFAULT_GENERATOR_CONFIG: ApiGeneratorConfig;
/**
 * Generate endpoint ID from route and method
 */
export declare function generateEndpointId(route: ScannedApiRoute, method: HttpMethod): string;
/**
 * Generate operation ID for OpenAPI
 */
export declare function generateOperationId(route: ScannedApiRoute, method: HttpMethod): string;
/**
 * Generate display name for endpoint
 */
export declare function generateDisplayName(route: ScannedApiRoute, method: HttpMethod): string;
/**
 * Generate description for endpoint
 */
export declare function generateDescription(route: ScannedApiRoute, method: HttpMethod): string;
/**
 * Compute access control from route
 */
export declare function computeAccess(route: ScannedApiRoute, _method: HttpMethod, accessOverride?: Partial<ComputedAccess>): ComputedAccess;
/**
 * Generate path parameters from route
 */
export declare function generatePathParams(route: ScannedApiRoute): readonly PathParameter[];
/**
 * Generate tags from route
 */
export declare function generateTags(route: ScannedApiRoute): readonly string[];
/**
 * Create endpoint handler configuration
 */
export declare function createHandlerConfig(route: ScannedApiRoute, method: HttpMethod, config: ApiGeneratorConfig): EndpointHandler;
/**
 * Get export name for HTTP method
 */
export declare function getExportNameForMethod(_fileType: ApiFileType, method: HttpMethod): string;
/**
 * Generate a single endpoint from route and method
 */
export declare function generateEndpoint(route: ScannedApiRoute, method: HttpMethod, config: ApiGeneratorConfig): Promise<GeneratedEndpoint>;
/**
 * Generate all endpoints from scanned routes
 */
export declare function generateApiEndpoints(routes: ScannedApiRoute[], config?: Partial<ApiGeneratorConfig>): Promise<GeneratedEndpoint[]>;
/**
 * OpenAPI document structure (simplified)
 */
export interface OpenAPIDocument {
    readonly openapi: string;
    readonly info: OpenAPIInfo;
    readonly servers?: readonly OpenAPIServer[];
    readonly paths: Record<string, OpenAPIPathItem>;
    readonly components?: OpenAPIComponents;
    readonly tags?: readonly OpenAPITag[];
}
/**
 * OpenAPI info object
 */
export interface OpenAPIInfo {
    readonly title: string;
    readonly version: string;
    readonly description?: string;
}
/**
 * OpenAPI server object
 */
export interface OpenAPIServer {
    readonly url: string;
    readonly description?: string;
}
/**
 * OpenAPI path item
 */
export interface OpenAPIPathItem {
    readonly get?: OpenAPIOperation;
    readonly post?: OpenAPIOperation;
    readonly put?: OpenAPIOperation;
    readonly patch?: OpenAPIOperation;
    readonly delete?: OpenAPIOperation;
    readonly head?: OpenAPIOperation;
    readonly options?: OpenAPIOperation;
}
/**
 * OpenAPI operation object
 */
export interface OpenAPIOperation {
    readonly operationId: string;
    readonly summary: string;
    readonly description?: string;
    readonly tags?: readonly string[];
    readonly parameters?: readonly OpenAPIParameter[];
    readonly requestBody?: OpenAPIRequestBody;
    readonly responses: Record<string, OpenAPIResponse>;
    readonly security?: readonly Record<string, readonly string[]>[];
    readonly deprecated?: boolean;
}
/**
 * OpenAPI parameter
 */
export interface OpenAPIParameter {
    readonly name: string;
    readonly in: 'path' | 'query' | 'header' | 'cookie';
    readonly required?: boolean;
    readonly description?: string;
    readonly schema: JSONSchemaLike;
}
/**
 * OpenAPI request body
 */
export interface OpenAPIRequestBody {
    readonly required?: boolean;
    readonly content: Record<string, OpenAPIMediaType>;
}
/**
 * OpenAPI media type
 */
export interface OpenAPIMediaType {
    readonly schema: JSONSchemaLike;
    readonly example?: unknown;
}
/**
 * OpenAPI response
 */
export interface OpenAPIResponse {
    readonly description: string;
    readonly content?: Record<string, OpenAPIMediaType>;
}
/**
 * OpenAPI components
 */
export interface OpenAPIComponents {
    readonly schemas?: Record<string, JSONSchemaLike>;
    readonly securitySchemes?: Record<string, OpenAPISecurityScheme>;
}
/**
 * OpenAPI security scheme
 */
export interface OpenAPISecurityScheme {
    readonly type: string;
    readonly scheme?: string;
    readonly bearerFormat?: string;
    readonly name?: string;
    readonly in?: string;
}
/**
 * OpenAPI tag
 */
export interface OpenAPITag {
    readonly name: string;
    readonly description?: string;
}
/**
 * Generate OpenAPI document from endpoints
 */
export declare function generateOpenAPISpec(endpoints: GeneratedEndpoint[], info: OpenAPIInfo, servers?: readonly OpenAPIServer[]): OpenAPIDocument;
/**
 * Type guard for GeneratedEndpoint
 */
export declare function isGeneratedEndpoint(value: unknown): value is GeneratedEndpoint;
/**
 * Type guard for ComputedAccess
 */
export declare function isComputedAccess(value: unknown): value is ComputedAccess;
/**
 * Filter endpoints by access requirements
 */
export declare function filterEndpointsByAccess(endpoints: GeneratedEndpoint[], predicate: (access: ComputedAccess) => boolean): GeneratedEndpoint[];
/**
 * Get public endpoints
 */
export declare function getPublicEndpoints(endpoints: GeneratedEndpoint[]): GeneratedEndpoint[];
/**
 * Get endpoints requiring authentication
 */
export declare function getAuthenticatedEndpoints(endpoints: GeneratedEndpoint[]): GeneratedEndpoint[];
/**
 * Get endpoints requiring specific role
 */
export declare function getEndpointsByRole(endpoints: GeneratedEndpoint[], role: string): GeneratedEndpoint[];
/**
 * Group endpoints by resource
 */
export declare function groupEndpointsByResource(endpoints: GeneratedEndpoint[]): Record<string, GeneratedEndpoint[]>;