mlb 0.10.0 → 0.11.0

data/lib/mlb/attendance_record.rb

@@ -0,0 +1,157 @@
+require "equalizer"
+require "shale"
+require_relative "team"
+
+module MLB
+  # Represents an attendance record for a team
+  class AttendanceRecord < Shale::Mapper
+    include Equalizer.new(:team, :year)
+
+    # @!attribute [rw] year
+    #   Returns the year of the attendance record
+    #   @api public
+    #   @example
+    #     attendance_record.year #=> "2024"
+    #   @return [String] the year
+    attribute :year, Shale::Type::String
+
+    # @!attribute [rw] team
+    #   Returns the team
+    #   @api public
+    #   @example
+    #     attendance_record.team #=> #<MLB::Team>
+    #   @return [Team] the team
+    attribute :team, Team
+
+    # @!attribute [rw] openings_total
+    #   Returns the total number of openings
+    #   @api public
+    #   @example
+    #     attendance_record.openings_total #=> 160
+    #   @return [Integer] the total openings
+    attribute :openings_total, Shale::Type::Integer
+
+    # @!attribute [rw] openings_total_home
+    #   Returns the total home openings
+    #   @api public
+    #   @example
+    #     attendance_record.openings_total_home #=> 79
+    #   @return [Integer] the total home openings
+    attribute :openings_total_home, Shale::Type::Integer
+
+    # @!attribute [rw] openings_total_away
+    #   Returns the total away openings
+    #   @api public
+    #   @example
+    #     attendance_record.openings_total_away #=> 81
+    #   @return [Integer] the total away openings
+    attribute :openings_total_away, Shale::Type::Integer
+
+    # @!attribute [rw] games_total
+    #   Returns the total number of games
+    #   @api public
+    #   @example
+    #     attendance_record.games_total #=> 165
+    #   @return [Integer] the total games
+    attribute :games_total, Shale::Type::Integer
+
+    # @!attribute [rw] games_home_total
+    #   Returns the total home games
+    #   @api public
+    #   @example
+    #     attendance_record.games_home_total #=> 83
+    #   @return [Integer] the total home games
+    attribute :games_home_total, Shale::Type::Integer
+
+    # @!attribute [rw] games_away_total
+    #   Returns the total away games
+    #   @api public
+    #   @example
+    #     attendance_record.games_away_total #=> 82
+    #   @return [Integer] the total away games
+    attribute :games_away_total, Shale::Type::Integer
+
+    # @!attribute [rw] attendance_total
+    #   Returns the total attendance
+    #   @api public
+    #   @example
+    #     attendance_record.attendance_total #=> 5947960
+    #   @return [Integer] the total attendance
+    attribute :attendance_total, Shale::Type::Integer
+
+    # @!attribute [rw] attendance_total_home
+    #   Returns the total home attendance
+    #   @api public
+    #   @example
+    #     attendance_record.attendance_total_home #=> 3309838
+    #   @return [Integer] the total home attendance
+    attribute :attendance_total_home, Shale::Type::Integer
+
+    # @!attribute [rw] attendance_total_away
+    #   Returns the total away attendance
+    #   @api public
+    #   @example
+    #     attendance_record.attendance_total_away #=> 2638122
+    #   @return [Integer] the total away attendance
+    attribute :attendance_total_away, Shale::Type::Integer
+
+    # @!attribute [rw] attendance_average_home
+    #   Returns the average home attendance
+    #   @api public
+    #   @example
+    #     attendance_record.attendance_average_home #=> 41897
+    #   @return [Integer] the average home attendance
+    attribute :attendance_average_home, Shale::Type::Integer
+
+    # @!attribute [rw] attendance_average_away
+    #   Returns the average away attendance
+    #   @api public
+    #   @example
+    #     attendance_record.attendance_average_away #=> 32569
+    #   @return [Integer] the average away attendance
+    attribute :attendance_average_away, Shale::Type::Integer
+
+    # @!attribute [rw] attendance_average_ytd
+    #   Returns the average year-to-date attendance
+    #   @api public
+    #   @example
+    #     attendance_record.attendance_average_ytd #=> 37175
+    #   @return [Integer] the average YTD attendance
+    attribute :attendance_average_ytd, Shale::Type::Integer
+
+    # @!attribute [rw] attendance_high
+    #   Returns the highest single-game attendance
+    #   @api public
+    #   @example
+    #     attendance_record.attendance_high #=> 48760
+    #   @return [Integer] the highest attendance
+    attribute :attendance_high, Shale::Type::Integer
+
+    # @!attribute [rw] attendance_low
+    #   Returns the lowest single-game attendance
+    #   @api public
+    #   @example
+    #     attendance_record.attendance_low #=> 30060
+    #   @return [Integer] the lowest attendance
+    attribute :attendance_low, Shale::Type::Integer
+
+    json do
+      map "year", to: :year
+      map "team", to: :team
+      map "openingsTotal", to: :openings_total
+      map "openingsTotalHome", to: :openings_total_home
+      map "openingsTotalAway", to: :openings_total_away
+      map "gamesTotal", to: :games_total
+      map "gamesHomeTotal", to: :games_home_total
+      map "gamesAwayTotal", to: :games_away_total
+      map "attendanceTotal", to: :attendance_total
+      map "attendanceTotalHome", to: :attendance_total_home
+      map "attendanceTotalAway", to: :attendance_total_away
+      map "attendanceAverageHome", to: :attendance_average_home
+      map "attendanceAverageAway", to: :attendance_average_away
+      map "attendanceAverageYtd", to: :attendance_average_ytd
+      map "attendanceHigh", to: :attendance_high
+      map "attendanceLow", to: :attendance_low
+    end
+  end
+end

data/lib/mlb/award.rb

@@ -1,24 +1,101 @@
 require "equalizer"
 require "shale"
-require "uri"
+require_relative "comparable_by_attribute"
 require_relative "league"
 require_relative "sport"
 require_relative "player"
 
 module MLB
+  # Represents an MLB award with recipient and voting information
   class Award < Shale::Mapper
     include Comparable
+    include ComparableByAttribute
     include Equalizer.new(:id, :player, :season)
 
+    # Returns the attribute used for sorting
+    #
+    # @api private
+    # @return [Symbol] the attribute used for comparison
+    def comparable_attribute = :sort_order
+
+    # @!attribute [rw] id
+    #   Returns the unique identifier for the award
+    #   @api public
+    #   @example
+    #     award.id #=> "MLBHOF"
+    #   @return [String] the unique identifier for the award
     attribute :id, Shale::Type::String
+
+    # @!attribute [rw] name
+    #   Returns the name of the award
+    #   @api public
+    #   @example
+    #     award.name #=> "Hall of Fame"
+    #   @return [String] the name of the award
     attribute :name, Shale::Type::String
+
+    # @!attribute [rw] notes
+    #   Returns additional notes about the award
+    #   @api public
+    #   @example
+    #     award.notes #=> "First ballot"
+    #   @return [String] additional notes about the award
     attribute :notes, Shale::Type::String
+
+    # @!attribute [rw] votes
+    #   Returns the number of votes received
+    #   @api public
+    #   @example
+    #     award.votes #=> 393
+    #   @return [Integer] the number of votes received
     attribute :votes, Shale::Type::Integer
+
+    # @!attribute [rw] date
+    #   Returns the date the award was given
+    #   @api public
+    #   @example
+    #     award.date #=> #<Date: 2024-01-23>
+    #   @return [Date] the date the award was given
     attribute :date, Shale::Type::Date
+
+    # @!attribute [rw] season
+    #   Returns the season year for the award
+    #   @api public
+    #   @example
+    #     award.season #=> 2024
+    #   @return [Integer] the season year for the award
     attribute :season, Shale::Type::Integer
+
+    # @!attribute [rw] sport
+    #   Returns the sport associated with the award
+    #   @api public
+    #   @example
+    #     award.sport #=> #<MLB::Sport>
+    #   @return [Sport] the sport associated with the award
     attribute :sport, Sport
+
+    # @!attribute [rw] player
+    #   Returns the player who received the award
+    #   @api public
+    #   @example
+    #     award.player #=> #<MLB::Player>
+    #   @return [Player] the player who received the award
     attribute :player, Player
+
+    # @!attribute [rw] league
+    #   Returns the league associated with the award
+    #   @api public
+    #   @example
+    #     award.league #=> #<MLB::League>
+    #   @return [League] the league associated with the award
     attribute :league, League
+
+    # @!attribute [rw] sort_order
+    #   Returns the sort order for display
+    #   @api public
+    #   @example
+    #     award.sort_order #=> 1
+    #   @return [Integer] the sort order for display
     attribute :sort_order, Shale::Type::Integer
 
     json do
@@ -33,16 +110,17 @@ module MLB
       map "votes", to: :votes
     end
 
-    def <=>(other)
-      sort_order <=> other.sort_order
-    end
-
-    def recipients(season: Time.now.year)
-      params = {season:}
-      query_string = URI.encode_www_form(params)
-      response = CLIENT.get("awards/#{id}/recipients?#{query_string}")
-      awards = Awards.from_json(response)
-      awards.awards
+    # Retrieves recipients of this award for a given season
+    #
+    # @api public
+    # @example
+    #   award.recipients(season: 2024) #=> [#<MLB::Award>, ...]
+    # @param season [Integer, nil] the season year (defaults to current year)
+    # @return [Array<Award>] the list of awards with recipients
+    def recipients(season: nil)
+      season ||= Utils.current_season
+      response = CLIENT.get("awards/#{id}/recipients?#{Utils.build_query(season:)}")
+      Awards.from_json(response).awards
     end
   end
 end

data/lib/mlb/awards.rb

@@ -2,21 +2,31 @@ require "shale"
 require_relative "award"
 
 module MLB
+  # Provides methods for fetching MLB awards from the API
   class Awards < Shale::Mapper
-    attribute :copyright, Shale::Type::String
     attribute :awards, Award, collection: true
 
+    # Retrieves all awards
+    #
+    # @api public
+    # @example
+    #   MLB::Awards.all #=> [#<MLB::Award>, ...]
+    # @return [Array<Award>] the sorted list of awards
     def self.all
       response = CLIENT.get("awards")
-      awards = from_json(response)
-      awards.awards.sort!
+      from_json(response).awards.sort
     end
 
+    # Finds a single award by ID or Award object
+    #
+    # @api public
+    # @example
+    #   MLB::Awards.find("MLBHOF") #=> #<MLB::Award>
+    # @param award [Award, String] the award or award ID
+    # @return [Award, nil] the found award or nil
     def self.find(award)
-      id = award.respond_to?(:id) ? award.id : award
-      response = CLIENT.get("awards")
-      awards = from_json(response)
-      awards.awards.find { |a| a.id.eql?(id) }
+      target_id = Utils.extract_id(award)
+      all.find { |a| a.id.eql?(target_id) }
     end
   end
 end

data/lib/mlb/baseball_stat.rb

@@ -0,0 +1,65 @@
+require "equalizer"
+require "shale"
+
+module MLB
+  # Represents a baseball statistic type
+  class BaseballStat < Shale::Mapper
+    include Equalizer.new(:name)
+
+    # @!attribute [rw] name
+    #   Returns the internal identifier for the stat
+    #   @api public
+    #   @example
+    #     stat.name #=> "homeRuns"
+    #   @return [String] the internal identifier for the stat
+    attribute :name, Shale::Type::String
+
+    # @!attribute [rw] lookup_param
+    #   Returns the query parameter used in API requests
+    #   @api public
+    #   @example
+    #     stat.lookup_param #=> "hr"
+    #   @return [String] the query parameter used in API requests
+    attribute :lookup_param, Shale::Type::String
+
+    # @!attribute [rw] is_counting
+    #   Returns whether this is a counting stat
+    #   @api public
+    #   @example
+    #     stat.is_counting #=> true
+    #   @return [Boolean] whether this is a counting stat
+    attribute :is_counting, Shale::Type::Boolean
+
+    # @!attribute [rw] label
+    #   Returns the display label for the stat
+    #   @api public
+    #   @example
+    #     stat.label #=> "Home Runs"
+    #   @return [String] the display label for the stat
+    attribute :label, Shale::Type::String
+
+    # @!attribute [rw] stat_groups
+    #   Returns the applicable stat categories
+    #   @api public
+    #   @example
+    #     stat.stat_groups #=> [{"displayName"=>"hitting"}]
+    #   @return [Array<Hash>] the applicable stat categories
+    attribute :stat_groups, Shale::Type::Value, collection: true
+
+    # @!method counting?
+    #   Returns whether this is a counting stat
+    #   @api public
+    #   @example
+    #     stat.counting? #=> true
+    #   @return [Boolean, nil] true if this is a counting stat
+    alias_method :counting?, :is_counting
+
+    json do
+      map "name", to: :name
+      map "lookupParam", to: :lookup_param
+      map "isCounting", to: :is_counting
+      map "label", to: :label
+      map "statGroups", to: :stat_groups
+    end
+  end
+end

data/lib/mlb/baseball_stats.rb

@@ -0,0 +1,12 @@
+require_relative "collection"
+require_relative "baseball_stat"
+
+module MLB
+  # Provides methods for fetching baseball statistic types from the API
+  #
+  # @example Fetch all baseball stats
+  #   MLB::BaseballStats.all #=> [#<MLB::BaseballStat>, ...]
+  class BaseballStats < Collection
+    collection endpoint: "baseballStats", item_type: BaseballStat, collection_name: :stats
+  end
+end

data/lib/mlb/boxscore.rb

@@ -0,0 +1,81 @@
+require "shale"
+require_relative "team"
+require_relative "boxscore_team_stats"
+
+module MLB
+  # Represents one team's boxscore data
+  class BoxscoreTeam < Shale::Mapper
+    # @!attribute [rw] team
+    #   Returns the team
+    #   @api public
+    #   @example
+    #     boxscore_team.team #=> #<MLB::Team>
+    #   @return [Team] the team
+    attribute :team, Team
+
+    # @!attribute [rw] team_stats
+    #   Returns the team statistics
+    #   @api public
+    #   @example
+    #     boxscore_team.team_stats #=> #<MLB::BoxscoreTeamStats>
+    #   @return [BoxscoreTeamStats] the team stats
+    attribute :team_stats, BoxscoreTeamStats
+
+    json do
+      map "team", to: :team
+      map "teamStats", to: :team_stats
+    end
+  end
+
+  # Represents both teams in a boxscore
+  class BoxscoreTeams < Shale::Mapper
+    # @!attribute [rw] home
+    #   Returns the home team data
+    #   @api public
+    #   @example
+    #     boxscore_teams.home #=> #<MLB::BoxscoreTeam>
+    #   @return [BoxscoreTeam] the home team
+    attribute :home, BoxscoreTeam
+
+    # @!attribute [rw] away
+    #   Returns the away team data
+    #   @api public
+    #   @example
+    #     boxscore_teams.away #=> #<MLB::BoxscoreTeam>
+    #   @return [BoxscoreTeam] the away team
+    attribute :away, BoxscoreTeam
+
+    json do
+      map "home", to: :home
+      map "away", to: :away
+    end
+  end
+
+  # Represents a game's boxscore
+  class Boxscore < Shale::Mapper
+    # @!attribute [rw] teams
+    #   Returns the teams data
+    #   @api public
+    #   @example
+    #     boxscore.teams #=> #<MLB::BoxscoreTeams>
+    #   @return [BoxscoreTeams] the teams
+    attribute :teams, BoxscoreTeams
+
+    json do
+      map "teams", to: :teams
+    end
+
+    # Retrieves the boxscore for a game
+    #
+    # @api public
+    # @example Get boxscore for a game
+    #   MLB::Boxscore.find(game: 745726)
+    # @param game [ScheduledGame, Integer] the game or game PK
+    # @return [Boxscore] the boxscore
+    def self.find(game:)
+      game_pk = game.respond_to?(:game_pk) ? game.game_pk : game
+      response = CLIENT.get("game/#{game_pk}/boxscore")
+      from_json(response)
+    end
+  end
+end

data/lib/mlb/boxscore_team_stats.rb

@@ -0,0 +1,210 @@
+require "shale"
+
+module MLB
+  # Represents batting statistics for a team in a boxscore
+  class BoxscoreBattingStats < Shale::Mapper
+    # @!attribute [rw] runs
+    #   Returns the runs scored
+    #   @api public
+    #   @example
+    #     stats.runs #=> 8
+    #   @return [Integer] the runs
+    attribute :runs, Shale::Type::Integer
+
+    # @!attribute [rw] hits
+    #   Returns the hits
+    #   @api public
+    #   @example
+    #     stats.hits #=> 9
+    #   @return [Integer] the hits
+    attribute :hits, Shale::Type::Integer
+
+    # @!attribute [rw] doubles
+    #   Returns the doubles
+    #   @api public
+    #   @example
+    #     stats.doubles #=> 2
+    #   @return [Integer] the doubles
+    attribute :doubles, Shale::Type::Integer
+
+    # @!attribute [rw] triples
+    #   Returns the triples
+    #   @api public
+    #   @example
+    #     stats.triples #=> 1
+    #   @return [Integer] the triples
+    attribute :triples, Shale::Type::Integer
+
+    # @!attribute [rw] home_runs
+    #   Returns the home runs
+    #   @api public
+    #   @example
+    #     stats.home_runs #=> 3
+    #   @return [Integer] the home runs
+    attribute :home_runs, Shale::Type::Integer
+
+    # @!attribute [rw] strike_outs
+    #   Returns the strikeouts
+    #   @api public
+    #   @example
+    #     stats.strike_outs #=> 10
+    #   @return [Integer] the strikeouts
+    attribute :strike_outs, Shale::Type::Integer
+
+    # @!attribute [rw] base_on_balls
+    #   Returns the walks
+    #   @api public
+    #   @example
+    #     stats.base_on_balls #=> 3
+    #   @return [Integer] the walks
+    attribute :base_on_balls, Shale::Type::Integer
+
+    # @!attribute [rw] at_bats
+    #   Returns the at-bats
+    #   @api public
+    #   @example
+    #     stats.at_bats #=> 36
+    #   @return [Integer] the at-bats
+    attribute :at_bats, Shale::Type::Integer
+
+    # @!attribute [rw] avg
+    #   Returns the batting average
+    #   @api public
+    #   @example
+    #     stats.avg #=> ".227"
+    #   @return [String] the batting average
+    attribute :avg, Shale::Type::String
+
+    # @!attribute [rw] rbi
+    #   Returns the runs batted in
+    #   @api public
+    #   @example
+    #     stats.rbi #=> 8
+    #   @return [Integer] the RBI
+    attribute :rbi, Shale::Type::Integer
+
+    # @!attribute [rw] left_on_base
+    #   Returns runners left on base
+    #   @api public
+    #   @example
+    #     stats.left_on_base #=> 11
+    #   @return [Integer] the left on base
+    attribute :left_on_base, Shale::Type::Integer
+
+    json do
+      map "runs", to: :runs
+      map "hits", to: :hits
+      map "doubles", to: :doubles
+      map "triples", to: :triples
+      map "homeRuns", to: :home_runs
+      map "strikeOuts", to: :strike_outs
+      map "baseOnBalls", to: :base_on_balls
+      map "atBats", to: :at_bats
+      map "avg", to: :avg
+      map "rbi", to: :rbi
+      map "leftOnBase", to: :left_on_base
+    end
+  end
+
+  # Represents pitching statistics for a team in a boxscore
+  class BoxscorePitchingStats < Shale::Mapper
+    # @!attribute [rw] runs
+    #   Returns runs allowed
+    #   @api public
+    #   @example
+    #     stats.runs #=> 4
+    #   @return [Integer] the runs
+    attribute :runs, Shale::Type::Integer
+
+    # @!attribute [rw] earned_runs
+    #   Returns earned runs allowed
+    #   @api public
+    #   @example
+    #     stats.earned_runs #=> 4
+    #   @return [Integer] the earned runs
+    attribute :earned_runs, Shale::Type::Integer
+
+    # @!attribute [rw] hits
+    #   Returns hits allowed
+    #   @api public
+    #   @example
+    #     stats.hits #=> 7
+    #   @return [Integer] the hits
+    attribute :hits, Shale::Type::Integer
+
+    # @!attribute [rw] home_runs
+    #   Returns home runs allowed
+    #   @api public
+    #   @example
+    #     stats.home_runs #=> 3
+    #   @return [Integer] the home runs
+    attribute :home_runs, Shale::Type::Integer
+
+    # @!attribute [rw] strike_outs
+    #   Returns strikeouts
+    #   @api public
+    #   @example
+    #     stats.strike_outs #=> 6
+    #   @return [Integer] the strikeouts
+    attribute :strike_outs, Shale::Type::Integer
+
+    # @!attribute [rw] base_on_balls
+    #   Returns walks
+    #   @api public
+    #   @example
+    #     stats.base_on_balls #=> 3
+    #   @return [Integer] the walks
+    attribute :base_on_balls, Shale::Type::Integer
+
+    # @!attribute [rw] innings_pitched
+    #   Returns innings pitched
+    #   @api public
+    #   @example
+    #     stats.innings_pitched #=> "9.0"
+    #   @return [String] the innings pitched
+    attribute :innings_pitched, Shale::Type::String
+
+    # @!attribute [rw] era
+    #   Returns the earned run average
+    #   @api public
+    #   @example
+    #     stats.era #=> "3.84"
+    #   @return [String] the ERA
+    attribute :era, Shale::Type::String
+
+    json do
+      map "runs", to: :runs
+      map "earnedRuns", to: :earned_runs
+      map "hits", to: :hits
+      map "homeRuns", to: :home_runs
+      map "strikeOuts", to: :strike_outs
+      map "baseOnBalls", to: :base_on_balls
+      map "inningsPitched", to: :innings_pitched
+      map "era", to: :era
+    end
+  end
+
+  # Represents team statistics in a boxscore
+  class BoxscoreTeamStats < Shale::Mapper
+    # @!attribute [rw] batting
+    #   Returns batting statistics
+    #   @api public
+    #   @example
+    #     team_stats.batting #=> #<MLB::BoxscoreBattingStats>
+    #   @return [BoxscoreBattingStats] the batting stats
+    attribute :batting, BoxscoreBattingStats
+
+    # @!attribute [rw] pitching
+    #   Returns pitching statistics
+    #   @api public
+    #   @example
+    #     team_stats.pitching #=> #<MLB::BoxscorePitchingStats>
+    #   @return [BoxscorePitchingStats] the pitching stats
+    attribute :pitching, BoxscorePitchingStats
+
+    json do
+      map "batting", to: :batting
+      map "pitching", to: :pitching
+    end
+  end
+end