twitch-api 0.3.0 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 13fa554e6376acacd400d0aad2e651d295c613297df4476ba7c1736b6e7640aa
-  data.tar.gz: 6e180eab8e7061535821922cbc6ad4c4b35e867096314a7ddf564704ea32882c
+  metadata.gz: bda514f18997d369233835dd22a840f0c0ba884af5371d10ce553381a672aa97
+  data.tar.gz: 87efa1511f0e9346e87190570e6cd0745b89daffbaef04359d7e7fb283523b67
 SHA512:
-  metadata.gz: 7b45c4f07f653c77e3058579dac055efbcb2b1664fe1c68f63caf3715bfd8471a318bacc2d6ec49f072d0fee7686b7d72313c939e26c0e8a8bbd888137611e1a
-  data.tar.gz: c29bf47c2020a2b2617d1f6a54b7fda59b0544c165c5787fcbba92963dc11eeaeee2149640e8bbcaa86a4b1eca7551050d82d40ca1d6657543c8647f511f4a40
+  metadata.gz: 638a7c88c04b0aaef5e6b17e0005ca75c312bac9a5140eaaee09e3e522d6df6ceba93c79d226ae2a255ebf7c1602b6cb3ea2335cf7bd6f7491c8ac134b9f3064
+  data.tar.gz: 9305290bf8b6103a0ed2497c0bc39616d919b0939763cea47e3d08c8941d44638e59a0ab93f1ff95b008f1dd32a0ffaa032d487270ddf0624ae1d25952f7d587

data/README.md

@@ -1,28 +1,32 @@
 [![Gem](https://img.shields.io/gem/v/twitch-api.svg)](https://rubygems.org/gems/twitch-api)
 [![Downloads](https://img.shields.io/gem/dt/twitch-api.svg)](https://rubygems.org/gems/twitch-api)
-[![Travis](https://img.shields.io/travis/mauricew/ruby-twitch-api.svg)](https://travis-ci.org/mauricew/ruby-twitch-api)
-[![License](https://img.shields.io/github/license/mauricew/ruby-twitch-api.svg)]()
+[![Cirrus CI - Base Branch Build Status](https://img.shields.io/cirrus/github/mauricew/ruby-twitch-api)](https://cirrus-ci.com/github/mauricew/ruby-twitch-api)
+[![License](https://img.shields.io/github/license/mauricew/ruby-twitch-api.svg)](LICENSE.txt)
+
 # Ruby Twitch API
 
 This library is a Ruby implementation of the [Twitch Helix API](https://dev.twitch.tv/docs/api).
 
-The goal is to provide access for the newest supported APIs provided by Twitch, while keeping extensiblity for their future expansion. These are still in development, as is this library which should remain in pace with changes made.
+The goal is to provide access for the newest supported APIs provided by Twitch,
+while keeping extensibility for their future expansion.
+These are still in development, as is this library which should remain in pace with changes made.
 
 Guaranteed supported APIs include:
-* Helix REST (full rolling support)
-* Helix Webhooks (coming soon)
+
+*   Helix REST (full rolling support)
+*   Helix Webhooks (coming soon)
 
 The future may bring:
-* Authentication
-* PubSub
-* TMI/chat
+
+*   PubSub
 
 These will not be considered:
-* Twitch kraken API
-* [Twitch GraphQL API](https://github.com/mauricew/twitch-graphql-api)
+
+*   [Twitch Kraken API](https://github.com/dustinlakin/twitch-rb)
+*   [Twitch GraphQL API](https://github.com/mauricew/twitch-graphql-api)
+*   [Twitch Chat (IRC/TMI)](https://github.com/EnotPoloskun/twitch-chat)
 
 ## Installation
-Ruby 2.1 or later compatibility is guaranteed, however the target is 2.0 and above.
 
 Add to your application's Gemfile:
 
@@ -35,27 +39,124 @@ gem 'twitch-api', :git => 'https://github.com/mauricew/ruby-twitch-api'
 
 And then execute:
 
-    $ bundle
+```sh
+$ bundle
+```
 
 Or install it yourself as:
 
-    $ gem install twitch-api
+```sh
+$ gem install twitch-api
+```
 
 ## Usage
-A client must be initialized with your client ID or bearer access token.
+
+### Authentication
+
+[Twitch documentation](https://dev.twitch.tv/docs/authentication).
+
+This gem uses [`twitch_oauth2` gem](https://github.com/AlexWayfer/twitch_oauth2)
+for authorization and authentication, you can read more detailed documentation there
+(but it's pretty simple).
+
+The goal is in an object with credentials and re-using it between different gems,
+for example for API and for chat, or for the old API and the new one.
+Also a logic for tokens validation and refreshing is encapsulated in it.
+
+One of references is [this JavaScript set of libraries](https://github.com/d-fischer/twitch).
+
+#### Client (application) flow
+
+This is easier flow with limited (non-personal) access.
+
+```ruby
+tokens = TwitchOAuth2::Tokens.new(
+  client: {
+    client_id: client_id,
+    client_secret: client_secret
+  },
+
+  ## this is default
+  # token_type: :application,
+
+  ## this can be required by some Twitch end-points
+  # scopes: scopes,
+
+  ## if you already have ones
+  # access_token: access_token
+)
+
+twitch_client = Twitch::Client.new(tokens: tokens)
 ```
-client = Twitch::Client.new(client_id: "YOUR_CLIENT_ID")
-# or
-client = Twitch::Client.new(access_token: "YOUR_ACCESS_TOKEN")
+
+#### Authorization (user) flow
+
+This is flow required for user-specific actions.
+
+If there are no `access_token` and `refresh_token` in `:tokens`,
+`TwitchOAuth2::AuthorizeError` will be raised with `#link`.
+
+If you have a web-application with N users, you can redirect them to this link
+and use `redirect_uri` to your application for callbacks.
+
+Otherwise, if you have something like CLI tool, you can print instructions with a link for user.
+
+Then you can use `tokens.code = 'a code from params in redirect uri'`
+and it'll store new `:access_token` and `:refresh_token`.
+
+```ruby
+tokens = TwitchOAuth2::Tokens.new(
+  client: {
+    client_id: client_id,
+    client_secret: client_secret,
+
+    ## `localhost` by default, can be your application end-point
+    # redirect_uri: redirect_uri
+  },
+
+  token_type: :user,
+
+  ## this can be required by some Twitch end-points
+  # scopes: scopes,
+
+  ## if you already have these
+  # access_token: access_token,
+  # refresh_token: refresh_token
+)
+
+twitch_client = Twitch::Client.new(tokens: tokens)
 ```
-Because data may change for certain endpoints, there is also a keyword parameter called `with_raw` that returns the raw response for any request called.
 
-Retrieval methods take in a hash equal to the parameters of the API endpoint, and return a response object containing the data and other associated request information:
-* **data** is the data you would get back. Even if it's an array of one object, it remains the same as what comes from the API.
-* **rate_limit** and associated fields contain API request limit information. Clip creation counts for a second limit (duration currently unknown).
-* **pagination** is a hash that appears when data can be traversed, and contains one member (*cursor*) which lets you pagniate through certain requests.
-* **raw** is the raw HTTP response data when `with_raw` is true in the client.
+#### After initialization
+
+If you've passed `refresh_token` to initialization and your `access_token` is invalid,
+requests that require `access_token` will automatically refresh it.
+
+You can access tokens:
+
+```ruby
+twitch_client.tokens # => `TwitchOAuth2::Tokens` instance
+twitch_client.tokens.access_token # => 'abcdef'
+twitch_client.tokens.refresh_token # => 'ghijkl'
 ```
+
+### Calls
+
+Because data may change for certain endpoints, there is also the raw response
+for any request called.
+
+Retrieval methods take in a hash equal to the parameters of the API endpoint,
+and return a response object containing the data and other associated request information:
+
+*   **data** is the data you would get back. Even if it's an array of one object,
+    it remains the same as what comes from the API.
+*   **rate_limit** and associated fields contain API request limit information.
+    Clip creation counts for a second limit (duration currently unknown).
+*   **pagination** is a hash that appears when data can be traversed,
+    and contains one member (*cursor*) which lets you paginate through certain requests.
+*   **raw** is the raw HTTP response data.
+
+```ruby
 # Get top live streams
 client.get_streams.data
 # Get a single user
@@ -66,12 +167,15 @@ client.get_games({name: ["Heroes of the Storm", "Super Mario Odyssey"]}).data
 ```
 
 ### Error handling
-An *ApiError* is raised whenever an HTTP error response is returned.
+
+An `APIError` is raised whenever an HTTP error response is returned.
 Rescue it to access the body of the response, which should include an error message.
 
 ## Development
 
-After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. (Tests require a Twitch Client ID; since cassettes exist you can use any value.)
+After checking out the repo, run `bin/setup` to install dependencies.
+Then, run `rake spec` to run the tests.
+(Tests require a Twitch Client ID; since cassettes exist you can use any value.)
 
 You can also run `bin/console` for an interactive prompt that will allow you to experiment.
 
@@ -79,4 +183,4 @@ To install this gem onto your local machine, run `bundle exec rake install`.
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/mauricew/ruby-twitch-api.
+Bug reports and pull requests are welcome on [GitHub](https://github.com/mauricew/ruby-twitch-api).

data/lib/twitch/api_error.rb

@@ -1,6 +1,8 @@
+# frozen_string_literal: true
+
 module Twitch
   # An error returned by the API.
-  class ApiError < StandardError
+  class APIError < StandardError
     # HTTP status code of the response.
     attr_reader :status_code
     # Body content of the response.
@@ -10,8 +12,7 @@ module Twitch
       @status_code = status_code
       @body = body
 
-      msg = "The server returned error #{status_code}"
-      super(msg)
+      super self.body['message']
     end
   end
-end
+end

data/lib/twitch/automod_message_status.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Twitch
+  # A determination if AutoMod would allow a message in a particular channel's chat.
+  class AutomodMessageStatus
+    # ID of the message. Matches the field of the same name passed in the request.
+    attr_reader :msg_id
+    # Whether the message would meet AutoMod requirements for the channel.
+    attr_reader :is_permitted
+
+    def initialize(attributes = {})
+      attributes.each do |key, value|
+        instance_variable_set "@#{key}", value
+      end
+    end
+  end
+end

data/lib/twitch/bits_leader.rb

@@ -1,8 +1,12 @@
+# frozen_string_literal: true
+
 module Twitch
   # A user that is a leader for bits.
   class BitsLeader
     # ID of the user giving bits.
     attr_reader :user_id
+    # Display name of the user giving bits.
+    attr_reader :user_name
     # Ranking of the user giving bits.
     # Reflects the parent object's date range.
     attr_reader :rank
@@ -11,8 +15,9 @@ module Twitch
 
     def initialize(attributes = {})
       @user_id = attributes['user_id']
+      @user_name = attributes['user_name']
       @rank = attributes['rank']
       @score = attributes['score']
     end
   end
-end
+end

data/lib/twitch/category.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Twitch
+  ## Data class for categories
+  class Category
+    ## A URL to an image of the game’s box art or streaming category.
+    attr_reader :box_art_url
+
+    ## The name of the game or category.
+    attr_reader :name
+
+    ## 	An ID that uniquely identifies the game or category.
+    attr_reader :id
+
+    ## Not always available:
+
+    ## The ID that IGDB uses to identify this game.
+    ## If the IGDB ID is not available to Twitch, this field is set to an empty string.
+    attr_reader :igdb_id
+
+    def initialize(attributes = {})
+      attributes.each do |key, value|
+        instance_variable_set "@#{key}", value
+      end
+    end
+  end
+end

data/lib/twitch/channel.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module Twitch
+  # Data object for Twitch channels
+  # https://dev.twitch.tv/docs/api/reference#get-channel-information
+  class Channel
+    # Twitch User ID of this channel owner.
+    attr_reader :broadcaster_id
+    # Broadcaster's user login name.
+    attr_reader :broadcaster_login
+    # Twitch user display name of this channel owner.
+    attr_reader :broadcaster_name
+    # Language of the channel.
+    # A language value is either the ISO 639-1 two-letter code for a supported stream language
+    # or "other".
+    attr_reader :broadcaster_language
+    # Current game ID being played on the channel .
+    attr_reader :game_id
+    # Name of the game being played on the channel.
+    attr_reader :game_name
+    # Title of the stream.
+    attr_reader :title
+    # Stream delay in seconds.
+    attr_reader :delay
+
+    # Some endpoints, like "Search Channels", can return different fields
+    attr_reader :id
+    attr_reader :display_name
+    # A Boolean value that determines whether the broadcaster is streaming live.
+    # Is true if the broadcaster is streaming live; otherwise, false.
+    attr_reader :is_live
+    # The tags applied to the channel.
+    attr_reader :tags
+    # A URL to a thumbnail of the broadcaster’s profile image.
+    attr_reader :thumbnail_url
+    # The UTC date and time (in RFC3339 format) of when the broadcaster started streaming.
+    # The string is empty if the broadcaster is not streaming live.
+    attr_reader :started_at
+
+    def initialize(attributes = {})
+      attributes.each do |key, value|
+        instance_variable_set "@#{key}", value
+      end
+    end
+  end
+end

data/lib/twitch/cheermote.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+require_relative 'cheermote_tier'
+
+module Twitch
+  ## Data class for Cheermotes, animated emotes that viewers can assign Bits to.
+  class Cheermote
+    ## The name portion of the Cheermote string that you use in chat to cheer Bits.
+    ## The full Cheermote string is the concatenation of {prefix} + {number of Bits}.
+    ## For example, if the prefix is “Cheer” and you want to cheer 100 Bits,
+    ## the full Cheermote string is Cheer100.
+    ## When the Cheermote string is entered in chat,
+    ## Twitch converts it to the image associated with the Bits tier that was cheered.
+    attr_reader :prefix
+
+    ## A list of tier levels that the Cheermote supports.
+    ## Each tier identifies the range of Bits that you can cheer at that tier level
+    ## and an image that graphically identifies the tier level.
+    attr_reader :tiers
+
+    ## The type of Cheermote. Possible values are:
+    ## * global_first_party — A Twitch-defined Cheermote that is shown in the Bits card.
+    ## * global_third_party — A Twitch-defined Cheermote that is not shown in the Bits card.
+    ## * channel_custom — A broadcaster-defined Cheermote.
+    ## * display_only — Do not use; for internal use only.
+    ## * sponsored — A sponsor-defined Cheermote.
+    ##   When used, the sponsor adds additional Bits to the amount that the user cheered.
+    ##   For example, if the user cheered Terminator100, the broadcaster might receive 110 Bits,
+    ##   which includes the sponsor's 10 Bits contribution.
+    attr_reader :type
+
+    ## The order that the Cheermotes are shown in the Bits card.
+    ## The numbers may not be consecutive. For example, the numbers may jump from 1 to 7 to 13.
+    ## The order numbers are unique within a Cheermote type (for example, global_first_party)
+    ## but may not be unique amongst all Cheermotes in the response.
+    attr_reader :order
+
+    ## The date and time when this Cheermote was last updated.
+    attr_reader :last_updated
+
+    ## A Boolean value that indicates whether this Cheermote provides
+    ## a charitable contribution match during charity campaigns.
+    attr_reader :is_charitable
+
+    def initialize(attributes = {})
+      attributes.each do |key, value|
+        value = value.map { |tier| CheermoteTier.new(tier) } if key == 'tiers'
+
+        instance_variable_set "@#{key}", value
+      end
+    end
+  end
+end

data/lib/twitch/cheermote_tier.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+require_relative 'cheermote_tier_images'
+
+module Twitch
+  ## Data class for Cheermote Tier.
+  ## Each tier identifies the range of Bits that you can cheer at that tier level
+  ## and an image that graphically identifies the tier level.
+  class CheermoteTier
+    ## The minimum number of Bits that you must cheer at this tier level.
+    ## The maximum number of Bits that you can cheer at this level
+    ## is determined by the required minimum Bits of the next tier level minus 1.
+    ## For example, if `min_bits` is 1 and `min_bits` for the next tier is 100,
+    ## the Bits range for this tier level is 1 through 99.
+    ## The minimum Bits value of the last tier is the maximum number of Bits you can cheer
+    ## using this Cheermote. For example, 10000.
+    attr_reader :min_bits
+
+    ## 	The tier level. Possible tiers are:
+    ## * 1
+    ## * 100
+    ## * 500
+    ## * 1000
+    ## * 5000
+    ## * 10000
+    ## * 100000
+    attr_reader :id
+
+    ## The hex code of the color associated with this tier level (for example, `#979797`).
+    attr_reader :color
+
+    ## The animated and static image sets for the Cheermote.
+    ## The dictionary of images is organized by theme, format, and size.
+    ## The theme keys are `dark` and `light`.
+    ## Each theme is a dictionary of formats: `animated` and `static`.
+    ## Each format is a dictionary of sizes: `1`, `1.5`, `2`, `3`, and `4`.
+    ## The value of each size contains the URL to the image.
+    attr_reader :images
+
+    ## A Boolean value that determines whether users can cheer at this tier level.
+    attr_reader :can_cheer
+
+    ## A Boolean value that determines whether this tier level is shown in the Bits card.
+    ## Is `true` if this tier level is shown in the Bits card.
+    attr_reader :show_in_bits_card
+
+    def initialize(attributes = {})
+      attributes.each do |key, value|
+        value = CheermoteTierImages.new(value) if key == 'images'
+
+        instance_variable_set "@#{key}", value
+      end
+    end
+  end
+end

data/lib/twitch/cheermote_tier_image.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Twitch
+  ## Data class for Cheermote Tier image, static and animated
+  class CheermoteTierImage
+    ## Each theme is a dictionary of formats: `animated` and `static`.
+    ## Each format is a dictionary of sizes: `1`, `1.5`, `2`, `3`, and `4`.
+    ## The value of each size contains the URL to the image.
+    attr_reader :animated
+    attr_reader :static
+
+    def initialize(attributes = {})
+      attributes.each do |key, value|
+        instance_variable_set "@#{key}", value
+      end
+    end
+  end
+end

data/lib/twitch/cheermote_tier_images.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require_relative 'cheermote_tier_image'
+
+module Twitch
+  ## Data class for Cheermote Tier images by themes
+  class CheermoteTierImages
+    ## The theme keys are `dark` and `light`.
+    ## Each theme is a dictionary of formats: `animated` and `static`.
+    ## Each format is a dictionary of sizes: `1`, `1.5`, `2`, `3`, and `4`.
+    ## The value of each size contains the URL to the image.
+    attr_reader :dark
+    attr_reader :light
+
+    def initialize(attributes = {})
+      attributes.each do |key, value|
+        instance_variable_set "@#{key}", CheermoteTierImage.new(value)
+      end
+    end
+  end
+end

data/lib/twitch/client/custom_rewards.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Twitch
+  class Client
+    ## API methods for custom rewards
+    module CustomRewards
+      def create_custom_reward(options = {})
+        initialize_response CustomReward, post('channel_points/custom_rewards', options)
+      end
+
+      def get_custom_reward(options = {})
+        initialize_response CustomReward, get('channel_points/custom_rewards', options)
+      end
+
+      def delete_custom_reward(options = {})
+        initialize_response CustomReward, delete('channel_points/custom_rewards', options)
+      end
+
+      def get_custom_reward_redemption(options = {})
+        initialize_response CustomReward, get('channel_points/custom_rewards/redemptions', options)
+      end
+
+      def update_custom_reward(options = {})
+        initialize_response CustomReward, patch('channel_points/custom_rewards', options)
+      end
+
+      def update_redemption_status(options = {})
+        initialize_response(
+          CustomReward,
+          patch('channel_points/custom_rewards/redemptions', options)
+        )
+      end
+    end
+  end
+end

data/lib/twitch/client/extensions.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Twitch
+  class Client
+    # API methods for extensions
+    module Extensions
+      def get_user_extensions(options = {})
+        initialize_response Extension, get('users/extensions/list', options)
+      end
+
+      def get_user_active_extensions(options = {})
+        initialize_response ExtensionsByTypes, get('users/extensions', options)
+      end
+
+      def update_user_extensions(options = {})
+        initialize_response ExtensionsByTypes, put('users/extensions', options)
+      end
+    end
+  end
+end

data/lib/twitch/client/games.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Twitch
+  class Client
+    ## API method for games
+    module Games
+      def get_games(options = {})
+        initialize_response Game, get('games', options)
+      end
+
+      def get_top_games(options = {})
+        initialize_response Game, get('games/top', options)
+      end
+
+      def get_game_analytics(options = {})
+        initialize_response GameAnalytic, get('analytics/games', options)
+      end
+    end
+  end
+end

data/lib/twitch/client/moderation.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Twitch
+  class Client
+    # API methods for stream moderation
+    module Moderation
+      def check_automod_status(options = {})
+        initialize_response AutomodMessageStatus, post('moderation/enforcements/status', options)
+      end
+
+      def get_banned_events(options = {})
+        initialize_response ModerationEvent, get('moderation/banned/events', options)
+      end
+
+      def get_banned_users(options = {})
+        initialize_response UserBan, get('moderation/banned', options)
+      end
+
+      def get_moderators(options = {})
+        initialize_response Moderator, get('moderation/moderators', options)
+      end
+
+      def get_moderator_events(options = {})
+        initialize_response ModerationEvent, get('moderation/moderators/events', options)
+      end
+    end
+  end
+end

data/lib/twitch/client/streams.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Twitch
+  class Client
+    ## API method for streams
+    module Streams
+      def create_stream_marker(options = {})
+        initialize_response StreamMarker, post('streams/markers', options)
+      end
+
+      def get_stream_markers(options = {})
+        initialize_response StreamMarkerResponse, get('streams/markers', options)
+      end
+
+      def get_streams(options = {})
+        initialize_response Stream, get('streams', options)
+      end
+
+      ## TODO: Can't find this method in documentation, test it
+      def get_streams_metadata(options = {})
+        initialize_response StreamMetadata, get('streams/metadata', options)
+      end
+
+      def get_stream_key(options = {})
+        initialize_response nil, get('streams/key', options)
+      end
+    end
+  end
+end

data/lib/twitch/client/subscriptions.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module Twitch
+  class Client
+    # API methods for subscriptions
+    module Subscriptions
+      def get_broadcaster_subscription(options = {})
+        initialize_response Subscription, post('subscriptions', options)
+      end
+    end
+  end
+end

data/lib/twitch/client/users.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Twitch
+  class Client
+    ## API method for users
+    module Users
+      def get_users_follows(options = {})
+        initialize_response UserFollow, get('users/follows', options)
+      end
+
+      def get_users(options = {})
+        initialize_response User, get('users', options)
+      end
+
+      def update_user(options = {})
+        initialize_response User, put('users', options)
+      end
+    end
+  end
+end