sleeper_api 1.7.0 → 1.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 764f1f24badfe4fbb8f017956f376a7e5604561d4d386e01a2ca77cf2174ddb8
-  data.tar.gz: 2616db091ddd38b8e942dce78929f8e56e2ad75de4e0bc5b5b5d52b7697bbddd
+  metadata.gz: ea2a84bc8be057968c5822116b20f53d1dac11550c8baf70d437fab4d72b427a
+  data.tar.gz: 3c518c6191fc0e117229a10d9ae5f7d1a04d4f8dc62db53c52e8d6af99e6a635
 SHA512:
-  metadata.gz: aea41e6b36a4cad02e526d35b0de424a32b20ce59d8d683bf8eccdd366669053c037c7ae6d2be6151031018c06d5b8d717733c8f941d3f9e7ab5bb6feb19cdb9
-  data.tar.gz: 2348a7481c68aaab18441ddf0096a02b5a4dc3a409ae7d7d1c90365af6139d1bdc919c62a9c9ab247c973c2bb03a7e989f17167ae3c5d23bdd95c2fc17ccf5a8
+  metadata.gz: 5e248beba16cf5d2ebba74570ce4856ddcefa4fa95a8c118e685d2e89ca57eea31268c848bcfc59501b25f40d0bb08bfd8c4f65d4f9f2129f799b5f8d829c053
+  data.tar.gz: 060bef1860b827761fdcbfc38e65e0a0a5ec4b1abb6da4e2e52d43416a400e3c574135ed4001363049728cf47f34d64e13465f9cfc00067f1c1ab03cb770e076

data/CHANGELOG.md

@@ -1,3 +1,33 @@
+## [1.9.0] - 2026-10-09
+
+### Added
+
+- **`avatar_url(thumb: true)`** on `User` and `League` returns
+  `sleepercdn.com/avatars/thumbs/{id}`: 19 KB of PNG where the full size was
+  2.2 MB of `application/octet-stream` (measured 2026-10-09). The default is
+  unchanged.
+- **`sport:` on `User#leagues`, `#rosters`, `#drafts` and `#summary`**, default
+  `"nfl"`, passed through to the client, which already took it. Each sport is
+  cached apart. Sleeper answers an unknown sport with `200` and `[]` (measured
+  2026-10-09), so a typo reads as "no leagues"; it is not checked against a list.
+- **`League#traded_picks`**, with `Draft#traded_picks`' three filters
+  (`original_owner_id:`, `previous_owner_id:`, `current_owner_id:`). `season`
+  stays the string Sleeper sends.
+- **`League#drafts`**, as symbol-keyed hashes rather than `Draft` objects, since
+  a `Draft` fetches on construction.
+
+## [1.8.0] - 2026-10-02
+
+### Added
+
+- **`Client#player_news(player_id, sport: "nfl", limit: 10)`** fetches one
+  player's recent news from the undocumented
+  `api.sleeper.com/players/{sport}/{id}/news`, newest first: RotoWire,
+  FantasyPros and RotoBaller items with a `metadata` title, description and
+  usually an analysis. Measured 2026-10-02: Sleeper returns at most 10 whatever
+  the limit, there is no paging, and an unknown id answers `200` with `[]`. The
+  path exists on the web host only.
+
 ## [1.7.0] - 2026-10-02
 
 ### Added

data/CLAUDE.md

@@ -70,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. 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`.
+**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`. `#player_news(id)` is that player's news on `WEB_HOST` only (`.app` 404s the path): at most 10 items whatever `limit` says, and an unknown id is `200` with `[]`, not a 404.
 
 ### Undocumented endpoints carry undocumented vocabularies
 

data/README.md

@@ -76,6 +76,7 @@ user = SleeperApi.client.user('johndoe')
 user.username                  # => "johndoe"
 user.display_name              # => "John Doe"
 user.avatar_url                # => "https://sleepercdn.com/avatars/abc123"
+user.avatar_url(thumb: true)   # => "https://sleepercdn.com/avatars/thumbs/abc123"
 user.is_bot                    # => false
 
 # All leagues for current season
@@ -89,6 +90,9 @@ end
 old_leagues = user.leagues(2023)
 championships = old_leagues.select { |l| l[:status] == "finished" }
 
+# Another sport (default "nfl"). An unknown sport answers [] rather than an error.
+basketball = user.leagues(2026, sport: "nba")
+
 # Get all my rosters across all leagues
 rosters = user.rosters
 rosters.each do |roster|
@@ -129,6 +133,7 @@ league.season                  # => "2024"
 league.total_rosters           # => 12
 league.status                  # => "regular"
 league.avatar_url              # => "https://sleepercdn.com/avatars/abc123"
+league.avatar_url(thumb: true) # => "https://sleepercdn.com/avatars/thumbs/abc123"
 
 # Formatted rosters (with team names and records)
 rosters = league.rosters
@@ -176,6 +181,13 @@ toilet_bowl_matchups = league.toilet_bowl
 matchup = toilet_bowl_matchups.first
 matchup[:team1_owner]          # => "Team Beta"
 matchup[:winner_owner]         # => "Team Beta"
+
+# Traded picks (only picks that moved), with the same filters as Draft#traded_picks
+picks = league.traded_picks(current_owner_id: 8)
+picks.first                    # => { season: "2027", round: 1, roster_id: 1, previous_owner_id: 1, owner_id: 8 }
+
+# Drafts, as hashes; open one with SleeperApi.client.draft(id)
+league.drafts.map { |d| d[:status] } # => ["complete"]
 ```
 
 ### Drafts
@@ -252,6 +264,11 @@ puts "#{player['first_name']} #{player['last_name']} - #{player['position']}"
 fresh = client.player("1234")
 puts "#{fresh['injury_status']} (#{fresh['injury_body_part']})"
 
+# One player's recent news, newest first (at most 10, from api.sleeper.com)
+client.player_news("1234").each do |item|
+  puts "#{item['source']}: #{item.dig('metadata', 'title')}"
+end
+
 # Get trending players
 trending_adds = client.trending_players(type: "add", limit: 10)
 trending_drops = client.trending_players(type: "drop", limit: 10)

data/lib/sleeper_api/client.rb

@@ -487,6 +487,20 @@ module SleeperApi
                    not_found: -> { PlayerNotFound.new("No Sleeper player #{player_id.to_s.inspect}") })
     end
 
+    # One player's recent news, newest first: RotoWire, FantasyPros and
+    # RotoBaller items, each with a `metadata` title, description and usually
+    # an analysis. Undocumented and on WEB_HOST only; Sleeper returns at most
+    # 10 whatever the limit, and an unknown id answers 200 with [].
+    #
+    # @param player_id [String] Player ID
+    # @param sport [String] Sport code (default: "nfl")
+    # @param limit [Integer] How many items, up to 10
+    # @return [HTTParty::Response] The items, newest first
+    def player_news(player_id, sport: "nfl", limit: 10)
+      query = URI.encode_www_form(limit: limit)
+      make_request("#{path("players", sport, player_id, "news")}?#{query}", host: WEB_HOST)
+    end
+
     private
 
     # Every request path is built here, from escaped segments. An unescaped

data/lib/sleeper_api/league.rb

@@ -30,6 +30,8 @@ module SleeperApi
       @transactions = nil
       @playoff_bracket = nil
       @toilet_bowl = nil
+      @traded_picks = nil
+      @drafts = nil
 
       fetch_league_data unless no_data
     end
@@ -43,9 +45,15 @@ module SleeperApi
 
     # Generate avatar URL from ID.
     #
-    # @return [String, nil] Full avatar URL or nil if no avatar
-    def avatar_url
-      avatar ? "https://sleepercdn.com/avatars/#{avatar}" : nil
+    # The full size was 2.2 MB of `application/octet-stream` and the thumbnail
+    # 19 KB of PNG, measured 2026-10-09; a list of avatars wants the thumbnail.
+    #
+    # @param thumb [Boolean] The thumbnail instead of the full-size image
+    # @return [String, nil] Avatar URL or nil if no avatar
+    def avatar_url(thumb: false)
+      return nil unless avatar
+
+      thumb ? "https://sleepercdn.com/avatars/thumbs/#{avatar}" : "https://sleepercdn.com/avatars/#{avatar}"
     end
 
     # Get the reigning champion's roster.
@@ -172,8 +180,38 @@ module SleeperApi
       @toilet_bowl
     end
 
+    # Get the league's traded draft picks, as Sleeper sends them.
+    #
+    # `season` is a string ("2027"); every owner is a roster id. A pick that
+    # never moved is not listed.
+    #
+    # @param original_owner_id [Integer, nil] Filter by the roster the pick began with
+    # @param previous_owner_id [Integer, nil] Filter by previous owner
+    # @param current_owner_id [Integer, nil] Filter by current owner
+    # @return [Array<Hash>] Traded picks, symbol-keyed
+    def traded_picks(original_owner_id: nil, previous_owner_id: nil, current_owner_id: nil)
+      fetch_traded_picks unless @traded_picks
+      picks = @traded_picks
+      picks = picks.select { |pick| pick[:roster_id] == original_owner_id } if original_owner_id
+      picks = picks.select { |pick| pick[:previous_owner_id] == previous_owner_id } if previous_owner_id
+      picks = picks.select { |pick| pick[:owner_id] == current_owner_id } if current_owner_id
+      picks
+    end
+
+    # Get the league's drafts. Hashes rather than `Draft` objects, because a
+    # `Draft` fetches on construction: `client.draft(id)` opens one.
+    #
+    # @return [Array<Hash>] Drafts, symbol-keyed
+    def drafts
+      @drafts ||= (@client.get_league_drafts(@league_id) || []).map { |draft| deep_symbolize_keys(draft) }
+    end
+
     private
 
+    def fetch_traded_picks
+      @traded_picks ||= (@client.get_league_traded_picks(@league_id) || []).map { |pick| deep_symbolize_keys(pick) }
+    end
+
     def fetch_league_data
       @league_data ||= @client.get_league(@league_id)
     end

data/lib/sleeper_api/user.rb

@@ -39,31 +39,40 @@ module SleeperApi
 
     # Generate avatar URL from ID.
     #
-    # @return [String, nil] Full avatar URL or nil if no avatar
-    def avatar_url
-      avatar ? "https://sleepercdn.com/avatars/#{avatar}" : nil
+    # The full size was 2.2 MB of `application/octet-stream` and the thumbnail
+    # 19 KB of PNG, measured 2026-10-09; a list of avatars wants the thumbnail.
+    #
+    # @param thumb [Boolean] The thumbnail instead of the full-size image
+    # @return [String, nil] Avatar URL or nil if no avatar
+    def avatar_url(thumb: false)
+      return nil unless avatar
+
+      thumb ? "https://sleepercdn.com/avatars/thumbs/#{avatar}" : "https://sleepercdn.com/avatars/#{avatar}"
     end
 
     # Get all leagues for a specific season.
     #
     # @param season [Integer] Season year (default: current year)
+    # @param sport [String] Sport code (default: "nfl"). An unknown one answers
+    #   200 with [] (measured 2026-10-09), so a typo reads as "no leagues".
     # @return [Array<Hash>] Formatted league objects
     # @raise [ArgumentError] If season is not an integer
-    def leagues(season = Time.now.year)
+    def leagues(season = Time.now.year, sport: "nfl")
       raise ArgumentError, "season must be a valid year" unless season.is_a?(Integer)
 
-      fetch_leagues(season)
+      fetch_leagues(season, sport)
     end
 
     # Get all rosters for this user across all leagues in a season.
     #
     # @param season [Integer] Season year (default: current year)
+    # @param sport [String] Sport code (default: "nfl")
     # @return [Array<Hash>] Formatted roster objects from all leagues
     # @raise [ArgumentError] If season is not an integer
-    def rosters(season = Time.now.year)
+    def rosters(season = Time.now.year, sport: "nfl")
       raise ArgumentError, "season must be a valid year" unless season.is_a?(Integer)
 
-      fetch_leagues(season).flat_map do |league|
+      fetch_leagues(season, sport).flat_map do |league|
         league_instance = League.new(league[:league_id], @client, no_data: true)
         league_instance.rosters(user_id: @user_id)
       end
@@ -72,21 +81,23 @@ module SleeperApi
     # Get all drafts for a specific season with enhanced metadata.
     #
     # @param season [Integer] Season year (default: current year)
+    # @param sport [String] Sport code (default: "nfl")
     # @return [Array<Hash>] Formatted draft objects with league info
     # @raise [ArgumentError] If season is not an integer
-    def drafts(season = Time.now.year)
+    def drafts(season = Time.now.year, sport: "nfl")
       raise ArgumentError, "season must be a valid year" unless season.is_a?(Integer)
 
-      format_drafts(fetch_drafts(season))
+      format_drafts(fetch_drafts(season, sport))
     end
 
     # Get a summary of user's league participation.
     #
     # @param season [Integer] Season year (default: current year)
+    # @param sport [String] Sport code (default: "nfl")
     # @return [Hash] Summary statistics
-    def summary(season = Time.now.year)
-      leagues_data = leagues(season)
-      rosters_data = rosters(season)
+    def summary(season = Time.now.year, sport: "nfl")
+      leagues_data = leagues(season, sport: sport)
+      rosters_data = rosters(season, sport: sport)
 
       {
         season: season,
@@ -113,14 +124,15 @@ module SleeperApi
       @user_data ||= @client.get_user(@identifier)
     end
 
-    def fetch_leagues(season)
-      @leagues[season] ||= (@client.get_user_leagues(@user_id, season: season) || []).map do |league|
+    # Keyed on the sport too, or one sport's answer would serve the other's.
+    def fetch_leagues(season, sport)
+      @leagues[[sport, season]] ||= (@client.get_user_leagues(@user_id, sport: sport, season: season) || []).map do |league|
         deep_symbolize_keys(league)
       end
     end
 
-    def fetch_drafts(season)
-      @drafts[season] ||= (@client.get_user_drafts(@user_id, season: season) || []).map do |draft|
+    def fetch_drafts(season, sport)
+      @drafts[[sport, season]] ||= (@client.get_user_drafts(@user_id, sport: sport, season: season) || []).map do |draft|
         deep_symbolize_keys(draft)
       end
     end

data/lib/sleeper_api/version.rb

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

metadata

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