kappa 0.4.0 → 1.0.0

data/README.md

@@ -7,7 +7,6 @@ Kappa is the Ruby library for interfacing with the [Twitch.tv API](https://githu
 [![Dependency Status](https://gemnasium.com/schmich/kappa.png)](https://gemnasium.com/schmich/kappa)
 [![Coverage Status](https://coveralls.io/repos/schmich/kappa/badge.png?branch=master)](https://coveralls.io/r/schmich/kappa?branch=master)
 [![Code Climate](https://codeclimate.com/github/schmich/kappa.png)](https://codeclimate.com/github/schmich/kappa)
-[![Bitdeli](https://d2weczhvl823v0.cloudfront.net/schmich/kappa/trend.png)](https://bitdeli.com/free "Bitdeli")
 
 ## Getting Started
 
@@ -22,6 +21,10 @@ frag = Twitch.channels.get('lethalfrag')
 puts frag.streaming?
 ```
 
+```ruby
+gem 'kappa', '~> 1.0'
+```
+
 ## Configuration
 
 When making requests to Twitch, you must specify a client ID for your application.
@@ -36,13 +39,79 @@ Twitch.configure do |config|
 end
 ```
 
-## Overview
+See the [`Twitch.configure`](http://rdoc.info/gems/kappa/Twitch#configure-class_method) documentation.
 
-### <a id="channels"></a>Channels
+## Examples
+
+Get the featured streams on the Twitch.tv homepage:
+
+```ruby
+Twitch.streams.featured do |stream|
+  channel = stream.channel
+  puts "#{channel.display_name}: #{stream.viewer_count} viewers"
+  puts "#{channel.status}"
+  puts '-' * 80
+end
+```
+
+See if certain users are streaming:
+
+```ruby
+users = ['destiny', 'followgrubby', 'incontroltv']
+Twitch.streams.find(:channel => users) do |stream|
+  puts "#{stream.channel.name} is streaming #{stream.game_name}."
+end
+```
+
+Get the most popular games being streamed:
 
-Channels serve as the home location for a [user's](#users) content. Channels have a [stream](#streams), can run commercials, store [videos](#videos), display information and status, and have a customized page including banners and backgrounds.
+```ruby
+Twitch.games.top(:limit => 3) do |game|
+  print "#{game.name}: "
+  print "#{game.viewer_count} viewers in "
+  puts  "#{game.channel_count} channels"
+end
+```
 
-See also [`Channel`](http://rdoc.info/gems/kappa/Kappa/V2/Channel) documentation.
+Get streams for a particular game:
+
+```ruby
+Twitch.streams.find(:game => 'League of Legends') do |stream|
+  next if stream.viewer_count < 1000
+  puts "#{stream.channel.display_name}: #{stream.viewer_count}"
+end
+```
+
+Get info for a single user:
+
+```ruby
+user = Twitch.users.get('lethalfrag')
+stream = user.stream
+
+puts user.display_name
+if stream
+  puts "Streaming #{stream.game_name} at #{stream.url}"
+else
+  puts 'Not streaming.'
+end
+```
+
+Get the followers of a channel:
+
+```ruby
+channel = Twitch.channels.get('day9tv')
+channel.followers do |user|
+  puts user.display_name
+end
+```
+
+## Resources
+
+### <a id="channels"></a>Channels
+
+Channels serve as the home location for a [user's](#users) content. Channels have a [stream](#streams),
+can run commercials, store [videos](#videos), display information and status, and have a customized page
+including banners and backgrounds. See the [`Channel`](http://rdoc.info/gems/kappa/Twitch/V2/Channel) documentation.
 
 ```ruby
 c = Twitch.channels.get('destiny')
@@ -57,9 +126,9 @@ c.followers   # => [#<Kappa::V2::User>, ...]
 
 ### <a id="streams"></a>Streams
 
-Streams are video broadcasts that are currently live. They belong to a [user](#users) and are part of a [channel](#channels).
-
-See also [`Stream`](http://rdoc.info/gems/kappa/Kappa/V2/Stream) and [`Streams`](http://rdoc.info/gems/kappa/Kappa/V2/Streams) documentation.
+Streams are video broadcasts that are currently live. They belong to a [user](#users) and are part of a
+[channel](#channels). See the [`Stream`](http://rdoc.info/gems/kappa/Twitch/V2/Stream) and
+[`Streams`](http://rdoc.info/gems/kappa/Twitch/V2/Streams) documentation.
 
 ```ruby
 s = Twitch.streams.get('idrajit')
@@ -71,9 +140,9 @@ s.channel.url   # => "http://www.twitch.tv/idrajit"
 
 ### <a id="users"></a>Users
 
-These are members of the Twitch community who have a Twitch account. If broadcasting, they can own a [stream](#streams) that they can broadcast on their [channel](#channels). If mainly viewing, they might follow or subscribe to channels.
-
-See also [`User`](http://rdoc.info/gems/kappa/Kappa/V2/User) documentation.
+These are members of the Twitch community who have a Twitch account. If broadcasting, they can own a
+[stream](#streams) that they can broadcast on their [channel](#channels). If mainly viewing, they might
+follow or subscribe to channels. See the [`User`](http://rdoc.info/gems/kappa/Twitch/V2/User) documentation.
 
 ```ruby
 u = Twitch.users.get('snoopeh')
@@ -84,9 +153,10 @@ u.following.map(&:name)   # => ["national_esl1", "dreamhacklol", "riotgames"]
 
 ### <a id="videos"></a>Videos
 
-Videos are broadcasts or highlights owned by a [channel](#channels). Broadcasts are unedited videos that are saved after a streaming session. Highlights are videos edited from broadcasts by the channel's owner.
-
-See also [`Video`](http://rdoc.info/gems/kappa/Kappa/V2/Video) and [`Videos`](http://rdoc.info/gems/kappa/Kappa/V2/Videos) documentation.
+Videos are broadcasts or highlights owned by a [channel](#channels). Broadcasts are unedited videos that are saved
+after a streaming session. Highlights are videos edited from broadcasts by the channel's owner. See the
+[`Video`](http://rdoc.info/gems/kappa/Twitch/V2/Video) and [`Videos`](http://rdoc.info/gems/kappa/Twitch/V2/Videos)
+documentation.
 
 ```ruby
 v = Twitch.videos.get('a395995729')
@@ -99,9 +169,8 @@ v.view_count    # => 12506
 
 ### <a id="teams"></a>Teams
 
-Teams are an organization of [channels](#channels).
-
-See also [`Team`](http://rdoc.info/gems/kappa/Kappa/V2/Team) documentation.
+Teams are an organization of [channels](#channels). See the [`Team`](http://rdoc.info/gems/kappa/Twitch/V2/Team)
+documentation.
 
 ```ruby
 t = Twitch.teams.get('teamliquid')
@@ -113,13 +182,14 @@ t.updated_at    # => 2013-05-24 00:17:10 UTC
 
 ### <a id="games"></a>Games
 
-Games are categories (e.g. League of Legends, Diablo 3) used by [streams](#streams) and [channels](#channels). Games can be searched for by query.
-
-See also [`Game`](http://rdoc.info/gems/kappa/Kappa/V2/Game), [`Games`](http://rdoc.info/gems/kappa/Kappa/V2/Games), and [`GameSuggestion`](http://rdoc.info/gems/kappa/Kappa/V2/GameSuggestion) documentation.
+Games are categories (e.g. League of Legends, Diablo 3) used by [streams](#streams) and [channels](#channels).
+Games can be searched for by query. See the [`Game`](http://rdoc.info/gems/kappa/Twitch/V2/Game),
+[`Games`](http://rdoc.info/gems/kappa/Twitch/V2/Games), and
+[`GameSuggestion`](http://rdoc.info/gems/kappa/Twitch/V2/GameSuggestion) documentation.
 
 ```ruby
-top = Twitch.games.top(:limit => 3)
-top.map(&:name)  # => ["League of Legends", "Dota 2", "StarCraft II: Heart of the Swarm"]
+top = Twitch.games.top(:limit => 2)
+top.map(&:name)  # => ["League of Legends", "StarCraft II: Heart of the Swarm"]
 ```
 
 ```ruby
@@ -127,16 +197,34 @@ g = Twitch.games.top(:limit => 1).first
 g.name                   # => "League of Legends"
 g.channel_count          # => 906
 g.viewer_count           # => 79223
-g.box_images.medium_url  # =>"http://static-cdn.jtvnw.net/ttv-boxart/League%20of%20Legends-272x380.jpg"
+g.box_images.medium_url  # =>"http://static-cdn.jtvnw.net/ttv-boxart/31412.jpg"
 ```
 
 ```ruby
 s = Twitch.games.find(:name => 'diablo', :live => true)
-s.map(&:name)        # => ["Diablo III", "Diablo II", "Diablo", "Diablo II: Lord of Destruction"]
-s.map(&:popularity)  # => [120, 4, 1, 1]
+s.map(&:name)        # => ["Diablo III", "Diablo II", "Diablo"]
+s.map(&:popularity)  # => [120, 4, 1]
 ```
 
-## Examples
+## Errors
+
+All errors derive from `Twitch::Error`.
+
+- `Twitch:Error` - Base class for all errors.
+- `Twitch::Error::ResponseError` - Base class for all Twitch.tv API response errors.
+- `Twitch::Error::FormatError` - The returned data was incorrectly formatted (e.g. invalid JSON).
+- `Twitch::Error::ClientError` - The server returned a 4xx status code.
+- `Twitch::Error::ServerError` - The server returned a 5xx status code.
+
+All `ResponseError` errors have additional diagnostic information:
+
+```ruby
+e.status # => 422
+e.body   # => '{"status":422,"message":"...","error":"..."}'
+e.url    # => "https://api.twitch.tv/streams/desrow"
+```
+
+See the [`ResponseError`](http://rdoc.info/gems/kappa/Twitch/Error/ResponseError) documentation.
 
 ## Documentation
 
@@ -194,3 +282,4 @@ end
 Copyright &copy; 2013 Chris Schmich
 <br />
 MIT License, See [LICENSE](LICENSE) for details.
+[![githalytics.com alpha](https://cruel-carlota.pagodabox.com/b885add21cf8f2b473d1394edc1cf5b4 "githalytics.com")](http://githalytics.com/schmich/kappa)

data/lib/kappa.rb

@@ -1,5 +1,7 @@
 require 'kappa/id_equality'
 require 'kappa/proxy'
+require 'kappa/status'
+require 'kappa/errors'
 require 'kappa/connection'
 require 'kappa/configuration'
 require 'kappa/query'

data/lib/kappa/channel.rb

@@ -68,57 +68,57 @@ module Twitch::V2
     # Get the users following this channel.
     # @note The number of followers is potentially very large, so it's recommended that you specify a `:limit`.
     # @example
-    #   f = c.followers(:limit => 20)
+    #   channel.followers(:limit => 20)
+    # @example
+    #   channel.followers do |follower|
+    #     puts follower.display_name
+    #   end
     # @param options [Hash] Filter criteria.
-    # @option options [Fixnum] :limit (none) Limit on the number of results returned.
+    # @option options [Fixnum] :limit (nil) Limit on the number of results returned.
     # @option options [Fixnum] :offset (0) Offset into the result set to begin enumeration.
+    # @yield Optional. If a block is given, each follower is yielded.
+    # @yieldparam [User] follower Current follower.
     # @see User
     # @see https://github.com/justintv/Twitch-API/blob/master/v2_resources/channels.md#get-channelschannelfollows GET /channels/:channel/follows
-    # @return [Array<User>] List of users following this channel.
-    def followers(options = {})
+    # @return [Array<User>] Users following this channel, if no block is given.
+    # @return [nil] If a block is given.
+    def followers(options = {}, &block)
+      name = CGI.escape(@name)
       return @query.connection.accumulate(
-        :path => "channels/#{@name}/follows",
+        :path => "channels/#{name}/follows",
         :json => 'follows',
         :sub_json => 'user',
         :create => -> hash { User.new(hash, @query) },
         :limit => options[:limit],
-        :offset => options[:offset]
+        :offset => options[:offset],
+        &block
       )
     end
 
     # Get the videos for a channel, most recently created first.
     # @note This incurs additional web requests.
+    # @note You can get videos directly from a channel name via {Videos#for_channel}.
+    # @example
+    #   v = channel.videos(:type => :broadcasts)
     # @example
-    #   c = Twitch.channels.get('idrajit')
-    #   v = c.videos(:type => :broadcasts)
+    #   channel.videos(:type => :highlights) do |video|
+    #     next if video.view_count < 10000
+    #     puts video.url
+    #   end 
     # @param options [Hash] Filter criteria.
     # @option options [Symbol] :type (:highlights) The type of videos to return. Valid values are `:broadcasts`, `:highlights`.
-    # @option options [Fixnum] :limit (none) Limit on the number of results returned.
+    # @option options [Fixnum] :limit (nil) Limit on the number of results returned.
     # @option options [Fixnum] :offset (0) Offset into the result set to begin enumeration.
+    # @yield Optional. If a block is given, each video is yielded.
+    # @yieldparam [Video] video Current video.
     # @see Video
+    # @see Videos#for_channel Videos#for_channel
     # @see https://github.com/justintv/Twitch-API/blob/master/v2_resources/videos.md#get-channelschannelvideos GET /channels/:channel/videos
     # @raise [ArgumentError] If `:type` is not one of `:broadcasts` or `:highlights`.
-    # @return [Array<Video>] List of videos for the channel.
-    def videos(options = {})
-      params = {}
-
-      type = options[:type] || :highlights
-      if !type.nil?
-        if ![:broadcasts, :highlights].include?(type)
-          raise ArgumentError, 'type'
-        end
-
-        params[:broadcasts] = (type == :broadcasts)
-      end
-
-      return @query.connection.accumulate(
-        :path => "channels/#{@name}/videos",
-        :params => params,
-        :json => 'videos',
-        :create => -> hash { Video.new(hash, @query) },
-        :limit => options[:limit],
-        :offset => options[:offset]
-      )
+    # @return [Array<Video>] Videos for the channel, if no block is given.
+    # @return [nil] If a block is given.
+    def videos(options = {}, &block)
+      @query.videos.for_channel(@name, options, &block)
     end
 
     # @example
@@ -170,7 +170,7 @@ module Twitch::V2
 
     # @example
     #   2013-07-21 05:27:58 UTC
-    # @return [Time] When the channel was last updated (UTC). For example, when a stream is started, its channel is updated.
+    # @return [Time] When the channel was last updated (UTC). For example, when a stream is started or a channel's status is changed, the channel is updated.
     attr_reader :updated_at
 
     # @example
@@ -202,13 +202,11 @@ module Twitch::V2
     # @param channel_name [String] The name of the channel to get. This is the same as the stream or user name.
     # @return [Channel] A valid `Channel` object if the channel exists, `nil` otherwise.
     def get(channel_name)
-      encoded_name = CGI.escape(channel_name)
-      json = @query.connection.get("channels/#{encoded_name}")
+      name = CGI.escape(channel_name)
 
       # HTTP 422 can happen if the channel is associated with a Justin.tv account.
-      if !json || json['status'] == 404 || json['status'] == 422
-        nil
-      else
+      Twitch::Status.map(404 => nil, 422 => nil) do
+        json = @query.connection.get("channels/#{name}")
         Channel.new(json, @query)
       end
     end

data/lib/kappa/configuration.rb

@@ -3,16 +3,48 @@ require 'securerandom'
 module Twitch
   @query = nil
 
-  # Configure global settings for interacting with Twitch. Future requests will use these settings.
+  # Configure global settings for interacting with Twitch. Future requests
+  # through the `Twitch` module will use these settings.
   # @example
   #   Twitch.configure do |config|
   #     config.client_id = 'sc2daily-v1.0.0'
   #     config.api = Twitch::V2
   #   end
+  #
+  #   streams = Twitch.streams.featured(:limit => 10)
+  # @param client_id [String] When making requests to Twitch,
+  #   you must specify a client ID for your application. If you do not specify a client ID,
+  #   Twitch reserves the right to rate-limit your application without warning. If unspecified,
+  #   this defaults to a random string, but in real applications, you should set this explicitly.
+  # @param api [Module] The version of the Twitch API to use. Defaults to `Twitch::V2`, the only
+  #   API version currently supported.
+  # @return [nil] nil
   def self.configure(&block)
     @query = instance(&block)
+    nil
   end
 
+  # Create a new interface to Twitch. This allows you to have multiple separate
+  # connections to Twitch in the same process, each with its own configuration.
+  # @example
+  #   client_a = Twitch.instance do |config|
+  #     config.client_id = 'App-A-v2.0.0'
+  #   end
+  #
+  #   client_b = Twitch.instance do |config|
+  #     config.client_id = 'App-B-v3.0.0'
+  #   end
+  #
+  #   streams = client_a.streams.featured(:limit => 10)
+  #   channel = client_b.channels.get('destiny')
+  # @param client_id [String] When making requests to Twitch,
+  #   you must specify a client ID for your application. If you do not specify a client ID,
+  #   Twitch reserves the right to rate-limit your application without warning. If unspecified,
+  #   this defaults to a random string, but in real applications, you should set this explicitly.
+  # @param api [Module] The version of the Twitch API to use. Defaults to `Twitch::V2`, the only
+  #   API version currently supported.
+  # @return [Object] A Twitch query object through which you can make requests. The methods on this
+  #   object are the same as the methods on the default `Twitch` object.
   def self.instance(&block)
     config = Configuration.new
     config.instance_eval(&block)
@@ -20,6 +52,7 @@ module Twitch
     return config.create(:Query, connection)
   end
 
+  # @private
   def self.method_missing(*args)
     @query ||= create_default_query
     @query.send(*args)
@@ -46,6 +79,7 @@ module Twitch
   end
 
 private
+  # @private
   def self.create_default_query
     config = Configuration.new
     connection = config.create(:Connection, config.client_id)

data/lib/kappa/connection.rb

@@ -9,11 +9,16 @@ module Twitch
     include HTTParty
 
     def initialize(client_id, base_url = DEFAULT_BASE_URL)
+      raise ArgumentError, 'client_id' if !client_id || client_id.empty?
+      raise ArgumentError, 'base_url' if !base_url || base_url.empty?
+
       @client_id = client_id
       @base_url = Addressable::URI.parse(base_url)
     end
 
     def get(path, query = nil)
+      raise ArgumentError, 'path' if !path || path.empty?
+
       request_url = @base_url + path
 
       all_headers = {
@@ -23,11 +28,27 @@ module Twitch
 
       response = self.class.get(request_url, :headers => all_headers, :query => query)
 
-      json = response.body
-      return JSON.parse(json)
+      url = response.request.last_uri.to_s
+      status = response.code
+      body = response.body
+
+      case status
+        when 400...500
+          raise Error::ClientError.new("HTTP client error, status #{status}.", url, status, body)
+        when 500...600
+          raise Error::ServerError.new("HTTP server error, status #{status}.", url, status, body)
+        else
+          # Ignore, assume success.
+      end
+
+      begin
+        return JSON.parse(body)
+      rescue JSON::ParserError => e
+        raise Error::FormatError.new(e, url, status, body)
+      end
     end
 
-    def accumulate(options)
+    def accumulate(options, &block)
       path = options[:path]
       params = options[:params] || {}
       json = options[:json]
@@ -47,8 +68,13 @@ module Twitch
       page_limit = [total_limit || 100, 100].min
       offset = options[:offset] || 0
 
-      objects = []
       ids = Set.new
+      objects = []
+      count = 0
+
+      block ||= -> object {
+        objects << object
+      }
 
       paginate(path, page_limit, offset, params) do |response_json|
         current_objects = response_json[json]
@@ -56,17 +82,18 @@ module Twitch
           object_json = object_json[sub_json] if sub_json
           object = create.call(object_json)
           if ids.add?(object.id)
-            objects << object
-            if !total_limit.nil? && (objects.count == total_limit)
-              return objects
+            count += 1
+            block.call(object)
+            if count == total_limit
+              return block_given? ? nil : objects
             end
           end
         end
 
-        !current_objects.empty? && (current_objects.count >= page_limit)
+        break if current_objects.empty? || (current_objects.count < page_limit)
       end
 
-      return objects
+      return block_given? ? nil : objects
     end
 
     def paginate(path, limit, offset, params = {})
@@ -81,7 +108,7 @@ module Twitch
 
       loop do
         break if json['error'] && (json['status'] == 503)
-        break if !yield(json)
+        yield json
 
         links = json['_links']
         next_url = links['next']
@@ -105,8 +132,8 @@ end
 module Twitch::V2
   # @private
   class Connection < Twitch::Connection
-      def headers
-        { 'Accept' => 'application/vnd.twitchtv.v2+json' }
-      end
+    def headers
+      { 'Accept' => 'application/vnd.twitchtv.v2+json' }
+    end
   end
 end

data/lib/kappa/errors.rb

@@ -0,0 +1,43 @@
+module Twitch
+  # The base class for all `Twitch` errors.
+  class Error < StandardError
+    # An error that occurred as the result of a request to the Twitch.tv API.
+    class ResponseError < Error
+      # @private
+      def initialize(arg, url, status, body)
+        super(arg)
+        @url = url
+        @status = status
+        @body = body
+      end
+
+      # @example
+      #   "https://api.twitch.tv/kraken/streams?limit=100&offset=0"
+      # @return [String] The request URL that resulted in this response error.
+      attr_reader :url
+
+      # @example
+      #   500
+      # @return [Fixnum] The HTTP status code for the response.
+      attr_reader :status
+
+      # @example
+      #   '{"status":422,"message":"Channel desrow is not available on Twitch","error":"Unprocessable Entity"}'
+      # @return [String] The response body.
+      attr_reader :body
+    end
+
+    # An error indicating an HTTP client error code (4xx) from the Twitch.tv API.
+    class ClientError < ResponseError
+    end
+
+    # An error indicating an HTTP server error code (5xx) from the Twitch.tv API.
+    class ServerError < ResponseError
+    end
+
+    # An error indicating a malformed response from the Twitch.tv API.
+    # All Twitch.tv responses are expected to valid JSON objects.
+    class FormatError < ResponseError
+    end
+  end
+end

data/lib/kappa/game.rb

@@ -8,7 +8,8 @@ module Twitch::V2
     include Twitch::IdEquality
 
     # @private
-    def initialize(hash)
+    def initialize(hash, query)
+      @query = query
       @channel_count = hash['channels']
       @viewer_count = hash['viewers']
 
@@ -20,6 +21,34 @@ module Twitch::V2
       @logo_images = Images.new(game['logo'])
     end
 
+    # Get streams for this game.
+    # @example
+    #   game.streams
+    # @example
+    #   game.streams(:embeddable => true, :limit => 20)
+    # @example
+    #   game.streams do |stream|
+    #     next if stream.viewer_count < 1000
+    #     puts stream.url
+    #   end
+    # @param options [Hash] Search criteria.
+    # @option options [Array<String, Channel, #name>] :channel Only return streams for these channels.
+    #   If a channel is not currently streaming, it is omitted. You must specify an array of channels
+    #   or channel names.
+    # @option options [Boolean] :embeddable (nil) If `true`, limit the streams to those that can be embedded. If `false` or `nil`, do not limit.
+    # @option options [Boolean] :hls (nil) If `true`, limit the streams to those using HLS (HTTP Live Streaming). If `false` or `nil`, do not limit.
+    # @option options [Fixnum] :limit (nil) Limit on the number of results returned.
+    # @option options [Fixnum] :offset (0) Offset into the result set to begin enumeration.
+    # @yield Optional. If a block is given, each stream found is yielded.
+    # @yieldparam [Stream] stream Current stream.
+    # @see https://github.com/justintv/Twitch-API/blob/master/v2_resources/streams.md#get-streams GET /streams
+    # @raise [ArgumentError] If `:channel` is not an array.
+    # @return [Array<Stream>] Streams matching the specified criteria, if no block is given.
+    # @return [nil] If a block is given.
+    def streams(options = {}, &block)
+      @query.streams.find(options.merge(:game => @name), &block)
+    end
+
     # @example
     #   21799
     # @return [Fixnum] Unique Twitch ID.
@@ -108,14 +137,22 @@ module Twitch::V2
     #   Twitch.games.top
     # @example
     #   Twitch.games.top(:limit => 10)
+    # @example
+    #   Twitch.games.top do |game|
+    #     next if game.viewer_count < 10000
+    #     puts game.name
+    #   end
     # @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] :limit (nil) Limit on the number of results returned.
     # @option options [Fixnum] :offset (0) Offset into the result set to begin enumeration.
+    # @yield Optional. If a block is given, each top game is yielded.
+    # @yieldparam [Game] game Current game.
     # @see Game 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 top(options = {})
+    # @return [Array<Game>] Games sorted by number of current viewers on Twitch, highest first, if no block is given.
+    # @return [nil] If a block is given.
+    def top(options = {}, &block)
       params = {}
 
       if options[:hls]
@@ -126,9 +163,10 @@ module Twitch::V2
         :path => 'games/top',
         :params => params,
         :json => 'top',
-        :create => Game,
+        :create => -> hash { Game.new(hash, @query) },
         :limit => options[:limit],
-        :offset => options[:offset]
+        :offset => options[:offset],
+        &block
       )
     end
     
@@ -137,14 +175,22 @@ module Twitch::V2
     #   Twitch.games.find(:name => 'diablo')
     # @example
     #   Twitch.games.find(:name => 'starcraft', :live => true)
+    # @example
+    #   Twitch.games.find(:name => 'starcraft') do |suggestion|
+    #     next if suggestion.name =~ /heart of the swarm/i
+    #     puts suggestion.name
+    #   end
     # @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.
+    # @option options [Fixnum] :limit (nil) Limit on the number of results returned.
+    # @yield Optional. If a block is given, each game suggestion is yielded.
+    # @yieldparam [GameSuggestion] suggestion Current game suggestion.
     # @see GameSuggestion 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.
+    # @return [Array<GameSuggestion>] Games matching the criteria, if no block is given.
+    # @return [nil] If a block is given.
     def find(options)
       raise ArgumentError, 'options' if options.nil?
       raise ArgumentError, 'name' if options[:name].nil?

data/lib/kappa/status.rb

@@ -0,0 +1,16 @@
+module Twitch
+  # @private
+  class Status
+    def self.map(status_map, &block)
+      begin
+        block.call
+      rescue Error::ClientError, Error::ServerError => e
+        if status_map.include? e.status
+          status_map[e.status]
+        else
+          raise
+        end
+      end
+    end
+  end
+end

data/lib/kappa/stream.rb

@@ -71,6 +71,26 @@ module Twitch::V2
     attr_reader :url
   end
 
+  # Site-wide stream summary statistics.
+  # @see Streams#summary Streams#summary
+  class StreamSummary
+    # @private
+    def initialize(hash)
+      @viewer_count = hash['viewers']
+      @channel_count = hash['channels']
+    end
+
+    # @example
+    #   194774
+    # @return [Fixnum] The sum of all viewers across all live streams.
+    attr_reader :viewer_count
+
+    # @example
+    #   4144
+    # @return [Fixnum] The count of all channels currently streaming.
+    attr_reader :channel_count
+  end
+
   # Query class for finding featured streams or streams meeting certain criteria.
   # @see Stream
   class Streams
@@ -91,40 +111,79 @@ module Twitch::V2
     # @param stream_name [String] The name of the stream to get. This is the same as the channel or user name.
     # @see #find
     # @see https://github.com/justintv/Twitch-API/blob/master/v2_resources/streams.md#get-streamschannel GET /streams/:channel
-    # @return [Stream] A valid `Stream` object if the stream exists and is currently live, `nil` otherwise.
+    # @return [Stream] A valid `Stream` object, if the stream exists and is live.
+    # @return [nil] If the stream does not exist or is not live.
     def get(stream_name)
-      encoded_name = CGI.escape(stream_name)
-      json = @query.connection.get("streams/#{encoded_name}")
-      stream = json['stream']
-      if json['status'] == 404 || !stream
-        nil
-      else
-        Stream.new(stream, @query)
+      name = CGI.escape(stream_name)
+
+      # HTTP 422 can happen if the stream is associated with a Justin.tv account.
+      Twitch::Status.map(404 => nil, 422 => nil) do
+        json = @query.connection.get("streams/#{name}")
+        stream = json['stream']
+        stream.nil? ? nil : Stream.new(stream, @query)
       end
     end
 
-    # Get a list of streams for a specific game, for a set of channels, or by other criteria.
+    # Get all currently live streams.
+    # @example
+    #   Twitch.streams.all
+    # @example
+    #   Twitch.streams.all(:offset => 100, :limit => 10)
+    # @example
+    #   Twitch.streams.all do |stream|
+    #     next if stream.viewer_count < 1000
+    #     puts stream.url
+    #   end
+    # @param options [Hash] Limit criteria.
+    # @option options [Fixnum] :limit (nil) Limit on the number of results returned.
+    # @option options [Fixnum] :offset (0) Offset into the result set to begin enumeration.
+    # @yield Optional. If a block is given, each stream is yielded.
+    # @yieldparam [Stream] stream Current stream.
+    # @see #get
+    # @see https://github.com/justintv/Twitch-API/blob/master/v2_resources/streams.md#get-streams GET /streams
+    # @return [Array<Stream>] Currently live streams, if no block is given.
+    # @return [nil] If a block is given.
+    def all(options = {}, &block)
+      return @query.connection.accumulate(
+        :path => 'streams',
+        :json => 'streams',
+        :create => -> hash { Stream.new(hash, @query) },
+        :limit => options[:limit],
+        :offset => options[:offset],
+        &block
+      )
+    end
+
+    # Get streams for a specific game, for a set of channels, or by other criteria.
     # @example
     #   Twitch.streams.find(:game => 'League of Legends', :limit => 50)
     # @example
     #   Twitch.streams.find(:channel => ['fgtvlive', 'incontroltv', 'destiny'])
     # @example
     #   Twitch.streams.find(:game => 'Diablo III', :channel => ['nl_kripp', 'protech'])
+    # @example
+    #   Twitch.streams.find(:game => 'League of Legends') do |stream|
+    #     next if stream.viewer_count < 1000
+    #     puts stream.url
+    #   end
     # @param options [Hash] Search criteria.
-    # @option options [String/Game/#name] :game Only return streams currently streaming the specified game.
-    # @option options [Array<String/Channel/#name>] :channel Only return streams for these channels.
+    # @option options [String, Game, #name] :game Only return streams currently streaming the specified game.
+    # @option options [Array<String, Channel, #name>] :channel Only return streams for these channels.
     #   If a channel is not currently streaming, it is omitted. You must specify an array of channels
     #   or channel names. If you want to find the stream for a single channel, see {Streams#get}.
     # @option options [Boolean] :embeddable (nil) If `true`, limit the streams to those that can be embedded. If `false` or `nil`, do not limit.
     # @option options [Boolean] :hls (nil) If `true`, limit the streams to those 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] :limit (nil) Limit on the number of results returned.
     # @option options [Fixnum] :offset (0) Offset into the result set to begin enumeration.
+    # @yield Optional. If a block is given, each stream found is yielded.
+    # @yieldparam [Stream] stream Current stream.
     # @see #get
     # @see https://github.com/justintv/Twitch-API/blob/master/v2_resources/streams.md#get-streams GET /streams
     # @raise [ArgumentError] If `options` does not specify a search criteria (`:game`, `:channel`, `:embeddable`, or `:hls`).
     # @raise [ArgumentError] If `:channel` is not an array.
-    # @return [Array<Stream>] List of streams matching the specified criteria.
-    def find(options)
+    # @return [Array<Stream>] Streams matching the specified criteria, if no block is given.
+    # @return [nil] If a block is given.
+    def find(options, &block)
       check = options.dup
       check.delete(:limit)
       check.delete(:offset)
@@ -170,23 +229,32 @@ module Twitch::V2
         :json => 'streams',
         :create => -> hash { Stream.new(hash, @query) },
         :limit => options[:limit],
-        :offset => options[:offset]
+        :offset => options[:offset],
+        &block
       )
     end
 
-    # Get the list of currently featured (promoted) streams. This includes the list of streams shown on the Twitch homepage.
+    # Get the currently featured (promoted) streams. This includes the streams shown on the Twitch homepage.
     # @note There is no guarantee of how many streams are featured at any given time.
     # @example
     #   Twitch.streams.featured
     # @example
     #   Twitch.streams.featured(:limit => 5)
+    # @example
+    #   Twitch.streams.featured do |stream|
+    #     next if stream.viewer_count < 1000
+    #     puts stream.url
+    #   end
     # @param options [Hash] Filter criteria.
     # @option options [Boolean] :hls (nil) If `true`, limit the streams to those 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] :limit (nil) Limit on the number of results returned.
     # @option options [Fixnum] :offset (0) Offset into the result set to begin enumeration.
+    # @yield Optional. If a block is given, each featured stream is yielded.
+    # @yieldparam [Stream] stream Current stream.
     # @see https://github.com/justintv/Twitch-API/blob/master/v2_resources/streams.md#get-streamsfeatured GET /streams/featured
-    # @return [Array<Stream>] List of currently featured streams.
-    def featured(options = {})
+    # @return [Array<Stream>] Featured streams, if no block is given.
+    # @return [nil] If a block is given.
+    def featured(options = {}, &block)
       params = {}
 
       if options[:hls]
@@ -200,8 +268,21 @@ module Twitch::V2
         :sub_json => 'stream',
         :create => -> hash { Stream.new(hash, @query) },
         :limit => options[:limit],
-        :offset => options[:offset]
+        :offset => options[:offset],
+        &block
       )
     end
+
+    # Get site-wide stream summary statistics.
+    # @example
+    #   summary = Twitch.streams.summary
+    #   summary.viewer_count  # => 194774
+    #   summary.channel_count # => 4144
+    # @see https://github.com/justintv/Twitch-API/blob/master/v2_resources/streams.md#gedt-streamssummary GET /streams/summary
+    # @return [StreamSummary] Stream summary statistics.
+    def summary
+      json = @query.connection.get('streams/summary')
+      StreamSummary.new(json)
+    end
   end
 end

data/lib/kappa/team.rb

@@ -1,3 +1,4 @@
+require 'cgi'
 require 'time'
 
 module Twitch::V2
@@ -20,7 +21,9 @@ module Twitch::V2
       @display_name = hash['display_name']
       @updated_at = Time.parse(hash['updated_at']).utc
       @created_at = Time.parse(hash['created_at']).utc
-      @url = "http://www.twitch.tv/team/#{@name}"
+
+      name = CGI.escape(@name)
+      @url = "http://www.twitch.tv/team/#{name}"
     end
 
     # @example
@@ -91,10 +94,9 @@ module Twitch::V2
     # @return [Team] A valid `Team` object if the team exists, `nil` otherwise.
     # @see https://github.com/justintv/Twitch-API/blob/master/v2_resources/teams.md#get-teamsteam GET /teams/:team
     def get(team_name)
-      json = @query.connection.get("teams/#{team_name}")
-      if json['status'] == 404
-        nil
-      else
+      name = CGI.escape(team_name)
+      Twitch::Status.map(404 => nil) do
+        json = @query.connection.get("teams/#{name}")
         Team.new(json)
       end
     end
@@ -104,17 +106,26 @@ module Twitch::V2
     #   Twitch.teams.all
     # @example
     #   Twitch.teams.all(:limit => 10)
+    # @example
+    #   Twitch.teams do |team|
+    #     next if (Time.now - team.updated_at) > (60 * 60 * 24)
+    #     puts team.url
+    #   end
     # @param options [Hash] Filter criteria.
-    # @option options [Fixnum] :limit (none) Limit on the number of results returned.
+    # @option options [Fixnum] :limit (nil) Limit on the number of results returned.
+    # @yield Optional. If a block is given, each team is yielded.
+    # @yieldparam [Team] team Current team.
     # @see https://github.com/justintv/Twitch-API/blob/master/v2_resources/teams.md#get-teams GET /teams
-    # @return [Array<Team>] List of all active teams.
-    def all(options = {})
+    # @return [Array<Team>] All active teams, if no block is given.
+    # @return [nil] If a block is given.
+    def all(options = {}, &block)
       return @query.connection.accumulate(
         :path => 'teams',
         :json => 'teams',
         :create => Team,
         :limit => options[:limit],
-        :offset => options[:offset]
+        :offset => options[:offset],
+        &block
       )
     end
   end

data/lib/kappa/user.rb

@@ -54,27 +54,39 @@ module Twitch::V2
     end
 
     # Get the channels the user is currently following.
+    # @example
+    #   user.following(:limit => 10)
+    # @example
+    #   user.following do |channel|
+    #     next if channel.game_name !~ /starcraft/i
+    #     puts channel.display_name
+    #   end
     # @param options [Hash] Filter criteria.
-    # @option options [Fixnum] :limit (none) Limit on the number of results returned.
+    # @option options [Fixnum] :limit (nil) Limit on the number of results returned.
     # @option options [Fixnum] :offset (0) Offset into the result set to begin enumeration.
+    # @yield Optional. If a block is given, each followed channel is yielded.
+    # @yieldparam [Channel] channel Current channel.
     # @see #following?
     # @see https://github.com/justintv/Twitch-API/blob/master/v2_resources/follows.md#get-usersuserfollowschannels GET /users/:user/follows/channels
-    # @return [Array<Channel>] List of channels the user is currently following.
-    def following(options = {})
+    # @return [Array<Channel>] Channels the user is currently following, if no block is given.
+    # @return [nil] If a block is given.
+    def following(options = {}, &block)
+      name = CGI.escape(@name)
       return @query.connection.accumulate(
-        :path => "users/#{@name}/follows/channels",
+        :path => "users/#{name}/follows/channels",
         :json => 'follows',
         :sub_json => 'channel',
         :create => -> hash { Channel.new(hash, @query) },
         :limit => options[:limit],
-        :offset => options[:offset]
+        :offset => options[:offset],
+        &block
       )
     end
 
-    # @param channel [String/Channel/User/Stream/#name] The name of the channel to check.
+    # @param target [String, Channel, User, Stream, #name] The name of the channel to check.
     # @return [Boolean] `true` if the user is following the channel, `false` otherwise.
     # @see #following
-    # @see https://github.com/justintv/Twitch-API/blob/master/v2_resources/follows.md#get-usersuserfollowschannelstarget GET /users/:user/follows/:channels/:target
+    # @see https://github.com/justintv/Twitch-API/blob/master/v2_resources/follows.md#get-usersuserfollowschannelstarget GET /users/:user/follows/channels/:target
     def following?(target)
       name = if target.respond_to?(:name)
         target.name
@@ -82,11 +94,13 @@ module Twitch::V2
         target.to_s
       end
 
-      name = CGI.escape(name)
+      user_name = CGI.escape(@name)
+      channel_name = CGI.escape(name)
 
-      json = @query.connection.get("users/#{@name}/follows/channels/#{name}")
-      status = json['status']
-      return !status || (status != 404)
+      Twitch::Status.map(404 => false) do
+        @query.connection.get("users/#{user_name}/follows/channels/#{channel_name}")
+        true
+      end
     end
 
     # @example
@@ -135,11 +149,9 @@ module Twitch::V2
     # @see https://github.com/justintv/Twitch-API/blob/master/v2_resources/users.md#get-usersuser GET /users/:user
     # @return [User] A valid `User` object if the user exists, `nil` otherwise.
     def get(user_name)
-      encoded_name = CGI.escape(user_name)
-      json = @query.connection.get("users/#{encoded_name}")
-      if !json || json['status'] == 404
-        nil
-      else
+      name = CGI.escape(user_name)
+      Twitch::Status.map(404 => nil) do
+        json = @query.connection.get("users/#{name}")
         User.new(json, @query)
       end
     end

data/lib/kappa/version.rb

@@ -1,3 +1,3 @@
 module Twitch
-  VERSION = '0.4.0'
+  VERSION = '1.0.0'
 end

data/lib/kappa/video.rb

@@ -120,11 +120,9 @@ module Twitch::V2
     def get(id)
       raise ArgumentError, 'id' if !id || id.strip.empty?
 
-      encoded_id = CGI.escape(id)
-      json = @query.connection.get("videos/#{encoded_id}")
-      if !json || json['status'] == 404
-        nil
-      else
+      id = CGI.escape(id)
+      Twitch::Status.map(404 => nil) do
+        json = @query.connection.get("videos/#{id}")
         Video.new(json, @query)
       end
     end
@@ -137,15 +135,23 @@ module Twitch::V2
     #   Twitch.videos.top(:period => :month, :game => 'Super Meat Boy')
     # @example
     #   Twitch.videos.top(:period => :all, :limit => 10)
+    # @example
+    #   Twitch.videos.top(:period => :all) do |video|
+    #     next if video.view_count < 10000
+    #     puts video.url
+    #   end
     # @param options [Hash] Filter criteria.
     # @option options [Symbol] :period (:week) Return videos only in this time period. Valid values are `:week`, `:month`, `:all`.
     # @option options [String] :game (nil) Return videos only for this game.
-    # @option options [Fixnum] :limit (none) Limit on the number of results returned.
+    # @option options [Fixnum] :limit (nil) Limit on the number of results returned.
     # @option options [Fixnum] :offset (0) Offset into the result set to begin enumeration.
+    # @yield Optional. If a block is given, each top video is yielded.
+    # @yieldparam [Video] video Current video.
     # @see https://github.com/justintv/Twitch-API/blob/master/v2_resources/videos.md#get-videostop GET /videos/top
     # @raise [ArgumentError] If `:period` is not one of `:week`, `:month`, or `:all`.
-    # @return [Array<Video>] List of top videos.
-    def top(options = {})
+    # @return [Array<Video>] Top videos, if no block is given.
+    # @return [nil] If a block is given.
+    def top(options = {}, &block)
       params = {}
 
       if options[:game]
@@ -165,6 +171,57 @@ module Twitch::V2
         :json => 'videos',
         :create => -> hash { Video.new(hash, @query) },
         :limit => options[:limit],
+        :offset => options[:offset],
+        &block
+      )
+    end
+
+    # Get the videos for a channel, most recently created first.
+    # @example
+    #   v = Twitch.videos.for_channel('dreamhacktv')
+    # @example
+    #   v = Twitch.videos.for_channel('dreamhacktv', :type => :highlights, :limit => 10)
+    # @example
+    #   Twitch.videos.for_channel('dreamhacktv') do |video|
+    #     next if video.view_count < 10000
+    #     puts video.url
+    #   end
+    # @param options [Hash] Filter criteria.
+    # @option options [Symbol] :type (:highlights) The type of videos to return. Valid values are `:broadcasts`, `:highlights`.
+    # @option options [Fixnum] :limit (nil) Limit on the number of results returned.
+    # @option options [Fixnum] :offset (0) Offset into the result set to begin enumeration.
+    # @yield Optional. If a block is given, each video is yielded.
+    # @yieldparam [Video] video Current video.
+    # @see Channel#videos Channel#videos
+    # @see https://github.com/justintv/Twitch-API/blob/master/v2_resources/videos.md#get-channelschannelvideos GET /channels/:channel/videos
+    # @raise [ArgumentError] If `:type` is not one of `:broadcasts` or `:highlights`.
+    # @return [Array<Video>] Videos for the channel, if no block is given.
+    # @return [nil] If a block is given.
+    def for_channel(channel, options = {})
+      if channel.respond_to?(:name)
+        channel_name = channel.name
+      else
+        channel_name = channel.to_s
+      end
+
+      params = {}
+
+      type = options[:type] || :highlights
+      if !type.nil?
+        if ![:broadcasts, :highlights].include?(type)
+          raise ArgumentError, 'type'
+        end
+
+        params[:broadcasts] = (type == :broadcasts)
+      end
+
+      name = CGI.escape(channel_name)
+      return @query.connection.accumulate(
+        :path => "channels/#{name}/videos",
+        :params => params,
+        :json => 'videos',
+        :create => -> hash { Video.new(hash, @query) },
+        :limit => options[:limit],
         :offset => options[:offset]
       )
     end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: kappa
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 1.0.0
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-07-22 00:00:00.000000000 Z
+date: 2013-08-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: httparty
@@ -171,8 +171,8 @@ dependencies:
     - - ! '>='
       - !ruby/object:Gem::Version
         version: '0'
-description: ! "    A Ruby library for interfacing with the Twitch.tv API\n    including
-  users, channels, streams, and followers.\n"
+description: ! "    The Ruby library for interfacing with the Twitch.tv API\n    including
+  users, channels, streams, games, and videos.\n"
 email: schmch@gmail.com
 executables: []
 extensions: []
@@ -185,8 +185,10 @@ files:
 - lib/kappa/team.rb
 - lib/kappa/images.rb
 - lib/kappa/user.rb
+- lib/kappa/status.rb
 - lib/kappa/id_equality.rb
 - lib/kappa/query.rb
+- lib/kappa/errors.rb
 - lib/kappa/channel.rb
 - lib/kappa/proxy.rb
 - lib/kappa/game.rb