twitchrb 1.10.0 → 2.0.0

data/lib/twitch/client.rb

@@ -1,24 +1,42 @@
 module Twitch
   class Client
     BASE_URL = "https://api.twitch.tv/helix"
+    DEFAULT_TIMEOUT = 30
+    DEFAULT_OPEN_TIMEOUT = 10
 
     attr_reader :client_id, :access_token, :adapter, :rate_limiter
     attr_reader :rate_limit_threshold, :auto_retry_rate_limit, :logger
+    attr_reader :timeout, :open_timeout
+    attr_reader :refresh_token, :client_secret, :on_token_refresh
 
+    # Pass refresh_token to refresh expired user access tokens automatically. client_secret is
+    # needed unless your app is a public client. on_token_refresh is called with the new token
+    # (access_token, refresh_token, expires_in, scope) so you can store it.
     def initialize(
       client_id:,
       access_token:,
+      refresh_token: nil,
+      client_secret: nil,
+      on_token_refresh: nil,
       adapter: Faraday.default_adapter,
       rate_limit_threshold: 10,
       auto_retry_rate_limit: true,
-      logger: nil
+      logger: nil,
+      timeout: DEFAULT_TIMEOUT,
+      open_timeout: DEFAULT_OPEN_TIMEOUT
     )
       @client_id = client_id
       @access_token = access_token
+      @refresh_token = refresh_token
+      @client_secret = client_secret
+      @on_token_refresh = on_token_refresh
+      @token_refresh_mutex = Mutex.new
       @adapter = adapter
       @rate_limit_threshold = rate_limit_threshold
       @auto_retry_rate_limit = auto_retry_rate_limit
       @logger = logger
+      @timeout = timeout
+      @open_timeout = open_timeout
       @rate_limiter = RateLimiter.new(logger: logger)
     end
 
@@ -58,10 +76,6 @@ module Twitch
       EventsubConduitsResource.new(self)
     end
 
-    def banned_events
-      BannedEventsResource.new(self)
-    end
-
     def banned_users
       BannedUsersResource.new(self)
     end
@@ -70,10 +84,6 @@ module Twitch
       ModeratorsResource.new(self)
     end
 
-    def moderator_events
-      ModeratorEventsResource.new(self)
-    end
-
     def polls
       PollsResource.new(self)
     end
@@ -102,10 +112,6 @@ module Twitch
       SubscriptionsResource.new(self)
     end
 
-    def tags
-      TagsResource.new(self)
-    end
-
     def custom_rewards
       CustomRewardsResource.new(self)
     end
@@ -122,10 +128,6 @@ module Twitch
       GoalsResource.new(self)
     end
 
-    def hype_train_events
-      HypeTrainEventsResource.new(self)
-    end
-
     def hype_train_status
       HypeTrainStatusResource.new(self)
     end
@@ -190,21 +192,108 @@ module Twitch
       SuspiciousUsersResource.new(self)
     end
 
+    def ads
+      AdsResource.new(self)
+    end
+
+    def analytics
+      AnalyticsResource.new(self)
+    end
+
+    def bits
+      BitsResource.new(self)
+    end
+
+    def chat_settings
+      ChatSettingsResource.new(self)
+    end
+
+    def content_classification_labels
+      ContentClassificationLabelsResource.new(self)
+    end
+
+    def drops_entitlements
+      DropsEntitlementsResource.new(self)
+    end
+
+    def extensions
+      ExtensionsResource.new(self)
+    end
+
+    def guest_star
+      GuestStarResource.new(self)
+    end
+
+    def shield_mode
+      ShieldModeResource.new(self)
+    end
+
+    def teams
+      TeamsResource.new(self)
+    end
+
+    # Refreshes the access token using the refresh token, and returns the new token
+    def refresh_access_token!
+      raise Error, "A refresh_token is required to refresh the access token" unless refresh_token
+
+      @token_refresh_mutex.synchronize { perform_token_refresh }
+    end
+
+    # Called after a 401. Refreshes the token if the response means it has expired, unless
+    # another thread already refreshed it. Returns true if the request should be retried.
+    def refresh_after_unauthorized(response, failed_access_token)
+      return false unless refresh_token && token_expired_response?(response)
+
+      @token_refresh_mutex.synchronize do
+        perform_token_refresh if access_token == failed_access_token
+      end
+
+      true
+    end
+
     def connection
       @connection ||= Faraday.new(BASE_URL) do |conn|
-        conn.request :authorization, :Bearer, access_token
+        # A lambda, so requests pick up a refreshed token
+        conn.request :authorization, :Bearer, -> { access_token }
 
         conn.headers = {
-          "User-Agent" => "twitchrb/v#{VERSION} (github.com/deanpcmad/twitchrb)",
+          "User-Agent" => "twitchrb/v#{VERSION} (github.com/d34ndev/twitchrb)",
           "Client-ID": client_id
         }
 
+        # Helix expects repeated keys for multiple values (id=1&id=2), not id[]=1&id[]=2
+        conn.options.params_encoder = Faraday::FlatParamsEncoder
+        conn.options.timeout = timeout
+        conn.options.open_timeout = open_timeout
+
         conn.request :json
 
         conn.response :json, content_type: "application/json"
 
-        conn.adapter adapter, @stubs
+        conn.adapter adapter
       end
     end
+
+    private
+
+    def oauth
+      @oauth ||= OAuth.new(client_id: client_id, client_secret: client_secret, timeout: timeout, open_timeout: open_timeout)
+    end
+
+    def perform_token_refresh
+      token = oauth.refresh(refresh_token: refresh_token)
+
+      @access_token = token.access_token
+      @refresh_token = token.refresh_token if token.refresh_token
+      on_token_refresh&.call(token)
+
+      token
+    end
+
+    # Helix also returns 401 for a token missing a required scope, which a refresh won't fix
+    def token_expired_response?(response)
+      message = response.body.is_a?(Hash) ? response.body["message"].to_s : ""
+      !message.match?(/missing scope/i)
+    end
   end
 end

data/lib/twitch/collection.rb

@@ -2,34 +2,81 @@ module Twitch
   class Collection
     include Enumerable
 
-    attr_reader :data, :total, :cursor
+    attr_reader :data, :total, :cursor, :errors
 
-    def self.from_response(response, type:)
+    def self.from_response(response, type:, next_page: nil)
       body = response.body
+      data = body["data"] || []
 
       new(
-        data: body["data"].map { |attrs| type.new(attrs) },
-        total: body["data"].count,
-        cursor: body.dig("pagination", "cursor")
+        data: data.map { |attrs| type.new(attrs) },
+        total: body["total"] || data.count,
+        cursor: cursor_from(body["pagination"]),
+        next_page: next_page,
+        errors: (body["errors"] || []).map { |attrs| Object.new(attrs) }
       )
     end
 
-    def initialize(data:, total:, cursor:)
+    # Most endpoints return pagination as { "cursor": "..." }, but a few
+    # (e.g. Get Extension Live Channels) return the cursor as a bare string
+    def self.cursor_from(pagination)
+      pagination.is_a?(Hash) ? pagination["cursor"] : pagination
+    end
+
+    # next_page is a callable that takes a cursor and returns the following Collection.
+    # errors lists items that failed, for endpoints that report partial failures (e.g. Update Conduit Shards).
+    def initialize(data:, total:, cursor:, next_page: nil, errors: [])
       @data = data
       @total = total
-      @cursor = cursor.nil? ? nil : cursor
+      @cursor = cursor
+      @next_page = next_page
+      @errors = errors
     end
 
     def each(&block)
       data.each(&block)
     end
 
-    def first
-      data.first
+    def first(...)
+      data.first(...)
+    end
+
+    def last(...)
+      data.last(...)
+    end
+
+    # Twitch can return a cursor alongside an empty last page, so an empty page has no next page
+    def next_page?
+      !@next_page.nil? && !cursor.nil? && !cursor.empty? && data.any?
+    end
+
+    # Fetches the following page, or returns nil on the last page
+    def next_page
+      @next_page.call(cursor) if next_page?
+    end
+
+    # Yields this page and each following page, fetching them as needed.
+    # Returns an Enumerator without a block.
+    def each_page
+      return enum_for(:each_page) unless block_given?
+
+      page = self
+      seen_cursors = []
+
+      while page
+        yield page
+        break if page.cursor.nil? || seen_cursors.include?(page.cursor)
+
+        seen_cursors << page.cursor
+        page = page.next_page
+      end
     end
 
-    def last
-      data.last
+    # Lazily iterates over every item across all pages, fetching pages only as needed.
+    #   client.clips.list(broadcaster_id: 123).auto_paginate.first(250)
+    #   client.channels.followers(broadcaster_id: 123, first: 100).auto_paginate.to_a
+    def auto_paginate
+      each_page.lazy.flat_map(&:data)
     end
   end
 end

data/lib/twitch/error_generator.rb

@@ -1,5 +1,6 @@
 module Twitch
-  class ErrorGenerator < StandardError
+  class ErrorGenerator < Error
+    attr_reader :response_body
     attr_reader :http_status_code
     attr_reader :twitch_error_code
     attr_reader :twitch_error_message
@@ -40,10 +41,11 @@ module Twitch
     end
 
     def build_message
-      if twitch_error_code.nil?
-        return "Error #{@http_status_code}: #{error_message}"
+      message = "Error #{@http_status_code}: #{error_message}"
+      if twitch_error_message && twitch_error_message != error_message
+        message += " '#{twitch_error_message}'"
       end
-      "Error #{@http_status_code}: #{error_message} '#{twitch_error_message}'"
+      message
     end
   end
 

data/lib/twitch/eventsub_webhook.rb

@@ -0,0 +1,140 @@
+require "openssl"
+require "time"
+
+module Twitch
+  # Verifies and parses an EventSub webhook request from Twitch.
+  # See https://dev.twitch.tv/docs/eventsub/handling-webhook-events/
+  #
+  #   webhook = Twitch::EventsubWebhook.new(secret: ENV["TWITCH_EVENTSUB_SECRET"], headers: request.headers, body: request.raw_post)
+  #   return head :forbidden unless webhook.valid?
+  #
+  # body must be the raw request body, as the signature covers the exact bytes Twitch sent.
+  class EventsubWebhook
+    MESSAGE_ID_HEADER = "Twitch-Eventsub-Message-Id".freeze
+    MESSAGE_TIMESTAMP_HEADER = "Twitch-Eventsub-Message-Timestamp".freeze
+    MESSAGE_SIGNATURE_HEADER = "Twitch-Eventsub-Message-Signature".freeze
+    MESSAGE_TYPE_HEADER = "Twitch-Eventsub-Message-Type".freeze
+    MESSAGE_RETRY_HEADER = "Twitch-Eventsub-Message-Retry".freeze
+    SUBSCRIPTION_TYPE_HEADER = "Twitch-Eventsub-Subscription-Type".freeze
+    SUBSCRIPTION_VERSION_HEADER = "Twitch-Eventsub-Subscription-Version".freeze
+
+    # Twitch recommends rejecting messages older than 10 minutes to guard against replay attacks
+    DEFAULT_MAX_AGE = 600
+
+    attr_reader :body
+
+    # Returns true if the request's signature is valid and it isn't older than max_age seconds
+    def self.verify(secret:, headers:, body:, max_age: DEFAULT_MAX_AGE)
+      new(secret: secret, headers: headers, body: body, max_age: max_age).valid?
+    end
+
+    # headers can be a Hash (any header name casing), a Rack env, or Rails' request.headers
+    def initialize(secret:, headers:, body:, max_age: DEFAULT_MAX_AGE)
+      raise ArgumentError, "body must be the raw request body string, not parsed JSON" unless body.is_a?(String)
+
+      @secret = secret
+      @headers = headers
+      @body = body
+      @max_age = max_age
+    end
+
+    def valid?
+      signature_valid? && !expired?
+    end
+
+    def signature_valid?
+      return false if @secret.nil? || @secret.empty?
+      return false if message_id.nil? || timestamp_header.nil? || signature.nil?
+
+      expected = "sha256=#{OpenSSL::HMAC.hexdigest("SHA256", @secret, message_id + timestamp_header + body)}"
+      OpenSSL.secure_compare(expected, signature)
+    end
+
+    # True if the message is older than max_age seconds, or has no readable timestamp.
+    # Also rejects timestamps far in the future.
+    def expired?
+      return true if timestamp.nil?
+
+      (Time.now - timestamp).abs > @max_age
+    end
+
+    # Use this to ignore messages you've already processed, as Twitch may send a message more than once
+    def message_id
+      header(MESSAGE_ID_HEADER)
+    end
+
+    # notification, webhook_callback_verification or revocation
+    def message_type
+      header(MESSAGE_TYPE_HEADER)
+    end
+
+    def notification?
+      message_type == "notification"
+    end
+
+    def verification?
+      message_type == "webhook_callback_verification"
+    end
+
+    def revocation?
+      message_type == "revocation"
+    end
+
+    def retry?
+      header(MESSAGE_RETRY_HEADER).to_i > 0
+    end
+
+    def timestamp
+      Time.iso8601(timestamp_header) if timestamp_header
+    rescue ArgumentError
+      nil
+    end
+
+    # e.g. channel.follow
+    def subscription_type
+      header(SUBSCRIPTION_TYPE_HEADER)
+    end
+
+    def subscription_version
+      header(SUBSCRIPTION_VERSION_HEADER)
+    end
+
+    def payload
+      @payload ||= JSON.parse(body)
+    end
+
+    def subscription
+      EventsubSubscription.new(payload["subscription"]) if payload["subscription"]
+    end
+
+    # The event data for notification messages
+    def event
+      Object.new(payload["event"]) if payload["event"]
+    end
+
+    # For webhook_callback_verification messages. Respond with this as a text/plain 200 response.
+    def challenge
+      payload["challenge"]
+    end
+
+    private
+
+    def signature
+      header(MESSAGE_SIGNATURE_HEADER)
+    end
+
+    def timestamp_header
+      header(MESSAGE_TIMESTAMP_HEADER)
+    end
+
+    def header(name)
+      rack_key = "HTTP_#{name.upcase.tr("-", "_")}"
+
+      value = @headers[name] || @headers[rack_key]
+      return value if value
+
+      @headers.each { |key, val| return val if key.to_s.casecmp?(name) }
+      nil
+    end
+  end
+end

data/lib/twitch/oauth.rb

@@ -1,23 +1,35 @@
 module Twitch
   class OAuth
-    attr_reader :client_id, :client_secret
+    BASE_URL = "https://id.twitch.tv/oauth2"
+    DEVICE_CODE_GRANT_TYPE = "urn:ietf:params:oauth:grant-type:device_code"
 
-    def initialize(client_id:, client_secret:)
+    attr_reader :client_id, :client_secret, :timeout, :open_timeout
+
+    # client_secret can be omitted for public clients using the device code flow
+    def initialize(client_id:, client_secret: nil, timeout: Client::DEFAULT_TIMEOUT, open_timeout: Client::DEFAULT_OPEN_TIMEOUT)
       @client_id = client_id
       @client_secret = client_secret
+      @timeout = timeout
+      @open_timeout = open_timeout
     end
 
-    def create(grant_type:, scope: nil)
-      send_request(url: "https://id.twitch.tv/oauth2/token", body: {
+    # Extra params (e.g. code and redirect_uri) are sent with the request
+    def create(grant_type:, scope: nil, **params)
+      send_request(url: "token", body: params.merge(
         client_id: client_id,
         client_secret: client_secret,
         grant_type: grant_type,
-        scope: scope
-      })
+        scope: scope_string(scope)
+      ))
+    end
+
+    # Exchanges the code from the authorization code grant flow for an access token and refresh token
+    def exchange_code(code:, redirect_uri:)
+      create(grant_type: "authorization_code", code: code, redirect_uri: redirect_uri)
     end
 
     def refresh(refresh_token:)
-      send_request(url: "https://id.twitch.tv/oauth2/token", body: {
+      send_request(url: "token", body: {
         client_id: client_id,
         client_secret: client_secret,
         grant_type: "refresh_token",
@@ -25,12 +37,25 @@ module Twitch
       })
     end
 
+    # Starts the device code grant flow. scopes can be an array or a space-delimited string.
     def device(scopes:)
-      send_request(url: "https://id.twitch.tv/oauth2/device", body: { client_id: client_id, scope: scopes })
+      send_request(url: "device", body: { client_id: client_id, scopes: scope_string(scopes) })
+    end
+
+    # Exchanges a device code for an access token and refresh token once the user has authorized.
+    # Until then, raises Twitch::Errors::BadRequestError with twitch_error_message "authorization_pending".
+    def device_token(device_code:, scopes:)
+      send_request(url: "token", body: {
+        client_id: client_id,
+        client_secret: client_secret,
+        device_code: device_code,
+        scopes: scope_string(scopes),
+        grant_type: DEVICE_CODE_GRANT_TYPE
+      })
     end
 
     def validate(token:)
-      response = Faraday.get("https://id.twitch.tv/oauth2/validate", nil, { "Authorization" => "OAuth #{token}" })
+      response = connection.get("validate", nil, { "Authorization" => "OAuth #{token}" })
 
       return false if response.status != 200
 
@@ -38,24 +63,34 @@ module Twitch
     end
 
     def revoke(token:)
-      response = Faraday.post("https://id.twitch.tv/oauth2/revoke", {
+      response = connection.post("revoke", {
         client_id: client_id,
         token: token
       })
 
-      JSON.parse(response.body, object_class: OpenStruct) if response.status != 200
-
-      true
+      response.status == 200
     end
 
     private
 
+    def connection
+      @connection ||= Faraday.new(BASE_URL) do |conn|
+        conn.options.timeout = timeout
+        conn.options.open_timeout = open_timeout
+        conn.request :url_encoded
+      end
+    end
+
     def send_request(url:, body:)
-      response = Faraday.post(url, body)
+      response = connection.post(url, body.compact)
 
-      return false if response.status != 200
+      raise ErrorFactory.create(response.body, response.status) if response.status != 200
 
       JSON.parse(response.body, object_class: OpenStruct)
     end
+
+    def scope_string(scopes)
+      scopes.is_a?(Array) ? scopes.join(" ") : scopes
+    end
   end
 end

data/lib/twitch/object.rb

@@ -15,5 +15,33 @@ module Twitch
         obj
       end
     end
+
+    # Unlike OpenStruct#to_h, converts nested objects back into hashes too,
+    # so the result can be serialized
+    def to_h(&block)
+      hash = super(&nil).transform_values { |value| to_hash_value(value) }
+      block ? hash.to_h(&block) : hash
+    end
+
+    def as_json(*)
+      to_h
+    end
+
+    def to_json(*args)
+      to_h.to_json(*args)
+    end
+
+    private
+
+    def to_hash_value(value)
+      case value
+      when OpenStruct
+        value.to_h.transform_values { |v| to_hash_value(v) }
+      when Array
+        value.map { |v| to_hash_value(v) }
+      else
+        value
+      end
+    end
   end
 end

data/lib/twitch/objects/ad_schedule.rb

@@ -0,0 +1,4 @@
+module Twitch
+  class AdSchedule < Object
+  end
+end

data/lib/twitch/objects/analytics_report.rb

@@ -0,0 +1,4 @@
+module Twitch
+  class AnalyticsReport < Object
+  end
+end

data/lib/twitch/objects/bits_leaderboard_entry.rb

@@ -0,0 +1,4 @@
+module Twitch
+  class BitsLeaderboardEntry < Object
+  end
+end

data/lib/twitch/objects/charity_donation.rb

@@ -0,0 +1,4 @@
+module Twitch
+  class CharityDonation < Object
+  end
+end

data/lib/twitch/objects/chat_settings.rb

@@ -0,0 +1,4 @@
+module Twitch
+  class ChatSettings < Object
+  end
+end

data/lib/twitch/objects/cheermote.rb

@@ -0,0 +1,4 @@
+module Twitch
+  class Cheermote < Object
+  end
+end

data/lib/twitch/objects/content_classification_label.rb

@@ -0,0 +1,4 @@
+module Twitch
+  class ContentClassificationLabel < Object
+  end
+end

data/lib/twitch/objects/drops_entitlement.rb

@@ -0,0 +1,4 @@
+module Twitch
+  class DropsEntitlement < Object
+  end
+end

data/lib/twitch/objects/drops_entitlement_update.rb

@@ -0,0 +1,4 @@
+module Twitch
+  class DropsEntitlementUpdate < Object
+  end
+end

data/lib/twitch/objects/extension.rb

@@ -0,0 +1,4 @@
+module Twitch
+  class Extension < Object
+  end
+end

data/lib/twitch/objects/extension_bits_product.rb

@@ -0,0 +1,4 @@
+module Twitch
+  class ExtensionBitsProduct < Object
+  end
+end

data/lib/twitch/objects/extension_configuration_segment.rb

@@ -0,0 +1,4 @@
+module Twitch
+  class ExtensionConfigurationSegment < Object
+  end
+end

data/lib/twitch/objects/extension_live_channel.rb

@@ -0,0 +1,4 @@
+module Twitch
+  class ExtensionLiveChannel < Object
+  end
+end

data/lib/twitch/objects/extension_secret.rb

@@ -0,0 +1,4 @@
+module Twitch
+  class ExtensionSecret < Object
+  end
+end

data/lib/twitch/objects/extension_transaction.rb

@@ -0,0 +1,4 @@
+module Twitch
+  class ExtensionTransaction < Object
+  end
+end