mlb 0.9.0 → 0.11.0

data/lib/mlb/streaks.rb

@@ -0,0 +1,184 @@
+require "shale"
+require_relative "player"
+require_relative "team"
+
+module MLB
+  # Represents a player's active streak (hitting streak, on-base streak, etc.)
+  class PlayerStreak < Shale::Mapper
+    include Equalizer.new(:player_id, :streak_type, :current_streak)
+
+    STREAK_HITTING = "hittingStreak".freeze
+    STREAK_ON_BASE = "onBaseStreak".freeze
+
+    # @!attribute [rw] player_id
+    #   Returns the player ID
+    #   @api public
+    #   @example
+    #     streak.player_id #=> 660271
+    #   @return [Integer] the player ID
+    attribute :player_id, Shale::Type::Integer
+
+    # @!attribute [rw] player_name
+    #   Returns the player name
+    #   @api public
+    #   @example
+    #     streak.player_name #=> "Shohei Ohtani"
+    #   @return [String] the player name
+    attribute :player_name, Shale::Type::String
+
+    # @!attribute [rw] streak_type
+    #   Returns the streak type
+    #   @api public
+    #   @example
+    #     streak.streak_type #=> "hittingStreak"
+    #   @return [String] the streak type
+    attribute :streak_type, Shale::Type::String
+
+    # @!attribute [rw] current_streak
+    #   Returns the current streak length
+    #   @api public
+    #   @example
+    #     streak.current_streak #=> 15
+    #   @return [Integer] the current streak
+    attribute :current_streak, Shale::Type::Integer
+
+    # @!attribute [rw] current_streak_stat
+    #   Returns the stat during the streak
+    #   @api public
+    #   @example
+    #     streak.current_streak_stat #=> "20-for-58"
+    #   @return [String] the streak stat
+    attribute :current_streak_stat, Shale::Type::String
+
+    # @!attribute [rw] team
+    #   Returns the player's team
+    #   @api public
+    #   @example
+    #     streak.team #=> #<MLB::Team>
+    #   @return [Team] the team
+    attribute :team, Team
+
+    # Returns whether this is a hitting streak
+    #
+    # @api public
+    # @example
+    #   streak.hitting_streak? #=> true
+    # @return [Boolean] whether this is a hitting streak
+    def hitting_streak? = streak_type.eql?(STREAK_HITTING)
+
+    # Returns whether this is an on-base streak
+    #
+    # @api public
+    # @example
+    #   streak.on_base_streak? #=> false
+    # @return [Boolean] whether this is an on-base streak
+    def on_base_streak? = streak_type.eql?(STREAK_ON_BASE)
+
+    json do
+      map "playerId", to: :player_id
+      map "playerName", to: :player_name
+      map "streakType", to: :streak_type
+      map "currentStreak", to: :current_streak
+      map "currentStreakStat", to: :current_streak_stat
+      map "team", to: :team
+    end
+  end
+
+  # Represents a streaks category
+  class StreakCategory < Shale::Mapper
+    CATEGORY_HITTING = "hittingStreak".freeze
+    CATEGORY_ON_BASE = "onBaseStreak".freeze
+
+    # @!attribute [rw] category_type
+    #   Returns the streak category type
+    #   @api public
+    #   @example
+    #     category.category_type #=> "hittingStreak"
+    #   @return [String] the category type
+    attribute :category_type, Shale::Type::String
+
+    # @!attribute [rw] streaks
+    #   Returns the streaks
+    #   @api public
+    #   @example
+    #     category.streaks #=> [#<MLB::PlayerStreak>, ...]
+    #   @return [Array<PlayerStreak>] the streaks
+    attribute :streaks, PlayerStreak, collection: true
+
+    # Returns whether this is a hitting streak category
+    #
+    # @api public
+    # @example
+    #   category.hitting_streak? #=> true
+    # @return [Boolean] whether this is a hitting streak category
+    def hitting_streak? = category_type.eql?(CATEGORY_HITTING)
+
+    # Returns whether this is an on-base streak category
+    #
+    # @api public
+    # @example
+    #   category.on_base_streak? #=> false
+    # @return [Boolean] whether this is an on-base streak category
+    def on_base_streak? = category_type.eql?(CATEGORY_ON_BASE)
+
+    json do
+      map "streakType", to: :category_type
+      map "streaks", to: :streaks
+    end
+  end
+
+  # Provides methods for fetching streak data from the API
+  class Streaks < Shale::Mapper
+    # @!attribute [rw] streak_stats
+    #   Returns the streak categories
+    #   @api public
+    #   @example
+    #     streaks.streak_stats #=> [#<MLB::StreakCategory>, ...]
+    #   @return [Array<StreakCategory>] the streak categories
+    attribute :streak_stats, StreakCategory, collection: true
+
+    json do
+      map "streakStats", to: :streak_stats
+    end
+
+    # Retrieves hitting streaks
+    #
+    # @api public
+    # @example Get current hitting streaks
+    #   MLB::Streaks.hitting(season: 2024)
+    # @param season [Integer, nil] the season year (defaults to current year)
+    # @param limit [Integer] the maximum number of results (defaults to 10)
+    # @return [Array<PlayerStreak>] the hitting streaks
+    def self.hitting(season: nil, limit: 10)
+      find(streak_type: "hittingStreak", season:, limit:)
+    end
+
+    # Retrieves on-base streaks
+    #
+    # @api public
+    # @example Get current on-base streaks
+    #   MLB::Streaks.on_base(season: 2024)
+    # @param season [Integer, nil] the season year (defaults to current year)
+    # @param limit [Integer] the maximum number of results (defaults to 10)
+    # @return [Array<PlayerStreak>] the on-base streaks
+    def self.on_base(season: nil, limit: 10)
+      find(streak_type: "onBaseStreak", season:, limit:)
+    end
+
+    # Retrieves streaks by type
+    #
+    # @api public
+    # @example Get hitting streaks
+    #   MLB::Streaks.find(streak_type: "hittingStreak", season: 2024)
+    # @param streak_type [String] the streak type
+    # @param season [Integer, nil] the season year (defaults to current year)
+    # @param limit [Integer] the maximum number of results (defaults to 10)
+    # @return [Array<PlayerStreak>] the streaks
+    def self.find(streak_type:, season: nil, limit: 10)
+      season ||= Utils.current_season
+      params = {streakType: streak_type, season:, limit:}
+      response = CLIENT.get("stats/streaks?#{Utils.build_query(params)}")
+      from_json(response).streak_stats.first&.streaks || []
+    end
+  end
+end

data/lib/mlb/team.rb

@@ -1,14 +1,54 @@
+require "equalizer"
 require "shale"
 require_relative "division"
 require_relative "league"
 require_relative "sport"
 require_relative "venue"
 
+# Ruby interface to the MLB Stats API
 module MLB
+  # Represents a team
   class Team < Shale::Mapper
+    include Equalizer.new(:id)
+
+    ALL_STAR_YES = "Y".freeze
+    ALL_STAR_NO = "N".freeze
+
+    # Team ID constants
+    AZ = 109
+    ATH = 133
+    ATL = 144
+    BAL = 110
+    BOS = 111
+    CHC = 112
+    CWS = 145
+    CIN = 113
+    CLE = 114
+    COL = 115
+    DET = 116
+    HOU = 117
+    KC = 118
+    LAA = 108
+    LAD = 119
+    MIA = 146
+    MIL = 158
+    MIN = 142
+    NYM = 121
+    NYY = 147
+    PHI = 143
+    PIT = 134
+    SD = 135
+    SF = 137
+    SEA = 136
+    STL = 138
+    TB = 139
+    TEX = 140
+    TOR = 141
+    WSH = 120
+
+    attribute :id, Shale::Type::Integer
     attribute :spring_league, League
     attribute :all_star_status, Shale::Type::String
-    attribute :id, Shale::Type::Integer
     attribute :name, Shale::Type::String
     attribute :link, Shale::Type::String
     attribute :season, Shale::Type::Integer
@@ -28,8 +68,22 @@ module MLB
     attribute :club_name, Shale::Type::String
     attribute :active, Shale::Type::Boolean
 
+    # Returns whether the team is active
+    #
+    # @api public
+    # @example
+    #   team.active?
+    # @return [Boolean, nil] true if the team is active
     alias_method :active?, :active
 
+    # Returns whether this is an All-Star team
+    #
+    # @api public
+    # @example
+    #   team.all_star? #=> false
+    # @return [Boolean] whether this is an All-Star team
+    def all_star? = all_star_status.eql?(ALL_STAR_YES)
+
     json do
       map "springLeague", to: :spring_league
       map "allStarStatus", to: :all_star_status
@@ -54,12 +108,17 @@ module MLB
       map "active", to: :active
     end
 
-    def roster(season: Time.now.year)
-      params = {season:}
-      query_string = URI.encode_www_form(params)
-      response = CLIENT.get("teams/#{id}/roster?#{query_string}")
-      roster = Roster.from_json(response)
-      roster.roster
+    # Retrieves the team's roster
+    #
+    # @api public
+    # @example
+    #   team.roster
+    # @param season [Integer, nil] the season year (defaults to current year)
+    # @return [Array<RosterEntry>] list of roster entries
+    def roster(season: nil)
+      season ||= Utils.current_season
+      response = CLIENT.get("teams/#{id}/roster?#{Utils.build_query(season:)}")
+      Roster.from_json(response).roster
     end
   end
 end

data/lib/mlb/team_history.rb

@@ -0,0 +1,28 @@
+require "shale"
+require_relative "team"
+
+module MLB
+  # Provides methods for fetching team history from the API
+  class TeamHistory < Shale::Mapper
+    attribute :teams, Team, collection: true
+
+    json do
+      map "teams", to: :teams
+    end
+
+    # Retrieves historical team records
+    #
+    # @api public
+    # @example Get history for a team
+    #   MLB::TeamHistory.find(team: 147)
+    # @example Get history for a team object
+    #   MLB::TeamHistory.find(team: Team.new(id: 147))
+    # @param team [Integer, Team] the team ID or Team object
+    # @return [Array<Team>] historical team records
+    def self.find(team:)
+      params = {teamIds: Utils.extract_id(team)}
+      response = CLIENT.get("teams/history?#{Utils.build_query(params)}")
+      from_json(response).teams
+    end
+  end
+end

data/lib/mlb/team_leader.rb

@@ -0,0 +1,59 @@
+require "equalizer"
+require "shale"
+require_relative "player"
+require_relative "team"
+
+module MLB
+  # Represents a team leader entry
+  class TeamLeader < Shale::Mapper
+    include Equalizer.new(:rank, :person)
+
+    # @!attribute [rw] rank
+    #   Returns the leader's rank
+    #   @api public
+    #   @example
+    #     leader.rank #=> 1
+    #   @return [Integer] the rank
+    attribute :rank, Shale::Type::Integer
+
+    # @!attribute [rw] value
+    #   Returns the stat value
+    #   @api public
+    #   @example
+    #     leader.value #=> "58"
+    #   @return [String] the stat value
+    attribute :value, Shale::Type::String
+
+    # @!attribute [rw] person
+    #   Returns the player
+    #   @api public
+    #   @example
+    #     leader.person #=> #<MLB::Player>
+    #   @return [Player] the player
+    attribute :person, Player
+
+    # @!attribute [rw] team
+    #   Returns the team
+    #   @api public
+    #   @example
+    #     leader.team #=> #<MLB::Team>
+    #   @return [Team] the team
+    attribute :team, Team
+
+    # @!attribute [rw] season
+    #   Returns the season
+    #   @api public
+    #   @example
+    #     leader.season #=> "2024"
+    #   @return [String] the season
+    attribute :season, Shale::Type::String
+
+    json do
+      map "rank", to: :rank
+      map "value", to: :value
+      map "person", to: :person
+      map "team", to: :team
+      map "season", to: :season
+    end
+  end
+end

data/lib/mlb/team_leaders.rb

@@ -0,0 +1,45 @@
+require "shale"
+require_relative "team_leader"
+
+module MLB
+  # Represents a team leader category
+  class TeamLeaderCategory < Shale::Mapper
+    attribute :leader_category, Shale::Type::String
+    attribute :season, Shale::Type::String
+    attribute :leaders, TeamLeader, collection: true
+
+    json do
+      map "leaderCategory", to: :leader_category
+      map "season", to: :season
+      map "leaders", to: :leaders
+    end
+  end
+
+  # Provides methods for fetching team leaders from the API
+  class TeamLeaders < Shale::Mapper
+    attribute :team_leaders, TeamLeaderCategory, collection: true
+
+    json do
+      map "teamLeaders", to: :team_leaders
+    end
+
+    # Retrieves team leaders for a category
+    #
+    # @api public
+    # @example Get team leaders for home runs
+    #   MLB::TeamLeaders.find(team: 147, category: "homeRuns", season: 2024)
+    # @example Get team leaders with a team object
+    #   MLB::TeamLeaders.find(team: Team.new(id: 147), category: "homeRuns")
+    # @param team [Integer, Team] the team ID or Team object
+    # @param category [String] the leader category
+    # @param season [Integer, nil] the season year (defaults to current year)
+    # @return [Array<TeamLeader>] the team leaders
+    def self.find(team:, category:, season: nil)
+      season ||= Utils.current_season
+      team_id = Utils.extract_id(team)
+      params = {leaderCategories: category, season:}
+      response = CLIENT.get("teams/#{team_id}/leaders?#{Utils.build_query(params)}")
+      from_json(response).team_leaders.first&.leaders || []
+    end
+  end
+end

data/lib/mlb/team_record.rb

@@ -0,0 +1,285 @@
+require "equalizer"
+require "shale"
+require_relative "team"
+
+module MLB
+  # Represents a team's league record (wins/losses)
+  class LeagueRecord < Shale::Mapper
+    # @!attribute [rw] wins
+    #   Returns the number of wins
+    #   @api public
+    #   @example
+    #     league_record.wins #=> 94
+    #   @return [Integer] the number of wins
+    attribute :wins, Shale::Type::Integer
+
+    # @!attribute [rw] losses
+    #   Returns the number of losses
+    #   @api public
+    #   @example
+    #     league_record.losses #=> 68
+    #   @return [Integer] the number of losses
+    attribute :losses, Shale::Type::Integer
+
+    # @!attribute [rw] ties
+    #   Returns the number of ties
+    #   @api public
+    #   @example
+    #     league_record.ties #=> 0
+    #   @return [Integer] the number of ties
+    attribute :ties, Shale::Type::Integer
+
+    # @!attribute [rw] pct
+    #   Returns the winning percentage
+    #   @api public
+    #   @example
+    #     league_record.pct #=> ".580"
+    #   @return [String] the winning percentage
+    attribute :pct, Shale::Type::String
+  end
+
+  # Represents a team's streak information
+  class Streak < Shale::Mapper
+    # @!attribute [rw] streak_code
+    #   Returns the streak code
+    #   @api public
+    #   @example
+    #     streak.streak_code #=> "W3"
+    #   @return [String] the streak code
+    attribute :streak_code, Shale::Type::String
+
+    # @!attribute [rw] streak_type
+    #   Returns the streak type
+    #   @api public
+    #   @example
+    #     streak.streak_type #=> "wins"
+    #   @return [String] the streak type
+    attribute :streak_type, Shale::Type::String
+
+    # @!attribute [rw] streak_number
+    #   Returns the streak length
+    #   @api public
+    #   @example
+    #     streak.streak_number #=> 3
+    #   @return [Integer] the streak length
+    attribute :streak_number, Shale::Type::Integer
+
+    # Winning streak type value
+    WINS = "wins".freeze
+    # Losing streak type value
+    LOSSES = "losses".freeze
+
+    # Returns whether this is a winning streak
+    #
+    # @api public
+    # @example
+    #   streak.winning? #=> true
+    # @return [Boolean] true if this is a winning streak
+    def winning? = streak_type.eql?(WINS)
+
+    # Returns whether this is a losing streak
+    #
+    # @api public
+    # @example
+    #   streak.losing? #=> false
+    # @return [Boolean] true if this is a losing streak
+    def losing? = streak_type.eql?(LOSSES)
+
+    json do
+      map "streakCode", to: :streak_code
+      map "streakType", to: :streak_type
+      map "streakNumber", to: :streak_number
+    end
+  end
+
+  # Represents a team's record in the standings
+  class TeamRecord < Shale::Mapper
+    include Equalizer.new(:team)
+
+    # @!attribute [rw] team
+    #   Returns the team
+    #   @api public
+    #   @example
+    #     team_record.team #=> #<MLB::Team>
+    #   @return [Team] the team
+    attribute :team, Team
+
+    # @!attribute [rw] season
+    #   Returns the season year
+    #   @api public
+    #   @example
+    #     team_record.season #=> "2024"
+    #   @return [String] the season year
+    attribute :season, Shale::Type::String
+
+    # @!attribute [rw] streak
+    #   Returns the current streak
+    #   @api public
+    #   @example
+    #     team_record.streak #=> #<MLB::Streak>
+    #   @return [Streak] the current streak
+    attribute :streak, Streak
+
+    # @!attribute [rw] division_rank
+    #   Returns the division rank
+    #   @api public
+    #   @example
+    #     team_record.division_rank #=> "1"
+    #   @return [String] the division rank
+    attribute :division_rank, Shale::Type::String
+
+    # @!attribute [rw] league_rank
+    #   Returns the league rank
+    #   @api public
+    #   @example
+    #     team_record.league_rank #=> "1"
+    #   @return [String] the league rank
+    attribute :league_rank, Shale::Type::String
+
+    attribute :wildcard_rank, Shale::Type::String
+
+    # @!attribute [rw] games_played
+    #   Returns the number of games played
+    #   @api public
+    #   @example
+    #     team_record.games_played #=> 162
+    #   @return [Integer] the number of games played
+    attribute :games_played, Shale::Type::Integer
+
+    # @!attribute [rw] games_back
+    #   Returns games behind the division leader
+    #   @api public
+    #   @example
+    #     team_record.games_back #=> "3.0"
+    #   @return [String] games behind the division leader
+    attribute :games_back, Shale::Type::String
+
+    attribute :wildcard_games_back, Shale::Type::String
+
+    # @!attribute [rw] league_record
+    #   Returns the league record
+    #   @api public
+    #   @example
+    #     team_record.league_record #=> #<MLB::LeagueRecord>
+    #   @return [LeagueRecord] the league record
+    attribute :league_record, LeagueRecord
+
+    # @!attribute [rw] wins
+    #   Returns the number of wins
+    #   @api public
+    #   @example
+    #     team_record.wins #=> 94
+    #   @return [Integer] the number of wins
+    attribute :wins, Shale::Type::Integer
+
+    # @!attribute [rw] losses
+    #   Returns the number of losses
+    #   @api public
+    #   @example
+    #     team_record.losses #=> 68
+    #   @return [Integer] the number of losses
+    attribute :losses, Shale::Type::Integer
+
+    # @!attribute [rw] runs_scored
+    #   Returns the runs scored
+    #   @api public
+    #   @example
+    #     team_record.runs_scored #=> 815
+    #   @return [Integer] the runs scored
+    attribute :runs_scored, Shale::Type::Integer
+
+    # @!attribute [rw] runs_allowed
+    #   Returns the runs allowed
+    #   @api public
+    #   @example
+    #     team_record.runs_allowed #=> 668
+    #   @return [Integer] the runs allowed
+    attribute :runs_allowed, Shale::Type::Integer
+
+    # @!attribute [rw] run_differential
+    #   Returns the run differential
+    #   @api public
+    #   @example
+    #     team_record.run_differential #=> 147
+    #   @return [Integer] the run differential
+    attribute :run_differential, Shale::Type::Integer
+
+    # @!attribute [rw] winning_percentage
+    #   Returns the winning percentage
+    #   @api public
+    #   @example
+    #     team_record.winning_percentage #=> ".580"
+    #   @return [String] the winning percentage
+    attribute :winning_percentage, Shale::Type::String
+
+    # @!attribute [rw] division_champ
+    #   Returns whether the team is a division champion
+    #   @api public
+    #   @example
+    #     team_record.division_champ #=> true
+    #   @return [Boolean] whether the team is a division champion
+    attribute :division_champ, Shale::Type::Boolean
+
+    # @!attribute [rw] division_leader
+    #   Returns whether the team leads the division
+    #   @api public
+    #   @example
+    #     team_record.division_leader #=> true
+    #   @return [Boolean] whether the team leads the division
+    attribute :division_leader, Shale::Type::Boolean
+
+    # @!attribute [rw] clinched
+    #   Returns whether the team has clinched a playoff spot
+    #   @api public
+    #   @example
+    #     team_record.clinched #=> true
+    #   @return [Boolean] whether the team has clinched
+    attribute :clinched, Shale::Type::Boolean
+
+    # @!method division_champ?
+    #   Returns whether the team is a division champion
+    #   @api public
+    #   @example
+    #     team_record.division_champ? #=> true
+    #   @return [Boolean, nil] whether the team is a division champion
+    alias_method :division_champ?, :division_champ
+
+    # @!method division_leader?
+    #   Returns whether the team leads the division
+    #   @api public
+    #   @example
+    #     team_record.division_leader? #=> true
+    #   @return [Boolean, nil] whether the team leads the division
+    alias_method :division_leader?, :division_leader
+
+    # @!method clinched?
+    #   Returns whether the team has clinched a playoff spot
+    #   @api public
+    #   @example
+    #     team_record.clinched? #=> true
+    #   @return [Boolean, nil] whether the team has clinched
+    alias_method :clinched?, :clinched
+
+    json do
+      map "team", to: :team
+      map "season", to: :season
+      map "streak", to: :streak
+      map "divisionRank", to: :division_rank
+      map "leagueRank", to: :league_rank
+      map "wildCardRank", to: :wildcard_rank
+      map "gamesPlayed", to: :games_played
+      map "gamesBack", to: :games_back
+      map "wildCardGamesBack", to: :wildcard_games_back
+      map "leagueRecord", to: :league_record
+      map "wins", to: :wins
+      map "losses", to: :losses
+      map "runsScored", to: :runs_scored
+      map "runsAllowed", to: :runs_allowed
+      map "runDifferential", to: :run_differential
+      map "winningPercentage", to: :winning_percentage
+      map "divisionChamp", to: :division_champ
+      map "divisionLeader", to: :division_leader
+      map "clinched", to: :clinched
+    end
+  end
+end