jtv 0.0.3 → 1.0.0.alpha1

data/CHANGELOG.md

@@ -6,3 +6,8 @@
 
 # v0.0.3
 * Added JtvSearch
+
+# v1.0.0.alpha1
+* Complete rework of the public interface
+* Includes access to Stream API
+

data/LICENSE

@@ -1,4 +1,4 @@
-Copyright (c) 2012 Mockra
+Copyright (c) 2012 David Ratajczak
 
 MIT License
 
@@ -19,4 +19,4 @@ MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
 NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
 LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
 OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
-WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -1,6 +1,6 @@
 # Jtv
 
-This gem allows you to quickly add Justin.TV integration to your Ruby applications. Jtv is a useful tool for providing a list of livestreams, as well as embedding Justin.TV streams and clips.
+This library provides a complete wrapper for the Justin.TV and Twitch.TV APIs.
 
 ## Installation
 
@@ -21,127 +21,79 @@ Or install it yourself as:
 If you want access to higher rate limits for your application, then you
 need to sign up for a [Justin.TV developer account](http://www.justin.tv/developer/activate).
 
-Once you have your API Keys, you'll need to set them up as environment
-variables for them to work with this gem. A great article on environment
-variables can be found at [Heroku](https://devcenter.heroku.com/articles/config-vars).
+Once you have your API Keys, you can set them up using the configuration guide
+below.
 
-``` ruby
-ENV['JTV_CONSUMER_KEY']
-ENV['JTV_CONSUMER_SECRET']
-```
-
-## Usage
-
-The Jtv gem offers various classes depending on the type of information
-you're looking for. JtvChannel and JtvClip should be used for creating records. 
-Jtv methods should be used for updating records.
-
-It's reccomended to cache your requests, and to always keep your
-account's rate limit in mind.
-
-Check out the [RDOC](http://rubydoc.info/github/Mockra/Jtv/).
-
-### Jtv
+## Configuration
 
 ```ruby
-Jtv.channel_viewers( 'channel_handle' )
+  Jtv.configure do |config|
+    config.consumer_key = YOUR_CONSUMER_KEY
+    config.consumer_secret = YOUR_CONSUMER_SECRET
+  end
 ```
 
-This method will return nil if the stream is offline. Use this
-method for providing realtime viewer numbers and stream status.
-
-### JtvSearch
-
-The JtvSearch provides access to the search api. If you pass
-JtvSearch.get a search query, it will return an array of channels.
-This class makes it easy to include a generic livestream list for your
-website.
+If you want to make requests on behalf of a specific user, then you need to
+instantiate a client.
 
 ```ruby
-streams = JtvSearch.get( 'league of legends', 50 )
-# You can pass the get method a search query, as well as
-# an optional stream limit that goes up to 100 and defaults to 20
+  @client = Jtv::Client.new oauth_token: 'users_token',
+    oauth_secret: 'users_secret'
+```
 
-streams.each do |stream|
+## Usage
 
-  stream.id
-  stream.title
-  stream.url
-  stream.viewers
-  stream.image_huge
-  stream.screen_cap_huge
+The Jtv gem offers various methods depending on the type of information
+you're looking for.
 
-end
-```
+It's recommended to cache your requests, and to always keep your
+account's rate limit in mind.
 
-### JtvChannel
+Check out the [RDOC](http://rubydoc.info/github/Mockra/Jtv/).
 
-The JtvChannel class provides access to stream information for a
-specific channel. You'll need to pass the channel handle when you
-initialize your object.
+### Stream
 
-```ruby
-channel = JtvChannel.new( 'channel_handle' )
-```
+#### Summary
 
-You'll then have access to the following information.
+Returns aggregate stream information for all live channels (possibly scoped by
+category).
 
 ```ruby
-channel.viewers
-# Number of current viewers on the stream, requires a second API call
-# If the stream is offline, this will return nil
+  Jtv.summary
+  # {"average_bitrate"=>0, "streams_count"=>4346, "viewers_count"=>"142733"}
 
-Jtv.channel_viewers( 'channel_handle' )
-# This will return nil for offline streams.
-# Use this method for updating current viewers
-
-channel.image_huge
-# 320x240 Image URL
-
-channel.screen_cap_huge
-# 320x240 Screen Capture URL
+  Jtv.summary channel: 'mockra'
+  # {"average_bitrate"=>0, "streams_count"=>0, "viewers_count"=>0}
+```
 
-channel.id
-# The channel handle
+You can include a channel, language, or category in your search params.
 
-channel.embed
-#Code required to embed the Justin.TV Player, response looks like:
-```
+#### List
 
-```
-<object type="application/x-shockwave-flash" height="295" width="353" id="jtv_player_flash" data="http://www.justin.tv/widgets/jtv_player.swf?channel=apidemo&quot; bgcolor="#000000"><param name="allowFullScreen" value="true" /><param name="allowscriptaccess" value="always" /><param name="movie" value="http://www.justin.tv/widgets/jtv_player.swf&quot; /><param name="flashvars" value="channel=apidemo&auto_play=false&start_volume=25" /></object>
-```
+Returns stream information for all live channels. The results are sorted by the
+current number of viewers, with the most popular channels first.
 
 ```ruby
-channel.title
-channel.url
-channel.about
-channel.description
+  Jtv.list category: 'gaming', limit: 1
+  # [{'name' => 'live_user_wingsofdeath'...}]
 ```
 
-### JtvClip
+You can include a channel, category, title, language, limit, and offset.
 
-The JtvClip class provides access to specific clip information. To
-create a clip object, simply pass the clip id when you initialize the
-object.
+#### Search
 
-```ruby
-clip = JtvClip.new( 1278312 )
-```
-
-The following method calls are available through the Clip class.
+Returns stream information for the live channels that match a search query. The
+results are sorted by the current number of viewers, with the most popular
+channels first.
 
 ```ruby
-clip.description
-clip.title
-clip.id
-clip.tags
-clip.embed
-clip.image_huge
-clip.length
-clip.created_on
+  Jtv.search 'gaming', limit: 1
+  # [{'name' => 'live_user_steven_bonnell_ii'...}]
 ```
 
+The first argument is your search query, and you can also pass limit and offset
+as params.
+
 ## Contributing
 
 Contributions and feedback are more than welcome and highly encouraged.

data/jtv.gemspec

@@ -2,11 +2,11 @@
 require File.expand_path('../lib/jtv/version', __FILE__)
 
 Gem::Specification.new do |gem|
-  gem.authors       = ["Mockra"]
+  gem.authors       = ["David Ratajczak"]
   gem.email         = ["david@mockra.com"]
-  gem.description   = %q{Gem for quickly accessing the Justin.TV API}
-  gem.summary       = %q{This tool provides simple Rails integration for common Justin.TV API calls.}
-  gem.homepage      = ""
+  gem.description   = %q{Ruby wrapper for the Justin.tv and Twitch.tv API}
+  gem.summary       = %q{Justin.tv and Twitch.tv API library}
+  gem.homepage      = "http://mockra.com"
 
   gem.files         = `git ls-files`.split($\)
   gem.executables   = gem.files.grep(%r{^bin/}).map{ |f| File.basename(f) }
@@ -15,7 +15,12 @@ Gem::Specification.new do |gem|
   gem.require_paths = ["lib"]
   gem.version       = Jtv::VERSION
 
+  gem.license = 'MIT'
+
   gem.add_development_dependency 'rspec'
+  gem.add_development_dependency 'vcr'
+  gem.add_development_dependency 'fakeweb'
+  gem.add_dependency 'faraday'
   gem.add_dependency 'json'
-  gem.add_dependency 'oauth'
+  gem.add_dependency 'simple_oauth'
 end

data/lib/jtv.rb

@@ -1,61 +1,24 @@
 require "jtv/version"
-require 'jtv/jtv_channel'
-require 'jtv/jtv_clip'
-require 'jtv/jtv_search'
-
-require 'json'
+require 'jtv/configuration'
+require 'jtv/client'
 
 module Jtv
+  class << self
+    include Jtv::Configuration
 
-  require 'oauth'
-
-  # Get current viewers for a specific channel
-  def self.channel_viewers( channel )
-    client = Jtv::JtvClient.new
-    json_data = client.get( "/stream/list.json?channel=#{channel}" )
-    if json_data.body == "[]"
-      return nil
-    else
-      data = JSON.parse( json_data.body )
+    def client
+      @client ||= Jtv::Client.new
     end
-    data[0]['stream_count'].to_i
-  end
-
-  class JtvClient
 
-    # Set API Keys through environment variables.
-    CONSUMER_KEY = ENV['JTV_CONSUMER_KEY']
-    CONSUMER_SECRET = ENV['JTV_CONSUMER_SECRET']
-
-    def initialize
-      @consumer = OAuth::Consumer.new(
-        CONSUMER_KEY,
-        CONSUMER_SECRET,
-        :site => "http://api.justin.tv",
-        :http_method => :get
-      )
+    def respond_to_missing?(method_name, include_private=false)
+      client.respond_to?(method_name, include_private) || super
     end
 
-    def get(path, access_token=nil)
-      (access_token || default_token).get("/api#{path}")
-    end
+  private
 
-    def post(path, post_params, access_token=nil)
-      (access_token || default_token).post("/api#{path}", post_params)
-    end
-
-    def make_request_token
-      @consumer.get_request_token
-    end
-
-    def exchange_request_token_for_access_token(request_token)
-      request_token.get_access_token
-    end
-
-    private
-    def default_token
-      OAuth::AccessToken.new @consumer
+    def method_missing method_name, *args, &block
+      return super unless client.respond_to?(method_name)
+      client.send(method_name, *args, &block)
     end
   end
-
 end

data/lib/jtv/client.rb

@@ -0,0 +1,44 @@
+require 'simple_oauth'
+require 'json'
+require 'faraday'
+require 'jtv/defaults'
+require 'jtv/stream'
+
+module Jtv
+  class Client
+    include Jtv::Defaults
+    include Jtv::Stream
+
+    def initialize args = {}
+      args.each do |key, value|
+        send "#{key}=", value
+      end
+    end
+
+    def get path, params = {}
+      get_json :get, path, params
+    end
+
+  private
+
+    def get_json method, path, params
+      response = request(method, path, params)
+      JSON.parse response[:body]
+    end
+
+    def request method, path, params
+      connection.send method, path, params do |req|
+        req.headers[:authorization] = req_header(method, path, params).to_s
+      end.env
+    end
+
+    def connection
+      @connection ||= Faraday.new 'http://api.justin.tv', options
+    end
+
+    def req_header method, path, params
+      uri = URI "http://api.justin.tv#{path}"
+      SimpleOAuth::Header.new method, uri, params, credentials
+    end
+  end
+end

data/lib/jtv/configuration.rb

@@ -0,0 +1,9 @@
+module Jtv
+  module Configuration
+    attr_accessor :consumer_key, :consumer_secret
+
+    def configure
+      yield self
+    end
+  end
+end

data/lib/jtv/defaults.rb

@@ -0,0 +1,23 @@
+module Jtv
+  module Defaults
+    attr_accessor :oauth_token, :oauth_secret
+
+    def credentials
+      { consumer_key: Jtv.consumer_key,
+        consumer_secret: Jtv.consumer_secret,
+        token: oauth_token || Jtv.oauth_token,
+        token_secret: oauth_secret || Jtv.oauth_secret }
+    end
+
+  private
+
+    def options
+      { headers: {
+          accept: 'application/json',
+          user_agent: 'Jtv Gem' },
+        request: {
+          open_timeout: 2,
+          timeout: 5 } }
+    end
+  end
+end

data/lib/jtv/stream.rb

@@ -0,0 +1,18 @@
+require 'uri'
+
+module Jtv
+  module Stream
+    def summary params = {}
+      get 'stream/summary', params
+    end
+
+    def list params = {}
+      get 'stream/list', params
+    end
+
+    def search query, params = {}
+      query = URI.escape query
+      get "stream/search/#{query}.json", params
+    end
+  end
+end

data/lib/jtv/version.rb

@@ -1,3 +1,3 @@
 module Jtv
-  VERSION = "0.0.3"
+  VERSION = "1.0.0.alpha1"
 end

data/spec/features/stream_spec.rb

@@ -0,0 +1,33 @@
+require 'spec_helper'
+require 'vcr_config'
+
+describe Jtv::Stream do
+  describe '#summary' do
+    use_vcr_cassette
+
+    it 'fetches a live channel' do
+      summary = Jtv.summary channel: 'wingsofdeath'
+      expect(summary['viewers_count']).to eq '14175'
+    end
+  end
+
+  describe '#list' do
+    use_vcr_cassette
+
+    it 'returns a list of streams for a category' do
+      list = Jtv.list category: 'gaming'
+      expect(list.count).to eq 50
+      expect(list.first['title']).to match(/wingsofdeath/i)
+    end
+  end
+
+  describe '#search' do
+    use_vcr_cassette
+
+    it 'returns streams based on search query' do
+      search = Jtv.search 'league of legends', limit: 10
+      expect(search.count).to eq 10
+      expect(search.first['category']).to eq 'gaming'
+    end
+  end
+end

data/spec/jtv/client_spec.rb

@@ -0,0 +1,28 @@
+require_relative '../../lib/jtv/client'
+
+describe Jtv::Client do
+  let(:client) { Jtv::Client.new }
+  let(:request) { Object.new }
+
+  describe '#get' do
+    it 'fetches JSON based on method, path, and params' do
+      client.should_receive(:get_json).with(:get, '/test/', {})
+      client.get '/test/'
+    end
+  end
+
+  context 'when including defaults' do
+    it 'has access to oauth details' do
+      expect(client).to respond_to :oauth_token
+    end
+  end
+
+  context 'when including stream' do
+    it 'has access to summary, list, and search' do
+      expect(client).to respond_to :summary
+      expect(client).to respond_to :list
+      expect(client).to respond_to :search
+    end
+
+  end
+end