Add Tiers, Playlist, ranked seasons parsing, leaderboards, docs links

.yardopts

@@ -0,0 +1 @@
+--markup markdown

lib/rls/api.rb

@@ -3,17 +3,20 @@
 require 'rest-client'
 require 'json'
 require 'rls/objects/platform'
-require 'rls/objects/player'
 require 'rls/objects/season'
 require 'rls/objects/search_results'
+require 'rls/objects/tier'
+require 'rls/objects/playlist'
+require 'rls/objects/player'
 
 module RLS
   # Mixin binding to RocketLeagueStats' REST API
   module API
     # The base URL of the RocketLeagueStats API
     APIBASE = 'https://api.rocketleaguestats.com/v1/'
 
-    # Retrieve a single player
+    # Retrieve a single player.
+    # [API docs for this method](http://documentation.rocketleaguestats.com/#single-player)
     # @param id [String, Integer] The unique identifier:
     #   Steam 64 ID / PSN Username / Xbox GamerTag or XUID
     # @param platform [Platform, Integer] The platform to use
@@ -34,7 +37,8 @@ def player(id, platform = Platform::Steam)
       Player.new(response)
     end
 
-    # Retrieves a batch of up to 10 players at a time from different platforms
+    # Retrieves a batch of up to 10 players at a time from different platforms.
+    # [API docs for this method](http://documentation.rocketleaguestats.com/#batch-players)
     # @example Retrieve a batch of players from different platforms
     #   client.players(
     #     76561198033338223, 1,
@@ -62,6 +66,7 @@ def players(*request_data)
 
     # Searches RLS's database for players matching a given display name.
     # The response is paginated.
+    # [API docs for this method](http://documentation.rocketleaguestats.com/#search-players)
     # @example Retrieve the results, one page at a time
     #   results = client.search('player')
     #   results.players #=> first page
@@ -88,7 +93,8 @@ def search(display_name, page = 0)
       SearchResults.new(self, response, display_name)
     end
 
-    # Retrieve the different platforms unless they've already been cached
+    # Retrieve the different platforms unless they've already been cached.
+    # [API docs for this method](http://documentation.rocketleaguestats.com/#platforms)
     # @param renew [true, false] Ignore the cache and make a new request
     # @return [Array<Platform>] An array of platform objects
     def platforms(renew = false)
@@ -105,7 +111,8 @@ def platforms(renew = false)
       end
     end
 
-    # Retrieve season information
+    # Retrieve season information.
+    # [API docs for this method](http://documentation.rocketleaguestats.com/#seasons)
     # @param renew [true, false] Ignore the cache and make a new request
     # @return [Hash<Integer => Season] The seasons by ID
     def seasons(renew = false)
@@ -122,6 +129,80 @@ def seasons(renew = false)
       end
     end
 
+    # Retrieve the current season's tiers.
+    # [API docs for this method](http://documentation.rocketleaguestats.com/#tiers)
+    # @param renew [true, false] Ignore the cache and make a new request
+    # @return [Hash<Integer => Tier] The tiers by ID
+    def tiers(renew = false)
+      if renew || !@tiers
+        response =
+          request(
+            :get,
+            'data/tiers'
+          )
+        @tiers =
+          response.map { |data| [data['tierId'], Tier.new(data)] }.to_h
+      else
+        @tiers
+      end
+    end
+
+    # Retrieve the current playlists.
+    # [API docs for this method](http://documentation.rocketleaguestats.com/#playlists)
+    # @param renew [true, false] Ignore the cache and make a new request
+    # @return [Hash<Integer => Playlist] The playlist by ID
+    def playlists(renew = false)
+      if renew || !@playlists
+        response =
+          request(
+            :get,
+            'data/playlists'
+          )
+        @playlists =
+          response.map { |data| [data['id'], Playlist.new(data)] }.to_h
+      else
+        @playlists
+      end
+    end
+
+    # Returns the top 100 players for the current season on a particular playlist.
+    # [API docs for this method](http://documentation.rocketleaguestats.com/#ranked-leaderboard)
+    # @param playlist_id [Integer]
+    # @return [Array<Player>]
+    def ranked_leaderboard(playlist_id)
+      raise ArgumentError, 'Invalid playlist_id' unless playlists.keys.include?(playlist_id)
+      response =
+        request(
+          :get,
+          'leaderboard/ranked',
+          params: {
+            playlist_id: playlist_id
+          }
+        )
+      response.map { |e| Player.new(e) }
+    end
+
+    # Valid stat types for the leaderboard/stat endpoint
+    VALID_STAT_TYPE = %i[wins goals mvps saves shots assists].freeze
+
+    # Returns the top 100 players for the current season by a particular stat.
+    # [API docs for this method](http://documentation.rocketleaguestats.com/#stat-leaderboard)
+    # @param type [Symbol, String]
+    # @return [Array<Player>]
+    # @raise [ArgumentError] if an unsupported type is specified
+    def stat_leaderboard(type)
+      raise ArgumentError, "Stat type must be one of: #{VALID_STAT_TYPE}" unless VALID_STAT_TYPE.include?(type)
+      response =
+        request(
+          :get,
+          'leaderboard/stat',
+          params: {
+            type: type
+          }
+        )
+      response.map { |e| Player.new(e) }
+    end
+
     # @param type [String, Symbol] HTTP verb
     # @param endpoint [String, Symbol] The API endpoint
     # @param attributes [Array<Hash>] Header and query parameters

lib/rls/client.rb

@@ -21,6 +21,20 @@ def season(id)
       seasons[id]
     end
 
+    # Returns a single tier by ID
+    # @param id [Integer]
+    # @return [Tier]
+    def tier(id)
+      tiers[id]
+    end
+
+    # Returns a single playlist by ID
+    # @param id [Integer]
+    # @return [Playlist]
+    def playlist(id)
+      playlists[id]
+    end
+
     # @return [Season] the current season
     def current_season
       seasons.values.find(&:current?)

lib/rls/objects/player.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require 'rls/objects/stats'
+require 'rls/objects/ranked_history'
 
 module RLS
   # A Rocket League player, as tracked by RLS
@@ -38,6 +39,9 @@ class Player
     # @return [Time]
     attr_reader :next_update
 
+    # @return [Hash<Integer, RankedHistory>] ranked history by season
+    attr_reader :ranked_seasons
+
     def initialize(data)
       @id             = data['uniqueId']
       @display_name   = data['displayName']
@@ -51,6 +55,15 @@ def initialize(data)
       @created_at     = RLS::Utils.time(data['createdAt'])
       @updated_at     = RLS::Utils.time(data['updatedAt'])
       @next_update    = RLS::Utils.time(data['nextUpdateAt'])
+
+      ranked_seaons_data = data['rankedSeasons']
+
+      @ranked_seasons = {}
+      ranked_seaons_data.each do |season_id, ranked_data|
+        @ranked_seasons[season_id.to_i] = ranked_data.map do |k, v|
+          RankedHistory.new(k.to_i, v)
+        end
+      end
     end
   end
 end

lib/rls/objects/playlist.rb

@@ -0,0 +1,25 @@
+# frozen-string-literal: true
+
+module RLS
+  # A Rocket League playlist, and participation statistics
+  class Playlist
+    # @return [Integer]
+    attr_reader :id
+
+    # @return [String]
+    attr_reader :name
+
+    # @return [Integer]
+    attr_reader :population
+
+    # @return [Time]
+    attr_reader :updated_at
+
+    def initialize(data)
+      @id = data['id']
+      @name = data['name']
+      @population = data['population']['players']
+      @updated_at = Utils.time(data['population']['updatedAt'])
+    end
+  end
+end

lib/rls/objects/ranked_history.rb

@@ -0,0 +1,29 @@
+# frozen-string-literal: true
+
+module RLS
+  # An entry in a player's ranked history
+  class RankedHistory
+    # @return [Integer]
+    attr_reader :playlist_id
+
+    # @return [Integer]
+    attr_reader :rank_points
+
+    # @return [Integer, nil]
+    attr_reader :matches_played
+
+    # @return [Integer, nil]
+    attr_reader :tier_id
+
+    # @return [Integer, nil]
+    attr_reader :division
+
+    def initialize(playlist_id, data)
+      @playlist_id = playlist_id
+      @rank_points = data['rankPoints']
+      @matches_played = data['matchesPlayed']
+      @tier_id = data['tier']
+      @division = data['division']
+    end
+  end
+end

lib/rls/objects/tier.rb

@@ -0,0 +1,17 @@
+# frozen-string-literal: true
+
+module RLS
+  # A ranked tier in Rocket League
+  class Tier
+    # @return [Integer]
+    attr_reader :id
+
+    # @return [String]
+    attr_reader :name
+
+    def initialize(data)
+      @id = data['tierId']
+      @name = data['tierName']
+    end
+  end
+end