using SharepointToolbox.Core.Models;

namespace SharepointToolbox.Services;

/// <summary>
/// Enumerates all enabled member users from a tenant via Microsoft Graph.
/// Used by Phase 13's User Directory ViewModel to populate the browse grid.
/// </summary>
public interface IGraphUserDirectoryService
{
    /// <summary>
    /// Returns all enabled member users in the tenant associated with <paramref name="clientId"/>.
    /// Iterates through all pages using the Graph SDK PageIterator until exhausted or cancelled.
    /// </summary>
    /// <param name="clientId">The client/tenant identifier used to obtain a Graph token.</param>
    /// <param name="includeGuests">
    /// When <c>false</c> (default), only member users are returned (userType eq 'Member').
    /// When <c>true</c>, both members and guests are returned (no userType filter).
    /// </param>
    /// <param name="progress">
    /// Optional progress reporter — receives the running count of users fetched so far.
    /// Phase 13's ViewModel uses this to show "Loading... X users" feedback.
    /// Pass <c>null</c> for no progress reporting.
    /// </param>
    /// <param name="ct">Cancellation token. Iteration stops when cancelled.</param>
    Task<IReadOnlyList<GraphDirectoryUser>> GetUsersAsync(
        string clientId,
        bool includeGuests = false,
        IProgress<int>? progress = null,
        CancellationToken ct = default);
}