using System;
using System.Threading;
using System.Threading.Tasks;
using Jellyfin.Plugin.JRay.Models;

namespace Jellyfin.Plugin.JRay.Services.Interfaces;

/// <summary>
/// Loads and caches scene-actor-extraction "truth" files for library items.
/// </summary>
public interface ITruthDataService
{
    /// <summary>
    /// Gets the truth file for the given library item, if one exists.
    /// </summary>
    /// <param name="itemId">The Jellyfin library item id.</param>
    /// <param name="cancellationToken">Cancellation token.</param>
    /// <returns>The parsed truth file, or null if no truth file exists for this item.</returns>
    Task<TruthFile?> GetTruthAsync(Guid itemId, CancellationToken cancellationToken);

    /// <summary>
    /// Gets how the item's truth data was obtained, or null if it has none.
    /// </summary>
    /// <remarks>
    /// Resolves the same precedence as <see cref="GetTruthAsync"/>: managed
    /// truth (pushed or fetched) wins, and a sidecar is reported as such.
    /// </remarks>
    /// <param name="itemId">The Jellyfin library item id.</param>
    /// <returns>The provenance of the truth data that would be served.</returns>
    TruthProvenance? GetProvenance(Guid itemId);

    /// <summary>
    /// Removes any cached truth file for the given item, so the next
    /// <see cref="GetTruthAsync"/> call re-reads from the managed store or sidecar file.
    /// </summary>
    /// <param name="itemId">The Jellyfin library item id.</param>
    void Invalidate(Guid itemId);

    /// <summary>
    /// Cheaply checks whether truth data exists for an item (managed upload
    /// or sidecar file), without loading or caching it.
    /// </summary>
    /// <param name="itemId">The Jellyfin library item id.</param>
    /// <param name="itemPath">The item's media file path.</param>
    /// <returns><c>true</c> if truth data exists for this item.</returns>
    bool HasTruth(Guid itemId, string itemPath);
}