namespace SVSim.EmulatedEntrypoint.Services;

public interface ICardAcquisitionService
{
    /// <summary>
    /// Grant N cards + their CardCosmeticReward cascades in a single transaction.
    /// Used by /pack/open and any future endpoint that grants new cards in bulk.
    /// Returns wire-shape reward_list entries (post-state counts for cards, single-grant
    /// entries for any newly-added cosmetics).
    /// </summary>
    Task<CardGrantResult> GrantManyAsync(long viewerId, IEnumerable<long> newCardIds);

    /// <summary>
    /// Scan all owned cards for missing CardCosmeticReward cosmetics; grant any not yet owned.
    /// Used by /load/index for retroactive cosmetic reconciliation. Card counts are NOT mutated.
    /// </summary>
    Task<CardGrantResult> BackfillCosmeticsAsync(long viewerId);
}