nba 0.1.1 → 0.2.0

data/lib/nba/live_scoreboard.rb

@@ -0,0 +1,102 @@
+require "json"
+require_relative "collection"
+require_relative "live_connection"
+require_relative "live_game"
+
+module NBA
+  # Default live client instance
+  LIVE_CLIENT = LiveConnection.new
+
+  # Provides methods to retrieve live NBA scoreboard data
+  module LiveScoreboard
+    # Retrieves today's live scoreboard
+    #
+    # @api public
+    # @example
+    #   games = NBA::LiveScoreboard.today
+    #   games.each { |g| puts "#{g.away_team_tricode} #{g.away_team_score} @ #{g.home_team_tricode} #{g.home_team_score}" }
+    # @param client [LiveConnection] the API client to use
+    # @return [Collection] a collection of live games
+    def self.today(client: LIVE_CLIENT)
+      path = "scoreboard/todaysScoreboard_00.json"
+      response = client.get(path)
+      parse_response(response)
+    end
+
+    # Parses the live scoreboard API response
+    #
+    # @api private
+    # @param response [String, nil] the JSON response body
+    # @return [Collection] a collection of live games
+    def self.parse_response(response)
+      return Collection.new unless response
+
+      data = JSON.parse(response)
+      games = data.dig("scoreboard", "games")
+      return Collection.new unless games
+
+      live_games = games.map { |game| build_live_game(game) }
+      Collection.new(live_games)
+    end
+    private_class_method :parse_response
+
+    # Builds a LiveGame object from raw data
+    #
+    # @api private
+    # @param data [Hash] the game data
+    # @return [LiveGame] the live game object
+    def self.build_live_game(data)
+      LiveGame.new(**live_game_attributes(data))
+    end
+    private_class_method :build_live_game
+
+    # Combines all live game attributes
+    #
+    # @api private
+    # @param data [Hash] the game data
+    # @return [Hash] the combined attributes
+    def self.live_game_attributes(data)
+      game_info_attributes(data).merge(home_team_attributes(data), away_team_attributes(data))
+    end
+    private_class_method :live_game_attributes
+
+    # Extracts game info attributes from data
+    #
+    # @api private
+    # @param data [Hash] the game data
+    # @return [Hash] game info attributes
+    def self.game_info_attributes(data)
+      {game_id: data["gameId"], game_code: data["gameCode"],
+       game_status: data["gameStatus"], game_status_text: data["gameStatusText"],
+       period: data["period"], game_clock: data["gameClock"],
+       game_time_utc: data["gameTimeUTC"], game_et: data["gameEt"]}
+    end
+    private_class_method :game_info_attributes
+
+    # Extracts home team attributes from data
+    #
+    # @api private
+    # @param data [Hash] the game data
+    # @return [Hash] home team attributes
+    def self.home_team_attributes(data)
+      home = data["homeTeam"] || {}
+      {home_team_id: home["teamId"], home_team_name: home["teamName"],
+       home_team_city: home["teamCity"], home_team_tricode: home["teamTricode"],
+       home_team_score: home["score"]}
+    end
+    private_class_method :home_team_attributes
+
+    # Extracts away team attributes from data
+    #
+    # @api private
+    # @param data [Hash] the game data
+    # @return [Hash] away team attributes
+    def self.away_team_attributes(data)
+      away = data["awayTeam"] || {}
+      {away_team_id: away["teamId"], away_team_name: away["teamName"],
+       away_team_city: away["teamCity"], away_team_tricode: away["teamTricode"],
+       away_team_score: away["score"]}
+    end
+    private_class_method :away_team_attributes
+  end
+end

data/lib/nba/matchup_rollup.rb

@@ -0,0 +1,98 @@
+require "equalizer"
+require "shale"
+
+module NBA
+  # Represents a matchup rollup statistic entry
+  #
+  # @api public
+  # @example
+  #   matchup.def_player_name #=> "Jayson Tatum"
+  #   matchup.matchup_fg_pct #=> 0.425
+  class MatchupRollup < Shale::Mapper
+    include Equalizer.new(:season_id, :def_player_id, :position)
+
+    #   Returns the season ID
+    #   @api public
+    #   @example
+    #     matchup.season_id #=> "22023"
+    #   @return [String, nil] the season ID
+    attribute :season_id, Shale::Type::String
+
+    #   Returns the position
+    #   @api public
+    #   @example
+    #     matchup.position #=> "F"
+    #   @return [String, nil] the position
+    attribute :position, Shale::Type::String
+
+    #   Returns percent of time
+    #   @api public
+    #   @example
+    #     matchup.percent_of_time #=> 0.15
+    #   @return [Float, nil] percent of time
+    attribute :percent_of_time, Shale::Type::Float
+
+    #   Returns the defensive player ID
+    #   @api public
+    #   @example
+    #     matchup.def_player_id #=> 1628369
+    #   @return [Integer, nil] the defensive player ID
+    attribute :def_player_id, Shale::Type::Integer
+
+    #   Returns the defensive player name
+    #   @api public
+    #   @example
+    #     matchup.def_player_name #=> "Jayson Tatum"
+    #   @return [String, nil] the defensive player name
+    attribute :def_player_name, Shale::Type::String
+
+    #   Returns games played
+    #   @api public
+    #   @example
+    #     matchup.gp #=> 82
+    #   @return [Integer, nil] games played
+    attribute :gp, Shale::Type::Integer
+
+    #   Returns matchup minutes
+    #   @api public
+    #   @example
+    #     matchup.matchup_min #=> 2.5
+    #   @return [Float, nil] matchup minutes
+    attribute :matchup_min, Shale::Type::Float
+
+    #   Returns partial possessions
+    #   @api public
+    #   @example
+    #     matchup.partial_poss #=> 1.8
+    #   @return [Float, nil] partial possessions
+    attribute :partial_poss, Shale::Type::Float
+
+    #   Returns player points
+    #   @api public
+    #   @example
+    #     matchup.player_pts #=> 1.2
+    #   @return [Float, nil] player points
+    attribute :player_pts, Shale::Type::Float
+
+    #   Returns team points
+    #   @api public
+    #   @example
+    #     matchup.team_pts #=> 1.4
+    #   @return [Float, nil] team points
+    attribute :team_pts, Shale::Type::Float
+
+    #   Returns matchup field goal percentage
+    #   @api public
+    #   @example
+    #     matchup.matchup_fg_pct #=> 0.425
+    #   @return [Float, nil] matchup field goal percentage
+    attribute :matchup_fg_pct, Shale::Type::Float
+
+    #   Returns matchup 3-point percentage
+    #   @api public
+    #   @example
+    #     matchup.matchup_fg3_pct #=> 0.375
+    #   @return [Float, nil] matchup 3-point percentage
+    attribute :matchup_fg3_pct, Shale::Type::Float
+  end
+end

data/lib/nba/matchups_rollup.rb

@@ -0,0 +1,81 @@
+require "json"
+require_relative "client"
+require_relative "collection"
+require_relative "matchup_rollup"
+require_relative "league"
+require_relative "response_parser"
+require_relative "utils"
+
+module NBA
+  # Provides methods to retrieve NBA matchup rollup statistics
+  module MatchupsRollup
+    # Result set name for matchups rollup
+    # @return [String] the result set name
+    RESULT_SET = "MatchupsRollup".freeze
+
+    # Retrieves matchup rollup statistics
+    #
+    # @api public
+    # @example
+    #   matchups = NBA::MatchupsRollup.all(season: 2023)
+    #   matchups.each { |m| puts "#{m.def_player_name}: #{m.matchup_fg_pct}" }
+    # @param season [Integer] the season year (defaults to current season)
+    # @param season_type [String] the season type (Regular Season, Playoffs, etc.)
+    # @param per_mode [String] the per mode (Totals, PerGame, etc.)
+    # @param def_player [Integer, Player, nil] the defensive player ID or Player object
+    # @param def_team [Integer, Team, nil] the defensive team ID or Team object
+    # @param off_player [Integer, Player, nil] the offensive player ID or Player object
+    # @param off_team [Integer, Team, nil] the offensive team ID or Team object
+    # @param league [String, League] the league ID or League object
+    # @param client [Client] the API client to use
+    # @return [Collection] a collection of matchup rollups
+    def self.all(season: Utils.current_season, season_type: "Regular Season",
+      per_mode: "Totals", def_player: nil, def_team: nil, off_player: nil,
+      off_team: nil, league: League::NBA, client: CLIENT)
+      league_id = Utils.extract_league_id(league)
+      opts = {season: season, season_type: season_type, per_mode: per_mode,
+              def_player_id: Utils.extract_id(def_player), def_team_id: Utils.extract_id(def_team),
+              off_player_id: Utils.extract_id(off_player), off_team_id: Utils.extract_id(off_team),
+              league_id: league_id}
+      ResponseParser.parse(client.get(build_path(opts)), result_set: RESULT_SET) do |data|
+        build_matchup(data)
+      end
+    end
+
+    # Builds the API request path
+    # @api private
+    # @return [String] the request path
+    def self.build_path(opts)
+      "matchupsrollup?DefPlayerID=#{opts[:def_player_id]}&DefTeamID=#{opts[:def_team_id]}" \
+        "&LeagueID=#{opts[:league_id]}&OffPlayerID=#{opts[:off_player_id]}" \
+        "&OffTeamID=#{opts[:off_team_id]}&PerMode=#{opts[:per_mode]}" \
+        "&Season=#{Utils.format_season(opts[:season])}&SeasonType=#{opts[:season_type]}"
+    end
+    private_class_method :build_path
+
+    # Builds a MatchupRollup object from raw data
+    # @api private
+    # @param data [Hash] the row data
+    # @return [MatchupRollup] the matchup object
+    def self.build_matchup(data)
+      MatchupRollup.new(**matchup_attributes(data))
+    end
+    private_class_method :build_matchup
+
+    # Extracts matchup attributes from data
+    # @api private
+    # @param data [Hash] the row data
+    # @return [Hash] matchup attributes
+    def self.matchup_attributes(data)
+      {season_id: data["SEASON_ID"], position: data["POSITION"],
+       percent_of_time: data["PERCENT_OF_TIME"],
+       def_player_id: data["DEF_PLAYER_ID"],
+       def_player_name: data["DEF_PLAYER_NAME"], gp: data["GP"],
+       matchup_min: data["MATCHUP_MIN"],
+       partial_poss: data["PARTIAL_POSS"], player_pts: data["PLAYER_PTS"],
+       team_pts: data["TEAM_PTS"], matchup_fg_pct: data["MATCHUP_FG_PCT"],
+       matchup_fg3_pct: data["MATCHUP_FG3_PCT"]}
+    end
+    private_class_method :matchup_attributes
+  end
+end

data/lib/nba/pass_stat.rb

@@ -0,0 +1,209 @@
+require "equalizer"
+require "shale"
+
+module NBA
+  # Represents player tracking pass statistics
+  #
+  # @api public
+  class PassStat < Shale::Mapper
+    include Equalizer.new(:player_id, :pass_to)
+
+    # @!attribute [rw] player_id
+    #   Returns the player ID
+    #   @api public
+    #   @example
+    #     stat.player_id #=> 201939
+    #   @return [Integer] the player ID
+    attribute :player_id, Shale::Type::Integer
+
+    # @!attribute [rw] player_name_last_first
+    #   Returns the player name in "Last, First" format
+    #   @api public
+    #   @example
+    #     stat.player_name_last_first #=> "Curry, Stephen"
+    #   @return [String] the player name
+    attribute :player_name_last_first, Shale::Type::String
+
+    # @!attribute [rw] pass_to
+    #   Returns the pass recipient or passer name
+    #   @api public
+    #   @example
+    #     stat.pass_to #=> "Klay Thompson"
+    #   @return [String] the pass partner name
+    attribute :pass_to, Shale::Type::String
+
+    # @!attribute [rw] pass_teammate_player_id
+    #   Returns the pass partner player ID
+    #   @api public
+    #   @example
+    #     stat.pass_teammate_player_id #=> 202691
+    #   @return [Integer] the teammate player ID
+    attribute :pass_teammate_player_id, Shale::Type::Integer
+
+    # @!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_abbreviation
+    #   Returns the team abbreviation
+    #   @api public
+    #   @example
+    #     stat.team_abbreviation #=> "GSW"
+    #   @return [String] the team abbreviation
+    attribute :team_abbreviation, Shale::Type::String
+
+    # @!attribute [rw] gp
+    #   Returns games played
+    #   @api public
+    #   @example
+    #     stat.gp #=> 74
+    #   @return [Integer] games played
+    attribute :gp, Shale::Type::Integer
+
+    # @!attribute [rw] g
+    #   Returns games
+    #   @api public
+    #   @example
+    #     stat.g #=> 74
+    #   @return [Integer] games
+    attribute :g, Shale::Type::Integer
+
+    # @!attribute [rw] pass_type
+    #   Returns the type of pass
+    #   @api public
+    #   @example
+    #     stat.pass_type #=> "Made"
+    #   @return [String] the pass type
+    attribute :pass_type, Shale::Type::String
+
+    # @!attribute [rw] frequency
+    #   Returns the frequency percentage
+    #   @api public
+    #   @example
+    #     stat.frequency #=> 0.25
+    #   @return [Float] the frequency
+    attribute :frequency, Shale::Type::Float
+
+    # @!attribute [rw] pass
+    #   Returns passes per game
+    #   @api public
+    #   @example
+    #     stat.pass #=> 5.2
+    #   @return [Float] passes per game
+    attribute :pass, Shale::Type::Float
+
+    # @!attribute [rw] ast
+    #   Returns assists per game
+    #   @api public
+    #   @example
+    #     stat.ast #=> 2.1
+    #   @return [Float] assists per game
+    attribute :ast, Shale::Type::Float
+
+    # @!attribute [rw] fgm
+    #   Returns field goals made following pass
+    #   @api public
+    #   @example
+    #     stat.fgm #=> 3.5
+    #   @return [Float] field goals made
+    attribute :fgm, Shale::Type::Float
+
+    # @!attribute [rw] fga
+    #   Returns field goals attempted following pass
+    #   @api public
+    #   @example
+    #     stat.fga #=> 7.2
+    #   @return [Float] field goals attempted
+    attribute :fga, Shale::Type::Float
+
+    # @!attribute [rw] fg_pct
+    #   Returns field goal percentage following pass
+    #   @api public
+    #   @example
+    #     stat.fg_pct #=> 0.486
+    #   @return [Float] field goal percentage
+    attribute :fg_pct, Shale::Type::Float
+
+    # @!attribute [rw] fg2m
+    #   Returns two-pointers made following pass
+    #   @api public
+    #   @example
+    #     stat.fg2m #=> 1.5
+    #   @return [Float] two-pointers made
+    attribute :fg2m, Shale::Type::Float
+
+    # @!attribute [rw] fg2a
+    #   Returns two-pointers attempted following pass
+    #   @api public
+    #   @example
+    #     stat.fg2a #=> 3.0
+    #   @return [Float] two-pointers attempted
+    attribute :fg2a, Shale::Type::Float
+
+    # @!attribute [rw] fg2_pct
+    #   Returns two-point percentage following pass
+    #   @api public
+    #   @example
+    #     stat.fg2_pct #=> 0.500
+    #   @return [Float] two-point percentage
+    attribute :fg2_pct, Shale::Type::Float
+
+    # @!attribute [rw] fg3m
+    #   Returns three-pointers made following pass
+    #   @api public
+    #   @example
+    #     stat.fg3m #=> 2.0
+    #   @return [Float] three-pointers made
+    attribute :fg3m, Shale::Type::Float
+
+    # @!attribute [rw] fg3a
+    #   Returns three-pointers attempted following pass
+    #   @api public
+    #   @example
+    #     stat.fg3a #=> 4.2
+    #   @return [Float] three-pointers attempted
+    attribute :fg3a, Shale::Type::Float
+
+    # @!attribute [rw] fg3_pct
+    #   Returns three-point percentage following pass
+    #   @api public
+    #   @example
+    #     stat.fg3_pct #=> 0.476
+    #   @return [Float] three-point percentage
+    attribute :fg3_pct, Shale::Type::Float
+
+    # Returns the player object
+    #
+    # @api public
+    # @example
+    #   stat.player #=> #<NBA::Player>
+    # @return [Player, nil] the player object
+    def player
+      Players.find(player_id)
+    end
+
+    # Returns the teammate player object
+    #
+    # @api public
+    # @example
+    #   stat.teammate #=> #<NBA::Player>
+    # @return [Player, nil] the teammate player object
+    def teammate
+      Players.find(pass_teammate_player_id)
+    end
+
+    # 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