sleeper_api 1.2.0 → 1.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 49f189b10709caa46c846f8733372cfd50d1dff0f66548aba5cb7ce0d32508f5
-  data.tar.gz: a0670835fa5f56541d041292b498722d0597a0599c724e95f9e3ed193151872c
+  metadata.gz: 6fd4df8d68adb46808ea692bbf8c715f2218a07a8f93212f5efddfe404741a30
+  data.tar.gz: cd3b09acb61407c634f04d76f165a1d2e0b7b840b3564117136ecc9343bc286c
 SHA512:
-  metadata.gz: dd18ff49145f5c1848857f7af5e9b15f02a8aac6f7940fe85517d333a213707f524d3f54d5d211ce94de28be9e955e6e366a3db66101ce329d39264f6eabf983
-  data.tar.gz: 0b254fa2078732333ee53f3f1074f3700c85c28733478234cd3c303b6b2698967889ad2db33d9802b1a93d00d7dee378387bfdb1d18403f55d0104daedc934b1
+  metadata.gz: a63777ce6255da38e963034bf9b016ca327d85dcaefc723ad508c85d58c9674939474ee00bd55b33b007e3268a043e81f8c175f06276cb77ae80b6a619871431
+  data.tar.gz: aed8fa84f731ddb1e8a01ef2cfb8987305826f665f338954e990fcb8c2c946c3d33f73edf510217ecee1923412bc6470a56931dbd9c60ba7369230c2c847627c

data/CHANGELOG.md

@@ -1,3 +1,25 @@
+## [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/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.
@@ -209,6 +210,54 @@ 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.
+    #
+    # 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.
+    #
+    # @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
@@ -271,6 +320,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/version.rb

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

metadata

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