using Codecrete.SwissQRBill.Generator;

namespace DocumentService.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="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="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.Common.Exceptions.NotFoundException">
    /// Thrown when no Swiss QR Code is found in the specified pages
    /// </exception>
    /// <exception cref="ArgumentException">
    /// Thrown when stream is empty or (for seekable streams) not positioned at the beginning
    /// </exception>
    Task<(Bill Bill, string[] RawLines)> ExtractSwissQrCodeAsync(
        Stream pdfStream, 
        int[]? pageNumbers = null, 
        CancellationToken cancellationToken = default);
}