sleeper_api 1.6.0 → 1.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0375caa5f944f2f083cdc8cec7672f44fc9219969e8e733bde441c377e16ede4
-  data.tar.gz: a1d54df90f2ff3ba533d11756993513eca6bae884f1a1fc0e57e51d9be84fa12
+  metadata.gz: da00a42dc3d3fa73feab8e1c2278f0cdcf7a274b12709c540c2f988782828269
+  data.tar.gz: 8b2fc35f6dd3a3b546cafae1679ac0dbca75193d7886fcb12b57c5bf616da667
 SHA512:
-  metadata.gz: ba5338528abf3a7c924dd9fdfd7dbf6440a1ac75debc3426cca4d580520a65ce7986075c2d8a6709305a5e57720c08a9b0749710e83b46381628b2991bab702b
-  data.tar.gz: 84ff6c0503398ca629009b1976dfd2ead6a9594d63eabdf97fb0056ed29d3b4965e8f2a4d17091c1e6d02560c1b28f469afeffeacaccc36acb7b394c3415dc2a
+  metadata.gz: c953ad4e95e986db6ef5f6f559a7cf464a9cdeaf98ccf83e4cb25f1e99008152066e5b15ad7b852de444a13fafd81b795d6b338b5ced2cebe3e9710223aa966a
+  data.tar.gz: 4ccdabb09c1bd25a39e7f32ce6cd97c58b5237b8c18f9a030aa3d9307f26b0f736cd63cf6f3f9cfb6381305aa0f9b0b8cc038431f06bd52d37f3c74bb5edb75d

data/CHANGELOG.md

@@ -1,3 +1,29 @@
+## [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
+
+- **`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

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.
+**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

@@ -243,10 +243,20 @@ 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']})"
+
+# 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)
@@ -370,6 +380,8 @@ end
 
 - 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
 
 ## Performance Considerations

data/lib/sleeper_api/client.rb

@@ -472,6 +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
+
+    # 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
@@ -503,9 +532,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
@@ -519,6 +550,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/version.rb

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

data/lib/sleeper_api.rb

@@ -13,6 +13,9 @@ module SleeperApi
   # 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.6.0
+  version: 1.8.0
 platform: ruby
 authors:
 - Eruity1