using Api.Services.Contracts.Models;

namespace Api.Services.Contracts
{
    /// <summary>
    /// Verifies a reCAPTCHA token against the Google verification API.
    /// </summary>
    public interface ICaptchaVerifier
    {
        /// <summary>
        /// Sends the token to the Google reCAPTCHA verification endpoint and
        /// returns a verdict indicating success, score, and any failure reason.
        /// </summary>
        /// <param name="token">The reCAPTCHA token provided by the client.</param>
        /// <param name="userIp">Optional remote IP address passed to Google for additional risk analysis.</param>
        /// <param name="expectedAction">Optional action name to validate against the token's embedded action (v3 only).</param>
        /// <param name="ct">Cancellation token.</param>
        /// <returns>A <see cref="CaptchaVerdictModel"/> with the verification outcome.</returns>
        Task<CaptchaVerdictModel> VerifyAsync(string token, string? userIp, string? expectedAction, CancellationToken ct);
    }
}