mlb 0.9.0 → 0.11.0

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

data/lib/mlb/event_type.rb

@@ -0,0 +1,61 @@
+require "equalizer"
+require "shale"
+
+module MLB
+  # Represents a baseball event type
+  class EventType < Shale::Mapper
+    include Equalizer.new(:code)
+
+    # @!attribute [rw] code
+    #   Returns the event code
+    #   @api public
+    #   @example
+    #     event_type.code #=> "single"
+    #   @return [String] the event code
+    attribute :code, Shale::Type::String
+
+    # @!attribute [rw] description
+    #   Returns the event description
+    #   @api public
+    #   @example
+    #     event_type.description #=> "Single"
+    #   @return [String] the event description
+    attribute :description, Shale::Type::String
+
+    # @!attribute [rw] plate_appearance
+    #   Returns whether this event counts as a plate appearance
+    #   @api public
+    #   @example
+    #     event_type.plate_appearance #=> true
+    #   @return [Boolean] whether this event counts as a plate appearance
+    attribute :plate_appearance, Shale::Type::Boolean
+
+    # @!attribute [rw] hit
+    #   Returns whether this event is a hit
+    #   @api public
+    #   @example
+    #     event_type.hit #=> true
+    #   @return [Boolean] whether this event is a hit
+    attribute :hit, Shale::Type::Boolean
+
+    # @!attribute [rw] base_running_event
+    #   Returns whether this event involves base running
+    #   @api public
+    #   @example
+    #     event_type.base_running_event #=> false
+    #   @return [Boolean] whether this event involves base running
+    attribute :base_running_event, Shale::Type::Boolean
+
+    alias_method :plate_appearance?, :plate_appearance
+    alias_method :hit?, :hit
+    alias_method :base_running_event?, :base_running_event
+
+    json do
+      map "code", to: :code
+      map "description", to: :description
+      map "plateAppearance", to: :plate_appearance
+      map "hit", to: :hit
+      map "baseRunningEvent", to: :base_running_event
+    end
+  end
+end

data/lib/mlb/event_types.rb

@@ -0,0 +1,12 @@
+require_relative "collection"
+require_relative "event_type"
+
+module MLB
+  # Provides methods for fetching event types from the API
+  #
+  # @example Fetch all event types
+  #   MLB::EventTypes.all #=> [#<MLB::EventType>, ...]
+  class EventTypes < Collection
+    collection endpoint: "eventTypes", item_type: EventType, collection_name: :event_types
+  end
+end

data/lib/mlb/free_agent.rb

@@ -0,0 +1,78 @@
+require "equalizer"
+require "shale"
+require_relative "player"
+require_relative "team"
+require_relative "position"
+
+module MLB
+  # Represents a free agent
+  class FreeAgent < Shale::Mapper
+    include Equalizer.new(:player)
+
+    # @!attribute [rw] player
+    #   Returns the player
+    #   @api public
+    #   @example
+    #     free_agent.player #=> #<MLB::Player>
+    #   @return [Player] the player
+    attribute :player, Player
+
+    # @!attribute [rw] original_team
+    #   Returns the team the player left
+    #   @api public
+    #   @example
+    #     free_agent.original_team #=> #<MLB::Team>
+    #   @return [Team] the original team
+    attribute :original_team, Team
+
+    # @!attribute [rw] new_team
+    #   Returns the team the player signed with
+    #   @api public
+    #   @example
+    #     free_agent.new_team #=> #<MLB::Team>
+    #   @return [Team] the new team
+    attribute :new_team, Team
+
+    # @!attribute [rw] notes
+    #   Returns signing notes
+    #   @api public
+    #   @example
+    #     free_agent.notes #=> "Seven-Year Contract"
+    #   @return [String] the notes
+    attribute :notes, Shale::Type::String
+
+    # @!attribute [rw] date_signed
+    #   Returns the date the player signed
+    #   @api public
+    #   @example
+    #     free_agent.date_signed #=> #<Date: 2024-12-10>
+    #   @return [Date] the date signed
+    attribute :date_signed, Shale::Type::Date
+
+    # @!attribute [rw] date_declared
+    #   Returns the date the player declared free agency
+    #   @api public
+    #   @example
+    #     free_agent.date_declared #=> #<Date: 2024-10-31>
+    #   @return [Date] the date declared
+    attribute :date_declared, Shale::Type::Date
+
+    # @!attribute [rw] position
+    #   Returns the player's position
+    #   @api public
+    #   @example
+    #     free_agent.position #=> #<MLB::Position>
+    #   @return [Position] the position
+    attribute :position, Position
+
+    json do
+      map "player", to: :player
+      map "originalTeam", to: :original_team
+      map "newTeam", to: :new_team
+      map "notes", to: :notes
+      map "dateSigned", to: :date_signed
+      map "dateDeclared", to: :date_declared
+      map "position", to: :position
+    end
+  end
+end