nba 0.1.1 → 0.2.0

data/lib/nba/box_score_summary.rb

@@ -0,0 +1,285 @@
+require "equalizer"
+require "shale"
+
+module NBA
+  # Represents game summary information
+  class BoxScoreSummary < Shale::Mapper
+    include Equalizer.new(:game_id)
+
+    # @!attribute [rw] game_id
+    #   Returns the game ID
+    #   @api public
+    #   @example
+    #     summary.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
+    #     summary.game_date #=> "2024-10-22"
+    #   @return [String] the game date
+    attribute :game_date, Shale::Type::String
+
+    # @!attribute [rw] game_status_id
+    #   Returns the game status ID
+    #   @api public
+    #   @example
+    #     summary.game_status_id #=> 3
+    #   @return [Integer] the status ID
+    attribute :game_status_id, Shale::Type::Integer
+
+    # @!attribute [rw] game_status_text
+    #   Returns the game status text
+    #   @api public
+    #   @example
+    #     summary.game_status_text #=> "Final"
+    #   @return [String] the status text
+    attribute :game_status_text, Shale::Type::String
+
+    # @!attribute [rw] home_team_id
+    #   Returns the home team ID
+    #   @api public
+    #   @example
+    #     summary.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
+    #     summary.visitor_team_id #=> 1610612747
+    #   @return [Integer] the visitor team ID
+    attribute :visitor_team_id, Shale::Type::Integer
+
+    # @!attribute [rw] season
+    #   Returns the season
+    #   @api public
+    #   @example
+    #     summary.season #=> "2024-25"
+    #   @return [String] the season
+    attribute :season, Shale::Type::String
+
+    # @!attribute [rw] live_period
+    #   Returns the current period if live
+    #   @api public
+    #   @example
+    #     summary.live_period #=> 4
+    #   @return [Integer] the live period
+    attribute :live_period, Shale::Type::Integer
+
+    # @!attribute [rw] live_pc_time
+    #   Returns the time on the clock if live
+    #   @api public
+    #   @example
+    #     summary.live_pc_time #=> "0:00"
+    #   @return [String] the live clock time
+    attribute :live_pc_time, Shale::Type::String
+
+    # @!attribute [rw] attendance
+    #   Returns the attendance
+    #   @api public
+    #   @example
+    #     summary.attendance #=> 18064
+    #   @return [Integer] the attendance
+    attribute :attendance, Shale::Type::Integer
+
+    # @!attribute [rw] game_time
+    #   Returns the game duration
+    #   @api public
+    #   @example
+    #     summary.game_time #=> "2:18"
+    #   @return [String] the game time
+    attribute :game_time, Shale::Type::String
+
+    # @!attribute [rw] arena
+    #   Returns the arena name
+    #   @api public
+    #   @example
+    #     summary.arena #=> "Chase Center"
+    #   @return [String] the arena
+    attribute :arena, Shale::Type::String
+
+    # @!attribute [rw] lead_changes
+    #   Returns the number of lead changes
+    #   @api public
+    #   @example
+    #     summary.lead_changes #=> 12
+    #   @return [Integer] lead changes
+    attribute :lead_changes, Shale::Type::Integer
+
+    # @!attribute [rw] times_tied
+    #   Returns the number of times tied
+    #   @api public
+    #   @example
+    #     summary.times_tied #=> 8
+    #   @return [Integer] times tied
+    attribute :times_tied, Shale::Type::Integer
+
+    # @!attribute [rw] officials
+    #   Returns the game officials
+    #   @api public
+    #   @example
+    #     summary.officials #=> ["Scott Foster", "Tony Brothers", "Marc Davis"]
+    #   @return [Array<String>] the officials
+    attribute :officials, Shale::Type::String, collection: true
+
+    # @!attribute [rw] home_pts_q1
+    #   Returns home team Q1 points
+    #   @api public
+    #   @example
+    #     summary.home_pts_q1 #=> 28
+    #   @return [Integer] Q1 points
+    attribute :home_pts_q1, Shale::Type::Integer
+
+    # @!attribute [rw] home_pts_q2
+    #   Returns home team Q2 points
+    #   @api public
+    #   @example
+    #     summary.home_pts_q2 #=> 32
+    #   @return [Integer] Q2 points
+    attribute :home_pts_q2, Shale::Type::Integer
+
+    # @!attribute [rw] home_pts_q3
+    #   Returns home team Q3 points
+    #   @api public
+    #   @example
+    #     summary.home_pts_q3 #=> 25
+    #   @return [Integer] Q3 points
+    attribute :home_pts_q3, Shale::Type::Integer
+
+    # @!attribute [rw] home_pts_q4
+    #   Returns home team Q4 points
+    #   @api public
+    #   @example
+    #     summary.home_pts_q4 #=> 33
+    #   @return [Integer] Q4 points
+    attribute :home_pts_q4, Shale::Type::Integer
+
+    # @!attribute [rw] home_pts_ot
+    #   Returns home team OT points
+    #   @api public
+    #   @example
+    #     summary.home_pts_ot #=> 0
+    #   @return [Integer] OT points
+    attribute :home_pts_ot, Shale::Type::Integer
+
+    # @!attribute [rw] home_pts
+    #   Returns home team total points
+    #   @api public
+    #   @example
+    #     summary.home_pts #=> 118
+    #   @return [Integer] total points
+    attribute :home_pts, Shale::Type::Integer
+
+    # @!attribute [rw] visitor_pts_q1
+    #   Returns visitor team Q1 points
+    #   @api public
+    #   @example
+    #     summary.visitor_pts_q1 #=> 25
+    #   @return [Integer] Q1 points
+    attribute :visitor_pts_q1, Shale::Type::Integer
+
+    # @!attribute [rw] visitor_pts_q2
+    #   Returns visitor team Q2 points
+    #   @api public
+    #   @example
+    #     summary.visitor_pts_q2 #=> 28
+    #   @return [Integer] Q2 points
+    attribute :visitor_pts_q2, Shale::Type::Integer
+
+    # @!attribute [rw] visitor_pts_q3
+    #   Returns visitor team Q3 points
+    #   @api public
+    #   @example
+    #     summary.visitor_pts_q3 #=> 30
+    #   @return [Integer] Q3 points
+    attribute :visitor_pts_q3, Shale::Type::Integer
+
+    # @!attribute [rw] visitor_pts_q4
+    #   Returns visitor team Q4 points
+    #   @api public
+    #   @example
+    #     summary.visitor_pts_q4 #=> 26
+    #   @return [Integer] Q4 points
+    attribute :visitor_pts_q4, Shale::Type::Integer
+
+    # @!attribute [rw] visitor_pts_ot
+    #   Returns visitor team OT points
+    #   @api public
+    #   @example
+    #     summary.visitor_pts_ot #=> 0
+    #   @return [Integer] OT points
+    attribute :visitor_pts_ot, Shale::Type::Integer
+
+    # @!attribute [rw] visitor_pts
+    #   Returns visitor team total points
+    #   @api public
+    #   @example
+    #     summary.visitor_pts #=> 109
+    #   @return [Integer] total points
+    attribute :visitor_pts, Shale::Type::Integer
+
+    # Returns the home team object
+    #
+    # @api public
+    # @example
+    #   summary.home_team #=> #<NBA::Team>
+    # @return [Team, nil] the home team
+    def home_team
+      Teams.find(home_team_id)
+    end
+
+    # Returns the visitor team object
+    #
+    # @api public
+    # @example
+    #   summary.visitor_team #=> #<NBA::Team>
+    # @return [Team, nil] the visitor team
+    def visitor_team
+      Teams.find(visitor_team_id)
+    end
+
+    # Returns the game object
+    #
+    # @api public
+    # @example
+    #   summary.game #=> #<NBA::Game>
+    # @return [Game, nil] the game
+    def game
+      Games.find(game_id)
+    end
+
+    # Returns whether the game is final
+    #
+    # @api public
+    # @example
+    #   summary.final? #=> true
+    # @return [Boolean] true if final
+    def final?
+      game_status_id.eql?(3)
+    end
+
+    # Returns whether the game is in progress
+    #
+    # @api public
+    # @example
+    #   summary.in_progress? #=> false
+    # @return [Boolean] true if in progress
+    def in_progress?
+      game_status_id.eql?(2)
+    end
+
+    # Returns whether the game has not started
+    #
+    # @api public
+    # @example
+    #   summary.scheduled? #=> false
+    # @return [Boolean] true if scheduled
+    def scheduled?
+      game_status_id.eql?(1)
+    end
+  end
+end

data/lib/nba/box_score_summary_v2.rb

@@ -0,0 +1,202 @@
+require "json"
+require_relative "client"
+require_relative "box_score_summary"
+require_relative "utils"
+
+module NBA
+  # Provides methods to retrieve game summary information
+  module BoxScoreSummaryV2
+    # Result set name for game summary
+    # @return [String] the result set name
+    GAME_SUMMARY = "GameSummary".freeze
+
+    # Result set name for line score
+    # @return [String] the result set name
+    LINE_SCORE = "LineScore".freeze
+
+    # Result set name for officials
+    # @return [String] the result set name
+    OFFICIALS = "Officials".freeze
+
+    # Result set name for other stats
+    # @return [String] the result set name
+    OTHER_STATS = "OtherStats".freeze
+
+    # Retrieves game summary information
+    #
+    # @api public
+    # @example
+    #   summary = NBA::BoxScoreSummaryV2.find(game: "0022400001")
+    #   puts "#{summary.home_team.full_name} #{summary.home_pts} - #{summary.visitor_pts} #{summary.visitor_team.full_name}"
+    # @param game [String, Game] the game ID or Game object
+    # @param client [Client] the API client to use
+    # @return [BoxScoreSummary, nil] the game summary
+    def self.find(game:, client: CLIENT)
+      game_id = Utils.extract_id(game)
+      path = "boxscoresummaryv2?GameID=#{game_id}"
+      response = client.get(path)
+      parse_response(response, game_id)
+    end
+
+    # Parses the API response
+    # @api private
+    # @param response [String, nil] the JSON response
+    # @param game_id [String] the game ID
+    # @return [BoxScoreSummary, nil] the game summary
+    def self.parse_response(response, game_id)
+      return unless response
+
+      data = JSON.parse(response)
+      game_summary = find_result_set(data, GAME_SUMMARY)
+      return unless game_summary
+
+      line_scores = find_result_set(data, LINE_SCORE)
+      officials = find_result_set(data, OFFICIALS)
+      other_stats = find_result_set(data, OTHER_STATS)
+
+      build_summary(game_summary, line_scores, officials, other_stats, game_id)
+    end
+    private_class_method :parse_response
+
+    # Finds a result set by name
+    # @api private
+    # @param data [Hash] the parsed JSON
+    # @param name [String] the result set name
+    # @return [Hash, nil] the result set
+    def self.find_result_set(data, name)
+      result_sets = data["resultSets"]
+      return unless result_sets
+
+      result_sets.find { |rs| rs.fetch("name").eql?(name) }
+    end
+    private_class_method :find_result_set
+
+    # Builds the summary object
+    # @api private
+    # @param game_summary [Hash] game summary result set
+    # @param line_scores [Hash] line score result set
+    # @param officials [Hash] officials result set
+    # @param other_stats [Hash] other stats result set
+    # @param game_id [String] the game ID
+    # @return [BoxScoreSummary, nil] the summary
+    def self.build_summary(game_summary, line_scores, officials, other_stats, game_id)
+      summary_row = extract_first_row(game_summary)
+      return unless summary_row
+
+      home_line, visitor_line = extract_line_scores(line_scores)
+      attrs = game_attributes(summary_row, game_id)
+      attrs = attrs.merge(home_score_attributes(home_line))
+      attrs = attrs.merge(visitor_score_attributes(visitor_line))
+      attrs = attrs.merge(officials: extract_officials(officials))
+      attrs = attrs.merge(other_attributes(extract_other_stats(other_stats)))
+      BoxScoreSummary.new(**attrs)
+    end
+    private_class_method :build_summary
+
+    # Extracts the first row from a result set
+    # @api private
+    # @param result_set [Hash] the result set
+    # @return [Hash, nil] the first row as a hash
+    def self.extract_first_row(result_set)
+      headers = result_set["headers"]
+      row = result_set.dig("rowSet", 0)
+      return unless headers && row
+
+      headers.zip(row).to_h
+    end
+    private_class_method :extract_first_row
+
+    # Extracts line scores for home and visitor
+    # @api private
+    # @param line_scores [Hash] line score result set
+    # @return [Array<Hash, Hash>] home and visitor line scores
+    def self.extract_line_scores(line_scores)
+      return [{}, {}] unless line_scores
+
+      headers = line_scores["headers"]
+      rows = line_scores["rowSet"]
+      return [{}, {}] unless headers && rows && rows.size >= 2
+
+      [headers.zip(rows.fetch(1)).to_h, headers.zip(rows.fetch(0)).to_h]
+    end
+    private_class_method :extract_line_scores
+
+    # Extracts official names
+    # @api private
+    # @param officials [Hash] officials result set
+    # @return [Array<String>] official names
+    def self.extract_officials(officials)
+      return [] unless officials
+
+      headers = officials["headers"]
+      rows = officials["rowSet"]
+      return [] unless headers && rows
+
+      first_name_idx = headers.index("FIRST_NAME")
+      last_name_idx = headers.index("LAST_NAME")
+      return [] unless first_name_idx && last_name_idx
+
+      rows.map { |row| "#{row.fetch(first_name_idx)} #{row.fetch(last_name_idx)}" }
+    end
+    private_class_method :extract_officials
+
+    # Extracts other stats
+    # @api private
+    # @param other_stats [Hash] other stats result set
+    # @return [Hash] other stats hash
+    def self.extract_other_stats(other_stats)
+      return {} unless other_stats
+
+      headers = other_stats["headers"]
+      row = other_stats.dig("rowSet", 0)
+      return {} unless headers && row
+
+      headers.zip(row).to_h
+    end
+    private_class_method :extract_other_stats
+
+    # Extracts game attributes
+    # @api private
+    # @param data [Hash] the summary data
+    # @param game_id [String] the game ID
+    # @return [Hash] game attributes
+    def self.game_attributes(data, game_id)
+      {game_id: game_id, game_date: data.fetch("GAME_DATE_EST"), game_status_id: data.fetch("GAME_STATUS_ID"),
+       game_status_text: data.fetch("GAME_STATUS_TEXT"), home_team_id: data.fetch("HOME_TEAM_ID"),
+       visitor_team_id: data.fetch("VISITOR_TEAM_ID"), season: data.fetch("SEASON"),
+       live_period: data.fetch("LIVE_PERIOD"), live_pc_time: data.fetch("LIVE_PC_TIME"),
+       attendance: data.fetch("ATTENDANCE"), game_time: data.fetch("GAME_TIME")}
+    end
+    private_class_method :game_attributes
+
+    # Extracts home score attributes
+    # @api private
+    # @param data [Hash] the line score data
+    # @return [Hash] home score attributes
+    def self.home_score_attributes(data)
+      {home_pts_q1: data["PTS_QTR1"], home_pts_q2: data["PTS_QTR2"], home_pts_q3: data["PTS_QTR3"],
+       home_pts_q4: data["PTS_QTR4"], home_pts_ot: data["PTS_OT1"], home_pts: data["PTS"]}
+    end
+    private_class_method :home_score_attributes
+
+    # Extracts visitor score attributes
+    # @api private
+    # @param data [Hash] the line score data
+    # @return [Hash] visitor score attributes
+    def self.visitor_score_attributes(data)
+      {visitor_pts_q1: data["PTS_QTR1"], visitor_pts_q2: data["PTS_QTR2"],
+       visitor_pts_q3: data["PTS_QTR3"], visitor_pts_q4: data["PTS_QTR4"],
+       visitor_pts_ot: data["PTS_OT1"], visitor_pts: data["PTS"]}
+    end
+    private_class_method :visitor_score_attributes
+
+    # Extracts other stats attributes
+    # @api private
+    # @param data [Hash] the other stats data
+    # @return [Hash] other stats attributes
+    def self.other_attributes(data)
+      {lead_changes: data["LEAD_CHANGES"], times_tied: data["TIMES_TIED"], arena: data["ARENA"]}
+    end
+    private_class_method :other_attributes
+  end
+end

data/lib/nba/box_score_summary_v3.rb

@@ -0,0 +1,120 @@
+require "json"
+require_relative "client"
+require_relative "box_score_summary_v3_data"
+require_relative "utils"
+
+module NBA
+  # Provides methods to retrieve game summary information using V3 API
+  module BoxScoreSummaryV3
+    # Result set name for box score summary
+    # @return [String] the result set name
+    BOX_SCORE_SUMMARY = "boxScoreSummary".freeze
+
+    # Retrieves game summary information
+    #
+    # @api public
+    # @example
+    #   summary = NBA::BoxScoreSummaryV3.find(game: "0022400001")
+    #   puts "#{summary.home_team_name} #{summary.home_pts} - #{summary.away_pts} #{summary.away_team_name}"
+    # @param game [String, Game] the game ID or Game object
+    # @param client [Client] the API client to use
+    # @return [BoxScoreSummaryV3Data, nil] the game summary
+    def self.find(game:, client: CLIENT)
+      game_id = Utils.extract_id(game)
+      response = client.get("boxscoresummaryv3?GameID=#{game_id}")
+      parse_response(response, game_id)
+    end
+
+    # Parses the API response
+    # @api private
+    # @return [BoxScoreSummaryV3Data, nil] the game summary
+    def self.parse_response(response, game_id)
+      return unless response
+
+      box_score = JSON.parse(response)[BOX_SCORE_SUMMARY]
+      build_summary(box_score, game_id) if box_score
+    end
+    private_class_method :parse_response
+
+    # Builds the summary object
+    # @api private
+    # @return [BoxScoreSummaryV3Data] the summary
+    def self.build_summary(box_score, game_id)
+      attrs = game_attributes(box_score, game_id).merge(arena_attributes(box_score))
+      attrs.merge!(team_attributes(box_score, "homeTeam", "home"))
+      attrs.merge!(team_attributes(box_score, "awayTeam", "away"))
+      attrs.merge!(other_stats_attributes(box_score))
+      BoxScoreSummaryV3Data.new(**attrs, officials: extract_officials(box_score))
+    end
+    private_class_method :build_summary
+
+    # Extracts game attributes
+    # @api private
+    # @return [Hash] game attributes
+    def self.game_attributes(data, game_id)
+      {game_id: game_id, game_code: data["gameCode"], game_status: data["gameStatus"],
+       game_status_text: data["gameStatusText"], period: data["period"],
+       game_clock: data["gameClock"], game_time_utc: data["gameTimeUTC"],
+       game_et: data["gameEt"], duration: data["duration"],
+       attendance: data["attendance"], sellout: data["sellout"]}
+    end
+    private_class_method :game_attributes
+
+    # Extracts arena attributes
+    # @api private
+    # @return [Hash] arena attributes
+    def self.arena_attributes(data)
+      arena = data.fetch("arena", {})
+      {arena_id: arena["arenaId"], arena_name: arena["arenaName"],
+       arena_city: arena["arenaCity"], arena_state: arena["arenaState"],
+       arena_country: arena["arenaCountry"], arena_timezone: arena["arenaTimezone"]}
+    end
+    private_class_method :arena_attributes
+
+    # Extracts team attributes for home or away team
+    # @api private
+    # @return [Hash] team attributes
+    def self.team_attributes(data, team_key, prefix)
+      team = data.fetch(team_key, {})
+      {"#{prefix}_team_id": team["teamId"], "#{prefix}_team_name": team["teamName"],
+       "#{prefix}_team_city": team["teamCity"], "#{prefix}_team_tricode": team["teamTricode"],
+       "#{prefix}_team_slug": team["teamSlug"], "#{prefix}_team_wins": team["teamWins"],
+       "#{prefix}_team_losses": team["teamLosses"], "#{prefix}_pts": team["score"],
+       "#{prefix}_pts_q1": extract_period_score(team, 1), "#{prefix}_pts_q2": extract_period_score(team, 2),
+       "#{prefix}_pts_q3": extract_period_score(team, 3), "#{prefix}_pts_q4": extract_period_score(team, 4)}
+    end
+    private_class_method :team_attributes
+
+    # Extracts period score from team data
+    # @api private
+    # @return [Integer, nil] period score
+    def self.extract_period_score(team, period)
+      periods = team["periods"]
+      return unless periods
+
+      period_data = periods.find { |p| p["period"].eql?(period) }
+      period_data&.[]("score")
+    end
+    private_class_method :extract_period_score
+
+    # Extracts other stats attributes
+    # @api private
+    # @return [Hash] other stats attributes
+    def self.other_stats_attributes(data)
+      {lead_changes: data["leadChanges"], times_tied: data["timesTied"],
+       largest_lead: data["largestLead"]}
+    end
+    private_class_method :other_stats_attributes
+
+    # Extracts official names
+    # @api private
+    # @return [Array<String>] official names
+    def self.extract_officials(data)
+      officials = data["officials"]
+      return [] unless officials
+
+      officials.filter_map { |o| "#{o.fetch("firstName")} #{o.fetch("familyName")}" if o["firstName"] && o["familyName"] }
+    end
+    private_class_method :extract_officials
+  end
+end