namespace Extrudex.API.Hubs;

/// <summary>
/// Strongly-typed client interface for the SignalR PrinterHub.
/// Defines the methods that the server can invoke on connected clients
/// to push real-time printer status updates.
/// </summary>
public interface IPrinterClient
{
    /// <summary>
    /// Pushes a full printer status update to all clients subscribed
    /// to a specific printer's group. Fired whenever a printer's
    /// operational status changes (e.g., Idle → Printing, Offline → Idle).
    /// </summary>
    /// <param name="printerId">The unique identifier of the printer that changed.</param>
    /// <param name="status">The new status value (e.g., "Idle", "Printing", "Offline", "Error", "Paused").</param>
    /// <param name="lastSeenAt">Timestamp (UTC) of when this status was last observed.</param>
    /// <returns>A Task that completes when the client has processed the update.</returns>
    Task PrinterStatusChanged(Guid printerId, string status, DateTime? lastSeenAt);

    /// <summary>
    /// Pushes a lightweight heartbeat to confirm that a printer is still
    /// reachable and its connection is alive. Useful for dashboards that
    /// display online/offline indicators without requiring a full status payload.
    /// </summary>
    /// <param name="printerId">The unique identifier of the printer.</param>
    /// <param name="isActive">Whether the printer is currently active and available for jobs.</param>
    /// <param name="lastSeenAt">Timestamp (UTC) of the last telemetry received from the printer.</param>
    /// <returns>A Task that completes when the client has processed the heartbeat.</returns>
    Task PrinterHeartbeat(Guid printerId, bool isActive, DateTime? lastSeenAt);
}