nba 0.1.1 → 0.2.0

data/lib/nba/team_game_log_entry.rb

@@ -0,0 +1,246 @@
+module NBA
+  # Represents a single team game log entry
+  class TeamGameLogEntry < Shale::Mapper
+    include Equalizer.new(:game_id, :team_id)
+
+    # @!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] 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 result
+    #   @api public
+    #   @example
+    #     log.wl #=> "W"
+    #   @return [String] the win/loss indicator
+    attribute :wl, Shale::Type::String
+
+    # @!attribute [rw] min
+    #   Returns the minutes played
+    #   @api public
+    #   @example
+    #     log.min #=> 240
+    #   @return [Integer] the minutes played
+    attribute :min, Shale::Type::Integer
+
+    # @!attribute [rw] fgm
+    #   Returns field goals made
+    #   @api public
+    #   @example
+    #     log.fgm #=> 42
+    #   @return [Integer] field goals made
+    attribute :fgm, Shale::Type::Integer
+
+    # @!attribute [rw] fga
+    #   Returns field goals attempted
+    #   @api public
+    #   @example
+    #     log.fga #=> 88
+    #   @return [Integer] field goals attempted
+    attribute :fga, Shale::Type::Integer
+
+    # @!attribute [rw] fg_pct
+    #   Returns field goal percentage
+    #   @api public
+    #   @example
+    #     log.fg_pct #=> 0.477
+    #   @return [Float] field goal percentage
+    attribute :fg_pct, Shale::Type::Float
+
+    # @!attribute [rw] fg3m
+    #   Returns three-pointers made
+    #   @api public
+    #   @example
+    #     log.fg3m #=> 15
+    #   @return [Integer] three-pointers made
+    attribute :fg3m, Shale::Type::Integer
+
+    # @!attribute [rw] fg3a
+    #   Returns three-pointers attempted
+    #   @api public
+    #   @example
+    #     log.fg3a #=> 40
+    #   @return [Integer] three-pointers attempted
+    attribute :fg3a, Shale::Type::Integer
+
+    # @!attribute [rw] fg3_pct
+    #   Returns three-point percentage
+    #   @api public
+    #   @example
+    #     log.fg3_pct #=> 0.375
+    #   @return [Float] three-point percentage
+    attribute :fg3_pct, Shale::Type::Float
+
+    # @!attribute [rw] ftm
+    #   Returns free throws made
+    #   @api public
+    #   @example
+    #     log.ftm #=> 20
+    #   @return [Integer] free throws made
+    attribute :ftm, Shale::Type::Integer
+
+    # @!attribute [rw] fta
+    #   Returns free throws attempted
+    #   @api public
+    #   @example
+    #     log.fta #=> 25
+    #   @return [Integer] free throws attempted
+    attribute :fta, Shale::Type::Integer
+
+    # @!attribute [rw] ft_pct
+    #   Returns free throw percentage
+    #   @api public
+    #   @example
+    #     log.ft_pct #=> 0.800
+    #   @return [Float] free throw percentage
+    attribute :ft_pct, Shale::Type::Float
+
+    # @!attribute [rw] oreb
+    #   Returns offensive rebounds
+    #   @api public
+    #   @example
+    #     log.oreb #=> 10
+    #   @return [Integer] offensive rebounds
+    attribute :oreb, Shale::Type::Integer
+
+    # @!attribute [rw] dreb
+    #   Returns defensive rebounds
+    #   @api public
+    #   @example
+    #     log.dreb #=> 35
+    #   @return [Integer] defensive rebounds
+    attribute :dreb, Shale::Type::Integer
+
+    # @!attribute [rw] reb
+    #   Returns total rebounds
+    #   @api public
+    #   @example
+    #     log.reb #=> 45
+    #   @return [Integer] total rebounds
+    attribute :reb, Shale::Type::Integer
+
+    # @!attribute [rw] ast
+    #   Returns assists
+    #   @api public
+    #   @example
+    #     log.ast #=> 28
+    #   @return [Integer] assists
+    attribute :ast, Shale::Type::Integer
+
+    # @!attribute [rw] stl
+    #   Returns steals
+    #   @api public
+    #   @example
+    #     log.stl #=> 8
+    #   @return [Integer] steals
+    attribute :stl, Shale::Type::Integer
+
+    # @!attribute [rw] blk
+    #   Returns blocks
+    #   @api public
+    #   @example
+    #     log.blk #=> 5
+    #   @return [Integer] blocks
+    attribute :blk, Shale::Type::Integer
+
+    # @!attribute [rw] tov
+    #   Returns turnovers
+    #   @api public
+    #   @example
+    #     log.tov #=> 12
+    #   @return [Integer] turnovers
+    attribute :tov, Shale::Type::Integer
+
+    # @!attribute [rw] pf
+    #   Returns personal fouls
+    #   @api public
+    #   @example
+    #     log.pf #=> 18
+    #   @return [Integer] personal fouls
+    attribute :pf, Shale::Type::Integer
+
+    # @!attribute [rw] pts
+    #   Returns points
+    #   @api public
+    #   @example
+    #     log.pts #=> 119
+    #   @return [Integer] points
+    attribute :pts, Shale::Type::Integer
+
+    # @!attribute [rw] plus_minus
+    #   Returns plus/minus
+    #   @api public
+    #   @example
+    #     log.plus_minus #=> 12
+    #   @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] whether the game was a win
+    def win?
+      wl.eql?("W")
+    end
+
+    # Returns whether the game was a loss
+    #
+    # @api public
+    # @example
+    #   log.loss? #=> false
+    # @return [Boolean] whether the game was a loss
+    def loss?
+      wl.eql?("L")
+    end
+
+    # Returns the team object for this game log
+    #
+    # @api public
+    # @example
+    #   log.team #=> #<NBA::Team>
+    # @return [Team, nil] the team object
+    def team
+      Teams.find(team_id)
+    end
+
+    # 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)
+    end
+  end
+end

data/lib/nba/team_game_log_stat.rb

@@ -0,0 +1,275 @@
+require "equalizer"
+require "shale"
+
+module NBA
+  # Represents a single team game log entry from the batch endpoint
+  #
+  # @api public
+  class TeamGameLogStat < Shale::Mapper
+    include Equalizer.new(:game_id, :team_id)
+
+    # @!attribute [rw] season_year
+    #   Returns the season year
+    #   @api public
+    #   @example
+    #     log.season_year #=> "2024-25"
+    #   @return [String] the season year
+    attribute :season_year, 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 #=> "2024-10-22T00:00:00"
+    #   @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 #=> 240
+    #   @return [Integer] the minutes played
+    attribute :min, Shale::Type::Integer
+
+    # @!attribute [rw] fgm
+    #   Returns the field goals made
+    #   @api public
+    #   @example
+    #     log.fgm #=> 42
+    #   @return [Integer] field goals made
+    attribute :fgm, Shale::Type::Integer
+
+    # @!attribute [rw] fga
+    #   Returns the field goals attempted
+    #   @api public
+    #   @example
+    #     log.fga #=> 88
+    #   @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.477
+    #   @return [Float] field goal percentage
+    attribute :fg_pct, Shale::Type::Float
+
+    # @!attribute [rw] fg3m
+    #   Returns the three-pointers made
+    #   @api public
+    #   @example
+    #     log.fg3m #=> 15
+    #   @return [Integer] three-pointers made
+    attribute :fg3m, Shale::Type::Integer
+
+    # @!attribute [rw] fg3a
+    #   Returns the three-pointers attempted
+    #   @api public
+    #   @example
+    #     log.fg3a #=> 38
+    #   @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.395
+    #   @return [Float] three-point percentage
+    attribute :fg3_pct, Shale::Type::Float
+
+    # @!attribute [rw] ftm
+    #   Returns the free throws made
+    #   @api public
+    #   @example
+    #     log.ftm #=> 19
+    #   @return [Integer] free throws made
+    attribute :ftm, Shale::Type::Integer
+
+    # @!attribute [rw] fta
+    #   Returns the free throws attempted
+    #   @api public
+    #   @example
+    #     log.fta #=> 22
+    #   @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.864
+    #   @return [Float] free throw percentage
+    attribute :ft_pct, Shale::Type::Float
+
+    # @!attribute [rw] oreb
+    #   Returns the offensive rebounds
+    #   @api public
+    #   @example
+    #     log.oreb #=> 10
+    #   @return [Integer] offensive rebounds
+    attribute :oreb, Shale::Type::Integer
+
+    # @!attribute [rw] dreb
+    #   Returns the defensive rebounds
+    #   @api public
+    #   @example
+    #     log.dreb #=> 35
+    #   @return [Integer] defensive rebounds
+    attribute :dreb, Shale::Type::Integer
+
+    # @!attribute [rw] reb
+    #   Returns the total rebounds
+    #   @api public
+    #   @example
+    #     log.reb #=> 45
+    #   @return [Integer] total rebounds
+    attribute :reb, Shale::Type::Integer
+
+    # @!attribute [rw] ast
+    #   Returns the assists
+    #   @api public
+    #   @example
+    #     log.ast #=> 28
+    #   @return [Integer] assists
+    attribute :ast, Shale::Type::Integer
+
+    # @!attribute [rw] stl
+    #   Returns the steals
+    #   @api public
+    #   @example
+    #     log.stl #=> 9
+    #   @return [Integer] steals
+    attribute :stl, Shale::Type::Integer
+
+    # @!attribute [rw] blk
+    #   Returns the blocks
+    #   @api public
+    #   @example
+    #     log.blk #=> 6
+    #   @return [Integer] blocks
+    attribute :blk, Shale::Type::Integer
+
+    # @!attribute [rw] tov
+    #   Returns the turnovers
+    #   @api public
+    #   @example
+    #     log.tov #=> 14
+    #   @return [Integer] turnovers
+    attribute :tov, Shale::Type::Integer
+
+    # @!attribute [rw] pf
+    #   Returns the personal fouls
+    #   @api public
+    #   @example
+    #     log.pf #=> 20
+    #   @return [Integer] personal fouls
+    attribute :pf, Shale::Type::Integer
+
+    # @!attribute [rw] pts
+    #   Returns the points scored
+    #   @api public
+    #   @example
+    #     log.pts #=> 118
+    #   @return [Integer] points
+    attribute :pts, Shale::Type::Integer
+
+    # @!attribute [rw] plus_minus
+    #   Returns the plus/minus
+    #   @api public
+    #   @example
+    #     log.plus_minus #=> 9
+    #   @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")
+    end
+
+    # 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")
+    end
+
+    # 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)
+    end
+
+    # Returns the team object for this log entry
+    #
+    # @api public
+    # @example
+    #   log.team #=> #<NBA::Team>
+    # @return [Team, nil] the team object
+    def team
+      Teams.find(team_id)
+    end
+  end
+end

data/lib/nba/team_game_logs.rb

@@ -0,0 +1,163 @@
+require "json"
+require_relative "client"
+require_relative "collection"
+require_relative "team_game_log_stat"
+require_relative "utils"
+
+module NBA
+  # Provides methods to retrieve team game logs in batch
+  #
+  # @api public
+  module TeamGameLogs
+    # Regular season type
+    # @return [String] the season type
+    REGULAR_SEASON = "Regular Season".freeze
+
+    # Playoffs season type
+    # @return [String] the season type
+    PLAYOFFS = "Playoffs".freeze
+
+    # Per game mode
+    # @return [String] the per mode
+    PER_GAME = "PerGame".freeze
+
+    # Totals mode
+    # @return [String] the per mode
+    TOTALS = "Totals".freeze
+
+    # Result set name
+    # @return [String] the result set name
+    RESULT_SET_NAME = "TeamGameLogs".freeze
+
+    # Retrieves game logs for all teams matching the criteria
+    #
+    # @api public
+    # @example
+    #   logs = NBA::TeamGameLogs.all(season: 2024)
+    #   logs.each { |log| puts "#{log.game_date}: #{log.team_name} - #{log.pts} pts" }
+    # @param season [Integer] the season year (defaults to current season)
+    # @param season_type [String] the season type (Regular Season, Playoffs)
+    # @param team [Integer, Team, nil] filter by team ID or Team object
+    # @param per_mode [String] the per mode (PerGame, Totals)
+    # @param client [Client] the API client to use
+    # @return [Collection] a collection of team game logs
+    def self.all(season: Utils.current_season, season_type: REGULAR_SEASON, team: nil,
+      per_mode: PER_GAME, client: CLIENT)
+      path = build_path(season, season_type, team, per_mode)
+      response = client.get(path)
+      parse_response(response)
+    end
+
+    # Builds the API path
+    #
+    # @api private
+    # @return [String] the API path
+    def self.build_path(season, season_type, team, per_mode)
+      path = "teamgamelogs?LeagueID=00&Season=#{Utils.format_season(season)}" \
+             "&SeasonType=#{season_type}&PerModeSimple=#{per_mode}"
+      path += "&TeamID=#{Utils.extract_id(team)}" if team
+      path
+    end
+    private_class_method :build_path
+
+    # Parses the API response
+    #
+    # @api private
+    # @param response [String] the JSON response body
+    # @return [Collection] a collection of team game logs
+    def self.parse_response(response)
+      return Collection.new unless response
+
+      data = JSON.parse(response)
+      result_set = find_result_set(data)
+      return Collection.new unless result_set
+
+      headers = result_set["headers"]
+      rows = result_set["rowSet"]
+      return Collection.new unless headers && rows
+
+      logs = rows.map { |row| build_game_log(headers, row) }
+      Collection.new(logs)
+    end
+    private_class_method :parse_response
+
+    # Finds the result set
+    #
+    # @api private
+    # @param data [Hash] the parsed JSON data
+    # @return [Hash, nil] the result set
+    def self.find_result_set(data)
+      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 game log from API data
+    #
+    # @api private
+    # @param headers [Array<String>] the column headers
+    # @param row [Array] the row data
+    # @return [TeamGameLogStat]
+    def self.build_game_log(headers, row)
+      data = headers.zip(row).to_h
+      TeamGameLogStat.new(**game_log_attributes(data))
+    end
+    private_class_method :build_game_log
+
+    # Combines all game log attributes
+    #
+    # @api private
+    # @param data [Hash] the raw data
+    # @return [Hash] combined attributes
+    def self.game_log_attributes(data)
+      game_info(data).merge(team_info(data), shooting_stats(data), counting_stats(data))
+    end
+    private_class_method :game_log_attributes
+
+    # Extracts game information from data
+    #
+    # @api private
+    # @return [Hash]
+    def self.game_info(data)
+      {season_year: data["SEASON_YEAR"], game_id: data["GAME_ID"],
+       game_date: data["GAME_DATE"], matchup: data["MATCHUP"],
+       wl: data["WL"], min: data["MIN"]}
+    end
+    private_class_method :game_info
+
+    # Extracts team information from data
+    #
+    # @api private
+    # @return [Hash]
+    def self.team_info(data)
+      {team_id: data["TEAM_ID"], team_abbreviation: data["TEAM_ABBREVIATION"],
+       team_name: data["TEAM_NAME"]}
+    end
+    private_class_method :team_info
+
+    # Extracts shooting statistics from data
+    #
+    # @api private
+    # @return [Hash]
+    def self.shooting_stats(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
+    private_class_method :shooting_stats
+
+    # Extracts counting statistics from data
+    #
+    # @api private
+    # @return [Hash]
+    def self.counting_stats(data)
+      {oreb: data["OREB"], dreb: data["DREB"], reb: data["REB"],
+       ast: data["AST"], stl: data["STL"], blk: data["BLK"],
+       tov: data["TOV"], pf: data["PF"], pts: data["PTS"],
+       plus_minus: data["PLUS_MINUS"]}
+    end
+    private_class_method :counting_stats
+  end
+end