sleeper_api 1.3.1 → 1.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3bd436fd0363716d6908e51d9137e89725230afb2c8a71479582a8894f12db57
-  data.tar.gz: b5933518c66d46edfc540ac261c0d473f62fc6c93f6cc03c9d7e426edebc9ed3
+  metadata.gz: 0fdd2ef6194210448caf049cdd89a37182bcd13205e45ea9543945c172d36fd4
+  data.tar.gz: 811a0991f5c863956c62c637971571aef98ccd379f9a3bff4b33ad1d28405290
 SHA512:
-  metadata.gz: 7bdf8104296937896fdf11dcd71d12008e5801d9197552827293d734dd360032ac99dacaa5d7ff656e34ba2938f206bf8f864385d20b6f30230e12d819dc2039
-  data.tar.gz: 12eb88e92e6f27af1734b059b24313248ccf1888e6354437b391439920d0e3d2c5c00e263d7a957ad67cc791503978a92786b67b12eb6e871152a1b274e814c3
+  metadata.gz: 16f575a6d822157d44b7d5aef135626371e0fb03ed8359c70abf82f49bf6d9ae1373ff7a5ee49cbf4c32986593eec23e838b08e70ce5306e29d5fb3df5229be4
+  data.tar.gz: b7b325b17bfd0c9d921ec16dbaa07fdcf6f277d242732db1f414d11f0c5846664ac300c2fc64f2401a3ef54402c112b8a9e89651f986ba3628a5fdcabc38f394

data/CHANGELOG.md

@@ -1,3 +1,69 @@
+## [1.5.0] - 2026-09-25
+
+### Added
+
+- **`Client#scores(season, week = nil)` — games with their kickoff times.** Each
+  game carries `start_time`, epoch milliseconds, which is **the only kickoff
+  time Sleeper publishes**: `#schedule` has a `date` and nothing finer. Measured
+  2026-09-25 against ATL @ GB, the previous night's Thursday game — its
+  `start_time` is 2026-09-25T00:15Z and agrees with `metadata.date_time` on
+  every game of the week.
+
+  ⚠️ **Also on `api.sleeper.com`**, like `#stats_with_context`, and with a
+  different shape: the season type is a **path segment**
+  (`/scores/nfl/regular/2026/3`), and the query-parameter form answers 200 with
+  nothing.
+
+  **Leave the week off for the whole season** — all 272 games of 2026 in one
+  ~610 KB call (~93 KB gzipped), against ~57 KB a week. `metadata` is the live
+  game (`quarter`, `time_remaining`, quarter scores, `is_in_progress`) plus the
+  TV channel, spread and forecast. Its `status` vocabulary (`scheduled`,
+  `closed`) differs from the top level's (`pre_game`, `complete`), and neither
+  value a live game carries has been read yet. Nothing 404s: week 19 and a
+  garbage season type answer `[]`.
+
+## [1.4.0] - 2026-09-14
+
+### Added
+
+- **`Client#stats_with_context(season, week)` — one week's stat lines carrying
+  the week they were played in.** Each row has the player's team *that week*,
+  their `opponent`, the `game_id` and the `date`, which the existing `#stats`
+  endpoint does not return at all.
+
+  ⚠️ **It is served from a different host: `api.sleeper.com`, not
+  `api.sleeper.app`.** Same sport and season in the path, no `/v1`, and the
+  season type is a query parameter rather than a segment. The `.app` endpoint
+  answers the *same stat lines with none of this metadata*, which is how it sat
+  unfound through four epics of stats work in the consuming app.
+
+  **What is genuinely per-week, measured** over the 2,275 players present in
+  both week 1 and week 16 of 2021: `team` differs on **164** of them and
+  `opponent` on **2,262**. ⚠️ **The nested `player` object is not history** — it
+  is the current catalog record stapled on, with `team` null inside it and
+  `injury_status` differing on 1 of the 204 rows carrying one across those
+  fifteen weeks. A 2021 row reporting "Questionable" is reporting that he is
+  questionable *now*.
+
+  ⚠️ **Pass a week.** Dropping it answers season totals — 8,251 rows for 2021 —
+  with `week` and `opponent` null on every one, so the season form carries none
+  of the context the endpoint exists for. Shares `#stats`' traps otherwise:
+  nothing 404s, and `pre`/`post` restart week numbering. An array of rows, not
+  a hash keyed by player id.
+
+### Changed
+
+- **`make_request` takes an optional `host:`**, which is how the second host is
+  reached. ⚠️ **Passing an absolute URL instead does not work**: HTTParty 0.24
+  raises `UnsafeURIError` for any URL whose host differs from the configured
+  `base_uri` — "this request could send credentials to an unintended server" —
+  so a second host has to arrive as its own per-request `base_uri`.
+
+  **Errors and logs now name the host whenever it is not the default.**
+  `/stats/nfl/2021/16` is a real path on both hosts and they return different
+  things, so a message quoting the path alone cannot say which one failed.
+  Messages for paths on `api.sleeper.app` are byte-for-byte what they were.
+
 ## [1.3.1] - 2026-09-10
 
 ### Fixed

data/CLAUDE.md

@@ -29,6 +29,32 @@ Four layers, with a deliberate split between HTTP and modeling:
 - **`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.
+
+  ⚠️ **There are two Sleeper hosts and v1.4.0 added the second.** `WEB_HOST`
+  (`https://api.sleeper.com`) is the one the web app uses, and it serves
+  **richer rows from same-looking paths**: `#stats_with_context` returns the
+  player's team *that week* and their opponent, while `#stats` on `.app`
+  returns the same stat lines with neither. Reached with `make_request(path,
+  host: WEB_HOST)` rather than by moving `base_uri`, because every other
+  endpoint lives on `.app`.
+
+  **Passing an absolute URL instead does not work**, and the failure is not
+  subtle: HTTParty 0.24 raises `UnsafeURIError` for any URL whose host differs
+  from the configured `base_uri` — *"this request could send credentials to an
+  unintended server"* — so a second host must arrive as its own per-request
+  `base_uri`. **The error and the log name the host whenever it is not the
+  default**, because `/stats/nfl/2021/16` is a real path on both and they
+  return different things; paths on `.app` quote exactly as they did before.
+
+  v1.5.0 added a second `WEB_HOST` endpoint, `#scores`, the only source of a
+  **kickoff time** — and its season type is a path segment where
+  `#stats_with_context` takes a query parameter. The host does not have one
+  convention; each path is measured on its own.
+
+  **When an endpoint almost has what you need, try the other host before
+  concluding the data does not exist.** Four epics of stats work in the
+  consuming app never surfaced the per-week team, because the documented-looking
+  path on `.app` answers 200 with a payload that simply omits it.
 - **`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/lib/sleeper_api/client.rb

@@ -22,6 +22,12 @@ module SleeperApi
     # pass to make_request.
     base_uri "https://api.sleeper.app"
 
+    # ⚠️ **The other Sleeper host.** The web app talks to `api.sleeper.com`,
+    # which serves *richer rows from same-looking paths* — see
+    # #stats_with_context. Reached per-request rather than by moving base_uri,
+    # because every other endpoint here lives on `.app`.
+    WEB_HOST = "https://api.sleeper.com".freeze
+
     # 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.
@@ -285,6 +291,92 @@ module SleeperApi
       make_request(weekly_path("projections", sport, season_type, season, week))
     end
 
+    # Get one week's stat lines **with the context of the week they were played
+    # in** — the player's team *that week*, their opponent, the game and its
+    # date. Probed 2026-09-08, re-probed 2026-09-14.
+    #
+    # ⚠️ **A different host: `api.sleeper.com`, not `api.sleeper.app`.** The
+    # `.app` endpoint #stats calls returns the *same stat lines with none of
+    # this metadata*, which is why it can be there for years without anyone
+    # finding it. Same sport and season in the path, but no `/v1` and the
+    # season type is a query parameter rather than a segment.
+    #
+    # **What is genuinely per-week, measured** over the 2,275 players present in
+    # both week 1 and week 16 of 2021: `team` differs on **164** of them (a
+    # midseason trade is a real change of team) and `opponent` on **2,262**. So
+    # both are history rather than today's catalog.
+    #
+    # ⚠️ **The nested `player` object is NOT history.** It is the current
+    # catalog record stapled on — `player.team` is null inside it, and
+    # `injury_status` differed on 1 of the 204 rows carrying one across fifteen
+    # weeks, which is the signature of a field that does not vary by week at
+    # all. A 2021 row reporting "Questionable" is reporting that he is
+    # questionable *now*. The top-level `status` is null on every row seen.
+    #
+    # ⚠️ **Pass a week.** Dropping it answers season totals — 8,251 rows for
+    # 2021 — with `week` and `opponent` null on every one, so the season form
+    # carries none of the context this endpoint exists for.
+    #
+    # Shares #stats' traps: nothing 404s (an unplayed 2026 week, a week out of
+    # range, a season before Sleeper's history and a garbage season type all
+    # answer `200` with `[]`), and `pre`/`post` restart week numbering — 2021
+    # `post` week 1 is the wildcard round, played 2022-01-15.
+    #
+    # **An array, not a hash.** #stats keys by player id; this returns a list of
+    # rows each carrying `player_id`, so a caller indexing it must build its own
+    # map. `/projections/nfl/{season}/{week}` on the same host answers the same
+    # shape (9,420 rows for 2021 week 16) and has no wrapper here yet.
+    #
+    # @param season [Integer, String] Season year, e.g. 2021
+    # @param week [Integer, String] Week number — required, see above
+    # @param season_type [String] "regular" (default), "pre", or "post"
+    # @param sport [String] Sport code (default: "nfl")
+    # @return [HTTParty::Response] Array of stat lines, each with `team`,
+    #   `opponent`, `game_id`, `date`, `week`, `season` and a nested `player`
+    def stats_with_context(season, week, season_type: "regular", sport: "nfl")
+      segments = [sport, season, week].map { |segment| ERB::Util.url_encode(segment.to_s) }
+      query = ERB::Util.url_encode(season_type.to_s)
+
+      make_request("/stats/#{segments.join("/")}?season_type=#{query}", host: WEB_HOST)
+    end
+
+    # Get games with their kickoff times — undocumented, on the web host.
+    #
+    # **The only kickoff time Sleeper publishes.** #schedule carries a `date`
+    # and nothing finer; each game here has `start_time`, epoch milliseconds —
+    # 2026's Thursday opener of week 3, ATL @ GB, is 1790295300000, which is
+    # 2026-09-25T00:15Z and agrees with `metadata.date_time` on every game.
+    # Measured 2026-09-25, the morning after that game.
+    #
+    # `metadata` is the live game: `quarter`, `time_remaining`, the score by
+    # quarter, `is_in_progress`, `is_over`, plus the TV `channel`, the spread and
+    # a forecast. Its `status` is a different vocabulary from the top level's —
+    # `scheduled`/`closed` against `pre_game`/`complete` — and neither value a
+    # live game carries has been read here yet. Match with a fallback.
+    #
+    # **Leave the week off for the whole season** — all 272 games of 2026 in one
+    # call, ~610 KB (~93 KB gzipped), against ~57 KB a week. Unlike
+    # #stats_with_context, the season form is useful.
+    #
+    # The season type is a **path segment**, not a query parameter —
+    # `/scores/nfl/2026/3?season_type=regular` answers 200 with nothing. Shares
+    # the host's traps: nothing 404s (week 19, a garbage season type all answer
+    # `200` with `[]`), and `pre`/`post` restart week numbering.
+    #
+    # @param season [Integer, String] Season year, e.g. 2026
+    # @param week [Integer, String, nil] Week number; nil for the whole season
+    # @param season_type [String] "regular" (default), "pre", or "post"
+    # @param sport [String] Sport code (default: "nfl")
+    # @return [HTTParty::Response] Array of games, each with `game_id`, `week`,
+    #   `status`, `start_time`, `date` and a nested `metadata`
+    def scores(season, week = nil, season_type: "regular", sport: "nfl")
+      segments = [sport, season_type, season, week].compact.map do |segment|
+        ERB::Util.url_encode(segment.to_s)
+      end
+
+      make_request("/scores/#{segments.join("/")}", host: WEB_HOST)
+    end
+
     # Get a season's game schedule.
     #
     # Undocumented, and served from the host root rather than /v1 — hence the
@@ -383,29 +475,45 @@ module SleeperApi
 
     # Make an HTTP request with retry logic and logging.
     #
+    # ⚠️ **`host:` cannot be done by passing an absolute URL instead.** HTTParty
+    # 0.24 raises `UnsafeURIError` for any URL whose host differs from the
+    # configured `base_uri` — "this request could send credentials to an
+    # unintended server" — so a second host has to arrive as its own
+    # `base_uri`, which is a per-request option it supports.
+    #
+    # **The error and the log name the host whenever it is not the default.**
+    # `/stats/nfl/2021/16` is a real path on both hosts and they return
+    # different things, so a message quoting the path alone cannot say which
+    # one failed. Paths on the default host quote exactly as they always have.
+    #
     # @param path [String] API endpoint path
+    # @param host [String, nil] a different host, e.g. WEB_HOST
     # @return [HTTParty::Response]
     # @raise [SleeperApi::Error] On HTTP errors or timeouts
-    def make_request(path)
-      @config.logger&.info("Making request to #{self.class.base_uri}#{path}")
+    def make_request(path, host: nil)
+      named = host ? "#{host}#{path}" : path
+      options = { timeout: @config.timeout }
+      options[:base_uri] = host if host
+
+      @config.logger&.info("Making request to #{host || self.class.base_uri}#{path}")
       retries = 0
       begin
-        response = self.class.get(path, timeout: @config.timeout)
+        response = self.class.get(path, **options)
         if response.success?
-          @config.logger&.info("Successful response for #{path}")
+          @config.logger&.info("Successful response for #{named}")
           response
         else
-          @config.logger&.error("Failed to fetch #{path}: #{response.code}")
-          raise SleeperApi::Error, "Failed to fetch #{path}: #{response.code}"
+          @config.logger&.error("Failed to fetch #{named}: #{response.code}")
+          raise SleeperApi::Error, "Failed to fetch #{named}: #{response.code}"
         end
       rescue Net::OpenTimeout, Net::ReadTimeout => e
         retries += 1
         if retries <= @config.retries
-          @config.logger&.warn("Retrying #{path} (attempt #{retries}/#{@config.retries}) due to #{e}")
+          @config.logger&.warn("Retrying #{named} (attempt #{retries}/#{@config.retries}) due to #{e}")
           sleep(1)
           retry
         else
-          @config.logger&.error("Request timed out for #{path} after #{retries} retries")
+          @config.logger&.error("Request timed out for #{named} after #{retries} retries")
           raise SleeperApi::Error, "Request timed out after #{retries} retries"
         end
       end

data/lib/sleeper_api/version.rb

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

metadata

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