namespace SVSim.EmulatedEntrypoint.Services;

public interface ICardAcquisitionService
{
    /// <summary>
    /// Grant cards + associated cosmetics in one transaction.
    ///
    /// • <paramref name="newCardIds"/> non-null  → increments OwnedCardEntry for each via
    ///   the existing IPackRepository.GrantCardsToViewer primitive, then grants any
    ///   cosmetics associated with those cards that the viewer doesn't yet own.
    /// • <paramref name="newCardIds"/> null      → backfill mode: skips card mutation,
    ///   scans viewer.Cards, grants missing cosmetics.
    ///
    /// Returns wire-shape RewardList in both modes. Backfill callers typically discard.
    /// All ownership writes happen in a single SaveChangesAsync.
    /// </summary>
    Task<CardGrantResult> GrantAsync(long viewerId, IEnumerable<long>? newCardIds = null);
}