mlb 0.9.0 → 0.11.0

data/lib/mlb/code_description_type.rb

@@ -0,0 +1,45 @@
+require "equalizer"
+require "shale"
+
+module MLB
+  # Base class for simple code/description value objects from the MLB Stats API.
+  # These represent enumerated types that consist of a code identifier and
+  # human-readable description (e.g., pitch types, wind directions, sky conditions).
+  #
+  # @api private
+  # @abstract Subclass and define specific domain semantics
+  class CodeDescriptionType < Shale::Mapper
+    include Equalizer.new(:code)
+
+    # @!attribute [rw] code
+    #   Returns the type code identifier
+    #   @api public
+    #   @example
+    #     instance.code #=> "SL"
+    #   @return [String] the type code identifier
+    attribute :code, Shale::Type::String
+
+    # @!attribute [rw] description
+    #   Returns the human-readable description
+    #   @api public
+    #   @example
+    #     instance.description #=> "Slider"
+    #   @return [String] the human-readable description
+    attribute :description, Shale::Type::String
+
+    json do
+      map "code", to: :code
+      map "description", to: :description
+    end
+
+    # Returns a string representation of the object
+    #
+    # @api public
+    # @example
+    #   pitch_type.to_s #=> "SL (Slider)"
+    # @return [String] string representation
+    def to_s
+      "#{code} (#{description})"
+    end
+  end
+end

data/lib/mlb/collection.rb

@@ -0,0 +1,48 @@
+require "shale"
+
+module MLB
+  # Base class for simple collection endpoints that only need an .all method.
+  # Provides a class macro to define the endpoint, item type, and attribute name,
+  # eliminating repetitive boilerplate across 20+ similar collection classes.
+  #
+  # @api private
+  class Collection < Shale::Mapper
+    class << self
+      # Returns the API endpoint for this collection
+      #
+      # @api private
+      # @return [String] the API endpoint
+      attr_reader :endpoint
+
+      # Returns the collection attribute name
+      #
+      # @api private
+      # @return [Symbol] the collection attribute name
+      attr_reader :collection_name
+
+      # Configures the collection with endpoint and item type
+      #
+      # @api private
+      # @param endpoint [String] the API endpoint to fetch from
+      # @param item_type [Class] the Shale::Mapper class for individual items
+      # @param collection_name [Symbol] the attribute name for the collection
+      # @return [void]
+      def collection(endpoint:, item_type:, collection_name:)
+        @endpoint = endpoint
+        @collection_name = collection_name
+        attribute collection_name, item_type, collection: true
+      end
+
+      # Retrieves all items from this collection
+      #
+      # @api public
+      # @example
+      #   MLB::Sports.all #=> [#<MLB::Sport id=1 name="Major League Baseball">, ...]
+      # @return [Array] the list of items
+      def all
+        response = CLIENT.get(endpoint)
+        from_json("{\"#{collection_name}\":#{response}}").public_send(collection_name)
+      end
+    end
+  end
+end

data/lib/mlb/comparable_by_attribute.rb

@@ -0,0 +1,56 @@
+module MLB
+  # Provides comparison behavior for model classes by a specified attribute.
+  # Handles nil values gracefully by placing them at the end when sorting.
+  #
+  # @api private
+  # @example
+  #   class Award < Shale::Mapper
+  #     include Comparable
+  #     include MLB::ComparableByAttribute
+  #
+  #     def comparable_attribute = :sort_order
+  #   end
+  module ComparableByAttribute
+    # Compares this object with another by the comparable attribute
+    #
+    # @api public
+    # @example
+    #   award1 <=> award2 #=> -1
+    # @param other [Object] the object to compare with
+    # @return [Integer, nil] -1, 0, 1, or nil if not comparable
+    def <=>(other)
+      return nil unless other.is_a?(self.class) || is_a?(other.class)
+
+      compare_values(
+        public_send(comparable_attribute),
+        other.public_send(comparable_attribute)
+      )
+    end
+
+    private
+
+    # Returns the attribute name used for comparison
+    #
+    # @api private
+    # @abstract Override in including class
+    # @return [Symbol] the attribute name
+    def comparable_attribute
+      raise NotImplementedError
+    end
+
+    # Compares two values, treating nil as greater than any value
+    #
+    # @api private
+    # @param self_val [Object, nil] the value from self
+    # @param other_val [Object, nil] the value from other
+    # @return [Integer] -1, 0, or 1
+    def compare_values(self_val, other_val)
+      case [self_val, other_val]
+      in [nil, nil] then 0
+      in [nil, _] then 1
+      in [_, nil] then -1
+      else self_val <=> other_val
+      end
+    end
+  end
+end

data/lib/mlb/conference.rb

@@ -0,0 +1,39 @@
+require "equalizer"
+require "shale"
+require_relative "league"
+require_relative "sport"
+
+module MLB
+  # Represents a conference
+  class Conference < Shale::Mapper
+    include Equalizer.new(:id)
+
+    attribute :id, Shale::Type::Integer
+    attribute :name, Shale::Type::String
+    attribute :link, Shale::Type::String
+    attribute :abbreviation, Shale::Type::String
+    attribute :has_wildcard, Shale::Type::Boolean
+    attribute :league, League
+    attribute :sport, Sport
+    attribute :name_short, Shale::Type::String
+
+    # Checks if the conference has a wildcard
+    #
+    # @api public
+    # @example
+    #   conference.wildcard? #=> true
+    # @return [Boolean] whether the conference has a wildcard
+    def wildcard? = has_wildcard
+
+    json do
+      map "id", to: :id
+      map "name", to: :name
+      map "link", to: :link
+      map "abbreviation", to: :abbreviation
+      map "hasWildcard", to: :has_wildcard
+      map "league", to: :league
+      map "sport", to: :sport
+      map "nameShort", to: :name_short
+    end
+  end
+end

data/lib/mlb/conferences.rb

@@ -0,0 +1,33 @@
+require "shale"
+require_relative "conference"
+
+module MLB
+  # Collection of conferences from the MLB Stats API
+  class Conferences < Shale::Mapper
+    attribute :conferences, Conference, collection: true
+
+    # Retrieves all conferences
+    #
+    # @api public
+    # @example
+    #   MLB::Conferences.all
+    # @return [Array<Conference>] list of all conferences
+    def self.all
+      response = CLIENT.get("conferences")
+      from_json(response).conferences
+    end
+
+    # Finds a conference by ID
+    #
+    # @api public
+    # @example
+    #   MLB::Conferences.find(301)
+    # @param conference [Integer, Conference] the conference ID or Conference object
+    # @return [Conference, nil] the conference if found
+    def self.find(conference)
+      params = {conferenceId: Utils.extract_id(conference)}
+      response = CLIENT.get("conferences?#{Utils.build_query(params)}")
+      from_json(response).conferences.first
+    end
+  end
+end

data/lib/mlb/connection.rb

@@ -5,15 +5,25 @@ require "uri"
 require_relative "errors/network_error"
 
 module MLB
+  # Manages HTTP connections to the MLB Stats API
   class Connection
     extend Forwardable
 
+    # Default host for API requests
     DEFAULT_HOST = "statsapi.mlb.com".freeze
+    # Default port for HTTPS connections
     DEFAULT_PORT = 443
+    # Default connection open timeout in seconds
     DEFAULT_OPEN_TIMEOUT = 60 # seconds
+    # Default read timeout in seconds
     DEFAULT_READ_TIMEOUT = 60 # seconds
+    # Default write timeout in seconds
     DEFAULT_WRITE_TIMEOUT = 60 # seconds
+    # Default debug output destination
     DEFAULT_DEBUG_OUTPUT = File.open(File::NULL, "w")
+    # HTTPS scheme identifier
+    HTTPS_SCHEME = "https".freeze
+    # Network errors that trigger a NetworkError exception
     NETWORK_ERRORS = [
       Errno::ECONNREFUSED,
       Errno::ECONNRESET,
@@ -22,33 +32,135 @@ module MLB
       OpenSSL::SSL::SSLError
     ].freeze
 
-    attr_accessor :open_timeout, :read_timeout, :write_timeout, :debug_output
-    attr_reader :proxy_url, :proxy_uri
+    # Returns the connection open timeout in seconds
+    #
+    # @api public
+    # @example
+    #   connection.open_timeout #=> 60
+    # @return [Integer] the connection open timeout in seconds
+    attr_accessor :open_timeout
+
+    # @!method open_timeout=(value)
+    #   Sets the connection open timeout in seconds
+    #   @api public
+    #   @example
+    #     connection.open_timeout = 30
+    #   @param value [Integer] the timeout in seconds
+    #   @return [Integer] the timeout in seconds
+
+    # Returns the read timeout in seconds
+    #
+    # @api public
+    # @example
+    #   connection.read_timeout #=> 60
+    # @return [Integer] the read timeout in seconds
+    attr_accessor :read_timeout
+
+    # @!method read_timeout=(value)
+    #   Sets the read timeout in seconds
+    #   @api public
+    #   @example
+    #     connection.read_timeout = 30
+    #   @param value [Integer] the timeout in seconds
+    #   @return [Integer] the timeout in seconds
+
+    # Returns the write timeout in seconds
+    #
+    # @api public
+    # @example
+    #   connection.write_timeout #=> 60
+    # @return [Integer] the write timeout in seconds
+    attr_accessor :write_timeout
+
+    # @!method write_timeout=(value)
+    #   Sets the write timeout in seconds
+    #   @api public
+    #   @example
+    #     connection.write_timeout = 30
+    #   @param value [Integer] the timeout in seconds
+    #   @return [Integer] the timeout in seconds
+
+    # Returns the IO object for debug output
+    #
+    # @api public
+    # @example
+    #   connection.debug_output #=> #<File:/dev/null>
+    # @return [IO] the IO object for debug output
+    attr_accessor :debug_output
+
+    # @!method debug_output=(value)
+    #   Sets the IO object for debug output
+    #   @api public
+    #   @example
+    #     connection.debug_output = $stderr
+    #   @param value [IO] the IO object for debug output
+    #   @return [IO] the IO object for debug output
+
+    # Returns the proxy URL
+    #
+    # @api public
+    # @example
+    #   connection.proxy_url #=> "http://proxy.example.com:8080"
+    # @return [String, nil] the proxy URL
+    attr_reader :proxy_url
+
+    # Returns the parsed proxy URI
+    #
+    # @api public
+    # @example
+    #   connection.proxy_uri #=> #<URI::HTTP http://proxy.example.com:8080>
+    # @return [URI::HTTP, nil] the parsed proxy URI
+    attr_reader :proxy_uri
 
     def_delegator :proxy_uri, :host, :proxy_host
     def_delegator :proxy_uri, :port, :proxy_port
     def_delegator :proxy_uri, :user, :proxy_user
     def_delegator :proxy_uri, :password, :proxy_pass
 
+    # Initializes a new Connection instance
+    #
+    # @api public
+    # @example
+    #   connection = MLB::Connection.new
+    # @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
     def initialize(open_timeout: DEFAULT_OPEN_TIMEOUT, read_timeout: DEFAULT_READ_TIMEOUT,
       write_timeout: DEFAULT_WRITE_TIMEOUT, debug_output: DEFAULT_DEBUG_OUTPUT, proxy_url: nil)
       @open_timeout = open_timeout
       @read_timeout = read_timeout
       @write_timeout = write_timeout
       @debug_output = debug_output
-      self.proxy_url = proxy_url unless proxy_url.nil?
+      self.proxy_url = proxy_url if proxy_url
     end
 
+    # Performs an HTTP request
+    #
+    # @api public
+    # @example
+    #   connection.perform(request: request)
+    # @param request [Net::HTTPRequest] the HTTP request to perform
+    # @return [Net::HTTPResponse] the HTTP response
+    # @raise [NetworkError] if a network error occurs
     def perform(request:)
-      host = request.uri.host || DEFAULT_HOST
-      port = request.uri.port || DEFAULT_PORT
-      http_client = build_http_client(host, port)
-      http_client.use_ssl = request.uri.scheme.eql?("https")
+      uri = request.uri
+      http_client = build_http_client(uri.host || DEFAULT_HOST, uri.port || DEFAULT_PORT)
+      http_client.use_ssl = uri.scheme.eql?(HTTPS_SCHEME)
       http_client.request(request)
     rescue *NETWORK_ERRORS => e
       raise NetworkError, "Network error: #{e}"
     end
 
+    # Sets the proxy URL
+    #
+    # @api public
+    # @example
+    #   connection.proxy_url = "http://proxy.example.com:8080"
+    # @param proxy_url [String] the proxy URL
+    # @return [void]
+    # @raise [ArgumentError] if the proxy URL is invalid
     def proxy_url=(proxy_url)
       @proxy_url = proxy_url
       proxy_uri = URI(proxy_url)
@@ -59,6 +171,12 @@ module MLB
 
     private
 
+    # Builds an HTTP client instance
+    #
+    # @api private
+    # @param host [String] the host to connect to
+    # @param port [Integer] the port to connect to
+    # @return [Net::HTTP] the configured HTTP client
     def build_http_client(host = DEFAULT_HOST, port = DEFAULT_PORT)
       http_client = if proxy_uri
         Net::HTTP.new(host, port, proxy_host, proxy_port, proxy_user, proxy_pass)
@@ -68,6 +186,11 @@ module MLB
       configure_http_client(http_client)
     end
 
+    # Configures an HTTP client with timeout settings
+    #
+    # @api private
+    # @param http_client [Net::HTTP] the HTTP client to configure
+    # @return [Net::HTTP] the configured HTTP client
     def configure_http_client(http_client)
       http_client.tap do |c|
         c.open_timeout = open_timeout

data/lib/mlb/context_metrics.rb

@@ -0,0 +1,90 @@
+require "shale"
+
+module MLB
+  # Represents sacrifice fly probability for a specific field zone
+  class SacFlyProbability < Shale::Mapper
+    include Equalizer.new(:probability)
+
+    # @!attribute [rw] probability
+    #   Returns the probability of a sacrifice fly to this field zone
+    #   @api public
+    #   @example
+    #     sac_fly.probability #=> 0.25
+    #   @return [Float] probability value between 0 and 1
+    attribute :probability, Shale::Type::Float
+
+    json do
+      map "probability", to: :probability
+    end
+  end
+
+  # Provides real-time context metrics for a game including win probability
+  # and sacrifice fly probabilities by field zone
+  #
+  # Context metrics are useful for understanding game state and
+  # making predictions about likely outcomes.
+  class ContextMetrics < Shale::Mapper
+    # @!attribute [rw] home_win_probability
+    #   Returns the home team's probability of winning
+    #   @api public
+    #   @example
+    #     metrics.home_win_probability #=> 0.52
+    #   @return [Float] probability value between 0 and 1
+    attribute :home_win_probability, Shale::Type::Float
+
+    # @!attribute [rw] away_win_probability
+    #   Returns the away team's probability of winning
+    #   @api public
+    #   @example
+    #     metrics.away_win_probability #=> 0.48
+    #   @return [Float] probability value between 0 and 1
+    attribute :away_win_probability, Shale::Type::Float
+
+    # @!attribute [rw] left_field_sac_fly_probability
+    #   Returns sacrifice fly probability for left field
+    #   @api public
+    #   @example
+    #     metrics.left_field_sac_fly_probability.probability #=> 0.25
+    #   @return [SacFlyProbability] left field sac fly metrics
+    attribute :left_field_sac_fly_probability, SacFlyProbability
+
+    # @!attribute [rw] center_field_sac_fly_probability
+    #   Returns sacrifice fly probability for center field
+    #   @api public
+    #   @example
+    #     metrics.center_field_sac_fly_probability.probability #=> 0.30
+    #   @return [SacFlyProbability] center field sac fly metrics
+    attribute :center_field_sac_fly_probability, SacFlyProbability
+
+    # @!attribute [rw] right_field_sac_fly_probability
+    #   Returns sacrifice fly probability for right field
+    #   @api public
+    #   @example
+    #     metrics.right_field_sac_fly_probability.probability #=> 0.35
+    #   @return [SacFlyProbability] right field sac fly metrics
+    attribute :right_field_sac_fly_probability, SacFlyProbability
+
+    json do
+      map "homeWinProbability", to: :home_win_probability
+      map "awayWinProbability", to: :away_win_probability
+      map "leftFieldSacFlyProbability", to: :left_field_sac_fly_probability
+      map "centerFieldSacFlyProbability", to: :center_field_sac_fly_probability
+      map "rightFieldSacFlyProbability", to: :right_field_sac_fly_probability
+    end
+
+    # Retrieves context metrics for a specific game
+    #
+    # @api public
+    # @example Using a game primary key
+    #   MLB::ContextMetrics.find(game: 745571)
+    # @example Using a ScheduledGame object
+    #   MLB::ContextMetrics.find(game: scheduled_game)
+    # @param game [Integer, #game_pk] game ID or object responding to #game_pk
+    # @return [ContextMetrics] the context metrics for the game
+    def self.find(game:)
+      game_pk = game.respond_to?(:game_pk) ? game.game_pk : game
+      response = CLIENT.get("game/#{game_pk}/contextMetrics")
+      from_json(response)
+    end
+  end
+end

data/lib/mlb/division.rb

@@ -1,10 +1,21 @@
+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
@@ -18,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
@@ -34,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.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