using DocumentService.Application.Common.DTOs;
using DocumentService.Client.Models.Results;

namespace DocumentService.Client.Interfaces;

/// <summary>
/// Orchestrated multi-step workflows that combine multiple DocumentService operations into
/// a single, higher-level call. Prefer these over manually chaining individual clients.
/// </summary>
public interface IWorkflowsClient
{
    /// <summary>
    /// Validates the PDF and attempts Swiss QR Code extraction in a single call,
    /// returning both results together. The method never throws on invalid documents –
    /// the caller receives the full <see cref="PdfValidationResult"/> regardless of outcome,
    /// enabling detailed logging, diagnostics, or batch processing without try/catch.
    /// </summary>
    /// <param name="pdfBytes">PDF file as byte array.</param>
    /// <param name="raw">
    /// <c>false</c> (default) – returns a parsed <see cref="SwissQrCodeExtractionResult.Bill"/> object.<br/>
    /// <c>true</c> – returns raw QR text lines without parsing.
    /// </param>
    /// <param name="cancellationToken">Cancellation token.</param>
    /// <returns>
    /// A <see cref="SwissQrCodeResult"/> containing the <see cref="PdfValidationResult"/>
    /// (always populated) and the <see cref="SwissQrCodeExtractionResult"/> (<c>null</c> if the
    /// document was invalid).
    /// </returns>
    Task<SwissQrCodeResult> InspectSwissQrCodeAsync(
        byte[] pdfBytes,
        bool raw = false,
        CancellationToken cancellationToken = default);

    /// <inheritdoc cref="InspectSwissQrCodeAsync(byte[], bool, CancellationToken)"/>
    /// <param name="pdfStream">PDF file as a stream.</param>
    /// <param name="raw"><inheritdoc cref="InspectSwissQrCodeAsync(byte[], bool, CancellationToken)" path="/param[@name=''raw'']"/></param>
    /// <param name="cancellationToken">Cancellation token.</param>
    Task<SwissQrCodeResult> InspectSwissQrCodeAsync(
        Stream pdfStream,
        bool raw = false,
        CancellationToken cancellationToken = default);
}