using DeepDrftModels.Enums;
using NetBlocks.Models;

namespace DeepDrftData;

/// <summary>
/// SQL-side anonymous telemetry service (Phase 16). Records play and share events to the append-only
/// logs and maintains the incremental play-counter rollup. The release dimension on a play is resolved
/// server-side from the track key (§2.3 / D4) — callers pass only what the client cheaply knows.
/// Returns NetBlocks <see cref="Result"/> at the boundary; the controller maps that to 202/4xx/5xx.
/// </summary>
public interface IEventService
{
    /// <summary>
    /// Record one play: append a <c>play_event</c> row (release resolved from the track key) and bump
    /// the track's <c>play_counter</c> in the same transaction. A play of an unknown/removed track key
    /// still logs (with a null release and no counter bump) rather than failing.
    /// </summary>
    Task<Result> RecordPlay(string trackEntryKey, PlayBucket bucket, string? anonId = null, CancellationToken cancellationToken = default);

    /// <summary>Record one share: append a <c>share_event</c> row. Target and channel come straight from the client.</summary>
    Task<Result> RecordShare(ShareTargetType targetType, string targetKey, ShareChannel channel, string? anonId = null, CancellationToken cancellationToken = default);

    /// <summary>
    /// Site-wide distinct-listener count (Phase 16 §3, D3 — all-time): distinct non-null <c>anon_id</c>
    /// values across all play events. Null tokens are excluded (not a known listener). The capability for
    /// wave 16.5's "N listeners" card; nothing surfaces it via API or UI in wave 16.3.
    /// </summary>
    Task<ResultContainer<int>> GetDistinctListenerCount(CancellationToken cancellationToken = default);

    /// <summary>Distinct listeners who played the given track (by vault entry key). Null tokens excluded.</summary>
    Task<ResultContainer<int>> GetDistinctListenerCountForTrack(string trackEntryKey, CancellationToken cancellationToken = default);

    /// <summary>
    /// Distinct listeners across the release's tracks (derived, D4) — a listener who played any track in
    /// the release counts once. Null tokens excluded.
    /// </summary>
    Task<ResultContainer<int>> GetDistinctListenerCountForRelease(long releaseId, CancellationToken cancellationToken = default);
}