sleeper_api 1.1.0 → 1.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8e64262b5b1ec981daba5a470cdaed3857b5b334b4b5b974b36369bb71d10fe6
-  data.tar.gz: 6e292f1ff2de695f2385736316d1d0329373cdfb8d944d399e42ffcda7014d2d
+  metadata.gz: 6fd4df8d68adb46808ea692bbf8c715f2218a07a8f93212f5efddfe404741a30
+  data.tar.gz: cd3b09acb61407c634f04d76f165a1d2e0b7b840b3564117136ecc9343bc286c
 SHA512:
-  metadata.gz: fcad44e534d0f99daa36897d56b228e432e5374d9e829915fed7cc71612588b9576a96147cedb07cc658cd0a590769161ccd74ef82f48ed7d1b0c2d7dc210e88
-  data.tar.gz: ca0a00e724c6b35182add239a7a80c9b8129c3a1af2805f216f21b50971842fa968a1c902ab97686819c676390ef89e3fa0fb4635013d9f3f8f7c5aec565d7e6
+  metadata.gz: a63777ce6255da38e963034bf9b016ca327d85dcaefc723ad508c85d58c9674939474ee00bd55b33b007e3268a043e81f8c175f06276cb77ae80b6a619871431
+  data.tar.gz: aed8fa84f731ddb1e8a01ef2cfb8987305826f665f338954e990fcb8c2c946c3d33f73edf510217ecee1923412bc6470a56931dbd9c60ba7369230c2c847627c

data/CHANGELOG.md

@@ -1,3 +1,37 @@
+## [1.3.0] - 2026-08-27
+
+### Added
+
+- `Client#stats(season, week:, season_type:, sport:)` and `Client#projections(...)` — per-player weekly statistics and projections, both undocumented, both under `/v1`. Found by probing on 2026-08-27; the consuming app's backlog had recorded "Sleeper has no projections endpoint and no player-stats endpoint" as settled fact, and several of its cards were blocked on that.
+
+  Each returns an object keyed by player id — plus `TEAM_XXX` keys for team-level rows — holding raw counting stats (`rec`, `rush_yd`, `off_snp`, `rec_rz_tgt`, …) alongside Sleeper's canned `pts_ppr` / `pts_half_ppr` / `pts_std`. 228 distinct fields were observed across one week of 2025. Omitting `week` requests season totals, which is a shorter path and a different resource rather than a default of week 1.
+
+  Three things a caller has to know, all confirmed live:
+
+  - **Nothing 404s.** An unplayed week (`regular/2026/1`), a week out of range (`regular/2025/99`) and an unrecognised season type (`banana`) all answer 200 with `{}`. An empty body is indistinguishable from a typo, so validate arguments rather than trusting emptiness.
+  - **A row count is not evidence of a projection.** `projections` for a season Sleeper has not projected still returns a full set of entries — 9,386 for 2030 — every one holding only `{"adp_dd_ppr" => 1000.0}` and no `pts_ppr`. Filter on the field you want.
+  - **`pre` and `post` restart week numbering at 1**, exactly as `#schedule` does, so rows from different season types must never be pooled.
+
+  `adp_dd_ppr` 1000.0 and `pos_rank_*` 999.0 are "unknown" sentinels rather than values.
+
+  Path segments are escaped, unlike the older `#get_user` — an unescaped segment can walk out of the endpoint entirely, which the consuming app had to work around at its own boundary.
+
+### Fixed
+
+- README.md contained 272 non-breaking spaces across 90 lines, 58 of them **inside `​```ruby` code fences** — so the documented examples raised a syntax error when copy-pasted. `lib/` and `spec/` were unaffected; only the documentation was broken. Replaced with ordinary spaces.
+
+## [1.2.0] - 2026-08-23
+
+### Added
+
+- `Client#schedule(season, season_type:, sport:)` — a season's game list, each entry `{status, date, home, away, week, game_id}`. A team's bye week is the week it appears in no game, which derives exactly: checked against 2024, 2025 and 2026, every one gives exactly one bye per team. Note `pre` (weeks 1-3) and `post` (weeks 1-4) restart week numbering, so games from different season types must never be pooled, and a season Sleeper has not scheduled yet answers 200 with `[]` rather than 404.
+
+### Changed
+
+- **`base_uri` is now the bare host, `https://api.sleeper.app`, and every path carries its own `/v1`.** The schedule endpoint is served from the host root, so while the version lived in `base_uri` it was unreachable at any path a caller could pass to `make_request`. Moving the version into the paths means one mechanism for every endpoint rather than an escape hatch for the exceptions.
+
+  **This changes the text of `SleeperApi::Error`**, which quotes the path it failed on: `"Failed to fetch /user/x: 404"` is now `"Failed to fetch /v1/user/x: 404"`. Anything matching on that string needs updating — though matching on it was never sound, since the same error covers a missing user, a 5xx and a timeout alike.
+
 ## [1.1.0] - 2026-08-22
 
 ### Fixed

data/CLAUDE.md

@@ -26,7 +26,9 @@ CI (`.github/workflows/ci.yml`) runs `bundle exec rake ci` on Ruby 3.2 only. The
 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/v1"`. Every call funnels through the private `make_request`, which handles retry-on-timeout, logging, and converts non-2xx into `SleeperApi::Error`. It also owns the 24-hour in-memory player cache.
+- **`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.
 - **`League` / `User` / `Draft`** — resource objects. Each takes `(id, client)`, fetches eagerly in the constructor, memoizes into ivars, and exposes formatted hashes.
 - **`Helpers`** — mixed into all four. `deep_symbolize_keys` plus `player_details`, which reaches through `@client` — so any class including it must define `@client`.
 

data/README.md

@@ -2,71 +2,71 @@
 
 [![Gem Version](https://badge.fury.io/rb/sleeper_api.svg)](https://badge.fury.io/rb/sleeper_api)
 
-A comprehensive Ruby gem for interacting with [Sleeper's fantasy football API](https://docs.sleeper.com/). Built with performance, reliability, and developer experience in mind.
+A comprehensive Ruby gem for interacting with [Sleeper's fantasy football API](https://docs.sleeper.com/). Built with performance, reliability, and developer experience in mind.
 
 ## Features
 
-- Complete API Coverage - Users, leagues, drafts, players, matchups, transactions
+- Complete API Coverage - Users, leagues, drafts, players, matchups, transactions
 
-- Performance Optimized - Smart caching, connection pooling, rate limiting
+- Performance Optimized - Smart caching, connection pooling, rate limiting
 
-- Robust Error Handling - Automatic retries, timeout management, detailed error messages
+- Robust Error Handling - Automatic retries, timeout management, detailed error messages
 
-- Well Tested - 90%+ test coverage with RSpec
+- Well Tested - 90%+ test coverage with RSpec
 
-- Highly Configurable - Custom timeouts, retries, logging
+- Highly Configurable - Custom timeouts, retries, logging
 
-- Production Ready - Type signatures, CI/CD, code quality tools
+- Production Ready - Type signatures, CI/CD, code quality tools
 
 ## Installation
 
 Add this line to your application's Gemfile:
 
 ```ruby
-gem 'sleeper_api'
+gem 'sleeper_api'
 ```
 
 ## Quick Start
 
 ```ruby
-require 'sleeper_api'
+require 'sleeper_api'
 
-# Basic usage with default configuration
-client = SleeperApi.client
-league = client.league("123456789012345678")
+# Basic usage with default configuration
+client = SleeperApi.client
+league = client.league("123456789012345678")
 
-# Access league information
-puts league.name          # "My Fantasy League"
-puts league.total_rosters # 12
-puts league.status        # "in_season"
+# Access league information
+puts league.name          # "My Fantasy League"
+puts league.total_rosters # 12
+puts league.status        # "in_season"
 
-# Get rosters
-rosters = league.rosters
-rosters.each do |roster|
-  puts "#{roster[:owner_display_name]}: #{roster[:wins]}-#{roster[:losses]}"
+# Get rosters
+rosters = league.rosters
+rosters.each do |roster|
+  puts "#{roster[:owner_display_name]}: #{roster[:wins]}-#{roster[:losses]}"
 end
 ```
 
 ## Configuration
 
-Customize the gem's behavior:
+Customize the gem's behavior:
 
 ```ruby
-SleeperApi.configure do |config|
-  config.timeout = 45    # Request timeout in seconds (10-60)
-  config.retries = 5     # Number of retries on failure (0-5)
-  config.logger = Logger.new(STDOUT)  # Custom logger
+SleeperApi.configure do |config|
+  config.timeout = 45    # Request timeout in seconds (10-60)
+  config.retries = 5     # Number of retries on failure (0-5)
+  config.logger = Logger.new(STDOUT)  # Custom logger
 end
 
-# Configuration is applied to all subsequent client instances
-client = SleeperApi.client
+# Configuration is applied to all subsequent client instances
+client = SleeperApi.client
 ```
 
 ## API Coverage
 
 ### Users
 
-Get user information and their leagues/drafts:
+Get user information and their leagues/drafts:
 
 ```ruby
 # Find a user by username
@@ -118,7 +118,7 @@ puts "Overall: #{summary[:total_wins]}-#{summary[:total_losses]}"
 
 ### Leagues
 
-Access league data, rosters, matchups, and transactions:
+Access league data, rosters, matchups, and transactions:
 
 ```ruby
 league = SleeperApi.client.league("123456")
@@ -180,7 +180,7 @@ matchup[:winner_owner]         # => "Team Beta"
 
 ### Drafts
 
-Access draft information, picks, and traded picks:
+Access draft information, picks, and traded picks:
 
 ```ruby
 # Get a specific draft
@@ -237,19 +237,19 @@ team_3_rounds = draft.team_picks[3] # Team 3's picks by round
 
 ### Players
 
-Access player data with automatic caching:
+Access player data with automatic caching:
 
 ```ruby
-# Get all players (cached for 24 hours)
-players = client.get_players
+# Get all players (cached for 24 hours)
+players = client.get_players
 
-# Find specific player
-player = client.get_player_by_id("1234")
-puts "#{player['first_name']} #{player['last_name']} - #{player['position']}"
+# Find specific player
+player = client.get_player_by_id("1234")
+puts "#{player['first_name']} #{player['last_name']} - #{player['position']}"
 
-# Get trending players
-trending_adds = client.trending_players(type: "add", limit: 10)
-trending_drops = client.trending_players(type: "drop", limit: 10)
+# Get trending players
+trending_adds = client.trending_players(type: "add", limit: 10)
+trending_drops = client.trending_players(type: "drop", limit: 10)
 ```
 
 ### Player Helper
@@ -313,103 +313,121 @@ rosters.each do |roster|
 end
 ```
 
-### Additional Endpoints
+### Additional Endpoints
 
 ```ruby
-# Get NFL state
-state = client.get_nfl_state
-puts "Current week: #{state['week']}"
+# Get NFL state
+state = client.get_nfl_state
+puts "Current week: #{state['week']}"
+
+# Per-player weekly stats and projections (undocumented endpoints).
+# Keyed by player id, plus TEAM_XXX keys for team-level rows.
+week_stats = client.stats(2025, week: 1)
+puts week_stats["4046"]["pts_ppr"]   # => 21.4
+puts week_stats["4046"]["off_snp"]   # raw counting stats too
+
+projected = client.projections(2026, week: 1)
+
+# Omit the week for season totals — a different resource, not a default.
+season_stats = client.stats(2025)
+
+# Nothing here 404s: an unplayed week, a week out of range and an unknown
+# season type all answer 200 with {}. And a projections call for a season
+# Sleeper has not projected still returns thousands of entries carrying only
+# an `adp_dd_ppr` sentinel — a row count is not evidence of a projection, so
+# filter on the field you actually want.
+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")
+# Get playoff brackets
+winners_bracket = client.get_league_playoff_bracket("league_id")
+losers_bracket = client.get_league_toilet_bowl("league_id")
 
-# Get league drafts
-league_drafts = client.get_league_drafts("league_id")
+# Get league drafts
+league_drafts = client.get_league_drafts("league_id")
 
-# Get traded picks
-traded_picks = client.get_league_traded_picks("league_id")
+# Get traded picks
+traded_picks = client.get_league_traded_picks("league_id")
 ```
 
-## Error Handling
+## Error Handling
 
 The gem provides comprehensive error handling:
 
 ```ruby
 begin
-  league = client.league("invalid_id")
-  # Process league data
-rescue SleeperApi::Error => e
-  puts "API Error: #{e.message}"
-rescue ArgumentError => e
-  puts "Invalid parameter: #{e.message}"
+  league = client.league("invalid_id")
+  # Process league data
+rescue SleeperApi::Error => e
+  puts "API Error: #{e.message}"
+rescue ArgumentError => e
+  puts "Invalid parameter: #{e.message}"
 end
 ```
 
 ### Error Types
 
-- SleeperApi::Error - API-related errors (404, 500, timeouts, etc.)
+- SleeperApi::Error - API-related errors (404, 500, timeouts, etc.)
 
-- ArgumentError - Invalid parameters passed to methods
+- ArgumentError - Invalid parameters passed to methods
 
 ## Performance Considerations
 
 ### Caching
 
-- Player data is cached for 24 hours to reduce API calls
+- Player data is cached for 24 hours to reduce API calls
 
-- League/User/Draft data is cached per instance
+- League/User/Draft data is cached per instance
 
-- Cache files are stored in the current working directory
+- Cache files are stored in the current working directory
 
-### Rate Limiting
+### Rate Limiting
 
-- Be mindful of Sleeper's rate limits: stay under 1000 API calls per minute
+- Be mindful of Sleeper's rate limits: stay under 1000 API calls per minute
 
-- The gem automatically handles timeouts and retries
+- The gem automatically handles timeouts and retries
 
 - Consider caching frequently accessed data in your application
 
 ### Memory Usage
 
-- Large datasets (like all players) are cached to disk
+- Large datasets (like all players) are cached to disk
 
-- League rosters and matchups are fetched lazily
+- League rosters and matchups are fetched lazily
 
-- Use no_data: true when initializing leagues if you don't need immediate data
+- Use no_data: true when initializing leagues if you don't need immediate data
 
 ## Testing
 
 The gem includes comprehensive tests:
 
 ```shellscript
-# Run all tests
-bundle exec rspec
-# Run with coverage
-bundle exec rspec --coverage
-# Run specific test file
-bundle exec rspec spec/sleeper_api/client_spec.rb
+# Run all tests
+bundle exec rspec
+# Run with coverage
+bundle exec rspec --coverage
+# Run specific test file
+bundle exec rspec spec/sleeper_api/client_spec.rb
 ```
 
 ### Setup
 
 ```shellscript
-git clone https://github.com/eruity1/sleeper_api.git
-cd sleeper_api
-bundle install
+git clone https://github.com/eruity1/sleeper_api.git
+cd sleeper_api
+bundle install
 ```
 
 ### Code Quality
 
 ```shellscript
-# Run all checks (tests + linting)
-bundle exec rake ci
+# Run all checks (tests + linting)
+bundle exec rake ci
 
-# Run RuboCop
-bundle exec rubocop
+# Run RuboCop
+bundle exec rubocop
 
-# Auto-fix RuboCop issues
-bundle exec rubocop -a
+# Auto-fix RuboCop issues
+bundle exec rubocop -a
 ```
 
 ### Contributing
@@ -426,24 +444,24 @@ bundle exec rubocop -a
 
 ### Development Dependencies
 
-- rspec - Testing framework
+- rspec - Testing framework
 
-- rubocop - Code style and quality
+- rubocop - Code style and quality
 
-- simplecov - Test coverage
+- simplecov - Test coverage
 
-- webmock - HTTP request mocking
+- webmock - HTTP request mocking
 
 ## Requirements
 
 - Ruby 2.6.0 or higher
 
-- No external dependencies (HTTParty is bundled)
+- No external dependencies (HTTParty is bundled)
 
 ## License
 
-The gem is available as open source under the terms of the MIT License.
+The gem is available as open source under the terms of the MIT License.
 
 ## Changelog
 
-See CHANGELOG.md for version history and updates.
+See CHANGELOG.md for version history and updates.

data/lib/sleeper_api/client.rb

@@ -1,5 +1,6 @@
 require "httparty"
 require "json"
+require "erb"
 
 module SleeperApi
   # HTTP client for Sleeper API requests.
@@ -15,7 +16,11 @@ module SleeperApi
     include Helpers
     include HTTParty
 
-    base_uri "https://api.sleeper.app/v1"
+    # The host only. The API version belongs in the paths because not every
+    # endpoint has one: /schedule is served from the root, and while base_uri
+    # carried "/v1" that endpoint was unreachable at any path a caller could
+    # pass to make_request.
+    base_uri "https://api.sleeper.app"
 
     # @param config [SleeperApi::Configuration] Client configuration
     def initialize(config)
@@ -57,7 +62,7 @@ module SleeperApi
     # @return [Hash] Raw user data
     # @see https://docs.sleeper.com/#user
     def get_user(identifier)
-      make_request("/user/#{identifier}")
+      make_request("/v1/user/#{identifier}")
     end
 
     # Get leagues for a user in a specific season.
@@ -68,7 +73,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("/user/#{user_id}/leagues/#{sport}/#{season}")
+      make_request("/v1/user/#{user_id}/leagues/#{sport}/#{season}")
     end
 
     # Get drafts for a user in a specific season.
@@ -79,7 +84,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("/user/#{user_id}/drafts/#{sport}/#{season}")
+      make_request("/v1/user/#{user_id}/drafts/#{sport}/#{season}")
     end
 
     # Fetch league details.
@@ -88,7 +93,7 @@ module SleeperApi
     # @return [Hash] League metadata
     # @see https://docs.sleeper.com/#get-a-specific-league
     def get_league(league_id)
-      make_request("/league/#{league_id}")
+      make_request("/v1/league/#{league_id}")
     end
 
     # Get all rosters in a league.
@@ -97,7 +102,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("/league/#{league_id}/rosters")
+      make_request("/v1/league/#{league_id}/rosters")
     end
 
     # Get all users in a league.
@@ -106,7 +111,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("/league/#{league_id}/users")
+      make_request("/v1/league/#{league_id}/users")
     end
 
     # Get matchups for a specific week.
@@ -116,7 +121,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("/league/#{league_id}/matchups/#{week}")
+      make_request("/v1/league/#{league_id}/matchups/#{week}")
     end
 
     # Get playoff winners bracket.
@@ -125,7 +130,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("/league/#{league_id}/winners_bracket")
+      make_request("/v1/league/#{league_id}/winners_bracket")
     end
 
     # Get toilet bowl (losers bracket).
@@ -134,7 +139,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("/league/#{league_id}/losers_bracket")
+      make_request("/v1/league/#{league_id}/losers_bracket")
     end
 
     # Get transactions for a specific week.
@@ -144,7 +149,7 @@ module SleeperApi
     # @return [Array<Hash>] Transaction data
     # @see https://docs.sleeper.com/#get-transactions
     def get_transactions(league_id, week)
-      make_request("/league/#{league_id}/transactions/#{week}")
+      make_request("/v1/league/#{league_id}/transactions/#{week}")
     end
 
     # Get league drafts.
@@ -153,7 +158,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("/league/#{league_id}/drafts")
+      make_request("/v1/league/#{league_id}/drafts")
     end
 
     # Get traded draft picks for a league.
@@ -162,7 +167,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("/league/#{league_id}/traded_picks")
+      make_request("/v1/league/#{league_id}/traded_picks")
     end
 
     # Fetch draft details.
@@ -171,7 +176,7 @@ module SleeperApi
     # @return [Hash] Draft metadata
     # @see https://docs.sleeper.com/#get-a-specific-draft
     def get_draft(draft_id)
-      make_request("/draft/#{draft_id}")
+      make_request("/v1/draft/#{draft_id}")
     end
 
     # Get draft picks.
@@ -180,7 +185,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("/draft/#{draft_id}/picks")
+      make_request("/v1/draft/#{draft_id}/picks")
     end
 
     # Get traded draft picks for a draft.
@@ -189,7 +194,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("/draft/#{draft_id}/traded_picks")
+      make_request("/v1/draft/#{draft_id}/traded_picks")
     end
 
     # Get NFL state (week, season status).
@@ -198,13 +203,84 @@ module SleeperApi
     # @return [Hash] State data
     # @see https://docs.sleeper.com/#get-nfl-state
     def get_nfl_state(sport = "nfl")
-      nfl_state = make_request("/state/#{sport}")
+      nfl_state = make_request("/v1/state/#{sport}")
       nfl_state.each_with_object({}) do |(k, v), result|
         key = k.is_a?(String) ? k.to_sym : k
         result[key] = v
       end
     end
 
+    # Get per-player statistics for one week, or for a whole season.
+    #
+    # Undocumented. Returns an object keyed by player id — plus `TEAM_XXX` keys
+    # for team-level rows — each holding raw counting stats (`rec`, `rush_yd`,
+    # `off_snp`, `rec_rz_tgt`…) alongside Sleeper's three canned point totals
+    # `pts_ppr` / `pts_half_ppr` / `pts_std`. 228 distinct fields were observed
+    # across one week of 2025.
+    #
+    # **Nothing here 404s.** An unplayed week, a week out of range, and an
+    # unrecognised season type all answer 200 with `{}`, so an empty result is
+    # a legitimate answer and is indistinguishable from a typo. Validate the
+    # arguments before you trust an empty body.
+    #
+    # Omitting `week` requests season totals, which is a different resource at
+    # a shorter path rather than a default of week 1.
+    #
+    # `pre` and `post` restart week numbering at 1, exactly as #schedule does,
+    # so rows from different season types must never be pooled.
+    #
+    # @param season [Integer, String] Season year, e.g. 2025
+    # @param week [Integer, String, nil] Week number, or nil for season totals
+    # @param season_type [String] "regular" (default), "pre", or "post"
+    # @param sport [String] Sport code (default: "nfl")
+    # @return [HTTParty::Response] Player id to stats mapping
+    def stats(season, week: nil, season_type: "regular", sport: "nfl")
+      make_request(weekly_path("stats", sport, season_type, season, week))
+    end
+
+    # Get per-player projections for one week, or for a whole season.
+    #
+    # Same shape and same caveats as #stats, with one of its own: for a season
+    # Sleeper has not projected, this still returns a full set of entries —
+    # 9,386 of them for 2030 — every one holding only `{"adp_dd_ppr" => 1000.0}`
+    # and no `pts_ppr` at all. **A row count is not evidence of a projection.**
+    # Filter on the field you actually want.
+    #
+    # `adp_dd_ppr` 1000.0 and `pos_rank_*` 999.0 are "unknown" sentinels rather
+    # than values.
+    #
+    # @param season [Integer, String] Season year, e.g. 2026
+    # @param week [Integer, String, nil] Week number, or nil for season totals
+    # @param season_type [String] "regular" (default), "pre", or "post"
+    # @param sport [String] Sport code (default: "nfl")
+    # @return [HTTParty::Response] Player id to projections mapping
+    def projections(season, week: nil, season_type: "regular", sport: "nfl")
+      make_request(weekly_path("projections", sport, season_type, season, week))
+    end
+
+    # Get a season's game schedule.
+    #
+    # Undocumented, and served from the host root rather than /v1 — hence the
+    # version living in the paths rather than in base_uri.
+    #
+    # Returns a flat array of games, each `{status, date, home, away, week,
+    # game_id}`. A team's bye week is the week it appears in no game; that
+    # derives exactly, but only within one season type — `pre` (weeks 1-3) and
+    # `post` (weeks 1-4) restart week numbering, so games from different season
+    # types must never be pooled.
+    #
+    # A season Sleeper has not scheduled yet answers 200 with an empty array
+    # rather than 404, so an empty result is a legitimate answer and not an
+    # error.
+    #
+    # @param season [Integer, String] Season year, e.g. 2026
+    # @param season_type [String] "regular" (default), "pre", or "post"
+    # @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}")
+    end
+
     # Get trending players.
     #
     # @param sport [String] Sport code (default: "nfl")
@@ -214,7 +290,7 @@ 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("/players/#{sport}/trending/#{type}?lookback_hours=#{lookback_hours}&limit=#{limit}")
+      make_request("/v1/players/#{sport}/trending/#{type}?lookback_hours=#{lookback_hours}&limit=#{limit}")
     end
 
     # Get all player data (cached for 24 hours).
@@ -225,7 +301,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("/players/#{sport}")
+      response = make_request("/v1/players/#{sport}")
       @players_cache = response.parsed_response
       @cache_timestamp = Time.now
 
@@ -244,6 +320,20 @@ 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) }
+
+      "/v1/#{escaped.join("/")}"
+    end
+
     # Make an HTTP request with retry logic and logging.
     #
     # @param path [String] API endpoint path

data/lib/sleeper_api/version.rb

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

metadata

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