nba 0.1.1 → 0.2.0

data/lib/nba/game_log.rb

@@ -0,0 +1,349 @@
+require "equalizer"
+require "shale"
+
+module NBA
+  # Represents a single game log entry for a player or team
+  #
+  # @api public
+  class GameLog < Shale::Mapper
+    include Equalizer.new(:game_id, :player_id)
+
+    # @!attribute [rw] season_id
+    #   Returns the season ID
+    #   @api public
+    #   @example
+    #     log.season_id #=> "22024"
+    #   @return [String] the season ID
+    attribute :season_id, Shale::Type::String
+
+    # @!attribute [rw] player_id
+    #   Returns the player ID
+    #   @api public
+    #   @example
+    #     log.player_id #=> 201939
+    #   @return [Integer] the player ID
+    attribute :player_id, Shale::Type::Integer
+
+    # @!attribute [rw] player_name
+    #   Returns the player name
+    #   @api public
+    #   @example
+    #     log.player_name #=> "Stephen Curry"
+    #   @return [String] the player name
+    attribute :player_name, Shale::Type::String
+
+    # @!attribute [rw] team_id
+    #   Returns the team ID
+    #   @api public
+    #   @example
+    #     log.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
+    #     log.team_abbreviation #=> "GSW"
+    #   @return [String] the team abbreviation
+    attribute :team_abbreviation, Shale::Type::String
+
+    # @!attribute [rw] team_name
+    #   Returns the team name
+    #   @api public
+    #   @example
+    #     log.team_name #=> "Warriors"
+    #   @return [String] the team name
+    attribute :team_name, Shale::Type::String
+
+    # @!attribute [rw] game_id
+    #   Returns the game ID
+    #   @api public
+    #   @example
+    #     log.game_id #=> "0022400001"
+    #   @return [String] the game ID
+    attribute :game_id, Shale::Type::String
+
+    # @!attribute [rw] game_date
+    #   Returns the game date
+    #   @api public
+    #   @example
+    #     log.game_date #=> "OCT 22, 2024"
+    #   @return [String] the game date
+    attribute :game_date, Shale::Type::String
+
+    # @!attribute [rw] matchup
+    #   Returns the matchup description
+    #   @api public
+    #   @example
+    #     log.matchup #=> "GSW vs. LAL"
+    #   @return [String] the matchup
+    attribute :matchup, Shale::Type::String
+
+    # @!attribute [rw] wl
+    #   Returns the win/loss indicator
+    #   @api public
+    #   @example
+    #     log.wl #=> "W"
+    #   @return [String] W for win, L for loss
+    attribute :wl, Shale::Type::String
+
+    # @!attribute [rw] min
+    #   Returns the minutes played
+    #   @api public
+    #   @example
+    #     log.min #=> 34
+    #   @return [Integer] the minutes played
+    attribute :min, Shale::Type::Integer
+
+    # @!attribute [rw] fgm
+    #   Returns the field goals made
+    #   @api public
+    #   @example
+    #     log.fgm #=> 10
+    #   @return [Integer] field goals made
+    attribute :fgm, Shale::Type::Integer
+
+    # @!attribute [rw] fga
+    #   Returns the field goals attempted
+    #   @api public
+    #   @example
+    #     log.fga #=> 20
+    #   @return [Integer] field goals attempted
+    attribute :fga, Shale::Type::Integer
+
+    # @!attribute [rw] fg_pct
+    #   Returns the field goal percentage
+    #   @api public
+    #   @example
+    #     log.fg_pct #=> 0.500
+    #   @return [Float] field goal percentage
+    attribute :fg_pct, Shale::Type::Float
+
+    # @!attribute [rw] fg3m
+    #   Returns the three-pointers made
+    #   @api public
+    #   @example
+    #     log.fg3m #=> 5
+    #   @return [Integer] three-pointers made
+    attribute :fg3m, Shale::Type::Integer
+
+    # @!attribute [rw] fg3a
+    #   Returns the three-pointers attempted
+    #   @api public
+    #   @example
+    #     log.fg3a #=> 10
+    #   @return [Integer] three-pointers attempted
+    attribute :fg3a, Shale::Type::Integer
+
+    # @!attribute [rw] fg3_pct
+    #   Returns the three-point percentage
+    #   @api public
+    #   @example
+    #     log.fg3_pct #=> 0.500
+    #   @return [Float] three-point percentage
+    attribute :fg3_pct, Shale::Type::Float
+
+    # @!attribute [rw] ftm
+    #   Returns the free throws made
+    #   @api public
+    #   @example
+    #     log.ftm #=> 5
+    #   @return [Integer] free throws made
+    attribute :ftm, Shale::Type::Integer
+
+    # @!attribute [rw] fta
+    #   Returns the free throws attempted
+    #   @api public
+    #   @example
+    #     log.fta #=> 6
+    #   @return [Integer] free throws attempted
+    attribute :fta, Shale::Type::Integer
+
+    # @!attribute [rw] ft_pct
+    #   Returns the free throw percentage
+    #   @api public
+    #   @example
+    #     log.ft_pct #=> 0.833
+    #   @return [Float] free throw percentage
+    attribute :ft_pct, Shale::Type::Float
+
+    # @!attribute [rw] oreb
+    #   Returns the offensive rebounds
+    #   @api public
+    #   @example
+    #     log.oreb #=> 1
+    #   @return [Integer] offensive rebounds
+    attribute :oreb, Shale::Type::Integer
+
+    # @!attribute [rw] dreb
+    #   Returns the defensive rebounds
+    #   @api public
+    #   @example
+    #     log.dreb #=> 5
+    #   @return [Integer] defensive rebounds
+    attribute :dreb, Shale::Type::Integer
+
+    # @!attribute [rw] reb
+    #   Returns the total rebounds
+    #   @api public
+    #   @example
+    #     log.reb #=> 6
+    #   @return [Integer] total rebounds
+    attribute :reb, Shale::Type::Integer
+
+    # @!attribute [rw] ast
+    #   Returns the assists
+    #   @api public
+    #   @example
+    #     log.ast #=> 8
+    #   @return [Integer] assists
+    attribute :ast, Shale::Type::Integer
+
+    # @!attribute [rw] stl
+    #   Returns the steals
+    #   @api public
+    #   @example
+    #     log.stl #=> 2
+    #   @return [Integer] steals
+    attribute :stl, Shale::Type::Integer
+
+    # @!attribute [rw] blk
+    #   Returns the blocks
+    #   @api public
+    #   @example
+    #     log.blk #=> 0
+    #   @return [Integer] blocks
+    attribute :blk, Shale::Type::Integer
+
+    # @!attribute [rw] tov
+    #   Returns the turnovers
+    #   @api public
+    #   @example
+    #     log.tov #=> 3
+    #   @return [Integer] turnovers
+    attribute :tov, Shale::Type::Integer
+
+    # @!attribute [rw] pf
+    #   Returns the personal fouls
+    #   @api public
+    #   @example
+    #     log.pf #=> 2
+    #   @return [Integer] personal fouls
+    attribute :pf, Shale::Type::Integer
+
+    # @!attribute [rw] pts
+    #   Returns the points scored
+    #   @api public
+    #   @example
+    #     log.pts #=> 30
+    #   @return [Integer] points
+    attribute :pts, Shale::Type::Integer
+
+    # @!attribute [rw] plus_minus
+    #   Returns the plus/minus
+    #   @api public
+    #   @example
+    #     log.plus_minus #=> 15
+    #   @return [Integer] plus/minus
+    attribute :plus_minus, Shale::Type::Integer
+
+    # Returns whether the game was a win
+    #
+    # @api public
+    # @example
+    #   log.win? #=> true
+    # @return [Boolean] true if the game was a win
+    def win? = wl.eql?("W")
+
+    # Returns whether the game was a loss
+    #
+    # @api public
+    # @example
+    #   log.loss? #=> false
+    # @return [Boolean] true if the game was a loss
+    def loss? = wl.eql?("L")
+
+    # Returns the game object for this log entry
+    #
+    # @api public
+    # @example
+    #   log.game #=> #<NBA::Game>
+    # @return [Game, nil] the game object
+    def game = Games.find(game_id)
+
+    # Returns the player object for this log entry
+    #
+    # @api public
+    # @example
+    #   log.player #=> #<NBA::Player>
+    # @return [Player, nil] the player object
+    def player = Players.find(player_id)
+
+    # rubocop:disable Metrics/BlockLength
+    json do
+      map "season_id", to: :season_id
+      map "SEASON_ID", to: :season_id
+      map "player_id", to: :player_id
+      map "Player_ID", to: :player_id
+      map "PLAYER_ID", to: :player_id
+      map "player_name", to: :player_name
+      map "PLAYER_NAME", to: :player_name
+      map "team_id", to: :team_id
+      map "TEAM_ID", to: :team_id
+      map "team_abbreviation", to: :team_abbreviation
+      map "TEAM_ABBREVIATION", to: :team_abbreviation
+      map "team_name", to: :team_name
+      map "TEAM_NAME", to: :team_name
+      map "game_id", to: :game_id
+      map "Game_ID", to: :game_id
+      map "game_date", to: :game_date
+      map "GAME_DATE", to: :game_date
+      map "matchup", to: :matchup
+      map "MATCHUP", to: :matchup
+      map "wl", to: :wl
+      map "WL", to: :wl
+      map "min", to: :min
+      map "MIN", to: :min
+      map "fgm", to: :fgm
+      map "FGM", to: :fgm
+      map "fga", to: :fga
+      map "FGA", to: :fga
+      map "fg_pct", to: :fg_pct
+      map "FG_PCT", to: :fg_pct
+      map "fg3m", to: :fg3m
+      map "FG3M", to: :fg3m
+      map "fg3a", to: :fg3a
+      map "FG3A", to: :fg3a
+      map "fg3_pct", to: :fg3_pct
+      map "FG3_PCT", to: :fg3_pct
+      map "ftm", to: :ftm
+      map "FTM", to: :ftm
+      map "fta", to: :fta
+      map "FTA", to: :fta
+      map "ft_pct", to: :ft_pct
+      map "FT_PCT", to: :ft_pct
+      map "oreb", to: :oreb
+      map "OREB", to: :oreb
+      map "dreb", to: :dreb
+      map "DREB", to: :dreb
+      map "reb", to: :reb
+      map "REB", to: :reb
+      map "ast", to: :ast
+      map "AST", to: :ast
+      map "stl", to: :stl
+      map "STL", to: :stl
+      map "blk", to: :blk
+      map "BLK", to: :blk
+      map "tov", to: :tov
+      map "TOV", to: :tov
+      map "pf", to: :pf
+      map "PF", to: :pf
+      map "pts", to: :pts
+      map "PTS", to: :pts
+      map "plus_minus", to: :plus_minus
+      map "PLUS_MINUS", to: :plus_minus
+    end
+    # rubocop:enable Metrics/BlockLength
+  end
+end

data/lib/nba/game_rotation.rb

@@ -0,0 +1,152 @@
+require "json"
+require_relative "client"
+require_relative "collection"
+
+require_relative "rotation_entry"
+
+module NBA
+  # Provides methods to retrieve game rotation data
+  module GameRotation
+    # Result set name for home team rotation
+    # @return [String] the result set name
+    HOME_TEAM = "HomeTeam".freeze
+
+    # Result set name for away team rotation
+    # @return [String] the result set name
+    AWAY_TEAM = "AwayTeam".freeze
+
+    # Retrieves rotation data for the home team in a game
+    #
+    # @api public
+    # @example
+    #   rotations = NBA::GameRotation.home_team(game: "0022400001")
+    #   rotations.each { |r| puts "#{r.player_name}: #{r.player_pts} pts" }
+    # @param game [String, Game] the game ID or Game object
+    # @param client [Client] the API client to use
+    # @return [Collection] a collection of rotation entries
+    def self.home_team(game:, client: CLIENT)
+      game_id = extract_game_id(game)
+      path = build_path(game_id)
+      response = client.get(path)
+      parse_response(response, HOME_TEAM, game_id)
+    end
+
+    # Retrieves rotation data for the away team in a game
+    #
+    # @api public
+    # @example
+    #   rotations = NBA::GameRotation.away_team(game: "0022400001")
+    #   rotations.each { |r| puts "#{r.player_name}: #{r.pt_diff} +/-" }
+    # @param game [String, Game] the game ID or Game object
+    # @param client [Client] the API client to use
+    # @return [Collection] a collection of rotation entries
+    def self.away_team(game:, client: CLIENT)
+      game_id = extract_game_id(game)
+      path = build_path(game_id)
+      response = client.get(path)
+      parse_response(response, AWAY_TEAM, game_id)
+    end
+
+    # Retrieves all rotation data for a game
+    #
+    # @api public
+    # @example
+    #   rotations = NBA::GameRotation.all(game: "0022400001")
+    #   rotations.each { |r| puts "#{r.team_name}: #{r.player_name}" }
+    # @param game [String, Game] the game ID or Game object
+    # @param client [Client] the API client to use
+    # @return [Collection] a collection of all rotation entries
+    def self.all(game:, client: CLIENT)
+      home = home_team(game: game, client: client).to_a
+      away = away_team(game: game, client: client).to_a
+      Collection.new(home + away)
+    end
+
+    # Builds the API request path
+    # @api private
+    # @return [String] the request path
+    def self.build_path(game_id)
+      "gamerotation?GameID=#{game_id}&LeagueID=00"
+    end
+    private_class_method :build_path
+
+    # Parses the API response into rotation entry objects
+    # @api private
+    # @return [Collection] collection of rotation entries
+    def self.parse_response(response, result_set_name, game_id)
+      return Collection.new unless response
+
+      data = JSON.parse(response)
+      result_set = find_result_set(data, result_set_name)
+      return Collection.new unless result_set
+
+      headers = result_set["headers"]
+      rows = result_set["rowSet"]
+      return Collection.new unless headers && rows
+
+      entries = rows.map { |row| build_rotation_entry(headers, row, game_id) }
+      Collection.new(entries)
+    end
+    private_class_method :parse_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 RotationEntry object from raw data
+    # @api private
+    # @return [RotationEntry] the rotation entry object
+    def self.build_rotation_entry(headers, row, game_id)
+      data = headers.zip(row).to_h
+      RotationEntry.new(**rotation_attributes(data, game_id))
+    end
+    private_class_method :build_rotation_entry
+
+    # Combines all rotation attributes
+    # @api private
+    # @return [Hash] the combined attributes
+    def self.rotation_attributes(data, game_id)
+      identity_attributes(data, game_id).merge(stint_attributes(data))
+    end
+    private_class_method :rotation_attributes
+
+    # Extracts identity attributes from data
+    # @api private
+    # @return [Hash] identity attributes
+    def self.identity_attributes(data, game_id)
+      {game_id: game_id, team_id: data.fetch("TEAM_ID"), team_city: data.fetch("TEAM_CITY"),
+       team_name: data.fetch("TEAM_NAME"), player_id: data.fetch("PERSON_ID"),
+       player_first: data.fetch("PLAYER_FIRST"), player_last: data.fetch("PLAYER_LAST")}
+    end
+    private_class_method :identity_attributes
+
+    # Extracts stint attributes from data
+    # @api private
+    # @return [Hash] stint attributes
+    def self.stint_attributes(data)
+      {in_time_real: data.fetch("IN_TIME_REAL"), out_time_real: data.fetch("OUT_TIME_REAL"),
+       player_pts: data.fetch("PLAYER_PTS"), pt_diff: data.fetch("PT_DIFF"), usg_pct: data.fetch("USG_PCT")}
+    end
+    private_class_method :stint_attributes
+
+    # Extracts game ID from a Game object or returns the string
+    #
+    # @api private
+    # @param game [Game, String] the game or game ID
+    # @return [String] the game ID
+    def self.extract_game_id(game)
+      case game
+      when Game then game.id
+      else game
+      end
+    end
+    private_class_method :extract_game_id
+  end
+end

data/lib/nba/game_streak.rb

@@ -0,0 +1,102 @@
+require "shale"
+
+module NBA
+  # Represents a player's game streak statistics
+  #
+  # @api public
+  class GameStreak < Shale::Mapper
+    include Equalizer.new(:player_id, :start_date, :end_date)
+
+    # @!attribute [rw] player_name
+    #   Returns the player's name
+    #   @api public
+    #   @example
+    #     streak.player_name #=> "Curry, Stephen"
+    #   @return [String, nil] the player's name in "Last, First" format
+    attribute :player_name, Shale::Type::String
+
+    # @!attribute [rw] player_id
+    #   Returns the player's unique identifier
+    #   @api public
+    #   @example
+    #     streak.player_id #=> 201939
+    #   @return [Integer, nil] the player ID
+    attribute :player_id, Shale::Type::Integer
+
+    # @!attribute [rw] game_streak
+    #   Returns the number of consecutive games in the streak
+    #   @api public
+    #   @example
+    #     streak.game_streak #=> 10
+    #   @return [Integer, nil] the streak length
+    attribute :game_streak, Shale::Type::Integer
+
+    # @!attribute [rw] start_date
+    #   Returns the start date of the streak
+    #   @api public
+    #   @example
+    #     streak.start_date #=> "2024-10-22"
+    #   @return [String, nil] the start date
+    attribute :start_date, Shale::Type::String
+
+    # @!attribute [rw] end_date
+    #   Returns the end date of the streak
+    #   @api public
+    #   @example
+    #     streak.end_date #=> "2024-11-15"
+    #   @return [String, nil] the end date
+    attribute :end_date, Shale::Type::String
+
+    # @!attribute [rw] active_streak
+    #   Returns whether the streak is active
+    #   @api public
+    #   @example
+    #     streak.active_streak #=> 1
+    #   @return [Integer, nil] 1 for active, 0 for inactive
+    attribute :active_streak, Shale::Type::Integer
+
+    # @!attribute [rw] num_seasons
+    #   Returns the number of seasons the streak spans
+    #   @api public
+    #   @example
+    #     streak.num_seasons #=> 1
+    #   @return [Integer, nil] the number of seasons
+    attribute :num_seasons, Shale::Type::Integer
+
+    # @!attribute [rw] last_season
+    #   Returns the last season of the streak
+    #   @api public
+    #   @example
+    #     streak.last_season #=> "2024-25"
+    #   @return [String, nil] the last season
+    attribute :last_season, Shale::Type::String
+
+    # @!attribute [rw] first_season
+    #   Returns the first season of the streak
+    #   @api public
+    #   @example
+    #     streak.first_season #=> "2024-25"
+    #   @return [String, nil] the first season
+    attribute :first_season, Shale::Type::String
+
+    # Returns whether the streak is currently active
+    #
+    # @api public
+    # @example
+    #   streak.active? #=> true
+    # @return [Boolean] true if the streak is active
+    def active?
+      active_streak.eql?(1)
+    end
+
+    # Returns the player associated with this streak
+    #
+    # @api public
+    # @example
+    #   streak.player #=> #<NBA::Player>
+    # @return [Player, nil] the player object for this streak
+    def player
+      Players.find(player_id)
+    end
+  end
+end

data/lib/nba/games.rb

@@ -0,0 +1,46 @@
+require_relative "client"
+require_relative "game"
+require_relative "response_parser"
+require_relative "teams"
+
+module NBA
+  # Provides methods to retrieve NBA games
+  module Games
+    # Game status lookup table
+    GAME_STATUSES = {1 => "Scheduled", 2 => "In Progress", 3 => "Final"}.freeze
+    private_constant :GAME_STATUSES
+
+    # Finds a game by ID
+    #
+    # @api public
+    # @example
+    #   game = NBA::Games.find("0022400001")
+    #   puts "#{game.away_team.name} @ #{game.home_team.name}: #{game.away_score}-#{game.home_score}"
+    # @param game_id [String] the game ID
+    # @param client [Client] the API client to use
+    # @return [Game, nil] the game or nil if not found
+    def self.find(game_id, client: CLIENT)
+      return unless game_id
+
+      path = "boxscoresummaryv2?GameID=#{game_id}"
+      ResponseParser.parse_single(client.get(path), result_set: "GameSummary") { |data| build_game(data) }
+    end
+
+    # Builds a game from summary data
+    #
+    # @api private
+    # @param data [Hash] the game summary data
+    # @return [Game] the game object
+    def self.build_game(data)
+      Game.new(
+        id: data["GAME_ID"],
+        date: data["GAME_DATE_EST"],
+        status: GAME_STATUSES.fetch(data["GAME_STATUS_ID"], "Unknown"),
+        home_team: Teams.find(data["HOME_TEAM_ID"]),
+        away_team: Teams.find(data["VISITOR_TEAM_ID"]),
+        arena: data["ARENA"]
+      )
+    end
+    private_class_method :build_game
+  end
+end