/**
 * @ai-summary Type definitions for Gas Stations feature
 */

/**
 * Geographic location coordinates
 */
export interface Location {
  latitude: number;
  longitude: number;
}

/**
 * Gas station search request parameters
 */
export interface StationSearchRequest extends Location {
  /** Search radius in meters (default: 5000 = 5km) */
  radius?: number;
  /** Optional fuel type filter */
  fuelType?: string;
}

/**
 * Station search response metadata
 */
export interface SearchLocation {
  latitude: number;
  longitude: number;
}

export interface StationSavedMetadata {
  nickname?: string;
  notes?: string;
  isFavorite: boolean;
  has93Octane: boolean;
  has93OctaneEthanolFree: boolean;
}

/**
 * Single gas station from search results
 */
export interface Station {
  /** Google Places ID for the station */
  placeId: string;
  /** Station name (e.g. "Shell Downtown") */
  name: string;
  /** Full address of the station */
  address: string;
  /** Formatted address from Google Maps */
  formattedAddress?: string;
  /** Latitude coordinate */
  latitude: number;
  /** Longitude coordinate */
  longitude: number;
  /** Google rating (0-5 stars) */
  rating: number;
  /** Distance from search location in meters */
  distance?: number;
  /** Photo reference for station photo if available */
  photoReference?: string;
  /** Whether the station is saved for the user */
  isSaved?: boolean;
  /** Saved-station metadata if applicable */
  savedMetadata?: StationSavedMetadata;
}

/**
 * Saved/favorited station with user metadata
 */
export interface SavedStation extends Station {
  /** Database record ID */
  id: string;
  /** Optional saved-station identifier (alias for id when needed) */
  savedStationId?: string;
  /** User ID who saved the station */
  userId: string;
  /** Stored station id (Google place id) */
  stationId?: string;
  /** Custom nickname given by user */
  nickname?: string;
  /** User notes about the station */
  notes?: string;
  /** Whether station is marked as favorite */
  isFavorite: boolean;
  /** Whether the station is confirmed to have 93 octane */
  has93Octane: boolean;
  /** Whether the 93 octane is ethanol free */
  has93OctaneEthanolFree: boolean;
  /** Created timestamp */
  createdAt: Date;
  /** Last updated timestamp */
  updatedAt: Date;
  /** Raw station object returned by backend, if any */
  station?: Station | null;
}

/**
 * Station search response with metadata
 */
export interface StationSearchResponse {
  /** Array of stations found */
  stations: Station[];
  /** Location where search was performed */
  searchLocation: SearchLocation;
  /** Radius used for search in meters */
  searchRadius: number;
  /** When search was performed */
  timestamp: string;
}

/**
 * Data needed to save a station
 */
export interface SaveStationData {
  /** Custom nickname for the station */
  nickname?: string;
  /** User notes about the station */
  notes?: string;
  /** Whether to mark as favorite */
  isFavorite?: boolean;
  /** Whether 93 octane is available */
  has93Octane?: boolean;
  /** Whether the 93 octane option is ethanol free */
  has93OctaneEthanolFree?: boolean;
}

/**
 * Marker for map display
 */
export interface MapMarker {
  placeId: string;
  name: string;
  latitude: number;
  longitude: number;
  isSaved: boolean;
  distance?: number;
}

/**
 * Geolocation position from browser API
 */
export interface GeolocationCoordinates {
  latitude: number;
  longitude: number;
  accuracy: number;
}

/**
 * Geolocation status and error types
 */
export enum GeolocationError {
  PERMISSION_DENIED = 'PERMISSION_DENIED',
  POSITION_UNAVAILABLE = 'POSITION_UNAVAILABLE',
  TIMEOUT = 'TIMEOUT',
  UNKNOWN = 'UNKNOWN'
}

/**
 * API error response
 */
export interface ApiError {
  message: string;
  code?: string;
  details?: Record<string, unknown>;
}

/** User-facing preference for 93 octane availability */
export type OctanePreference = 'none' | 'with_ethanol' | 'ethanol_free';
