nba 0.1.1 → 0.2.0

data/lib/nba/scoreboard.rb

@@ -0,0 +1,183 @@
+require "date"
+require "json"
+require_relative "client"
+require_relative "collection"
+require_relative "game"
+require_relative "team"
+require_relative "teams"
+
+module NBA
+  # Provides methods to retrieve NBA scoreboard data
+  module Scoreboard
+    # Retrieves games for a specific date
+    #
+    # @api public
+    # @example
+    #   games = NBA::Scoreboard.games(date: Date.today)
+    #   games.each { |game| puts "#{game.away_team.name} @ #{game.home_team.name}" }
+    # @param date [Date] the date to retrieve games for (defaults to today)
+    # @param client [Client] the API client to use
+    # @return [Collection] a collection of games
+    def self.games(date: Date.today, client: CLIENT)
+      path = "scoreboardv2?GameDate=#{date}&LeagueID=00&DayOffset=0"
+      response = client.get(path)
+      parse_scoreboard_response(response)
+    end
+
+    # Parses the scoreboard API response
+    #
+    # @api private
+    # @param response [String] the JSON response body
+    # @return [Collection] a collection of games
+    def self.parse_scoreboard_response(response)
+      return Collection.new unless response
+
+      data = JSON.parse(response)
+      game_header = find_result_set(data, "GameHeader")
+      line_score = find_result_set(data, "LineScore")
+      return Collection.new unless game_header && line_score
+
+      games = build_games(game_header, line_score)
+      Collection.new(games)
+    end
+    private_class_method :parse_scoreboard_response
+
+    # Finds a result set by name
+    #
+    # @api private
+    # @param data [Hash] the parsed JSON data
+    # @param name [String] the result set name to find
+    # @return [Hash, nil] the result set or nil
+    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 games from result sets
+    #
+    # @api private
+    # @param game_header [Hash] the GameHeader result set
+    # @param line_score [Hash] the LineScore result set
+    # @return [Array<Game>] the built games
+    def self.build_games(game_header, line_score)
+      header_data = parse_result_set(game_header)
+      score_data = parse_result_set(line_score)
+
+      header_data.uniq { |info| info.fetch("GAME_ID") }.map do |game_info|
+        game_id = game_info["GAME_ID"]
+        team_scores = score_data.select { |s| s["GAME_ID"].eql?(game_id) }
+        build_game(game_info, team_scores)
+      end
+    end
+    private_class_method :build_games
+
+    # Parses a result set into an array of hashes
+    #
+    # @api private
+    # @param result_set [Hash] the result set
+    # @return [Array<Hash>] array of data hashes
+    def self.parse_result_set(result_set)
+      headers = result_set["headers"]
+      rows = result_set["rowSet"]
+      return [] unless headers && rows
+
+      rows.map { |row| headers.zip(row).to_h }
+    end
+    private_class_method :parse_result_set
+
+    # Builds a game from header and score data
+    #
+    # @api private
+    # @param game_info [Hash] the game header info
+    # @param team_scores [Array<Hash>] the team score data
+    # @return [Game] the built game
+    def self.build_game(game_info, team_scores)
+      Game.new(**game_attributes(game_info, team_scores))
+    end
+    private_class_method :build_game
+
+    # Extracts game attributes from game info and scores
+    #
+    # @api private
+    # @param info [Hash] the game header info
+    # @param scores [Array<Hash>] the team score data
+    # @return [Hash] the game attributes
+    def self.game_attributes(info, scores)
+      {
+        id: info["GAME_ID"], date: info["GAME_DATE_EST"],
+        status: game_status(info),
+        home_team: find_team(info["HOME_TEAM_ID"]),
+        away_team: find_team(info["VISITOR_TEAM_ID"]),
+        home_score: find_score(scores, info["HOME_TEAM_ID"]),
+        away_score: find_score(scores, info["VISITOR_TEAM_ID"]),
+        arena: info["ARENA_NAME"]
+      }
+    end
+    private_class_method :game_attributes
+
+    # Finds the score for a team
+    #
+    # @api private
+    # @param scores [Array<Hash>] the team score data
+    # @param team_id [Integer] the team ID
+    # @return [Integer, nil] the score
+    def self.find_score(scores, team_id)
+      score_data = scores.find { |s| s["TEAM_ID"].eql?(team_id) }
+      extract_score(score_data)
+    end
+    private_class_method :find_score
+
+    # Extracts score from score data
+    #
+    # @api private
+    # @param score_data [Hash, nil] the score data
+    # @return [Integer, nil] the score
+    def self.extract_score(score_data)
+      return unless score_data
+
+      score_data["PTS"]
+    end
+    private_class_method :extract_score
+
+    # Converts game status info to string
+    #
+    # @api private
+    # @param info [Hash] the game info hash
+    # @return [String] the status string
+    def self.game_status(info)
+      status_text = info["GAME_STATUS_TEXT"]
+      return status_text if status_text
+
+      status_id_to_text(info["GAME_STATUS_ID"])
+    end
+    private_class_method :game_status
+
+    # Converts game status ID to string
+    #
+    # @api private
+    # @param status_id [Integer] the status ID
+    # @return [String] the status string
+    def self.status_id_to_text(status_id)
+      case status_id
+      when 1 then "Scheduled"
+      when 2 then "In Progress"
+      when 3 then "Final"
+      else "Unknown"
+      end
+    end
+    private_class_method :status_id_to_text
+
+    # Finds a team by ID
+    #
+    # @api private
+    # @param team_id [Integer] the team ID
+    # @return [Team, nil] the team or nil
+    def self.find_team(team_id)
+      Teams.find(team_id)
+    end
+    private_class_method :find_team
+  end
+end

data/lib/nba/scoreboard_v3.rb

@@ -0,0 +1,104 @@
+require "date"
+require "json"
+require_relative "client"
+require_relative "collection"
+require_relative "game"
+require_relative "league"
+require_relative "team"
+require_relative "teams"
+
+module NBA
+  # Provides methods to retrieve NBA scoreboard data using the V3 endpoint
+  module ScoreboardV3
+    # Retrieves games for a specific date
+    #
+    # @api public
+    # @example
+    #   games = NBA::ScoreboardV3.games(date: Date.today)
+    #   games.each { |game| puts "#{game.away_team.name} @ #{game.home_team.name}" }
+    # @param date [Date] the date to retrieve games for (defaults to today)
+    # @param league [League, String] the league ID (defaults to NBA)
+    # @param client [Client] the API client to use
+    # @return [Collection] a collection of games
+    def self.games(date: Date.today, league: League::NBA, client: CLIENT)
+      league_id = Utils.extract_league_id(league)
+      path = "scoreboardv3?GameDate=#{date}&LeagueID=#{league_id}"
+      response = client.get(path)
+      parse_scoreboard_response(response)
+    end
+
+    # Parses the scoreboard API response
+    #
+    # @api private
+    # @param response [String] the JSON response body
+    # @return [Collection] a collection of games
+    def self.parse_scoreboard_response(response)
+      return Collection.new if response.nil? || response.empty?
+
+      data = JSON.parse(response)
+      scoreboard = data["scoreboard"]
+      return Collection.new unless scoreboard
+
+      game_data = scoreboard["games"]
+      return Collection.new unless game_data
+
+      games = game_data.map { |game_info| build_game(game_info) }
+      Collection.new(games)
+    end
+    private_class_method :parse_scoreboard_response
+
+    # Builds a game from game data
+    #
+    # @api private
+    # @param game_info [Hash] the game info
+    # @return [Game] the built game
+    def self.build_game(game_info)
+      Game.new(**game_attributes(game_info))
+    end
+    private_class_method :build_game
+
+    # Extracts game attributes from game info
+    #
+    # @api private
+    # @param info [Hash] the game info
+    # @return [Hash] the game attributes
+    def self.game_attributes(info)
+      {
+        id: info["gameId"],
+        date: info["gameTimeUTC"],
+        status: game_status(info["gameStatus"]),
+        home_team: find_team(info.dig("homeTeam", "teamId")),
+        away_team: find_team(info.dig("awayTeam", "teamId")),
+        home_score: info.dig("homeTeam", "score"),
+        away_score: info.dig("awayTeam", "score"),
+        arena: info["arenaName"]
+      }
+    end
+    private_class_method :game_attributes
+
+    # Converts game status ID to string
+    #
+    # @api private
+    # @param status_id [Integer] the status ID
+    # @return [String] the status string
+    def self.game_status(status_id)
+      case status_id
+      when 1 then "Scheduled"
+      when 2 then "In Progress"
+      when 3 then "Final"
+      else "Unknown"
+      end
+    end
+    private_class_method :game_status
+
+    # Finds a team by ID
+    #
+    # @api private
+    # @param team_id [Integer] the team ID
+    # @return [Team, nil] the team or nil
+    def self.find_team(team_id)
+      Teams.find(team_id)
+    end
+    private_class_method :find_team
+  end
+end

data/lib/nba/shot.rb

@@ -0,0 +1,208 @@
+module NBA
+  # Represents a single shot attempt
+  class Shot < Shale::Mapper
+    include Equalizer.new(:game_id, :game_event_id)
+
+    # @!attribute [rw] game_id
+    #   Returns the game ID
+    #   @api public
+    #   @example
+    #     shot.game_id #=> "0022400001"
+    #   @return [String] the game ID
+    attribute :game_id, Shale::Type::String
+
+    # @!attribute [rw] game_event_id
+    #   Returns the game event ID
+    #   @api public
+    #   @example
+    #     shot.game_event_id #=> 10
+    #   @return [Integer] the event ID
+    attribute :game_event_id, Shale::Type::Integer
+
+    # @!attribute [rw] player_id
+    #   Returns the player ID
+    #   @api public
+    #   @example
+    #     shot.player_id #=> 201939
+    #   @return [Integer] the player ID
+    attribute :player_id, Shale::Type::Integer
+
+    # @!attribute [rw] player_name
+    #   Returns the player name
+    #   @api public
+    #   @example
+    #     shot.player_name #=> "Stephen Curry"
+    #   @return [String] the player name
+    attribute :player_name, Shale::Type::String
+
+    # @!attribute [rw] team_id
+    #   Returns the team ID
+    #   @api public
+    #   @example
+    #     shot.team_id #=> 1610612744
+    #   @return [Integer] the team ID
+    attribute :team_id, Shale::Type::Integer
+
+    # @!attribute [rw] team_name
+    #   Returns the team name
+    #   @api public
+    #   @example
+    #     shot.team_name #=> "Golden State Warriors"
+    #   @return [String] the team name
+    attribute :team_name, Shale::Type::String
+
+    # @!attribute [rw] period
+    #   Returns the period number
+    #   @api public
+    #   @example
+    #     shot.period #=> 1
+    #   @return [Integer] the period
+    attribute :period, Shale::Type::Integer
+
+    # @!attribute [rw] minutes_remaining
+    #   Returns minutes remaining in period
+    #   @api public
+    #   @example
+    #     shot.minutes_remaining #=> 10
+    #   @return [Integer] minutes remaining
+    attribute :minutes_remaining, Shale::Type::Integer
+
+    # @!attribute [rw] seconds_remaining
+    #   Returns seconds remaining in period
+    #   @api public
+    #   @example
+    #     shot.seconds_remaining #=> 45
+    #   @return [Integer] seconds remaining
+    attribute :seconds_remaining, Shale::Type::Integer
+
+    # @!attribute [rw] action_type
+    #   Returns the shot action type
+    #   @api public
+    #   @example
+    #     shot.action_type #=> "Jump Shot"
+    #   @return [String] the action type
+    attribute :action_type, Shale::Type::String
+
+    # @!attribute [rw] shot_type
+    #   Returns the shot type (2PT or 3PT)
+    #   @api public
+    #   @example
+    #     shot.shot_type #=> "3PT Field Goal"
+    #   @return [String] the shot type
+    attribute :shot_type, Shale::Type::String
+
+    # @!attribute [rw] shot_zone_basic
+    #   Returns the basic shot zone
+    #   @api public
+    #   @example
+    #     shot.shot_zone_basic #=> "Above the Break 3"
+    #   @return [String] the zone
+    attribute :shot_zone_basic, Shale::Type::String
+
+    # @!attribute [rw] shot_zone_area
+    #   Returns the shot zone area
+    #   @api public
+    #   @example
+    #     shot.shot_zone_area #=> "Center(C)"
+    #   @return [String] the area
+    attribute :shot_zone_area, Shale::Type::String
+
+    # @!attribute [rw] shot_zone_range
+    #   Returns the shot zone range
+    #   @api public
+    #   @example
+    #     shot.shot_zone_range #=> "24+ ft."
+    #   @return [String] the range
+    attribute :shot_zone_range, Shale::Type::String
+
+    # @!attribute [rw] shot_distance
+    #   Returns the shot distance in feet
+    #   @api public
+    #   @example
+    #     shot.shot_distance #=> 26
+    #   @return [Integer] the distance
+    attribute :shot_distance, Shale::Type::Integer
+
+    # @!attribute [rw] loc_x
+    #   Returns the X coordinate on the court
+    #   @api public
+    #   @example
+    #     shot.loc_x #=> -22
+    #   @return [Integer] the X coordinate
+    attribute :loc_x, Shale::Type::Integer
+
+    # @!attribute [rw] loc_y
+    #   Returns the Y coordinate on the court
+    #   @api public
+    #   @example
+    #     shot.loc_y #=> 239
+    #   @return [Integer] the Y coordinate
+    attribute :loc_y, Shale::Type::Integer
+
+    # @!attribute [rw] shot_attempted_flag
+    #   Returns whether a shot was attempted
+    #   @api public
+    #   @example
+    #     shot.shot_attempted_flag #=> 1
+    #   @return [Integer] 1 if attempted
+    attribute :shot_attempted_flag, Shale::Type::Integer
+
+    # @!attribute [rw] shot_made_flag
+    #   Returns whether the shot was made
+    #   @api public
+    #   @example
+    #     shot.shot_made_flag #=> 1
+    #   @return [Integer] 1 if made, 0 if missed
+    attribute :shot_made_flag, Shale::Type::Integer
+
+    # Returns whether a shot was attempted
+    #
+    # @api public
+    # @example
+    #   shot.attempted? #=> true
+    # @return [Boolean] true if attempted
+    def attempted?
+      shot_attempted_flag.eql?(1)
+    end
+
+    # Returns whether the shot was made
+    #
+    # @api public
+    # @example
+    #   shot.made? #=> true
+    # @return [Boolean] true if made
+    def made?
+      shot_made_flag.eql?(1)
+    end
+
+    # Returns whether the shot was missed
+    #
+    # @api public
+    # @example
+    #   shot.missed? #=> false
+    # @return [Boolean] true if missed
+    def missed?
+      shot_made_flag&.zero?
+    end
+
+    # Returns whether this is a three-pointer
+    #
+    # @api public
+    # @example
+    #   shot.three_pointer? #=> true
+    # @return [Boolean] true if 3PT shot
+    def three_pointer?
+      shot_type&.include?("3PT")
+    end
+
+    # Returns the game object for this shot
+    #
+    # @api public
+    # @example
+    #   shot.game #=> #<NBA::Game>
+    # @return [Game, nil] the game object
+    def game
+      Games.find(game_id)
+    end
+  end
+end

data/lib/nba/shot_chart.rb

@@ -0,0 +1,75 @@
+require_relative "client"
+require_relative "response_parser"
+require_relative "shot"
+require_relative "utils"
+
+module NBA
+  # Provides methods to retrieve shot chart data
+  module ShotChart
+    # Result set name for shot chart detail
+    # @return [String] the result set name
+    RESULT_SET_NAME = "Shot_Chart_Detail".freeze
+
+    # Retrieves shot chart data for a player
+    #
+    # @api public
+    # @example
+    #   shots = NBA::ShotChart.find(player: 201939, team: Team::GSW)
+    #   shots.each { |s| puts "#{s.action_type} at (#{s.loc_x}, #{s.loc_y}): #{s.made? ? 'Made' : 'Missed'}" }
+    # @param player [Integer, Player] the player ID or Player object
+    # @param team [Integer, Team] the team ID or Team object
+    # @param season [Integer] the season year (defaults to current season)
+    # @param client [Client] the API client to use
+    # @return [Collection] a collection of shots
+    def self.find(player:, team:, season: Utils.current_season, client: CLIENT)
+      path = "shotchartdetail?PlayerID=#{Utils.extract_id(player)}&TeamID=#{Utils.extract_id(team)}" \
+             "&Season=#{Utils.format_season(season)}&ContextMeasure=FGA"
+      ResponseParser.parse(client.get(path), result_set: RESULT_SET_NAME) { |data| build_shot(data) }
+    end
+
+    # Builds a shot from API data
+    # @api private
+    # @return [Shot]
+    def self.build_shot(data)
+      Shot.new(**identity_info(data), **timing_info(data), **shot_info(data), **location_info(data))
+    end
+    private_class_method :build_shot
+
+    # Extracts identity information from data
+    # @api private
+    # @return [Hash]
+    def self.identity_info(data)
+      {game_id: data["GAME_ID"], game_event_id: data["GAME_EVENT_ID"], player_id: data["PLAYER_ID"],
+       player_name: data["PLAYER_NAME"], team_id: data["TEAM_ID"], team_name: data["TEAM_NAME"]}
+    end
+    private_class_method :identity_info
+
+    # Extracts timing information from data
+    # @api private
+    # @return [Hash]
+    def self.timing_info(data)
+      {period: data["PERIOD"], minutes_remaining: data["MINUTES_REMAINING"],
+       seconds_remaining: data["SECONDS_REMAINING"]}
+    end
+    private_class_method :timing_info
+
+    # Extracts shot information from data
+    # @api private
+    # @return [Hash]
+    def self.shot_info(data)
+      {action_type: data["ACTION_TYPE"], shot_type: data["SHOT_TYPE"],
+       shot_zone_basic: data["SHOT_ZONE_BASIC"], shot_zone_area: data["SHOT_ZONE_AREA"],
+       shot_zone_range: data["SHOT_ZONE_RANGE"], shot_distance: data["SHOT_DISTANCE"],
+       shot_attempted_flag: data["SHOT_ATTEMPTED_FLAG"], shot_made_flag: data["SHOT_MADE_FLAG"]}
+    end
+    private_class_method :shot_info
+
+    # Extracts location information from data
+    # @api private
+    # @return [Hash]
+    def self.location_info(data)
+      {loc_x: data["LOC_X"], loc_y: data["LOC_Y"]}
+    end
+    private_class_method :location_info
+  end
+end

data/lib/nba/shot_chart_league_wide.rb

@@ -0,0 +1,102 @@
+require "json"
+require_relative "client"
+require_relative "collection"
+require_relative "utils"
+
+require_relative "league_wide_shot_stat"
+
+module NBA
+  # Provides methods to retrieve league-wide shot chart data
+  module ShotChartLeagueWide
+    # Result set name for league-wide shot data
+    # @return [String] the result set name
+    LEAGUE_WIDE = "LeagueWide".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
+
+    # Retrieves league-wide shot statistics
+    #
+    # @api public
+    # @example
+    #   stats = NBA::ShotChartLeagueWide.all(season: 2024)
+    #   stats.each { |s| puts "#{s.shot_zone_basic}: #{(s.fg_pct * 100).round(1)}%" }
+    # @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 league-wide shot stats
+    def self.all(season: Utils.current_season, season_type: REGULAR_SEASON, client: CLIENT)
+      path = build_path(season, season_type)
+      response = client.get(path)
+      parse_response(response)
+    end
+
+    # Builds the API path
+    #
+    # @api private
+    # @return [String] the request path
+    def self.build_path(season, season_type)
+      season_str = Utils.format_season(season)
+      "shotchartleaguewide?LeagueID=00&Season=#{season_str}&SeasonType=#{season_type}"
+    end
+    private_class_method :build_path
+
+    # Parses the API response into shot stat objects
+    #
+    # @api private
+    # @return [Collection] collection of shot 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_shot_stat(headers, row) }
+      Collection.new(stats)
+    end
+    private_class_method :parse_response
+
+    # Finds the 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?(LEAGUE_WIDE) }
+    end
+    private_class_method :find_result_set
+
+    # Builds a LeagueWideShotStat object from raw data
+    #
+    # @api private
+    # @return [LeagueWideShotStat] the shot stat object
+    def self.build_shot_stat(headers, row)
+      data = headers.zip(row).to_h
+      LeagueWideShotStat.new(**shot_stat_attributes(data))
+    end
+    private_class_method :build_shot_stat
+
+    # Extracts shot stat attributes from data
+    #
+    # @api private
+    # @return [Hash] shot stat attributes
+    def self.shot_stat_attributes(data)
+      {grid_type: data["GRID_TYPE"], shot_zone_basic: data["SHOT_ZONE_BASIC"],
+       shot_zone_area: data["SHOT_ZONE_AREA"], shot_zone_range: data["SHOT_ZONE_RANGE"],
+       fga: data["FGA"], fgm: data["FGM"], fg_pct: data["FG_PCT"]}
+    end
+    private_class_method :shot_stat_attributes
+  end
+end