nba 0.1.1 → 0.2.0

data/lib/nba/leaders.rb

@@ -0,0 +1,110 @@
+require "json"
+require_relative "client"
+require_relative "collection"
+require_relative "leader"
+require_relative "response_parser"
+require_relative "utils"
+
+module NBA
+  # Provides methods to retrieve NBA statistical leaders
+  module Leaders
+    # Points per game category
+    # @return [String] the category code
+    PTS = "PTS".freeze
+    # Rebounds per game category
+    # @return [String] the category code
+    REB = "REB".freeze
+    # Assists per game category
+    # @return [String] the category code
+    AST = "AST".freeze
+    # Steals per game category
+    # @return [String] the category code
+    STL = "STL".freeze
+    # Blocks per game category
+    # @return [String] the category code
+    BLK = "BLK".freeze
+    # Field goal percentage category
+    # @return [String] the category code
+    FG_PCT = "FG_PCT".freeze
+    # Three point percentage category
+    # @return [String] the category code
+    FG3_PCT = "FG3_PCT".freeze
+    # Free throw percentage category
+    # @return [String] the category code
+    FT_PCT = "FT_PCT".freeze
+    # Efficiency category
+    # @return [String] the category code
+    EFF = "EFF".freeze
+
+    # Categories that require Totals mode
+    PERCENTAGE_CATEGORIES = [FG_PCT, FG3_PCT, FT_PCT].freeze
+    private_constant :PERCENTAGE_CATEGORIES
+
+    # Retrieves league leaders for a statistical category
+    #
+    # @api public
+    # @example
+    #   leaders = NBA::Leaders.find(category: NBA::Leaders::PTS)
+    #   leaders.each { |leader| puts "#{leader.rank}. #{leader.player_name}: #{leader.value}" }
+    # @param category [String] the statistical category (PTS, REB, AST, etc.)
+    # @param season [Integer] the season year (defaults to current season)
+    # @param season_type [String] the season type (Regular Season, Playoffs)
+    # @param limit [Integer] the number of results to return (defaults to 10)
+    # @param client [Client] the API client to use
+    # @return [Collection] a collection of leaders
+    def self.find(category:, season: Utils.current_season, season_type: "Regular Season", limit: 10, client: CLIENT)
+      per_mode = PERCENTAGE_CATEGORIES.include?(category) ? "Totals" : "PerGame"
+      path = "leagueleaders?LeagueID=00&PerMode=#{per_mode}&Scope=S&Season=#{Utils.format_season(season)}" \
+             "&SeasonType=#{season_type}&StatCategory=#{category}"
+      parse_leaders_response(client.get(path), category, limit)
+    end
+
+    # Parses the leaders API response (uses resultSet instead of resultSets)
+    #
+    # @api private
+    # @param response [String] the JSON response body
+    # @param category [String] the category requested
+    # @param limit [Integer] the limit of results
+    # @return [Collection] a collection of leaders
+    def self.parse_leaders_response(response, category, limit)
+      headers, rows = extract_result_set(response)
+      return Collection.new unless headers && rows
+
+      leaders = rows.take(limit).map do |row|
+        build_leader(ResponseParser.zip_to_hash(headers, row), category)
+      end
+      Collection.new(leaders)
+    end
+    private_class_method :parse_leaders_response
+
+    # Extracts result set from API response
+    # @api private
+    # @return [Array, nil]
+    def self.extract_result_set(response)
+      return unless response
+
+      result_set = JSON.parse(response)["resultSet"]
+      return unless result_set
+
+      [result_set["headers"], result_set["rowSet"]]
+    end
+    private_class_method :extract_result_set
+
+    # Builds a leader from API data
+    # @api private
+    # @return [Leader]
+    def self.build_leader(data, category)
+      Leader.new(**leader_identity(data), category: category, rank: data["RANK"], value: data[category])
+    end
+    private_class_method :build_leader
+
+    # Extracts leader identity attributes from data
+    # @api private
+    # @return [Hash]
+    def self.leader_identity(data)
+      {player_id: data["PLAYER_ID"], player_name: data["PLAYER"],
+       team_id: data["TEAM_ID"], team_abbreviation: data["TEAM"]}
+    end
+    private_class_method :leader_identity
+  end
+end

data/lib/nba/leaders_tile.rb

@@ -0,0 +1,57 @@
+require "equalizer"
+require "shale"
+
+module NBA
+  # Represents a leaders tile entry
+  #
+  # @api public
+  # @example
+  #   tile.rank #=> 1
+  #   tile.team_abbreviation #=> "BOS"
+  #   tile.pts #=> 120.5
+  class LeadersTile < Shale::Mapper
+    include Equalizer.new(:rank, :team_id)
+
+    #   Returns the rank
+    #   @api public
+    #   @example
+    #     tile.rank #=> 1
+    #   @return [Integer, nil] the rank
+    attribute :rank, Shale::Type::Integer
+
+    #   Returns the team ID
+    #   @api public
+    #   @example
+    #     tile.team_id #=> 1610612738
+    #   @return [Integer, nil] the team ID
+    attribute :team_id, Shale::Type::Integer
+
+    #   Returns the team abbreviation
+    #   @api public
+    #   @example
+    #     tile.team_abbreviation #=> "BOS"
+    #   @return [String, nil] the team abbreviation
+    attribute :team_abbreviation, Shale::Type::String
+
+    #   Returns the team name
+    #   @api public
+    #   @example
+    #     tile.team_name #=> "Boston Celtics"
+    #   @return [String, nil] the team name
+    attribute :team_name, Shale::Type::String
+
+    #   Returns points
+    #   @api public
+    #   @example
+    #     tile.pts #=> 120.5
+    #   @return [Float, nil] points
+    attribute :pts, Shale::Type::Float
+
+    #   Returns season year (for all-time/low records)
+    #   @api public
+    #   @example
+    #     tile.season_year #=> "2023-24"
+    #   @return [String, nil] season year (for all-time/low records)
+    attribute :season_year, Shale::Type::String
+  end
+end

data/lib/nba/leaders_tiles.rb

@@ -0,0 +1,90 @@
+require "json"
+require_relative "client"
+require_relative "collection"
+require_relative "leaders_tile"
+require_relative "league"
+require_relative "response_parser"
+require_relative "utils"
+
+module NBA
+  # Provides methods to retrieve NBA leaders tiles statistics
+  module LeadersTiles
+    # Result set categories available in leaders tiles
+    RESULT_SETS = {
+      leaders: "LeadersTiles",
+      all_time_high: "AllTimeSeasonHigh",
+      last_season_high: "LastSeasonHigh",
+      low_season_high: "LowSeasonHigh"
+    }.freeze
+
+    # Retrieves leaders tiles for a result set category
+    #
+    # @api public
+    # @example
+    #   tiles = NBA::LeadersTiles.all(result_set: :leaders, season: 2023)
+    #   tiles.each { |t| puts "#{t.rank}. #{t.team_abbreviation}: #{t.pts}" }
+    # @param result_set [Symbol] the result set (:leaders, :all_time_high, etc.)
+    # @param season [Integer] the season year (defaults to current season)
+    # @param season_type [String] the season type (Regular Season, Playoffs, etc.)
+    # @param game_scope [String] the game scope (Season, Yesterday, etc.)
+    # @param player_or_team [String] player or team stats (Player, Team)
+    # @param player_scope [String] the player scope (All Players, Rookies)
+    # @param stat [String] the stat type (PTS, REB, AST, etc.)
+    # @param league [String, League] the league ID or League object
+    # @param client [Client] the API client to use
+    # @return [Collection] a collection of leaders tiles
+    def self.all(result_set: :leaders, season: Utils.current_season,
+      season_type: "Regular Season", game_scope: "Season", player_or_team: "Team",
+      player_scope: "All Players", stat: "PTS", league: League::NBA, client: CLIENT)
+      result_set_name = RESULT_SETS.fetch(result_set)
+      league_id = Utils.extract_league_id(league)
+      opts = {season: season, season_type: season_type, game_scope: game_scope,
+              player_or_team: player_or_team, player_scope: player_scope,
+              stat: stat, league_id: league_id}
+      response = client.get(build_path(opts))
+      parse_response(response, result_set_name)
+    end
+
+    # Builds the API request path
+    # @api private
+    # @return [String] the request path
+    def self.build_path(opts)
+      "leaderstiles?GameScope=#{opts[:game_scope]}&LeagueID=#{opts[:league_id]}" \
+        "&PlayerOrTeam=#{opts[:player_or_team]}&PlayerScope=#{opts[:player_scope]}" \
+        "&Season=#{Utils.format_season(opts[:season])}&SeasonType=#{opts[:season_type]}" \
+        "&Stat=#{opts[:stat]}"
+    end
+    private_class_method :build_path
+
+    # Parses the API response
+    # @api private
+    # @param response [String, nil] the raw API response
+    # @param result_set_name [String] the result set name
+    # @return [Collection] parsed tiles
+    def self.parse_response(response, result_set_name)
+      ResponseParser.parse(response, result_set: result_set_name) { |data| build_tile(data) }
+    end
+    private_class_method :parse_response
+
+    # Builds a LeadersTile object from raw data
+    # @api private
+    # @param data [Hash] the row data
+    # @return [LeadersTile] the tile object
+    def self.build_tile(data)
+      LeadersTile.new(**tile_attributes(data))
+    end
+    private_class_method :build_tile
+
+    # Extracts tile attributes from data
+    # @api private
+    # @param data [Hash] the row data
+    # @return [Hash] tile attributes
+    def self.tile_attributes(data)
+      {rank: data["RANK"], team_id: data["TEAM_ID"],
+       team_abbreviation: data["TEAM_ABBREVIATION"],
+       team_name: data["TEAM_NAME"], pts: data["PTS"],
+       season_year: data["SEASON_YEAR"]}
+    end
+    private_class_method :tile_attributes
+  end
+end

data/lib/nba/league.rb

@@ -0,0 +1,37 @@
+require "equalizer"
+require "shale"
+
+module NBA
+  # Represents a basketball league
+  class League < Shale::Mapper
+    include Equalizer.new(:id)
+
+    # NBA league ID
+    # @return [String] the NBA league ID
+    NBA = "00".freeze
+
+    # WNBA league ID
+    # @return [String] the WNBA league ID
+    WNBA = "10".freeze
+
+    # G League (NBA Development League) ID
+    # @return [String] the G League ID
+    G_LEAGUE = "20".freeze
+
+    # @!attribute [rw] id
+    #   Returns the unique identifier for the league
+    #   @api public
+    #   @example
+    #     league.id #=> "00"
+    #   @return [String] the unique identifier for the league
+    attribute :id, Shale::Type::String
+
+    # @!attribute [rw] name
+    #   Returns the name of the league
+    #   @api public
+    #   @example
+    #     league.name #=> "NBA"
+    #   @return [String] the name of the league
+    attribute :name, Shale::Type::String
+  end
+end

data/lib/nba/league_dash_lineup_stat.rb

@@ -0,0 +1,270 @@
+require "equalizer"
+require "shale"
+require_relative "teams"
+
+module NBA
+  # Represents a lineup's league dashboard statistics
+  #
+  # @api public
+  class LeagueDashLineupStat < Shale::Mapper
+    include Equalizer.new(:group_id, :team_id)
+
+    # @!attribute [rw] group_set
+    #   Returns the group set (e.g., "5-man lineups")
+    #   @api public
+    #   @example
+    #     stat.group_set #=> "5 Man Lineups"
+    #   @return [String, nil] the group set
+    attribute :group_set, Shale::Type::String
+
+    # @!attribute [rw] group_id
+    #   Returns the lineup group ID
+    #   @api public
+    #   @example
+    #     stat.group_id #=> "201939-203110-1628369"
+    #   @return [String, nil] the group ID
+    attribute :group_id, Shale::Type::String
+
+    # @!attribute [rw] group_name
+    #   Returns the lineup group name
+    #   @api public
+    #   @example
+    #     stat.group_name #=> "S. Curry - K. Thompson - A. Wiggins"
+    #   @return [String, nil] the group name
+    attribute :group_name, Shale::Type::String
+
+    # @!attribute [rw] team_id
+    #   Returns the team ID
+    #   @api public
+    #   @example
+    #     stat.team_id #=> 1610612744
+    #   @return [Integer, nil] 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, nil] the team abbreviation
+    attribute :team_abbreviation, Shale::Type::String
+
+    # @!attribute [rw] gp
+    #   Returns games played
+    #   @api public
+    #   @example
+    #     stat.gp #=> 45
+    #   @return [Integer, nil] games played
+    attribute :gp, Shale::Type::Integer
+
+    # @!attribute [rw] w
+    #   Returns wins
+    #   @api public
+    #   @example
+    #     stat.w #=> 30
+    #   @return [Integer, nil] wins
+    attribute :w, Shale::Type::Integer
+
+    # @!attribute [rw] l
+    #   Returns losses
+    #   @api public
+    #   @example
+    #     stat.l #=> 15
+    #   @return [Integer, nil] losses
+    attribute :l, Shale::Type::Integer
+
+    # @!attribute [rw] w_pct
+    #   Returns win percentage
+    #   @api public
+    #   @example
+    #     stat.w_pct #=> 0.667
+    #   @return [Float, nil] win percentage
+    attribute :w_pct, Shale::Type::Float
+
+    # @!attribute [rw] min
+    #   Returns minutes played
+    #   @api public
+    #   @example
+    #     stat.min #=> 245.5
+    #   @return [Float, nil] minutes played
+    attribute :min, Shale::Type::Float
+
+    # @!attribute [rw] fgm
+    #   Returns field goals made
+    #   @api public
+    #   @example
+    #     stat.fgm #=> 8.5
+    #   @return [Float, nil] field goals made
+    attribute :fgm, Shale::Type::Float
+
+    # @!attribute [rw] fga
+    #   Returns field goals attempted
+    #   @api public
+    #   @example
+    #     stat.fga #=> 17.2
+    #   @return [Float, nil] field goals attempted
+    attribute :fga, Shale::Type::Float
+
+    # @!attribute [rw] fg_pct
+    #   Returns field goal percentage
+    #   @api public
+    #   @example
+    #     stat.fg_pct #=> 0.494
+    #   @return [Float, nil] field goal percentage
+    attribute :fg_pct, Shale::Type::Float
+
+    # @!attribute [rw] fg3m
+    #   Returns three-pointers made
+    #   @api public
+    #   @example
+    #     stat.fg3m #=> 3.2
+    #   @return [Float, nil] three-pointers made
+    attribute :fg3m, Shale::Type::Float
+
+    # @!attribute [rw] fg3a
+    #   Returns three-pointers attempted
+    #   @api public
+    #   @example
+    #     stat.fg3a #=> 8.5
+    #   @return [Float, nil] three-pointers attempted
+    attribute :fg3a, Shale::Type::Float
+
+    # @!attribute [rw] fg3_pct
+    #   Returns three-point percentage
+    #   @api public
+    #   @example
+    #     stat.fg3_pct #=> 0.376
+    #   @return [Float, nil] three-point percentage
+    attribute :fg3_pct, Shale::Type::Float
+
+    # @!attribute [rw] ftm
+    #   Returns free throws made
+    #   @api public
+    #   @example
+    #     stat.ftm #=> 3.1
+    #   @return [Float, nil] free throws made
+    attribute :ftm, Shale::Type::Float
+
+    # @!attribute [rw] fta
+    #   Returns free throws attempted
+    #   @api public
+    #   @example
+    #     stat.fta #=> 3.8
+    #   @return [Float, nil] free throws attempted
+    attribute :fta, Shale::Type::Float
+
+    # @!attribute [rw] ft_pct
+    #   Returns free throw percentage
+    #   @api public
+    #   @example
+    #     stat.ft_pct #=> 0.816
+    #   @return [Float, nil] free throw percentage
+    attribute :ft_pct, Shale::Type::Float
+
+    # @!attribute [rw] oreb
+    #   Returns offensive rebounds
+    #   @api public
+    #   @example
+    #     stat.oreb #=> 1.8
+    #   @return [Float, nil] offensive rebounds
+    attribute :oreb, Shale::Type::Float
+
+    # @!attribute [rw] dreb
+    #   Returns defensive rebounds
+    #   @api public
+    #   @example
+    #     stat.dreb #=> 6.2
+    #   @return [Float, nil] defensive rebounds
+    attribute :dreb, Shale::Type::Float
+
+    # @!attribute [rw] reb
+    #   Returns total rebounds
+    #   @api public
+    #   @example
+    #     stat.reb #=> 8.0
+    #   @return [Float, nil] total rebounds
+    attribute :reb, Shale::Type::Float
+
+    # @!attribute [rw] ast
+    #   Returns assists
+    #   @api public
+    #   @example
+    #     stat.ast #=> 5.5
+    #   @return [Float, nil] assists
+    attribute :ast, Shale::Type::Float
+
+    # @!attribute [rw] tov
+    #   Returns turnovers
+    #   @api public
+    #   @example
+    #     stat.tov #=> 2.1
+    #   @return [Float, nil] turnovers
+    attribute :tov, Shale::Type::Float
+
+    # @!attribute [rw] stl
+    #   Returns steals
+    #   @api public
+    #   @example
+    #     stat.stl #=> 1.5
+    #   @return [Float, nil] steals
+    attribute :stl, Shale::Type::Float
+
+    # @!attribute [rw] blk
+    #   Returns blocks
+    #   @api public
+    #   @example
+    #     stat.blk #=> 0.8
+    #   @return [Float, nil] blocks
+    attribute :blk, Shale::Type::Float
+
+    # @!attribute [rw] blka
+    #   Returns blocked attempts
+    #   @api public
+    #   @example
+    #     stat.blka #=> 0.5
+    #   @return [Float, nil] blocked attempts
+    attribute :blka, Shale::Type::Float
+
+    # @!attribute [rw] pf
+    #   Returns personal fouls
+    #   @api public
+    #   @example
+    #     stat.pf #=> 2.3
+    #   @return [Float, nil] personal fouls
+    attribute :pf, Shale::Type::Float
+
+    # @!attribute [rw] pfd
+    #   Returns personal fouls drawn
+    #   @api public
+    #   @example
+    #     stat.pfd #=> 3.1
+    #   @return [Float, nil] personal fouls drawn
+    attribute :pfd, Shale::Type::Float
+
+    # @!attribute [rw] pts
+    #   Returns points
+    #   @api public
+    #   @example
+    #     stat.pts #=> 23.3
+    #   @return [Float, nil] points
+    attribute :pts, 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
+  end
+end