nba 0.1.1 → 0.2.0

data/lib/nba/assist_tracker_entry.rb

@@ -0,0 +1,206 @@
+require "equalizer"
+require "shale"
+require_relative "players"
+require_relative "teams"
+
+module NBA
+  # Represents an assist tracker entry (pass to score)
+  class AssistTrackerEntry < Shale::Mapper
+    include Equalizer.new(:player_id, :pass_to)
+
+    # @!attribute [rw] player_id
+    #   Returns the passer's player ID
+    #   @api public
+    #   @example
+    #     entry.player_id #=> 201566
+    #   @return [Integer] the passer's player ID
+    attribute :player_id, Shale::Type::Integer
+
+    # @!attribute [rw] player_name
+    #   Returns the passer's name
+    #   @api public
+    #   @example
+    #     entry.player_name #=> "Russell Westbrook"
+    #   @return [String] the passer's name
+    attribute :player_name, Shale::Type::String
+
+    # @!attribute [rw] team_id
+    #   Returns the team ID
+    #   @api public
+    #   @example
+    #     entry.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
+    #     entry.team_abbreviation #=> "LAC"
+    #   @return [String] the team abbreviation
+    attribute :team_abbreviation, Shale::Type::String
+
+    # @!attribute [rw] pass_to
+    #   Returns the name of the player receiving the pass
+    #   @api public
+    #   @example
+    #     entry.pass_to #=> "Kawhi Leonard"
+    #   @return [String] the receiver's name
+    attribute :pass_to, Shale::Type::String
+
+    # @!attribute [rw] pass_to_player_id
+    #   Returns the ID of the player receiving the pass
+    #   @api public
+    #   @example
+    #     entry.pass_to_player_id #=> 202695
+    #   @return [Integer] the receiver's player ID
+    attribute :pass_to_player_id, Shale::Type::Integer
+
+    # @!attribute [rw] frequency
+    #   Returns the frequency of this pass combination
+    #   @api public
+    #   @example
+    #     entry.frequency #=> 0.123
+    #   @return [Float] the frequency
+    attribute :frequency, Shale::Type::Float
+
+    # @!attribute [rw] pass
+    #   Returns the number of passes
+    #   @api public
+    #   @example
+    #     entry.pass #=> 45
+    #   @return [Integer] the number of passes
+    attribute :pass, Shale::Type::Integer
+
+    # @!attribute [rw] ast
+    #   Returns the number of assists
+    #   @api public
+    #   @example
+    #     entry.ast #=> 32
+    #   @return [Integer] the number of assists
+    attribute :ast, Shale::Type::Integer
+
+    # @!attribute [rw] fg_m
+    #   Returns the field goals made
+    #   @api public
+    #   @example
+    #     entry.fg_m #=> 28
+    #   @return [Integer] the field goals made
+    attribute :fg_m, Shale::Type::Integer
+
+    # @!attribute [rw] fg_a
+    #   Returns the field goal attempts
+    #   @api public
+    #   @example
+    #     entry.fg_a #=> 45
+    #   @return [Integer] the field goal attempts
+    attribute :fg_a, Shale::Type::Integer
+
+    # @!attribute [rw] fg_pct
+    #   Returns the field goal percentage
+    #   @api public
+    #   @example
+    #     entry.fg_pct #=> 0.622
+    #   @return [Float] the field goal percentage
+    attribute :fg_pct, Shale::Type::Float
+
+    # @!attribute [rw] fg2m
+    #   Returns the 2-point field goals made
+    #   @api public
+    #   @example
+    #     entry.fg2m #=> 20
+    #   @return [Integer] the 2-point field goals made
+    attribute :fg2m, Shale::Type::Integer
+
+    # @!attribute [rw] fg2a
+    #   Returns the 2-point field goal attempts
+    #   @api public
+    #   @example
+    #     entry.fg2a #=> 30
+    #   @return [Integer] the 2-point field goal attempts
+    attribute :fg2a, Shale::Type::Integer
+
+    # @!attribute [rw] fg2_pct
+    #   Returns the 2-point field goal percentage
+    #   @api public
+    #   @example
+    #     entry.fg2_pct #=> 0.667
+    #   @return [Float] the 2-point field goal percentage
+    attribute :fg2_pct, Shale::Type::Float
+
+    # @!attribute [rw] fg3m
+    #   Returns the 3-point field goals made
+    #   @api public
+    #   @example
+    #     entry.fg3m #=> 8
+    #   @return [Integer] the 3-point field goals made
+    attribute :fg3m, Shale::Type::Integer
+
+    # @!attribute [rw] fg3a
+    #   Returns the 3-point field goal attempts
+    #   @api public
+    #   @example
+    #     entry.fg3a #=> 15
+    #   @return [Integer] the 3-point field goal attempts
+    attribute :fg3a, Shale::Type::Integer
+
+    # @!attribute [rw] fg3_pct
+    #   Returns the 3-point field goal percentage
+    #   @api public
+    #   @example
+    #     entry.fg3_pct #=> 0.533
+    #   @return [Float] the 3-point field goal percentage
+    attribute :fg3_pct, Shale::Type::Float
+
+    # Returns the passer player object
+    #
+    # @api public
+    # @example
+    #   entry.player #=> #<NBA::Player>
+    # @return [Player, nil] the passer player object
+    def player
+      Players.find(player_id)
+    end
+
+    # Returns the receiver player object
+    #
+    # @api public
+    # @example
+    #   entry.pass_to_player #=> #<NBA::Player>
+    # @return [Player, nil] the receiver player object
+    def pass_to_player
+      Players.find(pass_to_player_id)
+    end
+
+    # Returns the team object
+    #
+    # @api public
+    # @example
+    #   entry.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 "player_name", to: :player_name
+      map "team_id", to: :team_id
+      map "team_abbreviation", to: :team_abbreviation
+      map "pass_to", to: :pass_to
+      map "pass_to_player_id", to: :pass_to_player_id
+      map "frequency", to: :frequency
+      map "pass", to: :pass
+      map "ast", to: :ast
+      map "fg_m", to: :fg_m
+      map "fg_a", to: :fg_a
+      map "fg_pct", to: :fg_pct
+      map "fg2m", to: :fg2m
+      map "fg2a", to: :fg2a
+      map "fg2_pct", to: :fg2_pct
+      map "fg3m", to: :fg3m
+      map "fg3a", to: :fg3a
+      map "fg3_pct", to: :fg3_pct
+    end
+  end
+end

data/lib/nba/award.rb

@@ -0,0 +1,128 @@
+module NBA
+  # Represents a player's award
+  class Award < Shale::Mapper
+    include Equalizer.new(:player_id, :description, :season)
+
+    # @!attribute [rw] player_id
+    #   Returns the player ID
+    #   @api public
+    #   @example
+    #     award.player_id #=> 201939
+    #   @return [Integer] the player ID
+    attribute :player_id, Shale::Type::Integer
+
+    # @!attribute [rw] first_name
+    #   Returns the player's first name
+    #   @api public
+    #   @example
+    #     award.first_name #=> "Stephen"
+    #   @return [String] the first name
+    attribute :first_name, Shale::Type::String
+
+    # @!attribute [rw] last_name
+    #   Returns the player's last name
+    #   @api public
+    #   @example
+    #     award.last_name #=> "Curry"
+    #   @return [String] the last name
+    attribute :last_name, Shale::Type::String
+
+    # @!attribute [rw] team
+    #   Returns the team name
+    #   @api public
+    #   @example
+    #     award.team #=> "Golden State Warriors"
+    #   @return [String] the team name
+    attribute :team, Shale::Type::String
+
+    # @!attribute [rw] description
+    #   Returns the award description
+    #   @api public
+    #   @example
+    #     award.description #=> "All-NBA"
+    #   @return [String] the award description
+    attribute :description, Shale::Type::String
+
+    # @!attribute [rw] all_nba_team_number
+    #   Returns the All-NBA team number (1st, 2nd, 3rd)
+    #   @api public
+    #   @example
+    #     award.all_nba_team_number #=> 1
+    #   @return [Integer] the team number
+    attribute :all_nba_team_number, Shale::Type::Integer
+
+    # @!attribute [rw] season
+    #   Returns the season
+    #   @api public
+    #   @example
+    #     award.season #=> "2023-24"
+    #   @return [String] the season
+    attribute :season, Shale::Type::String
+
+    # @!attribute [rw] month
+    #   Returns the month (for monthly awards)
+    #   @api public
+    #   @example
+    #     award.month #=> 11
+    #   @return [Integer] the month
+    attribute :month, Shale::Type::Integer
+
+    # @!attribute [rw] week
+    #   Returns the week (for weekly awards)
+    #   @api public
+    #   @example
+    #     award.week #=> 5
+    #   @return [Integer] the week
+    attribute :week, Shale::Type::Integer
+
+    # @!attribute [rw] conference
+    #   Returns the conference
+    #   @api public
+    #   @example
+    #     award.conference #=> "West"
+    #   @return [String] the conference
+    attribute :conference, Shale::Type::String
+
+    # @!attribute [rw] award_type
+    #   Returns the award type
+    #   @api public
+    #   @example
+    #     award.award_type #=> "All-Star"
+    #   @return [String] the award type
+    attribute :award_type, Shale::Type::String
+
+    # @!attribute [rw] subtype1
+    #   Returns the award subtype 1
+    #   @api public
+    #   @example
+    #     award.subtype1 #=> "Guard"
+    #   @return [String] the subtype
+    attribute :subtype1, Shale::Type::String
+
+    # @!attribute [rw] subtype2
+    #   Returns the award subtype 2
+    #   @api public
+    #   @example
+    #     award.subtype2 #=> "Starter"
+    #   @return [String] the subtype
+    attribute :subtype2, Shale::Type::String
+
+    # @!attribute [rw] subtype3
+    #   Returns the award subtype 3
+    #   @api public
+    #   @example
+    #     award.subtype3 #=> nil
+    #   @return [String] the subtype
+    attribute :subtype3, Shale::Type::String
+
+    # Returns the player object
+    #
+    # @api public
+    # @example
+    #   award.player #=> #<NBA::Player>
+    # @return [Player, nil] the player object
+    def player
+      Players.find(player_id)
+    end
+  end
+end

data/lib/nba/box_score.rb

@@ -0,0 +1,2 @@
+require_relative "box_score_player_stat"
+require_relative "box_score_team_stat"

data/lib/nba/box_score_advanced.rb

@@ -0,0 +1,114 @@
+require_relative "box_score_advanced_player_stat"
+require_relative "box_score_advanced_team_stat"
+require_relative "client"
+require_relative "response_parser"
+require_relative "utils"
+
+module NBA
+  # Provides methods to retrieve advanced box score statistics
+  module BoxScoreAdvanced
+    # Result set name for player stats
+    # @return [String] the result set name
+    PLAYER_STATS = "PlayerStats".freeze
+
+    # Result set name for team stats
+    # @return [String] the result set name
+    TEAM_STATS = "TeamStats".freeze
+
+    # Retrieves player advanced box score stats for a game
+    #
+    # @api public
+    # @example
+    #   stats = NBA::BoxScoreAdvanced.player_stats(game: "0022400001")
+    #   stats.each { |s| puts "#{s.player_name}: #{s.off_rating} ORTG" }
+    # @param game [String, Game] the game ID or Game object
+    # @param client [Client] the API client to use
+    # @return [Collection] a collection of player advanced box score stats
+    def self.player_stats(game:, client: CLIENT)
+      path = "boxscoreadvancedv2?GameID=#{Utils.extract_id(game)}"
+      ResponseParser.parse(client.get(path), result_set: PLAYER_STATS) { |data| build_player_stat(data) }
+    end
+
+    # Retrieves team advanced box score stats for a game
+    #
+    # @api public
+    # @example
+    #   stats = NBA::BoxScoreAdvanced.team_stats(game: "0022400001")
+    #   stats.each { |s| puts "#{s.team_name}: #{s.off_rating} ORTG" }
+    # @param game [String, Game] the game ID or Game object
+    # @param client [Client] the API client to use
+    # @return [Collection] a collection of team advanced box score stats
+    def self.team_stats(game:, client: CLIENT)
+      path = "boxscoreadvancedv2?GameID=#{Utils.extract_id(game)}"
+      ResponseParser.parse(client.get(path), result_set: TEAM_STATS) { |data| build_team_stat(data) }
+    end
+
+    # Builds a player stat object from API data
+    # @api private
+    # @return [BoxScoreAdvancedPlayerStat]
+    def self.build_player_stat(data)
+      BoxScoreAdvancedPlayerStat.new(**player_identity(data), **rating_stats(data),
+        **efficiency_stats(data), **tempo_stats(data), usg_pct: data["USG_PCT"], e_usg_pct: data["E_USG_PCT"])
+    end
+    private_class_method :build_player_stat
+
+    # Builds a team stat object from API data
+    # @api private
+    # @return [BoxScoreAdvancedTeamStat]
+    def self.build_team_stat(data)
+      BoxScoreAdvancedTeamStat.new(**team_identity(data), **rating_stats(data),
+        **efficiency_stats(data), **tempo_stats(data))
+    end
+    private_class_method :build_team_stat
+
+    # Extracts player identity attributes from data
+    # @api private
+    # @return [Hash]
+    def self.player_identity(data)
+      {game_id: data["GAME_ID"], team_id: data["TEAM_ID"], team_abbreviation: data["TEAM_ABBREVIATION"],
+       team_city: data["TEAM_CITY"], player_id: data["PLAYER_ID"], player_name: data["PLAYER_NAME"],
+       start_position: data["START_POSITION"], comment: data["COMMENT"], min: data["MIN"]}
+    end
+    private_class_method :player_identity
+
+    # Extracts team identity attributes from data
+    # @api private
+    # @return [Hash]
+    def self.team_identity(data)
+      {game_id: data["GAME_ID"], team_id: data["TEAM_ID"], team_name: data["TEAM_NAME"],
+       team_abbreviation: data["TEAM_ABBREVIATION"], team_city: data["TEAM_CITY"], min: data["MIN"]}
+    end
+    private_class_method :team_identity
+
+    # Extracts rating statistics from data
+    # @api private
+    # @return [Hash]
+    def self.rating_stats(data)
+      {e_off_rating: data["E_OFF_RATING"], off_rating: data["OFF_RATING"],
+       e_def_rating: data["E_DEF_RATING"], def_rating: data["DEF_RATING"],
+       e_net_rating: data["E_NET_RATING"], net_rating: data["NET_RATING"]}
+    end
+    private_class_method :rating_stats
+
+    # Extracts efficiency statistics from data
+    # @api private
+    # @return [Hash]
+    def self.efficiency_stats(data)
+      {ast_pct: data["AST_PCT"], ast_tov: data["AST_TOV"],
+       ast_ratio: data["AST_RATIO"], oreb_pct: data["OREB_PCT"],
+       dreb_pct: data["DREB_PCT"], reb_pct: data["REB_PCT"],
+       tov_pct: data["TM_TOV_PCT"], efg_pct: data["EFG_PCT"],
+       ts_pct: data["TS_PCT"], pie: data["PIE"]}
+    end
+    private_class_method :efficiency_stats
+
+    # Extracts tempo statistics from data
+    # @api private
+    # @return [Hash]
+    def self.tempo_stats(data)
+      {e_pace: data["E_PACE"], pace: data["PACE"], pace_per40: data["PACE_PER40"],
+       poss: data["POSS"]}
+    end
+    private_class_method :tempo_stats
+  end
+end