nba 0.1.1 → 0.2.0

data/lib/nba/team_season_rank.rb

@@ -0,0 +1,110 @@
+require "equalizer"
+require "shale"
+require_relative "teams"
+
+module NBA
+  # Represents team season rankings from the TeamInfoCommon endpoint
+  #
+  # @api public
+  class TeamSeasonRank < Shale::Mapper
+    include Equalizer.new(:team_id, :season_id)
+
+    # @!attribute [rw] league_id
+    #   Returns the league ID
+    #   @api public
+    #   @example
+    #     rank.league_id #=> "00"
+    #   @return [String, nil] the league ID
+    attribute :league_id, Shale::Type::String
+
+    # @!attribute [rw] season_id
+    #   Returns the season ID
+    #   @api public
+    #   @example
+    #     rank.season_id #=> "2024-25"
+    #   @return [String, nil] the season ID
+    attribute :season_id, Shale::Type::String
+
+    # @!attribute [rw] team_id
+    #   Returns the team ID
+    #   @api public
+    #   @example
+    #     rank.team_id #=> 1610612744
+    #   @return [Integer, nil] the team's ID
+    attribute :team_id, Shale::Type::Integer
+
+    # @!attribute [rw] pts_rank
+    #   Returns the points per game rank
+    #   @api public
+    #   @example
+    #     rank.pts_rank #=> 5
+    #   @return [Integer, nil] the points rank
+    attribute :pts_rank, Shale::Type::Integer
+
+    # @!attribute [rw] pts_pg
+    #   Returns the points per game
+    #   @api public
+    #   @example
+    #     rank.pts_pg #=> 118.9
+    #   @return [Float, nil] the points per game
+    attribute :pts_pg, Shale::Type::Float
+
+    # @!attribute [rw] reb_rank
+    #   Returns the rebounds per game rank
+    #   @api public
+    #   @example
+    #     rank.reb_rank #=> 12
+    #   @return [Integer, nil] the rebounds rank
+    attribute :reb_rank, Shale::Type::Integer
+
+    # @!attribute [rw] reb_pg
+    #   Returns the rebounds per game
+    #   @api public
+    #   @example
+    #     rank.reb_pg #=> 44.2
+    #   @return [Float, nil] the rebounds per game
+    attribute :reb_pg, Shale::Type::Float
+
+    # @!attribute [rw] ast_rank
+    #   Returns the assists per game rank
+    #   @api public
+    #   @example
+    #     rank.ast_rank #=> 3
+    #   @return [Integer, nil] the assists rank
+    attribute :ast_rank, Shale::Type::Integer
+
+    # @!attribute [rw] ast_pg
+    #   Returns the assists per game
+    #   @api public
+    #   @example
+    #     rank.ast_pg #=> 28.7
+    #   @return [Float, nil] the assists per game
+    attribute :ast_pg, Shale::Type::Float
+
+    # @!attribute [rw] opp_pts_rank
+    #   Returns the opponent points per game rank
+    #   @api public
+    #   @example
+    #     rank.opp_pts_rank #=> 15
+    #   @return [Integer, nil] the opponent points rank
+    attribute :opp_pts_rank, Shale::Type::Integer
+
+    # @!attribute [rw] opp_pts_pg
+    #   Returns the opponent points per game
+    #   @api public
+    #   @example
+    #     rank.opp_pts_pg #=> 115.2
+    #   @return [Float, nil] the opponent points per game
+    attribute :opp_pts_pg, Shale::Type::Float
+
+    # Returns the team associated with this rank
+    #
+    # @api public
+    # @example
+    #   rank.team #=> #<NBA::Team ...>
+    # @return [Team, nil] the Team object
+    def team
+      Teams.find(team_id)
+    end
+  end
+end

data/lib/nba/team_shot_stat.rb

@@ -0,0 +1,173 @@
+require "equalizer"
+require "shale"
+
+module NBA
+  # Represents team tracking shot statistics
+  #
+  # @api public
+  class TeamShotStat < Shale::Mapper
+    include Equalizer.new(:team_id, :shot_type, :g)
+
+    # @!attribute [rw] team_id
+    #   Returns the team ID
+    #   @api public
+    #   @example
+    #     stat.team_id #=> 1610612744
+    #   @return [Integer, nil] the team's 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, nil] the team's name
+    attribute :team_name, Shale::Type::String
+
+    # @!attribute [rw] team_abbreviation
+    #   Returns the team abbreviation
+    #   @api public
+    #   @example
+    #     stat.team_abbreviation #=> "GSW"
+    #   @return [String, nil] the team abbreviation
+    attribute :team_abbreviation, Shale::Type::String
+
+    # @!attribute [rw] sort_order
+    #   Returns the sort order
+    #   @api public
+    #   @example
+    #     stat.sort_order #=> 1
+    #   @return [Integer, nil] the sort order
+    attribute :sort_order, Shale::Type::Integer
+
+    # @!attribute [rw] g
+    #   Returns number of games
+    #   @api public
+    #   @example
+    #     stat.g #=> 74
+    #   @return [Integer, nil] games
+    attribute :g, Shale::Type::Integer
+
+    # @!attribute [rw] shot_type
+    #   Returns the shot type or category
+    #   @api public
+    #   @example
+    #     stat.shot_type #=> "Catch and Shoot"
+    #   @return [String, nil] the shot type or category
+    attribute :shot_type, Shale::Type::String
+
+    # @!attribute [rw] fga_frequency
+    #   Returns field goal attempt frequency
+    #   @api public
+    #   @example
+    #     stat.fga_frequency #=> 0.35
+    #   @return [Float, nil] field goal attempt frequency
+    attribute :fga_frequency, Shale::Type::Float
+
+    # @!attribute [rw] fgm
+    #   Returns field goals made
+    #   @api public
+    #   @example
+    #     stat.fgm #=> 7.2
+    #   @return [Float, nil] field goals made
+    attribute :fgm, Shale::Type::Float
+
+    # @!attribute [rw] fga
+    #   Returns field goals attempted
+    #   @api public
+    #   @example
+    #     stat.fga #=> 15.3
+    #   @return [Float, nil] field goals attempted
+    attribute :fga, Shale::Type::Float
+
+    # @!attribute [rw] fg_pct
+    #   Returns field goal percentage
+    #   @api public
+    #   @example
+    #     stat.fg_pct #=> 0.472
+    #   @return [Float, nil] field goal percentage
+    attribute :fg_pct, Shale::Type::Float
+
+    # @!attribute [rw] efg_pct
+    #   Returns effective field goal percentage
+    #   @api public
+    #   @example
+    #     stat.efg_pct #=> 0.561
+    #   @return [Float, nil] effective field goal percentage
+    attribute :efg_pct, Shale::Type::Float
+
+    # @!attribute [rw] fg2a_frequency
+    #   Returns 2-point field goal attempt frequency
+    #   @api public
+    #   @example
+    #     stat.fg2a_frequency #=> 0.45
+    #   @return [Float, nil] 2-point field goal attempt frequency
+    attribute :fg2a_frequency, Shale::Type::Float
+
+    # @!attribute [rw] fg2m
+    #   Returns 2-point field goals made
+    #   @api public
+    #   @example
+    #     stat.fg2m #=> 4.1
+    #   @return [Float, nil] 2-point field goals made
+    attribute :fg2m, Shale::Type::Float
+
+    # @!attribute [rw] fg2a
+    #   Returns 2-point field goals attempted
+    #   @api public
+    #   @example
+    #     stat.fg2a #=> 7.8
+    #   @return [Float, nil] 2-point field goals attempted
+    attribute :fg2a, Shale::Type::Float
+
+    # @!attribute [rw] fg2_pct
+    #   Returns 2-point field goal percentage
+    #   @api public
+    #   @example
+    #     stat.fg2_pct #=> 0.526
+    #   @return [Float, nil] 2-point field goal percentage
+    attribute :fg2_pct, Shale::Type::Float
+
+    # @!attribute [rw] fg3a_frequency
+    #   Returns 3-point field goal attempt frequency
+    #   @api public
+    #   @example
+    #     stat.fg3a_frequency #=> 0.55
+    #   @return [Float, nil] 3-point field goal attempt frequency
+    attribute :fg3a_frequency, Shale::Type::Float
+
+    # @!attribute [rw] fg3m
+    #   Returns 3-point field goals made
+    #   @api public
+    #   @example
+    #     stat.fg3m #=> 4.8
+    #   @return [Float, nil] 3-point field goals made
+    attribute :fg3m, Shale::Type::Float
+
+    # @!attribute [rw] fg3a
+    #   Returns 3-point field goals attempted
+    #   @api public
+    #   @example
+    #     stat.fg3a #=> 11.2
+    #   @return [Float, nil] 3-point field goals attempted
+    attribute :fg3a, Shale::Type::Float
+
+    # @!attribute [rw] fg3_pct
+    #   Returns 3-point field goal percentage
+    #   @api public
+    #   @example
+    #     stat.fg3_pct #=> 0.428
+    #   @return [Float, nil] 3-point field goal percentage
+    attribute :fg3_pct, Shale::Type::Float
+
+    # Returns the team associated with this stat
+    #
+    # @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_vs_player.rb

@@ -0,0 +1,151 @@
+require "json"
+require_relative "client"
+require_relative "collection"
+require_relative "team_vs_player_stat"
+require_relative "utils"
+
+module NBA
+  # Provides methods to retrieve team vs player statistics
+  #
+  # @api public
+  module TeamVsPlayer
+    # Result set name for overall comparison
+    # @return [String] the result set name
+    OVERALL = "Overall".freeze
+
+    # Result set name for on/off court comparison
+    # @return [String] the result set name
+    ON_OFF_COURT = "OnOffCourt".freeze
+
+    # Retrieves overall comparison statistics for team vs player
+    #
+    # @api public
+    # @example
+    #   stats = NBA::TeamVsPlayer.overall(team: 1610612744, vs_player: 201566)
+    #   stats.first.pts #=> 106.4
+    # @param team [Integer, Team] the team ID or Team object
+    # @param vs_player [Integer, Player] the vs player ID or Player 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 vs player statistics
+    def self.overall(team:, vs_player:, season: Utils.current_season, season_type: "Regular Season",
+      per_mode: "PerGame", client: CLIENT)
+      options = {season_type: season_type, per_mode: per_mode, result_set: OVERALL}
+      fetch_stats(team, vs_player, season, options, client: client)
+    end
+
+    # Retrieves on/off court comparison statistics for team vs player
+    #
+    # @api public
+    # @example
+    #   stats = NBA::TeamVsPlayer.on_off_court(team: 1610612744, vs_player: 201566)
+    #   stats.each { |s| puts "#{s.court_status}: #{s.pts}" }
+    # @param team [Integer, Team] the team ID or Team object
+    # @param vs_player [Integer, Player] the vs player ID or Player 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 vs player statistics
+    def self.on_off_court(team:, vs_player:, season: Utils.current_season, season_type: "Regular Season",
+      per_mode: "PerGame", client: CLIENT)
+      options = {season_type: season_type, per_mode: per_mode, result_set: ON_OFF_COURT}
+      fetch_stats(team, vs_player, season, options, client: client)
+    end
+
+    # Fetches team vs player statistics from the API
+    #
+    # @api private
+    # @return [Collection] the collection of statistics
+    def self.fetch_stats(team, vs_player, season, options, client:)
+      path = build_path(team, vs_player, season, options.fetch(:season_type), options.fetch(:per_mode))
+      response = client.get(path)
+      parse_response(response, options.fetch(:result_set))
+    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, vs_player, season, season_type, per_mode)
+      team_id = Utils.extract_id(team)
+      vs_player_id = Utils.extract_id(vs_player)
+      season_str = Utils.format_season(season)
+      "teamvsplayer?TeamID=#{team_id}&VsPlayerID=#{vs_player_id}&Season=#{season_str}" \
+        "&SeasonType=#{season_type}&PerMode=#{per_mode}&LeagueID=00"
+    end
+    private_class_method :build_path
+
+    # Parses the API response and extracts the result set
+    #
+    # @api private
+    # @return [Collection] the collection of statistics
+    def self.parse_response(response, result_set_name)
+      return Collection.new if response.nil? || response.empty?
+
+      data = JSON.parse(response)
+      result_set = find_result_set(data, result_set_name)
+      build_collection(result_set)
+    end
+    private_class_method :parse_response
+
+    # Finds the result set matching the given name
+    #
+    # @api private
+    # @return [Hash, nil] the result set hash or nil
+    def self.find_result_set(data, result_set_name)
+      result_sets = data["resultSets"]
+      return unless result_sets
+
+      result_sets.find { |rs| rs["name"].eql?(result_set_name) }
+    end
+    private_class_method :find_result_set
+
+    # Builds a collection from the result set data
+    #
+    # @api private
+    # @return [Collection] the collection of statistics
+    def self.build_collection(result_set)
+      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_team_vs_player_stat(headers.zip(row).to_h) })
+    end
+    private_class_method :build_collection
+
+    # Builds a stat object from the data hash
+    #
+    # @api private
+    # @return [TeamVsPlayerStat] the stat object
+    def self.build_team_vs_player_stat(data)
+      TeamVsPlayerStat.new(**identity_info(data), **stat_info(data))
+    end
+    private_class_method :build_team_vs_player_stat
+
+    # Extracts identity information from the data hash
+    #
+    # @api private
+    # @return [Hash] the identity attributes
+    def self.identity_info(data)
+      {team_id: data["TEAM_ID"], vs_player_id: data["VS_PLAYER_ID"],
+       court_status: data["COURT_STATUS"], gp: data["GP"], min: data["MIN"]}
+    end
+    private_class_method :identity_info
+
+    # Extracts stat information from the data hash
+    #
+    # @api private
+    # @return [Hash] the stat attributes
+    def self.stat_info(data)
+      {pts: data["PTS"], reb: data["REB"], ast: data["AST"], stl: data["STL"],
+       blk: data["BLK"], tov: data["TOV"], fg_pct: data["FG_PCT"], plus_minus: data["PLUS_MINUS"]}
+    end
+    private_class_method :stat_info
+  end
+end

data/lib/nba/team_vs_player_stat.rb

@@ -0,0 +1,157 @@
+require "equalizer"
+require "shale"
+require_relative "players"
+require_relative "teams"
+
+module NBA
+  # Represents team vs player comparison statistics
+  #
+  # @api public
+  class TeamVsPlayerStat < Shale::Mapper
+    include Equalizer.new(:team_id, :vs_player_id)
+
+    # @!attribute [rw] team_id
+    #   Returns the team ID
+    #   @api public
+    #   @example
+    #     stat.team_id #=> 1610612744
+    #   @return [Integer, nil] the team's ID
+    attribute :team_id, Shale::Type::Integer
+
+    # @!attribute [rw] vs_player_id
+    #   Returns the vs player ID
+    #   @api public
+    #   @example
+    #     stat.vs_player_id #=> 201566
+    #   @return [Integer, nil] the vs player's ID
+    attribute :vs_player_id, Shale::Type::Integer
+
+    # @!attribute [rw] court_status
+    #   Returns the on/off court status
+    #   @api public
+    #   @example
+    #     stat.court_status #=> "On"
+    #   @return [String, nil] on/off court status
+    attribute :court_status, Shale::Type::String
+
+    # @!attribute [rw] gp
+    #   Returns games played
+    #   @api public
+    #   @example
+    #     stat.gp #=> 24
+    #   @return [Integer, nil] games played
+    attribute :gp, Shale::Type::Integer
+
+    # @!attribute [rw] min
+    #   Returns minutes played
+    #   @api public
+    #   @example
+    #     stat.min #=> 32.5
+    #   @return [Float, nil] minutes played
+    attribute :min, Shale::Type::Float
+
+    # @!attribute [rw] pts
+    #   Returns points
+    #   @api public
+    #   @example
+    #     stat.pts #=> 26.4
+    #   @return [Float, nil] points
+    attribute :pts, Shale::Type::Float
+
+    # @!attribute [rw] reb
+    #   Returns rebounds
+    #   @api public
+    #   @example
+    #     stat.reb #=> 5.7
+    #   @return [Float, nil] rebounds
+    attribute :reb, Shale::Type::Float
+
+    # @!attribute [rw] ast
+    #   Returns assists
+    #   @api public
+    #   @example
+    #     stat.ast #=> 6.1
+    #   @return [Float, nil] assists
+    attribute :ast, Shale::Type::Float
+
+    # @!attribute [rw] stl
+    #   Returns steals
+    #   @api public
+    #   @example
+    #     stat.stl #=> 1.2
+    #   @return [Float, nil] steals
+    attribute :stl, Shale::Type::Float
+
+    # @!attribute [rw] blk
+    #   Returns blocks
+    #   @api public
+    #   @example
+    #     stat.blk #=> 0.3
+    #   @return [Float, nil] blocks
+    attribute :blk, Shale::Type::Float
+
+    # @!attribute [rw] tov
+    #   Returns turnovers
+    #   @api public
+    #   @example
+    #     stat.tov #=> 3.1
+    #   @return [Float, nil] turnovers
+    attribute :tov, Shale::Type::Float
+
+    # @!attribute [rw] fg_pct
+    #   Returns field goal percentage
+    #   @api public
+    #   @example
+    #     stat.fg_pct #=> 0.467
+    #   @return [Float, nil] field goal percentage
+    attribute :fg_pct, Shale::Type::Float
+
+    # @!attribute [rw] plus_minus
+    #   Returns plus/minus
+    #   @api public
+    #   @example
+    #     stat.plus_minus #=> 8.5
+    #   @return [Float, nil] plus/minus
+    attribute :plus_minus, Shale::Type::Float
+
+    # Returns the team
+    #
+    # @api public
+    # @example
+    #   stat.team #=> #<NBA::Team id=1610612744 ...>
+    # @return [Team, nil] the team object
+    def team
+      Teams.find(team_id)
+    end
+
+    # Returns the vs player
+    #
+    # @api public
+    # @example
+    #   stat.vs_player #=> #<NBA::Player id=201566 ...>
+    # @return [Player, nil] the vs player object
+    def vs_player
+      Players.find(vs_player_id)
+    end
+
+    # Returns whether the player is on court
+    #
+    # @api public
+    # @example
+    #   stat.on_court? #=> true
+    # @return [Boolean] true if player is on court
+    def on_court?
+      court_status.eql?("On")
+    end
+
+    # Returns whether the player is off court
+    #
+    # @api public
+    # @example
+    #   stat.off_court? #=> true
+    # @return [Boolean] true if player is off court
+    def off_court?
+      court_status.eql?("Off")
+    end
+  end
+end

data/lib/nba/team_year.rb

@@ -0,0 +1,55 @@
+require "equalizer"
+require "shale"
+
+module NBA
+  # Represents a year/season a team participated in the league
+  class TeamYear < Shale::Mapper
+    include Equalizer.new(:team_id, :year)
+
+    # @!attribute [rw] team_id
+    #   Returns the team ID
+    #   @api public
+    #   @example
+    #     team_year.team_id #=> 1610612744
+    #   @return [Integer] the team ID
+    attribute :team_id, Shale::Type::Integer
+
+    # @!attribute [rw] year
+    #   Returns the year
+    #   @api public
+    #   @example
+    #     team_year.year #=> 2024
+    #   @return [Integer] the year
+    attribute :year, Shale::Type::Integer
+
+    # @!attribute [rw] abbreviation
+    #   Returns the team abbreviation for that year
+    #   @api public
+    #   @example
+    #     team_year.abbreviation #=> "GSW"
+    #   @return [String] the abbreviation
+    attribute :abbreviation, Shale::Type::String
+
+    # Returns the team object
+    #
+    # @api public
+    # @example
+    #   team_year.team #=> #<NBA::Team>
+    # @return [Team, nil] the team object
+    def team
+      Teams.find(team_id)
+    end
+
+    # Returns the season string
+    #
+    # @api public
+    # @example
+    #   team_year.season #=> "2024-25"
+    # @return [String, nil] the season string
+    def season
+      return unless year
+
+      Utils.format_season(year)
+    end
+  end
+end