nba 0.1.1 → 0.2.0

data/lib/nba/position.rb

@@ -0,0 +1,48 @@
+require "equalizer"
+require "shale"
+
+module NBA
+  # Represents a player position
+  class Position < Shale::Mapper
+    include Equalizer.new(:code)
+
+    # @!attribute [rw] code
+    #   Returns the position code
+    #   @api public
+    #   @example
+    #     position.code #=> "PG"
+    #   @return [String] the position code
+    attribute :code, Shale::Type::String
+
+    # @!attribute [rw] name
+    #   Returns the position name
+    #   @api public
+    #   @example
+    #     position.name #=> "Point Guard"
+    #   @return [String] the position name
+    attribute :name, Shale::Type::String
+
+    # @!attribute [rw] type
+    #   Returns the position type
+    #   @api public
+    #   @example
+    #     position.type #=> "Guard"
+    #   @return [String] the position type
+    attribute :type, Shale::Type::String
+
+    # @!attribute [rw] abbreviation
+    #   Returns the position abbreviation
+    #   @api public
+    #   @example
+    #     position.abbreviation #=> "G"
+    #   @return [String] the position abbreviation
+    attribute :abbreviation, Shale::Type::String
+
+    json do
+      map "code", to: :code
+      map "name", to: :name
+      map "type", to: :type
+      map "abbreviation", to: :abbreviation
+    end
+  end
+end

data/lib/nba/rebound_stat.rb

@@ -0,0 +1,189 @@
+require "equalizer"
+require "shale"
+
+module NBA
+  # Represents player tracking rebound statistics
+  #
+  # @api public
+  class ReboundStat < Shale::Mapper
+    include Equalizer.new(:player_id, :g, :reb)
+
+    # @!attribute [rw] player_id
+    #   Returns the player ID
+    #   @api public
+    #   @example
+    #     stat.player_id #=> 201939
+    #   @return [Integer, nil] the player's 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, nil] the player's name in "Last, First" format
+    attribute :player_name_last_first, Shale::Type::String
+
+    # @!attribute [rw] sort_order
+    #   Returns the sort order for the row
+    #   @api public
+    #   @example
+    #     stat.sort_order #=> 1
+    #   @return [Integer, nil] the sort order for the row
+    attribute :sort_order, Shale::Type::Integer
+
+    # @!attribute [rw] g
+    #   Returns the number of games
+    #   @api public
+    #   @example
+    #     stat.g #=> 74
+    #   @return [Integer, nil] the number of games
+    attribute :g, Shale::Type::Integer
+
+    # @!attribute [rw] reb_num_contesting_range
+    #   Returns the number of contesting players range
+    #   @api public
+    #   @example
+    #     stat.reb_num_contesting_range #=> "0 Contests"
+    #   @return [String, nil] the number of contesting players range
+    attribute :reb_num_contesting_range, Shale::Type::String
+
+    # @!attribute [rw] overall
+    #   Returns the overall category
+    #   @api public
+    #   @example
+    #     stat.overall #=> "Overall"
+    #   @return [String, nil] the overall category
+    attribute :overall, Shale::Type::String
+
+    # @!attribute [rw] reb_dist_range
+    #   Returns the rebound distance range
+    #   @api public
+    #   @example
+    #     stat.reb_dist_range #=> "0-6 Feet"
+    #   @return [String, nil] the rebound distance range
+    attribute :reb_dist_range, Shale::Type::String
+
+    # @!attribute [rw] shot_dist_range
+    #   Returns the shot distance range
+    #   @api public
+    #   @example
+    #     stat.shot_dist_range #=> "0-6 Feet"
+    #   @return [String, nil] the shot distance range
+    attribute :shot_dist_range, Shale::Type::String
+
+    # @!attribute [rw] shot_type_range
+    #   Returns the shot type range
+    #   @api public
+    #   @example
+    #     stat.shot_type_range #=> "2PT FGs"
+    #   @return [String, nil] the shot type range
+    attribute :shot_type_range, Shale::Type::String
+
+    # @!attribute [rw] reb_frequency
+    #   Returns the rebound frequency
+    #   @api public
+    #   @example
+    #     stat.reb_frequency #=> 0.25
+    #   @return [Float, nil] the rebound frequency
+    attribute :reb_frequency, Shale::Type::Float
+
+    # @!attribute [rw] oreb
+    #   Returns offensive rebounds per game
+    #   @api public
+    #   @example
+    #     stat.oreb #=> 1.2
+    #   @return [Float, nil] offensive rebounds per game
+    attribute :oreb, Shale::Type::Float
+
+    # @!attribute [rw] dreb
+    #   Returns defensive rebounds per game
+    #   @api public
+    #   @example
+    #     stat.dreb #=> 4.5
+    #   @return [Float, nil] defensive rebounds per game
+    attribute :dreb, Shale::Type::Float
+
+    # @!attribute [rw] reb
+    #   Returns total rebounds per game
+    #   @api public
+    #   @example
+    #     stat.reb #=> 5.7
+    #   @return [Float, nil] total rebounds per game
+    attribute :reb, Shale::Type::Float
+
+    # @!attribute [rw] c_oreb
+    #   Returns contested offensive rebounds per game
+    #   @api public
+    #   @example
+    #     stat.c_oreb #=> 0.8
+    #   @return [Float, nil] contested offensive rebounds per game
+    attribute :c_oreb, Shale::Type::Float
+
+    # @!attribute [rw] c_dreb
+    #   Returns contested defensive rebounds per game
+    #   @api public
+    #   @example
+    #     stat.c_dreb #=> 2.1
+    #   @return [Float, nil] contested defensive rebounds per game
+    attribute :c_dreb, Shale::Type::Float
+
+    # @!attribute [rw] c_reb
+    #   Returns contested total rebounds per game
+    #   @api public
+    #   @example
+    #     stat.c_reb #=> 2.9
+    #   @return [Float, nil] contested total rebounds per game
+    attribute :c_reb, Shale::Type::Float
+
+    # @!attribute [rw] c_reb_pct
+    #   Returns contested rebound percentage
+    #   @api public
+    #   @example
+    #     stat.c_reb_pct #=> 0.509
+    #   @return [Float, nil] contested rebound percentage
+    attribute :c_reb_pct, Shale::Type::Float
+
+    # @!attribute [rw] uc_oreb
+    #   Returns uncontested offensive rebounds per game
+    #   @api public
+    #   @example
+    #     stat.uc_oreb #=> 0.4
+    #   @return [Float, nil] uncontested offensive rebounds per game
+    attribute :uc_oreb, Shale::Type::Float
+
+    # @!attribute [rw] uc_dreb
+    #   Returns uncontested defensive rebounds per game
+    #   @api public
+    #   @example
+    #     stat.uc_dreb #=> 2.4
+    #   @return [Float, nil] uncontested defensive rebounds per game
+    attribute :uc_dreb, Shale::Type::Float
+
+    # @!attribute [rw] uc_reb
+    #   Returns uncontested total rebounds per game
+    #   @api public
+    #   @example
+    #     stat.uc_reb #=> 2.8
+    #   @return [Float, nil] uncontested total rebounds per game
+    attribute :uc_reb, Shale::Type::Float
+
+    # @!attribute [rw] uc_reb_pct
+    #   Returns uncontested rebound percentage
+    #   @api public
+    #   @example
+    #     stat.uc_reb_pct #=> 0.491
+    #   @return [Float, nil] uncontested rebound percentage
+    attribute :uc_reb_pct, Shale::Type::Float
+
+    # Returns the player associated with this stat
+    #
+    # @api public
+    # @example
+    #   stat.player #=> #<NBA::Player ...>
+    # @return [Player, nil] the Player object
+    def player
+      Players.find(player_id)
+    end
+  end
+end

data/lib/nba/response_parser.rb

@@ -0,0 +1,116 @@
+require "json"
+require_relative "collection"
+
+module NBA
+  # Parses NBA API responses and builds collections of objects
+  #
+  # This module consolidates the common pattern of parsing JSON responses
+  # from the NBA Stats API, extracting result sets, and building objects
+  # from header/row pairs.
+  module ResponseParser
+    # Parses an API response and returns a collection of objects
+    #
+    # @api public
+    # @example
+    #   ResponseParser.parse(response, result_set: "PlayerStats") { |data| Player.new(**data) }
+    # @param response [String, nil] the JSON response body
+    # @param result_set [String, nil] the name of the result set to extract (nil for first)
+    # @yield [Hash] yields each row as a hash with header keys
+    # @return [Collection] a collection of parsed objects
+    def self.parse(response, result_set: nil, &builder)
+      return Collection.new unless response
+
+      data = parse_json(response)
+      return Collection.new unless data
+
+      result = find_result_set(data, result_set)
+      return Collection.new unless result
+
+      build_collection(result, &builder)
+    end
+
+    # Parses an API response and returns a single object
+    #
+    # @api public
+    # @example
+    #   ResponseParser.parse_single(response) { |data| Player.new(**data) }
+    # @param response [String, nil] the JSON response body
+    # @param result_set [String, nil] the name of the result set to extract
+    # @yield [Hash] yields the first row as a hash with header keys
+    # @return [Object, nil] the parsed object or nil
+    def self.parse_single(response, result_set: nil)
+      return unless response
+
+      data = parse_json(response)
+      return unless data
+
+      result = find_result_set(data, result_set)
+      return unless result
+
+      headers = result["headers"]
+      row = result.dig("rowSet", 0)
+      return unless headers && row
+
+      yield zip_to_hash(headers, row)
+    end
+
+    # Zips headers and row into a hash
+    #
+    # @api public
+    # @example
+    #   ResponseParser.zip_to_hash(["NAME", "AGE"], ["LeBron", 39])
+    #   #=> {"NAME" => "LeBron", "AGE" => 39}
+    # @param headers [Array<String>] the column headers
+    # @param row [Array] the row data
+    # @return [Hash] a hash with header keys and row values
+    def self.zip_to_hash(headers, row)
+      headers.zip(row).to_h
+    end
+
+    # Parses JSON safely, returning nil on error
+    #
+    # @api private
+    # @param response [String] the JSON string to parse
+    # @return [Hash, nil] the parsed JSON or nil on error
+    def self.parse_json(response)
+      JSON.parse(response)
+    rescue JSON::ParserError
+      nil
+    end
+    private_class_method :parse_json
+
+    # Finds a result set by name or returns the first one
+    #
+    # @api private
+    # @param data [Hash] the parsed JSON data
+    # @param name [String, nil] the result set name (nil for first)
+    # @return [Hash, nil] the result set or nil
+    def self.find_result_set(data, name)
+      result_sets = data["resultSets"]
+      return unless result_sets
+
+      if name
+        result_sets.find { |rs| rs["name"].eql?(name) }
+      else
+        result_sets.first
+      end
+    end
+    private_class_method :find_result_set
+
+    # Builds a collection from a result set
+    #
+    # @api private
+    # @param result [Hash] the result set
+    # @yield [Hash] yields each row as a hash
+    # @return [Collection] a collection of objects
+    def self.build_collection(result)
+      headers = result["headers"]
+      rows = result["rowSet"]
+      return Collection.new unless headers && rows
+
+      objects = rows.map { |row| yield zip_to_hash(headers, row) }
+      Collection.new(objects)
+    end
+    private_class_method :build_collection
+  end
+end

data/lib/nba/roster.rb

@@ -0,0 +1,74 @@
+require_relative "client"
+require_relative "response_parser"
+require_relative "player"
+require_relative "utils"
+
+module NBA
+  # Provides methods to retrieve team rosters
+  module Roster
+    # Finds the roster for a team
+    #
+    # @api public
+    # @example
+    #   roster = NBA::Roster.find(team: NBA::Team::GSW)
+    #   roster.each { |player| puts player.full_name }
+    # @param team [Integer, Team] the team ID or Team object
+    # @param season [Integer] the season year (defaults to current season)
+    # @param client [Client] the API client to use
+    # @return [Collection] a collection of players on the roster
+    def self.find(team:, season: Utils.current_season, client: CLIENT)
+      path = "commonteamroster?TeamID=#{Utils.extract_id(team)}&Season=#{Utils.format_season(season)}"
+      ResponseParser.parse(client.get(path)) { |data| build_player(data) }
+    end
+
+    # Builds a player from roster data
+    #
+    # @api private
+    # @param data [Hash] the roster row data
+    # @return [Player] the player object
+    def self.build_player(data)
+      Player.new(**player_attributes(data))
+    end
+    private_class_method :build_player
+
+    # Extracts player attributes from data
+    # @api private
+    # @return [Hash]
+    def self.player_attributes(data)
+      {id: data["PLAYER_ID"], height: data["HEIGHT"], college: data["SCHOOL"], is_active: true,
+       jersey_number: Utils.parse_integer(data["NUM"]), weight: Utils.parse_integer(data["WEIGHT"]),
+       country: extract_country(data["BIRTH_DATE"]), position: build_position(data["POSITION"]),
+       **name_attributes(data["PLAYER"])}
+    end
+    private_class_method :player_attributes
+
+    # Builds a position from abbreviation
+    # @api private
+    # @return [Position, nil]
+    def self.build_position(abbreviation)
+      return unless abbreviation
+
+      Position.new(abbreviation: abbreviation)
+    end
+    private_class_method :build_position
+
+    # Extracts name attributes from full name
+    # @api private
+    # @return [Hash]
+    def self.name_attributes(full_name)
+      parts = full_name&.split || []
+      {full_name: full_name, first_name: parts.first, last_name: parts.drop(1).join(" ")}
+    end
+    private_class_method :name_attributes
+
+    # Extracts country from birth date string
+    # @api private
+    # @return [String, nil]
+    def self.extract_country(birth_date)
+      return unless birth_date
+
+      birth_date.split(",").last&.strip
+    end
+    private_class_method :extract_country
+  end
+end

data/lib/nba/rotation_entry.rb

@@ -0,0 +1,154 @@
+module NBA
+  # Represents a player's rotation entry in a game
+  class RotationEntry < Shale::Mapper
+    include Equalizer.new(:game_id, :player_id, :in_time_real)
+
+    # @!attribute [rw] game_id
+    #   Returns the game ID
+    #   @api public
+    #   @example
+    #     entry.game_id #=> "0022400001"
+    #   @return [String] the game ID
+    attribute :game_id, Shale::Type::String
+
+    # @!attribute [rw] team_id
+    #   Returns the team ID
+    #   @api public
+    #   @example
+    #     entry.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
+    #     entry.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
+    #     entry.team_name #=> "Warriors"
+    #   @return [String] the team name
+    attribute :team_name, Shale::Type::String
+
+    # @!attribute [rw] player_id
+    #   Returns the player ID
+    #   @api public
+    #   @example
+    #     entry.player_id #=> 201939
+    #   @return [Integer] the player ID
+    attribute :player_id, Shale::Type::Integer
+
+    # @!attribute [rw] player_first
+    #   Returns the player's first name
+    #   @api public
+    #   @example
+    #     entry.player_first #=> "Stephen"
+    #   @return [String] the first name
+    attribute :player_first, Shale::Type::String
+
+    # @!attribute [rw] player_last
+    #   Returns the player's last name
+    #   @api public
+    #   @example
+    #     entry.player_last #=> "Curry"
+    #   @return [String] the last name
+    attribute :player_last, Shale::Type::String
+
+    # @!attribute [rw] in_time_real
+    #   Returns the time the player checked in (in tenths of seconds from game start)
+    #   @api public
+    #   @example
+    #     entry.in_time_real #=> 0
+    #   @return [Integer] the in time
+    attribute :in_time_real, Shale::Type::Integer
+
+    # @!attribute [rw] out_time_real
+    #   Returns the time the player checked out (in tenths of seconds from game start)
+    #   @api public
+    #   @example
+    #     entry.out_time_real #=> 4320
+    #   @return [Integer] the out time
+    attribute :out_time_real, Shale::Type::Integer
+
+    # @!attribute [rw] player_pts
+    #   Returns the points scored during this stint
+    #   @api public
+    #   @example
+    #     entry.player_pts #=> 12
+    #   @return [Integer] the points
+    attribute :player_pts, Shale::Type::Integer
+
+    # @!attribute [rw] pt_diff
+    #   Returns the point differential during this stint
+    #   @api public
+    #   @example
+    #     entry.pt_diff #=> 8
+    #   @return [Integer] the point differential
+    attribute :pt_diff, Shale::Type::Integer
+
+    # @!attribute [rw] usg_pct
+    #   Returns the usage percentage during this stint
+    #   @api public
+    #   @example
+    #     entry.usg_pct #=> 32.5
+    #   @return [Float] the usage percentage
+    attribute :usg_pct, Shale::Type::Float
+
+    # Returns the player object
+    #
+    # @api public
+    # @example
+    #   entry.player #=> #<NBA::Player>
+    # @return [Player, nil] the player object
+    def player
+      Players.find(player_id)
+    end
+
+    # Returns the team object
+    #
+    # @api public
+    # @example
+    #   entry.team #=> #<NBA::Team>
+    # @return [Team, nil] the team object
+    def team
+      Teams.find(team_id)
+    end
+
+    # Returns the game object
+    #
+    # @api public
+    # @example
+    #   entry.game #=> #<NBA::Game>
+    # @return [Game, nil] the game object
+    def game
+      Games.find(game_id)
+    end
+
+    # Returns the player's full name
+    #
+    # @api public
+    # @example
+    #   entry.player_name #=> "Stephen Curry"
+    # @return [String] the full name
+    def player_name
+      "#{player_first} #{player_last}".strip
+    end
+
+    # Returns the stint duration in tenths of seconds
+    #
+    # @api public
+    # @example
+    #   entry.duration #=> 4320
+    # @return [Integer, nil] the duration
+    def duration
+      return unless in_time_real && out_time_real
+
+      out_time_real - in_time_real
+    end
+  end
+end