/**
 * @fileoverview CON-04 Developer SDK - Validation Utilities
 * @description Public API for runtime validation and type guards
 * @version 0.18.5-alpha
 */

// Core validation functions
export {
  validatePayload,
  safeValidatePayload
} from '../validators/validatePayload';

export {
  validateStandardEnvelope,
  validateEnhancedEnvelope,
  validateEnvelope,
  validateEnhancedEnvelope as validateEnvelopeEnhanced,
  validateErrorEnvelope,
  safeValidateEnvelope
} from '../validators/validateEnvelope';

// Type guard factory functions
export {
  createTypeGuard,
  createStrictTypeGuard,
  createSafeTypeGuard,
  combineGuards,
  combineGuardsOr,
  createArrayGuard,
  createOptionalGuard
} from '../validators/guardFactory';

// Route registry validation (from CON-03)
export {
  assertValidResponse,
  assertValidRequest,
  assertValidResponseData,
  validateRouteResponse,
  validateRouteRequest,
  getRouteInfo,
  getRoutesByMethod,
  getActiveRoutes,
  getDeprecatedRoutes
} from '../registry/RouteRegistry';

// Error classes
export {
  ValidationError,
  PayloadValidationError,
  EnvelopeValidationError,
  TypeGuardError,
  RouteValidationError
} from '../utils/errors';

// Re-export generated guards when available
// TODO: Import from '../validators/generated/guards' after generation

/**
 * @fileoverview CON-04 SDK Usage Examples
 * @description Common usage patterns for the validation SDK
 * @version 0.18.5-alpha
 */

/**
 * Example: Basic payload validation
 *
 * ```typescript
 * import { validatePayload } from '@neuronetiq/contracts/sdk/validation';
 * import { z } from 'zod';
 *
 * const userSchema = z.object({
 *   id: z.string(),
 *   email: z.string().email(),
 *   name: z.string()
 * });
 *
 * function createUser(data: unknown) {
 *   const validUser = validatePayload(userSchema, data);
 *   // validUser is now typed as { id: string, email: string, name: string }
 *   return validUser;
 * }
 * ```
 */

/**
 * Example: Envelope validation for API responses
 *
 * ```typescript
 * import { validateEnvelope } from '@neuronetiq/contracts/sdk/validation';
 * import { z } from 'zod';
 *
 * const portfolioSchema = z.object({
 *   total_value: z.number(),
 *   total_cost: z.number(),
 *   total_pl: z.number()
 * });
 *
 * async function fetchPortfolio() {
 *   const response = await fetch('/api/portfolio/summary');
 *   const data = await response.json();
 *
 *   const envelopeWithPortfolio = validateEnvelope(portfolioSchema);
 *   const result = envelopeWithPortfolio.parse(data);
 *
 *   // result.data is now typed as portfolio data
 *   return result.data;
 * }
 * ```
 */

/**
 * Example: Type guards for runtime type checking
 *
 * ```typescript
 * import { createTypeGuard } from '@neuronetiq/contracts/sdk/validation';
 * import { z } from 'zod';
 *
 * const tradeSchema = z.object({
 *   id: z.string(),
 *   symbol: z.string(),
 *   action: z.enum(['BUY', 'SELL']),
 *   size: z.number(),
 *   price: z.number()
 * });
 *
 * const isTrade = createTypeGuard(tradeSchema);
 *
 * function processTrades(data: unknown) {
 *   if (isTrade(data)) {
 *     // TypeScript knows data is Trade type
 *     console.log(`Trade: ${data.symbol} ${data.action} ${data.size} @ ${data.price}`);
 *   } else {
 *     console.log('Invalid trade data');
 *   }
 * }
 * ```
 */

/**
 * Example: Route-specific validation
 *
 * ```typescript
 * import { validateRouteResponse } from '@neuronetiq/contracts/sdk/validation';
 * import { ROUTES } from '@neuronetiq/contracts';
 *
 * async function fetchPortfolioSummary() {
 *   const response = await fetch(ROUTES.INFRA.PORTFOLIO.SUMMARY);
 *   const data = await response.json();
 *
 *   // Validates both envelope format and data structure
 *   validateRouteResponse(ROUTES.INFRA.PORTFOLIO.SUMMARY, data);
 *
 *   // TypeScript now knows data matches the route's expected response
 *   return data.data;
 * }
 * ```
 */

/**
 * Example: Error handling with validation errors
 *
 * ```typescript
 * import { ValidationError } from '@neuronetiq/contracts/sdk/validation';
 *
 * try {
 *   const result = validatePayload(userSchema, invalidData);
 * } catch (error) {
 *   if (error instanceof ValidationError) {
 *     // Handle validation error specifically
 *     console.error('Validation failed:', error.message);
 *     console.error('Details:', error.details);
 *
 *     // Log to monitoring service
 *     monitoring.logValidationError(error);
 *   } else {
 *     // Handle other errors
 *     console.error('Unexpected error:', error);
 *   }
 * }
 * ```
 */