kappa 0.3.0 → 0.4.0

data/README.md

@@ -7,6 +7,7 @@ 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
 
@@ -17,10 +18,22 @@ gem install kappa
 ```ruby
 require 'kappa'
 
-include Kappa::V2
+frag = Twitch.channels.get('lethalfrag')
+puts frag.streaming?
+```
+
+## Configuration
+
+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.
+
+Your client ID can be specified through configuration, for example:
 
-grubby = Channel.get('followgrubby')
-puts grubby.streaming?
+```ruby
+Twitch.configure do |config|
+  config.client_id = 'sc2daily-v1.0.0'
+end
 ```
 
 ## Overview
@@ -32,7 +45,7 @@ Channels serve as the home location for a [user's](#users) content. Channels hav
 See also [`Channel`](http://rdoc.info/gems/kappa/Kappa/V2/Channel) documentation.
 
 ```ruby
-c = Channel.get('destiny')
+c = Twitch.channels.get('destiny')
 c.nil?        # => false (channel exists)
 c.stream      # => #<Kappa::V2::Stream> (current live stream)
 c.url         # => "http://www.twitch.tv/destiny"
@@ -49,7 +62,7 @@ Streams are video broadcasts that are currently live. They belong to a [user](#u
 See also [`Stream`](http://rdoc.info/gems/kappa/Kappa/V2/Stream) and [`Streams`](http://rdoc.info/gems/kappa/Kappa/V2/Streams) documentation.
 
 ```ruby
-s = Stream.get('idrajit')
+s = Twitch.streams.get('idrajit')
 s.nil?          # => false (currently live)
 s.game_name     # => "StarCraft II: Heart of the Swarm"
 s.viewer_count  # => 7267
@@ -63,7 +76,7 @@ These are members of the Twitch community who have a Twitch account. If broadcas
 See also [`User`](http://rdoc.info/gems/kappa/Kappa/V2/User) documentation.
 
 ```ruby
-u = User.get('snoopeh')
+u = Twitch.users.get('snoopeh')
 u.nil?                    # => false (user exists)
 u.channel                 # => #<Kappa::V2::Channel>
 u.following.map(&:name)   # => ["national_esl1", "dreamhacklol", "riotgames"]
@@ -76,7 +89,7 @@ Videos are broadcasts or highlights owned by a [channel](#channels). Broadcasts
 See also [`Video`](http://rdoc.info/gems/kappa/Kappa/V2/Video) and [`Videos`](http://rdoc.info/gems/kappa/Kappa/V2/Videos) documentation.
 
 ```ruby
-v = Video.get('a395995729')
+v = Twitch.videos.get('a395995729')
 v.nil?          # => false (video exists)
 v.title         # => "DreamHack Open Stockholm 26-27 April"
 v.game_name     # => "StarCraft II: Heart of the Swarm"
@@ -91,7 +104,7 @@ Teams are an organization of [channels](#channels).
 See also [`Team`](http://rdoc.info/gems/kappa/Kappa/V2/Team) documentation.
 
 ```ruby
-t = Team.get('teamliquid')
+t = Twitch.teams.get('teamliquid')
 t.nil?          # => false (team exists)
 t.display_name  # => "TeamLiquid"
 t.info          # => "TeamLiquid is awesome. and esports. video games. \n\n"
@@ -105,12 +118,12 @@ Games are categories (e.g. League of Legends, Diablo 3) used by [streams](#strea
 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.
 
 ```ruby
-top = Games.top(:limit => 3)
+top = Twitch.games.top(:limit => 3)
 top.map(&:name)  # => ["League of Legends", "Dota 2", "StarCraft II: Heart of the Swarm"]
 ```
 
 ```ruby
-g = Games.top(:limit => 1).first
+g = Twitch.games.top(:limit => 1).first
 g.name                   # => "League of Legends"
 g.channel_count          # => 906
 g.viewer_count           # => 79223
@@ -118,7 +131,7 @@ g.box_images.medium_url  # =>"http://static-cdn.jtvnw.net/ttv-boxart/League%20of
 ```
 
 ```ruby
-s = Games.find(:name => 'diablo', :live => true)
+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]
 ```
@@ -149,26 +162,25 @@ backwards-compatible bugfixes will result in a new patch version (e.g. `x.x.1` t
 
 ### Twitch API versions
 
-Twitch supports multiple versions of their API simultaneously, with each version potentially providing different data and behaving differently. Because of this, you must specify which version of the Twitch API you wish to use. With Kappa, this is done with modules.
+Twitch supports multiple versions of their API simultaneously, with each version potentially providing different data
+and behaving differently. Because of this, you can specify which version of the Twitch API you wish to use.
+This is done through Kappa configuration.
 
-For example, if you want to use the v2 Twitch API:
+For example, if you want to use the V2 Twitch API:
 
 ```ruby
-# Option 1: Include the module once.
-include Kappa::V2
-c = Channel.get('day9tv')
-u = User.get('artosis')
-```
-```ruby
-# Option 2: Specify the full class name each time.
-c = Kappa::V2::Channel.get('day9tv')
-u = Kappa::V2::User.get('artosis')
+Twitch.configure do |config|
+  config.client_id = 'sc2daily-v1.0.0'
+  config.api = Twitch::V2
+end
 ```
 
+`Twitch::V2` is the default and is currently the only supported API version.
+
 ## Contributing
 
 - [Fork and clone the repo.](http://help.github.com/fork-a-repo/)
-- [Create a branch for your changes.](http://learn.github.com/p/branching.html)
+- [Create a branch for your changes.](http://git-scm.com/book/en/Git-Branching-Basic-Branching-and-Merging)
 - Run `bundle install` to install development requirements.
 - Implement your feature or bug fix.
 - Add specs under the `spec` folder to prevent regressions or to test new code.

data/lib/kappa.rb

@@ -1,6 +1,8 @@
 require 'kappa/id_equality'
 require 'kappa/proxy'
 require 'kappa/connection'
+require 'kappa/configuration'
+require 'kappa/query'
 require 'kappa/channel'
 require 'kappa/stream'
 require 'kappa/game'
@@ -8,5 +10,4 @@ require 'kappa/video'
 require 'kappa/team'
 require 'kappa/user'
 require 'kappa/images'
-require 'kappa/twitch'
 require 'kappa/version'

data/lib/kappa/channel.rb

@@ -1,19 +1,20 @@
 require 'cgi'
 require 'time'
 
-module Kappa::V2
+module Twitch::V2
   # Channels serve as the home location for a user's content. Channels have a stream, can run
   # commercials, store videos, display information and status, and have a customized page including
   # banners and backgrounds.
-  # @see .get Channel.get
+  # @see Channels#get Channels#get
+  # @see Channels
   # @see Stream
   # @see User
   class Channel
-    include Connection
-    include Kappa::IdEquality
+    include Twitch::IdEquality
 
     # @private
-    def initialize(hash)
+    def initialize(hash, query)
+      @query = query
       @id = hash['_id']
       @background_url = hash['background']
       @banner_url = hash['banner']
@@ -35,21 +36,6 @@ module Kappa::V2
       end
     end
 
-    # Get a channel by name.
-    # @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 self.get(channel_name)
-      encoded_name = CGI.escape(channel_name)
-      json = connection.get("channels/#{encoded_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
-        new(json)
-      end
-    end
-
     # Does this channel have mature content? This flag is specified by the owner of the channel.
     # @return [Boolean] `true` if the channel has mature content, `false` otherwise.
     def mature?
@@ -61,7 +47,7 @@ module Kappa::V2
     # @return [Stream] Live stream object for this channel, or `nil` if the channel is not currently streaming.
     # @see #streaming?
     def stream
-      Stream.get(@name)
+      @query.streams.get(@name)
     end
 
     # Does this channel currently have a live stream?
@@ -76,11 +62,13 @@ module Kappa::V2
     # @note This incurs an additional web request.
     # @return [User] The user that owns this channel.
     def user
-      User.get(@name)
+      @query.users.get(@name)
     end
 
     # 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)
     # @param options [Hash] Filter criteria.
     # @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.
@@ -88,56 +76,141 @@ module Kappa::V2
     # @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 = {})
-      params = {}
-
-      return connection.accumulate(
+      return @query.connection.accumulate(
         :path => "channels/#{@name}/follows",
-        :params => params,
         :json => 'follows',
         :sub_json => 'user',
-        :class => User,
+        :create => -> hash { User.new(hash, @query) },
         :limit => options[:limit],
         :offset => options[:offset]
       )
     end
 
+    # Get the videos for a channel, most recently created first.
+    # @note This incurs additional web requests.
+    # @example
+    #   c = Twitch.channels.get('idrajit')
+    #   v = c.videos(:type => :broadcasts)
+    # @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] :offset (0) Offset into the result set to begin enumeration.
+    # @see Video
+    # @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]
+      )
+    end
+
+    # @example
+    #   23460970
     # @return [Fixnum] Unique Twitch ID.
     attr_reader :id
 
+    # @example
+    #   "http://static-cdn.jtvnw.net/jtv_user_pictures/lethalfrag-channel_background_image-833a4324bc698c9b.jpeg"
     # @return [String] URL for background image.
     attr_reader :background_url
 
+    # @example
+    #   "http://static-cdn.jtvnw.net/jtv_user_pictures/lethalfrag-channel_header_image-463a4670c91c2b61-640x125.jpeg"
     # @return [String] URL for banner image.
     attr_reader :banner_url
 
+    # @example
+    #   2011-07-15 07:53:58 UTC
     # @return [Time] When the channel was created (UTC).
     attr_reader :created_at
 
+    # @example
+    #   "Lethalfrag"
+    # @see #name
     # @return [String] User-friendly display name. This name is used for the channel's page title.
     attr_reader :display_name
 
+    # @example
+    #   "Super Meat Boy"
     # @return [String] Name of the primary game for this channel.
     attr_reader :game_name
 
+    # @example
+    #   "http://static-cdn.jtvnw.net/jtv_user_pictures/lethalfrag-profile_image-050adf252718823b-300x300.png"
     # @return [String] URL for the logo image.
     attr_reader :logo_url
 
+    # @example
+    #   "lethalfrag"
+    # @see #display_name
     # @return [String] Unique Twitch name.
     attr_reader :name
 
+    # @example
+    #   "(Day 563/731) | Dinner and a Game (Cooking at http://twitch.tv/lookatmychicken)"
     # @return [String] Current status set by the channel's owner.
     attr_reader :status
 
+    # @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.
     attr_reader :updated_at
 
+    # @example
+    #   "http://www.twitch.tv/lethalfrag"
     # @return [String] The URL for the channel's main page.
     attr_reader :url
 
+    # @example
+    #   "http://static-cdn.jtvnw.net/jtv_user_pictures/lethalfrag-channel_offline_image-3b801b2ccc11830b-640x360.jpeg"
     # @return [String] URL for the image shown when the stream is offline.
     attr_reader :video_banner_url
 
+    # @see Team
     # @return [Array<Team>] The list of teams that this channel is associated with. Not all channels have associated teams.
     attr_reader :teams
   end
+
+  # Query class for finding channels.
+  # @see Channel
+  class Channels
+    # @private
+    def initialize(query)
+      @query = query
+    end
+
+    # Get a channel by name.
+    # @example
+    #   c = Twitch.channels.get('day9tv')
+    # @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}")
+
+      # HTTP 422 can happen if the channel is associated with a Justin.tv account.
+      if !json || json['status'] == 404 || json['status'] == 422
+        nil
+      else
+        Channel.new(json, @query)
+      end
+    end
+  end
 end

data/lib/kappa/configuration.rb

@@ -0,0 +1,54 @@
+require 'securerandom'
+
+module Twitch
+  @query = nil
+
+  # Configure global settings for interacting with Twitch. Future requests will use these settings.
+  # @example
+  #   Twitch.configure do |config|
+  #     config.client_id = 'sc2daily-v1.0.0'
+  #     config.api = Twitch::V2
+  #   end
+  def self.configure(&block)
+    @query = instance(&block)
+  end
+
+  def self.instance(&block)
+    config = Configuration.new
+    config.instance_eval(&block)
+    connection = config.create(:Connection, config.client_id)
+    return config.create(:Query, connection)
+  end
+
+  def self.method_missing(*args)
+    @query ||= create_default_query
+    @query.send(*args)
+  end
+
+  # @private
+  class Configuration
+    def initialize
+      @api = Twitch::V2
+    end
+
+    def client_id
+      # Generate a random client_id if it's not already set.
+      @client_id ||= "Kappa-%s" % SecureRandom.uuid
+      @client_id
+    end
+
+    def create(symbol, *args)
+      @api.const_get(symbol).new(*args)
+    end
+
+    attr_writer :client_id
+    attr_accessor :api
+  end
+
+private
+  def self.create_default_query
+    config = Configuration.new
+    connection = config.create(:Connection, config.client_id)
+    return config.create(:Query, connection)
+  end
+end

data/lib/kappa/connection.rb

@@ -1,30 +1,27 @@
 require 'httparty'
 require 'addressable/uri'
-require 'securerandom'
 require 'json'
-require 'singleton'
 require 'set'
 
-module Kappa
+module Twitch
   # @private
-  class ConnectionBase
+  class Connection
     include HTTParty
 
-    def initialize(base_url = DEFAULT_BASE_URL)
+    def initialize(client_id, base_url = DEFAULT_BASE_URL)
+      @client_id = client_id
       @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 = {
+      all_headers = {
         'Client-ID' => @client_id,
-      }.merge(custom_headers)
+        'Kappa-Version' => Twitch::VERSION
+      }.merge(headers())
 
-      response = self.class.get(request_url, :headers => headers, :query => query)
+      response = self.class.get(request_url, :headers => all_headers, :query => query)
 
       json = response.body
       return JSON.parse(json)
@@ -35,11 +32,16 @@ module Kappa
       params = options[:params] || {}
       json = options[:json]
       sub_json = options[:sub_json]
-      klass = options[:class]
+      create = options[:create]
 
       raise ArgumentError, 'json' if json.nil?
       raise ArgumentError, 'path' if path.nil?
-      raise ArgumentError, 'class' if klass.nil?
+      raise ArgumentError, 'create' if create.nil?
+
+      if create.is_a? Class
+        klass = create
+        create = -> hash { klass.new(hash) }
+      end
 
       total_limit = options[:limit]
       page_limit = [total_limit || 100, 100].min
@@ -48,11 +50,11 @@ module Kappa
       objects = []
       ids = Set.new
 
-      paginated(path, page_limit, offset, params) do |response_json|
+      paginate(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)
+          object = create.call(object_json)
           if ids.add?(object.id)
             objects << object
             if !total_limit.nil? && (objects.count == total_limit)
@@ -67,7 +69,7 @@ module Kappa
       return objects
     end
 
-    def paginated(path, limit, offset, params = {})
+    def paginate(path, limit, offset, params = {})
       path_uri = Addressable::URI.parse(path)
       query = { 'limit' => limit, 'offset' => offset }
       path_uri.query_values ||= {}
@@ -91,7 +93,7 @@ module Kappa
         break if total && (offset > total)
 
         request_url = next_url
-        json = get(request_url)
+        json = get(request_url, params)
       end
     end
 
@@ -100,30 +102,11 @@ module Kappa
   end
 end
 
-module Kappa::V2
+module Twitch::V2
   # @private
-  module Connection
-    class Impl < Kappa::ConnectionBase
-      include Singleton
-
-    private
-      def custom_headers
+  class Connection < Twitch::Connection
+      def 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