nba 0.1.1 → 0.2.0

data/lib/nba/team_pass_stat.rb

@@ -0,0 +1,183 @@
+require "equalizer"
+require "shale"
+
+module NBA
+  # Represents team tracking pass statistics
+  #
+  # @api public
+  class TeamPassStat < Shale::Mapper
+    include Equalizer.new(:team_id, :pass_teammate_player_id)
+
+    # @!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_name
+    #   Returns the team name
+    #   @api public
+    #   @example
+    #     stat.team_name #=> "Golden State Warriors"
+    #   @return [String] the team name
+    attribute :team_name, Shale::Type::String
+
+    # @!attribute [rw] pass_type
+    #   Returns the type of pass
+    #   @api public
+    #   @example
+    #     stat.pass_type #=> "Made"
+    #   @return [String] the pass type
+    attribute :pass_type, Shale::Type::String
+
+    # @!attribute [rw] g
+    #   Returns games
+    #   @api public
+    #   @example
+    #     stat.g #=> 74
+    #   @return [Integer] games
+    attribute :g, Shale::Type::Integer
+
+    # @!attribute [rw] pass_from
+    #   Returns the passer name (for passes made)
+    #   @api public
+    #   @example
+    #     stat.pass_from #=> "Stephen Curry"
+    #   @return [String] the passer name
+    attribute :pass_from, Shale::Type::String
+
+    # @!attribute [rw] pass_to
+    #   Returns the pass recipient name (for passes received)
+    #   @api public
+    #   @example
+    #     stat.pass_to #=> "Klay Thompson"
+    #   @return [String] the recipient name
+    attribute :pass_to, Shale::Type::String
+
+    # @!attribute [rw] pass_teammate_player_id
+    #   Returns the pass partner player ID
+    #   @api public
+    #   @example
+    #     stat.pass_teammate_player_id #=> 202691
+    #   @return [Integer] the teammate player ID
+    attribute :pass_teammate_player_id, Shale::Type::Integer
+
+    # @!attribute [rw] frequency
+    #   Returns the frequency percentage
+    #   @api public
+    #   @example
+    #     stat.frequency #=> 0.25
+    #   @return [Float] the frequency
+    attribute :frequency, Shale::Type::Float
+
+    # @!attribute [rw] pass
+    #   Returns passes per game
+    #   @api public
+    #   @example
+    #     stat.pass #=> 5.2
+    #   @return [Float] passes per game
+    attribute :pass, Shale::Type::Float
+
+    # @!attribute [rw] ast
+    #   Returns assists per game
+    #   @api public
+    #   @example
+    #     stat.ast #=> 2.1
+    #   @return [Float] assists per game
+    attribute :ast, Shale::Type::Float
+
+    # @!attribute [rw] fgm
+    #   Returns field goals made following pass
+    #   @api public
+    #   @example
+    #     stat.fgm #=> 3.5
+    #   @return [Float] field goals made
+    attribute :fgm, Shale::Type::Float
+
+    # @!attribute [rw] fga
+    #   Returns field goals attempted following pass
+    #   @api public
+    #   @example
+    #     stat.fga #=> 7.2
+    #   @return [Float] field goals attempted
+    attribute :fga, Shale::Type::Float
+
+    # @!attribute [rw] fg_pct
+    #   Returns field goal percentage following pass
+    #   @api public
+    #   @example
+    #     stat.fg_pct #=> 0.486
+    #   @return [Float] field goal percentage
+    attribute :fg_pct, Shale::Type::Float
+
+    # @!attribute [rw] fg2m
+    #   Returns two-pointers made following pass
+    #   @api public
+    #   @example
+    #     stat.fg2m #=> 1.5
+    #   @return [Float] two-pointers made
+    attribute :fg2m, Shale::Type::Float
+
+    # @!attribute [rw] fg2a
+    #   Returns two-pointers attempted following pass
+    #   @api public
+    #   @example
+    #     stat.fg2a #=> 3.0
+    #   @return [Float] two-pointers attempted
+    attribute :fg2a, Shale::Type::Float
+
+    # @!attribute [rw] fg2_pct
+    #   Returns two-point percentage following pass
+    #   @api public
+    #   @example
+    #     stat.fg2_pct #=> 0.500
+    #   @return [Float] two-point percentage
+    attribute :fg2_pct, Shale::Type::Float
+
+    # @!attribute [rw] fg3m
+    #   Returns three-pointers made following pass
+    #   @api public
+    #   @example
+    #     stat.fg3m #=> 2.0
+    #   @return [Float] three-pointers made
+    attribute :fg3m, Shale::Type::Float
+
+    # @!attribute [rw] fg3a
+    #   Returns three-pointers attempted following pass
+    #   @api public
+    #   @example
+    #     stat.fg3a #=> 4.2
+    #   @return [Float] three-pointers attempted
+    attribute :fg3a, Shale::Type::Float
+
+    # @!attribute [rw] fg3_pct
+    #   Returns three-point percentage following pass
+    #   @api public
+    #   @example
+    #     stat.fg3_pct #=> 0.476
+    #   @return [Float] three-point percentage
+    attribute :fg3_pct, Shale::Type::Float
+
+    # Returns the teammate player object
+    #
+    # @api public
+    # @example
+    #   stat.teammate #=> #<NBA::Player>
+    # @return [Player, nil] the teammate player object
+    def teammate
+      Players.find(pass_teammate_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

data/lib/nba/team_player_dashboard.rb

@@ -0,0 +1,212 @@
+require "json"
+require_relative "client"
+require_relative "collection"
+require_relative "utils"
+
+module NBA
+  # Provides methods to retrieve player dashboard data for a team
+  module TeamPlayerDashboard
+    # Result set name for player stats
+    # @return [String] the result set name
+    PLAYERS = "PlayersSeasonTotals".freeze
+
+    # Result set name for team overall stats
+    # @return [String] the result set name
+    TEAM_OVERALL = "TeamOverall".freeze
+
+    # Retrieves player statistics for a team
+    #
+    # @api public
+    # @example
+    #   stats = NBA::TeamPlayerDashboard.players(team: NBA::Team::GSW)
+    #   stats.each { |s| puts "#{s.player_name}: #{s.pts} ppg" }
+    # @param team [Integer, Team] the team ID or Team object
+    # @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 stats
+    def self.players(team:, season: Utils.current_season, season_type: "Regular Season", per_mode: "PerGame", client: CLIENT)
+      fetch_stats(team, season, season_type, per_mode, PLAYERS, client:)
+    end
+
+    # Retrieves team overall statistics
+    #
+    # @api public
+    # @example
+    #   stats = NBA::TeamPlayerDashboard.team(team: NBA::Team::GSW)
+    #   stats.first.pts #=> 111.8
+    # @param team [Integer, Team] the team ID or Team object
+    # @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 team overall stats
+    def self.team(team:, season: Utils.current_season, season_type: "Regular Season", per_mode: "PerGame", client: CLIENT)
+      fetch_stats(team, season, season_type, per_mode, TEAM_OVERALL, client:)
+    end
+
+    # Fetches stats from the API
+    #
+    # @api private
+    # @return [Collection] collection of stats
+    def self.fetch_stats(team, season, season_type, per_mode, result_set_name, client:)
+      team_id = Utils.extract_id(team)
+      path = build_path(team_id, season, season_type, per_mode)
+      response = client.get(path)
+      parse_response(response, result_set_name)
+    end
+    private_class_method :fetch_stats
+
+    # Builds the API path
+    #
+    # @api private
+    # @return [String] the request path
+    def self.build_path(team_id, season, season_type, per_mode)
+      season_str = Utils.format_season(season)
+      "teamplayerdashboard?TeamID=#{team_id}&Season=#{season_str}&SeasonType=#{season_type}&PerMode=#{per_mode}&LeagueID=00"
+    end
+    private_class_method :build_path
+
+    # Parses the API response into stat objects
+    #
+    # @api private
+    # @return [Collection] collection of stats
+    def self.parse_response(response, result_set_name)
+      return Collection.new unless response
+
+      data = JSON.parse(response)
+      result_sets = data["resultSets"]
+      return Collection.new unless result_sets
+
+      result_set = find_result_set(result_sets, result_set_name)
+      return Collection.new unless result_set
+
+      build_collection(result_set, result_set_name)
+    end
+    private_class_method :parse_response
+
+    # Finds a result set by name
+    #
+    # @api private
+    # @return [Hash, nil] the result set or nil if not found
+    def self.find_result_set(result_sets, name)
+      result_sets.find { |rs| rs["name"].eql?(name) }
+    end
+    private_class_method :find_result_set
+
+    # Builds a collection from a result set
+    #
+    # @api private
+    # @return [Collection] collection of stats
+    def self.build_collection(result_set, result_set_name)
+      headers = result_set["headers"]
+      rows = result_set["rowSet"]
+      return Collection.new unless headers && rows
+
+      stats = rows.map { |row| build_stat(headers, row, result_set_name) }
+      Collection.new(stats)
+    end
+    private_class_method :build_collection
+
+    # Builds a stat object from raw data
+    #
+    # @api private
+    # @return [TeamPlayerStat, TeamDashboardStat] the stat object
+    def self.build_stat(headers, row, result_set_name)
+      data = headers.zip(row).to_h
+      if result_set_name.eql?(PLAYERS)
+        TeamPlayerStat.new(**player_attributes(data))
+      else
+        TeamDashboardStat.new(**team_attributes(data))
+      end
+    end
+    private_class_method :build_stat
+
+    # Extracts player attributes from data
+    #
+    # @api private
+    # @return [Hash] player attributes
+    def self.player_attributes(data)
+      identity_attributes(data)
+        .merge(record_attributes(data))
+        .merge(shooting_attributes(data))
+        .merge(counting_attributes(data))
+        .merge(bonus_attributes(data))
+    end
+    private_class_method :player_attributes
+
+    # Extracts team attributes from data
+    #
+    # @api private
+    # @return [Hash] team attributes
+    def self.team_attributes(data)
+      team_identity(data)
+        .merge(record_attributes(data))
+        .merge(shooting_attributes(data))
+        .merge(counting_attributes(data))
+    end
+    private_class_method :team_attributes
+
+    # Extracts identity attributes from data
+    #
+    # @api private
+    # @return [Hash] identity attributes
+    def self.identity_attributes(data)
+      {group_set: data["GROUP_SET"], player_id: data["PLAYER_ID"],
+       player_name: data["PLAYER_NAME"], gp: data["GP"], min: data["MIN"]}
+    end
+    private_class_method :identity_attributes
+
+    # Extracts team identity attributes from data
+    #
+    # @api private
+    # @return [Hash] team identity attributes
+    def self.team_identity(data)
+      {group_set: data["GROUP_SET"], group_value: data["GROUP_VALUE"],
+       team_id: data["TEAM_ID"], gp: data["GP"], min: data["MIN"]}
+    end
+    private_class_method :team_identity
+
+    # Extracts record attributes from data
+    #
+    # @api private
+    # @return [Hash] record attributes
+    def self.record_attributes(data)
+      {w: data["W"], l: data["L"], w_pct: data["W_PCT"]}
+    end
+    private_class_method :record_attributes
+
+    # Extracts shooting attributes from data
+    #
+    # @api private
+    # @return [Hash] shooting attributes
+    def self.shooting_attributes(data)
+      {fgm: data["FGM"], fga: data["FGA"], fg_pct: data["FG_PCT"],
+       fg3m: data["FG3M"], fg3a: data["FG3A"], fg3_pct: data["FG3_PCT"],
+       ftm: data["FTM"], fta: data["FTA"], ft_pct: data["FT_PCT"]}
+    end
+    private_class_method :shooting_attributes
+
+    # Extracts counting stats attributes from data
+    #
+    # @api private
+    # @return [Hash] counting attributes
+    def self.counting_attributes(data)
+      {oreb: data["OREB"], dreb: data["DREB"], reb: data["REB"],
+       ast: data["AST"], tov: data["TOV"], stl: data["STL"], blk: data["BLK"],
+       blka: data["BLKA"], pf: data["PF"], pfd: data["PFD"],
+       pts: data["PTS"], plus_minus: data["PLUS_MINUS"]}
+    end
+    private_class_method :counting_attributes
+
+    # Extracts bonus attributes from data
+    #
+    # @api private
+    # @return [Hash] bonus attributes
+    def self.bonus_attributes(data)
+      {nba_fantasy_pts: data["NBA_FANTASY_PTS"], dd2: data["DD2"], td3: data["TD3"]}
+    end
+    private_class_method :bonus_attributes
+  end
+end

data/lib/nba/team_player_on_off_details.rb

@@ -0,0 +1,218 @@
+require "json"
+require_relative "client"
+require_relative "collection"
+require_relative "utils"
+
+module NBA
+  # Provides methods to retrieve team on/off court details
+  module TeamPlayerOnOffDetails
+    # Result set name for overall team stats
+    # @return [String] the result set name
+    OVERALL = "OverallTeamPlayerOnOffDetails".freeze
+    # Result set name for players on court stats
+    # @return [String] the result set name
+    PLAYERS_ON = "PlayersOnCourtTeamPlayerOnOffDetails".freeze
+    # Result set name for players off court stats
+    # @return [String] the result set name
+    PLAYERS_OFF = "PlayersOffCourtTeamPlayerOnOffDetails".freeze
+
+    # Retrieves overall team on/off court statistics
+    #
+    # @api public
+    # @example
+    #   stats = NBA::TeamPlayerOnOffDetails.overall(team: NBA::Team::GSW)
+    #   stats.each { |s| puts "#{s.group_value}: #{s.pts} pts" }
+    # @param team [Integer, Team] the team ID or Team object
+    # @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 overall stats
+    def self.overall(team:, season: Utils.current_season, season_type: "Regular Season", per_mode: "PerGame", client: CLIENT)
+      fetch_stats(team, season, season_type, per_mode, OVERALL, client:)
+    end
+
+    # Retrieves statistics when opponent players are on the court
+    #
+    # @api public
+    # @example
+    #   stats = NBA::TeamPlayerOnOffDetails.players_on_court(team: NBA::Team::GSW)
+    #   stats.each { |s| puts "#{s.vs_player_name}: #{s.pts} pts" }
+    # @param team [Integer, Team] the team ID or Team object
+    # @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 on court stats
+    def self.players_on_court(team:, season: Utils.current_season, season_type: "Regular Season", per_mode: "PerGame", client: CLIENT)
+      fetch_stats(team, season, season_type, per_mode, PLAYERS_ON, client:)
+    end
+
+    # Retrieves statistics when opponent players are off the court
+    #
+    # @api public
+    # @example
+    #   stats = NBA::TeamPlayerOnOffDetails.players_off_court(team: NBA::Team::GSW)
+    #   stats.each { |s| puts "#{s.vs_player_name}: #{s.pts} pts" }
+    # @param team [Integer, Team] the team ID or Team object
+    # @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 off court stats
+    def self.players_off_court(team:, season: Utils.current_season, season_type: "Regular Season", per_mode: "PerGame", client: CLIENT)
+      fetch_stats(team, season, season_type, per_mode, PLAYERS_OFF, client:)
+    end
+
+    # Fetches team player on/off details from the API
+    #
+    # @api private
+    # @return [Collection] the collection of statistics
+    def self.fetch_stats(team, season, season_type, per_mode, result_set_name, client:)
+      path = build_path(Utils.extract_id(team), season, season_type, per_mode)
+      parse_response(client.get(path), result_set_name)
+    end
+    private_class_method :fetch_stats
+
+    # Builds the API request path with all parameters
+    #
+    # @api private
+    # @return [String] the API request path
+    def self.build_path(team_id, season, season_type, per_mode)
+      season_str = Utils.format_season(season)
+      "teamplayeronoffdetails?TeamID=#{team_id}&Season=#{season_str}&SeasonType=#{season_type}&PerMode=#{per_mode}&LeagueID=00"
+    end
+    private_class_method :build_path
+
+    # Parses the API response into stat objects
+    # @api private
+    # @return [Collection] collection of stat objects
+    def self.parse_response(response, result_set_name)
+      return Collection.new unless response
+
+      result_set = find_result_set(JSON.parse(response), result_set_name)
+      build_collection(result_set, result_set_name)
+    end
+    private_class_method :parse_response
+
+    # Finds a result set by name in the parsed response data
+    # @api private
+    # @return [Hash, nil] the matching result set or nil
+    def self.find_result_set(data, name)
+      data["resultSets"]&.find { |rs| rs["name"].eql?(name) }
+    end
+    private_class_method :find_result_set
+
+    # Builds a collection of stat objects from a result set
+    # @api private
+    # @return [Collection] collection of stat objects
+    def self.build_collection(result_set, result_set_name)
+      return Collection.new unless result_set
+
+      headers = result_set["headers"]
+      rows = result_set["rowSet"]
+      return Collection.new unless headers && rows
+
+      Collection.new(rows.map { |row| build_stat(headers.zip(row).to_h, result_set_name) })
+    end
+    private_class_method :build_collection
+
+    # Builds a stat object from row data
+    # @api private
+    # @return [TeamOnOffOverallStat, TeamOnOffPlayerStat] the stat object
+    def self.build_stat(data, result_set_name)
+      attrs = result_set_name.eql?(OVERALL) ? overall_attrs(data) : player_attrs(data)
+      result_set_name.eql?(OVERALL) ? TeamOnOffOverallStat.new(**attrs) : TeamOnOffPlayerStat.new(**attrs)
+    end
+    private_class_method :build_stat
+
+    # Extracts overall stat attributes from row data
+    # @api private
+    # @return [Hash] overall stat attributes
+    def self.overall_attrs(data)
+      {group_set: data["GROUP_SET"], group_value: data["GROUP_VALUE"], team_id: data["TEAM_ID"],
+       team_abbreviation: data["TEAM_ABBREVIATION"], team_name: data["TEAM_NAME"]}.merge(stat_attrs(data))
+    end
+    private_class_method :overall_attrs
+
+    # Extracts player stat attributes from row data
+    # @api private
+    # @return [Hash] player stat attributes
+    def self.player_attrs(data)
+      {group_set: data["GROUP_SET"], team_id: data["TEAM_ID"], team_abbreviation: data["TEAM_ABBREVIATION"],
+       team_name: data["TEAM_NAME"], vs_player_id: data["VS_PLAYER_ID"], vs_player_name: data["VS_PLAYER_NAME"],
+       court_status: data["COURT_STATUS"]}.merge(stat_attrs(data))
+    end
+    private_class_method :player_attrs
+
+    # Extracts common stat attributes from row data
+    # @api private
+    # @return [Hash] common stat attributes
+    def self.stat_attrs(data)
+      record_attrs(data).merge(shooting_attrs(data), counting_attrs(data), rank_attrs(data))
+    end
+    private_class_method :stat_attrs
+
+    # Extracts record attributes from row data
+    # @api private
+    # @return [Hash] record attributes
+    def self.record_attrs(data)
+      {gp: data["GP"], w: data["W"], l: data["L"], w_pct: data["W_PCT"], min: data["MIN"]}
+    end
+    private_class_method :record_attrs
+
+    # Extracts shooting stat attributes from row data
+    # @api private
+    # @return [Hash] shooting stat attributes
+    def self.shooting_attrs(data)
+      {fgm: data["FGM"], fga: data["FGA"], fg_pct: data["FG_PCT"], fg3m: data["FG3M"], fg3a: data["FG3A"],
+       fg3_pct: data["FG3_PCT"], ftm: data["FTM"], fta: data["FTA"], ft_pct: data["FT_PCT"]}
+    end
+    private_class_method :shooting_attrs
+
+    # Extracts counting stat attributes from row data
+    # @api private
+    # @return [Hash] counting stat attributes
+    def self.counting_attrs(data)
+      {oreb: data["OREB"], dreb: data["DREB"], reb: data["REB"], ast: data["AST"], tov: data["TOV"], stl: data["STL"],
+       blk: data["BLK"], blka: data["BLKA"], pf: data["PF"], pfd: data["PFD"], pts: data["PTS"], plus_minus: data["PLUS_MINUS"]}
+    end
+    private_class_method :counting_attrs
+
+    # Extracts rank attributes from row data
+    # @api private
+    # @return [Hash] rank attributes
+    def self.rank_attrs(data)
+      record_rank_attrs(data).merge(shooting_rank_attrs(data), counting_rank_attrs(data))
+    end
+    private_class_method :rank_attrs
+
+    # Extracts record rank attributes from row data
+    # @api private
+    # @return [Hash] record rank attributes
+    def self.record_rank_attrs(data)
+      {gp_rank: data["GP_RANK"], w_rank: data["W_RANK"], l_rank: data["L_RANK"], w_pct_rank: data["W_PCT_RANK"], min_rank: data["MIN_RANK"]}
+    end
+    private_class_method :record_rank_attrs
+
+    # Extracts shooting rank attributes from row data
+    # @api private
+    # @return [Hash] shooting rank attributes
+    def self.shooting_rank_attrs(data)
+      {fgm_rank: data["FGM_RANK"], fga_rank: data["FGA_RANK"], fg_pct_rank: data["FG_PCT_RANK"], fg3m_rank: data["FG3M_RANK"],
+       fg3a_rank: data["FG3A_RANK"], fg3_pct_rank: data["FG3_PCT_RANK"], ftm_rank: data["FTM_RANK"], fta_rank: data["FTA_RANK"],
+       ft_pct_rank: data["FT_PCT_RANK"]}
+    end
+    private_class_method :shooting_rank_attrs
+
+    # Extracts counting rank attributes from row data
+    # @api private
+    # @return [Hash] counting rank attributes
+    def self.counting_rank_attrs(data)
+      {oreb_rank: data["OREB_RANK"], dreb_rank: data["DREB_RANK"], reb_rank: data["REB_RANK"], ast_rank: data["AST_RANK"],
+       tov_rank: data["TOV_RANK"], stl_rank: data["STL_RANK"], blk_rank: data["BLK_RANK"], blka_rank: data["BLKA_RANK"],
+       pf_rank: data["PF_RANK"], pfd_rank: data["PFD_RANK"], pts_rank: data["PTS_RANK"], plus_minus_rank: data["PLUS_MINUS_RANK"]}
+    end
+    private_class_method :counting_rank_attrs
+  end
+end