mlb 0.9.0 → 0.11.0

data/lib/mlb/team_stat.rb

@@ -0,0 +1,50 @@
+require "equalizer"
+require "shale"
+require_relative "stat_values"
+require_relative "team"
+
+module MLB
+  # Represents a team stat split
+  class TeamStat < Shale::Mapper
+    include Equalizer.new(:team, :rank)
+
+    # @!attribute [rw] season
+    #   Returns the season for this stat split
+    #   @api public
+    #   @example
+    #     team_stat.season #=> "2024"
+    #   @return [String] the season
+    attribute :season, Shale::Type::String
+
+    # @!attribute [rw] stat
+    #   Returns the stat values
+    #   @api public
+    #   @example
+    #     team_stat.stat.runs #=> 829
+    #   @return [StatValues] the stat values
+    attribute :stat, StatValues
+
+    # @!attribute [rw] team
+    #   Returns the team
+    #   @api public
+    #   @example
+    #     team_stat.team.name #=> "New York Yankees"
+    #   @return [Team] the team
+    attribute :team, Team
+
+    # @!attribute [rw] rank
+    #   Returns the rank in the stat leaderboard
+    #   @api public
+    #   @example
+    #     team_stat.rank #=> 1
+    #   @return [Integer] the rank
+    attribute :rank, Shale::Type::Integer
+
+    json do
+      map "season", to: :season
+      map "stat", to: :stat
+      map "team", to: :team
+      map "rank", to: :rank
+    end
+  end
+end

data/lib/mlb/team_stats.rb

@@ -0,0 +1,52 @@
+require "shale"
+require_relative "team_stat"
+
+module MLB
+  # Represents a stat type group
+  class TeamStatGroup < Shale::Mapper
+    # @!attribute [rw] splits
+    #   Returns the stat splits
+    #   @api public
+    #   @example
+    #     group.splits #=> [#<MLB::TeamStat>, ...]
+    #   @return [Array<TeamStat>] the stat splits
+    attribute :splits, TeamStat, collection: true
+
+    json do
+      map "splits", to: :splits
+    end
+  end
+
+  # Provides methods for fetching team stats from the API
+  class TeamStats < Shale::Mapper
+    # @!attribute [rw] stats
+    #   Returns the stat groups
+    #   @api public
+    #   @example
+    #     team_stats.stats #=> [#<MLB::TeamStatGroup>, ...]
+    #   @return [Array<TeamStatGroup>] the stat groups
+    attribute :stats, TeamStatGroup, collection: true
+
+    json do
+      map "stats", to: :stats
+    end
+
+    # Retrieves team stats
+    #
+    # @api public
+    # @example Get team hitting stats
+    #   MLB::TeamStats.find(season: 2024, group: "hitting")
+    # @example Get team pitching stats
+    #   MLB::TeamStats.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)
+    # @return [Array<TeamStat>] the team stats
+    def self.find(season: nil, group: "hitting", stats: "season")
+      season ||= Utils.current_season
+      params = {season:, group:, stats:}
+      response = CLIENT.get("teams/stats?#{Utils.build_query(params)}")
+      from_json(response).stats.first&.splits || []
+    end
+  end
+end

data/lib/mlb/teams.rb

@@ -1,30 +1,40 @@
 require "shale"
-require "uri"
-require_relative "sport"
 require_relative "team"
 
 module MLB
+  # Collection of teams from the MLB Stats API
   class Teams < Shale::Mapper
-    attribute :copyright, Shale::Type::String
     attribute :teams, Team, collection: true
 
-    def self.all(season: Time.now.year, sport: Sport.new(id: 1))
-      sport_id = sport.respond_to?(:id) ? sport.id : sport
-      params = {sportId: sport_id, season:}
-      query_string = URI.encode_www_form(params)
-      response = CLIENT.get("teams?#{query_string}")
-      teams = from_json(response)
-      teams.teams
+    # Retrieves all teams
+    #
+    # @api public
+    # @example
+    #   MLB::Teams.all
+    # @param season [Integer, nil] the season year (defaults to current year)
+    # @param sport [Integer, Sport] the sport ID or Sport object
+    # @return [Array<Team>] list of all teams
+    def self.all(season: nil, sport: Utils::DEFAULT_SPORT_ID)
+      season ||= Utils.current_season
+      params = {sportId: Utils.extract_id(sport), season:}
+      response = CLIENT.get("teams?#{Utils.build_query(params)}")
+      from_json(response).teams
     end
 
-    def self.find(team, season: Time.now.year, sport: Sport.new(id: 1))
-      id = team.respond_to?(:id) ? team.id : team
-      sport_id = sport.respond_to?(:id) ? sport.id : sport
-      params = {sportId: sport_id, season:}
-      query_string = URI.encode_www_form(params)
-      response = CLIENT.get("teams/#{id}?#{query_string}")
-      teams = from_json(response)
-      teams.teams.first
+    # Finds a team by ID
+    #
+    # @api public
+    # @example
+    #   MLB::Teams.find(147)
+    # @param team [Integer, Team] the team ID or Team object
+    # @param season [Integer, nil] the season year (defaults to current year)
+    # @param sport [Integer, Sport] the sport ID or Sport object
+    # @return [Team, nil] the team if found
+    def self.find(team, season: nil, sport: Utils::DEFAULT_SPORT_ID)
+      season ||= Utils.current_season
+      params = {sportId: Utils.extract_id(sport), season:}
+      response = CLIENT.get("teams/#{Utils.extract_id(team)}?#{Utils.build_query(params)}")
+      from_json(response).teams.first
     end
   end
 end

data/lib/mlb/tied_games.rb

@@ -0,0 +1,32 @@
+require "shale"
+require_relative "schedule_date"
+
+module MLB
+  # Provides methods for fetching tied games from the API
+  class TiedGames < Shale::Mapper
+    # @!attribute [rw] dates
+    #   Returns the schedule dates with tied games
+    #   @api public
+    #   @example
+    #     tied_games.dates #=> [#<MLB::ScheduleDate>, ...]
+    #   @return [Array<ScheduleDate>] the schedule dates with games
+    attribute :dates, ScheduleDate, collection: true
+
+    json do
+      map "dates", to: :dates
+    end
+
+    # Retrieves tied games for a given season
+    #
+    # @api public
+    # @example Get tied games for a season
+    #   MLB::TiedGames.all(season: 2024)
+    # @param season [Integer, nil] the season year (defaults to current year)
+    # @return [Array<ScheduledGame>] the list of tied games
+    def self.all(season: nil)
+      season ||= Utils.current_season
+      response = CLIENT.get("schedule/games/tied?#{Utils.build_query(season:)}")
+      from_json(response).dates.flat_map(&:games)
+    end
+  end
+end

data/lib/mlb/transaction.rb

@@ -1,20 +1,148 @@
+require "equalizer"
 require "shale"
 require_relative "player"
 require_relative "team"
 
 module MLB
+  # Represents a player transaction (trade, signing, etc.)
   class Transaction < Shale::Mapper
+    include Equalizer.new(:id)
+
+    TYPE_TRADE = "TR".freeze
+    TYPE_FREE_AGENT = "FA".freeze
+    TYPE_ASSIGNMENT = "ASG".freeze
+    TYPE_SIGNING = "SGN".freeze
+    TYPE_RELEASE = "REL".freeze
+    TYPE_WAIVER = "WV".freeze
+
+    # @!attribute [rw] id
+    #   Returns the unique identifier for the transaction
+    #   @api public
+    #   @example
+    #     transaction.id #=> 12345
+    #   @return [Integer] the unique identifier for the transaction
     attribute :id, Shale::Type::Integer
+
+    # @!attribute [rw] player
+    #   Returns the player involved in the transaction
+    #   @api public
+    #   @example
+    #     transaction.player #=> #<MLB::Player>
+    #   @return [Player] the player involved in the transaction
     attribute :player, Player
+
+    # @!attribute [rw] from_team
+    #   Returns the team the player is leaving
+    #   @api public
+    #   @example
+    #     transaction.from_team #=> #<MLB::Team>
+    #   @return [Team, nil] the team the player is leaving
     attribute :from_team, Team, default: nil
+
+    # @!attribute [rw] to_team
+    #   Returns the team the player is joining
+    #   @api public
+    #   @example
+    #     transaction.to_team #=> #<MLB::Team>
+    #   @return [Team] the team the player is joining
     attribute :to_team, Team
+
+    # @!attribute [rw] date
+    #   Returns the date of the transaction
+    #   @api public
+    #   @example
+    #     transaction.date #=> #<Date: 2024-01-15>
+    #   @return [Date] the date of the transaction
     attribute :date, Shale::Type::Date
+
+    # @!attribute [rw] effective_date
+    #   Returns the effective date of the transaction
+    #   @api public
+    #   @example
+    #     transaction.effective_date #=> #<Date: 2024-01-16>
+    #   @return [Date] the effective date of the transaction
     attribute :effective_date, Shale::Type::Date
+
+    # @!attribute [rw] resolution_date
+    #   Returns the resolution date of the transaction
+    #   @api public
+    #   @example
+    #     transaction.resolution_date #=> #<Date: 2024-01-20>
+    #   @return [Date] the resolution date of the transaction
     attribute :resolution_date, Shale::Type::Date
+
+    # @!attribute [rw] type_code
+    #   Returns the transaction type code
+    #   @api public
+    #   @example
+    #     transaction.type_code #=> "TR"
+    #   @return [String] the transaction type code
     attribute :type_code, Shale::Type::String
+
+    # @!attribute [rw] type_desc
+    #   Returns the transaction type description
+    #   @api public
+    #   @example
+    #     transaction.type_desc #=> "Trade"
+    #   @return [String] the transaction type description
     attribute :type_desc, Shale::Type::String
+
+    # @!attribute [rw] description
+    #   Returns the full transaction description
+    #   @api public
+    #   @example
+    #     transaction.description #=> "Player X traded to Team Y for Player Z"
+    #   @return [String] the full transaction description
     attribute :description, Shale::Type::String
 
+    # Returns whether this is a trade transaction
+    #
+    # @api public
+    # @example
+    #   transaction.trade? #=> true
+    # @return [Boolean] whether this is a trade
+    def trade? = type_code.eql?(TYPE_TRADE)
+
+    # Returns whether this is a free agent transaction
+    #
+    # @api public
+    # @example
+    #   transaction.free_agent? #=> false
+    # @return [Boolean] whether this is a free agent signing
+    def free_agent? = type_code.eql?(TYPE_FREE_AGENT)
+
+    # Returns whether this is an assignment transaction
+    #
+    # @api public
+    # @example
+    #   transaction.assignment? #=> false
+    # @return [Boolean] whether this is an assignment
+    def assignment? = type_code.eql?(TYPE_ASSIGNMENT)
+
+    # Returns whether this is a signing transaction
+    #
+    # @api public
+    # @example
+    #   transaction.signing? #=> false
+    # @return [Boolean] whether this is a signing
+    def signing? = type_code.eql?(TYPE_SIGNING)
+
+    # Returns whether this is a release transaction
+    #
+    # @api public
+    # @example
+    #   transaction.release? #=> false
+    # @return [Boolean] whether this is a release
+    def release? = type_code.eql?(TYPE_RELEASE)
+
+    # Returns whether this is a waiver transaction
+    #
+    # @api public
+    # @example
+    #   transaction.waiver? #=> false
+    # @return [Boolean] whether this is a waiver
+    def waiver? = type_code.eql?(TYPE_WAIVER)
+
     json do
       map "id", to: :id
       map "person", to: :player

data/lib/mlb/transactions.rb

@@ -1,18 +1,23 @@
 require "shale"
-require "uri"
 require_relative "transaction"
 
 module MLB
+  # Provides methods for fetching MLB transactions from the API
   class Transactions < Shale::Mapper
-    attribute :copyright, Shale::Type::String
     attribute :transactions, Transaction, collection: true
 
+    # Retrieves transactions between two dates
+    #
+    # @api public
+    # @example
+    #   MLB::Transactions.between(start_date: Date.new(2024, 1, 1), end_date: Date.new(2024, 1, 31))
+    # @param start_date [Date] the start date
+    # @param end_date [Date] the end date
+    # @return [Array<Transaction>] the list of transactions
     def self.between(start_date: Date.today, end_date: start_date)
       params = {startDate: start_date, endDate: end_date}
-      query_string = URI.encode_www_form(params)
-      response = CLIENT.get("transactions?#{query_string}")
-      transactions = from_json(response)
-      transactions.transactions
+      response = CLIENT.get("transactions?#{Utils.build_query(params)}")
+      from_json(response).transactions
     end
   end
 end

data/lib/mlb/uniforms.rb

@@ -0,0 +1,97 @@
+require "shale"
+require "equalizer"
+
+module MLB
+  # Represents uniform color information
+  class UniformColor < Shale::Mapper
+    attribute :name, Shale::Type::String
+    attribute :hex, Shale::Type::String
+
+    json do
+      map "name", to: :name
+      map "hex", to: :hex
+    end
+  end
+
+  # Represents uniform asset information
+  class UniformAsset < Shale::Mapper
+    attribute :cap, Shale::Type::String
+    attribute :jersey, Shale::Type::String
+
+    json do
+      map "cap", to: :cap
+      map "jersey", to: :jersey
+    end
+  end
+
+  # Represents a team's uniform information
+  class UniformInfo < Shale::Mapper
+    include Equalizer.new(:team_id, :uniform_type)
+
+    attribute :team_id, Shale::Type::Integer
+    attribute :uniform_type, Shale::Type::String
+    attribute :jersey_color, UniformColor
+    attribute :cap_color, UniformColor
+    attribute :assets, UniformAsset
+
+    json do
+      map "teamId", to: :team_id
+      map "uniformType", to: :uniform_type
+      map "jerseyColor", to: :jersey_color
+      map "capColor", to: :cap_color
+      map "assets", to: :assets
+    end
+  end
+
+  # Represents game uniform information for both teams
+  class GameUniforms < Shale::Mapper
+    attribute :away, UniformInfo
+    attribute :home, UniformInfo
+
+    json do
+      map "away", to: :away
+      map "home", to: :home
+    end
+
+    # Retrieves uniform information for a game
+    #
+    # @api public
+    # @example Get uniforms for a game
+    #   MLB::GameUniforms.find(game: 745571)
+    # @example Get uniforms using a ScheduledGame object
+    #   MLB::GameUniforms.find(game: scheduled_game)
+    # @param game [Integer, ScheduledGame] the game ID or game object
+    # @return [GameUniforms] the game uniforms
+    def self.find(game:)
+      game_pk = game.respond_to?(:game_pk) ? game.game_pk : game
+      response = CLIENT.get("uniforms/game?#{Utils.build_query(gamePk: game_pk)}")
+      from_json(response)
+    end
+  end
+
+  # Represents team uniform collection
+  class TeamUniforms < Shale::Mapper
+    attribute :uniforms, UniformInfo, collection: true
+
+    json do
+      map "uniforms", to: :uniforms
+    end
+
+    # Retrieves uniform information for a team
+    #
+    # @api public
+    # @example Get uniforms for a team
+    #   MLB::TeamUniforms.find(team: 147)
+    # @example Get uniforms using a Team object
+    #   MLB::TeamUniforms.find(team: team)
+    # @param team [Integer, Team] the team ID or team object
+    # @param season [Integer, nil] the season year (defaults to current year)
+    # @return [Array<UniformInfo>] the team uniforms
+    def self.find(team:, season: nil)
+      season ||= Utils.current_season
+      params = {teamId: Utils.extract_id(team), season:}
+      response = CLIENT.get("uniforms/team?#{Utils.build_query(params)}")
+      from_json(response).uniforms
+    end
+  end
+end

data/lib/mlb/utils.rb

@@ -0,0 +1,45 @@
+require "uri"
+
+module MLB
+  # Utility methods and constants shared across the MLB gem
+  module Utils
+    # Default sport ID for MLB (Major League Baseball)
+    DEFAULT_SPORT_ID = 1
+
+    class << self
+      # Returns the current MLB season year
+      #
+      # @api public
+      # @example
+      #   Utils.current_season #=> 2024
+      # @return [Integer] the current year
+      def current_season
+        Time.now.year
+      end
+
+      # Extracts the ID from an object or returns the value as-is
+      #
+      # @api private
+      # @example With a model object
+      #   Utils.extract_id(team) #=> 147
+      # @example With a raw ID
+      #   Utils.extract_id(147) #=> 147
+      # @param object [#id, Integer, String] an object with an id method or an ID value
+      # @return [Integer, String] the extracted ID
+      def extract_id(object)
+        object.respond_to?(:id) ? object.id : object
+      end
+
+      # Builds a URL-encoded query string from parameters
+      #
+      # @api private
+      # @example
+      #   Utils.build_query(season: 2024, sportId: 1) #=> "season=2024&sportId=1"
+      # @param params [Hash] the parameters to encode
+      # @return [String] the URL-encoded query string
+      def build_query(params)
+        URI.encode_www_form(params)
+      end
+    end
+  end
+end

data/lib/mlb/venue.rb

@@ -1,13 +1,23 @@
+require "equalizer"
 require "shale"
 
 module MLB
+  # Represents a venue (stadium/ballpark)
   class Venue < Shale::Mapper
+    include Equalizer.new(:id)
+
     attribute :id, Shale::Type::Integer
     attribute :name, Shale::Type::String
     attribute :link, Shale::Type::String
     attribute :active, Shale::Type::Boolean
     attribute :season, Shale::Type::Integer
 
+    # Returns whether the venue is active
+    #
+    # @api public
+    # @example
+    #   venue.active?
+    # @return [Boolean, nil] true if the venue is active
     alias_method :active?, :active
   end
 end

data/lib/mlb/venues.rb

@@ -1,30 +1,40 @@
 require "shale"
-require "uri"
-require_relative "sport"
 require_relative "venue"
 
 module MLB
+  # Collection of venues from the MLB Stats API
   class Venues < Shale::Mapper
-    attribute :copyright, Shale::Type::String
     attribute :venues, Venue, collection: true
 
-    def self.all(season: Time.now.year, sport: Sport.new(id: 1))
-      sport_id = sport.respond_to?(:id) ? sport.id : sport
-      params = {sportId: sport_id, season:}
-      query_string = URI.encode_www_form(params)
-      response = CLIENT.get("venues?#{query_string}")
-      venues = from_json(response)
-      venues.venues
+    # Retrieves all venues
+    #
+    # @api public
+    # @example
+    #   MLB::Venues.all
+    # @param season [Integer, nil] the season year (defaults to current year)
+    # @param sport [Integer, Sport] the sport ID or Sport object
+    # @return [Array<Venue>] list of all venues
+    def self.all(season: nil, sport: Utils::DEFAULT_SPORT_ID)
+      season ||= Utils.current_season
+      params = {sportId: Utils.extract_id(sport), season:}
+      response = CLIENT.get("venues?#{Utils.build_query(params)}")
+      from_json(response).venues
     end
 
-    def self.find(venue, season: Time.now.year, sport: Sport.new(id: 1))
-      id = venue.respond_to?(:id) ? venue.id : venue
-      sport_id = sport.respond_to?(:id) ? sport.id : sport
-      params = {sportId: sport_id, season:}
-      query_string = URI.encode_www_form(params)
-      response = CLIENT.get("venues/#{id}?#{query_string}")
-      venues = from_json(response)
-      venues.venues.first
+    # Finds a venue by ID
+    #
+    # @api public
+    # @example
+    #   MLB::Venues.find(15)
+    # @param venue [Integer, Venue] the venue ID or Venue object
+    # @param season [Integer, nil] the season year (defaults to current year)
+    # @param sport [Integer, Sport] the sport ID or Sport object
+    # @return [Venue, nil] the venue if found
+    def self.find(venue, season: nil, sport: Utils::DEFAULT_SPORT_ID)
+      season ||= Utils.current_season
+      params = {sportId: Utils.extract_id(sport), season:}
+      response = CLIENT.get("venues/#{Utils.extract_id(venue)}?#{Utils.build_query(params)}")
+      from_json(response).venues.first
     end
   end
 end

data/lib/mlb/version.rb

@@ -1,5 +1,6 @@
 require "rubygems/version"
 
 module MLB
-  VERSION = Gem::Version.create("0.9.0")
+  # Current version of the MLB gem
+  VERSION = Gem::Version.create("0.11.0")
 end

data/lib/mlb/win_probability.rb

@@ -0,0 +1,64 @@
+require "shale"
+
+module MLB
+  # Represents a win probability data point for a play
+  class WinProbabilityEntry < Shale::Mapper
+    include Equalizer.new(:at_bat_index, :home_team_win_probability)
+
+    # @!attribute [rw] at_bat_index
+    #   Returns the at bat index
+    #   @api public
+    #   @example
+    #     entry.at_bat_index #=> 0
+    #   @return [Integer] the at bat index
+    attribute :at_bat_index, Shale::Type::Integer
+
+    # @!attribute [rw] home_team_win_probability
+    #   Returns the home team win probability
+    #   @api public
+    #   @example
+    #     entry.home_team_win_probability #=> 0.52
+    #   @return [Float] the home team win probability
+    attribute :home_team_win_probability, Shale::Type::Float
+
+    # @!attribute [rw] away_team_win_probability
+    #   Returns the away team win probability
+    #   @api public
+    #   @example
+    #     entry.away_team_win_probability #=> 0.48
+    #   @return [Float] the away team win probability
+    attribute :away_team_win_probability, Shale::Type::Float
+
+    json do
+      map "atBatIndex", to: :at_bat_index
+      map "homeTeamWinProbability", to: :home_team_win_probability
+      map "awayTeamWinProbability", to: :away_team_win_probability
+    end
+  end
+
+  # Provides methods for fetching win probability data for a game
+  class WinProbability < Shale::Mapper
+    # @!attribute [rw] entries
+    #   Returns the win probability entries
+    #   @api public
+    #   @example
+    #     wp.entries #=> [#<MLB::WinProbabilityEntry>, ...]
+    #   @return [Array<WinProbabilityEntry>] the win probability data points
+    attribute :entries, WinProbabilityEntry, collection: true
+
+    # Retrieves win probability data for a game
+    #
+    # @api public
+    # @example Get win probability for a game
+    #   MLB::WinProbability.find(game: 745571)
+    # @example Get win probability using a ScheduledGame object
+    #   MLB::WinProbability.find(game: scheduled_game)
+    # @param game [Integer, ScheduledGame] the game ID or game object
+    # @return [Array<WinProbabilityEntry>] the win probability data points
+    def self.find(game:)
+      game_pk = game.respond_to?(:game_pk) ? game.game_pk : game
+      response = CLIENT.get("game/#{game_pk}/winProbability") || "[]"
+      JSON.parse(response).map { |entry| WinProbabilityEntry.from_json(entry.to_json) }
+    end
+  end
+end

data/lib/mlb/wind_direction.rb

@@ -0,0 +1,6 @@
+require_relative "code_description_type"
+
+module MLB
+  # Represents a wind direction
+  class WindDirection < CodeDescriptionType; end
+end