using Books.Api.EventFlow.ReadModels;

namespace Books.Api.AiBookkeeper;

/// <summary>
/// Matches documents to pending bank transactions based on amount.
/// </summary>
public interface IBankTransactionMatcher
{
    /// <summary>
    /// Find the oldest pending bank transaction matching the given amount.
    /// For expenses (negative amounts), matches transactions where the bank amount is negative.
    /// For income (positive amounts), matches transactions where the bank amount is positive.
    /// </summary>
    /// <param name="companyId">Company ID</param>
    /// <param name="amount">Document amount (positive for income, negative for expense)</param>
    /// <param name="tolerance">Amount tolerance (default ±0.01)</param>
    /// <param name="cancellationToken">Cancellation token</param>
    /// <returns>Matching bank transaction, or null if not found</returns>
    Task<BankTransactionDto?> FindMatchingTransactionAsync(
        string companyId,
        decimal amount,
        decimal tolerance = 0.01m,
        CancellationToken cancellationToken = default);
}