nba 0.1.1 → 0.2.0

data/lib/nba/player_profile_v2.rb

@@ -0,0 +1,169 @@
+require "json"
+require_relative "client"
+require_relative "collection"
+require_relative "career_stats"
+require_relative "utils"
+
+module NBA
+  # Provides methods to retrieve comprehensive player profile data
+  #
+  # @api public
+  module PlayerProfileV2
+    # Regular season result set name
+    # @return [String] the result set name
+    CAREER_REGULAR_SEASON = "CareerTotalsRegularSeason".freeze
+
+    # Post season result set name
+    # @return [String] the result set name
+    CAREER_POST_SEASON = "CareerTotalsPostSeason".freeze
+
+    # Season totals regular season result set name
+    # @return [String] the result set name
+    SEASON_REGULAR_SEASON = "SeasonTotalsRegularSeason".freeze
+
+    # Season totals post season result set name
+    # @return [String] the result set name
+    SEASON_POST_SEASON = "SeasonTotalsPostSeason".freeze
+
+    # Retrieves career regular season totals for a player
+    #
+    # @api public
+    # @example
+    #   stats = NBA::PlayerProfileV2.career_regular_season(player: 201939)
+    # @param player [Integer, Player] the player ID or Player object
+    # @param client [Client] the API client to use
+    # @return [Collection] career regular season totals
+    def self.career_regular_season(player:, client: CLIENT)
+      fetch_stats(player, CAREER_REGULAR_SEASON, client: client)
+    end
+
+    # Retrieves career post season totals for a player
+    #
+    # @api public
+    # @example
+    #   stats = NBA::PlayerProfileV2.career_post_season(player: 201939)
+    # @param player [Integer, Player] the player ID or Player object
+    # @param client [Client] the API client to use
+    # @return [Collection] career post season totals
+    def self.career_post_season(player:, client: CLIENT)
+      fetch_stats(player, CAREER_POST_SEASON, client: client)
+    end
+
+    # Retrieves season-by-season regular season totals for a player
+    #
+    # @api public
+    # @example
+    #   stats = NBA::PlayerProfileV2.season_regular_season(player: 201939)
+    # @param player [Integer, Player] the player ID or Player object
+    # @param client [Client] the API client to use
+    # @return [Collection] season-by-season regular season totals
+    def self.season_regular_season(player:, client: CLIENT)
+      fetch_stats(player, SEASON_REGULAR_SEASON, client: client)
+    end
+
+    # Retrieves season-by-season post season totals for a player
+    #
+    # @api public
+    # @example
+    #   stats = NBA::PlayerProfileV2.season_post_season(player: 201939)
+    # @param player [Integer, Player] the player ID or Player object
+    # @param client [Client] the API client to use
+    # @return [Collection] season-by-season post season totals
+    def self.season_post_season(player:, client: CLIENT)
+      fetch_stats(player, SEASON_POST_SEASON, client: client)
+    end
+
+    # Fetches stats from a specific result set
+    #
+    # @api private
+    # @return [Collection] the stats collection
+    def self.fetch_stats(player, result_set_name, client:)
+      player_id = Utils.extract_id(player)
+      path = "playerprofilev2?PlayerID=#{player_id}&PerMode=PerGame"
+      response = client.get(path)
+      parse_result_set(response, result_set_name, player_id)
+    end
+    private_class_method :fetch_stats
+
+    # Parses a specific result set from the response
+    #
+    # @api private
+    # @return [Collection] the parsed stats collection
+    def self.parse_result_set(response, result_set_name, player_id)
+      return Collection.new if response.nil? || response.empty?
+
+      result_set = find_result_set(JSON.parse(response), result_set_name)
+      build_collection(result_set, player_id)
+    end
+    private_class_method :parse_result_set
+
+    # Finds a result set by name
+    #
+    # @api private
+    # @return [Hash, nil] the result set hash or nil if not found
+    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 a result set
+    #
+    # @api private
+    # @return [Collection] the stats collection
+    def self.build_collection(result_set, player_id)
+      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_stats(headers.zip(row).to_h, player_id) })
+    end
+    private_class_method :build_collection
+
+    # Builds career stats from API data
+    #
+    # @api private
+    # @return [CareerStats] the career stats object
+    def self.build_stats(data, player_id)
+      CareerStats.new(**season_info(data, player_id), **shooting_stats(data), **counting_stats(data))
+    end
+    private_class_method :build_stats
+
+    # Extracts season information from data
+    #
+    # @api private
+    # @return [Hash] the season information hash
+    def self.season_info(data, player_id)
+      {player_id: player_id, season_id: data["SEASON_ID"], team_id: data["TEAM_ID"],
+       team_abbreviation: data["TEAM_ABBREVIATION"], player_age: data["PLAYER_AGE"],
+       gp: data["GP"], gs: data["GS"], min: data["MIN"]}
+    end
+    private_class_method :season_info
+
+    # Extracts shooting statistics from data
+    #
+    # @api private
+    # @return [Hash] the shooting statistics hash
+    def self.shooting_stats(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_stats
+
+    # Extracts counting statistics from data
+    #
+    # @api private
+    # @return [Hash] the counting statistics hash
+    def self.counting_stats(data)
+      {oreb: data["OREB"], dreb: data["DREB"], reb: data["REB"],
+       ast: data["AST"], stl: data["STL"], blk: data["BLK"],
+       tov: data["TOV"], pf: data["PF"], pts: data["PTS"]}
+    end
+    private_class_method :counting_stats
+  end
+end

data/lib/nba/player_vs_player.rb

@@ -0,0 +1,153 @@
+require "json"
+require_relative "client"
+require_relative "collection"
+require_relative "vs_player_stat"
+require_relative "utils"
+
+module NBA
+  # Provides methods to retrieve player vs player statistics
+  #
+  # @api public
+  module PlayerVsPlayer
+    # 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 between two players
+    #
+    # @api public
+    # @example
+    #   stats = NBA::PlayerVsPlayer.overall(player: 201939, vs_player: 201566)
+    #   stats.first.pts #=> 26.4
+    # @param player [Integer, Player] the player ID or Player 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 vs player statistics
+    def self.overall(player:, 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(player, vs_player, season, options, client: client)
+    end
+
+    # Retrieves on/off court comparison statistics between two players
+    #
+    # @api public
+    # @example
+    #   stats = NBA::PlayerVsPlayer.on_off_court(player: 201939, vs_player: 201566)
+    #   stats.each { |s| puts "#{s.court_status}: #{s.pts}" }
+    # @param player [Integer, Player] the player ID or Player 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 vs player statistics
+    def self.on_off_court(player:, 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(player, vs_player, season, options, client: client)
+    end
+
+    # Fetches vs player stats from the API
+    #
+    # @api private
+    # @return [Collection] collection of vs player stats
+    def self.fetch_stats(player, vs_player, season, options, client:)
+      path = build_path(player, 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 path
+    #
+    # @api private
+    # @return [String] the request path
+    def self.build_path(player, vs_player, season, season_type, per_mode)
+      player_id = Utils.extract_id(player)
+      vs_player_id = Utils.extract_id(vs_player)
+      season_str = Utils.format_season(season)
+      "playervsplayer?PlayerID=#{player_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 into vs player stat objects
+    #
+    # @api private
+    # @return [Collection] collection of vs player stats
+    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 a result set by name
+    #
+    # @api private
+    # @return [Hash, nil] the result set hash or nil if not found
+    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 a result set
+    #
+    # @api private
+    # @return [Collection] the stats collection
+    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_vs_player_stat(headers.zip(row).to_h) })
+    end
+    private_class_method :build_collection
+
+    # Builds a vs player stat from API data
+    #
+    # @api private
+    # @return [VsPlayerStat] the vs player stat object
+    def self.build_vs_player_stat(data)
+      VsPlayerStat.new(**identity_info(data), **stat_info(data))
+    end
+    private_class_method :build_vs_player_stat
+
+    # Extracts identity information from data
+    #
+    # @api private
+    # @return [Hash] the identity information hash
+    def self.identity_info(data)
+      {player_id: data["PLAYER_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 data
+    #
+    # @api private
+    # @return [Hash] the stat information hash
+    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/players.rb

@@ -0,0 +1,107 @@
+require_relative "client"
+require_relative "response_parser"
+require_relative "player"
+require_relative "utils"
+
+module NBA
+  # Provides methods to retrieve NBA players
+  module Players
+    # Retrieves all NBA players
+    #
+    # @api public
+    # @example
+    #   players = NBA::Players.all
+    #   players.each { |player| puts player.full_name }
+    # @param season [Integer] the season year (defaults to current season)
+    # @param only_current [Boolean] whether to only return current players
+    # @param client [Client] the API client to use
+    # @return [Collection] a collection of all players
+    def self.all(season: Utils.current_season, only_current: true, client: CLIENT)
+      current_flag = only_current ? 1 : 0
+      path = "commonallplayers?LeagueID=00&Season=#{Utils.format_season(season)}&IsOnlyCurrentSeason=#{current_flag}"
+      ResponseParser.parse(client.get(path)) { |data| build_player_summary(data) }
+    end
+
+    # Finds a player by ID
+    #
+    # @api public
+    # @example
+    #   roster = NBA::Roster.find(team: NBA::Team::GSW)
+    #   curry = roster.find { |p| p.jersey_number == 30 }
+    #   player = NBA::Players.find(curry.id)
+    # @param player_id [Integer, Player] the player ID or Player object
+    # @param client [Client] the API client to use
+    # @return [Player, nil] the player with the given ID, or nil if not found
+    def self.find(player_id, client: CLIENT)
+      id = Utils.extract_id(player_id)
+      return unless id
+
+      path = "commonplayerinfo?PlayerID=#{id}"
+      ResponseParser.parse_single(client.get(path)) { |data| build_player_detail(data) }
+    end
+
+    # Builds a player summary from list data
+    #
+    # @api private
+    # @param data [Hash] the player row data
+    # @return [Player] the player object
+    def self.build_player_summary(data)
+      full_name = data["DISPLAY_FIRST_LAST"]
+      Player.new(
+        id: data["PERSON_ID"],
+        full_name: full_name,
+        first_name: full_name&.split&.first,
+        last_name: full_name&.split&.last,
+        is_active: [1, "Active"].include?(data["ROSTERSTATUS"])
+      )
+    end
+    private_class_method :build_player_summary
+
+    # Builds a player detail from API data
+    # @api private
+    # @return [Player]
+    def self.build_player_detail(data)
+      Player.new(**identity_info(data), **physical_info(data), **draft_info(data))
+    end
+    private_class_method :build_player_detail
+
+    # Extracts identity information from data
+    # @api private
+    # @return [Hash]
+    def self.identity_info(data)
+      {id: data["PERSON_ID"], full_name: data["DISPLAY_FIRST_LAST"],
+       first_name: data["FIRST_NAME"], last_name: data["LAST_NAME"],
+       is_active: [1, "Active"].include?(data["ROSTERSTATUS"])}
+    end
+    private_class_method :identity_info
+
+    # Extracts physical information from data
+    # @api private
+    # @return [Hash]
+    def self.physical_info(data)
+      {jersey_number: Utils.parse_integer(data["JERSEY"]), height: data["HEIGHT"],
+       weight: Utils.parse_integer(data["WEIGHT"]), college: data["SCHOOL"],
+       country: data["COUNTRY"], position: build_position(data["POSITION"])}
+    end
+    private_class_method :physical_info
+
+    # Builds a position from name
+    # @api private
+    # @return [Position, nil]
+    def self.build_position(name)
+      return unless name
+
+      Position.new(name: name)
+    end
+    private_class_method :build_position
+
+    # Extracts draft information from data
+    # @api private
+    # @return [Hash]
+    def self.draft_info(data)
+      {draft_year: Utils.parse_integer(data["DRAFT_YEAR"]), draft_round: Utils.parse_integer(data["DRAFT_ROUND"]),
+       draft_number: Utils.parse_integer(data["DRAFT_NUMBER"])}
+    end
+    private_class_method :draft_info
+  end
+end

data/lib/nba/playoff_matchup.rb

@@ -0,0 +1,84 @@
+require "shale"
+require "equalizer"
+
+module NBA
+  # Represents a playoff matchup in the playoff picture
+  #
+  # @api public
+  # @example
+  #   matchup.conference #=> "East"
+  #   matchup.high_seed_team #=> "Boston Celtics"
+  class PlayoffMatchup < Shale::Mapper
+    include Equalizer.new(:conference, :high_seed_team_id, :low_seed_team_id)
+
+    #   Returns the conference name
+    #   @api public
+    #   @example
+    #     matchup.conference #=> "East"
+    #   @return [String, nil] the conference name
+    attribute :conference, Shale::Type::String
+
+    #   Returns the high seed ranking
+    #   @api public
+    #   @example
+    #     matchup.high_seed_rank #=> 1
+    #   @return [Integer, nil] the high seed ranking
+    attribute :high_seed_rank, Shale::Type::Integer
+
+    #   Returns the high seed team name
+    #   @api public
+    #   @example
+    #     matchup.high_seed_team #=> "Boston Celtics"
+    #   @return [String, nil] the high seed team name
+    attribute :high_seed_team, Shale::Type::String
+
+    #   Returns the high seed team ID
+    #   @api public
+    #   @example
+    #     matchup.high_seed_team_id #=> 1610612738
+    #   @return [Integer, nil] the high seed team ID
+    attribute :high_seed_team_id, Shale::Type::Integer
+
+    #   Returns the low seed ranking
+    #   @api public
+    #   @example
+    #     matchup.low_seed_rank #=> 8
+    #   @return [Integer, nil] the low seed ranking
+    attribute :low_seed_rank, Shale::Type::Integer
+
+    #   Returns the low seed team name
+    #   @api public
+    #   @example
+    #     matchup.low_seed_team #=> "Miami Heat"
+    #   @return [String, nil] the low seed team name
+    attribute :low_seed_team, Shale::Type::String
+
+    #   Returns the low seed team ID
+    #   @api public
+    #   @example
+    #     matchup.low_seed_team_id #=> 1610612748
+    #   @return [Integer, nil] the low seed team ID
+    attribute :low_seed_team_id, Shale::Type::Integer
+
+    #   Returns the high seed series wins
+    #   @api public
+    #   @example
+    #     matchup.high_seed_series_wins #=> 4
+    #   @return [Integer, nil] the high seed series wins
+    attribute :high_seed_series_wins, Shale::Type::Integer
+
+    #   Returns the low seed series wins
+    #   @api public
+    #   @example
+    #     matchup.low_seed_series_wins #=> 1
+    #   @return [Integer, nil] the low seed series wins
+    attribute :low_seed_series_wins, Shale::Type::Integer
+
+    #   Returns the series status description
+    #   @api public
+    #   @example
+    #     matchup.series_status #=> "BOS wins 4-1"
+    #   @return [String, nil] the series status description
+    attribute :series_status, Shale::Type::String
+  end
+end

data/lib/nba/playoff_picture.rb

@@ -0,0 +1,98 @@
+require "json"
+require_relative "client"
+require_relative "collection"
+require_relative "league"
+require_relative "playoff_matchup"
+require_relative "response_parser"
+require_relative "utils"
+
+module NBA
+  # Provides methods to retrieve NBA playoff picture data
+  module PlayoffPicture
+    # Retrieves playoff matchups for both conferences
+    #
+    # @api public
+    # @example
+    #   matchups = NBA::PlayoffPicture.all(season: 2023)
+    #   matchups.each { |m| puts "#{m.high_seed_team} vs #{m.low_seed_team}" }
+    # @param season [Integer] the season year (defaults to current season)
+    # @param league [String, League] the league ID or League object
+    # @param client [Client] the API client to use
+    # @return [Collection] a collection of playoff matchups
+    def self.all(season: Utils.current_season, league: League::NBA, client: CLIENT)
+      league_id = Utils.extract_league_id(league)
+      season_id = Utils.format_season_id(season)
+      path = "playoffpicture?LeagueID=#{league_id}&SeasonID=#{season_id}"
+      response = client.get(path)
+      parse_playoff_picture(response)
+    end
+
+    # Parses the playoff picture response
+    #
+    # @api private
+    # @param response [String] the JSON response body
+    # @return [Collection] a collection of playoff matchups
+    def self.parse_playoff_picture(response)
+      return Collection.new if response.nil? || response.empty?
+
+      data = JSON.parse(response)
+      result_sets = data["resultSets"]
+      return Collection.new unless result_sets
+
+      matchups = []
+      matchups.concat(parse_conference(result_sets, "EastConfPlayoffPicture", "East"))
+      matchups.concat(parse_conference(result_sets, "WestConfPlayoffPicture", "West"))
+      Collection.new(matchups)
+    end
+    private_class_method :parse_playoff_picture
+
+    # Parses a conference result set
+    #
+    # @api private
+    # @param result_sets [Array] all result sets
+    # @param name [String] the result set name to find
+    # @param conference [String] the conference name
+    # @return [Array<PlayoffMatchup>] array of matchups
+    def self.parse_conference(result_sets, name, conference)
+      result_set = result_sets.find { |rs| rs.fetch("name").eql?(name) }
+      return [] unless result_set
+
+      headers = result_set["headers"]
+      rows = result_set["rowSet"]
+      return [] unless headers && rows
+
+      rows.map { |row| build_matchup(headers.zip(row).to_h, conference) }
+    end
+    private_class_method :parse_conference
+
+    # Builds a playoff matchup from data
+    #
+    # @api private
+    # @param data [Hash] the row data
+    # @param conference [String] the conference name
+    # @return [PlayoffMatchup] the matchup object
+    def self.build_matchup(data, conference)
+      PlayoffMatchup.new(**matchup_attributes(data, conference))
+    end
+    private_class_method :build_matchup
+
+    # Extracts matchup attributes from data
+    #
+    # @api private
+    # @param data [Hash] the row data
+    # @param conference [String] the conference name
+    # @return [Hash] matchup attributes
+    def self.matchup_attributes(data, conference)
+      {conference: conference, high_seed_rank: data["HIGH_SEED_RANK"],
+       high_seed_team: data["HIGH_SEED_TEAM"],
+       high_seed_team_id: data["HIGH_SEED_TEAM_ID"],
+       low_seed_rank: data["LOW_SEED_RANK"],
+       low_seed_team: data["LOW_SEED_TEAM"],
+       low_seed_team_id: data["LOW_SEED_TEAM_ID"],
+       high_seed_series_wins: data["HIGH_SEED_SERIES_W"],
+       low_seed_series_wins: data["LOW_SEED_SERIES_W"],
+       series_status: data["SERIES_STATUS"]}
+    end
+    private_class_method :matchup_attributes
+  end
+end

data/lib/nba/playoff_series.rb

@@ -0,0 +1,76 @@
+module NBA
+  # Represents a playoff series
+  class PlayoffSeries < Shale::Mapper
+    include Equalizer.new(:game_id, :series_id)
+
+    # @!attribute [rw] game_id
+    #   Returns the game ID
+    #   @api public
+    #   @example
+    #     series.game_id #=> "0042400101"
+    #   @return [String] the game ID
+    attribute :game_id, Shale::Type::String
+
+    # @!attribute [rw] home_team_id
+    #   Returns the home team ID
+    #   @api public
+    #   @example
+    #     series.home_team_id #=> 1610612744
+    #   @return [Integer] the home team ID
+    attribute :home_team_id, Shale::Type::Integer
+
+    # @!attribute [rw] visitor_team_id
+    #   Returns the visitor team ID
+    #   @api public
+    #   @example
+    #     series.visitor_team_id #=> 1610612747
+    #   @return [Integer] the visitor team ID
+    attribute :visitor_team_id, Shale::Type::Integer
+
+    # @!attribute [rw] series_id
+    #   Returns the series ID
+    #   @api public
+    #   @example
+    #     series.series_id #=> "0042400101"
+    #   @return [String] the series ID
+    attribute :series_id, Shale::Type::String
+
+    # @!attribute [rw] game_num
+    #   Returns the game number in the series
+    #   @api public
+    #   @example
+    #     series.game_num #=> 1
+    #   @return [Integer] the game number
+    attribute :game_num, Shale::Type::Integer
+
+    # Returns the home team object
+    #
+    # @api public
+    # @example
+    #   series.home_team #=> #<NBA::Team>
+    # @return [Team, nil] the home team object
+    def home_team
+      Teams.find(home_team_id)
+    end
+
+    # Returns the visitor team object
+    #
+    # @api public
+    # @example
+    #   series.visitor_team #=> #<NBA::Team>
+    # @return [Team, nil] the visitor team object
+    def visitor_team
+      Teams.find(visitor_team_id)
+    end
+
+    # Returns the game object
+    #
+    # @api public
+    # @example
+    #   series.game #=> #<NBA::Game>
+    # @return [Game, nil] the game object
+    def game
+      Games.find(game_id)
+    end
+  end
+end