nba 0.1.1 → 0.2.0

data/lib/nba/live_game.rb

@@ -0,0 +1,230 @@
+module NBA
+  # Represents a live game from the NBA Live Data API
+  class LiveGame < Shale::Mapper
+    include Equalizer.new(:game_id)
+
+    # @!attribute [rw] game_id
+    #   Returns the game ID
+    #   @api public
+    #   @example
+    #     game.game_id #=> "0022400001"
+    #   @return [String] the game ID
+    attribute :game_id, Shale::Type::String
+
+    # @!attribute [rw] game_code
+    #   Returns the game code
+    #   @api public
+    #   @example
+    #     game.game_code #=> "20241022/LALGSW"
+    #   @return [String] the game code
+    attribute :game_code, Shale::Type::String
+
+    # @!attribute [rw] game_status
+    #   Returns the game status (1=scheduled, 2=in progress, 3=final)
+    #   @api public
+    #   @example
+    #     game.game_status #=> 2
+    #   @return [Integer] the game status
+    attribute :game_status, Shale::Type::Integer
+
+    # @!attribute [rw] game_status_text
+    #   Returns the game status text
+    #   @api public
+    #   @example
+    #     game.game_status_text #=> "Q4 2:30"
+    #   @return [String] the game status text
+    attribute :game_status_text, Shale::Type::String
+
+    # @!attribute [rw] period
+    #   Returns the current period
+    #   @api public
+    #   @example
+    #     game.period #=> 4
+    #   @return [Integer] the current period
+    attribute :period, Shale::Type::Integer
+
+    # @!attribute [rw] game_clock
+    #   Returns the game clock
+    #   @api public
+    #   @example
+    #     game.game_clock #=> "PT02M30.00S"
+    #   @return [String] the game clock in ISO 8601 duration format
+    attribute :game_clock, Shale::Type::String
+
+    # @!attribute [rw] game_time_utc
+    #   Returns the game time in UTC
+    #   @api public
+    #   @example
+    #     game.game_time_utc #=> "2024-10-22T23:30:00Z"
+    #   @return [String] the game time in UTC
+    attribute :game_time_utc, Shale::Type::String
+
+    # @!attribute [rw] game_et
+    #   Returns the game time in Eastern Time
+    #   @api public
+    #   @example
+    #     game.game_et #=> "2024-10-22T19:30:00"
+    #   @return [String] the game time in ET
+    attribute :game_et, Shale::Type::String
+
+    # @!attribute [rw] home_team_id
+    #   Returns the home team ID
+    #   @api public
+    #   @example
+    #     game.home_team_id #=> 1610612744
+    #   @return [Integer] the home team ID
+    attribute :home_team_id, Shale::Type::Integer
+
+    # @!attribute [rw] home_team_name
+    #   Returns the home team name
+    #   @api public
+    #   @example
+    #     game.home_team_name #=> "Warriors"
+    #   @return [String] the home team name
+    attribute :home_team_name, Shale::Type::String
+
+    # @!attribute [rw] home_team_city
+    #   Returns the home team city
+    #   @api public
+    #   @example
+    #     game.home_team_city #=> "Golden State"
+    #   @return [String] the home team city
+    attribute :home_team_city, Shale::Type::String
+
+    # @!attribute [rw] home_team_tricode
+    #   Returns the home team tricode
+    #   @api public
+    #   @example
+    #     game.home_team_tricode #=> "GSW"
+    #   @return [String] the home team tricode
+    attribute :home_team_tricode, Shale::Type::String
+
+    # @!attribute [rw] home_team_score
+    #   Returns the home team score
+    #   @api public
+    #   @example
+    #     game.home_team_score #=> 112
+    #   @return [Integer] the home team score
+    attribute :home_team_score, Shale::Type::Integer
+
+    # @!attribute [rw] away_team_id
+    #   Returns the away team ID
+    #   @api public
+    #   @example
+    #     game.away_team_id #=> 1610612747
+    #   @return [Integer] the away team ID
+    attribute :away_team_id, Shale::Type::Integer
+
+    # @!attribute [rw] away_team_name
+    #   Returns the away team name
+    #   @api public
+    #   @example
+    #     game.away_team_name #=> "Lakers"
+    #   @return [String] the away team name
+    attribute :away_team_name, Shale::Type::String
+
+    # @!attribute [rw] away_team_city
+    #   Returns the away team city
+    #   @api public
+    #   @example
+    #     game.away_team_city #=> "Los Angeles"
+    #   @return [String] the away team city
+    attribute :away_team_city, Shale::Type::String
+
+    # @!attribute [rw] away_team_tricode
+    #   Returns the away team tricode
+    #   @api public
+    #   @example
+    #     game.away_team_tricode #=> "LAL"
+    #   @return [String] the away team tricode
+    attribute :away_team_tricode, Shale::Type::String
+
+    # @!attribute [rw] away_team_score
+    #   Returns the away team score
+    #   @api public
+    #   @example
+    #     game.away_team_score #=> 108
+    #   @return [Integer] the away team score
+    attribute :away_team_score, Shale::Type::Integer
+
+    # Returns the home team object
+    #
+    # @api public
+    # @example
+    #   game.home_team #=> #<NBA::Team>
+    # @return [Team, nil] the home team object
+    def home_team
+      Teams.find(home_team_id)
+    end
+
+    # Returns the away team object
+    #
+    # @api public
+    # @example
+    #   game.away_team #=> #<NBA::Team>
+    # @return [Team, nil] the away team object
+    def away_team
+      Teams.find(away_team_id)
+    end
+
+    # Returns whether the game is scheduled
+    #
+    # @api public
+    # @example
+    #   game.scheduled? #=> false
+    # @return [Boolean] true if scheduled
+    def scheduled?
+      game_status.eql?(1)
+    end
+
+    # Returns whether the game is in progress
+    #
+    # @api public
+    # @example
+    #   game.in_progress? #=> true
+    # @return [Boolean] true if in progress
+    def in_progress?
+      game_status.eql?(2)
+    end
+
+    # Returns whether the game is final
+    #
+    # @api public
+    # @example
+    #   game.final? #=> false
+    # @return [Boolean] true if final
+    def final?
+      game_status.eql?(3)
+    end
+
+    # Returns the game status text (alias for CLI compatibility)
+    #
+    # @api public
+    # @example
+    #   game.status #=> "Q4 2:30"
+    # @return [String] the game status text
+    def status
+      game_status_text
+    end
+
+    # Returns the home team score (alias for CLI compatibility)
+    #
+    # @api public
+    # @example
+    #   game.home_score #=> 112
+    # @return [Integer] the home team score
+    def home_score
+      home_team_score
+    end
+
+    # Returns the away team score (alias for CLI compatibility)
+    #
+    # @api public
+    # @example
+    #   game.away_score #=> 108
+    # @return [Integer] the away team score
+    def away_score
+      away_team_score
+    end
+  end
+end

data/lib/nba/live_play_by_play.rb

@@ -0,0 +1,120 @@
+require "json"
+require_relative "collection"
+require_relative "live_connection"
+require_relative "utils"
+
+require_relative "live_action"
+
+module NBA
+  # Provides methods to retrieve live play-by-play data
+  module LivePlayByPlay
+    # Retrieves live play-by-play for a game
+    #
+    # @api public
+    # @example
+    #   actions = NBA::LivePlayByPlay.find(game: "0022400001")
+    #   actions.each { |a| puts "#{a.clock}: #{a.description}" }
+    # @param game [String, Game] the game ID or Game object
+    # @param client [LiveConnection] the API client to use
+    # @return [Collection] a collection of actions
+    def self.find(game:, client: LIVE_CLIENT)
+      game_id = Utils.extract_id(game)
+      path = "playbyplay/playbyplay_#{game_id}.json"
+      response = client.get(path)
+      parse_response(response, game_id)
+    end
+
+    # Parses the live play-by-play API response
+    #
+    # @api private
+    # @param response [String, nil] the JSON response body
+    # @param game_id [String] the game ID
+    # @return [Collection] a collection of actions
+    def self.parse_response(response, game_id)
+      return Collection.new unless response
+
+      data = JSON.parse(response)
+      actions = data.dig("game", "actions")
+      return Collection.new unless actions
+
+      live_actions = actions.map { |action| build_action(action, game_id) }
+      Collection.new(live_actions)
+    end
+    private_class_method :parse_response
+
+    # Builds a LiveAction object from raw data
+    #
+    # @api private
+    # @param data [Hash] the action data
+    # @param game_id [String] the game ID
+    # @return [LiveAction] the live action object
+    def self.build_action(data, game_id)
+      LiveAction.new(**action_attributes(data, game_id))
+    end
+    private_class_method :build_action
+
+    # Combines all action attributes
+    #
+    # @api private
+    # @param data [Hash] the action data
+    # @param game_id [String] the game ID
+    # @return [Hash] the combined attributes
+    def self.action_attributes(data, game_id)
+      timing_attributes(data, game_id)
+        .merge(action_info_attributes(data))
+        .merge(player_team_attributes(data))
+        .merge(shot_attributes(data))
+    end
+    private_class_method :action_attributes
+
+    # Extracts timing attributes from data
+    #
+    # @api private
+    # @param data [Hash] the action data
+    # @param game_id [String] the game ID
+    # @return [Hash] timing attributes
+    def self.timing_attributes(data, game_id)
+      {game_id: game_id, action_number: data["actionNumber"],
+       clock: data["clock"], time_actual: data["timeActual"],
+       period: data["period"], period_type: data["periodType"]}
+    end
+    private_class_method :timing_attributes
+
+    # Extracts action info attributes from data
+    #
+    # @api private
+    # @param data [Hash] the action data
+    # @return [Hash] action info attributes
+    def self.action_info_attributes(data)
+      {action_type: data["actionType"], sub_type: data["subType"],
+       qualifiers: data["qualifiers"], description: data["description"],
+       score_home: data["scoreHome"], score_away: data["scoreAway"],
+       points_total: data["pointsTotal"]}
+    end
+    private_class_method :action_info_attributes
+
+    # Extracts player and team attributes from data
+    #
+    # @api private
+    # @param data [Hash] the action data
+    # @return [Hash] player and team attributes
+    def self.player_team_attributes(data)
+      {player_id: data["personId"], player_name: data["playerName"],
+       player_name_i: data["playerNameI"], team_id: data["teamId"],
+       team_tricode: data["teamTricode"]}
+    end
+    private_class_method :player_team_attributes
+
+    # Extracts shot attributes from data
+    #
+    # @api private
+    # @param data [Hash] the action data
+    # @return [Hash] shot attributes
+    def self.shot_attributes(data)
+      {x_legacy: data["xLegacy"], y_legacy: data["yLegacy"],
+       shot_distance: data["shotDistance"], is_field_goal: data["isFieldGoal"],
+       shot_result: data["shotResult"]}
+    end
+    private_class_method :shot_attributes
+  end
+end

data/lib/nba/live_player_stat.rb

@@ -0,0 +1,276 @@
+module NBA
+  # Represents a player's live box score stats
+  class LivePlayerStat < Shale::Mapper
+    include Equalizer.new(:player_id, :game_id)
+
+    # @!attribute [rw] game_id
+    #   Returns the game ID
+    #   @api public
+    #   @example
+    #     stat.game_id #=> "0022400001"
+    #   @return [String] the game ID
+    attribute :game_id, Shale::Type::String
+
+    # @!attribute [rw] player_id
+    #   Returns the player ID
+    #   @api public
+    #   @example
+    #     stat.player_id #=> 201939
+    #   @return [Integer] the player ID
+    attribute :player_id, Shale::Type::Integer
+
+    # @!attribute [rw] name
+    #   Returns the player name
+    #   @api public
+    #   @example
+    #     stat.name #=> "Stephen Curry"
+    #   @return [String] the player name
+    attribute :name, Shale::Type::String
+
+    # @!attribute [rw] first_name
+    #   Returns the player's first name
+    #   @api public
+    #   @example
+    #     stat.first_name #=> "Stephen"
+    #   @return [String] the first name
+    attribute :first_name, Shale::Type::String
+
+    # @!attribute [rw] family_name
+    #   Returns the player's family name
+    #   @api public
+    #   @example
+    #     stat.family_name #=> "Curry"
+    #   @return [String] the family name
+    attribute :family_name, Shale::Type::String
+
+    # @!attribute [rw] jersey_num
+    #   Returns the jersey number
+    #   @api public
+    #   @example
+    #     stat.jersey_num #=> "30"
+    #   @return [String] the jersey number
+    attribute :jersey_num, Shale::Type::String
+
+    # @!attribute [rw] position
+    #   Returns the position
+    #   @api public
+    #   @example
+    #     stat.position #=> "G"
+    #   @return [String] the position
+    attribute :position, Shale::Type::String
+
+    # @!attribute [rw] team_id
+    #   Returns the team ID
+    #   @api public
+    #   @example
+    #     stat.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
+    #     stat.team_tricode #=> "GSW"
+    #   @return [String] the team tricode
+    attribute :team_tricode, Shale::Type::String
+
+    # @!attribute [rw] starter
+    #   Returns whether the player started
+    #   @api public
+    #   @example
+    #     stat.starter #=> "1"
+    #   @return [String] "1" if starter, "0" otherwise
+    attribute :starter, Shale::Type::String
+
+    # @!attribute [rw] minutes
+    #   Returns minutes played
+    #   @api public
+    #   @example
+    #     stat.minutes #=> "PT34M12S"
+    #   @return [String] minutes in ISO 8601 duration format
+    attribute :minutes, Shale::Type::String
+
+    # @!attribute [rw] points
+    #   Returns points scored
+    #   @api public
+    #   @example
+    #     stat.points #=> 28
+    #   @return [Integer] points
+    attribute :points, Shale::Type::Integer
+
+    # @!attribute [rw] rebounds_total
+    #   Returns total rebounds
+    #   @api public
+    #   @example
+    #     stat.rebounds_total #=> 7
+    #   @return [Integer] total rebounds
+    attribute :rebounds_total, Shale::Type::Integer
+
+    # @!attribute [rw] rebounds_offensive
+    #   Returns offensive rebounds
+    #   @api public
+    #   @example
+    #     stat.rebounds_offensive #=> 1
+    #   @return [Integer] offensive rebounds
+    attribute :rebounds_offensive, Shale::Type::Integer
+
+    # @!attribute [rw] rebounds_defensive
+    #   Returns defensive rebounds
+    #   @api public
+    #   @example
+    #     stat.rebounds_defensive #=> 6
+    #   @return [Integer] defensive rebounds
+    attribute :rebounds_defensive, Shale::Type::Integer
+
+    # @!attribute [rw] assists
+    #   Returns assists
+    #   @api public
+    #   @example
+    #     stat.assists #=> 8
+    #   @return [Integer] assists
+    attribute :assists, Shale::Type::Integer
+
+    # @!attribute [rw] steals
+    #   Returns steals
+    #   @api public
+    #   @example
+    #     stat.steals #=> 2
+    #   @return [Integer] steals
+    attribute :steals, Shale::Type::Integer
+
+    # @!attribute [rw] blocks
+    #   Returns blocks
+    #   @api public
+    #   @example
+    #     stat.blocks #=> 1
+    #   @return [Integer] blocks
+    attribute :blocks, Shale::Type::Integer
+
+    # @!attribute [rw] turnovers
+    #   Returns turnovers
+    #   @api public
+    #   @example
+    #     stat.turnovers #=> 3
+    #   @return [Integer] turnovers
+    attribute :turnovers, Shale::Type::Integer
+
+    # @!attribute [rw] fouls_personal
+    #   Returns personal fouls
+    #   @api public
+    #   @example
+    #     stat.fouls_personal #=> 2
+    #   @return [Integer] personal fouls
+    attribute :fouls_personal, Shale::Type::Integer
+
+    # @!attribute [rw] plus_minus
+    #   Returns plus/minus
+    #   @api public
+    #   @example
+    #     stat.plus_minus #=> 12.0
+    #   @return [Float] plus/minus
+    attribute :plus_minus, Shale::Type::Float
+
+    # @!attribute [rw] field_goals_made
+    #   Returns field goals made
+    #   @api public
+    #   @example
+    #     stat.field_goals_made #=> 10
+    #   @return [Integer] field goals made
+    attribute :field_goals_made, Shale::Type::Integer
+
+    # @!attribute [rw] field_goals_attempted
+    #   Returns field goals attempted
+    #   @api public
+    #   @example
+    #     stat.field_goals_attempted #=> 20
+    #   @return [Integer] field goals attempted
+    attribute :field_goals_attempted, Shale::Type::Integer
+
+    # @!attribute [rw] field_goals_percentage
+    #   Returns field goal percentage
+    #   @api public
+    #   @example
+    #     stat.field_goals_percentage #=> 0.5
+    #   @return [Float] field goal percentage
+    attribute :field_goals_percentage, Shale::Type::Float
+
+    # @!attribute [rw] three_pointers_made
+    #   Returns three-pointers made
+    #   @api public
+    #   @example
+    #     stat.three_pointers_made #=> 5
+    #   @return [Integer] three-pointers made
+    attribute :three_pointers_made, Shale::Type::Integer
+
+    # @!attribute [rw] three_pointers_attempted
+    #   Returns three-pointers attempted
+    #   @api public
+    #   @example
+    #     stat.three_pointers_attempted #=> 12
+    #   @return [Integer] three-pointers attempted
+    attribute :three_pointers_attempted, Shale::Type::Integer
+
+    # @!attribute [rw] three_pointers_percentage
+    #   Returns three-point percentage
+    #   @api public
+    #   @example
+    #     stat.three_pointers_percentage #=> 0.417
+    #   @return [Float] three-point percentage
+    attribute :three_pointers_percentage, Shale::Type::Float
+
+    # @!attribute [rw] free_throws_made
+    #   Returns free throws made
+    #   @api public
+    #   @example
+    #     stat.free_throws_made #=> 3
+    #   @return [Integer] free throws made
+    attribute :free_throws_made, Shale::Type::Integer
+
+    # @!attribute [rw] free_throws_attempted
+    #   Returns free throws attempted
+    #   @api public
+    #   @example
+    #     stat.free_throws_attempted #=> 3
+    #   @return [Integer] free throws attempted
+    attribute :free_throws_attempted, Shale::Type::Integer
+
+    # @!attribute [rw] free_throws_percentage
+    #   Returns free throw percentage
+    #   @api public
+    #   @example
+    #     stat.free_throws_percentage #=> 1.0
+    #   @return [Float] free throw percentage
+    attribute :free_throws_percentage, Shale::Type::Float
+
+    # Returns whether the player was a starter
+    #
+    # @api public
+    # @example
+    #   stat.starter? #=> true
+    # @return [Boolean] true if starter
+    def starter?
+      starter.eql?("1")
+    end
+
+    # Returns the player object
+    #
+    # @api public
+    # @example
+    #   stat.player #=> #<NBA::Player>
+    # @return [Player, nil] the player object
+    def player
+      Players.find(player_id)
+    end
+
+    # Returns the team object
+    #
+    # @api public
+    # @example
+    #   stat.team #=> #<NBA::Team>
+    # @return [Team, nil] the team object
+    def team
+      Teams.find(team_id)
+    end
+  end
+end