using System;
using System.Threading;
using System.Threading.Tasks;

namespace Jellyfin.Plugin.RecentlyAddedGuard.Core;

/// <summary>
/// An external source for the first "date added" of a medium, e.g. the import history of Radarr or Sonarr.
/// </summary>
/// <remarks>
/// Extension point for v2: implementations registered in the DI container are consulted by the
/// ledger synchronization, and earlier dates lower the ledger via <see cref="Reconciler.ApplyExternalFirstAdded"/>.
/// v1 ships no implementation.
/// </remarks>
public interface IExternalDateSource
{
    /// <summary>
    /// Gets the name of the source for logs.
    /// </summary>
    string Name { get; }

    /// <summary>
    /// Looks up when the medium was first imported.
    /// </summary>
    /// <param name="identity">The medium.</param>
    /// <param name="cancellationToken">The cancellation token.</param>
    /// <returns>The first import date (UTC), or <c>null</c> if unknown.</returns>
    Task<DateTime?> GetFirstAddedAsync(MediaIdentity identity, CancellationToken cancellationToken);
}