njacobeus-tokboxer 0.1.1

data/History.txt

@@ -0,0 +1,19 @@
+== 0.1.1 2008-11-26
+
+* Fixed config problem causing missing files in the gem
+
+== 0.1.0 2008-11-13
+
+* First gem release
+
+== 0.0.2 2008-11-05
+
+* Added classes VMail and Call
+* Corrected bug with url encoding (didn't deal properly with spaces in params)
+* Some stupid bugs removed
+* Added some documentation and cleaned the gem
+* Removed useless dependency on rest-client (just using Net::HTTP now)
+
+== 0.0.1 2008-11-03
+
+* Initial release with all the methods implemented

data/Manifest.txt

@@ -0,0 +1,24 @@
+History.txt
+Manifest.txt
+PostInstall.txt
+README.rdoc
+Rakefile
+config/website.yml.sample
+lib/TokBoxer.rb
+lib/TokBoxer/Api.rb
+lib/TokBoxer/Call.rb
+lib/TokBoxer/User.rb
+lib/TokBoxer/VMail.rb
+script/console
+script/destroy
+script/generate
+script/txt2html
+spec/TokBoxer_spec.rb
+spec/spec.opts
+spec/spec_helper.rb
+tasks/rspec.rake
+website/index.html
+website/index.txt
+website/javascripts/rounded_corners_lite.inc.js
+website/stylesheets/screen.css
+website/template.html.erb

data/PostInstall.txt

@@ -0,0 +1,7 @@
+
+For more information on TokBoxer, see http://TokBoxer.rubyforge.org
+
+NOTE: Change this information in PostInstall.txt 
+You can also delete it if you don't want it.
+
+

data/README.rdoc

@@ -0,0 +1,109 @@
+= TokBoxer
+
+* http://github.com/njacobeus/tokboxer/
+
+== DESCRIPTION:
+
+This is a ruby implementation of the TokBox API. Tokbox is a free video calling / video mailing platform (see http://www.tokbox.com).
+
+All API methods specified in the Tokbox Developer API wiki (http://developers.tokbox.com/index.php/API) are implemented but not all objects yet. So you may have to dig into the hash returned by the call (XML converted to a Ruby hash).
+
+For the moment, this gem currently specifically serves our needs for the implementation of video conversations and video mails on iStockCV (www.istockcv.com), an online recruitment network which we are developing. Your needs may vary so feel free to contact me (nj@belighted.com).
+
+== FEATURES/PROBLEMS:
+
+* Features currently available:
+
+  * Create a guest user or register a user on TokBox
+
+  * Get information about a user
+
+  * Create a call
+
+  * Retrieve the list of vmails for a user
+
+  * Generate embed codes for a player, a recorder, and a call
+
+* Limitations:
+
+  * For the moment, the Call and VMail objects are quite simple (they only hold an id)
+
+  * No tests yet (ouch)
+
+== SYNOPSIS:
+
+  # To create an instance of the API object:
+
+  api  = TokBoxer::Api.new(partner_key, partner_secret, api_server_url) # defaults to "http://sandbox.tokbox.com/"
+
+  # To create a user instance:
+
+  user = api.create_guest_user
+  # or
+  user = api.register_user(firstname, lastname, email)
+  # or if you have already created a user previously on TokBox
+  user = api.create_user(user_jabber_id, user_secret)
+
+  # To get info about the user object:
+
+  user.access_token_valid? # returns true or false whether the secret of the user is correct or not
+  user.is_online?
+  user.display_name
+  user.username
+  user.userid
+  user.show
+
+  # To embed a player or a recorder:
+  
+  user.recorder_embed_code(width, height)           # returns the HTML for embedding a recorder
+  user.player_embed_code(message_id, width, height) # returns the HTML for embedding a player for a specific message
+
+  # To create a call:
+
+  call = user.create_call("My full name") # set "true" as 2nd param if you want it persistent
+  call.embed_code                         # returns the HTML for embedding the call in a web page
+
+  # To manipulate vmails:
+
+  user.vmails          # returns an array of VMail objects for all the vmails in the user's feed
+  user.sent_vmails     # returns an array of VMail objects for sent vmails only
+  user.received_vmails # returns an array of VMail objects for received vmails only
+
+== REQUIREMENTS:
+
+* xml-simple
+* A partner key and a partner secret at Tokbox (you can get those here: http://developers.tokbox.com/index.php/Main_Page)
+
+== INSTALL:
+
+* gem sources -a http://gems.github.com
+* sudo gem install njacobeus-tokboxer
+
+OR (from RubyForge)
+
+* sudo gem install tokboxer
+
+== LICENSE:
+
+(The MIT License)
+
+Copyright (c) 2008 Nicolas Jacobeus - Belighted SPRL (http://www.belighted.com/)
+
+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/Rakefile

@@ -0,0 +1,28 @@
+%w[rubygems rake rake/clean fileutils newgem rubigen].each { |f| require f }
+require File.dirname(__FILE__) + '/lib/TokBoxer'
+
+# Generate all the Rake tasks
+# Run 'rake -T' to see list of generated tasks (from gem root directory)
+$hoe = Hoe.new('tokboxer', TokBoxer::VERSION) do |p|
+  p.developer('Nicolas Jacobeus', 'nj@belighted.com')
+  p.changes              = p.paragraphs_of("History.txt", 0..1).join("\n\n")
+  #p.post_install_message = 'PostInstall.txt' # TODO remove if post-install message not required
+  p.rubyforge_name       = p.name # TODO this is default value
+  p.extra_deps         = [
+    ['xml-simple','>= 1.0.11'],
+  ]
+  p.extra_dev_deps = [
+    ['newgem', ">= #{::Newgem::VERSION}"]
+  ]
+  
+  p.clean_globs |= %w[**/.DS_Store tmp *.log]
+  path = (p.rubyforge_name == p.name) ? p.rubyforge_name : "\#{p.rubyforge_name}/\#{p.name}"
+  p.remote_rdoc_dir = File.join(path.gsub(/^#{p.rubyforge_name}\/?/,''), 'rdoc')
+  p.rsync_args = '-av --delete --ignore-errors'
+end
+
+require 'newgem/tasks' # load /tasks/*.rake
+Dir['tasks/**/*.rake'].each { |t| load t }
+
+# TODO - want other tests/tasks run by default? Add them to the list
+# task :default => [:spec, :features]

data/config/website.yml.sample

@@ -0,0 +1,2 @@
+host: unknown@rubyforge.org
+remote_dir: /var/www/gforge-projects/TokBoxer

data/lib/TokBoxer.rb

@@ -0,0 +1,28 @@
+$:.unshift(File.dirname(__FILE__)) unless
+  $:.include?(File.dirname(__FILE__)) || $:.include?(File.expand_path(File.dirname(__FILE__)))
+
+require 'rubygems'
+require 'net/http'
+require 'uri'
+require 'digest/md5'
+#require 'rest_client'
+require 'cgi'
+require 'xmlsimple'
+require 'pp' # just for debugging purposes
+
+module TokBoxer
+  VERSION = '0.1.1'
+  
+  API_SERVER_LOGIN_URL       = "view/oauth&"
+  API_SERVER_METHODS_URL     = "a/v0"
+  API_SERVER_CALL_WIDGET     = "vc/"
+  API_SERVER_RECORDER_WIDGET = "vr/"
+  API_SERVER_PLAYER_WIDGET   = "vp/"
+  API_VERSION                = "1.0.0"
+  API_SIGNATURE_METHOD       = "SIMPLE-MD5"
+end
+
+require 'TokBoxer/Api'
+require 'TokBoxer/User'
+require 'TokBoxer/Call'
+require 'TokBoxer/VMail'

data/lib/TokBoxer/Api.rb

@@ -0,0 +1,290 @@
+module TokBoxer
+
+  class Api
+
+    attr_reader :api_server_url, :api_key
+
+    # Call API actions =================================================================================
+
+    def create_call(callerJabberId, callerName, persistent=false, features="")
+      method = "POST"
+      call = "/calls/create"
+      params = { :callerJabberId => callerJabberId, :callerName => callerName, :persistent => persistent, :features => features }
+      result = request(method, call, params)
+    end
+
+    def create_invite(callerJabberId, calleeJabberId, call_id)
+      method = "POST"
+      call = "/calls/invite"
+      params = { :callerJabberId => callerJabberId, :calleeJabberId => calleeJabberId, :call_id => call_id }
+      result = request(method, call, params)
+    end
+
+    def join_call(invite_id)
+      method = "POST"
+      call = "/calls/join"
+      params = { :invite_id => invite_id }
+      result = request(method, call, params)
+    end
+
+    # Contacts API Actions =============================================================================
+
+    def add_contact(jabberId, remoteJabberId)
+      method = "POST"
+      call = "/contacts/request"
+      params = { :jabberId => jabberId, :remoteJabberId => remoteJabberId }
+      result = request(method, call, params)
+    end
+
+    def is_friend(jabberId, remoteJabberId)
+      method = "POST"
+      call = "/contacts/getRelation"
+      params = { :jabberId => jabberId, :remoteJabberId => remoteJabberId }
+      result = request(method, call, params)
+    end
+
+    def remove_contact(jabberId, remoteJabberId)
+      method = "POST"
+      call = "/contacts/remove"
+      params = { :jabberId => jabberId, :remoteJabberId => remoteJabberId }
+      result = request(method, call, params)
+    end
+
+    def reject_contact(jabberId, remoteJabberId)
+      method = "POST"
+      call = "/contacts/reject"
+      params = { :jabberId => jabberId, :remoteJabberId => remoteJabberId }
+      result = request(method, call, params)
+    end
+
+    # Feed API actions =================================================================================
+
+    def add_comment(posterjabberId, vmailmessageid, commenttext, vmailcontentid)
+      method = "POST"
+      call = "/vmail/addcomment"
+      params = { :posterjabberId => posterjabberId, :vmailmessageid => vmailmessageid, :commenttext => commenttext, :vmailcontentid => vmailcontentid }
+      result = request(method, call, params)
+    end
+
+    def delete_missed_call_from_feed(jabberId, invite_id)
+      method = "POST"
+      call = "/callevent/delete"
+      params = { :jabberId => jabberId, :invite_id => invite_id }
+      result = request(method, call, params)
+    end
+
+    def delete_vmail_from_feed(message_id, type)
+      method = "POST"
+      call = "/vmail/delete"
+      params = { :message_id => message_id, :type => type }
+      result = request(method, call, params)
+    end
+
+    def get_all_of_the_comments_on_a_post(message_id, start = nil, count = nil)
+      method = "POST"
+      call = "/vmail/getcomments"
+      params = { :message_id => message_id, :start => start, :count => count }
+      result = request(method, call, params)
+    end
+
+    def get_feed(jabberId, filter=nil, start=nil, count=nil, sort=nil, dateRange=nil)
+      method = "POST"
+      call = "/feed/getFeed"
+      params = { :jabberId => jabberId, :filter => filter, :start => start, :count => count, :sort => sort, :dateRange => nil }
+      result = request(method, call, params)
+    end
+
+    def get_feed_unread_count(jabberId)
+      method = "POST"
+      call = "/feed/unreadCount"
+      params = { :jabberId => jabberId }
+      result = request(method, call, params)
+    end
+
+    def mark_missed_call_as_read_in_feed(jabberId, invite_id)
+      method = "POST"
+      call = "/callevent/markasviewed"
+      params = { :jabberId => jabberId, :invite_id => invite_id }
+      result = request(method, call, params)
+    end
+
+    def mark_vmail_as_read(message_id)
+      method = "POST"
+      call = "/vmail/markasviewed"
+      params = { :message_id => message_id }
+      result = request(method, call, params)
+    end
+
+    # Token API actions ================================================================================
+
+    def get_access_token(jabberId, password)
+      method = "POST"
+      call = "/auth/getAccessToken"
+      params = { :jabberId => jabberId, :password => password }
+      result = request(method, call, params, @api_secret)
+    end
+
+    def get_request_token(callbackUrl)
+      method = "POST"
+      call = "/auth/getRequestToken"
+      params = { :callbackUrl => callbackUrl }
+      result = request(method, call, params, @api_secret)
+    end
+
+    def validate_access_token(jabberId, accessSecret)
+      method = "POST"
+      call = "/auth/validateAccessToken"
+      params = { :jabberId => jabberId, :accessSecret => accessSecret }
+      result = request(method, call, params, @api_secret)
+    end
+
+    # User API actions =================================================================================
+
+    def login_user(jabberId, secret)
+      @jabberId = jabberId
+      @secret = secret
+    end
+    
+    def create_user(jabberId, secret)
+      TokBoxer::User.new(jabberId, secret, self)
+    end
+
+    def create_guest_user
+      method = "POST"
+      call = "/users/createGuest"
+      params = { :partnerKey => @api_key }
+      result = request(method, call, params, @api_secret)
+      if result['error']
+        return nil # error
+      else
+        return create_user(result["createGuest"].first["jabberId"].first, result["createGuest"].first["secret"].first)
+      end
+    end
+
+    def register_user(firstname,lastname,email)
+      method = "POST"
+      call = "/users/register"
+      params = { :firstname => firstname, :lastname => lastname, :email => email }
+      result = request(method, call, params, @api_secret)
+      if result['error']
+        return nil # error
+      else
+        return create_user(result["registerUser"].first["jabberId"].first, result["registerUser"].first["secret"].first)
+      end
+    end
+
+    def get_user_profile(jabberId)
+      @jabberId = jabberId
+      method = "POST"
+      call = "/users/getProfile"
+      params = { :jabberId => jabberId }
+      result = request(method, call, params)
+    end
+
+    # VMail API actions ================================================================================
+
+    def forward_vmail(vmail_id, senderJabberId, text="", tokboxRecipients="", emailRecipients="")
+      method = "POST"
+      call = "/vmail/forward"
+      params = { :vmail_id => vmail_id, :senderJabberId => senderJabberId, :text => text, :tokboxRecipients => tokboxRecipients, :emailRecipients => emailRecipients }
+      result = request(method, call, params)
+    end
+
+    def forward_vmail_to_all_friends(vmail_id, senderJabberId, text="")
+      method = "POST"
+      call = "/vmail/forwardToFriends"
+      params = { :vmail_id => vmail_id, :senderJabberId => senderJabberId, :text => text }
+      result = request(method, call, params)
+    end
+
+    def get_vmail(message_id)
+      method = "POST"
+      call = "/vmail/getVmail"
+      params = { :message_id => message_id }
+      result = request(method, call, params)
+    end
+
+    def post_public_vmail(vmail_id, scope, senderJabberId, text)
+      method = "POST"
+      call = "/vmail/postPublic"
+      params = { :vmail_id => vmail_id, :scope => scope, :senderJabberId => senderJabberId, :text => text }
+      result = request(method, call, params)
+    end
+
+    def send_vmail(vmail_id, senderJabberId, text="", tokboxRecipients="", emailRecipients="")
+      method = "POST"
+      call = "/vmail/send"
+      params = { :vmail_id => vmail_id, :senderJabberId => senderJabberId, :text => text, :tokboxRecipients => tokboxRecipients, :emailRecipients => emailRecipients }
+      result = request(method, call, params)
+    end
+
+    def send_vmail_to_alL_friends(vmail_id, senderJabberId, text="")
+      method = "POST"
+      call = "/vmail/sendToFriends"
+      params = { :vmail_id => vmail_id, :senderJabberId => senderJabberId, :text => text }
+      result = request(method, call, params)
+    end
+
+    private # ==========================================================================================
+
+    def initialize(api_key, api_secret, api_server_url = 'http://sandbox.tokbox.com/')
+        @api_key = api_key
+        @api_secret = api_secret
+        @api_server_url = api_server_url
+    end
+
+    def generate_nonce
+      (0...16).map { "0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ"[rand(62)] }.join
+    end
+
+    def generate_request_string(hash)
+      hash.reject{ |k,v| k=~/^_/ or v.nil? or v.to_s == "" }.
+               map{|k,v| "#{CGI.escape(k.to_s)}=#{CGI.escape(v.to_s)}".gsub("+","%20")}.sort.join("&")
+    end
+
+    def build_signed_request(method, uri, nonce, timestamp, paramList, secret)
+      signed_auth_fields = { 'oauth_partner_key'      => @api_key,
+                             'oauth_signature_method' => API_SIGNATURE_METHOD,
+                             'oauth_timestamp'        => timestamp,
+                             'oauth_version'          => API_VERSION,
+                             'oauth_nonce'            => nonce,
+                             'tokbox_jabberid'        => @jabberId }.merge(paramList)
+      request_string = method + "&" + uri + "&" + generate_request_string(signed_auth_fields)
+      Digest::MD5.hexdigest(request_string + secret)
+    end
+
+    def request(method, apiURL, paramList, secret = nil)
+      nonce = generate_nonce
+      timestamp = Time.now.to_i
+      request_url = @api_server_url + API_SERVER_METHODS_URL + apiURL
+      authfields = { 'oauth_partner_key'      => @api_key,
+                     'oauth_signature_method' => API_SIGNATURE_METHOD,
+                     'oauth_timestamp'        => timestamp,
+                     'oauth_version'          => API_VERSION,
+                     'oauth_nonce'            => nonce,
+                     'oauth_signature'        => build_signed_request(method,request_url,nonce,timestamp,paramList, secret || @secret),
+                     'tokbox_jabberid'        => @jabberId }
+      datastring = generate_request_string(paramList)+"&"+generate_request_string(authfields)
+      datastring += '&_AUTHORIZATION='
+      datastring += authfields.map{|k,v|"#{CGI.escape(k.to_s)}=\"#{CGI.escape(v.to_s)}\""}.join(",").gsub("+","%20")
+      if @debug
+        puts "=========================v"
+        puts "Call   : #{method} #{request_url}"
+        puts "Params : #{paramList.inspect}"
+        puts "-------------------------"
+      end
+      url        = URI.parse(request_url)
+      request    = Net::HTTP.new(url.host,url.port)
+      response   = request.post(url.path,datastring)
+      result     = response.body
+      xml_result = XmlSimple.xml_in(result)
+      if @debug
+        pp xml_result
+        puts "=========================^"  
+      end
+      xml_result
+    end
+
+  end
+
+end