sleeper_api 1.0.0

data/lib/sleeper_api/client.rb

@@ -0,0 +1,277 @@
+require "httparty"
+require "json"
+
+module SleeperApi
+  # HTTP client for Sleeper API requests.
+  #
+  # Handles all low-level HTTP calls, caching, retries, and error handling.
+  # Use via {SleeperApi.client} or create directly.
+  #
+  # @example
+  #   client = SleeperApi::Client.new(config)
+  #   league = client.league("123456")
+  #   user = client.user("username")
+  class Client
+    include Helpers
+    include HTTParty
+
+    base_uri "https://api.sleeper.app/v1"
+
+    # @param config [SleeperApi::Configuration] Client configuration
+    def initialize(config)
+      @config = config
+      @players_cache = nil
+      @cache_timestamp = nil
+    end
+
+    # Create a new {SleeperApi::League} instance.
+    #
+    # @param league_id [String] League identifier
+    # @return [SleeperApi::League]
+    # @see https://docs.sleeper.com/#leagues
+    def league(league_id)
+      League.new(league_id, self)
+    end
+
+    # Create a new {SleeperApi::User} instance.
+    #
+    # @param identifier [String] Username or user ID
+    # @return [SleeperApi::User]
+    # @see https://docs.sleeper.com/#user
+    def user(identifier)
+      User.new(identifier, self)
+    end
+
+    # Create a new {SleeperApi::Draft} instance.
+    #
+    # @param draft_id [String] Draft identifier
+    # @return [SleeperApi::Draft]
+    # @see https://docs.sleeper.com/#drafts
+    def draft(draft_id)
+      Draft.new(draft_id, self)
+    end
+
+    # Fetch user data by identifier.
+    #
+    # @param identifier [String] Username or user ID
+    # @return [Hash] Raw user data
+    # @see https://docs.sleeper.com/#user
+    def get_user(identifier)
+      make_request("/user/#{identifier}")
+    end
+
+    # Get leagues for a user in a specific season.
+    #
+    # @param user_id [String] User ID
+    # @param sport [String] Sport code (default: "nfl")
+    # @param season [Integer] Season year (default: current year)
+    # @return [Array<Hash>] League data
+    # @see https://docs.sleeper.com/#get-all-leagues-for-user
+    def get_user_leagues(user_id, sport: "nfl", season: Time.now.year)
+      make_request("/user/#{user_id}/leagues/#{sport}/#{season}")
+    end
+
+    # Get drafts for a user in a specific season.
+    #
+    # @param user_id [String] User ID
+    # @param sport [String] Sport code (default: "nfl")
+    # @param season [Integer] Season year (default: current year)
+    # @return [Array<Hash>] Draft data
+    # @see https://docs.sleeper.com/#get-all-drafts-for-user
+    def get_user_drafts(user_id, sport: "nfl", season: Time.now.year)
+      make_request("/user/#{user_id}/drafts/#{sport}/#{season}")
+    end
+
+    # Fetch league details.
+    #
+    # @param league_id [String] League ID
+    # @return [Hash] League metadata
+    # @see https://docs.sleeper.com/#get-a-specific-league
+    def get_league(league_id)
+      make_request("/league/#{league_id}")
+    end
+
+    # Get all rosters in a league.
+    #
+    # @param league_id [String] League ID
+    # @return [Array<Hash>] Roster data
+    # @see https://docs.sleeper.com/#getting-rosters-in-a-league
+    def get_league_rosters(league_id)
+      make_request("/league/#{league_id}/rosters")
+    end
+
+    # Get all users in a league.
+    #
+    # @param league_id [String, Integer] League ID
+    # @return [Array<Hash>] User data
+    # @see https://docs.sleeper.com/#getting-users-in-a-league
+    def get_league_users(league_id)
+      make_request("/league/#{league_id}/users")
+    end
+
+    # Get matchups for a specific week.
+    #
+    # @param league_id [String, Integer] League ID
+    # @param week [Integer] Week number (1-17)
+    # @return [Array<Hash>] Matchup data
+    # @see https://docs.sleeper.com/#getting-matchups-in-a-league
+    def get_league_matchups(league_id, week)
+      make_request("/league/#{league_id}/matchups/#{week}")
+    end
+
+    # Get playoff winners bracket.
+    #
+    # @param league_id [String, Integer] League ID
+    # @return [Array<Hash>] Bracket matchups
+    # @see https://docs.sleeper.com/#getting-the-playoff-bracket
+    def get_playoff_bracket(league_id)
+      make_request("/league/#{league_id}/winners_bracket")
+    end
+
+    # Get toilet bowl (losers bracket).
+    #
+    # @param league_id [String, Integer] League ID
+    # @return [Array<Hash>] Bracket matchups
+    # @see https://docs.sleeper.com/#getting-the-playoff-bracket
+    def get_toilet_bowl(league_id)
+      make_request("/league/#{league_id}/losers_bracket")
+    end
+
+    # Get transactions for a specific week.
+    #
+    # @param league_id [String, Integer] League ID
+    # @param week [Integer] Week number
+    # @return [Array<Hash>] Transaction data
+    # @see https://docs.sleeper.com/#get-transactions
+    def get_transactions(league_id, week)
+      make_request("/league/#{league_id}/transactions/#{week}")
+    end
+
+    # Get league drafts.
+    #
+    # @param league_id [String, Integer] League ID
+    # @return [Array<Hash>] Draft data
+    # @see https://docs.sleeper.com/#get-all-drafts-for-a-league
+    def get_league_drafts(league_id)
+      make_request("/league/#{league_id}/drafts")
+    end
+
+    # Get traded draft picks for a league.
+    #
+    # @param league_id [String, Integer] League ID
+    # @return [Array<Hash>] Traded picks
+    # @see https://docs.sleeper.com/#get-traded-picks-in-a-draft
+    def get_league_traded_picks(league_id)
+      make_request("/league/#{league_id}/traded_picks")
+    end
+
+    # Fetch draft details.
+    #
+    # @param draft_id [String, Integer] Draft ID
+    # @return [Hash] Draft metadata
+    # @see https://docs.sleeper.com/#get-a-specific-draft
+    def get_draft(draft_id)
+      make_request("/draft/#{draft_id}")
+    end
+
+    # Get draft picks.
+    #
+    # @param draft_id [String, Integer] Draft ID
+    # @return [Array<Hash>] Pick data
+    # @see https://docs.sleeper.com/#get-all-picks-in-a-draft
+    def get_draft_picks(draft_id)
+      make_request("/draft/#{draft_id}/picks")
+    end
+
+    # Get traded draft picks for a draft.
+    #
+    # @param draft_id [String, Integer] Draft ID
+    # @return [Array<Hash>] Traded picks
+    # @see https://docs.sleeper.com/#get-traded-picks-in-a-draft
+    def get_draft_traded_picks(draft_id)
+      make_request("/draft/#{draft_id}/traded_picks")
+    end
+
+    # Get NFL state (week, season status).
+    #
+    # @param sport [String] Sport code (default: "nfl")
+    # @return [Hash] State data
+    # @see https://docs.sleeper.com/#get-nfl-state
+    def get_nfl_state(sport = "nfl")
+      nfl_state = make_request("/state/#{sport}")
+      nfl_state.each_with_object({}) do |(k, v), result|
+        key = k.is_a?(String) ? k.to_sym : k
+        result[key] = v
+      end
+    end
+
+    # Get trending players.
+    #
+    # @param sport [String] Sport code (default: "nfl")
+    # @param type [String] Trend type ("add" or "drop", default: "add")
+    # @param lookback_hours [Integer] Hours to look back (default: 24)
+    # @param limit [Integer] Max results (default: 25)
+    # @return [Array<Hash>] Trending players
+    # @see https://docs.sleeper.com/#trending-players
+    def trending_players(sport = "nfl", type: "add", lookback_hours: 24, limit: 25)
+      make_request("/players/#{sport}/trending/#{type}?lookback_hours=#{lookback_hours}&limit=#{limit}")
+    end
+
+    # Get all player data (cached for 24 hours).
+    #
+    # @param sport [String] Sport code (default: "nfl")
+    # @return [Hash{String => Hash}] Player ID to player data mapping
+    # @see https://docs.sleeper.com/#fetch-all-players
+    def get_players(sport = "nfl")
+      return @players_cache if @players_cache && @cache_timestamp && (Time.now - @cache_timestamp) < (3600 * 24)
+
+      response = make_request("/players/#{sport}")
+      @players_cache = response.parsed_response
+      @cache_timestamp = Time.now
+
+      @players_cache
+    end
+
+    # Get a specific player by ID.
+    #
+    # @param player_id [String] Player ID
+    # @param sport [String] Sport code (default: "nfl")
+    # @return [Hash, nil] Player data or nil if not found
+    # @see #get_players
+    def get_player_by_id(player_id, sport = "nfl")
+      get_players(sport)[player_id]
+    end
+
+    private
+
+    # Make an HTTP request with retry logic and logging.
+    #
+    # @param path [String] API endpoint path
+    # @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}")
+      retries = 0
+      begin
+        response = self.class.get(path, timeout: @config.timeout)
+        if response.success?
+          @config.logger&.info("Successful response for #{path}")
+          response
+        else
+          @config.logger&.error("Failed to fetch #{path}: #{response.code}")
+          raise SleeperApi::Error, "Failed to fetch #{path}: #{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}")
+          sleep(1)
+          retry
+        else
+          @config.logger&.error("Request timed out for #{path} after #{retries} retries")
+          raise SleeperApi::Error, "Request timed out after #{retries} retries"
+        end
+      end
+    end
+  end
+end

data/lib/sleeper_api/draft.rb

@@ -0,0 +1,150 @@
+# frozen_string_literal: true
+
+module SleeperApi
+  class Draft
+    include Helpers
+
+    # Draft attributes from the API.
+    ATTRIBUTES = %w[draft_id created creators draft_order last_message_id last_message_time last_picked league_id
+                    settings season season_type metadata slot_to_roster_id sport start_time status type].freeze
+
+    attr_reader :draft_id
+
+    # @param draft_id [String] Draft identifier
+    # @param client [SleeperApi::Client] HTTP client instance
+    # @raise [ArgumentError] If draft_id is empty
+    def initialize(draft_id, client)
+      raise ArgumentError, "draft_id must be a non-empty string" if draft_id.to_s.empty?
+
+      @draft_id = draft_id
+      @client = client
+      @draft_data = nil
+      @picks = nil
+      @traded_picks = nil
+
+      fetch_draft_data
+    end
+
+    # Dynamically define attribute readers for draft data.
+    ATTRIBUTES.each do |attr|
+      define_method(attr) do
+        @draft_data[attr]
+      end
+    end
+
+    # Get all draft picks with optional filtering.
+    #
+    # @param round [Integer, nil] Filter by round number
+    # @param roster_id [Integer, nil] Filter by team/roster
+    # @return [Array<Hash>] Formatted pick objects
+    def picks(round: nil, roster_id: nil)
+      fetch_picks unless @picks
+      picks = @picks
+      picks = picks.select { |pick| pick[:round] == round } if round
+      picks = picks.select { |pick| pick[:roster_id] == roster_id } if roster_id
+      picks
+    end
+
+    # Get traded draft picks with optional filtering.
+    #
+    # @param original_owner_id [Integer, nil] Filter by original team
+    # @param previous_owner_id [Integer, nil] Filter by previous owner
+    # @param current_owner_id [Integer, nil] Filter by current owner
+    # @return [Array<Hash>] Formatted traded pick objects
+    def traded_picks(original_owner_id: nil, previous_owner_id: nil, current_owner_id: nil)
+      fetch_traded_picks unless @traded_picks
+      traded_picks = @traded_picks
+      traded_picks = traded_picks.select { |pick| pick[:roster_id] == original_owner_id } if original_owner_id
+      traded_picks = traded_picks.select { |pick| pick[:previous_owner_id] == previous_owner_id } if previous_owner_id
+      traded_picks = traded_picks.select { |pick| pick[:owner_id] == current_owner_id } if current_owner_id
+      traded_picks
+    end
+
+    # Get the associated league for this draft.
+    #
+    # @return [SleeperApi::League] League object
+    def league
+      @client.league(league_id)
+    end
+
+    # Find who picked a specific player.
+    #
+    # @param player_id [String, Integer] Player ID
+    # @return [Hash] User data for the picker, or nil if player not drafted
+    def picked_by(player_id)
+      fetch_picks unless @picks
+      pick = @picks.find { |pick| pick[:player_id] == player_id }
+      return nil unless pick
+
+      league_users = league.users
+      league_users.find { |user| user[:user_id] == pick[:picked_by] }
+    end
+
+    # Calculate the next pick for a live draft.
+    #
+    # @return [Hash, nil] Next pick details or nil if draft is complete
+    def next_pick
+      return nil if status == "complete"
+
+      teams_count = settings["teams"]
+      last_pick_no = picks.map { |pick| pick[:pick_no] }.max || 0
+      {
+        pick_no: last_pick_no + 1,
+        round: ((last_pick_no / (teams_count || 12)) + 1).to_i,
+        draft_slot: ((last_pick_no % (teams_count || 12)) + 1)
+      }
+    end
+
+    # Get a high-level draft summary.
+    #
+    # @return [Hash] Summary with top picks and stats
+    def summary
+      fetch_picks unless @picks
+      {
+        draft_id: draft_id,
+        type: type,
+        season: season,
+        total_picks: picks.length,
+        total_rounds: settings["rounds"] || 0,
+        top_picks: picks.select { |pick| pick[:round] == 1 }.map do |pick|
+          {
+            player_id: pick[:player_id],
+            player_name: "#{pick[:metadata][:first_name]} #{pick[:metadata][:last_name]}",
+            position: pick[:metadata][:position],
+            picked_by: pick[:picked_by]
+          }
+        end
+      }
+    end
+
+    # Get picks grouped by round.
+    #
+    # @return [Hash{Integer => Array<Hash>}] Round number to picks mapping
+    def rounds
+      fetch_picks unless @picks
+      @picks.group_by { |pick| pick[:round] }
+    end
+
+    # Get picks grouped by team/roster.
+    #
+    # @return [Hash{Integer => Array<Hash>}] Roster ID to picks mapping
+    def team_picks
+      fetch_picks unless @picks
+      @picks.group_by { |pick| pick[:roster_id] }
+    end
+
+    private
+
+    def fetch_draft_data
+      @draft_data ||= @client.get_draft(@draft_id)
+    end
+
+    def fetch_picks
+      @picks ||= (@client.get_draft_picks(@draft_id) || []).map { |pick| deep_symbolize_keys(pick) }
+    end
+
+    def fetch_traded_picks
+      @traded_picks ||= (@client.get_draft_traded_picks(@draft_id) || []).map { |pick| deep_symbolize_keys(pick) }
+    end
+  end
+end

data/lib/sleeper_api/helpers.rb

@@ -0,0 +1,24 @@
+module SleeperApi
+  module Helpers
+    def deep_symbolize_keys(obj)
+      case obj
+      when Hash
+        obj.each_with_object({}) do |(k, v), result|
+          key = k.is_a?(String) ? k.to_sym : k
+          result[key] = deep_symbolize_keys(v)
+        end
+      when Array
+        obj.map { |el| deep_symbolize_keys(el) }
+      else
+        obj
+      end
+    end
+
+    def player_details(player_id)
+      player = @client.get_player_by_id(player_id)
+      return nil unless player
+
+      deep_symbolize_keys(player)
+    end
+  end
+end