vimeo 1.0.0 → 1.1.0

data/.gitignore

@@ -1,3 +1,4 @@
 *.sw?
 .DS_Store
-coverage
+coverage
+pkg/

data/README.markdown

@@ -0,0 +1,312 @@
+# Vimeo API Gem
+
+This gem implements a full-featured Ruby interface for the Vimeo API v2.
+
+For a more in depth look at the API check out [Vimeo's Simple API Documentation](http://www.vimeo.com/api/docs/simple-api) or [Vimeo's Advanced API Documentation](http://www.vimeo.com/api/docs/advanced-api). I would also recommend checking out the [API Forums](http://www.vimeo.com/forum:api) if
+things aren't working as they should.
+
+__I have been experiencing trouble with intermittent 303 errors (Invalid Signature). As far as I can tell, this is a server-side issue.__
+
+## Install
+
+First, install [Gemcutter](http://gemcutter.org), then:
+
+    sudo gem install vimeo
+
+If you're using Rails, add the following to your environment.rb file:
+
+    config.gem "vimeo"
+
+## How to Use
+
+There are two modules:
+
+    Vimeo::Simple
+    Vimeo::Advanced
+
+## Simple API
+
+Let's look at the [Simple API](http://www.vimeo.com/api/docs/simple-api) first.
+
+The wrapper for the Simple API consists of several classes. To use the Simple API, just call one of the class methods. For example:
+
+    user_info = Vimeo::Simple::User.info("matthooks")
+    # =>
+    # {
+    #   "id":"888046",
+    #   "display_name":"Matt Hooks",
+    #   "created_on":"2008-10-30 14:17:32",
+    #   "is_staff":"0",
+    #   "is_plus":"0",
+    #   "location":"Chicago, IL",
+    #   "url":"http:\/\/blackholeinthemidwest.com\/",
+    #   "bio":"",
+    #   "profile_url":"http:\/\/vimeo.com\/matthooks",
+    #   "videos_url":"http:\/\/vimeo.com\/matthooks\/videos",
+    #   "total_videos_uploaded":2,
+    #   "total_videos_appears_in":0,
+    #   "total_videos_liked":2,
+    #   "total_contacts":3,
+    #   "total_albums":0,
+    #   "total_channels":1,
+    #   "portrait_small":"http:\/\/images.vimeo.com\/11\/42\/16\/114216178\/114216178_30.jpg",
+    #   "portrait_medium":"http:\/\/images.vimeo.com\/11\/42\/16\/114216178\/114216178_75.jpg",
+    #   "portrait_large":"http:\/\/images.vimeo.com\/11\/42\/16\/114216178\/114216178_100.jpg",
+    #   "portrait_huge":"http:\/\/images.vimeo.com\/11\/42\/16\/114216178\/114216178_300.jpg"
+    # }
+
+Thanks to HTTParty, the data is parsed and ready to use.
+
+    user_info["location"]
+    # => "Chicago, IL"
+
+## Overview of the Simple API
+
+### Vimeo::Simple::Activity
+
+    Vimeo::Simple::Activity.user_did("username")
+    Vimeo::Simple::Activity.happened_to_user("username")
+    Vimeo::Simple::Activity.contacts_did("username")
+    Vimeo::Simple::Activity.happened_to_contacts("username")
+    Vimeo::Simple::Activity.everyone_did("username")
+
+### Vimeo::Simple::Album
+
+    Vimeo::Simple::Album.videos("album_id")
+    Vimeo::Simple::Album.info("album_id")
+  
+### Vimeo::Simple::Channel
+
+    Vimeo::Simple::Channel.videos("channelname")
+    Vimeo::Simple::Channel.info("channelname")
+
+### Vimeo::Simple::Group
+
+    Vimeo::Simple::Group.videos("groupname")
+    Vimeo::Simple::Group.users("groupname")
+    Vimeo::Simple::Group.info("groupname")
+
+### Vimeo::Simple::User
+
+    Vimeo::Simple::User.info("username")
+    Vimeo::Simple::User.videos("username")
+    Vimeo::Simple::User.likes("username")
+    Vimeo::Simple::User.appears_in("username")
+    Vimeo::Simple::User.all_videos("username")
+    Vimeo::Simple::User.subscriptions("username")
+    Vimeo::Simple::User.albums("username")
+    Vimeo::Simple::User.channels("username")
+    Vimeo::Simple::User.groups("username")
+    Vimeo::Simple::User.contacts_videos("username")
+    Vimeo::Simple::User.contacts_like("username")
+
+### Vimeo::Simple::Video
+
+    Vimeo::Simple::Video.info("video_id")
+
+## Advanced API
+
+To use the [Advanced API](http://www.vimeo.com/api/docs/advanced-api), first you must authenticate your user using OAuth.
+
+### Authentication Example using Rails
+
+First, instantiate the Base class:
+
+    base = Vimeo::Advanced::Base.new("consumer_key", "consumer_secret")
+
+Then, send your user to the authorization URL:
+
+    redirect_to base.authorize_url
+
+Once the user has allowed your application to access their account, they will be redirected to the callback URL you set up for your application. You will be given two parameters `oauth_token` and `oauth_verifier`. Re-instantiate your Base class, then get an access token:
+
+    base = Vimeo::Advanced::Base.new("consumer_key", "consumer_secret")
+    access_token = base.get_access_token(params[:oauth_token], params[:oauth_verifier])
+    # You'll want to hold on to the user's token and secret. I'll save it to the database.
+    user.token = access_token.token
+    user.secret = access_token.secret
+    user.save
+  
+Now you've got everything you need to use the Advanced API. Let's get a user's videos:
+
+    video = Vimeo::Advanced::Video.new("consumer_key", "consumer_secret", :token => user.token, :secret => user.secret)
+    video.get_videos("matthooks")
+
+    # => {"videos"=> { ... }, "stat"=>"ok", "generated_in"=>"0.5753"}
+
+Piece of cake.
+
+Some methods have optional variables. Pass these as a hash at the end of a call.
+
+    video.get_all("matthooks", :page => "2", :per_page => "50")
+
+## Overview of the Advanced API
+
+### Vimeo::Advanced::Album
+
+    album = Vimeo::Advanced::Album.new("consumer_key", "consumer_secret", :token => user.token, :secret => user.secret)
+
+    album.add_video("album_id", "video_id")
+    album.create("title", "video_id", { :description => "description", "videos" => "123,124,125" })
+    album.delete("album_id")
+    album.get_all("user_id", { :page => "1", :per_page => "25", :sort => "newest" })
+    album.get_videos("album_id", { :page => "1", :per_page => "25", :full_response => "0", :password => nil })
+    album.remove_video("album_id", "video_id")
+    album.set_description("album_id", "description")
+    album.get_password("album_id", "password")
+    album.get_title("album_id", "title")
+  
+### Vimeo::Advanced::Base
+
+    base = Vimeo::Advanced::Base.new("consumer_key", "consumer_secret", :token => user.token, :secret => user.secret)
+
+    base.check_access_token
+  
+### Vimeo::Advanced::Channel
+
+    channel = Vimeo::Advanced::Channel.new("consumer_key", "consumer_secret", :token => user.token, :secret => user.secret)
+
+    channel.add_video("channel_id", "video_id")
+    channel.get_all({ :page => "1", :per_page => "25", :sort => "newest", :user_id => "user_id" })
+    channel.get_info(channel_id)
+    channel.get_moderators(channel_id, { :page => "1", :per_page => "25" })
+    channel.get_subscribers(channel_id, { :page => "1", :per_page => "25" })
+    channel.get_videos(channel_id, { :page => "1", :per_page => "25", :full_response => "0" })
+    channel.remove_video("channel_id", "video_id")
+    channel.subscribe("channel_id")
+    channel.unsubscribe("channel_id")
+
+### Vimeo::Advanced::Contact
+
+    contact = Vimeo::Advanced::Contact.new("consumer_key", "consumer_secret", :token => user.token, :secret => user.secret)
+
+    contact.get_all(user_id, { :page => "1", :per_page => "25", :sort => "newest" })
+    contact.get_mutual(user_id, { :page => "1", :per_page => "25" })
+    contact.get_online({ :page => "1", :per_page => "25" })
+    contact.get_who_added(user_id, { :page => "1", :per_page => "25", :sort => "newest" })
+
+### Vimeo::Advanced::Group
+
+    group = Vimeo::Advanced::Group.new("consumer_key", "consumer_secret", :token => user.token, :secret => user.secret)
+
+    group.add_video("group_id", "video_id")
+    group.get_all({ :page => "1", :per_page => "25", :sort => "newest", :user_id => "user_id" })
+    group.get_files("group_id", { :page => "1", :per_page => "25" })
+    group.get_info("group_id")
+    group.get_members("group_id", { :page => "1", :per_page => "25", :sort => "newest" })
+    group.get_moderators("group_id", { :page => "1", :per_page => "25" })
+    group.get_video_comments("group_id", "video_id", { :page => "1", :per_page => "25" })
+    group.get_videos("group_id", { :page => "1", :per_page => "25", :full_response => "0", :sort => "newest" })
+    group.join("group_id")
+    group.leave("group_id")
+
+### Vimeo::Advanced::GroupEvents
+
+    group_events = Vimeo::Advanced::GroupEvents.new("consumer_key", "consumer_secret", :token => user.token, :secret => user.secret)
+
+    group_events.get_month("group_id", { :page => "1", :per_page => "25", :month => nil, :year => nil })
+    group_events.get_past("group_id", { :page => "1", :per_page => "25" })
+    group_events.get_year("group_id", { :page => "1", :per_page => "25" })
+
+### Vimeo::Advanced::GroupForums
+
+    group_forums = Vimeo::Advanced::GroupForums.new("consumer_key", "consumer_secret", :token => user.token, :secret => user.secret)
+
+    group_forums.get_topic_comments("group_id", "topic_id", { :page => "1", :per_page => "25" })
+    group_forums.get_topics("group_id", { :page => "1", :per_page => "25" })
+
+### Vimeo::Advanced::Person
+
+    person = Vimeo::Advanced::Person.new("consumer_key", "consumer_secret", :token => user.token, :secret => user.secret)
+
+    person.add_contact("user_id")
+    person.add_subscription("user_id", "types") # Types is a comma-delimited string. Valid: "likes", "appears", "uploads"
+    person.find_by_email("user_id")
+    person.get_hd_embeds
+    person.get_info("user_id")
+    person.get_portrait_urls("user_id")
+    person.remove_contact("user_id")
+    person.remove_subscription("user_id", "types") # Types is a comma-delimited string. Valid: "likes", "appears", "uploads"
+
+### Vimeo::Advanced::Test
+
+    test = Vimeo::Advanced::Test.new("consumer_key", "consumer_secret", :token => user.token, :secret => user.secret)
+
+    test.echo
+    test.null
+    test.login
+
+### Vimeo::Advanced::Upload
+
+    upload = Vimeo::Advanced::Upload.new("consumer_key", "consumer_secret", :token => user.token, :secret => user.secret)
+
+    upload.confirm("ticket_id", "json_manifest")
+    upload.get_quota
+    upload.get_ticket
+    upload.upload("path_to_file", "ticket_id", "end_point")
+    upload.verify_manifest("ticket_id", "json_manifest")
+
+### Vimeo::Advanced::Video
+
+    video = Vimeo::Advanced::Video.new("consumer_key", "consumer_secret", :token => user.token, :secret => user.secret)
+
+    video.add_cast("video_id", "user_id", { :role => nil })
+    video.add_photos("video_id", "photo_urls")
+    video.add_tags("video_id", "tags")
+    video.clear_tags("video_id")
+    video.delete("video_id")
+    video.get_all("user_id", { :page => "1", :per_page => "25", :full_response => "0", :sort => "newest" })
+    video.get_appears_in("user_id", { :page => "1", :per_page => "25", :full_response => "0", :sort => "newest" })
+    video.get_by_tag("tag", { :page => "1", :per_page => "25", :full_response => "0", :sort => "newest" })
+    video.get_cast("video_id", { :page => "1", :per_page => "25" })
+    video.get_contacts_liked("user_id", { :page => "1", :per_page => "25", :full_response => "0", :sort => "newest" })
+    video.get_contacts_uploaded("user_id", { :page => "1", :per_page => "25", :full_response => "0", :sort => "newest" })
+    video.get_info("video_id")
+    video.get_likes("user_id", { :page => "1", :per_page => "25", :full_response => "0", :sort => "newest" })
+    video.get_subscriptions("user_id", { :page => "1", :per_page => "25", :full_response => "0", :sort => "newest" })
+    video.get_thumbnail_urls("video_id")
+    video.get_uploaded("user_id", { :page => "1", :per_page => "25", :full_response => "0", :sort => "newest" })
+    video.remove_cast("video_id", "user_id")
+    video.remove_tag("video_id", "tag_id")
+    video.search("query", { :page => "1", :per_page => "25", :full_response => "0", :sort => "newest", :user_id => nil })
+    video.set_description("video_id", "description")
+    video.set_like("video_id", "like")
+    video.set_privacy("video_id", "privacy", { :users => nil, :password => nil })
+    video.set_title("video_id", "title")
+
+    # comments
+    video.add_comment("video_id", "comment_text", { :reply_to_comment_id => nil })
+    video.delete_comment("video_id", "comment_id")
+    video.edit_comment("video_id", "comment_id", "comment_text")
+    video.get_comments_list("video_id", { :page => "1", :per_page => "25" })
+
+### Vimeo::Advanced::VideoEmbed
+
+    video_embed = Vimeo::Advanced::VideoEmbed.new("consumer_key", "consumer_secret", :token => user.token, :secret => user.secret)
+
+    video_embed.get_presets({ :page => "1", :per_page => "25" })
+    video_embed.set_preset("video_id", "preset_id")
+
+## Uploads
+
+__Uploads are not working since the move to OAuth. They will be fixed shortly.__
+
+## Todo
+
+* Fix tests that cannot be stubbed because of OAuth nonce.
+* Better structure. There's too many classes. Is there a way to simplify the Advanced API?
+* Better error handling.
+* More re-factoring.
+* Make tests more robust and faster. If anyone has any ideas let me know.
+
+## Contributors
+
+* {matthooks}[http://github.com/matthooks]
+* {sirlantis}[http://github.com/sirlantis]
+
+## Thanks to
+
+* {HTTParty}[http://github.com/jnunemaker/httparty/tree/master]: Easily one of the best tools I have used since I started using Ruby.
+* {Jeweler}[http://github.com/technicalpickles/jeweler/tree/master]: Great tool for creating gems for Github.
+
+### Copyright (c) 2009 Matt Hooks. See LICENSE for details.

data/Rakefile

@@ -21,8 +21,8 @@ begin
     gem.extra_rdoc_files = ['README.rdoc', 'LICENSE', 'CHANGELOG.rdoc']
     
     gem.add_dependency "httparty", ">= 0.4.5"
-    gem.add_dependency "curb", ">= 0.5.4.0"
     gem.add_dependency "json", ">= 1.1.9"
+    gem.add_dependency "oauth", ">= 0.3.6"
   end
   Jeweler::GemcutterTasks.new
 rescue LoadError

data/VERSION.yml

@@ -1,4 +1,5 @@
 --- 
-:minor: 0
+:build: 
 :patch: 0
 :major: 1
+:minor: 1

data/init.rb

@@ -0,0 +1,2 @@
+$:.unshift(File.dirname(__FILE__))
+require 'lib/vimeo'

data/lib/vimeo.rb

@@ -3,6 +3,7 @@ require 'httparty'
 require 'digest/md5'
 
 $:.unshift(File.dirname(__FILE__))
+require 'oauth_client'
 require 'vimeo/simple'
 require 'vimeo/advanced'
 

data/lib/vimeo/advanced.rb

@@ -1,7 +1,6 @@
 $:.unshift(File.dirname(__FILE__))
 require 'advanced/base'
 require 'advanced/album'
-require 'advanced/auth'
 require 'advanced/channel'
 require 'advanced/contact'
 require 'advanced/group'

data/lib/vimeo/advanced/album.rb

@@ -5,20 +5,18 @@ module Vimeo
       # Adds a video to an album.
       create_api_method :add_video,
                         "vimeo.albums.addVideo",
-                        :required => [:auth_token, :album_id, :video_id]
+                        :required => [:album_id, :video_id]
 
       # Creates an album.
-      # FIXME: Nothing is returned if you add multiple videos to an album.
-      # The optional parameter videos is a comma-separated list of video ids.
       create_api_method :create,
                         "vimeo.albums.create",
-                        :required => [:auth_token, :title, :video_id],
+                        :required => [:title, :video_id],
                         :optional => [:description, :videos]
       
       # Deletes an album.
       create_api_method :delete,
                         "vimeo.albums.delete",
-                        :required => [:auth_token, :album_id]
+                        :required => [:album_id]
       
       # Returns a list of a user's albums.
       create_api_method :get_all,
@@ -29,28 +27,28 @@ module Vimeo
       # Returns a list of the videos in an album.
       create_api_method :get_videos,
                         "vimeo.albums.getVideos",
-                        :required => [:auth_token, :album_id],
+                        :required => [:album_id],
                         :optional => [:page, :per_page, :full_response, :password]
       
       # Removes a video from an album.
       create_api_method :remove_video,
                         "vimeo.albums.removeVideo",
-                        :required => [:auth_token, :album_id, :video_id]
+                        :required => [:album_id, :video_id]
 
       # Sets the description of an album.
       create_api_method :set_description,
                         "vimeo.albums.setDescription",
-                        :required => [:auth_token, :album_id, :description]
+                        :required => [:album_id, :description]
                         
       # Sets the password of an album.
       create_api_method :set_password,
                         "vimeo.albums.setPassword",
-                        :required => [:auth_token, :album_id, :password]
+                        :required => [:album_id, :password]
       
       # Sets the title of an album.
       create_api_method :set_title,
                         "vimeo.albums.setTitle",
-                        :required => [:auth_token, :album_id, :title]
+                        :required => [:album_id, :title]
 
     end # Album
   end # Advanced

data/lib/vimeo/advanced/base.rb

@@ -1,26 +1,25 @@
 module CreateApiMethod
   
-  # Small DSL that creates a method that calls a Vimeo method through the advanced API.
+  # Creates a method that calls a Vimeo Method through the Advanced API.
   #
   # @param [String] method The name of the method being created.
   # @param [String] vimeo_method The name of the advanced API Method the function should call.
   # @param [Hash] options Some optional parameters.
   # @option options [Array] :required An array of required parameters.
   # @option options [Array] :optional An array of optional parameters.
-  # @option options [Array] :unsigned An array of required parameters that should not be included in the api_sig.
   def create_api_method(method, vimeo_method, options={})
-    options = { :required => [], :optional => [], :unsigned => [] }.merge(options)
+    options = { :required => [], :optional => [] }.merge(options)
+    
+    method = method.to_s
+    camelized_method = camelize(method, false)
     
     raise ArgumentError, 'Required parameters must be an array.' unless options[:required].is_a? Array
     raise ArgumentError, 'Optional parameters must be an array.' unless options[:optional].is_a? Array
-    raise ArgumentError, 'Unsigned parameters must be an array.' unless options[:optional].is_a? Array
     
-    required = (options[:required] + options[:unsigned]).map { |r| r.to_s }.join(",")
-    required_hash = options[:required].map { |r| ":#{r} => #{r}" }.join(",")
-    optional_hash = options[:optional].map { |o| ":#{o} => nil" }.join(",")
-    unsigned_hash = options[:unsigned].map { |u| ":#{u} => #{u}" }.join(",")
+    required = options[:required].map { |r| r.to_s }.join(",")
+    optional = options[:optional].map { |o| ":#{o} => nil" }.join(",")
     
-    parameters = "(#{required unless required.blank?}#{',' unless required.blank?}options={#{optional_hash}})"
+    parameters = "(#{required unless required.blank?}#{',' unless required.blank?}options={#{optional}})"
     
     method_string = <<-method
 
@@ -35,71 +34,82 @@ module CreateApiMethod
         #{ options[:required].map { |r| "sig_options.merge! :#{r} => #{r}"}.join("\n") }
         #{ options[:optional].map { |o| "sig_options.merge! :#{o} => options[:#{o}] unless options[:#{o}].nil?" }.join("\n") }
         
-        make_request sig_options#{ ", :unsigned => {" + unsigned_hash + "}" unless options[:unsigned].empty? }
+        make_request sig_options
       end
       
+      alias #{camelized_method} #{method}
+      
     method
     
     class_eval method_string
   end
-
+  
+  protected
+  
+  # taken from ActiveSupport-2.3.4, activesupport/lib/active_support/inflector.rb, line 178
+  def camelize(lower_case_and_underscored_word, first_letter_in_uppercase = true)
+    if first_letter_in_uppercase
+      lower_case_and_underscored_word.to_s.gsub(/\/(.?)/) { "::#{$1.upcase}" }.gsub(/(?:^|_)(.)/) { $1.upcase }
+    else
+      lower_case_and_underscored_word[0..0].downcase + camelize(lower_case_and_underscored_word)[1..-1]
+    end
+  end
 end
 
 module Vimeo
   module Advanced
 
+    class RequestFailed < StandardError; end
+
     class Base
-      include HTTParty
-      base_uri 'vimeo.com'
       extend CreateApiMethod
 
-      # TODO: Pass an auth token, if you've already got one
-      # TODO: implement format_options
-      # Requires your API key and secret phrase.
-      # The API key and secret are prepended to every request.
-      def initialize(api_key, secret, format_options={})
-        @auth = { :api_key => api_key }
-        @secret = secret
+      def initialize(consumer_key, consumer_secret, options = {})
+        @oauth_consumer = OAuth::Consumer.new(consumer_key, consumer_secret, :site => 'http://vimeo.com', :http_method => :get, :scheme => :query_string)
+        unless options[:token].nil? && options[:secret].nil?
+          @access_token = OAuth::AccessToken.new(@oauth_consumer, options[:token], options[:secret])
+        end
       end
       
-      # Generates a link that allows a user to authorize
-      # your web application to use the advanced API
-      def web_login_link(perms)
-        api_sig = generate_api_sig :perms => perms
-        "http://vimeo.com/services/auth/?api_key=#{@auth[:api_key]}&perms=#{perms}&api_sig=#{api_sig}"
+      def authorize_url(permission = "delete")
+        get_request_token.authorize_url :permission => permission
       end
       
-      # Generates a link that allows a user to authorize
-      # your desktop application to use the advanced API
-      def desktop_login_link(perms, frob)
-        api_sig = generate_api_sig :frob => frob, :perms => perms
-        "http://vimeo.com/services/auth/?api_key=#{@auth[:api_key]}&perms=#{perms}&frob=#{frob}&api_sig=#{api_sig}"
+      def get_access_token(oauth_token=nil, oauth_verifier=nil)
+        @access_token ||= get_request_token.get_access_token :oauth_token => oauth_token, :oauth_verifier => oauth_verifier
       end
       
+      # TODO: Move this to OAuth
+      create_api_method :check_access_token,
+                        "vimeo.oauth.checkAccessToken"
+      
       private
 
-      def make_request(sig_options, options={})
-        options = { :unsigned => [] }.merge(options)
-        unsigned = options[:unsigned]
-
-        api_sig = generate_api_sig sig_options
-        self.class.post "/api/rest/v2", :query => query(sig_options, api_sig), :body => unsigned
+      def get_request_token
+        @request_token ||= @oauth_consumer.get_request_token :scheme => :query_string
       end
 
-      # Generates a MD5 hashed API signature for Advanced API requests
-      def generate_api_sig(options={})
-        # Every request requires the api_key parameter
-        options.merge! @auth
-        # Keys must be sorted alphabetically
-        api_sig = options.sort { |a, b| a.to_s <=> b.to_s }.join
-        Digest::MD5.hexdigest("#{@secret}#{api_sig}")
+      def make_request(options)
+        response = Crack::JSON.parse @oauth_consumer.request(:post, "http://vimeo.com/api/rest/v2", get_access_token, {}, options).body
+        validate_response! response
+        response
       end
       
-      def query(sig_options, api_sig)
-        sig_options.merge :api_key => @auth[:api_key], :api_sig => api_sig
+      # Raises an exception if the response does contain a +stat+ different from "ok"
+      def validate_response!(response)
+        raise "empty response" unless response
+        
+        status = response["stat"]
+        if status and status != "ok"
+          error = response["err"]
+          if error
+            raise RequestFailed, "#{error["code"]}: #{error["msg"]}, explanation: #{error["expl"]}"
+          else
+            raise RequestFailed, "Error: #{status}, no error message"
+          end
+        end
       end
 
     end # Base
-
   end # Advanced
 end # Vimeo