DocumentService/DocumentOperator.Application/Common/Interfaces/IPdfProcessor.cs

using DocumentOperator.Application.Common.DTOs;

namespace DocumentOperator.Application.Common.Interfaces;

public interface IPdfProcessor
{
    /// <summary>
    /// Validates a PDF and extracts metadata.
    /// </summary>
    /// <param name="pdfStream">
    /// PDF document stream. Must be readable and positioned at the beginning (Position = 0).
    /// Non-seekable streams are supported. Caller is responsible for disposal.
    /// </param>
    /// <returns>PDF metadata (page count, size, version, attachments)</returns>
    /// <exception cref="Domain.Common.Exceptions.BadRequestException">
    /// Thrown when stream is empty, invalid, or not positioned at the beginning
    /// </exception>
    Task<PdfMetadata> ValidateAsync(Stream pdfStream);

    /// <summary>
    /// Validates a PDF/A document and checks conformance level.
    /// </summary>
    /// <param name="pdfStream">
    /// PDF document stream. Must be readable and positioned at the beginning (Position = 0).
    /// Non-seekable streams are supported. Caller is responsible for disposal.
    /// </param>
    /// <returns>PDF/A metadata including conformance level and validation errors/warnings</returns>
    /// <exception cref="Domain.Common.Exceptions.BadRequestException">
    /// Thrown when stream is empty, invalid, or not positioned at the beginning
    /// </exception>
    Task<PdfAMetadata> ValidatePdfAAsync(Stream pdfStream);

    /// <summary>
    /// Checks for embedded files (attachments) in a PDF document and returns detailed metadata.
    /// </summary>
    /// <param name="pdfStream">
    /// PDF document stream. Must be readable and positioned at the beginning (Position = 0).
    /// Non-seekable streams are supported. Caller is responsible for disposal.
    /// </param>
    /// <returns>Attachment information (count, file names, MIME types, sizes)</returns>
    /// <exception cref="Domain.Common.Exceptions.BadRequestException">
    /// Thrown when stream is empty, invalid, or not positioned at the beginning
    /// </exception>
    Task<AttachmentInfo> CheckAttachmentsAsync(Stream pdfStream);

    /// <summary>
    /// Extracts all embedded files from a PDF document and returns them as a ZIP archive.
    /// </summary>
    /// <param name="pdfStream">
    /// PDF document stream. Must be readable and positioned at the beginning (Position = 0).
    /// Non-seekable streams are supported. Caller is responsible for disposal.
    /// </param>
    /// <returns>ZIP archive containing all extracted attachments as byte array</returns>
    /// <exception cref="Domain.Common.Exceptions.BadRequestException">
    /// Thrown when stream is empty, invalid, or not positioned at the beginning
    /// </exception>
    /// <exception cref="Domain.Common.Exceptions.NotFoundException">
    /// Thrown when PDF contains no attachments
    /// </exception>
    Task<byte[]> ExtractAttachmentsAsync(Stream pdfStream);

    /// <summary>
    /// Merges multiple PDF documents into a single PDF.
    /// </summary>
    /// <param name="pdfStreams">
    /// PDF streams to merge (minimum 2 required). Each stream must be readable and positioned 
    /// at the beginning (Position = 0). Caller is responsible for disposal.
    /// </param>
    /// <param name="pageRanges">
    /// Optional page ranges per PDF (null = all pages). Format: "1-3,5" means pages 1, 2, 3, and 5.
    /// If null or empty for a PDF, all pages are included. Array length must match pdfStreams length if provided.
    /// </param>
    /// <returns>Merged PDF as byte array</returns>
    /// <exception cref="Domain.Common.Exceptions.BadRequestException">
    /// Thrown when fewer than 2 PDFs provided, any stream is empty/invalid/not at Position=0, 
    /// or page range format is invalid
    /// </exception>
    Task<byte[]> MergePdfsAsync(IReadOnlyList<Stream> pdfStreams, IReadOnlyList<string?>? pageRanges = null);

    /// <summary>
    /// Adds an annotation to a PDF document at the specified page and rectangle.
    /// </summary>
    /// <param name="pdfStream">
    /// PDF document stream. Must be readable and positioned at the beginning (Position = 0).
    /// Non-seekable streams are supported. Caller is responsible for disposal.
    /// </param>
    /// <param name="annotationType">Type of annotation to add (TextMarkup, FreeText, StickyNote, Circle, Square)</param>
    /// <param name="pageNumber">Page number (1-based) where annotation should be added</param>
    /// <param name="rectangle">Annotation bounding rectangle (X1, Y1, X2, Y2) in PDF coordinates</param>
    /// <param name="content">Annotation content/comment text (required for FreeText and StickyNote)</param>
    /// <param name="author">Optional author name</param>
    /// <param name="color">Optional annotation color in RGB format (hex string like "FF0000" for red)</param>
    /// <param name="textMarkupStyle">Text markup style (Highlight, Underline, Strikeout) - only for TextMarkup type</param>
    /// <returns>Annotated PDF as byte array</returns>
    /// <exception cref="Domain.Common.Exceptions.BadRequestException">
    /// Thrown when stream is empty/invalid/not at Position=0, page number out of range, 
    /// rectangle invalid, or content missing for types that require it
    /// </exception>
    Task<byte[]> AddAnnotationAsync(
        Stream pdfStream,
        Domain.Models.ValueObjects.AnnotationType annotationType,
        int pageNumber,
        (double X1, double Y1, double X2, double Y2) rectangle,
        string? content = null,
        string? author = null,
        string? color = null,
        Domain.Models.ValueObjects.TextMarkupStyle? textMarkupStyle = null);
}