shoc-backend/SeaHaven.DataServices/Interfaces/IForgetPasswordDataService.cs

using Data.SeaHavenIndustries;

namespace SeaHaven.DataServices.Interfaces
{
    public interface IForgetPasswordDataService
    {
        /// <summary>
        /// In one transaction, deletes every pending code for the email and every expired
        /// code, then stores the new one.
        /// </summary>
        Task ReplaceCodeAsync(string email, string userId, string codeHash, string codeSalt, DateTime expiresAtUtc, DateTime nowUtc, CancellationToken cancellationToken);

        Task PurgeExpiredAsync(DateTime nowUtc, CancellationToken cancellationToken);

        /// <summary>Returns the pending code for exactly this email, or null.</summary>
        Task<ForgetPasswordCode?> GetByEmailAsync(string email, CancellationToken cancellationToken);

        /// <summary>
        /// Atomically consumes one attempt when the code is unexpired and has fewer
        /// than <paramref name="maxAttempts"/> consumed. Returns false otherwise.
        /// </summary>
        Task<bool> TryConsumeAttemptAsync(int id, int maxAttempts, DateTime nowUtc, CancellationToken cancellationToken);

        /// <summary>Gives back an attempt consumed by a check that matched.</summary>
        Task RefundAttemptAsync(int id, CancellationToken cancellationToken);

        Task RemoveByEmailAsync(string email, CancellationToken cancellationToken);

        /// <summary>
        /// Deletes the email's codes issued up to and including <paramref name="throughId"/>,
        /// leaving any code issued after it by a concurrent request.
        /// </summary>
        Task RemoveIssuedThroughAsync(string email, int throughId, CancellationToken cancellationToken);
    }
}