using System.Collections.Generic;
using System.Threading;
using System.Threading.Tasks;
using Jellyfin.Plugin.SRFPlay.Api.Models;

namespace Jellyfin.Plugin.SRFPlay.Services.Interfaces;

/// <summary>
/// Interface for managing topic/category data and filtering.
/// </summary>
public interface ICategoryService
{
    /// <summary>
    /// Gets all topics for a business unit.
    /// </summary>
    /// <param name="businessUnit">The business unit.</param>
    /// <param name="cancellationToken">The cancellation token.</param>
    /// <returns>List of topics.</returns>
    Task<List<PlayV3Topic>> GetTopicsAsync(string businessUnit, CancellationToken cancellationToken = default);

    /// <summary>
    /// Gets a topic by ID.
    /// </summary>
    /// <param name="topicId">The topic ID.</param>
    /// <param name="businessUnit">The business unit.</param>
    /// <param name="cancellationToken">The cancellation token.</param>
    /// <returns>The topic, or null if not found.</returns>
    Task<PlayV3Topic?> GetTopicByIdAsync(string topicId, string businessUnit, CancellationToken cancellationToken = default);

    /// <summary>
    /// Filters shows by topic ID.
    /// </summary>
    /// <param name="shows">The shows to filter.</param>
    /// <param name="topicId">The topic ID to filter by.</param>
    /// <returns>Filtered list of shows.</returns>
    IReadOnlyList<PlayV3Show> FilterShowsByTopic(IReadOnlyList<PlayV3Show> shows, string topicId);

    /// <summary>
    /// Groups shows by their topics.
    /// </summary>
    /// <param name="shows">The shows to group.</param>
    /// <returns>Dictionary mapping topic IDs to shows.</returns>
    IReadOnlyDictionary<string, List<PlayV3Show>> GroupShowsByTopics(IReadOnlyList<PlayV3Show> shows);

    /// <summary>
    /// Gets shows for a specific topic, sorted by number of episodes.
    /// </summary>
    /// <param name="topicId">The topic ID.</param>
    /// <param name="businessUnit">The business unit.</param>
    /// <param name="maxResults">Maximum number of results to return.</param>
    /// <param name="cancellationToken">The cancellation token.</param>
    /// <returns>List of shows for the topic.</returns>
    Task<List<PlayV3Show>> GetShowsByTopicAsync(
        string topicId,
        string businessUnit,
        int maxResults = 50,
        CancellationToken cancellationToken = default);

    /// <summary>
    /// Gets video count for each topic.
    /// </summary>
    /// <param name="shows">The shows to analyze.</param>
    /// <returns>Dictionary mapping topic IDs to video counts.</returns>
    IReadOnlyDictionary<string, int> GetVideoCountByTopic(IReadOnlyList<PlayV3Show> shows);

    /// <summary>
    /// Clears the topics cache.
    /// </summary>
    void ClearCache();
}