nba 0.1.1 → 0.2.0

data/lib/nba/franchise_leaders.rb

@@ -0,0 +1,162 @@
+require "json"
+require_relative "client"
+require_relative "franchise_leader"
+
+module NBA
+  # Provides methods to retrieve franchise leaders
+  module FranchiseLeaders
+    # Result set name for franchise leaders
+    # @return [String] the result set name
+    RESULTS = "FranchiseLeaders".freeze
+
+    # Retrieves franchise leaders for a team
+    #
+    # @api public
+    # @example
+    #   leader = NBA::FranchiseLeaders.find(team: NBA::Team::GSW)
+    #   puts "Points: #{leader.pts_player_name} (#{leader.pts})"
+    # @param team [Integer, Team] the team ID or Team object
+    # @param league [String, League] the league ID or League object (default NBA)
+    # @param client [Client] the API client to use
+    # @return [FranchiseLeader, nil] the franchise leader
+    def self.find(team:, league: League::NBA, client: CLIENT)
+      team_id = extract_team_id(team)
+      league_id = Utils.extract_league_id(league)
+      path = "franchiseleaders?TeamID=#{team_id}&LeagueID=#{league_id}"
+      response = client.get(path)
+      parse_response(response)
+    end
+
+    # Parses the API response
+    #
+    # @api private
+    # @param response [String] the JSON response body
+    # @return [FranchiseLeader, nil] the franchise leader
+    def self.parse_response(response)
+      return unless response
+
+      data = JSON.parse(response)
+      result_set = find_result_set(data, RESULTS)
+      return unless result_set
+
+      headers = result_set["headers"]
+      row = result_set.dig("rowSet", 0)
+      return unless headers && row
+
+      build_franchise_leader(headers, row)
+    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 leader from a row
+    #
+    # @api private
+    # @param headers [Array<String>] the column headers
+    # @param row [Array] the row data
+    # @return [FranchiseLeader] the franchise leader object
+    def self.build_franchise_leader(headers, row)
+      data = headers.zip(row).to_h
+      FranchiseLeader.new(**franchise_leader_attributes(data))
+    end
+    private_class_method :build_franchise_leader
+
+    # Extracts franchise leader attributes from row data
+    #
+    # @api private
+    # @param data [Hash] the franchise leader row data
+    # @return [Hash] the franchise leader attributes
+    def self.franchise_leader_attributes(data)
+      team_attributes(data).merge(points_attributes(data), assists_attributes(data),
+        rebounds_attributes(data), blocks_attributes(data), steals_attributes(data))
+    end
+    private_class_method :franchise_leader_attributes
+
+    # Extracts team attributes
+    #
+    # @api private
+    # @param data [Hash] the franchise leader data
+    # @return [Hash] the team attributes
+    def self.team_attributes(data)
+      {team_id: data.fetch("TEAM_ID")}
+    end
+    private_class_method :team_attributes
+
+    # Extracts points leader attributes
+    #
+    # @api private
+    # @param data [Hash] the franchise leader data
+    # @return [Hash] the points attributes
+    def self.points_attributes(data)
+      {pts_person_id: data.fetch("PTS_PERSON_ID"), pts_player_name: data.fetch("PTS_PLAYER"),
+       pts: data.fetch("PTS")}
+    end
+    private_class_method :points_attributes
+
+    # Extracts assists leader attributes
+    #
+    # @api private
+    # @param data [Hash] the franchise leader data
+    # @return [Hash] the assists attributes
+    def self.assists_attributes(data)
+      {ast_person_id: data.fetch("AST_PERSON_ID"), ast_player_name: data.fetch("AST_PLAYER"),
+       ast: data.fetch("AST")}
+    end
+    private_class_method :assists_attributes
+
+    # Extracts rebounds leader attributes
+    #
+    # @api private
+    # @param data [Hash] the franchise leader data
+    # @return [Hash] the rebounds attributes
+    def self.rebounds_attributes(data)
+      {reb_person_id: data.fetch("REB_PERSON_ID"), reb_player_name: data.fetch("REB_PLAYER"),
+       reb: data.fetch("REB")}
+    end
+    private_class_method :rebounds_attributes
+
+    # Extracts blocks leader attributes
+    #
+    # @api private
+    # @param data [Hash] the franchise leader data
+    # @return [Hash] the blocks attributes
+    def self.blocks_attributes(data)
+      {blk_person_id: data.fetch("BLK_PERSON_ID"), blk_player_name: data.fetch("BLK_PLAYER"),
+       blk: data.fetch("BLK")}
+    end
+    private_class_method :blocks_attributes
+
+    # Extracts steals leader attributes
+    #
+    # @api private
+    # @param data [Hash] the franchise leader data
+    # @return [Hash] the steals attributes
+    def self.steals_attributes(data)
+      {stl_person_id: data.fetch("STL_PERSON_ID"), stl_player_name: data.fetch("STL_PLAYER"),
+       stl: data.fetch("STL")}
+    end
+    private_class_method :steals_attributes
+
+    # Extracts team ID from team object or integer
+    #
+    # @api private
+    # @param team [Integer, Team] the team ID or Team object
+    # @return [Integer] 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/franchise_player.rb

@@ -0,0 +1,224 @@
+module NBA
+  # Represents a player's franchise statistics
+  class FranchisePlayer < Shale::Mapper
+    include Equalizer.new(:person_id)
+
+    # @!attribute [rw] league_id
+    #   Returns the league ID
+    #   @api public
+    #   @example
+    #     player.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
+    #     player.team_id #=> 1610612744
+    #   @return [Integer] the team ID
+    attribute :team_id, Shale::Type::Integer
+
+    # @!attribute [rw] team
+    #   Returns the team name
+    #   @api public
+    #   @example
+    #     player.team #=> "Golden State Warriors"
+    #   @return [String] the team name
+    attribute :team, Shale::Type::String
+
+    # @!attribute [rw] person_id
+    #   Returns the player ID
+    #   @api public
+    #   @example
+    #     player.person_id #=> 201939
+    #   @return [Integer] the player ID
+    attribute :person_id, Shale::Type::Integer
+
+    # @!attribute [rw] player
+    #   Returns the player name
+    #   @api public
+    #   @example
+    #     player.player #=> "Stephen Curry"
+    #   @return [String] the player name
+    attribute :player, Shale::Type::String
+
+    # @!attribute [rw] season_type
+    #   Returns the season type
+    #   @api public
+    #   @example
+    #     player.season_type #=> "Regular Season"
+    #   @return [String] the season type
+    attribute :season_type, Shale::Type::String
+
+    # @!attribute [rw] active_with_team
+    #   Returns whether the player is active with the team
+    #   @api public
+    #   @example
+    #     player.active_with_team #=> "Y"
+    #   @return [String] the active status
+    attribute :active_with_team, Shale::Type::String
+
+    # @!attribute [rw] gp
+    #   Returns the games played
+    #   @api public
+    #   @example
+    #     player.gp #=> 745
+    #   @return [Integer] the games played
+    attribute :gp, Shale::Type::Integer
+
+    # @!attribute [rw] fgm
+    #   Returns the field goals made
+    #   @api public
+    #   @example
+    #     player.fgm #=> 9.2
+    #   @return [Float] the field goals made
+    attribute :fgm, Shale::Type::Float
+
+    # @!attribute [rw] fga
+    #   Returns the field goals attempted
+    #   @api public
+    #   @example
+    #     player.fga #=> 19.3
+    #   @return [Float] the field goals attempted
+    attribute :fga, Shale::Type::Float
+
+    # @!attribute [rw] fg_pct
+    #   Returns the field goal percentage
+    #   @api public
+    #   @example
+    #     player.fg_pct #=> 0.476
+    #   @return [Float] the field goal percentage
+    attribute :fg_pct, Shale::Type::Float
+
+    # @!attribute [rw] fg3m
+    #   Returns the three-point field goals made
+    #   @api public
+    #   @example
+    #     player.fg3m #=> 4.5
+    #   @return [Float] the three-point field goals made
+    attribute :fg3m, Shale::Type::Float
+
+    # @!attribute [rw] fg3a
+    #   Returns the three-point field goals attempted
+    #   @api public
+    #   @example
+    #     player.fg3a #=> 11.2
+    #   @return [Float] the three-point field goals attempted
+    attribute :fg3a, Shale::Type::Float
+
+    # @!attribute [rw] fg3_pct
+    #   Returns the three-point field goal percentage
+    #   @api public
+    #   @example
+    #     player.fg3_pct #=> 0.426
+    #   @return [Float] the three-point field goal percentage
+    attribute :fg3_pct, Shale::Type::Float
+
+    # @!attribute [rw] ftm
+    #   Returns the free throws made
+    #   @api public
+    #   @example
+    #     player.ftm #=> 4.8
+    #   @return [Float] the free throws made
+    attribute :ftm, Shale::Type::Float
+
+    # @!attribute [rw] fta
+    #   Returns the free throws attempted
+    #   @api public
+    #   @example
+    #     player.fta #=> 5.3
+    #   @return [Float] the free throws attempted
+    attribute :fta, Shale::Type::Float
+
+    # @!attribute [rw] ft_pct
+    #   Returns the free throw percentage
+    #   @api public
+    #   @example
+    #     player.ft_pct #=> 0.908
+    #   @return [Float] the free throw percentage
+    attribute :ft_pct, Shale::Type::Float
+
+    # @!attribute [rw] oreb
+    #   Returns the offensive rebounds
+    #   @api public
+    #   @example
+    #     player.oreb #=> 0.5
+    #   @return [Float] the offensive rebounds
+    attribute :oreb, Shale::Type::Float
+
+    # @!attribute [rw] dreb
+    #   Returns the defensive rebounds
+    #   @api public
+    #   @example
+    #     player.dreb #=> 4.5
+    #   @return [Float] the defensive rebounds
+    attribute :dreb, Shale::Type::Float
+
+    # @!attribute [rw] reb
+    #   Returns the total rebounds
+    #   @api public
+    #   @example
+    #     player.reb #=> 5.0
+    #   @return [Float] the total rebounds
+    attribute :reb, Shale::Type::Float
+
+    # @!attribute [rw] ast
+    #   Returns the assists
+    #   @api public
+    #   @example
+    #     player.ast #=> 6.5
+    #   @return [Float] the assists
+    attribute :ast, Shale::Type::Float
+
+    # @!attribute [rw] pf
+    #   Returns the personal fouls
+    #   @api public
+    #   @example
+    #     player.pf #=> 2.1
+    #   @return [Float] the personal fouls
+    attribute :pf, Shale::Type::Float
+
+    # @!attribute [rw] stl
+    #   Returns the steals
+    #   @api public
+    #   @example
+    #     player.stl #=> 1.6
+    #   @return [Float] the steals
+    attribute :stl, Shale::Type::Float
+
+    # @!attribute [rw] tov
+    #   Returns the turnovers
+    #   @api public
+    #   @example
+    #     player.tov #=> 3.1
+    #   @return [Float] the turnovers
+    attribute :tov, Shale::Type::Float
+
+    # @!attribute [rw] blk
+    #   Returns the blocks
+    #   @api public
+    #   @example
+    #     player.blk #=> 0.2
+    #   @return [Float] the blocks
+    attribute :blk, Shale::Type::Float
+
+    # @!attribute [rw] pts
+    #   Returns the points
+    #   @api public
+    #   @example
+    #     player.pts #=> 24.8
+    #   @return [Float] the points
+    attribute :pts, Shale::Type::Float
+
+    # Returns the player information
+    #
+    # @api public
+    # @example
+    #   franchise_player.player_info #=> #<NBA::Player>
+    # @return [Player, nil] the player object
+    def player_info
+      Players.find(person_id)
+    end
+  end
+end

data/lib/nba/franchise_players.rb

@@ -0,0 +1,147 @@
+require "json"
+require_relative "client"
+require_relative "collection"
+require_relative "franchise_player"
+
+module NBA
+  # Provides methods to retrieve franchise player statistics
+  module FranchisePlayers
+    # Result set name for franchise players
+    # @return [String] the result set name
+    RESULTS = "FranchisePlayers".freeze
+
+    # Per mode constant for per game stats
+    # @return [String] the per game mode
+    PER_GAME = "PerGame".freeze
+
+    # Per mode constant for totals stats
+    # @return [String] the totals mode
+    TOTALS = "Totals".freeze
+
+    # Retrieves all franchise player statistics
+    #
+    # @api public
+    # @example
+    #   players = NBA::FranchisePlayers.all(team: 1610612744)
+    #   players.each { |p| puts "#{p.player}: #{p.pts} PPG" }
+    # @param team [Integer, String, Team] the team ID or Team object
+    # @param season_type [String] the season type (default "Regular Season")
+    # @param per_mode [String] the per mode (default PER_GAME)
+    # @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 franchise players
+    def self.all(team:, season_type: "Regular Season", per_mode: PER_GAME, league: League::NBA, client: CLIENT)
+      team_id = Utils.extract_id(team)
+      return Collection.new unless team_id
+
+      league_id = Utils.extract_league_id(league)
+      path = "franchiseplayers?TeamID=#{team_id}&SeasonType=#{season_type}&PerMode=#{per_mode}&LeagueID=#{league_id}"
+      response = client.get(path)
+      parse_response(response)
+    end
+
+    # Parses the API response
+    #
+    # @api private
+    # @param response [String] the JSON response body
+    # @return [Collection] a collection of franchise players
+    def self.parse_response(response)
+      return Collection.new unless response
+
+      data = JSON.parse(response)
+      result_set = find_result_set(data, RESULTS)
+      return Collection.new unless result_set
+
+      headers = result_set["headers"]
+      rows = result_set["rowSet"]
+      return Collection.new unless headers && rows
+
+      players = rows.map { |row| build_player(headers, row) }
+      Collection.new(players)
+    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 player from a row
+    #
+    # @api private
+    # @param headers [Array<String>] the column headers
+    # @param row [Array] the row data
+    # @return [FranchisePlayer] the franchise player object
+    def self.build_player(headers, row)
+      data = headers.zip(row).to_h
+      FranchisePlayer.new(**player_attributes(data))
+    end
+    private_class_method :build_player
+
+    # Extracts player attributes from row data
+    #
+    # @api private
+    # @param data [Hash] the player row data
+    # @return [Hash] the player attributes
+    def self.player_attributes(data)
+      identity_attributes(data).merge(stats_attributes(data), shooting_attributes(data), rebound_attributes(data))
+    end
+    private_class_method :player_attributes
+
+    # Extracts identity attributes
+    #
+    # @api private
+    # @param data [Hash] the player data
+    # @return [Hash] the identity attributes
+    def self.identity_attributes(data)
+      {league_id: data["LEAGUE_ID"], team_id: data["TEAM_ID"],
+       team: data["TEAM"], person_id: data["PERSON_ID"],
+       player: data["PLAYER"], season_type: data["SEASON_TYPE"],
+       active_with_team: data["ACTIVE_WITH_TEAM"]}
+    end
+    private_class_method :identity_attributes
+
+    # Extracts basic stats attributes
+    #
+    # @api private
+    # @param data [Hash] the player data
+    # @return [Hash] the stats attributes
+    def self.stats_attributes(data)
+      {gp: data["GP"], ast: data["AST"], pf: data["PF"],
+       stl: data["STL"], tov: data["TOV"], blk: data["BLK"],
+       pts: data["PTS"]}
+    end
+    private_class_method :stats_attributes
+
+    # Extracts shooting attributes
+    #
+    # @api private
+    # @param data [Hash] the player data
+    # @return [Hash] the shooting attributes
+    def self.shooting_attributes(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_attributes
+
+    # Extracts rebound attributes
+    #
+    # @api private
+    # @param data [Hash] the player data
+    # @return [Hash] the rebound attributes
+    def self.rebound_attributes(data)
+      {oreb: data["OREB"], dreb: data["DREB"], reb: data["REB"]}
+    end
+    private_class_method :rebound_attributes
+  end
+end

data/lib/nba/game.rb

@@ -1,76 +1,92 @@
-module NBA
-  class Game
-    attr_reader :home_team, :home_score, :away_team, :away_score, :status
+require "equalizer"
+require "shale"
+require_relative "team"
 
-    # Returns an array of Team objects
-    #
-    # @example
-    #   NBA::Game.all '20140102'
-    #   >>  Final/OT  -   Cavaliers     87  :  81    Magic
-    #   >>    Final   -      Heat      114  : 123   Warriors
-    #   >>    Final   -     Bulls       94  :  82   Celtics
-    #   >>    Final   -    Thunder      93  :  95     Nets
-    #   >>    Final   -     Spurs      101  : 105    Knicks
-    #   >>    Final   -      Suns       91  :  99  Grizzlies
-    #   >>    Final   -      Jazz       96  :  87    Bucks
-    #   >>    Final   - Trail Blazers  134  : 104   Bobcats
-    #   >>    Final   -     Kings      104  : 113    76ers
-    def self.all(date = (Time.now.utc - 5 * 60 * 60).strftime("%Y%m%d"))
-      results = scoreboard(date)
+module NBA
+  # Represents an NBA game
+  class Game < Shale::Mapper
+    include Equalizer.new(:id)
 
-      if results == 'fail'
-        puts "Fail to fetch game scoreboard/schedule!"
-      else
-        puts scoreboard(date).join("\n")
-      end
-    end
+    # @!attribute [rw] id
+    #   Returns the unique identifier for the game
+    #   @api public
+    #   @example
+    #     game.id #=> "0022400001"
+    #   @return [String] the unique identifier for the game
+    attribute :id, Shale::Type::String
 
-    def self.scoreboard(date = (Time.now.utc - 5 * 60 * 60).strftime("%Y%m%d"))
-      begin
-        format_games(results_to_game(results_from_espn(date)))
-      rescue Faraday::Error::ConnectionFailed, Faraday::Error::TimeoutError, Errno::EHOSTUNREACH
-        "fail"
-      end
-    end
+    # @!attribute [rw] date
+    #   Returns the date of the game
+    #   @api public
+    #   @example
+    #     game.date #=> "2024-10-22"
+    #   @return [String] the date of the game
+    attribute :date, Shale::Type::String
 
-    def pretty_format(options = {})
-      self.status.center(options[:status_length].to_i + 1) + " - " + \
-        self.home_team.center(options[:home_length].to_i + 1) + " " + \
-        self.home_score.center(options[:home_score].to_i + 1) + " : " + \
-        self.away_score.center(options[:away_score].to_i + 1) + " " + \
-        self.away_team.center(options[:away_length].to_i + 1)
-    end
+    # @!attribute [rw] status
+    #   Returns the game status
+    #   @api public
+    #   @example
+    #     game.status #=> "Final"
+    #   @return [String] the game status
+    attribute :status, Shale::Type::String
 
-    private
+    # @!attribute [rw] home_team
+    #   Returns the home team
+    #   @api public
+    #   @example
+    #     game.home_team #=> #<NBA::Team>
+    #   @return [Team] the home team
+    attribute :home_team, Team
 
-      def initialize(attributes = {})
-        attributes.each do |key, value|
-          instance_variable_set("@#{key}", value) if self.respond_to?(key)
-        end
-      end
+    # @!attribute [rw] away_team
+    #   Returns the away team
+    #   @api public
+    #   @example
+    #     game.away_team #=> #<NBA::Team>
+    #   @return [Team] the away team
+    attribute :away_team, Team
 
-      def self.length_options_of(games)
-        {
-          :status_length => games.map(&:status).map(&:length).max,
-          :home_length   => games.map(&:home_team).map(&:length).max,
-          :home_score    => games.map(&:home_score).map(&:length).max,
-          :away_length   => games.map(&:away_team).map(&:length).max,
-          :away_score    => games.map(&:away_score).map(&:length).max
-        }
-      end
+    # @!attribute [rw] home_score
+    #   Returns the home team score
+    #   @api public
+    #   @example
+    #     game.home_score #=> 112
+    #   @return [Integer] the home team score
+    attribute :home_score, Shale::Type::Integer
 
-      def self.format_games(games)
-        length_options = length_options_of(games)
-        games.map { |game| game.pretty_format(length_options) }
-      end
+    # @!attribute [rw] away_score
+    #   Returns the away team score
+    #   @api public
+    #   @example
+    #     game.away_score #=> 108
+    #   @return [Integer] the away team score
+    attribute :away_score, Shale::Type::Integer
 
-      def self.results_to_game(results)
-        results.map { |result| new result }
-      end
+    # @!attribute [rw] arena
+    #   Returns the arena where the game is played
+    #   @api public
+    #   @example
+    #     game.arena #=> "Chase Center"
+    #   @return [String] the arena name
+    attribute :arena, Shale::Type::String
 
-      def self.results_from_espn(date)
-        options = {:date => date}
-        Request.get_games('/nba/scoreboard', options)
-      end
+    json do
+      map "id", to: :id
+      map "gameId", to: :id
+      map "date", to: :date
+      map "gameDate", to: :date
+      map "status", to: :status
+      map "gameStatus", to: :status
+      map "home_team", to: :home_team
+      map "homeTeam", to: :home_team
+      map "away_team", to: :away_team
+      map "awayTeam", to: :away_team
+      map "home_score", to: :home_score
+      map "homeScore", to: :home_score
+      map "away_score", to: :away_score
+      map "awayScore", to: :away_score
+      map "arena", to: :arena
+    end
   end
 end