using adas_core.Domain.Models;
using adas_core.Domain.Models.MongoModels;
using MongoDB.Bson;

namespace adas_core.Application.Services.Interfaces;

public interface INoticeService
{
    /// <summary>
    /// Asynchronously deletes the specified notice.
    /// </summary>
    /// <param name="notice">The notice to delete.</param>
    /// <returns>A task that represents the asynchronous delete operation.</returns>
    Task DeleteNoticeAsync(Notice notice);
    /// <summary>
    /// Asynchronously deletes a notice identified by the specified identifier.
    /// </summary>
    /// <param name="noticeId">The unique identifier of the notice to delete.</param>
    Task DeleteNoticeByIdAsync(ObjectId noticeId);
    /// <summary>
    /// Asynchronously retrieves a <see cref="Notice"/> entity by its unique identifier from the data store.
    /// Returns <see langword="null"/> when no notice matches the provided identifier.
    /// </summary>
    /// <param name="noticeId">The <see cref="ObjectId"/> that uniquely identifies the notice to retrieve.</param>
    /// <returns>A <see cref="Task{T}"/> containing the matching <see cref="Notice"/>, or <see langword="null"/> if no notice is found.</returns>
    Task<Notice?> GetNoticeByIdAsync(ObjectId noticeId);
    /// <summary>
    /// Asynchronously retrieves a collection of notices filtered by the specified notice type.
    /// The task result may be null when no notices match the given type.
    /// </summary>
    /// <param name="noticeType">The type of notice to filter by.</param>
    /// <returns>A task containing an enumerable of matching <see cref="Notice"/> objects, or null if none are found.</returns>
    Task<IEnumerable<Notice>?> GetNoticeByTypeAsync(string noticeType);
    /// <summary>
    /// Asynchronously retrieves a collection of notices.
    /// </summary>
    /// <returns>A task that represents the asynchronous operation. The task result contains an enumerable collection of <see cref="Notice"/> objects.</returns>
    Task<IEnumerable<Notice>> GetNoticesAsync();
    /// <summary>
    /// Inserts a new notice into the data store.
    /// </summary>
    /// <param name="notice">The notice entity to insert.</param>
    /// <returns>A task that represents the asynchronous operation. The task result contains the inserted <see cref="Notice"/>, or <c>null</c> if the notice could not be inserted.</returns>
    Task<Notice?> InsertNotice(Notice notice);
    /// <summary>
    /// Asynchronously updates an existing notice in the system.
    /// </summary>
    /// <param name="notice">The notice entity containing the updated information to be persisted.</param>
    Task UpdateNoticeAsync(Notice notice);
    /// <summary>
    /// Persists the provided API request to the data store.
    /// </summary>
    /// <param name="apiRequest">The API request to be saved.</param>
    Task SaveRequest(ApiRequest apiRequest);
    /// <summary>
    /// Asynchronously persists the specified API request.
    /// </summary>
    /// <param name="apiRequest">The API request to save.</param>
    Task SaveRequestAsync(ApiRequest apiRequest);
    /// <summary>
    /// Asynchronously retrieves the collection of notices associated with the specified display identifier.
    /// </summary>
    /// <param name="displayId">The identifier of the display whose notices should be retrieved.</param>
    /// <returns>A task that returns the notices for the display, or <c>null</c> when no notices are found for the given display.</returns>
    Task<IEnumerable<Notice>?> GetNoticesByDisplayId(ObjectId displayId);
}