/**
 * @fileoverview @neuronetiq/contracts SDK - Canonical Public API Surface
 * @description Unified exports for Frontend, Infra, and ML teams
 * @version 0.18.4
 */

// Runtime validation (CON-04) - Main feature of this sprint
export * from "./validation";

// Re-export core contracts functionality without conflicts
export {
  RouteRegistry,
  RoutePaths,
  RouteDefinition,
  ROUTE_REGISTRY_METADATA,
  CONTRACTS_VERSION,
  CONTRACTS_FINGERPRINT,
  ROUTES,
  AUTH_ROUTES,
  USER_ROUTES,
  ADMIN_ROUTES,
  INFRA_ROUTES,
  LEGACY_ROUTES,
  SessionEnvelope,
  UserEnvelope,
  AuthResponse,
  SupabaseAuthResponse,
  UserAuthResponse
} from "../index";

// Standard envelope and utilities - re-exported from main index to avoid duplication
export {
  ApiEnvelope,
  STANDARD_HEADERS,
  successEnvelope,
  errorEnvelope,
  generateRequestId,
  emitContractHeaders
} from "../index";

// Export metadata constants
export { SCHEMA_VERSION, RELEASE_DATE, INFRASTRUCTURE_ALIGNMENT } from '../schemas/index.js';

// Canonical SDK version constant
export const CONTRACTS_SDK_VERSION = "0.18.4";

/**
 * @fileoverview SDK Usage Examples
 * @description Common usage patterns for the contracts SDK
 * @version 0.18.4
 */

/**
 * Example: Basic payload validation
 *
 * ```typescript
 * import { validatePayload } from '@neuronetiq/contracts/sdk';
 * 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';
 * 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';
 * 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';
 * 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';
 *
 * 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);
 *   }
 * }
 * ```
 */