using Extrudex.Domain.Entities;
using Extrudex.Domain.Enums;

namespace Extrudex.Domain.Interfaces;

/// <summary>
/// Service for recording filament usage entries. Writes to the usage_logs table
/// and provides query capabilities for usage history.
/// </summary>
public interface IUsageLogService
{
    /// <summary>
    /// Records a filament usage entry.
    /// </summary>
    /// <param name="spoolId">The spool that provided the filament.</param>
    /// <param name="gramsUsed">Grams of filament consumed.</param>
    /// <param name="dataSource">Where the data came from.</param>
    /// <param name="printerId">Optional printer ID.</param>
    /// <param name="printJobId">Optional print job ID.</param>
    /// <param name="mmExtruded">Optional mm extruded.</param>
    /// <param name="usageTimestamp">When the usage occurred (defaults to UTC now).</param>
    /// <param name="notes">Optional notes.</param>
    /// <returns>The created UsageLog entity.</returns>
    Task<UsageLog> RecordUsageAsync(
        Guid spoolId,
        decimal gramsUsed,
        DataSource dataSource,
        Guid? printerId = null,
        Guid? printJobId = null,
        decimal? mmExtruded = null,
        DateTime? usageTimestamp = null,
        string? notes = null);

    /// <summary>
    /// Retrieves usage logs for a specific spool, ordered by usage timestamp descending.
    /// </summary>
    /// <param name="spoolId">The spool ID to filter by.</param>
    /// <param name="cancellationToken">Cancellation token.</param>
    /// <returns>A collection of usage logs for the spool.</returns>
    Task<IEnumerable<UsageLog>> GetBySpoolAsync(Guid spoolId, CancellationToken cancellationToken = default);

    /// <summary>
    /// Retrieves usage logs for a specific printer, ordered by usage timestamp descending.
    /// </summary>
    /// <param name="printerId">The printer ID to filter by.</param>
    /// <param name="cancellationToken">Cancellation token.</param>
    /// <returns>A collection of usage logs for the printer.</returns>
    Task<IEnumerable<UsageLog>> GetByPrinterAsync(Guid printerId, CancellationToken cancellationToken = default);

    /// <summary>
    /// Retrieves usage logs for a specific print job, ordered by usage timestamp descending.
    /// </summary>
    /// <param name="printJobId">The print job ID to filter by.</param>
    /// <param name="cancellationToken">Cancellation token.</param>
    /// <returns>A collection of usage logs for the print job.</returns>
    Task<IEnumerable<UsageLog>> GetByPrintJobAsync(Guid printJobId, CancellationToken cancellationToken = default);
}