dropbox-api-petems 0.4.1

data/.gitignore

@@ -0,0 +1,7 @@
+*.gem
+.bundle
+Gemfile.lock
+pkg/*
+spec/connection.yml
+bin
+coverage

data/.rspec

@@ -0,0 +1 @@
+--color

data/.ruby-version

@@ -0,0 +1 @@
+1.9.3

data/Gemfile

@@ -0,0 +1,10 @@
+source "http://rubygems.org"
+
+# Specify your gem's dependencies in dropbox-api.gemspec
+gemspec
+
+gem "rspec"
+gem "rake"
+gem 'simplecov'
+gem "ruby-debug19"
+gem "yajl-ruby"

data/LICENSE

@@ -0,0 +1,22 @@
+Copyright (c) 2011 Marcin Bunsch, Future Simple Inc.
+
+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.markdown

@@ -0,0 +1,335 @@
+Dropbox::API - Dropbox Ruby API client (PeteMS fork...)
+=========
+
+A Ruby client for the DropBox REST API.
+
+Goal:
+
+To deliver a more Rubyesque experience when using the DropBox API.
+
+Current state:
+
+First release, whole API covered.
+
+Important!!!
+------------
+
+From version 0.2.0, Dropbox::API::File#delete and Dropbox::API::Dir#delete *are gone*!!
+
+The reason is that it's based on Hashie::Mash and was screwing Hash#delete.
+
+It is replaced with Dropbox::API::File#destroy and Dropbox::API::Dir#destroy.
+
+Installation
+------------
+
+Dropbox::API is available on RubyGems, so:
+
+```
+gem install dropbox-api
+```
+
+Or in your Gemfile:
+
+```ruby
+gem "dropbox-api"
+```
+
+Configuration
+-------------
+
+In order to use this client, you need to have an app created on https://www.dropbox.com/developers/apps.
+
+Once you have it, put this configuration somewhere in your code, before you start working with the client.
+
+```ruby
+Dropbox::API::Config.app_key    = YOUR_APP_TOKEN
+Dropbox::API::Config.app_secret = YOUR_APP_SECRET
+Dropbox::API::Config.mode       = "sandbox" # if you have a single-directory app or "dropbox" if it has access to the whole dropbox
+```
+
+Dropbox::API::Client
+--------------------
+
+The client is the base for all communication with the API and wraps around almost all calls
+available in the API.
+
+In order to create a Dropbox::API::Client object, you need to have the configuration set up for OAuth.
+Second thing you need is to have the user authorize your app using OAuth. Here's a short intro
+on how to do this:
+
+```ruby
+consumer = Dropbox::API::OAuth.consumer(:authorize)
+request_token = consumer.get_request_token
+# Store the token and secret so after redirecting we have the same request token
+session[:token] = request_token.token
+session[:token_secret] = request_token.secret
+request_token.authorize_url(:oauth_callback => 'http://yoursite.com/callback')
+# Here the user goes to Dropbox, authorizes the app and is redirected
+hash = { oauth_token: session[:token], oauth_token_secret: session[:token_secret]}
+request_token  = OAuth::RequestToken.from_hash(consumer, hash)
+result = request_token.get_access_token(:oauth_verifier => oauth_token)
+```
+
+Now that you have the oauth token and secret, you can create a new instance of the Dropbox::API::Client, like this:
+
+```ruby
+client = Dropbox::API::Client.new :token => result.token, :secret => result.secret
+```
+
+Rake-based authorization
+------------------------
+
+Dropbox::API supplies you with a helper rake which will authorize a single client. This is useful for development and testing.
+
+In order to have this rake available, put this on your Rakefile:
+
+```ruby
+require "dropbox-api/tasks"
+Dropbox::API::Tasks.install
+```
+
+You will notice that you have a new rake task - dropbox:authorize
+
+When you call this Rake task, it will ask you to provide the consumer key and secret. Afterwards it will present you with an authorize url on Dropbox.
+
+Simply go to that url, authorize the app, then press enter in the console.
+
+The rake task will output valid ruby code which you can use to create a client.
+
+What differs this from the DropBox Ruby SDK?
+--------------------------------------------
+
+A few things:
+
+* It's using the ruby oauth gem, instead of reinventing the wheel and implementing OAuth communication
+* It treats files and directories as Ruby objects with appropriate classes, on which you can perform operations
+
+Consider the following example which takes all files with names like 'test.txt' and copies them with a suffix '.old'
+
+This is how it would look using the SDK:
+
+```ruby
+# Because you need the session with the right access token, you need to create one instance per user
+@session = DropboxSession.new(APP_TOKEN, APP_SECRET)
+@session.set_access_token(ACCESS_TOKEN, ACCESS_SECRET)
+@client = DropboxClient.new(@session, :app_folder)
+# The result is a hash, so we need to call a method on the client, supplying the right key from the hash
+@client.search('/', 'test.txt').each do |hash|
+  @client.file_copy(hash['path'], hash['path'] + ".old")
+end
+```
+
+With Dropbox::API, you can clean it up, first you put the app token and secret in a config or initializer file:
+
+```ruby
+Dropbox::API::Config.app_key    = APP_TOKEN
+Dropbox::API::Config.app_secret = APP_SECRET
+```
+
+And when you want to use it, just create a new client object with a specific access token and secret:
+
+```ruby
+# The app token and secret are read from config, that's all you need to have a client ready for one user
+@client = Dropbox::API::Client.new(:token  => ACCESS_TOKEN, :secret => ACCESS_SECRET)
+# The file is a Dropbox::API::File object, so you can call methods on it!
+@client.search('test.txt').each do |file|
+  file.copy(file.path + ".old2")
+end
+```
+
+What differs this from the dropbox gem?
+--------------------------------------
+
+Dropbox::API does not extend the Ruby primitives, like the dropbox gem:
+
+https://github.com/RISCfuture/dropbox/tree/master/lib/dropbox/extensions
+
+Dropbox::API::Client methods
+----------------------------
+
+### Dropbox::API::Client#account
+
+Returns a simple object with information about the account:
+
+```ruby
+client.account # => #<Dropbox::API::Object>
+```
+
+For more info, see [https://www.dropbox.com/developers/reference/api#account-info](https://www.dropbox.com/developers/reference/api#account-info)
+
+### Dropbox::API::Client#find
+
+When provided a path, returns a single file or directory
+
+```ruby
+client.find 'file.txt' # => #<Dropbox::API::File>
+```
+
+### Dropbox::API::Client#ls
+
+When provided a path, returns a list of files or directories within that path
+
+By default it's the root path:
+
+```ruby
+client.ls # => [#<Dropbox::API::File>, #<Dropbox::API::Dir>]
+```
+
+But you can provide your own path:
+
+```ruby
+client.ls 'somedir' # => [#<Dropbox::API::File>, #<Dropbox::API::Dir>]
+```
+
+### Dropbox::API::Client#mkdir
+
+Creates a new directory and returns a Dropbox::API::Dir object
+
+```ruby
+client.mkdir 'new_dir' # => #<Dropbox::API::Dir>
+```
+
+### Dropbox::API::Client#upload
+
+Stores a file with a provided body under a provided name and returns a Dropbox::API::File object
+
+```ruby
+client.upload 'file.txt', 'file body' # => #<Dropbox::API::File>
+```
+
+### Dropbox::API::Client#download
+
+Downloads a file with a provided name and returns it's content
+
+```ruby
+client.download 'file.txt' # => 'file body'
+```
+
+### Dropbox::API::Client#search
+
+When provided a pattern, returns a list of files or directories within that path
+
+By default it searches the root path:
+
+```ruby
+client.search 'pattern' # => [#<Dropbox::API::File>, #<Dropbox::API::Dir>]
+```
+
+However, you can specify your own path:
+
+```ruby
+client.search 'pattern', :path => 'somedir' # => [#<Dropbox::API::File>, #<Dropbox::API::Dir>]
+```
+
+### Dropbox::API::Client#delta
+
+Returns a cursor and a list of files that have changed since the cursor was generated.
+
+```ruby
+delta = client.delta 'abc123'
+delta.cursor # => 'def456'
+delta.entries # => [#<Dropbox::API::File>, #<Dropbox::API::Dir>]
+```
+
+When called without a cursor, it returns all the files.
+
+```ruby
+delta = client.delta 'abc123'
+delta.cursor # => 'abc123'
+delta.entries # => [#<Dropbox::API::File>, #<Dropbox::API::Dir>]
+```
+
+Dropbox::API::File and Dropbox::API::Dir methods
+----------------------------
+
+These methods are shared by Dropbox::API::File and Dropbox::API::Dir
+
+### Dropbox::API::File#copy | Dropbox::API::Dir#copy
+
+Copies a file/directory to a new specified filename
+
+```ruby
+file.copy 'newfilename.txt' # => #<Dropbox::API::File>
+```
+
+### Dropbox::API::File#move | Dropbox::API::Dir#move
+
+Moves a file/directory to a new specified filename
+
+```ruby
+file.move 'newfilename.txt' # => #<Dropbox::API::File>
+```
+
+### Dropbox::API::File#destroy | Dropbox::API::Dir#destroy
+
+Deletes a file/directory
+
+```ruby
+file.destroy 'newfilename.txt' # => #<Dropbox::API::File>
+```
+
+
+Dropbox::API::File methods
+----------------------------
+
+### Dropbox::API::File#revisions
+
+Returns an Array of Dropbox::API::File objects with appropriate rev attribute
+
+For more info, see [https://www.dropbox.com/developers/reference/api#revisions](https://www.dropbox.com/developers/reference/api#revisions)
+
+### Dropbox::API::File#restore
+
+Restores a file to a specific revision
+
+For more info, see [https://www.dropbox.com/developers/reference/api#restore](https://www.dropbox.com/developers/reference/api#restore)
+
+### Dropbox::API::File#share_url
+
+Returns the link to a file page in Dropbox
+
+For more info, see [https://www.dropbox.com/developers/reference/api#shares](https://www.dropbox.com/developers/reference/api#shares)
+
+### Dropbox::API::File#direct_url
+
+Returns the link to a file in Dropbox
+
+For more info, see [https://www.dropbox.com/developers/reference/api#media](https://www.dropbox.com/developers/reference/api#media)
+
+### Dropbox::API::File#thumbnail
+
+Returns the thumbnail for an image
+
+For more info, see [https://www.dropbox.com/developers/reference/api#thumbnail](https://www.dropbox.com/developers/reference/api#thumbnail)
+
+### Dropbox::API::File#download
+
+Downloads a file and returns it's content
+
+```ruby
+file.download # => 'file body'
+```
+
+Dropbox::API::Dir methods
+----------------------------
+
+### Dropbox::API::Dir#ls
+
+Returns a list of files or directorys within that directory
+
+```ruby
+dir.ls # => [#<Dropbox::API::File>, #<Dropbox::API::Dir>]
+```
+
+Testing
+---------
+
+In order to run tests, you need to have an application created and authorized. Put all tokens in spec/connection.yml and you're good to go.
+
+Check out spec/connection.sample.yml for an example.
+
+Copyright
+---------
+
+Copyright (c) 2011 Marcin Bunsch, Future Simple Inc. See LICENSE for details.

data/Rakefile

@@ -0,0 +1,4 @@
+require 'bundler/gem_tasks'
+
+require "dropbox-api/tasks"
+Dropbox::API::Tasks.install

data/dropbox-api.gemspec

@@ -0,0 +1,24 @@
+# -*- encoding: utf-8 -*-
+$:.push File.expand_path("../lib", __FILE__)
+require "dropbox-api/version"
+
+Gem::Specification.new do |s|
+  s.name        = "dropbox-api-petems"
+  s.version     = Dropbox::API::VERSION
+  s.authors     = ["Peter Souter"]
+  s.email       = ["p.morsou@gmail.com"]
+  s.homepage    = "http://github.com/petems/dropbox-api-petems"
+  s.summary     = "A Ruby client for the DropBox REST API (Originally by marcinbunsch, forked by petems)"
+  s.description = "To deliver a more Rubyesque experience when using the DropBox API."
+
+  s.rubyforge_project = "dropbox-api"
+
+  s.add_dependency 'multi_json'
+  s.add_dependency 'oauth'
+  s.add_dependency 'hashie'
+
+  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"]
+end

data/lib/dropbox-api/client/files.rb

@@ -0,0 +1,40 @@
+module Dropbox
+  module API
+
+    class Client
+
+      module Files
+
+        def download(path, options = {})
+          root     = options.delete(:root) || Dropbox::API::Config.mode
+          path     = Dropbox::API::Util.escape(path)
+          url      = ['', "files", root, path].compact.join('/')
+          connection.get_raw(:content, url)
+        end
+
+        def upload(path, data, options = {})
+          root     = options.delete(:root) || Dropbox::API::Config.mode
+          query    = Dropbox::API::Util.query(options)
+          path     = Dropbox::API::Util.escape(path)
+          url      = ['', "files_put", root, path].compact.join('/')
+          response = connection.put(:content, "#{url}?#{query}", data, {
+            'Content-Type'   => "application/octet-stream",
+            "Content-Length" => data.length.to_s
+          })
+          Dropbox::API::File.init(response, self)
+        end
+
+        def copy_from_copy_ref(copy_ref, to, options = {})
+          raw.copy({ 
+            :from_copy_ref => copy_ref, 
+            :to_path => to 
+          }.merge(options))
+        end
+
+      end
+
+    end
+
+  end
+end
+

data/lib/dropbox-api/client/raw.rb

@@ -0,0 +1,51 @@
+module Dropbox
+  module API
+
+    class Raw
+
+      attr_accessor :connection
+
+      def initialize(options = {})
+        @connection = options[:connection]
+      end
+
+      def self.add_method(method, action, options = {})
+        # Add the default root bit, but allow it to be disabled by a config option
+        root = options[:root] == false ? '' : "options[:root] ||= Dropbox::API::Config.mode"
+        self.class_eval <<-STR
+          def #{options[:as] || action}(options = {})
+            #{root}
+            request(:#{options[:endpoint] || 'main'}, :#{method}, "#{action}", options)
+          end
+        STR
+      end
+
+      def request(endpoint, method, action, data = {})
+        action.sub! ':root', data.delete(:root) if action.match ':root'
+        action.sub! ':path', Dropbox::API::Util.escape(data.delete(:path)) if action.match ':path'
+        action = Dropbox::API::Util.remove_double_slashes(action)
+        connection.send(method, endpoint, action, data)
+      end
+
+      add_method :get,  "/account/info",           :as => 'account', :root => false
+
+      add_method :get,  "/metadata/:root/:path",   :as => 'metadata'
+      add_method :post, "/delta",                  :as => 'delta', :root => false
+      add_method :get,  "/revisions/:root/:path",  :as => 'revisions'
+      add_method :post, "/restore/:root/:path",    :as => 'restore'
+      add_method :get,  "/search/:root/:path",     :as => 'search'
+      add_method :post, "/shares/:root/:path",     :as => 'shares'
+      add_method :post, "/media/:root/:path",      :as => 'media'
+
+      add_method :get_raw, "/thumbnails/:root/:path", :as => 'thumbnails', :endpoint => :content
+
+      add_method :post, "/fileops/copy",           :as => "copy"
+      add_method :get,  "/copy_ref/:root/:path",   :as => 'copy_ref'
+      add_method :post, "/fileops/create_folder",  :as => "create_folder"
+      add_method :post, "/fileops/delete",         :as => "delete"
+      add_method :post, "/fileops/move",           :as => "move"
+
+    end
+
+  end
+end

data/lib/dropbox-api/client.rb

@@ -0,0 +1,68 @@
+require "dropbox-api/client/raw"
+require "dropbox-api/client/files"
+
+module Dropbox
+  module API
+
+    class Client
+
+      attr_accessor :raw, :connection
+
+      def initialize(options = {})
+        @connection = Dropbox::API::Connection.new(:token  => options.delete(:token),
+                                                   :secret => options.delete(:secret))
+        @raw        = Dropbox::API::Raw.new :connection => @connection
+        @options    = options
+      end
+
+      include Dropbox::API::Client::Files
+
+      def find(filename)
+        data = self.raw.metadata(:path => filename)
+        data.delete('contents')
+        Dropbox::API::Object.convert(data, self)
+      end
+
+      def ls(path = '')
+        Dropbox::API::Dir.init({'path' => path}, self).ls
+      end
+
+      def account
+        Dropbox::API::Object.init(self.raw.account, self)
+      end
+
+      def mkdir(path)
+        # Remove the characters not allowed by Dropbox
+        path = path.gsub(/[\\\:\?\*\<\>\"\|]+/, '')
+        response = raw.create_folder :path => path
+        Dropbox::API::Dir.init(response, self)
+      end
+
+      def search(term, options = {})
+        options[:path] ||= ''
+        results = raw.search({ :query => term }.merge(options))
+        Dropbox::API::Object.convert(results, self)
+      end
+
+      def delta(cursor=nil)
+        entries  = []
+        has_more = true
+        params   = cursor ? {:cursor => cursor} : {}
+        while has_more
+          response        = raw.delta(params)
+          params[:cursor] = response['cursor']
+          has_more        = response['has_more']
+          entries.push     *response['entries']
+        end
+
+        files = entries.map do |entry|
+          entry.last || {:is_deleted => true, :path => entry.first}
+        end
+
+        Delta.new(params[:cursor], Dropbox::API::Object.convert(files, self))
+      end
+
+    end
+
+  end
+end

data/lib/dropbox-api/connection/requests.rb

@@ -0,0 +1,79 @@
+module Dropbox
+  module API
+
+    class Connection
+
+      module Requests
+
+        def request(options = {})
+          response = yield
+          raise Dropbox::API::Error::ConnectionFailed if !response
+          status = response.code.to_i
+          case status
+            when 400
+              parsed = MultiJson.decode(response.body)
+              raise Dropbox::API::Error::BadInput.new("400 - Bad input parameter - #{parsed['error']}")
+            when 401
+              raise Dropbox::API::Error::Unauthorized.new("401 - Bad or expired token")
+            when 403
+              parsed = MultiJson.decode(response.body)
+              raise Dropbox::API::Error::Forbidden.new('403 - Bad OAuth request')
+            when 404
+              raise Dropbox::API::Error::NotFound.new("404 - Not found")
+            when 405
+              parsed = MultiJson.decode(response.body)
+              raise Dropbox::API::Error::WrongMethod.new("405 - Request method not expected - #{parsed['error']}")
+            when 406
+              parsed = MultiJson.decode(response.body)
+              raise Dropbox::API::Error.new("#{status} - #{parsed['error']}")
+            when 429
+              raise Dropbox::API::Error::RateLimit.new('429 - Rate Limiting in affect')
+            when 300..399
+              raise Dropbox::API::Error::Redirect.new("#{status} - Redirect Error")
+            when 503
+              parsed = MultiJson.decode(response.body)
+              raise Dropbox::API::Error.new("503 - Possible Rate Limiting: #{parsed["error"]}")
+            when 507
+              raise Dropbox::API::Error::StorageQuota.new("507 - Dropbox storage quota exceeded.")
+            when 500..599
+              parsed = MultiJson.decode(response.body)
+              raise Dropbox::API::Error.new("#{status} - Server error. Check http://status.dropbox.com/")
+            else
+              options[:raw] ? response.body : MultiJson.decode(response.body)
+          end
+        end
+
+
+
+        def get_raw(endpoint, path, data = {}, headers = {})
+          query = Dropbox::API::Util.query(data)
+          request(:raw => true) do
+            token(endpoint).get "#{Dropbox::API::Config.prefix}#{path}?#{URI.parse(URI.encode(query))}", headers
+          end
+        end
+
+        def get(endpoint, path, data = {}, headers = {})
+          query = Dropbox::API::Util.query(data)
+          request do
+            token(endpoint).get "#{Dropbox::API::Config.prefix}#{path}?#{URI.parse(URI.encode(query))}", headers
+          end
+        end
+
+        def post(endpoint, path, data = {}, headers = {})
+          request do
+            token(endpoint).post "#{Dropbox::API::Config.prefix}#{path}", data, headers
+          end
+        end
+
+        def put(endpoint, path, data = {}, headers = {})
+          request do
+            token(endpoint).put "#{Dropbox::API::Config.prefix}#{path}", data, headers
+          end
+        end
+
+      end
+
+    end
+
+  end
+end

data/lib/dropbox-api/connection.rb

@@ -0,0 +1,34 @@
+require "dropbox-api/connection/requests"
+
+module Dropbox
+  module API
+
+    class Connection
+
+      include Dropbox::API::Connection::Requests
+
+      attr_accessor :consumers
+      attr_accessor :tokens
+
+      def initialize(options = {})
+        @options   = options
+        @consumers = {}
+        @tokens    = {}
+        Dropbox::API::Config.endpoints.each do |endpoint, url|
+          @consumers[endpoint] = Dropbox::API::OAuth.consumer(endpoint)
+          @tokens[endpoint]    = Dropbox::API::OAuth.access_token(@consumers[endpoint], options)
+        end
+      end
+
+      def consumer(endpoint = :main)
+        @consumers[endpoint]
+      end
+
+      def token(endpoint = :main)
+        @tokens[endpoint]
+      end
+
+    end
+
+  end
+end