nba 0.1.1 → 0.2.0

data/lib/nba/league_game_log.rb

@@ -0,0 +1,224 @@
+require "json"
+require_relative "client"
+require_relative "collection"
+require_relative "game_log"
+require_relative "team_game_log"
+require_relative "utils"
+
+module NBA
+  # Provides methods to retrieve league-wide game logs
+  module LeagueGameLog
+    # Season type constant for regular season
+    # @return [String] the season type
+    REGULAR_SEASON = "Regular Season".freeze
+
+    # Season type constant for playoffs
+    # @return [String] the season type
+    PLAYOFFS = "Playoffs".freeze
+
+    # Player or team constant for player logs
+    # @return [String] the player/team type
+    PLAYER = "P".freeze
+
+    # Player or team constant for team logs
+    # @return [String] the player/team type
+    TEAM = "T".freeze
+
+    # Result set name for league game log
+    # @return [String] the result set name
+    LEAGUE_GAME_LOG = "LeagueGameLog".freeze
+
+    # Retrieves league-wide player game logs
+    #
+    # @api public
+    # @example
+    #   logs = NBA::LeagueGameLog.player_logs(season: 2024)
+    #   logs.each { |l| puts "#{l.game_date}: #{l.matchup} - #{l.pts} pts" }
+    # @param season [Integer] the season year
+    # @param season_type [String] the season type (Regular Season or Playoffs)
+    # @param client [Client] the API client to use
+    # @return [Collection] a collection of game logs
+    def self.player_logs(season: Utils.current_season, season_type: REGULAR_SEASON, client: CLIENT)
+      path = build_path(season, season_type, PLAYER)
+      response = client.get(path)
+      parse_response(response)
+    end
+
+    # Retrieves league-wide team game logs
+    #
+    # @api public
+    # @example
+    #   logs = NBA::LeagueGameLog.team_logs(season: 2024)
+    #   logs.each { |l| puts "#{l.game_date}: #{l.matchup} - #{l.pts} pts" }
+    # @param season [Integer] the season year
+    # @param season_type [String] the season type (Regular Season or Playoffs)
+    # @param client [Client] the API client to use
+    # @return [Collection] a collection of game logs
+    def self.team_logs(season: Utils.current_season, season_type: REGULAR_SEASON, client: CLIENT)
+      path = build_path(season, season_type, TEAM)
+      response = client.get(path)
+      parse_team_response(response)
+    end
+
+    # Builds the API path
+    #
+    # @api private
+    # @param season [Integer] the season year
+    # @param season_type [String] the season type
+    # @param player_or_team [String] player or team type
+    # @return [String] the API path
+    def self.build_path(season, season_type, player_or_team)
+      season_str = Utils.format_season(season)
+      encoded_type = season_type
+      "leaguegamelog?LeagueID=00&Season=#{season_str}&SeasonType=#{encoded_type}&PlayerOrTeam=#{player_or_team}"
+    end
+    private_class_method :build_path
+
+    # Parses the API response for player logs
+    #
+    # @api private
+    # @param response [String] the JSON response body
+    # @return [Collection] a collection of game logs
+    def self.parse_response(response)
+      return Collection.new unless response
+
+      data = JSON.parse(response)
+      result_set = find_result_set(data)
+      return Collection.new unless result_set
+
+      headers = result_set["headers"]
+      rows = result_set["rowSet"]
+      return Collection.new unless headers && rows
+
+      logs = rows.map { |row| build_game_log(headers, row) }
+      Collection.new(logs)
+    end
+    private_class_method :parse_response
+
+    # Parses the API response for team logs
+    #
+    # @api private
+    # @param response [String] the JSON response body
+    # @return [Collection] a collection of team game log entries
+    def self.parse_team_response(response)
+      return Collection.new unless response
+
+      data = JSON.parse(response)
+      result_set = find_result_set(data)
+      return Collection.new unless result_set
+
+      headers = result_set["headers"]
+      rows = result_set["rowSet"]
+      return Collection.new unless headers && rows
+
+      logs = rows.map { |row| build_team_game_log(headers, row) }
+      Collection.new(logs)
+    end
+    private_class_method :parse_team_response
+
+    # Finds the result set
+    #
+    # @api private
+    # @param data [Hash] the parsed JSON data
+    # @return [Hash, nil] the result set
+    def self.find_result_set(data)
+      result_sets = data["resultSets"]
+      return unless result_sets
+
+      result_sets.find { |rs| rs["name"].eql?(LEAGUE_GAME_LOG) }
+    end
+    private_class_method :find_result_set
+
+    # Builds a game log from a row
+    #
+    # @api private
+    # @param headers [Array<String>] the column headers
+    # @param row [Array] the row data
+    # @return [GameLog] the game log object
+    def self.build_game_log(headers, row)
+      data = headers.zip(row).to_h
+      GameLog.new(**game_log_attributes(data))
+    end
+    private_class_method :build_game_log
+
+    # Builds a team game log from a row
+    #
+    # @api private
+    # @param headers [Array<String>] the column headers
+    # @param row [Array] the row data
+    # @return [TeamGameLogEntry] the team game log object
+    def self.build_team_game_log(headers, row)
+      data = headers.zip(row).to_h
+      TeamGameLogEntry.new(**team_game_log_attributes(data))
+    end
+    private_class_method :build_team_game_log
+
+    # Extracts game log attributes from row data
+    #
+    # @api private
+    # @param data [Hash] the game log row data
+    # @return [Hash] the game log attributes
+    def self.game_log_attributes(data)
+      game_info_attributes(data).merge(shooting_attributes(data), counting_attributes(data))
+    end
+    private_class_method :game_log_attributes
+
+    # Extracts team game log attributes from row data
+    #
+    # @api private
+    # @param data [Hash] the game log row data
+    # @return [Hash] the game log attributes
+    def self.team_game_log_attributes(data)
+      team_info_attributes(data).merge(shooting_attributes(data), counting_attributes(data))
+    end
+    private_class_method :team_game_log_attributes
+
+    # Extracts game info attributes
+    #
+    # @api private
+    # @param data [Hash] the game log data
+    # @return [Hash] the game info attributes
+    def self.game_info_attributes(data)
+      {season_id: data.fetch("SEASON_ID"), player_id: data.fetch("PLAYER_ID"),
+       game_id: data.fetch("GAME_ID"), game_date: data.fetch("GAME_DATE"),
+       matchup: data.fetch("MATCHUP"), wl: data.fetch("WL"), min: data.fetch("MIN")}
+    end
+    private_class_method :game_info_attributes
+
+    # Extracts team info attributes
+    #
+    # @api private
+    # @param data [Hash] the game log data
+    # @return [Hash] the team info attributes
+    def self.team_info_attributes(data)
+      {team_id: data.fetch("TEAM_ID"), game_id: data.fetch("GAME_ID"),
+       game_date: data.fetch("GAME_DATE"), matchup: data.fetch("MATCHUP"),
+       wl: data.fetch("WL"), min: data.fetch("MIN")}
+    end
+    private_class_method :team_info_attributes
+
+    # Extracts shooting attributes
+    #
+    # @api private
+    # @param data [Hash] the game log data
+    # @return [Hash] the shooting attributes
+    def self.shooting_attributes(data)
+      {fgm: data.fetch("FGM"), fga: data.fetch("FGA"), fg_pct: data.fetch("FG_PCT"),
+       fg3m: data.fetch("FG3M"), fg3a: data.fetch("FG3A"), fg3_pct: data.fetch("FG3_PCT"),
+       ftm: data.fetch("FTM"), fta: data.fetch("FTA"), ft_pct: data.fetch("FT_PCT")}
+    end
+    private_class_method :shooting_attributes
+
+    # Extracts counting stats attributes
+    #
+    # @api private
+    # @param data [Hash] the game log data
+    # @return [Hash] the counting stats attributes
+    def self.counting_attributes(data)
+      {oreb: data.fetch("OREB"), dreb: data.fetch("DREB"), reb: data.fetch("REB"),
+       ast: data.fetch("AST"), stl: data.fetch("STL"), blk: data.fetch("BLK"),
+       tov: data.fetch("TOV"), pf: data.fetch("PF"), pts: data.fetch("PTS"), plus_minus: data.fetch("PLUS_MINUS")}
+    end
+    private_class_method :counting_attributes
+  end
+end

data/lib/nba/league_hustle_stats_player.rb

@@ -0,0 +1,161 @@
+require "json"
+require_relative "client"
+require_relative "collection"
+require_relative "utils"
+
+module NBA
+  # Provides methods to retrieve league-wide player hustle statistics
+  module LeagueHustleStatsPlayer
+    # Result set name for hustle stats
+    # @return [String] the result set name
+    HUSTLE_STATS_PLAYER = "HustleStatsPlayer".freeze
+
+    # Season type constant for regular season
+    # @return [String] the season type
+    REGULAR_SEASON = "Regular Season".freeze
+
+    # Season type constant for playoffs
+    # @return [String] the season type
+    PLAYOFFS = "Playoffs".freeze
+
+    # Per mode constant for per game stats
+    # @return [String] the per mode
+    PER_GAME = "PerGame".freeze
+
+    # Per mode constant for totals
+    # @return [String] the per mode
+    TOTALS = "Totals".freeze
+
+    # Retrieves league-wide player hustle statistics
+    #
+    # @api public
+    # @example
+    #   stats = NBA::LeagueHustleStatsPlayer.all(season: 2024)
+    #   stats.each { |s| puts "#{s.player_name}: #{s.deflections} deflections" }
+    # @param season [Integer] the season year
+    # @param season_type [String] the season type
+    # @param per_mode [String] the per mode
+    # @param client [Client] the API client to use
+    # @return [Collection] a collection of player hustle stats
+    def self.all(season: Utils.current_season, season_type: REGULAR_SEASON, per_mode: PER_GAME, client: CLIENT)
+      path = build_path(season, season_type, per_mode)
+      response = client.get(path)
+      parse_response(response)
+    end
+
+    # Builds the API path
+    #
+    # @api private
+    # @param season [Integer] the season year
+    # @param season_type [String] the season type
+    # @param per_mode [String] the per mode
+    # @return [String] the API path
+    def self.build_path(season, season_type, per_mode)
+      season_str = Utils.format_season(season)
+      "leaguehustlestatsplayer?LeagueID=00&Season=#{season_str}&SeasonType=#{season_type}&PerMode=#{per_mode}"
+    end
+    private_class_method :build_path
+
+    # Parses the API response
+    #
+    # @api private
+    # @param response [String] the JSON response body
+    # @return [Collection] a collection of player hustle stats
+    def self.parse_response(response)
+      return Collection.new unless response
+
+      data = JSON.parse(response)
+      result_set = find_result_set(data)
+      return Collection.new unless result_set
+
+      headers = result_set["headers"]
+      rows = result_set["rowSet"]
+      return Collection.new unless headers && rows
+
+      stats = rows.map { |row| build_player_stat(headers, row) }
+      Collection.new(stats)
+    end
+    private_class_method :parse_response
+
+    # Finds the result set
+    #
+    # @api private
+    # @param data [Hash] the parsed JSON data
+    # @return [Hash, nil] the result set
+    def self.find_result_set(data)
+      result_sets = data["resultSets"]
+      return unless result_sets
+
+      result_sets.find { |rs| rs["name"].eql?(HUSTLE_STATS_PLAYER) }
+    end
+    private_class_method :find_result_set
+
+    # Builds a player stat from a row
+    #
+    # @api private
+    # @param headers [Array<String>] the column headers
+    # @param row [Array] the row data
+    # @return [LeagueHustleStatsPlayerStat] the player stat object
+    def self.build_player_stat(headers, row)
+      data = headers.zip(row).to_h
+      LeagueHustleStatsPlayerStat.new(**player_stat_attributes(data))
+    end
+    private_class_method :build_player_stat
+
+    # Extracts player stat attributes from row data
+    #
+    # @api private
+    # @param data [Hash] the player stat row data
+    # @return [Hash] the player stat attributes
+    def self.player_stat_attributes(data)
+      identity_attributes(data).merge(hustle_attributes(data), box_out_attributes(data))
+    end
+    private_class_method :player_stat_attributes
+
+    # Extracts identity attributes
+    #
+    # @api private
+    # @param data [Hash] the player stat data
+    # @return [Hash] the identity attributes
+    def self.identity_attributes(data)
+      {player_id: data["PLAYER_ID"], player_name: data["PLAYER_NAME"],
+       team_id: data["TEAM_ID"], team_abbreviation: data["TEAM_ABBREVIATION"],
+       age: data["AGE"], g: data["G"], min: data["MIN"]}
+    end
+    private_class_method :identity_attributes
+
+    # Extracts hustle attributes
+    #
+    # @api private
+    # @param data [Hash] the player stat data
+    # @return [Hash] the hustle attributes
+    def self.hustle_attributes(data)
+      {contested_shots: data["CONTESTED_SHOTS"],
+       contested_shots_2pt: data["CONTESTED_SHOTS_2PT"],
+       contested_shots_3pt: data["CONTESTED_SHOTS_3PT"],
+       deflections: data["DEFLECTIONS"], charges_drawn: data["CHARGES_DRAWN"],
+       screen_assists: data["SCREEN_ASSISTS"], screen_ast_pts: data["SCREEN_AST_PTS"],
+       off_loose_balls_recovered: data["OFF_LOOSE_BALLS_RECOVERED"],
+       def_loose_balls_recovered: data["DEF_LOOSE_BALLS_RECOVERED"],
+       loose_balls_recovered: data["LOOSE_BALLS_RECOVERED"],
+       pct_loose_balls_recovered_off: data["PCT_LOOSE_BALLS_RECOVERED_OFF"],
+       pct_loose_balls_recovered_def: data["PCT_LOOSE_BALLS_RECOVERED_DEF"]}
+    end
+    private_class_method :hustle_attributes
+
+    # Extracts box out attributes
+    #
+    # @api private
+    # @param data [Hash] the player stat data
+    # @return [Hash] the box out attributes
+    def self.box_out_attributes(data)
+      {off_boxouts: data["OFF_BOXOUTS"], def_boxouts: data["DEF_BOXOUTS"],
+       box_out_player_team_rebs: data["BOX_OUT_PLAYER_TEAM_REBS"],
+       box_out_player_rebs: data["BOX_OUT_PLAYER_REBS"], box_outs: data["BOX_OUTS"],
+       pct_box_outs_off: data["PCT_BOX_OUTS_OFF"], pct_box_outs_def: data["PCT_BOX_OUTS_DEF"],
+       pct_box_outs_team_reb: data["PCT_BOX_OUTS_TEAM_REB"],
+       pct_box_outs_reb: data["PCT_BOX_OUTS_REB"]}
+    end
+    private_class_method :box_out_attributes
+  end
+end

data/lib/nba/league_hustle_stats_player_stat.rb

@@ -0,0 +1,253 @@
+require "equalizer"
+require "shale"
+
+module NBA
+  # Represents league-wide hustle statistics for a player
+  class LeagueHustleStatsPlayerStat < Shale::Mapper
+    include Equalizer.new(:player_id)
+
+    # @!attribute [rw] player_id
+    #   Returns the player ID
+    #   @api public
+    #   @example
+    #     stat.player_id #=> 201939
+    #   @return [Integer] the player ID
+    attribute :player_id, Shale::Type::Integer
+
+    # @!attribute [rw] player_name
+    #   Returns the player name
+    #   @api public
+    #   @example
+    #     stat.player_name #=> "Stephen Curry"
+    #   @return [String] the player name
+    attribute :player_name, Shale::Type::String
+
+    # @!attribute [rw] team_id
+    #   Returns the team ID
+    #   @api public
+    #   @example
+    #     stat.team_id #=> 1610612744
+    #   @return [Integer] the team ID
+    attribute :team_id, Shale::Type::Integer
+
+    # @!attribute [rw] team_abbreviation
+    #   Returns the team abbreviation
+    #   @api public
+    #   @example
+    #     stat.team_abbreviation #=> "GSW"
+    #   @return [String] the team abbreviation
+    attribute :team_abbreviation, Shale::Type::String
+
+    # @!attribute [rw] age
+    #   Returns the player's age
+    #   @api public
+    #   @example
+    #     stat.age #=> 36
+    #   @return [Integer] the age
+    attribute :age, Shale::Type::Integer
+
+    # @!attribute [rw] g
+    #   Returns games played
+    #   @api public
+    #   @example
+    #     stat.g #=> 72
+    #   @return [Integer] games played
+    attribute :g, Shale::Type::Integer
+
+    # @!attribute [rw] min
+    #   Returns total minutes played
+    #   @api public
+    #   @example
+    #     stat.min #=> 2484.5
+    #   @return [Float] total minutes
+    attribute :min, Shale::Type::Float
+
+    # @!attribute [rw] contested_shots
+    #   Returns contested shots
+    #   @api public
+    #   @example
+    #     stat.contested_shots #=> 156
+    #   @return [Integer] contested shots
+    attribute :contested_shots, Shale::Type::Integer
+
+    # @!attribute [rw] contested_shots_2pt
+    #   Returns contested 2-point shots
+    #   @api public
+    #   @example
+    #     stat.contested_shots_2pt #=> 98
+    #   @return [Integer] contested 2-point shots
+    attribute :contested_shots_2pt, Shale::Type::Integer
+
+    # @!attribute [rw] contested_shots_3pt
+    #   Returns contested 3-point shots
+    #   @api public
+    #   @example
+    #     stat.contested_shots_3pt #=> 58
+    #   @return [Integer] contested 3-point shots
+    attribute :contested_shots_3pt, Shale::Type::Integer
+
+    # @!attribute [rw] deflections
+    #   Returns deflections
+    #   @api public
+    #   @example
+    #     stat.deflections #=> 85
+    #   @return [Integer] deflections
+    attribute :deflections, Shale::Type::Integer
+
+    # @!attribute [rw] charges_drawn
+    #   Returns charges drawn
+    #   @api public
+    #   @example
+    #     stat.charges_drawn #=> 5
+    #   @return [Integer] charges drawn
+    attribute :charges_drawn, Shale::Type::Integer
+
+    # @!attribute [rw] screen_assists
+    #   Returns screen assists
+    #   @api public
+    #   @example
+    #     stat.screen_assists #=> 142
+    #   @return [Integer] screen assists
+    attribute :screen_assists, Shale::Type::Integer
+
+    # @!attribute [rw] screen_ast_pts
+    #   Returns points from screen assists
+    #   @api public
+    #   @example
+    #     stat.screen_ast_pts #=> 284
+    #   @return [Integer] screen assist points
+    attribute :screen_ast_pts, Shale::Type::Integer
+
+    # @!attribute [rw] off_loose_balls_recovered
+    #   Returns offensive loose balls recovered
+    #   @api public
+    #   @example
+    #     stat.off_loose_balls_recovered #=> 25
+    #   @return [Integer] offensive loose balls recovered
+    attribute :off_loose_balls_recovered, Shale::Type::Integer
+
+    # @!attribute [rw] def_loose_balls_recovered
+    #   Returns defensive loose balls recovered
+    #   @api public
+    #   @example
+    #     stat.def_loose_balls_recovered #=> 35
+    #   @return [Integer] defensive loose balls recovered
+    attribute :def_loose_balls_recovered, Shale::Type::Integer
+
+    # @!attribute [rw] loose_balls_recovered
+    #   Returns total loose balls recovered
+    #   @api public
+    #   @example
+    #     stat.loose_balls_recovered #=> 60
+    #   @return [Integer] loose balls recovered
+    attribute :loose_balls_recovered, Shale::Type::Integer
+
+    # @!attribute [rw] pct_loose_balls_recovered_off
+    #   Returns percentage of offensive loose balls recovered
+    #   @api public
+    #   @example
+    #     stat.pct_loose_balls_recovered_off #=> 0.417
+    #   @return [Float] percentage of offensive loose balls recovered
+    attribute :pct_loose_balls_recovered_off, Shale::Type::Float
+
+    # @!attribute [rw] pct_loose_balls_recovered_def
+    #   Returns percentage of defensive loose balls recovered
+    #   @api public
+    #   @example
+    #     stat.pct_loose_balls_recovered_def #=> 0.583
+    #   @return [Float] percentage of defensive loose balls recovered
+    attribute :pct_loose_balls_recovered_def, Shale::Type::Float
+
+    # @!attribute [rw] off_boxouts
+    #   Returns offensive box outs
+    #   @api public
+    #   @example
+    #     stat.off_boxouts #=> 12
+    #   @return [Integer] offensive box outs
+    attribute :off_boxouts, Shale::Type::Integer
+
+    # @!attribute [rw] def_boxouts
+    #   Returns defensive box outs
+    #   @api public
+    #   @example
+    #     stat.def_boxouts #=> 45
+    #   @return [Integer] defensive box outs
+    attribute :def_boxouts, Shale::Type::Integer
+
+    # @!attribute [rw] box_out_player_team_rebs
+    #   Returns team rebounds from player box outs
+    #   @api public
+    #   @example
+    #     stat.box_out_player_team_rebs #=> 38
+    #   @return [Integer] team rebounds from box outs
+    attribute :box_out_player_team_rebs, Shale::Type::Integer
+
+    # @!attribute [rw] box_out_player_rebs
+    #   Returns player rebounds from box outs
+    #   @api public
+    #   @example
+    #     stat.box_out_player_rebs #=> 22
+    #   @return [Integer] player rebounds from box outs
+    attribute :box_out_player_rebs, Shale::Type::Integer
+
+    # @!attribute [rw] box_outs
+    #   Returns total box outs
+    #   @api public
+    #   @example
+    #     stat.box_outs #=> 57
+    #   @return [Integer] total box outs
+    attribute :box_outs, Shale::Type::Integer
+
+    # @!attribute [rw] pct_box_outs_off
+    #   Returns percentage of offensive box outs
+    #   @api public
+    #   @example
+    #     stat.pct_box_outs_off #=> 0.211
+    #   @return [Float] percentage of offensive box outs
+    attribute :pct_box_outs_off, Shale::Type::Float
+
+    # @!attribute [rw] pct_box_outs_def
+    #   Returns percentage of defensive box outs
+    #   @api public
+    #   @example
+    #     stat.pct_box_outs_def #=> 0.789
+    #   @return [Float] percentage of defensive box outs
+    attribute :pct_box_outs_def, Shale::Type::Float
+
+    # @!attribute [rw] pct_box_outs_team_reb
+    #   Returns percentage of box outs resulting in team rebounds
+    #   @api public
+    #   @example
+    #     stat.pct_box_outs_team_reb #=> 0.667
+    #   @return [Float] percentage of box outs resulting in team rebounds
+    attribute :pct_box_outs_team_reb, Shale::Type::Float
+
+    # @!attribute [rw] pct_box_outs_reb
+    #   Returns percentage of box outs resulting in player rebounds
+    #   @api public
+    #   @example
+    #     stat.pct_box_outs_reb #=> 0.386
+    #   @return [Float] percentage of box outs resulting in player rebounds
+    attribute :pct_box_outs_reb, Shale::Type::Float
+
+    # Returns the player object
+    #
+    # @api public
+    # @example
+    #   stat.player #=> #<NBA::Player>
+    # @return [Player, nil] the player object
+    def player
+      Players.find(player_id)
+    end
+
+    # Returns the team object
+    #
+    # @api public
+    # @example
+    #   stat.team #=> #<NBA::Team>
+    # @return [Team, nil] the team object
+    def team
+      Teams.find(team_id)
+    end
+  end
+end