mlb 0.9.0 → 0.11.0

data/lib/mlb/award.rb

@@ -0,0 +1,126 @@
+require "equalizer"
+require "shale"
+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
+      map "id", to: :id
+      map "name", to: :name
+      map "sport", to: :sport
+      map "league", to: :league
+      map "player", to: :player
+      map "sortOrder", to: :sort_order
+      map "season", to: :season
+      map "notes", to: :notes
+      map "votes", to: :votes
+    end
+
+    # 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

@@ -0,0 +1,32 @@
+require "shale"
+require_relative "award"
+
+module MLB
+  # Provides methods for fetching MLB awards from the API
+  class Awards < Shale::Mapper
+    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")
+      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)
+      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

data/lib/mlb/client.rb

@@ -5,18 +5,46 @@ require_relative "request_builder"
 require_relative "error_handler"
 
 module MLB
+  # HTTP client for making requests to the MLB Stats API
   class Client
     extend Forwardable
 
+    # Default base URL for the MLB Stats API
     DEFAULT_BASE_URL = "https://statsapi.mlb.com/api/v1/".freeze
 
+    # Returns the base URL for API requests
+    #
+    # @api public
+    # @example
+    #   client.base_url #=> "https://statsapi.mlb.com/api/v1/"
+    # @return [String] the base URL for API requests
     attr_accessor :base_url
 
+    # @!method base_url=(value)
+    #   Sets the base URL for API requests
+    #   @api public
+    #   @example
+    #     client.base_url = "https://example.com/api/"
+    #   @param value [String] the base URL for API requests
+    #   @return [String] the base URL for API requests
+
     def_delegators :@connection, :open_timeout, :read_timeout, :write_timeout, :proxy_url, :debug_output
     def_delegators :@connection, :open_timeout=, :read_timeout=, :write_timeout=, :proxy_url=, :debug_output=
     def_delegators :@redirect_handler, :max_redirects
     def_delegators :@redirect_handler, :max_redirects=
 
+    # Initializes a new Client instance
+    #
+    # @api public
+    # @example
+    #   client = MLB::Client.new
+    # @param base_url [String] the base URL for API requests
+    # @param open_timeout [Integer] the connection open timeout in seconds
+    # @param read_timeout [Integer] the read timeout in seconds
+    # @param write_timeout [Integer] the write timeout in seconds
+    # @param debug_output [IO] the IO object for debug output
+    # @param proxy_url [String, nil] the proxy URL
+    # @param max_redirects [Integer] the maximum number of redirects to follow
     def initialize(base_url: DEFAULT_BASE_URL,
       open_timeout: Connection::DEFAULT_OPEN_TIMEOUT,
       read_timeout: Connection::DEFAULT_READ_TIMEOUT,
@@ -24,7 +52,6 @@ module MLB
       debug_output: Connection::DEFAULT_DEBUG_OUTPUT,
       proxy_url: nil,
       max_redirects: RedirectHandler::DEFAULT_MAX_REDIRECTS)
-
       @base_url = base_url
       @connection = Connection.new(open_timeout:, read_timeout:, write_timeout:, debug_output:, proxy_url:)
       @request_builder = RequestBuilder.new
@@ -32,24 +59,66 @@ module MLB
       @error_handler = ErrorHandler.new
     end
 
+    # Performs a GET request
+    #
+    # @api public
+    # @example
+    #   client.get("teams")
+    # @param endpoint [String] the API endpoint
+    # @param headers [Hash] optional HTTP headers
+    # @return [String, nil] the response body
     def get(endpoint, headers: {})
       execute_request(:get, endpoint, headers:)
     end
 
+    # Performs a POST request
+    #
+    # @api public
+    # @example
+    #   client.post("endpoint", '{"key": "value"}')
+    # @param endpoint [String] the API endpoint
+    # @param body [String, nil] the request body
+    # @param headers [Hash] optional HTTP headers
+    # @return [String, nil] the response body
     def post(endpoint, body = nil, headers: {})
       execute_request(:post, endpoint, body:, headers:)
     end
 
+    # Performs a PUT request
+    #
+    # @api public
+    # @example
+    #   client.put("endpoint", '{"key": "value"}')
+    # @param endpoint [String] the API endpoint
+    # @param body [String, nil] the request body
+    # @param headers [Hash] optional HTTP headers
+    # @return [String, nil] the response body
     def put(endpoint, body = nil, headers: {})
       execute_request(:put, endpoint, body:, headers:)
     end
 
+    # Performs a DELETE request
+    #
+    # @api public
+    # @example
+    #   client.delete("endpoint")
+    # @param endpoint [String] the API endpoint
+    # @param headers [Hash] optional HTTP headers
+    # @return [String, nil] the response body
     def delete(endpoint, headers: {})
       execute_request(:delete, endpoint, headers:)
     end
 
     private
 
+    # Executes an HTTP request
+    #
+    # @api private
+    # @param http_method [Symbol] the HTTP method
+    # @param endpoint [String] the API endpoint
+    # @param headers [Hash] HTTP headers
+    # @param body [String, nil] the request body
+    # @return [String, nil] the response body
     def execute_request(http_method, endpoint, headers:, body: nil)
       uri = URI.join(base_url, endpoint)
       request = @request_builder.build(http_method:, uri:, body:, headers:)
@@ -59,5 +128,6 @@ module MLB
     end
   end
 
+  # Default client instance
   CLIENT = Client.new
 end

data/lib/mlb/coaches.rb

@@ -0,0 +1,28 @@
+require "shale"
+require_relative "job"
+
+module MLB
+  # Provides methods for fetching team coaching staff from the API
+  class Coaches < Shale::Mapper
+    attribute :roster, Job, collection: true
+
+    json do
+      map "roster", to: :roster
+    end
+
+    # Retrieves coaches for a team
+    #
+    # @api public
+    # @example Get coaches for a team
+    #   MLB::Coaches.find(team: 147, season: 2024)
+    # @param team [Team, Integer] the team or team ID
+    # @param season [Integer, nil] the season year (defaults to current year)
+    # @return [Array<Job>] the coaches
+    def self.find(team:, season: nil)
+      season ||= Utils.current_season
+      team_id = Utils.extract_id(team)
+      response = CLIENT.get("teams/#{team_id}/coaches?#{Utils.build_query(season:)}")
+      from_json(response).roster
+    end
+  end
+end