namespace Api.Services.Contracts;

/// <summary>
/// Extracts plain text from a job posting, either from a pasted description or by fetching and parsing a URL.
/// </summary>
public interface IJobTextExtractor
{
    /// <summary>
    /// Returns normalised plain text for the job posting.
    /// Prefers <paramref name="jobDescription"/> when provided; otherwise fetches and strips HTML from <paramref name="jobUrl"/>.
    /// </summary>
    /// <param name="jobUrl">URL of the job posting page, used when no description is pasted.</param>
    /// <param name="jobDescription">Pasted job description text; takes priority over URL fetching.</param>
    /// <param name="ct">Cancellation token.</param>
    /// <returns>Normalised plain text, truncated to the configured maximum character limit.</returns>
    Task<string> ExtractAsync(string? jobUrl, string? jobDescription, CancellationToken ct);
}