mlb 0.10.0 → 0.11.0

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,
@@ -31,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:)
@@ -58,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

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

@@ -4,6 +4,7 @@ require_relative "league"
 require_relative "sport"
 
 module MLB
+  # Represents a conference
   class Conference < Shale::Mapper
     include Equalizer.new(:id)
 
@@ -16,7 +17,13 @@ module MLB
     attribute :sport, Sport
     attribute :name_short, Shale::Type::String
 
-    alias_method :wildcard?, :has_wildcard
+    # 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

data/lib/mlb/conferences.rb

@@ -1,25 +1,33 @@
 require "shale"
-require "uri"
 require_relative "conference"
 
 module MLB
+  # Collection of conferences from the MLB Stats API
   class Conferences < Shale::Mapper
-    attribute :copyright, Shale::Type::String
     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")
-      conferences = from_json(response)
-      conferences.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)
-      id = conference.respond_to?(:id) ? conference.id : conference
-      params = {conferenceId: id}
-      query_string = URI.encode_www_form(params)
-      response = CLIENT.get("conferences?#{query_string}")
-      conferences = from_json(response)
-      conferences.conferences.first
+      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