namespace TeleWave.Application.Common.Interfaces;

/// <summary>
/// Локальное хранилище картинок метаданных (постеры/кадры) под metadata/ в корне хранилища. Скачивает
/// изображения к себе, чтобы не зависеть от внешнего CDN на этапе показа.
/// </summary>
public interface IMetadataImageStore
{
    /// <summary>Скачивает постер по URL и сохраняет для шоу. Возвращает относительный путь или null при ошибке.</summary>
    Task<string?> DownloadShowPosterAsync(
        Guid showId,
        string url,
        CancellationToken cancellationToken
    );

    /// <summary>Сохраняет загруженный вручную постер шоу. Возвращает относительный путь.</summary>
    Task<string> SaveShowPosterAsync(
        Guid showId,
        string extension,
        Stream content,
        CancellationToken cancellationToken
    );

    void DeleteShowImages(Guid showId);

    /// <summary>Скачивает кадр серии по URL. Возвращает относительный путь или null при ошибке.</summary>
    Task<string?> DownloadEpisodeStillAsync(
        Guid episodeId,
        string url,
        CancellationToken cancellationToken
    );

    void DeleteEpisodeImages(Guid episodeId);

    /// <summary>Абсолютный путь к файлу по относительному (с защитой от traversal) или null, если вне корня.</summary>
    string? ResolveAbsolutePath(string relativePath);
}