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>
    /// 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>
    /// Clears the topics cache.
    /// </summary>
    void ClearCache();
}