Interface IAdminService

Namespace

Builvero.Application.Services

Assembly

Builvero.Application.dll

Defines the contract for administrative operations including user management, invitation management, and bulk email communications.

public interface IAdminService

Remarks

This interface provides methods for administrative tasks that require elevated permissions (AdminRead or AdminWrite policies). All operations are designed to be safe for concurrent access and include proper error handling.

Methods

BlockUserAsync(Guid, CancellationToken)

Blocks a user account, preventing them from logging in or accessing the platform.

Task BlockUserAsync(Guid userId, CancellationToken cancellationToken = default)

Parameters

userId Guid

The unique identifier of the user to block.

cancellationToken CancellationToken

Cancellation token to cancel the operation.

Returns

Task

Defines the contract for administrative operations including user management, invitation management, and bulk email communications.

Exceptions

Exception

Thrown when the user is not found.

ChangeUserRoleAsync(Guid, string, CancellationToken)

Changes the role assigned to a user, affecting their permissions and access level.

Task ChangeUserRoleAsync(Guid userId, string role, CancellationToken cancellationToken = default)

Parameters

userId Guid

The unique identifier of the user whose role should be changed.

role string

The new role as a string (e.g., "Admin", "Moderator", "User"). Must match a UserRole enum value.

cancellationToken CancellationToken

Cancellation token to cancel the operation.

Returns

Task

Defines the contract for administrative operations including user management, invitation management, and bulk email communications.

Exceptions

Exception

Thrown when the role is invalid or the user is not found.

CreateInvitationAsync(Guid, CreateInvitationRequest, string, CancellationToken)

Creates a new invitation code that can be used for user registration.

Task<InvitationDto> CreateInvitationAsync(Guid createdByUserId, CreateInvitationRequest request, string baseUrl, CancellationToken cancellationToken = default)

Parameters

createdByUserId Guid

The unique identifier of the admin user creating the invitation.

request CreateInvitationRequest

The invitation creation request containing max uses, expiration date, and optional label.

baseUrl string

The base URL of the application, used to construct the full invitation link.

cancellationToken CancellationToken

Cancellation token to cancel the operation.

Returns

Task<InvitationDto>

An InvitationDto containing the created invitation details including the generated code and full invitation link.

GetInvitationsAsync(int, int, CancellationToken)

Retrieves a paginated list of all invitation codes in the system.

Task<(List<InvitationDto> Invitations, int TotalCount)> GetInvitationsAsync(int page, int pageSize, CancellationToken cancellationToken = default)

Parameters

page int

The page number (1-based) to retrieve.

pageSize int

The number of invitations per page.

cancellationToken CancellationToken

Cancellation token to cancel the operation.

Returns

Task<(List<InvitationDto> Invitations, int TotalCount)>

A tuple containing the list of invitations and the total count of all invitations.

GetUserProfileAsync(Guid, CancellationToken)

Retrieves the complete profile information for a user, including profile photo with presigned URL.

Task<ProfileDto> GetUserProfileAsync(Guid userId, CancellationToken cancellationToken = default)

Parameters

userId Guid

The unique identifier of the user whose profile should be retrieved.

cancellationToken CancellationToken

Cancellation token to cancel the operation.

Returns

Task<ProfileDto>

A ProfileDto containing all profile information.

Exceptions

Exception

Thrown when the user is not found, user email is missing, or profile is not found.

GetUserProjectsAsync(Guid, CancellationToken)

Retrieves all projects associated with a user, including projects they own and projects they are members of.

Task<List<ProjectDto>> GetUserProjectsAsync(Guid userId, CancellationToken cancellationToken = default)

Parameters

userId Guid

The unique identifier of the user whose projects should be retrieved.

cancellationToken CancellationToken

Cancellation token to cancel the operation.

Returns

Task<List<ProjectDto>>

A list of ProjectDto objects representing all projects for the user.

GetUsersAsync(int, int, string?, string?, string?, CancellationToken)

Retrieves a paginated list of users with optional filtering by search term, status, and role.

Task<(List<UserListDto> Users, int TotalCount)> GetUsersAsync(int page, int pageSize, string? search = null, string? status = null, string? role = null, CancellationToken cancellationToken = default)

Parameters

page int

The page number (1-based) to retrieve.

pageSize int

The number of users per page.

search string

Optional search term to filter users by email or name.

status string

Optional status filter (e.g., "Active", "Blocked"). Must match UserStatus enum values.

role string

Optional role filter (e.g., "User", "Admin"). Must match UserRole enum values.

cancellationToken CancellationToken

Cancellation token to cancel the operation.

Returns

Task<(List<UserListDto> Users, int TotalCount)>

A tuple containing the list of users and the total count matching the filters.

SendAdminUpdatesAsync(List<UserRole>, string, CancellationToken)

Sends admin update emails to all active users with the specified roles using the SendGrid AdminUpdates template.

Task<AdminUpdateSendResult> SendAdminUpdatesAsync(List<UserRole> roles, string htmlContent, CancellationToken cancellationToken = default)

Parameters

roles List<UserRole>

List of user roles to target. At least one role must be specified.

htmlContent string

Raw HTML content for the email body. Must not be empty or whitespace.

cancellationToken CancellationToken

Cancellation token to cancel the operation.

Returns

Task<AdminUpdateSendResult>

An AdminUpdateSendResult containing detailed statistics about the email sending operation.

Remarks

This method automatically excludes users with email addresses containing "demo.builvero.local". Emails are sent in batches of 100 recipients with a maximum of 10 concurrent sends to avoid rate limiting. Individual failures are collected without aborting the entire operation.

The email subject is defined in the SendGrid template and cannot be overridden. The HTML content is sent as-is to the template's content_html dynamic field.

Exceptions

ArgumentException

Thrown when roles list is null/empty or htmlContent is null/empty/whitespace.

SendInvitationEmailsAsync(Guid, List<string>, string, Guid, string?, CancellationToken)

Sends invitation emails to multiple recipients for a specific invitation code.

Task<SendInvitationResponse> SendInvitationEmailsAsync(Guid invitationId, List<string> emails, string baseUrl, Guid senderUserId, string? supportEmail = null, CancellationToken cancellationToken = default)

Parameters

invitationId Guid

The unique identifier of the invitation to send.

emails List<string>

List of email addresses to send invitations to.

baseUrl string

The base URL of the frontend application, used to construct invitation links.

senderUserId Guid

The unique identifier of the admin user sending the invitations.

supportEmail string

Optional support email address to include in invitation emails.

cancellationToken CancellationToken

Cancellation token to cancel the operation.

Returns

Task<SendInvitationResponse>

A SendInvitationResponse containing per-email results (sent and failed).

Exceptions

Exception

Thrown when the invitation is not found.

UnblockUserAsync(Guid, CancellationToken)

Unblocks a user account, restoring their access to the platform.

Task UnblockUserAsync(Guid userId, CancellationToken cancellationToken = default)

Parameters

userId Guid

The unique identifier of the user to unblock.

cancellationToken CancellationToken

Cancellation token to cancel the operation.

Returns

Task

Defines the contract for administrative operations including user management, invitation management, and bulk email communications.

Exceptions

Exception

Thrown when the user is not found.

UpdateInvitationAsync(Guid, UpdateInvitationRequest, CancellationToken)

Updates an existing invitation code's properties (max uses, expiration date, label).

Task<InvitationDto> UpdateInvitationAsync(Guid invitationId, UpdateInvitationRequest request, CancellationToken cancellationToken = default)

Parameters

invitationId Guid

The unique identifier of the invitation to update.

request UpdateInvitationRequest

The update request containing the fields to modify. Only provided fields are updated.

cancellationToken CancellationToken

Cancellation token to cancel the operation.

Returns

Task<InvitationDto>

An InvitationDto representing the updated invitation.

Exceptions

Exception

Thrown when the invitation is not found or max uses is set to less than the current usage count.

UpdateUserAsync(Guid, UpdateUserRequest, CancellationToken)

Updates user account information including email, password, role, and status.

Task<UserListDto> UpdateUserAsync(Guid userId, UpdateUserRequest request, CancellationToken cancellationToken = default)

Parameters

userId Guid

The unique identifier of the user to update.

request UpdateUserRequest

The update request containing the fields to modify. Only provided fields are updated.

cancellationToken CancellationToken

Cancellation token to cancel the operation.

Returns

Task<UserListDto>

A UserListDto representing the updated user information.

Exceptions

Exception

Thrown when the user is not found, email is already in use by another user, or invalid role/status values are provided.