twitch-api 0.4.0 → 1.0.0

data/lib/twitch/client.rb

@@ -1,149 +1,176 @@
-require "faraday"
-require "faraday_middleware"
-
-require "twitch/response"
-require "twitch/api_error"
-require "twitch/bits_leader"
-require "twitch/clip"
-require "twitch/entitlement_grant_url"
-require "twitch/game"
-require "twitch/game_analytic"
-require "twitch/stream"
-require "twitch/stream_marker"
-require "twitch/stream_metadata"
-require "twitch/user"
-require "twitch/user_follow"
-require "twitch/video"
+# frozen_string_literal: true
+
+require 'faraday'
+require 'faraday/parse_dates'
+require 'faraday/retry'
+require 'twitch_oauth2'
+
+require_relative 'response'
+
+require_relative 'api_error'
+require_relative 'bits_leader'
+require_relative 'category'
+require_relative 'channel'
+require_relative 'cheermote'
+require_relative 'clip'
+require_relative 'custom_reward'
+require_relative 'editor'
+require_relative 'entitlement_grant_url'
+require_relative 'extension'
+require_relative 'extensions_by_types'
+require_relative 'game'
+require_relative 'game_analytic'
+require_relative 'moderation_event'
+require_relative 'moderator'
+require_relative 'stream'
+require_relative 'stream_marker'
+require_relative 'stream_metadata'
+require_relative 'subscription'
+require_relative 'user'
+require_relative 'user_ban'
+require_relative 'user_follow'
+require_relative 'redemption'
+require_relative 'video'
 
 module Twitch
+  # Core class for requests
   class Client
-    # Helix API endpoint.
-    API_ENDPOINT = "https://api.twitch.tv/helix".freeze
+    # Base connection to Helix API.
+    CONNECTION = Faraday.new(
+      'https://api.twitch.tv/helix', {
+        headers: { 'User-Agent': "twitch-api ruby client #{Twitch::VERSION}" }
+      }
+    ) do |faraday|
+      faraday.request :retry,
+        exceptions: [*Faraday::Retry::Middleware::DEFAULT_EXCEPTIONS, Faraday::ConnectionFailed]
+
+      faraday.response :parse_dates
+
+      faraday.request :json
+      faraday.response :json
+    end
+
+    attr_reader :tokens
 
     # Initializes a Twitch client.
-    # 
-    # - client_id [String] The client ID.
-    # Used as the Client-ID header in a request.
-    # - access_token [String] An access token.
-    # Used as the Authorization header in a request.
-    # Any "Bearer " prefix will be stripped.
-    # - with_raw [Boolean] Whether to include raw HTTP response
-    # Intended for testing/checking API results
-    def initialize(client_id: nil, access_token: nil, with_raw: false)
-      if client_id.nil? && access_token.nil?
-        raise "An identifier token (client ID or bearer token) is required"
-      elsif !!client_id && !!access_token
-        warn(%{WARNING:
-It is recommended that only one identifier token is specified.
-Unpredictable behavior may follow.})
-      end
+    #
+    # - tokens [TwitchOAuth2::Tokens] Tokens object with their refreshing logic inside.
+    # All client and authentication information (`client_id`, `:scopes`, etc.) stores there.
+    def initialize(tokens:)
+      @tokens = tokens
 
-      headers = {
-        "User-Agent": "twitch-api ruby client #{Twitch::VERSION}"
-      }
-      unless client_id.nil?
-        headers["Client-ID"] = client_id
-      end
-      unless access_token.nil?
-        access_token = access_token.gsub(/^Bearer /, "")
-        headers["Authorization"] = "Bearer #{access_token}"
-      end
-      
-      @conn = Faraday.new(API_ENDPOINT, { headers: headers }) do |faraday|
-        faraday.request :json
-        faraday.response :json
-        faraday.adapter Faraday.default_adapter
-      end
+      CONNECTION.headers['Client-ID'] = self.tokens.client.client_id
 
-      @with_raw = with_raw
+      renew_authorization_header
     end
 
     def create_clip(options = {})
-      Response.new(Clip, post('clips', options))
+      initialize_response Clip, post('clips', options)
     end
 
     def create_entitlement_grant_url(options = {})
-      Response.new(EntitlementGrantUrl, post('entitlements/upload', options))
-    end
-
-    def create_stream_marker(options = {})
-      Response.new(StreamMarker, post('streams/markers', options))
+      initialize_response EntitlementGrantUrl, post('entitlements/upload', options)
     end
 
     def get_clips(options = {})
-      Response.new(Clip, get('clips', options))
+      initialize_response Clip, get('clips', options)
     end
 
     def get_bits_leaderboard(options = {})
-      Response.new(BitsLeader, get('bits/leaderboard', options))
+      initialize_response BitsLeader, get('bits/leaderboard', options)
     end
 
-    def get_games(options = {})
-      Response.new(Game, get('games', options))
+    def get_cheermotes(options = {})
+      initialize_response Cheermote, get('bits/cheermotes', options)
     end
 
-    def get_top_games(options = {})
-      Response.new(Game, get('games/top', options))
-    end
+    require_relative 'client/extensions'
+    include Extensions
 
-    def get_game_analytics(options = {})
-      Response.new(GameAnalytic, get('analytics/games', options))
-    end
+    require_relative 'client/games'
+    include Games
+
+    require_relative 'client/moderation'
+    include Moderation
+
+    require_relative 'client/streams'
+    include Streams
 
-    def get_stream_markers(options = {})
-      Response.new(StreamMarkerResponse, get('streams/markers', options))
+    require_relative 'client/subscriptions'
+    include Subscriptions
+
+    def get_videos(options = {})
+      initialize_response Video, get('videos', options)
     end
 
-    def get_streams(options = {})
-      Response.new(Stream, get('streams', options))
+    require_relative 'client/users'
+    include Users
+
+    require_relative 'client/custom_rewards'
+    include CustomRewards
+
+    ## https://dev.twitch.tv/docs/api/reference#get-channel-information
+    def get_channels(options = {})
+      initialize_response Channel, get('channels', options)
     end
 
-    def get_streams_metadata(options = {})
-      Response.new(StreamMetadata, get('streams/metadata', options))
+    ## https://dev.twitch.tv/docs/api/reference/#search-channels
+    def search_channels(options = {})
+      initialize_response Channel, get('search/channels', options)
     end
 
-    def get_users_follows(options = {})
-      Response.new(UserFollow, get('users/follows', options))
+    ## https://dev.twitch.tv/docs/api/reference#modify-channel-information
+    def modify_channel(options = {})
+      response = patch('channels', options)
+
+      return true if response.body.empty?
+
+      response.body
     end
 
-    def get_users(options = {})
-      Response.new(User, get('users', options))
+    ## https://dev.twitch.tv/docs/api/reference/#start-commercial
+    def start_commercial(options = {})
+      initialize_response nil, post('channels/commercial', options)
     end
 
-    def update_user(options = {})
-      Response.new(User, put('users', options))
+    ## https://dev.twitch.tv/docs/api/reference/#get-channel-editors
+    def get_channel_editors(options = {})
+      initialize_response Editor, get('channels/editors', options)
     end
 
-    def get_videos(options = {})
-      Response.new(Video, get('videos', options))
+    ## https://dev.twitch.tv/docs/api/reference/#search-categories
+    def search_categories(options = {})
+      initialize_response Category, get('search/categories', options)
     end
 
     private
 
-      def get(resource, params)
-        http_res = @conn.get(resource, params)
-        finish(http_res)
-      end
+    def initialize_response(data_class, http_response)
+      Response.new(data_class, http_response: http_response)
+    end
 
-      def post(resource, params)
-        http_res = @conn.post(resource, params)
-        finish(http_res)
+    %w[get post put patch].each do |http_method|
+      define_method http_method do |resource, params|
+        request http_method, resource, params
       end
+    end
 
-      def put(resource, params)
-        http_res = @conn.put(resource, params)
-        finish(http_res)
-      end
+    def renew_authorization_header
+      CONNECTION.headers['Authorization'] = "Bearer #{tokens.access_token}"
+    end
 
-      def finish(http_res)
-        unless http_res.success?
-          raise ApiError.new(http_res.status, http_res.body)
-        end
+    def request(http_method, resource, params)
+      http_response = CONNECTION.public_send http_method, resource, params
 
-        {
-            http_res: http_res,
-            with_raw: @with_raw
-        }
+      if http_response.status == 401
+        renew_authorization_header
+
+        http_response = CONNECTION.public_send http_method, resource, params
       end
+
+      return http_response if http_response.success?
+
+      raise APIError.new(http_response.status, http_response.body)
+    end
   end
 end

data/lib/twitch/clip.rb

@@ -1,9 +1,8 @@
+# frozen_string_literal: true
+
 module Twitch
   # A small segment of a broadcast captured by another user.
   class Clip
-    # Fields to be converted from ISO 8601 string to a typed date.
-    DATE_ATTRIBUTES = [:created_at]
-
     # ID of the clip.
     attr_reader :id
     # Title of the clip.
@@ -34,14 +33,9 @@ module Twitch
     attr_reader :video_id
 
     def initialize(attributes = {})
-      attributes.each do |k, v|
-        if DATE_ATTRIBUTES.include?(k.to_sym)
-          instance_variable_set("@#{k}", Time.parse(v))
-        else
-          instance_variable_set("@#{k}", v)
-        end
+      attributes.each do |key, value|
+        instance_variable_set "@#{key}", value
       end
     end
-    
   end
-end
+end

data/lib/twitch/custom_reward.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+module Twitch
+  ## Data object for Twitch custom rewards
+  class CustomReward
+    ## Data object for images of Twitch custom rewards
+    class CustomRewardImage
+      # The URL to a small version of the image.
+      attr_reader :url_1x
+      # The URL to a medium version of the image.
+      attr_reader :url_2x
+      # The URL to a large version of the image.
+      attr_reader :url_4x
+
+      def initialize(attributes = {})
+        attributes.each do |key, value|
+          instance_variable_set "@#{key}", value
+        end
+      end
+    end
+
+    # The ID that uniquely identifies the broadcaster.
+    attr_reader :broadcaster_id
+    # The broadcaster’s login name.
+    attr_reader :broadcaster_login
+    # The broadcaster’s display name.
+    attr_reader :broadcaster_name
+    # The ID that uniquely identifies this custom reward.
+    attr_reader :id
+    # The title of the reward.
+    attr_reader :title
+    # The prompt shown to the viewer when they redeem the reward if user input is required
+    # (see the `is_user_input_required` field).
+    attr_reader :prompt
+    # The cost of the reward in Channel Points.
+    attr_reader :cost
+    # A set of custom images for the reward.
+    # This field is `nil` if the broadcaster didn’t upload images.
+    attr_reader :image
+    # A set of default images for the reward.
+    attr_reader :default_image
+    # The background color to use for the reward.
+    # The color is in Hex format (for example, `#00E5CB`).
+    attr_reader :background_color
+    # A Boolean value that determines whether the reward is enabled.
+    # Is `true` if enabled; otherwise, `false`. Disabled rewards aren’t shown to the user.
+    attr_reader :is_enabled
+    # A Boolean value that determines whether the user must enter information
+    # when redeeming the reward. Is `true` if the user is prompted.
+    attr_reader :is_user_input_required
+    # The settings used to determine whether to apply a maximum to the number of redemptions
+    # allowed per live stream.
+    attr_reader :max_per_stream_setting
+    # The settings used to determine whether to apply a maximum to the number of redemptions
+    # allowed per user per live stream.
+    attr_reader :max_per_user_per_stream_setting
+    # The settings used to determine whether to apply a cooldown period between redemptions
+    # and the length of the cooldown.
+    attr_reader :global_cooldown_setting
+    # A Boolean value that determines whether the reward is currently paused.
+    # Is `true` if the reward is paused. Viewers can’t redeem paused rewards.
+    attr_reader :is_paused
+    # A Boolean value that determines whether the reward is currently in stock.
+    # Is `true` if the reward is in stock. Viewers can’t redeem out of stock rewards.
+    attr_reader :is_in_stock
+    # A Boolean value that determines whether redemptions should be set to FULFILLED status
+    # immediately when a reward is redeemed. If `false`, status is set to UNFULFILLED
+    # and follows the normal request queue process.
+    attr_reader :should_redemptions_skip_request_queue
+    # The number of redemptions redeemed during the current live stream.
+    # The number counts against the `max_per_stream_setting` limit.
+    # This field is `nil` if the broadcaster’s stream isn’t live
+    # or `max_per_stream_setting` isn’t enabled.
+    attr_reader :redemptions_redeemed_current_stream
+    # The timestamp of when the cooldown period expires.
+    # Is `nil` if the reward isn’t in a cooldown state.
+    # See the `global_cooldown_setting` field.
+    attr_reader :cooldown_expires_at
+
+    IMAGE_ATTRS = %w[image default_image].freeze
+    private_constant :IMAGE_ATTRS
+
+    def initialize(attributes = {})
+      attributes.each do |key, value|
+        value = CustomRewardImage.new(value) if IMAGE_ATTRS.include?(key) && !value.nil?
+
+        instance_variable_set "@#{key}", value
+      end
+    end
+  end
+end

data/lib/twitch/editor.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Twitch
+  ## A user who can edit broadcast content, settings, etc.
+  class Editor
+    ## An ID that uniquely identifies a user with editor permissions.
+    attr_reader :user_id
+
+    ## The user’s display name.
+    attr_reader :user_name
+
+    ## The date and time when the user became one of the broadcaster’s editors.
+    attr_reader :created_at
+
+    def initialize(attributes = {})
+      attributes.each do |key, value|
+        instance_variable_set "@#{key}", value
+      end
+    end
+  end
+end

data/lib/twitch/entitlement_grant_url.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Twitch
   # A URL that can be used to notify users of an entitlement.
   class EntitlementGrantUrl
@@ -8,6 +10,5 @@ module Twitch
     def initialize(attributes = {})
       @url = attributes['url']
     end
-    
   end
-end
+end

data/lib/twitch/extension.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module Twitch
+  # A feature used to augment dynamic information on a stream.
+  class Extension
+    # ID of the extension.
+    attr_reader :id
+    # Version number of the extension.
+    attr_reader :version
+    # Name of the extension.
+    attr_reader :name
+    # Whether the extension is configured such that it can be activated.
+    attr_reader :can_activate
+    # The extension types that you can activate for this extension. Possible values are:
+    # `component`, `mobile`, `overlay`, `panel`
+    attr_reader :type
+
+    # Optional attributes for extensions from `get` methods results
+
+    # A Boolean value that determines the extension’s activation state.
+    # If false, the user has not configured this component extension.
+    attr_reader :active
+
+    # Optional attributes for extensions with `component` type
+
+    # The x-coordinate where the extension is placed.
+    attr_reader :x
+    # The y-coordinate where the extension is placed.
+    attr_reader :y
+
+    def initialize(attributes = {})
+      attributes.each do |key, value|
+        instance_variable_set "@#{key}", value
+      end
+    end
+  end
+end

data/lib/twitch/extensions_by_types.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Twitch
+  # A dictionary (Hash) of Extensions by their types and placements
+  class ExtensionsByTypes
+    # A dictionary that contains the data for a panel extension.
+    # The dictionary’s key is a sequential number beginning with 1.
+    # The following fields contain the panel’s data for each key.
+    attr_reader :panel
+
+    # A dictionary that contains the data for a video-overlay extension.
+    # The dictionary’s key is a sequential number beginning with 1.
+    # The following fields contain the overlay’s data for each key.
+    attr_reader :overlay
+
+    # A dictionary that contains the data for a video-component extension.
+    # The dictionary’s key is a sequential number beginning with 1.
+    # The following fields contain the component’s data for each key.
+    attr_reader :component
+
+    def initialize(attributes = {})
+      %w[panel overlay component].each do |type|
+        instance_variable_set(
+          "@#{type}",
+          attributes[type].transform_values do |extension_data|
+            Extension.new(extension_data)
+          end
+        )
+      end
+    end
+  end
+end

data/lib/twitch/game.rb

@@ -1,5 +1,7 @@
+# frozen_string_literal: true
+
 module Twitch
-  # A filterable category for a stream.  
+  # A filterable category for a stream.
   # (not necessarily limited to games, e.g. 'IRL')
   class Game
     # ID of the game.
@@ -8,7 +10,7 @@ module Twitch
     attr_reader :name
     # Box art URL template.
     #
-    # Substitute the {width} and {height} string tokens 
+    # Substitute the {width} and {height} string tokens
     # with your desired numeric values.
     attr_reader :box_art_url
 

data/lib/twitch/game_analytic.rb

@@ -1,5 +1,7 @@
+# frozen_string_literal: true
+
 module Twitch
-  # A 
+  # Data object for `/analytics/games` requests
   class GameAnalytic
     # ID of the game requested.
     attr_reader :game_id
@@ -11,4 +13,4 @@ module Twitch
       @url = attributes['URL']
     end
   end
-end
+end

data/lib/twitch/moderation_event.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Twitch
+  # Information about a moderation action.
+  # The action is determined based on the `event_type` field.
+  class ModerationEvent
+    # Fields to be converted from ISO 8601 string to a typed date.
+    DATE_ATTRIBUTES = %i[event_timestamp].freeze
+
+    # ID of the moderation event.
+    attr_reader :id
+    # Event type.
+    # The `moderation.user` prefix is for user bans and unbans in a channel.
+    # The `moderation.moderator` prefix is for addition and removal of moderators in a channel.
+    attr_reader :event_type
+    # Time at which the event happened.
+    attr_reader :event_timestamp
+    # Version of the endpoint the data was retrieved from.
+    attr_reader :version
+    # A hash containing information about the moderation action.
+    attr_reader :event_data
+
+    def initialize(attributes = {})
+      attributes.each do |key, value|
+        if DATE_ATTRIBUTES.include?(key.to_sym)
+          instance_variable_set "@#{key}", Time.parse(value)
+        else
+          instance_variable_set "@#{key}", value
+        end
+      end
+    end
+  end
+end

data/lib/twitch/moderator.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Twitch
+  # A user who wields some form of power in a broadcaster's Twitch chat.
+  # This is simply a user ID/name pair.
+  class Moderator
+    # User ID of the moderator.
+    attr_reader :user_id
+    # The user’s login name.
+    attr_reader :user_login
+    # The user’s display name.
+    attr_reader :user_name
+
+    def initialize(attributes = {})
+      attributes.each do |key, value|
+        instance_variable_set "@#{key}", value
+      end
+    end
+  end
+end

data/lib/twitch/redemption.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Twitch
+  # Data object for Twitch users
+  class Redemption
+    # ID of the broadcaster.
+    attr_reader :broadcaster_id
+    # Unformatted (lowercase) username of thebroadcaster.
+    attr_reader :broadcaster_login
+    # Formatted username of the broadcaster.
+    attr_reader :broadcaster_display_name
+    # ID of the redemption.
+    attr_reader :id
+    # ID of the user.
+    attr_reader :user_id
+    # Unformatted (lowercase) username of the user.
+    attr_reader :user_login
+    # Formatted username of the user.
+    attr_reader :user_name
+    # The associated reward being redeemed
+    attr_reader :reward
+    # The user input (e.g. text) if allowed by the reward
+    attr_reader :user_input
+    # The status of the redemption's fulfillment
+    attr_reader :status
+    # The timestamp of the redemption
+    attr_reader :redeemed_at
+
+    def initialize(attributes = {})
+      attributes.each do |key, value|
+        instance_variable_set "@#{key}", value
+      end
+    end
+  end
+end