QuantEngineByItz/src/dotnet/QuantEngine.Core/Interfaces/ITokenCache.cs

namespace QuantEngine.Core.Interfaces;

/// <summary>
/// Token caching for KIS API authentication.
/// Replaces Python's sqlite3-based token storage with PostgreSQL.
/// </summary>
public interface ITokenCache
{
    /// <summary>
    /// Retrieve cached access token if valid and not near expiration.
    /// </summary>
    /// <param name="account">Account type: "real" or "mock"</param>
    /// <returns>Access token if cached and valid; null if expired or missing</returns>
    Task<string?> GetCachedTokenAsync(string account);

    /// <summary>
    /// Store access token with expiration time.
    /// </summary>
    /// <param name="account">Account type: "real" or "mock"</param>
    /// <param name="token">Access token</param>
    /// <param name="expiresAt">Token expiration time (UTC)</param>
    Task SaveTokenAsync(string account, string token, DateTime expiresAt);

    /// <summary>
    /// Clear expired tokens and stale entries.
    /// </summary>
    Task ClearExpiredTokensAsync();
}