namespace Api.Services.Contracts;

/// <summary>
/// Manages one-time job search tokens and the sessions they trigger.
/// </summary>
public interface IJobTokenService
{
    /// <summary>
    /// Creates a new single-use job search token linked to the given CV document and user.
    /// The token expires after the number of days configured in <c>JobSearch:TokenExpiryDays</c>.
    /// </summary>
    /// <param name="cvDocumentId">Identifier of the indexed CV document.</param>
    /// <param name="email">Email address of the user who will receive the results.</param>
    /// <param name="language">Preferred language for result emails (e.g. <c>"en"</c>, <c>"ro"</c>).</param>
    /// <param name="ct">Cancellation token.</param>
    /// <returns>The generated token ID, to be embedded in the one-click job search link.</returns>
    Task<string> CreateTokenAsync(string cvDocumentId, string email, string language, CancellationToken ct);

    /// <summary>
    /// Validates the token and, if valid, marks it as used and creates a <c>Pending</c> job search session.
    /// </summary>
    /// <param name="tokenId">The token ID from the one-click link.</param>
    /// <param name="ct">Cancellation token.</param>
    /// <returns>
    /// One of the <c>StartJobSearchStatus</c> string constants:
    /// <c>Started</c>, <c>AlreadyUsed</c>, <c>Expired</c>, or <c>NotFound</c>.
    /// </returns>
    Task<string> TriggerStartAsync(string tokenId, CancellationToken ct);
}