API Documentation

// ===== API Response Types =====

/** Main check response wrapper */
interface VehicleCheckResponse {
  success: boolean;
  report_id: string;
  registration: string;
  check_type: 'maxi' | 'maxi-plus';
  data: VehicleData;
  balance: BalanceInfo;
}

/** Balance information returned with each check */
interface BalanceInfo {
  before: number;
  after: number;
  currency: 'GBP';
  low_balance_warning: boolean;
}

/** Complete vehicle data structure */
interface VehicleData {
  // Identity
  make: string;
  model: string;
  year: number;
  colour: string;
  vin?: string; // Partial VIN for Maxi, full for Maxi-Plus
  
  // Registration & Tax
  registrationDate: string; // ISO date
  taxStatus: 'Taxed' | 'SORN' | 'Untaxed';
  taxDueDate?: string;
  motExpiryDate?: string;
  
  // Technical
  fuelType: string;
  engineSize?: number; // cc
  transmission?: string;
  bodyType?: string;
  doors?: number;
  co2Emissions?: number;
  euroStatus?: string;
  
  // Valuations (9-band)
  valuation?: ValuationData;
  
  // MOT History
  motHistory?: MOTRecord[];
  
  // EV Data (if applicable)
  evData?: EVData;
  
  // Maxi-Plus Only Fields
  stolenCheck?: StolenCheckResult;
  financeRecords?: FinanceRecord[];
  writeOffRecords?: WriteOffRecord[];
  keeperHistory?: KeeperRecord[];
  plateChanges?: PlateChange[];
  ncapRating?: NCAPRating;
  performanceData?: PerformanceData;
  dimensions?: DimensionsData;
}

/** 9-band valuation data */
interface ValuationData {
  dealerForecourt: number;
  tradeRetail: number;
  tradeAverage: number;
  privateClean: number;
  privateAverage: number;
  auction: number;
  partExchange: number;
  futureValue3Months?: number;
  futureValue6Months?: number;
  futureValue12Months?: number;
  valuationDate: string;
}

/** Individual MOT test record */
interface MOTRecord {
  testDate: string;
  expiryDate?: string;
  result: 'PASS' | 'FAIL';
  odometerValue: number;
  odometerUnit: 'mi' | 'km';
  testNumber: string;
  defects?: MOTDefect[];
  advisories?: MOTDefect[];
}

interface MOTDefect {
  text: string;
  type: 'DANGEROUS' | 'MAJOR' | 'MINOR' | 'ADVISORY';
  dangerous?: boolean;
}

/** EV-specific data */
interface EVData {
  batteryCapacity?: number; // kWh
  wltpRange?: number; // miles
  realWorldRange?: number; // miles
  chargingSpeedAC?: number; // kW
  chargingSpeedDC?: number; // kW
  connectorTypes?: string[];
  chargeTime0to100AC?: number; // hours
  chargeTime10to80DC?: number; // minutes
}

/** Stolen vehicle check result (Maxi-Plus) */
interface StolenCheckResult {
  isStolen: boolean;
  stolenDate?: string;
  policeReference?: string;
  policeForce?: string;
}

/** Outstanding finance record (Maxi-Plus) */
interface FinanceRecord {
  agreementType: 'HP' | 'PCP' | 'Lease' | 'Other';
  agreementId: string;
  financerName: string;
  financerContact?: string;
  startDate?: string;
  endDate?: string;
}

/** Insurance write-off record (Maxi-Plus) */
interface WriteOffRecord {
  category: 'A' | 'B' | 'S' | 'N';
  recordedDate: string;
  insurer?: string;
  lossType?: string;
}

/** Keeper/owner history (Maxi-Plus) */
interface KeeperRecord {
  dateFrom: string;
  dateTo?: string;
  keeperNumber: number;
  isCurrentKeeper: boolean;
}

/** Registration plate change (Maxi-Plus) */
interface PlateChange {
  previousPlate: string;
  newPlate: string;
  changeDate: string;
}

/** NCAP safety rating (Maxi-Plus) */
interface NCAPRating {
  overallRating: number; // 0-5 stars
  adultOccupant: number; // percentage
  childOccupant: number;
  pedestrian: number;
  safetyAssist: number;
  testYear?: number;
}

/** Performance specifications (Maxi-Plus) */
interface PerformanceData {
  powerBHP?: number;
  torqueNm?: number;
  torqueLbFt?: number;
  acceleration0to60?: number; // seconds
  topSpeed?: number; // mph
  fuelConsumptionCombined?: number; // mpg
}

/** Vehicle dimensions (Maxi-Plus) */
interface DimensionsData {
  lengthMm?: number;
  widthMm?: number;
  heightMm?: number;
  wheelbaseMm?: number;
  bootCapacityLitres?: number;
  fuelTankLitres?: number;
  kerbWeightKg?: number;
  grossWeightKg?: number;
  towingCapacityBrakedKg?: number;
  towingCapacityUnbrakedKg?: number;
}

// ===== Error Response =====
interface APIErrorResponse {
  success: false;
  error: string;
  code: ErrorCode;
  details?: Record<string, unknown>;
}

type ErrorCode = 
  | 'MISSING_API_KEY'
  | 'INVALID_API_KEY'
  | 'KEY_REVOKED'
  | 'API_ACCESS_DISABLED'
  | 'INSUFFICIENT_BALANCE'
  | 'RATE_LIMITED'
  | 'VEHICLE_NOT_FOUND'
  | 'INVALID_REGISTRATION'
  | 'INTERNAL_ERROR';