/**
 * @fileoverview CON-03 Envelope Automation - Request Validation
 * @description Runtime validation for API requests with type safety
 * @version 0.18.4-alpha
 */

import { z } from 'zod';

/**
 * Validates that a request payload conforms to the expected schema
 * Provides type-safe request validation for API endpoints
 *
 * @param schema - Zod schema for the expected request structure
 * @param payload - Unknown payload to validate
 * @throws {ZodError} if payload doesn't match the expected request schema
 *
 * @example
 * ```typescript
 * // Validate a login request
 * const request = { email: "user@example.com", password: "secret123" };
 * validateRequest(LoginRequestSchema, request);
 * // Throws if request doesn't match expected structure
 * ```
 */
export function validateRequest<T>(
  schema: z.ZodSchema<T>,
  payload: unknown
): asserts payload is T {
  schema.parse(payload);
}

/**
 * Validates request data for specific routes
 * Provides compile-time route path validation
 *
 * @param routePath - Route path from RouteRegistry
 * @param payload - Request payload to validate
 * @throws {ZodError} if payload doesn't match route's expected request schema
 */
export function validateRouteRequest<K extends string>(
  routePath: K,
  payload: unknown
): asserts payload is any {
  // This will be enhanced in Phase 3 with actual route registry integration
  // For now, it provides the interface for type-safe validation
  // Route-specific schemas will be injected by the auto-generation script
  z.any().parse(payload);
}

/**
 * Validates query parameters for GET requests
 *
 * @param schema - Zod schema for query parameters
 * @param query - Query parameter object
 * @throws {ZodError} if query doesn't match schema
 */
export function validateQueryParams<T>(
  schema: z.ZodSchema<T>,
  query: unknown
): asserts query is T {
  schema.parse(query);
}

/**
 * Validates path parameters for dynamic routes
 *
 * @param schema - Zod schema for path parameters
 * @param params - Path parameter object
 * @throws {ZodError} if params don't match schema
 */
export function validatePathParams<T>(
  schema: z.ZodSchema<T>,
  params: unknown
): asserts params is T {
  schema.parse(params);
}

/**
 * Validates request body for POST/PUT requests
 *
 * @param schema - Zod schema for request body
 * @param body - Request body object
 * @throws {ZodError} if body doesn't match schema
 */
export function validateRequestBody<T>(
  schema: z.ZodSchema<T>,
  body: unknown
): asserts body is T {
  schema.parse(body);
}

/**
 * Validates complete request (query + body + params)
 * Useful for complex requests with multiple parts
 *
 * @param requestSchema - Combined schema for all request parts
 * @param request - Complete request object
 * @throws {ZodError} if request doesn't match schema
 */
export function validateCompleteRequest<T>(
  requestSchema: z.ZodSchema<T>,
  request: unknown
): asserts request is T {
  requestSchema.parse(request);
}