namespace NexusReader.Application.Abstractions.Messaging;

/// <summary>
/// Abstraction for broadcasting real-time sync events to connected clients.
/// Defined in Application to prevent a direct dependency on SignalR in Application layer handlers.
/// </summary>
public interface ISyncBroadcaster
{
    /// <summary>
    /// Broadcasts a reading progress update to all devices belonging to the specified user,
    /// optionally excluding the originating connection.
    /// </summary>
    /// <param name="userId">The user whose other devices should be notified.</param>
    /// <param name="pageId">The block/page ID the user has reached.</param>
    /// <param name="timestamp">The server-side UTC timestamp of the update.</param>
    /// <param name="excludedConnectionId">SignalR connection ID to exclude (the sender's device).</param>
    /// <param name="cancellationToken">Cancellation token.</param>
    Task BroadcastProgressAsync(
        string userId,
        string pageId,
        DateTime timestamp,
        string? excludedConnectionId,
        CancellationToken cancellationToken = default);

    /// <summary>
    /// Broadcasts real-time ingestion status updates to a specific user.
    /// This is used by background workers to provide feedback during AI-intensive processing.
    /// </summary>
    /// <param name="userId">The ID of the user who owns the ingestion request.</param>
    /// <param name="message">A human-readable status message (e.g., "Parsing chapters...").</param>
    /// <param name="progress">Progress percentage (0.0 to 1.0).</param>
    /// <param name="cancellationToken">Cancellation token.</param>
    Task BroadcastIngestionProgressAsync(
        string userId,
        string message,
        double progress,
        CancellationToken cancellationToken = default);
}