nba 0.1.1 → 0.2.0

data/lib/nba/college_player_stat.rb

@@ -0,0 +1,200 @@
+module NBA
+  # Represents a player's career stats from a specific college
+  class CollegePlayerStat < Shale::Mapper
+    include Equalizer.new(:player_id)
+
+    # @!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
+    #   Returns the player's name
+    #   @api public
+    #   @example
+    #     stat.player_name #=> "Stephen Curry"
+    #   @return [String] the player name
+    attribute :player_name, Shale::Type::String
+
+    # @!attribute [rw] college
+    #   Returns the college name
+    #   @api public
+    #   @example
+    #     stat.college #=> "Davidson"
+    #   @return [String] the college name
+    attribute :college, Shale::Type::String
+
+    # @!attribute [rw] gp
+    #   Returns games played
+    #   @api public
+    #   @example
+    #     stat.gp #=> 966
+    #   @return [Integer] games played
+    attribute :gp, Shale::Type::Integer
+
+    # @!attribute [rw] min
+    #   Returns total minutes played
+    #   @api public
+    #   @example
+    #     stat.min #=> 31000.0
+    #   @return [Float] minutes
+    attribute :min, Shale::Type::Float
+
+    # @!attribute [rw] fgm
+    #   Returns field goals made
+    #   @api public
+    #   @example
+    #     stat.fgm #=> 8000.0
+    #   @return [Float] field goals made
+    attribute :fgm, Shale::Type::Float
+
+    # @!attribute [rw] fga
+    #   Returns field goals attempted
+    #   @api public
+    #   @example
+    #     stat.fga #=> 16000.0
+    #   @return [Float] field goals attempted
+    attribute :fga, Shale::Type::Float
+
+    # @!attribute [rw] fg_pct
+    #   Returns field goal percentage
+    #   @api public
+    #   @example
+    #     stat.fg_pct #=> 0.475
+    #   @return [Float] field goal percentage
+    attribute :fg_pct, Shale::Type::Float
+
+    # @!attribute [rw] fg3m
+    #   Returns three-pointers made
+    #   @api public
+    #   @example
+    #     stat.fg3m #=> 3500.0
+    #   @return [Float] three-pointers made
+    attribute :fg3m, Shale::Type::Float
+
+    # @!attribute [rw] fg3a
+    #   Returns three-pointers attempted
+    #   @api public
+    #   @example
+    #     stat.fg3a #=> 8500.0
+    #   @return [Float] three-pointers attempted
+    attribute :fg3a, Shale::Type::Float
+
+    # @!attribute [rw] fg3_pct
+    #   Returns three-point percentage
+    #   @api public
+    #   @example
+    #     stat.fg3_pct #=> 0.428
+    #   @return [Float] three-point percentage
+    attribute :fg3_pct, Shale::Type::Float
+
+    # @!attribute [rw] ftm
+    #   Returns free throws made
+    #   @api public
+    #   @example
+    #     stat.ftm #=> 4500.0
+    #   @return [Float] free throws made
+    attribute :ftm, Shale::Type::Float
+
+    # @!attribute [rw] fta
+    #   Returns free throws attempted
+    #   @api public
+    #   @example
+    #     stat.fta #=> 4900.0
+    #   @return [Float] free throws attempted
+    attribute :fta, Shale::Type::Float
+
+    # @!attribute [rw] ft_pct
+    #   Returns free throw percentage
+    #   @api public
+    #   @example
+    #     stat.ft_pct #=> 0.918
+    #   @return [Float] free throw percentage
+    attribute :ft_pct, Shale::Type::Float
+
+    # @!attribute [rw] oreb
+    #   Returns offensive rebounds
+    #   @api public
+    #   @example
+    #     stat.oreb #=> 700.0
+    #   @return [Float] offensive rebounds
+    attribute :oreb, Shale::Type::Float
+
+    # @!attribute [rw] dreb
+    #   Returns defensive rebounds
+    #   @api public
+    #   @example
+    #     stat.dreb #=> 4200.0
+    #   @return [Float] defensive rebounds
+    attribute :dreb, Shale::Type::Float
+
+    # @!attribute [rw] reb
+    #   Returns total rebounds
+    #   @api public
+    #   @example
+    #     stat.reb #=> 4900.0
+    #   @return [Float] total rebounds
+    attribute :reb, Shale::Type::Float
+
+    # @!attribute [rw] ast
+    #   Returns assists
+    #   @api public
+    #   @example
+    #     stat.ast #=> 5800.0
+    #   @return [Float] assists
+    attribute :ast, Shale::Type::Float
+
+    # @!attribute [rw] stl
+    #   Returns steals
+    #   @api public
+    #   @example
+    #     stat.stl #=> 1400.0
+    #   @return [Float] steals
+    attribute :stl, Shale::Type::Float
+
+    # @!attribute [rw] blk
+    #   Returns blocks
+    #   @api public
+    #   @example
+    #     stat.blk #=> 300.0
+    #   @return [Float] blocks
+    attribute :blk, Shale::Type::Float
+
+    # @!attribute [rw] tov
+    #   Returns turnovers
+    #   @api public
+    #   @example
+    #     stat.tov #=> 2600.0
+    #   @return [Float] turnovers
+    attribute :tov, Shale::Type::Float
+
+    # @!attribute [rw] pf
+    #   Returns personal fouls
+    #   @api public
+    #   @example
+    #     stat.pf #=> 2000.0
+    #   @return [Float] personal fouls
+    attribute :pf, Shale::Type::Float
+
+    # @!attribute [rw] pts
+    #   Returns points
+    #   @api public
+    #   @example
+    #     stat.pts #=> 24000.0
+    #   @return [Float] points
+    attribute :pts, 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
+  end
+end

data/lib/nba/common_player_info.rb

@@ -0,0 +1,142 @@
+require "json"
+require_relative "client"
+require_relative "player_info"
+require_relative "utils"
+
+module NBA
+  # Provides methods to retrieve detailed player information
+  module CommonPlayerInfo
+    # Result set name for common player info
+    # @return [String] the result set name
+    COMMON_PLAYER_INFO = "CommonPlayerInfo".freeze
+
+    # Retrieves detailed information for a player
+    #
+    # @api public
+    # @example
+    #   info = NBA::CommonPlayerInfo.find(player: 201939)
+    #   puts "#{info.display_name} - #{info.position} - #{info.team_name}"
+    # @param player [Integer, Player] the player ID or Player object
+    # @param client [Client] the API client to use
+    # @return [PlayerInfo, nil] the player info
+    def self.find(player:, client: CLIENT)
+      player_id = extract_player_id(player)
+      path = "commonplayerinfo?PlayerID=#{player_id}"
+      response = client.get(path)
+      parse_response(response)
+    end
+
+    # Parses the API response into a PlayerInfo object
+    # @api private
+    # @param response [String, nil] the JSON response
+    # @return [PlayerInfo, nil] the player info
+    def self.parse_response(response)
+      return unless response
+
+      data = JSON.parse(response)
+      result_set = find_result_set(data)
+      return unless result_set
+
+      headers = result_set["headers"]
+      row = result_set.dig("rowSet", 0)
+      return unless headers && row
+
+      build_player_info(headers, row)
+    end
+    private_class_method :parse_response
+
+    # Finds the common player info 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?(COMMON_PLAYER_INFO) }
+    end
+    private_class_method :find_result_set
+
+    # Builds a PlayerInfo object from raw data
+    # @api private
+    # @param headers [Array<String>] the column headers
+    # @param row [Array] the row data
+    # @return [PlayerInfo] the player info object
+    def self.build_player_info(headers, row)
+      data = headers.zip(row).to_h
+      PlayerInfo.new(**player_info_attributes(data))
+    end
+    private_class_method :build_player_info
+
+    # Combines all player info attributes
+    # @api private
+    # @param data [Hash] the raw data
+    # @return [Hash] the combined attributes
+    def self.player_info_attributes(data)
+      identity_attributes(data).merge(physical_attributes(data), team_attributes(data), draft_attributes(data))
+    end
+    private_class_method :player_info_attributes
+
+    # Extracts identity attributes from data
+    # @api private
+    # @param data [Hash] the raw data
+    # @return [Hash] identity attributes
+    def self.identity_attributes(data)
+      {player_id: data["PERSON_ID"], first_name: data["FIRST_NAME"], last_name: data["LAST_NAME"],
+       display_name: data["DISPLAY_FIRST_LAST"], birthdate: data["BIRTHDATE"], school: data["SCHOOL"],
+       country: data["COUNTRY"], from_year: data["FROM_YEAR"], to_year: data["TO_YEAR"],
+       greatest_75_flag: data["GREATEST_75_FLAG"]}
+    end
+    private_class_method :identity_attributes
+
+    # Extracts physical attributes from data
+    # @api private
+    # @param data [Hash] the raw data
+    # @return [Hash] physical attributes
+    def self.physical_attributes(data)
+      {height: data["HEIGHT"], weight: data["WEIGHT"], season_exp: data["SEASON_EXP"],
+       jersey: data["JERSEY"], position: data["POSITION"]}
+    end
+    private_class_method :physical_attributes
+
+    # Extracts team attributes from data
+    # @api private
+    # @param data [Hash] the raw data
+    # @return [Hash] team attributes
+    def self.team_attributes(data)
+      {team_id: data["TEAM_ID"], team_name: data["TEAM_NAME"],
+       team_abbreviation: data["TEAM_ABBREVIATION"], team_city: data["TEAM_CITY"]}
+    end
+    private_class_method :team_attributes
+
+    # Extracts draft attributes from data
+    # @api private
+    # @param data [Hash] the raw data
+    # @return [Hash] draft attributes
+    def self.draft_attributes(data)
+      {draft_year: parse_draft_value(data["DRAFT_YEAR"]), draft_round: parse_draft_value(data["DRAFT_ROUND"]),
+       draft_number: parse_draft_value(data["DRAFT_NUMBER"])}
+    end
+    private_class_method :draft_attributes
+
+    # Parses draft value, handling "Undrafted" case
+    # @api private
+    # @param value [String, Integer, nil] the draft value
+    # @return [Integer, nil] the parsed draft value
+    def self.parse_draft_value(value)
+      return if value.eql?("Undrafted")
+
+      value
+    end
+    private_class_method :parse_draft_value
+
+    # Extracts player ID from player object or integer
+    # @api private
+    # @param player [Player, Integer] the player
+    # @return [Integer, nil] the player ID
+    def self.extract_player_id(player)
+      player.instance_of?(Player) ? player.id : player
+    end
+    private_class_method :extract_player_id
+  end
+end

data/lib/nba/common_playoff_series.rb

@@ -0,0 +1,90 @@
+require "json"
+require_relative "client"
+require_relative "collection"
+require_relative "utils"
+
+require_relative "playoff_series"
+
+module NBA
+  # Provides methods to retrieve playoff series data
+  module CommonPlayoffSeries
+    # Result set name for playoff series
+    # @return [String] the result set name
+    PLAYOFF_SERIES = "PlayoffSeries".freeze
+
+    # Retrieves all playoff series for a season
+    #
+    # @api public
+    # @example
+    #   series = NBA::CommonPlayoffSeries.all(season: 2024)
+    #   series.each { |s| puts "Game #{s.game_num}: #{s.home_team_id} vs #{s.visitor_team_id}" }
+    # @param season [Integer] the season year
+    # @param league [String, League] the league ID or League object (default NBA)
+    # @param client [Client] the API client to use
+    # @return [Collection] a collection of playoff series
+    def self.all(season: Utils.current_season, league: League::NBA, client: CLIENT)
+      league_id = Utils.extract_league_id(league)
+      path = build_path(season, league_id)
+      response = client.get(path)
+      parse_response(response)
+    end
+
+    # Builds the API request path
+    # @api private
+    # @return [String] the request path
+    def self.build_path(season, league_id)
+      season_str = Utils.format_season(season)
+      "commonplayoffseries?LeagueID=#{league_id}&Season=#{season_str}"
+    end
+    private_class_method :build_path
+
+    # Parses the API response into playoff series objects
+    # @api private
+    # @return [Collection] collection of playoff series
+    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
+
+      series = rows.map { |row| build_series(headers, row) }
+      Collection.new(series)
+    end
+    private_class_method :parse_response
+
+    # Finds the playoff series result set in the response
+    # @api private
+    # @return [Hash, nil] the result set hash
+    def self.find_result_set(data)
+      result_sets = data["resultSets"]
+      return unless result_sets
+
+      result_sets.find { |rs| rs["name"].eql?(PLAYOFF_SERIES) }
+    end
+    private_class_method :find_result_set
+
+    # Builds a PlayoffSeries object from raw data
+    # @api private
+    # @return [PlayoffSeries] the playoff series object
+    def self.build_series(headers, row)
+      data = headers.zip(row).to_h
+      PlayoffSeries.new(**series_attributes(data))
+    end
+    private_class_method :build_series
+
+    # Extracts series attributes from data
+    # @api private
+    # @return [Hash] series attributes
+    def self.series_attributes(data)
+      {game_id: data["GAME_ID"], home_team_id: data["HOME_TEAM_ID"],
+       visitor_team_id: data["VISITOR_TEAM_ID"], series_id: data["SERIES_ID"],
+       game_num: data["GAME_NUM"]}
+    end
+    private_class_method :series_attributes
+  end
+end

data/lib/nba/common_team_years.rb

@@ -0,0 +1,113 @@
+require "json"
+require_relative "client"
+require_relative "collection"
+require_relative "team_year"
+
+module NBA
+  # Provides methods to retrieve team year history
+  module CommonTeamYears
+    # Result set name
+    # @return [String] the result set name
+    TEAM_YEARS = "TeamYears".freeze
+
+    # Retrieves all years a team has participated in the league
+    #
+    # @api public
+    # @example
+    #   years = NBA::CommonTeamYears.all
+    #   gsw_years = years.select { |y| y.team_id == NBA::Team::GSW }
+    #   puts "Warriors have played #{gsw_years.size} seasons"
+    # @param client [Client] the API client to use
+    # @return [Collection] a collection of team years
+    def self.all(client: CLIENT)
+      path = "commonteamyears?LeagueID=00"
+      response = client.get(path)
+      parse_response(response)
+    end
+
+    # Retrieves years for a specific team
+    #
+    # @api public
+    # @example
+    #   years = NBA::CommonTeamYears.find(team: NBA::Team::GSW)
+    #   puts "First year: #{years.first.year}, Latest: #{years.last.year}"
+    # @param team [Integer, Team] the team ID or Team object
+    # @param client [Client] the API client to use
+    # @return [Collection] a collection of team years for the team
+    def self.find(team:, client: CLIENT)
+      team_id = extract_team_id(team)
+      years = all(client: client)
+      Collection.new(years.select { |y| y.team_id.eql?(team_id) })
+    end
+
+    # Parses the API response
+    # @api private
+    # @param response [String, nil] the JSON response
+    # @return [Collection] collection of team years
+    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
+
+      build_team_years(result_set)
+    end
+    private_class_method :parse_response
+
+    # Finds the result set
+    # @api private
+    # @param data [Hash] the parsed JSON
+    # @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.fetch("name").eql?(TEAM_YEARS) }
+    end
+    private_class_method :find_result_set
+
+    # Builds team years collection
+    # @api private
+    # @param result_set [Hash] the result set
+    # @return [Collection] collection of team years
+    def self.build_team_years(result_set)
+      headers = result_set["headers"]
+      rows = result_set["rowSet"]
+      return Collection.new unless headers && rows
+
+      years = rows.map { |row| build_team_year(headers, row) }
+      Collection.new(years)
+    end
+    private_class_method :build_team_years
+
+    # Builds a team year
+    # @api private
+    # @param headers [Array<String>] the headers
+    # @param row [Array] the row data
+    # @return [TeamYear] the team year
+    def self.build_team_year(headers, row)
+      data = headers.zip(row).to_h
+      TeamYear.new(**team_year_attributes(data))
+    end
+    private_class_method :build_team_year
+
+    # Extracts team year attributes
+    # @api private
+    # @param data [Hash] the raw data
+    # @return [Hash] the attributes
+    def self.team_year_attributes(data)
+      {team_id: data.fetch("TEAM_ID"), year: data.fetch("MAX_YEAR"), abbreviation: data.fetch("ABBREVIATION")}
+    end
+    private_class_method :team_year_attributes
+
+    # Extracts team ID
+    # @api private
+    # @param team [Team, Integer] the team
+    # @return [Integer, nil] the team ID
+    def self.extract_team_id(team)
+      team.instance_of?(Team) ? team.id : team
+    end
+    private_class_method :extract_team_id
+  end
+end

data/lib/nba/conference.rb

@@ -0,0 +1,39 @@
+require "equalizer"
+require "shale"
+
+module NBA
+  # Represents an NBA conference (Eastern or Western)
+  class Conference < Shale::Mapper
+    include Equalizer.new(:id)
+
+    # @!attribute [rw] id
+    #   Returns the unique identifier for the conference
+    #   @api public
+    #   @example
+    #     conference.id #=> 1
+    #   @return [Integer] the unique identifier for the conference
+    attribute :id, Shale::Type::Integer
+
+    # @!attribute [rw] name
+    #   Returns the conference name
+    #   @api public
+    #   @example
+    #     conference.name #=> "Eastern"
+    #   @return [String] the conference name
+    attribute :name, Shale::Type::String
+
+    # @!attribute [rw] link
+    #   Returns the API link for the conference
+    #   @api public
+    #   @example
+    #     conference.link #=> "/api/v1/conferences/1"
+    #   @return [String] the API link for the conference
+    attribute :link, Shale::Type::String
+
+    json do
+      map "id", to: :id
+      map "name", to: :name
+      map "link", to: :link
+    end
+  end
+end

data/lib/nba/connection.rb

@@ -0,0 +1,84 @@
+require "net/http"
+require "openssl"
+require "stringio"
+require "uri"
+require "zlib"
+
+module NBA
+  # Handles HTTP connections to the NBA API
+  class Connection
+    # Default base URL for the NBA Stats API
+    # @return [String] the default base URL
+    BASE_URL = "https://stats.nba.com/stats/".freeze
+
+    # Returns the base URL for API requests
+    #
+    # @api private
+    # @return [String] the base URL
+    attr_reader :base_url
+
+    # Initializes a new Connection object
+    #
+    # @api public
+    # @example
+    #   connection = NBA::Connection.new
+    # @param base_url [String] the base URL for API requests
+    # @return [NBA::Connection] a new connection instance
+    def initialize(base_url: BASE_URL)
+      @base_url = base_url
+    end
+
+    # Makes a GET request to the specified path
+    #
+    # @api public
+    # @example
+    #   connection.get("teams")
+    # @param path [String] the API path to request
+    # @return [String] the response body
+    def get(path)
+      uri = URI.join(base_url, path)
+      hostname = uri.hostname or raise ArgumentError, "Invalid URI: #{uri}"
+      request = Net::HTTP::Get.new(uri)
+      apply_headers(request)
+
+      Net::HTTP.start(hostname, uri.port, use_ssl: uri.scheme.eql?("https")) do |http|
+        response = http.request(request)
+        decode_body(response) if response.is_a?(Net::HTTPSuccess)
+      end
+    end
+
+    private
+
+    # Applies the required headers for NBA Stats API requests
+    #
+    # @api private
+    # @param request [Net::HTTP::Get] the request object
+    # @return [void]
+    def apply_headers(request)
+      request["User-Agent"] = "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) " \
+                              "AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36"
+      request["Accept"] = "application/json, text/plain, */*"
+      request["Accept-Language"] = "en-US,en;q=0.9"
+      request["Accept-Encoding"] = "gzip, deflate, identity"
+      request["Connection"] = "keep-alive"
+      request["Referer"] = "https://www.nba.com/"
+      request["Origin"] = "https://www.nba.com"
+    end
+
+    # Decodes the response body based on Content-Encoding
+    #
+    # @api private
+    # @param response [Net::HTTPResponse] the HTTP response
+    # @return [String, nil] the decoded response body
+    def decode_body(response)
+      case response["Content-Encoding"]
+      when "gzip"
+        Zlib::GzipReader.new(StringIO.new(response.body)).read
+      when "deflate"
+        Zlib::Inflate.inflate(response.body)
+      else
+        response.body
+      end
+    end
+  end
+end