Sharepoint-Toolbox/SharepointToolbox/Services/IStorageService.cs

using Microsoft.SharePoint.Client;
using SharepointToolbox.Core.Models;

namespace SharepointToolbox.Services;

public interface IStorageService
{
    /// <summary>
    /// Collects storage metrics per library/folder using SharePoint StorageMetrics API.
    /// Returns a tree of StorageNode objects with aggregate size data.
    /// </summary>
    Task<IReadOnlyList<StorageNode>> CollectStorageAsync(
        ClientContext ctx,
        StorageScanOptions options,
        IProgress<OperationProgress> progress,
        CancellationToken ct);

    /// <summary>
    /// Enumerates files across all non-hidden document libraries in the site
    /// and aggregates storage consumption grouped by file extension.
    /// Uses CSOM CamlQuery to retrieve FileLeafRef and File_x0020_Size per file.
    /// This is a separate operation from CollectStorageAsync -- it provides
    /// file-type breakdown data for chart visualization.
    /// </summary>
    Task<IReadOnlyList<FileTypeMetric>> CollectFileTypeMetricsAsync(
        ClientContext ctx,
        IProgress<OperationProgress> progress,
        CancellationToken ct);

    /// <summary>
    /// Backfills StorageNodes that have zero TotalFileCount/TotalSizeBytes
    /// by enumerating files per library via CamlQuery.
    /// This works around the StorageMetrics API returning zeros when the
    /// caller lacks sufficient permissions or metrics haven't been calculated.
    /// </summary>
    Task BackfillZeroNodesAsync(
        ClientContext ctx,
        IReadOnlyList<StorageNode> nodes,
        IProgress<OperationProgress> progress,
        CancellationToken ct);
}