sleeper_api 1.3.0 → 1.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6fd4df8d68adb46808ea692bbf8c715f2218a07a8f93212f5efddfe404741a30
-  data.tar.gz: cd3b09acb61407c634f04d76f165a1d2e0b7b840b3564117136ecc9343bc286c
+  metadata.gz: 3bd436fd0363716d6908e51d9137e89725230afb2c8a71479582a8894f12db57
+  data.tar.gz: b5933518c66d46edfc540ac261c0d473f62fc6c93f6cc03c9d7e426edebc9ed3
 SHA512:
-  metadata.gz: a63777ce6255da38e963034bf9b016ca327d85dcaefc723ad508c85d58c9674939474ee00bd55b33b007e3268a043e81f8c175f06276cb77ae80b6a619871431
-  data.tar.gz: aed8fa84f731ddb1e8a01ef2cfb8987305826f665f338954e990fcb8c2c946c3d33f73edf510217ecee1923412bc6470a56931dbd9c60ba7369230c2c847627c
+  metadata.gz: 7bdf8104296937896fdf11dcd71d12008e5801d9197552827293d734dd360032ac99dacaa5d7ff656e34ba2938f206bf8f864385d20b6f30230e12d819dc2039
+  data.tar.gz: 12eb88e92e6f27af1734b059b24313248ccf1888e6354437b391439920d0e3d2c5c00e263d7a957ad67cc791503978a92786b67b12eb6e871152a1b274e814c3

data/CHANGELOG.md

@@ -1,3 +1,69 @@
+## [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

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/lib/sleeper_api/client.rb

@@ -22,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
@@ -223,6 +228,14 @@ module SleeperApi
     # 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.
     #
@@ -249,6 +262,20 @@ module SleeperApi
     # `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"
@@ -269,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.

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.3.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.3.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