Interface IForumService

Namespace

Builvero.Application.Interfaces.Services

Assembly

Builvero.Application.dll

Defines the contract for forum operations including topics, messages, subscriptions, and moderation.

public interface IForumService

Remarks

This interface provides methods for:

• Topic and message creation and retrieval with access control
• Subscription management for email notifications
• Soft deletion for moderation (admins/moderators only)
• Admin operations for viewing all projects and topics

Access control: Regular users must be active project members. Admins, moderators, and team members have elevated access.

Methods

AddMessageAsync(Guid, Guid, string, CancellationToken)

Adds a new message to an existing forum topic.

Task<ProjectForumMessageDto> AddMessageAsync(Guid topicId, Guid currentUserId, string body, CancellationToken ct)

Parameters

topicId Guid

The unique identifier of the topic to add the message to.

currentUserId Guid

The unique identifier of the user posting the message.

body string

The body content of the message.

ct CancellationToken

Cancellation token to cancel the operation.

Returns

Task<ProjectForumMessageDto>

A ProjectForumMessageDto representing the created message.

CreateTopicAsync(Guid, Guid, string, string, CancellationToken)

Creates a new forum topic in a project with an initial message.

Task<ProjectForumTopicDto> CreateTopicAsync(Guid projectId, Guid currentUserId, string title, string body, CancellationToken ct)

Parameters

projectId Guid

The unique identifier of the project where the topic should be created.

currentUserId Guid

The unique identifier of the user creating the topic.

title string

The title of the forum topic. Must be unique within the project.

body string

The body content of the initial message in the topic.

ct CancellationToken

Cancellation token to cancel the operation.

Returns

Task<ProjectForumTopicDto>

A ProjectForumTopicDto representing the created topic.

GetAllProjectsForAdminAsync(CancellationToken)

Retrieves a summary list of all projects for admin/moderation purposes.

Task<IReadOnlyList<ProjectSummaryDto>> GetAllProjectsForAdminAsync(CancellationToken ct)

Parameters

ct CancellationToken

Cancellation token to cancel the operation.

Returns

Task<IReadOnlyList<ProjectSummaryDto>>

A read-only list of project summaries.

Remarks

This method is intended for admin/moderation UI to browse all projects and their forums. Requires admin/moderator/team member privileges.

GetAllTopicsForProjectAsAdminAsync(Guid, CancellationToken)

Retrieves all forum topics for a project, including deleted topics, for admin/moderation purposes.

Task<IReadOnlyList<ProjectForumTopicDto>> GetAllTopicsForProjectAsAdminAsync(Guid projectId, CancellationToken ct)

Parameters

projectId Guid

The unique identifier of the project.

ct CancellationToken

Cancellation token to cancel the operation.

Returns

Task<IReadOnlyList<ProjectForumTopicDto>>

A read-only list of all forum topics, including deleted ones.

Remarks

This method is intended for admin/moderation UI to view all topics, including soft-deleted ones. Requires admin/moderator/team member privileges.

GetSubscriptionStateAsync(Guid, Guid, Guid, CancellationToken)

Retrieves the current subscription state for a user regarding a project and topic.

Task<ForumSubscriptionStateDto> GetSubscriptionStateAsync(Guid projectId, Guid topicId, Guid userId, CancellationToken ct)

Parameters

projectId Guid

The unique identifier of the project.

topicId Guid

The unique identifier of the forum topic.

userId Guid

The unique identifier of the user.

ct CancellationToken

Cancellation token to cancel the operation.

Returns

Task<ForumSubscriptionStateDto>

A ForumSubscriptionStateDto containing global and topic-level subscription status.

GetTopicWithMessagesAsync(Guid, Guid, bool, CancellationToken)

Retrieves a forum topic with all its messages.

Task<ProjectForumTopicDto> GetTopicWithMessagesAsync(Guid topicId, Guid currentUserId, bool includeDeletedForAdmins, CancellationToken ct)

Parameters

topicId Guid

The unique identifier of the topic to retrieve.

currentUserId Guid

The unique identifier of the user requesting the topic.

includeDeletedForAdmins bool

Whether to include soft-deleted messages (only effective for admins/moderators/team members).

ct CancellationToken

Cancellation token to cancel the operation.

Returns

Task<ProjectForumTopicDto>

A ProjectForumTopicDto containing the topic and all its messages.

GetTopicsAsync(Guid, Guid, bool, CancellationToken)

Retrieves all forum topics for a project, with access control based on user role and project membership.

Task<IReadOnlyList<ProjectForumTopicDto>> GetTopicsAsync(Guid projectId, Guid currentUserId, bool includeDeletedForAdmins, CancellationToken ct)

Parameters

projectId Guid

The unique identifier of the project whose topics should be retrieved.

currentUserId Guid

The unique identifier of the user requesting the topics.

includeDeletedForAdmins bool

Whether to include soft-deleted topics (only effective for admins/moderators/team members).

ct CancellationToken

Cancellation token to cancel the operation.

Returns

Task<IReadOnlyList<ProjectForumTopicDto>>

A read-only list of forum topics for the project.

SetGlobalSubscriptionAsync(Guid, Guid, bool, CancellationToken)

Sets the global forum notification preference for a user in a project.

Task SetGlobalSubscriptionAsync(Guid projectId, Guid userId, bool receiveAll, CancellationToken ct)

Parameters

projectId Guid

The unique identifier of the project.

userId Guid

The unique identifier of the user.

receiveAll bool

Whether the user should receive all forum notifications for this project.

ct CancellationToken

Cancellation token to cancel the operation.

Returns

Task

Defines the contract for forum operations including topics, messages, subscriptions, and moderation.

Remarks

When receiveAll is false, the user will not receive any forum notifications for the project, regardless of individual topic subscriptions.

SetTopicSubscriptionAsync(Guid, Guid, bool, CancellationToken)

Sets the subscription status for a user to a specific forum topic.

Task SetTopicSubscriptionAsync(Guid topicId, Guid userId, bool isSubscribed, CancellationToken ct)

Parameters

topicId Guid

The unique identifier of the forum topic.

userId Guid

The unique identifier of the user.

isSubscribed bool

Whether the user should be subscribed to receive notifications for this topic.

ct CancellationToken

Cancellation token to cancel the operation.

Returns

Task

Defines the contract for forum operations including topics, messages, subscriptions, and moderation.

Remarks

Topic-level subscriptions only take effect if the user's global subscription for the project allows notifications.

SoftDeleteMessageAsync(Guid, Guid, bool, CancellationToken)

Soft-deletes a forum message, hiding it from normal view while preserving it in the database.

Task SoftDeleteMessageAsync(Guid messageId, Guid performedByUserId, bool asAdminOrModerator, CancellationToken ct)

Parameters

messageId Guid

The unique identifier of the message to delete.

performedByUserId Guid

The unique identifier of the user performing the deletion (must be admin/moderator or message creator).

asAdminOrModerator bool

Whether the deletion is being performed with admin/moderator privileges.

ct CancellationToken

Cancellation token to cancel the operation.

Returns

Task

Defines the contract for forum operations including topics, messages, subscriptions, and moderation.

Remarks

Admins, moderators, and team members can delete any message. Regular users can only delete their own messages.

Exceptions

UnauthorizedAccessException

Thrown when the user does not have permission to delete the message.

SoftDeleteTopicAsync(Guid, Guid, bool, CancellationToken)

Soft-deletes a forum topic, hiding it from normal view while preserving it in the database.

Task SoftDeleteTopicAsync(Guid topicId, Guid performedByUserId, bool asAdminOrModerator, CancellationToken ct)

Parameters

topicId Guid

The unique identifier of the topic to delete.

performedByUserId Guid

The unique identifier of the user performing the deletion (must be admin/moderator).

asAdminOrModerator bool

Whether the deletion is being performed with admin/moderator privileges.

ct CancellationToken

Cancellation token to cancel the operation.

Returns

Task

Defines the contract for forum operations including topics, messages, subscriptions, and moderation.

Remarks

Only admins, moderators, and team members can soft-delete topics. The topic and all its messages are marked as deleted.

Exceptions

UnauthorizedAccessException

Thrown when the user does not have permission to delete topics.