using System.Collections.Generic;
using System.Threading;
using Jellyfin.Data.Entities;
using Jellyfin.Plugin.SRFPlay.Api.Models;
using MediaBrowser.Controller.Entities;

namespace Jellyfin.Plugin.SRFPlay.Services.Interfaces;

/// <summary>
/// Removes stale plugin-owned resume points so ended livestreams and abandoned playback
/// stop accumulating in every user's "Continue Watching" row.
/// </summary>
public interface IResumeCleanupService
{
    /// <summary>
    /// Scans every user's resumable items and clears the resume point of those owned by this
    /// plugin that match a staleness rule. Items belonging to other plugins or to the regular
    /// library are never touched.
    /// </summary>
    /// <param name="clearAll">
    /// When true every plugin-owned resume point is cleared regardless of the staleness rules.
    /// Used by the "Clear all" maintenance action.
    /// </param>
    /// <param name="cancellationToken">The cancellation token.</param>
    /// <returns>A summary of what was inspected and cleared.</returns>
    ResumeCleanupResult Cleanup(bool clearAll, CancellationToken cancellationToken);

    /// <summary>
    /// Clears the resume point of a single item for the given users.
    /// </summary>
    /// <param name="item">The item whose resume point should be reset.</param>
    /// <param name="users">The users to clear it for.</param>
    /// <param name="reason">A short reason, logged for traceability.</param>
    /// <returns>The number of resume points actually cleared.</returns>
    int ClearResumePoint(BaseItem item, IEnumerable<User> users, string reason);

    /// <summary>
    /// Determines whether an item belongs to this plugin (an SRG channel item or a recording).
    /// </summary>
    /// <param name="item">The item to test.</param>
    /// <returns>True if the item is owned by this plugin.</returns>
    bool IsPluginItem(BaseItem item);

    /// <summary>
    /// Clears the resume point if the item is one of this plugin's livestreams and livestream
    /// cleanup is enabled. Called right after playback stops so an ended broadcast never reaches
    /// "Continue Watching" in the first place, instead of waiting for the nightly task.
    /// </summary>
    /// <param name="item">The item that just stopped playing.</param>
    /// <param name="users">The users the playback was attributed to.</param>
    /// <returns>The number of resume points cleared.</returns>
    int ClearLiveStreamResumePoint(BaseItem item, IEnumerable<User> users);
}