using EnvelopeGenerator.Application.Common.Dto;

namespace EnvelopeGenerator.Application.Common.Interfaces.Services;

/// <summary>
/// Manages per-user UI preferences (theme, dark mode, grid layouts).
/// Preferences are stored in the distributed cache (dbo.TBDD_CACHE) as JSON.
/// Cache key schema: "signflow.user-preferences:{username}"
/// </summary>
public interface IUserPreferencesService
{
    /// <summary>
    /// Retrieves preferences for the given user.
    /// Always returns a valid object — never throws, never returns null.
    /// Returns defaults if no entry exists in cache.
    /// </summary>
    /// <param name="id"></param>
    /// <param name="ct">Cancellation token.</param>
    Task<UserPreferencesDto> GetOrCreateAsync(string id, CancellationToken ct = default);

    /// <summary>
    /// Persists the given preferences for the user in the distributed cache.
    /// Failures are non-fatal and silently ignored.
    /// </summary>
    /// <param name="id"></param>
    /// <param name="preferences">The preferences to persist.</param>
    /// <param name="ct">Cancellation token.</param>
    Task SaveAsync(string id, UserPreferencesDto preferences, CancellationToken ct = default);
}