OutlookAddin/src/OutlookAddin.Core/Services/IMatchingService.cs

using System.Threading;
using System.Threading.Tasks;
using MarcusLaw.OutlookAddin.Core.Models;

namespace MarcusLaw.OutlookAddin.Core.Services
{
    public interface IMatchingService
    {
        /// <summary>
        /// Looks up the contact/account/recent-cases bundle for a sender
        /// email address. Returns null when there is no unique Contact match
        /// (0 or 2+ candidates). Results are cached for 10 minutes.
        /// </summary>
        Task<MatchResult?> LookupAsync(string senderEmail, CancellationToken cancellationToken = default);

        /// <summary>
        /// Loads the full contact + account + recent-cases bundle for a
        /// specific contact id. Used when the sender's email matches
        /// multiple contacts and the user picks one from the candidate
        /// list — we then drill into that contact's cases without
        /// dropping back to manual search.
        /// </summary>
        Task<MatchResult?> LookupContactAsync(string contactId, string? senderEmail = null, CancellationToken cancellationToken = default);

        void Invalidate(string senderEmail);
    }
}