using DeepDrftModels.DTOs;
using DeepDrftModels.Enums;
using Models.Common;
using NetBlocks.Models;

namespace DeepDrftManager.Services;

/// <summary>
/// CMS-side release operations for the Manager host. Mirrors <see cref="ICmsTrackService"/>: every
/// read and write goes over HTTP to DeepDrftAPI's <c>api/release</c> family, which is the single
/// authority over both the SQL metadata store and the binary vault. The Manager holds no in-process
/// data layer.
/// </summary>
public interface ICmsReleaseService
{
    /// <summary>
    /// Fetch a page of releases from <c>GET api/release</c>, optionally filtered to one
    /// <paramref name="medium"/>. The matching medium's metadata satellite is populated on each row;
    /// the others are null. Null medium returns all releases unfiltered.
    /// </summary>
    Task<ResultContainer<PagedResult<ReleaseDto>>> GetPagedAsync(
        ReleaseMedium? medium,
        int page, int pageSize, string? sortColumn, bool sortDescending,
        CancellationToken ct = default);

    /// <summary>
    /// Fetch a single release with both metadata navs from <c>GET api/release/{id}</c> (nulls for the
    /// non-matching medium). A 404 returns a passing result with a null value.
    /// </summary>
    Task<ResultContainer<ReleaseDto?>> GetByIdAsync(long id, CancellationToken ct = default);

    /// <summary>
    /// Upload a Session hero image via <c>POST api/release/{id}/session/hero-image</c> (multipart).
    /// The server stores it in the image vault and sets <c>SessionMetadata.HeroImageEntryKey</c>.
    /// Maps a 404 to a "Release not found." failure; relays 4xx validation text as-is.
    /// </summary>
    Task<Result> UploadSessionHeroImageAsync(
        long releaseId,
        Stream imageStream,
        string fileName,
        string contentType,
        CancellationToken ct = default);

    /// <summary>
    /// Trigger high-resolution waveform generation for a Mix via
    /// <c>POST api/release/{id}/mix/waveform</c> (no body). The server fetches the mix audio from its
    /// own vault, computes the datum, stores it, and sets <c>MixMetadata.WaveformEntryKey</c>. Maps a
    /// 404 to a "Mix audio not found." failure.
    /// </summary>
    Task<Result> GenerateMixWaveformAsync(long releaseId, CancellationToken ct = default);
}