mlb 0.10.0 → 0.11.0

data/lib/mlb/game_pace.rb

@@ -0,0 +1,173 @@
+require "shale"
+require_relative "sport"
+
+module MLB
+  # Represents game pace statistics
+  class GamePaceStats < Shale::Mapper
+    # @!attribute [rw] hits_per_9inn
+    #   Returns hits per 9 innings
+    #   @api public
+    #   @example
+    #     stats.hits_per_9inn #=> 16.63
+    #   @return [Float] the hits per 9 innings
+    attribute :hits_per_9inn, Shale::Type::Float
+
+    # @!attribute [rw] runs_per_9inn
+    #   Returns runs per 9 innings
+    #   @api public
+    #   @example
+    #     stats.runs_per_9inn #=> 8.91
+    #   @return [Float] the runs per 9 innings
+    attribute :runs_per_9inn, Shale::Type::Float
+
+    # @!attribute [rw] pitches_per_9inn
+    #   Returns pitches per 9 innings
+    #   @api public
+    #   @example
+    #     stats.pitches_per_9inn #=> 296.2
+    #   @return [Float] the pitches per 9 innings
+    attribute :pitches_per_9inn, Shale::Type::Float
+
+    # @!attribute [rw] hits_per_game
+    #   Returns hits per game
+    #   @api public
+    #   @example
+    #     stats.hits_per_game #=> 16.39
+    #   @return [Float] the hits per game
+    attribute :hits_per_game, Shale::Type::Float
+
+    # @!attribute [rw] runs_per_game
+    #   Returns runs per game
+    #   @api public
+    #   @example
+    #     stats.runs_per_game #=> 8.79
+    #   @return [Float] the runs per game
+    attribute :runs_per_game, Shale::Type::Float
+
+    # @!attribute [rw] pitches_per_game
+    #   Returns pitches per game
+    #   @api public
+    #   @example
+    #     stats.pitches_per_game #=> 292.1
+    #   @return [Float] the pitches per game
+    attribute :pitches_per_game, Shale::Type::Float
+
+    # @!attribute [rw] total_games
+    #   Returns total games
+    #   @api public
+    #   @example
+    #     stats.total_games #=> 2429
+    #   @return [Integer] the total games
+    attribute :total_games, Shale::Type::Integer
+
+    # @!attribute [rw] total_innings_played
+    #   Returns total innings played
+    #   @api public
+    #   @example
+    #     stats.total_innings_played #=> 21626.5
+    #   @return [Float] the total innings
+    attribute :total_innings_played, Shale::Type::Float
+
+    # @!attribute [rw] total_hits
+    #   Returns total hits
+    #   @api public
+    #   @example
+    #     stats.total_hits #=> 39823
+    #   @return [Integer] the total hits
+    attribute :total_hits, Shale::Type::Integer
+
+    # @!attribute [rw] total_runs
+    #   Returns total runs
+    #   @api public
+    #   @example
+    #     stats.total_runs #=> 21343
+    #   @return [Integer] the total runs
+    attribute :total_runs, Shale::Type::Integer
+
+    # @!attribute [rw] total_pitches
+    #   Returns total pitches
+    #   @api public
+    #   @example
+    #     stats.total_pitches #=> 709511
+    #   @return [Integer] the total pitches
+    attribute :total_pitches, Shale::Type::Integer
+
+    # @!attribute [rw] time_per_game
+    #   Returns average time per game
+    #   @api public
+    #   @example
+    #     stats.time_per_game #=> "02:38:44"
+    #   @return [String] the time per game
+    attribute :time_per_game, Shale::Type::String
+
+    # @!attribute [rw] time_per_pitch
+    #   Returns average time per pitch
+    #   @api public
+    #   @example
+    #     stats.time_per_pitch #=> "00:00:32"
+    #   @return [String] the time per pitch
+    attribute :time_per_pitch, Shale::Type::String
+
+    # @!attribute [rw] season
+    #   Returns the season
+    #   @api public
+    #   @example
+    #     stats.season #=> "2024"
+    #   @return [String] the season
+    attribute :season, Shale::Type::String
+
+    # @!attribute [rw] sport
+    #   Returns the sport
+    #   @api public
+    #   @example
+    #     stats.sport #=> #<MLB::Sport>
+    #   @return [Sport] the sport
+    attribute :sport, Sport
+
+    json do
+      map "hitsPer9Inn", to: :hits_per_9inn
+      map "runsPer9Inn", to: :runs_per_9inn
+      map "pitchesPer9Inn", to: :pitches_per_9inn
+      map "hitsPerGame", to: :hits_per_game
+      map "runsPerGame", to: :runs_per_game
+      map "pitchesPerGame", to: :pitches_per_game
+      map "totalGames", to: :total_games
+      map "totalInningsPlayed", to: :total_innings_played
+      map "totalHits", to: :total_hits
+      map "totalRuns", to: :total_runs
+      map "totalPitches", to: :total_pitches
+      map "timePerGame", to: :time_per_game
+      map "timePerPitch", to: :time_per_pitch
+      map "season", to: :season
+      map "sport", to: :sport
+    end
+  end
+
+  # Provides methods for fetching game pace data from the API
+  class GamePace < Shale::Mapper
+    # @!attribute [rw] sports
+    #   Returns the sports game pace data
+    #   @api public
+    #   @example
+    #     game_pace.sports #=> [#<MLB::GamePaceStats>, ...]
+    #   @return [Array<GamePaceStats>] the sports data
+    attribute :sports, GamePaceStats, collection: true
+
+    json do
+      map "sports", to: :sports
+    end
+
+    # Retrieves game pace statistics for a season
+    #
+    # @api public
+    # @example Get game pace for 2024
+    #   MLB::GamePace.find(season: 2024)
+    # @param season [Integer, nil] the season year (defaults to current year)
+    # @return [GamePaceStats] the game pace stats for MLB
+    def self.find(season: nil)
+      season ||= Utils.current_season
+      response = CLIENT.get("gamePace?#{Utils.build_query(season:)}")
+      from_json(response).sports.first
+    end
+  end
+end

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