using Codecrete.SwissQRBill.Generator;

namespace DocumentOperator.Application.Common.Interfaces;

/// <summary>
/// Interface for Swiss QR Code processing operations.
/// Extracts and parses Swiss QR Codes from PDF documents.
/// </summary>
public interface ISwissQrCodeProcessor
{
    /// <summary>
    /// Extracts and parses Swiss QR Code from a PDF document.
    /// Returns both parsed Bill object and raw QR text lines.
    /// </summary>
    /// <param name="pdfBytes">PDF document as byte array</param>
    /// <param name="pageNumbers">Optional: Specific page numbers to scan (1-indexed). If null, scans all pages starting with last page.</param>
    /// <param name="cancellationToken">Cancellation token</param>
    /// <returns>Tuple: (Parsed Codecrete Bill, Raw QR lines as string array)</returns>
    /// <exception cref="Domain.Exceptions.SwissQrCodeNotFoundException">
    /// Thrown when no Swiss QR Code is found in the specified pages
    /// </exception>
    /// <exception cref="Domain.Exceptions.PdfProcessingException">
    /// Thrown when PDF processing fails
    /// </exception>
    Task<(Bill Bill, string[] RawLines)> ExtractSwissQrCodeAsync(
        byte[] pdfBytes, 
        int[]? pageNumbers = null, 
        CancellationToken cancellationToken = default);
}