namespace Api.Services.Contracts;

/// <summary>
/// Extracts and normalises plain text from documents.
/// </summary>
public interface ITextExtractor
{
    /// <summary>
    /// Reads all pages of a PDF stream and returns the concatenated, normalised plain text.
    /// </summary>
    /// <param name="stream">Readable stream positioned at the start of the PDF file.</param>
    /// <param name="ct">Cancellation token (checked between pages).</param>
    /// <returns>Normalised plain text extracted from the PDF.</returns>
    Task<string> ExtractPdfAsync(Stream stream, CancellationToken ct);

    /// <summary>
    /// Collapses all whitespace sequences in <paramref name="value"/> to single spaces and trims the result.
    /// Returns an empty string for null/whitespace input.
    /// </summary>
    /// <param name="value">Raw text to normalise.</param>
    /// <returns>Whitespace-normalised text.</returns>
    string Normalize(string value);
}