uservoice-ruby 0.0.1

data/.gitignore

@@ -0,0 +1,6 @@
+*.gem
+.bundle
+Gemfile.lock
+pkg/*
+/spec/config.yml
+*.sw*

data/Gemfile

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

data/README.md

@@ -0,0 +1,119 @@
+UserVoice gem for API connections
+=================================
+
+This gem allows you to easily:
+* Generate SSO token for creating SSO users / logging them into UserVoice (http://uservoice.com).
+* Do 3-legged and 2-legged UserVoice API calls safely without having to worry about the cryptographic details.
+
+Installation
+============
+
+Place this in your Gemfile:
+```ruby
+gem 'uservoice', :git => 'https://github.com/uservoice/uservoice-ruby'
+```
+Run the bundle command and then try one of the examples below.
+
+Examples
+========
+
+Prerequisites:
+* Suppose your UserVoice site is at http://uservoice-subdomain.uservoice.com/ and **USERVOICE\_SUBDOMAIN** = uservoice-subdomain
+* **SSO\_KEY** = 982c88f2df72572859e8e23423eg87ed (Admin Console -> Settings -> General -> User Authentication)
+* The account has a following API client (Admin Console -> Settings -> Channels -> API):
+    * **API\_KEY** = oQt2BaunWNuainc8BvZpAm
+    * **API\_SECRET** = 3yQMSoXBpAwuK3nYHR0wpY6opE341inL9a2HynGF2
+
+
+SSO-token generation using uservoice gem
+----------------------------------------
+
+SSO-token can be used to create sessions for SSO users. They are capable of synchronizing the user information from one system to another.
+Generating the SSO token from SSO key and given uservoice subdomain can be done by calling UserVoice.generate\_sso\_token method like this:
+
+```ruby
+require 'uservoice'
+sso_token = UserVoice.generate_sso_token(USERVOICE_SUBDOMAIN, SSO_KEY, {
+    :guid => 1001,
+    :display_name => "John Doe",
+    :email => 'john.doe@example.com'
+})
+
+# Now this URL will log John Doe in:
+puts "https://#{USERVOICE_SUBDOMAIN}.uservoice.com/?sso=#{sso_token}"
+```
+
+Making API calls
+----------------
+
+With the gem you need to create an instance of UserVoice::Oauth. You get
+API_KEY and API_SECRET from an API client which you can create in Admin Console
+-> Settings -> Channels -> API.
+
+```ruby
+require 'uservoice'
+begin
+  uservoice_client = UserVoice::Client.new(USERVOICE_SUBDOMAIN, API_KEY, API_SECRET)
+
+  # Get users of a subdomain (requires trusted client, but no user)
+  users = uservoice_client.get("/api/v1/users.json?per_page=3")['users']
+  users.each do |user|
+    puts "User: \"#{user['name']}\", Profile URL: #{user['url']}"
+  end
+
+  # Now, let's login as mailaddress@example.com, a regular user
+  uservoice_client.login_as('mailaddress@example.com')
+
+  # Example request #1: Get current user.
+  user = uservoice_client.get("/api/v1/users/current.json")['user']
+
+  puts "User: \"#{user['name']}\", Profile URL: #{user['url']}"
+
+  # Login as account owner
+  uservoice_client.login_as_owner
+
+  # Example request #2: Create a new private forum limited to only example.com email domain.
+  forum = uservoice_client.post("/api/v1/forums.json", :forum => {
+    :name => 'Example.com Private Feedback',
+    :private => true,
+    :allow_by_email_domain => true,
+    :allowed_email_domains => [{:domain => 'example.com'}]
+  })['forum']
+
+  puts "Forum '#{forum['name']}' created! URL: #{forum['url']}"
+rescue UserVoice::Unauthorized => e
+  # Thrown usually due to faulty tokens, untrusted client or if attempting
+  # operations without Admin Privileges
+  raise
+end
+```
+
+Verifying a UserVoice user
+--------------------------
+
+If you want to make calls on behalf of a user, but want to make sure he or she
+actually owns certain email address in UserVoice, you need to use 3-Legged API
+calls. Just pass your user an authorize link to click, so that user may grant
+your site permission to access his or her data in UserVoice.
+
+```ruby
+require 'uservoice'
+CALLBACK_URL = 'http://localhost:3000/' # your site
+
+uservoice_client = UserVoice::Client.new(USERVOICE_SUBDOMAIN, API_KEY, API_SECRET, :callback => CALLBACK_URL)
+
+# At this point you want to print/redirect to uservoice_client.authorize_url in your application.
+# Here we just output them as this is a command-line example.
+puts "1. Go to #{uservoice_client.authorize_url} and click \"Allow access\"."
+puts "2. Then type the oauth_verifier which is passed as a GET parameter to the callback URL:"
+
+# In a web app we would get the oauth_verifier through a redirect from UserVoice (after a redirection back to CALLBACK_URL).
+# In this command-line example we just read it from stdin:
+uservoice_client.login_verified_user(gets.match('\w*').to_s)
+
+# All done. Now we can read the current user to know user's email address:
+user = uservoice_client.get("/api/v1/users/current.json")['user']
+
+puts "User logged in, Name: #{user['name']}, email: #{user['email']}"
+```
+

data/Rakefile

@@ -0,0 +1,8 @@
+require 'bundler/gem_tasks'
+require 'rspec/core/rake_task'
+
+task :spec do
+  RSpec::Core::RakeTask.new(:spec) do |t|
+    t.pattern = './spec/**/*_spec.rb'
+  end
+end

data/lib/uservoice/user_voice.rb

@@ -0,0 +1,160 @@
+require "uservoice/version"
+require 'rubygems'
+require 'ezcrypto'
+require 'json'
+require 'cgi'
+require 'base64'
+require 'oauth'
+
+module UserVoice
+  EMAIL_FORMAT = %r{^(\w[-+.\w!\#\$%&'\*\+\-/=\?\^_`\{\|\}~]*@([-\w]*\.)+[a-zA-Z]{2,9})$}
+  DEFAULT_HEADERS = { 'Content-Type'=> 'application/json', 'Accept'=> 'application/json' }
+
+  class APIError < RuntimeError
+  end
+  Unauthorized = Class.new(APIError)
+  NotFound = Class.new(APIError)
+  ApplicationError = Class.new(APIError)
+ 
+  def self.generate_sso_token(subdomain_key, sso_key, user_hash, valid_for = 5 * 60)
+    user_hash[:expires] ||= (Time.now.utc + valid_for).to_s unless valid_for.nil?
+    unless user_hash[:email].to_s.match(EMAIL_FORMAT)
+      raise Unauthorized.new("'#{user_hash[:email]}' is not a valid email address")
+    end
+    unless sso_key.to_s.length > 1
+      raise Unauthorized.new("Please specify your SSO key")
+    end
+
+    key = EzCrypto::Key.with_password(subdomain_key, sso_key)
+    encrypted = key.encrypt(user_hash.to_json)
+    encoded = Base64.encode64(encrypted).gsub(/\n/,'')
+
+    return CGI.escape(encoded)
+  end
+
+  class Client
+
+    def initialize(*args)
+      case args.size
+      when 3,4
+        init_subdomain_and_api_keys(*args)
+      when 1,2
+        init_consumer_and_access_token(*args)
+      end
+    end
+
+    def init_subdomain_and_api_keys(subdomain_name, api_key, api_secret, attrs={})
+      consumer = OAuth::Consumer.new(api_key, api_secret, { 
+        :site => "#{attrs[:protocol] || 'https'}://#{subdomain_name}.#{attrs[:uservoice_domain] || 'uservoice.com'}"
+      })
+      init_consumer_and_access_token(consumer, attrs)
+    end
+
+    def init_consumer_and_access_token(consumer, attrs={})
+      @consumer = consumer
+      @token = OAuth::AccessToken.new(@consumer, attrs[:oauth_token] || '', attrs[:oauth_token_secret] || '')
+      @response_format = attrs[:response_format] || :hash
+      @callback = attrs[:callback]
+    end
+
+    def authorize_url
+      request_token.authorize_url
+    end
+
+    def login_with_verifier(oauth_verifier)
+      token = request_token.get_access_token(:oauth_verifier => oauth_verifier)
+      Client.new(@consumer, :oauth_token => token.token, :oauth_token_secret => token.secret)
+    end
+
+    def login_with_access_token(oauth_token, oauth_token_secret, &block)
+      token = Client.new(@consumer, :oauth_token => oauth_token, :oauth_token_secret => oauth_token_secret)
+      if block_given?
+        yield token
+      else
+        return token
+      end
+    end
+
+    def token
+      @token.token
+    end
+
+    def secret
+      @token.secret
+    end
+
+    def request_token
+      @consumer.get_request_token(:oauth_callback => @callback)
+    end
+
+    def login_as_owner(&block)
+      token = post('/api/v1/users/login_as_owner.json', {
+        'request_token' => request_token.token
+      })['token']
+      if token
+        login_with_access_token(token['oauth_token'], token['oauth_token_secret'], &block)
+      else
+        raise Unauthorized.new("Could not get Access Token")
+      end
+    end
+
+    def login_as(email, &block)
+      unless email.to_s.match(EMAIL_FORMAT)
+        raise Unauthorized.new("'#{email}' is not a valid email address")
+      end
+      token = post('/api/v1/users/login_as.json', {
+        :user => { :email => email },
+        :request_token => request_token.token
+      })['token']
+
+      if token
+        login_with_access_token(token['oauth_token'], token['oauth_token_secret'], &block)
+      else
+        raise Unauthorized.new("Could not get Access Token")
+      end
+    end
+
+    def request(method, uri, request_body={}, headers={})
+      headers = DEFAULT_HEADERS.merge(headers)
+
+      if headers['Content-Type'] == 'application/json' && request_body.is_a?(Hash)
+        request_body = request_body.to_json
+      end
+
+      response = case method.to_sym
+                 when :post, :put
+                   @token.request(method, uri, request_body, headers)
+                 when :head, :delete, :get
+                   @token.request(method, uri, headers)
+                 else
+                   raise RuntimeError.new("Invalid HTTP method #{method}")
+                 end
+
+      return case @response_format.to_s
+             when 'raw'
+               response
+             else
+               attrs = JSON.parse(response.body)
+               if attrs && attrs['errors']
+                 case attrs['errors']['type']
+                 when 'unauthorized'
+                   raise Unauthorized.new(attrs)
+                 when 'record_not_found'
+                   raise NotFound.new(attrs)
+                 when 'application_error'
+                   raise ApplicationError.new(attrs)
+                 else
+                   raise APIError.new(attrs)
+                 end
+               end
+               attrs
+             end
+    end
+
+    %w(get post delete put).each do |method|
+      define_method(method) do |*args|
+        request(method, *args)
+      end
+    end
+  end
+end

data/lib/uservoice/version.rb

@@ -0,0 +1,3 @@
+module Uservoice
+  VERSION = "0.0.1"
+end

data/lib/uservoice-ruby.rb

@@ -0,0 +1 @@
+require 'uservoice/user_voice'

data/spec/config.yml.templ

@@ -0,0 +1,4 @@
+subdomain_name: uservoice
+api_key: GIOIuigIGuisguiGisg3Gd
+api_secret: GIIGDSDUGI678sGoOrGvGJSGISKSDGTEWUfhGoW9Gu
+sso_key: 678bfe76feb876feb786fbe876feb67e

data/spec/lib/user_voice_spec.rb

@@ -0,0 +1,186 @@
+require 'spec_helper'
+
+describe UserVoice do
+
+  it "should generate SSO token" do
+    token = UserVoice.generate_sso_token(config['subdomain_name'], config['sso_key'], {
+      :display_name => "User Name",
+      :email => 'mailaddress@example.com'
+    })
+    encrypted_raw_data = Base64.decode64(CGI.unescape(token))
+
+    key = EzCrypto::Key.with_password(config['subdomain_name'], config['sso_key'])
+    key.decrypt(encrypted_raw_data).should match('mailaddress@example.com')
+  end
+
+  describe UserVoice::Client do
+    subject { UserVoice::Client.new(config['subdomain_name'],
+                                    config['api_key'],
+                                    config['api_secret'],
+                                   :uservoice_domain => config['uservoice_domain'],
+                                   :protocol => config['protocol']) }
+
+    it "should get user names from the API" do
+      users = subject.get("/api/v1/users.json?per_page=3")
+      user_names = users['users'].map { |user| user['name'] }
+      user_names.all?.should == true
+      user_names.size.should == 3
+    end
+
+    it "should not get current user without logged in user" do
+      lambda do
+        user = subject.get("/api/v1/users/current.json")
+      end.should raise_error(UserVoice::Unauthorized)
+    end
+
+    it "should be able to get access token as owner" do
+      subject.login_as_owner do |owner|
+        owner.get("/api/v1/users/current.json")['user']['roles']['owner'].should == true
+
+        owner.login_as('regular@example.com') do |regular|
+          owner.get("/api/v1/users/current.json")['user']['roles']['owner'].should == true
+          @user = regular.get("/api/v1/users/current.json")['user']
+          @user['roles']['owner'].should == false
+        end
+
+        owner.get("/api/v1/users/current.json")['user']['roles']['owner'].should == true
+      end
+      # ensure blocks got run
+      @user['email'].should == 'regular@example.com'
+    end
+
+    it "should not be able to create KB article as nobody" do
+      lambda do
+        result = subject.post("/api/v1/articles.json", :article => {
+          :title => 'good morning'
+        })
+      end.should raise_error(UserVoice::Unauthorized)
+    end
+
+    it "should be able to create and delete a forum as the owner" do
+      owner = subject.login_as_owner
+      forum = owner.post("/api/v1/forums.json", :forum => {
+        :name => 'Test forum from RSpec',
+        'private' => true,
+        'allow_by_email_domain' => true,
+        'allowed_email_domains' => [{'domain' => 'raimo.rspec.example.com'}]
+      })['forum']
+
+      forum['id'].should be_a(Integer)
+
+      deleted_forum = owner.delete("/api/v1/forums/#{forum['id']}.json")['forum']
+      deleted_forum['id'].should == forum['id']
+    end
+
+    it "should get current user with 2-legged call" do
+      user = subject.login_as('mailaddress@example.com') do |token|
+        token.get("/api/v1/users/current.json")['user']
+      end
+
+      user['email'].should == 'mailaddress@example.com'
+    end
+
+    it "should get current user with copied access token" do
+      original_token = subject.login_as('mailaddress@example.com')
+
+      client = UserVoice::Client.new(config['subdomain_name'],
+                                   config['api_key'],
+                                   config['api_secret'],
+                                  :uservoice_domain => config['uservoice_domain'],
+                                  :protocol => config['protocol'],
+                                  :oauth_token => original_token.token,
+                                  :oauth_token_secret => original_token.secret)
+      # Also this works but creates an extra object:
+      # client = client.login_with_access_token(original_token.token, original_token.secret)
+
+      user = client.get("/api/v1/users/current.json")['user']
+
+      user['email'].should == 'mailaddress@example.com'
+    end
+
+    it "should login as an owner" do
+      me = subject.login_as_owner
+
+      owner = me.get("/api/v1/users/current.json")['user']
+      owner['roles']['owner'].should == true
+    end
+
+    it "should not be able to delete when not deleting on behalf of anyone" do
+      lambda {
+        result = subject.delete("/api/v1/users/#{234}.json")
+      }.should raise_error(UserVoice::Unauthorized, /user required/i)
+    end
+
+    it "should not be able to delete owner" do
+      owner_access_token = subject.login_as_owner
+
+      owner = owner_access_token.get("/api/v1/users/current.json")['user']
+
+      lambda {
+        result = owner_access_token.delete("/api/v1/users/#{owner['id']}.json")
+      }.should raise_error(UserVoice::Unauthorized, /last owner/i)
+    end
+
+    it "should not be able to delete user without login" do
+      regular_user = subject.login_as('somebodythere@example.com').get("/api/v1/users/current.json")['user']
+
+      lambda {
+        subject.delete("/api/v1/users/#{regular_user['id']}.json")
+      }.should raise_error(UserVoice::Unauthorized)
+    end
+
+    it "should be able to identify suggestions" do
+      owner_token = subject.login_as_owner
+      external_scope='sync_to_moon'
+      suggestions = owner_token.get("/api/v1/suggestions.json?filter=with_external_id&external_scope=#{external_scope}&manual_action=#{external_scope}")['suggestions']
+
+      identifications = suggestions.map {|s| { :id => s['id'], :external_id => s['id'].to_i*10 } }
+
+      ids = owner_token.put("/api/v1/suggestions/identify.json",
+                          :external_scope => external_scope,
+                          :identifications => identifications)['identifications']['ids']
+      ids.should == identifications.map { |s| s[:id] }.sort
+    end
+
+    it "should be able to delete itself" do
+      my_token = subject.login_as('somebodythere@example.com')
+
+      # whoami
+      my_id = my_token.get("/api/v1/users/current.json")['user']['id']
+
+      # Delete myself!
+      my_token.delete("/api/v1/users/#{my_id}.json")['user']['id'].should == my_id
+
+      # I don't exist anymore
+      lambda {
+        my_token.get("/api/v1/users/current.json")
+      }.should raise_error(UserVoice::NotFound)
+    end
+
+    it "should/be able to delete random user and login as him after that" do
+      somebody = subject.login_as('somebodythere@example.com')
+      owner = subject.login_as_owner
+
+      # somebody is still there...
+      regular_user = somebody.get("/api/v1/users/current.json")['user']
+      regular_user['email'].should == 'somebodythere@example.com'
+
+      # delete somebody!
+      owner.delete("/api/v1/users/#{regular_user['id']}.json")['user']['id'].should == regular_user['id']
+
+      # not found anymore!
+      lambda {
+        somebody.get("/api/v1/users/current.json")['errors']['type']
+      }.should raise_error(UserVoice::NotFound)
+
+      # this recreates somebody
+      somebody = subject.login_as('somebodythere@example.com')
+      somebody.get("/api/v1/users/current.json")['user']['id'].should_not == regular_user['id']
+    end
+
+    it "should raise error with invalid email parameter" do
+      expect { subject.login_as('ma') }.to raise_error(UserVoice::Unauthorized)
+      expect { subject.login_as(nil) }.to raise_error(UserVoice::Unauthorized)
+    end
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,10 @@
+require 'uservoice'
+require 'yaml'
+
+def config
+  begin
+    YAML.load_file(File.expand_path('../config.yml', __FILE__))
+  rescue Errno::ENOENT
+    raise "Configure your own config.yml and place it in the spec directory"
+  end
+end

data/uservoice-ruby.gemspec

@@ -0,0 +1,25 @@
+# -*- encoding: utf-8 -*-
+$:.push File.expand_path("../lib", __FILE__)
+require "uservoice/version"
+
+Gem::Specification.new do |s|
+  s.name        = "uservoice-ruby"
+  s.version     = Uservoice::VERSION
+  s.authors     = ["Raimo Tuisku"]
+  s.email       = ["dev@usevoice.com"]
+  s.homepage    = "http://developer.uservoice.com"
+  s.summary     = %q{Client library for UserVoice API}
+  s.description = %q{The gem provides Ruby-bindings to UserVoice API and helps generating Single-Sign-On tokens.}
+
+  s.rubyforge_project = "uservoice-ruby"
+
+  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_development_dependency "rspec"
+  s.add_runtime_dependency 'ezcrypto'
+  s.add_runtime_dependency 'json'
+  s.add_runtime_dependency 'oauth'
+end

metadata

@@ -0,0 +1,104 @@
+--- !ruby/object:Gem::Specification
+name: uservoice-ruby
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+  prerelease: 
+platform: ruby
+authors:
+- Raimo Tuisku
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2012-09-21 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: &70340927735480 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: *70340927735480
+- !ruby/object:Gem::Dependency
+  name: ezcrypto
+  requirement: &70340927734840 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: *70340927734840
+- !ruby/object:Gem::Dependency
+  name: json
+  requirement: &70340927732680 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: *70340927732680
+- !ruby/object:Gem::Dependency
+  name: oauth
+  requirement: &70340927731780 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: *70340927731780
+description: The gem provides Ruby-bindings to UserVoice API and helps generating
+  Single-Sign-On tokens.
+email:
+- dev@usevoice.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- .gitignore
+- Gemfile
+- README.md
+- Rakefile
+- lib/uservoice-ruby.rb
+- lib/uservoice/user_voice.rb
+- lib/uservoice/version.rb
+- spec/config.yml.templ
+- spec/lib/user_voice_spec.rb
+- spec/spec_helper.rb
+- uservoice-ruby.gemspec
+homepage: http://developer.uservoice.com
+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'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: uservoice-ruby
+rubygems_version: 1.8.15
+signing_key: 
+specification_version: 3
+summary: Client library for UserVoice API
+test_files:
+- spec/config.yml.templ
+- spec/lib/user_voice_spec.rb
+- spec/spec_helper.rb