nba 0.1.1 → 0.2.0

data/lib/nba/team_game_streak.rb

@@ -0,0 +1,111 @@
+require "equalizer"
+require "shale"
+
+module NBA
+  # Represents a team's game streak statistics
+  #
+  # @api public
+  class TeamGameStreak < Shale::Mapper
+    include Equalizer.new(:team_id, :start_date, :end_date)
+
+    # @!attribute [rw] team_name
+    #   Returns the team name
+    #   @api public
+    #   @example
+    #     streak.team_name #=> "Warriors"
+    #   @return [String, nil] the team's name
+    attribute :team_name, Shale::Type::String
+
+    # @!attribute [rw] team_id
+    #   Returns the team ID
+    #   @api public
+    #   @example
+    #     streak.team_id #=> 1610612744
+    #   @return [Integer, nil] the team ID
+    attribute :team_id, Shale::Type::Integer
+
+    # @!attribute [rw] abbreviation
+    #   Returns the team abbreviation
+    #   @api public
+    #   @example
+    #     streak.abbreviation #=> "GSW"
+    #   @return [String, nil] the team abbreviation
+    attribute :abbreviation, Shale::Type::String
+
+    # @!attribute [rw] game_streak
+    #   Returns the number of consecutive games in the streak
+    #   @api public
+    #   @example
+    #     streak.game_streak #=> 10
+    #   @return [Integer, nil] the number of consecutive games in the streak
+    attribute :game_streak, Shale::Type::Integer
+
+    # @!attribute [rw] start_date
+    #   Returns the start date of the streak
+    #   @api public
+    #   @example
+    #     streak.start_date #=> "2024-01-15"
+    #   @return [String, nil] the start date of the streak
+    attribute :start_date, Shale::Type::String
+
+    # @!attribute [rw] end_date
+    #   Returns the end date of the streak
+    #   @api public
+    #   @example
+    #     streak.end_date #=> "2024-02-10"
+    #   @return [String, nil] the end date of the streak
+    attribute :end_date, Shale::Type::String
+
+    # @!attribute [rw] active_streak
+    #   Returns whether the streak is active (1 for active, 0 for inactive)
+    #   @api public
+    #   @example
+    #     streak.active_streak #=> 1
+    #   @return [Integer, nil] 1 for active, 0 for inactive
+    attribute :active_streak, Shale::Type::Integer
+
+    # @!attribute [rw] num_seasons
+    #   Returns the number of seasons the streak spans
+    #   @api public
+    #   @example
+    #     streak.num_seasons #=> 2
+    #   @return [Integer, nil] the number of seasons the streak spans
+    attribute :num_seasons, Shale::Type::Integer
+
+    # @!attribute [rw] last_season
+    #   Returns the last season of the streak
+    #   @api public
+    #   @example
+    #     streak.last_season #=> "2024-25"
+    #   @return [String, nil] the last season of the streak
+    attribute :last_season, Shale::Type::String
+
+    # @!attribute [rw] first_season
+    #   Returns the first season of the streak
+    #   @api public
+    #   @example
+    #     streak.first_season #=> "2023-24"
+    #   @return [String, nil] the first season of the streak
+    attribute :first_season, Shale::Type::String
+
+    # Returns whether the streak is currently active
+    #
+    # @api public
+    # @example
+    #   streak.active? #=> true
+    # @return [Boolean] true if the streak is active
+    def active?
+      active_streak.eql?(1)
+    end
+
+    # Returns the team associated with this streak
+    #
+    # @api public
+    # @example
+    #   streak.team #=> #<NBA::Team>
+    # @return [Team, nil] the team object for this streak
+    def team
+      Teams.find(team_id)
+    end
+  end
+end

data/lib/nba/team_game_streak_finder.rb

@@ -0,0 +1,109 @@
+require "json"
+require_relative "client"
+require_relative "response_parser"
+require_relative "team_game_streak"
+require_relative "utils"
+
+module NBA
+  # Provides methods to find team game streaks
+  #
+  # @api public
+  module TeamGameStreakFinder
+    # Result set name for streak finder results
+    # @return [String] the result set name
+    RESULT_SET_NAME = "TeamGameStreakFinderParametersResults".freeze
+
+    # Stat filter parameter mappings
+    # @return [Hash] mapping of Ruby method parameters to API parameters
+    STAT_FILTERS = {gt_pts: :GtPTS, gt_reb: :GtREB, gt_ast: :GtAST, gt_stl: :GtSTL, gt_blk: :GtBLK,
+                    gt_fg3m: :GtFG3M, w_streak: :WStreak, l_streak: :LStreak}.freeze
+
+    # Finds team game streaks matching the specified criteria
+    #
+    # @api public
+    # @example Find active 100+ point streaks
+    #   NBA::TeamGameStreakFinder.find(gt_pts: 100, active_streaks_only: true)
+    # @param season [String, nil] the season to search (e.g., "2024-25")
+    # @param team [Integer, Team, nil] filter by team ID or Team object
+    # @param active_streaks_only [Boolean, nil] only return active streaks
+    # @param gt_pts [Integer, nil] minimum points per game
+    # @param gt_reb [Integer, nil] minimum rebounds per game
+    # @param gt_ast [Integer, nil] minimum assists per game
+    # @param gt_stl [Integer, nil] minimum steals per game
+    # @param gt_blk [Integer, nil] minimum blocks per game
+    # @param gt_fg3m [Integer, nil] minimum 3-pointers made per game
+    # @param w_streak [Integer, nil] minimum consecutive wins
+    # @param l_streak [Integer, nil] minimum consecutive losses
+    # @param client [Client] the API client to use
+    # @return [Collection] collection of TeamGameStreak objects
+    def self.find(season: nil, team: nil, active_streaks_only: nil, gt_pts: nil, gt_reb: nil,
+      gt_ast: nil, gt_stl: nil, gt_blk: nil, gt_fg3m: nil, w_streak: nil, l_streak: nil, client: CLIENT)
+      filters = {gt_pts: gt_pts, gt_reb: gt_reb, gt_ast: gt_ast, gt_stl: gt_stl, gt_blk: gt_blk,
+                 gt_fg3m: gt_fg3m, w_streak: w_streak, l_streak: l_streak}
+      path = build_path(season, team, active_streaks_only, filters)
+      ResponseParser.parse(client.get(path), result_set: RESULT_SET_NAME) { |data| build_streak(data) }
+    end
+
+    # Builds the API path with query parameters
+    #
+    # @api private
+    # @return [String] the API endpoint path
+    def self.build_path(season, team, active_only, filters)
+      params = base_params(season, team, active_only)
+      add_stat_filters(params, filters)
+      "teamgamestreakfinder?#{URI.encode_www_form(params)}"
+    end
+    private_class_method :build_path
+
+    # Returns base parameters for the endpoint
+    #
+    # @api private
+    # @return [Hash] the base parameters hash
+    def self.base_params(season, team, active_only)
+      params = {LeagueID: "00", MinGames: 1}
+      params[:SeasonNullable] = season if season
+      params[:TeamIDNullable] = Utils.extract_id(team) if team
+      params[:ActiveStreaksOnly] = "Y" if active_only
+      params
+    end
+    private_class_method :base_params
+
+    # Adds stat filter parameters
+    #
+    # @api private
+    # @return [void]
+    def self.add_stat_filters(params, filters)
+      STAT_FILTERS.each { |key, param| params[param] = filters.fetch(key) if filters.fetch(key) }
+    end
+    private_class_method :add_stat_filters
+
+    # Builds a TeamGameStreak from API data
+    #
+    # @api private
+    # @return [TeamGameStreak] the team game streak object
+    def self.build_streak(data)
+      TeamGameStreak.new(**team_info(data), **streak_info(data))
+    end
+    private_class_method :build_streak
+
+    # Extracts team information from data
+    #
+    # @api private
+    # @return [Hash] the team information hash
+    def self.team_info(data)
+      {team_name: data["TEAM_NAME"], team_id: data["TEAM_ID"], abbreviation: data["ABBREVIATION"]}
+    end
+    private_class_method :team_info
+
+    # Extracts streak information from data
+    #
+    # @api private
+    # @return [Hash] the streak information hash
+    def self.streak_info(data)
+      {game_streak: data["GAMESTREAK"], start_date: data["STARTDATE"], end_date: data["ENDDATE"],
+       active_streak: data["ACTIVESTREAK"], num_seasons: data["NUMSEASONS"],
+       last_season: data["LASTSEASON"], first_season: data["FIRSTSEASON"]}
+    end
+    private_class_method :streak_info
+  end
+end

data/lib/nba/team_historical_leader.rb

@@ -0,0 +1,207 @@
+require "equalizer"
+require "shale"
+
+module NBA
+  # Represents a team's all-time statistical leaders
+  #
+  # @api public
+  class TeamHistoricalLeader < Shale::Mapper
+    include Equalizer.new(:team_id)
+
+    # @!attribute [rw] team_id
+    #   Returns the team ID
+    #   @api public
+    #   @example
+    #     leader.team_id #=> 1610612744
+    #   @return [Integer, nil] the team ID
+    attribute :team_id, Shale::Type::Integer
+
+    # @!attribute [rw] season_year
+    #   Returns the season year
+    #   @api public
+    #   @example
+    #     leader.season_year #=> 2024
+    #   @return [Integer, nil] the season year
+    attribute :season_year, Shale::Type::Integer
+
+    # @!attribute [rw] pts
+    #   Returns the all-time points total
+    #   @api public
+    #   @example
+    #     leader.pts #=> 25000
+    #   @return [Integer, nil] all-time points total
+    attribute :pts, Shale::Type::Integer
+
+    # @!attribute [rw] pts_person_id
+    #   Returns the points leader player ID
+    #   @api public
+    #   @example
+    #     leader.pts_person_id #=> 201939
+    #   @return [Integer, nil] points leader player ID
+    attribute :pts_person_id, Shale::Type::Integer
+
+    # @!attribute [rw] pts_player
+    #   Returns the points leader player name
+    #   @api public
+    #   @example
+    #     leader.pts_player #=> "Stephen Curry"
+    #   @return [String, nil] points leader player name
+    attribute :pts_player, Shale::Type::String
+
+    # @!attribute [rw] ast
+    #   Returns the all-time assists total
+    #   @api public
+    #   @example
+    #     leader.ast #=> 5000
+    #   @return [Integer, nil] all-time assists total
+    attribute :ast, Shale::Type::Integer
+
+    # @!attribute [rw] ast_person_id
+    #   Returns the assists leader player ID
+    #   @api public
+    #   @example
+    #     leader.ast_person_id #=> 201939
+    #   @return [Integer, nil] assists leader player ID
+    attribute :ast_person_id, Shale::Type::Integer
+
+    # @!attribute [rw] ast_player
+    #   Returns the assists leader player name
+    #   @api public
+    #   @example
+    #     leader.ast_player #=> "Stephen Curry"
+    #   @return [String, nil] assists leader player name
+    attribute :ast_player, Shale::Type::String
+
+    # @!attribute [rw] reb
+    #   Returns the all-time rebounds total
+    #   @api public
+    #   @example
+    #     leader.reb #=> 8000
+    #   @return [Integer, nil] all-time rebounds total
+    attribute :reb, Shale::Type::Integer
+
+    # @!attribute [rw] reb_person_id
+    #   Returns the rebounds leader player ID
+    #   @api public
+    #   @example
+    #     leader.reb_person_id #=> 201142
+    #   @return [Integer, nil] rebounds leader player ID
+    attribute :reb_person_id, Shale::Type::Integer
+
+    # @!attribute [rw] reb_player
+    #   Returns the rebounds leader player name
+    #   @api public
+    #   @example
+    #     leader.reb_player #=> "Wilt Chamberlain"
+    #   @return [String, nil] rebounds leader player name
+    attribute :reb_player, Shale::Type::String
+
+    # @!attribute [rw] blk
+    #   Returns the all-time blocks total
+    #   @api public
+    #   @example
+    #     leader.blk #=> 1500
+    #   @return [Integer, nil] all-time blocks total
+    attribute :blk, Shale::Type::Integer
+
+    # @!attribute [rw] blk_person_id
+    #   Returns the blocks leader player ID
+    #   @api public
+    #   @example
+    #     leader.blk_person_id #=> 201142
+    #   @return [Integer, nil] blocks leader player ID
+    attribute :blk_person_id, Shale::Type::Integer
+
+    # @!attribute [rw] blk_player
+    #   Returns the blocks leader player name
+    #   @api public
+    #   @example
+    #     leader.blk_player #=> "Nate Thurmond"
+    #   @return [String, nil] blocks leader player name
+    attribute :blk_player, Shale::Type::String
+
+    # @!attribute [rw] stl
+    #   Returns the all-time steals total
+    #   @api public
+    #   @example
+    #     leader.stl #=> 1200
+    #   @return [Integer, nil] all-time steals total
+    attribute :stl, Shale::Type::Integer
+
+    # @!attribute [rw] stl_person_id
+    #   Returns the steals leader player ID
+    #   @api public
+    #   @example
+    #     leader.stl_person_id #=> 201939
+    #   @return [Integer, nil] steals leader player ID
+    attribute :stl_person_id, Shale::Type::Integer
+
+    # @!attribute [rw] stl_player
+    #   Returns the steals leader player name
+    #   @api public
+    #   @example
+    #     leader.stl_player #=> "Chris Mullin"
+    #   @return [String, nil] steals leader player name
+    attribute :stl_player, Shale::Type::String
+
+    # Returns the team for this leader record
+    #
+    # @api public
+    # @example
+    #   leader.team #=> #<NBA::Team ...>
+    # @return [Team, nil] the team
+    def team
+      Teams.find(team_id)
+    end
+
+    # Returns the points leader player
+    #
+    # @api public
+    # @example
+    #   leader.pts_leader #=> #<NBA::Player ...>
+    # @return [Player, nil] the points leader
+    def pts_leader
+      Players.find(pts_person_id)
+    end
+
+    # Returns the assists leader player
+    #
+    # @api public
+    # @example
+    #   leader.ast_leader #=> #<NBA::Player ...>
+    # @return [Player, nil] the assists leader
+    def ast_leader
+      Players.find(ast_person_id)
+    end
+
+    # Returns the rebounds leader player
+    #
+    # @api public
+    # @example
+    #   leader.reb_leader #=> #<NBA::Player ...>
+    # @return [Player, nil] the rebounds leader
+    def reb_leader
+      Players.find(reb_person_id)
+    end
+
+    # Returns the blocks leader player
+    #
+    # @api public
+    # @example
+    #   leader.blk_leader #=> #<NBA::Player ...>
+    # @return [Player, nil] the blocks leader
+    def blk_leader
+      Players.find(blk_person_id)
+    end
+
+    # Returns the steals leader player
+    #
+    # @api public
+    # @example
+    #   leader.stl_leader #=> #<NBA::Player ...>
+    # @return [Player, nil] the steals leader
+    def stl_leader
+      Players.find(stl_person_id)
+    end
+  end
+end

data/lib/nba/team_historical_leaders.rb

@@ -0,0 +1,98 @@
+require_relative "client"
+require_relative "collection"
+require_relative "response_parser"
+require_relative "utils"
+
+module NBA
+  # Provides methods to retrieve team historical career leaders
+  #
+  # @api public
+  module TeamHistoricalLeaders
+    # Result set name in API response
+    # @return [String] the result set name
+    RESULT_SET_NAME = "CareerLeadersByTeam".freeze
+
+    # Retrieves historical leaders for a team
+    #
+    # @api public
+    # @example
+    #   leaders = NBA::TeamHistoricalLeaders.find(team: 1610612744)
+    #   leaders.pts_player #=> "Stephen Curry"
+    # @param team [Integer, Team] the team or team ID
+    # @param season [Integer] the season year (defaults to current season)
+    # @param client [Client] the API client to use
+    # @return [TeamHistoricalLeader, nil] the team historical leaders
+    def self.find(team:, season: Utils.current_season, client: CLIENT)
+      id = Utils.extract_id(team)
+      return unless id
+
+      path = build_path(id, season)
+      ResponseParser.parse_single(client.get(path), result_set: RESULT_SET_NAME) { |data| build_leader(data) }
+    end
+
+    # Builds the API path
+    # @api private
+    # @return [String]
+    def self.build_path(team_id, season)
+      "teamhistoricalleaders?TeamID=#{team_id}&LeagueID=00&SeasonID=#{Utils.format_season_id(season)}"
+    end
+    private_class_method :build_path
+
+    # Builds a TeamHistoricalLeader from API data
+    # @api private
+    # @return [TeamHistoricalLeader]
+    def self.build_leader(data)
+      TeamHistoricalLeader.new(**identity_info(data), **pts_info(data), **ast_info(data), **reb_info(data),
+        **blk_info(data), **stl_info(data))
+    end
+    private_class_method :build_leader
+
+    # Extracts identity fields
+    # @api private
+    # @return [Hash]
+    def self.identity_info(data)
+      {team_id: data["TEAM_ID"], season_year: data["SEASON_YEAR"]}
+    end
+    private_class_method :identity_info
+
+    # Extracts points leader fields
+    # @api private
+    # @return [Hash]
+    def self.pts_info(data)
+      {pts: data["PTS"], pts_person_id: data["PTS_PERSON_ID"], pts_player: data["PTS_PLAYER"]}
+    end
+    private_class_method :pts_info
+
+    # Extracts assists leader fields
+    # @api private
+    # @return [Hash]
+    def self.ast_info(data)
+      {ast: data["AST"], ast_person_id: data["AST_PERSON_ID"], ast_player: data["AST_PLAYER"]}
+    end
+    private_class_method :ast_info
+
+    # Extracts rebounds leader fields
+    # @api private
+    # @return [Hash]
+    def self.reb_info(data)
+      {reb: data["REB"], reb_person_id: data["REB_PERSON_ID"], reb_player: data["REB_PLAYER"]}
+    end
+    private_class_method :reb_info
+
+    # Extracts blocks leader fields
+    # @api private
+    # @return [Hash]
+    def self.blk_info(data)
+      {blk: data["BLK"], blk_person_id: data["BLK_PERSON_ID"], blk_player: data["BLK_PLAYER"]}
+    end
+    private_class_method :blk_info
+
+    # Extracts steals leader fields
+    # @api private
+    # @return [Hash]
+    def self.stl_info(data)
+      {stl: data["STL"], stl_person_id: data["STL_PERSON_ID"], stl_player: data["STL_PLAYER"]}
+    end
+    private_class_method :stl_info
+  end
+end

data/lib/nba/team_historical_record.rb

@@ -0,0 +1,139 @@
+require "equalizer"
+require "shale"
+
+module NBA
+  # Represents a team's historical record
+  class TeamHistoricalRecord < Shale::Mapper
+    include Equalizer.new(:team_id, :season_id)
+
+    # @!attribute [rw] team_id
+    #   Returns the team ID
+    #   @api public
+    #   @example
+    #     record.team_id #=> 1610612744
+    #   @return [Integer] the team ID
+    attribute :team_id, Shale::Type::Integer
+
+    # @!attribute [rw] city
+    #   Returns the team city
+    #   @api public
+    #   @example
+    #     record.city #=> "Golden State"
+    #   @return [String] the city
+    attribute :city, Shale::Type::String
+
+    # @!attribute [rw] nickname
+    #   Returns the team nickname
+    #   @api public
+    #   @example
+    #     record.nickname #=> "Warriors"
+    #   @return [String] the nickname
+    attribute :nickname, Shale::Type::String
+
+    # @!attribute [rw] season_id
+    #   Returns the season ID
+    #   @api public
+    #   @example
+    #     record.season_id #=> "22024"
+    #   @return [String] the season ID
+    attribute :season_id, Shale::Type::String
+
+    # @!attribute [rw] year
+    #   Returns the year
+    #   @api public
+    #   @example
+    #     record.year #=> 2024
+    #   @return [Integer] the year
+    attribute :year, Shale::Type::Integer
+
+    # @!attribute [rw] wins
+    #   Returns the number of wins
+    #   @api public
+    #   @example
+    #     record.wins #=> 46
+    #   @return [Integer] the wins
+    attribute :wins, Shale::Type::Integer
+
+    # @!attribute [rw] losses
+    #   Returns the number of losses
+    #   @api public
+    #   @example
+    #     record.losses #=> 36
+    #   @return [Integer] the losses
+    attribute :losses, Shale::Type::Integer
+
+    # @!attribute [rw] win_pct
+    #   Returns the win percentage
+    #   @api public
+    #   @example
+    #     record.win_pct #=> 0.561
+    #   @return [Float] the win percentage
+    attribute :win_pct, Shale::Type::Float
+
+    # @!attribute [rw] conf_rank
+    #   Returns the conference rank
+    #   @api public
+    #   @example
+    #     record.conf_rank #=> 10
+    #   @return [Integer] the conference rank
+    attribute :conf_rank, Shale::Type::Integer
+
+    # @!attribute [rw] div_rank
+    #   Returns the division rank
+    #   @api public
+    #   @example
+    #     record.div_rank #=> 3
+    #   @return [Integer] the division rank
+    attribute :div_rank, Shale::Type::Integer
+
+    # @!attribute [rw] po_wins
+    #   Returns playoff wins
+    #   @api public
+    #   @example
+    #     record.po_wins #=> 0
+    #   @return [Integer] the playoff wins
+    attribute :po_wins, Shale::Type::Integer
+
+    # @!attribute [rw] po_losses
+    #   Returns playoff losses
+    #   @api public
+    #   @example
+    #     record.po_losses #=> 0
+    #   @return [Integer] the playoff losses
+    attribute :po_losses, Shale::Type::Integer
+
+    # @!attribute [rw] conf_count
+    #   Returns conference titles
+    #   @api public
+    #   @example
+    #     record.conf_count #=> 0
+    #   @return [Integer] the conference titles
+    attribute :conf_count, Shale::Type::Integer
+
+    # @!attribute [rw] div_count
+    #   Returns division titles
+    #   @api public
+    #   @example
+    #     record.div_count #=> 0
+    #   @return [Integer] the division titles
+    attribute :div_count, Shale::Type::Integer
+
+    # @!attribute [rw] nba_finals_appearance
+    #   Returns NBA Finals appearances
+    #   @api public
+    #   @example
+    #     record.nba_finals_appearance #=> "N/A"
+    #   @return [String] the Finals appearances
+    attribute :nba_finals_appearance, Shale::Type::String
+
+    # Returns the team object
+    #
+    # @api public
+    # @example
+    #   record.team #=> #<NBA::Team>
+    # @return [Team, nil] the team object
+    def team
+      Teams.find(team_id)
+    end
+  end
+end