/**
 * @ai-summary Type definitions for NHTSA vPIC API
 * @ai-context Defines request/response types for VIN decoding
 */

/**
 * Individual result from NHTSA DecodeVin API
 */
export interface NHTSAResult {
  Value: string | null;
  ValueId: string | null;
  Variable: string;
  VariableId: number;
}

/**
 * Raw response from NHTSA DecodeVin API
 * GET https://vpic.nhtsa.dot.gov/api/vehicles/decodevin/{VIN}?format=json
 */
export interface NHTSADecodeResponse {
  Count: number;
  Message: string;
  SearchCriteria: string;
  Results: NHTSAResult[];
}

/**
 * Confidence level for matched dropdown values
 */
export type MatchConfidence = 'high' | 'medium' | 'none';

/**
 * Matched field with confidence indicator
 */
export interface MatchedField<T> {
  value: T | null;
  nhtsaValue: string | null;
  confidence: MatchConfidence;
}

/**
 * Decoded vehicle data with match confidence per field
 * Maps NHTSA response fields to internal field names (camelCase)
 *
 * NHTSA Field Mappings:
 * - ModelYear -> year
 * - Make -> make
 * - Model -> model
 * - Trim -> trimLevel
 * - BodyClass -> bodyType
 * - DriveType -> driveType
 * - FuelTypePrimary -> fuelType
 * - EngineModel / EngineCylinders + EngineDisplacementL -> engine
 * - TransmissionStyle -> transmission
 */
export interface DecodedVehicleData {
  year: MatchedField<number>;
  make: MatchedField<string>;
  model: MatchedField<string>;
  trimLevel: MatchedField<string>;
  bodyType: MatchedField<string>;
  driveType: MatchedField<string>;
  fuelType: MatchedField<string>;
  engine: MatchedField<string>;
  transmission: MatchedField<string>;
}

/**
 * Cached VIN data from vin_cache table
 */
export interface VinCacheEntry {
  vin: string;
  make: string | null;
  model: string | null;
  year: number | null;
  engineType: string | null;
  bodyType: string | null;
  rawData: NHTSADecodeResponse;
  cachedAt: Date;
}

/**
 * VIN decode request body
 */
export interface DecodeVinRequest {
  vin: string;
}

/**
 * VIN decode error response
 */
export interface VinDecodeError {
  error: 'INVALID_VIN' | 'VIN_DECODE_FAILED' | 'TIER_REQUIRED';
  message: string;
  details?: string;
}
