namespace PLib.Application.Abstractions;

/// <summary>Produces (and caches on disk) a poster frame for a video file.</summary>
public interface IThumbnailGenerator
{
    /// <summary>
    /// Returns the absolute path of the poster frame for <paramref name="videoPath"/>,
    /// generating it if it is not cached yet. Returns <c>null</c> when no frame could be
    /// extracted; a missing thumbnail is a normal outcome, not an error.
    /// </summary>
    Task<string?> GetOrCreateAsync(
        string videoPath,
        TimeSpan? duration,
        CancellationToken cancellationToken = default);

    /// <summary>
    /// True when a previously generated poster frame is still present in the cache. The
    /// cache directory is ordinary user-writable storage, so a path the library remembers
    /// is not proof that the file behind it still exists.
    /// </summary>
    bool IsAvailable(string? thumbnailPath);

    /// <summary>
    /// Deletes cached frames that no library item points at any more, and returns how many
    /// files were removed. Call only after a complete scan: anything not in
    /// <paramref name="inUsePaths"/> is treated as garbage.
    /// </summary>
    Task<int> PurgeUnusedAsync(
        IReadOnlyCollection<string> inUsePaths,
        CancellationToken cancellationToken = default);

    /// <summary>How much disk the cache currently occupies, in bytes.</summary>
    Task<long> GetCacheSizeInBytesAsync(CancellationToken cancellationToken = default);

    /// <summary>Empties the cache completely. Returns how many files were removed.</summary>
    Task<int> ClearAsync(CancellationToken cancellationToken = default);
}