nba 0.1.1 → 0.2.0

data/lib/nba/all_time_leader.rb

@@ -0,0 +1,77 @@
+require "equalizer"
+require "shale"
+
+module NBA
+  # Represents an all-time statistical leader
+  class AllTimeLeader < Shale::Mapper
+    include Equalizer.new(:player_id, :category)
+
+    # @!attribute [rw] player_id
+    #   Returns the player ID
+    #   @api public
+    #   @example
+    #     leader.player_id #=> 2544
+    #   @return [Integer] the player ID
+    attribute :player_id, Shale::Type::Integer
+
+    # @!attribute [rw] player_name
+    #   Returns the player name
+    #   @api public
+    #   @example
+    #     leader.player_name #=> "LeBron James"
+    #   @return [String] the player name
+    attribute :player_name, Shale::Type::String
+
+    # @!attribute [rw] category
+    #   Returns the statistical category
+    #   @api public
+    #   @example
+    #     leader.category #=> "PTS"
+    #   @return [String] the category
+    attribute :category, Shale::Type::String
+
+    # @!attribute [rw] value
+    #   Returns the stat value
+    #   @api public
+    #   @example
+    #     leader.value #=> 40474
+    #   @return [Float] the value
+    attribute :value, Shale::Type::Float
+
+    # @!attribute [rw] rank
+    #   Returns the ranking position
+    #   @api public
+    #   @example
+    #     leader.rank #=> 1
+    #   @return [Integer] the rank
+    attribute :rank, Shale::Type::Integer
+
+    # @!attribute [rw] is_active
+    #   Returns whether the player is active
+    #   @api public
+    #   @example
+    #     leader.is_active #=> true
+    #   @return [Boolean] whether active
+    attribute :is_active, Shale::Type::Boolean
+
+    # Returns the player object
+    #
+    # @api public
+    # @example
+    #   leader.player #=> #<NBA::Player>
+    # @return [Player, nil] the player object
+    def player
+      Players.find(player_id)
+    end
+
+    # Returns whether the player is active
+    #
+    # @api public
+    # @example
+    #   leader.active? #=> true
+    # @return [Boolean] true if active
+    def active?
+      is_active
+    end
+  end
+end

data/lib/nba/all_time_leaders.rb

@@ -0,0 +1,185 @@
+require "json"
+require_relative "client"
+require_relative "collection"
+require_relative "all_time_leader"
+
+module NBA
+  # Provides methods to retrieve all-time NBA statistical leaders
+  module AllTimeLeaders
+    # Points category
+    # @return [String] the category code
+    PTS = "PTS".freeze
+    # Rebounds category
+    # @return [String] the category code
+    REB = "REB".freeze
+    # Assists category
+    # @return [String] the category code
+    AST = "AST".freeze
+    # Steals category
+    # @return [String] the category code
+    STL = "STL".freeze
+    # Blocks category
+    # @return [String] the category code
+    BLK = "BLK".freeze
+    # Field goals made category
+    # @return [String] the category code
+    FGM = "FGM".freeze
+    # Field goals attempted category
+    # @return [String] the category code
+    FGA = "FGA".freeze
+    # Three pointers made category
+    # @return [String] the category code
+    FG3M = "FG3M".freeze
+    # Three pointers attempted category
+    # @return [String] the category code
+    FG3A = "FG3A".freeze
+    # Free throws made category
+    # @return [String] the category code
+    FTM = "FTM".freeze
+    # Free throws attempted category
+    # @return [String] the category code
+    FTA = "FTA".freeze
+    # Games played category
+    # @return [String] the category code
+    GP = "GP".freeze
+    # Turnovers category
+    # @return [String] the category code
+    TOV = "TOV".freeze
+    # Personal fouls category
+    # @return [String] the category code
+    PF = "PF".freeze
+    # Offensive rebounds category
+    # @return [String] the category code
+    OREB = "OREB".freeze
+    # Defensive rebounds category
+    # @return [String] the category code
+    DREB = "DREB".freeze
+
+    # Regular season type
+    # @return [String] the season type
+    REGULAR_SEASON = "Regular Season".freeze
+    # Playoffs season type
+    # @return [String] the season type
+    PLAYOFFS = "Playoffs".freeze
+
+    # Totals per mode
+    # @return [String] the per mode
+    TOTALS = "Totals".freeze
+    # Per game per mode
+    # @return [String] the per mode
+    PER_GAME = "PerGame".freeze
+
+    # Category to result set mapping
+    CATEGORY_RESULT_SETS = {
+      PTS => "PTSLeaders", REB => "REBLeaders", AST => "ASTLeaders",
+      STL => "STLLeaders", BLK => "BLKLeaders", FGM => "FGMLeaders",
+      FGA => "FGALeaders", FG3M => "FG3MLeaders", FG3A => "FG3ALeaders",
+      FTM => "FTMLeaders", FTA => "FTALeaders", GP => "GPLeaders",
+      TOV => "TOVLeaders", PF => "PFLeaders", OREB => "OREBLeaders",
+      DREB => "DREBLeaders"
+    }.freeze
+    private_constant :CATEGORY_RESULT_SETS
+
+    # Retrieves all-time leaders for a statistical category
+    #
+    # @api public
+    # @example
+    #   leaders = NBA::AllTimeLeaders.find(category: NBA::AllTimeLeaders::PTS)
+    #   leaders.each { |l| puts "#{l.rank}. #{l.player_name}: #{l.value.to_i}" }
+    # @param category [String] the statistical category (PTS, REB, AST, etc.)
+    # @param season_type [String] the season type (Regular Season, Playoffs)
+    # @param per_mode [String] the per mode (Totals, PerGame)
+    # @param limit [Integer] number of results to return (default 10)
+    # @param client [Client] the API client to use
+    # @return [Collection] a collection of all-time leaders
+    def self.find(category:, season_type: REGULAR_SEASON, per_mode: TOTALS, limit: 10, client: CLIENT)
+      path = build_path(season_type, per_mode, limit)
+      response = client.get(path)
+      parse_response(response, category, limit)
+    end
+
+    # Builds the API path
+    # @api private
+    # @param season_type [String] the season type
+    # @param per_mode [String] the per mode
+    # @param limit [Integer] the limit
+    # @return [String] the path
+    def self.build_path(season_type, per_mode, limit)
+      "alltimeleadersgrids?LeagueID=00&PerMode=#{per_mode}&SeasonType=#{season_type}&TopX=#{limit}"
+    end
+    private_class_method :build_path
+
+    # Parses the API response
+    # @api private
+    # @param response [String, nil] the JSON response
+    # @param category [String] the category
+    # @param limit [Integer] the limit
+    # @return [Collection] collection of leaders
+    def self.parse_response(response, category, limit)
+      return Collection.new unless response
+
+      data = JSON.parse(response)
+      result_set = find_result_set(data, CATEGORY_RESULT_SETS[category])
+      return Collection.new unless result_set
+
+      build_leaders(result_set, category, limit)
+    end
+    private_class_method :parse_response
+
+    # Finds a result set by name
+    # @api private
+    # @param data [Hash] the parsed JSON
+    # @param name [String] the result set name
+    # @return [Hash, nil] the result set
+    def self.find_result_set(data, name)
+      result_sets = data["resultSets"]
+      return unless result_sets
+
+      result_sets.find { |rs| rs.fetch("name").eql?(name) }
+    end
+    private_class_method :find_result_set
+
+    # Builds leaders collection from result set
+    # @api private
+    # @param result_set [Hash] the result set
+    # @param category [String] the category
+    # @param limit [Integer] the limit
+    # @return [Collection] collection of leaders
+    def self.build_leaders(result_set, category, limit)
+      headers = result_set["headers"]
+      rows = result_set["rowSet"]
+      return Collection.new unless headers && rows
+
+      leaders = rows.take(limit).map.with_index(1) do |row, rank|
+        build_leader(headers, row, category, rank)
+      end
+      Collection.new(leaders)
+    end
+    private_class_method :build_leaders
+
+    # Builds a single leader
+    # @api private
+    # @param headers [Array<String>] the headers
+    # @param row [Array] the row data
+    # @param category [String] the category
+    # @param rank [Integer] the rank
+    # @return [AllTimeLeader] the leader
+    def self.build_leader(headers, row, category, rank)
+      data = headers.zip(row).to_h
+      AllTimeLeader.new(**leader_attributes(data, category, rank))
+    end
+    private_class_method :build_leader
+
+    # Extracts leader attributes from data
+    # @api private
+    # @param data [Hash] the raw data
+    # @param category [String] the category
+    # @param rank [Integer] the rank
+    # @return [Hash] the attributes
+    def self.leader_attributes(data, category, rank)
+      {player_id: data.fetch("PLAYER_ID"), player_name: data.fetch("PLAYER_NAME"), category: category,
+       value: data.fetch(category), rank: rank, is_active: data.fetch("IS_ACTIVE_FLAG").eql?("Y")}
+    end
+    private_class_method :leader_attributes
+  end
+end

data/lib/nba/assist_leader.rb

@@ -0,0 +1,92 @@
+require "equalizer"
+require "shale"
+require_relative "players"
+require_relative "teams"
+
+module NBA
+  # Represents an assist leader entry
+  class AssistLeader < Shale::Mapper
+    include Equalizer.new(:player_id, :rank)
+
+    # @!attribute [rw] player_id
+    #   Returns the player ID
+    #   @api public
+    #   @example
+    #     leader.player_id #=> 201566
+    #   @return [Integer] the player ID
+    attribute :player_id, Shale::Type::Integer
+
+    # @!attribute [rw] player_name
+    #   Returns the player name
+    #   @api public
+    #   @example
+    #     leader.player_name #=> "Russell Westbrook"
+    #   @return [String] the player name
+    attribute :player_name, Shale::Type::String
+
+    # @!attribute [rw] team_id
+    #   Returns the team ID
+    #   @api public
+    #   @example
+    #     leader.team_id #=> 1610612746
+    #   @return [Integer] the team ID
+    attribute :team_id, Shale::Type::Integer
+
+    # @!attribute [rw] team_abbreviation
+    #   Returns the team abbreviation
+    #   @api public
+    #   @example
+    #     leader.team_abbreviation #=> "LAC"
+    #   @return [String] the team abbreviation
+    attribute :team_abbreviation, Shale::Type::String
+
+    # @!attribute [rw] rank
+    #   Returns the rank in the category
+    #   @api public
+    #   @example
+    #     leader.rank #=> 1
+    #   @return [Integer] the rank
+    attribute :rank, Shale::Type::Integer
+
+    # @!attribute [rw] ast
+    #   Returns the total assists
+    #   @api public
+    #   @example
+    #     leader.ast #=> 654
+    #   @return [Integer] the total assists
+    attribute :ast, Shale::Type::Integer
+
+    # Returns the player object for this leader
+    #
+    # @api public
+    # @example
+    #   leader.player #=> #<NBA::Player>
+    # @return [Player, nil] the hydrated player object
+    def player
+      Players.find(player_id)
+    end
+
+    # Returns the team object for this leader
+    #
+    # @api public
+    # @example
+    #   leader.team #=> #<NBA::Team>
+    # @return [Team, nil] the team object
+    def team
+      Teams.find(team_id)
+    end
+
+    json do
+      map "player_id", to: :player_id
+      map "playerId", to: :player_id
+      map "player_name", to: :player_name
+      map "playerName", to: :player_name
+      map "team_id", to: :team_id
+      map "teamId", to: :team_id
+      map "team_abbreviation", to: :team_abbreviation
+      map "teamAbbreviation", to: :team_abbreviation
+      map "rank", to: :rank
+      map "ast", to: :ast
+    end
+  end
+end

data/lib/nba/assist_leaders.rb

@@ -0,0 +1,64 @@
+require "json"
+require_relative "client"
+require_relative "collection"
+require_relative "assist_leader"
+require_relative "response_parser"
+require_relative "utils"
+
+module NBA
+  # Provides methods to retrieve NBA assist leaders
+  module AssistLeaders
+    # Result set name for assist leaders
+    # @return [String] the result set name
+    RESULT_SET = "AssistLeaders".freeze
+
+    # Retrieves assist leaders for a season
+    #
+    # @api public
+    # @example
+    #   leaders = NBA::AssistLeaders.all(season: 2023)
+    #   leaders.each { |leader| puts "#{leader.rank}. #{leader.player_name}: #{leader.ast}" }
+    # @param season [Integer] the season year (defaults to current season)
+    # @param season_type [String] the season type (Regular Season, Playoffs, etc.)
+    # @param per_mode [String] the per mode (Totals, PerGame)
+    # @param player_or_team [String] player or team stats (Player, Team)
+    # @param league [String, League] the league ID or League object (default NBA)
+    # @param client [Client] the API client to use
+    # @return [Collection] a collection of assist leaders
+    def self.all(season: Utils.current_season, season_type: "Regular Season", per_mode: "Totals",
+      player_or_team: "Player", league: League::NBA, client: CLIENT)
+      league_id = Utils.extract_league_id(league)
+      path = build_path(season, season_type, per_mode, player_or_team, league_id)
+      ResponseParser.parse(client.get(path), result_set: RESULT_SET) { |data| build_leader(data) }
+    end
+
+    # Builds the API request path
+    # @api private
+    # @return [String] the request path
+    def self.build_path(season, season_type, per_mode, player_or_team, league_id)
+      "assistleaders?LeagueID=#{league_id}&PerMode=#{per_mode}&PlayerOrTeam=#{player_or_team}" \
+        "&Season=#{Utils.format_season(season)}&SeasonType=#{season_type}"
+    end
+    private_class_method :build_path
+
+    # Builds an AssistLeader object from raw data
+    # @api private
+    # @param data [Hash] the row data
+    # @return [AssistLeader] the leader object
+    def self.build_leader(data)
+      AssistLeader.new(**leader_attributes(data))
+    end
+    private_class_method :build_leader
+
+    # Extracts leader attributes from data
+    # @api private
+    # @param data [Hash] the row data
+    # @return [Hash] leader attributes
+    def self.leader_attributes(data)
+      {player_id: data["PLAYER_ID"], player_name: data["PLAYER_NAME"],
+       team_id: data["TEAM_ID"], team_abbreviation: data["TEAM_ABBREVIATION"],
+       rank: data["RANK"], ast: data["AST"]}
+    end
+    private_class_method :leader_attributes
+  end
+end

data/lib/nba/assist_tracker.rb

@@ -0,0 +1,108 @@
+require "json"
+require_relative "client"
+require_relative "collection"
+require_relative "assist_tracker_entry"
+require_relative "response_parser"
+require_relative "utils"
+
+module NBA
+  # Provides methods to retrieve NBA assist tracker data (who passes to who)
+  module AssistTracker
+    # Result set name for assist tracker
+    # @return [String] the result set name
+    RESULT_SET = "AssistTracker".freeze
+
+    # Retrieves assist tracker data for a season
+    #
+    # @api public
+    # @example
+    #   entries = NBA::AssistTracker.all(season: 2023)
+    #   entries.each { |e| puts "#{e.player_name} -> #{e.pass_to}: #{e.ast} assists" }
+    # @param season [Integer] the season year (defaults to current season)
+    # @param season_type [String] the season type (Regular Season, Playoffs, etc.)
+    # @param per_mode [String] the per mode (Totals, PerGame)
+    # @param league [String, League] the league ID or League object (default NBA)
+    # @param client [Client] the API client to use
+    # @return [Collection] a collection of assist tracker entries
+    def self.all(season: Utils.current_season, season_type: "Regular Season", per_mode: "Totals",
+      league: League::NBA, client: CLIENT)
+      league_id = Utils.extract_league_id(league)
+      path = build_path(season, season_type, per_mode, league_id)
+      ResponseParser.parse(client.get(path), result_set: RESULT_SET) { |data| build_entry(data) }
+    end
+
+    # Builds the API request path
+    # @api private
+    # @return [String] the request path
+    def self.build_path(season, season_type, per_mode, league_id)
+      "assisttracker?LeagueID=#{league_id}&PerMode=#{per_mode}" \
+        "&Season=#{Utils.format_season(season)}&SeasonType=#{season_type}"
+    end
+    private_class_method :build_path
+
+    # Builds an AssistTrackerEntry object from raw data
+    # @api private
+    # @param data [Hash] the row data
+    # @return [AssistTrackerEntry] the entry object
+    def self.build_entry(data)
+      AssistTrackerEntry.new(**player_attrs(data), **pass_attrs(data), **shooting_attrs(data))
+    end
+    private_class_method :build_entry
+
+    # Extracts player attributes from data
+    # @api private
+    # @param data [Hash] the row data
+    # @return [Hash] player attributes
+    def self.player_attrs(data)
+      {player_id: data["PLAYER_ID"], player_name: data["PLAYER_NAME"],
+       team_id: data["TEAM_ID"], team_abbreviation: data["TEAM_ABBREVIATION"]}
+    end
+    private_class_method :player_attrs
+
+    # Extracts pass attributes from data
+    # @api private
+    # @param data [Hash] the row data
+    # @return [Hash] pass attributes
+    def self.pass_attrs(data)
+      {pass_to: data["PASS_TO"], pass_to_player_id: data["PASS_TO_PLAYER_ID"],
+       frequency: data["FREQUENCY"], pass: data["PASS"], ast: data["AST"]}
+    end
+    private_class_method :pass_attrs
+
+    # Extracts shooting attributes from data
+    # @api private
+    # @param data [Hash] the row data
+    # @return [Hash] shooting attributes
+    def self.shooting_attrs(data)
+      fg_attrs(data).merge(fg2_attrs(data)).merge(fg3_attrs(data))
+    end
+    private_class_method :shooting_attrs
+
+    # Extracts field goal attributes from data
+    # @api private
+    # @param data [Hash] the row data
+    # @return [Hash] field goal attributes
+    def self.fg_attrs(data)
+      {fg_m: data["FGM"], fg_a: data["FGA"], fg_pct: data["FG_PCT"]}
+    end
+    private_class_method :fg_attrs
+
+    # Extracts 2-point field goal attributes from data
+    # @api private
+    # @param data [Hash] the row data
+    # @return [Hash] 2-point field goal attributes
+    def self.fg2_attrs(data)
+      {fg2m: data["FG2M"], fg2a: data["FG2A"], fg2_pct: data["FG2_PCT"]}
+    end
+    private_class_method :fg2_attrs
+
+    # Extracts 3-point field goal attributes from data
+    # @api private
+    # @param data [Hash] the row data
+    # @return [Hash] 3-point field goal attributes
+    def self.fg3_attrs(data)
+      {fg3m: data["FG3M"], fg3a: data["FG3A"], fg3_pct: data["FG3_PCT"]}
+    end
+    private_class_method :fg3_attrs
+  end
+end