kappa 0.2.0 → 0.3.0

data/lib/kappa/connection.rb

@@ -1,142 +1,129 @@
-require 'httparty'
-require 'addressable/uri'
-require 'securerandom'
-require 'json'
-require 'singleton'
-require 'set'
-
-module Kappa
-  # @private
-  class ConnectionBase
-    include HTTParty
-
-    def initialize(base_url = DEFAULT_BASE_URL)
-      @base_url = Addressable::URI.parse(base_url)
-
-      # TODO: Expose client_id so clients of the library can (optionally) set this
-      # themselves and avoid rate limiting. Clients should still have the option to
-      # not set this and use a randomly generated ID.
-      
-      uuid = SecureRandom.uuid
-      # TODO: Use current library version.
-      @client_id = "Kappa-v1-#{uuid}"
-    end
-
-    def get(path, query = nil)
-      request_url = @base_url + path
-
-      headers = {
-        'Client-ID' => @client_id,
-      }.merge(custom_headers)
-
-      response = self.class.get(request_url, :headers => headers, :query => query)
-
-      # TODO: Handle non-JSON response
-      # TODO: Handle invalid JSON
-      # TODO: Handle non-200 codes
-      # TODO: Include HTTP status code in the return value
-
-      json = response.body
-      return JSON.parse(json)
-    end
-
-    def accumulate(options)
-      path = options[:path]
-      params = options[:params] || {}
-      json = options[:json]
-      sub_json = options[:sub_json]
-      klass = options[:class]
-
-      total_limit = options[:limit]
-      page_limit = params[:limit] || 100
-
-      objects = []
-      ids = Set.new
-
-      paginated(path, params) do |response_json|
-        current_objects = response_json[json]
-        current_objects.each do |object_json|
-          object_json = object_json[sub_json] if sub_json
-          object = klass.new(object_json)
-          if ids.add?(object.id)
-            objects << object
-            if objects.count == total_limit
-              return objects
-            end
-          end
-        end
-
-        !current_objects.empty? && (current_objects.count >= page_limit)
-      end
-
-      return objects
-    end
-
-    def paginated(path, params = {})
-      limit = [params[:limit] || 100, 100].min
-      offset = params[:offset] || 0
-
-      path_uri = Addressable::URI.parse(path)
-      query = { 'limit' => limit, 'offset' => offset }
-      path_uri.query_values ||= {}
-      path_uri.query_values = path_uri.query_values.merge(query)
-
-      request_url = path_uri.to_s
-
-      params = params.dup
-      params.delete(:limit)
-      params.delete(:offset)
-
-      json = get(request_url, params)
-
-      # TODO: Hande request retry.
-      loop do
-        break if json['error'] && (json['status'] == 503)
-        break if !yield(json)
-
-        links = json['_links']
-        next_url = links['next']
-
-        next_uri = Addressable::URI.parse(next_url)
-        offset = next_uri.query_values['offset'].to_i
-
-        total = json['_total']
-        break if total && (offset > total)
-
-        request_url = next_url
-        json = get(request_url)
-      end
-    end
-
-  private
-    DEFAULT_BASE_URL = 'https://api.twitch.tv/kraken/'
-  end
-end
-
-module Kappa::V2
-  # @private
-  module Connection
-    class Impl < Kappa::ConnectionBase
-      include Singleton
-
-    private
-      def custom_headers
-        { 'Accept' => 'application/vnd.twitchtv.v2+json' }
-      end
-    end
-
-    def self.included(base)
-      base.extend(ClassMethods)
-    end
-
-    def connection
-      Impl.instance
-    end
-
-    module ClassMethods
-      def connection
-        Impl.instance
-      end
-    end
-  end
-end
+require 'httparty'
+require 'addressable/uri'
+require 'securerandom'
+require 'json'
+require 'singleton'
+require 'set'
+
+module Kappa
+  # @private
+  class ConnectionBase
+    include HTTParty
+
+    def initialize(base_url = DEFAULT_BASE_URL)
+      @base_url = Addressable::URI.parse(base_url)
+      
+      uuid = SecureRandom.uuid
+      @client_id = "Kappa-v1-#{uuid}"
+    end
+
+    def get(path, query = nil)
+      request_url = @base_url + path
+
+      headers = {
+        'Client-ID' => @client_id,
+      }.merge(custom_headers)
+
+      response = self.class.get(request_url, :headers => headers, :query => query)
+
+      json = response.body
+      return JSON.parse(json)
+    end
+
+    def accumulate(options)
+      path = options[:path]
+      params = options[:params] || {}
+      json = options[:json]
+      sub_json = options[:sub_json]
+      klass = options[:class]
+
+      raise ArgumentError, 'json' if json.nil?
+      raise ArgumentError, 'path' if path.nil?
+      raise ArgumentError, 'class' if klass.nil?
+
+      total_limit = options[:limit]
+      page_limit = [total_limit || 100, 100].min
+      offset = options[:offset] || 0
+
+      objects = []
+      ids = Set.new
+
+      paginated(path, page_limit, offset, params) do |response_json|
+        current_objects = response_json[json]
+        current_objects.each do |object_json|
+          object_json = object_json[sub_json] if sub_json
+          object = klass.new(object_json)
+          if ids.add?(object.id)
+            objects << object
+            if !total_limit.nil? && (objects.count == total_limit)
+              return objects
+            end
+          end
+        end
+
+        !current_objects.empty? && (current_objects.count >= page_limit)
+      end
+
+      return objects
+    end
+
+    def paginated(path, limit, offset, params = {})
+      path_uri = Addressable::URI.parse(path)
+      query = { 'limit' => limit, 'offset' => offset }
+      path_uri.query_values ||= {}
+      path_uri.query_values = path_uri.query_values.merge(query)
+
+      request_url = path_uri.to_s
+
+      json = get(request_url, params)
+
+      loop do
+        break if json['error'] && (json['status'] == 503)
+        break if !yield(json)
+
+        links = json['_links']
+        next_url = links['next']
+
+        next_uri = Addressable::URI.parse(next_url)
+        offset = next_uri.query_values['offset'].to_i
+
+        total = json['_total']
+        break if total && (offset > total)
+
+        request_url = next_url
+        json = get(request_url)
+      end
+    end
+
+  private
+    DEFAULT_BASE_URL = 'https://api.twitch.tv/kraken/'
+  end
+end
+
+module Kappa::V2
+  # @private
+  module Connection
+    class Impl < Kappa::ConnectionBase
+      include Singleton
+
+    private
+      def custom_headers
+        { 'Accept' => 'application/vnd.twitchtv.v2+json' }
+      end
+    end
+
+    def self.included(base)
+      base.extend(ClassMethods)
+    end
+
+    def connection
+      Impl.instance
+    end
+
+    module ClassMethods
+      def connection
+        Impl.instance
+      end
+    end
+  end
+end

data/lib/kappa/game.rb

@@ -1,161 +1,147 @@
-module Kappa::V2
-  # Games are categories (e.g. League of Legends, Diablo 3) used by streams and channels.
-  # Games can be searched for by query.
-  # @see Games
-  class Game
-    include Kappa::IdEquality
-
-    # @private
-    def initialize(hash)
-      @channel_count = hash['channels']
-      @viewer_count = hash['viewers']
-
-      game = hash['game']
-      @id = game['_id']
-      @name = game['name']
-      @giantbomb_id = game['giantbomb_id']
-      @box_images = Images.new(game['box'])
-      @logo_images = Images.new(game['logo'])
-    end
-
-    # @return [Fixnum] Unique Twitch ID.
-    attr_reader :id
-
-    # @return [String] User-friendly game name.
-    attr_reader :name
-
-    # @return [Fixnum] Unique game ID for GiantBomb.com. 
-    attr_reader :giantbomb_id
-
-    # @return [Images] Set of images for the game's box art.
-    attr_reader :box_images
-
-    # @return [Images] Set of images for the game's logo.
-    attr_reader :logo_images
-
-    # @return [Fixnum] Total number of channels currently streaming this game on Twitch.
-    attr_reader :channel_count
-
-    # @return [Fixnum] Total number of viewers across all channels currently watching this game on Twitch.
-    attr_reader :viewer_count
-  end
-
-  # A game suggestion returned by Twitch when searching for games via `Games.find`.
-  # @see Games.find
-  class GameSuggestion
-    include Kappa::IdEquality
-
-    # @private
-    def initialize(hash)
-      @id = hash['_id']
-      @name = hash['name']
-      @giantbomb_id = hash['giantbomb_id']
-      @popularity = hash['popularity']
-      @box_images = Images.new(hash['box'])
-      @logo_images = Images.new(hash['logo'])
-    end
-
-    # @return [Fixnum] Unique Twitch ID.
-    attr_reader :id
-
-    # @return [String] Game name.
-    attr_reader :name
-
-    # @return [Fixnum] Unique game ID for GiantBomb.com. 
-    attr_reader :giantbomb_id
-
-    # @return [Fixnum] Relative popularity metric. Higher number means more popular.
-    attr_reader :popularity
-
-    # @return [Images] Set of images for the game's box art.
-    attr_reader :box_images
-
-    # @return [Images] Set of images for the game's logo.
-    attr_reader :logo_images
-  end
-
-  # Query class used for finding top games or finding games by name.
-  # @see Game
-  # @see GameSuggestion
-  class Games
-    include Connection
-
-    # Get a list of games with the highest number of current viewers on Twitch.
-    # @example
-    #   Games.top
-    # @example
-    #   Games.top(:limit => 10)
-    # @param options [Hash] Filter criteria.
-    # @option options [Boolean] :hls (false) TODO
-    # @option options [Fixnum] :limit (none) Limit on the number of results returned.
-    # @option options [Fixnum] :offset (0) Offset into the result set to begin enumeration.
-    # @see Game
-    # @see https://github.com/justintv/Twitch-API/blob/master/v2_resources/games.md#get-gamestop GET /games/top
-    # @return [Array<Game>] List of games sorted by number of current viewers on Twitch, most popular first.
-    def self.top(options = {})
-      params = {}
-
-      # TODO: Support :offset.
-      # TODO: Support :hls.
-
-      limit = options[:limit]
-      if limit && (limit < 100)
-        params[:limit] = limit
-      else
-        params[:limit] = 100
-        limit = 0
-      end
-
-      return connection.accumulate(
-        :path => 'games/top',
-        :params => params,
-        :json => 'top',
-        :class => Game,
-        :limit => limit
-      )
-    end
-    
-    # Get a list of games with names similar to the specified name.
-    # @example
-    #   Games.find(:name => 'diablo')
-    # @example
-    #   Games.find(:name => 'starcraft', :live => true)
-    # @param options [Hash] Search criteria.
-    # @option options [String] :name Game name search term. This can be a partial name, e.g. `"league"`.
-    # @option options [Boolean] :live (false) If `true`, only returns games that are currently live on at least one channel.
-    # @see GameSuggestion
-    # @see https://github.com/justintv/Twitch-API/blob/master/v2_resources/search.md#get-searchgames GET /search/games
-    # @raise [ArgumentError] If `:name` is not specified.
-    # @return [Array<GameSuggestion>] List of games matching the criteria.
-    def self.find(options)
-      raise ArgumentError if options.nil? || options[:name].nil?
-
-      name = options[:name]
-
-      params = {
-        :query => name,
-        :type => 'suggest'
-      }
-
-      if options[:live]
-        params.merge!(:live => true)
-      end
-
-      # TODO: Use connection#accumulate here.
-
-      games = []
-      ids = Set.new
-
-      json = connection.get('search/games', params)
-      all_games = json['games']
-      all_games.each do |game_json|
-        game = GameSuggestion.new(game_json)
-        if ids.add?(game.id)
-          games << game
-        end
-      end
-
-      games
-    end
-  end
-end
+module Kappa::V2
+  # Games are categories (e.g. League of Legends, Diablo 3) used by streams and channels.
+  # Games can be searched for by query.
+  # @see Games
+  class Game
+    include Kappa::IdEquality
+
+    # @private
+    def initialize(hash)
+      @channel_count = hash['channels']
+      @viewer_count = hash['viewers']
+
+      game = hash['game']
+      @id = game['_id']
+      @name = game['name']
+      @giantbomb_id = game['giantbomb_id']
+      @box_images = Images.new(game['box'])
+      @logo_images = Images.new(game['logo'])
+    end
+
+    # @return [Fixnum] Unique Twitch ID.
+    attr_reader :id
+
+    # @return [String] User-friendly game name.
+    attr_reader :name
+
+    # @return [Fixnum] Unique game ID for GiantBomb.com. 
+    attr_reader :giantbomb_id
+
+    # @return [Images] Set of images for the game's box art.
+    attr_reader :box_images
+
+    # @return [Images] Set of images for the game's logo.
+    attr_reader :logo_images
+
+    # @return [Fixnum] Total number of channels currently streaming this game on Twitch.
+    attr_reader :channel_count
+
+    # @return [Fixnum] Total number of viewers across all channels currently watching this game on Twitch.
+    attr_reader :viewer_count
+  end
+
+  # A game suggestion returned by Twitch when searching for games via `Games.find`.
+  # @see Games.find
+  class GameSuggestion
+    include Kappa::IdEquality
+
+    # @private
+    def initialize(hash)
+      @id = hash['_id']
+      @name = hash['name']
+      @giantbomb_id = hash['giantbomb_id']
+      @popularity = hash['popularity']
+      @box_images = Images.new(hash['box'])
+      @logo_images = Images.new(hash['logo'])
+    end
+
+    # @return [Fixnum] Unique Twitch ID.
+    attr_reader :id
+
+    # @return [String] Game name.
+    attr_reader :name
+
+    # @return [Fixnum] Unique game ID for GiantBomb.com. 
+    attr_reader :giantbomb_id
+
+    # @return [Fixnum] Relative popularity metric. Higher number means more popular.
+    attr_reader :popularity
+
+    # @return [Images] Set of images for the game's box art.
+    attr_reader :box_images
+
+    # @return [Images] Set of images for the game's logo.
+    attr_reader :logo_images
+  end
+
+  # Query class used for finding top games or finding games by name.
+  # @see Game
+  # @see GameSuggestion
+  class Games
+    include Connection
+
+    # Get a list of games with the highest number of current viewers on Twitch.
+    # @example
+    #   Games.top
+    # @example
+    #   Games.top(:limit => 10)
+    # @param options [Hash] Filter criteria.
+    # @option options [Boolean] :hls (nil) If `true`, limit the games to those that have any streams using HLS (HTTP Live Streaming). If `false` or `nil`, do not limit.
+    # @option options [Fixnum] :limit (none) Limit on the number of results returned.
+    # @option options [Fixnum] :offset (0) Offset into the result set to begin enumeration.
+    # @see Game
+    # @see https://github.com/justintv/Twitch-API/blob/master/v2_resources/games.md#get-gamestop GET /games/top
+    # @return [Array<Game>] List of games sorted by number of current viewers on Twitch, most popular first.
+    def self.top(options = {})
+      params = {}
+
+      if options[:hls]
+        params[:hls] = true
+      end
+
+      return connection.accumulate(
+        :path => 'games/top',
+        :params => params,
+        :json => 'top',
+        :class => Game,
+        :limit => options[:limit],
+        :offset => options[:offset]
+      )
+    end
+    
+    # Get a list of games with names similar to the specified name.
+    # @example
+    #   Games.find(:name => 'diablo')
+    # @example
+    #   Games.find(:name => 'starcraft', :live => true)
+    # @param options [Hash] Search criteria.
+    # @option options [String] :name Game name search term. This can be a partial name, e.g. `"league"`.
+    # @option options [Boolean] :live (false) If `true`, only returns games that are currently live on at least one channel.
+    # @option options [Fixnum] :limit (none) Limit on the number of results returned.
+    # @see GameSuggestion
+    # @see https://github.com/justintv/Twitch-API/blob/master/v2_resources/search.md#get-searchgames GET /search/games
+    # @raise [ArgumentError] If `:name` is not specified.
+    # @return [Array<GameSuggestion>] List of games matching the criteria.
+    def self.find(options)
+      raise ArgumentError, 'options' if options.nil?
+      raise ArgumentError, 'name' if options[:name].nil?
+
+      params = {
+        :query => options[:name],
+        :type => 'suggest'
+      }
+
+      if options[:live]
+        params.merge!(:live => true)
+      end
+
+      return connection.accumulate(
+        :path => 'search/games',
+        :params => params,
+        :json => 'games',
+        :class => GameSuggestion,
+        :limit => options[:limit]
+      )
+    end
+  end
+end