Merge remote-tracking branch 'origin/dev' into agent/dex/CUB-33-moonraker-usage-polling

# Conflicts:
#	backend/Domain/Interfaces/IMoonrakerClient.cs
#	backend/Infrastructure/Services/MoonrakerClient.cs

backend/Domain/Interfaces/IMoonrakerClient.cs

@@ -1,76 +1,131 @@
+using Extrudex.Domain.DTOs.Moonraker;
+
 namespace Extrudex.Domain.Interfaces;
 
 /// <summary>
-/// Client for communicating with Moonraker REST API on Klipper-based printers
-/// (e.g., Elegoo Centauri Carbon). Retrieves print job metadata including
-/// filament usage data.
+/// Client interface for communicating with Moonraker REST API endpoints
+/// on Klipper-based printers (e.g., Elegoo Centauri Carbon).
+/// Provides strongly-typed methods for server discovery, printer status,
+/// print job history, and real-time telemetry.
 /// </summary>
 public interface IMoonrakerClient
 {
     /// <summary>
-    /// Retrieves the current printer status from Moonraker.
+    /// Checks whether the Moonraker server is reachable and responding.
+    /// Calls the /server/info endpoint and returns the server information
+    /// if successful, or null if the server is unreachable.
     /// </summary>
-    /// <param name="hostnameOrIp">Printer hostname or IP address.</param>
-    /// <param name="port">Moonraker port (default: 7125).</param>
+    /// <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.</param>
-    /// <returns>The printer status string (e.g., "idle", "printing", "paused", "error").</returns>
-    Task<string> GetPrinterStatusAsync(
+    /// <param name="cancellationToken">Cancellation token for the HTTP request.</param>
+    /// <returns>Server info if reachable; <c>null</c> if unreachable.</returns>
+    Task<MoonrakerServerInfo?> GetServerInfoAsync(
         string hostnameOrIp,
         int port,
-        string? apiKey = null,
+        string? apiKey,
         CancellationToken cancellationToken = default);
 
     /// <summary>
-    /// Retrieves filament usage data from the current or most recent print job.
-    /// Moonraker exposes this via the /api/objects endpoint querying
-    /// "history" and "print_stats" objects.
+    /// Checks whether the Moonraker server is reachable and responding.
+    /// This is a convenience method equivalent to calling GetServerInfoAsync
+    /// and checking for a non-null result.
     /// </summary>
-    /// <param name="hostnameOrIp">Printer hostname or IP address.</param>
-    /// <param name="port">Moonraker port (default: 7125).</param>
+    /// <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.</param>
-    /// <returns> Filament usage data from Moonraker, or null if unavailable.</returns>
-    Task<MoonrakerFilamentUsage?> GetFilamentUsageAsync(
+    /// <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 = null,
+        string? apiKey,
         CancellationToken cancellationToken = default);
-}
-
-/// <summary>
-/// Represents filament usage data retrieved from a Moonraker-equipped printer.
-/// Maps to Moonraker's print_stats and history objects.
-/// </summary>
-public class MoonrakerFilamentUsage
-{
-    /// <summary>
-    /// Millimeters of filament extruded during the print job.
-    /// </summary>
-    public decimal MmExtruded { get; set; }
 
     /// <summary>
-    /// The filename of the G-code file being or recently printed.
+    /// Fetches the current printer info from the /printer/info endpoint.
+    /// Returns the Klipper state and readiness status.
     /// </summary>
-    public string? GcodeFileName { get; set; }
+    /// <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>Printer info if successful; <c>null</c> if the request failed.</returns>
+    Task<MoonrakerPrinterInfo?> GetPrinterInfoAsync(
+        string hostnameOrIp,
+        int port,
+        string? apiKey,
+        CancellationToken cancellationToken = default);
 
     /// <summary>
-    /// Current print state from Moonraker (e.g., "printing", "complete", "error").
+    /// Fetches print job history from the /server/history/items endpoint.
+    /// Returns the most recent print jobs with filament usage data,
+    /// print duration, and completion status.
     /// </summary>
-    public string PrintState { get; set; } = string.Empty;
+    /// <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="limit">Maximum number of history items to return. Default: 50.</param>
+    /// <param name="cancellationToken">Cancellation token for the HTTP request.</param>
+    /// <returns>History response with print jobs; empty list if request failed.</returns>
+    Task<MoonrakerHistoryResponse> GetPrintHistoryAsync(
+        string hostnameOrIp,
+        int port,
+        string? apiKey,
+        int limit = 50,
+        CancellationToken cancellationToken = default);
 
     /// <summary>
-    /// Total print time in seconds, if available from Moonraker.
+    /// Fetches the current print statistics from the /printer/objects/query endpoint.
+    /// Returns real-time data including filament used, print duration,
+    /// and current print state for the active or most recent print.
     /// </summary>
-    public double? PrintDurationSeconds { get; set; }
+    /// <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>Print stats if successful; <c>null</c> if the request failed.</returns>
+    Task<MoonrakerPrintStats?> GetPrintStatsAsync(
+        string hostnameOrIp,
+        int port,
+        string? apiKey,
+        CancellationToken cancellationToken = default);
 
     /// <summary>
-    /// Timestamp (UTC) when the print job was started, if available.
+    /// Fetches the current display status from the /printer/objects/query endpoint.
+    /// Returns progress percentage and status message for the active print.
+    /// Used by SignalR to push real-time progress updates to connected clients.
     /// </summary>
-    public DateTime? StartedAt { get; set; }
+    /// <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>Display status if successful; <c>null</c> if the request failed.</returns>
+    Task<MoonrakerDisplayStatus?> GetDisplayStatusAsync(
+        string hostnameOrIp,
+        int port,
+        string? apiKey,
+        CancellationToken cancellationToken = default);
 
     /// <summary>
-    /// Timestamp (UTC) when the print job completed, if available.
+    /// Fetches the current filament usage data from the Moonraker server.
+    /// Returns a dictionary of usage metrics reported by the printer.
+    /// 
+    /// <para>
+    /// <b>Prefer GetPrintHistoryAsync or GetPrintStatsAsync for new code.</b>
+    /// This method is retained for backward compatibility with the
+    /// FilamentUsageSyncService and returns a dictionary of metric names
+    /// to their decimal values for callers that don't need typed DTOs.
+    /// </para>
     /// </summary>
-    public DateTime? CompletedAt { get; set; }
+    /// <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);
 }