mlb 0.9.0 → 0.11.0

data/lib/mlb/schedule_date.rb

@@ -0,0 +1,37 @@
+require "shale"
+require_relative "scheduled_game"
+
+module MLB
+  # Represents a date within a schedule response
+  class ScheduleDate < Shale::Mapper
+    # @!attribute [rw] date
+    #   Returns the date
+    #   @api public
+    #   @example
+    #     schedule_date.date #=> #<Date: 2024-07-04>
+    #   @return [Date] the date
+    attribute :date, Shale::Type::Date
+
+    # @!attribute [rw] total_games
+    #   Returns the total number of games on this date
+    #   @api public
+    #   @example
+    #     schedule_date.total_games #=> 15
+    #   @return [Integer] the total number of games
+    attribute :total_games, Shale::Type::Integer
+
+    # @!attribute [rw] games
+    #   Returns the games scheduled for this date
+    #   @api public
+    #   @example
+    #     schedule_date.games #=> [#<MLB::ScheduledGame>, ...]
+    #   @return [Array<ScheduledGame>] the games scheduled for this date
+    attribute :games, ScheduledGame, collection: true
+
+    json do
+      map "date", to: :date
+      map "totalGames", to: :total_games
+      map "games", to: :games
+    end
+  end
+end

data/lib/mlb/schedule_event_type.rb

@@ -0,0 +1,25 @@
+require "equalizer"
+require "shale"
+
+module MLB
+  # Represents a schedule event type
+  class ScheduleEventType < Shale::Mapper
+    include Equalizer.new(:code)
+
+    # @!attribute [rw] code
+    #   Returns the event type code
+    #   @api public
+    #   @example
+    #     schedule_event_type.code #=> "P"
+    #   @return [String] the event type code
+    attribute :code, Shale::Type::String
+
+    # @!attribute [rw] name
+    #   Returns the event type name
+    #   @api public
+    #   @example
+    #     schedule_event_type.name #=> "Postseason Game"
+    #   @return [String] the event type name
+    attribute :name, Shale::Type::String
+  end
+end

data/lib/mlb/schedule_event_types.rb

@@ -0,0 +1,12 @@
+require_relative "collection"
+require_relative "schedule_event_type"
+
+module MLB
+  # Provides methods for fetching schedule event types from the API
+  #
+  # @example Fetch all schedule event types
+  #   MLB::ScheduleEventTypes.all #=> [#<MLB::ScheduleEventType>, ...]
+  class ScheduleEventTypes < Collection
+    collection endpoint: "scheduleEventTypes", item_type: ScheduleEventType, collection_name: :schedule_event_types
+  end
+end

data/lib/mlb/scheduled_game.rb

@@ -0,0 +1,321 @@
+require "equalizer"
+require "shale"
+require_relative "game_status"
+require_relative "team"
+require_relative "venue"
+
+module MLB
+  # Represents a team's information in a scheduled game
+  class ScheduledGameTeam < Shale::Mapper
+    include Equalizer.new(:team)
+
+    # @!attribute [rw] team
+    #   Returns the team
+    #   @api public
+    #   @example
+    #     scheduled_game_team.team #=> #<MLB::Team>
+    #   @return [Team] the team
+    attribute :team, Team
+
+    # @!attribute [rw] score
+    #   Returns the team's score
+    #   @api public
+    #   @example
+    #     scheduled_game_team.score #=> 5
+    #   @return [Integer] the team's score
+    attribute :score, Shale::Type::Integer
+
+    # @!attribute [rw] is_winner
+    #   Returns whether this team won the game
+    #   @api public
+    #   @example
+    #     scheduled_game_team.is_winner #=> true
+    #   @return [Boolean] whether this team won the game
+    attribute :is_winner, Shale::Type::Boolean
+
+    # @!method winner?
+    #   Returns whether this team won the game
+    #   @api public
+    #   @example
+    #     scheduled_game_team.winner? #=> true
+    #   @return [Boolean, nil] whether this team won the game
+    alias_method :winner?, :is_winner
+
+    json do
+      map "team", to: :team
+      map "score", to: :score
+      map "isWinner", to: :is_winner
+    end
+  end
+
+  # Represents the teams playing in a scheduled game
+  class ScheduledGameTeams < Shale::Mapper
+    # @!attribute [rw] away
+    #   Returns the away team information
+    #   @api public
+    #   @example
+    #     teams.away #=> #<MLB::ScheduledGameTeam>
+    #   @return [ScheduledGameTeam] the away team information
+    attribute :away, ScheduledGameTeam
+
+    # @!attribute [rw] home
+    #   Returns the home team information
+    #   @api public
+    #   @example
+    #     teams.home #=> #<MLB::ScheduledGameTeam>
+    #   @return [ScheduledGameTeam] the home team information
+    attribute :home, ScheduledGameTeam
+  end
+
+  # Represents a scheduled game from the MLB Stats API
+  class ScheduledGame < Shale::Mapper
+    include Equalizer.new(:game_pk)
+
+    # @!attribute [rw] game_pk
+    #   Returns the unique game identifier
+    #   @api public
+    #   @example
+    #     scheduled_game.game_pk #=> 744834
+    #   @return [Integer] the unique game identifier
+    attribute :game_pk, Shale::Type::Integer
+
+    # @!attribute [rw] link
+    #   Returns the API link for the game feed
+    #   @api public
+    #   @example
+    #     scheduled_game.link #=> "/api/v1.1/game/744834/feed/live"
+    #   @return [String] the API link for the game feed
+    attribute :link, Shale::Type::String
+
+    # @!attribute [rw] game_type
+    #   Returns the game type code
+    #   @api public
+    #   @example
+    #     scheduled_game.game_type #=> "R"
+    #   @return [String] the game type code
+    attribute :game_type, Shale::Type::String
+
+    # @!attribute [rw] season
+    #   Returns the season year
+    #   @api public
+    #   @example
+    #     scheduled_game.season #=> "2024"
+    #   @return [String] the season year
+    attribute :season, Shale::Type::String
+
+    # @!attribute [rw] game_date
+    #   Returns the game date and time
+    #   @api public
+    #   @example
+    #     scheduled_game.game_date #=> "2024-07-04T15:05:00Z"
+    #   @return [String] the game date and time
+    attribute :game_date, Shale::Type::String
+
+    # @!attribute [rw] official_date
+    #   Returns the official game date
+    #   @api public
+    #   @example
+    #     scheduled_game.official_date #=> #<Date: 2024-07-04>
+    #   @return [Date] the official game date
+    attribute :official_date, Shale::Type::Date
+
+    # @!attribute [rw] status
+    #   Returns the game status
+    #   @api public
+    #   @example
+    #     scheduled_game.status #=> #<MLB::GameStatus>
+    #   @return [GameStatus] the game status
+    attribute :status, GameStatus
+
+    # @!attribute [rw] teams
+    #   Returns the teams playing
+    #   @api public
+    #   @example
+    #     scheduled_game.teams #=> #<MLB::ScheduledGameTeams>
+    #   @return [ScheduledGameTeams] the teams playing
+    attribute :teams, ScheduledGameTeams
+
+    # @!attribute [rw] venue
+    #   Returns the game venue
+    #   @api public
+    #   @example
+    #     scheduled_game.venue #=> #<MLB::Venue>
+    #   @return [Venue] the game venue
+    attribute :venue, Venue
+
+    # @!attribute [rw] is_tie
+    #   Returns whether the game ended in a tie
+    #   @api public
+    #   @example
+    #     scheduled_game.is_tie #=> false
+    #   @return [Boolean] whether the game ended in a tie
+    attribute :is_tie, Shale::Type::Boolean
+
+    # @!attribute [rw] game_number
+    #   Returns the game number (for doubleheaders)
+    #   @api public
+    #   @example
+    #     scheduled_game.game_number #=> 1
+    #   @return [Integer] the game number
+    attribute :game_number, Shale::Type::Integer
+
+    # @!attribute [rw] double_header
+    #   Returns the doubleheader indicator
+    #   @api public
+    #   @example
+    #     scheduled_game.double_header #=> "N"
+    #   @return [String] the doubleheader indicator
+    attribute :double_header, Shale::Type::String
+
+    # @!attribute [rw] day_night
+    #   Returns whether the game is a day or night game
+    #   @api public
+    #   @example
+    #     scheduled_game.day_night #=> "day"
+    #   @return [String] the day/night indicator
+    attribute :day_night, Shale::Type::String
+
+    # @!attribute [rw] scheduled_innings
+    #   Returns the number of scheduled innings
+    #   @api public
+    #   @example
+    #     scheduled_game.scheduled_innings #=> 9
+    #   @return [Integer] the number of scheduled innings
+    attribute :scheduled_innings, Shale::Type::Integer
+
+    # @!attribute [rw] series_description
+    #   Returns the series description
+    #   @api public
+    #   @example
+    #     scheduled_game.series_description #=> "Regular Season"
+    #   @return [String] the series description
+    attribute :series_description, Shale::Type::String
+
+    # @!attribute [rw] games_in_series
+    #   Returns the number of games in the series
+    #   @api public
+    #   @example
+    #     scheduled_game.games_in_series #=> 4
+    #   @return [Integer] the number of games in the series
+    attribute :games_in_series, Shale::Type::Integer
+
+    # @!attribute [rw] series_game_number
+    #   Returns the game number within the series
+    #   @api public
+    #   @example
+    #     scheduled_game.series_game_number #=> 1
+    #   @return [Integer] the game number within the series
+    attribute :series_game_number, Shale::Type::Integer
+
+    # @!method tie?
+    #   Returns whether the game ended in a tie
+    #   @api public
+    #   @example
+    #     scheduled_game.tie? #=> false
+    #   @return [Boolean, nil] whether the game ended in a tie
+    alias_method :tie?, :is_tie
+
+    # Day game indicator value
+    DAY = "day".freeze
+    # Night game indicator value
+    NIGHT = "night".freeze
+    # Doubleheader indicator values that indicate a doubleheader
+    DOUBLE_HEADER_VALUES = %w[Y S].freeze
+    # Game type: Regular Season
+    GAME_TYPE_REGULAR = "R".freeze
+    # Game type: Spring Training
+    GAME_TYPE_SPRING = "S".freeze
+    # Game type: Exhibition
+    GAME_TYPE_EXHIBITION = "E".freeze
+    # Game type: All-Star Game
+    GAME_TYPE_ALL_STAR = "A".freeze
+    # Game type codes that indicate postseason games
+    POSTSEASON_GAME_TYPES = %w[F D L W].freeze
+
+    # Returns whether this is a day game
+    #
+    # @api public
+    # @example
+    #   scheduled_game.day? #=> true
+    # @return [Boolean] true if the game is a day game
+    def day? = day_night.eql?(DAY)
+
+    # Returns whether this is a night game
+    #
+    # @api public
+    # @example
+    #   scheduled_game.night? #=> false
+    # @return [Boolean] true if the game is a night game
+    def night? = day_night.eql?(NIGHT)
+
+    # Returns whether this game is part of a doubleheader
+    #
+    # @api public
+    # @example
+    #   scheduled_game.double_header? #=> false
+    # @return [Boolean] true if the game is part of a doubleheader
+    # mutant:disable - .to_s is for type safety; include?(nil) returns false anyway
+    def double_header? = DOUBLE_HEADER_VALUES.include?(double_header.to_s)
+
+    # Returns whether this is a regular season game
+    #
+    # @api public
+    # @example
+    #   scheduled_game.regular_season? #=> true
+    # @return [Boolean] true if the game is a regular season game
+    def regular_season? = game_type.eql?(GAME_TYPE_REGULAR)
+
+    # Returns whether this is a spring training game
+    #
+    # @api public
+    # @example
+    #   scheduled_game.spring_training? #=> false
+    # @return [Boolean] true if the game is a spring training game
+    def spring_training? = game_type.eql?(GAME_TYPE_SPRING)
+
+    # Returns whether this is an exhibition game
+    #
+    # @api public
+    # @example
+    #   scheduled_game.exhibition? #=> false
+    # @return [Boolean] true if the game is an exhibition game
+    def exhibition? = game_type.eql?(GAME_TYPE_EXHIBITION)
+
+    # Returns whether this is an All-Star game
+    #
+    # @api public
+    # @example
+    #   scheduled_game.all_star? #=> false
+    # @return [Boolean] true if the game is an All-Star game
+    def all_star? = game_type.eql?(GAME_TYPE_ALL_STAR)
+
+    # Returns whether this is a postseason game
+    #
+    # @api public
+    # @example
+    #   scheduled_game.postseason? #=> false
+    # @return [Boolean] true if the game is a postseason game
+    # mutant:disable - .to_s is for type safety; include?(nil) returns false anyway
+    def postseason? = POSTSEASON_GAME_TYPES.include?(game_type.to_s)
+
+    json do
+      map "gamePk", to: :game_pk
+      map "link", to: :link
+      map "gameType", to: :game_type
+      map "season", to: :season
+      map "gameDate", to: :game_date
+      map "officialDate", to: :official_date
+      map "status", to: :status
+      map "teams", to: :teams
+      map "venue", to: :venue
+      map "isTie", to: :is_tie
+      map "gameNumber", to: :game_number
+      map "doubleHeader", to: :double_header
+      map "dayNight", to: :day_night
+      map "scheduledInnings", to: :scheduled_innings
+      map "seriesDescription", to: :series_description
+      map "gamesInSeries", to: :games_in_series
+      map "seriesGameNumber", to: :series_game_number
+    end
+  end
+end

data/lib/mlb/season.rb

@@ -0,0 +1,74 @@
+require "equalizer"
+require "shale"
+require_relative "comparable_by_attribute"
+require_relative "league"
+require_relative "sport"
+
+module MLB
+  # Represents a season
+  class Season < Shale::Mapper
+    include Comparable
+    include ComparableByAttribute
+    include Equalizer.new(:id)
+
+    # Returns the attribute used for sorting
+    #
+    # @api private
+    # @return [Symbol] the attribute used for comparison
+    def comparable_attribute = :id
+
+    attribute :id, Shale::Type::Integer
+    attribute :has_wildcard, Shale::Type::Boolean
+    attribute :preseason_start_date, Shale::Type::Date
+    attribute :preseason_end_date, Shale::Type::Date
+    attribute :season_start_date, Shale::Type::Date
+    attribute :spring_start_date, Shale::Type::Date
+    attribute :spring_end_date, Shale::Type::Date
+    attribute :regular_season_start_date, Shale::Type::Date
+    attribute :last_date_first_half, Shale::Type::Date
+    attribute :all_star_date, Shale::Type::Date
+    attribute :first_date_second_half, Shale::Type::Date
+    attribute :regular_season_end_date, Shale::Type::Date
+    attribute :postseason_start_date, Shale::Type::Date
+    attribute :postseason_end_date, Shale::Type::Date
+    attribute :season_end_date, Shale::Type::Date
+    attribute :offseason_start_date, Shale::Type::Date
+    attribute :offseason_end_date, Shale::Type::Date
+    attribute :season_level_gameday_type, Shale::Type::String
+    attribute :game_level_gameday_type, Shale::Type::String
+    attribute :qualifier_plate_appearances, Shale::Type::Float
+    attribute :qualifier_outs_pitched, Shale::Type::Float
+
+    # Returns whether the season has a wild card
+    #
+    # @api public
+    # @example
+    #   season.wildcard?
+    # @return [Boolean, nil] true if the season has a wild card
+    alias_method :wildcard?, :has_wildcard
+
+    json do
+      map "seasonId", to: :id
+      map "hasWildcard", to: :has_wildcard
+      map "preSeasonStartDate", to: :preseason_start_date
+      map "preSeasonEndDate", to: :preseason_end_date
+      map "seasonStartDate", to: :season_start_date
+      map "springStartDate", to: :spring_start_date
+      map "springEndDate", to: :spring_end_date
+      map "regularSeasonStartDate", to: :regular_season_start_date
+      map "lastDate1stHalf", to: :last_date_first_half
+      map "allStarDate", to: :all_star_date
+      map "firstDate2ndHalf", to: :first_date_second_half
+      map "regularSeasonEndDate", to: :regular_season_end_date
+      map "postSeasonStartDate", to: :postseason_start_date
+      map "postSeasonEndDate", to: :postseason_end_date
+      map "seasonEndDate", to: :season_end_date
+      map "offseasonStartDate", to: :offseason_start_date
+      map "offSeasonEndDate", to: :offseason_end_date
+      map "seasonLevelGamedayType", to: :season_level_gameday_type
+      map "gameLevelGamedayType", to: :game_level_gameday_type
+      map "qualifierPlateAppearances", to: :qualifier_plate_appearances
+      map "qualifierOutsPitched", to: :qualifier_outs_pitched
+    end
+  end
+end

data/lib/mlb/season_date_info.rb

@@ -1,7 +1,11 @@
+require "equalizer"
 require "shale"
 
 module MLB
+  # Represents important dates for an MLB season
   class SeasonDateInfo < Shale::Mapper
+    include Equalizer.new(:season_id)
+
     attribute :season_id, Shale::Type::String
     attribute :pre_season_start_date, Shale::Type::Date
     attribute :pre_season_end_date, Shale::Type::Date

data/lib/mlb/seasons.rb

@@ -0,0 +1,36 @@
+require "shale"
+require_relative "season"
+
+module MLB
+  # Collection of seasons from the MLB Stats API
+  class Seasons < Shale::Mapper
+    attribute :seasons, Season, collection: true
+
+    # Retrieves all seasons
+    #
+    # @api public
+    # @example
+    #   MLB::Seasons.all
+    # @param sport [Integer, Sport] the sport ID or Sport object
+    # @return [Array<Season>] list of all seasons
+    def self.all(sport: Utils::DEFAULT_SPORT_ID)
+      params = {sportId: Utils.extract_id(sport)}
+      response = CLIENT.get("seasons?#{Utils.build_query(params)}")
+      from_json(response).seasons.sort
+    end
+
+    # Finds a season by ID
+    #
+    # @api public
+    # @example
+    #   MLB::Seasons.find(2024)
+    # @param season [Integer, Season] the season ID or Season object
+    # @param sport [Integer, Sport] the sport ID or Sport object
+    # @return [Season, nil] the season if found
+    def self.find(season, sport: Utils::DEFAULT_SPORT_ID)
+      params = {sportId: Utils.extract_id(sport)}
+      response = CLIENT.get("seasons/#{Utils.extract_id(season)}?#{Utils.build_query(params)}")
+      from_json(response).seasons.min_by { |s| s.id || 0 }
+    end
+  end
+end

data/lib/mlb/single_team_stats.rb

@@ -0,0 +1,33 @@
+require "shale"
+require_relative "team_stats"
+
+module MLB
+  # Provides methods for fetching individual team stats from the API
+  class SingleTeamStats < Shale::Mapper
+    attribute :stats, TeamStatGroup, collection: true
+
+    json do
+      map "stats", to: :stats
+    end
+
+    # Retrieves stats for a specific team
+    #
+    # @api public
+    # @example Get team hitting stats
+    #   MLB::SingleTeamStats.find(team: 147, season: 2024, group: "hitting")
+    # @example Get team pitching stats
+    #   MLB::SingleTeamStats.find(team: Team.new(id: 147), season: 2024, group: "pitching")
+    # @param team [Integer, Team] the team ID or Team object
+    # @param season [Integer, nil] the season year (defaults to current year)
+    # @param group [String] the stat group (hitting, pitching, fielding)
+    # @param stats [String] the stats type (default: season)
+    # @return [Array<TeamStat>] the team stats
+    def self.find(team:, season: nil, group: "hitting", stats: "season")
+      season ||= Utils.current_season
+      team_id = Utils.extract_id(team)
+      params = {season:, group:, stats:}
+      response = CLIENT.get("teams/#{team_id}/stats?#{Utils.build_query(params)}")
+      from_json(response).stats.first&.splits || []
+    end
+  end
+end

data/lib/mlb/situation_code.rb

@@ -0,0 +1,116 @@
+require "equalizer"
+require "shale"
+
+module MLB
+  # Represents a situation code for statistical filtering
+  class SituationCode < Shale::Mapper
+    include Equalizer.new(:code)
+
+    # @!attribute [rw] code
+    #   Returns the situation code
+    #   @api public
+    #   @example
+    #     situation_code.code #=> "h"
+    #   @return [String] the situation code
+    attribute :code, Shale::Type::String
+
+    # @!attribute [rw] sort_order
+    #   Returns the sort order
+    #   @api public
+    #   @example
+    #     situation_code.sort_order #=> 1
+    #   @return [Integer] the sort order
+    attribute :sort_order, Shale::Type::Integer
+
+    # @!attribute [rw] navigation_menu
+    #   Returns the navigation menu category
+    #   @api public
+    #   @example
+    #     situation_code.navigation_menu #=> "Game"
+    #   @return [String] the navigation menu category
+    attribute :navigation_menu, Shale::Type::String
+
+    # @!attribute [rw] description
+    #   Returns the description
+    #   @api public
+    #   @example
+    #     situation_code.description #=> "Home Games"
+    #   @return [String] the description
+    attribute :description, Shale::Type::String
+
+    # @!attribute [rw] team
+    #   Returns whether this applies to team statistics
+    #   @api public
+    #   @example
+    #     situation_code.team #=> true
+    #   @return [Boolean] whether this applies to team statistics
+    attribute :team, Shale::Type::Boolean
+
+    # @!attribute [rw] batting
+    #   Returns whether this applies to batting statistics
+    #   @api public
+    #   @example
+    #     situation_code.batting #=> true
+    #   @return [Boolean] whether this applies to batting statistics
+    attribute :batting, Shale::Type::Boolean
+
+    # @!attribute [rw] fielding
+    #   Returns whether this applies to fielding statistics
+    #   @api public
+    #   @example
+    #     situation_code.fielding #=> true
+    #   @return [Boolean] whether this applies to fielding statistics
+    attribute :fielding, Shale::Type::Boolean
+
+    # @!attribute [rw] pitching
+    #   Returns whether this applies to pitching statistics
+    #   @api public
+    #   @example
+    #     situation_code.pitching #=> true
+    #   @return [Boolean] whether this applies to pitching statistics
+    attribute :pitching, Shale::Type::Boolean
+
+    # Returns whether this applies to team statistics
+    #
+    # @api public
+    # @example
+    #   situation_code.team? #=> true
+    # @return [Boolean] whether this applies to team statistics
+    def team? = team
+
+    # Returns whether this applies to batting statistics
+    #
+    # @api public
+    # @example
+    #   situation_code.batting? #=> true
+    # @return [Boolean] whether this applies to batting statistics
+    def batting? = batting
+
+    # Returns whether this applies to fielding statistics
+    #
+    # @api public
+    # @example
+    #   situation_code.fielding? #=> true
+    # @return [Boolean] whether this applies to fielding statistics
+    def fielding? = fielding
+
+    # Returns whether this applies to pitching statistics
+    #
+    # @api public
+    # @example
+    #   situation_code.pitching? #=> true
+    # @return [Boolean] whether this applies to pitching statistics
+    def pitching? = pitching
+
+    json do
+      map "code", to: :code
+      map "sortOrder", to: :sort_order
+      map "navigationMenu", to: :navigation_menu
+      map "description", to: :description
+      map "team", to: :team
+      map "batting", to: :batting
+      map "fielding", to: :fielding
+      map "pitching", to: :pitching
+    end
+  end
+end

data/lib/mlb/situation_codes.rb

@@ -0,0 +1,12 @@
+require_relative "collection"
+require_relative "situation_code"
+
+module MLB
+  # Provides methods for fetching situation codes from the API
+  #
+  # @example Fetch all situation codes
+  #   MLB::SituationCodes.all #=> [#<MLB::SituationCode>, ...]
+  class SituationCodes < Collection
+    collection endpoint: "situationCodes", item_type: SituationCode, collection_name: :situation_codes
+  end
+end

data/lib/mlb/skies.rb

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