nba 0.1.1 → 0.2.0

data/lib/nba/team_year_by_year_stats.rb

@@ -0,0 +1,152 @@
+require "json"
+require_relative "client"
+require_relative "collection"
+
+require_relative "team_year_stat"
+
+module NBA
+  # Provides methods to retrieve team year-by-year statistics
+  module TeamYearByYearStats
+    # Result set name for team stats
+    # @return [String] the result set name
+    TEAM_STATS = "TeamStats".freeze
+
+    # Season type constant for regular season
+    # @return [String] the season type
+    REGULAR_SEASON = "Regular Season".freeze
+
+    # Season type constant for playoffs
+    # @return [String] the season type
+    PLAYOFFS = "Playoffs".freeze
+
+    # Per mode constant for per game stats
+    # @return [String] the per mode
+    PER_GAME = "PerGame".freeze
+
+    # Per mode constant for totals
+    # @return [String] the per mode
+    TOTALS = "Totals".freeze
+
+    # Retrieves year-by-year statistics for a team
+    #
+    # @api public
+    # @example
+    #   stats = NBA::TeamYearByYearStats.find(team: NBA::Team::GSW)
+    #   stats.each { |s| puts "#{s.year}: #{s.wins}-#{s.losses}" }
+    # @param team [Integer, Team] the team ID or Team object
+    # @param season_type [String] the season type
+    # @param per_mode [String] the per mode
+    # @param client [Client] the API client to use
+    # @return [Collection] a collection of year-by-year stats
+    def self.find(team:, season_type: REGULAR_SEASON, per_mode: PER_GAME, client: CLIENT)
+      team_id = extract_team_id(team)
+      path = build_path(team_id, season_type, per_mode)
+      response = client.get(path)
+      parse_response(response)
+    end
+
+    # Builds the API request path
+    # @api private
+    # @return [String] the request path
+    def self.build_path(team_id, season_type, per_mode)
+      encoded_type = season_type
+      "teamyearbyyearstats?TeamID=#{team_id}&SeasonType=#{encoded_type}&PerMode=#{per_mode}&LeagueID=00"
+    end
+    private_class_method :build_path
+
+    # Parses the API response into year stat objects
+    # @api private
+    # @return [Collection] collection of year stats
+    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
+
+      stats = rows.map { |row| build_year_stat(headers, row) }
+      Collection.new(stats)
+    end
+    private_class_method :parse_response
+
+    # Finds the team stats 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?(TEAM_STATS) }
+    end
+    private_class_method :find_result_set
+
+    # Builds a TeamYearStat object from raw data
+    # @api private
+    # @return [TeamYearStat] the year stat object
+    def self.build_year_stat(headers, row)
+      data = headers.zip(row).to_h
+      TeamYearStat.new(**year_stat_attributes(data))
+    end
+    private_class_method :build_year_stat
+
+    # Combines all year stat attributes
+    # @api private
+    # @return [Hash] the combined attributes
+    def self.year_stat_attributes(data)
+      identity_attributes(data).merge(record_attributes(data), shooting_attributes(data), counting_attributes(data))
+    end
+    private_class_method :year_stat_attributes
+
+    # Extracts identity attributes from data
+    # @api private
+    # @return [Hash] identity attributes
+    def self.identity_attributes(data)
+      {team_id: data["TEAM_ID"], team_city: data["TEAM_CITY"],
+       team_name: data["TEAM_NAME"], year: data["YEAR"], gp: data["GP"]}
+    end
+    private_class_method :identity_attributes
+
+    # Extracts record attributes from data
+    # @api private
+    # @return [Hash] record attributes
+    def self.record_attributes(data)
+      {wins: data["WINS"], losses: data["LOSSES"], win_pct: data["WIN_PCT"],
+       conf_rank: data["CONF_RANK"], div_rank: data["DIV_RANK"],
+       po_wins: data["PO_WINS"], po_losses: data["PO_LOSSES"],
+       nba_finals_appearance: data["NBA_FINALS_APPEARANCE"]}
+    end
+    private_class_method :record_attributes
+
+    # Extracts shooting attributes from data
+    # @api private
+    # @return [Hash] 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 counting stats attributes from data
+    # @api private
+    # @return [Hash] counting attributes
+    def self.counting_attributes(data)
+      {oreb: data["OREB"], dreb: data["DREB"], reb: data["REB"],
+       ast: data["AST"], pf: data["PF"], stl: data["STL"],
+       tov: data["TOV"], blk: data["BLK"], pts: data["PTS"], pts_rank: data["PTS_RANK"]}
+    end
+    private_class_method :counting_attributes
+
+    # Extracts team ID from team object or integer
+    # @api private
+    # @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/team_year_stat.rb

@@ -0,0 +1,282 @@
+module NBA
+  # Represents a team's year-by-year statistics
+  class TeamYearStat < Shale::Mapper
+    include Equalizer.new(:team_id, :year)
+
+    # @!attribute [rw] team_id
+    #   Returns the team ID
+    #   @api public
+    #   @example
+    #     stat.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
+    #     stat.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
+    #     stat.team_name #=> "Warriors"
+    #   @return [String] the team name
+    attribute :team_name, Shale::Type::String
+
+    # @!attribute [rw] year
+    #   Returns the year
+    #   @api public
+    #   @example
+    #     stat.year #=> "2024-25"
+    #   @return [String] the year
+    attribute :year, Shale::Type::String
+
+    # @!attribute [rw] gp
+    #   Returns games played
+    #   @api public
+    #   @example
+    #     stat.gp #=> 82
+    #   @return [Integer] games played
+    attribute :gp, Shale::Type::Integer
+
+    # @!attribute [rw] wins
+    #   Returns wins
+    #   @api public
+    #   @example
+    #     stat.wins #=> 46
+    #   @return [Integer] wins
+    attribute :wins, Shale::Type::Integer
+
+    # @!attribute [rw] losses
+    #   Returns losses
+    #   @api public
+    #   @example
+    #     stat.losses #=> 36
+    #   @return [Integer] losses
+    attribute :losses, Shale::Type::Integer
+
+    # @!attribute [rw] win_pct
+    #   Returns win percentage
+    #   @api public
+    #   @example
+    #     stat.win_pct #=> 0.561
+    #   @return [Float] win percentage
+    attribute :win_pct, Shale::Type::Float
+
+    # @!attribute [rw] conf_rank
+    #   Returns conference rank
+    #   @api public
+    #   @example
+    #     stat.conf_rank #=> 10
+    #   @return [Integer] conference rank
+    attribute :conf_rank, Shale::Type::Integer
+
+    # @!attribute [rw] div_rank
+    #   Returns division rank
+    #   @api public
+    #   @example
+    #     stat.div_rank #=> 3
+    #   @return [Integer] division rank
+    attribute :div_rank, Shale::Type::Integer
+
+    # @!attribute [rw] po_wins
+    #   Returns playoff wins
+    #   @api public
+    #   @example
+    #     stat.po_wins #=> 0
+    #   @return [Integer] playoff wins
+    attribute :po_wins, Shale::Type::Integer
+
+    # @!attribute [rw] po_losses
+    #   Returns playoff losses
+    #   @api public
+    #   @example
+    #     stat.po_losses #=> 0
+    #   @return [Integer] playoff losses
+    attribute :po_losses, Shale::Type::Integer
+
+    # @!attribute [rw] nba_finals_appearance
+    #   Returns NBA Finals appearance
+    #   @api public
+    #   @example
+    #     stat.nba_finals_appearance #=> "N/A"
+    #   @return [String] Finals appearance
+    attribute :nba_finals_appearance, Shale::Type::String
+
+    # @!attribute [rw] fgm
+    #   Returns field goals made per game
+    #   @api public
+    #   @example
+    #     stat.fgm #=> 43.2
+    #   @return [Float] field goals made
+    attribute :fgm, Shale::Type::Float
+
+    # @!attribute [rw] fga
+    #   Returns field goals attempted per game
+    #   @api public
+    #   @example
+    #     stat.fga #=> 91.5
+    #   @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.472
+    #   @return [Float] field goal percentage
+    attribute :fg_pct, Shale::Type::Float
+
+    # @!attribute [rw] fg3m
+    #   Returns three-pointers made per game
+    #   @api public
+    #   @example
+    #     stat.fg3m #=> 14.8
+    #   @return [Float] three-pointers made
+    attribute :fg3m, Shale::Type::Float
+
+    # @!attribute [rw] fg3a
+    #   Returns three-pointers attempted per game
+    #   @api public
+    #   @example
+    #     stat.fg3a #=> 40.2
+    #   @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.368
+    #   @return [Float] three-point percentage
+    attribute :fg3_pct, Shale::Type::Float
+
+    # @!attribute [rw] ftm
+    #   Returns free throws made per game
+    #   @api public
+    #   @example
+    #     stat.ftm #=> 17.5
+    #   @return [Float] free throws made
+    attribute :ftm, Shale::Type::Float
+
+    # @!attribute [rw] fta
+    #   Returns free throws attempted per game
+    #   @api public
+    #   @example
+    #     stat.fta #=> 22.1
+    #   @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.792
+    #   @return [Float] free throw percentage
+    attribute :ft_pct, Shale::Type::Float
+
+    # @!attribute [rw] oreb
+    #   Returns offensive rebounds per game
+    #   @api public
+    #   @example
+    #     stat.oreb #=> 10.5
+    #   @return [Float] offensive rebounds
+    attribute :oreb, Shale::Type::Float
+
+    # @!attribute [rw] dreb
+    #   Returns defensive rebounds per game
+    #   @api public
+    #   @example
+    #     stat.dreb #=> 33.8
+    #   @return [Float] defensive rebounds
+    attribute :dreb, Shale::Type::Float
+
+    # @!attribute [rw] reb
+    #   Returns total rebounds per game
+    #   @api public
+    #   @example
+    #     stat.reb #=> 44.3
+    #   @return [Float] total rebounds
+    attribute :reb, Shale::Type::Float
+
+    # @!attribute [rw] ast
+    #   Returns assists per game
+    #   @api public
+    #   @example
+    #     stat.ast #=> 28.1
+    #   @return [Float] assists
+    attribute :ast, Shale::Type::Float
+
+    # @!attribute [rw] pf
+    #   Returns personal fouls per game
+    #   @api public
+    #   @example
+    #     stat.pf #=> 19.5
+    #   @return [Float] personal fouls
+    attribute :pf, Shale::Type::Float
+
+    # @!attribute [rw] stl
+    #   Returns steals per game
+    #   @api public
+    #   @example
+    #     stat.stl #=> 7.8
+    #   @return [Float] steals
+    attribute :stl, Shale::Type::Float
+
+    # @!attribute [rw] tov
+    #   Returns turnovers per game
+    #   @api public
+    #   @example
+    #     stat.tov #=> 14.2
+    #   @return [Float] turnovers
+    attribute :tov, Shale::Type::Float
+
+    # @!attribute [rw] blk
+    #   Returns blocks per game
+    #   @api public
+    #   @example
+    #     stat.blk #=> 5.2
+    #   @return [Float] blocks
+    attribute :blk, Shale::Type::Float
+
+    # @!attribute [rw] pts
+    #   Returns points per game
+    #   @api public
+    #   @example
+    #     stat.pts #=> 118.7
+    #   @return [Float] points
+    attribute :pts, Shale::Type::Float
+
+    # @!attribute [rw] pts_rank
+    #   Returns points rank
+    #   @api public
+    #   @example
+    #     stat.pts_rank #=> 5
+    #   @return [Integer] points rank
+    attribute :pts_rank, Shale::Type::Integer
+
+    # Returns the team object
+    #
+    # @api public
+    # @example
+    #   stat.team #=> #<NBA::Team>
+    # @return [Team, nil] the team object
+    def team
+      Teams.find(team_id)
+    end
+
+    # Returns the full team name
+    #
+    # @api public
+    # @example
+    #   stat.full_name #=> "Golden State Warriors"
+    # @return [String] the full name
+    def full_name
+      "#{team_city} #{team_name}".strip
+    end
+  end
+end

data/lib/nba/teams.rb

@@ -0,0 +1,33 @@
+require_relative "collection"
+require_relative "data"
+require_relative "team"
+require_relative "utils"
+
+module NBA
+  # Provides methods to retrieve NBA teams
+  module Teams
+    # Retrieves all NBA teams
+    #
+    # @api public
+    # @example
+    #   teams = NBA::Teams.all
+    #   teams.each { |team| puts team.name }
+    # @return [Collection] a collection of all NBA teams
+    def self.all
+      Collection.new(Data::TEAMS.map { |data| Team.new(**data) })
+    end
+
+    # Finds a team by ID
+    #
+    # @api public
+    # @example
+    #   warriors = NBA::Teams.find(NBA::Team::GSW)
+    # @param team_id [Integer] the team ID to find
+    # @return [Team, nil] the team with the given ID, or nil if not found
+    def self.find(team_id)
+      id = Utils.extract_id(team_id)
+      data = Data::TEAMS.find { |t| t.fetch(:id).eql?(id) }
+      Team.new(**data) if data
+    end
+  end
+end

data/lib/nba/upcoming_game.rb

@@ -0,0 +1,115 @@
+require "equalizer"
+require "shale"
+
+module NBA
+  # Represents an upcoming game
+  #
+  # @api public
+  class UpcomingGame < Shale::Mapper
+    include Equalizer.new(:game_id)
+
+    # @!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-22T00:00:00"
+    #   @return [String] the game date
+    attribute :game_date, Shale::Type::String
+
+    # @!attribute [rw] game_time
+    #   Returns the game time
+    #   @api public
+    #   @example
+    #     game.game_time #=> "7:30 PM"
+    #   @return [String] the game time
+    attribute :game_time, Shale::Type::String
+
+    # @!attribute [rw] home_team_id
+    #   Returns the home team ID
+    #   @api public
+    #   @example
+    #     game.home_team_id #=> 1610612744
+    #   @return [Integer] the home team ID
+    attribute :home_team_id, Shale::Type::Integer
+
+    # @!attribute [rw] visitor_team_id
+    #   Returns the visitor team ID
+    #   @api public
+    #   @example
+    #     game.visitor_team_id #=> 1610612747
+    #   @return [Integer] the visitor team ID
+    attribute :visitor_team_id, Shale::Type::Integer
+
+    # @!attribute [rw] home_team_name
+    #   Returns the home team full name
+    #   @api public
+    #   @example
+    #     game.home_team_name #=> "Golden State Warriors"
+    #   @return [String] the home team name
+    attribute :home_team_name, Shale::Type::String
+
+    # @!attribute [rw] visitor_team_name
+    #   Returns the visitor team full name
+    #   @api public
+    #   @example
+    #     game.visitor_team_name #=> "Los Angeles Lakers"
+    #   @return [String] the visitor team name
+    attribute :visitor_team_name, Shale::Type::String
+
+    # @!attribute [rw] home_team_abbreviation
+    #   Returns the home team abbreviation
+    #   @api public
+    #   @example
+    #     game.home_team_abbreviation #=> "GSW"
+    #   @return [String] the home team abbreviation
+    attribute :home_team_abbreviation, Shale::Type::String
+
+    # @!attribute [rw] visitor_team_abbreviation
+    #   Returns the visitor team abbreviation
+    #   @api public
+    #   @example
+    #     game.visitor_team_abbreviation #=> "LAL"
+    #   @return [String] the visitor team abbreviation
+    attribute :visitor_team_abbreviation, Shale::Type::String
+
+    # @!attribute [rw] home_team_nickname
+    #   Returns the home team nickname
+    #   @api public
+    #   @example
+    #     game.home_team_nickname #=> "Warriors"
+    #   @return [String] the home team nickname
+    attribute :home_team_nickname, Shale::Type::String
+
+    # @!attribute [rw] visitor_team_nickname
+    #   Returns the visitor team nickname
+    #   @api public
+    #   @example
+    #     game.visitor_team_nickname #=> "Lakers"
+    #   @return [String] the visitor team nickname
+    attribute :visitor_team_nickname, Shale::Type::String
+
+    # Returns the home team object
+    #
+    # @api public
+    # @example
+    #   game.home_team #=> #<NBA::Team>
+    # @return [Team, nil] the home team
+    def home_team = Teams.find(home_team_id)
+
+    # Returns the visitor team object
+    #
+    # @api public
+    # @example
+    #   game.visitor_team #=> #<NBA::Team>
+    # @return [Team, nil] the visitor team
+    def visitor_team = Teams.find(visitor_team_id)
+  end
+end

data/lib/nba/utils.rb

@@ -0,0 +1,94 @@
+require "date"
+require "uri"
+
+module NBA
+  # Utility methods for the NBA gem
+  module Utils
+    # Returns the current NBA season year
+    #
+    # @api public
+    # @example
+    #   NBA::Utils.current_season #=> 2024
+    # @return [Integer] the current season year
+    def self.current_season
+      today = Date.today
+      # NBA season typically runs from October to June
+      # If we're in January-June, we're in the same season (which started previous year)
+      # Otherwise (July-December), return current year
+      (today.month <= 6) ? today.year - 1 : today.year
+    end
+
+    # Formats a season year into the NBA API format (e.g., "2024-25")
+    #
+    # @api public
+    # @example
+    #   NBA::Utils.format_season(2024) #=> "2024-25"
+    # @param year [Integer] the season start year
+    # @return [String] the formatted season string
+    def self.format_season(year)
+      "#{year}-#{(year + 1).to_s[-2..]}"
+    end
+
+    # Formats a season year into the NBA SeasonID format (e.g., "22024")
+    #
+    # @api public
+    # @example
+    #   NBA::Utils.format_season_id(2024) #=> "22024"
+    # @param year [Integer] the season start year
+    # @return [String] the formatted season ID string
+    def self.format_season_id(year)
+      "2#{year}"
+    end
+
+    # Builds a query string from a hash of parameters
+    #
+    # @api public
+    # @example
+    #   NBA::Utils.build_query(season: 2024, team_id: 1) #=> "season=2024&team_id=1"
+    # @param params [Hash] the parameters to build into a query string
+    # @return [String] the query string
+    def self.build_query(**params)
+      URI.encode_www_form(params.compact)
+    end
+
+    # Extracts an ID from an entity object or returns the value as-is
+    #
+    # @api public
+    # @example
+    #   NBA::Utils.extract_id(player) #=> 2544
+    #   NBA::Utils.extract_id(2544) #=> 2544
+    # @param entity [Player, Team, Game, Integer, String] the entity or ID
+    # @return [Integer, String] the extracted ID
+    def self.extract_id(entity)
+      entity.respond_to?(:id) ? entity.id : entity
+    end
+
+    # Parses a value as an integer, returning nil for invalid values
+    #
+    # @api public
+    # @example
+    #   NBA::Utils.parse_integer("42") #=> 42
+    #   NBA::Utils.parse_integer("N/A") #=> nil
+    # @param value [String, Integer, nil] the value to parse
+    # @return [Integer, nil] the parsed integer or nil
+    def self.parse_integer(value)
+      return if value.to_s.empty?
+
+      Integer(value)
+    rescue ArgumentError
+      nil
+    end
+
+    # Extracts a league ID from a League object or returns the value as-is
+    #
+    # @api public
+    # @example
+    #   NBA::Utils.extract_league_id(league) #=> "00"
+    #   NBA::Utils.extract_league_id("00") #=> "00"
+    # @param league [League, String] the league or ID
+    # @return [String] the extracted league ID
+    def self.extract_league_id(league)
+      league.respond_to?(:id) ? league.id : league
+    end
+  end
+end

data/lib/nba/version.rb

@@ -1,3 +1,6 @@
-module Nba
-  VERSION = "0.1.1"
+require "rubygems/version"
+
+module NBA
+  # Current version of the NBA gem
+  VERSION = Gem::Version.create("0.2.0")
 end