namespace Extrudex.Domain.Interfaces;

/// <summary>
/// Client interface for communicating with Moonraker REST API endpoints
/// on Klipper-based printers (e.g., Elegoo Centauri Carbon).
/// Used to retrieve filament usage data, print job status, and
/// remaining spool weight from the printer.
/// </summary>
public interface IMoonrakerClient
{
    /// <summary>
    /// Fetches the current filament usage data from the Moonraker server.
    /// Returns a dictionary of usage metrics reported by the printer.
    /// </summary>
    /// <param name="hostnameOrIp">The printer's hostname or IP address.</param>
    /// <param name="port">The Moonraker API port (default: 7125).</param>
    /// <param name="apiKey">Optional API key for authentication.</param>
    /// <param name="cancellationToken">Cancellation token for the HTTP request.</param>
    /// <returns>A dictionary of usage metric names to their decimal values.</returns>
    Task<Dictionary<string, decimal>> GetFilamentUsageAsync(
        string hostnameOrIp,
        int port,
        string? apiKey,
        CancellationToken cancellationToken = default);

    /// <summary>
    /// Checks whether the Moonraker server is reachable and responding.
    /// </summary>
    /// <param name="hostnameOrIp">The printer's hostname or IP address.</param>
    /// <param name="port">The Moonraker API port (default: 7125).</param>
    /// <param name="apiKey">Optional API key for authentication.</param>
    /// <param name="cancellationToken">Cancellation token for the HTTP request.</param>
    /// <returns><c>true</c> if the server responded successfully; otherwise <c>false</c>.</returns>
    Task<bool> IsReachableAsync(
        string hostnameOrIp,
        int port,
        string? apiKey,
        CancellationToken cancellationToken = default);
}