mlb 0.9.0 → 0.11.0

data/lib/mlb/player.rb

@@ -1,35 +1,220 @@
+require "equalizer"
 require "shale"
 require_relative "position"
 require_relative "handedness"
 require_relative "team"
 
 module MLB
+  # Represents an MLB player with biographical and career information
   class Player < Shale::Mapper
+    include Equalizer.new(:id)
+
+    # @!attribute [rw] id
+    #   Returns the unique identifier for the player
+    #   @api public
+    #   @example
+    #     player.id #=> 660271
+    #   @return [Integer] the unique identifier for the player
     attribute :id, Shale::Type::Integer
+
+    # @!attribute [rw] full_name
+    #   Returns the player's full name
+    #   @api public
+    #   @example
+    #     player.full_name #=> "Shohei Ohtani"
+    #   @return [String] the player's full name
     attribute :full_name, Shale::Type::String
+
+    # @!attribute [rw] link
+    #   Returns the API link for the player
+    #   @api public
+    #   @example
+    #     player.link #=> "/api/v1/people/660271"
+    #   @return [String] the API link for the player
     attribute :link, Shale::Type::String
+
+    # @!attribute [rw] first_name
+    #   Returns the player's first name
+    #   @api public
+    #   @example
+    #     player.first_name #=> "Shohei"
+    #   @return [String] the player's first name
     attribute :first_name, Shale::Type::String
+
+    # @!attribute [rw] last_name
+    #   Returns the player's last name
+    #   @api public
+    #   @example
+    #     player.last_name #=> "Ohtani"
+    #   @return [String] the player's last name
     attribute :last_name, Shale::Type::String
+
+    # @!attribute [rw] primary_number
+    #   Returns the player's primary jersey number
+    #   @api public
+    #   @example
+    #     player.primary_number #=> 17
+    #   @return [Integer] the player's primary jersey number
     attribute :primary_number, Shale::Type::Integer
+
+    # @!attribute [rw] birth_date
+    #   Returns the player's date of birth
+    #   @api public
+    #   @example
+    #     player.birth_date #=> #<Date: 1994-07-05>
+    #   @return [Date] the player's date of birth
     attribute :birth_date, Shale::Type::Date
+
+    # @!attribute [rw] current_age
+    #   Returns the player's current age
+    #   @api public
+    #   @example
+    #     player.current_age #=> 30
+    #   @return [Integer] the player's current age
     attribute :current_age, Shale::Type::Integer
+
+    # @!attribute [rw] birth_city
+    #   Returns the player's birth city
+    #   @api public
+    #   @example
+    #     player.birth_city #=> "Oshu"
+    #   @return [String] the player's birth city
     attribute :birth_city, Shale::Type::String
+
+    # @!attribute [rw] birth_state_province
+    #   Returns the player's birth state or province
+    #   @api public
+    #   @example
+    #     player.birth_state_province #=> "Iwate"
+    #   @return [String] the player's birth state or province
     attribute :birth_state_province, Shale::Type::String
+
+    # @!attribute [rw] birth_country
+    #   Returns the player's birth country
+    #   @api public
+    #   @example
+    #     player.birth_country #=> "Japan"
+    #   @return [String] the player's birth country
     attribute :birth_country, Shale::Type::String
+
+    # @!attribute [rw] height
+    #   Returns the player's height
+    #   @api public
+    #   @example
+    #     player.height #=> "6' 4\""
+    #   @return [String] the player's height
     attribute :height, Shale::Type::String
+
+    # @!attribute [rw] weight
+    #   Returns the player's weight in pounds
+    #   @api public
+    #   @example
+    #     player.weight #=> 210
+    #   @return [Integer] the player's weight in pounds
     attribute :weight, Shale::Type::Integer
+
+    # @!attribute [rw] active
+    #   Returns whether the player is currently active
+    #   @api public
+    #   @example
+    #     player.active #=> true
+    #   @return [Boolean] whether the player is currently active
     attribute :active, Shale::Type::Boolean
+
+    # @!attribute [rw] current_team
+    #   Returns the player's current team
+    #   @api public
+    #   @example
+    #     player.current_team #=> #<MLB::Team>
+    #   @return [Team] the player's current team
     attribute :current_team, Team
+
+    # @!attribute [rw] primary_position
+    #   Returns the player's primary position
+    #   @api public
+    #   @example
+    #     player.primary_position #=> #<MLB::Position>
+    #   @return [Position] the player's primary position
     attribute :primary_position, Position
+
+    # @!attribute [rw] use_name
+    #   Returns the player's preferred name
+    #   @api public
+    #   @example
+    #     player.use_name #=> "Shohei"
+    #   @return [String] the player's preferred name
     attribute :use_name, Shale::Type::String
+
+    # @!attribute [rw] middle_name
+    #   Returns the player's middle name
+    #   @api public
+    #   @example
+    #     player.middle_name #=> "James"
+    #   @return [String] the player's middle name
     attribute :middle_name, Shale::Type::String
+
+    # @!attribute [rw] boxscore_name
+    #   Returns the player's name as displayed in boxscores
+    #   @api public
+    #   @example
+    #     player.boxscore_name #=> "Ohtani"
+    #   @return [String] the player's name as displayed in boxscores
     attribute :boxscore_name, Shale::Type::String
+
+    # @!attribute [rw] gender
+    #   Returns the player's gender
+    #   @api public
+    #   @example
+    #     player.gender #=> "M"
+    #   @return [String] the player's gender
     attribute :gender, Shale::Type::String
+
+    # @!attribute [rw] is_player
+    #   Returns whether the person is a player
+    #   @api public
+    #   @example
+    #     player.is_player #=> true
+    #   @return [Boolean] whether the person is a player
     attribute :is_player, Shale::Type::Boolean
+
+    # @!attribute [rw] is_verified
+    #   Returns whether the player's information is verified
+    #   @api public
+    #   @example
+    #     player.is_verified #=> true
+    #   @return [Boolean] whether the player's information is verified
     attribute :is_verified, Shale::Type::Boolean
+
+    # @!attribute [rw] draft_year
+    #   Returns the year the player was drafted
+    #   @api public
+    #   @example
+    #     player.draft_year #=> 2018
+    #   @return [Integer] the year the player was drafted
     attribute :draft_year, Shale::Type::Integer
+
+    # @!attribute [rw] mlb_debut_date
+    #   Returns the date of the player's MLB debut
+    #   @api public
+    #   @example
+    #     player.mlb_debut_date #=> #<Date: 2018-03-29>
+    #   @return [Date] the date of the player's MLB debut
     attribute :mlb_debut_date, Shale::Type::Date
+
+    # @!attribute [rw] bat_side
+    #   Returns the player's batting side
+    #   @api public
+    #   @example
+    #     player.bat_side #=> #<MLB::Handedness>
+    #   @return [Handedness] the player's batting side
     attribute :bat_side, Handedness
+
+    # @!attribute [rw] pitch_hand
+    #   Returns the player's pitching hand
+    #   @api public
+    #   @example
+    #     player.pitch_hand #=> #<MLB::Handedness>
+    #   @return [Handedness] the player's pitching hand
     attribute :pitch_hand, Handedness
 
     alias_method :verified?, :is_verified
@@ -39,6 +224,7 @@ module MLB
     json do
       map "id", to: :id
       map "fullName", to: :full_name
+      map "nameFirstLast", to: :full_name
       map "link", to: :link
       map "firstName", to: :first_name
       map "lastName", to: :last_name

data/lib/mlb/player_game_stats.rb

@@ -0,0 +1,350 @@
+require "shale"
+require_relative "player"
+require_relative "team"
+
+module MLB
+  # Represents a player's batting stats for a game
+  class PlayerGameBattingStats < Shale::Mapper
+    # @!attribute [rw] games_played
+    #   Returns games played
+    #   @api public
+    #   @example
+    #     stats.games_played #=> 1
+    #   @return [Integer] games played
+    attribute :games_played, Shale::Type::Integer
+
+    # @!attribute [rw] at_bats
+    #   Returns at bats
+    #   @api public
+    #   @example
+    #     stats.at_bats #=> 4
+    #   @return [Integer] at bats
+    attribute :at_bats, Shale::Type::Integer
+
+    # @!attribute [rw] runs
+    #   Returns runs scored
+    #   @api public
+    #   @example
+    #     stats.runs #=> 1
+    #   @return [Integer] runs
+    attribute :runs, Shale::Type::Integer
+
+    # @!attribute [rw] hits
+    #   Returns hits
+    #   @api public
+    #   @example
+    #     stats.hits #=> 2
+    #   @return [Integer] hits
+    attribute :hits, Shale::Type::Integer
+
+    # @!attribute [rw] doubles
+    #   Returns doubles
+    #   @api public
+    #   @example
+    #     stats.doubles #=> 1
+    #   @return [Integer] doubles
+    attribute :doubles, Shale::Type::Integer
+
+    # @!attribute [rw] triples
+    #   Returns triples
+    #   @api public
+    #   @example
+    #     stats.triples #=> 0
+    #   @return [Integer] triples
+    attribute :triples, Shale::Type::Integer
+
+    # @!attribute [rw] home_runs
+    #   Returns home runs
+    #   @api public
+    #   @example
+    #     stats.home_runs #=> 1
+    #   @return [Integer] home runs
+    attribute :home_runs, Shale::Type::Integer
+
+    # @!attribute [rw] rbi
+    #   Returns RBIs
+    #   @api public
+    #   @example
+    #     stats.rbi #=> 3
+    #   @return [Integer] RBIs
+    attribute :rbi, Shale::Type::Integer
+
+    # @!attribute [rw] stolen_bases
+    #   Returns stolen bases
+    #   @api public
+    #   @example
+    #     stats.stolen_bases #=> 0
+    #   @return [Integer] stolen bases
+    attribute :stolen_bases, Shale::Type::Integer
+
+    # @!attribute [rw] base_on_balls
+    #   Returns walks
+    #   @api public
+    #   @example
+    #     stats.base_on_balls #=> 1
+    #   @return [Integer] walks
+    attribute :base_on_balls, Shale::Type::Integer
+
+    # @!attribute [rw] strike_outs
+    #   Returns strikeouts
+    #   @api public
+    #   @example
+    #     stats.strike_outs #=> 1
+    #   @return [Integer] strikeouts
+    attribute :strike_outs, Shale::Type::Integer
+
+    json do
+      map "gamesPlayed", to: :games_played
+      map "atBats", to: :at_bats
+      map "runs", to: :runs
+      map "hits", to: :hits
+      map "doubles", to: :doubles
+      map "triples", to: :triples
+      map "homeRuns", to: :home_runs
+      map "rbi", to: :rbi
+      map "stolenBases", to: :stolen_bases
+      map "baseOnBalls", to: :base_on_balls
+      map "strikeOuts", to: :strike_outs
+    end
+  end
+
+  # Represents a player's pitching stats for a game
+  class PlayerGamePitchingStats < Shale::Mapper
+    # @!attribute [rw] games_played
+    #   Returns games played
+    #   @api public
+    #   @example
+    #     stats.games_played #=> 1
+    #   @return [Integer] games played
+    attribute :games_played, Shale::Type::Integer
+
+    # @!attribute [rw] games_started
+    #   Returns games started
+    #   @api public
+    #   @example
+    #     stats.games_started #=> 1
+    #   @return [Integer] games started
+    attribute :games_started, Shale::Type::Integer
+
+    # @!attribute [rw] wins
+    #   Returns wins
+    #   @api public
+    #   @example
+    #     stats.wins #=> 1
+    #   @return [Integer] wins
+    attribute :wins, Shale::Type::Integer
+
+    # @!attribute [rw] losses
+    #   Returns losses
+    #   @api public
+    #   @example
+    #     stats.losses #=> 0
+    #   @return [Integer] losses
+    attribute :losses, Shale::Type::Integer
+
+    # @!attribute [rw] saves
+    #   Returns saves
+    #   @api public
+    #   @example
+    #     stats.saves #=> 0
+    #   @return [Integer] saves
+    attribute :saves, Shale::Type::Integer
+
+    # @!attribute [rw] innings_pitched
+    #   Returns innings pitched
+    #   @api public
+    #   @example
+    #     stats.innings_pitched #=> "7.0"
+    #   @return [String] innings pitched
+    attribute :innings_pitched, Shale::Type::String
+
+    # @!attribute [rw] hits
+    #   Returns hits allowed
+    #   @api public
+    #   @example
+    #     stats.hits #=> 5
+    #   @return [Integer] hits allowed
+    attribute :hits, Shale::Type::Integer
+
+    # @!attribute [rw] runs
+    #   Returns runs allowed
+    #   @api public
+    #   @example
+    #     stats.runs #=> 2
+    #   @return [Integer] runs allowed
+    attribute :runs, Shale::Type::Integer
+
+    # @!attribute [rw] earned_runs
+    #   Returns earned runs
+    #   @api public
+    #   @example
+    #     stats.earned_runs #=> 2
+    #   @return [Integer] earned runs
+    attribute :earned_runs, Shale::Type::Integer
+
+    # @!attribute [rw] home_runs
+    #   Returns home runs allowed
+    #   @api public
+    #   @example
+    #     stats.home_runs #=> 1
+    #   @return [Integer] home runs allowed
+    attribute :home_runs, Shale::Type::Integer
+
+    # @!attribute [rw] base_on_balls
+    #   Returns walks
+    #   @api public
+    #   @example
+    #     stats.base_on_balls #=> 2
+    #   @return [Integer] walks
+    attribute :base_on_balls, Shale::Type::Integer
+
+    # @!attribute [rw] strike_outs
+    #   Returns strikeouts
+    #   @api public
+    #   @example
+    #     stats.strike_outs #=> 8
+    #   @return [Integer] strikeouts
+    attribute :strike_outs, Shale::Type::Integer
+
+    # @!attribute [rw] number_of_pitches
+    #   Returns pitch count
+    #   @api public
+    #   @example
+    #     stats.number_of_pitches #=> 95
+    #   @return [Integer] pitch count
+    attribute :number_of_pitches, Shale::Type::Integer
+
+    json do
+      map "gamesPlayed", to: :games_played
+      map "gamesStarted", to: :games_started
+      map "wins", to: :wins
+      map "losses", to: :losses
+      map "saves", to: :saves
+      map "inningsPitched", to: :innings_pitched
+      map "hits", to: :hits
+      map "runs", to: :runs
+      map "earnedRuns", to: :earned_runs
+      map "homeRuns", to: :home_runs
+      map "baseOnBalls", to: :base_on_balls
+      map "strikeOuts", to: :strike_outs
+      map "numberOfPitches", to: :number_of_pitches
+    end
+  end
+
+  # Represents a player's stat split for a game
+  class PlayerGameStatSplit < Shale::Mapper
+    # @!attribute [rw] stat
+    #   Returns the batting stats
+    #   @api public
+    #   @example
+    #     split.stat #=> #<MLB::PlayerGameBattingStats>
+    #   @return [PlayerGameBattingStats, PlayerGamePitchingStats] the stats
+    attribute :stat, Shale::Type::Value
+
+    # @!attribute [rw] team
+    #   Returns the team
+    #   @api public
+    #   @example
+    #     split.team #=> #<MLB::Team>
+    #   @return [Team] the team
+    attribute :team, Team
+
+    # @!attribute [rw] player
+    #   Returns the player
+    #   @api public
+    #   @example
+    #     split.player #=> #<MLB::Player>
+    #   @return [Player] the player
+    attribute :player, Player
+
+    json do
+      map "stat", to: :stat
+      map "team", to: :team
+      map "player", to: :player
+    end
+  end
+
+  # Represents a stat group for a player's game
+  class PlayerGameStatGroup < Shale::Mapper
+    # @!attribute [rw] group
+    #   Returns the stat group name
+    #   @api public
+    #   @example
+    #     group.group #=> "hitting"
+    #   @return [String] the group name
+    attribute :group, Shale::Type::String
+
+    # @!attribute [rw] splits
+    #   Returns the stat splits
+    #   @api public
+    #   @example
+    #     group.splits #=> [#<MLB::PlayerGameStatSplit>, ...]
+    #   @return [Array<PlayerGameStatSplit>] the splits
+    attribute :splits, PlayerGameStatSplit, collection: true
+
+    json do
+      map "group", to: :group
+      map "splits", to: :splits
+    end
+  end
+
+  # Provides methods for fetching player game stats from the API
+  class PlayerGameStats < Shale::Mapper
+    # @!attribute [rw] stats
+    #   Returns the stat groups
+    #   @api public
+    #   @example
+    #     stats.stats #=> [#<MLB::PlayerGameStatGroup>, ...]
+    #   @return [Array<PlayerGameStatGroup>] the stat groups
+    attribute :stats, PlayerGameStatGroup, collection: true
+
+    json do
+      map "stats", to: :stats
+    end
+
+    # Retrieves a player's stats for a specific game
+    #
+    # @api public
+    # @example Get player stats for a game
+    #   MLB::PlayerGameStats.find(player: 660271, game: 745571)
+    # @example Get stats using Player and ScheduledGame objects
+    #   MLB::PlayerGameStats.find(player: player, game: game)
+    # @param player [Integer, Player] the player ID or player object
+    # @param game [Integer, ScheduledGame] the game ID or game object
+    # @return [PlayerGameStats] the player's game stats
+    def self.find(player:, game:)
+      player_id = Utils.extract_id(player)
+      game_pk = game.respond_to?(:game_pk) ? game.game_pk : game
+      response = CLIENT.get("people/#{player_id}/stats/game/#{game_pk}")
+      from_json(response)
+    end
+
+    # Returns the batting stats from the response
+    #
+    # @api public
+    # @example Get batting stats
+    #   stats.batting #=> #<MLB::PlayerGameBattingStats>
+    # @return [PlayerGameBattingStats, nil] the batting stats
+    def batting
+      batting_group = stats.find { |s| s.group.eql?("hitting") }
+      split = batting_group&.splits&.first
+      return nil unless split
+
+      PlayerGameBattingStats.from_json(split.stat.to_json)
+    end
+
+    # Returns the pitching stats from the response
+    #
+    # @api public
+    # @example Get pitching stats
+    #   stats.pitching #=> #<MLB::PlayerGamePitchingStats>
+    # @return [PlayerGamePitchingStats, nil] the pitching stats
+    def pitching
+      pitching_group = stats.find { |s| s.group.eql?("pitching") }
+      split = pitching_group&.splits&.first
+      return nil unless split
+
+      PlayerGamePitchingStats.from_json(split.stat.to_json)
+    end
+  end
+end

data/lib/mlb/player_stat.rb

@@ -0,0 +1,70 @@
+require "equalizer"
+require "shale"
+require_relative "stat_values"
+require_relative "player"
+require_relative "team"
+require_relative "position"
+
+module MLB
+  # Represents a player stat split
+  class PlayerStat < Shale::Mapper
+    include Equalizer.new(:player, :rank)
+
+    # @!attribute [rw] season
+    #   Returns the season for this stat split
+    #   @api public
+    #   @example
+    #     player_stat.season #=> "2024"
+    #   @return [String] the season
+    attribute :season, Shale::Type::String
+
+    # @!attribute [rw] stat
+    #   Returns the stat values
+    #   @api public
+    #   @example
+    #     player_stat.stat.home_runs #=> 54
+    #   @return [StatValues] the stat values
+    attribute :stat, StatValues
+
+    # @!attribute [rw] player
+    #   Returns the player
+    #   @api public
+    #   @example
+    #     player_stat.player.name #=> "Aaron Judge"
+    #   @return [Player] the player
+    attribute :player, Player
+
+    # @!attribute [rw] team
+    #   Returns the team
+    #   @api public
+    #   @example
+    #     player_stat.team.name #=> "New York Yankees"
+    #   @return [Team] the team
+    attribute :team, Team
+
+    # @!attribute [rw] rank
+    #   Returns the rank in the stat leaderboard
+    #   @api public
+    #   @example
+    #     player_stat.rank #=> 1
+    #   @return [Integer] the rank
+    attribute :rank, Shale::Type::Integer
+
+    # @!attribute [rw] position
+    #   Returns the player's position
+    #   @api public
+    #   @example
+    #     player_stat.position.abbreviation #=> "RF"
+    #   @return [Position] the position
+    attribute :position, Position
+
+    json do
+      map "season", to: :season
+      map "stat", to: :stat
+      map "player", to: :player
+      map "team", to: :team
+      map "rank", to: :rank
+      map "position", to: :position
+    end
+  end
+end