sleeper_api 1.6.0 → 1.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0375caa5f944f2f083cdc8cec7672f44fc9219969e8e733bde441c377e16ede4
-  data.tar.gz: a1d54df90f2ff3ba533d11756993513eca6bae884f1a1fc0e57e51d9be84fa12
+  metadata.gz: 764f1f24badfe4fbb8f017956f376a7e5604561d4d386e01a2ca77cf2174ddb8
+  data.tar.gz: 2616db091ddd38b8e942dce78929f8e56e2ad75de4e0bc5b5b5d52b7697bbddd
 SHA512:
-  metadata.gz: ba5338528abf3a7c924dd9fdfd7dbf6440a1ac75debc3426cca4d580520a65ce7986075c2d8a6709305a5e57720c08a9b0749710e83b46381628b2991bab702b
-  data.tar.gz: 84ff6c0503398ca629009b1976dfd2ead6a9594d63eabdf97fb0056ed29d3b4965e8f2a4d17091c1e6d02560c1b28f469afeffeacaccc36acb7b394c3415dc2a
+  metadata.gz: aea41e6b36a4cad02e526d35b0de424a32b20ce59d8d683bf8eccdd366669053c037c7ae6d2be6151031018c06d5b8d717733c8f941d3f9e7ab5bb6feb19cdb9
+  data.tar.gz: 2348a7481c68aaab18441ddf0096a02b5a4dc3a409ae7d7d1c90365af6139d1bdc919c62a9c9ab247c973c2bb03a7e989f17167ae3c5d23bdd95c2fc17ccf5a8

data/CHANGELOG.md

@@ -1,3 +1,17 @@
+## [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`.
 
 ### 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)
@@ -370,6 +375,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,21 @@ 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
 
     # Every request path is built here, from escaped segments. An unescaped
@@ -503,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
@@ -519,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/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module SleeperApi
-  VERSION = "1.6.0"
+  VERSION = "1.7.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.7.0
 platform: ruby
 authors:
 - Eruity1