namespace SchotzIadKmTracker.Api.Services;

/// <summary>
/// Client de l'API OpenRouteService (ORS) — calcul d'itinéraire routier uniquement.
/// ORS n'est jamais appelé pour du géocodage ni avec des coordonnées nulles :
/// les coordonnées de départ et d'arrivée doivent être connues (non-null).
/// </summary>
public interface IORSClient
{
    /// <summary>
    /// Calcule l'itinéraire routier entre deux points géographiques connus via
    /// <c>POST /v2/directions/driving-car</c> et retourne la distance (km) et la
    /// géométrie GeoJSON de l'itinéraire.
    /// </summary>
    /// <param name="lat1">Latitude du point de départ.</param>
    /// <param name="lon1">Longitude du point de départ.</param>
    /// <param name="lat2">Latitude du point d'arrivée.</param>
    /// <param name="lon2">Longitude du point d'arrivée.</param>
    /// <param name="cancellationToken">Jeton d'annulation.</param>
    /// <returns>Un <see cref="RouteResult"/> (distance en km + géométrie GeoJSON).</returns>
    /// <exception cref="ORSTimeoutException">
    /// Levée si l'appel dépasse le délai imparti (voir <c>ORSOptions.TimeoutSeconds</c>),
    /// afin que l'appelant applique le fallback orthodromique (Haversine).
    /// </exception>
    /// <exception cref="ORSException">
    /// Levée en cas d'échec général (erreur réseau, réponse invalide, corps illisible).
    /// </exception>
    Task<RouteResult> CalculateRouteAsync(
        double lat1,
        double lon1,
        double lat2,
        double lon2,
        CancellationToken cancellationToken = default);
}