mlb 0.9.0 → 0.11.0

data/lib/mlb/free_agents.rb

@@ -0,0 +1,34 @@
+require "shale"
+require_relative "free_agent"
+
+module MLB
+  # Provides methods for fetching free agent data from the API
+  class FreeAgents < Shale::Mapper
+    # @!attribute [rw] free_agents
+    #   Returns the free agents
+    #   @api public
+    #   @example
+    #     free_agents.free_agents #=> [#<MLB::FreeAgent>, ...]
+    #   @return [Array<FreeAgent>] the free agents
+    attribute :free_agents, FreeAgent, collection: true
+
+    json do
+      map "freeAgents", to: :free_agents
+    end
+
+    # Retrieves all free agents for a season
+    #
+    # @api public
+    # @example Get free agents for the current season
+    #   MLB::FreeAgents.all
+    # @example Get free agents for a specific season
+    #   MLB::FreeAgents.all(season: 2024)
+    # @param season [Integer, nil] the season year (defaults to current year)
+    # @return [Array<FreeAgent>] the free agents
+    def self.all(season: nil)
+      season ||= Utils.current_season
+      response = CLIENT.get("people/freeAgents?#{Utils.build_query(season:)}")
+      from_json(response).free_agents
+    end
+  end
+end

data/lib/mlb/game_changes.rb

@@ -0,0 +1,87 @@
+require "shale"
+
+module MLB
+  # Represents a game that has been modified since a given timestamp
+  class ChangedGame < Shale::Mapper
+    include Equalizer.new(:game_pk)
+
+    # @!attribute [rw] game_pk
+    #   Returns the unique game identifier
+    #   @api public
+    #   @example
+    #     game.game_pk #=> 745571
+    #   @return [Integer] the game primary key
+    attribute :game_pk, Shale::Type::Integer
+
+    json do
+      map "gamePk", to: :game_pk
+    end
+  end
+
+  # Groups changed games by date
+  class ChangedGameDate < Shale::Mapper
+    # @!attribute [rw] date
+    #   Returns the date string
+    #   @api public
+    #   @example
+    #     date_entry.date #=> "2024-06-15"
+    #   @return [String] the date in YYYY-MM-DD format
+    attribute :date, Shale::Type::String
+
+    # @!attribute [rw] games
+    #   Returns the games that changed on this date
+    #   @api public
+    #   @example
+    #     date_entry.games #=> [#<MLB::ChangedGame>, ...]
+    #   @return [Array<ChangedGame>] the changed games
+    attribute :games, ChangedGame, collection: true
+
+    json do
+      map "date", to: :date
+      map "games", to: :games
+    end
+  end
+
+  # Fetches games that have been modified since a given timestamp
+  #
+  # This endpoint is useful for efficiently polling for game updates
+  # rather than fetching all game data repeatedly.
+  class GameChanges < Shale::Mapper
+    # @!attribute [rw] dates
+    #   Returns dates containing changed games
+    #   @api public
+    #   @example
+    #     response.dates #=> [#<MLB::ChangedGameDate>, ...]
+    #   @return [Array<ChangedGameDate>] the dates with changes
+    attribute :dates, ChangedGameDate, collection: true
+
+    json do
+      map "dates", to: :dates
+    end
+
+    # Retrieves games modified since the given timestamp
+    #
+    # @api public
+    # @example Basic usage with ISO 8601 timestamp
+    #   MLB::GameChanges.since(updated_since: "2024-06-15T12:00:00Z")
+    # @example Filter by sport (1 = MLB)
+    #   MLB::GameChanges.since(updated_since: "2024-06-15T12:00:00Z", sport_id: 1)
+    # @example Filter by season and game type
+    #   MLB::GameChanges.since(updated_since: timestamp, season: 2024, game_type: "R")
+    # @param updated_since [#to_s] timestamp to check changes from (ISO 8601 format)
+    # @param sport_id [Integer, nil] filter by sport ID
+    # @param season [Integer, nil] filter by season year
+    # @param game_type [String, nil] filter by game type (R=Regular, P=Postseason, etc.)
+    # @return [Array<ChangedGame>] games modified since the timestamp
+    def self.since(updated_since:, sport_id: nil, season: nil, game_type: nil)
+      params = {
+        updatedSince: updated_since.to_s,
+        sportId: sport_id,
+        season: season,
+        gameType: game_type
+      }.compact
+      response = CLIENT.get("game/changes?#{URI.encode_www_form(params)}")
+      from_json(response).dates.flat_map(&:games)
+    end
+  end
+end

data/lib/mlb/game_content.rb

@@ -0,0 +1,251 @@
+require "shale"
+
+module MLB
+  # Represents a media playback option
+  class MediaPlayback < Shale::Mapper
+    # @!attribute [rw] name
+    #   Returns the playback name
+    #   @api public
+    #   @example
+    #     playback.name #=> "mp4Avc"
+    #   @return [String] the name
+    attribute :name, Shale::Type::String
+
+    # @!attribute [rw] url
+    #   Returns the playback URL
+    #   @api public
+    #   @example
+    #     playback.url #=> "https://..."
+    #   @return [String] the URL
+    attribute :url, Shale::Type::String
+
+    json do
+      map "name", to: :name
+      map "url", to: :url
+    end
+  end
+
+  # Represents a media image cut
+  class MediaCut < Shale::Mapper
+    # @!attribute [rw] aspect_ratio
+    #   Returns the aspect ratio
+    #   @api public
+    #   @example
+    #     cut.aspect_ratio #=> "16:9"
+    #   @return [String] the aspect ratio
+    attribute :aspect_ratio, Shale::Type::String
+
+    # @!attribute [rw] width
+    #   Returns the width
+    #   @api public
+    #   @example
+    #     cut.width #=> 1920
+    #   @return [Integer] the width
+    attribute :width, Shale::Type::Integer
+
+    # @!attribute [rw] height
+    #   Returns the height
+    #   @api public
+    #   @example
+    #     cut.height #=> 1080
+    #   @return [Integer] the height
+    attribute :height, Shale::Type::Integer
+
+    # @!attribute [rw] src
+    #   Returns the image source URL
+    #   @api public
+    #   @example
+    #     cut.src #=> "https://..."
+    #   @return [String] the source URL
+    attribute :src, Shale::Type::String
+
+    json do
+      map "aspectRatio", to: :aspect_ratio
+      map "width", to: :width
+      map "height", to: :height
+      map "src", to: :src
+    end
+  end
+
+  # Represents media image information
+  class MediaImage < Shale::Mapper
+    # @!attribute [rw] title
+    #   Returns the image title
+    #   @api public
+    #   @example
+    #     image.title #=> "Highlight Image"
+    #   @return [String] the title
+    attribute :title, Shale::Type::String
+
+    # @!attribute [rw] cuts
+    #   Returns the image cuts
+    #   @api public
+    #   @example
+    #     image.cuts #=> [#<MLB::MediaCut>, ...]
+    #   @return [Array<MediaCut>] the cuts
+    attribute :cuts, MediaCut, collection: true
+
+    json do
+      map "title", to: :title
+      map "cuts", to: :cuts
+    end
+  end
+
+  # Represents a game highlight
+  class Highlight < Shale::Mapper
+    include Equalizer.new(:id, :headline)
+
+    # @!attribute [rw] id
+    #   Returns the highlight ID
+    #   @api public
+    #   @example
+    #     highlight.id #=> "12345"
+    #   @return [String] the ID
+    attribute :id, Shale::Type::String
+
+    # @!attribute [rw] type
+    #   Returns the content type
+    #   @api public
+    #   @example
+    #     highlight.type #=> "video"
+    #   @return [String] the type
+    attribute :type, Shale::Type::String
+
+    # @!attribute [rw] headline
+    #   Returns the headline
+    #   @api public
+    #   @example
+    #     highlight.headline #=> "Player hits home run"
+    #   @return [String] the headline
+    attribute :headline, Shale::Type::String
+
+    # @!attribute [rw] description
+    #   Returns the description
+    #   @api public
+    #   @example
+    #     highlight.description #=> "Player crushes a 3-run homer"
+    #   @return [String] the description
+    attribute :description, Shale::Type::String
+
+    # @!attribute [rw] duration
+    #   Returns the duration in seconds
+    #   @api public
+    #   @example
+    #     highlight.duration #=> "00:00:45"
+    #   @return [String] the duration
+    attribute :duration, Shale::Type::String
+
+    # @!attribute [rw] playbacks
+    #   Returns the playback options
+    #   @api public
+    #   @example
+    #     highlight.playbacks #=> [#<MLB::MediaPlayback>, ...]
+    #   @return [Array<MediaPlayback>] the playbacks
+    attribute :playbacks, MediaPlayback, collection: true
+
+    # @!attribute [rw] image
+    #   Returns the thumbnail image
+    #   @api public
+    #   @example
+    #     highlight.image #=> #<MLB::MediaImage>
+    #   @return [MediaImage] the image
+    attribute :image, MediaImage
+
+    json do
+      map "id", to: :id
+      map "type", to: :type
+      map "headline", to: :headline
+      map "description", to: :description
+      map "duration", to: :duration
+      map "playbacks", to: :playbacks
+      map "image", to: :image
+    end
+  end
+
+  # Represents the highlights section
+  class HighlightsSection < Shale::Mapper
+    # @!attribute [rw] highlights
+    #   Returns the highlights
+    #   @api public
+    #   @example
+    #     section.highlights #=> [#<MLB::Highlight>, ...]
+    #   @return [Array<Highlight>] the highlights
+    attribute :highlights, Highlight, collection: true
+
+    json do
+      map "items", to: :highlights
+    end
+  end
+
+  # Represents the game content media
+  class GameContentMedia < Shale::Mapper
+    # @!attribute [rw] free_game
+    #   Returns whether this is a free game
+    #   @api public
+    #   @example
+    #     media.free_game #=> true
+    #   @return [Boolean] whether free game
+    attribute :free_game, Shale::Type::Boolean
+
+    # @!attribute [rw] enhanced_game
+    #   Returns whether this is an enhanced game
+    #   @api public
+    #   @example
+    #     media.enhanced_game #=> false
+    #   @return [Boolean] whether enhanced game
+    attribute :enhanced_game, Shale::Type::Boolean
+
+    json do
+      map "freeGame", to: :free_game
+      map "enhancedGame", to: :enhanced_game
+    end
+  end
+
+  # Represents the game content
+  class GameContent < Shale::Mapper
+    # @!attribute [rw] link
+    #   Returns the API link
+    #   @api public
+    #   @example
+    #     content.link #=> "/api/v1/game/745571/content"
+    #   @return [String] the link
+    attribute :link, Shale::Type::String
+
+    # @!attribute [rw] media
+    #   Returns the media info
+    #   @api public
+    #   @example
+    #     content.media #=> #<MLB::GameContentMedia>
+    #   @return [GameContentMedia] the media
+    attribute :media, GameContentMedia
+
+    # @!attribute [rw] highlights
+    #   Returns the highlights
+    #   @api public
+    #   @example
+    #     content.highlights #=> #<MLB::HighlightsSection>
+    #   @return [HighlightsSection] the highlights
+    attribute :highlights, HighlightsSection
+
+    json do
+      map "link", to: :link
+      map "media", to: :media
+      map "highlights", to: :highlights
+    end
+
+    # Retrieves the content for a game
+    #
+    # @api public
+    # @example Get content for a game
+    #   MLB::GameContent.find(game: 745571)
+    # @example Get content using a ScheduledGame object
+    #   MLB::GameContent.find(game: scheduled_game)
+    # @param game [Integer, ScheduledGame] the game ID or game object
+    # @return [GameContent] the game content
+    def self.find(game:)
+      game_pk = game.respond_to?(:game_pk) ? game.game_pk : game
+      response = CLIENT.get("game/#{game_pk}/content")
+      from_json(response)
+    end
+  end
+end

data/lib/mlb/game_data.rb

@@ -0,0 +1,155 @@
+require "shale"
+require_relative "team"
+require_relative "venue"
+require_relative "player"
+
+module MLB
+  # Represents game date/time information
+  class GameDateTime < Shale::Mapper
+    # @!attribute [rw] date_time
+    #   Returns the game date and time
+    #   @api public
+    #   @example
+    #     datetime.date_time #=> "2024-10-01T23:08:00Z"
+    #   @return [String] the game date and time
+    attribute :date_time, Shale::Type::String
+
+    # @!attribute [rw] original_date
+    #   Returns the original scheduled date
+    #   @api public
+    #   @example
+    #     datetime.original_date #=> "2024-10-01"
+    #   @return [String] the original date
+    attribute :original_date, Shale::Type::String
+
+    # @!attribute [rw] day_night
+    #   Returns day or night game indicator
+    #   @api public
+    #   @example
+    #     datetime.day_night #=> "night"
+    #   @return [String] day or night
+    attribute :day_night, Shale::Type::String
+
+    # @!attribute [rw] time
+    #   Returns the game time
+    #   @api public
+    #   @example
+    #     datetime.time #=> "7:08"
+    #   @return [String] the time
+    attribute :time, Shale::Type::String
+
+    # @!attribute [rw] am_pm
+    #   Returns AM or PM indicator
+    #   @api public
+    #   @example
+    #     datetime.am_pm #=> "PM"
+    #   @return [String] AM or PM
+    attribute :am_pm, Shale::Type::String
+
+    # Day game indicator value
+    DAY = "day".freeze
+    # Night game indicator value
+    NIGHT = "night".freeze
+    # AM indicator value
+    AM = "AM".freeze
+    # PM indicator value
+    PM = "PM".freeze
+
+    # Returns whether this is a day game
+    #
+    # @api public
+    # @example
+    #   datetime.day? #=> false
+    # @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
+    #   datetime.night? #=> true
+    # @return [Boolean] true if the game is a night game
+    def night? = day_night.eql?(NIGHT)
+
+    # Returns whether this game starts in the morning (AM)
+    #
+    # @api public
+    # @example
+    #   datetime.am? #=> false
+    # @return [Boolean] true if the game starts in the morning
+    def am? = am_pm.eql?(AM)
+
+    # Returns whether this game starts in the afternoon/evening (PM)
+    #
+    # @api public
+    # @example
+    #   datetime.pm? #=> true
+    # @return [Boolean] true if the game starts in the afternoon/evening
+    def pm? = am_pm.eql?(PM)
+
+    json do
+      map "dateTime", to: :date_time
+      map "originalDate", to: :original_date
+      map "dayNight", to: :day_night
+      map "time", to: :time
+      map "ampm", to: :am_pm
+    end
+  end
+
+  # Represents the teams playing in a game
+  class GameTeams < Shale::Mapper
+    # @!attribute [rw] away
+    #   Returns the away team
+    #   @api public
+    #   @example
+    #     teams.away #=> #<MLB::Team>
+    #   @return [Team] the away team
+    attribute :away, Team
+
+    # @!attribute [rw] home
+    #   Returns the home team
+    #   @api public
+    #   @example
+    #     teams.home #=> #<MLB::Team>
+    #   @return [Team] the home team
+    attribute :home, Team
+
+    json do
+      map "away", to: :away
+      map "home", to: :home
+    end
+  end
+
+  # Represents the game metadata
+  class GameData < Shale::Mapper
+    # @!attribute [rw] datetime
+    #   Returns the game date/time info
+    #   @api public
+    #   @example
+    #     data.datetime #=> #<MLB::GameDateTime>
+    #   @return [GameDateTime] the date/time info
+    attribute :datetime, GameDateTime
+
+    # @!attribute [rw] teams
+    #   Returns the teams
+    #   @api public
+    #   @example
+    #     data.teams #=> #<MLB::GameTeams>
+    #   @return [GameTeams] the teams
+    attribute :teams, GameTeams
+
+    # @!attribute [rw] venue
+    #   Returns the venue
+    #   @api public
+    #   @example
+    #     data.venue #=> #<MLB::Venue>
+    #   @return [Venue] the venue
+    attribute :venue, Venue
+
+    json do
+      map "datetime", to: :datetime
+      map "teams", to: :teams
+      map "venue", to: :venue
+    end
+  end
+end

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