klout-rb 1.0.0

data/.gitignore

@@ -0,0 +1,5 @@
+*.gem
+.bundle
+Gemfile.lock
+doc/*
+pkg/*

data/.rspec

@@ -0,0 +1,2 @@
+--color
+--format documentation

data/.travis.yml

@@ -0,0 +1,4 @@
+rvm:
+  - 1.8.7
+  - 1.9.2
+  - 1.9.3

data/Gemfile

@@ -0,0 +1,4 @@
+source "http://rubygems.org"
+
+# Specify your gem's dependencies in ruby-oas.gemspec
+gemspec

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2011 Damian Caruso
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+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.

data/README.md

@@ -0,0 +1,57 @@
+Klout [![Build Status](https://secure.travis-ci.org/cdamian/klout-rb.png)](http://travis-ci.org/cdamian/klout-rb)
+=====
+Ruby wrapper for the Klout REST API
+
+Installation
+------------
+
+Klout is available through [Rubygems](http://rubygems.org/gems/klout-rb) and can be installed via:
+
+    gem install klout-rb
+
+Usage
+-----
+
+#### Configure API key
+
+    Klout::Client.configure do |config|
+      config.api_key = "<YOUR_API_KEY>"
+    end
+
+#### Get users klout score
+
+    Klout::Client.score("ladygaga", "davidguetta").map do |user|
+      "#{user.twitter_screen_name}: #{user.kscore}"
+    end
+
+#### Get users klout profile
+
+    Klout::Client.score("ladygaga", "davidguetta").map do |user|
+      "#{user.twitter_screen_name}: #{user.score.true_reach}"
+    end
+
+#### Get users topics
+
+    Klout::Client.topics("ladygaga", "davidguetta").map do |user|
+      "#{user.twitter_screen_name}: #{user.topics.join(',')}"
+    end
+
+#### Get users influencers
+
+    Klout::Client.influenced_by("ladygaga", "davidguetta").map do |user|
+      "#{user.twitter_screen_name}: #{user.influencers.map { |i| i.twitter_screen_name }.join(',')}"
+    end
+
+#### Get users influencees
+
+    Klout::Client.influencer_of("ladygaga", "davidguetta").map do |user|
+      "#{user.twitter_screen_name}: #{user.influencees.map { |i| i.twitter_screen_name }.join(',')}"
+    end
+
+Performance
+-----------
+
+Klout-rb uses [multi_json](https://github.com/intridea/multi_json) for parsing JSON responses and [HTTPI](https://github.com/rubiii/httpi) for making HTTP requests.
+
+You can use [yajl](https://github.com/brianmario/yajl-ruby) and [httpclient](https://github.com/nahi/httpclient) for better performance.
+

data/Rakefile

@@ -0,0 +1,8 @@
+require 'bundler'
+Bundler::GemHelper.install_tasks
+
+require 'rspec/core/rake_task'
+RSpec::Core::RakeTask.new('spec')
+
+task :test => :spec
+task :default => :spec

data/klout-rb.gemspec

@@ -0,0 +1,30 @@
+# -*- encoding: utf-8 -*-
+$:.push File.expand_path("../lib", __FILE__)
+require "klout/version"
+
+Gem::Specification.new do |s|
+  s.name        = "klout-rb"
+  s.version     = Klout::VERSION
+  s.platform    = Gem::Platform::RUBY
+  s.authors     = ["Damian Caruso"]
+  s.email       = ["damian.caruso@gmail.com"]
+  s.homepage    = "http://github.com/cdamian/klout-rb"
+  s.summary     = %q{Ruby wrapper for the Klout REST API}
+  s.description = %q{Ruby wrapper for the Klout REST API}
+
+  s.rubyforge_project = "klout-rb"
+
+  s.files         = `git ls-files`.split("\n")
+  s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
+  s.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
+  s.require_paths = ["lib"]
+  
+  s.add_dependency "hashie", "~> 1.2.0"
+  s.add_dependency "httpi", "~> 0.9.5"
+  s.add_dependency "multi_json", "~> 1.0.3"
+  
+  s.add_development_dependency "rake", "~> 0.9.2.2"
+  s.add_development_dependency "rspec", "~> 2.7.0"
+  s.add_development_dependency "webmock", "~> 1.7.7"
+end
+

data/lib/klout/client.rb

@@ -0,0 +1,135 @@
+require 'forwardable'
+require 'hashie/mash'
+require 'httpi'
+require 'multi_json'
+require 'rack/utils'
+require 'singleton'
+
+module Klout
+  class Error < StandardError; end
+  class Error::Forbidden < Klout::Error; end
+  class Error::InternalServerError < Klout::Error; end
+  class Error::ServiceUnavailable < Klout::Error; end
+
+  # Public: Class with the necessary methods for performing all Klout API operations.
+  # All API methods are instance methods but can be called on the Client class.
+  class Client
+    include Singleton
+    extend SingleForwardable
+  
+    # Public: Gets/Sets the Klout API key.
+    attr_accessor :api_key
+
+    # Public: Gets/Sets an optional Proxy host to use.
+    attr_accessor :proxy
+
+    # Internal: Delegates api methods to the Klout::Client instance.
+    def_delegators :instance, :score, :profile, :topics, :influenced_by, :influencer_of
+
+    # Public: Configure Klout Client options.
+    #
+    # Yields the Klout::Client instance.
+    #
+    # Returns nothing.
+    def self.configure
+      yield instance if block_given?
+    end
+
+    # Public: Klout REST API endpoint
+    #
+    # Returns the Klout REST API endpoint
+    def self.endpoint
+      'http://api.klout.com'
+    end
+
+    # Public: Retrieve Klout score for the given usernames.
+    # 
+    # usernames - The username or Array of usernames to look for.
+    #
+    # Returns an Array of user klout score objects.
+    def score(usernames)
+      get("/1/klout.json", :users => [usernames].flatten).users
+    end
+
+    # Public: Retrieve users Klout profile for the given usernames.
+    # 
+    # usernames - The username or Array of usernames to look for.
+    #
+    # Returns an Array of user klout profile objects.
+    def profile(usernames)
+      get("/1/users/show.json", :users => [usernames].flatten).users
+    end
+
+    # Public: Retrieve users topics for the given usernames.
+    # 
+    # usernames - The username or Array of usernames to look for.
+    #
+    # Returns an Array of user klout topics objects.
+    def topics(usernames)
+      get("/1/users/topics.json", :users => [usernames].flatten).users
+    end
+
+    # Public: Retrieve users influencers for the given usernames.
+    # 
+    # usernames - The username or Array of usernames to look for.
+    #
+    # Returns an Array of klout users with their corresponding influencers.
+    def influenced_by(usernames)
+      get("/1/soi/influenced_by.json", :users => [usernames].flatten).users
+    end
+
+    # Public: Retrieve users influencees for the given usernames.
+    # 
+    # usernames - The username or Array of usernames to look for.
+    #
+    # Returns an Array of klout users with their corresponding influencees.
+    def influencer_of(usernames)
+      get("/1/soi/influencer_of.json", :users => [usernames].flatten).users
+    end
+
+    private
+    # Internal: Executes a GET HTTP request.
+    # 
+    # path   - The path to make the request again.
+    # params - A Hash with the optionals http params.
+    #
+    # Returns a response object.
+    def get(path, params = {})
+      request = HTTPI::Request.new(build_url(path, params))
+      request.proxy = proxy unless proxy.nil?
+      parse_response(HTTPI.get(request))
+    end
+
+    # Internal: Parses the HTTP response.
+    #
+    # Returns a Mash of the JSON parsed hash.
+    # Raises Klout::Error::Forbidden if Klout api key is not valid.
+    # Raises Klout::Error::InternalServerError if there is a server error in Klout.
+    # Raises Klout::Error::ServiceUnavailable if Klout endpoint is unavailable.
+    def parse_response(response)
+      case response.code.to_i
+      when 403
+        raise Klout::Error::Forbidden.new
+      when 500
+        raise Klout::Error::InternalServerError.new
+      when 503
+        raise Klout::Error::ServiceUnavailable.new
+      end
+      body = ::MultiJson.decode(response.body)
+      raise Klout::Error.new(body['body']['error']) if body.has_key?('body') && body['body'].has_key?('error')
+      Hashie::Mash.new(body)
+    end
+
+    # Internal: Builds the request url.
+    #
+    # path   - The path to make the request again.
+    # params - A Hash with the optionals http params.
+    #
+    # Returns a string url.
+    def build_url(path, params = {})
+      "#{self.class.endpoint}#{path}?#{Rack::Utils.build_query(params.merge(:key => api_key.to_s))}"
+    end
+  end
+
+  HTTPI.log = false
+end

data/lib/klout/version.rb

@@ -0,0 +1,4 @@
+module Klout
+  VERSION = "1.0.0"
+end
+

data/lib/klout-rb.rb

@@ -0,0 +1 @@
+require ::File.expand_path('klout', File.dirname(__FILE__))

data/lib/klout.rb

@@ -0,0 +1,5 @@
+require 'klout/version'
+
+module Klout
+  autoload :Client, 'klout/client'
+end

data/spec/fixtures/klout.json

@@ -0,0 +1,9 @@
+{
+    "status": 200,
+    "users": [
+        {
+            "twitter_screen_name": "damiancaruso",
+            "kscore": 10.86
+        }
+    ]
+}

data/spec/fixtures/no_users.json

@@ -0,0 +1,7 @@
+{
+    "status": 200,
+    "headers": [],
+    "body": {
+        "error": "No users"
+    }
+}

data/spec/fixtures/soi_influenced_by.json

@@ -0,0 +1,18 @@
+{
+    "status": 200,
+    "users": [
+        {
+            "twitter_screen_name": "damiancaruso",
+            "influencers": [
+                {
+                    "twitter_screen_name": "foursquare",
+                    "kscore": 95.71
+                },
+                {
+                    "twitter_screen_name": "rubyconfar",
+                    "kscore": 49.93
+                }
+            ]
+        }
+    ]
+}

data/spec/fixtures/soi_influencer_of.json

@@ -0,0 +1,22 @@
+{
+    "status": 200,
+    "users": [
+        {
+            "twitter_screen_name": "damiancaruso",
+            "influencees": [
+                {
+                    "twitter_screen_name": "manolo22",
+                    "kscore": 12.03
+                },
+                {
+                    "twitter_screen_name": "gorrete",
+                    "kscore": 19.12
+                },
+                {
+                    "twitter_screen_name": "jackiechan",
+                    "kscore": 20.7
+                }
+            ]
+        }
+    ]
+}

data/spec/fixtures/users_show.json

@@ -0,0 +1,23 @@
+{
+    "status": 200,
+    "users": [
+        {
+            "twitter_id": "90718004",
+            "twitter_screen_name": "damiancaruso",
+            "score": {
+                "kscore": 10.86,
+                "slope": -0.32,
+                "description": "",
+                "kclass_id": 1,
+                "kclass": "Observer",
+                "kclass_description": "You don't share very much, but you follow the social web more than you let on. You may just enjoy observing more than sharing or you're checking this stuff out before jumping in full-force.",
+                "kscore_description": "",
+                "network_score": 11.25,
+                "amplification_score": 2,
+                "true_reach": 3,
+                "delta_1day": -0.07,
+                "delta_5day": -0.34
+            }
+        }
+    ]
+}

data/spec/fixtures/users_topics.json

@@ -0,0 +1,15 @@
+{
+    "status": 200,
+    "users": [
+        {
+            "twitter_screen_name": "damiancaruso",
+            "topics": [
+                "humor",
+                "comedy",
+                "babies",
+                "human rights",
+                "entertainment"
+            ]
+        }
+    ]
+}

data/spec/klout_spec.rb

@@ -0,0 +1,134 @@
+require 'spec_helper'
+
+describe Klout::Client do
+  before do
+    @query = {:key => ""}
+  end
+
+  describe "errors" do
+    context "no users found" do
+      before do
+        stub_get("/1/klout.json").with(:query => @query.merge({:users => "damiancaruso"})).
+          to_return(:body => fixture("no_users.json"), :headers => {:content_type => "application/json; charset=utf-8"})
+      end
+
+      it "should raise an error if users are not found" do
+        expect { Klout::Client.score("damiancaruso") }.to raise_error(Klout::Error, "No users")
+      end
+    end
+
+    context "invalid key" do
+      before do
+        stub_get("/1/klout.json").with(:query => @query.merge({:users => "damiancaruso"})).
+          to_return(:status => 403, :body => "<h1> 403 Developer Inactive </h1>", :headers => {:content_type => "application/xml; charset=utf-8"})
+      end
+
+      it "should raise an error if the key is invalid" do
+        expect { Klout::Client.score("damiancaruso") }.to raise_error(Klout::Error::Forbidden)
+      end
+    end
+
+    context "internal server error" do
+      before do
+        stub_get("/1/klout.json").with(:query => @query.merge({:users => "damiancaruso"})).
+          to_return(:status => 500)
+      end
+
+      it "should raise an error if there is a server error in klout" do
+        expect { Klout::Client.score("damiancaruso") }.to raise_error(Klout::Error::InternalServerError)
+      end
+    end
+
+    context "service unavailable" do
+      before do
+        stub_get("/1/klout.json").with(:query => @query.merge({:users => "damiancaruso"})).
+          to_return(:status => 503)
+      end
+
+      it "should raise an error if the service is unavailable" do
+        expect { Klout::Client.score("damiancaruso") }.to raise_error(Klout::Error::ServiceUnavailable)
+      end
+    end
+  end
+
+  describe ".score" do
+    before do
+      stub_get("/1/klout.json").with(:query => @query.merge({:users => "damiancaruso"})).
+        to_return(:body => fixture("klout.json"), :headers => {:content_type => "application/json; charset=utf-8"})
+    end
+
+    it "should get a the klout score object for the given users" do
+      users = Klout::Client.score("damiancaruso")
+      users.first.twitter_screen_name.should_not be_nil
+      users.first.kscore.should be_kind_of(Numeric)
+    end
+  end
+
+  describe ".profile" do
+    before do
+      stub_get("/1/users/show.json").with(:query => @query.merge({:users => "damiancaruso"})).
+        to_return(:body => fixture("users_show.json"), :headers => {:content_type => "application/json; charset=utf-8"})
+    end
+
+    it "should get a the klout user object for the given users" do
+      users = Klout::Client.profile("damiancaruso")
+      users.first.twitter_id.should_not be_nil
+      users.first.twitter_screen_name.should_not be_nil
+      users.first.score.kscore.should be_kind_of(Numeric)
+      users.first.score.slope.should be_kind_of(Numeric)
+      users.first.score.description.should_not be_nil
+      users.first.score.kclass_id.should be_kind_of(Numeric)
+      users.first.score.kclass.should_not be_nil
+      users.first.score.kclass_description.should_not be_nil
+      users.first.score.kscore_description.should_not be_nil
+      users.first.score.network_score.should be_kind_of(Numeric)
+      users.first.score.amplification_score.should be_kind_of(Numeric)
+      users.first.score.true_reach.should be_kind_of(Numeric)
+      users.first.score.delta_1day.should be_kind_of(Numeric)
+      users.first.score.delta_5day.should be_kind_of(Numeric)
+    end
+  end
+
+  describe ".topics" do
+    before do
+      stub_get("/1/users/topics.json").with(:query => @query.merge({:users => "damiancaruso"})).
+        to_return(:body => fixture("users_topics.json"), :headers => {:content_type => "application/json; charset=utf-8"})
+    end
+
+    it "should get a the klout topic object for the given users" do
+      users = Klout::Client.topics("damiancaruso")
+      users.first.twitter_screen_name.should_not be_nil
+      users.first.topics.should be_kind_of(Array)
+    end
+  end
+
+  describe ".influenced_by" do
+    before do
+      stub_get("/1/soi/influenced_by.json").with(:query => @query.merge({:users => "damiancaruso"})).
+        to_return(:body => fixture("soi_influenced_by.json"), :headers => {:content_type => "application/json; charset=utf-8"})
+    end
+
+    it "should get a the klout score object for the given users's influencers" do
+      users = Klout::Client.influenced_by("damiancaruso")
+      users.first.twitter_screen_name.should_not be_nil
+      users.first.influencers.should be_kind_of(Array)
+      users.first.influencers.first.twitter_screen_name.should_not be_nil
+      users.first.influencers.first.kscore.should be_kind_of(Numeric)
+    end
+  end
+
+  describe ".influencer_of" do
+    before do
+      stub_get("/1/soi/influencer_of.json").with(:query => @query.merge({:users => "damiancaruso"})).
+        to_return(:body => fixture("soi_influencer_of.json"), :headers => {:content_type => "application/json; charset=utf-8"})
+    end
+
+    it "should get a the klout score object for the given users's influenceers" do
+      users = Klout::Client.influencer_of("damiancaruso")
+      users.first.twitter_screen_name.should_not be_nil
+      users.first.influencees.should be_kind_of(Array)
+      users.first.influencees.first.twitter_screen_name.should_not be_nil
+      users.first.influencees.first.kscore.should be_kind_of(Numeric)
+    end
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,24 @@
+require 'klout'
+require 'rspec'
+require "webmock/rspec"
+
+# Requires supporting files with custom matchers and macros, etc,
+# in ./support/ and its subdirectories.
+Dir["#{File.dirname(__FILE__)}/support/**/*.rb"].each {|f| require f}
+
+RSpec.configure do |config|
+  config.include WebMock::API
+  config.mock_with :rspec
+end
+
+def stub_get(path)
+  stub_request(:get, Klout::Client.endpoint + path)
+end
+
+def fixture_path
+  File.expand_path("../fixtures", __FILE__)
+end
+
+def fixture(file)
+  File.new(fixture_path + '/' + file)
+end

metadata

@@ -0,0 +1,137 @@
+--- !ruby/object:Gem::Specification
+name: klout-rb
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+  prerelease: 
+platform: ruby
+authors:
+- Damian Caruso
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2011-11-17 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: hashie
+  requirement: &73583900 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 1.2.0
+  type: :runtime
+  prerelease: false
+  version_requirements: *73583900
+- !ruby/object:Gem::Dependency
+  name: httpi
+  requirement: &73583560 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 0.9.5
+  type: :runtime
+  prerelease: false
+  version_requirements: *73583560
+- !ruby/object:Gem::Dependency
+  name: multi_json
+  requirement: &73583260 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 1.0.3
+  type: :runtime
+  prerelease: false
+  version_requirements: *73583260
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: &73582970 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 0.9.2.2
+  type: :development
+  prerelease: false
+  version_requirements: *73582970
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: &73582710 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 2.7.0
+  type: :development
+  prerelease: false
+  version_requirements: *73582710
+- !ruby/object:Gem::Dependency
+  name: webmock
+  requirement: &73582450 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 1.7.7
+  type: :development
+  prerelease: false
+  version_requirements: *73582450
+description: Ruby wrapper for the Klout REST API
+email:
+- damian.caruso@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- .gitignore
+- .rspec
+- .travis.yml
+- Gemfile
+- LICENSE
+- README.md
+- Rakefile
+- klout-rb.gemspec
+- lib/klout-rb.rb
+- lib/klout.rb
+- lib/klout/client.rb
+- lib/klout/version.rb
+- spec/fixtures/klout.json
+- spec/fixtures/no_users.json
+- spec/fixtures/soi_influenced_by.json
+- spec/fixtures/soi_influencer_of.json
+- spec/fixtures/users_show.json
+- spec/fixtures/users_topics.json
+- spec/klout_spec.rb
+- spec/spec_helper.rb
+homepage: http://github.com/cdamian/klout-rb
+licenses: []
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+      segments:
+      - 0
+      hash: 947582353
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+      segments:
+      - 0
+      hash: 947582353
+requirements: []
+rubyforge_project: klout-rb
+rubygems_version: 1.8.10
+signing_key: 
+specification_version: 3
+summary: Ruby wrapper for the Klout REST API
+test_files: []