CUB-33: integrate Moonraker filament usage polling

backend/Domain/Interfaces/IFilamentUsageService.cs

@@ -0,0 +1,50 @@
+using Extrudex.Domain.Entities;
+
+namespace Extrudex.Domain.Interfaces;
+
+/// <summary>
+/// Service for persisting and querying filament usage records.
+/// Tracks consumption per print job and per spool for COGS and inventory tracking.
+/// </summary>
+public interface IFilamentUsageService
+{
+    /// <summary>
+    /// Records a new filament usage entry for a print job.
+    /// </summary>
+    /// <param name="printJobId">The print job that consumed the filament.</param>
+    /// <param name="spoolId">The spool that provided the filament.</param>
+    /// <param name="printerId">The printer that executed the print.</param>
+    /// <param name="gramsUsed">Grams of filament consumed.</param>
+    /// <param name="mmExtruded">Millimeters of filament extruded.</param>
+    /// <param name="notes">Optional notes about this usage record.</param>
+    /// <param name="cancellationToken">Cancellation token.</param>
+    /// <returns>The created FilamentUsage entity.</returns>
+    Task<FilamentUsage> RecordUsageAsync(
+        Guid printJobId,
+        Guid spoolId,
+        Guid printerId,
+        decimal gramsUsed,
+        decimal mmExtruded,
+        string? notes = null,
+        CancellationToken cancellationToken = default);
+
+    /// <summary>
+    /// Retrieves all filament usage records for a specific print job.
+    /// </summary>
+    /// <param name="printJobId">The print job ID.</param>
+    /// <param name="cancellationToken">Cancellation token.</param>
+    /// <returns>Collection of filament usage records for the print job.</returns>
+    Task<IReadOnlyList<FilamentUsage>> GetByPrintJobAsync(
+        Guid printJobId,
+        CancellationToken cancellationToken = default);
+
+    /// <summary>
+    /// Retrieves all filament usage records for a specific spool.
+    /// </summary>
+    /// <param name="spoolId">The spool ID.</param>
+    /// <param name="cancellationToken">Cancellation token.</param>
+    /// <returns>Collection of filament usage records for the spool.</returns>
+    Task<IReadOnlyList<FilamentUsage>> GetBySpoolAsync(
+        Guid spoolId,
+        CancellationToken cancellationToken = default);
+}

backend/Domain/Interfaces/IMoonrakerClient.cs

@@ -0,0 +1,76 @@
+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.
+/// </summary>
+public interface IMoonrakerClient
+{
+    /// <summary>
+    /// Retrieves the current printer status from Moonraker.
+    /// </summary>
+    /// <param name="hostnameOrIp">Printer hostname or IP address.</param>
+    /// <param name="port">Moonraker 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(
+        string hostnameOrIp,
+        int port,
+        string? apiKey = null,
+        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.
+    /// </summary>
+    /// <param name="hostnameOrIp">Printer hostname or IP address.</param>
+    /// <param name="port">Moonraker 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(
+        string hostnameOrIp,
+        int port,
+        string? apiKey = null,
+        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.
+    /// </summary>
+    public string? GcodeFileName { get; set; }
+
+    /// <summary>
+    /// Current print state from Moonraker (e.g., "printing", "complete", "error").
+    /// </summary>
+    public string PrintState { get; set; } = string.Empty;
+
+    /// <summary>
+    /// Total print time in seconds, if available from Moonraker.
+    /// </summary>
+    public double? PrintDurationSeconds { get; set; }
+
+    /// <summary>
+    /// Timestamp (UTC) when the print job was started, if available.
+    /// </summary>
+    public DateTime? StartedAt { get; set; }
+
+    /// <summary>
+    /// Timestamp (UTC) when the print job completed, if available.
+    /// </summary>
+    public DateTime? CompletedAt { get; set; }
+}