Interface IVolunteerApplicationService

Namespace

Builvero.Application.Interfaces.Services

Assembly

Builvero.Application.dll

Defines the contract for volunteer application operations including creation, retrieval, status updates, and resume management.

public interface IVolunteerApplicationService

Remarks

This interface provides methods for managing volunteer applications throughout their lifecycle. Applications include applicant information, resume upload to S3, and application status tracking. Resume files are stored securely in S3 and managed with presigned URLs for downloads. Application deletion includes S3 cleanup for GDPR compliance.

Methods

CreateApplicationAsync(CreateVolunteerApplicationRequest, Stream, string, string, long, CancellationToken)

Creates a new volunteer application with resume upload to S3.

Task<VolunteerApplicationDto> CreateApplicationAsync(CreateVolunteerApplicationRequest request, Stream resumeStream, string resumeFileName, string resumeContentType, long resumeSizeBytes, CancellationToken cancellationToken = default)

Parameters

request CreateVolunteerApplicationRequest

The application request containing applicant information and role details.

resumeStream Stream

The resume file stream to upload.

resumeFileName string

The original filename of the resume.

resumeContentType string

The MIME content type of the resume file.

resumeSizeBytes long

The size of the resume file in bytes.

cancellationToken CancellationToken

Cancellation token to cancel the operation.

Returns

Task<VolunteerApplicationDto>

The created volunteer application DTO.

Exceptions

Exception

Thrown when email already exists, role not found, role is closed, or resume upload fails.

ArgumentException

Thrown when hours per week value is invalid.

DeleteApplicationAsync(Guid, CancellationToken)

Deletes a volunteer application and its associated resume from S3 (GDPR compliance - right to be forgotten).

Task<bool> DeleteApplicationAsync(Guid applicationId, CancellationToken cancellationToken = default)

Parameters

applicationId Guid

The unique identifier of the application to delete.

cancellationToken CancellationToken

Cancellation token to cancel the operation.

Returns

Task<bool>

True if the application was successfully deleted; otherwise, false.

EmailExistsAsync(string, CancellationToken)

Checks if an email address already exists in the volunteer applications database.

Task<bool> EmailExistsAsync(string email, CancellationToken cancellationToken = default)

Parameters

email string

The email address to check.

cancellationToken CancellationToken

Cancellation token to cancel the operation.

Returns

Task<bool>

True if an application with the email address exists; otherwise, false.

GetApplicationByIdAsync(Guid, CancellationToken)

Retrieves a specific volunteer application by ID.

Task<VolunteerApplicationDto?> GetApplicationByIdAsync(Guid id, CancellationToken cancellationToken = default)

Parameters

id Guid

The unique identifier of the application to retrieve.

cancellationToken CancellationToken

Cancellation token to cancel the operation.

Returns

Task<VolunteerApplicationDto>

The application DTO if found; otherwise, null.

GetApplicationsAsync(int, int, Guid?, string?, CancellationToken)

Retrieves a paginated list of volunteer applications with optional filtering by role and status.

Task<(List<VolunteerApplicationDto> Applications, int TotalCount)> GetApplicationsAsync(int page, int pageSize, Guid? roleId = null, string? status = null, CancellationToken cancellationToken = default)

Parameters

page int

The page number (1-based) to retrieve.

pageSize int

The number of applications per page.

roleId Guid?

Optional role ID filter to retrieve applications for a specific role.

status string

Optional status filter (e.g., "New", "Reviewed", "Accepted"). Must match ApplicationStatus enum values (case-insensitive).

cancellationToken CancellationToken

Cancellation token to cancel the operation.

Returns

Task<(List<VolunteerApplicationDto> Applications, int TotalCount)>

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

GetResumeDownloadUrlAsync(Guid, CancellationToken)

Generates a presigned URL for downloading a volunteer application's resume from S3.

Task<string> GetResumeDownloadUrlAsync(Guid applicationId, CancellationToken cancellationToken = default)

Parameters

applicationId Guid

The unique identifier of the application whose resume should be downloaded.

cancellationToken CancellationToken

Cancellation token to cancel the operation.

Returns

Task<string>

A presigned URL valid for 5 minutes that can be used to download the resume.

Exceptions

Exception

Thrown when the application is not found or the resume S3 key is missing.

UpdateApplicationStatusAsync(Guid, ApplicationStatus, CancellationToken)

Updates the status of a volunteer application.

Task<VolunteerApplicationDto> UpdateApplicationStatusAsync(Guid applicationId, ApplicationStatus status, CancellationToken cancellationToken = default)

Parameters

applicationId Guid

The unique identifier of the application to update.

status ApplicationStatus

The new status to set. Must be one of: New, Reviewed, or Accepted.

cancellationToken CancellationToken

Cancellation token to cancel the operation.

Returns

Task<VolunteerApplicationDto>

The updated application DTO.

Exceptions

Exception

Thrown when the application is not found.

ArgumentException

Thrown when the status is Rejected (use discard/delete instead).