feature: Leaderboards and statistic rotations

schema.graphqls

@@ -240,10 +240,22 @@
 "Statistic-related data."
 type Statistics {
     "Returns the raw value stored for this statistic."
     value(
         statisticKey: String!
         @spectaql(options: [{ key: "example", value: "games_played" }])
     ): StatisticValueResult
+    @deprecated(reason: "This value is not backed by a rotation and will be removed. Use `rotationValue` instead.")
+
+    """
+    Returns the value stored for the given statistic in a rotation.
+
+    The returned number will be `null` if the statistic does not track in the provided rotation, or if the statistic doesn't exist.
+    """
+    rotationValue(
+        statisticKey: String!
+        @spectaql(options: [{ key: "example", value: "games_played" }]),
+        rotation: Rotation! = LIFETIME,
+    ): Int
 }
 
 "A statistic."
@@ -254,6 +266,41 @@
 
     "If this statistic generates leaderboards."
     forLeaderboard: Boolean!
+
+    """
+    The rotations for which this statistic is tracked.
+
+    These are the rotations that can be used to generate leaderboards or fetch rotation values.
+    Note that the `YEARLY` rotation never generates leaderboards, even if it is returned in this list.
+    """
+    rotations: [Rotation!]!
+
+    """
+    Returns the leaderboard for this statistic in a given rotation.
+
+    If this statistic does not generate leaderboards, or the statistic is not tracked for the provided rotation, this will return `null`.
+    """
+    leaderboard(
+        rotation: Rotation! = LIFETIME,
+        amount: Int! = 10,
+    ): [LeaderboardEntry!]
+}
+
+"An entry in a leaderboard."
+type LeaderboardEntry {
+    """
+    The player who has this entry.
+
+    This will be `null` if the player does not have the statistics enabled for the API.
+    However, for Crown Level or Trophy count leaderboards, the player will not be `null`.
+    """
+    player: Player
+
+    "The rank for this entry."
+    rank: Int!
+
+    "The value for this entry."
+    value: Int!
 }
 
 "The result of fetching a value of a statistic."
@@ -265,6 +312,28 @@
     value: Int!
 }
 
+"""
+A rotation period.
+
+Each period resets at 10AM UTC.
+"""
+enum Rotation {
+    "A daily rotation that resets."
+    DAILY
+
+    "A weekly rotation that resets on Tuesdays."
+    WEEKLY
+
+    "A monthly rotation that resets on the first day of every month."
+    MONTHLY
+
+    "A yearly rotation that resets on the first day of every year."
+    YEARLY
+
+    "A lifetime rotation; a rotation period used to indicate something never rotates."
+    LIFETIME
+}
+
 "Available queries."
 type Query {
     "Given a UUID, returns a Player if they have logged in to MCC Island."
@@ -283,6 +352,26 @@
 
     "Returns a list of all known statistics."
     statistics: [Statistic!]!
+
+    "Returns a statistic by it's name."
+    statistic(
+        key: String!
+        @spectaql(options: [{ key: "example", value: "games_played" }])
+    ): Statistic
+
+    """
+    Returns when this rotation will next rotate.
+
+    If the rotation is due the exact time this method is called, this method will return the next time that it will rotate.
+    """
+    nextRotation(rotation: Rotation!): DateTime!
+
+    """
+    Returns when this rotation last rotated.
+
+    If the rotation is due the exact time this method is called, this method will return the current time.
+    """
+    previousRotation(rotation: Rotation!): DateTime!
 }
 
 "Internal directive used to generate some documentation elements."