namespace DocumentService.Client.Interfaces;

/// <summary>
/// Client for ZUGFeRD operations (detection, extraction).
/// </summary>
public interface IZugferdClient
{
    /// <summary>
    /// Checks whether a PDF contains a ZUGFeRD XML attachment (multipart).
    /// </summary>
    /// <param name="pdfStream">PDF file stream</param>
    /// <param name="cancellationToken">Cancellation token</param>
    /// <returns>ZUGFeRD check result</returns>
    Task<ZugferdCheckResult> HasZugferdAsync(Stream pdfStream, CancellationToken cancellationToken = default);

    /// <summary>
    /// Checks whether a PDF contains a ZUGFeRD XML attachment (Base64).
    /// </summary>
    /// <param name="pdfBytes">PDF file as byte array</param>
    /// <param name="cancellationToken">Cancellation token</param>
    /// <returns>ZUGFeRD check result</returns>
    Task<ZugferdCheckResult> HasZugferdAsync(byte[] pdfBytes, CancellationToken cancellationToken = default);

    /// <summary>
    /// Extracts the ZUGFeRD XML from a PDF and returns the raw XML stream (multipart).
    /// </summary>
    /// <param name="pdfStream">PDF file stream</param>
    /// <param name="cancellationToken">Cancellation token</param>
    /// <returns>ZUGFeRD XML content as stream</returns>
    Task<Stream> ExtractZugferdAsync(Stream pdfStream, CancellationToken cancellationToken = default);

    /// <summary>
    /// Extracts the ZUGFeRD XML from a PDF and returns the raw XML stream (Base64).
    /// </summary>
    /// <param name="pdfBytes">PDF file as byte array</param>
    /// <param name="cancellationToken">Cancellation token</param>
    /// <returns>ZUGFeRD XML content as stream</returns>
    Task<Stream> ExtractZugferdAsync(byte[] pdfBytes, CancellationToken cancellationToken = default);

    /// <summary>
    /// Extracts ZUGFeRD metadata and XML content as a structured result (multipart).
    /// </summary>
    /// <param name="pdfStream">PDF file stream</param>
    /// <param name="cancellationToken">Cancellation token</param>
    /// <returns>Structured ZUGFeRD extraction result</returns>
    Task<ZugferdExtractionResult> ExtractZugferdAsResultAsync(Stream pdfStream, CancellationToken cancellationToken = default);

    /// <summary>
    /// Extracts ZUGFeRD metadata and XML content as a structured result (Base64).
    /// </summary>
    /// <param name="pdfBytes">PDF file as byte array</param>
    /// <param name="cancellationToken">Cancellation token</param>
    /// <returns>Structured ZUGFeRD extraction result</returns>
    Task<ZugferdExtractionResult> ExtractZugferdAsResultAsync(byte[] pdfBytes, CancellationToken cancellationToken = default);
}

/// <summary>DTO for ZUGFeRD detection result</summary>
public record ZugferdCheckResult
{
    /// <summary>Whether the document contains a ZUGFeRD XML attachment.</summary>
    public bool HasZugferd { get; init; }
    /// <summary>Detected ZUGFeRD version (e.g. "2.1"), or <c>null</c> if not present.</summary>
    public string? Version { get; init; }
    /// <summary>ZUGFeRD profile name (e.g. "EN 16931"), or <c>null</c> if not present.</summary>
    public string? Profile { get; init; }
}

/// <summary>DTO for ZUGFeRD extraction result</summary>
public record ZugferdExtractionResult
{
    /// <summary>File name of the extracted XML attachment (e.g. "factur-x.xml").</summary>
    public string FileName { get; init; } = string.Empty;
    /// <summary>Full XML content of the ZUGFeRD attachment.</summary>
    public string XmlContent { get; init; } = string.Empty;
    /// <summary>ZUGFeRD version (e.g. "2.1"), or <c>null</c> if not detected.</summary>
    public string? Version { get; init; }
    /// <summary>ZUGFeRD profile name (e.g. "EN 16931"), or <c>null</c> if not detected.</summary>
    public string? Profile { get; init; }
}