nba 0.1.1 → 0.2.0

data/lib/nba/league_season_matchup_stat.rb

@@ -0,0 +1,241 @@
+require "equalizer"
+require "shale"
+require_relative "players"
+require_relative "teams"
+
+module NBA
+  # Represents a season matchup statistic between offensive and defensive players
+  #
+  # @api public
+  class LeagueSeasonMatchupStat < Shale::Mapper
+    include Equalizer.new(:season_id, :off_player_id, :def_player_id)
+
+    # @!attribute [rw] season_id
+    #   Returns the season ID
+    #   @api public
+    #   @example
+    #     stat.season_id #=> "22024"
+    #   @return [String, nil] the season ID
+    attribute :season_id, Shale::Type::String
+
+    # @!attribute [rw] off_player_id
+    #   Returns the offensive player ID
+    #   @api public
+    #   @example
+    #     stat.off_player_id #=> 201939
+    #   @return [Integer, nil] the offensive player's ID
+    attribute :off_player_id, Shale::Type::Integer
+
+    # @!attribute [rw] off_player_name
+    #   Returns the offensive player name
+    #   @api public
+    #   @example
+    #     stat.off_player_name #=> "Stephen Curry"
+    #   @return [String, nil] the offensive player's name
+    attribute :off_player_name, Shale::Type::String
+
+    # @!attribute [rw] def_player_id
+    #   Returns the defensive player ID
+    #   @api public
+    #   @example
+    #     stat.def_player_id #=> 203507
+    #   @return [Integer, nil] the defensive player's ID
+    attribute :def_player_id, Shale::Type::Integer
+
+    # @!attribute [rw] def_player_name
+    #   Returns the defensive player name
+    #   @api public
+    #   @example
+    #     stat.def_player_name #=> "Giannis Antetokounmpo"
+    #   @return [String, nil] the defensive player's name
+    attribute :def_player_name, Shale::Type::String
+
+    # @!attribute [rw] gp
+    #   Returns games played
+    #   @api public
+    #   @example
+    #     stat.gp #=> 4
+    #   @return [Integer, nil] games played
+    attribute :gp, Shale::Type::Integer
+
+    # @!attribute [rw] matchup_min
+    #   Returns matchup minutes
+    #   @api public
+    #   @example
+    #     stat.matchup_min #=> 12.5
+    #   @return [Float, nil] matchup minutes
+    attribute :matchup_min, Shale::Type::Float
+
+    # @!attribute [rw] partial_poss
+    #   Returns partial possessions
+    #   @api public
+    #   @example
+    #     stat.partial_poss #=> 45.2
+    #   @return [Float, nil] partial possessions
+    attribute :partial_poss, Shale::Type::Float
+
+    # @!attribute [rw] player_pts
+    #   Returns points scored by offensive player
+    #   @api public
+    #   @example
+    #     stat.player_pts #=> 18.0
+    #   @return [Float, nil] player points
+    attribute :player_pts, Shale::Type::Float
+
+    # @!attribute [rw] team_pts
+    #   Returns team points during matchup
+    #   @api public
+    #   @example
+    #     stat.team_pts #=> 22.0
+    #   @return [Float, nil] team points
+    attribute :team_pts, Shale::Type::Float
+
+    # @!attribute [rw] matchup_ast
+    #   Returns assists during matchup
+    #   @api public
+    #   @example
+    #     stat.matchup_ast #=> 3.0
+    #   @return [Float, nil] matchup assists
+    attribute :matchup_ast, Shale::Type::Float
+
+    # @!attribute [rw] matchup_tov
+    #   Returns turnovers during matchup
+    #   @api public
+    #   @example
+    #     stat.matchup_tov #=> 1.0
+    #   @return [Float, nil] matchup turnovers
+    attribute :matchup_tov, Shale::Type::Float
+
+    # @!attribute [rw] matchup_blk
+    #   Returns blocks during matchup
+    #   @api public
+    #   @example
+    #     stat.matchup_blk #=> 0.5
+    #   @return [Float, nil] matchup blocks
+    attribute :matchup_blk, Shale::Type::Float
+
+    # @!attribute [rw] matchup_fgm
+    #   Returns field goals made during matchup
+    #   @api public
+    #   @example
+    #     stat.matchup_fgm #=> 6.0
+    #   @return [Float, nil] matchup field goals made
+    attribute :matchup_fgm, Shale::Type::Float
+
+    # @!attribute [rw] matchup_fga
+    #   Returns field goals attempted during matchup
+    #   @api public
+    #   @example
+    #     stat.matchup_fga #=> 14.0
+    #   @return [Float, nil] matchup field goals attempted
+    attribute :matchup_fga, Shale::Type::Float
+
+    # @!attribute [rw] matchup_fg_pct
+    #   Returns field goal percentage during matchup
+    #   @api public
+    #   @example
+    #     stat.matchup_fg_pct #=> 0.429
+    #   @return [Float, nil] matchup field goal percentage
+    attribute :matchup_fg_pct, Shale::Type::Float
+
+    # @!attribute [rw] matchup_fg3m
+    #   Returns three-pointers made during matchup
+    #   @api public
+    #   @example
+    #     stat.matchup_fg3m #=> 2.0
+    #   @return [Float, nil] matchup three-pointers made
+    attribute :matchup_fg3m, Shale::Type::Float
+
+    # @!attribute [rw] matchup_fg3a
+    #   Returns three-pointers attempted during matchup
+    #   @api public
+    #   @example
+    #     stat.matchup_fg3a #=> 6.0
+    #   @return [Float, nil] matchup three-pointers attempted
+    attribute :matchup_fg3a, Shale::Type::Float
+
+    # @!attribute [rw] matchup_fg3_pct
+    #   Returns three-point percentage during matchup
+    #   @api public
+    #   @example
+    #     stat.matchup_fg3_pct #=> 0.333
+    #   @return [Float, nil] matchup three-point percentage
+    attribute :matchup_fg3_pct, Shale::Type::Float
+
+    # @!attribute [rw] help_blk
+    #   Returns help blocks
+    #   @api public
+    #   @example
+    #     stat.help_blk #=> 0.0
+    #   @return [Float, nil] help blocks
+    attribute :help_blk, Shale::Type::Float
+
+    # @!attribute [rw] help_fgm
+    #   Returns help field goals made
+    #   @api public
+    #   @example
+    #     stat.help_fgm #=> 1.0
+    #   @return [Float, nil] help field goals made
+    attribute :help_fgm, Shale::Type::Float
+
+    # @!attribute [rw] help_fga
+    #   Returns help field goals attempted
+    #   @api public
+    #   @example
+    #     stat.help_fga #=> 2.0
+    #   @return [Float, nil] help field goals attempted
+    attribute :help_fga, Shale::Type::Float
+
+    # @!attribute [rw] help_fg_pct
+    #   Returns help field goal percentage
+    #   @api public
+    #   @example
+    #     stat.help_fg_pct #=> 0.500
+    #   @return [Float, nil] help field goal percentage
+    attribute :help_fg_pct, Shale::Type::Float
+
+    # @!attribute [rw] matchup_ftm
+    #   Returns free throws made during matchup
+    #   @api public
+    #   @example
+    #     stat.matchup_ftm #=> 4.0
+    #   @return [Float, nil] matchup free throws made
+    attribute :matchup_ftm, Shale::Type::Float
+
+    # @!attribute [rw] matchup_fta
+    #   Returns free throws attempted during matchup
+    #   @api public
+    #   @example
+    #     stat.matchup_fta #=> 5.0
+    #   @return [Float, nil] matchup free throws attempted
+    attribute :matchup_fta, Shale::Type::Float
+
+    # @!attribute [rw] sfl
+    #   Returns shooting fouls drawn
+    #   @api public
+    #   @example
+    #     stat.sfl #=> 2.0
+    #   @return [Float, nil] shooting fouls
+    attribute :sfl, Shale::Type::Float
+
+    # Returns the offensive player
+    #
+    # @api public
+    # @example
+    #   stat.off_player #=> #<NBA::Player id=201939 ...>
+    # @return [Player, nil] the offensive player object
+    def off_player
+      Players.find(off_player_id)
+    end
+
+    # Returns the defensive player
+    #
+    # @api public
+    # @example
+    #   stat.def_player #=> #<NBA::Player id=203507 ...>
+    # @return [Player, nil] the defensive player object
+    def def_player
+      Players.find(def_player_id)
+    end
+  end
+end

data/lib/nba/league_season_matchups.rb

@@ -0,0 +1,181 @@
+require "json"
+require_relative "client"
+require_relative "collection"
+require_relative "league_season_matchup_stat"
+require_relative "utils"
+
+module NBA
+  # Provides methods to retrieve league-wide season matchup statistics
+  #
+  # @api public
+  module LeagueSeasonMatchups
+    # Result set name for season matchups
+    # @return [String] the result set name
+    SEASON_MATCHUPS = "SeasonMatchups".freeze
+
+    # Regular season type constant
+    # @return [String] the season type
+    REGULAR_SEASON = "Regular Season".freeze
+
+    # Playoffs season type constant
+    # @return [String] the season type
+    PLAYOFFS = "Playoffs".freeze
+
+    # Per game mode constant
+    # @return [String] the per mode
+    PER_GAME = "PerGame".freeze
+
+    # Totals mode constant
+    # @return [String] the per mode
+    TOTALS = "Totals".freeze
+
+    # Retrieves all league-wide season matchup statistics
+    #
+    # @api public
+    # @example
+    #   matchups = NBA::LeagueSeasonMatchups.all(season: 2024)
+    #   matchups.first.off_player_name #=> "Stephen Curry"
+    # @param season [Integer] the season year
+    # @param season_type [String] the season type
+    # @param per_mode [String] the per mode
+    # @param off_player [Integer, #id, nil] offensive player ID or object
+    # @param def_player [Integer, #id, nil] defensive player ID or object
+    # @param off_team [Integer, #id, nil] offensive team ID or object
+    # @param def_team [Integer, #id, nil] defensive team ID or object
+    # @param client [Client] the API client to use
+    # @return [Collection] a collection of matchup statistics
+    def self.all(season: Utils.current_season, season_type: REGULAR_SEASON, per_mode: PER_GAME,
+      off_player: nil, def_player: nil, off_team: nil, def_team: nil, client: CLIENT)
+      path = build_path(season, season_type: season_type, per_mode: per_mode,
+        off_player: off_player, def_player: def_player, off_team: off_team, def_team: def_team)
+      response = client.get(path)
+      parse_response(response)
+    end
+
+    # Builds the API request path
+    #
+    # @api private
+    # @return [String] the request path
+    def self.build_path(season, opts)
+      season_str = Utils.format_season(season)
+      path = "leagueseasonmatchups?LeagueID=00&Season=#{season_str}" \
+             "&SeasonType=#{opts.fetch(:season_type)}&PerMode=#{opts.fetch(:per_mode)}"
+      append_optional_params(path, opts)
+    end
+    private_class_method :build_path
+
+    # Appends optional parameters to the path
+    #
+    # @api private
+    # @return [String] the path with optional parameters
+    def self.append_optional_params(path, opts)
+      off_player_id = Utils.extract_id(opts.fetch(:off_player))
+      def_player_id = Utils.extract_id(opts.fetch(:def_player))
+      off_team_id = Utils.extract_id(opts.fetch(:off_team))
+      def_team_id = Utils.extract_id(opts.fetch(:def_team))
+
+      path += "&OffPlayerID=#{off_player_id}" if off_player_id
+      path += "&DefPlayerID=#{def_player_id}" if def_player_id
+      path += "&OffTeamID=#{off_team_id}" if off_team_id
+      path += "&DefTeamID=#{def_team_id}" if def_team_id
+      path
+    end
+    private_class_method :append_optional_params
+
+    # Parses the API response into stat objects
+    #
+    # @api private
+    # @return [Collection] collection of matchup stats
+    def self.parse_response(response)
+      return Collection.new if response.nil? || response.empty?
+
+      data = JSON.parse(response)
+      result_set = find_result_set(data)
+      build_stats(result_set)
+    end
+    private_class_method :parse_response
+
+    # Finds the 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_sets = data["resultSets"]
+      return unless result_sets
+
+      result_sets.find { |rs| rs["name"].eql?(SEASON_MATCHUPS) }
+    end
+    private_class_method :find_result_set
+
+    # Builds stats collection from result set
+    #
+    # @api private
+    # @return [Collection] the stats collection
+    def self.build_stats(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_stats
+
+    # Builds a single stat object from API data
+    #
+    # @api private
+    # @return [LeagueSeasonMatchupStat] the stat object
+    def self.build_stat(data)
+      LeagueSeasonMatchupStat.new(**identity_info(data), **matchup_stats(data), **shooting_stats(data),
+        **help_stats(data))
+    end
+    private_class_method :build_stat
+
+    # Extracts identity information from data
+    #
+    # @api private
+    # @return [Hash] the identity information hash
+    def self.identity_info(data)
+      {season_id: data["SEASON_ID"], off_player_id: data["OFF_PLAYER_ID"],
+       off_player_name: data["OFF_PLAYER_NAME"], def_player_id: data["DEF_PLAYER_ID"],
+       def_player_name: data["DEF_PLAYER_NAME"], gp: data["GP"]}
+    end
+    private_class_method :identity_info
+
+    # Extracts matchup statistics from data
+    #
+    # @api private
+    # @return [Hash] the matchup statistics hash
+    def self.matchup_stats(data)
+      {matchup_min: data["MATCHUP_MIN"], partial_poss: data["PARTIAL_POSS"],
+       player_pts: data["PLAYER_PTS"], team_pts: data["TEAM_PTS"],
+       matchup_ast: data["MATCHUP_AST"], matchup_tov: data["MATCHUP_TOV"],
+       matchup_blk: data["MATCHUP_BLK"]}
+    end
+    private_class_method :matchup_stats
+
+    # Extracts shooting statistics from data
+    #
+    # @api private
+    # @return [Hash] the shooting statistics hash
+    def self.shooting_stats(data)
+      {matchup_fgm: data["MATCHUP_FGM"], matchup_fga: data["MATCHUP_FGA"],
+       matchup_fg_pct: data["MATCHUP_FG_PCT"], matchup_fg3m: data["MATCHUP_FG3M"],
+       matchup_fg3a: data["MATCHUP_FG3A"], matchup_fg3_pct: data["MATCHUP_FG3_PCT"],
+       matchup_ftm: data["MATCHUP_FTM"], matchup_fta: data["MATCHUP_FTA"],
+       sfl: data["SFL"]}
+    end
+    private_class_method :shooting_stats
+
+    # Extracts help defense statistics from data
+    #
+    # @api private
+    # @return [Hash] the help defense statistics hash
+    def self.help_stats(data)
+      {help_blk: data["HELP_BLK"], help_fgm: data["HELP_FGM"],
+       help_fga: data["HELP_FGA"], help_fg_pct: data["HELP_FG_PERC"]}
+    end
+    private_class_method :help_stats
+  end
+end

data/lib/nba/league_standing.rb

@@ -0,0 +1,284 @@
+module NBA
+  # Represents a team's standing with extended information
+  class LeagueStanding < Shale::Mapper
+    include Equalizer.new(:team_id, :season_id)
+
+    # @!attribute [rw] league_id
+    #   Returns the league ID
+    #   @api public
+    #   @example
+    #     standing.league_id #=> "00"
+    #   @return [String] the league ID
+    attribute :league_id, Shale::Type::String
+
+    # @!attribute [rw] season_id
+    #   Returns the season ID
+    #   @api public
+    #   @example
+    #     standing.season_id #=> "22024"
+    #   @return [String] the season ID
+    attribute :season_id, Shale::Type::String
+
+    # @!attribute [rw] team_id
+    #   Returns the team ID
+    #   @api public
+    #   @example
+    #     standing.team_id #=> 1610612744
+    #   @return [Integer] the team ID
+    attribute :team_id, Shale::Type::Integer
+
+    # @!attribute [rw] team_city
+    #   Returns the team city
+    #   @api public
+    #   @example
+    #     standing.team_city #=> "Golden State"
+    #   @return [String] the team city
+    attribute :team_city, Shale::Type::String
+
+    # @!attribute [rw] team_name
+    #   Returns the team name
+    #   @api public
+    #   @example
+    #     standing.team_name #=> "Warriors"
+    #   @return [String] the team name
+    attribute :team_name, Shale::Type::String
+
+    # @!attribute [rw] team_slug
+    #   Returns the team slug
+    #   @api public
+    #   @example
+    #     standing.team_slug #=> "warriors"
+    #   @return [String] the team slug
+    attribute :team_slug, Shale::Type::String
+
+    # @!attribute [rw] conference
+    #   Returns the conference
+    #   @api public
+    #   @example
+    #     standing.conference #=> "West"
+    #   @return [String] the conference
+    attribute :conference, Shale::Type::String
+
+    # @!attribute [rw] conference_record
+    #   Returns the conference record
+    #   @api public
+    #   @example
+    #     standing.conference_record #=> "30-22"
+    #   @return [String] the conference record
+    attribute :conference_record, Shale::Type::String
+
+    # @!attribute [rw] playoff_rank
+    #   Returns the playoff rank
+    #   @api public
+    #   @example
+    #     standing.playoff_rank #=> 10
+    #   @return [Integer] the playoff rank
+    attribute :playoff_rank, Shale::Type::Integer
+
+    # @!attribute [rw] clinch_indicator
+    #   Returns the clinch indicator
+    #   @api public
+    #   @example
+    #     standing.clinch_indicator #=> "x"
+    #   @return [String] the clinch indicator
+    attribute :clinch_indicator, Shale::Type::String
+
+    # @!attribute [rw] division
+    #   Returns the division
+    #   @api public
+    #   @example
+    #     standing.division #=> "Pacific"
+    #   @return [String] the division
+    attribute :division, Shale::Type::String
+
+    # @!attribute [rw] division_record
+    #   Returns the division record
+    #   @api public
+    #   @example
+    #     standing.division_record #=> "8-8"
+    #   @return [String] the division record
+    attribute :division_record, Shale::Type::String
+
+    # @!attribute [rw] division_rank
+    #   Returns the division rank
+    #   @api public
+    #   @example
+    #     standing.division_rank #=> 3
+    #   @return [Integer] the division rank
+    attribute :division_rank, Shale::Type::Integer
+
+    # @!attribute [rw] wins
+    #   Returns the number of wins
+    #   @api public
+    #   @example
+    #     standing.wins #=> 46
+    #   @return [Integer] the wins
+    attribute :wins, Shale::Type::Integer
+
+    # @!attribute [rw] losses
+    #   Returns the number of losses
+    #   @api public
+    #   @example
+    #     standing.losses #=> 36
+    #   @return [Integer] the losses
+    attribute :losses, Shale::Type::Integer
+
+    # @!attribute [rw] win_pct
+    #   Returns the win percentage
+    #   @api public
+    #   @example
+    #     standing.win_pct #=> 0.561
+    #   @return [Float] the win percentage
+    attribute :win_pct, Shale::Type::Float
+
+    # @!attribute [rw] league_rank
+    #   Returns the league rank
+    #   @api public
+    #   @example
+    #     standing.league_rank #=> 15
+    #   @return [Integer] the league rank
+    attribute :league_rank, Shale::Type::Integer
+
+    # @!attribute [rw] record
+    #   Returns the full record string
+    #   @api public
+    #   @example
+    #     standing.record #=> "46-36"
+    #   @return [String] the record
+    attribute :record, Shale::Type::String
+
+    # @!attribute [rw] home_record
+    #   Returns the home record
+    #   @api public
+    #   @example
+    #     standing.home_record #=> "28-13"
+    #   @return [String] the home record
+    attribute :home_record, Shale::Type::String
+
+    # @!attribute [rw] road_record
+    #   Returns the road record
+    #   @api public
+    #   @example
+    #     standing.road_record #=> "18-23"
+    #   @return [String] the road record
+    attribute :road_record, Shale::Type::String
+
+    # @!attribute [rw] l10_record
+    #   Returns the last 10 games record
+    #   @api public
+    #   @example
+    #     standing.l10_record #=> "6-4"
+    #   @return [String] the L10 record
+    attribute :l10_record, Shale::Type::String
+
+    # @!attribute [rw] long_win_streak
+    #   Returns the longest win streak
+    #   @api public
+    #   @example
+    #     standing.long_win_streak #=> 7
+    #   @return [Integer] the longest win streak
+    attribute :long_win_streak, Shale::Type::Integer
+
+    # @!attribute [rw] long_loss_streak
+    #   Returns the longest loss streak
+    #   @api public
+    #   @example
+    #     standing.long_loss_streak #=> 4
+    #   @return [Integer] the longest loss streak
+    attribute :long_loss_streak, Shale::Type::Integer
+
+    # @!attribute [rw] current_streak
+    #   Returns the current streak
+    #   @api public
+    #   @example
+    #     standing.current_streak #=> "W 2"
+    #   @return [String] the current streak
+    attribute :current_streak, Shale::Type::String
+
+    # @!attribute [rw] conference_games_back
+    #   Returns games back in the conference
+    #   @api public
+    #   @example
+    #     standing.conference_games_back #=> 12.0
+    #   @return [Float] the games back
+    attribute :conference_games_back, Shale::Type::Float
+
+    # @!attribute [rw] clinched_conference_title
+    #   Returns if team clinched conference title
+    #   @api public
+    #   @example
+    #     standing.clinched_conference_title #=> 0
+    #   @return [Integer] 1 if clinched, 0 otherwise
+    attribute :clinched_conference_title, Shale::Type::Integer
+
+    # @!attribute [rw] clinched_playoff_birth
+    #   Returns if team clinched playoff berth
+    #   @api public
+    #   @example
+    #     standing.clinched_playoff_birth #=> 1
+    #   @return [Integer] 1 if clinched, 0 otherwise
+    attribute :clinched_playoff_birth, Shale::Type::Integer
+
+    # @!attribute [rw] eliminated_conference
+    #   Returns if team is eliminated from conference
+    #   @api public
+    #   @example
+    #     standing.eliminated_conference #=> 0
+    #   @return [Integer] 1 if eliminated, 0 otherwise
+    attribute :eliminated_conference, Shale::Type::Integer
+
+    # @!attribute [rw] points_pg
+    #   Returns points per game
+    #   @api public
+    #   @example
+    #     standing.points_pg #=> 118.7
+    #   @return [Float] the points per game
+    attribute :points_pg, Shale::Type::Float
+
+    # @!attribute [rw] opp_points_pg
+    #   Returns opponent points per game
+    #   @api public
+    #   @example
+    #     standing.opp_points_pg #=> 117.2
+    #   @return [Float] the opponent points per game
+    attribute :opp_points_pg, Shale::Type::Float
+
+    # @!attribute [rw] diff_points_pg
+    #   Returns point differential per game
+    #   @api public
+    #   @example
+    #     standing.diff_points_pg #=> 1.5
+    #   @return [Float] the point differential
+    attribute :diff_points_pg, Shale::Type::Float
+
+    # Returns the team object
+    #
+    # @api public
+    # @example
+    #   standing.team #=> #<NBA::Team>
+    # @return [Team, nil] the team object
+    def team
+      Teams.find(team_id)
+    end
+
+    # Returns the full team name
+    #
+    # @api public
+    # @example
+    #   standing.full_name #=> "Golden State Warriors"
+    # @return [String] the full name
+    def full_name
+      "#{team_city} #{team_name}".strip
+    end
+
+    # Returns whether the team made the playoffs
+    #
+    # @api public
+    # @example
+    #   standing.playoffs? #=> true
+    # @return [Boolean] true if in playoffs
+    def playoffs?
+      clinched_playoff_birth.eql?(1)
+    end
+  end
+end