nba 0.1.1 → 0.2.0

data/lib/nba/player_fantasy_profile_bar_graph.rb

@@ -0,0 +1,147 @@
+require "json"
+require_relative "client"
+require_relative "collection"
+require_relative "fantasy_profile_stat"
+require_relative "utils"
+
+module NBA
+  # Provides methods to retrieve player fantasy profile bar graph statistics
+  #
+  # @api public
+  module PlayerFantasyProfileBarGraph
+    # Result set name for last five games average
+    # @return [String] the result set name
+    LAST_FIVE_GAMES_AVG = "LastFiveGamesAvg".freeze
+
+    # Result set name for season average
+    # @return [String] the result set name
+    SEASON_AVG = "SeasonAvg".freeze
+
+    # Retrieves last five games average statistics for a player
+    #
+    # @api public
+    # @example
+    #   stats = NBA::PlayerFantasyProfileBarGraph.last_five_games_avg(player: 201939)
+    #   stats.first.fan_duel_pts #=> 45.2
+    # @param player [Integer, Player] the player ID or Player object
+    # @param season [Integer] the season year
+    # @param season_type [String] the season type
+    # @param client [Client] the API client to use
+    # @return [Collection] a collection of fantasy profile statistics
+    def self.last_five_games_avg(player:, season: Utils.current_season, season_type: "Regular Season",
+      client: CLIENT)
+      path = build_path(player, season, season_type)
+      response = client.get(path)
+      parse_response(response, LAST_FIVE_GAMES_AVG)
+    end
+
+    # Retrieves season average statistics for a player
+    #
+    # @api public
+    # @example
+    #   stats = NBA::PlayerFantasyProfileBarGraph.season_avg(player: 201939)
+    #   stats.first.nba_fantasy_pts #=> 52.1
+    # @param player [Integer, Player] the player ID or Player object
+    # @param season [Integer] the season year
+    # @param season_type [String] the season type
+    # @param client [Client] the API client to use
+    # @return [Collection] a collection of fantasy profile statistics
+    def self.season_avg(player:, season: Utils.current_season, season_type: "Regular Season",
+      client: CLIENT)
+      path = build_path(player, season, season_type)
+      response = client.get(path)
+      parse_response(response, SEASON_AVG)
+    end
+
+    # Builds the API path
+    #
+    # @api private
+    # @return [String] the request path
+    def self.build_path(player, season, season_type)
+      player_id = Utils.extract_id(player)
+      season_str = Utils.format_season(season)
+      "playerfantasyprofilebargraph?PlayerID=#{player_id}&Season=#{season_str}" \
+        "&SeasonType=#{season_type}&LeagueID=00"
+    end
+    private_class_method :build_path
+
+    # Parses the API response into fantasy profile stat objects
+    #
+    # @api private
+    # @return [Collection] collection of fantasy profile stats
+    def self.parse_response(response, result_set_name)
+      return Collection.new if response.nil? || response.empty?
+
+      data = JSON.parse(response)
+      result_set = find_result_set(data, result_set_name)
+      build_collection(result_set)
+    end
+    private_class_method :parse_response
+
+    # Finds a result set by name
+    #
+    # @api private
+    # @return [Hash, nil] the result set hash or nil if not found
+    def self.find_result_set(data, result_set_name)
+      result_sets = data["resultSets"]
+      return unless result_sets
+
+      result_sets.find { |rs| rs["name"].eql?(result_set_name) }
+    end
+    private_class_method :find_result_set
+
+    # Builds a collection from a result set
+    #
+    # @api private
+    # @return [Collection] the stats collection
+    def self.build_collection(result_set)
+      return Collection.new unless result_set
+
+      headers = result_set["headers"]
+      rows = result_set["rowSet"]
+      return Collection.new unless headers && rows
+
+      Collection.new(rows.map { |row| build_fantasy_profile_stat(headers.zip(row).to_h) })
+    end
+    private_class_method :build_collection
+
+    # Builds a fantasy profile stat from API data
+    #
+    # @api private
+    # @return [FantasyProfileStat] the fantasy profile stat object
+    def self.build_fantasy_profile_stat(data)
+      FantasyProfileStat.new(**identity_info(data), **fantasy_info(data), **stat_info(data))
+    end
+    private_class_method :build_fantasy_profile_stat
+
+    # Extracts identity information from data
+    #
+    # @api private
+    # @return [Hash] the identity information hash
+    def self.identity_info(data)
+      {player_id: data["PLAYER_ID"], player_name: data["PLAYER_NAME"],
+       team_id: data["TEAM_ID"], team_abbreviation: data["TEAM_ABBREVIATION"]}
+    end
+    private_class_method :identity_info
+
+    # Extracts fantasy information from data
+    #
+    # @api private
+    # @return [Hash] the fantasy information hash
+    def self.fantasy_info(data)
+      {fan_duel_pts: data["FAN_DUEL_PTS"], nba_fantasy_pts: data["NBA_FANTASY_PTS"]}
+    end
+    private_class_method :fantasy_info
+
+    # Extracts stat information from data
+    #
+    # @api private
+    # @return [Hash] the stat information hash
+    def self.stat_info(data)
+      {pts: data["PTS"], reb: data["REB"], ast: data["AST"],
+       fg3m: data["FG3M"], fg_pct: data["FG_PCT"], ft_pct: data["FT_PCT"],
+       stl: data["STL"], blk: data["BLK"], tov: data["TOV"]}
+    end
+    private_class_method :stat_info
+  end
+end

data/lib/nba/player_game_log.rb

@@ -0,0 +1,72 @@
+require_relative "client"
+require_relative "response_parser"
+require_relative "game_log"
+require_relative "utils"
+
+module NBA
+  # Provides methods to retrieve player game logs
+  module PlayerGameLog
+    # Regular season type
+    # @return [String] the season type
+    REGULAR_SEASON = "Regular Season".freeze
+
+    # Playoffs season type
+    # @return [String] the season type
+    PLAYOFFS = "Playoffs".freeze
+
+    # Retrieves game logs for a player
+    #
+    # @api public
+    # @example
+    #   logs = NBA::PlayerGameLog.find(player: 201939)
+    #   logs.each { |log| puts "#{log.game_date}: #{log.pts} points" }
+    # @param player [Integer, Player] the player ID or Player object
+    # @param season [Integer] the season year (defaults to current season)
+    # @param season_type [String] the season type (Regular Season, Playoffs)
+    # @param client [Client] the API client to use
+    # @return [Collection] a collection of game logs
+    def self.find(player:, season: Utils.current_season, season_type: REGULAR_SEASON, client: CLIENT)
+      path = "playergamelog?PlayerID=#{Utils.extract_id(player)}&Season=#{Utils.format_season(season)}" \
+             "&SeasonType=#{season_type}"
+      ResponseParser.parse(client.get(path)) { |data| build_game_log(data) }
+    end
+
+    # Builds a game log from API data
+    # @api private
+    # @return [GameLog]
+    def self.build_game_log(data)
+      GameLog.new(**game_info(data), **shooting_stats(data), **counting_stats(data))
+    end
+    private_class_method :build_game_log
+
+    # Extracts game information from data
+    # @api private
+    # @return [Hash]
+    def self.game_info(data)
+      {season_id: data["SEASON_ID"], player_id: data["Player_ID"], game_id: data["Game_ID"],
+       game_date: data["GAME_DATE"], matchup: data["MATCHUP"], wl: data["WL"], min: data["MIN"]}
+    end
+    private_class_method :game_info
+
+    # Extracts shooting statistics from data
+    # @api private
+    # @return [Hash]
+    def self.shooting_stats(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_stats
+
+    # Extracts counting statistics from data
+    # @api private
+    # @return [Hash]
+    def self.counting_stats(data)
+      {oreb: data["OREB"], dreb: data["DREB"], reb: data["REB"],
+       ast: data["AST"], stl: data["STL"], blk: data["BLK"],
+       tov: data["TOV"], pf: data["PF"], pts: data["PTS"],
+       plus_minus: data["PLUS_MINUS"]}
+    end
+    private_class_method :counting_stats
+  end
+end

data/lib/nba/player_game_logs.rb

@@ -0,0 +1,117 @@
+require_relative "client"
+require_relative "response_parser"
+require_relative "game_log"
+require_relative "utils"
+
+module NBA
+  # Provides methods to retrieve player game logs in batch
+  #
+  # @api public
+  module PlayerGameLogs
+    # Regular season type
+    # @return [String] the season type
+    REGULAR_SEASON = "Regular Season".freeze
+
+    # Playoffs season type
+    # @return [String] the season type
+    PLAYOFFS = "Playoffs".freeze
+
+    # Per game mode
+    # @return [String] the per mode
+    PER_GAME = "PerGame".freeze
+
+    # Totals mode
+    # @return [String] the per mode
+    TOTALS = "Totals".freeze
+
+    # Result set name
+    # @return [String] the result set name
+    RESULT_SET_NAME = "PlayerGameLogs".freeze
+
+    # Retrieves game logs for all players matching the criteria
+    #
+    # @api public
+    # @example
+    #   logs = NBA::PlayerGameLogs.all(season: 2024)
+    #   logs.each { |log| puts "#{log.game_date}: #{log.player_name} - #{log.pts} pts" }
+    # @param season [Integer] the season year (defaults to current season)
+    # @param season_type [String] the season type (Regular Season, Playoffs)
+    # @param player [Integer, Player, nil] filter by player ID or Player object
+    # @param team [Integer, Team, nil] filter by team ID or Team object
+    # @param per_mode [String] the per mode (PerGame, Totals)
+    # @param client [Client] the API client to use
+    # @return [Collection] a collection of game logs
+    def self.all(season: Utils.current_season, season_type: REGULAR_SEASON, player: nil, team: nil,
+      per_mode: PER_GAME, client: CLIENT)
+      path = build_path(season, season_type, player, team, per_mode)
+      ResponseParser.parse(client.get(path), result_set: RESULT_SET_NAME) { |data| build_game_log(data) }
+    end
+
+    # Builds the API path
+    #
+    # @api private
+    # @return [String] the API path
+    def self.build_path(season, season_type, player, team, per_mode)
+      path = "playergamelogs?LeagueID=00&Season=#{Utils.format_season(season)}" \
+             "&SeasonType=#{season_type}&PerModeSimple=#{per_mode}"
+      path += "&PlayerID=#{Utils.extract_id(player)}" if player
+      path += "&TeamID=#{Utils.extract_id(team)}" if team
+      path
+    end
+    private_class_method :build_path
+
+    # Builds a game log from API data
+    #
+    # @api private
+    # @return [GameLog]
+    def self.build_game_log(data)
+      GameLog.new(**game_info(data), **player_info(data), **shooting_stats(data), **counting_stats(data))
+    end
+    private_class_method :build_game_log
+
+    # Extracts game information from data
+    #
+    # @api private
+    # @return [Hash]
+    def self.game_info(data)
+      {season_id: data["SEASON_YEAR"], game_id: data["GAME_ID"],
+       game_date: data["GAME_DATE"], matchup: data["MATCHUP"],
+       wl: data["WL"], min: data["MIN"]}
+    end
+    private_class_method :game_info
+
+    # Extracts player information from data
+    #
+    # @api private
+    # @return [Hash]
+    def self.player_info(data)
+      {player_id: data["PLAYER_ID"], player_name: data["PLAYER_NAME"],
+       team_id: data["TEAM_ID"], team_abbreviation: data["TEAM_ABBREVIATION"],
+       team_name: data["TEAM_NAME"]}
+    end
+    private_class_method :player_info
+
+    # Extracts shooting statistics from data
+    #
+    # @api private
+    # @return [Hash]
+    def self.shooting_stats(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_stats
+
+    # Extracts counting statistics from data
+    #
+    # @api private
+    # @return [Hash]
+    def self.counting_stats(data)
+      {oreb: data["OREB"], dreb: data["DREB"], reb: data["REB"],
+       ast: data["AST"], stl: data["STL"], blk: data["BLK"],
+       tov: data["TOV"], pf: data["PF"], pts: data["PTS"],
+       plus_minus: data["PLUS_MINUS"]}
+    end
+    private_class_method :counting_stats
+  end
+end

data/lib/nba/player_game_streak_finder.rb

@@ -0,0 +1,108 @@
+require "json"
+require_relative "client"
+require_relative "response_parser"
+require_relative "game_streak"
+require_relative "utils"
+
+module NBA
+  # Provides methods to find player game streaks
+  #
+  # @api public
+  module PlayerGameStreakFinder
+    # Result set name for streak finder results
+    # @return [String] the result set name
+    RESULT_SET_NAME = "PlayerGameStreakFinderResults".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}.freeze
+
+    # Finds player game streaks matching the specified criteria
+    #
+    # @api public
+    # @example Find active 10+ point streaks
+    #   NBA::PlayerGameStreakFinder.find(gt_pts: 10, active_streaks_only: true)
+    # @param season [String, nil] the season to search (e.g., "2024-25")
+    # @param player [Integer, Player, nil] filter by player ID or Player object
+    # @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 client [Client] the API client to use
+    # @return [Collection] collection of GameStreak objects
+    def self.find(season: nil, player: 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, 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}
+      path = build_path(season, player, 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, player, team, active_only, filters)
+      params = base_params(season, player, team, active_only)
+      add_stat_filters(params, filters)
+      "playergamestreakfinder?#{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, player, team, active_only)
+      params = {LeagueID: "00", MinGames: 1}
+      params[:SeasonNullable] = season if season
+      params[:PlayerIDNullable] = Utils.extract_id(player) if player
+      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 GameStreak from API data
+    #
+    # @api private
+    # @return [GameStreak] the game streak object
+    def self.build_streak(data)
+      GameStreak.new(**player_info(data), **streak_info(data))
+    end
+    private_class_method :build_streak
+
+    # Extracts player information from data
+    #
+    # @api private
+    # @return [Hash] the player information hash
+    def self.player_info(data)
+      {player_name: data["PLAYER_NAME_LAST_FIRST"], player_id: data["PLAYER_ID"]}
+    end
+    private_class_method :player_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/player_index.rb

@@ -0,0 +1,135 @@
+require_relative "client"
+require_relative "response_parser"
+require_relative "utils"
+
+require_relative "player_index_entry"
+
+module NBA
+  # Provides methods to search and retrieve the player index
+  #
+  # @api public
+  module PlayerIndex
+    # Result set name for player index
+    # @return [String] the result set name
+    RESULT_SET_NAME = "PlayerIndex".freeze
+
+    # Historical flag: include historical players
+    # @return [Integer] the flag value
+    HISTORICAL = 1
+
+    # Historical flag: current players only
+    # @return [Integer] the flag value
+    CURRENT = 0
+
+    # Retrieves the player index with optional filters
+    #
+    # @api public
+    # @example
+    #   # Get all current players
+    #   players = NBA::PlayerIndex.all
+    #   players.size #=> 450
+    #
+    # @example
+    #   # Get players from a specific college
+    #   duke_players = NBA::PlayerIndex.all(college: "Duke")
+    #
+    # @example
+    #   # Get players from a specific country
+    #   canadian = NBA::PlayerIndex.all(country: "Canada")
+    #
+    # @param season [Integer] the season year
+    # @param historical [Integer] whether to include historical players (0 or 1)
+    # @param active [String, nil] filter by active status ("1" for active)
+    # @param all_star [String, nil] filter by all-star status
+    # @param college [String, nil] filter by college
+    # @param country [String, nil] filter by country
+    # @param draft_pick [String, nil] filter by draft pick
+    # @param draft_year [String, nil] filter by draft year
+    # @param height [String, nil] filter by height
+    # @param team [Integer, Team, nil] filter by team
+    # @param weight [String, nil] filter by weight
+    # @param client [Client] the API client to use
+    # @return [Collection] a collection of player index entries
+    def self.all(season: Utils.current_season, historical: CURRENT, active: nil, all_star: nil,
+      college: nil, country: nil, draft_pick: nil, draft_year: nil, height: nil,
+      team: nil, weight: nil, client: CLIENT)
+      params = {season: season, historical: historical, active: active, all_star: all_star,
+                college: college, country: country, draft_pick: draft_pick, draft_year: draft_year,
+                height: height, team: team, weight: weight}
+      path = build_path(params)
+      ResponseParser.parse(client.get(path), result_set: RESULT_SET_NAME) do |data|
+        build_entry(data)
+      end
+    end
+
+    # Builds the API request path
+    # @api private
+    # @return [String] the request path
+    def self.build_path(params)
+      season_str = Utils.format_season(params.fetch(:season))
+      team_id = Utils.extract_id(params.fetch(:team))
+      "playerindex?LeagueID=00&Season=#{season_str}&Historical=#{params[:historical]}" \
+        "&Active=#{params[:active]}&AllStar=#{params[:all_star]}&College=#{params[:college]}" \
+        "&Country=#{params[:country]}&DraftPick=#{params[:draft_pick]}&DraftYear=#{params[:draft_year]}" \
+        "&Height=#{params[:height]}&TeamID=#{team_id}&Weight=#{params[:weight]}"
+    end
+    private_class_method :build_path
+
+    # Builds a player index entry from API data
+    # @api private
+    # @return [PlayerIndexEntry]
+    def self.build_entry(data)
+      PlayerIndexEntry.new(**identity_info(data), **team_info(data), **physical_info(data),
+        **draft_info(data), **stats_info(data))
+    end
+    private_class_method :build_entry
+
+    # Extracts identity information from data
+    # @api private
+    # @return [Hash]
+    def self.identity_info(data)
+      {id: data["PERSON_ID"], last_name: data["PLAYER_LAST_NAME"],
+       first_name: data["PLAYER_FIRST_NAME"], slug: data["PLAYER_SLUG"]}
+    end
+    private_class_method :identity_info
+
+    # Extracts team information from data
+    # @api private
+    # @return [Hash]
+    def self.team_info(data)
+      {team_id: data["TEAM_ID"], team_slug: data["TEAM_SLUG"],
+       team_city: data["TEAM_CITY"], team_name: data["TEAM_NAME"],
+       team_abbreviation: data["TEAM_ABBREVIATION"]}
+    end
+    private_class_method :team_info
+
+    # Extracts physical information from data
+    # @api private
+    # @return [Hash]
+    def self.physical_info(data)
+      {jersey_number: data["JERSEY_NUMBER"], position: data["POSITION"],
+       height: data["HEIGHT"], weight: data["WEIGHT"],
+       college: data["COLLEGE"], country: data["COUNTRY"]}
+    end
+    private_class_method :physical_info
+
+    # Extracts draft information from data
+    # @api private
+    # @return [Hash]
+    def self.draft_info(data)
+      {draft_year: data["DRAFT_YEAR"], draft_round: data["DRAFT_ROUND"],
+       draft_number: data["DRAFT_NUMBER"], roster_status: data["ROSTER_STATUS"]}
+    end
+    private_class_method :draft_info
+
+    # Extracts stats information from data
+    # @api private
+    # @return [Hash]
+    def self.stats_info(data)
+      {pts: data["PTS"], reb: data["REB"], ast: data["AST"],
+       stats_timeframe: data["STATS_TIMEFRAME"], from_year: data["FROM_YEAR"],
+       to_year: data["TO_YEAR"], is_defunct: data["IS_DEFUNCT"]}
+    end
+    private_class_method :stats_info
+  end
+end