mlb 0.9.0 → 0.11.0

data/lib/mlb/sky.rb

@@ -0,0 +1,6 @@
+require_relative "code_description_type"
+
+module MLB
+  # Represents a sky condition (weather)
+  class Sky < CodeDescriptionType; end
+end

data/lib/mlb/sport.rb

@@ -1,8 +1,19 @@
+require "equalizer"
 require "shale"
+require_relative "comparable_by_attribute"
 
 module MLB
+  # Represents a sport (e.g., MLB, Minor League Baseball)
   class Sport < 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 = :sort_order
 
     attribute :id, Shale::Type::Integer
     attribute :code, Shale::Type::String
@@ -12,7 +23,13 @@ module MLB
     attribute :sort_order, Shale::Type::Integer
     attribute :active, Shale::Type::Boolean
 
-    alias_method :active?, :active
+    # Checks if the sport is active
+    #
+    # @api public
+    # @example
+    #   sport.active? #=> true
+    # @return [Boolean] whether the sport is active
+    def active? = active
 
     json do
       map "id", to: :id
@@ -23,9 +40,5 @@ module MLB
       map "sortOrder", to: :sort_order
       map "activeStatus", to: :active
     end
-
-    def <=>(other)
-      sort_order <=> other.sort_order
-    end
   end
 end

data/lib/mlb/sport_players.rb

@@ -0,0 +1,30 @@
+require "shale"
+require_relative "player"
+
+module MLB
+  # Provides methods for fetching players for a sport from the API
+  class SportPlayers < Shale::Mapper
+    attribute :people, Player, collection: true
+
+    json do
+      map "people", to: :people
+    end
+
+    # Retrieves all players for a sport
+    #
+    # @api public
+    # @example Get all MLB players for a season
+    #   MLB::SportPlayers.all(season: 2024)
+    # @example Get all players with a sport object
+    #   MLB::SportPlayers.all(season: 2024, sport: Sport.new(id: 1))
+    # @param season [Integer, nil] the season year (defaults to current year)
+    # @param sport [Integer, Sport] the sport ID or Sport object
+    # @return [Array<Player>] the players
+    def self.all(season: nil, sport: Utils::DEFAULT_SPORT_ID)
+      season ||= Utils.current_season
+      sport_id = Utils.extract_id(sport)
+      response = CLIENT.get("sports/#{sport_id}/players?#{Utils.build_query(season:)}")
+      from_json(response).people
+    end
+  end
+end

data/lib/mlb/sports.rb

@@ -2,21 +2,31 @@ require "shale"
 require_relative "sport"
 
 module MLB
+  # Collection of sports from the MLB Stats API
   class Sports < Shale::Mapper
-    attribute :copyright, Shale::Type::String
     attribute :sports, Sport, collection: true
 
+    # Retrieves all sports
+    #
+    # @api public
+    # @example
+    #   MLB::Sports.all
+    # @return [Array<Sport>] list of all sports
     def self.all
       response = CLIENT.get("sports")
-      sports = from_json(response)
-      sports.sports.sort!
+      from_json(response).sports.sort
     end
 
+    # Finds a sport by ID
+    #
+    # @api public
+    # @example
+    #   MLB::Sports.find(1)
+    # @param sport [Integer, Sport] the sport ID or Sport object
+    # @return [Sport, nil] the sport if found
     def self.find(sport)
-      id = sport.respond_to?(:id) ? sport.id : sport
-      response = CLIENT.get("sports/#{id}")
-      sports = from_json(response)
-      sports.sports.first
+      response = CLIENT.get("sports/#{Utils.extract_id(sport)}")
+      from_json(response).sports.min_by { |s| s.sort_order || 0 }
     end
   end
 end

data/lib/mlb/standings.rb

@@ -0,0 +1,47 @@
+require "shale"
+require_relative "standings_record"
+
+module MLB
+  # Provides methods for fetching standings from the API
+  class Standings < Shale::Mapper
+    # Default league IDs for American League (103) and National League (104)
+    DEFAULT_LEAGUE_IDS = [103, 104].freeze
+
+    attribute :records, StandingsRecord, collection: true
+
+    json do
+      map "records", to: :records
+    end
+
+    # Retrieves standings for the given leagues
+    #
+    # @api public
+    # @example Get MLB standings
+    #   MLB::Standings.all
+    # @example Get standings for a specific season
+    #   MLB::Standings.all(season: 2023)
+    # @param season [Integer, nil] the season year (defaults to current year)
+    # @param league_ids [Array<Integer>] league IDs (default: [103, 104] for AL and NL)
+    # @return [Array<StandingsRecord>] the standings records
+    def self.all(season: nil, league_ids: DEFAULT_LEAGUE_IDS)
+      season ||= Utils.current_season
+      params = {leagueId: league_ids.join(","), season:}
+      response = CLIENT.get("standings?#{Utils.build_query(params)}")
+      from_json(response).records
+    end
+
+    # Retrieves standings for a specific division
+    #
+    # @api public
+    # @example Get AL East standings
+    #   MLB::Standings.find(division: 201)
+    # @param division [Division, Integer] the division or division ID
+    # @param season [Integer, nil] the season year (defaults to current year)
+    # @param league_ids [Array<Integer>] league IDs (default: [103, 104] for AL and NL)
+    # @return [StandingsRecord, nil] the standings record for the division
+    def self.find(division:, season: nil, league_ids: DEFAULT_LEAGUE_IDS)
+      division_id = Utils.extract_id(division)
+      all(season:, league_ids:).find { |record| record.division&.id.eql?(division_id) }
+    end
+  end
+end

data/lib/mlb/standings_record.rb

@@ -0,0 +1,108 @@
+require "shale"
+require_relative "division"
+require_relative "league"
+require_relative "sport"
+require_relative "team_record"
+
+module MLB
+  # Represents a standings record for a division
+  class StandingsRecord < Shale::Mapper
+    STANDINGS_REGULAR_SEASON = "regularSeason".freeze
+    STANDINGS_WILD_CARD = "wildCard".freeze
+    STANDINGS_DIVISION_LEADERS = "divisionLeaders".freeze
+    STANDINGS_WILD_CARD_WITH_LEADERS = "wildCardWithLeaders".freeze
+    STANDINGS_FIRST_HALF = "firstHalf".freeze
+    STANDINGS_SECOND_HALF = "secondHalf".freeze
+    STANDINGS_SPRING_TRAINING = "springTraining".freeze
+    STANDINGS_POSTSEASON = "postseason".freeze
+
+    # @!attribute [rw] standings_type
+    #   Returns the standings type
+    #   @api public
+    #   @example
+    #     standings_record.standings_type #=> "regularSeason"
+    #   @return [String] the standings type
+    attribute :standings_type, Shale::Type::String
+
+    # @!attribute [rw] league
+    #   Returns the league
+    #   @api public
+    #   @example
+    #     standings_record.league #=> #<MLB::League>
+    #   @return [League] the league
+    attribute :league, League
+
+    # @!attribute [rw] division
+    #   Returns the division
+    #   @api public
+    #   @example
+    #     standings_record.division #=> #<MLB::Division>
+    #   @return [Division] the division
+    attribute :division, Division
+
+    # @!attribute [rw] sport
+    #   Returns the sport
+    #   @api public
+    #   @example
+    #     standings_record.sport #=> #<MLB::Sport>
+    #   @return [Sport] the sport
+    attribute :sport, Sport
+
+    # @!attribute [rw] last_updated
+    #   Returns when the standings were last updated
+    #   @api public
+    #   @example
+    #     standings_record.last_updated #=> "2024-09-23T02:30:10.088Z"
+    #   @return [String] when the standings were last updated
+    attribute :last_updated, Shale::Type::String
+
+    # @!attribute [rw] team_records
+    #   Returns the team records
+    #   @api public
+    #   @example
+    #     standings_record.team_records #=> [#<MLB::TeamRecord>, ...]
+    #   @return [Array<TeamRecord>] the team records
+    attribute :team_records, TeamRecord, collection: true
+
+    # Returns whether this is regular season standings
+    #
+    # @api public
+    # @example
+    #   standings_record.regular_season? #=> true
+    # @return [Boolean] whether this is regular season standings
+    def regular_season? = standings_type.eql?(STANDINGS_REGULAR_SEASON)
+
+    # Returns whether this is wild card standings
+    #
+    # @api public
+    # @example
+    #   standings_record.wild_card? #=> false
+    # @return [Boolean] whether this is wild card standings
+    def wild_card? = standings_type.eql?(STANDINGS_WILD_CARD)
+
+    # Returns whether this is spring training standings
+    #
+    # @api public
+    # @example
+    #   standings_record.spring_training? #=> false
+    # @return [Boolean] whether this is spring training standings
+    def spring_training? = standings_type.eql?(STANDINGS_SPRING_TRAINING)
+
+    # Returns whether this is postseason standings
+    #
+    # @api public
+    # @example
+    #   standings_record.postseason? #=> false
+    # @return [Boolean] whether this is postseason standings
+    def postseason? = standings_type.eql?(STANDINGS_POSTSEASON)
+
+    json do
+      map "standingsType", to: :standings_type
+      map "league", to: :league
+      map "division", to: :division
+      map "sport", to: :sport
+      map "lastUpdated", to: :last_updated
+      map "teamRecords", to: :team_records
+    end
+  end
+end

data/lib/mlb/standings_type.rb

@@ -0,0 +1,25 @@
+require "equalizer"
+require "shale"
+
+module MLB
+  # Represents a standings type
+  class StandingsType < Shale::Mapper
+    include Equalizer.new(:name)
+
+    # @!attribute [rw] name
+    #   Returns the standings type name
+    #   @api public
+    #   @example
+    #     standings_type.name #=> "regularSeason"
+    #   @return [String] the standings type name
+    attribute :name, Shale::Type::String
+
+    # @!attribute [rw] description
+    #   Returns the description
+    #   @api public
+    #   @example
+    #     standings_type.description #=> "Regular Season Standings"
+    #   @return [String] the description
+    attribute :description, Shale::Type::String
+  end
+end

data/lib/mlb/standings_types.rb

@@ -0,0 +1,12 @@
+require_relative "collection"
+require_relative "standings_type"
+
+module MLB
+  # Provides methods for fetching standings types from the API
+  #
+  # @example Fetch all standings types
+  #   MLB::StandingsTypes.all #=> [#<MLB::StandingsType>, ...]
+  class StandingsTypes < Collection
+    collection endpoint: "standingsTypes", item_type: StandingsType, collection_name: :standings_types
+  end
+end

data/lib/mlb/stat_group.rb

@@ -0,0 +1,21 @@
+require "equalizer"
+require "shale"
+
+module MLB
+  # Represents a stat group
+  class StatGroup < Shale::Mapper
+    include Equalizer.new(:display_name)
+
+    # @!attribute [rw] display_name
+    #   Returns the display name for the stat group
+    #   @api public
+    #   @example
+    #     stat_group.display_name #=> "hitting"
+    #   @return [String] the display name for the stat group
+    attribute :display_name, Shale::Type::String
+
+    json do
+      map "displayName", to: :display_name
+    end
+  end
+end

data/lib/mlb/stat_groups.rb

@@ -0,0 +1,12 @@
+require_relative "collection"
+require_relative "stat_group"
+
+module MLB
+  # Provides methods for fetching stat groups from the API
+  #
+  # @example Fetch all stat groups
+  #   MLB::StatGroups.all #=> [#<MLB::StatGroup>, ...]
+  class StatGroups < Collection
+    collection endpoint: "statGroups", item_type: StatGroup, collection_name: :stat_groups
+  end
+end

data/lib/mlb/stat_type.rb

@@ -0,0 +1,21 @@
+require "equalizer"
+require "shale"
+
+module MLB
+  # Represents a stat type
+  class StatType < Shale::Mapper
+    include Equalizer.new(:display_name)
+
+    # @!attribute [rw] display_name
+    #   Returns the display name for the stat type
+    #   @api public
+    #   @example
+    #     stat_type.display_name #=> "season"
+    #   @return [String] the display name for the stat type
+    attribute :display_name, Shale::Type::String
+
+    json do
+      map "displayName", to: :display_name
+    end
+  end
+end

data/lib/mlb/stat_types.rb

@@ -0,0 +1,12 @@
+require_relative "collection"
+require_relative "stat_type"
+
+module MLB
+  # Provides methods for fetching stat types from the API
+  #
+  # @example Fetch all stat types
+  #   MLB::StatTypes.all #=> [#<MLB::StatType>, ...]
+  class StatTypes < Collection
+    collection endpoint: "statTypes", item_type: StatType, collection_name: :stat_types
+  end
+end

data/lib/mlb/stat_values.rb

@@ -0,0 +1,158 @@
+require "shale"
+
+module MLB
+  # Represents offensive stat values for players or teams
+  #
+  # @example Access player stats
+  #   player_stat.stat.games_played #=> 162
+  #   player_stat.stat.home_runs #=> 54
+  #
+  # @example Access team stats
+  #   team_stat.stat.runs #=> 829
+  #   team_stat.stat.ops #=> ".781"
+  class StatValues < Shale::Mapper
+    # @!attribute [rw] games_played
+    #   Returns the number of games played
+    #   @api public
+    #   @example
+    #     stat.games_played #=> 162
+    #   @return [Integer] games played
+    attribute :games_played, Shale::Type::Integer
+
+    # @!attribute [rw] runs
+    #   Returns the number of runs scored
+    #   @api public
+    #   @example
+    #     stat.runs #=> 122
+    #   @return [Integer] runs scored
+    attribute :runs, Shale::Type::Integer
+
+    # @!attribute [rw] doubles
+    #   Returns the number of doubles
+    #   @api public
+    #   @example
+    #     stat.doubles #=> 28
+    #   @return [Integer] doubles
+    attribute :doubles, Shale::Type::Integer
+
+    # @!attribute [rw] triples
+    #   Returns the number of triples
+    #   @api public
+    #   @example
+    #     stat.triples #=> 3
+    #   @return [Integer] triples
+    attribute :triples, Shale::Type::Integer
+
+    # @!attribute [rw] home_runs
+    #   Returns the number of home runs
+    #   @api public
+    #   @example
+    #     stat.home_runs #=> 54
+    #   @return [Integer] home runs
+    attribute :home_runs, Shale::Type::Integer
+
+    # @!attribute [rw] strike_outs
+    #   Returns the number of strikeouts
+    #   @api public
+    #   @example
+    #     stat.strike_outs #=> 175
+    #   @return [Integer] strikeouts
+    attribute :strike_outs, Shale::Type::Integer
+
+    # @!attribute [rw] base_on_balls
+    #   Returns the number of walks
+    #   @api public
+    #   @example
+    #     stat.base_on_balls #=> 111
+    #   @return [Integer] walks
+    attribute :base_on_balls, Shale::Type::Integer
+
+    # @!attribute [rw] hits
+    #   Returns the number of hits
+    #   @api public
+    #   @example
+    #     stat.hits #=> 177
+    #   @return [Integer] hits
+    attribute :hits, Shale::Type::Integer
+
+    # @!attribute [rw] avg
+    #   Returns the batting average
+    #   @api public
+    #   @example
+    #     stat.avg #=> ".311"
+    #   @return [String] batting average
+    attribute :avg, Shale::Type::String
+
+    # @!attribute [rw] at_bats
+    #   Returns the number of at bats
+    #   @api public
+    #   @example
+    #     stat.at_bats #=> 570
+    #   @return [Integer] at bats
+    attribute :at_bats, Shale::Type::Integer
+
+    # @!attribute [rw] obp
+    #   Returns the on-base percentage
+    #   @api public
+    #   @example
+    #     stat.obp #=> ".425"
+    #   @return [String] on-base percentage
+    attribute :obp, Shale::Type::String
+
+    # @!attribute [rw] slg
+    #   Returns the slugging percentage
+    #   @api public
+    #   @example
+    #     stat.slg #=> ".686"
+    #   @return [String] slugging percentage
+    attribute :slg, Shale::Type::String
+
+    # @!attribute [rw] ops
+    #   Returns the on-base plus slugging
+    #   @api public
+    #   @example
+    #     stat.ops #=> "1.111"
+    #   @return [String] on-base plus slugging
+    attribute :ops, Shale::Type::String
+
+    # @!attribute [rw] stolen_bases
+    #   Returns the number of stolen bases
+    #   @api public
+    #   @example
+    #     stat.stolen_bases #=> 9
+    #   @return [Integer] stolen bases
+    attribute :stolen_bases, Shale::Type::Integer
+
+    # @!attribute [rw] rbi
+    #   Returns the number of runs batted in
+    #   @api public
+    #   @example
+    #     stat.rbi #=> 130
+    #   @return [Integer] runs batted in
+    attribute :rbi, Shale::Type::Integer
+
+    json do
+      map "gamesPlayed", to: :games_played
+      map "runs", to: :runs
+      map "doubles", to: :doubles
+      map "triples", to: :triples
+      map "homeRuns", to: :home_runs
+      map "strikeOuts", to: :strike_outs
+      map "baseOnBalls", to: :base_on_balls
+      map "hits", to: :hits
+      map "avg", to: :avg
+      map "atBats", to: :at_bats
+      map "obp", to: :obp
+      map "slg", to: :slg
+      map "ops", to: :ops
+      map "stolenBases", to: :stolen_bases
+      map "rbi", to: :rbi
+    end
+  end
+
+  # @deprecated Use {StatValues} instead
+  PlayerStatValues = StatValues
+
+  # @deprecated Use {StatValues} instead
+  TeamStatValues = StatValues
+end

data/lib/mlb/stats.rb

@@ -0,0 +1,41 @@
+require "shale"
+require_relative "player_stat"
+
+module MLB
+  # Represents a player stat group
+  class PlayerStatGroup < Shale::Mapper
+    attribute :splits, PlayerStat, collection: true
+
+    json do
+      map "splits", to: :splits
+    end
+  end
+
+  # Provides methods for fetching player stats from the API
+  class Stats < Shale::Mapper
+    attribute :stats, PlayerStatGroup, collection: true
+
+    json do
+      map "stats", to: :stats
+    end
+
+    # Retrieves player stats
+    #
+    # @api public
+    # @example Get player hitting stats
+    #   MLB::Stats.find(season: 2024, group: "hitting")
+    # @example Get player pitching stats
+    #   MLB::Stats.find(season: 2024, group: "pitching", stats: "season")
+    # @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)
+    # @param sport [Integer, Sport] the sport ID or Sport object
+    # @return [Array<PlayerStat>] the player stats
+    def self.find(season: nil, group: "hitting", stats: "season", sport: Utils::DEFAULT_SPORT_ID)
+      season ||= Utils.current_season
+      params = {season:, group:, stats:, sportIds: Utils.extract_id(sport)}
+      response = CLIENT.get("stats?#{Utils.build_query(params)}")
+      from_json(response).stats.first&.splits || []
+    end
+  end
+end

data/lib/mlb/status.rb

@@ -1,8 +1,25 @@
+require "equalizer"
 require "shale"
 
 module MLB
+  # Represents a roster status
   class Status < Shale::Mapper
+    include Equalizer.new(:code)
+
+    # @!attribute [rw] code
+    #   Returns the status code
+    #   @api public
+    #   @example
+    #     status.code #=> "A"
+    #   @return [String] the status code
     attribute :code, Shale::Type::String
+
+    # @!attribute [rw] description
+    #   Returns the status description
+    #   @api public
+    #   @example
+    #     status.description #=> "Active"
+    #   @return [String] the status description
     attribute :description, Shale::Type::String
   end
 end