piwigodotnet/PiwigoDotnet/Piwigo.Client/IImageApi.cs

using Piwigo.Client.Contract;

namespace Piwigo.Client;

public interface IImageApi
{
    /// <summary>
    ///     Adds an image to piwigo after all parts have been uploaded.
    /// </summary>
    /// <param name="imageUpload">The metadata of the uploaded image</param>
    /// <param name="cancellationToken">
    ///     <see cref="CancellationToken" />
    /// </param>
    /// <returns>Information about the uploaded image</returns>
    /// <remarks>Ensure that you called <see cref="AddChunkAsync" /> for every chunk of the image.</remarks>
    Task<ImageUploaded> AddAsync(ImageUpload imageUpload, CancellationToken cancellationToken = default);

    /// <summary>
    ///     Updates an image to piwigo after all parts have been uploaded.
    /// </summary>
    /// <param name="imageId">The image id to update</param>
    /// <param name="imageUpload">The metadata of the uploaded image</param>
    /// <param name="cancellationToken">
    ///     <see cref="CancellationToken" />
    /// </param>
    /// <returns>Information about the uploaded image</returns>
    /// <remarks>Ensure that you called <see cref="AddChunkAsync" /> for every chunk of the image.</remarks>
    Task<ImageUploaded> UpdateAsync(int imageId, ImageUpload imageUpload, CancellationToken cancellationToken = default);

    /// <summary>
    ///     Adds a comment to the given image.
    /// </summary>
    /// <param name="imageId">The id of the image</param>
    /// <param name="author">The author</param>
    /// <param name="content">The content</param>
    /// <param name="key">
    ///     The key to post: The key can read from <see cref="GetInfoAsync" /> and <see cref="CommentPost.Key" />
    /// </param>
    /// <param name="cancellationToken">
    ///     <see cref="CancellationToken" />
    /// </param>
    /// <returns>The id of the new comment</returns>
    Task<int> AddCommentAsync(int imageId, string? author, string content, string key, CancellationToken cancellationToken = default);

    /// <summary>
    ///     Adds a chunk of an image to piwigo.
    ///     This enables uploading of large images using multiple chunks of data.
    /// </summary>
    /// <param name="data">The chunk to upload</param>
    /// <param name="originalSum">The original image checksum</param>
    /// <param name="position">The chunk position</param>
    /// <param name="cancellationToken">
    ///     <see cref="CancellationToken" />
    /// </param>
    Task AddChunkAsync(byte[] data, string originalSum, int position, CancellationToken cancellationToken = default);

    /// <summary>
    ///     Checks if piwigo is ready to get images uploaded.
    /// </summary>
    /// <param name="cancellationToken">
    ///     <see cref="CancellationToken" />
    /// </param>
    /// <returns>true if ready; otherwise false</returns>
    Task<bool> ReadyForUploadAsync(CancellationToken cancellationToken = default);

    /// <summary>
    ///     Gets detailed information about the image.
    /// </summary>
    /// <param name="imageId">The image id to read</param>
    /// <param name="commentsPage">The requested comments page</param>
    /// <param name="commentsPerPage">Number of comments per page</param>
    /// <param name="cancellationToken">
    ///     <see cref="CancellationToken" />
    /// </param>
    /// <returns>The metadata of a given image id</returns>
    Task<Image> GetInfoAsync(int imageId, int? commentsPage, int? commentsPerPage, CancellationToken cancellationToken = default);

    /// <summary>
    ///     Gets a list of images for a given album.
    /// </summary>
    /// <param name="albumId">The album id</param>
    /// <param name="recursive">true to get images from sub-albums</param>
    /// <param name="page">Information about the paging</param>
    /// <param name="filter">Filter criteria applied to the returned images</param>
    /// <param name="order">How the list should be sorted</param>
    /// <param name="cancellationToken">
    ///     <see cref="CancellationToken" />
    /// </param>
    /// <returns>a paged list of the images of a given album</returns>
    Task<PagedImages> GetImagesAsync(int albumId, bool recursive, ImagePagingInfo page, ImageFilter filter, ImageOrder order = ImageOrder.Name,
        CancellationToken cancellationToken = default);

    /// <summary>
    ///     Checks if an image is the same as on the server.
    /// </summary>
    /// <param name="imageId">The image id</param>
    /// <param name="md5Sum">The md5 checksum of the given image</param>
    /// <param name="cancellationToken">
    ///     <see cref="CancellationToken" />
    /// </param>
    /// <returns>
    ///     <see cref="ImageCheckStatus" />
    /// </returns>
    Task<ImageCheckStatus> CheckImageAsync(int imageId, string md5Sum, CancellationToken cancellationToken = default);

    /// <summary>
    ///     Deletes the given image from the server.
    /// </summary>
    /// <param name="imageId">the image id to delete</param>
    /// <param name="apiToken">The API token that can be read from <see cref="SessionStatus" /></param>
    /// <param name="cancellationToken">
    ///     <see cref="CancellationToken" />
    /// </param>
    /// <returns>true if the image was found and removed; false if it does not exist</returns>
    Task<bool> DeleteAsync(int imageId, string apiToken, CancellationToken cancellationToken = default);

    /// <summary>
    ///     Deletes a block of orphaned images from the server and returns the number of remaining orphans.
    /// </summary>
    /// <param name="apiToken">The API token that can be read from <see cref="SessionStatus" /></param>
    /// <param name="blockSize">Number of orphaned images to delete in this call</param>
    /// <param name="cancellationToken">
    ///     <see cref="CancellationToken" />
    /// </param>
    /// <returns>The number of deleted orphans and the number of remaining orphan images.</returns>
    Task<OrphanImagesDeleted> DeleteOrphansAsync(string apiToken, int? blockSize = null, CancellationToken cancellationToken = default);

    /// <summary>
    ///     Checks if the given images can be found by their md5 sum.
    ///     This method will only return any information if the configuration of your server contains the following setting:
    ///     <code>$conf[uniqueness_mode]==md5sum</code>
    /// </summary>
    /// <param name="md5Sums">A enumerable of md5sums to check against the piwigo instance</param>
    /// <param name="cancellationToken">
    ///     <see cref="CancellationToken" />
    /// </param>
    /// <returns>
    ///     A dictionary containing the md5sum as key and the image id as value. The image id is null if the image does
    ///     not exist.
    /// </returns>
    Task<IReadOnlyDictionary<string, int?>> ExistsByMd5SumsAsync(IEnumerable<string> md5Sums, CancellationToken cancellationToken = default);

    /// <summary>
    ///     Rates an image. This function only works if you have image rating enabled on your instance under Admin ->
    ///     Configuration -> Options -> General in section Permission.
    /// </summary>
    /// <param name="imageId">The image id that should get this rate</param>
    /// <param name="rate">Rating from 0 to 5</param>
    /// <param name="cancellationToken">
    ///     <see cref="CancellationToken" />
    /// </param>
    /// <returns>Your current rating and the average score including number of rates. <see cref="ImageRating" /></returns>
    Task<ImageRating> RateAsync(int imageId, int rate, CancellationToken cancellationToken = default);

    /// <summary>
    ///     Updates or replaces image information depending on the provided update modes.
    /// </summary>
    /// <param name="imageId">Image id to update</param>
    /// <param name="imageInfo">The image information to use</param>
    /// <param name="singleValueMode">UpdateMode for single value fields: <see cref="ValueUpdateMode" /></param>
    /// <param name="multiValueMode">UpdateMode for multi value fields: <see cref="ValueUpdateMode" /></param>
    /// <param name="cancellationToken">
    ///     <see cref="CancellationToken" />
    /// </param>
    /// <returns></returns>
    Task SetInfoAsync(int imageId, ImageInfo imageInfo, ValueUpdateMode singleValueMode = ValueUpdateMode.Append, ValueUpdateMode multiValueMode = ValueUpdateMode.Append,
        CancellationToken cancellationToken = default);
}