mlb 0.10.0 → 0.11.0

data/lib/mlb/home_run_derby.rb

@@ -0,0 +1,285 @@
+require "shale"
+require_relative "player"
+
+module MLB
+  # Represents a home run in the derby
+  class DerbyHomeRun < Shale::Mapper
+    # @!attribute [rw] total_distance
+    #   Returns the total distance of the home run
+    #   @api public
+    #   @example
+    #     hr.total_distance #=> 450
+    #   @return [Integer] the distance in feet
+    attribute :total_distance, Shale::Type::Integer
+
+    # @!attribute [rw] launch_speed
+    #   Returns the launch speed
+    #   @api public
+    #   @example
+    #     hr.launch_speed #=> 112.5
+    #   @return [Float] the launch speed in mph
+    attribute :launch_speed, Shale::Type::Float
+
+    # @!attribute [rw] launch_angle
+    #   Returns the launch angle
+    #   @api public
+    #   @example
+    #     hr.launch_angle #=> 28.5
+    #   @return [Float] the launch angle in degrees
+    attribute :launch_angle, Shale::Type::Float
+
+    # @!attribute [rw] is_bonus_time
+    #   Returns whether this was hit during bonus time
+    #   @api public
+    #   @example
+    #     hr.bonus_time? #=> false
+    #   @return [Boolean] whether bonus time
+    attribute :is_bonus_time, Shale::Type::Boolean
+
+    # Returns whether this home run was during bonus time
+    #
+    # @api public
+    # @example
+    #   hr.bonus_time? #=> false
+    # @return [Boolean] whether bonus time
+    def bonus_time?
+      is_bonus_time
+    end
+
+    json do
+      map "totalDistance", to: :total_distance
+      map "launchSpeed", to: :launch_speed
+      map "launchAngle", to: :launch_angle
+      map "isBonusTime", to: :is_bonus_time
+    end
+  end
+
+  # Represents a batter's derby performance
+  class DerbyBatter < Shale::Mapper
+    include Equalizer.new(:id, :seed)
+
+    # @!attribute [rw] id
+    #   Returns the player ID
+    #   @api public
+    #   @example
+    #     batter.id #=> 660271
+    #   @return [Integer] the player ID
+    attribute :id, Shale::Type::Integer
+
+    # @!attribute [rw] full_name
+    #   Returns the player's full name
+    #   @api public
+    #   @example
+    #     batter.full_name #=> "Shohei Ohtani"
+    #   @return [String] the full name
+    attribute :full_name, Shale::Type::String
+
+    # @!attribute [rw] link
+    #   Returns the API link to the player
+    #   @api public
+    #   @example
+    #     batter.link #=> "/api/v1/people/660271"
+    #   @return [String] the link
+    attribute :link, Shale::Type::String
+
+    # @!attribute [rw] seed
+    #   Returns the batter's seed
+    #   @api public
+    #   @example
+    #     batter.seed #=> 1
+    #   @return [Integer] the seed
+    attribute :seed, Shale::Type::Integer
+
+    # @!attribute [rw] home_runs
+    #   Returns the number of home runs
+    #   @api public
+    #   @example
+    #     batter.home_runs #=> 24
+    #   @return [Integer] the home run count
+    attribute :home_runs, Shale::Type::Integer
+
+    # @!attribute [rw] is_winner
+    #   Returns whether this batter won their matchup
+    #   @api public
+    #   @example
+    #     batter.winner? #=> true
+    #   @return [Boolean] whether winner
+    attribute :is_winner, Shale::Type::Boolean
+
+    # @!attribute [rw] is_bonus
+    #   Returns whether batter earned bonus time
+    #   @api public
+    #   @example
+    #     batter.bonus? #=> true
+    #   @return [Boolean] whether bonus earned
+    attribute :is_bonus, Shale::Type::Boolean
+
+    # @!attribute [rw] hits
+    #   Returns the home run details
+    #   @api public
+    #   @example
+    #     batter.hits #=> [#<MLB::DerbyHomeRun>, ...]
+    #   @return [Array<DerbyHomeRun>] the home runs
+    attribute :hits, DerbyHomeRun, collection: true
+
+    # Returns whether this batter won their matchup
+    #
+    # @api public
+    # @example
+    #   batter.winner? #=> true
+    # @return [Boolean] whether winner
+    def winner?
+      is_winner
+    end
+
+    # Returns whether this batter earned bonus time
+    #
+    # @api public
+    # @example
+    #   batter.bonus? #=> true
+    # @return [Boolean] whether bonus earned
+    def bonus?
+      is_bonus
+    end
+
+    json do
+      map "id", to: :id
+      map "fullName", to: :full_name
+      map "link", to: :link
+      map "seed", to: :seed
+      map "homeRuns", to: :home_runs
+      map "isWinner", to: :is_winner
+      map "isBonus", to: :is_bonus
+      map "hits", to: :hits
+    end
+  end
+
+  # Represents a matchup in the derby round
+  class DerbyMatchup < Shale::Mapper
+    # @!attribute [rw] matchup_id
+    #   Returns the matchup ID
+    #   @api public
+    #   @example
+    #     matchup.matchup_id #=> 1
+    #   @return [Integer] the matchup ID
+    attribute :matchup_id, Shale::Type::Integer
+
+    # @!attribute [rw] top_seed
+    #   Returns the top seed batter
+    #   @api public
+    #   @example
+    #     matchup.top_seed #=> #<MLB::DerbyBatter>
+    #   @return [DerbyBatter] the top seed
+    attribute :top_seed, DerbyBatter
+
+    # @!attribute [rw] bottom_seed
+    #   Returns the bottom seed batter
+    #   @api public
+    #   @example
+    #     matchup.bottom_seed #=> #<MLB::DerbyBatter>
+    #   @return [DerbyBatter] the bottom seed
+    attribute :bottom_seed, DerbyBatter
+
+    json do
+      map "matchupId", to: :matchup_id
+      map "topSeed", to: :top_seed
+      map "bottomSeed", to: :bottom_seed
+    end
+  end
+
+  # Represents a round in the derby
+  class DerbyRound < Shale::Mapper
+    # @!attribute [rw] round
+    #   Returns the round number
+    #   @api public
+    #   @example
+    #     round.round #=> 1
+    #   @return [Integer] the round number
+    attribute :round, Shale::Type::Integer
+
+    # @!attribute [rw] num_batters
+    #   Returns the number of batters
+    #   @api public
+    #   @example
+    #     round.num_batters #=> 8
+    #   @return [Integer] the number of batters
+    attribute :num_batters, Shale::Type::Integer
+
+    # @!attribute [rw] matchups
+    #   Returns the matchups
+    #   @api public
+    #   @example
+    #     round.matchups #=> [#<MLB::DerbyMatchup>, ...]
+    #   @return [Array<DerbyMatchup>] the matchups
+    attribute :matchups, DerbyMatchup, collection: true
+
+    json do
+      map "round", to: :round
+      map "numBatters", to: :num_batters
+      map "matchups", to: :matchups
+    end
+  end
+
+  # Represents home run derby info
+  class DerbyInfo < Shale::Mapper
+    # @!attribute [rw] id
+    #   Returns the derby ID
+    #   @api public
+    #   @example
+    #     info.id #=> 511101
+    #   @return [Integer] the ID
+    attribute :id, Shale::Type::Integer
+
+    # @!attribute [rw] name
+    #   Returns the derby name
+    #   @api public
+    #   @example
+    #     info.name #=> "2024 Home Run Derby"
+    #   @return [String] the name
+    attribute :name, Shale::Type::String
+
+    json do
+      map "id", to: :id
+      map "name", to: :name
+    end
+  end
+
+  # Represents home run derby data
+  class HomeRunDerby < Shale::Mapper
+    # @!attribute [rw] info
+    #   Returns the derby info
+    #   @api public
+    #   @example
+    #     derby.info #=> #<MLB::DerbyInfo>
+    #   @return [DerbyInfo] the info
+    attribute :info, DerbyInfo
+
+    # @!attribute [rw] rounds
+    #   Returns the rounds
+    #   @api public
+    #   @example
+    #     derby.rounds #=> [#<MLB::DerbyRound>, ...]
+    #   @return [Array<DerbyRound>] the rounds
+    attribute :rounds, DerbyRound, collection: true
+
+    json do
+      map "info", to: :info
+      map "rounds", to: :rounds
+    end
+
+    # Retrieves home run derby data for a game
+    #
+    # @api public
+    # @example Get derby data for a game
+    #   MLB::HomeRunDerby.find(game: 511101)
+    # @example Get derby data using a ScheduledGame object
+    #   MLB::HomeRunDerby.find(game: scheduled_game)
+    # @param game [Integer, ScheduledGame] the game ID or game object
+    # @return [HomeRunDerby] the derby data
+    def self.find(game:)
+      game_pk = game.respond_to?(:game_pk) ? game.game_pk : game
+      response = CLIENT.get("homeRunDerby/#{game_pk}")
+      from_json(response)
+    end
+  end
+end

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