twitchrb 1.8.0 → 1.8.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9f92c10fcfb6dba2f494d6bd5e0c24bb8cc89662a8dd577d4b8478e744f0f0fa
-  data.tar.gz: 32082cfe85dfb4fc7ded29a37b80dc25ce68ccb47481af2957c6a0a990a1c09b
+  metadata.gz: 0af94cfa8ea419d970609f4aa3fe44af46930d515afb8db7c7ba948ef0e04db1
+  data.tar.gz: cd8f2687ec21aebdc8b283f40ef62f0e00244c9fc1c75b232e7092bf06c14477
 SHA512:
-  metadata.gz: 0b021607c7e10827384d6d6461b3ba8b9d3f6459996efca1cc276a8e304f9d9ce9c16371e4f6d0a6b136f5ade2cd856d730e38f5f1df94a9d1805f7cf6f1570d
-  data.tar.gz: 94e26f89f370b871527b4c76f4aeda72ac77093a5012801efc9cd25695d05e5e683f8e3bbcef9342f0747f6e9595904f9060573e5260de017f8fb8806f9cc13d
+  metadata.gz: 9c99ec3d458e8139664062eddc8ff36e17bc4e4e83155492855daa715fdbce478a7d2c894ac764d094a4ede8aa318b52a0d8d22687c24ca69bc7ed828b8be3e9
+  data.tar.gz: b90c023cc4fff3ecdde4547871a48c77d9a34c5a841a278cb90abe9d5203bf0324cdd837a0161edc53a048f76e502db027096a27fdabe0fdbe7c53c91da50929

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    twitchrb (1.8.0)
+    twitchrb (1.8.1)
       faraday (~> 2.11)
       ostruct (~> 0.6.0)
 

data/README.md

@@ -68,6 +68,82 @@ results.cursor
 #=> Twitch::Collection
 ```
 
+### Rate Limiting
+
+The Twitch API has rate limits to ensure fair usage. TwitchRB automatically tracks rate limit information from API responses and can warn you when approaching limits.
+
+#### Automatic Rate Limit Tracking
+
+By default, the client tracks rate limit headers from all API responses:
+
+```ruby
+@client = Twitch::Client.new(client_id: "abc123", access_token: "xyz123")
+
+# Make an API call
+user = @client.users.retrieve(id: 12345)
+
+# Check current rate limit status
+@client.rate_limiter.remaining   #=> 119
+@client.rate_limiter.limit       #=> 120
+@client.rate_limiter.reset_at    #=> 1701619234 (Unix timestamp)
+@client.rate_limiter.status      #=> "119/120 requests remaining"
+```
+
+#### Configuring Rate Limit Warnings
+
+You can configure the client to warn when approaching the rate limit:
+
+```ruby
+# With logging enabled (e.g., Rails logger)
+@client = Twitch::Client.new(
+  client_id: "abc123",
+  access_token: "xyz123",
+  logger: Rails.logger,
+  rate_limit_threshold: 10  # Warn when remaining <= 10
+)
+
+# When approaching the limit, a warning will be logged:
+# "Twitch API rate limit approaching: 5/120 requests remaining. Resets in 45 seconds."
+```
+
+#### Handling Rate Limit Errors
+
+When you hit the rate limit (429 response), the library raises a `Twitch::Errors::RateLimitError` with detailed information:
+
+```ruby
+begin
+  @client.users.retrieve(id: 12345)
+rescue Twitch::Errors::RateLimitError => e
+  puts e.message
+  #=> "Error 429: Your request exceeded the API rate limit. (Resets at 14:23:45, 0/120 requests)"
+
+  puts e.reset_at     #=> 1701619234 (Unix timestamp)
+  puts e.remaining    #=> 0
+  puts e.limit        #=> 120
+end
+```
+
+#### Rate Limiter Methods
+
+The `rate_limiter` object has several useful methods:
+
+```ruby
+# Check if approaching limit
+@client.rate_limiter.approaching_limit?(threshold: 10)  #=> true/false
+
+# Get seconds until reset
+@client.rate_limiter.reset_in  #=> 45
+
+# Check if rate limited
+@client.rate_limiter.rate_limited?  #=> false
+
+# Wait until rate limit resets (useful for batch operations)
+@client.rate_limiter.wait_if_rate_limited
+
+# Reset tracking (useful when creating new client instances)
+@client.rate_limiter.reset
+```
+
 ### OAuth
 
 This library includes the ability to create, refresh and revoke OAuth tokens.
@@ -196,6 +272,11 @@ attributes = {title: "My new title"}
 # Required scope: channel:read:stream_key
 @client.channels.stream_key(broadcaster_id: 123123)
 => #<Twitch::StreamKey stream_key="live_abc123">
+
+# Run a commercial
+# broadcaster_id must match the currently authenticated user
+# Required scope: channel:edit:commercial
+@client.channels.commercial(broadcaster_id: 123123, length: 30)
 ```
 
 ### Videos

data/lib/twitch/client.rb

@@ -2,12 +2,24 @@ module Twitch
   class Client
     BASE_URL = "https://api.twitch.tv/helix"
 
-    attr_reader :client_id, :access_token, :adapter
-
-    def initialize(client_id:, access_token:, adapter: Faraday.default_adapter)
+    attr_reader :client_id, :access_token, :adapter, :rate_limiter
+    attr_reader :rate_limit_threshold, :auto_retry_rate_limit, :logger
+
+    def initialize(
+      client_id:,
+      access_token:,
+      adapter: Faraday.default_adapter,
+      rate_limit_threshold: 10,
+      auto_retry_rate_limit: true,
+      logger: nil
+    )
       @client_id = client_id
       @access_token = access_token
       @adapter = adapter
+      @rate_limit_threshold = rate_limit_threshold
+      @auto_retry_rate_limit = auto_retry_rate_limit
+      @logger = logger
+      @rate_limiter = RateLimiter.new(logger: logger)
     end
 
     def users

data/lib/twitch/collection.rb

@@ -1,5 +1,7 @@
 module Twitch
   class Collection
+    include Enumerable
+
     attr_reader :data, :total, :cursor
 
     def self.from_response(response, type:)

data/lib/twitch/error_generator.rb

@@ -96,6 +96,34 @@ module Twitch
       end
     end
 
+    class RateLimitError < TooManyRequestsError
+      attr_reader :reset_at, :remaining, :limit
+
+      def initialize(response_body, http_status_code, reset_at: nil, remaining: nil, limit: nil)
+        @reset_at = reset_at
+        @remaining = remaining
+        @limit = limit
+        super(response_body, http_status_code)
+      end
+
+      private
+
+      def build_message
+        base_message = super
+        rate_info = build_rate_info
+        "#{base_message}#{rate_info}"
+      end
+
+      def build_rate_info
+        return "" if reset_at.nil?
+
+        reset_time = Time.at(reset_at).strftime("%H:%M:%S")
+        info = " (Resets at #{reset_time}"
+        info += ", #{remaining}/#{limit} requests" if remaining && limit
+        info + ")"
+      end
+    end
+
     class InternalError < ErrorGenerator
       private
 

data/lib/twitch/rate_limiter.rb

@@ -0,0 +1,99 @@
+module Twitch
+  class RateLimiter
+    # Twitch API rate limit header names
+    LIMIT_HEADER = "ratelimit-limit".freeze
+    REMAINING_HEADER = "ratelimit-remaining".freeze
+    RESET_HEADER = "ratelimit-reset".freeze
+
+    attr_reader :limit, :remaining, :reset_at, :logger
+
+    def initialize(logger: nil)
+      @limit = nil
+      @remaining = nil
+      @reset_at = nil
+      @logger = logger
+      @last_warn_at = nil
+    end
+
+    # Update rate limit info from response headers
+    def update(response_headers)
+      return unless response_headers
+
+      @limit = response_headers[LIMIT_HEADER]&.to_i
+      @remaining = response_headers[REMAINING_HEADER]&.to_i
+      @reset_at = response_headers[RESET_HEADER]&.to_i
+    end
+
+    # Check if we're approaching the rate limit
+    def approaching_limit?(threshold: 10)
+      return false if remaining.nil? || limit.nil?
+
+      remaining <= threshold
+    end
+
+    # Get seconds until rate limit resets
+    def reset_in
+      return nil if reset_at.nil?
+
+      seconds = reset_at - Time.now.to_i
+      [ seconds, 0 ].max  # Ensure non-negative
+    end
+
+    # Check if rate limited (no remaining requests)
+    def rate_limited?
+      remaining == 0
+    end
+
+    # Log rate limit warning if approaching threshold
+    def warn_if_approaching(threshold: 10)
+      return unless approaching_limit?(threshold: threshold)
+      return unless logger
+      return if recently_warned?
+
+      @last_warn_at = Time.now
+      logger.warn(
+        "Twitch API rate limit approaching: #{remaining}/#{limit} requests remaining. " \
+        "Resets in #{reset_in} seconds."
+      )
+    end
+
+    # Wait if rate limited, with exponential backoff
+    def wait_if_rate_limited(base_wait: 1.0, max_wait: 60.0)
+      return if !rate_limited? || reset_in.nil?
+
+      wait_seconds = [ reset_in + 1, max_wait ].min  # Add 1 second buffer
+
+      if logger
+        logger.warn("Rate limited. Waiting #{wait_seconds} seconds until reset at #{Time.at(reset_at)}")
+      end
+
+      sleep(wait_seconds)
+    end
+
+    # Reset rate limit tracking
+    def reset
+      @limit = nil
+      @remaining = nil
+      @reset_at = nil
+      @last_warn_at = nil
+    end
+
+    # Get formatted status string
+    def status
+      if limit.nil? || remaining.nil?
+        "Rate limit info not available"
+      else
+        "#{remaining}/#{limit} requests remaining"
+      end
+    end
+
+    private
+
+    def recently_warned?
+      return false if @last_warn_at.nil?
+
+      # Don't warn more than once per minute
+      (Time.now - @last_warn_at) < 60
+    end
+  end
+end

data/lib/twitch/resource.rb

@@ -29,6 +29,9 @@ module Twitch
     end
 
     def handle_response(response)
+      # Extract and update rate limit info from response headers
+      update_rate_limit(response)
+
       return true if response.status == 204
       return response unless error?(response)
 
@@ -41,8 +44,32 @@ module Twitch
     end
 
     def raise_error(response)
+      # Special handling for rate limit errors
+      if response.status == 429
+        raise_rate_limit_error(response)
+      end
+
       error = Twitch::ErrorFactory.create(response.body, response.status)
       raise error if error
     end
+
+    private
+
+    def update_rate_limit(response)
+      client.rate_limiter.update(response.headers)
+      client.rate_limiter.warn_if_approaching(threshold: client.rate_limit_threshold)
+    end
+
+    def raise_rate_limit_error(response)
+      headers = response.headers
+      error = Twitch::Errors::RateLimitError.new(
+        response.body,
+        response.status,
+        reset_at: headers["ratelimit-reset"]&.to_i,
+        remaining: headers["ratelimit-remaining"]&.to_i,
+        limit: headers["ratelimit-limit"]&.to_i
+      )
+      raise error
+    end
   end
 end

data/lib/twitch/resources/channels.rb

@@ -50,5 +50,9 @@ module Twitch
       response = get_request("streams/key?broadcaster_id=#{broadcaster_id}")
       StreamKey.new(response.body.dig("data")[0])
     end
+
+    def commercial(broadcaster_id:, length:)
+      post_request("channels/commercial", body: { broadcaster_id: broadcaster_id, length: length })
+    end
   end
 end

data/lib/twitch/version.rb

@@ -1,3 +1,3 @@
 module Twitch
-  VERSION = "1.8.0"
+  VERSION = "1.8.1"
 end

data/lib/twitch.rb

@@ -9,6 +9,8 @@ module Twitch
   autoload :ErrorGenerator, "twitch/error_generator"
   autoload :ErrorFactory, "twitch/error_generator"
 
+  autoload :RateLimiter, "twitch/rate_limiter"
+
   autoload :Client, "twitch/client"
   autoload :Collection, "twitch/collection"
   autoload :Resource, "twitch/resource"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: twitchrb
 version: !ruby/object:Gem::Version
-  version: 1.8.0
+  version: 1.8.1
 platform: ruby
 authors:
 - Dean Perry
@@ -107,6 +107,7 @@ files:
 - lib/twitch/objects/video.rb
 - lib/twitch/objects/vip.rb
 - lib/twitch/objects/warning.rb
+- lib/twitch/rate_limiter.rb
 - lib/twitch/resource.rb
 - lib/twitch/resources/announcements.rb
 - lib/twitch/resources/automod.rb