mlb 0.9.0 → 0.11.0

data/lib/mlb/id_description_type.rb

@@ -0,0 +1,44 @@
+require "equalizer"
+require "shale"
+
+module MLB
+  # Base class for simple id/description value objects from the MLB Stats API.
+  # Similar to CodeDescriptionType but uses 'id' as the identifier field.
+  #
+  # @api private
+  # @abstract Subclass and define specific domain semantics
+  class IdDescriptionType < Shale::Mapper
+    include Equalizer.new(:id)
+
+    # @!attribute [rw] id
+    #   Returns the type identifier
+    #   @api public
+    #   @example
+    #     instance.id #=> "R"
+    #   @return [String] the type identifier
+    attribute :id, Shale::Type::String
+
+    # @!attribute [rw] description
+    #   Returns the human-readable description
+    #   @api public
+    #   @example
+    #     instance.description #=> "Regular Season"
+    #   @return [String] the human-readable description
+    attribute :description, Shale::Type::String
+
+    json do
+      map "id", to: :id
+      map "description", to: :description
+    end
+
+    # Returns a string representation of the object
+    #
+    # @api public
+    # @example
+    #   game_type.to_s #=> "R (Regular Season)"
+    # @return [String] string representation
+    def to_s
+      "#{id} (#{description})"
+    end
+  end
+end

data/lib/mlb/inning_score.rb

@@ -0,0 +1,87 @@
+require "shale"
+
+module MLB
+  # Represents the score for one side of an inning
+  class InningHalfScore < Shale::Mapper
+    # @!attribute [rw] runs
+    #   Returns the runs scored
+    #   @api public
+    #   @example
+    #     inning_half_score.runs #=> 2
+    #   @return [Integer] the runs
+    attribute :runs, Shale::Type::Integer
+
+    # @!attribute [rw] hits
+    #   Returns the hits
+    #   @api public
+    #   @example
+    #     inning_half_score.hits #=> 3
+    #   @return [Integer] the hits
+    attribute :hits, Shale::Type::Integer
+
+    # @!attribute [rw] errors
+    #   Returns the errors
+    #   @api public
+    #   @example
+    #     inning_half_score.errors #=> 0
+    #   @return [Integer] the errors
+    attribute :errors, Shale::Type::Integer
+
+    # @!attribute [rw] left_on_base
+    #   Returns runners left on base
+    #   @api public
+    #   @example
+    #     inning_half_score.left_on_base #=> 1
+    #   @return [Integer] the left on base
+    attribute :left_on_base, Shale::Type::Integer
+
+    json do
+      map "runs", to: :runs
+      map "hits", to: :hits
+      map "errors", to: :errors
+      map "leftOnBase", to: :left_on_base
+    end
+  end
+
+  # Represents the score for one inning
+  class InningScore < Shale::Mapper
+    # @!attribute [rw] num
+    #   Returns the inning number
+    #   @api public
+    #   @example
+    #     inning_score.num #=> 1
+    #   @return [Integer] the inning number
+    attribute :num, Shale::Type::Integer
+
+    # @!attribute [rw] ordinal_num
+    #   Returns the ordinal inning number
+    #   @api public
+    #   @example
+    #     inning_score.ordinal_num #=> "1st"
+    #   @return [String] the ordinal number
+    attribute :ordinal_num, Shale::Type::String
+
+    # @!attribute [rw] home
+    #   Returns the home team's score
+    #   @api public
+    #   @example
+    #     inning_score.home #=> #<MLB::InningHalfScore>
+    #   @return [InningHalfScore] the home score
+    attribute :home, InningHalfScore
+
+    # @!attribute [rw] away
+    #   Returns the away team's score
+    #   @api public
+    #   @example
+    #     inning_score.away #=> #<MLB::InningHalfScore>
+    #   @return [InningHalfScore] the away score
+    attribute :away, InningHalfScore
+
+    json do
+      map "num", to: :num
+      map "ordinalNum", to: :ordinal_num
+      map "home", to: :home
+      map "away", to: :away
+    end
+  end
+end

data/lib/mlb/job.rb

@@ -0,0 +1,58 @@
+require "equalizer"
+require "shale"
+require_relative "player"
+
+module MLB
+  # Represents a job/role (umpire, datacaster, etc.)
+  class Job < Shale::Mapper
+    include Equalizer.new(:person)
+
+    # @!attribute [rw] person
+    #   Returns the person holding the job
+    #   @api public
+    #   @example
+    #     job.person #=> #<MLB::Player>
+    #   @return [Player] the person
+    attribute :person, Player
+
+    # @!attribute [rw] jersey_number
+    #   Returns the jersey number
+    #   @api public
+    #   @example
+    #     job.jersey_number #=> "67"
+    #   @return [String] the jersey number
+    attribute :jersey_number, Shale::Type::String
+
+    # @!attribute [rw] job
+    #   Returns the job title
+    #   @api public
+    #   @example
+    #     job.job #=> "Umpire"
+    #   @return [String] the job title
+    attribute :job, Shale::Type::String
+
+    # @!attribute [rw] job_id
+    #   Returns the job identifier
+    #   @api public
+    #   @example
+    #     job.job_id #=> "UMPR"
+    #   @return [String] the job identifier
+    attribute :job_id, Shale::Type::String
+
+    # @!attribute [rw] title
+    #   Returns the title
+    #   @api public
+    #   @example
+    #     job.title #=> "Umpire"
+    #   @return [String] the title
+    attribute :title, Shale::Type::String
+
+    json do
+      map "person", to: :person
+      map "jerseyNumber", to: :jersey_number
+      map "job", to: :job
+      map "jobId", to: :job_id
+      map "title", to: :title
+    end
+  end
+end

data/lib/mlb/job_type.rb

@@ -0,0 +1,39 @@
+require "equalizer"
+require "shale"
+
+module MLB
+  # Represents a job type
+  class JobType < Shale::Mapper
+    include Equalizer.new(:code)
+
+    # @!attribute [rw] code
+    #   Returns the job type code
+    #   @api public
+    #   @example
+    #     job_type.code #=> "UMPR"
+    #   @return [String] the job type code
+    attribute :code, Shale::Type::String
+
+    # @!attribute [rw] job
+    #   Returns the job title
+    #   @api public
+    #   @example
+    #     job_type.job #=> "Umpire"
+    #   @return [String] the job title
+    attribute :job, Shale::Type::String
+
+    # @!attribute [rw] sort_order
+    #   Returns the sort order
+    #   @api public
+    #   @example
+    #     job_type.sort_order #=> 1
+    #   @return [Integer] the sort order
+    attribute :sort_order, Shale::Type::Integer
+
+    json do
+      map "code", to: :code
+      map "job", to: :job
+      map "sortOrder", to: :sort_order
+    end
+  end
+end

data/lib/mlb/job_types.rb

@@ -0,0 +1,12 @@
+require_relative "collection"
+require_relative "job_type"
+
+module MLB
+  # Provides methods for fetching job types from the API
+  #
+  # @example Fetch all job types
+  #   MLB::JobTypes.all #=> [#<MLB::JobType>, ...]
+  class JobTypes < Collection
+    collection endpoint: "jobTypes", item_type: JobType, collection_name: :job_types
+  end
+end

data/lib/mlb/jobs.rb

@@ -0,0 +1,87 @@
+require "shale"
+require_relative "job"
+
+module MLB
+  # Provides methods for fetching job data from the API
+  class Jobs < Shale::Mapper
+    # @!attribute [rw] roster
+    #   Returns the job roster
+    #   @api public
+    #   @example
+    #     jobs.roster #=> [#<MLB::Job>, ...]
+    #   @return [Array<Job>] the job roster
+    attribute :roster, Job, collection: true
+
+    json do
+      map "roster", to: :roster
+    end
+
+    # Retrieves all umpires
+    #
+    # @api public
+    # @example Get all umpires for the current season
+    #   MLB::Jobs.umpires
+    # @example Get umpires for a specific season
+    #   MLB::Jobs.umpires(season: 2024)
+    # @param season [Integer, nil] the season year (defaults to current year)
+    # @return [Array<Job>] the umpires
+    def self.umpires(season: nil)
+      fetch_jobs("jobs/umpires", season:)
+    end
+
+    # Retrieves all datacasters
+    #
+    # @api public
+    # @example Get all datacasters for the current season
+    #   MLB::Jobs.datacasters
+    # @example Get datacasters for a specific season
+    #   MLB::Jobs.datacasters(season: 2024)
+    # @param season [Integer, nil] the season year (defaults to current year)
+    # @return [Array<Job>] the datacasters
+    def self.datacasters(season: nil)
+      fetch_jobs("jobs/datacasters", season:)
+    end
+
+    # Retrieves all official scorers
+    #
+    # @api public
+    # @example Get all official scorers for the current season
+    #   MLB::Jobs.official_scorers
+    # @example Get official scorers for a specific season
+    #   MLB::Jobs.official_scorers(season: 2024)
+    # @param season [Integer, nil] the season year (defaults to current year)
+    # @return [Array<Job>] the official scorers
+    def self.official_scorers(season: nil)
+      fetch_jobs("jobs/officialScorers", season:)
+    end
+
+    # Retrieves games for a specific umpire
+    #
+    # @api public
+    # @example Get games for an umpire
+    #   MLB::Jobs.umpire_games(umpire: 427127, season: 2024)
+    # @param umpire [Job, Integer] the umpire or umpire ID
+    # @param season [Integer, nil] the season year (defaults to current year)
+    # @return [Array<Job>] the umpire's game assignments
+    def self.umpire_games(umpire:, season: nil)
+      umpire_id = umpire.respond_to?(:person) ? umpire.person.id : umpire
+      fetch_jobs("jobs/umpires/games/#{umpire_id}", season:)
+    end
+
+    class << self
+      private
+
+      # Fetches jobs from the specified endpoint
+      #
+      # @api private
+      # @param endpoint [String] the API endpoint path
+      # @param season [Integer, nil] the season year
+      # @return [Array<Job>] the jobs
+      def fetch_jobs(endpoint, season:)
+        season ||= Utils.current_season
+        response = CLIENT.get("#{endpoint}?#{Utils.build_query(season:)}")
+        from_json(response).roster
+      end
+    end
+  end
+end

data/lib/mlb/language.rb

@@ -0,0 +1,48 @@
+require "equalizer"
+require "shale"
+
+module MLB
+  # Represents a language
+  class Language < Shale::Mapper
+    include Equalizer.new(:language_id)
+
+    # @!attribute [rw] language_id
+    #   Returns the unique language identifier
+    #   @api public
+    #   @example
+    #     language.language_id #=> 1
+    #   @return [Integer] the unique language identifier
+    attribute :language_id, Shale::Type::Integer
+
+    # @!attribute [rw] language_code
+    #   Returns the language code
+    #   @api public
+    #   @example
+    #     language.language_code #=> "en"
+    #   @return [String] the language code
+    attribute :language_code, Shale::Type::String
+
+    # @!attribute [rw] name
+    #   Returns the language name
+    #   @api public
+    #   @example
+    #     language.name #=> "English"
+    #   @return [String] the language name
+    attribute :name, Shale::Type::String
+
+    # @!attribute [rw] locale
+    #   Returns the locale identifier
+    #   @api public
+    #   @example
+    #     language.locale #=> "en_US"
+    #   @return [String] the locale identifier
+    attribute :locale, Shale::Type::String
+
+    json do
+      map "languageId", to: :language_id
+      map "languageCode", to: :language_code
+      map "name", to: :name
+      map "locale", to: :locale
+    end
+  end
+end

data/lib/mlb/languages.rb

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

data/lib/mlb/leader.rb

@@ -0,0 +1,79 @@
+require "equalizer"
+require "shale"
+require_relative "player"
+require_relative "team"
+require_relative "league"
+require_relative "sport"
+
+module MLB
+  # Represents a league leader
+  class Leader < Shale::Mapper
+    include Equalizer.new(:rank, :person)
+
+    # @!attribute [rw] rank
+    #   Returns the leader rank
+    #   @api public
+    #   @example
+    #     leader.rank #=> 1
+    #   @return [Integer] the rank
+    attribute :rank, Shale::Type::Integer
+
+    # @!attribute [rw] value
+    #   Returns the stat value
+    #   @api public
+    #   @example
+    #     leader.value #=> "58"
+    #   @return [String] the value
+    attribute :value, Shale::Type::String
+
+    # @!attribute [rw] person
+    #   Returns the player
+    #   @api public
+    #   @example
+    #     leader.person #=> #<MLB::Player>
+    #   @return [Player] the player
+    attribute :person, Player
+
+    # @!attribute [rw] team
+    #   Returns the team
+    #   @api public
+    #   @example
+    #     leader.team #=> #<MLB::Team>
+    #   @return [Team] the team
+    attribute :team, Team
+
+    # @!attribute [rw] league
+    #   Returns the league
+    #   @api public
+    #   @example
+    #     leader.league #=> #<MLB::League>
+    #   @return [League] the league
+    attribute :league, League
+
+    # @!attribute [rw] sport
+    #   Returns the sport
+    #   @api public
+    #   @example
+    #     leader.sport #=> #<MLB::Sport>
+    #   @return [Sport] the sport
+    attribute :sport, Sport
+
+    # @!attribute [rw] season
+    #   Returns the season
+    #   @api public
+    #   @example
+    #     leader.season #=> "2024"
+    #   @return [String] the season
+    attribute :season, Shale::Type::String
+
+    json do
+      map "rank", to: :rank
+      map "value", to: :value
+      map "person", to: :person
+      map "team", to: :team
+      map "league", to: :league
+      map "sport", to: :sport
+      map "season", to: :season
+    end
+  end
+end

data/lib/mlb/leaders.rb

@@ -0,0 +1,68 @@
+require "shale"
+require_relative "leader"
+
+module MLB
+  # Represents a leader category result
+  class LeaderCategory < Shale::Mapper
+    # @!attribute [rw] leader_category
+    #   Returns the category name
+    #   @api public
+    #   @example
+    #     category.leader_category #=> "homeRuns"
+    #   @return [String] the category
+    attribute :leader_category, Shale::Type::String
+
+    # @!attribute [rw] season
+    #   Returns the season
+    #   @api public
+    #   @example
+    #     category.season #=> "2024"
+    #   @return [String] the season
+    attribute :season, Shale::Type::String
+
+    # @!attribute [rw] leaders
+    #   Returns the leaders
+    #   @api public
+    #   @example
+    #     category.leaders #=> [#<MLB::Leader>, ...]
+    #   @return [Array<Leader>] the leaders
+    attribute :leaders, Leader, collection: true
+
+    json do
+      map "leaderCategory", to: :leader_category
+      map "season", to: :season
+      map "leaders", to: :leaders
+    end
+  end
+
+  # Provides methods for fetching league leaders from the API
+  class Leaders < Shale::Mapper
+    # @!attribute [rw] league_leaders
+    #   Returns the league leaders
+    #   @api public
+    #   @example
+    #     leaders.league_leaders #=> [#<MLB::LeaderCategory>, ...]
+    #   @return [Array<LeaderCategory>] the league leaders
+    attribute :league_leaders, LeaderCategory, collection: true
+
+    json do
+      map "leagueLeaders", to: :league_leaders
+    end
+
+    # Retrieves league leaders for a category
+    #
+    # @api public
+    # @example Get home run leaders
+    #   MLB::Leaders.find(category: "homeRuns", season: 2024)
+    # @param category [String] the stat category
+    # @param season [Integer, nil] the season year (defaults to current year)
+    # @param limit [Integer] the number of leaders to return (defaults to 10)
+    # @return [Array<Leader>] the leaders
+    def self.find(category:, season: nil, limit: 10)
+      season ||= Utils.current_season
+      params = {leaderCategories: category, season:, limit:}
+      response = CLIENT.get("stats/leaders?#{Utils.build_query(params)}")
+      from_json(response).league_leaders.first&.leaders || []
+    end
+  end
+end

data/lib/mlb/league.rb

@@ -1,10 +1,26 @@
+require "equalizer"
 require "shale"
+require_relative "comparable_by_attribute"
 require_relative "season_date_info"
 require_relative "sport"
 
 module MLB
+  # Represents a league (e.g., American League, National League)
   class League < Shale::Mapper
     include Comparable
+    include ComparableByAttribute
+    include Equalizer.new(:id)
+
+    SEASON_PRESEASON = "preseason".freeze
+    SEASON_INSEASON = "inseason".freeze
+    SEASON_POSTSEASON = "postseason".freeze
+    SEASON_OFFSEASON = "offseason".freeze
+
+    # 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
@@ -12,7 +28,7 @@ module MLB
     attribute :abbreviation, Shale::Type::String
     attribute :name_short, Shale::Type::String
     attribute :season_state, Shale::Type::String
-    attribute :has_wild_card, Shale::Type::Boolean
+    attribute :has_wildcard, Shale::Type::Boolean
     attribute :has_split_season, Shale::Type::Boolean
     attribute :num_games, Shale::Type::Integer
     attribute :has_playoff_points, Shale::Type::Boolean
@@ -27,14 +43,85 @@ module MLB
     attribute :sort_order, Shale::Type::Integer
     attribute :active, Shale::Type::Boolean
 
-    alias_method :active?, :active
-    alias_method :wild_card?, :has_wild_card
-    alias_method :has_wildcard, :has_wild_card
-    alias_method :wildcard?, :has_wild_card
-    alias_method :split_season?, :has_split_season
-    alias_method :playoff_points?, :has_playoff_points
-    alias_method :conferences?, :conferences_in_use
-    alias_method :divisions?, :divisions_in_use
+    # Checks if the league is active
+    #
+    # @api public
+    # @example
+    #   league.active? #=> true
+    # @return [Boolean] whether the league is active
+    def active? = active
+
+    # Checks if the league has a wildcard
+    #
+    # @api public
+    # @example
+    #   league.wildcard? #=> true
+    # @return [Boolean] whether the league has a wildcard
+    def wildcard? = has_wildcard
+
+    # Checks if the league has a split season
+    #
+    # @api public
+    # @example
+    #   league.split_season? #=> false
+    # @return [Boolean] whether the league has a split season
+    def split_season? = has_split_season
+
+    # Checks if the league uses playoff points
+    #
+    # @api public
+    # @example
+    #   league.playoff_points? #=> false
+    # @return [Boolean] whether the league uses playoff points
+    def playoff_points? = has_playoff_points
+
+    # Checks if the league uses conferences
+    #
+    # @api public
+    # @example
+    #   league.conferences? #=> false
+    # @return [Boolean] whether the league uses conferences
+    def conferences? = conferences_in_use
+
+    # Checks if the league uses divisions
+    #
+    # @api public
+    # @example
+    #   league.divisions? #=> true
+    # @return [Boolean] whether the league uses divisions
+    def divisions? = divisions_in_use
+
+    # Checks if the league is in preseason
+    #
+    # @api public
+    # @example
+    #   league.preseason? #=> false
+    # @return [Boolean] whether the league is in preseason
+    def preseason? = season_state.eql?(SEASON_PRESEASON)
+
+    # Checks if the league is in season
+    #
+    # @api public
+    # @example
+    #   league.in_season? #=> true
+    # @return [Boolean] whether the league is in season
+    def in_season? = season_state.eql?(SEASON_INSEASON)
+
+    # Checks if the league is in postseason
+    #
+    # @api public
+    # @example
+    #   league.postseason? #=> false
+    # @return [Boolean] whether the league is in postseason
+    def postseason? = season_state.eql?(SEASON_POSTSEASON)
+
+    # Checks if the league is in offseason
+    #
+    # @api public
+    # @example
+    #   league.offseason? #=> false
+    # @return [Boolean] whether the league is in offseason
+    def offseason? = season_state.eql?(SEASON_OFFSEASON)
 
     json do
       map "id", to: :id
@@ -43,7 +130,7 @@ module MLB
       map "abbreviation", to: :abbreviation
       map "nameShort", to: :name_short
       map "seasonState", to: :season_state
-      map "hasWildCard", to: :has_wild_card
+      map "hasWildCard", to: :has_wildcard
       map "hasSplitSeason", to: :has_split_season
       map "numGames", to: :num_games
       map "hasPlayoffPoints", to: :has_playoff_points
@@ -58,9 +145,5 @@ module MLB
       map "sortOrder", to: :sort_order
       map "active", to: :active
     end
-
-    def <=>(other)
-      sort_order <=> other.sort_order
-    end
   end
 end