nba 0.1.1 → 0.2.0

data/lib/nba/team_and_players_vs_players.rb

@@ -0,0 +1,227 @@
+require "json"
+require_relative "client"
+require_relative "collection"
+require_relative "team_and_players_vs_players_stat"
+require_relative "utils"
+
+module NBA
+  # Provides methods to retrieve team and players vs players statistics
+  #
+  # @api public
+  module TeamAndPlayersVsPlayers
+    # Result set name for players vs players
+    # @return [String] the result set name
+    PLAYERS_VS_PLAYERS = "PlayersVsPlayers".freeze
+
+    # Result set name for team players vs players off court
+    # @return [String] the result set name
+    TEAM_PLAYERS_VS_PLAYERS_OFF = "TeamPlayersVsPlayersOff".freeze
+
+    # Result set name for team players vs players on court
+    # @return [String] the result set name
+    TEAM_PLAYERS_VS_PLAYERS_ON = "TeamPlayersVsPlayersOn".freeze
+
+    # Result set name for team vs players
+    # @return [String] the result set name
+    TEAM_VS_PLAYERS = "TeamVsPlayers".freeze
+
+    # Retrieves players vs players comparison statistics
+    #
+    # @api public
+    # @example
+    #   stats = NBA::TeamAndPlayersVsPlayers.players_vs_players(
+    #     team: 1610612744, vs_team: 1610612747, players: [201939], vs_players: [2544]
+    #   )
+    #   stats.first.pts #=> 26.4
+    # @param team [Integer, Team] the team ID or Team object
+    # @param vs_team [Integer, Team] the vs team ID or Team object
+    # @param players [Array<Integer, Player>] array of player IDs or Player objects
+    # @param vs_players [Array<Integer, Player>] array of vs player IDs or Player objects
+    # @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 player vs player statistics
+    def self.players_vs_players(team:, vs_team:, players:, vs_players:, season: Utils.current_season,
+      season_type: "Regular Season", per_mode: "PerGame", client: CLIENT)
+      opts = {season: season, season_type: season_type, per_mode: per_mode, result_set: PLAYERS_VS_PLAYERS}
+      fetch_stats(team, vs_team, players, vs_players, opts, client: client)
+    end
+
+    # Retrieves team players vs players off court statistics
+    #
+    # @api public
+    # @example
+    #   stats = NBA::TeamAndPlayersVsPlayers.team_players_vs_players_off(
+    #     team: 1610612744, vs_team: 1610612747, players: [201939], vs_players: [2544]
+    #   )
+    #   stats.first.pts #=> 22.1
+    # @param team [Integer, Team] the team ID or Team object
+    # @param vs_team [Integer, Team] the vs team ID or Team object
+    # @param players [Array<Integer, Player>] array of player IDs or Player objects
+    # @param vs_players [Array<Integer, Player>] array of vs player IDs or Player objects
+    # @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 player statistics
+    def self.team_players_vs_players_off(team:, vs_team:, players:, vs_players:, season: Utils.current_season,
+      season_type: "Regular Season", per_mode: "PerGame", client: CLIENT)
+      opts = {season: season, season_type: season_type, per_mode: per_mode, result_set: TEAM_PLAYERS_VS_PLAYERS_OFF}
+      fetch_stats(team, vs_team, players, vs_players, opts, client: client)
+    end
+
+    # Retrieves team players vs players on court statistics
+    #
+    # @api public
+    # @example
+    #   stats = NBA::TeamAndPlayersVsPlayers.team_players_vs_players_on(
+    #     team: 1610612744, vs_team: 1610612747, players: [201939], vs_players: [2544]
+    #   )
+    #   stats.first.pts #=> 28.3
+    # @param team [Integer, Team] the team ID or Team object
+    # @param vs_team [Integer, Team] the vs team ID or Team object
+    # @param players [Array<Integer, Player>] array of player IDs or Player objects
+    # @param vs_players [Array<Integer, Player>] array of vs player IDs or Player objects
+    # @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 player statistics
+    def self.team_players_vs_players_on(team:, vs_team:, players:, vs_players:, season: Utils.current_season,
+      season_type: "Regular Season", per_mode: "PerGame", client: CLIENT)
+      opts = {season: season, season_type: season_type, per_mode: per_mode, result_set: TEAM_PLAYERS_VS_PLAYERS_ON}
+      fetch_stats(team, vs_team, players, vs_players, opts, client: client)
+    end
+
+    # Retrieves team vs players statistics
+    #
+    # @api public
+    # @example
+    #   stats = NBA::TeamAndPlayersVsPlayers.team_vs_players(
+    #     team: 1610612744, vs_team: 1610612747, players: [201939], vs_players: [2544]
+    #   )
+    #   stats.first.pts #=> 112.4
+    # @param team [Integer, Team] the team ID or Team object
+    # @param vs_team [Integer, Team] the vs team ID or Team object
+    # @param players [Array<Integer, Player>] array of player IDs or Player objects
+    # @param vs_players [Array<Integer, Player>] array of vs player IDs or Player objects
+    # @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 statistics
+    def self.team_vs_players(team:, vs_team:, players:, vs_players:, season: Utils.current_season,
+      season_type: "Regular Season", per_mode: "PerGame", client: CLIENT)
+      opts = {season: season, season_type: season_type, per_mode: per_mode, result_set: TEAM_VS_PLAYERS}
+      fetch_stats(team, vs_team, players, vs_players, opts, client: client)
+    end
+
+    # Fetches team and players vs players statistics from the API
+    #
+    # @api private
+    # @return [Collection] the collection of statistics
+    def self.fetch_stats(team, vs_team, players, vs_players, opts, client:)
+      path = build_path(team, vs_team, players, vs_players, opts)
+      response = client.get(path)
+      parse_response(response, opts.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_team, players, vs_players, opts)
+      team_id = Utils.extract_id(team)
+      vs_team_id = Utils.extract_id(vs_team)
+      season_str = Utils.format_season(opts.fetch(:season))
+      player_params = build_player_params(players, "PlayerID")
+      vs_player_params = build_player_params(vs_players, "VsPlayerID")
+      "teamandplayersvsplayers?TeamID=#{team_id}&VsTeamID=#{vs_team_id}&Season=#{season_str}" \
+        "&SeasonType=#{opts.fetch(:season_type)}&PerMode=#{opts.fetch(:per_mode)}" \
+        "&LeagueID=00#{player_params}#{vs_player_params}"
+    end
+    private_class_method :build_path
+
+    # Builds player parameter string for API request
+    #
+    # @api private
+    # @return [String] the player parameters string
+    def self.build_player_params(players, param_prefix)
+      ids = players.map { |p| Utils.extract_id(p) }
+      (1..5).map { |i| "&#{param_prefix}#{i}=#{ids.at(i - 1) || 0}" }.join
+    end
+    private_class_method :build_player_params
+
+    # 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_stat(headers.zip(row).to_h) })
+    end
+    private_class_method :build_collection
+
+    # Builds a stat object from the data hash
+    #
+    # @api private
+    # @return [TeamAndPlayersVsPlayersStat] the stat object
+    def self.build_stat(data)
+      TeamAndPlayersVsPlayersStat.new(**identity_info(data), **stat_info(data))
+    end
+    private_class_method :build_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"], player_id: data["PLAYER_ID"],
+       vs_player_id: data["VS_PLAYER_ID"], player_name: data["PLAYER_NAME"],
+       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_and_players_vs_players_stat.rb

@@ -0,0 +1,155 @@
+require "equalizer"
+require "shale"
+require_relative "players"
+require_relative "teams"
+
+module NBA
+  # Represents team and players vs players comparison statistics
+  #
+  # @api public
+  class TeamAndPlayersVsPlayersStat < Shale::Mapper
+    include Equalizer.new(:team_id, :player_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] player_id
+    #   Returns the player ID
+    #   @api public
+    #   @example
+    #     stat.player_id #=> 201939
+    #   @return [Integer, nil] the player's ID
+    attribute :player_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] player_name
+    #   Returns the player name
+    #   @api public
+    #   @example
+    #     stat.player_name #=> "Stephen Curry"
+    #   @return [String, nil] the player's name
+    attribute :player_name, 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 player
+    #
+    # @api public
+    # @example
+    #   stat.player #=> #<NBA::Player id=201939 ...>
+    # @return [Player, nil] the player object
+    def player
+      Players.find(player_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
+  end
+end

data/lib/nba/team_dash_pt_pass.rb

@@ -0,0 +1,157 @@
+require "json"
+require_relative "client"
+require_relative "collection"
+require_relative "team_pass_stat"
+require_relative "utils"
+
+module NBA
+  # Provides methods to retrieve team tracking pass statistics
+  #
+  # @api public
+  module TeamDashPtPass
+    # Result set name for passes made
+    # @return [String] the result set name
+    PASSES_MADE = "PassesMade".freeze
+
+    # Result set name for passes received
+    # @return [String] the result set name
+    PASSES_RECEIVED = "PassesReceived".freeze
+
+    # Retrieves passes made statistics for a team
+    #
+    # @api public
+    # @example
+    #   stats = NBA::TeamDashPtPass.passes_made(team: 1610612744)
+    #   stats.each { |s| puts "#{s.pass_from}: #{s.ast} assists" }
+    # @param team [Integer, Team] the team ID or Team 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 pass statistics
+    def self.passes_made(team:, season: Utils.current_season, season_type: "Regular Season",
+      per_mode: "PerGame", client: CLIENT)
+      fetch_stats(team, season, season_type, per_mode, PASSES_MADE, client: client)
+    end
+
+    # Retrieves passes received statistics for a team
+    #
+    # @api public
+    # @example
+    #   stats = NBA::TeamDashPtPass.passes_received(team: 1610612744)
+    #   stats.each { |s| puts "#{s.pass_to}: #{s.pass} passes" }
+    # @param team [Integer, Team] the team ID or Team 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 pass statistics
+    def self.passes_received(team:, season: Utils.current_season, season_type: "Regular Season",
+      per_mode: "PerGame", client: CLIENT)
+      fetch_stats(team, season, season_type, per_mode, PASSES_RECEIVED, client: client)
+    end
+
+    # Fetches pass stats from the API
+    #
+    # @api private
+    # @return [Collection] collection of pass stats
+    def self.fetch_stats(team, season, season_type, per_mode, result_set_name, client:)
+      path = build_path(team, season, season_type, per_mode)
+      response = client.get(path)
+      parse_response(response, result_set_name)
+    end
+    private_class_method :fetch_stats
+
+    # Builds the API path
+    #
+    # @api private
+    # @return [String] the request path
+    def self.build_path(team, season, season_type, per_mode)
+      team_id = Utils.extract_id(team)
+      season_str = Utils.format_season(season)
+      "teamdashptpass?TeamID=#{team_id}&Season=#{season_str}" \
+        "&SeasonType=#{season_type}&PerMode=#{per_mode}&LeagueID=00"
+    end
+    private_class_method :build_path
+
+    # Parses the API response into pass stat objects
+    #
+    # @api private
+    # @return [Collection] collection of pass 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_pass_stat(headers.zip(row).to_h) })
+    end
+    private_class_method :build_collection
+
+    # Builds a pass stat from API data
+    #
+    # @api private
+    # @return [TeamPassStat] the pass stat object
+    def self.build_pass_stat(data)
+      TeamPassStat.new(**identity_info(data), **pass_info(data), **shooting_info(data))
+    end
+    private_class_method :build_pass_stat
+
+    # Extracts identity information from data
+    #
+    # @api private
+    # @return [Hash] the identity information hash
+    def self.identity_info(data)
+      {team_id: data["TEAM_ID"], team_name: data["TEAM_NAME"], pass_type: data["PASS_TYPE"],
+       g: data["G"], pass_teammate_player_id: data["PASS_TEAMMATE_PLAYER_ID"]}
+    end
+    private_class_method :identity_info
+
+    # Extracts pass information from data
+    #
+    # @api private
+    # @return [Hash] the pass information hash
+    def self.pass_info(data)
+      {pass_from: data["PASS_FROM"], pass_to: data["PASS_TO"], frequency: data["FREQUENCY"],
+       pass: data["PASS"], ast: data["AST"]}
+    end
+    private_class_method :pass_info
+
+    # Extracts shooting information from data
+    #
+    # @api private
+    # @return [Hash] the shooting information hash
+    def self.shooting_info(data)
+      {fgm: data["FGM"], fga: data["FGA"], fg_pct: data["FG_PCT"],
+       fg2m: data["FG2M"], fg2a: data["FG2A"], fg2_pct: data["FG2_PCT"],
+       fg3m: data["FG3M"], fg3a: data["FG3A"], fg3_pct: data["FG3_PCT"]}
+    end
+    private_class_method :shooting_info
+  end
+end