using adas_core.Application.Subscriptions;
using MongoDB.Bson;

namespace adas_core.Application.Services.Interfaces;

public interface ISubscribersService
{
    /// <summary>
    /// Retrieves the list of subscribers.
    /// </summary>
    /// <returns>A list of <see cref="WsSubscriber"/> instances representing the subscribers.</returns>
    /// <!-- aidoc:v1 sig=7e137ae -->
    List<WsSubscriber> GetSubscribers();
    /// <summary>
    /// Retrieves a <see cref="WsSubscriber"/> associated with the specified context connection identifier.
    /// </summary>
    /// <param name="contextConnectionId">The unique identifier of the context connection used to look up the subscriber.</param>
    /// <returns>The <see cref="WsSubscriber"/> matching the given connection identifier, or <c>null</c> if no subscriber is found.</returns>
    /// <!-- aidoc:v1 sig=b24d002 -->
    WsSubscriber? GetById(string contextConnectionId);
    /// <summary>
    /// Retrieves the list of subscribers associated with the specified point of contact (POC) identifier.
    /// </summary>
    /// <param name="pocId">The identifier of the point of contact whose subscribers should be returned.</param>
    /// <returns>A list of <see cref="WsSubscriber"/> instances matching the provided POC identifier.</returns>
    /// <!-- aidoc:v1 sig=aec8331 -->
    List<WsSubscriber> GetByPocId(ObjectId pocId);
    /// <summary>
    /// Removes a connection identified by the specified context connection identifier.
    /// </summary>
    /// <param name="contextConnectionId">The unique identifier of the connection to remove.</param>
    /// <returns>An integer indicating the result of the removal operation.</returns>
    /// <!-- aidoc:v1 sig=26b732e -->
    int RemoveConnectionById(string contextConnectionId);
    /// <summary>
    /// Registers the specified WebSocket subscriber to receive notifications or messages.
    /// </summary>
    /// <param name="subscriber">The <see cref="WsSubscriber"/> instance to be added to the collection of subscribers.</param>
    /// <!-- aidoc:v1 sig=695cf06 -->
    void AddSubscriber(WsSubscriber subscriber);
}