/**
 * @fileoverview CON-03 Envelope Automation - Response Validation
 * @description Runtime validation for API responses with envelope automation
 * @version 0.18.4-alpha
 */

import { z } from 'zod';
import { ApiEnvelopeSchema } from "../envelopes/standard";

/**
 * Validates that a payload conforms to the expected API envelope format
 * with the specified data schema, providing type-safe response validation
 *
 * @param schema - Zod schema for the expected response data structure
 * @param payload - Unknown payload to validate
 * @throws {ZodError} if payload doesn't match the envelope + data schema
 *
 * @example
 * ```typescript
 * // Validate a portfolio summary response
 * const response = { success: true, data: { total_value: 1000 } };
 * validateResponse(PortfolioSummarySchema, response);
 * // Throws if response doesn't match expected envelope + data structure
 * ```
 */
export function validateResponse<T>(
  schema: z.ZodSchema<T>,
  payload: unknown
): asserts payload is { success: boolean; data: T; meta?: Record<string, any>; error?: any } {
  // Create the combined envelope + data schema
  const envelopeWithDataSchema = ApiEnvelopeSchema.extend({
    data: schema
  });

  // Validate and throw on failure
  envelopeWithDataSchema.parse(payload);
}

/**
 * Validates response data without the envelope wrapper
 * Useful for internal processing where envelope is already stripped
 *
 * @param schema - Zod schema for the response data
 * @param data - Data payload to validate
 * @throws {ZodError} if data doesn't match schema
 */
export function validateResponseData<T>(
  schema: z.ZodSchema<T>,
  data: unknown
): asserts data is T {
  schema.parse(data);
}

/**
 * Type-safe response validator for specific routes
 * Provides compile-time route path validation
 *
 * @param routePath - Route path from RouteRegistry
 * @param payload - Response payload to validate
 * @throws {ZodError} if payload doesn't match route's expected response schema
 */
export function validateRouteResponse<K extends string>(
  routePath: K,
  payload: unknown
): asserts payload is { success: boolean; data: any; meta?: Record<string, any>; error?: any } {
  // This will be enhanced in Phase 3 with actual route registry integration
  // For now, it provides the interface for type-safe validation
  const envelopeSchema = ApiEnvelopeSchema.extend({
    data: z.any() // Will be replaced with actual route schema in auto-generated version
  });

  envelopeSchema.parse(payload);
}

/**
 * Validates error responses according to the standard error envelope format
 *
 * @param payload - Error payload to validate
 * @throws {ZodError} if error doesn't match expected format
 */
export function validateErrorResponse(
  payload: unknown
): asserts payload is { success: false; error: { code: string; message: string; details?: Record<string, any>; timestamp: string }; meta?: Record<string, any> } {
  const errorEnvelopeSchema = ApiEnvelopeSchema.extend({
    success: z.literal(false),
    error: z.object({
      code: z.string().min(1),
      message: z.string().min(1),
      details: z.record(z.any()).optional(),
      timestamp: z.string().datetime()
    }).strict(),
    data: z.undefined()
  });

  errorEnvelopeSchema.parse(payload);
}