mlb 0.10.0 → 0.11.0

data/lib/mlb/event_type.rb

@@ -0,0 +1,61 @@
+require "equalizer"
+require "shale"
+
+module MLB
+  # Represents a baseball event type
+  class EventType < Shale::Mapper
+    include Equalizer.new(:code)
+
+    # @!attribute [rw] code
+    #   Returns the event code
+    #   @api public
+    #   @example
+    #     event_type.code #=> "single"
+    #   @return [String] the event code
+    attribute :code, Shale::Type::String
+
+    # @!attribute [rw] description
+    #   Returns the event description
+    #   @api public
+    #   @example
+    #     event_type.description #=> "Single"
+    #   @return [String] the event description
+    attribute :description, Shale::Type::String
+
+    # @!attribute [rw] plate_appearance
+    #   Returns whether this event counts as a plate appearance
+    #   @api public
+    #   @example
+    #     event_type.plate_appearance #=> true
+    #   @return [Boolean] whether this event counts as a plate appearance
+    attribute :plate_appearance, Shale::Type::Boolean
+
+    # @!attribute [rw] hit
+    #   Returns whether this event is a hit
+    #   @api public
+    #   @example
+    #     event_type.hit #=> true
+    #   @return [Boolean] whether this event is a hit
+    attribute :hit, Shale::Type::Boolean
+
+    # @!attribute [rw] base_running_event
+    #   Returns whether this event involves base running
+    #   @api public
+    #   @example
+    #     event_type.base_running_event #=> false
+    #   @return [Boolean] whether this event involves base running
+    attribute :base_running_event, Shale::Type::Boolean
+
+    alias_method :plate_appearance?, :plate_appearance
+    alias_method :hit?, :hit
+    alias_method :base_running_event?, :base_running_event
+
+    json do
+      map "code", to: :code
+      map "description", to: :description
+      map "plateAppearance", to: :plate_appearance
+      map "hit", to: :hit
+      map "baseRunningEvent", to: :base_running_event
+    end
+  end
+end

data/lib/mlb/event_types.rb

@@ -0,0 +1,12 @@
+require_relative "collection"
+require_relative "event_type"
+
+module MLB
+  # Provides methods for fetching event types from the API
+  #
+  # @example Fetch all event types
+  #   MLB::EventTypes.all #=> [#<MLB::EventType>, ...]
+  class EventTypes < Collection
+    collection endpoint: "eventTypes", item_type: EventType, collection_name: :event_types
+  end
+end

data/lib/mlb/free_agent.rb

@@ -0,0 +1,78 @@
+require "equalizer"
+require "shale"
+require_relative "player"
+require_relative "team"
+require_relative "position"
+
+module MLB
+  # Represents a free agent
+  class FreeAgent < Shale::Mapper
+    include Equalizer.new(:player)
+
+    # @!attribute [rw] player
+    #   Returns the player
+    #   @api public
+    #   @example
+    #     free_agent.player #=> #<MLB::Player>
+    #   @return [Player] the player
+    attribute :player, Player
+
+    # @!attribute [rw] original_team
+    #   Returns the team the player left
+    #   @api public
+    #   @example
+    #     free_agent.original_team #=> #<MLB::Team>
+    #   @return [Team] the original team
+    attribute :original_team, Team
+
+    # @!attribute [rw] new_team
+    #   Returns the team the player signed with
+    #   @api public
+    #   @example
+    #     free_agent.new_team #=> #<MLB::Team>
+    #   @return [Team] the new team
+    attribute :new_team, Team
+
+    # @!attribute [rw] notes
+    #   Returns signing notes
+    #   @api public
+    #   @example
+    #     free_agent.notes #=> "Seven-Year Contract"
+    #   @return [String] the notes
+    attribute :notes, Shale::Type::String
+
+    # @!attribute [rw] date_signed
+    #   Returns the date the player signed
+    #   @api public
+    #   @example
+    #     free_agent.date_signed #=> #<Date: 2024-12-10>
+    #   @return [Date] the date signed
+    attribute :date_signed, Shale::Type::Date
+
+    # @!attribute [rw] date_declared
+    #   Returns the date the player declared free agency
+    #   @api public
+    #   @example
+    #     free_agent.date_declared #=> #<Date: 2024-10-31>
+    #   @return [Date] the date declared
+    attribute :date_declared, Shale::Type::Date
+
+    # @!attribute [rw] position
+    #   Returns the player's position
+    #   @api public
+    #   @example
+    #     free_agent.position #=> #<MLB::Position>
+    #   @return [Position] the position
+    attribute :position, Position
+
+    json do
+      map "player", to: :player
+      map "originalTeam", to: :original_team
+      map "newTeam", to: :new_team
+      map "notes", to: :notes
+      map "dateSigned", to: :date_signed
+      map "dateDeclared", to: :date_declared
+      map "position", to: :position
+    end
+  end
+end

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