sleeper_api 1.0.0 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7343fb5de26fd02795df2ef4c91322eec909026cb792e52fcb24299c83cff901
-  data.tar.gz: 5036b7dfa94981abe61d3204e6a1d265164e846961c1450eb92b03614a942ec9
+  metadata.gz: 8e64262b5b1ec981daba5a470cdaed3857b5b334b4b5b974b36369bb71d10fe6
+  data.tar.gz: 6e292f1ff2de695f2385736316d1d0329373cdfb8d944d399e42ffcda7014d2d
 SHA512:
-  metadata.gz: ca60a9cfad9925c86afd87b1f2e219405dad22d80849130ee9b70c7b71321903e9cc27cb539ed9feb4b900b73b42cfcd6c0a284e3b8009b9578a900f7888f052
-  data.tar.gz: 5559a1bffa0cbe150be4aff3789cc4ecc298e568c9c5e3f518293921efd0965b50ed6c440a56c98683ec62fed12707af16f51cef30c849ead3b34e76beeca8c2
+  metadata.gz: fcad44e534d0f99daa36897d56b228e432e5374d9e829915fed7cc71612588b9576a96147cedb07cc658cd0a590769161ccd74ef82f48ed7d1b0c2d7dc210e88
+  data.tar.gz: ca0a00e724c6b35182add239a7a80c9b8129c3a1af2805f216f21b50971842fa968a1c902ab97686819c676390ef89e3fa0fb4635013d9f3f8f7c5aec565d7e6

data/.github/workflows/ci.yml

@@ -12,7 +12,7 @@ jobs:
 
     strategy:
       matrix:
-        ruby-version: [3.2]
+        ruby-version: ["3.2", "3.4"]
 
     steps:
       - uses: actions/checkout@v4

data/CHANGELOG.md

@@ -1,3 +1,29 @@
+## [1.1.0] - 2026-08-22
+
+### Fixed
+
+- `League#rosters` truncated every score. Sleeper splits a score across two integer fields — `fpts: 1617` with `fpts_decimal: 78` is 1617.78 — and `total_points` read `fpts` alone. The loss was invisible because what remained was still a plausible score, and no fixture carried a `fpts_decimal` to catch it. **This changes `total_points` from an Integer to a Float** for any roster whose score has a fractional part.
+- `League#rosters` returned `co_owners: nil` for every roster, always. It read `roster["co_owner"]`, singular; no Sleeper payload has ever contained that key. Now reads the plural spelling, and still yields `nil` when the field is absent — Sleeper's documented roster object does not include co-owners, though the published docs are partial (the league `settings` object is rendered only as `{ settings object }`).
+
+### Added
+
+- `League#rosters` now returns `points_against`, combining `fpts_against` with `fpts_against_decimal` the same way. Previously reachable only by digging into the raw `settings` hash that passes through wholesale.
+
+## [1.0.1] - 2026-08-12
+
+### Fixed
+
+- `User#leagues` returned `nil` on every call after the first, because the memoization guard was the method's return value
+- `League#users` raised `NoMethodError` when any league member had no `metadata` (Sleeper omits it for users who never set a team name), which also broke `#playoff_bracket` and `#toilet_bowl`
+- `Client#make_request` raised `NameError: undefined local variable 'config'` when a retry fired with a logger configured — the retry path was only reachable with logging on, so it never surfaced in tests
+- `League#matchups_by_week` returned a literal `nil` element for any roster with no `matchup_id` (bye weeks / unscheduled rosters)
+- `League#matchups_by_week` raised `NoMethodError` when a matchup roster had no `players` or no `points`
+- `League#users` memoization checked an undefined `@fetch_users` ivar instead of `@league_users`
+
+### Changed
+
+- SimpleCov now starts before the library is required. It previously started after, so no lines were instrumented and the `minimum_coverage 90` gate passed vacuously on 0/0 lines. Real coverage at the time was 72%; `lib/` is now at 100%.
+
 ## [1.0.0] - 2025-01-17
 
 ### Added

data/CLAUDE.md

@@ -0,0 +1,63 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## What this is
+
+`sleeper_api` — a published Ruby gem (rubygems.org, v1.0.0) wrapping [Sleeper's fantasy football API](https://docs.sleeper.com/). Read-only public API: no auth, no API key, no write endpoints.
+
+Consumed by the `fantasy-football-manager` project in the sibling directory, which is the primary real-world user.
+
+## Commands
+
+```bash
+bin/setup                  # install deps
+bundle exec rake ci        # rubocop + rspec — this is what CI runs
+bundle exec rspec
+bundle exec rspec spec/sleeper_api/league_spec.rb:42   # single example
+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.
+
+## Architecture
+
+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.
+- **`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`.
+
+### Conventions that matter
+
+**Raw data is string-keyed; formatted output is symbol-keyed.** The `ATTRIBUTES` readers (defined via `define_method` on each class) return raw API values straight off the string-keyed hash. The `format_*` private methods return symbol-keyed hashes. Don't mix the two — inside `format_rosters` you're indexing `roster["starters"]` but returning `starters:`.
+
+**`Client` returns `HTTParty::Response`, not Hash.** `make_request` returns the response object, which delegates `[]` and `dig` to `parsed_response`, so it usually behaves like a Hash. `get_players` is the exception — it explicitly stores `.parsed_response`. If you add code that needs a real Hash (e.g. `.merge`, `.transform_keys`), call `.parsed_response` yourself; `fetch_playoff_bracket` already does.
+
+**Eager construction.** `League.new` and `User.new` hit the network in the constructor. `League.new(id, client, no_data: true)` skips it — used by `User#rosters` to avoid N redundant league fetches. Be aware `no_data: true` leaves `@league_data` nil, so `format_rosters`' `remaining_faab` falls back to `0 - waiver_budget_used`.
+
+**Guard nil defensively.** Sleeper omits fields freely — users without `metadata`, rosters without `players`, matchups without `points`. Real leagues hit these; the spec fixtures often don't. Use `&.dig` rather than `[]` on anything nested off an API response.
+
+**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.
+
+## 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`).
+
+`spec_helper.rb` resets `SleeperApi`'s `@client` and `@configuration` ivars before each example, since both are module-level memoized state that would otherwise leak between tests.
+
+**SimpleCov must start before `require "sleeper_api"`.** It previously started after, which meant zero lines were instrumented and `minimum_coverage 90` passed vacuously on 0/0. Don't reorder those requires back — it silently disables the gate rather than failing loudly.
+
+`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.
+
+## 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.
+
+**The API key needs the `push_rubygem` scope.** `gem signin` defaults to `index_rubygems` only — read access — and answering `n` to "Do you want to customise scopes?" produces a key that fails the upload with `This API key cannot perform the specified action on this gem`. Answer `y` and enable `push_rubygem`, or edit the key's scopes at https://rubygems.org/profile/api_keys. Credentials land in `~/.local/share/gem/credentials` (the XDG path, not `~/.gem/credentials`).
+
+**`rake release` is not atomic.** It tags and pushes the tag *before* uploading, so a failed upload leaves the tag published and the gem unreleased. Recovering means `gem push pkg/sleeper_api-<version>.gem` on the existing artifact — re-running `rake release` fails on the tag that already exists.
+
+Consumers do not get a fix until it is published *and* they bump their lockfile.

data/README.md

@@ -1,5 +1,7 @@
 # SleeperApi
 
+[![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.
 
 ## Features

data/lib/sleeper_api/client.rb

@@ -264,7 +264,7 @@ module SleeperApi
       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 #{path} (attempt #{retries}/#{@config.retries}) due to #{e}")
           sleep(1)
           retry
         else

data/lib/sleeper_api/league.rb

@@ -134,7 +134,7 @@ module SleeperApi
     #     puts "#{user[:display_name]} #{role}"
     #   end
     def users
-      fetch_users unless @fetch_users
+      fetch_users unless @league_users
       format_users
     end
 
@@ -281,7 +281,8 @@ module SleeperApi
           injured_reserve: roster["reserve"] || [],
           taxi: roster["taxi"] || [],
           bench: (roster["players"] || []) - (roster["starters"] || []) - (roster["reserve"] || []) - (roster["taxi"] || []),
-          total_points: roster_settings&.dig("fpts"),
+          total_points: combined_points(roster_settings, "fpts"),
+          points_against: combined_points(roster_settings, "fpts_against"),
           wins: roster_settings&.dig("wins"),
           ties: roster_settings&.dig("ties"),
           losses: roster_settings&.dig("losses"),
@@ -290,7 +291,7 @@ module SleeperApi
           faab_used: roster_settings&.dig("waiver_budget_used"),
           waiver_position: roster_settings&.dig("waiver_position"),
           streak: roster_metadata&.dig("streak"),
-          co_owners: roster["co_owner"],
+          co_owners: roster["co_owners"],
           keepers: roster["keepers"],
           players_map: roster["player_map"],
           players: roster["players"],
@@ -300,6 +301,21 @@ module SleeperApi
       end
     end
 
+    # Sleeper splits a score across two integer fields: fpts 1617 with
+    # fpts_decimal 78 is 1617.78. Reading fpts alone truncates every score in
+    # the league, and the loss is invisible because what remains is still a
+    # plausible number.
+    #
+    # Recombined as (whole * 100 + fraction) / 100.0 rather than
+    # whole + fraction / 100.0 — the latter accumulates two rounding steps and
+    # lands on 1617.7800000000002.
+    def combined_points(settings, key)
+      whole = settings&.dig(key)
+      return nil if whole.nil?
+
+      ((whole * 100) + (settings["#{key}_decimal"] || 0)) / 100.0
+    end
+
     def format_matchups(week)
       week_matchups = @matchups[week] || []
       return [] if week_matchups.empty?
@@ -310,14 +326,14 @@ module SleeperApi
         {
           matchup_id: matchup_id,
           rosters: matchup_entries.map do |roster|
-            starters = roster["starters"]
+            starters = roster["starters"] || []
 
-            bench = roster["players"] - starters
+            bench = (roster["players"] || []) - starters
             {
               roster_id: roster["roster_id"],
               points: roster["points"],
               custom_points: roster["custom_points"],
-              total_points: roster["points"] + (roster["custom_points"] || 0),
+              total_points: (roster["points"] || 0) + (roster["custom_points"] || 0),
               starters: starters,
               bench: bench,
               starter_points: (starters || []).map do |starter_id|
@@ -329,7 +345,7 @@ module SleeperApi
             }
           end
         }
-      end
+      end.compact
     end
 
     def format_users
@@ -342,7 +358,7 @@ module SleeperApi
           username: user["username"],
           display_name: user["display_name"],
           avatar_id: user["avatar"],
-          team_name: user_metadata["team_name"],
+          team_name: user_metadata&.dig("team_name"),
           commissioner: user["is_owner"],
           is_bot: user["is_bot"],
           metadata: user_metadata.is_a?(Hash) ? user_metadata.transform_keys(&:to_sym) : user_metadata,

data/lib/sleeper_api/user.rb

@@ -50,7 +50,8 @@ module SleeperApi
     def leagues(season = Time.now.year)
       raise ArgumentError, "season must be a valid year" unless season.is_a?(Integer)
 
-      fetch_leagues(season) unless @leagues
+      fetch_leagues(season)
+      @leagues
     end
 
     # Get all rosters for this user across all leagues in a season.

data/lib/sleeper_api/version.rb

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

metadata

@@ -1,14 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: sleeper_api
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.1.0
 platform: ruby
 authors:
 - Eruity1
-autorequire:
 bindir: exe
 cert_chain: []
-date: 2025-09-23 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: httparty
@@ -138,6 +137,7 @@ files:
 - ".rubocop.yml"
 - ".rubocop_todo.yml"
 - CHANGELOG.md
+- CLAUDE.md
 - Gemfile
 - LICENSE.txt
 - README.md
@@ -162,7 +162,6 @@ metadata:
   source_code_uri: https://github.com/eruity1/sleeper_api
   changelog_uri: https://github.com/eruity1/sleeper_api/blob/main/CHANGELOG.md
   documentation_uri: https://github.com/eruity1/sleeper_api/blob/main/README.md
-post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -177,8 +176,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.4.10
-signing_key:
+rubygems_version: 3.6.7
 specification_version: 4
 summary: Comprehensive Ruby wrapper for the Sleeper's fantasy sports API
 test_files: []