using EnvelopeGenerator.Application.Common.Dto;

namespace EnvelopeGenerator.Application.Common.Interfaces.Services;

/// <summary>
/// Defines PDF digital-signing operations for the application boundary.
/// </summary>
public interface IPdfDigitalSignatureService
{
    /// <summary>
    /// Creates a digital signature for the provided PDF bytes and returns
    /// a new signed PDF document.
    /// </summary>
    /// <param name="inputPdf">Source PDF content stream.</param>
    /// <param name="outputPdf">Destination stream for signed PDF output.</param>
    /// <param name="options">Optional signing options that map to PDF signature metadata fields.</param>
    /// <param name="cancellationToken">Cancellation token for cooperative cancellation.</param>
    Task SignPdfAsync(Stream inputPdf, Stream outputPdf, PdfSignOptionsDto? options = null, CancellationToken cancellationToken = default);

    /// <summary>
    /// Applies multiple signatures to the provided PDF in sequence and returns
    /// the final signed PDF document.
    /// </summary>
    /// <param name="inputPdf">Source PDF content stream.</param>
    /// <param name="outputPdf">Destination stream for signed PDF output.</param>
    /// <param name="optionsList">Ordered signing options; one signature is applied per item.</param>
    /// <param name="cancellationToken">Cancellation token for cooperative cancellation.</param>
    Task SignPdfAsync(Stream inputPdf, Stream outputPdf, IReadOnlyList<PdfSignOptionsDto> optionsList, CancellationToken cancellationToken = default);

    /// <summary>
    /// Checks whether the provided PDF contains signature field(s) and whether
    /// those signatures are cryptographically valid.
    /// </summary>
    /// <param name="inputPdf">PDF content stream to inspect.</param>
    /// <param name="cancellationToken">Cancellation token for cooperative cancellation.</param>
    /// <returns>A structured result containing signature presence and per-signature details.</returns>
    Task<PdfSignatureCheckResultDto> CheckPdfSignatureAsync(Stream inputPdf, CancellationToken cancellationToken = default);

    /// <summary>
    /// Extracts the original signed revision from a signed PDF.
    /// For multi-revision files this returns the first signed revision bytes.
    /// </summary>
    /// <param name="inputPdf">Signed PDF content stream.</param>
    /// <param name="outputPdf">Destination stream for original revision output.</param>
    /// <param name="cancellationToken">Cancellation token for cooperative cancellation.</param>
    Task ExtractOriginalPdfAsync(Stream inputPdf, Stream outputPdf, CancellationToken cancellationToken = default);
}