nba 0.1.1 → 0.2.0

data/lib/nba/found_game.rb

@@ -0,0 +1,260 @@
+module NBA
+  # Represents a found game from the league game finder
+  class FoundGame < Shale::Mapper
+    include Equalizer.new(:game_id)
+
+    # @!attribute [rw] season_id
+    #   Returns the season ID
+    #   @api public
+    #   @example
+    #     game.season_id #=> "22024"
+    #   @return [String] the season ID
+    attribute :season_id, Shale::Type::String
+
+    # @!attribute [rw] team_id
+    #   Returns the team ID
+    #   @api public
+    #   @example
+    #     game.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
+    #     game.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
+    #     game.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
+    #     game.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
+    #     game.game_date #=> "2024-10-22"
+    #   @return [String] the game date
+    attribute :game_date, Shale::Type::String
+
+    # @!attribute [rw] matchup
+    #   Returns the matchup string
+    #   @api public
+    #   @example
+    #     game.matchup #=> "GSW vs. LAL"
+    #   @return [String] the matchup
+    attribute :matchup, Shale::Type::String
+
+    # @!attribute [rw] wl
+    #   Returns win/loss result
+    #   @api public
+    #   @example
+    #     game.wl #=> "W"
+    #   @return [String] W or L
+    attribute :wl, Shale::Type::String
+
+    # @!attribute [rw] min
+    #   Returns minutes played
+    #   @api public
+    #   @example
+    #     game.min #=> 240
+    #   @return [Integer] minutes
+    attribute :min, Shale::Type::Integer
+
+    # @!attribute [rw] pts
+    #   Returns points scored
+    #   @api public
+    #   @example
+    #     game.pts #=> 110
+    #   @return [Integer] points
+    attribute :pts, Shale::Type::Integer
+
+    # @!attribute [rw] fgm
+    #   Returns field goals made
+    #   @api public
+    #   @example
+    #     game.fgm #=> 42
+    #   @return [Integer] field goals made
+    attribute :fgm, Shale::Type::Integer
+
+    # @!attribute [rw] fga
+    #   Returns field goals attempted
+    #   @api public
+    #   @example
+    #     game.fga #=> 85
+    #   @return [Integer] field goals attempted
+    attribute :fga, Shale::Type::Integer
+
+    # @!attribute [rw] fg_pct
+    #   Returns field goal percentage
+    #   @api public
+    #   @example
+    #     game.fg_pct #=> 0.494
+    #   @return [Float] field goal percentage
+    attribute :fg_pct, Shale::Type::Float
+
+    # @!attribute [rw] fg3m
+    #   Returns three-pointers made
+    #   @api public
+    #   @example
+    #     game.fg3m #=> 14
+    #   @return [Integer] three-pointers made
+    attribute :fg3m, Shale::Type::Integer
+
+    # @!attribute [rw] fg3a
+    #   Returns three-pointers attempted
+    #   @api public
+    #   @example
+    #     game.fg3a #=> 35
+    #   @return [Integer] three-pointers attempted
+    attribute :fg3a, Shale::Type::Integer
+
+    # @!attribute [rw] fg3_pct
+    #   Returns three-point percentage
+    #   @api public
+    #   @example
+    #     game.fg3_pct #=> 0.4
+    #   @return [Float] three-point percentage
+    attribute :fg3_pct, Shale::Type::Float
+
+    # @!attribute [rw] ftm
+    #   Returns free throws made
+    #   @api public
+    #   @example
+    #     game.ftm #=> 12
+    #   @return [Integer] free throws made
+    attribute :ftm, Shale::Type::Integer
+
+    # @!attribute [rw] fta
+    #   Returns free throws attempted
+    #   @api public
+    #   @example
+    #     game.fta #=> 15
+    #   @return [Integer] free throws attempted
+    attribute :fta, Shale::Type::Integer
+
+    # @!attribute [rw] ft_pct
+    #   Returns free throw percentage
+    #   @api public
+    #   @example
+    #     game.ft_pct #=> 0.8
+    #   @return [Float] free throw percentage
+    attribute :ft_pct, Shale::Type::Float
+
+    # @!attribute [rw] oreb
+    #   Returns offensive rebounds
+    #   @api public
+    #   @example
+    #     game.oreb #=> 10
+    #   @return [Integer] offensive rebounds
+    attribute :oreb, Shale::Type::Integer
+
+    # @!attribute [rw] dreb
+    #   Returns defensive rebounds
+    #   @api public
+    #   @example
+    #     game.dreb #=> 32
+    #   @return [Integer] defensive rebounds
+    attribute :dreb, Shale::Type::Integer
+
+    # @!attribute [rw] reb
+    #   Returns total rebounds
+    #   @api public
+    #   @example
+    #     game.reb #=> 42
+    #   @return [Integer] total rebounds
+    attribute :reb, Shale::Type::Integer
+
+    # @!attribute [rw] ast
+    #   Returns assists
+    #   @api public
+    #   @example
+    #     game.ast #=> 28
+    #   @return [Integer] assists
+    attribute :ast, Shale::Type::Integer
+
+    # @!attribute [rw] stl
+    #   Returns steals
+    #   @api public
+    #   @example
+    #     game.stl #=> 8
+    #   @return [Integer] steals
+    attribute :stl, Shale::Type::Integer
+
+    # @!attribute [rw] blk
+    #   Returns blocks
+    #   @api public
+    #   @example
+    #     game.blk #=> 5
+    #   @return [Integer] blocks
+    attribute :blk, Shale::Type::Integer
+
+    # @!attribute [rw] tov
+    #   Returns turnovers
+    #   @api public
+    #   @example
+    #     game.tov #=> 12
+    #   @return [Integer] turnovers
+    attribute :tov, Shale::Type::Integer
+
+    # @!attribute [rw] pf
+    #   Returns personal fouls
+    #   @api public
+    #   @example
+    #     game.pf #=> 18
+    #   @return [Integer] personal fouls
+    attribute :pf, Shale::Type::Integer
+
+    # @!attribute [rw] plus_minus
+    #   Returns plus/minus
+    #   @api public
+    #   @example
+    #     game.plus_minus #=> 10
+    #   @return [Integer] plus/minus
+    attribute :plus_minus, Shale::Type::Integer
+
+    # Returns the team object
+    #
+    # @api public
+    # @example
+    #   game.team #=> #<NBA::Team>
+    # @return [Team, nil] the team object
+    def team
+      Teams.find(team_id)
+    end
+
+    # Returns whether the game was a win
+    #
+    # @api public
+    # @example
+    #   game.win? #=> true
+    # @return [Boolean] true if win
+    def win?
+      wl.eql?("W")
+    end
+
+    # Returns whether the game was a loss
+    #
+    # @api public
+    # @example
+    #   game.loss? #=> true
+    # @return [Boolean] true if loss
+    def loss?
+      wl.eql?("L")
+    end
+  end
+end

data/lib/nba/franchise.rb

@@ -0,0 +1,136 @@
+module NBA
+  # Represents franchise history data
+  class Franchise < Shale::Mapper
+    include Equalizer.new(:team_id)
+
+    # @!attribute [rw] league_id
+    #   Returns the league ID
+    #   @api public
+    #   @example
+    #     franchise.league_id #=> "00"
+    #   @return [String] the league ID
+    attribute :league_id, Shale::Type::String
+
+    # @!attribute [rw] team_id
+    #   Returns the team ID
+    #   @api public
+    #   @example
+    #     franchise.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
+    #     franchise.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
+    #     franchise.team_name #=> "Warriors"
+    #   @return [String] the team name
+    attribute :team_name, Shale::Type::String
+
+    # @!attribute [rw] start_year
+    #   Returns the franchise start year
+    #   @api public
+    #   @example
+    #     franchise.start_year #=> 1946
+    #   @return [Integer] the start year
+    attribute :start_year, Shale::Type::Integer
+
+    # @!attribute [rw] end_year
+    #   Returns the franchise end year
+    #   @api public
+    #   @example
+    #     franchise.end_year #=> 2024
+    #   @return [Integer] the end year
+    attribute :end_year, Shale::Type::Integer
+
+    # @!attribute [rw] years
+    #   Returns the number of years the franchise has existed
+    #   @api public
+    #   @example
+    #     franchise.years #=> 78
+    #   @return [Integer] the number of years
+    attribute :years, Shale::Type::Integer
+
+    # @!attribute [rw] games
+    #   Returns the total games played
+    #   @api public
+    #   @example
+    #     franchise.games #=> 5832
+    #   @return [Integer] the total games
+    attribute :games, Shale::Type::Integer
+
+    # @!attribute [rw] wins
+    #   Returns the total wins
+    #   @api public
+    #   @example
+    #     franchise.wins #=> 2980
+    #   @return [Integer] the total wins
+    attribute :wins, Shale::Type::Integer
+
+    # @!attribute [rw] losses
+    #   Returns the total losses
+    #   @api public
+    #   @example
+    #     franchise.losses #=> 2852
+    #   @return [Integer] the total losses
+    attribute :losses, Shale::Type::Integer
+
+    # @!attribute [rw] win_pct
+    #   Returns the all-time win percentage
+    #   @api public
+    #   @example
+    #     franchise.win_pct #=> 0.511
+    #   @return [Float] the win percentage
+    attribute :win_pct, Shale::Type::Float
+
+    # @!attribute [rw] po_appearances
+    #   Returns the number of playoff appearances
+    #   @api public
+    #   @example
+    #     franchise.po_appearances #=> 35
+    #   @return [Integer] the playoff appearances
+    attribute :po_appearances, Shale::Type::Integer
+
+    # @!attribute [rw] div_titles
+    #   Returns the number of division titles
+    #   @api public
+    #   @example
+    #     franchise.div_titles #=> 12
+    #   @return [Integer] the division titles
+    attribute :div_titles, Shale::Type::Integer
+
+    # @!attribute [rw] conf_titles
+    #   Returns the number of conference titles
+    #   @api public
+    #   @example
+    #     franchise.conf_titles #=> 7
+    #   @return [Integer] the conference titles
+    attribute :conf_titles, Shale::Type::Integer
+
+    # @!attribute [rw] league_titles
+    #   Returns the number of league/NBA championships
+    #   @api public
+    #   @example
+    #     franchise.league_titles #=> 7
+    #   @return [Integer] the league championships
+    attribute :league_titles, Shale::Type::Integer
+
+    # Returns the team object for this franchise
+    #
+    # @api public
+    # @example
+    #   franchise.team #=> #<NBA::Team>
+    # @return [Team, nil] the team object
+    def team
+      Teams.find(team_id)
+    end
+  end
+end

data/lib/nba/franchise_history.rb

@@ -0,0 +1,142 @@
+require "json"
+require_relative "client"
+require_relative "collection"
+require_relative "franchise"
+
+module NBA
+  # Provides methods to retrieve franchise history
+  module FranchiseHistory
+    # Result set name for franchise history
+    # @return [String] the result set name
+    FRANCHISE_HISTORY = "FranchiseHistory".freeze
+
+    # Result set name for defunct teams
+    # @return [String] the result set name
+    DEFUNCT_TEAMS = "DefunctTeams".freeze
+
+    # Retrieves all franchise history data
+    #
+    # @api public
+    # @example
+    #   franchises = NBA::FranchiseHistory.all
+    #   franchises.each { |f| puts "#{f.team_city} #{f.team_name}: #{f.league_titles} titles" }
+    # @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 franchises
+    def self.all(league: League::NBA, client: CLIENT)
+      league_id = Utils.extract_league_id(league)
+      path = "franchisehistory?LeagueID=#{league_id}"
+      response = client.get(path)
+      parse_response(response, FRANCHISE_HISTORY)
+    end
+
+    # Retrieves defunct team history data
+    #
+    # @api public
+    # @example
+    #   defunct = NBA::FranchiseHistory.defunct
+    #   defunct.each { |f| puts "#{f.team_city} #{f.team_name}: #{f.start_year}-#{f.end_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 defunct franchises
+    def self.defunct(league: League::NBA, client: CLIENT)
+      league_id = Utils.extract_league_id(league)
+      path = "franchisehistory?LeagueID=#{league_id}"
+      response = client.get(path)
+      parse_response(response, DEFUNCT_TEAMS)
+    end
+
+    # Parses the API response
+    #
+    # @api private
+    # @param response [String] the JSON response body
+    # @param result_set_name [String] the name of the result set to extract
+    # @return [Collection] a collection of franchises
+    def self.parse_response(response, result_set_name)
+      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
+
+      franchises = rows.map { |row| build_franchise(headers, row) }
+      Collection.new(franchises)
+    end
+    private_class_method :parse_response
+
+    # Finds a result set by name
+    #
+    # @api private
+    # @param data [Hash] the parsed JSON data
+    # @param name [String] the result set name
+    # @return [Hash, nil] the result set
+    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 franchise from a row
+    #
+    # @api private
+    # @param headers [Array<String>] the column headers
+    # @param row [Array] the row data
+    # @return [Franchise] the franchise object
+    def self.build_franchise(headers, row)
+      data = headers.zip(row).to_h
+      Franchise.new(**franchise_attributes(data))
+    end
+    private_class_method :build_franchise
+
+    # Extracts franchise attributes from row data
+    #
+    # @api private
+    # @param data [Hash] the franchise row data
+    # @return [Hash] the franchise attributes
+    def self.franchise_attributes(data)
+      identity_attributes(data).merge(history_attributes(data), title_attributes(data))
+    end
+    private_class_method :franchise_attributes
+
+    # Extracts identity attributes
+    #
+    # @api private
+    # @param data [Hash] the franchise data
+    # @return [Hash] the identity attributes
+    def self.identity_attributes(data)
+      {league_id: data["LEAGUE_ID"], team_id: data["TEAM_ID"], team_city: data["TEAM_CITY"],
+       team_name: data["TEAM_NAME"]}
+    end
+    private_class_method :identity_attributes
+
+    # Extracts history attributes
+    #
+    # @api private
+    # @param data [Hash] the franchise data
+    # @return [Hash] the history attributes
+    def self.history_attributes(data)
+      {start_year: data["START_YEAR"], end_year: data["END_YEAR"],
+       years: data["YEARS"], games: data["GAMES"],
+       wins: data["WINS"], losses: data["LOSSES"],
+       win_pct: data["WIN_PCT"]}
+    end
+    private_class_method :history_attributes
+
+    # Extracts title/championship attributes
+    #
+    # @api private
+    # @param data [Hash] the franchise data
+    # @return [Hash] the title attributes
+    def self.title_attributes(data)
+      {po_appearances: data["PO_APPEARANCES"], div_titles: data["DIV_TITLES"],
+       conf_titles: data["CONF_TITLES"], league_titles: data["LEAGUE_TITLES"]}
+    end
+    private_class_method :title_attributes
+  end
+end

data/lib/nba/franchise_leader.rb

@@ -0,0 +1,147 @@
+require "equalizer"
+require "shale"
+
+module NBA
+  # Represents franchise leaders in various statistical categories
+  class FranchiseLeader < Shale::Mapper
+    include Equalizer.new(:team_id)
+
+    # @!attribute [rw] team_id
+    #   Returns the team ID
+    #   @api public
+    #   @example
+    #     leader.team_id #=> 1610612744
+    #   @return [Integer] the team ID
+    attribute :team_id, Shale::Type::Integer
+
+    # @!attribute [rw] pts_person_id
+    #   Returns the person ID of the points leader
+    #   @api public
+    #   @example
+    #     leader.pts_person_id #=> 201939
+    #   @return [Integer] the points leader's person ID
+    attribute :pts_person_id, Shale::Type::Integer
+
+    # @!attribute [rw] pts_player_name
+    #   Returns the name of the points leader
+    #   @api public
+    #   @example
+    #     leader.pts_player_name #=> "Stephen Curry"
+    #   @return [String] the points leader's name
+    attribute :pts_player_name, Shale::Type::String
+
+    # @!attribute [rw] pts
+    #   Returns the total points scored by the leader
+    #   @api public
+    #   @example
+    #     leader.pts #=> 23668
+    #   @return [Integer] the total points
+    attribute :pts, Shale::Type::Integer
+
+    # @!attribute [rw] ast_person_id
+    #   Returns the person ID of the assists leader
+    #   @api public
+    #   @example
+    #     leader.ast_person_id #=> 201939
+    #   @return [Integer] the assists leader's person ID
+    attribute :ast_person_id, Shale::Type::Integer
+
+    # @!attribute [rw] ast_player_name
+    #   Returns the name of the assists leader
+    #   @api public
+    #   @example
+    #     leader.ast_player_name #=> "Stephen Curry"
+    #   @return [String] the assists leader's name
+    attribute :ast_player_name, Shale::Type::String
+
+    # @!attribute [rw] ast
+    #   Returns the total assists by the leader
+    #   @api public
+    #   @example
+    #     leader.ast #=> 5845
+    #   @return [Integer] the total assists
+    attribute :ast, Shale::Type::Integer
+
+    # @!attribute [rw] reb_person_id
+    #   Returns the person ID of the rebounds leader
+    #   @api public
+    #   @example
+    #     leader.reb_person_id #=> 600015
+    #   @return [Integer] the rebounds leader's person ID
+    attribute :reb_person_id, Shale::Type::Integer
+
+    # @!attribute [rw] reb_player_name
+    #   Returns the name of the rebounds leader
+    #   @api public
+    #   @example
+    #     leader.reb_player_name #=> "Nate Thurmond"
+    #   @return [String] the rebounds leader's name
+    attribute :reb_player_name, Shale::Type::String
+
+    # @!attribute [rw] reb
+    #   Returns the total rebounds by the leader
+    #   @api public
+    #   @example
+    #     leader.reb #=> 12771
+    #   @return [Integer] the total rebounds
+    attribute :reb, Shale::Type::Integer
+
+    # @!attribute [rw] blk_person_id
+    #   Returns the person ID of the blocks leader
+    #   @api public
+    #   @example
+    #     leader.blk_person_id #=> 2442
+    #   @return [Integer] the blocks leader's person ID
+    attribute :blk_person_id, Shale::Type::Integer
+
+    # @!attribute [rw] blk_player_name
+    #   Returns the name of the blocks leader
+    #   @api public
+    #   @example
+    #     leader.blk_player_name #=> "Manute Bol"
+    #   @return [String] the blocks leader's name
+    attribute :blk_player_name, Shale::Type::String
+
+    # @!attribute [rw] blk
+    #   Returns the total blocks by the leader
+    #   @api public
+    #   @example
+    #     leader.blk #=> 2086
+    #   @return [Integer] the total blocks
+    attribute :blk, Shale::Type::Integer
+
+    # @!attribute [rw] stl_person_id
+    #   Returns the person ID of the steals leader
+    #   @api public
+    #   @example
+    #     leader.stl_person_id #=> 959
+    #   @return [Integer] the steals leader's person ID
+    attribute :stl_person_id, Shale::Type::Integer
+
+    # @!attribute [rw] stl_player_name
+    #   Returns the name of the steals leader
+    #   @api public
+    #   @example
+    #     leader.stl_player_name #=> "Chris Mullin"
+    #   @return [String] the steals leader's name
+    attribute :stl_player_name, Shale::Type::String
+
+    # @!attribute [rw] stl
+    #   Returns the total steals by the leader
+    #   @api public
+    #   @example
+    #     leader.stl #=> 1360
+    #   @return [Integer] the total steals
+    attribute :stl, Shale::Type::Integer
+
+    # Returns the team object for this franchise
+    #
+    # @api public
+    # @example
+    #   leader.team #=> #<NBA::Team>
+    # @return [Team, nil] the team object
+    def team
+      Teams.find(team_id)
+    end
+  end
+end