sleeper_api 1.2.0 → 1.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 49f189b10709caa46c846f8733372cfd50d1dff0f66548aba5cb7ce0d32508f5
-  data.tar.gz: a0670835fa5f56541d041292b498722d0597a0599c724e95f9e3ed193151872c
+  metadata.gz: 3bd436fd0363716d6908e51d9137e89725230afb2c8a71479582a8894f12db57
+  data.tar.gz: b5933518c66d46edfc540ac261c0d473f62fc6c93f6cc03c9d7e426edebc9ed3
 SHA512:
-  metadata.gz: dd18ff49145f5c1848857f7af5e9b15f02a8aac6f7940fe85517d333a213707f524d3f54d5d211ce94de28be9e955e6e366a3db66101ce329d39264f6eabf983
-  data.tar.gz: 0b254fa2078732333ee53f3f1074f3700c85c28733478234cd3c303b6b2698967889ad2db33d9802b1a93d00d7dee378387bfdb1d18403f55d0104daedc934b1
+  metadata.gz: 7bdf8104296937896fdf11dcd71d12008e5801d9197552827293d734dd360032ac99dacaa5d7ff656e34ba2938f206bf8f864385d20b6f30230e12d819dc2039
+  data.tar.gz: 12eb88e92e6f27af1734b059b24313248ccf1888e6354437b391439920d0e3d2c5c00e263d7a957ad67cc791503978a92786b67b12eb6e871152a1b274e814c3

data/CHANGELOG.md

@@ -1,3 +1,91 @@
+## [1.3.1] - 2026-09-10
+
+### Fixed
+
+- **Every request raised `ArgumentError: unknown keyword: quirks_mode` under
+  `json` 3.0.** HTTParty 0.24.2 parses with `JSON.parse(body, quirks_mode:
+  true, allow_nan: true)`; json 3.0 removed that keyword. Total breakage rather
+  than a degradation, and it arrives through a transitive bump rather than
+  anything a consumer chose — this gem has no committed lockfile, so CI went
+  red with no commit in between. httparty 0.24.2 is the newest release and has
+  no fix.
+
+  `SleeperApi::JsonParser` subclasses `HTTParty::Parser` and overrides its
+  `json` method to drop the flag; `Client` parses with it. **Deliberately not a
+  `json < 3` pin in the gemspec**, which would fix the same crash by forbidding
+  every app that uses this gem from upgrading json at all, for a flag none of
+  them asked for.
+
+  `quirks_mode: true` allowed a bare scalar at the top level, which is not
+  academic here — Sleeper answers an unknown username with a literal `null`.
+  Both majors parse that correctly without it: `JSON.parse("null")` is `nil`
+  under 2.21.2 and under 3.0.2. The suite passes under both.
+
+### Documented
+
+Three facts measured against the live API on 2026-09-10, while NFL week 1 was
+half-played — one game finished, one being played, fourteen not yet started.
+No behaviour changed; all three are things a caller could previously only find
+out by being wrong first.
+
+- **`#schedule`'s `status` values are named: `pre_game`, `in_game`, `complete`,
+  `canceled`.** `in_game` was read off a live game; the other three come from
+  the published 2025 and 2026 schedules. It is the only per-game signal that a
+  game has been played — this payload has a `date` and no kickoff time, so a
+  caller can know a game is under way but never how far into it. **A week is
+  not one event**: week 1 of 2026 held three of those states at once, so
+  reasoning about "has the week started" from `date` alone gets it wrong for
+  everyone whose game is on Sunday. Treat the four as open and match with a
+  fallback — a postponement would be a fifth and none has been seen.
+
+- **`#projections` is a pre-game, whole-game projection that does not move
+  while the game is played.** Five players in one night's game held the same
+  `pts_ppr` to the decimal across six hours spanning its kickoff; a game that
+  had already finished still projected 19.69 for a player who scored 26.2, so
+  it does not settle onto the final either. This is the natural endpoint to
+  reach for when building anything live, and it cannot answer the question:
+  **there is no live projection here**, so nothing in this payload says whether
+  a player is on pace. A player on 8 of a projected 12 in the first quarter is
+  ahead of schedule, and this reports 12 all afternoon.
+
+- **`#stats` answers a week still being played with a partial set, and says
+  nothing about being partial.** Mid-week-1 it returned 301 rows with 42
+  carrying a `pts_ppr`. That is distinct from the already-documented empty
+  week: a caller treating "the week's stats" as the whole week gets a
+  half-filled answer for as long as the week is in progress, which for a
+  regular-season week is most of five days. `#schedule`'s per-game `status` is
+  the only thing that tells a missing row from a scoreless one.
+
+### Changed
+
+- `#schedule`'s spec fixture carries all four statuses rather than `pre_game`
+  alone, and an example pins that they pass through untranslated. The narrow
+  fixture was a shape live data produces only on a quiet Tuesday, and a fixture
+  narrower than the API is how a caller ends up written against a vocabulary of
+  one.
+
+## [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

data/CLAUDE.md

@@ -19,7 +19,7 @@ bundle exec rubocop -A     # autocorrect
 bin/console                # IRB with the gem loaded
 ```
 
-CI (`.github/workflows/ci.yml`) runs `bundle exec rake ci` on Ruby 3.2 only. The gemspec claims `required_ruby_version >= 2.6.0` and RuboCop targets 2.6, but nothing tests below 3.2 — treat 2.6 compatibility as unverified.
+CI (`.github/workflows/ci.yml`) runs `bundle exec rake ci` on Ruby 3.2 and 3.4. The gemspec claims `required_ruby_version >= 2.6.0` and RuboCop targets 2.6, but nothing tests below 3.2 — treat 2.6 compatibility as unverified.
 
 ## Architecture
 
@@ -44,6 +44,22 @@ Four layers, with a deliberate split between HTTP and modeling:
 
 **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.
 
+### Undocumented endpoints carry undocumented vocabularies
+
+Sleeper publishes no field reference, so every enum this gem passes through was
+found by looking. Four are known — `#schedule`'s game `status`, `Player`'s
+`status` and `injury_status`, and a roster's `lineup_position` — and **none of
+them is closed**. Match with a fallback rather than a whitelist, and never
+translate one into a vocabulary of this gem's own: the caller is the only one
+who knows what to do with a value nobody has seen.
+
+**When a value is measured, name it in the docstring and put the date and the
+circumstance next to it.** `in_game` shipped as an unnamed fallback in the
+consuming app for a day before anyone saw a live game; the fallback was right,
+and the thing that made it a fact rather than a guess was writing down that it
+was read at 21:13 on 2026-09-10 during a specific game. A vocabulary with no
+provenance is indistinguishable from one somebody assumed.
+
 ## Testing
 
 RSpec + WebMock, with `WebMock.disable_net_connect!` — **specs must never hit the network**. Stub with `stub_request` (see `client_spec.rb`) or `instance_double(SleeperApi::Client)` for resource-object specs (see `league_spec.rb`).
@@ -54,6 +70,24 @@ RSpec + WebMock, with `WebMock.disable_net_connect!` — **specs must never hit
 
 `lib/` is at 100% line coverage. Every bug found in this gem so far has been in a `League#format_*` method handling a field Sleeper omitted, exercised only by real data. When adding a formatter, write the nil-field case first.
 
+### There is no committed Gemfile.lock, so CI resolves fresh every run
+
+That is right for a library — a lockfile would hide exactly the incompatibility
+a consumer is going to hit — but it has a consequence worth naming: **a green
+run does not stay green.** A transitive release can turn CI red with no commit
+in between, and the first PR opened afterwards looks like the culprit.
+
+`json` 3.0 did this on 2026-09-11. It removed `quirks_mode`, which
+`httparty` 0.24.2 passes on every JSON parse, so 11 examples began raising
+`ArgumentError: unknown keyword: quirks_mode` — on a documentation-only PR that
+touched no code. Check whether `main` is red before reading a failure as the
+branch's fault; `main`'s last run can be weeks old.
+
+`SleeperApi::JsonParser` is the fix, and it is worth reading before reaching for
+a version pin: the gem overrides the one broken method rather than constraining
+`json` in the gemspec, because a constraint there would forbid every consuming
+app from upgrading `json` for a flag none of them asked for.
+
 ## Release
 
 Version lives in `lib/sleeper_api/version.rb`. Update `CHANGELOG.md`, then `bundle exec rake release` from a clean `main`, which builds to `pkg/`, tags, pushes the tag, and uploads to rubygems.

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.
@@ -21,6 +22,11 @@ module SleeperApi
     # pass to make_request.
     base_uri "https://api.sleeper.app"
 
+    # 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.
+    parser SleeperApi::JsonParser
+
     # @param config [SleeperApi::Configuration] Client configuration
     def initialize(config)
       @config = config
@@ -209,6 +215,76 @@ module SleeperApi
       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.
+    #
+    # **A week still being played answers with a partial set, and says nothing
+    # about being partial.** Mid-week-1 of 2026 this returned 301 rows with
+    # only 42 carrying a `pts_ppr` — the two teams whose games had finished or
+    # started. A caller that treats "the week's stats" as the whole week gets a
+    # half-filled answer for as long as the week is in progress, which for a
+    # regular-season week is most of five days. #schedule's per-game `status`
+    # is the only thing that can tell a missing row from a scoreless one.
+    #
+    # 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.
+    #
+    # ⚠️ **This is a pre-game, whole-game projection and it does not move while
+    # the game is played.** Measured on 2026-09-10 across six hours spanning a
+    # kickoff: five players in that night's game held the same `pts_ppr` before
+    # it started and while it was in progress, to the decimal. Checked again
+    # against a game that had already finished — the projection still read
+    # 19.69 for a player who had scored 26.2, so it does not settle onto the
+    # final either.
+    #
+    # That matters because it is the natural thing to reach for and the wrong
+    # one: **there is no live projection here**, so nothing in this payload can
+    # say whether a player is on pace. A player on 8 points of a projected 12
+    # in the first quarter is ahead of schedule, and this endpoint will report
+    # 12 all afternoon.
+    #
+    # @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
@@ -220,6 +296,26 @@ module SleeperApi
     # `post` (weeks 1-4) restart week numbering, so games from different season
     # types must never be pooled.
     #
+    # **`status` is `pre_game`, `in_game`, `complete` or `canceled`**, observed
+    # across the 2025 and 2026 regular seasons. `in_game` was read off a live
+    # game on 2026-09-10; the other three come from the published schedule. It
+    # is the only per-game signal of whether a game has been played — there is
+    # no kickoff time anywhere in this payload, only `date`, so a caller can
+    # know that a game is under way but never how far into it.
+    #
+    # **A week is not one event, and a caller reasoning from `date` alone will
+    # get that wrong.** Week 1 of 2026 held all three live states at the same
+    # moment: one `complete`, one `in_game`, fourteen `pre_game`.
+    #
+    # Treat the four as an open vocabulary. A postponement or a suspension
+    # would be a fifth value and none has been seen, so match with a fallback
+    # rather than a whitelist.
+    #
+    # **A team can carry two games in one week.** 2026 lists a canceled DAL/SEA
+    # in week 6 that was superseded rather than called off, and both teams play
+    # someone else that week. Order by status before picking one, or you will
+    # hand a team a bye it does not have.
+    #
     # 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.
@@ -271,6 +367,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/json_parser.rb

@@ -0,0 +1,40 @@
+require "httparty"
+require "json"
+
+module SleeperApi
+  # HTTParty's JSON parser, minus the one argument that stops it working.
+  #
+  # HTTParty 0.24.2 parses with `JSON.parse(body, quirks_mode: true,
+  # allow_nan: true)`. **json 3.0 removed `quirks_mode`**, so every response
+  # this gem parses raises `ArgumentError: unknown keyword: quirks_mode` the
+  # moment a consumer resolves json 3 — which is total breakage, not a
+  # degradation, and it arrives through a transitive bump nobody asked for.
+  # httparty 0.24.2 is the newest release and has no fix.
+  #
+  # **Dropping the option rather than pinning json is what keeps this the
+  # gem's problem instead of its consumers'.** A `json < 3` constraint in the
+  # gemspec would fix the same crash by forbidding every app that uses this
+  # gem from upgrading json at all, for a flag none of them asked for.
+  #
+  # `quirks_mode: true` allowed a bare scalar at the top level. That is not
+  # academic here — Sleeper answers an unknown username with a literal `null`.
+  # Both majors parse that correctly without the flag, checked on 2026-09-11:
+  # `JSON.parse("null")` is `nil` under json 2.21.2 and under 3.0.2. The flag
+  # has been doing nothing for this gem for some time.
+  #
+  # **@api private.** It is public only because `parser` has to name something
+  # a consumer's Ruby can resolve. Nothing here is a promise: it exists to be
+  # deleted the day httparty parses without the flag, and it is why 1.3.1 is a
+  # patch rather than a minor — a new constant that is not API does not earn
+  # one, and a fix for total breakage should reach a `~> 1.3.0` pin.
+  #
+  # A subclass rather than a `parser` lambda, because everything else in
+  # `HTTParty::Parser#parse` still applies — the blank-body guard, the format
+  # detection, the supported-format table. One method is wrong; one method is
+  # overridden.
+  class JsonParser < HTTParty::Parser
+    def json
+      JSON.parse(body, allow_nan: true)
+    end
+  end
+end

data/lib/sleeper_api/version.rb

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

data/lib/sleeper_api.rb

@@ -1,5 +1,6 @@
 require_relative "sleeper_api/version"
 require_relative "sleeper_api/helpers"
+require_relative "sleeper_api/json_parser"
 require_relative "sleeper_api/client"
 require_relative "sleeper_api/league"
 require_relative "sleeper_api/user"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: sleeper_api
 version: !ruby/object:Gem::Version
-  version: 1.2.0
+  version: 1.3.1
 platform: ruby
 authors:
 - Eruity1
@@ -148,6 +148,7 @@ files:
 - lib/sleeper_api/client.rb
 - lib/sleeper_api/draft.rb
 - lib/sleeper_api/helpers.rb
+- lib/sleeper_api/json_parser.rb
 - lib/sleeper_api/league.rb
 - lib/sleeper_api/user.rb
 - lib/sleeper_api/version.rb