nba 0.1.1 → 0.2.0

data/lib/nba/draft_combine_stats.rb

@@ -0,0 +1,160 @@
+require "json"
+require_relative "client"
+require_relative "collection"
+require_relative "draft_combine_stat"
+
+module NBA
+  # Provides methods to retrieve draft combine stats
+  module DraftCombineStats
+    # Result set name
+    # @return [String] the result set name
+    RESULTS = "Results".freeze
+
+    # Retrieves draft combine stats for a season
+    #
+    # @api public
+    # @example
+    #   stats = NBA::DraftCombineStats.all(season: 2019)
+    #   stats.each { |s| puts "#{s.player_name}: #{s.height_w_shoes}" }
+    # @param season [Integer] the draft combine season year
+    # @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 draft combine stats
+    def self.all(season:, league: League::NBA, client: CLIENT)
+      league_id = Utils.extract_league_id(league)
+      path = build_path(season, league_id)
+      response = client.get(path)
+      parse_response(response)
+    end
+
+    # Builds the API request path
+    # @api private
+    # @return [String] the request path
+    def self.build_path(season, league_id)
+      "draftcombinestats?LeagueID=#{league_id}&SeasonYear=#{season}"
+    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)
+      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
+
+      results = rows.map { |row| build_result(headers, row) }
+      Collection.new(results)
+    end
+    private_class_method :parse_response
+
+    # Finds the result set in the response
+    # @api private
+    # @return [Hash, nil] the result set hash
+    def self.find_result_set(data)
+      result_sets = data["resultSets"]
+      return unless result_sets
+
+      result_sets.find { |rs| rs["name"].eql?(RESULTS) }
+    end
+    private_class_method :find_result_set
+
+    # Builds a DraftCombineStat object from raw data
+    # @api private
+    # @return [DraftCombineStat] the stat object
+    def self.build_result(headers, row)
+      data = headers.zip(row).to_h
+      DraftCombineStat.new(**result_attributes(data))
+    end
+    private_class_method :build_result
+
+    # Extracts result attributes from data
+    # @api private
+    # @return [Hash] the result attributes
+    def self.result_attributes(data)
+      player_attributes(data).merge(
+        physical_attributes(data),
+        athletic_attributes(data)
+      )
+    end
+    private_class_method :result_attributes
+
+    # Extracts player attributes from data
+    # @api private
+    # @return [Hash] player attributes
+    def self.player_attributes(data)
+      {
+        season: data["SEASON"],
+        player_id: data["PLAYER_ID"],
+        first_name: data["FIRST_NAME"],
+        last_name: data["LAST_NAME"],
+        player_name: data["PLAYER_NAME"],
+        position: data["POSITION"]
+      }
+    end
+    private_class_method :player_attributes
+
+    # Extracts physical measurement attributes from data
+    # @api private
+    # @return [Hash] physical measurement attributes
+    def self.physical_attributes(data)
+      height_attrs(data).merge(body_attrs(data)).merge(hand_attrs(data))
+    end
+    private_class_method :physical_attributes
+
+    # Extracts height attributes from data
+    # @api private
+    # @param data [Hash] the row data
+    # @return [Hash] height attributes
+    def self.height_attrs(data)
+      {height_wo_shoes: data["HEIGHT_WO_SHOES"],
+       height_wo_shoes_ft_in: data["HEIGHT_WO_SHOES_FT_IN"],
+       height_w_shoes: data["HEIGHT_W_SHOES"],
+       height_w_shoes_ft_in: data["HEIGHT_W_SHOES_FT_IN"]}
+    end
+    private_class_method :height_attrs
+
+    # Extracts body measurement attributes from data
+    # @api private
+    # @param data [Hash] the row data
+    # @return [Hash] body measurement attributes
+    def self.body_attrs(data)
+      {weight: data["WEIGHT"], wingspan: data["WINGSPAN"],
+       wingspan_ft_in: data["WINGSPAN_FT_IN"],
+       standing_reach: data["STANDING_REACH"],
+       standing_reach_ft_in: data["STANDING_REACH_FT_IN"],
+       body_fat_pct: data["BODY_FAT_PCT"]}
+    end
+    private_class_method :body_attrs
+
+    # Extracts hand measurement attributes from data
+    # @api private
+    # @param data [Hash] the row data
+    # @return [Hash] hand measurement attributes
+    def self.hand_attrs(data)
+      {hand_length: data["HAND_LENGTH"], hand_width: data["HAND_WIDTH"]}
+    end
+    private_class_method :hand_attrs
+
+    # Extracts athletic test attributes from data
+    # @api private
+    # @return [Hash] athletic test attributes
+    def self.athletic_attributes(data)
+      {
+        standing_vertical_leap: data["STANDING_VERTICAL_LEAP"],
+        max_vertical_leap: data["MAX_VERTICAL_LEAP"],
+        lane_agility_time: data["LANE_AGILITY_TIME"],
+        modified_lane_agility_time: data["MODIFIED_LANE_AGILITY_TIME"],
+        three_quarter_sprint: data["THREE_QUARTER_SPRINT"],
+        bench_press: data["BENCH_PRESS"]
+      }
+    end
+    private_class_method :athletic_attributes
+  end
+end

data/lib/nba/draft_history.rb

@@ -0,0 +1,142 @@
+require "json"
+require_relative "client"
+require_relative "collection"
+
+require_relative "draft_pick"
+
+module NBA
+  # Provides methods to retrieve draft history
+  module DraftHistory
+    # Result set name for draft history
+    # @return [String] the result set name
+    DRAFT_HISTORY = "DraftHistory".freeze
+
+    # Retrieves all draft picks for a season
+    #
+    # @api public
+    # @example
+    #   picks = NBA::DraftHistory.all(season: 2023)
+    #   picks.each { |p| puts "#{p.overall_pick}. #{p.player_name}" }
+    # @param season [Integer] the draft year
+    # @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 draft picks
+    def self.all(season: nil, league: League::NBA, client: CLIENT)
+      league_id = Utils.extract_league_id(league)
+      path = build_path(season, league_id)
+      response = client.get(path)
+      parse_response(response)
+    end
+
+    # Retrieves draft picks for a specific team
+    #
+    # @api public
+    # @example
+    #   picks = NBA::DraftHistory.by_team(team: NBA::Team::GSW, season: 2023)
+    #   picks.each { |p| puts "#{p.round_number}.#{p.round_pick}: #{p.player_name}" }
+    # @param team [Integer, Team] the team ID or Team object
+    # @param season [Integer] the draft year
+    # @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 draft picks
+    def self.by_team(team:, season: nil, league: League::NBA, client: CLIENT)
+      team_id = extract_team_id(team)
+      all_picks = all(season: season, league: league, client: client)
+      filtered = all_picks.select { |pick| pick.team_id.eql?(team_id) }
+      Collection.new(filtered)
+    end
+
+    # Builds the API request path
+    # @api private
+    # @return [String] the request path
+    def self.build_path(season, league_id)
+      season_param = season && "&Season=#{season}"
+      "drafthistory?LeagueID=#{league_id}#{season_param}"
+    end
+    private_class_method :build_path
+
+    # Parses the API response into draft pick objects
+    # @api private
+    # @return [Collection] collection of draft picks
+    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
+
+      picks = rows.map { |row| build_draft_pick(headers, row) }
+      Collection.new(picks)
+    end
+    private_class_method :parse_response
+
+    # Finds the draft history result set in the response
+    # @api private
+    # @return [Hash, nil] the result set hash
+    def self.find_result_set(data)
+      result_sets = data["resultSets"]
+      return unless result_sets
+
+      result_sets.find { |rs| rs["name"].eql?(DRAFT_HISTORY) }
+    end
+    private_class_method :find_result_set
+
+    # Builds a DraftPick object from raw data
+    # @api private
+    # @return [DraftPick] the draft pick object
+    def self.build_draft_pick(headers, row)
+      data = headers.zip(row).to_h
+      DraftPick.new(**draft_pick_attributes(data))
+    end
+    private_class_method :build_draft_pick
+
+    # Combines all draft pick attributes
+    # @api private
+    # @return [Hash] the combined attributes
+    def self.draft_pick_attributes(data)
+      pick_info_attributes(data).merge(team_attributes(data), player_attributes(data))
+    end
+    private_class_method :draft_pick_attributes
+
+    # Extracts pick info attributes from data
+    # @api private
+    # @return [Hash] pick info attributes
+    def self.pick_info_attributes(data)
+      {player_id: data["PERSON_ID"], season: data["SEASON"],
+       round_number: data["ROUND_NUMBER"], round_pick: data["ROUND_PICK"],
+       overall_pick: data["OVERALL_PICK"], draft_type: data["DRAFT_TYPE"]}
+    end
+    private_class_method :pick_info_attributes
+
+    # Extracts team attributes from data
+    # @api private
+    # @return [Hash] team attributes
+    def self.team_attributes(data)
+      {team_id: data["TEAM_ID"], team_city: data["TEAM_CITY"],
+       team_name: data["TEAM_NAME"], team_abbreviation: data["TEAM_ABBREVIATION"]}
+    end
+    private_class_method :team_attributes
+
+    # Extracts player attributes from data
+    # @api private
+    # @return [Hash] player attributes
+    def self.player_attributes(data)
+      {player_name: data["PLAYER_NAME"], position: data["POSITION"],
+       height: data["HEIGHT"], weight: data["WEIGHT"],
+       college: data["ORGANIZATION"], country: data["PLAYER_PROFILE_FLAG"]}
+    end
+    private_class_method :player_attributes
+
+    # Extracts team ID from team object or integer
+    # @api private
+    # @return [Integer] the team ID
+    def self.extract_team_id(team)
+      team.instance_of?(Team) ? team.id : team
+    end
+    private_class_method :extract_team_id
+  end
+end

data/lib/nba/draft_pick.rb

@@ -0,0 +1,154 @@
+module NBA
+  # Represents a draft pick
+  class DraftPick < Shale::Mapper
+    include Equalizer.new(:player_id, :season)
+
+    # @!attribute [rw] player_id
+    #   Returns the player ID
+    #   @api public
+    #   @example
+    #     pick.player_id #=> 1630162
+    #   @return [Integer] the player ID
+    attribute :player_id, Shale::Type::Integer
+
+    # @!attribute [rw] season
+    #   Returns the draft season/year
+    #   @api public
+    #   @example
+    #     pick.season #=> 2023
+    #   @return [Integer] the season
+    attribute :season, Shale::Type::Integer
+
+    # @!attribute [rw] round_number
+    #   Returns the round number
+    #   @api public
+    #   @example
+    #     pick.round_number #=> 1
+    #   @return [Integer] the round number
+    attribute :round_number, Shale::Type::Integer
+
+    # @!attribute [rw] round_pick
+    #   Returns the pick number within the round
+    #   @api public
+    #   @example
+    #     pick.round_pick #=> 1
+    #   @return [Integer] the round pick
+    attribute :round_pick, Shale::Type::Integer
+
+    # @!attribute [rw] overall_pick
+    #   Returns the overall pick number
+    #   @api public
+    #   @example
+    #     pick.overall_pick #=> 1
+    #   @return [Integer] the overall pick
+    attribute :overall_pick, Shale::Type::Integer
+
+    # @!attribute [rw] draft_type
+    #   Returns the draft type
+    #   @api public
+    #   @example
+    #     pick.draft_type #=> "Draft"
+    #   @return [String] the draft type
+    attribute :draft_type, Shale::Type::String
+
+    # @!attribute [rw] team_id
+    #   Returns the team ID that drafted the player
+    #   @api public
+    #   @example
+    #     pick.team_id #=> 1610612759
+    #   @return [Integer] the team ID
+    attribute :team_id, Shale::Type::Integer
+
+    # @!attribute [rw] team_city
+    #   Returns the team city
+    #   @api public
+    #   @example
+    #     pick.team_city #=> "San Antonio"
+    #   @return [String] the team city
+    attribute :team_city, Shale::Type::String
+
+    # @!attribute [rw] team_name
+    #   Returns the team name
+    #   @api public
+    #   @example
+    #     pick.team_name #=> "Spurs"
+    #   @return [String] the team name
+    attribute :team_name, Shale::Type::String
+
+    # @!attribute [rw] team_abbreviation
+    #   Returns the team abbreviation
+    #   @api public
+    #   @example
+    #     pick.team_abbreviation #=> "SAS"
+    #   @return [String] the team abbreviation
+    attribute :team_abbreviation, Shale::Type::String
+
+    # @!attribute [rw] player_name
+    #   Returns the player name
+    #   @api public
+    #   @example
+    #     pick.player_name #=> "Victor Wembanyama"
+    #   @return [String] the player name
+    attribute :player_name, Shale::Type::String
+
+    # @!attribute [rw] position
+    #   Returns the player's position
+    #   @api public
+    #   @example
+    #     pick.position #=> "C"
+    #   @return [String] the position
+    attribute :position, Shale::Type::String
+
+    # @!attribute [rw] height
+    #   Returns the player's height
+    #   @api public
+    #   @example
+    #     pick.height #=> "7-4"
+    #   @return [String] the height
+    attribute :height, Shale::Type::String
+
+    # @!attribute [rw] weight
+    #   Returns the player's weight
+    #   @api public
+    #   @example
+    #     pick.weight #=> 210
+    #   @return [Integer] the weight
+    attribute :weight, Shale::Type::Integer
+
+    # @!attribute [rw] college
+    #   Returns the player's college
+    #   @api public
+    #   @example
+    #     pick.college #=> "France"
+    #   @return [String] the college
+    attribute :college, Shale::Type::String
+
+    # @!attribute [rw] country
+    #   Returns the player's country
+    #   @api public
+    #   @example
+    #     pick.country #=> "France"
+    #   @return [String] the country
+    attribute :country, Shale::Type::String
+
+    # Returns the player object
+    #
+    # @api public
+    # @example
+    #   pick.player #=> #<NBA::Player>
+    # @return [Player, nil] the player object
+    def player
+      Players.find(player_id)
+    end
+
+    # Returns the team object
+    #
+    # @api public
+    # @example
+    #   pick.team #=> #<NBA::Team>
+    # @return [Team, nil] the team object
+    def team
+      Teams.find(team_id)
+    end
+  end
+end

data/lib/nba/dunk_score_leader.rb

@@ -0,0 +1,93 @@
+require "equalizer"
+require "shale"
+require_relative "players"
+require_relative "teams"
+
+module NBA
+  # Represents a dunk score leader from the draft combine
+  class DunkScoreLeader < Shale::Mapper
+    include Equalizer.new(:player_id, :rank)
+
+    # @!attribute [rw] player_id
+    #   Returns the player ID
+    #   @api public
+    #   @example
+    #     leader.player_id #=> 1631094
+    #   @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 #=> "Paolo Banchero"
+    #   @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 #=> 1610612753
+    #   @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 #=> "ORL"
+    #   @return [String] the team abbreviation
+    attribute :team_abbreviation, Shale::Type::String
+
+    # @!attribute [rw] rank
+    #   Returns the rank in dunk score
+    #   @api public
+    #   @example
+    #     leader.rank #=> 1
+    #   @return [Integer] the rank
+    attribute :rank, Shale::Type::Integer
+
+    # @!attribute [rw] dunk_score
+    #   Returns the dunk score
+    #   @api public
+    #   @example
+    #     leader.dunk_score #=> 85.5
+    #   @return [Float] the dunk score
+    attribute :dunk_score, Shale::Type::Float
+
+    # 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 "dunk_score", to: :dunk_score
+      map "dunkScore", to: :dunk_score
+    end
+  end
+end

data/lib/nba/dunk_score_leaders.rb

@@ -0,0 +1,77 @@
+require "json"
+require_relative "client"
+require_relative "collection"
+require_relative "dunk_score_leader"
+require_relative "response_parser"
+require_relative "utils"
+
+module NBA
+  # Provides methods to retrieve dunk score leaders from the draft combine
+  module DunkScoreLeaders
+    # Result set name for dunk score leaders
+    # @return [String] the result set name
+    RESULT_SET = "DunkScoreLeaders".freeze
+
+    # Retrieves dunk score leaders for a season
+    #
+    # @api public
+    # @example
+    #   leaders = NBA::DunkScoreLeaders.all(season: 2023)
+    #   leaders.each { |leader| puts "#{leader.rank}. #{leader.player_name}: #{leader.dunk_score}" }
+    # @param season [Integer] the season year (defaults to current season)
+    # @param season_type [String] the season type (Regular Season, Playoffs, All Star, etc.)
+    # @param player [Integer, Player, nil] optional player ID or Player object to filter by
+    # @param team [Integer, Team, nil] optional team ID or Team object to filter by
+    # @param game [String, Game, nil] optional game ID or Game object to filter by
+    # @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 dunk score leaders
+    def self.all(season: Utils.current_season, season_type: "Regular Season", player: nil, team: nil, game: nil,
+      league: League::NBA, client: CLIENT)
+      params = build_params(season: season, season_type: season_type, player: player, team: team, game: game,
+        league: league)
+      path = build_path(params)
+      ResponseParser.parse(client.get(path), result_set: RESULT_SET) { |data| build_leader(data) }
+    end
+
+    # Builds the params hash for the API request
+    # @api private
+    # @return [Hash] the params hash
+    def self.build_params(season:, season_type:, player:, team:, game:, league:)
+      {season: Utils.format_season(season), season_type: season_type, league_id: Utils.extract_league_id(league),
+       player_id: Utils.extract_id(player), team_id: Utils.extract_id(team), game_id: Utils.extract_id(game)}
+    end
+    private_class_method :build_params
+
+    # Builds the API request path
+    # @api private
+    # @return [String] the request path
+    def self.build_path(params)
+      base = "dunkscoreleaders?LeagueID=#{params.fetch(:league_id)}&Season=#{params.fetch(:season)}"
+      season_type = "&SeasonType=#{params.fetch(:season_type)}"
+      filter = "&PlayerID=#{params.fetch(:player_id)}&TeamID=#{params.fetch(:team_id)}&GameID=#{params.fetch(:game_id)}"
+      "#{base}#{season_type}#{filter}"
+    end
+    private_class_method :build_path
+
+    # Builds a DunkScoreLeader object from raw data
+    # @api private
+    # @param data [Hash] the row data
+    # @return [DunkScoreLeader] the leader object
+    def self.build_leader(data)
+      DunkScoreLeader.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"], dunk_score: data["DUNK_SCORE"]}
+    end
+    private_class_method :leader_attributes
+  end
+end