nba 0.1.1 → 0.2.0

data/lib/nba/team_details.rb

@@ -0,0 +1,173 @@
+require "json"
+require_relative "client"
+require_relative "collection"
+require_relative "team_detail"
+require_relative "team_historical_record"
+
+module NBA
+  # Provides methods to retrieve team details
+  module TeamDetails
+    # Result set name for team background
+    # @return [String] the result set name
+    TEAM_BACKGROUND = "TeamBackground".freeze
+
+    # Result set name for team history
+    # @return [String] the result set name
+    TEAM_HISTORY = "TeamHistory".freeze
+
+    # Retrieves detailed information for a team
+    #
+    # @api public
+    # @example
+    #   detail = NBA::TeamDetails.find(team: NBA::Team::GSW)
+    #   puts "#{detail.full_name} plays at #{detail.arena}"
+    # @param team [Integer, Team] the team ID or Team object
+    # @param client [Client] the API client to use
+    # @return [TeamDetail, nil] the team detail
+    def self.find(team:, client: CLIENT)
+      team_id = extract_team_id(team)
+      path = "teamdetails?TeamID=#{team_id}"
+      response = client.get(path)
+      parse_detail_response(response)
+    end
+
+    # Retrieves historical records for a team
+    #
+    # @api public
+    # @example
+    #   history = NBA::TeamDetails.history(team: NBA::Team::GSW)
+    #   history.each { |h| puts "#{h.year}: #{h.wins}-#{h.losses}" }
+    # @param team [Integer, Team] the team ID or Team object
+    # @param client [Client] the API client to use
+    # @return [Collection] a collection of historical records
+    def self.history(team:, client: CLIENT)
+      team_id = extract_team_id(team)
+      path = "teamdetails?TeamID=#{team_id}"
+      response = client.get(path)
+      parse_history_response(response)
+    end
+
+    # Parses the API response into a team detail object
+    # @api private
+    # @return [TeamDetail, nil] the team detail
+    def self.parse_detail_response(response)
+      return unless response
+
+      data = JSON.parse(response)
+      result_set = find_result_set(data, TEAM_BACKGROUND)
+      return unless result_set
+
+      headers = result_set["headers"]
+      row = result_set.dig("rowSet", 0)
+      return unless headers && row
+
+      build_team_detail(headers, row)
+    end
+    private_class_method :parse_detail_response
+
+    # Parses the API response into historical record objects
+    # @api private
+    # @return [Collection] collection of historical records
+    def self.parse_history_response(response)
+      return Collection.new unless response
+
+      data = JSON.parse(response)
+      result_set = find_result_set(data, TEAM_HISTORY)
+      return Collection.new unless result_set
+
+      headers = result_set["headers"]
+      rows = result_set["rowSet"]
+      return Collection.new unless headers && rows
+
+      records = rows.map { |row| build_historical_record(headers, row) }
+      Collection.new(records)
+    end
+    private_class_method :parse_history_response
+
+    # Finds the specified result set in the response
+    # @api private
+    # @return [Hash, nil] the result set hash
+    def self.find_result_set(data, name)
+      result_sets = data["resultSets"]
+      return unless result_sets
+
+      result_sets.find { |rs| rs["name"].eql?(name) }
+    end
+    private_class_method :find_result_set
+
+    # Builds a TeamDetail object from raw data
+    # @api private
+    # @return [TeamDetail] the team detail object
+    def self.build_team_detail(headers, row)
+      data = headers.zip(row).to_h
+      TeamDetail.new(**detail_attributes(data))
+    end
+    private_class_method :build_team_detail
+
+    # Builds a TeamHistoricalRecord object from raw data
+    # @api private
+    # @return [TeamHistoricalRecord] the historical record object
+    def self.build_historical_record(headers, row)
+      data = headers.zip(row).to_h
+      TeamHistoricalRecord.new(**history_attributes(data))
+    end
+    private_class_method :build_historical_record
+
+    # Extracts team detail attributes from data
+    # @api private
+    # @return [Hash] detail attributes
+    def self.detail_attributes(data)
+      {team_id: data.fetch("TEAM_ID"), abbreviation: data.fetch("ABBREVIATION"),
+       nickname: data.fetch("NICKNAME"), year_founded: data.fetch("YEARFOUNDED"),
+       city: data.fetch("CITY"), arena: data.fetch("ARENA"),
+       arena_capacity: data.fetch("ARENACAPACITY"), owner: data.fetch("OWNER"),
+       general_manager: data.fetch("GENERALMANAGER"), head_coach: data.fetch("HEADCOACH"),
+       d_league_affiliation: data.fetch("DLEAGUEAFFILIATION")}
+    end
+    private_class_method :detail_attributes
+
+    # Combines all history attributes
+    # @api private
+    # @return [Hash] the combined attributes
+    def self.history_attributes(data)
+      identity_history_attributes(data).merge(record_attributes(data), playoff_attributes(data))
+    end
+    private_class_method :history_attributes
+
+    # Extracts identity history attributes from data
+    # @api private
+    # @return [Hash] identity history attributes
+    def self.identity_history_attributes(data)
+      {team_id: data.fetch("TEAM_ID"), city: data.fetch("CITY"), nickname: data.fetch("NICKNAME"),
+       season_id: data.fetch("SEASON_ID"), year: data.fetch("YEAR")}
+    end
+    private_class_method :identity_history_attributes
+
+    # Extracts record attributes from data
+    # @api private
+    # @return [Hash] record attributes
+    def self.record_attributes(data)
+      {wins: data.fetch("WINS"), losses: data.fetch("LOSSES"), win_pct: data.fetch("WIN_PCT"),
+       conf_rank: data.fetch("CONF_RANK"), div_rank: data.fetch("DIV_RANK")}
+    end
+    private_class_method :record_attributes
+
+    # Extracts playoff attributes from data
+    # @api private
+    # @return [Hash] playoff attributes
+    def self.playoff_attributes(data)
+      {po_wins: data.fetch("PO_WINS"), po_losses: data.fetch("PO_LOSSES"),
+       conf_count: data.fetch("CONF_COUNT"), div_count: data.fetch("DIV_COUNT"),
+       nba_finals_appearance: data.fetch("NBA_FINALS_APPEARANCE")}
+    end
+    private_class_method :playoff_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/team_estimated_metrics.rb

@@ -0,0 +1,91 @@
+require_relative "client"
+require_relative "collection"
+require_relative "response_parser"
+require_relative "utils"
+
+require_relative "team_estimated_metrics_stat"
+
+module NBA
+  # Provides methods to retrieve team estimated metrics
+  #
+  # @api public
+  module TeamEstimatedMetrics
+    # Season type constant for regular season
+    # @return [String] the season type
+    REGULAR_SEASON = "Regular Season".freeze
+
+    # Season type constant for playoffs
+    # @return [String] the season type
+    PLAYOFFS = "Playoffs".freeze
+
+    # Result set name for team estimated metrics
+    # @return [String] the result set name
+    RESULT_SET_NAME = "TeamEstimatedMetrics".freeze
+
+    # Retrieves estimated metrics for all teams
+    #
+    # @api public
+    # @example
+    #   stats = NBA::TeamEstimatedMetrics.all
+    #   stats.each { |s| puts "#{s.team_name}: #{s.e_net_rating} net rating" }
+    #
+    # @param season [Integer] the season year
+    # @param season_type [String] the season type
+    # @param client [Client] the API client to use
+    # @return [Collection] a collection of estimated metrics stats
+    def self.all(season: Utils.current_season, season_type: REGULAR_SEASON, client: CLIENT)
+      path = build_path(season, season_type)
+      ResponseParser.parse(client.get(path), result_set: RESULT_SET_NAME) { |data| build_stat(data) }
+    end
+
+    # Builds the API request path
+    #
+    # @api private
+    # @return [String] the request path
+    def self.build_path(season, season_type)
+      season_str = Utils.format_season(season)
+      "teamestimatedmetrics?LeagueID=00&Season=#{season_str}&SeasonType=#{season_type}"
+    end
+    private_class_method :build_path
+
+    # Builds an estimated metrics stat from API data
+    #
+    # @api private
+    # @return [TeamEstimatedMetricsStat]
+    def self.build_stat(data)
+      TeamEstimatedMetricsStat.new(**identity_info(data), **rating_info(data), **percentage_info(data))
+    end
+    private_class_method :build_stat
+
+    # Extracts identity information from data
+    #
+    # @api private
+    # @return [Hash]
+    def self.identity_info(data)
+      {team_id: data["TEAM_ID"], team_name: data["TEAM_NAME"],
+       gp: data["GP"], w: data["W"], l: data["L"],
+       w_pct: data["W_PCT"], min: data["MIN"]}
+    end
+    private_class_method :identity_info
+
+    # Extracts rating information from data
+    #
+    # @api private
+    # @return [Hash]
+    def self.rating_info(data)
+      {e_off_rating: data["E_OFF_RATING"], e_def_rating: data["E_DEF_RATING"],
+       e_net_rating: data["E_NET_RATING"], e_pace: data["E_PACE"], e_ast_ratio: data["E_AST_RATIO"]}
+    end
+    private_class_method :rating_info
+
+    # Extracts percentage information from data
+    #
+    # @api private
+    # @return [Hash]
+    def self.percentage_info(data)
+      {e_oreb_pct: data["E_OREB_PCT"], e_dreb_pct: data["E_DREB_PCT"],
+       e_reb_pct: data["E_REB_PCT"], e_tm_tov_pct: data["E_TM_TOV_PCT"]}
+    end
+    private_class_method :percentage_info
+  end
+end

data/lib/nba/team_estimated_metrics_stat.rb

@@ -0,0 +1,146 @@
+module NBA
+  # Represents team estimated metrics
+  #
+  # @api public
+  class TeamEstimatedMetricsStat < Shale::Mapper
+    include Equalizer.new(:team_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] gp
+    #   Returns games played
+    #   @api public
+    #   @example
+    #     stat.gp #=> 82
+    #   @return [Integer] games played
+    attribute :gp, Shale::Type::Integer
+
+    # @!attribute [rw] w
+    #   Returns wins
+    #   @api public
+    #   @example
+    #     stat.w #=> 46
+    #   @return [Integer] wins
+    attribute :w, Shale::Type::Integer
+
+    # @!attribute [rw] l
+    #   Returns losses
+    #   @api public
+    #   @example
+    #     stat.l #=> 36
+    #   @return [Integer] losses
+    attribute :l, Shale::Type::Integer
+
+    # @!attribute [rw] w_pct
+    #   Returns win percentage
+    #   @api public
+    #   @example
+    #     stat.w_pct #=> 0.561
+    #   @return [Float] win percentage
+    attribute :w_pct, Shale::Type::Float
+
+    # @!attribute [rw] min
+    #   Returns minutes per game
+    #   @api public
+    #   @example
+    #     stat.min #=> 48.0
+    #   @return [Float] minutes
+    attribute :min, Shale::Type::Float
+
+    # @!attribute [rw] e_off_rating
+    #   Returns estimated offensive rating
+    #   @api public
+    #   @example
+    #     stat.e_off_rating #=> 117.5
+    #   @return [Float] estimated offensive rating
+    attribute :e_off_rating, Shale::Type::Float
+
+    # @!attribute [rw] e_def_rating
+    #   Returns estimated defensive rating
+    #   @api public
+    #   @example
+    #     stat.e_def_rating #=> 110.2
+    #   @return [Float] estimated defensive rating
+    attribute :e_def_rating, Shale::Type::Float
+
+    # @!attribute [rw] e_net_rating
+    #   Returns estimated net rating
+    #   @api public
+    #   @example
+    #     stat.e_net_rating #=> 7.3
+    #   @return [Float] estimated net rating
+    attribute :e_net_rating, Shale::Type::Float
+
+    # @!attribute [rw] e_pace
+    #   Returns estimated pace
+    #   @api public
+    #   @example
+    #     stat.e_pace #=> 101.5
+    #   @return [Float] estimated pace
+    attribute :e_pace, Shale::Type::Float
+
+    # @!attribute [rw] e_ast_ratio
+    #   Returns estimated assist ratio
+    #   @api public
+    #   @example
+    #     stat.e_ast_ratio #=> 18.5
+    #   @return [Float] estimated assist ratio
+    attribute :e_ast_ratio, Shale::Type::Float
+
+    # @!attribute [rw] e_oreb_pct
+    #   Returns estimated offensive rebound percentage
+    #   @api public
+    #   @example
+    #     stat.e_oreb_pct #=> 25.5
+    #   @return [Float] estimated offensive rebound percentage
+    attribute :e_oreb_pct, Shale::Type::Float
+
+    # @!attribute [rw] e_dreb_pct
+    #   Returns estimated defensive rebound percentage
+    #   @api public
+    #   @example
+    #     stat.e_dreb_pct #=> 75.5
+    #   @return [Float] estimated defensive rebound percentage
+    attribute :e_dreb_pct, Shale::Type::Float
+
+    # @!attribute [rw] e_reb_pct
+    #   Returns estimated rebound percentage
+    #   @api public
+    #   @example
+    #     stat.e_reb_pct #=> 50.5
+    #   @return [Float] estimated rebound percentage
+    attribute :e_reb_pct, Shale::Type::Float
+
+    # @!attribute [rw] e_tm_tov_pct
+    #   Returns estimated team turnover percentage
+    #   @api public
+    #   @example
+    #     stat.e_tm_tov_pct #=> 11.5
+    #   @return [Float] estimated team turnover percentage
+    attribute :e_tm_tov_pct, Shale::Type::Float
+
+    # 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_game_log.rb

@@ -0,0 +1,143 @@
+require "json"
+require_relative "client"
+require_relative "collection"
+require_relative "utils"
+
+require_relative "team_game_log_entry"
+
+module NBA
+  # Provides methods to retrieve team game logs
+  module TeamGameLog
+    # Regular season type
+    # @return [String] the season type
+    REGULAR_SEASON = "Regular Season".freeze
+
+    # Playoffs season type
+    # @return [String] the season type
+    PLAYOFFS = "Playoffs".freeze
+
+    # Retrieves game logs for a team
+    #
+    # @api public
+    # @example
+    #   logs = NBA::TeamGameLog.find(team: Team::GSW)
+    #   logs.each { |log| puts "#{log.game_date}: #{log.pts} points" }
+    # @param team [Integer, Team] the team ID or Team object
+    # @param season [Integer] the season year (defaults to current season)
+    # @param season_type [String] the season type (Regular Season, Playoffs)
+    # @param client [Client] the API client to use
+    # @return [Collection] a collection of team game logs
+    def self.find(team:, season: Utils.current_season, season_type: REGULAR_SEASON, client: CLIENT)
+      team_id = extract_team_id(team)
+      season_str = Utils.format_season(season)
+      path = build_path(team_id, season_str, season_type)
+      response = client.get(path)
+      parse_response(response)
+    end
+
+    # Builds the API path for team game log
+    #
+    # @api private
+    # @param team_id [Integer] the team ID
+    # @param season_str [String] the season string
+    # @param season_type [String] the season type
+    # @return [String] the API path
+    def self.build_path(team_id, season_str, season_type)
+      encoded_type = season_type
+      "teamgamelog?TeamID=#{team_id}&Season=#{season_str}&SeasonType=#{encoded_type}"
+    end
+    private_class_method :build_path
+
+    # Parses the API response
+    #
+    # @api private
+    # @param response [String] the JSON response body
+    # @return [Collection] a collection of team game logs
+    def self.parse_response(response)
+      return Collection.new unless response
+
+      data = JSON.parse(response)
+      result_set = data.dig("resultSets", 0)
+      return Collection.new unless result_set
+
+      headers = result_set["headers"]
+      rows = result_set["rowSet"]
+      return Collection.new unless headers && rows
+
+      logs = rows.map { |row| build_team_game_log(headers, row) }
+      Collection.new(logs)
+    end
+    private_class_method :parse_response
+
+    # Builds a team game log from a row
+    #
+    # @api private
+    # @param headers [Array<String>] the column headers
+    # @param row [Array] the row data
+    # @return [TeamGameLogEntry] the team game log object
+    def self.build_team_game_log(headers, row)
+      data = headers.zip(row).to_h
+      TeamGameLogEntry.new(**team_game_log_attributes(data))
+    end
+    private_class_method :build_team_game_log
+
+    # Combines all team game log attributes
+    #
+    # @api private
+    # @param data [Hash] the game log data
+    # @return [Hash] the combined attributes
+    def self.team_game_log_attributes(data)
+      game_info_attributes(data).merge(shooting_attributes(data), counting_attributes(data))
+    end
+    private_class_method :team_game_log_attributes
+
+    # Extracts game info attributes
+    #
+    # @api private
+    # @param data [Hash] the game log data
+    # @return [Hash] the game info attributes
+    def self.game_info_attributes(data)
+      {team_id: data["Team_ID"], game_id: data["Game_ID"], game_date: data["GAME_DATE"],
+       matchup: data["MATCHUP"], wl: data["WL"], min: data["MIN"]}
+    end
+    private_class_method :game_info_attributes
+
+    # Extracts shooting attributes
+    #
+    # @api private
+    # @param data [Hash] the game log data
+    # @return [Hash] the 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
+    #
+    # @api private
+    # @param data [Hash] the game log data
+    # @return [Hash] the counting stats attributes
+    def self.counting_attributes(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"],
+       plus_minus: data["PLUS_MINUS"]}
+    end
+    private_class_method :counting_attributes
+
+    # Extracts team ID from a Team object or returns the integer
+    #
+    # @api private
+    # @param team [Team, Integer] the team or team ID
+    # @return [Integer] the team ID
+    def self.extract_team_id(team)
+      case team
+      when Team then team.id
+      else team
+      end
+    end
+    private_class_method :extract_team_id
+  end
+end