dropbox_api 0.1.0

data/lib/dropbox_api/authenticator.rb

@@ -0,0 +1,20 @@
+require 'oauth2'
+
+module DropboxApi
+  class Authenticator < OAuth2::Client
+    def initialize(client_id, client_secret)
+      @oauth_client = OAuth2::Client.new(client_id, client_secret, {
+        :authorize_url => 'https://www.dropbox.com/1/oauth2/authorize',
+        :token_url => 'https://api.dropboxapi.com/1/oauth2/token'
+      })
+    end
+
+    def authorize_url
+      @oauth_client.auth_code.authorize_url
+    end
+
+    def get_token(oauth_code)
+      @oauth_client.auth_code.get_token oauth_code
+    end
+  end
+end

data/lib/dropbox_api/client.rb

@@ -0,0 +1,13 @@
+module DropboxApi
+  class Client
+    def initialize(oauth_bearer = ENV["DROPBOX_OAUTH_BEARER"])
+      @connection_builder = ConnectionBuilder.new(oauth_bearer)
+    end
+
+    def self.add_endpoint(name, endpoint)
+      define_method(name) do |*args, &block|
+        endpoint.new(@connection_builder).send(name, *args, &block)
+      end
+    end
+  end
+end

data/lib/dropbox_api/connection_builder.rb

@@ -0,0 +1,17 @@
+module DropboxApi
+  class ConnectionBuilder
+    def initialize(oauth_bearer)
+      @oauth_bearer = oauth_bearer
+    end
+
+    def build(url)
+      Faraday.new(url) do |c|
+        c.authorization :Bearer, @oauth_bearer
+
+        yield c
+
+        c.adapter Faraday.default_adapter
+      end
+    end
+  end
+end

data/lib/dropbox_api/endpoints/base.rb

@@ -0,0 +1,44 @@
+module DropboxApi::Endpoints
+  class Base
+    def self.add_endpoint(name, &block)
+      define_method(name, block)
+      DropboxApi::Client.add_endpoint(name, self)
+    end
+
+    private
+
+    def perform_request(params)
+      process_response(get_response(params))
+    end
+
+    def get_response(*args)
+      run_request(*build_request(*args))
+    end
+
+    def process_response(raw_response)
+      case raw_response.status
+      when 200, 409
+        # Status code 409 is "Endpoint-specific error". We need to look at
+        # the response body to build an exception.
+        build_result(raw_response.env[:api_result])
+      else
+        raise DropboxApi::Errors::HttpError,
+          "HTTP #{raw_response.status}: #{raw_response.body}"
+      end
+    end
+
+    def build_result(api_result)
+      result_builder = DropboxApi::ResultBuilder.new(api_result)
+
+      if result_builder.has_error?
+        raise result_builder.build_error(self.class::ErrorType)
+      else
+        result_builder.build(self.class::ResultType)
+      end
+    end
+
+    def run_request(body, headers)
+      @connection.run_request(self.class::Method, self.class::Path, body, headers)
+    end
+  end
+end

data/lib/dropbox_api/endpoints/content_download.rb

@@ -0,0 +1,33 @@
+module DropboxApi::Endpoints
+  class ContentDownload < DropboxApi::Endpoints::Base
+    def initialize(builder)
+      @connection = builder.build("https://content.dropboxapi.com") do |c|
+        c.response :decode_result
+      end
+    end
+
+    def build_request(params)
+      body = nil
+      headers = {
+        'Dropbox-API-Arg' => JSON.dump(params),
+        'Content-Type' => ''
+      }
+
+      return body, headers
+    end
+
+    def perform_request(params)
+      response = get_response(params)
+      api_result = process_response response
+
+      # TODO: Stream response, current implementation will fail with very large
+      #       files.
+      yield response.body if block_given?
+
+      api_result
+    end
+  end
+end
+# TODO:
+#  1. Combine ContentDownload and ContentUpload to share its initialize method.
+#  2. Reorganize the methods which create the request.

data/lib/dropbox_api/endpoints/content_upload.rb

@@ -0,0 +1,25 @@
+module DropboxApi::Endpoints
+  class ContentUpload < DropboxApi::Endpoints::Base
+    def initialize(builder)
+      @connection = builder.build("https://content.dropboxapi.com") do |c|
+        c.response :decode_result
+      end
+    end
+
+    def build_request(params, content)
+      # TODO: It would be better to have a stream object on which we can call
+      #       #read, rather than the full file content.
+      body = content
+      headers = {
+        'Dropbox-API-Arg' => JSON.dump(params),
+        'Content-Type' => 'application/octet-stream'
+      }
+
+      return body, headers
+    end
+
+    def perform_request(params, content)
+      process_response(get_response(params, content))
+    end
+  end
+end

data/lib/dropbox_api/endpoints/files/copy.rb

@@ -0,0 +1,22 @@
+module DropboxApi::Endpoints::Files
+  class Copy < DropboxApi::Endpoints::Rpc
+    Method      = :post
+    Path        = "/2/files/copy".freeze
+    ResultType  = DropboxApi::Metadata::Resource
+    ErrorType   = DropboxApi::Errors::RelocationError
+
+    # @method copy(from, to)
+    # Copy a file or folder to a different location in the user's Dropbox.
+    # If the source path is a folder all its contents will be copied.
+    #
+    # @param from [String] Path in the user's Dropbox to be copied or moved.
+    # @param to [String] Path in the user's Dropbox that is the destination.
+    # @return The moved file.
+    add_endpoint :copy do |from, to|
+      perform_request({
+        :from_path => from,
+        :to_path => to
+      })
+    end
+  end
+end

data/lib/dropbox_api/endpoints/files/create_folder.rb

@@ -0,0 +1,19 @@
+module DropboxApi::Endpoints::Files
+  class CreateFolder < DropboxApi::Endpoints::Rpc
+    Method      = :post
+    Path        = "/2/files/create_folder".freeze
+    ResultType  = DropboxApi::Metadata::Folder
+    ErrorType   = DropboxApi::Errors::CreateFolderError
+
+    # @method create_folder(path)
+    # Create a folder at a given path.
+    #
+    # @param path [String] Path in the user's Dropbox to create.
+    # @return [DropboxApi::Metadata::Folder] The new folder.
+    add_endpoint :create_folder do |path|
+      perform_request({
+        :path => path
+      })
+    end
+  end
+end

data/lib/dropbox_api/endpoints/files/delete.rb

@@ -0,0 +1,25 @@
+module DropboxApi::Endpoints::Files
+  class Delete < DropboxApi::Endpoints::Rpc
+    Method      = :post
+    Path        = "/2/files/delete".freeze
+    ResultType  = DropboxApi::Metadata::Resource
+    ErrorType   = DropboxApi::Errors::DeleteError
+
+    # @method delete(path)
+    # Delete the file or folder at a given path.
+    #
+    # If the path is a folder, all its contents will be deleted too.
+    #
+    # A successful response indicates that the file or folder was deleted.
+    # The returned metadata will be the corresponding FileMetadata or
+    # FolderMetadata for the item at time of deletion, and not a
+    # DeletedMetadata object.
+    #
+    # @param path [String] Path in the user's Dropbox to delete.
+    add_endpoint :delete do |path|
+      perform_request({
+        :path => path
+      })
+    end
+  end
+end

data/lib/dropbox_api/endpoints/files/download.rb

@@ -0,0 +1,16 @@
+module DropboxApi::Endpoints::Files
+  class Download < DropboxApi::Endpoints::ContentDownload
+    Method      = :post
+    Path        = "/2/files/download".freeze
+    ResultType  = DropboxApi::Metadata::File
+    ErrorType   = DropboxApi::Errors::DownloadError
+
+    # @method download(path)
+    # Download a file from a user's Dropbox.
+    #
+    # @param path [String] The path of the file to download.
+    add_endpoint :download do |path, &block|
+      perform_request({:path => path}, &block)
+    end
+  end
+end

data/lib/dropbox_api/endpoints/files/get_metadata.rb

@@ -0,0 +1,29 @@
+module DropboxApi::Endpoints::Files
+  class GetMetadata < DropboxApi::Endpoints::Rpc
+    Method      = :post
+    Path        = "/2/files/get_metadata".freeze
+    ResultType  = DropboxApi::Metadata::Resource
+    ErrorType   = DropboxApi::Errors::GetMetadataError
+
+    include DropboxApi::Endpoints::OptionsValidator
+
+    # @method get_metadata(path, options = {})
+    # Returns the metadata for a file or folder.
+    #
+    # Note: Metadata for the root folder is unsupported.
+    #
+    # @param path [String] The path of a file or folder on Dropbox.
+    # @option include_media_info [Boolean] If `true`, FileMetadata.media_info
+    #   is set for photo and video. The default for this field is `false`.
+    # @option include_deleted [Boolean] If `true`, DeletedMetadata will be
+    #   returned for deleted file or folder, otherwise LookupError.not_found
+    #   will be returned. The default for this field is False.
+    add_endpoint :get_metadata do |path, options = {}|
+      validate_options([:include_media_info, :include_deleted], options)
+
+      perform_request(options.merge({
+        :path => path
+      }))
+    end
+  end
+end

data/lib/dropbox_api/endpoints/files/get_preview.rb

@@ -0,0 +1,18 @@
+module DropboxApi::Endpoints::Files
+  class GetPreview < DropboxApi::Endpoints::ContentDownload
+    Method      = :post
+    Path        = "/2/files/get_preview".freeze
+    ResultType  = DropboxApi::Metadata::File
+    ErrorType   = DropboxApi::Errors::PreviewError
+
+    # @method get_preview(path)
+    # Get a preview for a file. Currently previews are only generated for the
+    # files with the following extensions: .doc, .docx, .docm, .ppt, .pps,
+    # .ppsx, .ppsm, .pptx, .pptm, .xls, .xlsx, .xlsm, .rtf
+    #
+    # @param path [String] The path of the file to preview.
+    add_endpoint :get_preview do |path, &block|
+      perform_request({:path => path}, &block)
+    end
+  end
+end

data/lib/dropbox_api/endpoints/files/get_temporary_link.rb

@@ -0,0 +1,18 @@
+module DropboxApi::Endpoints::Files
+  class GetTemporaryLink < DropboxApi::Endpoints::Rpc
+    Method      = :post
+    Path        = "/2/files/get_temporary_link".freeze
+    ResultType  = DropboxApi::Results::GetTemporaryLinkResult
+    ErrorType   = DropboxApi::Errors::GetMetadataError
+
+    # @method get_temporary_link(path)
+    # Get a temporary link to stream content of a file. This link will expire
+    # in four hours and afterwards you will get 410 Gone. Content-Type of the
+    # link is determined automatically by the file's mime type.
+    #
+    # @param path [String] The path to the file you want a temporary link to.
+    add_endpoint :get_temporary_link do |path|
+      perform_request({:path => path})
+    end
+  end
+end

data/lib/dropbox_api/endpoints/files/get_thumbnail.rb

@@ -0,0 +1,34 @@
+module DropboxApi::Endpoints::Files
+  class GetThumbnail < DropboxApi::Endpoints::ContentDownload
+    Method      = :post
+    Path        = "/2/files/get_thumbnail".freeze
+    ResultType  = DropboxApi::Metadata::File
+    ErrorType   = DropboxApi::Errors::PreviewError
+
+    include DropboxApi::Endpoints::OptionsValidator
+
+    # @method get_thumbnail(path, options = {})
+    # Get a thumbnail for an image.
+    #
+    # This method currently supports files with the following file extensions:
+    # jpg, jpeg, png, tiff, tif, gif and bmp. Photos that are larger than 20MB
+    # in size won't be converted to a thumbnail.
+    #
+    # @param path [String] The path to the image file you want to thumbnail.
+    # @option format [:jpeg, :png] The format for the thumbnail image, jpeg
+    #   (default) or png. For images that are photos, jpeg should be preferred,
+    #   while png is better for screenshots and digital arts. The default is
+    #   :jpeg.
+    # @option size [:w32h32, :w64h64, :w128h128, :w640h480, :w1024h768] The
+    #   size for the thumbnail image. The default is :w64h64
+    add_endpoint :get_thumbnail do |path, options = {}, &block|
+      validate_options([:format, :size], options)
+      options[:format] ||= :jpeg
+      options[:size] ||= :w64h64
+
+      perform_request(options.merge({
+        :path => path
+      }), &block)
+    end
+  end
+end

data/lib/dropbox_api/endpoints/files/list_folder.rb

@@ -0,0 +1,38 @@
+module DropboxApi::Endpoints::Files
+  class ListFolder < DropboxApi::Endpoints::Rpc
+    Method      = :post
+    Path        = "/2/files/list_folder".freeze
+    ResultType  = DropboxApi::Results::ListFolderResult
+    ErrorType   = DropboxApi::Errors::ListFolderError
+
+    include DropboxApi::Endpoints::OptionsValidator
+
+    # @method list_folder(path, options = {})
+    # Returns the contents of a folder.
+    #
+    # @param path [String] The path to the folder you want to read.
+    # @option recursive [Boolean] If `true`, the list folder operation will be
+    #   applied recursively to all subfolders and the response will contain
+    #   contents of all subfolders. The default for this field is `false`.
+    # @option include_media_info [Boolean] If `true`, FileMetadata.media_info
+    #   is set for photo and video. The default for this field is `false`.
+    # @option include_deleted [Boolean] If `true`, DeletedMetadata will be
+    #   returned for deleted file or folder, otherwise LookupError.not_found
+    #   will be returned. The default for this field is `false`.
+    add_endpoint :list_folder do |path, options = {}|
+      validate_options([
+        :recursive,
+        :include_media_info,
+        :include_deleted,
+        :include_has_explicit_shared_members
+      ], options)
+      options[:recursive] ||= false
+      options[:include_media_info] ||= false
+      options[:include_deleted] ||= false
+
+      perform_request options.merge({
+        :path => path
+      })
+    end
+  end
+end

data/lib/dropbox_api/endpoints/files/list_folder_continue.rb

@@ -0,0 +1,21 @@
+module DropboxApi::Endpoints::Files
+  class ListFolderContinue < DropboxApi::Endpoints::Rpc
+    # NOTE: This hasn't been tested with real data, I couldn't make a query
+    #       long enough to enable the `has_more` attribute in the
+    #       `ListFolderResult`.
+    Method      = :post
+    Path        = "/2/files/list_folder/continue".freeze
+    ResultType  = DropboxApi::Results::ListFolderResult
+    ErrorType   = DropboxApi::Errors::ListFolderContinueError
+
+    # @method list_folder_continue(cursor)
+    # Once a cursor has been retrieved from `list_folder`, use this to paginate
+    # through all files and retrieve updates to the folder.
+    #
+    # @param cursor [String] The cursor returned by your last call to
+    #   list_folder or list_folder_continue.
+    add_endpoint :list_folder_continue do |cursor|
+      perform_request :cursor => cursor
+    end
+  end
+end

data/lib/dropbox_api/endpoints/files/list_folder_get_latest_cursor.rb

@@ -0,0 +1,40 @@
+module DropboxApi::Endpoints::Files
+  class ListFolderGetLatestCursor < DropboxApi::Endpoints::Rpc
+    Method      = :post
+    Path        = "/2/files/list_folder/get_latest_cursor".freeze
+    ResultType  = DropboxApi::Results::ListFolderGetLatestCursorResult
+    ErrorType   = DropboxApi::Errors::ListFolderError
+
+    include DropboxApi::Endpoints::OptionsValidator
+
+    # @method list_folder_get_latest_cursor(options)
+    # A way to quickly get a cursor for the folder's state. Unlike list_folder,
+    # list_folder_get_latest_cursor doesn't return any entries. This endpoint
+    # is for app which only needs to know about new files and modifications and
+    # doesn't need to know about files that already exist in Dropbox.
+    #
+    # @param path [String] The path to the folder you want to read.
+    # @option recursive [Boolean] If `true`, the list folder operation will be
+    #   applied recursively to all subfolders and the response will contain
+    #   contents of all subfolders. The default for this field is `false`.
+    # @option include_media_info [Boolean] If `true`, FileMetadata.media_info
+    #   is set for photo and video. The default for this field is `false`.
+    # @option include_deleted [Boolean] If `true`, DeletedMetadata will be
+    #   returned for deleted file or folder, otherwise LookupError.not_found
+    #   will be returned. The default for this field is False.
+    add_endpoint :list_folder_get_latest_cursor do |options = {}|
+      validate_options([
+        :path,
+        :recursive,
+        :include_media_info,
+        :include_deleted,
+        :include_has_explicit_shared_members
+      ], options)
+      options[:recursive] ||= false
+      options[:include_media_info] ||= false
+      options[:include_deleted] ||= false
+
+      perform_request options
+    end
+  end
+end