Cleanuparr/code/backend/Cleanuparr.Infrastructure/Features/Arr/Interfaces/IArrClient.cs

using Cleanuparr.Domain.Entities.Arr;
using Cleanuparr.Domain.Entities.Arr.ManualImport;
using Cleanuparr.Domain.Entities.Arr.Queue;
using Cleanuparr.Domain.Enums;
using Cleanuparr.Persistence.Models.Configuration.Arr;

namespace Cleanuparr.Infrastructure.Features.Arr.Interfaces;

public interface IArrClient
{
    Task<QueueListResponse> GetQueueItemsAsync(ArrInstance arrInstance, int page);

    Task<bool> ShouldRemoveFromQueue(InstanceType instanceType, QueueRecord record, bool isPrivateDownload, short arrMaxStrikes);

    /// <summary>
    /// Whether this arr exposes the manual import endpoints that force import needs.
    /// </summary>
    bool SupportsForceImport { get; }

    /// <summary>
    /// Reads the files an arr found for a download, each with the reasons the arr refuses to import it.
    /// </summary>
    /// <param name="arrInstance">The instance holding the download.</param>
    /// <param name="downloadId">The download id as the arr reports it, which the arr matches exactly.</param>
    Task<List<ManualImportCandidate>> GetManualImportCandidatesAsync(ArrInstance arrInstance, string downloadId);

    /// <summary>
    /// Makes the arr import files it refused to import on its own.
    /// </summary>
    /// <returns>True when the request was sent, false when dry run skipped it.</returns>
    Task<bool> ForceImportAsync(ArrInstance arrInstance, List<ManualImportFile> files);

    /// <summary>
    /// Counts the times the arr recorded an import for a download.
    /// </summary>
    /// <remarks>
    /// The arr keeps history past the download, so only a count that grew proves a new import.
    /// </remarks>
    /// <param name="downloadId">The download id as the arr reports it, which the arr matches exactly.</param>
    Task<int> GetImportedCountAsync(ArrInstance arrInstance, string downloadId);

    /// <summary>
    /// Builds the import payload for a candidate.
    /// </summary>
    /// <returns>The payload, or null when the candidate maps to other content than the queue record.</returns>
    ManualImportFile? MapCandidate(QueueRecord record, ManualImportCandidate candidate);

    /// <summary>
    /// Removes a queue item from the *arr instance.
    /// </summary>
    /// <param name="arrInstance">The *arr instance hosting the queue item.</param>
    /// <param name="record">The queue record to remove.</param>
    /// <param name="removeFromClient">When true, also delete the download from the download client. Ignored when <paramref name="changeCategory"/> is true.</param>
    /// <param name="changeCategory">When true, instructs the *arr to change the download's category to the post-import category instead of removing it from the download client. Mutually exclusive with <paramref name="removeFromClient"/>.</param>
    /// <param name="deleteReason">Reason for removal, used for logging and event publishing.</param>
    /// <returns>True when the request was sent, false when dry run skipped it.</returns>
    Task<bool> DeleteQueueItemAsync(ArrInstance arrInstance, QueueRecord record, bool removeFromClient, bool changeCategory, DeleteReason deleteReason);

    /// <summary>
    /// Triggers a search for the specified items and returns the arr command IDs
    /// </summary>
    Task<List<long>> SearchItemsAsync(ArrInstance arrInstance, HashSet<SearchItem>? items);

    /// <summary>
    /// Triggers a search for a single item and returns the arr command ID
    /// </summary>
    Task<long> SearchItemAsync(ArrInstance arrInstance, SearchItem item);

    /// <summary>
    /// Gets the status of an arr command by its ID
    /// </summary>
    Task<ArrCommandStatus> GetCommandStatusAsync(ArrInstance arrInstance, long commandId);

    /// <summary>
    /// Gets every command the arr instance currently knows about
    /// </summary>
    Task<List<ArrCommandStatus>> GetCommandsAsync(ArrInstance arrInstance);

    bool IsRecordValid(QueueRecord record);

    /// <summary>
    /// Checks whether the record has an id (movie id, tv show id etc.)
    /// </summary>
    /// <param name="record">The record to check</param>
    /// <returns>True if the record has an id, false otherwise</returns>
    bool HasContentId(QueueRecord record);

    /// <summary>
    /// Tests the connection to an Arr instance
    /// </summary>
    /// <param name="arrInstance">The instance to test connection to</param>
    /// <returns>Task that completes when the connection test is done</returns>
    Task HealthCheckAsync(ArrInstance arrInstance);

    /// <summary>
    /// Returns the number of items actively downloading (SizeLeft > 0) across all queue pages.
    /// Items that are completed, import-blocked, or otherwise finished are not counted.
    /// </summary>
    Task<int> GetActiveDownloadCountAsync(ArrInstance arrInstance);

    Task<List<Tag>> GetAllTagsAsync(ArrInstance arrInstance);
}