namespace SharepointToolbox.Services;

/// <summary>
/// Searches tenant users via Microsoft Graph API for the people-picker autocomplete.
/// </summary>
public interface IGraphUserSearchService
{
    /// <summary>
    /// Searches for users in the tenant whose display name or email matches the query.
    /// Returns up to <paramref name="maxResults"/> matches.
    /// </summary>
    /// <param name="clientId">The Azure AD app client ID for Graph authentication.</param>
    /// <param name="query">Partial name or email to search for.</param>
    /// <param name="maxResults">Maximum number of results to return (default 10).</param>
    /// <param name="ct">Cancellation token.</param>
    /// <returns>List of (DisplayName, Email/UPN) tuples.</returns>
    Task<IReadOnlyList<GraphUserResult>> SearchUsersAsync(
        string clientId,
        string query,
        int maxResults = 10,
        CancellationToken ct = default);
}

/// <summary>
/// Represents a user returned by the Graph API people search.
/// </summary>
public record GraphUserResult(string DisplayName, string UserPrincipalName, string? Mail);