sleeper_api 1.5.0 → 1.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0fdd2ef6194210448caf049cdd89a37182bcd13205e45ea9543945c172d36fd4
-  data.tar.gz: 811a0991f5c863956c62c637971571aef98ccd379f9a3bff4b33ad1d28405290
+  metadata.gz: 0375caa5f944f2f083cdc8cec7672f44fc9219969e8e733bde441c377e16ede4
+  data.tar.gz: a1d54df90f2ff3ba533d11756993513eca6bae884f1a1fc0e57e51d9be84fa12
 SHA512:
-  metadata.gz: 16f575a6d822157d44b7d5aef135626371e0fb03ed8359c70abf82f49bf6d9ae1373ff7a5ee49cbf4c32986593eec23e838b08e70ce5306e29d5fb3df5229be4
-  data.tar.gz: b7b325b17bfd0c9d921ec16dbaa07fdcf6f277d242732db1f414d11f0c5846664ac300c2fc64f2401a3ef54402c112b8a9e89651f986ba3628a5fdcabc38f394
+  metadata.gz: ba5338528abf3a7c924dd9fdfd7dbf6440a1ac75debc3426cca4d580520a65ce7986075c2d8a6709305a5e57720c08a9b0749710e83b46381628b2991bab702b
+  data.tar.gz: 84ff6c0503398ca629009b1976dfd2ead6a9594d63eabdf97fb0056ed29d3b4965e8f2a4d17091c1e6d02560c1b28f469afeffeacaccc36acb7b394c3415dc2a

data/CHANGELOG.md

@@ -1,3 +1,61 @@
+## [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
+
+- **A connection that never got an answer now raises `SleeperApi::Error`.**
+  Before, only non-2xx responses and timeouts did: no DNS (`SocketError`), a
+  refused, reset or unreachable connection (`SystemCallError`), a failed TLS
+  handshake (`OpenSSL::SSL::SSLError`) and a socket closed mid-response
+  (`EOFError`) escaped `make_request` as themselves. A caller rescuing
+  `SleeperApi::Error` for "Sleeper is down" missed the commonest outage of all —
+  a laptop waking before its network — and one consumer recorded 196 failed
+  imports that its retry policy never saw.
+
+  The message is `"Could not reach <path>: <original message>"`, naming the host
+  for a `WEB_HOST` call. **These are not retried** whatever `retries` is set to:
+  they fail at once, and the caller's backoff is the one that can wait long
+  enough to matter. `retries` still governs timeouts only.
+
 ## [1.5.0] - 2026-09-25
 
 ### Added

data/CLAUDE.md

@@ -28,7 +28,9 @@ Four layers, with a deliberate split between HTTP and modeling:
 - **`SleeperApi`** (`lib/sleeper_api.rb`) — module-level config + memoized global `SleeperApi.client`. `Configuration` validates `timeout` (10–60) and `retries` (0–5), raising `SleeperApi::Error` outside those bounds.
 - **`Client`** — the only thing that talks HTTP. `include HTTParty` with `base_uri "https://api.sleeper.app"` — **the bare host; the `/v1` lives in each path**. That is deliberate and load-bearing: not every Sleeper endpoint is versioned. `/schedule/{sport}/{season_type}/{season}` is served from the host root, and while `base_uri` carried the version that endpoint was unreachable at any path a caller could pass in. A new endpoint spells out where it lives; do not move the version back into `base_uri` to shorten the paths.
 
-  Every call funnels through the private `make_request`, which handles retry-on-timeout, logging, and converts non-2xx into `SleeperApi::Error`. **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.
+  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

data/README.md

@@ -339,8 +339,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 +366,9 @@ 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
 
 - ArgumentError - Invalid parameters passed to methods
 
@@ -374,12 +376,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 +390,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

@@ -1,4 +1,5 @@
 require "httparty"
+require "openssl"
 require "json"
 require "erb"
 
@@ -28,6 +29,12 @@ module SleeperApi
     # because every other endpoint here lives on `.app`.
     WEB_HOST = "https://api.sleeper.com".freeze
 
+    # The request never got an answer (1.5.1): no DNS, a refused or reset
+    # connection, a failed TLS handshake, a socket closed mid-response. Before,
+    # these escaped as themselves, so a caller rescuing SleeperApi::Error for
+    # an outage missed the commonest one. Timeouts are handled separately.
+    CONNECTION_ERRORS = [SocketError, SystemCallError, OpenSSL::SSL::SSLError, EOFError].freeze
+
     # Not HTTParty's own. Its JSON branch passes `quirks_mode`, which json 3.0
     # removed, so without this every response raises ArgumentError the moment a
     # consumer resolves json 3. See JsonParser.
@@ -69,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.
@@ -84,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.
@@ -95,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.
@@ -104,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.
@@ -113,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.
@@ -122,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.
@@ -132,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.
@@ -141,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).
@@ -150,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.
@@ -160,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.
@@ -169,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.
@@ -178,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.
@@ -187,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.
@@ -196,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.
@@ -205,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).
@@ -214,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
@@ -417,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.
@@ -429,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).
@@ -440,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
 
@@ -459,18 +474,18 @@ module SleeperApi
 
     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.
@@ -516,6 +531,11 @@ module SleeperApi
           @config.logger&.error("Request timed out for #{named} after #{retries} retries")
           raise SleeperApi::Error, "Request timed out after #{retries} retries"
         end
+      rescue *CONNECTION_ERRORS => e
+        # No retry: these fail at once, and the caller's backoff is the one
+        # that can wait long enough to matter.
+        @config.logger&.error("Could not reach #{named}: #{e.message}")
+        raise SleeperApi::Error, "Could not reach #{named}: #{e.message}"
       end
     end
   end

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.0"
+  VERSION = "1.6.0"
 end

data/lib/sleeper_api.rb

@@ -9,6 +9,10 @@ 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
+
   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.0
+  version: 1.6.0
 platform: ruby
 authors:
 - Eruity1