using TrajetKmTracker.Api.Models.DTOs;

namespace TrajetKmTracker.Api.Services;

/// <summary>
/// Client de l'API BAN (Base Adresses Nationale) pour l'autocomplétion
/// et le géocodage des adresses françaises.
/// </summary>
public interface IBANClient
{
    /// <summary>
    /// Recherche des adresses correspondant à <paramref name="query"/> via l'endpoint
    /// <c>/search/</c> de la BAN (limité à 5 résultats).
    /// </summary>
    /// <param name="query">Texte de recherche (adresse partielle ou complète).</param>
    /// <param name="cancellationToken">Jeton d'annulation.</param>
    /// <returns>La liste des adresses trouvées, mappées en <see cref="BANAdresseDto"/>.</returns>
    /// <exception cref="Exceptions.BANIndisponibleException">
    /// Levée en cas d'échec réseau, de réponse non réussie ou de dépassement du délai.
    /// </exception>
    Task<IReadOnlyList<BANAdresseDto>> RechercherAsync(string query, CancellationToken cancellationToken = default);
}