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

namespace Jellyfin.Plugin.JRay.Services.Interfaces;

/// <summary>
/// Stores and retrieves truth files that were pushed to JRay directly
/// (e.g. by a remote extraction worker), independent of any sidecar file
/// on the media filesystem.
/// </summary>
public interface IManagedTruthStore
{
    /// <summary>
    /// Loads the managed truth file for the given item, if one was uploaded.
    /// </summary>
    /// <param name="itemId">The Jellyfin library item id.</param>
    /// <param name="cancellationToken">Cancellation token.</param>
    /// <returns>The parsed truth file, or null if none has been uploaded for this item.</returns>
    Task<TruthFile?> LoadAsync(Guid itemId, CancellationToken cancellationToken);

    /// <summary>
    /// Saves (creates or replaces) the managed truth file for the given item.
    /// </summary>
    /// <param name="itemId">The Jellyfin library item id.</param>
    /// <param name="truth">The truth file contents to persist.</param>
    /// <param name="provenance">How this truth data was obtained.</param>
    /// <param name="cancellationToken">Cancellation token.</param>
    /// <returns>A task that completes when the file has been written.</returns>
    /// <remarks>
    /// Provenance is written beside the truth file, never into it: the bytes
    /// served back must be the bytes the producer wrote (JR-004).
    /// </remarks>
    Task SaveAsync(Guid itemId, TruthFile truth, TruthProvenance provenance, CancellationToken cancellationToken);

    /// <summary>
    /// Loads the provenance recorded alongside an item's managed truth data.
    /// </summary>
    /// <param name="itemId">The Jellyfin library item id.</param>
    /// <returns>The provenance, or null if this item has no managed truth data.</returns>
    TruthProvenance? LoadProvenance(Guid itemId);

    /// <summary>
    /// Deletes the managed truth file for the given item, if one exists.
    /// </summary>
    /// <param name="itemId">The Jellyfin library item id.</param>
    /// <returns><c>true</c> if a file was deleted; <c>false</c> if none existed.</returns>
    bool Delete(Guid itemId);

    /// <summary>
    /// Checks whether a managed truth file has been uploaded for the given item.
    /// </summary>
    /// <param name="itemId">The Jellyfin library item id.</param>
    /// <returns><c>true</c> if a managed truth file exists.</returns>
    bool Exists(Guid itemId);
}