using DocumentService.Client.Models.Requests;

namespace DocumentService.Client.Interfaces;

/// <summary>
/// Client for PDF operations (merge, annotate, stamp).
/// </summary>
public interface IPdfOperationsClient
{
    // ==================== MERGE OPERATIONS ====================
    
    /// <summary>
    /// Merges multiple PDFs (multipart).
    /// </summary>
    /// <param name="pdfStreams">PDF file streams to merge</param>
    /// <param name="pageRanges">Optional page ranges per PDF (e.g., "1-3,5")</param>
    /// <param name="cancellationToken">Cancellation token</param>
    /// <returns>Merged PDF as stream</returns>
    Task<Stream> MergeAsync(IEnumerable<Stream> pdfStreams, List<string?>? pageRanges = null, CancellationToken cancellationToken = default);

    /// <summary>
    /// Merges multiple PDFs (Base64).
    /// </summary>
    /// <param name="pdfByteArrays">PDF files as byte arrays</param>
    /// <param name="pageRanges">Optional page ranges per PDF (e.g., "1-3,5")</param>
    /// <param name="cancellationToken">Cancellation token</param>
    /// <returns>Merged PDF as stream</returns>
    Task<Stream> MergeAsync(IEnumerable<byte[]> pdfByteArrays, List<string?>? pageRanges = null, CancellationToken cancellationToken = default);

    // ==================== ANNOTATION OPERATIONS ====================
    
    /// <summary>
    /// Adds annotation to PDF (multipart).
    /// </summary>
    /// <param name="pdfStream">PDF file stream</param>
    /// <param name="request">Annotation request with coordinates and style</param>
    /// <param name="cancellationToken">Cancellation token</param>
    /// <returns>Annotated PDF as stream</returns>
    Task<Stream> AnnotateAsync(Stream pdfStream, AddAnnotationBase64Request request, CancellationToken cancellationToken = default);

    /// <summary>
    /// Adds annotation to PDF (Base64).
    /// </summary>
    /// <param name="pdfBytes">PDF file as byte array</param>
    /// <param name="request">Annotation request with coordinates and style</param>
    /// <param name="cancellationToken">Cancellation token</param>
    /// <returns>Annotated PDF as stream</returns>
    Task<Stream> AnnotateAsync(byte[] pdfBytes, AddAnnotationBase64Request request, CancellationToken cancellationToken = default);

    // ==================== STAMP OPERATIONS ====================
    
    /// <summary>
    /// Adds stamp to PDF (multipart).
    /// </summary>
    /// <param name="pdfStream">PDF file stream</param>
    /// <param name="request">Stamp request with position and style</param>
    /// <param name="cancellationToken">Cancellation token</param>
    /// <returns>Stamped PDF as stream</returns>
    Task<Stream> StampAsync(Stream pdfStream, AddStampBase64Request request, CancellationToken cancellationToken = default);

    /// <summary>
    /// Adds stamp to PDF (Base64).
    /// </summary>
    /// <param name="pdfBytes">PDF file as byte array</param>
    /// <param name="request">Stamp request with position and style</param>
    /// <param name="cancellationToken">Cancellation token</param>
    /// <returns>Stamped PDF as stream</returns>
    Task<Stream> StampAsync(byte[] pdfBytes, AddStampBase64Request request, CancellationToken cancellationToken = default);
}