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

using Data.SeaHavenIndustries;
using SeaHaven.DataServices.Dto;

namespace SeaHaven.DataServices.Interfaces
{
    /// <summary>
    /// Persistence for team member registration invites. Every state transition that
    /// guards a security limit is a single conditional update, so concurrent requests
    /// cannot exceed the limit; each returns whether the transition happened.
    /// </summary>
    public interface ITeamMemberInviteDataService
    {
        Task AddAsync(TeamMemberInvite invite, CancellationToken cancellationToken);

        /// <summary>Revokes every open invite for the invite's user and adds the new one, atomically.</summary>
        Task ReplaceOpenForUserAsync(TeamMemberInvite invite, DateTime now, CancellationToken cancellationToken);

        Task<TeamMemberInviteData?> GetByTokenHashAsync(string tokenHash, CancellationToken cancellationToken);

        Task<bool> TryStartCodeAsync(StartTeamMemberInviteCodeCommand command, CancellationToken cancellationToken);

        /// <summary>Counts one verification attempt against a live code; false once the attempt limit is used up.</summary>
        Task<bool> TryReserveCodeAttemptAsync(int inviteId, int maxAttempts, DateTime now, CancellationToken cancellationToken);

        Task<bool> TryConfirmEmailAsync(int inviteId, string codeHash, DateTime now, CancellationToken cancellationToken);

        /// <summary>Marks an open, unexpired, email-confirmed invite as used; false when another request already did.</summary>
        Task<bool> TryClaimAsync(int inviteId, DateTime now, CancellationToken cancellationToken);
    }
}