dropbox_api 0.1.16 → 0.1.21

data/docs/top-level-namespace.html

@@ -6,15 +6,15 @@
 <title>
   Top Level Namespace
   
-    &mdash; Documentation by YARD 0.9.15
+    &mdash; Documentation by YARD 0.9.26
   
 </title>
 
-  <link rel="stylesheet" href="css/style.css" type="text/css" charset="utf-8" />
+  <link rel="stylesheet" href="css/style.css" type="text/css" />
 
-  <link rel="stylesheet" href="css/common.css" type="text/css" charset="utf-8" />
+  <link rel="stylesheet" href="css/common.css" type="text/css" />
 
-<script type="text/javascript" charset="utf-8">
+<script type="text/javascript">
   pathId = "";
   relpath = '';
 </script>
@@ -102,9 +102,9 @@
 </div>
 
       <div id="footer">
-  Generated on Fri Nov 16 09:02:01 2018 by
+  Generated on Wed Sep 29 23:44:24 2021 by
   <a href="http://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
-  0.9.15 (ruby-2.3.3).
+  0.9.26 (ruby-2.6.5).
 </div>
 
     </div>

data/dropbox_api.gemspec

@@ -1,30 +1,25 @@
 # coding: utf-8
+# frozen_string_literal: true
 lib = File.expand_path('../lib', __FILE__)
 $LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
 require 'dropbox_api/version'
 
 Gem::Specification.new do |spec|
-  spec.name          = "dropbox_api"
+  spec.name          = 'dropbox_api'
   spec.version       = DropboxApi::VERSION
-  spec.authors       = ["Jesús Burgos"]
-  spec.email         = ["jburmac@gmail.com"]
+  spec.authors       = ['Jesús Burgos']
+  spec.email         = ['jburmac@gmail.com']
 
-  spec.summary       = "Library for communicating with Dropbox API v2"
-  spec.homepage      = "https://github.com/Jesus/dropbox_api"
-  spec.license       = "MIT"
+  spec.summary       = 'Library for communicating with Dropbox API v2'
+  spec.homepage      = 'https://github.com/Jesus/dropbox_api'
+  spec.license       = 'MIT'
 
   spec.files         = `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
 
-  spec.require_paths = ["lib"]
+  spec.require_paths = ['lib']
 
-  spec.has_rdoc = "yard"
+  spec.required_ruby_version = '>= 2.3'
 
-  spec.add_development_dependency "bundler", ">= 1.7"
-  spec.add_development_dependency "rake", "~> 10.0"
-  spec.add_development_dependency "rspec"
-  spec.add_development_dependency "vcr"
-  spec.add_development_dependency "webmock"
-
-  spec.add_dependency "oauth2", "~> 1.1"
-  spec.add_dependency "faraday", ">= 0.8", "<= 0.15.4"
+  spec.add_dependency 'faraday', '< 3.0'
+  spec.add_dependency 'oauth2', '~> 1.1'
 end

data/lib/dropbox_api/authenticator.rb

@@ -1,16 +1,13 @@
+# frozen_string_literal: true
 require 'oauth2'
 
 module DropboxApi
   class Authenticator < OAuth2::Client
-    extend Forwardable
-
     def initialize(client_id, client_secret)
-      @auth_code = OAuth2::Client.new(client_id, client_secret, {
-        :authorize_url => 'https://www.dropbox.com/oauth2/authorize',
-        :token_url => 'https://api.dropboxapi.com/oauth2/token'
-      }).auth_code
+      super(client_id, client_secret, {
+        authorize_url: 'https://www.dropbox.com/oauth2/authorize',
+        token_url: 'https://api.dropboxapi.com/oauth2/token'
+      })
     end
-
-    def_delegators :@auth_code, :authorize_url, :get_token
   end
 end

data/lib/dropbox_api/chunked_uploader.rb

@@ -1,3 +1,4 @@
+# frozen_string_literal: true
 module DropboxApi
   class ChunkedUploader
     include DropboxApi::OptionsValidator
@@ -13,7 +14,7 @@ module DropboxApi
 
     def start
       chunk = @i_stream.read @chunk_size
-      chunk = "" if chunk.nil?
+      chunk = '' if chunk.nil?
 
       @cursor = @client.upload_session_start chunk
     end

data/lib/dropbox_api/client.rb

@@ -1,13 +1,35 @@
+# frozen_string_literal: true
 module DropboxApi
   class Client
-    def initialize(oauth_bearer = ENV["DROPBOX_OAUTH_BEARER"])
-      @connection_builder = ConnectionBuilder.new(oauth_bearer)
+    def initialize(
+      oauth_bearer = ENV['DROPBOX_OAUTH_BEARER'],
+      access_token: nil,
+      on_token_refreshed: nil
+    )
+      if access_token
+        @connection_builder = ConnectionBuilder.new(
+          access_token: access_token,
+          on_token_refreshed: on_token_refreshed
+        )
+      elsif oauth_bearer
+        @connection_builder = ConnectionBuilder.new(oauth_bearer)
+      else
+        raise ArgumentError, "Either oauth_bearer or access_token should be set"
+      end
     end
 
     def middleware
       @connection_builder.middleware
     end
 
+    def namespace_id=(value)
+      @connection_builder.namespace_id = value
+    end
+
+    def namespace_id
+      @connection_builder.namespace_id
+    end
+
     # @!visibility private
     def self.add_endpoint(name, endpoint)
       define_method(name) do |*args, &block|

data/lib/dropbox_api/connection_builder.rb

@@ -1,18 +1,53 @@
+# frozen_string_literal: true
 module DropboxApi
   class ConnectionBuilder
-    def initialize(oauth_bearer)
-      @oauth_bearer = oauth_bearer
+    attr_accessor :namespace_id
+
+    def initialize(oauth_bearer = nil, access_token: nil, on_token_refreshed: nil)
+      if access_token
+        if !access_token.is_a?(OAuth2::AccessToken)
+          raise ArgumentError, "access_token should be an OAuth2::AccessToken"
+        end
+
+        @access_token = access_token
+        @on_token_refreshed = on_token_refreshed
+      elsif oauth_bearer
+        @oauth_bearer = oauth_bearer
+      else
+        raise ArgumentError, "Either oauth_bearer or access_token should be set"
+      end
     end
 
     def middleware
       @middleware ||= MiddleWare::Stack.new
     end
 
+    def can_refresh_access_token?
+      @access_token && @access_token.refresh_token
+    end
+
+    def refresh_access_token
+      @access_token = @access_token.refresh!
+      @on_token_refreshed.call(@access_token.to_hash) if @on_token_refreshed
+    end
+
+    private def bearer
+      @oauth_bearer or oauth_bearer_from_access_token
+    end
+
+    private def oauth_bearer_from_access_token
+      refresh_access_token if @access_token.expired?
+
+      @access_token.token
+    end
+
     def build(url)
       Faraday.new(url) do |connection|
+        connection.use DropboxApi::MiddleWare::PathRoot, {
+          namespace_id: self.namespace_id
+        }
         middleware.apply(connection) do
-          connection.authorization :Bearer, @oauth_bearer
-
+          connection.request :authorization, :Bearer, bearer
           yield connection
         end
       end

data/lib/dropbox_api/endpoints/auth/token_revoke.rb

@@ -1,7 +1,8 @@
+# frozen_string_literal: true
 module DropboxApi::Endpoints::Auth
   class TokenRevoke < DropboxApi::Endpoints::Rpc
     Method      = :post
-    Path        = "/2/auth/token/revoke".freeze
+    Path        = '/2/auth/token/revoke'
     ResultType  = DropboxApi::Results::VoidResult
     ErrorType   = nil
 

data/lib/dropbox_api/endpoints/base.rb

@@ -1,5 +1,11 @@
+# frozen_string_literal: true
 module DropboxApi::Endpoints
   class Base
+    def initialize(builder)
+      @builder = builder
+      build_connection
+    end
+
     def self.add_endpoint(name, &block)
       define_method(name, block)
       DropboxApi::Client.add_endpoint(name, self)
@@ -9,6 +15,14 @@ module DropboxApi::Endpoints
 
     def perform_request(params)
       process_response(get_response(params))
+    rescue DropboxApi::Errors::ExpiredAccessTokenError => e
+      if @builder.can_refresh_access_token?
+        @builder.refresh_access_token
+        build_connection
+        process_response(get_response(params))
+      else
+        raise e
+      end
     end
 
     def get_response(*args)
@@ -23,18 +37,25 @@ module DropboxApi::Endpoints
         # 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])
+      when 401
+        raise DropboxApi::Errors::ExpiredAccessTokenError.build(
+          raw_response.env[:api_result]['error_summary'],
+          raw_response.env[:api_result]['error']
+        )
       when 429
         error = DropboxApi::Errors::TooManyRequestsError.build(
-          raw_response.env[:api_result]["error_summary"],
-          raw_response.env[:api_result]["error"]["reason"]
+          raw_response.env[:api_result]['error_summary'],
+          raw_response.env[:api_result]['error']['reason']
         )
 
-        error.retry_after = raw_response.headers["retry-after"].to_i
+        error.retry_after = raw_response.headers['retry-after'].to_i
 
         raise error
       else
-        raise DropboxApi::Errors::HttpError,
+        raise(
+          DropboxApi::Errors::HttpError,
           "HTTP #{raw_response.status}: #{raw_response.body}"
+        )
       end
     end
 
@@ -49,7 +70,12 @@ module DropboxApi::Endpoints
     end
 
     def run_request(body, headers)
-      @connection.run_request(self.class::Method, self.class::Path, body, headers)
+      @connection.run_request(
+        self.class::Method,
+        self.class::Path,
+        body,
+        headers
+      )
     end
   end
 end

data/lib/dropbox_api/endpoints/content_download.rb

@@ -1,7 +1,8 @@
+# frozen_string_literal: true
 module DropboxApi::Endpoints
   class ContentDownload < DropboxApi::Endpoints::Base
-    def initialize(builder)
-      @connection = builder.build("https://content.dropboxapi.com") do |c|
+    def build_connection
+      @connection = @builder.build('https://content.dropboxapi.com') do |c|
         c.response :decode_result
       end
     end
@@ -20,14 +21,11 @@ module DropboxApi::Endpoints
       response = get_response(params)
       api_result = process_response response
 
-      # TODO: Stream response, current implementation will fail with very large
-      #       files.
+      # We just yield the whole response to the block, it'd be nice in the
+      # future to support an interface that streams the response in chunks.
       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

@@ -1,7 +1,8 @@
+# frozen_string_literal: true
 module DropboxApi::Endpoints
   class ContentUpload < DropboxApi::Endpoints::Base
-    def initialize(builder)
-      @connection = builder.build("https://content.dropboxapi.com") do |c|
+    def build_connection
+      @connection = @builder.build('https://content.dropboxapi.com') do |c|
         c.response :decode_result
       end
     end

data/lib/dropbox_api/endpoints/file_requests/create_file_request.rb

@@ -1,7 +1,8 @@
+# frozen_string_literal: true
 module DropboxApi::Endpoints::Files
   class CreateFileRequest < DropboxApi::Endpoints::Rpc
     Method      = :post
-    Path        = "/2/file_requests/create".freeze
+    Path        = '/2/file_requests/create'
     ResultType  = DropboxApi::Metadata::FileRequest
     ErrorType   = DropboxApi::Errors::CreateFileRequestError
 

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

@@ -1,7 +1,8 @@
+# frozen_string_literal: true
 module DropboxApi::Endpoints::Files
   class Copy < DropboxApi::Endpoints::Rpc
     Method      = :post
-    Path        = "/2/files/copy".freeze
+    Path        = '/2/files/copy'
     ResultType  = DropboxApi::Metadata::Resource
     ErrorType   = DropboxApi::Errors::RelocationError
 
@@ -13,8 +14,8 @@ module DropboxApi::Endpoints::Files
     # @return The moved file.
     add_endpoint :copy do |from, to|
       perform_request({
-        :from_path => from,
-        :to_path => to
+        from_path: from,
+        to_path: to
       })
     end
   end

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

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+module DropboxApi::Endpoints::Files
+  class CopyBatch < DropboxApi::Endpoints::Rpc
+    Method      = :post
+    Path        = '/2/files/copy_batch_v2'
+    ResultType  = DropboxApi::Results::CopyBatchResult
+
+    include DropboxApi::OptionsValidator
+
+    # Copy multiple files or folders to different locations at once in the
+    # user's Dropbox.
+    #
+    # This will either finish synchronously, or return a job ID and do
+    # the async copy job in background. Please use {Client#copy_batch_check}
+    # to check the job status.
+    #
+    # Note: No errors are returned by this endpoint.
+    #
+    # @param entries [Array<Hash>] List of entries to be moved or copied.
+    #   Each entry must be a hash with two keys: `:from_path` & `:to_path`.
+    # @option options autorename [Boolean] If there's a conflict with any file,
+    #   have the Dropbox server try to autorename that file to avoid the
+    #   conflict. The default for this field is `false`.
+    # @return [String, Array] Either the job id or the list of job statuses.
+    add_endpoint :copy_batch do |entries, options = {}|
+      validate_options([
+        :autorename
+      ], options)
+      options[:autorename] ||= false
+
+      perform_request(options.merge({
+        entries: entries
+      }))
+    end
+  end
+end

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

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+module DropboxApi::Endpoints::Files
+  class CopyBatchCheck < DropboxApi::Endpoints::Rpc
+    Method      = :post
+    Path        = '/2/files/copy_batch/check_v2'
+    ResultType  = DropboxApi::Results::RelocationBatchResult
+    ErrorType   = DropboxApi::Errors::PollError
+
+    # Returns the status of an asynchronous job for {Client#copy_batch}. It
+    # returns a list of results for each entry.
+    #
+    # @param async_job_id [String] Id of the asynchronous job.
+    #   This is the value of a response returned from the method that
+    #   launched the job.
+    # @return [:in_progress, Array] This could be either the `:in_progress`
+    #   flag or a list of job statuses.
+    add_endpoint :copy_batch_check do |async_job_id|
+      perform_request async_job_id: async_job_id
+    end
+  end
+end

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

@@ -1,7 +1,8 @@
+# frozen_string_literal: true
 module DropboxApi::Endpoints::Files
   class CopyReferenceGet < DropboxApi::Endpoints::Rpc
     Method      = :post
-    Path        = "/2/files/copy_reference/get".freeze
+    Path        = '/2/files/copy_reference/get'
     ResultType  = DropboxApi::Results::GetCopyReferenceResult
     ErrorType   = DropboxApi::Errors::GetCopyReferenceError
 
@@ -14,7 +15,7 @@ module DropboxApi::Endpoints::Files
     # @return [DropboxApi::Results::GetCopyReferenceResult]
     add_endpoint :copy_reference_get do |path|
       perform_request({
-        :path => path
+        path: path
       })
     end
   end

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

@@ -1,7 +1,8 @@
+# frozen_string_literal: true
 module DropboxApi::Endpoints::Files
   class CopyReferenceSave < DropboxApi::Endpoints::Rpc
     Method      = :post
-    Path        = "/2/files/copy_reference/save".freeze
+    Path        = '/2/files/copy_reference/save'
     ResultType  = DropboxApi::Results::SaveCopyReferenceResult
     ErrorType   = DropboxApi::Errors::SaveCopyReferenceError
 
@@ -14,8 +15,8 @@ module DropboxApi::Endpoints::Files
     # @return [DropboxApi::Results::SaveCopyReferenceResult]
     add_endpoint :copy_reference_save do |copy_reference, path|
       perform_request({
-        :copy_reference => copy_reference,
-        :path => path
+        copy_reference: copy_reference,
+        path: path
       })
     end
   end

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

@@ -1,7 +1,8 @@
+# frozen_string_literal: true
 module DropboxApi::Endpoints::Files
   class CreateFolder < DropboxApi::Endpoints::Rpc
     Method      = :post
-    Path        = "/2/files/create_folder".freeze
+    Path        = '/2/files/create_folder'
     ResultType  = DropboxApi::Metadata::Folder
     ErrorType   = DropboxApi::Errors::CreateFolderError
 
@@ -11,7 +12,7 @@ module DropboxApi::Endpoints::Files
     # @return [DropboxApi::Metadata::Folder] The new folder.
     add_endpoint :create_folder do |path|
       perform_request({
-        :path => path
+        path: path
       })
     end
   end

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

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+module DropboxApi::Endpoints::Files
+  class CreateFolderBatch < DropboxApi::Endpoints::Rpc
+    Method      = :post
+    Path        = '/2/files/create_folder_batch'
+    ResultType  = DropboxApi::Results::CreateFolderBatchResult
+
+    include DropboxApi::OptionsValidator
+
+    # Create multiple folders at once.
+    #
+    # This route is asynchronous for large batches, which returns a job ID
+    # immediately and runs the create folder batch asynchronously. Otherwise,
+    # creates the folders and returns the result synchronously for smaller
+    # inputs. You can force asynchronous behaviour by using the `:force_async`
+    # flag. Use {Client#create_folder_batch_check} to check the job status.
+    #
+    # Note: No errors are returned by this endpoint.
+    #
+    # @param paths [Array] List of paths to be created in the user's Dropbox.
+    #   Duplicate path arguments in the batch are considered only once.
+    # @option options autorename [Boolean] If there's a conflict, have the
+    #   Dropbox server try to autorename the folder to avoid the conflict.
+    #   The default for this field is `false`.
+    # @option options force_async [Boolean] Whether to force the create to
+    #   happen asynchronously. The default for this field is `false`.
+    # @return [String, Array] Either the job id or the list of job statuses.
+    add_endpoint :create_folder_batch do |paths, options = {}|
+      validate_options([
+        :autorename,
+        :force_async
+      ], options)
+      options[:autorename] ||= false
+      options[:force_async] ||= false
+
+      perform_request(options.merge({
+        paths: paths
+      }))
+    end
+  end
+end

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

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+module DropboxApi::Endpoints::Files
+  class CreateFolderBatchCheck < DropboxApi::Endpoints::Rpc
+    Method      = :post
+    Path        = '/2/files/create_folder_batch/check'
+    ResultType  = DropboxApi::Results::CreateFolderBatchResult
+    ErrorType   = DropboxApi::Errors::PollError
+
+    # Returns the status of an asynchronous job for create_folder_batch.
+    # If success, it returns list of result for each entry.
+    #
+    # @param async_job_id [String] Id of the asynchronous job.
+    #   This is the value of a response returned from the method that launched
+    #   the job.
+    # @return [Array] A list of one result for each entry.
+    add_endpoint :create_folder_batch_check do |async_job_id|
+      perform_request({
+        async_job_id: async_job_id
+      })
+    end
+  end
+end

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

@@ -1,7 +1,8 @@
+# frozen_string_literal: true
 module DropboxApi::Endpoints::Files
   class Delete < DropboxApi::Endpoints::Rpc
     Method      = :post
-    Path        = "/2/files/delete".freeze
+    Path        = '/2/files/delete'
     ResultType  = DropboxApi::Metadata::Resource
     ErrorType   = DropboxApi::Errors::DeleteError
 
@@ -25,7 +26,7 @@ module DropboxApi::Endpoints::Files
       validate_options([:parent_rev], options)
 
       perform_request options.merge({
-        :path => path
+        path: path
       })
     end
   end

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

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+module DropboxApi::Endpoints::Files
+  class DeleteBatch < DropboxApi::Endpoints::Rpc
+    Method      = :post
+    Path        = '/2/files/delete_batch'
+    ResultType  = DropboxApi::Results::DeleteBatchResult
+
+    # Delete multiple files/folders at once.
+    #
+    # This route is asynchronous, which returns a job ID immediately and runs
+    # the delete batch asynchronously. Use {Client#delete_batch_check} to check
+    # the job status.
+    #
+    # @param entries [Array] List of entries, each entry is a Hash with these
+    #   fields: `path` (mandatory) & parent_rev (optional).
+    # @return [String, Array] Either the job id or the list of job statuses.
+    add_endpoint :delete_batch do |entries|
+      perform_request({
+        entries: entries
+      })
+    end
+  end
+end

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

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+module DropboxApi::Endpoints::Files
+  class DeleteBatchCheck < DropboxApi::Endpoints::Rpc
+    Method      = :post
+    Path        = '/2/files/delete_batch/check'
+    ResultType  = DropboxApi::Results::DeleteBatchResult
+    ErrorType   = DropboxApi::Errors::PollError
+
+    # Returns the status of an asynchronous job for delete_batch. If success,
+    # it returns list of result for each entry.
+    #
+    # @param async_job_id [String] Id of the asynchronous job.
+    # @return [:in_progress, Array] This could be either the `:in_progress`
+    #   flag or a list of job statuses.
+    add_endpoint :delete_batch_check do |async_job_id|
+      perform_request({
+        async_job_id: async_job_id
+      })
+    end
+  end
+end

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

@@ -1,7 +1,8 @@
+# frozen_string_literal: true
 module DropboxApi::Endpoints::Files
   class Download < DropboxApi::Endpoints::ContentDownload
     Method      = :post
-    Path        = "/2/files/download".freeze
+    Path        = '/2/files/download'
     ResultType  = DropboxApi::Metadata::File
     ErrorType   = DropboxApi::Errors::DownloadError
 
@@ -9,7 +10,7 @@ module DropboxApi::Endpoints::Files
     #
     # @param path [String] The path of the file to download.
     add_endpoint :download do |path, &block|
-      perform_request({:path => path}, &block)
+      perform_request({path: path}, &block)
     end
   end
 end

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

@@ -1,7 +1,8 @@
+# frozen_string_literal: true
 module DropboxApi::Endpoints::Files
   class GetMetadata < DropboxApi::Endpoints::Rpc
     Method      = :post
-    Path        = "/2/files/get_metadata".freeze
+    Path        = '/2/files/get_metadata'
     ResultType  = DropboxApi::Metadata::Resource
     ErrorType   = DropboxApi::Errors::GetMetadataError
 
@@ -34,7 +35,7 @@ module DropboxApi::Endpoints::Files
       ], options)
 
       perform_request(options.merge({
-        :path => path
+        path: path
       }))
     end
   end