sleeper_api 1.5.1 → 1.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c1ac943353dae30f0fd6efa95f54f3287a85e116abd8408e843e980103557e29
-  data.tar.gz: 11569ff23125b08872ead08956c3395612a0092cf254a93450997fef069b2f19
+  metadata.gz: 764f1f24badfe4fbb8f017956f376a7e5604561d4d386e01a2ca77cf2174ddb8
+  data.tar.gz: 2616db091ddd38b8e942dce78929f8e56e2ad75de4e0bc5b5b5d52b7697bbddd
 SHA512:
-  metadata.gz: cf5797fea22593f99b428469ea2b99089f9f463f170c86bf7536c9a50398996d6a2edf2f06707b2ae6e3077ccce00d28c1bfe3ee2799943708f65a56090a536d
-  data.tar.gz: '08b1850e3dfb474167c1bc8df50700cab7669c7ac77c8d83ad6d757a92968ac345a82c5ecfc05b22b5238351d448782b48d297372acc33448dce0d1f4e9f1618'
+  metadata.gz: aea41e6b36a4cad02e526d35b0de424a32b20ce59d8d683bf8eccdd366669053c037c7ae6d2be6151031018c06d5b8d717733c8f941d3f9e7ab5bb6feb19cdb9
+  data.tar.gz: 2348a7481c68aaab18441ddf0096a02b5a4dc3a409ae7d7d1c90365af6139d1bdc919c62a9c9ab247c973c2bb03a7e989f17167ae3c5d23bdd95c2fc17ccf5a8

data/CHANGELOG.md

@@ -1,3 +1,57 @@
+## [1.7.0] - 2026-10-02
+
+### Added
+
+- **`Client#player(player_id, sport: "nfl")`** fetches one player from the
+  undocumented `/v1/players/{sport}/{id}`: the same fields as a catalog row, in
+  about 1.2 KB rather than the 14.6 MB `#get_players` downloads. It is live and
+  uncached, so it is the way to read an `injury_status` or `depth_chart_order`
+  fresher than a nightly catalog.
+- **`SleeperApi::PlayerNotFound`, a subclass of `SleeperApi::Error`.** An
+  unknown player id is a `404`, checked live 2026-10-02, unlike an unknown
+  user's `200` and `null`. Any other failure is still a plain
+  `SleeperApi::Error`.
+
+## [1.6.0] - 2026-09-28
+
+### Added
+
+- **`SleeperApi::UserNotFound`, a subclass of `SleeperApi::Error`.** Sleeper
+  answers an unknown user with `200` and a literal `null` body — checked live
+  2026-09-28 — so there was no error at all: `get_user` returned a response
+  whose `parsed_response` was nil. It now raises `UserNotFound`, and so does
+  `User.new` for a payload with no `user_id`. A caller can tell "no such user"
+  (permanent) from an outage without matching message strings; rescuing
+  `SleeperApi::Error` alone still sees both.
+
+### Changed
+
+- **`League#matchups_by_week` returns rosters on a bye** instead of dropping
+  them. Each comes back unpaired as `{ matchup_id: nil, rosters: [roster] }`,
+  never grouped with another bye. A bye used to look exactly like a missing
+  team.
+- **`get_user` raises for an unknown user** rather than returning a nil-bodied
+  response (see Added).
+
+### Fixed
+
+- **`User#leagues`, `#rosters` and `#drafts` answer for the season asked.** The
+  memo was not keyed by season, so `leagues(2025)` then `leagues(2024)` on one
+  instance returned 2025's leagues — silently wrong rows for a multi-season
+  caller.
+- **Every value interpolated into a request path is escaped.** `get_user("a b")`
+  raised `URI::InvalidURIError`, which is not a `SleeperApi::Error`, and
+  `get_user("../../league/123")` requested `/league/123`. Every `Client` path is
+  now built from escaped segments.
+- **Week 18 is reachable.** `matchups_by_week` and `transactions` accepted
+  weeks 1–17 and Sleeper's regular season runs to 18; `#matchups` now fetches
+  all eighteen.
+- **`Draft#summary` no longer raises on a pick with no metadata**, and a pick
+  with one name part is not padded with a space.
+- **The README** named `get_league_playoff_bracket` / `get_league_toilet_bowl`
+  (the methods are `get_playoff_bracket` / `get_toilet_bowl`) and described a
+  disk cache that does not exist.
+
 ## [1.5.1] - 2026-09-25
 
 ### Fixed

data/CLAUDE.md

@@ -30,6 +30,8 @@ Four layers, with a deliberate split between HTTP and modeling:
 
   Every call funnels through the private `make_request`, which handles retry-on-timeout, logging, and converts non-2xx into `SleeperApi::Error` — and, since 1.5.1, **every connection failure too** (`CONNECTION_ERRORS`: `SocketError`, `SystemCallError`, `OpenSSL::SSL::SSLError`, `EOFError`), unretried, as `"Could not reach <path>: …"`. A consumer can rescue `SleeperApi::Error` alone and see every way a call fails. **That error quotes the path**, so the path prefix is part of a public string — v1.2.0 changed it from `"Failed to fetch /user/x: 404"` to `"Failed to fetch /v1/user/x: 404"`. `Client` also owns the 24-hour in-memory player cache.
 
+  ⚠️ **Never interpolate a value into a request path; build it with the private `path(*segments)`**, which escapes each segment. An unescaped one raised `URI::InvalidURIError` — not a `SleeperApi::Error`, so it escaped every rescue — or walked out of the endpoint: `../../league/123` as a username requested `/league/123` (G.6, v1.6.0). An unknown user is `200` with a `null` body, which `get_user` turns into `SleeperApi::UserNotFound`.
+
   ⚠️ **There are two Sleeper hosts and v1.4.0 added the second.** `WEB_HOST`
   (`https://api.sleeper.com`) is the one the web app uses, and it serves
   **richer rows from same-looking paths**: `#stats_with_context` returns the
@@ -68,7 +70,7 @@ Four layers, with a deliberate split between HTTP and modeling:
 
 **Guard nil defensively.** Sleeper omits fields freely — users without `metadata`, rosters without `players`, matchups without `points`. Real leagues hit these; the spec fixtures often don't. Use `&.dig` rather than `[]` on anything nested off an API response.
 
-**Never fan out `get_players`.** It's a multi-megabyte payload of every NFL player. It's cached for 24h in an ivar on the client instance — which means the cache dies with the client. Consumers holding a short-lived client re-download it every time.
+**Never fan out `get_players`.** It's a multi-megabyte payload of every NFL player. It's cached for 24h in an ivar on the client instance — which means the cache dies with the client. Consumers holding a short-lived client re-download it every time. For one player, `#player(id)` fetches `/v1/players/nfl/{id}` live (~1.2 KB, undocumented, uncached); an unknown id is a **404** there, not the `200`/`null` an unknown user gets, and becomes `PlayerNotFound`.
 
 ### Undocumented endpoints carry undocumented vocabularies
 

data/README.md

@@ -243,10 +243,15 @@ Access player data with automatic caching:
 # Get all players (cached for 24 hours)
 players = client.get_players
 
-# Find specific player
+# Find specific player (reads the cached catalog above)
 player = client.get_player_by_id("1234")
 puts "#{player['first_name']} #{player['last_name']} - #{player['position']}"
 
+# One player, live and uncached: ~1.2 KB instead of the whole catalog.
+# Use it for a fresher injury_status or depth_chart_order than the catalog has.
+fresh = client.player("1234")
+puts "#{fresh['injury_status']} (#{fresh['injury_body_part']})"
+
 # Get trending players
 trending_adds = client.trending_players(type: "add", limit: 10)
 trending_drops = client.trending_players(type: "drop", limit: 10)
@@ -339,8 +344,8 @@ season_stats = client.stats(2025)
 real = projected.parsed_response.select { |_id, row| row.key?("pts_ppr") }
 
 # Get playoff brackets
-winners_bracket = client.get_league_playoff_bracket("league_id")
-losers_bracket = client.get_league_toilet_bowl("league_id")
+winners_bracket = client.get_playoff_bracket("league_id")
+losers_bracket = client.get_toilet_bowl("league_id")
 
 # Get league drafts
 league_drafts = client.get_league_drafts("league_id")
@@ -366,7 +371,11 @@ end
 
 ### Error Types
 
-- SleeperApi::Error - API-related errors (404, 500, timeouts, etc.)
+- SleeperApi::Error - API-related errors (404, 500, timeouts, an unreachable host)
+
+- SleeperApi::UserNotFound - a subclass of SleeperApi::Error: no Sleeper user has that identifier. Permanent, so rescue it before SleeperApi::Error if you retry the rest
+
+- SleeperApi::PlayerNotFound - a subclass of SleeperApi::Error: `client.player` was given an id Sleeper does not have. Permanent, like UserNotFound
 
 - ArgumentError - Invalid parameters passed to methods
 
@@ -374,12 +383,10 @@ end
 
 ### Caching
 
-- Player data is cached for 24 hours to reduce API calls
+- Player data is cached in memory for 24 hours, on the client instance — a new client downloads it again
 
 - League/User/Draft data is cached per instance
 
-- Cache files are stored in the current working directory
-
 ### Rate Limiting
 
 - Be mindful of Sleeper's rate limits: stay under 1000 API calls per minute
@@ -390,7 +397,7 @@ end
 
 ### Memory Usage
 
-- Large datasets (like all players) are cached to disk
+- The all-players payload is several megabytes and held in memory; never fan it out
 
 - League rosters and matchups are fetched lazily
 

data/lib/sleeper_api/client.rb

@@ -76,11 +76,18 @@ module SleeperApi
 
     # Fetch user data by identifier.
     #
+    # Sleeper answers an unknown user with 200 and a literal `null` body, not
+    # a 404, so that is turned into {SleeperApi::UserNotFound} here.
+    #
     # @param identifier [String] Username or user ID
     # @return [Hash] Raw user data
+    # @raise [SleeperApi::UserNotFound] If no user has that identifier
     # @see https://docs.sleeper.com/#user
     def get_user(identifier)
-      make_request("/v1/user/#{identifier}")
+      response = make_request(path("v1", "user", identifier))
+      raise UserNotFound, "No Sleeper user #{identifier.to_s.inspect}" if response.parsed_response.nil?
+
+      response
     end
 
     # Get leagues for a user in a specific season.
@@ -91,7 +98,7 @@ module SleeperApi
     # @return [Array<Hash>] League data
     # @see https://docs.sleeper.com/#get-all-leagues-for-user
     def get_user_leagues(user_id, sport: "nfl", season: Time.now.year)
-      make_request("/v1/user/#{user_id}/leagues/#{sport}/#{season}")
+      make_request(path("v1", "user", user_id, "leagues", sport, season))
     end
 
     # Get drafts for a user in a specific season.
@@ -102,7 +109,7 @@ module SleeperApi
     # @return [Array<Hash>] Draft data
     # @see https://docs.sleeper.com/#get-all-drafts-for-user
     def get_user_drafts(user_id, sport: "nfl", season: Time.now.year)
-      make_request("/v1/user/#{user_id}/drafts/#{sport}/#{season}")
+      make_request(path("v1", "user", user_id, "drafts", sport, season))
     end
 
     # Fetch league details.
@@ -111,7 +118,7 @@ module SleeperApi
     # @return [Hash] League metadata
     # @see https://docs.sleeper.com/#get-a-specific-league
     def get_league(league_id)
-      make_request("/v1/league/#{league_id}")
+      make_request(path("v1", "league", league_id))
     end
 
     # Get all rosters in a league.
@@ -120,7 +127,7 @@ module SleeperApi
     # @return [Array<Hash>] Roster data
     # @see https://docs.sleeper.com/#getting-rosters-in-a-league
     def get_league_rosters(league_id)
-      make_request("/v1/league/#{league_id}/rosters")
+      make_request(path("v1", "league", league_id, "rosters"))
     end
 
     # Get all users in a league.
@@ -129,7 +136,7 @@ module SleeperApi
     # @return [Array<Hash>] User data
     # @see https://docs.sleeper.com/#getting-users-in-a-league
     def get_league_users(league_id)
-      make_request("/v1/league/#{league_id}/users")
+      make_request(path("v1", "league", league_id, "users"))
     end
 
     # Get matchups for a specific week.
@@ -139,7 +146,7 @@ module SleeperApi
     # @return [Array<Hash>] Matchup data
     # @see https://docs.sleeper.com/#getting-matchups-in-a-league
     def get_league_matchups(league_id, week)
-      make_request("/v1/league/#{league_id}/matchups/#{week}")
+      make_request(path("v1", "league", league_id, "matchups", week))
     end
 
     # Get playoff winners bracket.
@@ -148,7 +155,7 @@ module SleeperApi
     # @return [Array<Hash>] Bracket matchups
     # @see https://docs.sleeper.com/#getting-the-playoff-bracket
     def get_playoff_bracket(league_id)
-      make_request("/v1/league/#{league_id}/winners_bracket")
+      make_request(path("v1", "league", league_id, "winners_bracket"))
     end
 
     # Get toilet bowl (losers bracket).
@@ -157,7 +164,7 @@ module SleeperApi
     # @return [Array<Hash>] Bracket matchups
     # @see https://docs.sleeper.com/#getting-the-playoff-bracket
     def get_toilet_bowl(league_id)
-      make_request("/v1/league/#{league_id}/losers_bracket")
+      make_request(path("v1", "league", league_id, "losers_bracket"))
     end
 
     # Get transactions for a specific week.
@@ -167,7 +174,7 @@ module SleeperApi
     # @return [Array<Hash>] Transaction data
     # @see https://docs.sleeper.com/#get-transactions
     def get_transactions(league_id, week)
-      make_request("/v1/league/#{league_id}/transactions/#{week}")
+      make_request(path("v1", "league", league_id, "transactions", week))
     end
 
     # Get league drafts.
@@ -176,7 +183,7 @@ module SleeperApi
     # @return [Array<Hash>] Draft data
     # @see https://docs.sleeper.com/#get-all-drafts-for-a-league
     def get_league_drafts(league_id)
-      make_request("/v1/league/#{league_id}/drafts")
+      make_request(path("v1", "league", league_id, "drafts"))
     end
 
     # Get traded draft picks for a league.
@@ -185,7 +192,7 @@ module SleeperApi
     # @return [Array<Hash>] Traded picks
     # @see https://docs.sleeper.com/#get-traded-picks-in-a-draft
     def get_league_traded_picks(league_id)
-      make_request("/v1/league/#{league_id}/traded_picks")
+      make_request(path("v1", "league", league_id, "traded_picks"))
     end
 
     # Fetch draft details.
@@ -194,7 +201,7 @@ module SleeperApi
     # @return [Hash] Draft metadata
     # @see https://docs.sleeper.com/#get-a-specific-draft
     def get_draft(draft_id)
-      make_request("/v1/draft/#{draft_id}")
+      make_request(path("v1", "draft", draft_id))
     end
 
     # Get draft picks.
@@ -203,7 +210,7 @@ module SleeperApi
     # @return [Array<Hash>] Pick data
     # @see https://docs.sleeper.com/#get-all-picks-in-a-draft
     def get_draft_picks(draft_id)
-      make_request("/v1/draft/#{draft_id}/picks")
+      make_request(path("v1", "draft", draft_id, "picks"))
     end
 
     # Get traded draft picks for a draft.
@@ -212,7 +219,7 @@ module SleeperApi
     # @return [Array<Hash>] Traded picks
     # @see https://docs.sleeper.com/#get-traded-picks-in-a-draft
     def get_draft_traded_picks(draft_id)
-      make_request("/v1/draft/#{draft_id}/traded_picks")
+      make_request(path("v1", "draft", draft_id, "traded_picks"))
     end
 
     # Get NFL state (week, season status).
@@ -221,7 +228,7 @@ module SleeperApi
     # @return [Hash] State data
     # @see https://docs.sleeper.com/#get-nfl-state
     def get_nfl_state(sport = "nfl")
-      nfl_state = make_request("/v1/state/#{sport}")
+      nfl_state = make_request(path("v1", "state", sport))
       nfl_state.each_with_object({}) do |(k, v), result|
         key = k.is_a?(String) ? k.to_sym : k
         result[key] = v
@@ -424,7 +431,7 @@ module SleeperApi
     # @param sport [String] Sport code (default: "nfl")
     # @return [HTTParty::Response] Array of games
     def schedule(season, season_type: "regular", sport: "nfl")
-      make_request("/schedule/#{sport}/#{season_type}/#{season}")
+      make_request(path("schedule", sport, season_type, season))
     end
 
     # Get trending players.
@@ -436,7 +443,8 @@ module SleeperApi
     # @return [Array<Hash>] Trending players
     # @see https://docs.sleeper.com/#trending-players
     def trending_players(sport = "nfl", type: "add", lookback_hours: 24, limit: 25)
-      make_request("/v1/players/#{sport}/trending/#{type}?lookback_hours=#{lookback_hours}&limit=#{limit}")
+      query = URI.encode_www_form(lookback_hours: lookback_hours, limit: limit)
+      make_request("#{path("v1", "players", sport, "trending", type)}?#{query}")
     end
 
     # Get all player data (cached for 24 hours).
@@ -447,7 +455,7 @@ module SleeperApi
     def get_players(sport = "nfl")
       return @players_cache if @players_cache && @cache_timestamp && (Time.now - @cache_timestamp) < (3600 * 24)
 
-      response = make_request("/v1/players/#{sport}")
+      response = make_request(path("v1", "players", sport))
       @players_cache = response.parsed_response
       @cache_timestamp = Time.now
 
@@ -464,20 +472,35 @@ module SleeperApi
       get_players(sport)[player_id]
     end
 
+    # Fetch one player, live: about 1.2 KB where #get_players is 14.6 MB, and
+    # not cached. Undocumented; same fields as a catalog row.
+    #
+    # Sleeper answers an unknown id with 404, unlike an unknown user's 200 and
+    # null, and that 404 becomes {SleeperApi::PlayerNotFound}.
+    #
+    # @param player_id [String] Player ID
+    # @param sport [String] Sport code (default: "nfl")
+    # @return [HTTParty::Response] The player's raw data
+    # @raise [SleeperApi::PlayerNotFound] If no player has that ID
+    def player(player_id, sport: "nfl")
+      make_request(path("v1", "players", sport, player_id),
+                   not_found: -> { PlayerNotFound.new("No Sleeper player #{player_id.to_s.inspect}") })
+    end
+
     private
 
-    # Path for #stats and #projections. Segments are escaped because they are
-    # interpolated into a URI path: an unescaped one can walk out of the
-    # endpoint entirely, which is the bug the consuming app had to work around
-    # for #get_user.
-    #
-    # A nil week drops the segment rather than defaulting, because the shorter
-    # path is season totals.
-    def weekly_path(resource, sport, season_type, season, week)
-      segments = [resource, sport, season_type, season, week].compact
-      escaped = segments.map { |segment| ERB::Util.url_encode(segment.to_s) }
+    # Every request path is built here, from escaped segments. An unescaped
+    # one raised URI::InvalidURIError, which is not a SleeperApi::Error, or
+    # walked out of the endpoint entirely: `../../league/123` as a username
+    # requested /league/123.
+    def path(*segments)
+      "/#{segments.map { |segment| ERB::Util.url_encode(segment.to_s) }.join("/")}"
+    end
 
-      "/v1/#{escaped.join("/")}"
+    # Path for #stats and #projections. A nil week drops the segment rather
+    # than defaulting, because the shorter path is season totals.
+    def weekly_path(resource, sport, season_type, season, week)
+      path("v1", *[resource, sport, season_type, season, week].compact)
     end
 
     # Make an HTTP request with retry logic and logging.
@@ -495,9 +518,11 @@ module SleeperApi
     #
     # @param path [String] API endpoint path
     # @param host [String, nil] a different host, e.g. WEB_HOST
+    # @param not_found [Proc, nil] builds the error a 404 raises, for an
+    #   endpoint where 404 means "no such thing" rather than a failure
     # @return [HTTParty::Response]
     # @raise [SleeperApi::Error] On HTTP errors or timeouts
-    def make_request(path, host: nil)
+    def make_request(path, host: nil, not_found: nil)
       named = host ? "#{host}#{path}" : path
       options = { timeout: @config.timeout }
       options[:base_uri] = host if host
@@ -511,6 +536,8 @@ module SleeperApi
           response
         else
           @config.logger&.error("Failed to fetch #{named}: #{response.code}")
+          raise not_found.call if not_found && response.code == 404
+
           raise SleeperApi::Error, "Failed to fetch #{named}: #{response.code}"
         end
       rescue Net::OpenTimeout, Net::ReadTimeout => e

data/lib/sleeper_api/draft.rb

@@ -109,8 +109,8 @@ module SleeperApi
         top_picks: picks.select { |pick| pick[:round] == 1 }.map do |pick|
           {
             player_id: pick[:player_id],
-            player_name: "#{pick[:metadata][:first_name]} #{pick[:metadata][:last_name]}",
-            position: pick[:metadata][:position],
+            player_name: pick_player_name(pick),
+            position: pick[:metadata]&.dig(:position),
             picked_by: pick[:picked_by]
           }
         end
@@ -135,6 +135,13 @@ module SleeperApi
 
     private
 
+    # A pick can arrive with null metadata, or a team defense with only a
+    # last name, so the name is built from whatever parts exist.
+    def pick_player_name(pick)
+      parts = [pick[:metadata]&.dig(:first_name), pick[:metadata]&.dig(:last_name)].compact
+      parts.empty? ? nil : parts.join(" ")
+    end
+
     def fetch_draft_data
       @draft_data ||= @client.get_draft(@draft_id)
     end

data/lib/sleeper_api/league.rb

@@ -22,7 +22,7 @@ module SleeperApi
 
       @league_id = league_id
       @client = client
-      @weeks = 1..17
+      @weeks = 1..18
       @league_data = nil
       @league_rosters = nil
       @league_users = nil
@@ -105,7 +105,7 @@ module SleeperApi
 
     # Get formatted matchups for a specific week.
     #
-    # @param week [Integer] Week number (1-17)
+    # @param week [Integer] Week number (1-18)
     # @return [Array<Hash>] Matchup data with scoring breakdown
     # @raise [ArgumentError] If week is invalid
     #
@@ -117,7 +117,7 @@ module SleeperApi
     #     end
     #   end
     def matchups_by_week(week: nil)
-      raise ArgumentError, "Week must be between 1 and 17" unless @weeks.include?(week)
+      raise ArgumentError, "Week must be between #{@weeks.min} and #{@weeks.max}" unless @weeks.include?(week)
 
       fetch_matchups([week]) unless @matchups&.key?(week)
       format_matchups(week)
@@ -140,7 +140,7 @@ module SleeperApi
 
     # Get formatted transactions for a specific week.
     #
-    # @param week [Integer] Week number (1-17)
+    # @param week [Integer] Week number (1-18)
     # @return [Array<Hash>] Transaction data with adds/drops and draft picks
     # @raise [ArgumentError] If week is invalid
     #
@@ -150,7 +150,7 @@ module SleeperApi
     #     puts "#{tx[:type]}: #{tx[:adds]&.length || 0} adds, #{tx[:drops]&.length || 0} drops"
     #   end
     def transactions(week: nil)
-      raise ArgumentError, "Week must be between 1 and 17" unless @weeks.include?(week)
+      raise ArgumentError, "Week must be between #{@weeks.min} and #{@weeks.max}" unless @weeks.include?(week)
 
       fetch_transactions([week]) unless @transactions&.key?(week)
       format_transactions(week)
@@ -320,32 +320,32 @@ module SleeperApi
       week_matchups = @matchups[week] || []
       return [] if week_matchups.empty?
 
-      week_matchups.group_by { |match| match["matchup_id"] }.map do |matchup_id, matchup_entries|
-        next unless matchup_id
+      # A roster on a bye has a null matchup_id. Each one is its own unpaired
+      # entry: grouping the nils together would pair two teams that never met.
+      paired, byes = week_matchups.partition { |match| match["matchup_id"] }
 
-        {
-          matchup_id: matchup_id,
-          rosters: matchup_entries.map do |roster|
-            starters = roster["starters"] || []
-
-            bench = (roster["players"] || []) - starters
-            {
-              roster_id: roster["roster_id"],
-              points: roster["points"],
-              custom_points: roster["custom_points"],
-              total_points: (roster["points"] || 0) + (roster["custom_points"] || 0),
-              starters: starters,
-              bench: bench,
-              starter_points: (starters || []).map do |starter_id|
-                { starter_id => roster["players_points"]&.dig(starter_id) || 0 }
-              end,
-              bench_points: bench.map do |bench_player_id|
-                { bench_player_id => roster["players_points"]&.dig(bench_player_id) || 0 }
-              end
-            }
-          end
-        }
-      end.compact
+      paired.group_by { |match| match["matchup_id"] }.map do |matchup_id, entries|
+        { matchup_id: matchup_id, rosters: entries.map { |roster| format_matchup_roster(roster) } }
+      end + byes.map { |roster| { matchup_id: nil, rosters: [format_matchup_roster(roster)] } }
+    end
+
+    def format_matchup_roster(roster)
+      starters = roster["starters"] || []
+      bench = (roster["players"] || []) - starters
+      {
+        roster_id: roster["roster_id"],
+        points: roster["points"],
+        custom_points: roster["custom_points"],
+        total_points: (roster["points"] || 0) + (roster["custom_points"] || 0),
+        starters: starters,
+        bench: bench,
+        starter_points: player_points(roster, starters),
+        bench_points: player_points(roster, bench)
+      }
+    end
+
+    def player_points(roster, player_ids)
+      player_ids.map { |player_id| { player_id => roster["players_points"]&.dig(player_id) || 0 } }
     end
 
     def format_users

data/lib/sleeper_api/user.rb

@@ -14,18 +14,20 @@ module SleeperApi
     # @param identifier [String, Integer] Username or user ID
     # @param client [SleeperApi::Client] HTTP client instance
     # @raise [ArgumentError] If identifier is empty
-    # @raise [SleeperApi::Error] If user data is invalid
+    # @raise [SleeperApi::UserNotFound] If no user has that identifier
     def initialize(identifier, client)
       raise ArgumentError, "identifier must be a non-empty string" if identifier.to_s.empty?
 
       @identifier = identifier
       @client = client
       @user_data = nil
-      @leagues = nil
-      @drafts = nil
+      # Keyed by season: one instance is asked about several seasons, and a
+      # single memo answered every later season with the first one's data.
+      @leagues = {}
+      @drafts = {}
 
       fetch_user_data
-      @user_id = @user_data["user_id"] || raise(SleeperApi::Error, "Invalid user data: user_id not found")
+      @user_id = @user_data["user_id"] || raise(SleeperApi::UserNotFound, "Invalid user data: user_id not found")
     end
 
     # Dynamically define attribute readers for user data.
@@ -51,7 +53,6 @@ module SleeperApi
       raise ArgumentError, "season must be a valid year" unless season.is_a?(Integer)
 
       fetch_leagues(season)
-      @leagues
     end
 
     # Get all rosters for this user across all leagues in a season.
@@ -62,8 +63,7 @@ module SleeperApi
     def rosters(season = Time.now.year)
       raise ArgumentError, "season must be a valid year" unless season.is_a?(Integer)
 
-      fetch_leagues(season) unless @leagues
-      (@leagues || []).flat_map do |league|
+      fetch_leagues(season).flat_map do |league|
         league_instance = League.new(league[:league_id], @client, no_data: true)
         league_instance.rosters(user_id: @user_id)
       end
@@ -77,8 +77,7 @@ module SleeperApi
     def drafts(season = Time.now.year)
       raise ArgumentError, "season must be a valid year" unless season.is_a?(Integer)
 
-      fetch_drafts(season) unless @drafts
-      format_drafts
+      format_drafts(fetch_drafts(season))
     end
 
     # Get a summary of user's league participation.
@@ -115,17 +114,19 @@ module SleeperApi
     end
 
     def fetch_leagues(season)
-      @leagues ||= (@client.get_user_leagues(@user_id, season: season) || []).map do |league|
+      @leagues[season] ||= (@client.get_user_leagues(@user_id, season: season) || []).map do |league|
         deep_symbolize_keys(league)
       end
     end
 
     def fetch_drafts(season)
-      @drafts ||= (@client.get_user_drafts(@user_id, season: season) || []).map { |draft| deep_symbolize_keys(draft) }
+      @drafts[season] ||= (@client.get_user_drafts(@user_id, season: season) || []).map do |draft|
+        deep_symbolize_keys(draft)
+      end
     end
 
-    def format_drafts
-      (@drafts || []).map do |draft|
+    def format_drafts(drafts)
+      drafts.map do |draft|
         draft.merge(
           league_name: draft.dig(:metadata, :name),
           scoring_type: draft.dig(:metadata, :scoring_type),

data/lib/sleeper_api/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module SleeperApi
-  VERSION = "1.5.1"
+  VERSION = "1.7.0"
 end

data/lib/sleeper_api.rb

@@ -9,6 +9,13 @@ require_relative "sleeper_api/draft"
 module SleeperApi
   class Error < StandardError; end
 
+  # The identifier names no Sleeper user. Permanent, unlike the rest of
+  # Error — retrying will not help — so a caller can rescue it on its own.
+  class UserNotFound < Error; end
+
+  # The id names no Sleeper player. Permanent, like UserNotFound.
+  class PlayerNotFound < Error; end
+
   class << self
     attr_writer :configuration
   end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: sleeper_api
 version: !ruby/object:Gem::Version
-  version: 1.5.1
+  version: 1.7.0
 platform: ruby
 authors:
 - Eruity1