nba 0.1.1 → 0.2.0

data/lib/nba/cume_stats_player.rb

@@ -0,0 +1,358 @@
+require "json"
+require_relative "client"
+require_relative "collection"
+require_relative "cume_stats_player_game"
+require_relative "cume_stats_player_total"
+require_relative "league"
+require_relative "utils"
+
+module NBA
+  # Provides methods to retrieve cumulative player statistics
+  module CumeStatsPlayer
+    # Result set name for game-by-game stats
+    # @return [String] the result set name
+    GAME_BY_GAME_STATS = "GameByGameStats".freeze
+
+    # Result set name for total player stats
+    # @return [String] the result set name
+    TOTAL_PLAYER_STATS = "TotalPlayerStats".freeze
+
+    # Retrieves cumulative player statistics for specific games
+    #
+    # @api public
+    # @example
+    #   stats = NBA::CumeStatsPlayer.find(
+    #     player: 201939,
+    #     game_ids: ["0022400001", "0022400002"],
+    #     season: "2024-25",
+    #     season_type: "Regular Season"
+    #   )
+    #   stats[:game_by_game].each { |g| puts "#{g.game_date}: #{g.pts} PTS" }
+    #   puts "Total: #{stats[:total].pts} PTS"
+    # @param player [Integer, Player] the player ID or Player object
+    # @param game_ids [Array<String>, String] game IDs as array or pipe-separated string
+    # @param season [String] the season (e.g., "2024-25")
+    # @param season_type [String] the season type (default "Regular Season")
+    # @param league [String, League] the league ID or League object (default NBA)
+    # @param client [Client] the API client to use
+    # @return [Hash, nil] hash with :game_by_game and :total keys, or nil
+    def self.find(player:, game_ids:, season:, season_type: "Regular Season", league: League::NBA, client: CLIENT)
+      player_id = Utils.extract_id(player)
+      league_id = Utils.extract_league_id(league)
+      game_ids_param = format_game_ids(game_ids)
+
+      path = "cumestatsplayer?PlayerID=#{player_id}&GameIDs=#{game_ids_param}" \
+             "&LeagueID=#{league_id}&Season=#{season}&SeasonType=#{season_type}"
+      response = client.get(path)
+      parse_response(response)
+    end
+
+    # Parses the API response
+    #
+    # @api private
+    # @param response [String] the JSON response body
+    # @return [Hash, nil] hash with :game_by_game and :total keys, or nil
+    def self.parse_response(response)
+      return unless response
+
+      data = JSON.parse(response)
+      game_by_game = parse_game_by_game(data)
+      total = parse_total(data)
+
+      return unless game_by_game && total
+
+      {game_by_game: game_by_game, total: total}
+    end
+    private_class_method :parse_response
+
+    # Parses the game-by-game stats result set
+    #
+    # @api private
+    # @param data [Hash] the parsed JSON data
+    # @return [Collection, nil] collection of game stats, or nil
+    def self.parse_game_by_game(data)
+      result_set = find_result_set(data, GAME_BY_GAME_STATS)
+      return unless result_set
+
+      headers = result_set["headers"]
+      rows = result_set["rowSet"]
+      return unless headers && rows
+
+      games = rows.map { |row| build_game(headers, row) }
+      Collection.new(games)
+    end
+    private_class_method :parse_game_by_game
+
+    # Parses the total player stats result set
+    #
+    # @api private
+    # @param data [Hash] the parsed JSON data
+    # @return [CumeStatsPlayerTotal, nil] total stats, or nil
+    def self.parse_total(data)
+      result_set = find_result_set(data, TOTAL_PLAYER_STATS)
+      return unless result_set
+
+      headers = result_set["headers"]
+      row = result_set.dig("rowSet", 0)
+      return unless headers && row
+
+      build_total(headers, row)
+    end
+    private_class_method :parse_total
+
+    # Finds a result set by name
+    #
+    # @api private
+    # @param data [Hash] the parsed JSON data
+    # @param name [String] the result set name
+    # @return [Hash, nil] the result set
+    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 game stat object from a row
+    #
+    # @api private
+    # @param headers [Array<String>] the column headers
+    # @param row [Array] the row data
+    # @return [CumeStatsPlayerGame] the game stat object
+    def self.build_game(headers, row)
+      data = headers.zip(row).to_h
+      CumeStatsPlayerGame.new(**GameAttributes.extract(data))
+    end
+    private_class_method :build_game
+
+    # Builds a total stat object from a row
+    #
+    # @api private
+    # @param headers [Array<String>] the column headers
+    # @param row [Array] the row data
+    # @return [CumeStatsPlayerTotal] the total stat object
+    def self.build_total(headers, row)
+      data = headers.zip(row).to_h
+      CumeStatsPlayerTotal.new(**TotalAttributes.extract(data))
+    end
+    private_class_method :build_total
+
+    # Formats game IDs as a pipe-separated string
+    #
+    # @api private
+    # @param game_ids [Array<String>, String] game IDs as array or string
+    # @return [String] pipe-separated game IDs
+    def self.format_game_ids(game_ids)
+      game_ids.instance_of?(Array) ? game_ids.join("|") : game_ids
+    end
+    private_class_method :format_game_ids
+
+    # Extracts game attributes from row data
+    # @api private
+    module GameAttributes
+      # Extracts all game attributes from data
+      # @api private
+      # @param data [Hash] the row data
+      # @return [Hash] extracted attributes
+      def self.extract(data)
+        identity(data).merge(stats(data))
+      end
+
+      # Extracts identity attributes from data
+      # @api private
+      # @param data [Hash] the row data
+      # @return [Hash] identity attributes
+      def self.identity(data)
+        {
+          game_id: data["GAME_ID"],
+          matchup: data["MATCHUP"],
+          game_date: data["GAME_DATE"],
+          vs_team_id: data["VS_TEAM_ID"],
+          vs_team_city: data["VS_TEAM_CITY"],
+          vs_team_name: data["VS_TEAM_NAME"]
+        }
+      end
+
+      # Extracts stat attributes from data
+      # @api private
+      # @param data [Hash] the row data
+      # @return [Hash] stat attributes
+      def self.stats(data)
+        time(data).merge(shooting(data)).merge(rebounds(data)).merge(other(data))
+      end
+
+      # Extracts time attributes from data
+      # @api private
+      # @param data [Hash] the row data
+      # @return [Hash] time attributes
+      def self.time(data)
+        {min: data["MIN"], sec: data["SEC"]}
+      end
+
+      # Extracts shooting attributes from data
+      # @api private
+      # @param data [Hash] the row data
+      # @return [Hash] shooting attributes
+      def self.shooting(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
+
+      # Extracts rebound attributes from data
+      # @api private
+      # @param data [Hash] the row data
+      # @return [Hash] rebound attributes
+      def self.rebounds(data)
+        {oreb: data["OREB"], dreb: data["DREB"], reb: data["REB"]}
+      end
+
+      # Extracts other stat attributes from data
+      # @api private
+      # @param data [Hash] the row data
+      # @return [Hash] other stat attributes
+      def self.other(data)
+        {
+          ast: data["AST"], pf: data["PF"], stl: data["STL"],
+          tov: data["TOV"], blk: data["BLK"], pts: data["PTS"]
+        }
+      end
+    end
+
+    # Extracts total attributes from row data
+    # @api private
+    module TotalAttributes
+      # Extracts all total attributes from data
+      # @api private
+      # @param data [Hash] the row data
+      # @return [Hash] extracted attributes
+      def self.extract(data)
+        identity(data).merge(totals(data)).merge(averages(data)).merge(maximums(data))
+      end
+
+      # Extracts identity attributes from data
+      # @api private
+      # @param data [Hash] the row data
+      # @return [Hash] identity attributes
+      def self.identity(data)
+        {
+          player_id: data["PLAYER_ID"], player_name: data["PLAYER_NAME"],
+          jersey_num: data["JERSEY_NUM"], season: data["SEASON"],
+          gp: data["GP"], gs: data["GS"],
+          actual_minutes: data["ACTUAL_MINUTES"], actual_seconds: data["ACTUAL_SECONDS"]
+        }
+      end
+
+      # Extracts total stat attributes from data
+      # @api private
+      # @param data [Hash] the row data
+      # @return [Hash] total stat attributes
+      def self.totals(data)
+        shooting(data).merge(rebounds_and_other(data))
+      end
+
+      # Extracts shooting attributes from data
+      # @api private
+      # @param data [Hash] the row data
+      # @return [Hash] shooting attributes
+      def self.shooting(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
+
+      # Extracts rebound and other stat attributes from data
+      # @api private
+      # @param data [Hash] the row data
+      # @return [Hash] rebound and other stat attributes
+      def self.rebounds_and_other(data)
+        {
+          oreb: data["OREB"], dreb: data["DREB"], tot_reb: data["TOT_REB"],
+          ast: data["AST"], pf: data["PF"], stl: data["STL"],
+          tov: data["TOV"], blk: data["BLK"], pts: data["PTS"]
+        }
+      end
+
+      # Extracts average stat attributes from data
+      # @api private
+      # @param data [Hash] the row data
+      # @return [Hash] average stat attributes
+      def self.averages(data)
+        avg_time(data).merge(avg_shooting(data)).merge(avg_other(data))
+      end
+
+      # Extracts average time attributes from data
+      # @api private
+      # @param data [Hash] the row data
+      # @return [Hash] average time attributes
+      def self.avg_time(data)
+        {avg_min: data["AVG_MIN"], avg_sec: data["AVG_SEC"]}
+      end
+
+      # Extracts average shooting attributes from data
+      # @api private
+      # @param data [Hash] the row data
+      # @return [Hash] average shooting attributes
+      def self.avg_shooting(data)
+        {
+          avg_fgm: data["AVG_FGM"], avg_fga: data["AVG_FGA"],
+          avg_fg3m: data["AVG_FG3M"], avg_fg3a: data["AVG_FG3A"],
+          avg_ftm: data["AVG_FTM"], avg_fta: data["AVG_FTA"],
+          avg_oreb: data["AVG_OREB"], avg_dreb: data["AVG_DREB"]
+        }
+      end
+
+      # Extracts average other stat attributes from data
+      # @api private
+      # @param data [Hash] the row data
+      # @return [Hash] average other stat attributes
+      def self.avg_other(data)
+        {
+          avg_tot_reb: data["AVG_TOT_REB"], avg_ast: data["AVG_AST"],
+          avg_pf: data["AVG_PF"], avg_stl: data["AVG_STL"],
+          avg_tov: data["AVG_TOV"], avg_blk: data["AVG_BLK"],
+          avg_pts: data["AVG_PTS"]
+        }
+      end
+
+      # Extracts maximum stat attributes from data
+      # @api private
+      # @param data [Hash] the row data
+      # @return [Hash] maximum stat attributes
+      def self.maximums(data)
+        max_shooting(data).merge(max_other(data))
+      end
+
+      # Extracts maximum shooting attributes from data
+      # @api private
+      # @param data [Hash] the row data
+      # @return [Hash] maximum shooting attributes
+      def self.max_shooting(data)
+        {
+          max_min: data["MAX_MIN"], max_fgm: data["MAX_FGM"],
+          max_fga: data["MAX_FGA"], max_fg3m: data["MAX_FG3M"],
+          max_fg3a: data["MAX_FG3A"], max_ftm: data["MAX_FTM"],
+          max_fta: data["MAX_FTA"], max_oreb: data["MAX_OREB"],
+          max_dreb: data["MAX_DREB"], max_reb: data["MAX_REB"]
+        }
+      end
+
+      # Extracts maximum other stat attributes from data
+      # @api private
+      # @param data [Hash] the row data
+      # @return [Hash] maximum other stat attributes
+      def self.max_other(data)
+        {
+          max_ast: data["MAX_AST"], max_pf: data["MAX_PF"],
+          max_stl: data["MAX_STL"], max_tov: data["MAX_TOV"],
+          max_blk: data["MAX_BLK"], max_pts: data["MAX_PTS"]
+        }
+      end
+    end
+  end
+end

data/lib/nba/cume_stats_player_game.rb

@@ -0,0 +1,217 @@
+require "equalizer"
+require "shale"
+
+module NBA
+  # Represents a single game in cumulative player statistics
+  class CumeStatsPlayerGame < Shale::Mapper
+    include Equalizer.new(:game_id)
+
+    # @!attribute [rw] game_id
+    #   Returns the game ID
+    #   @api public
+    #   @example
+    #     game.game_id #=> "0022400001"
+    #   @return [String] the game ID
+    attribute :game_id, Shale::Type::String
+
+    # @!attribute [rw] matchup
+    #   Returns the matchup description
+    #   @api public
+    #   @example
+    #     game.matchup #=> "GSW vs. LAL"
+    #   @return [String] the matchup description
+    attribute :matchup, Shale::Type::String
+
+    # @!attribute [rw] game_date
+    #   Returns the game date
+    #   @api public
+    #   @example
+    #     game.game_date #=> "2024-10-22"
+    #   @return [String] the game date
+    attribute :game_date, Shale::Type::String
+
+    # @!attribute [rw] vs_team_id
+    #   Returns the opposing team ID
+    #   @api public
+    #   @example
+    #     game.vs_team_id #=> 1610612747
+    #   @return [Integer] the opposing team ID
+    attribute :vs_team_id, Shale::Type::Integer
+
+    # @!attribute [rw] vs_team_city
+    #   Returns the opposing team city
+    #   @api public
+    #   @example
+    #     game.vs_team_city #=> "Los Angeles"
+    #   @return [String] the opposing team city
+    attribute :vs_team_city, Shale::Type::String
+
+    # @!attribute [rw] vs_team_name
+    #   Returns the opposing team name
+    #   @api public
+    #   @example
+    #     game.vs_team_name #=> "Lakers"
+    #   @return [String] the opposing team name
+    attribute :vs_team_name, Shale::Type::String
+
+    # @!attribute [rw] min
+    #   Returns the minutes played
+    #   @api public
+    #   @example
+    #     game.min #=> 35
+    #   @return [Integer] the minutes played
+    attribute :min, Shale::Type::Integer
+
+    # @!attribute [rw] sec
+    #   Returns the seconds played
+    #   @api public
+    #   @example
+    #     game.sec #=> 42
+    #   @return [Integer] the seconds played
+    attribute :sec, Shale::Type::Integer
+
+    # @!attribute [rw] fgm
+    #   Returns the field goals made
+    #   @api public
+    #   @example
+    #     game.fgm #=> 10
+    #   @return [Integer] the field goals made
+    attribute :fgm, Shale::Type::Integer
+
+    # @!attribute [rw] fga
+    #   Returns the field goals attempted
+    #   @api public
+    #   @example
+    #     game.fga #=> 20
+    #   @return [Integer] the field goals attempted
+    attribute :fga, Shale::Type::Integer
+
+    # @!attribute [rw] fg_pct
+    #   Returns the field goal percentage
+    #   @api public
+    #   @example
+    #     game.fg_pct #=> 0.500
+    #   @return [Float] the field goal percentage
+    attribute :fg_pct, Shale::Type::Float
+
+    # @!attribute [rw] fg3m
+    #   Returns the three-point field goals made
+    #   @api public
+    #   @example
+    #     game.fg3m #=> 3
+    #   @return [Integer] the three-point field goals made
+    attribute :fg3m, Shale::Type::Integer
+
+    # @!attribute [rw] fg3a
+    #   Returns the three-point field goals attempted
+    #   @api public
+    #   @example
+    #     game.fg3a #=> 8
+    #   @return [Integer] the three-point field goals attempted
+    attribute :fg3a, Shale::Type::Integer
+
+    # @!attribute [rw] fg3_pct
+    #   Returns the three-point field goal percentage
+    #   @api public
+    #   @example
+    #     game.fg3_pct #=> 0.375
+    #   @return [Float] the three-point field goal percentage
+    attribute :fg3_pct, Shale::Type::Float
+
+    # @!attribute [rw] ftm
+    #   Returns the free throws made
+    #   @api public
+    #   @example
+    #     game.ftm #=> 7
+    #   @return [Integer] the free throws made
+    attribute :ftm, Shale::Type::Integer
+
+    # @!attribute [rw] fta
+    #   Returns the free throws attempted
+    #   @api public
+    #   @example
+    #     game.fta #=> 8
+    #   @return [Integer] the free throws attempted
+    attribute :fta, Shale::Type::Integer
+
+    # @!attribute [rw] ft_pct
+    #   Returns the free throw percentage
+    #   @api public
+    #   @example
+    #     game.ft_pct #=> 0.875
+    #   @return [Float] the free throw percentage
+    attribute :ft_pct, Shale::Type::Float
+
+    # @!attribute [rw] oreb
+    #   Returns the offensive rebounds
+    #   @api public
+    #   @example
+    #     game.oreb #=> 2
+    #   @return [Integer] the offensive rebounds
+    attribute :oreb, Shale::Type::Integer
+
+    # @!attribute [rw] dreb
+    #   Returns the defensive rebounds
+    #   @api public
+    #   @example
+    #     game.dreb #=> 6
+    #   @return [Integer] the defensive rebounds
+    attribute :dreb, Shale::Type::Integer
+
+    # @!attribute [rw] reb
+    #   Returns the total rebounds
+    #   @api public
+    #   @example
+    #     game.reb #=> 8
+    #   @return [Integer] the total rebounds
+    attribute :reb, Shale::Type::Integer
+
+    # @!attribute [rw] ast
+    #   Returns the assists
+    #   @api public
+    #   @example
+    #     game.ast #=> 5
+    #   @return [Integer] the assists
+    attribute :ast, Shale::Type::Integer
+
+    # @!attribute [rw] pf
+    #   Returns the personal fouls
+    #   @api public
+    #   @example
+    #     game.pf #=> 3
+    #   @return [Integer] the personal fouls
+    attribute :pf, Shale::Type::Integer
+
+    # @!attribute [rw] stl
+    #   Returns the steals
+    #   @api public
+    #   @example
+    #     game.stl #=> 2
+    #   @return [Integer] the steals
+    attribute :stl, Shale::Type::Integer
+
+    # @!attribute [rw] tov
+    #   Returns the turnovers
+    #   @api public
+    #   @example
+    #     game.tov #=> 3
+    #   @return [Integer] the turnovers
+    attribute :tov, Shale::Type::Integer
+
+    # @!attribute [rw] blk
+    #   Returns the blocks
+    #   @api public
+    #   @example
+    #     game.blk #=> 1
+    #   @return [Integer] the blocks
+    attribute :blk, Shale::Type::Integer
+
+    # @!attribute [rw] pts
+    #   Returns the points
+    #   @api public
+    #   @example
+    #     game.pts #=> 30
+    #   @return [Integer] the points
+    attribute :pts, Shale::Type::Integer
+  end
+end

data/lib/nba/cume_stats_player_games.rb

@@ -0,0 +1,99 @@
+require_relative "client"
+require_relative "response_parser"
+require_relative "cume_stats_player_games_entry"
+require_relative "utils"
+
+module NBA
+  # Provides methods to retrieve cumulative stats player games
+  #
+  # @api public
+  module CumeStatsPlayerGames
+    # Result set name for cumulative stats player games
+    # @return [String] the result set name
+    RESULTS = "CumeStatsPlayerGames".freeze
+
+    # Retrieves all cumulative stats player games for specified criteria
+    #
+    # @api public
+    # @example
+    #   games = NBA::CumeStatsPlayerGames.all(player: 201939, season: 2024, season_type: "Regular Season")
+    #   games.each { |game| puts "#{game.matchup} - #{game.game_id}" }
+    # @param player [Integer, Player] the player ID or Player object
+    # @param season [Integer] the season year
+    # @param season_type [String] the season type (Regular Season, Playoffs)
+    # @param league [String, League] the league ID or League object (default NBA)
+    # @param location [String, nil] filter by location (Home, Road)
+    # @param outcome [String, nil] filter by outcome (W, L)
+    # @param vs_conference [String, nil] filter by opponent conference
+    # @param vs_division [String, nil] filter by opponent division
+    # @param vs_team [Integer, Team, nil] filter by opponent team ID or Team object
+    # @param client [Client] the API client to use
+    # @return [Collection] a collection of cumulative stats player games entries
+    def self.all(player:, season:, season_type: "Regular Season", league: League::NBA, location: nil,
+      outcome: nil, vs_conference: nil, vs_division: nil, vs_team: nil, client: CLIENT)
+      opts = {player: player, season: season, season_type: season_type, league: league,
+              location: location, outcome: outcome, vs_conference: vs_conference,
+              vs_division: vs_division, vs_team: vs_team}
+      path = PathBuilder.build(opts)
+      ResponseParser.parse(client.get(path), result_set: RESULTS) { |data| build_entry(data) }
+    end
+
+    # Builds an entry from API data
+    #
+    # @api private
+    # @return [CumeStatsPlayerGamesEntry]
+    def self.build_entry(data)
+      CumeStatsPlayerGamesEntry.new(**entry_attributes(data))
+    end
+    private_class_method :build_entry
+
+    # Extracts entry attributes from data
+    #
+    # @api private
+    # @param data [Hash] the entry data
+    # @return [Hash] the entry attributes
+    def self.entry_attributes(data)
+      {game_id: data["GAME_ID"], matchup: data["MATCHUP"]}
+    end
+    private_class_method :entry_attributes
+
+    # Builds API path from options
+    # @api private
+    module PathBuilder
+      # Builds the complete API path from options
+      # @api private
+      # @param opts [Hash] the options hash
+      # @return [String] the complete API path
+      def self.build(opts)
+        base_path(opts) + optional_params(opts)
+      end
+
+      # Builds the base API path from options
+      # @api private
+      # @param opts [Hash] the options hash
+      # @return [String] the base API path
+      def self.base_path(opts)
+        player_id = Utils.extract_id(opts.fetch(:player))
+        league_id = Utils.extract_league_id(opts.fetch(:league))
+        season_str = Utils.format_season(opts.fetch(:season))
+
+        "cumestatsplayergames?PlayerID=#{player_id}&LeagueID=#{league_id}" \
+          "&Season=#{season_str}&SeasonType=#{opts.fetch(:season_type)}"
+      end
+
+      # Builds optional parameters string from options
+      # @api private
+      # @param opts [Hash] the options hash
+      # @return [String] the optional parameters string
+      def self.optional_params(opts)
+        path = ""
+        path += "&Location=#{opts.fetch(:location)}" if opts.fetch(:location)
+        path += "&Outcome=#{opts.fetch(:outcome)}" if opts.fetch(:outcome)
+        path += "&VsConference=#{opts.fetch(:vs_conference)}" if opts.fetch(:vs_conference)
+        path += "&VsDivision=#{opts.fetch(:vs_division)}" if opts.fetch(:vs_division)
+        path += "&VsTeamID=#{Utils.extract_id(opts.fetch(:vs_team))}" if opts.fetch(:vs_team)
+        path
+      end
+    end
+  end
+end

data/lib/nba/cume_stats_player_games_entry.rb

@@ -0,0 +1,25 @@
+require "equalizer"
+require "shale"
+
+module NBA
+  # Represents a single game entry from cumulative stats player games
+  class CumeStatsPlayerGamesEntry < Shale::Mapper
+    include Equalizer.new(:game_id)
+
+    # @!attribute [rw] game_id
+    #   Returns the game ID
+    #   @api public
+    #   @example
+    #     entry.game_id #=> "0022400001"
+    #   @return [String] the game ID
+    attribute :game_id, Shale::Type::String
+
+    # @!attribute [rw] matchup
+    #   Returns the game matchup description
+    #   @api public
+    #   @example
+    #     entry.matchup #=> "GSW vs. LAL"
+    #   @return [String] the matchup description
+    attribute :matchup, Shale::Type::String
+  end
+end