nba 0.1.1 → 0.2.0

data/lib/nba/league_standings.rb

@@ -0,0 +1,159 @@
+require "json"
+require_relative "client"
+require_relative "collection"
+require_relative "utils"
+
+require_relative "league_standing"
+
+module NBA
+  # Provides methods to retrieve league standings with extended data
+  module LeagueStandings
+    # Result set name for standings
+    # @return [String] the result set name
+    STANDINGS = "Standings".freeze
+
+    # Season type constant for regular season
+    # @return [String] the season type
+    REGULAR_SEASON = "Regular Season".freeze
+
+    # Retrieves all league standings
+    #
+    # @api public
+    # @example
+    #   standings = NBA::LeagueStandings.all(season: 2024)
+    #   standings.each { |s| puts "#{s.playoff_rank}. #{s.full_name}: #{s.wins}-#{s.losses}" }
+    # @param season [Integer] the season year
+    # @param season_type [String] the season type
+    # @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 standings
+    def self.all(season: Utils.current_season, season_type: REGULAR_SEASON, league: League::NBA, client: CLIENT)
+      league_id = Utils.extract_league_id(league)
+      path = build_path(season, season_type, league_id)
+      response = client.get(path)
+      parse_response(response)
+    end
+
+    # Retrieves standings for a specific conference
+    #
+    # @api public
+    # @example
+    #   west = NBA::LeagueStandings.conference("West", season: 2024)
+    #   west.each { |s| puts "#{s.playoff_rank}. #{s.full_name}" }
+    # @param conference_name [String] the conference name ("East" or "West")
+    # @param season [Integer] the season year
+    # @param season_type [String] the season type
+    # @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 standings
+    def self.conference(conference_name, season: Utils.current_season, season_type: REGULAR_SEASON, league: League::NBA,
+      client: CLIENT)
+      all_standings = all(season: season, season_type: season_type, league: league, client: client)
+      filtered = all_standings.select { |s| s.conference.eql?(conference_name) }
+      Collection.new(filtered)
+    end
+
+    # Builds the API request path
+    # @api private
+    # @return [String] the request path
+    def self.build_path(season, season_type, league_id)
+      season_str = Utils.format_season(season)
+      encoded_type = season_type
+      "leaguestandingsv3?LeagueID=#{league_id}&Season=#{season_str}&SeasonType=#{encoded_type}"
+    end
+    private_class_method :build_path
+
+    # Parses the API response into standing objects
+    # @api private
+    # @return [Collection] collection of standings
+    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
+
+      standings = rows.map { |row| build_standing(headers, row) }
+      Collection.new(standings)
+    end
+    private_class_method :parse_response
+
+    # Finds the standings 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?(STANDINGS) }
+    end
+    private_class_method :find_result_set
+
+    # Builds a LeagueStanding object from raw data
+    # @api private
+    # @return [LeagueStanding] the standing object
+    def self.build_standing(headers, row)
+      data = headers.zip(row).to_h
+      LeagueStanding.new(**standing_attributes(data))
+    end
+    private_class_method :build_standing
+
+    # Combines all standing attributes
+    # @api private
+    # @return [Hash] the combined attributes
+    def self.standing_attributes(data)
+      identity_attributes(data).merge(record_attributes(data), streak_attributes(data), points_attributes(data))
+    end
+    private_class_method :standing_attributes
+
+    # Extracts identity attributes from data
+    # @api private
+    # @return [Hash] identity attributes
+    def self.identity_attributes(data)
+      {league_id: data.fetch("LeagueID"), season_id: data.fetch("SeasonID"),
+       team_id: data.fetch("TeamID"), team_city: data.fetch("TeamCity"),
+       team_name: data.fetch("TeamName"), team_slug: data.fetch("TeamSlug"),
+       conference: data.fetch("Conference"), division: data.fetch("Division"),
+       clinch_indicator: data.fetch("ClinchIndicator")}
+    end
+    private_class_method :identity_attributes
+
+    # Extracts record attributes from data
+    # @api private
+    # @return [Hash] record attributes
+    def self.record_attributes(data)
+      {conference_record: data.fetch("ConferenceRecord"), playoff_rank: data.fetch("PlayoffRank"),
+       division_record: data.fetch("DivisionRecord"), division_rank: data.fetch("DivisionRank"),
+       wins: data.fetch("WINS"), losses: data.fetch("LOSSES"), win_pct: data.fetch("WinPCT"),
+       league_rank: data.fetch("LeagueRank"), record: data.fetch("Record"),
+       home_record: data.fetch("HOME"), road_record: data.fetch("ROAD"),
+       conference_games_back: data.fetch("ConferenceGamesBack")}
+    end
+    private_class_method :record_attributes
+
+    # Extracts streak attributes from data
+    # @api private
+    # @return [Hash] streak attributes
+    def self.streak_attributes(data)
+      {l10_record: data.fetch("L10"), long_win_streak: data.fetch("LongWinStreak"),
+       long_loss_streak: data.fetch("LongLossStreak"), current_streak: data.fetch("CurrentStreak"),
+       clinched_conference_title: data.fetch("ClinchedConferenceTitle"),
+       clinched_playoff_birth: data.fetch("ClinchedPlayoffBirth"),
+       eliminated_conference: data.fetch("EliminatedConference")}
+    end
+    private_class_method :streak_attributes
+
+    # Extracts points attributes from data
+    # @api private
+    # @return [Hash] points attributes
+    def self.points_attributes(data)
+      {points_pg: data.fetch("PointsPG"), opp_points_pg: data.fetch("OppPointsPG"),
+       diff_points_pg: data.fetch("DiffPointsPG")}
+    end
+    private_class_method :points_attributes
+  end
+end

data/lib/nba/league_wide_shot_stat.rb

@@ -0,0 +1,62 @@
+module NBA
+  # Represents league-wide shot data
+  class LeagueWideShotStat < Shale::Mapper
+    include Equalizer.new(:shot_zone_basic, :shot_zone_area, :shot_zone_range)
+
+    # @!attribute [rw] grid_type
+    #   Returns the grid type
+    #   @api public
+    #   @example
+    #     stat.grid_type #=> "Shot Zone Basic"
+    #   @return [String] the grid type
+    attribute :grid_type, Shale::Type::String
+
+    # @!attribute [rw] shot_zone_basic
+    #   Returns the basic shot zone
+    #   @api public
+    #   @example
+    #     stat.shot_zone_basic #=> "Mid-Range"
+    #   @return [String] the basic zone
+    attribute :shot_zone_basic, Shale::Type::String
+
+    # @!attribute [rw] shot_zone_area
+    #   Returns the shot zone area
+    #   @api public
+    #   @example
+    #     stat.shot_zone_area #=> "Left Side"
+    #   @return [String] the zone area
+    attribute :shot_zone_area, Shale::Type::String
+
+    # @!attribute [rw] shot_zone_range
+    #   Returns the shot zone range
+    #   @api public
+    #   @example
+    #     stat.shot_zone_range #=> "16-24 ft."
+    #   @return [String] the zone range
+    attribute :shot_zone_range, Shale::Type::String
+
+    # @!attribute [rw] fga
+    #   Returns field goals attempted
+    #   @api public
+    #   @example
+    #     stat.fga #=> 1500
+    #   @return [Integer] field goals attempted
+    attribute :fga, Shale::Type::Integer
+
+    # @!attribute [rw] fgm
+    #   Returns field goals made
+    #   @api public
+    #   @example
+    #     stat.fgm #=> 650
+    #   @return [Integer] field goals made
+    attribute :fgm, Shale::Type::Integer
+
+    # @!attribute [rw] fg_pct
+    #   Returns field goal percentage
+    #   @api public
+    #   @example
+    #     stat.fg_pct #=> 0.433
+    #   @return [Float] field goal percentage
+    attribute :fg_pct, Shale::Type::Float
+  end
+end

data/lib/nba/live_action.rb

@@ -0,0 +1,240 @@
+module NBA
+  # Represents a live play-by-play action
+  class LiveAction < Shale::Mapper
+    include Equalizer.new(:action_number, :game_id)
+
+    # @!attribute [rw] game_id
+    #   Returns the game ID
+    #   @api public
+    #   @example
+    #     action.game_id #=> "0022400001"
+    #   @return [String] the game ID
+    attribute :game_id, Shale::Type::String
+
+    # @!attribute [rw] action_number
+    #   Returns the action number
+    #   @api public
+    #   @example
+    #     action.action_number #=> 1
+    #   @return [Integer] the action number
+    attribute :action_number, Shale::Type::Integer
+
+    # @!attribute [rw] clock
+    #   Returns the game clock at time of action
+    #   @api public
+    #   @example
+    #     action.clock #=> "PT11M47S"
+    #   @return [String] the clock in ISO 8601 duration format
+    attribute :clock, Shale::Type::String
+
+    # @!attribute [rw] time_actual
+    #   Returns the actual time of the action
+    #   @api public
+    #   @example
+    #     action.time_actual #=> "2024-10-22T19:10:00Z"
+    #   @return [String] the actual time in UTC
+    attribute :time_actual, Shale::Type::String
+
+    # @!attribute [rw] period
+    #   Returns the period
+    #   @api public
+    #   @example
+    #     action.period #=> 1
+    #   @return [Integer] the period number
+    attribute :period, Shale::Type::Integer
+
+    # @!attribute [rw] period_type
+    #   Returns the period type
+    #   @api public
+    #   @example
+    #     action.period_type #=> "REGULAR"
+    #   @return [String] the period type (REGULAR, OVERTIME)
+    attribute :period_type, Shale::Type::String
+
+    # @!attribute [rw] action_type
+    #   Returns the action type
+    #   @api public
+    #   @example
+    #     action.action_type #=> "2pt"
+    #   @return [String] the action type
+    attribute :action_type, Shale::Type::String
+
+    # @!attribute [rw] sub_type
+    #   Returns the action subtype
+    #   @api public
+    #   @example
+    #     action.sub_type #=> "LAYUP"
+    #   @return [String] the action subtype
+    attribute :sub_type, Shale::Type::String
+
+    # @!attribute [rw] qualifier
+    #   Returns any qualifier for the action
+    #   @api public
+    #   @example
+    #     action.qualifiers #=> ["DRIVING"]
+    #   @return [Array<String>] the qualifiers
+    attribute :qualifiers, Shale::Type::String, collection: true
+
+    # @!attribute [rw] description
+    #   Returns the play description
+    #   @api public
+    #   @example
+    #     action.description #=> "Curry Driving Layup"
+    #   @return [String] the description
+    attribute :description, Shale::Type::String
+
+    # @!attribute [rw] player_id
+    #   Returns the player ID involved in the action
+    #   @api public
+    #   @example
+    #     action.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
+    #     action.player_name #=> "Stephen Curry"
+    #   @return [String] the player name
+    attribute :player_name, Shale::Type::String
+
+    # @!attribute [rw] player_name_i
+    #   Returns the player name in abbreviated format
+    #   @api public
+    #   @example
+    #     action.player_name_i #=> "S. Curry"
+    #   @return [String] the abbreviated player name
+    attribute :player_name_i, Shale::Type::String
+
+    # @!attribute [rw] team_id
+    #   Returns the team ID
+    #   @api public
+    #   @example
+    #     action.team_id #=> 1610612744
+    #   @return [Integer] the team ID
+    attribute :team_id, Shale::Type::Integer
+
+    # @!attribute [rw] team_tricode
+    #   Returns the team tricode
+    #   @api public
+    #   @example
+    #     action.team_tricode #=> "GSW"
+    #   @return [String] the team tricode
+    attribute :team_tricode, Shale::Type::String
+
+    # @!attribute [rw] score_home
+    #   Returns the home team score after this action
+    #   @api public
+    #   @example
+    #     action.score_home #=> "2"
+    #   @return [String] the home score
+    attribute :score_home, Shale::Type::String
+
+    # @!attribute [rw] score_away
+    #   Returns the away team score after this action
+    #   @api public
+    #   @example
+    #     action.score_away #=> "0"
+    #   @return [String] the away score
+    attribute :score_away, Shale::Type::String
+
+    # @!attribute [rw] points_total
+    #   Returns the points from this action
+    #   @api public
+    #   @example
+    #     action.points_total #=> 2
+    #   @return [Integer] the points
+    attribute :points_total, Shale::Type::Integer
+
+    # @!attribute [rw] x_legacy
+    #   Returns the x coordinate on the court
+    #   @api public
+    #   @example
+    #     action.x_legacy #=> 5.0
+    #   @return [Float] the x coordinate
+    attribute :x_legacy, Shale::Type::Float
+
+    # @!attribute [rw] y_legacy
+    #   Returns the y coordinate on the court
+    #   @api public
+    #   @example
+    #     action.y_legacy #=> 25.0
+    #   @return [Float] the y coordinate
+    attribute :y_legacy, Shale::Type::Float
+
+    # @!attribute [rw] shot_distance
+    #   Returns the shot distance
+    #   @api public
+    #   @example
+    #     action.shot_distance #=> 2.5
+    #   @return [Float] the shot distance in feet
+    attribute :shot_distance, Shale::Type::Float
+
+    # @!attribute [rw] is_field_goal
+    #   Returns whether this is a field goal attempt
+    #   @api public
+    #   @example
+    #     action.is_field_goal #=> 1
+    #   @return [Integer] 1 if field goal, 0 otherwise
+    attribute :is_field_goal, Shale::Type::Integer
+
+    # @!attribute [rw] shot_result
+    #   Returns the shot result
+    #   @api public
+    #   @example
+    #     action.shot_result #=> "Made"
+    #   @return [String] "Made" or "Missed"
+    attribute :shot_result, Shale::Type::String
+
+    # Returns the player object
+    #
+    # @api public
+    # @example
+    #   action.player #=> #<NBA::Player>
+    # @return [Player, nil] the player object
+    def player
+      Players.find(player_id)
+    end
+
+    # Returns the team object
+    #
+    # @api public
+    # @example
+    #   action.team #=> #<NBA::Team>
+    # @return [Team, nil] the team object
+    def team
+      Teams.find(team_id)
+    end
+
+    # Returns whether this is a field goal attempt
+    #
+    # @api public
+    # @example
+    #   action.field_goal? #=> true
+    # @return [Boolean] true if field goal attempt
+    def field_goal?
+      is_field_goal.eql?(1)
+    end
+
+    # Returns whether this shot was made
+    #
+    # @api public
+    # @example
+    #   action.made? #=> true
+    # @return [Boolean] true if shot was made
+    def made?
+      shot_result.eql?("Made")
+    end
+
+    # Returns whether this shot was missed
+    #
+    # @api public
+    # @example
+    #   action.missed? #=> true
+    # @return [Boolean] true if shot was missed
+    def missed?
+      shot_result.eql?("Missed")
+    end
+  end
+end

data/lib/nba/live_box_score.rb

@@ -0,0 +1,143 @@
+require "json"
+require_relative "collection"
+require_relative "live_connection"
+require_relative "utils"
+
+require_relative "live_player_stat"
+
+module NBA
+  # Provides methods to retrieve live box score data
+  module LiveBoxScore
+    # Retrieves live box score for a game
+    #
+    # @api public
+    # @example
+    #   stats = NBA::LiveBoxScore.find(game: "0022400001")
+    #   stats.each { |s| puts "#{s.name}: #{s.points} pts" }
+    # @param game [String, Game] the game ID or Game object
+    # @param client [LiveConnection] the API client to use
+    # @return [Collection] a collection of player stats
+    def self.find(game:, client: LIVE_CLIENT)
+      game_id = Utils.extract_id(game)
+      path = "boxscore/boxscore_#{game_id}.json"
+      response = client.get(path)
+      parse_response(response, game_id)
+    end
+
+    # Parses the live box score API response
+    #
+    # @api private
+    # @param response [String, nil] the JSON response body
+    # @param game_id [String] the game ID
+    # @return [Collection] a collection of player stats
+    def self.parse_response(response, game_id)
+      return Collection.new unless response
+
+      data = JSON.parse(response)
+      game_data = data["game"]
+      return Collection.new unless game_data
+
+      home_players = extract_players(game_data, "homeTeam", game_id)
+      away_players = extract_players(game_data, "awayTeam", game_id)
+      Collection.new(home_players + away_players)
+    end
+    private_class_method :parse_response
+
+    # Extracts players from a team's data
+    #
+    # @api private
+    # @param game_data [Hash] the game data
+    # @param team_key [String] the team key ("homeTeam" or "awayTeam")
+    # @param game_id [String] the game ID
+    # @return [Array<LivePlayerStat>] array of player stats
+    def self.extract_players(game_data, team_key, game_id)
+      team_data = game_data[team_key]
+      return [] unless team_data
+
+      players = team_data["players"]
+      return [] unless players
+
+      team_id = team_data["teamId"]
+      team_tricode = team_data["teamTricode"]
+
+      players.map { |p| build_player_stat(p, game_id, team_id, team_tricode) }
+    end
+    private_class_method :extract_players
+
+    # Builds a LivePlayerStat object from raw data
+    #
+    # @api private
+    # @param data [Hash] the player data
+    # @param game_id [String] the game ID
+    # @param team_id [Integer] the team ID
+    # @param team_tricode [String] the team tricode
+    # @return [LivePlayerStat] the player stat object
+    def self.build_player_stat(data, game_id, team_id, team_tricode)
+      LivePlayerStat.new(**player_stat_attributes(data, game_id, team_id, team_tricode))
+    end
+    private_class_method :build_player_stat
+
+    # Combines all player stat attributes
+    #
+    # @api private
+    # @param data [Hash] the player data
+    # @param game_id [String] the game ID
+    # @param team_id [Integer] the team ID
+    # @param team_tricode [String] the team tricode
+    # @return [Hash] the combined attributes
+    def self.player_stat_attributes(data, game_id, team_id, team_tricode)
+      identity_attributes(data, game_id, team_id, team_tricode)
+        .merge(counting_attributes(data))
+        .merge(shooting_attributes(data))
+    end
+    private_class_method :player_stat_attributes
+
+    # Extracts identity attributes from data
+    #
+    # @api private
+    # @param data [Hash] the player data
+    # @param game_id [String] the game ID
+    # @param team_id [Integer] the team ID
+    # @param team_tricode [String] the team tricode
+    # @return [Hash] identity attributes
+    def self.identity_attributes(data, game_id, team_id, team_tricode)
+      {game_id: game_id, player_id: data["personId"], name: data["name"],
+       first_name: data["firstName"], family_name: data["familyName"],
+       jersey_num: data["jerseyNum"], position: data["position"],
+       team_id: team_id, team_tricode: team_tricode, starter: data["starter"],
+       minutes: data.dig("statistics", "minutes")}
+    end
+    private_class_method :identity_attributes
+
+    # Extracts counting stats attributes from data
+    #
+    # @api private
+    # @param data [Hash] the player data
+    # @return [Hash] counting attributes
+    def self.counting_attributes(data)
+      stats = data["statistics"] || {}
+      {points: stats["points"], rebounds_total: stats["reboundsTotal"],
+       rebounds_offensive: stats["reboundsOffensive"], rebounds_defensive: stats["reboundsDefensive"],
+       assists: stats["assists"], steals: stats["steals"], blocks: stats["blocks"],
+       turnovers: stats["turnovers"], fouls_personal: stats["foulsPersonal"],
+       plus_minus: stats["plusMinusPoints"]}
+    end
+    private_class_method :counting_attributes
+
+    # Extracts shooting stats attributes from data
+    #
+    # @api private
+    # @param data [Hash] the player data
+    # @return [Hash] shooting attributes
+    def self.shooting_attributes(data)
+      stats = data["statistics"] || {}
+      {field_goals_made: stats["fieldGoalsMade"], field_goals_attempted: stats["fieldGoalsAttempted"],
+       field_goals_percentage: stats["fieldGoalsPercentage"],
+       three_pointers_made: stats["threePointersMade"], three_pointers_attempted: stats["threePointersAttempted"],
+       three_pointers_percentage: stats["threePointersPercentage"],
+       free_throws_made: stats["freeThrowsMade"], free_throws_attempted: stats["freeThrowsAttempted"],
+       free_throws_percentage: stats["freeThrowsPercentage"]}
+    end
+    private_class_method :shooting_attributes
+  end
+end

data/lib/nba/live_connection.rb

@@ -0,0 +1,84 @@
+require "net/http"
+require "openssl"
+require "stringio"
+require "uri"
+require "zlib"
+
+module NBA
+  # Handles HTTP connections to the NBA Live Data API
+  class LiveConnection
+    # Default base URL for the NBA Live Data API
+    # @return [String] the default base URL
+    BASE_URL = "https://cdn.nba.com/static/json/liveData/".freeze
+
+    # Returns the base URL for API requests
+    #
+    # @api private
+    # @return [String] the base URL
+    attr_reader :base_url
+
+    # Initializes a new LiveConnection object
+    #
+    # @api public
+    # @example
+    #   connection = NBA::LiveConnection.new
+    # @param base_url [String] the base URL for API requests
+    # @return [NBA::LiveConnection] a new live connection instance
+    def initialize(base_url: BASE_URL)
+      @base_url = base_url
+    end
+
+    # Makes a GET request to the specified path
+    #
+    # @api public
+    # @example
+    #   connection.get("scoreboard/todaysScoreboard_00.json")
+    # @param path [String] the API path to request
+    # @return [String] the response body
+    def get(path)
+      uri = URI.join(base_url, path)
+      hostname = uri.hostname or raise ArgumentError, "Invalid URI: #{uri}"
+      request = Net::HTTP::Get.new(uri)
+      apply_headers(request)
+
+      Net::HTTP.start(hostname, uri.port, use_ssl: uri.scheme.eql?("https")) do |http|
+        response = http.request(request)
+        decode_body(response) if response.is_a?(Net::HTTPSuccess)
+      end
+    end
+
+    private
+
+    # Applies the required headers for NBA Live Data API requests
+    #
+    # @api private
+    # @param request [Net::HTTP::Get] the request object
+    # @return [void]
+    def apply_headers(request)
+      request["User-Agent"] = "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) " \
+                              "AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36"
+      request["Accept"] = "application/json, text/plain, */*"
+      request["Accept-Language"] = "en-US,en;q=0.9"
+      request["Accept-Encoding"] = "gzip, deflate, identity"
+      request["Connection"] = "keep-alive"
+      request["Referer"] = "https://www.nba.com/"
+      request["Origin"] = "https://www.nba.com"
+    end
+
+    # Decodes the response body based on Content-Encoding
+    #
+    # @api private
+    # @param response [Net::HTTPResponse] the HTTP response
+    # @return [String, nil] the decoded response body
+    def decode_body(response)
+      case response["Content-Encoding"]
+      when "gzip"
+        Zlib::GzipReader.new(StringIO.new(response.body)).read
+      when "deflate"
+        Zlib::Inflate.inflate(response.body)
+      else
+        response.body
+      end
+    end
+  end
+end