sleeper_api 1.4.0 → 1.5.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c89b9383f35e517efd9ce353f9c14b1463f37375cc7dc4c30310c5c57370cdab
-  data.tar.gz: 336f7a25653bdbad75ec3094d150389fb5abba4244ef80ffbe97ce702e6a7ce9
+  metadata.gz: c1ac943353dae30f0fd6efa95f54f3287a85e116abd8408e843e980103557e29
+  data.tar.gz: 11569ff23125b08872ead08956c3395612a0092cf254a93450997fef069b2f19
 SHA512:
-  metadata.gz: 49c0c6f2843e597c53cf8c8c548a348f7c03255e6a38306a8e43190523f2ad485125145e9dc844b4f6b1ea326b74286e8a26cffa34c8c8522caeb70822477f0b
-  data.tar.gz: 45c2ebd6bc9b2e9ef3cd4f5f53c6635cd00f8199f9f5da7d0061d740c99f27aa94a1894ac682d072fb542e5c0498996ba799d1ee8c094689281188befdce33f3
+  metadata.gz: cf5797fea22593f99b428469ea2b99089f9f463f170c86bf7536c9a50398996d6a2edf2f06707b2ae6e3077ccce00d28c1bfe3ee2799943708f65a56090a536d
+  data.tar.gz: '08b1850e3dfb474167c1bc8df50700cab7669c7ac77c8d83ad6d757a92968ac345a82c5ecfc05b22b5238351d448782b48d297372acc33448dce0d1f4e9f1618'

data/CHANGELOG.md

@@ -1,3 +1,45 @@
+## [1.5.1] - 2026-09-25
+
+### Fixed
+
+- **A connection that never got an answer now raises `SleeperApi::Error`.**
+  Before, only non-2xx responses and timeouts did: no DNS (`SocketError`), a
+  refused, reset or unreachable connection (`SystemCallError`), a failed TLS
+  handshake (`OpenSSL::SSL::SSLError`) and a socket closed mid-response
+  (`EOFError`) escaped `make_request` as themselves. A caller rescuing
+  `SleeperApi::Error` for "Sleeper is down" missed the commonest outage of all —
+  a laptop waking before its network — and one consumer recorded 196 failed
+  imports that its retry policy never saw.
+
+  The message is `"Could not reach <path>: <original message>"`, naming the host
+  for a `WEB_HOST` call. **These are not retried** whatever `retries` is set to:
+  they fail at once, and the caller's backoff is the one that can wait long
+  enough to matter. `retries` still governs timeouts only.
+
+## [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

data/CLAUDE.md

@@ -28,7 +28,7 @@ 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"` — **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.
+  Every call funnels through the private `make_request`, which handles retry-on-timeout, logging, and converts non-2xx into `SleeperApi::Error` — and, since 1.5.1, **every connection failure too** (`CONNECTION_ERRORS`: `SocketError`, `SystemCallError`, `OpenSSL::SSL::SSLError`, `EOFError`), unretried, as `"Could not reach <path>: …"`. A consumer can rescue `SleeperApi::Error` alone and see every way a call fails. **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
@@ -46,6 +46,11 @@ Four layers, with a deliberate split between HTTP and modeling:
   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

data/lib/sleeper_api/client.rb

@@ -1,4 +1,5 @@
 require "httparty"
+require "openssl"
 require "json"
 require "erb"
 
@@ -28,6 +29,12 @@ module SleeperApi
     # because every other endpoint here lives on `.app`.
     WEB_HOST = "https://api.sleeper.com".freeze
 
+    # The request never got an answer (1.5.1): no DNS, a refused or reset
+    # connection, a failed TLS handshake, a socket closed mid-response. Before,
+    # these escaped as themselves, so a caller rescuing SleeperApi::Error for
+    # an outage missed the commonest one. Timeouts are handled separately.
+    CONNECTION_ERRORS = [SocketError, SystemCallError, OpenSSL::SSL::SSLError, EOFError].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.
@@ -340,6 +347,43 @@ module SleeperApi
       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
@@ -479,6 +523,11 @@ module SleeperApi
           @config.logger&.error("Request timed out for #{named} after #{retries} retries")
           raise SleeperApi::Error, "Request timed out after #{retries} retries"
         end
+      rescue *CONNECTION_ERRORS => e
+        # No retry: these fail at once, and the caller's backoff is the one
+        # that can wait long enough to matter.
+        @config.logger&.error("Could not reach #{named}: #{e.message}")
+        raise SleeperApi::Error, "Could not reach #{named}: #{e.message}"
       end
     end
   end

data/lib/sleeper_api/version.rb

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

metadata

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