using System.Text.Json.Serialization;

namespace DeepDrftModels.Enums;

/// <summary>
/// Completion bucket for a recorded play (Phase 16 §1a / D1). The three buckets are exhaustive and
/// non-overlapping, classified by the high-water playback fraction reached before the session closed:
/// <c>Partial</c> [0, 30%), <c>Sampled</c> [30%, 80%], <c>Complete</c> (80%, 100%]. The headline
/// "Plays" figure is the sum of all three — every started listen that crosses the engagement floor
/// is a play; the buckets are the texture beneath it.
///
/// Serialized as its string name on the wire — the converter on the type makes the
/// client to proxy to API JSON contract string-based regardless of host serializer config.
/// </summary>
[JsonConverter(typeof(JsonStringEnumConverter<PlayBucket>))]
public enum PlayBucket
{
    /// <summary>Reached &lt; 30% of duration — a skip or a brief partial listen (still past the floor).</summary>
    Partial,

    /// <summary>Reached 30%–80% of duration — a real listen that was neither a skip nor a finish.</summary>
    Sampled,

    /// <summary>Reached &gt; 80% of duration — effectively a finished listen.</summary>
    Complete
}