ikbis 0.2.0

data/.gitignore

@@ -0,0 +1,3 @@
+*.sw?
+.DS_Store
+coverage

data/LICENSE

@@ -0,0 +1,20 @@
+ZZCopyright (c) 2008 Moski Doski
+
+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

@@ -0,0 +1,9 @@
+ikbis
+=====
+
+Description goes here.
+
+COPYRIGHT
+=========
+
+Copyright (c) 2008 Moski Doski. See LICENSE for details.

data/README.markdown

@@ -0,0 +1,97 @@
+# Ikbis API GEM
+	This gem implements a full-featured ruby interface for the Ikbis API.
+
+
+## Installation
+If you haven't already, add github's gem server to your sources:
+
+  	gem sources -a http://gems.github.com
+
+Then, it's as easy as:
+
+    sudo gem install ikbis
+
+Add the gem plugin to your Rails project by adding the following to your @environment.rb@ file:
+	
+	config.gem "ikbis", :lib => "ikbis"
+	
+
+## Use
+There are two modules:
+
+  	Ikbis::Simple
+  	Ikbis::Advanced
+
+## Simple API
+
+The wrapper for the Simple API consists of the following classes and methods:
+
+### Ikbis::Simple::User
+	
+	Ikbis::Simple::User.info(username, response='xml')
+
+
+# Advance API 
+The classes in Ikbis::Advanced must be instantiated. For example,
+
+	  ikbis_video = Ikbis::Advanced::Video.new
+	  ikbis_video.getInfo('moski_doski' , {:how => 'json'}) 
+
+### Authentication
+There are two steps you'll need to do to authenticate your application to Ikbis. First, you'll need to register your application with Ikbis. Log in to Ikbis as the user under whose account the messages should appear. Then go to http://ikbis.com/api/manage_keys. You will be asked to describe your application. Fill out the form and submit it. This will provide you with a client key and secret. Make note of them as you will need them for the next step.
+
+Then, you'll need to do the OAuth exchange, which will give you an access token and secret. Open up a terminal and run:
+
+    ikbis-auth
+
+This will prompt you for the client key and secret you just obtained. It will then echo a URL which you will need to visit while still logged in to Ikbis as the user from the previous step. You'll be asked to authorize your application. Click the Authorize button, then go back to your terminal and hit Return. The script will then get the access token and secret from Ikbis, and store all four pieces of information in a file called ikbis.yml. **Don't lose this file!** It constitutes the credentials that you will need to do anything useful with Ikbis. It is not encrypted, so keep it secure. Once you have the ikbis.yml file, you will not need to do these steps again unless you de-authorize the application.	
+	  	
+
+Now to authenticate any call, you can do the following:
+
+	ikbis_video.oauth_authentication('path_to_ikbis.yml_file')
+
+Any call you do with this object will use the your credentials when talking to ikbis.com	
+	
+	
+The wrapper for the Advanced API consists of the following classes and methods:
+
+### Ikbis::Advanced::Test
+
+	echo(options={})
+  	ping(options={})
+  	login(options={})
+
+### Ikbis::Advanced::Video
+	
+	getUploadedList(username  , {:how => 'json'})		
+	getInfo(video_id  , {:how => 'ruby'})
+	getThumbnailUrl(video_id  , {:how => 'xml'})
+	setTitle(video_id  , title , {:how => 'php'})           	## Must call oauth_authentication before use
+	setCaption(video_id  , caption , {})                        ## Must call oauth_authentication before use
+
+
+### Ikbis::Advanced::Photo
+
+	getUploadedList(username  , {:how => 'json'})		
+	getInfo(video_id  , {:how => 'ruby'})
+	getThumbnailUrl(video_id  , {:how => 'xml'})
+	setTitle(video_id  , title , {:how => 'php'})           	## Must call oauth_authentication before use
+	setCaption(video_id  , caption , {})                        ## Must call oauth_authentication before use
+	
+
+## Thanks to
+
+* {Jeweler}[http://github.com/technicalpickles/jeweler/tree/master]: The best for gems.
+* {HTTParty}[http://github.com/jnunemaker/httparty/tree/master].
+
+
+## License
+
+Copyright (C) 2008 Ikbis (http://www.ikbis.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,43 @@
+require 'rake'
+require 'rake/testtask'
+require 'rake/rdoctask'
+require 'rcov/rcovtask'
+
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |s|
+    s.name = "ikbis"
+    s.summary = "This gem implements a full-featured ruby interface for the Ikbis API."
+    s.email = "abushaikh@gmail.com"
+    s.homepage = "http://github.com/moski/ikbis"
+    s.description = "This gem implements a full-featured ruby interface for the Ikbis API."
+    s.authors = ["Moski Doski"]
+    s.add_dependency('multipart-post', '>= 1.0')
+    s.add_dependency('httparty', '>= 0.5.0')
+    s.add_dependency('oauth', '>= 0.3.6')
+  end
+rescue LoadError
+  puts "Jeweler not available. Install it with: sudo gem install technicalpickles-jeweler -s http://gems.github.com"
+end
+
+Rake::TestTask.new do |t|
+  t.libs << 'lib'
+  t.pattern = 'test/**/*_test.rb'
+  t.verbose = false
+end
+
+Rake::RDocTask.new do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title    = 'ikbis'
+  rdoc.options << '--line-numbers' << '--inline-source'
+  rdoc.rdoc_files.include('README*')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end
+
+Rcov::RcovTask.new do |t|
+  t.libs << 'test'
+  t.test_files = FileList['test/**/*_test.rb']
+  t.verbose = true
+end
+
+task :default => :rcov

data/VERSION.yml

@@ -0,0 +1,4 @@
+--- 
+:patch: 0
+:major: 0
+:minor: 2

data/bin/ikbis-auth

@@ -0,0 +1,33 @@
+#!/usr/bin/env ruby
+ 
+require 'rubygems'
+require 'oauth/consumer'
+require 'yaml'
+ 
+puts "Please enter your client key, then hit Return."
+consumer_key = gets.chomp
+puts "Please enter your client secret, then hit Return."
+consumer_secret = gets.chomp
+ 
+begin
+  consumer = OAuth::Consumer.new consumer_key, consumer_secret, { :site => "http://ikbis.com" }
+  request_token = consumer.get_request_token
+  puts "Please go to:\n#{request_token.authorize_url}\nin your browser. Click Authorize on that page.\nHit Return here when you are done."
+  gets
+  access_token = request_token.get_access_token
+  credentials = {
+    :consumer_key => consumer.key,
+    :consumer_secret => consumer.secret,
+    :access_token => access_token.token,
+    :access_token_secret => access_token.secret
+  }
+  begin
+    File.open('ikbis.yml', 'w') { |file| YAML.dump(credentials, file) }
+    File.chmod(0600, 'ikbis.yml')
+    puts "Your credentials have been saved."
+  rescue
+    puts "Couldn't save your credentials."
+  end
+rescue
+  puts "Couldn't authorize with Ikbis. Did you enter your client credentials correctly?"
+end

data/lib/ikbis.rb

@@ -0,0 +1,14 @@
+require 'rubygems'
+require 'httparty'
+require 'cgi'
+require 'net/http'
+require 'net/http/post/multipart'
+require 'oauth/consumer'
+require 'yaml'
+
+$:.unshift(File.dirname(__FILE__))
+require 'ikbis/simple'
+require 'ikbis/advanced'
+
+module Ikbis
+end

data/lib/ikbis/advanced.rb

@@ -0,0 +1,12 @@
+$:.unshift(File.dirname(__FILE__))
+require 'advanced/base'
+require 'advanced/test'
+require 'advanced/media'
+require 'advanced/video'
+require 'advanced/photo'
+require 'advanced/upload'
+module Ikbis
+  module Advanced
+    
+  end
+end

data/lib/ikbis/advanced/base.rb

@@ -0,0 +1,89 @@
+module Ikbis
+  module Advanced
+    class Base
+      include HTTParty
+      base_uri 'ikbis.com'
+      #base_uri  'localhost:3000'
+      
+      class CouldNotLoadCredentials < Exception; end
+      class CouldNotPost < Exception; end
+      
+      attr_reader :access_token
+      
+      #######################################################
+      # Authenticate using OAuth::Consumer.
+      # After calling this method, the user will be logged in
+      # in to ikbis and can use all the private methods.
+      # 
+      # Prerequisites:
+      #   Must call ikbis-auth to generate the credentials yaml file.
+      # 
+      ######################
+      # @Created : DEC/31/2007
+      # @LastRefactor : DEC/31/2007
+      # @Author  : Monther Abushaikh <abushaikh@gmail.com>
+      #######################################################
+      def oauth_authentication(credential_file='credentials.yml')
+        begin
+          @credentials = YAML.load_file(credential_file)
+        rescue
+          raise CouldNotLoadCredentials, "Couldn't load your ikbis credentials. You may need to run ikbis-auth."
+        end
+        @consumer = OAuth::Consumer.new(@credentials[:consumer_key], @credentials[:consumer_secret], {:site => "http://localhost:3000"})
+        @access_token = OAuth::AccessToken.new(@consumer, @credentials[:access_token], @credentials[:access_token_secret])
+      end
+      
+      protected
+      
+      #######################################################
+      # Send the request to ikbis and return the results.
+      # If @access_token is defined use OAuth::Consumer else use
+      # HTTParty to send request.
+      # 
+      # Params:
+      #   :method => 
+      #     enum(get | post | put | delete)
+      #   :id => 
+      #     id of the resource we're manipulating
+      #   :what =>
+      #     method to perform, if empty, action taken will be controlled by the provided method, 
+      #     ie :method => get and :what => "" will retrieve the resource's info
+      #        :method => post and :what => "" will create a resource
+      #        :method => put and :what => "add_tag" will add a tag to resource with :id
+      #   :how => 
+      #     defines type of response; enum(xml | json | rb | php)
+      #
+      # Return:
+      #   See :how in Params.
+      ######################
+      # @Created : DEC/31/2007
+      # @LastRefactor : Jan/13/2010
+      #   by: ahmad@ikbis
+      # @Author  : Monther Abushaikh <abushaikh@gmail.com>
+      #######################################################
+      def send_request(options)
+
+        # construct our RESTful request URI
+        uri = "#{Base.base_uri}/api/#{options[:target]}"
+        uri += "/#{options[:id]}" if options.has_key?(:id)
+        uri += "/#{options[:what]}" if options.has_key?(:what)
+        uri += ".#{options[:how]}" if options[:method] == "get"
+        puts "|---------------------  SEND_REQUEST  ---------------------|"
+        puts "| URI"
+        puts "|   #{uri}"
+        puts "| Params"
+        puts "|   id => #{options[:id]}"
+        puts "|   what => #{options[:what]}"
+        puts "|   how => #{options[:how]}"
+        puts "|--------------------- ------------ ---------------------|"
+        
+        if @access_token.nil? 
+          return self.class.send(options[:method] || "get", uri, options)
+        else
+          return @access_token.send(options[:method] || "get", uri, options).body
+        end
+        
+      end ## end send_request
+    end ## end Base
+  end ## end Advanced
+end ## end ikbis

data/lib/ikbis/advanced/media.rb

@@ -0,0 +1,264 @@
+module Ikbis
+  module Advanced
+    class Media < Ikbis::Advanced::Base
+      
+      #######################################################
+      # Class constants:
+      # I.  MEDIA_EXTENTION: used to override the methods names.
+      # II. RESERVER:        List of reserved methods we don't need to
+      #                      override.
+      #######################################################
+      MEDIA_EXTENTION = 'media_'
+      RESERVED = ['initialize' , 'method_missing' , 'method_added']
+      
+      #######################################################
+      # Try to generate the method name if its a valid method
+      # name and call the paret class.
+      ######################
+      # @Created : Jan/19/2009
+      # @LastRefactor : Jan/19/2009
+      # @Author  : Moski
+      #######################################################
+      def method_missing(key, *args, &block)
+        if @@valid_methods.include?(key.to_s)                    
+          (class << self; self; end).class_eval do
+            define_method(key) do |*args|
+               args.insert(0,"#{@class_extention}.#{key}")
+               send "#{MEDIA_EXTENTION}#{key}" , *args
+            end
+          end
+          send "#{key}" , *args
+        else
+          super
+        end
+      end ## end method_missing
+       
+      
+      #######################################################
+      # When a method is defined added to the valid_methods
+      # array.
+      # This is just overriding the ruby hook method(method_added)
+      ######################
+      # @Created : Jan/19/2009
+      # @LastRefactor : Jan/19/2009
+      # @Author  : Moski
+      ####################################################### 
+      def self.method_added(name)
+        @@valid_methods ||= []
+        @@valid_methods << name.to_s.gsub(MEDIA_EXTENTION , '')
+      end 
+       
+       
+      protected
+
+
+      #######################################################
+      # Returns a sheet of all videos uploaded by user.
+      # 
+      # NOTE:
+      #   Now requires user_id instead of username.
+      #######################################################
+      # @ LastRefactor: Jan/06/2010
+      # @ Devs:
+      #     Moski
+      #     Ahmad
+      #######################################################
+      def getUploadedList(action_name , user_id, options = {})
+        setup_what_how("videos" , options)
+
+        # does not deal with medias controller, but with users instead...        
+        options.merge!(:target => "users")
+        options.merge!(:id => user_id)
+        options.merge!(:method => "get")
+        
+        return send_request(options)
+      end ## end function.
+      
+      
+      #######################################################
+      # Returns sheet of media info in specified format.
+      #######################################################
+      # @ LastRefactor: Jan/06/2010
+      # @ Devs:
+      #     Moski
+      #     Ahmad
+      #######################################################      
+      def getInfo(action_name ,media_id  , options = {})
+        # debug
+        puts "------ getInfo routine ------"
+        puts "* action_name => #{action_name}"
+        puts "* options => #{options}"
+        puts "--------------------------------"
+        
+        # action name is empty here because info is the default
+        # GET response
+        setup_what_how("" , options)
+        options.merge!(:id => media_id)
+        options.merge!(:method => "get")
+        
+        return send_request(options)
+      end ## end function
+      
+
+
+      #######################################################
+      # Returns URL pointing to the thumbnail picture requested
+      # by size.
+      #
+      # params:
+      #   * int media_id
+      #   * string enum :size option
+      #     {
+      #      - medium_crop
+      #      - screen
+      #      - big_screen
+      #      - medium
+      #      - small
+      #      - large
+      #      - thumb
+      #     }
+      #
+      #   ex media.getThumbnailUrl("204732", :size => "large")
+      #######################################################
+      # @ LastRefactor: Jan/06/2010
+      # @ Devs:
+      #     Moski
+      #     Ahmad
+      #######################################################
+      def getThumbnailUrl(action_name , media_id  , options = {})
+
+        # get vid info where thumb URIs are contained
+        media = getInfo(media_id)
+        
+        # enforce a default value if none is provided
+        size = (options[:size].empty?) ? "thumb" : options[:size]
+        
+        type = (media.type == "Image") ? "photo" : "video"
+        
+        # since HTTParty parses the XML into a ruby hash,
+        # we only need to access the element and get our URI!
+        thumb_uri = media['ikbis'][type]['thumbnails'][size]
+
+        return thumb_uri
+      end ## end function
+      
+      
+      #######################################################
+      # Modifies title of specified media that belongs to the logged
+      # in user.
+      #######################################################
+      # @ LastRefactor: Jan/06/2010
+      # @ Devs:
+      #     Moski
+      #     Ahmad
+      #######################################################
+      def setTitle(action_name , media_id  , title ,options = {})
+        # using PUT method allows us to update without
+        # specifying an action name, since it's a RESTful route
+        setup_what_how("" , options)
+        options.merge!(:method => "put")
+        options.merge!(:id => media_id)
+        options.merge!(:title => CGI.escape(title))
+        
+        return send_request(options)
+      end
+
+      #######################################################
+      # Modifies caption of specified media that belongs to the 
+      # logged in user.
+      #######################################################
+      # @ LastRefactor: Jan/06/2010
+      # @ Devs:
+      #     Moski
+      #     Ahmad
+      #######################################################      
+      def setCaption(action_name,media_id  , caption ,options = {})
+        setup_what_how("", options)
+        options.merge!(:id => media_id)
+        options.merge!(:caption => CGI.escape(caption))
+        options.merge!(:method => "put")
+        
+        return send_request(options)
+      end
+      
+      # DEPRECATED
+      #def setFavorite(action_name, media_id  , favorite = 'yes' ,options = {})
+      #  setup_what_how(action_name , options)
+      #  options.merge!(:media_id => media_id)
+      #  options.merge!(:favorite => favorite)
+      #  return send_request(options)
+      #end
+      
+      #######################################################
+      # Adds 1 tag at a time to media.
+      # NOTE:
+      #   trying to add more than one tag using a ' ' space delimiter
+      #   will result in an escaped '+' character instead. 
+      #######################################################
+      # @ LastRefactor: Jan/06/2010
+      # @ Devs:
+      #     Moski
+      #     Ahmad
+      #######################################################
+      def addTag(action_name, media_id  , tags  ,options = {})
+        setup_what_how("add_tag", options)
+        options.merge!(:id => media_id)
+        options.merge!(:tag => CGI.escape(tags))
+        options.merge!(:method => "put")
+        
+        return send_request(options)
+      end
+      
+      #######################################################
+      # Removes all occurences of 'tag' in media's tags.
+      #######################################################
+      # @ LastRefactor: Jan/06/2010
+      # @ Devs:
+      #     Moski
+      #     Ahmad
+      #######################################################
+      def removeTag(action_name, media_id  , tag  ,options = {})
+        setup_what_how("remove_tag" , options)
+        options.merge!(:id => media_id)
+        options.merge!(:tag => CGI.escape(tag))
+        options.merge!(:method => "put")
+        
+        return send_request(options)
+      end
+      
+      
+      #######################################################
+      # Rename the Class methods by added the media extention to
+      # it and remove the old definition.
+      ######################
+      # @Created : Jan/19/2009
+      # @LastRefactor : Jan/19/2009
+      # @Author  : Moski
+      #######################################################
+      class_eval{instance_methods(false).each {|m| 
+        unless RESERVED.include?(m)
+          alias_method "#{MEDIA_EXTENTION}#{m}" , m ;undef_method m
+        end
+      }}
+      
+      
+      private
+      
+      #######################################################
+      # Just a common helper method to add the action_name and the
+      # return type.
+      ######################
+      # @Created : Jan/19/2009
+      # @LastRefactor : Jan/19/2009
+      # @Author  : Moski
+      #######################################################
+      def setup_what_how(action_name , options)
+        options.merge!(:target => "medias")
+        options.merge!(:what => action_name)
+        options.merge!(:how => 'xml') unless options.has_key?(:how)
+      end
+      
+      
+    end ## end class
+  end## end advanced
+end ## end ikbis