/**
 * @fileoverview Standard API Envelope Schemas
 * @description Standardized response envelope schemas for all API endpoints
 * @version 0.18.4
 */

import { z } from 'zod';

/**
 * Error response schema for consistent error handling
 */
export const ErrorEnvelopeSchema = z.object({
  code: z.string().min(1),
  message: z.string().min(1),
  details: z.record(z.any()).optional(),
  timestamp: z.string().datetime()
}).strict().describe('Standard error response format');

/**
 * Standard API response envelope schema
 * Used by all endpoints to provide consistent response format
 */
export const ApiEnvelopeSchema = z.object({
  success: z.boolean(),
  data: z.any().optional(),
  error: ErrorEnvelopeSchema.optional(),
  meta: z.record(z.any()).optional()
}).strict().describe('Standard API response envelope');

/**
 * Enhanced API response envelope with additional metadata
 */
export const EnhancedApiEnvelopeSchema = z.object({
  success: z.boolean(),
  data: z.any().optional(),
  error: ErrorEnvelopeSchema.optional(),

  // Standard metadata
  requestId: z.string(),
  timestamp: z.string().datetime(),

  // Enhanced metadata (Management improvement #5)
  meta: z.object({
    contractsVersion: z.string(),
    traceId: z.string().optional(),          // Distributed tracing
    latencyMs: z.number().int().nonnegative().optional(),
    source: z.string().optional(),           // 'infra-api', 'cache', etc.
  }).strict().optional()
}).strict().describe('Enhanced API response envelope with metadata');

// Type exports
export type ErrorEnvelope = z.infer<typeof ErrorEnvelopeSchema>;
export type ApiEnvelope<T = any> = z.infer<typeof ApiEnvelopeSchema> & { data?: T };
export type EnhancedApiEnvelope<T = any> = z.infer<typeof EnhancedApiEnvelopeSchema> & { data?: T };