using DocumentService.Application.Common.DTOs;
using DocumentService.Client.Models.Requests;

namespace DocumentService.Client.Interfaces;

/// <summary>
/// Client for PDF attachment operations (check, extract, add).
/// </summary>
public interface IPdfAttachmentClient
{
    /// <summary>
    /// Checks if PDF contains attachments (multipart).
    /// </summary>
    /// <param name="pdfStream">PDF file stream</param>
    /// <param name="cancellationToken">Cancellation token</param>
    /// <returns>Attachment check result with metadata</returns>
    Task<AttachmentCheckResult> CheckAttachmentsAsync(Stream pdfStream, CancellationToken cancellationToken = default);

    /// <summary>
    /// Checks if PDF contains attachments (Base64).
    /// </summary>
    /// <param name="pdfBytes">PDF file as byte array</param>
    /// <param name="cancellationToken">Cancellation token</param>
    /// <returns>Attachment check result with metadata</returns>
    Task<AttachmentCheckResult> CheckAttachmentsAsync(byte[] pdfBytes, CancellationToken cancellationToken = default);

    /// <summary>
    /// Extracts all embedded attachments from a PDF (multipart).
    /// The returned dictionary maps each file name to its decompressed content stream.
    /// </summary>
    /// <param name="pdfStream">PDF file stream</param>
    /// <param name="cancellationToken">Cancellation token</param>
    /// <returns>Dictionary of file name ? content stream for each extracted attachment</returns>
    Task<Dictionary<string, Stream>> ExtractAttachmentsAsync(Stream pdfStream, CancellationToken cancellationToken = default);

    /// <summary>
    /// Extracts all embedded attachments from a PDF (Base64).
    /// The returned dictionary maps each file name to its decompressed content stream.
    /// </summary>
    /// <param name="pdfBytes">PDF file as byte array</param>
    /// <param name="cancellationToken">Cancellation token</param>
    /// <returns>Dictionary of file name ? content stream for each extracted attachment</returns>
    Task<Dictionary<string, Stream>> ExtractAttachmentsAsync(byte[] pdfBytes, CancellationToken cancellationToken = default);

    /// <summary>
    /// Adds attachments to PDF (multipart). ?? Not implemented yet in API.
    /// </summary>
    /// <param name="pdfStream">PDF file stream</param>
    /// <param name="attachments">Attachments to add</param>
    /// <param name="cancellationToken">Cancellation token</param>
    /// <returns>Modified PDF as stream</returns>
    [Obsolete("API endpoint not implemented yet")]
    Task<Stream> AddAttachmentsAsync(Stream pdfStream, List<AttachmentRequestDto> attachments, CancellationToken cancellationToken = default);

    /// <summary>
    /// Adds attachments to PDF (Base64). ?? Not implemented yet in API.
    /// </summary>
    /// <param name="pdfBytes">PDF file as byte array</param>
    /// <param name="attachments">Attachments to add</param>
    /// <param name="cancellationToken">Cancellation token</param>
    /// <returns>Modified PDF as stream</returns>
    [Obsolete("API endpoint not implemented yet")]
    Task<Stream> AddAttachmentsAsync(byte[] pdfBytes, List<AttachmentRequestDto> attachments, CancellationToken cancellationToken = default);
}