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 content as stream (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 or invalid
    /// </exception>
    Task<PdfMetadata> ValidateAsync(Stream pdfStream);

    /// <summary>
    /// Validates a PDF/A document and checks conformance level.
    /// </summary>
    /// <param name="pdfStream">PDF content as stream (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 or invalid
    /// </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 content as stream (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 or invalid
    /// </exception>
    Task<AttachmentInfo> CheckAttachmentsAsync(Stream pdfStream);
}