mlb 0.9.0 → 0.11.0

data/lib/mlb/players.rb

@@ -1,25 +1,56 @@
 require "shale"
-require "uri"
-require_relative "sport"
 require_relative "player"
 
 module MLB
+  # Provides methods for fetching MLB players from the API
   class Players < Shale::Mapper
-    attribute :copyright, Shale::Type::String
     attribute :players, Player, collection: true
 
     json do
-      map "copyright", to: :copyright
       map "people", to: :players
     end
 
-    def self.all(season: Time.now.year, sport: Sport.new(id: 1))
-      sport_id = sport.respond_to?(:id) ? sport.id : sport
-      params = {season:}
-      query_string = URI.encode_www_form(params)
-      response = CLIENT.get("sports/#{sport_id}/players?#{query_string}")
-      players = from_json(response)
-      players.players
+    # Retrieves all players for a given season and sport
+    #
+    # @api public
+    # @example
+    #   MLB::Players.all #=> [#<MLB::Player>, ...]
+    # @param season [Integer, nil] the season year (defaults to current year)
+    # @param sport [Sport, Integer] the sport or sport ID
+    # @return [Array<Player>] the list of players
+    def self.all(season: nil, sport: Utils::DEFAULT_SPORT_ID)
+      season ||= Utils.current_season
+      sport_id = Utils.extract_id(sport)
+      response = CLIENT.get("sports/#{sport_id}/players?#{Utils.build_query(season:)}")
+      from_json(response).players
+    end
+
+    # Finds a single player by ID or Player object
+    #
+    # @api public
+    # @example
+    #   MLB::Players.find(660271) #=> #<MLB::Player>
+    # @param player [Player, Integer] the player or player ID
+    # @return [Player, nil] the found player or nil
+    def self.find(player)
+      params = {personIds: Utils.extract_id(player)}
+      response = CLIENT.get("people?#{Utils.build_query(params)}")
+      from_json(response).players.first
+    end
+
+    # Finds multiple players by IDs or Player objects
+    #
+    # @api public
+    # @example
+    #   MLB::Players.find_all(660271, 545361) #=> [#<MLB::Player>, ...]
+    # @param players [Array<Player, Integer>] the players or player IDs
+    # @return [Array<Player>] the list of found players
+    def self.find_all(*players)
+      return all if players.empty?
+
+      player_ids = players.map { |p| Utils.extract_id(p) }.join(",")
+      response = CLIENT.get("people?#{Utils.build_query(personIds: player_ids)}")
+      from_json(response).players
     end
   end
 end

data/lib/mlb/position.rb

@@ -1,12 +1,80 @@
+require "equalizer"
 require "shale"
 
 module MLB
+  # Represents a baseball position
   class Position < Shale::Mapper
+    include Equalizer.new(:code)
+
+    TYPE_PITCHER = "Pitcher".freeze
+    TYPE_CATCHER = "Catcher".freeze
+    TYPE_INFIELDER = "Infielder".freeze
+    TYPE_OUTFIELDER = "Outfielder".freeze
+
+    # @!attribute [rw] code
+    #   Returns the position code
+    #   @api public
+    #   @example
+    #     position.code #=> "1"
+    #   @return [String] the position code
     attribute :code, Shale::Type::String
+
+    # @!attribute [rw] name
+    #   Returns the position name
+    #   @api public
+    #   @example
+    #     position.name #=> "Pitcher"
+    #   @return [String] the position name
     attribute :name, Shale::Type::String
+
+    # @!attribute [rw] type
+    #   Returns the position type
+    #   @api public
+    #   @example
+    #     position.type #=> "Pitcher"
+    #   @return [String] the position type
     attribute :type, Shale::Type::String
+
+    # @!attribute [rw] abbreviation
+    #   Returns the position abbreviation
+    #   @api public
+    #   @example
+    #     position.abbreviation #=> "P"
+    #   @return [String] the position abbreviation
     attribute :abbreviation, Shale::Type::String
 
+    # Returns whether this is a pitcher position
+    #
+    # @api public
+    # @example
+    #   position.pitcher? #=> true
+    # @return [Boolean] whether this is a pitcher
+    def pitcher? = type.eql?(TYPE_PITCHER)
+
+    # Returns whether this is a catcher position
+    #
+    # @api public
+    # @example
+    #   position.catcher? #=> false
+    # @return [Boolean] whether this is a catcher
+    def catcher? = type.eql?(TYPE_CATCHER)
+
+    # Returns whether this is an infielder position
+    #
+    # @api public
+    # @example
+    #   position.infielder? #=> false
+    # @return [Boolean] whether this is an infielder
+    def infielder? = type.eql?(TYPE_INFIELDER)
+
+    # Returns whether this is an outfielder position
+    #
+    # @api public
+    # @example
+    #   position.outfielder? #=> false
+    # @return [Boolean] whether this is an outfielder
+    def outfielder? = type.eql?(TYPE_OUTFIELDER)
+
     json do
       map "code", to: :code
       map "name", to: :name

data/lib/mlb/positions.rb

@@ -0,0 +1,12 @@
+require_relative "collection"
+require_relative "position"
+
+module MLB
+  # Provides methods for fetching positions from the API
+  #
+  # @example Fetch all positions
+  #   MLB::Positions.all #=> [#<MLB::Position>, ...]
+  class Positions < Collection
+    collection endpoint: "positions", item_type: Position, collection_name: :positions
+  end
+end

data/lib/mlb/postseason_schedule.rb

@@ -0,0 +1,41 @@
+require "shale"
+require_relative "schedule_date"
+
+module MLB
+  # Provides methods for fetching postseason schedule data from the API
+  class PostseasonSchedule < Shale::Mapper
+    # @!attribute [rw] total_games
+    #   Returns the total number of games
+    #   @api public
+    #   @example
+    #     schedule.total_games #=> 43
+    #   @return [Integer] the total games
+    attribute :total_games, Shale::Type::Integer
+
+    # @!attribute [rw] dates
+    #   Returns the schedule dates
+    #   @api public
+    #   @example
+    #     schedule.dates #=> [#<MLB::ScheduleDate>, ...]
+    #   @return [Array<ScheduleDate>] the dates
+    attribute :dates, ScheduleDate, collection: true
+
+    json do
+      map "totalGames", to: :total_games
+      map "dates", to: :dates
+    end
+
+    # Retrieves postseason games for a season
+    #
+    # @api public
+    # @example Get postseason games for 2024
+    #   MLB::PostseasonSchedule.games(season: 2024)
+    # @param season [Integer, nil] the season year (defaults to current year)
+    # @return [Array<ScheduledGame>] the postseason games
+    def self.games(season: nil)
+      season ||= Utils.current_season
+      response = CLIENT.get("schedule/postseason?#{Utils.build_query(season:)}")
+      from_json(response).dates.flat_map(&:games)
+    end
+  end
+end

data/lib/mlb/postseason_series.rb

@@ -0,0 +1,54 @@
+require "shale"
+require_relative "scheduled_game"
+
+module MLB
+  # Represents postseason series information
+  class SeriesInfo < Shale::Mapper
+    attribute :id, Shale::Type::String
+    attribute :sort_number, Shale::Type::Integer
+    attribute :game_type, Shale::Type::String
+
+    json do
+      map "id", to: :id
+      map "sortNumber", to: :sort_number
+      map "gameType", to: :game_type
+    end
+  end
+
+  # Represents a postseason series with games
+  class PostseasonSeriesEntry < Shale::Mapper
+    attribute :series, SeriesInfo
+    attribute :total_games, Shale::Type::Integer
+    attribute :games, ScheduledGame, collection: true
+
+    json do
+      map "series", to: :series
+      map "totalGames", to: :total_games
+      map "games", to: :games
+    end
+  end
+
+  # Provides methods for fetching postseason series from the API
+  class PostseasonSeries < Shale::Mapper
+    attribute :series, PostseasonSeriesEntry, collection: true
+
+    json do
+      map "series", to: :series
+    end
+
+    # Retrieves postseason series for a season
+    #
+    # @api public
+    # @example Get postseason series for a season
+    #   MLB::PostseasonSeries.all(season: 2024)
+    # @param season [Integer, nil] the season year (defaults to current year)
+    # @param sport [Integer, Sport] the sport ID or Sport object
+    # @return [Array<PostseasonSeriesEntry>] the postseason series
+    def self.all(season: nil, sport: Utils::DEFAULT_SPORT_ID)
+      season ||= Utils.current_season
+      params = {season:, sportId: Utils.extract_id(sport)}
+      response = CLIENT.get("schedule/postseason/series?#{Utils.build_query(params)}")
+      from_json(response).series
+    end
+  end
+end

data/lib/mlb/redirect_handler.rb

@@ -5,12 +5,55 @@ require_relative "errors/too_many_redirects"
 require_relative "request_builder"
 
 module MLB
+  # Handles HTTP redirects for API requests
   class RedirectHandler
+    # Default maximum number of redirects to follow
     DEFAULT_MAX_REDIRECTS = 10
+    # HTTP redirect codes that preserve the original method and body
+    PRESERVE_METHOD_CODES = [307, 308].freeze
+    # HTTP header for redirect location
+    LOCATION_HEADER = "location".freeze
 
+    # Returns the maximum number of redirects to follow
+    #
+    # @api public
+    # @example
+    #   handler.max_redirects #=> 10
+    # @return [Integer] the maximum redirects
     attr_accessor :max_redirects
-    attr_reader :connection, :request_builder
 
+    # @!method max_redirects=(value)
+    #   Sets the maximum number of redirects to follow
+    #   @api public
+    #   @example
+    #     handler.max_redirects = 5
+    #   @param value [Integer] the maximum number of redirects
+    #   @return [Integer] the maximum number of redirects
+
+    # Returns the connection instance
+    #
+    # @api public
+    # @example
+    #   handler.connection #=> #<MLB::Connection>
+    # @return [Connection] the connection instance
+    attr_reader :connection
+
+    # Returns the request builder instance
+    #
+    # @api public
+    # @example
+    #   handler.request_builder #=> #<MLB::RequestBuilder>
+    # @return [RequestBuilder] the request builder instance
+    attr_reader :request_builder
+
+    # Initializes a new RedirectHandler instance
+    #
+    # @api public
+    # @example
+    #   handler = MLB::RedirectHandler.new
+    # @param connection [Connection] the connection instance
+    # @param request_builder [RequestBuilder] the request builder instance
+    # @param max_redirects [Integer] the maximum number of redirects to follow
     def initialize(connection: Connection.new, request_builder: RequestBuilder.new,
       max_redirects: DEFAULT_MAX_REDIRECTS)
       @connection = connection
@@ -18,38 +61,54 @@ module MLB
       @max_redirects = max_redirects
     end
 
+    # Handles HTTP redirects
+    #
+    # @api public
+    # @example
+    #   handler.handle(response: response, request: request, base_url: "https://example.com")
+    # @param response [Net::HTTPResponse] the HTTP response
+    # @param request [Net::HTTPRequest] the original HTTP request
+    # @param base_url [String] the base URL for relative redirects
+    # @param redirect_count [Integer] the current redirect count
+    # @return [Net::HTTPResponse] the final HTTP response
+    # @raise [TooManyRedirects] if the maximum number of redirects is exceeded
     def handle(response:, request:, base_url:, redirect_count: 0)
-      if response.is_a?(Net::HTTPRedirection)
-        raise TooManyRedirects, "Too many redirects" if redirect_count > max_redirects
-
-        new_uri = build_new_uri(response, base_url)
+      return response unless response.is_a?(Net::HTTPRedirection)
+      raise TooManyRedirects, "Too many redirects" if redirect_count > max_redirects
 
-        new_request = build_request(request, new_uri, Integer(response.code))
-        new_response = connection.perform(request: new_request)
+      new_uri = build_redirect_uri(response, base_url)
+      new_request = build_redirect_request(request, new_uri, Integer(response.code))
+      new_response = connection.perform(request: new_request)
 
-        handle(response: new_response, request: new_request, base_url:, redirect_count: redirect_count + 1)
-      else
-        response
-      end
+      handle(response: new_response, request: new_request, base_url:, redirect_count: redirect_count + 1)
     end
 
     private
 
-    def build_new_uri(response, base_url)
-      location = response.fetch("location")
-      # If location is relative, it will join with the original base URL, otherwise it will overwrite it
+    # Builds a new URI from a redirect response
+    #
+    # @api private
+    # @param response [Net::HTTPResponse] the redirect response
+    # @param base_url [String] the base URL for relative redirects
+    # @return [URI::Generic] the new URI
+    def build_redirect_uri(response, base_url)
+      location = response.fetch(LOCATION_HEADER)
       URI.join(base_url, location)
     end
 
-    def build_request(request, uri, response_code)
-      http_method, body = case response_code
-      in 307 | 308
-        [request.method.downcase.to_sym, request.body]
+    # Builds a new request for a redirect
+    #
+    # @api private
+    # @param request [Net::HTTPRequest] the original request
+    # @param uri [URI::Generic] the new URI
+    # @param response_code [Integer] the redirect response code
+    # @return [Net::HTTPRequest] the new request
+    def build_redirect_request(request, uri, response_code)
+      if PRESERVE_METHOD_CODES.include?(response_code)
+        request_builder.build(http_method: request.method.downcase.to_sym, uri:, body: request.body)
       else
-        [:get, nil]
+        request_builder.build(http_method: :get, uri:)
       end
-
-      request_builder.build(http_method:, uri:, body:)
     end
   end
 end

data/lib/mlb/request_builder.rb

@@ -3,11 +3,14 @@ require "uri"
 require_relative "version"
 
 module MLB
+  # Builds HTTP requests for the MLB Stats API
   class RequestBuilder
+    # Default HTTP headers for API requests
     DEFAULT_HEADERS = {
       "Content-Type" => "application/json; charset=utf-8",
       "User-Agent" => "MLB-Client/#{VERSION} #{RUBY_ENGINE}/#{RUBY_VERSION} (#{RUBY_PLATFORM})"
     }.freeze
+    # Mapping of HTTP method symbols to Net::HTTP request classes
     HTTP_METHODS = {
       get: Net::HTTP::Get,
       post: Net::HTTP::Post,
@@ -15,6 +18,16 @@ module MLB
       delete: Net::HTTP::Delete
     }.freeze
 
+    # Builds an HTTP request
+    #
+    # @api public
+    # @example
+    #   builder.build(http_method: :get, uri: URI("https://example.com"))
+    # @param http_method [Symbol] the HTTP method (:get, :post, :put, :delete)
+    # @param uri [URI::Generic] the request URI
+    # @param body [String, nil] the request body
+    # @param headers [Hash] additional HTTP headers
+    # @return [Net::HTTPRequest] the built HTTP request
     def build(http_method:, uri:, body: nil, headers: {})
       request = create_request(http_method:, uri:, body:)
       add_headers(request:, headers:)
@@ -23,6 +36,14 @@ module MLB
 
     private
 
+    # Creates an HTTP request object
+    #
+    # @api private
+    # @param http_method [Symbol] the HTTP method
+    # @param uri [URI::Generic] the request URI
+    # @param body [String, nil] the request body
+    # @return [Net::HTTPRequest] the created HTTP request
+    # @raise [ArgumentError] if the HTTP method is not supported
     def create_request(http_method:, uri:, body:)
       http_method_class = HTTP_METHODS[http_method]
 
@@ -34,13 +55,23 @@ module MLB
       request
     end
 
+    # Adds headers to an HTTP request
+    #
+    # @api private
+    # @param request [Net::HTTPRequest] the HTTP request
+    # @param headers [Hash] additional headers to add
+    # @return [void]
     def add_headers(request:, headers:)
       DEFAULT_HEADERS.merge(headers).each do |key, value|
-        request.delete(key)
-        request.add_field(key, value)
+        request[key] = value
       end
     end
 
+    # Escapes query parameters in a URI
+    #
+    # @api private
+    # @param uri [URI::Generic] the URI to escape
+    # @return [URI::Generic] the URI with escaped query parameters
     def escape_query_params(uri)
       URI(uri).tap { |u| u.query = URI.encode_www_form(URI.decode_www_form(u.query)) if u.query }
     end

data/lib/mlb/review_reason.rb

@@ -0,0 +1,6 @@
+require_relative "code_description_type"
+
+module MLB
+  # Represents a review reason
+  class ReviewReason < CodeDescriptionType; end
+end

data/lib/mlb/review_reasons.rb

@@ -0,0 +1,12 @@
+require_relative "collection"
+require_relative "review_reason"
+
+module MLB
+  # Provides methods for fetching review reasons from the API
+  #
+  # @example Fetch all review reasons
+  #   MLB::ReviewReasons.all #=> [#<MLB::ReviewReason>, ...]
+  class ReviewReasons < Collection
+    collection endpoint: "reviewReasons", item_type: ReviewReason, collection_name: :review_reasons
+  end
+end

data/lib/mlb/roster.rb

@@ -1,22 +1,26 @@
 require "shale"
-require "uri"
 require_relative "roster_entry"
-require_relative "sport"
-require_relative "team"
 
 module MLB
+  # Provides methods for fetching team rosters from the API
   class Roster < Shale::Mapper
-    attribute :copyright, Shale::Type::String
     attribute :roster, RosterEntry, collection: true
 
-    def self.find(team:, season: Time.now.year, sport: Sport.new(id: 1))
-      team_id = team.respond_to?(:id) ? team.id : team
-      sport_id = sport.respond_to?(:id) ? sport.id : sport
-      params = {season:, sportId: sport_id}
-      query_string = URI.encode_www_form(params)
-      response = CLIENT.get("teams/#{team_id}/roster?#{query_string}")
-      roster = from_json(response)
-      roster.roster
+    # Finds a team's roster for a given season and sport
+    #
+    # @api public
+    # @example
+    #   MLB::Roster.find(team: 119) #=> [#<MLB::RosterEntry>, ...]
+    # @param team [Team, Integer] the team or team ID
+    # @param season [Integer, nil] the season year (defaults to current year)
+    # @param sport [Sport, Integer] the sport or sport ID
+    # @return [Array<RosterEntry>] the list of roster entries
+    def self.find(team:, season: nil, sport: Utils::DEFAULT_SPORT_ID)
+      season ||= Utils.current_season
+      team_id = Utils.extract_id(team)
+      params = {season:, sportId: Utils.extract_id(sport)}
+      response = CLIENT.get("teams/#{team_id}/roster?#{Utils.build_query(params)}")
+      from_json(response).roster
     end
   end
 end

data/lib/mlb/roster_entry.rb

@@ -1,14 +1,52 @@
+require "equalizer"
 require "shale"
 require_relative "player"
 require_relative "position"
 require_relative "status"
 
 module MLB
+  # Represents a player's entry on a team roster
   class RosterEntry < Shale::Mapper
+    include Equalizer.new(:team_id, :player)
+
+    # @!attribute [rw] player
+    #   Returns the player on the roster
+    #   @api public
+    #   @example
+    #     entry.player #=> #<MLB::Player>
+    #   @return [Player] the player on the roster
     attribute :player, Player
+
+    # @!attribute [rw] jersey_number
+    #   Returns the player's jersey number
+    #   @api public
+    #   @example
+    #     entry.jersey_number #=> 17
+    #   @return [Integer] the player's jersey number
     attribute :jersey_number, Shale::Type::Integer
+
+    # @!attribute [rw] position
+    #   Returns the player's position
+    #   @api public
+    #   @example
+    #     entry.position #=> #<MLB::Position>
+    #   @return [Position] the player's position
     attribute :position, Position
+
+    # @!attribute [rw] status
+    #   Returns the player's roster status
+    #   @api public
+    #   @example
+    #     entry.status #=> #<MLB::Status>
+    #   @return [Status] the player's roster status
     attribute :status, Status
+
+    # @!attribute [rw] team_id
+    #   Returns the parent team ID
+    #   @api public
+    #   @example
+    #     entry.team_id #=> 119
+    #   @return [Integer] the parent team ID
     attribute :team_id, Shale::Type::Integer
 
     json do

data/lib/mlb/roster_type.rb

@@ -0,0 +1,39 @@
+require "equalizer"
+require "shale"
+
+module MLB
+  # Represents a roster type
+  class RosterType < Shale::Mapper
+    include Equalizer.new(:parameter)
+
+    # @!attribute [rw] description
+    #   Returns the roster type description
+    #   @api public
+    #   @example
+    #     roster_type.description #=> "40-Man Roster"
+    #   @return [String] the roster type description
+    attribute :description, Shale::Type::String
+
+    # @!attribute [rw] lookup_name
+    #   Returns the lookup name
+    #   @api public
+    #   @example
+    #     roster_type.lookup_name #=> "40Man"
+    #   @return [String] the lookup name
+    attribute :lookup_name, Shale::Type::String
+
+    # @!attribute [rw] parameter
+    #   Returns the API parameter value
+    #   @api public
+    #   @example
+    #     roster_type.parameter #=> "40Man"
+    #   @return [String] the API parameter value
+    attribute :parameter, Shale::Type::String
+
+    json do
+      map "description", to: :description
+      map "lookupName", to: :lookup_name
+      map "parameter", to: :parameter
+    end
+  end
+end

data/lib/mlb/roster_types.rb

@@ -0,0 +1,12 @@
+require_relative "collection"
+require_relative "roster_type"
+
+module MLB
+  # Provides methods for fetching roster types from the API
+  #
+  # @example Fetch all roster types
+  #   MLB::RosterTypes.all #=> [#<MLB::RosterType>, ...]
+  class RosterTypes < Collection
+    collection endpoint: "rosterTypes", item_type: RosterType, collection_name: :roster_types
+  end
+end

data/lib/mlb/schedule.rb

@@ -0,0 +1,33 @@
+require "shale"
+require_relative "schedule_date"
+
+module MLB
+  # Provides methods for fetching game schedules from the API
+  class Schedule < Shale::Mapper
+    attribute :total_games, Shale::Type::Integer
+    attribute :dates, ScheduleDate, collection: true
+
+    json do
+      map "totalGames", to: :total_games
+      map "dates", to: :dates
+    end
+
+    # Retrieves the schedule for a given date
+    #
+    # @api public
+    # @example Get schedule for a specific date
+    #   MLB::Schedule.games(date: Date.new(2024, 7, 4))
+    # @example Get schedule for a team on a specific date
+    #   MLB::Schedule.games(date: Date.new(2024, 7, 4), team: 147)
+    # @param date [Date] the date to get the schedule for
+    # @param sport [Sport, Integer] the sport or sport ID (default: MLB)
+    # @param team [Team, Integer] optional team or team ID to filter by
+    # @return [Array<ScheduledGame>] the list of scheduled games
+    def self.games(date: Date.today, sport: Utils::DEFAULT_SPORT_ID, team: nil)
+      params = {sportId: Utils.extract_id(sport), date:}
+      params[:teamId] = Utils.extract_id(team) if team
+      response = CLIENT.get("schedule?#{Utils.build_query(params)}")
+      from_json(response).dates.flat_map(&:games)
+    end
+  end
+end