mlb 0.10.0 → 0.11.0

data/lib/mlb/division.rb

@@ -1,13 +1,22 @@
 require "equalizer"
 require "shale"
+require_relative "comparable_by_attribute"
 require_relative "league"
 require_relative "sport"
 
 module MLB
+  # Represents a division (e.g., AL East, NL West)
   class Division < Shale::Mapper
     include Comparable
+    include ComparableByAttribute
     include Equalizer.new(:id)
 
+    # Returns the attribute used for sorting
+    #
+    # @api private
+    # @return [Symbol] the attribute used for comparison
+    def comparable_attribute = :sort_order
+
     attribute :id, Shale::Type::Integer
     attribute :name, Shale::Type::String
     attribute :season, Shale::Type::String
@@ -20,8 +29,21 @@ module MLB
     attribute :sort_order, Shale::Type::Integer
     attribute :active, Shale::Type::Boolean
 
-    alias_method :active?, :active
-    alias_method :wildcard?, :has_wildcard
+    # Checks if the division is active
+    #
+    # @api public
+    # @example
+    #   division.active? #=> true
+    # @return [Boolean] whether the division is active
+    def active? = active
+
+    # Checks if the division has a wildcard
+    #
+    # @api public
+    # @example
+    #   division.wildcard? #=> true
+    # @return [Boolean] whether the division has a wildcard
+    def wildcard? = has_wildcard
 
     json do
       map "id", to: :id
@@ -36,9 +58,5 @@ module MLB
       map "sortOrder", to: :sort_order
       map "active", to: :active
     end
-
-    def <=>(other)
-      sort_order <=> other.sort_order
-    end
   end
 end

data/lib/mlb/divisions.rb

@@ -1,30 +1,36 @@
 require "shale"
-require "uri"
-require_relative "sport"
 require_relative "division"
 
 module MLB
+  # Collection of divisions from the MLB Stats API
   class Divisions < Shale::Mapper
-    attribute :copyright, Shale::Type::String
     attribute :divisions, Division, collection: true
 
-    def self.all(sport: Sport.new(id: 1))
-      sport_id = sport.respond_to?(:id) ? sport.id : sport
-      params = {sportId: sport_id}
-      query_string = URI.encode_www_form(params)
-      response = CLIENT.get("divisions?#{query_string}")
-      divisions = from_json(response)
-      divisions.divisions.sort!
+    # Retrieves all divisions
+    #
+    # @api public
+    # @example
+    #   MLB::Divisions.all
+    # @param sport [Integer, Sport] the sport ID or Sport object
+    # @return [Array<Division>] list of all divisions
+    def self.all(sport: Utils::DEFAULT_SPORT_ID)
+      params = {sportId: Utils.extract_id(sport)}
+      response = CLIENT.get("divisions?#{Utils.build_query(params)}")
+      from_json(response).divisions.sort
     end
 
-    def self.find(division, sport: Sport.new(id: 1))
-      id = division.respond_to?(:id) ? division.id : division
-      sport_id = sport.respond_to?(:id) ? sport.id : sport
-      params = {sportId: sport_id}
-      query_string = URI.encode_www_form(params)
-      response = CLIENT.get("divisions/#{id}?#{query_string}")
-      divisions = from_json(response)
-      divisions.divisions.sort!.first
+    # Finds a division by ID
+    #
+    # @api public
+    # @example
+    #   MLB::Divisions.find(201)
+    # @param division [Integer, Division] the division ID or Division object
+    # @param sport [Integer, Sport] the sport ID or Sport object
+    # @return [Division, nil] the division if found
+    def self.find(division, sport: Utils::DEFAULT_SPORT_ID)
+      params = {sportId: Utils.extract_id(sport)}
+      response = CLIENT.get("divisions/#{Utils.extract_id(division)}?#{Utils.build_query(params)}")
+      from_json(response).divisions.min_by { |d| d.sort_order || 0 }
     end
   end
 end

data/lib/mlb/draft.rb

@@ -0,0 +1,83 @@
+require "shale"
+require_relative "draft_pick"
+
+module MLB
+  # Represents a round in the draft
+  class DraftRound < Shale::Mapper
+    # @!attribute [rw] round
+    #   Returns the round number
+    #   @api public
+    #   @example
+    #     round.round #=> "1"
+    #   @return [String] the round
+    attribute :round, Shale::Type::String
+
+    # @!attribute [rw] picks
+    #   Returns the picks in this round
+    #   @api public
+    #   @example
+    #     round.picks #=> [#<MLB::DraftPick>, ...]
+    #   @return [Array<DraftPick>] the picks
+    attribute :picks, DraftPick, collection: true
+
+    json do
+      map "round", to: :round
+      map "picks", to: :picks
+    end
+  end
+
+  # Represents a draft year
+  class DraftYear < Shale::Mapper
+    # @!attribute [rw] draft_year
+    #   Returns the draft year
+    #   @api public
+    #   @example
+    #     draft.draft_year #=> 2024
+    #   @return [Integer] the year
+    attribute :draft_year, Shale::Type::Integer
+
+    # @!attribute [rw] rounds
+    #   Returns the draft rounds
+    #   @api public
+    #   @example
+    #     draft.rounds #=> [#<MLB::DraftRound>, ...]
+    #   @return [Array<DraftRound>] the rounds
+    attribute :rounds, DraftRound, collection: true
+
+    json do
+      map "draftYear", to: :draft_year
+      map "rounds", to: :rounds
+    end
+  end
+
+  # Provides methods for fetching draft data from the API
+  class Draft < Shale::Mapper
+    # @!attribute [rw] drafts
+    #   Returns the draft data
+    #   @api public
+    #   @example
+    #     draft.drafts #=> #<MLB::DraftYear>
+    #   @return [DraftYear] the draft data
+    attribute :drafts, DraftYear
+
+    json do
+      map "drafts", to: :drafts
+    end
+
+    # Retrieves draft picks for a year
+    #
+    # @api public
+    # @example Get draft picks for 2024
+    #   MLB::Draft.picks(year: 2024)
+    # @example Get draft picks for the current year
+    #   MLB::Draft.picks
+    # @param year [Integer, nil] the draft year (defaults to current year)
+    # @return [Array<DraftPick>] the draft picks
+    def self.picks(year: nil)
+      year ||= Utils.current_season
+      response = CLIENT.get("draft/#{year}")
+      result = from_json(response)
+      result.drafts&.rounds&.flat_map(&:picks) || []
+    end
+  end
+end

data/lib/mlb/draft_pick.rb

@@ -0,0 +1,155 @@
+require "equalizer"
+require "shale"
+require_relative "player"
+require_relative "team"
+
+module MLB
+  # Represents a school in the draft
+  class DraftSchool < Shale::Mapper
+    # @!attribute [rw] name
+    #   Returns the school name
+    #   @api public
+    #   @example
+    #     school.name #=> "Oregon State"
+    #   @return [String] the school name
+    attribute :name, Shale::Type::String
+
+    # @!attribute [rw] school_class
+    #   Returns the class level
+    #   @api public
+    #   @example
+    #     school.school_class #=> "4YR JR"
+    #   @return [String] the class level
+    attribute :school_class, Shale::Type::String
+
+    # @!attribute [rw] city
+    #   Returns the city
+    #   @api public
+    #   @example
+    #     school.city #=> "Corvallis"
+    #   @return [String] the city
+    attribute :city, Shale::Type::String
+
+    # @!attribute [rw] state
+    #   Returns the state
+    #   @api public
+    #   @example
+    #     school.state #=> "OR"
+    #   @return [String] the state
+    attribute :state, Shale::Type::String
+
+    # @!attribute [rw] country
+    #   Returns the country
+    #   @api public
+    #   @example
+    #     school.country #=> "USA"
+    #   @return [String] the country
+    attribute :country, Shale::Type::String
+
+    json do
+      map "name", to: :name
+      map "schoolClass", to: :school_class
+      map "city", to: :city
+      map "state", to: :state
+      map "country", to: :country
+    end
+  end
+
+  # Represents a draft pick
+  class DraftPick < Shale::Mapper
+    include Equalizer.new(:pick_number, :person)
+
+    # @!attribute [rw] pick_round
+    #   Returns the round number
+    #   @api public
+    #   @example
+    #     pick.pick_round #=> "1"
+    #   @return [String] the round
+    attribute :pick_round, Shale::Type::String
+
+    # @!attribute [rw] pick_number
+    #   Returns the overall pick number
+    #   @api public
+    #   @example
+    #     pick.pick_number #=> 1
+    #   @return [Integer] the pick number
+    attribute :pick_number, Shale::Type::Integer
+
+    # @!attribute [rw] round_pick_number
+    #   Returns the pick number within the round
+    #   @api public
+    #   @example
+    #     pick.round_pick_number #=> 1
+    #   @return [Integer] the round pick number
+    attribute :round_pick_number, Shale::Type::Integer
+
+    # @!attribute [rw] rank
+    #   Returns the prospect rank
+    #   @api public
+    #   @example
+    #     pick.rank #=> 1
+    #   @return [Integer] the rank
+    attribute :rank, Shale::Type::Integer
+
+    # @!attribute [rw] pick_value
+    #   Returns the pick slot value
+    #   @api public
+    #   @example
+    #     pick.pick_value #=> "10570600"
+    #   @return [String] the pick value
+    attribute :pick_value, Shale::Type::String
+
+    # @!attribute [rw] signing_bonus
+    #   Returns the signing bonus
+    #   @api public
+    #   @example
+    #     pick.signing_bonus #=> "8950000"
+    #   @return [String] the signing bonus
+    attribute :signing_bonus, Shale::Type::String
+
+    # @!attribute [rw] person
+    #   Returns the drafted player
+    #   @api public
+    #   @example
+    #     pick.person #=> #<MLB::Player>
+    #   @return [Player] the player
+    attribute :person, Player
+
+    # @!attribute [rw] team
+    #   Returns the drafting team
+    #   @api public
+    #   @example
+    #     pick.team #=> #<MLB::Team>
+    #   @return [Team] the team
+    attribute :team, Team
+
+    # @!attribute [rw] school
+    #   Returns the player's school
+    #   @api public
+    #   @example
+    #     pick.school #=> #<MLB::DraftSchool>
+    #   @return [DraftSchool] the school
+    attribute :school, DraftSchool
+
+    # @!attribute [rw] blurb
+    #   Returns the scouting report blurb
+    #   @api public
+    #   @example
+    #     pick.blurb #=> "A native of Sydney..."
+    #   @return [String] the blurb
+    attribute :blurb, Shale::Type::String
+
+    json do
+      map "pickRound", to: :pick_round
+      map "pickNumber", to: :pick_number
+      map "roundPickNumber", to: :round_pick_number
+      map "rank", to: :rank
+      map "pickValue", to: :pick_value
+      map "signingBonus", to: :signing_bonus
+      map "person", to: :person
+      map "team", to: :team
+      map "school", to: :school
+      map "blurb", to: :blurb
+    end
+  end
+end

data/lib/mlb/error_handler.rb

@@ -16,7 +16,9 @@ require_relative "errors/unauthorized"
 require_relative "errors/unprocessable_entity"
 
 module MLB
+  # Handles HTTP error responses from the MLB Stats API
   class ErrorHandler
+    # Mapping of HTTP status codes to error classes
     ERROR_MAP = {
       400 => BadRequest,
       401 => Unauthorized,
@@ -34,6 +36,14 @@ module MLB
       504 => GatewayTimeout
     }.freeze
 
+    # Handles an HTTP response
+    #
+    # @api public
+    # @example
+    #   handler.handle(response: response)
+    # @param response [Net::HTTPResponse] the HTTP response
+    # @return [String, nil] the response body if successful
+    # @raise [HTTPError] if the response is not successful
     def handle(response:)
       raise error(response) unless response.is_a?(Net::HTTPSuccess)
 
@@ -42,12 +52,22 @@ module MLB
 
     private
 
+    # Creates an error from a response
+    #
+    # @api private
+    # @param response [Net::HTTPResponse] the HTTP response
+    # @return [HTTPError] the error instance
     def error(response)
       error_class(response).new(response:)
     end
 
+    # Returns the error class for a response
+    #
+    # @api private
+    # @param response [Net::HTTPResponse] the HTTP response
+    # @return [Class] the error class
     def error_class(response)
-      ERROR_MAP[Integer(response.code)] || HTTPError
+      ERROR_MAP.fetch(Integer(response.code), HTTPError)
     end
   end
 end

data/lib/mlb/errors/bad_gateway.rb

@@ -1,5 +1,10 @@
 require_relative "server_error"
+require_relative "retryable"
 
 module MLB
-  class BadGateway < ServerError; end
+  # Error raised for HTTP 502 Bad Gateway responses.
+  # These errors indicate temporary proxy/gateway issues and are safe to retry.
+  class BadGateway < ServerError
+    include Retryable
+  end
 end

data/lib/mlb/errors/bad_request.rb

@@ -1,5 +1,6 @@
 require_relative "client_error"
 
 module MLB
+  # Error raised for HTTP 400 Bad Request responses
   class BadRequest < ClientError; end
 end

data/lib/mlb/errors/client_error.rb

@@ -1,5 +1,6 @@
 require_relative "http_error"
 
 module MLB
+  # Error raised for HTTP 4xx client errors
   class ClientError < HTTPError; end
 end

data/lib/mlb/errors/connection_exception.rb

@@ -1,5 +1,6 @@
 require_relative "client_error"
 
 module MLB
+  # Error raised for connection failures during HTTP requests
   class ConnectionException < ClientError; end
 end

data/lib/mlb/errors/error.rb

@@ -1,3 +1,4 @@
 module MLB
+  # Base error class for all MLB gem errors
   class Error < StandardError; end
 end

data/lib/mlb/errors/forbidden.rb

@@ -1,5 +1,6 @@
 require_relative "client_error"
 
 module MLB
+  # Error raised for HTTP 403 Forbidden responses
   class Forbidden < ClientError; end
 end

data/lib/mlb/errors/gateway_timeout.rb

@@ -1,5 +1,10 @@
 require_relative "server_error"
+require_relative "retryable"
 
 module MLB
-  class GatewayTimeout < ServerError; end
+  # Error raised for HTTP 504 Gateway Timeout responses.
+  # These errors indicate temporary infrastructure issues and are safe to retry.
+  class GatewayTimeout < ServerError
+    include Retryable
+  end
 end

data/lib/mlb/errors/gone.rb

@@ -1,5 +1,6 @@
 require_relative "client_error"
 
 module MLB
+  # Error raised for HTTP 410 Gone responses
   class Gone < ClientError; end
 end

data/lib/mlb/errors/http_error.rb

@@ -1,10 +1,30 @@
-require "json"
 require_relative "error"
 
 module MLB
+  # HTTP error raised when an API request fails
   class HTTPError < Error
-    attr_reader :response, :code
+    # Returns the HTTP response
+    #
+    # @api public
+    # @example
+    #   error.response #=> #<Net::HTTPNotFound 404 Not Found>
+    # @return [Net::HTTPResponse] the HTTP response
+    attr_reader :response
 
+    # Returns the HTTP status code
+    #
+    # @api public
+    # @example
+    #   error.code #=> "404"
+    # @return [String] the HTTP status code
+    attr_reader :code
+
+    # Initializes a new HTTPError instance
+    #
+    # @api public
+    # @example
+    #   HTTPError.new(response: response)
+    # @param response [Net::HTTPResponse] the HTTP response
     def initialize(response:)
       super(response.message)
       @response = response

data/lib/mlb/errors/internal_server_error.rb

@@ -1,5 +1,6 @@
 require_relative "server_error"
 
 module MLB
+  # Error raised for HTTP 500 Internal Server Error responses
   class InternalServerError < ServerError; end
 end

data/lib/mlb/errors/network_error.rb

@@ -1,5 +1,10 @@
 require_relative "error"
+require_relative "retryable"
 
 module MLB
-  class NetworkError < Error; end
+  # Error raised when a network connection fails.
+  # These errors are typically transient and safe to retry.
+  class NetworkError < Error
+    include Retryable
+  end
 end

data/lib/mlb/errors/not_acceptable.rb

@@ -1,5 +1,6 @@
 require_relative "client_error"
 
 module MLB
+  # Error raised for HTTP 406 Not Acceptable responses
   class NotAcceptable < ClientError; end
 end

data/lib/mlb/errors/not_found.rb

@@ -1,5 +1,6 @@
 require_relative "client_error"
 
 module MLB
+  # Error raised for HTTP 404 Not Found responses
   class NotFound < ClientError; end
 end

data/lib/mlb/errors/payload_too_large.rb

@@ -1,5 +1,6 @@
 require_relative "client_error"
 
 module MLB
+  # Error raised for HTTP 413 Payload Too Large responses
   class PayloadTooLarge < ClientError; end
 end

data/lib/mlb/errors/retryable.rb

@@ -0,0 +1,15 @@
+module MLB
+  # Module to mark errors that are safe to retry.
+  # Include this in error classes where automatic retry logic is appropriate,
+  # such as transient network issues or temporary server unavailability.
+  #
+  # @api public
+  # @example Checking if an error is retryable
+  #   begin
+  #     client.get("teams")
+  #   rescue MLB::Error => e
+  #     retry if e.is_a?(MLB::Retryable) && attempts < 3
+  #     raise
+  #   end
+  module Retryable; end
+end

data/lib/mlb/errors/server_error.rb

@@ -1,5 +1,6 @@
 require_relative "http_error"
 
 module MLB
+  # Error raised for HTTP 5xx server errors
   class ServerError < HTTPError; end
 end

data/lib/mlb/errors/service_unavailable.rb

@@ -1,5 +1,10 @@
 require_relative "server_error"
+require_relative "retryable"
 
 module MLB
-  class ServiceUnavailable < ServerError; end
+  # Error raised for HTTP 503 Service Unavailable responses.
+  # These errors indicate temporary server issues and are safe to retry.
+  class ServiceUnavailable < ServerError
+    include Retryable
+  end
 end

data/lib/mlb/errors/too_many_redirects.rb

@@ -1,5 +1,6 @@
 require_relative "error"
 
 module MLB
+  # Error raised when too many HTTP redirects are encountered
   class TooManyRedirects < Error; end
 end

data/lib/mlb/errors/too_many_requests.rb

@@ -1,5 +1,10 @@
 require_relative "client_error"
+require_relative "retryable"
 
 module MLB
-  class TooManyRequests < ClientError; end
+  # Error raised for HTTP 429 Too Many Requests responses.
+  # These errors indicate rate limiting and are safe to retry after a delay.
+  class TooManyRequests < ClientError
+    include Retryable
+  end
 end

data/lib/mlb/errors/unauthorized.rb

@@ -1,5 +1,6 @@
 require_relative "client_error"
 
 module MLB
+  # Error raised for HTTP 401 Unauthorized responses
   class Unauthorized < ClientError; end
 end

data/lib/mlb/errors/unprocessable_entity.rb

@@ -1,5 +1,6 @@
 require_relative "client_error"
 
 module MLB
+  # Error raised for HTTP 422 Unprocessable Entity responses
   class UnprocessableEntity < ClientError; end
 end