mlb 0.10.0 → 0.11.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7cffb04037de85352415288a1c8756fb223d79181b7051322fa671e60a264580
-  data.tar.gz: 141e7eb182d2130fb4906aa9a6d93fdd640562f432004b29ecca505a8c96dd5d
+  metadata.gz: db602fd85f9408753f1bafd303fde04b04f55397f22e991682b14a25add446f1
+  data.tar.gz: e4a3b1d6e2125c8b3a3fb31ae4318a8504bc9c290d6f798ad0c95a1386fe82cb
 SHA512:
-  metadata.gz: 98a59eca40923bdeaecb637dbf863282fe9958c554afe15a3e75964745129aec710bcb24c8e2eeacc709190f37ac3a97bc76babc9531432e589985222ab3bfaf
-  data.tar.gz: ba7675aab23a6167c94adcb9b554b9f5b1645182d452152a690a1904af9a2af58fb9aec19624e671b3fc14cc23a4ae4ad57e2f366fa4b795905b491733e09775
+  metadata.gz: d4c25a70b9f418ff1a725f8e727ed0b8dbce4949f091302760f2aae8436cf84d2738cba2f8e2f73f3bbff36363637cdb94a7b9d548f406f1f25ee9e56ce2419b
+  data.tar.gz: 15c038e7a0bade972e0aacd3bf5a2ebadc67d07f4499bb9856057e43d52ed4b517a5dc7ed9e627e345897535a32df7290ad5181a87c273faaf9521da50f84d85

data/CHANGELOG.md

@@ -1,3 +1,18 @@
+## [0.11.0] - 2025-12-30
+* Add game data endpoints: Schedule, LiveFeed, Boxscore, Linescore, PlayByPlay
+* Add Standings for league standings and team records
+* Add Stats and Leaders for player/team statistics and league leaders
+* Add HomeRunDerby for derby bracket, pool, and player performance data
+* Add Draft for draft picks and prospect information
+* Add FreeAgents for free agent tracking
+* Add PostseasonSchedule and PostseasonSeries for playoff data
+* Add Attendance for attendance records
+* Add TeamStats, TeamLeaders, and TeamHistory endpoints
+* Add metadata endpoints: GameTypes, GameStatuses, EventTypes, Positions, PitchTypes, PitchCodes, RosterTypes, and more
+* Add WinProbability and ContextMetrics for advanced game analytics
+* Add Jobs for umpires, official scorers, and datacasters
+* Add Streaks for player hitting/pitching streaks
+
 ## [0.10.0] - 2025-04-30
 * Drop support for Ruby 3.1
 * Add equalizer for object identity

data/README.md

@@ -1,8 +1,6 @@
 [![Tests](https://github.com/sferik/mlb-ruby/actions/workflows/test.yml/badge.svg)](https://github.com/sferik/mlb-ruby/actions/workflows/test.yml)
-[![Test Coverage](https://api.codeclimate.com/v1/badges/fc32f80cb778b773a5b2/test_coverage)](https://codeclimate.com/github/sferik/mlb-ruby/test_coverage)
 [![Mutant](https://github.com/sferik/mlb-ruby/actions/workflows/mutant.yml/badge.svg)](https://github.com/sferik/mlb-ruby/actions/workflows/mutant.yml)
 [![Linter](https://github.com/sferik/mlb-ruby/actions/workflows/lint.yml/badge.svg)](https://github.com/sferik/mlb-ruby/actions/workflows/lint.yml)
-[![Maintainability](https://api.codeclimate.com/v1/badges/fc32f80cb778b773a5b2/maintainability)](https://codeclimate.com/github/sferik/mlb-ruby/maintainability)
 [![Gem Version](https://badge.fury.io/rb/mlb.svg)](https://rubygems.org/gems/mlb)
 
 # A [Ruby](https://www.ruby-lang.org) interface to the [MLB Stats API](https://statsapi.mlb.com)
@@ -25,35 +23,326 @@ Or, if Bundler is not being used to manage dependencies:
 
 ```ruby
 require "mlb"
+```
+
+### Teams
+
+```ruby
+# Get all MLB teams for a season
+teams = MLB::Teams.all(season: 2025)
+teams.size                   # => 30
+
+mets = teams.find { |t| t.id == MLB::Team::NYM }
+mets.name                    # => "New York Mets"
+mets.short_name              # => "NY Mets"
+mets.league.name             # => "National League"
+mets.division.name           # => "National League East"
+mets.first_year_of_play      # => 1962
+mets.venue.name              # => "Citi Field"
+```
+
+### Roster
+
+```ruby
+# Get a team's roster
+roster = MLB::Roster.find(team: MLB::Team::NYM, season: 2025)
+roster.size                        # => 39
+
+# Find a specific player on the roster
+entry = roster.find { |e| e.player.full_name == "Francisco Lindor" }
+entry.player.full_name             # => "Francisco Lindor"
+entry.jersey_number                # => 12
+entry.position.name                # => "Shortstop"
+entry.status.description           # => "Active"
+```
+
+### Players
+
+```ruby
+# Find a player by ID
+senga = MLB::Players.find(807882)
+senga.full_name               # => "Kodai Senga"
+senga.primary_number          # => 34
+senga.primary_position.name   # => "Pitcher"
+senga.pitch_hand.description  # => "Right"
+senga.bat_side.description    # => "Right"
+senga.current_age             # => 32
+senga.birth_date.to_s         # => "1993-01-30"
+senga.birth_city              # => "Nagaoka"
+senga.birth_state_province    # => "Niigata"
+senga.birth_country           # => "Japan"
+senga.mlb_debut_date.to_s     # => "2023-04-01"
+senga.height                  # => "6' 1\""
+senga.weight                  # => 200
+senga.active?                 # => true
+```
+
+### Schedule
+
+```ruby
+# Get games for a specific date
+games = MLB::Schedule.games(date: Date.new(2025, 6, 14))
+games.size                       # => 15
+
+# Get games for a specific team (Mets home opener)
+mets_games = MLB::Schedule.games(date: Date.new(2025, 4, 4), team: MLB::Team::NYM)
+game = mets_games.first
+game.game_pk                     # => 778465
+game.official_date.to_s          # => "2025-04-04"
+game.status.final?               # => true
+game.venue.name                  # => "Citi Field"
+game.day?                        # => true
+game.description                 # => "Mets home opener"
+game.teams.away.team.name        # => "Toronto Blue Jays"
+game.teams.home.team.name        # => "New York Mets"
+game.teams.away.score            # => 0
+game.teams.home.score            # => 5
+game.teams.home.winner?          # => true
+```
+
+### Standings
+
+```ruby
+# Get all division standings
+standings = MLB::Standings.all(season: 2025)
+standings.size                         # => 6
+
+# Access a specific division
+nl_east = standings.find { |s| s.division.name == "National League East" }
+nl_east.division.name                  # => "National League East"
+nl_east.team_records.size              # => 5
+
+# Get team standings info (Mets finished 2nd in NL East in 2025)
+mets = nl_east.team_records.find { |r| r.team.name == "New York Mets" }
+mets.team.name                         # => "New York Mets"
+mets.wins                              # => 83
+mets.losses                            # => 79
+mets.winning_percentage                # => ".512"
+mets.games_back                        # => "13.0"
+mets.runs_scored                       # => 766
+mets.runs_allowed                      # => 715
+mets.run_differential                  # => 51
+mets.division_rank                     # => "2"
+mets.streak.streak_code                # => "L1"
+```
+
+### Team Leaders
+
+```ruby
+# Get home run leaders for a specific team
+hr_leaders = MLB::TeamLeaders.find(team: MLB::Team::NYM, category: "homeRuns", season: 2025)
+hr_leaders.size                        # => 10
+
+hr_leader = hr_leaders.first
+hr_leader.rank                         # => 1
+hr_leader.value                        # => "43"
+hr_leader.person.full_name             # => "Juan Soto"
+```
+
+### League Leaders
+
+```ruby
+# Get home run leaders
+hr_leaders = MLB::Leaders.find(category: "homeRuns", season: 2025, limit: 5)
+hr_leader = hr_leaders.first
+hr_leader.rank                         # => 1
+hr_leader.value                        # => "60"
+hr_leader.person.full_name             # => "Cal Raleigh"
+hr_leader.team.name                    # => "Seattle Mariners"
+
+# Get batting average leaders
+avg_leaders = MLB::Leaders.find(category: "battingAverage", season: 2025, limit: 3)
+avg_leaders.first.person.full_name     # => "Aaron Judge"
+avg_leaders.first.value                # => ".331"
+
+# Get wins leaders for pitchers
+wins_leaders = MLB::Leaders.find(category: "wins", season: 2025, limit: 3)
+wins_leaders.first.person.full_name    # => "Max Fried"
+wins_leaders.first.value               # => "19"
+```
+
+### Awards
+
+```ruby
+# Find an award and get its recipients
+mvp = MLB::Awards.find("NLMVP")
+recipients = mvp.recipients(season: 2025)
+winner = recipients.first
+winner.player.full_name                # => "Shohei Ohtani"
+```
+
+### Draft
+
+```ruby
+# Get draft picks for a year
+picks = MLB::Draft.picks(year: 2025)
+picks.size                             # => 615
+
+# First overall pick
+first_pick = picks.first
+first_pick.pick_number                 # => 1
+first_pick.pick_round                  # => "1"
+first_pick.person.full_name            # => "Eli Willits"
+first_pick.team.name                   # => "Washington Nationals"
+first_pick.school.name                 # => "Fort Cobb-Broxton HS"
+first_pick.school.school_class         # => "HS SR"
+first_pick.pick_value                  # => "11075900"
+first_pick.signing_bonus               # => "8200000"
+```
+
+### Transactions
+
+```ruby
+# Get transactions for a date range
+transactions = MLB::Transactions.between(
+  start_date: Date.new(2025, 12, 22),
+  end_date: Date.new(2025, 12, 22)
+)
+
+# Find a specific transaction
+trade = transactions.find { |t| t.trade? && t.player&.full_name == "Jeff McNeil" }
+trade.trade?                           # => true
+trade.player.full_name                 # => "Jeff McNeil"
+trade.from_team.name                   # => "New York Mets"
+trade.to_team.name                     # => "Athletics"
+trade.description                      # => "New York Mets traded 2B Jeff McNeil and cash to Athletics for RHP Yordan Rodriguez."
+```
+
+### Boxscore
+
+```ruby
+# Get boxscore for Mets home opener (5-0 shutout win)
+boxscore = MLB::Boxscore.find(game: 778465)
+
+# Team batting stats
+home_batting = boxscore.teams.home.team_stats.batting
+home_batting.runs                      # => 5
+home_batting.hits                      # => 4
+home_batting.home_runs                 # => 1
+home_batting.rbi                       # => 5
+
+# Team pitching stats
+home_pitching = boxscore.teams.home.team_stats.pitching
+home_pitching.innings_pitched          # => "9.0"
+home_pitching.hits                     # => 4
+home_pitching.strike_outs              # => 10
+home_pitching.earned_runs              # => 0
+```
+
+### Linescore
+
+```ruby
+# Get linescore for 2025 World Series Game 7 (11 innings)
+linescore = MLB::Linescore.find(game: 813024)
+linescore.scheduled_innings            # => 9
+linescore.innings.count                # => 11
+
+# Team totals (runs, hits, errors)
+linescore.teams.home.runs              # => 4
+linescore.teams.home.hits              # => 14
+linescore.teams.away.runs              # => 5
+linescore.teams.away.hits              # => 11
+
+# Inning-by-inning breakdown
+eleventh = linescore.innings[10]
+eleventh.ordinal_num                   # => "11th"
+eleventh.away.runs                     # => 1
+eleventh.away.hits                     # => 1
+```
+
+### Play-by-Play
+
+```ruby
+# Get play-by-play for Mets home opener
+pbp = MLB::PlayByPlay.find(game: 778465)
+pbp.all_plays.size                     # => 65
+pbp.scoring_plays.size                 # => 4
+
+# Find scoring plays
+scoring = pbp.all_plays.select { |p| p.about.scoring_play? }
+hr = scoring.first
+hr.about.inning                        # => 1
+hr.about.scoring_play?                 # => true
+hr.result.event                        # => "Home Run"
+hr.result.description                  # => "Pete Alonso homers (3) on a fly ball to right field.    Francisco Lindor scores."
+hr.result.rbi                          # => 2
+hr.matchup.batter.full_name            # => "Pete Alonso"
+hr.matchup.pitcher.full_name           # => "Kevin Gausman"
+```
+
+### Win Probability
 
-mets = MLB::Teams.all(season: 2024).last
-mets.name                   # => "New York Mets"
-mets.short_name             # => "NY Mets"
-mets.abbreviation           # => "NYM"
-mets.league.name            # => "National League"
-mets.spring_league.name     # => "Grapefruit League"
-mets.division.name          # => "National League East"
-mets.first_year_of_play     # => 1962
-mets.location_name          # => "Flushing"
-mets.venue.name             # => "Citi Field"
-
-adam = MLB::Players.find(mets.roster.first.player)
-
-adam.full_name              # => "Adam Ottavino"
-adam.primary_number         # => 0
-adam.primary_position.name  # => "Pitcher"
-adam.pitch_hand.description # => "Right"
-adam.bat_side.description   # => "Switch"
-adam.current_age            # => 38
-adam.birth_date.to_s        # => "1985-11-22"
-adam.birth_city             # => "New York"
-adam.birth_state_province   # => "NY"
-adam.birth_country          # => "USA"
-adam.draft_year             # => 2006
-adam.mlb_debut_date.to_s    # => "2010-05-29"
-adam.height                 # => "6' 5\""
-adam.weight                 # => 246
-adam.active?                # => true
+```ruby
+# Get win probability data for 2025 World Series Game 7
+# Dodgers vs Blue Jays at Rogers Centre (Dodgers won 5-4 in 11 innings)
+wp = MLB::WinProbability.find(game: 813024)
+wp.size                                # => 99
+
+# Probability at game start (away team Dodgers slight favorites)
+wp.first.at_bat_index                  # => 0
+wp.first.home_team_win_probability     # => 0.464
+wp.first.away_team_win_probability     # => 0.536
+
+# After Bo Bichette's 3-run HR in the 3rd, Blue Jays led 3-0
+wp[22].home_team_win_probability       # => 0.828
+wp[22].away_team_win_probability       # => 0.172
+
+# Miguel Rojas's game-tying HR in the 9th
+wp[73].home_team_win_probability       # => 0.558
+wp[73].away_team_win_probability       # => 0.442
+
+# Will Smith's go-ahead HR in the 11th
+wp[93].home_team_win_probability       # => 0.194
+wp[93].away_team_win_probability       # => 0.806
+
+# Final out - Dodgers clinch the title
+wp.last.home_team_win_probability      # => 0.0
+wp.last.away_team_win_probability      # => 1.0
+```
+
+### Venues
+
+```ruby
+# Get all MLB venues
+venues = MLB::Venues.all(season: 2025)
+venues.size                            # => 30
+
+# Find a specific venue
+citi_field = venues.find { |v| v.name == "Citi Field" }
+citi_field.id                          # => 3289
+citi_field.name                        # => "Citi Field"
+citi_field.active?                     # => true
+
+# Find venue by ID
+citi_field = MLB::Venues.find(3289, season: 2025)
+citi_field.name                        # => "Citi Field"
+```
+
+### Attendance
+
+```ruby
+# Get attendance data for a team
+attendance = MLB::Attendance.find(team: MLB::Team::NYM, season: 2025)
+record = attendance.first
+record.team.name                       # => "New York Mets"
+record.attendance_total                # => 5816527
+record.attendance_average_home         # => 39316
+record.attendance_high                 # => 43945
+record.attendance_high_date            # => 2025-04-04 (home opener)
+record.games_home_total                # => 82
+```
+
+### Game Pace
+
+```ruby
+# Get league-wide pace of play statistics
+pace = MLB::GamePace.find(season: 2025)
+pace.total_games                       # => 2430
+pace.time_per_game                     # => "02:40:51"
+pace.runs_per_game                     # => 8.89
+pace.hits_per_game                     # => 16.52
+pace.pitches_per_game                  # => 292.22
+pace.total_extra_inn_games             # => 209
 ```
 
 ## Sponsorship
@@ -70,82 +359,6 @@ Building and maintaining an open-source project like this takes a considerable a
 
 [Click here to sponsor this project.](https://github.com/sponsors/sferik)
 
-## TODO
-
-Many of the MLB Stats API endpoints have not yet been implemented in this library. You can contribute to this library by implementing one or more of these endpoinds. If you are financially unable to sponsor this project, you can contribute code instead.
-
-- [ ] /attendance
-- [ ] /baseballStats
-- [ ] /draft{prospects}{year}{latest}
-- [ ] /eventTypes
-- [ ] /game/changes
-- [ ] /game/{gamePk}/boxscore
-- [ ] /game/{gamePk}/content
-- [ ] /game/{gamePk}/contextMetrics
-- [ ] /game/{gamePk}/feed/color
-- [ ] /game/{gamePk}/feed/color/diffPatch
-- [ ] /game/{gamePk}/feed/color/timestamps
-- [ ] /game/{gamePk}/feed/live
-- [ ] /game/{gamePk}/feed/live/diffPatch
-- [ ] /game/{gamePk}/feed/live/timestamps
-- [ ] /game/{gamePk}/linescore
-- [ ] /game/{gamePk}/playByPlay
-- [ ] /game/{gamePk}/winProbability
-- [ ] /gamePace
-- [ ] /gameStatus
-- [ ] /gameTypes
-- [ ] /highLow/{orgType}
-- [ ] /hitTrajectories
-- [ ] /homeRunDerby/{gamePk}{bracket}{pool}
-- [ ] /jobTypes
-- [ ] /jobs
-- [ ] /jobs/datacasters
-- [ ] /jobs/officialScorers
-- [ ] /jobs/umpires
-- [ ] /jobs/umpires/games/{umpireId}
-- [ ] /languages
-- [ ] /league/{leagueId}/allStarBallot
-- [ ] /league/{leagueId}/allStarFinalVote
-- [ ] /league/{leagueId}/allStarWriteIns
-- [ ] /leagueLeaderTypes
-- [ ] /logicalEvents
-- [ ] /metrics
-- [ ] /people/changes
-- [ ] /people/freeAgents
-- [ ] /people/{personId}
-- [ ] /people/{personId}/stats/game/{gamePk}
-- [ ] /pitchCodes
-- [ ] /pitchTypes
-- [ ] /platforms
-- [ ] /positions
-- [ ] /reviewReasons
-- [ ] /rosterTypes
-- [ ] /schedule
-- [ ] /schedule/games/tied
-- [ ] /schedule/postseason
-- [ ] /schedule/postseason/series
-- [ ] /schedule/postseason/tuneIn
-- [ ] /scheduleEventTypes
-- [ ] /situationCodes
-- [ ] /sky
-- [ ] /standings
-- [ ] /standingsTypes
-- [ ] /statGroups
-- [ ] /statTypes
-- [ ] /stats
-- [ ] /stats/leaders
-- [ ] /stats/streaks
-- [ ] /teams/affiliates
-- [ ] /teams/history
-- [ ] /teams/stats
-- [ ] /teams/{teamId}/alumni
-- [ ] /teams/{teamId}/coaches
-- [ ] /teams/{teamId}/leaders
-- [ ] /teams/{teamId}/personnel
-- [ ] /teams/{teamId}/roster
-- [ ] /teams/{teamId}/stats
-- [ ] /windDirection
-
 ## Development
 
 1. Checkout and repo:
@@ -182,14 +395,22 @@ Pull requests will only be accepted if they meet all the following criteria:
 
        bundle exec rake rubocop
 
-3. 100% C0 code coverage. This can be verified with:
+3. Code must typecheck. This can be verified with:
+
+       bundle exec rake steep
+
+4. 100% branch coverage. This can be verified with:
 
        bundle exec rake test
 
-4. 100% mutation coverage. This can be verified with:
+5. 100% mutation coverage. This can be verified with:
 
        bundle exec rake mutant
 
+6. 100% documentation coverage. This can be verified with:
+
+       bundle exec rake yardstick
+
 ## License
 
 The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/lib/mlb/affiliates.rb

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

data/lib/mlb/alumni.rb

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

data/lib/mlb/attendance.rb

@@ -0,0 +1,28 @@
+require "shale"
+require_relative "attendance_record"
+
+module MLB
+  # Provides methods for fetching attendance data from the API
+  class Attendance < Shale::Mapper
+    attribute :records, AttendanceRecord, collection: true
+
+    json do
+      map "records", to: :records
+    end
+
+    # Retrieves attendance data for a team
+    #
+    # @api public
+    # @example Get attendance for a team
+    #   MLB::Attendance.find(team: 147, season: 2024)
+    # @param team [Team, Integer] the team or team ID
+    # @param season [Integer, nil] the season year (defaults to current year)
+    # @return [Array<AttendanceRecord>] the attendance records
+    def self.find(team:, season: nil)
+      season ||= Utils.current_season
+      params = {teamId: Utils.extract_id(team), season:}
+      response = CLIENT.get("attendance?#{Utils.build_query(params)}")
+      from_json(response).records
+    end
+  end
+end