// ***********************************************************************
// <copyright file="IUserService.cs">
//     AgileWebs
// </copyright>
// ***********************************************************************

using Core.Thalos.BuildingBlocks;
using Core.Thalos.Domain.Contexts.Onboarding.Request;

namespace Core.Thalos.Provider.Contracts
{
    /// <summary>
    /// Interface for User-related service operations.
    /// </summary>
    public interface IUserProvider
    {
        /// <summary>
        /// Creates a new User.
        /// </summary>
        /// <param name="newUser">The User to be created.</param>
        /// <param name="cancellationToken">A token to cancel the asynchronous operation.</param>
        /// <returns>
        /// A <see cref="ValueTask{UserAdapter}"/> representing the asynchronous execution of the service.
        /// </returns>
        ValueTask<UserAdapter> CreateUser(UserRequest newUser, CancellationToken cancellationToken);

        /// <summary>
        /// Gets a User by Mongo identifier.
        /// </summary>
        /// <param name="_id">The User Mongo identifier.</param>
        /// <param name="cancellationToken">A token to cancel the asynchronous operation.</param>
        /// <returns>
        /// A <see cref="ValueTask{UserAdapter}"/> representing the asynchronous execution of the service.
        /// </returns>
        ValueTask<UserAdapter> GetUserById(string _id, CancellationToken cancellationToken);

        /// <summary>
        /// Gets all Users.
        /// </summary>
        /// <param name="cancellationToken">A token to cancel the asynchronous operation.</param>
        /// <returns>
        /// A <see cref="ValueTask{IEnumerable{UserAdapter}}"/> representing the asynchronous execution of the service.
        /// </returns>
        ValueTask<IEnumerable<UserAdapter>> GetAllUsers(CancellationToken cancellationToken);

        /// <summary>
        /// Gets a User by email.
        /// </summary>
        /// <param name="email">The User's email.</param>
        /// <param name="cancellationToken">A token to cancel the asynchronous operation.</param>
        /// <returns>
        /// A <see cref="ValueTask{UserAdapter}"/> representing the asynchronous execution of the service.
        /// </returns>
        ValueTask<UserAdapter> GetUserByEmail(string email, CancellationToken cancellationToken);

        /// <summary>
        /// Validates if a User exists by email.
        /// </summary>
        /// <param name="email">The User's email.</param>
        /// <param name="cancellationToken">A token to cancel the asynchronous operation.</param>
        /// <returns>
        /// A <see cref="ValueTask{UserExistenceAdapter}"/> representing the asynchronous execution of the service.
        /// </returns>
        ValueTask<UserExistenceAdapter> ValidateUserExistence(string email, CancellationToken cancellationToken);

        /// <summary>
        /// Changes the status of a User.
        /// </summary>
        /// <param name="_id">The User Mongo identifier.</param>
        /// <param name="newStatus">The new status of the User.</param>
        /// <param name="cancellationToken">A token to cancel the asynchronous operation.</param>
        /// <returns>
        /// A <see cref="ValueTask{UserAdapter}"/> representing the asynchronous execution of the service.
        /// </returns>
        ValueTask<UserAdapter?> ChangeUserStatus(string _id, Blueprint.Mongo.StatusEnum newStatus, CancellationToken cancellationToken);

        /// <summary>
        /// Updates a User.
        /// </summary>
        /// <param name="entity">The User to be updated.</param>
        /// <param name="cancellationToken">A token to cancel the asynchronous operation.</param>
        /// <returns>
        /// A <see cref="ValueTask{UserAdapter}"/> representing the asynchronous execution of the service.
        /// </returns>
        ValueTask<UserAdapter?> UpdateUser(UserAdapter entity, CancellationToken cancellationToken);

        /// <summary>
        /// Logs in the User.
        /// </summary>
        /// <param name="email">The User's email.</param>
        /// <param name="cancellationToken">A token to cancel the asynchronous operation.</param>
        /// <returns>
        /// A <see cref="ValueTask{UserAdapter}"/> representing the asynchronous execution of the service.
        /// </returns>
        ValueTask<UserAdapter?> LogInUser(string email, CancellationToken cancellationToken);

        /// <summary>
        /// Logs out the User's session.
        /// </summary>
        /// <param name="email">The User's email.</param>
        /// <param name="cancellationToken">A token to cancel the asynchronous operation.</param>
        /// <returns>
        /// A <see cref="ValueTask{UserAdapter}"/> representing the asynchronous execution of the service.
        /// </returns>
        ValueTask<UserAdapter?> LogOutUserSession(string email, CancellationToken cancellationToken);

        /// <summary>
        /// Gets the TokenAdapter for a User.
        /// </summary>
        /// <param name="email">The User's email.</param>
        /// <param name="cancellationToken">A token to cancel the asynchronous operation.</param>
        /// <returns>
        /// A <see cref="ValueTask{TokenAdapter}"/> representing the asynchronous execution of the service.
        /// </returns>
        ValueTask<TokenAdapter?> GetToken(string email, CancellationToken cancellationToken);

        /// <summary>
        /// Deletes a User by Mongo identifier.
        /// </summary>
        /// <param name="_id">The User Mongo identifier.</param>
        /// <param name="cancellationToken">A token to cancel the asynchronous operation.</param>
        /// <returns>
        /// A <see cref="ValueTask{UserAdapter}"/> representing the asynchronous execution of the service.
        /// </returns>
        ValueTask<UserAdapter?> DeleteUser(string _id, CancellationToken cancellationToken);
    }
}