mlb 0.9.0 → 0.11.0

data/lib/mlb/game_status.rb

@@ -0,0 +1,94 @@
+require "equalizer"
+require "shale"
+
+module MLB
+  # Represents a game status
+  class GameStatus < Shale::Mapper
+    include Equalizer.new(:status_code)
+
+    FINAL = "Final".freeze
+    LIVE = "Live".freeze
+    PREVIEW = "Preview".freeze
+
+    # @!attribute [rw] abstract_game_state
+    #   Returns the high-level game state
+    #   @api public
+    #   @example
+    #     game_status.abstract_game_state #=> "Final"
+    #   @return [String] the high-level game state
+    attribute :abstract_game_state, Shale::Type::String
+
+    # @!attribute [rw] coded_game_state
+    #   Returns the coded game state
+    #   @api public
+    #   @example
+    #     game_status.coded_game_state #=> "F"
+    #   @return [String] the coded game state
+    attribute :coded_game_state, Shale::Type::String
+
+    # @!attribute [rw] detailed_state
+    #   Returns the detailed game state
+    #   @api public
+    #   @example
+    #     game_status.detailed_state #=> "Final"
+    #   @return [String] the detailed game state
+    attribute :detailed_state, Shale::Type::String
+
+    # @!attribute [rw] status_code
+    #   Returns the status code
+    #   @api public
+    #   @example
+    #     game_status.status_code #=> "F"
+    #   @return [String] the status code
+    attribute :status_code, Shale::Type::String
+
+    # @!attribute [rw] abstract_game_code
+    #   Returns the abstract game code
+    #   @api public
+    #   @example
+    #     game_status.abstract_game_code #=> "F"
+    #   @return [String] the abstract game code
+    attribute :abstract_game_code, Shale::Type::String
+
+    # @!attribute [rw] reason
+    #   Returns the reason for the status
+    #   @api public
+    #   @example
+    #     game_status.reason #=> "Rain"
+    #   @return [String] the reason for the status
+    attribute :reason, Shale::Type::String
+
+    # Returns whether the game is final (completed)
+    #
+    # @api public
+    # @example
+    #   game_status.final? #=> true
+    # @return [Boolean] whether the game is final
+    def final? = abstract_game_state.eql?(FINAL)
+
+    # Returns whether the game is live (in progress)
+    #
+    # @api public
+    # @example
+    #   game_status.live? #=> false
+    # @return [Boolean] whether the game is live
+    def live? = abstract_game_state.eql?(LIVE)
+
+    # Returns whether the game is in preview (not yet started)
+    #
+    # @api public
+    # @example
+    #   game_status.preview? #=> false
+    # @return [Boolean] whether the game is in preview
+    def preview? = abstract_game_state.eql?(PREVIEW)
+
+    json do
+      map "abstractGameState", to: :abstract_game_state
+      map "codedGameState", to: :coded_game_state
+      map "detailedState", to: :detailed_state
+      map "statusCode", to: :status_code
+      map "abstractGameCode", to: :abstract_game_code
+      map "reason", to: :reason
+    end
+  end
+end

data/lib/mlb/game_statuses.rb

@@ -0,0 +1,12 @@
+require_relative "collection"
+require_relative "game_status"
+
+module MLB
+  # Provides methods for fetching game statuses from the API
+  #
+  # @example Fetch all game statuses
+  #   MLB::GameStatuses.all #=> [#<MLB::GameStatus>, ...]
+  class GameStatuses < Collection
+    collection endpoint: "gameStatus", item_type: GameStatus, collection_name: :game_statuses
+  end
+end

data/lib/mlb/game_type.rb

@@ -0,0 +1,98 @@
+require_relative "id_description_type"
+
+module MLB
+  # Represents a game type (e.g., Regular Season, Postseason, Spring Training)
+  class GameType < IdDescriptionType
+    # Game type: Regular Season
+    TYPE_REGULAR = "R".freeze
+    # Game type: Spring Training
+    TYPE_SPRING = "S".freeze
+    # Game type: Exhibition
+    TYPE_EXHIBITION = "E".freeze
+    # Game type: All-Star Game
+    TYPE_ALL_STAR = "A".freeze
+    # Game type: Wild Card
+    TYPE_WILD_CARD = "F".freeze
+    # Game type: Division Series
+    TYPE_DIVISION = "D".freeze
+    # Game type: League Championship Series
+    TYPE_LCS = "L".freeze
+    # Game type: World Series
+    TYPE_WORLD_SERIES = "W".freeze
+    # Game type codes that indicate postseason games
+    POSTSEASON_TYPES = %w[F D L W].freeze
+
+    # Returns whether this is a regular season game type
+    #
+    # @api public
+    # @example
+    #   game_type.regular_season? #=> true
+    # @return [Boolean] whether this is a regular season game type
+    def regular_season? = id.eql?(TYPE_REGULAR)
+
+    # Returns whether this is a spring training game type
+    #
+    # @api public
+    # @example
+    #   game_type.spring_training? #=> false
+    # @return [Boolean] whether this is a spring training game type
+    def spring_training? = id.eql?(TYPE_SPRING)
+
+    # Returns whether this is an exhibition game type
+    #
+    # @api public
+    # @example
+    #   game_type.exhibition? #=> false
+    # @return [Boolean] whether this is an exhibition game type
+    def exhibition? = id.eql?(TYPE_EXHIBITION)
+
+    # Returns whether this is an All-Star game type
+    #
+    # @api public
+    # @example
+    #   game_type.all_star? #=> false
+    # @return [Boolean] whether this is an All-Star game type
+    def all_star? = id.eql?(TYPE_ALL_STAR)
+
+    # Returns whether this is a Wild Card game type
+    #
+    # @api public
+    # @example
+    #   game_type.wild_card? #=> false
+    # @return [Boolean] whether this is a Wild Card game type
+    def wild_card? = id.eql?(TYPE_WILD_CARD)
+
+    # Returns whether this is a Division Series game type
+    #
+    # @api public
+    # @example
+    #   game_type.division_series? #=> false
+    # @return [Boolean] whether this is a Division Series game type
+    def division_series? = id.eql?(TYPE_DIVISION)
+
+    # Returns whether this is a League Championship Series game type
+    #
+    # @api public
+    # @example
+    #   game_type.lcs? #=> false
+    # @return [Boolean] whether this is a League Championship Series game type
+    def lcs? = id.eql?(TYPE_LCS)
+
+    # Returns whether this is a World Series game type
+    #
+    # @api public
+    # @example
+    #   game_type.world_series? #=> false
+    # @return [Boolean] whether this is a World Series game type
+    def world_series? = id.eql?(TYPE_WORLD_SERIES)
+
+    # Returns whether this is a postseason game type
+    #
+    # @api public
+    # @example
+    #   game_type.postseason? #=> false
+    # @return [Boolean] whether this is a postseason game type
+    # mutant:disable - .to_s is for type safety; include?(nil) returns false anyway
+    def postseason? = POSTSEASON_TYPES.include?(id.to_s)
+  end
+end

data/lib/mlb/game_types.rb

@@ -0,0 +1,12 @@
+require_relative "collection"
+require_relative "game_type"
+
+module MLB
+  # Provides methods for fetching game types from the API
+  #
+  # @example Fetch all game types
+  #   MLB::GameTypes.all #=> [#<MLB::GameType>, ...]
+  class GameTypes < Collection
+    collection endpoint: "gameTypes", item_type: GameType, collection_name: :game_types
+  end
+end

data/lib/mlb/handedness.rb

@@ -1,13 +1,34 @@
-require "shale"
+require_relative "code_description_type"
 
 module MLB
-  class Handedness < Shale::Mapper
-    attribute :code, Shale::Type::String
-    attribute :description, Shale::Type::String
-
-    json do
-      map "code", to: :code
-      map "description", to: :description
-    end
+  # Represents handedness (batting or throwing side)
+  class Handedness < CodeDescriptionType
+    LEFT = "L".freeze
+    RIGHT = "R".freeze
+    SWITCH = "S".freeze
+
+    # Returns whether this is left-handed
+    #
+    # @api public
+    # @example
+    #   handedness.left? #=> true
+    # @return [Boolean] whether this is left-handed
+    def left? = code.eql?(LEFT)
+
+    # Returns whether this is right-handed
+    #
+    # @api public
+    # @example
+    #   handedness.right? #=> false
+    # @return [Boolean] whether this is right-handed
+    def right? = code.eql?(RIGHT)
+
+    # Returns whether this is switch (both sides)
+    #
+    # @api public
+    # @example
+    #   handedness.switch? #=> false
+    # @return [Boolean] whether this is switch
+    def switch? = code.eql?(SWITCH)
   end
 end

data/lib/mlb/high_low.rb

@@ -0,0 +1,121 @@
+require "equalizer"
+require "shale"
+require_relative "team"
+
+module MLB
+  # Represents a high/low stat result
+  class HighLowResult < Shale::Mapper
+    include Equalizer.new(:team, :date, :rank)
+
+    # @!attribute [rw] season
+    #   Returns the season
+    #   @api public
+    #   @example
+    #     result.season #=> "2024"
+    #   @return [String] the season
+    attribute :season, Shale::Type::String
+
+    # @!attribute [rw] team
+    #   Returns the team
+    #   @api public
+    #   @example
+    #     result.team #=> #<MLB::Team>
+    #   @return [Team] the team
+    attribute :team, Team
+
+    # @!attribute [rw] opponent
+    #   Returns the opponent team
+    #   @api public
+    #   @example
+    #     result.opponent #=> #<MLB::Team>
+    #   @return [Team] the opponent
+    attribute :opponent, Team
+
+    # @!attribute [rw] date
+    #   Returns the date
+    #   @api public
+    #   @example
+    #     result.date #=> "2024-06-06"
+    #   @return [String] the date
+    attribute :date, Shale::Type::String
+
+    # @!attribute [rw] is_home
+    #   Returns whether the team was at home
+    #   @api public
+    #   @example
+    #     result.home? #=> false
+    #   @return [Boolean] whether at home
+    attribute :is_home, Shale::Type::Boolean
+
+    # @!attribute [rw] rank
+    #   Returns the rank
+    #   @api public
+    #   @example
+    #     result.rank #=> 1
+    #   @return [Integer] the rank
+    attribute :rank, Shale::Type::Integer
+
+    # Returns whether the team was at home
+    #
+    # @api public
+    # @example
+    #   result.home? #=> false
+    # @return [Boolean] whether at home
+    def home?
+      is_home
+    end
+
+    json do
+      map "season", to: :season
+      map "team", to: :team
+      map "opponent", to: :opponent
+      map "date", to: :date
+      map "isHome", to: :is_home
+      map "rank", to: :rank
+    end
+  end
+
+  # Represents a high/low group
+  class HighLowGroup < Shale::Mapper
+    # @!attribute [rw] splits
+    #   Returns the stat splits
+    #   @api public
+    #   @example
+    #     group.splits #=> [#<MLB::HighLowResult>, ...]
+    #   @return [Array<HighLowResult>] the splits
+    attribute :splits, HighLowResult, collection: true
+
+    json do
+      map "splits", to: :splits
+    end
+  end
+
+  # Provides methods for fetching high/low stats from the API
+  class HighLow < Shale::Mapper
+    # @!attribute [rw] high_low_results
+    #   Returns the high/low results
+    #   @api public
+    #   @example
+    #     high_low.high_low_results #=> [#<MLB::HighLowGroup>, ...]
+    #   @return [Array<HighLowGroup>] the results
+    attribute :high_low_results, HighLowGroup, collection: true
+
+    json do
+      map "highLowResults", to: :high_low_results
+    end
+
+    # Retrieves high/low stats for teams
+    #
+    # @api public
+    # @example Get high/low stats for teams
+    #   MLB::HighLow.find(org_type: "team", season: 2024)
+    # @param org_type [String] the organization type (team, league, sport)
+    # @param season [Integer, nil] the season year (defaults to current year)
+    # @return [Array<HighLowResult>] the high/low results
+    def self.find(org_type:, season: nil)
+      season ||= Utils.current_season
+      response = CLIENT.get("highLow/#{org_type}?#{Utils.build_query(season:)}")
+      from_json(response).high_low_results.flat_map(&:splits)
+    end
+  end
+end

data/lib/mlb/hit_trajectories.rb

@@ -0,0 +1,12 @@
+require_relative "collection"
+require_relative "hit_trajectory"
+
+module MLB
+  # Provides methods for fetching hit trajectories from the API
+  #
+  # @example Fetch all hit trajectories
+  #   MLB::HitTrajectories.all #=> [#<MLB::HitTrajectory>, ...]
+  class HitTrajectories < Collection
+    collection endpoint: "hitTrajectories", item_type: HitTrajectory, collection_name: :hit_trajectories
+  end
+end

data/lib/mlb/hit_trajectory.rb

@@ -0,0 +1,6 @@
+require_relative "code_description_type"
+
+module MLB
+  # Represents a hit trajectory type (e.g., Line Drive, Fly Ball, Ground Ball)
+  class HitTrajectory < CodeDescriptionType; end
+end

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