twitch-api 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: eb54134c100870a945316675e056f7c32c0cd67ea354d19bfba277d7a1660fb1
-  data.tar.gz: 4fa7aff219b7993eb679d7444e7ebd35d309923d3ffcc52daa5d3130ec2ce6b7
+  metadata.gz: 496abaceb2ef84dbd33eee192a05daf8270d9c77c373ba6beadaf915bb1cf426
+  data.tar.gz: 66a591c5e4c176fab22c198b907020a31dffd2499c7d95cada41e0cd53feb7f1
 SHA512:
-  metadata.gz: 8a8429635b999c142b06996ed11ff36d35b10dac4ed68d255bd6eefd9341e3360f13e3d8c1b8ce8ac303efccde1ff48fdba9f613396971ffeef7129b28af8680
-  data.tar.gz: 51b75f09e9df2d67045e0c9b8e32f707425156641066789b6544e8384cc2b20cc532a274c698a30b5e2ae5e49f2269f5b920b67e58676642fdbf6705db9a2488
+  metadata.gz: c9a8bc3775456383bfa0162aff51fc62d35374dcd8fe355b46ec3fb0fe5733fe0164319a3fc1fd0487df2043aae49a8d5e9976f01bddc59572ea6a3e24028c9f
+  data.tar.gz: b5498b3112dfb9d61a64f04780a46d3aa895ba827b38074739f1b7c4dbdc31d9f4b1687c1c277e3b131a556f9848df65ff47193d7582f08af13fcf0f8e25b34b

data/README.md

@@ -1,14 +1,31 @@
-# Ruby Twitch API (work in progress)
+# 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.
+
+Guaranteed supported APIs include:
+* Helix REST (full rolling support)
+* Helix Webhooks (coming soon)
+
+The future may bring:
+* PubSub
+* TMI/chat
+
+These will not be considered:
+* Twitch kraken API
+* [Twitch GraphQL API](https://github.com/mauricew/twitch-graphql-api)
+
 ## Installation
-Ruby 2.1 or later is required.
+Ruby 2.1 or later compatibility is guaranteed, however the target is 2.0 and above.
 
-Add this line to your application's Gemfile:
+Add to your application's Gemfile:
 
 ```ruby
+# If you want a full release
 gem 'twitch-api'
+# If you want to live on the edge
+gem 'twitch-api', :git => 'https://github.com/mauricew/ruby-twitch-api'
 ```
 
 And then execute:
@@ -20,14 +37,16 @@ Or install it yourself as:
     $ gem install twitch-api
 
 ## Usage
-A client must be initialized with your client ID, and optionally an OAuth access token.
+A client must be initialized with your client ID or bearer access token.
 ```
 client = Twitch::Client.new client_id: "YOUR_CLIENT_ID"
+# or
+client = Twitch::Client.new access_token: "YOUR_ACCESS_TOKEN"
 ```
-The retrieval methods take in a hash equal to the GET 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
-* **rate_limit** contains the number of API requests that can be made in total within a 60-second window. See **rate_limit_remaining** and  **rate_limit_resets_at** to determine the current allowed rate.
-* **pagination** (optional) is an hash that usually contains one member (*cursor*) which lets you pagniate through certain requests.
+The 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 an hash that appears when data can be traversed, and contains one member (*cursor*) which lets you pagniate through certain requests.
 ```
 # Get top live streams
 client.get_streams.data
@@ -38,9 +57,15 @@ client.get_users({login: "disguisedtoasths"}).data.first
 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.
+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. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+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.
 
 To install this gem onto your local machine, run `bundle exec rake install`.
 

data/lib/twitch/api_error.rb

@@ -1,6 +1,10 @@
 module Twitch
+  # An error returned by the API.
   class ApiError < StandardError
-    attr_reader :status_code, :body
+    # HTTP status code of the response.
+    attr_reader :status_code
+    # Body content of the response.
+    attr_reader :body
 
     def initialize(status_code, body)
       @status_code = status_code

data/lib/twitch/client.rb

@@ -3,34 +3,74 @@ require "faraday_middleware"
 
 require "twitch/response"
 require "twitch/api_error"
+require "twitch/clip"
+require "twitch/entitlement_grant_url"
+require "twitch/game"
 require "twitch/stream"
 require "twitch/stream_metadata"
 require "twitch/user"
 require "twitch/user_follow"
-require "twitch/game"
 require "twitch/video"
 
 module Twitch
   class Client
+    # Helix API endpoint.
     API_ENDPOINT = "https://api.twitch.tv/helix".freeze
 
+    # 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.
     def initialize(client_id: nil, access_token: nil)
-      raise "Client ID is required" if client_id.nil?
-      
+      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
+
       headers = {
-        "Client-ID": client_id,
         "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
     end
 
+    def create_clip(options = {})
+      res = post('clips', options)
+
+      clip = res[:data].map { |c| Clip.new(c) }
+      Response.new(clip, res[:rate_limit_headers])
+    end
+
+    def create_entitlement_grant_url(options = {})
+      res = post('entitlements/upload', options)
+
+      entitlement_grant = res[:data].map { |e| EntitlementGrantUrl.new(e) }
+      Response.new(entitlement_grant, res[:rate_limit_headers])
+    end
+
+    def get_clips(options = {})
+      res = get('clips', options)
+
+      clips = res[:data].map { |c| Clip.new(c) }
+      Response.new(clips, res[:rate_limit_headers])
+    end
 
     def get_games(options = {})
       res = get('games', options)
@@ -39,6 +79,13 @@ module Twitch
       Response.new(games, res[:rate_limit_headers])
     end
 
+    def get_top_games(options = {})
+      res = get('games/top', options)
+
+      games = res[:data].map { |g| Game.new(g) }
+      Response.new(games, res[:rate_limit_headers], res[:pagination])
+    end
+
     def get_streams(options = {})
       res = get('streams', options)
 
@@ -67,6 +114,13 @@ module Twitch
       Response.new(users, res[:rate_limit_headers])
     end
 
+    def update_user(options = {})
+      res = put('users', options)
+
+      user = res[:data].map { |u| User.new(u) }
+      Response.new(user, res[:rate_limit_headers])
+    end
+
     def get_videos(options = {})
       res = get('videos', options)
 
@@ -78,16 +132,31 @@ module Twitch
 
       def get(resource, params)
         http_res = @conn.get(resource, params)
+        finish(http_res)
+      end
+
+      def post(resource, params)
+        http_res = @conn.post(resource, params)
+        finish(http_res)
+      end
 
+      def put(resource, params)
+        http_res = @conn.put(resource, params)
+        finish(http_res)
+      end
+
+      def finish(http_res)
         unless http_res.success?
           raise ApiError.new(http_res.status, http_res.body)
         end
 
-        rate_limit_headers = Hash[http_res.headers.select { |k,v|
+        rate_limit_headers = Hash[http_res.headers.select do |k,v|
           k.to_s.downcase.match(/^ratelimit/)
-        }.map { |k,v| [k.gsub('ratelimit-', '').to_sym, v] }]
+        end.map { |k,v| [k.gsub('ratelimit-', '').to_sym, v] }]
 
-        pagination = http_res.body['pagination'] if http_res.body.key?('pagination')
+        if http_res.body.key?('pagination')
+          pagination = http_res.body['pagination'] 
+        end
 
         { 
           data: http_res.body['data'],

data/lib/twitch/clip.rb

@@ -0,0 +1,43 @@
+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.
+    attr_reader :title
+    # Date the clip was created.
+    attr_reader :created_at
+    # URL of the clip.
+    attr_reader :url
+    # URL of the thumbnail image.
+    attr_reader :thumbnail_url
+    # URL for embedding the clip.
+    attr_reader :embed_url
+    # Number of views.
+    attr_reader :view_count
+    # Language of the originating broadcast.
+    attr_reader :language
+    # (User) ID of the clip's source broadcast.
+    attr_reader :broadcaster_id
+    # (User) ID of the clip's creator.
+    attr_reader :creator_id
+    # ID of the game being played.
+    attr_reader :game_id
+    # ID of the archived broadcast (may not be available).
+    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
+      end
+    end
+    
+  end
+end

data/lib/twitch/entitlement_grant_url.rb

@@ -0,0 +1,13 @@
+module Twitch
+  # A URL that can be used to notify users of an entitlement.
+  class EntitlementGrantUrl
+    # The URL to upload an entitlement manifest.
+    # See the Twitch API documentation on how to use this.
+    attr_reader :url
+
+    def initialize(attributes = {})
+      @url = attributes['url']
+    end
+    
+  end
+end

data/lib/twitch/game.rb

@@ -1,11 +1,21 @@
 module Twitch
+  # A filterable category for a stream.  
+  # (not necessarily limited to games, e.g. 'IRL')
   class Game
-    attr_reader :id, :name, :box_art_url
+    # ID of the game.
+    attr_reader :id
+    # Name of the game
+    attr_reader :name
+    # Box art URL template.
+    #
+    # Substitute the {width} and {height} string tokens 
+    # with your desired numeric values.
+    attr_reader :box_art_url
 
     def initialize(attributes = {})
       @id = attributes['id']
       @name = attributes['name']
-      @box_art_url = attributes['name']
+      @box_art_url = attributes['box_art_url']
     end
   end
 end

data/lib/twitch/response.rb

@@ -1,6 +1,25 @@
 module Twitch
+  # A compiled response from the API.
   class Response
-    attr_reader :data, :pagination,  :rate_limit, :rate_limit_remaining, :rate_limit_resets_at
+    # The requested data.
+    attr_reader :data
+    # A hash containing a pagination token.  
+    # Access it with
+    #    pagination['cursor']
+    attr_reader :pagination
+    # The total amount of calls that can be used in
+    # the rate limit period (one minute by default).
+    attr_reader :rate_limit
+    # The remaining amount of calls for the rate limit period.
+    attr_reader :rate_limit_remaining
+    # The date at which the rate limit is reset.
+    attr_reader :rate_limit_resets_at
+    # The total amount of clips that can be created in
+    # the clip rate limit period (currently unknown).
+    attr_reader :clip_rate_limit
+    # The remaining amount of clips that can be created in 
+    # the clip rate limit period. 
+    attr_reader :clip_rate_limit_remaining
 
     def initialize(data, rate_limit_headers, pagination = nil)
       @data = data
@@ -9,6 +28,11 @@ module Twitch
       @rate_limit_remaining = rate_limit_headers[:remaining].to_i
       @rate_limit_resets_at = Time.at(rate_limit_headers[:reset].to_i)
 
+      if rate_limit_headers.keys.any? { |k| k.to_s.start_with?('helixclipscreation') }
+        @clip_rate_limit = rate_limit_headers[:'helixclipscreation-limit']
+        @clip_rate_limit_remaining = rate_limit_headers[:'helixclipscreation-remaining']
+      end
+
       @pagination = pagination
     end
   end

data/lib/twitch/stream.rb

@@ -1,9 +1,33 @@
 require "time"
 
 module Twitch
+  # A user's broadcasting session.
   class Stream
-    attr_reader :id, :user_id, :game_id, :community_ids, :type, :title, :viewer_count, :started_at, :language, :thumbnail_url
+    # Fields to be converted from ISO 8601 string to a typed date.
     DATE_ATTRIBUTES = [:started_at]
+    
+    # ID of the stream.
+    attr_reader :id
+    # ID of the user broadcasting.
+    attr_reader :user_id
+    # ID of the game being broadcast.
+    attr_reader :game_id
+    # Associated community IDs for the broadcaster.
+    attr_reader :community_ids
+    # The type of broadcast
+    # which may include 'live', 'playlist', or 'watch_party'.
+    attr_reader :type
+    # Title of the stream session.
+    attr_reader :title
+    # Concurrent viewer count of the broadcast.
+    attr_reader :viewer_count
+    # Date at which the broadcast started.
+    attr_reader :started_at
+    # Language of the broadcast.
+    attr_reader :language
+    # URL of the latest thumbnail image for the broadcast.
+    attr_reader :thumbnail_url
+
 
     def initialize(attributes = {})
       attributes.each do |k, v|

data/lib/twitch/stream_metadata.rb

@@ -1,13 +1,23 @@
 module Twitch
+  # A set of metadata to provide additional information about a
+  # game being streamed.  
+  # Additional getters are assigned at initialization time, e.g.
+  #    self.hearthstone
+  # has data when Hearthstone is being streamed.  
+  # Other games may be included, but will be set to nil
+  # if they aren't the game currently being streamed.
   class StreamMetadata
-    attr_reader :user_id, :game_id
+    # ID of the streaming user.
+    attr_reader :user_id
+    # ID of the game being playead.
+    attr_reader :game_id
 
     def initialize(attributes = {})
       @user_id = attributes['user_id']
       @game_id = attributes['game_id']
 
-      # Since more games can be supported in the future, this will ensure
-      # they will all be available.
+      # Since more games can be supported in the future,
+      # this will ensure they will all be available.
       attributes.each do |k, v|
         unless instance_variables.include?("@#{k}".to_sym)
           self.class.send(:attr_reader, k.to_sym)

data/lib/twitch/user.rb

@@ -1,7 +1,26 @@
 module Twitch
   class User
-    # All fields are read-only until update support is implemented
-    attr_reader :id, :login, :display_name, :type, :broadcaster_type, :description, :profile_image_url, :offline_image_url, :view_count
+    # ID of the user.
+    attr_reader :id
+    # Unformatted (lowercase) username of the user.
+    attr_reader :login
+    # Formatted username of the user.
+    attr_reader :display_name
+    # Represents a special role of a user.
+    # (global mod, admin, staff)
+    attr_reader :type
+    # Represents a special broadcaster role of a user.
+    # (partner, affilaite)
+    attr_reader :broadcaster_type
+    # Description/biographical info of a user.
+    attr_reader :description
+    # URL to the user's profile image.
+    attr_reader :profile_image_url
+    # URL to the image displayed in the video box
+    # when the stream is offline.
+    attr_reader :offline_image_url
+    # Total number of visits to the user's stream page.
+    attr_reader :view_count
 
     def initialize(attributes = {})
       attributes.each do |k, v|

data/lib/twitch/user_follow.rb

@@ -1,6 +1,12 @@
 module Twitch
+  # Represents a relationship of one user following another.
   class UserFollow
-    attr_reader :from_id, :to_id, :followed_at
+    # User ID of the *following* user.
+    attr_reader :from_id
+    # User ID of the *followed* user.
+    attr_reader :to_id
+    # Date at which the follow action was performed.
+    attr_reader :followed_at
 
     def initialize(attributes = {})
       @from_id = attributes['from_id']

data/lib/twitch/version.rb

@@ -1,3 +1,4 @@
 module Twitch
-  VERSION = "0.1.0"
+  # Library version.
+  VERSION = "0.2.0"
 end

data/lib/twitch/video.rb

@@ -1,11 +1,37 @@
 require "time"
 
 module Twitch
+  # A captured broadcast or portion of a broadcast.
   class Video
     DATE_ATTRIBUTES = [:created_at, :published_at]
 
-    attr_reader :id, :title, :description, :language, :view_count, :created_at, 
-      :published_at, :thumbnail_url, :type, :url, :user_id, :viewable, :duration
+    # ID of the video.
+    attr_reader :id
+    # Title of the video.
+    attr_reader :title
+    # Description of the video.
+    attr_reader :description
+    # Language of the video.
+    attr_reader :language
+    # Number of views 
+    attr_reader :view_count
+    # Date the video was created.
+    attr_reader :created_at
+    # Date the video was published.
+    attr_reader :published_at
+    # URL to the thumbnail image of the video.
+    attr_reader :thumbnail_url
+    # Type of the video (archive, highlight or upload).
+    attr_reader :type
+    # URL of the video.
+    attr_reader :url
+    # ID of the user who uploaded/broadcasted the video.
+    attr_reader :user_id
+    # Viewability of the video (public or private)
+    attr_reader :viewable
+    # Duration of the video, in the format
+    # 0h0m0s
+    attr_reader :duration
 
     def initialize(attributes = {})
       attributes.each do |k, v|
@@ -16,5 +42,6 @@ module Twitch
         end
       end
     end
+    
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: twitch-api
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Maurice Wahba
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2017-11-21 00:00:00.000000000 Z
+date: 2018-01-06 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday
@@ -127,6 +127,8 @@ files:
 - lib/twitch-api.rb
 - lib/twitch/api_error.rb
 - lib/twitch/client.rb
+- lib/twitch/clip.rb
+- lib/twitch/entitlement_grant_url.rb
 - lib/twitch/game.rb
 - lib/twitch/response.rb
 - lib/twitch/stream.rb