dropbox_api 0.1.10 → 0.1.11

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 2801013459cdb9c5a71f72f07e5967cc09452625
-  data.tar.gz: d99d873e573f87879f2b0acb8f215eda78ba5182
+  metadata.gz: 47cd12fc36b2c62e257a717af58a4a2fa11f802c
+  data.tar.gz: c1ae321423d2b7f2494bba5fa9e24870322b0b25
 SHA512:
-  metadata.gz: c968a2f558de87f21e1428786ed34c021ffe092df8975f7904c93013a27a57a36f2f8bb0bc6e291cdaf8d7a025c7cd9b82637308ea49da88e1701b42ec0618f4
-  data.tar.gz: a7659b676c8df3cd23df8679723d2716cd21bfd0280a3f1de6480a8c46fd769bc8d75d8adf7c6f9074dfc34caba3baba14563fe1dd07c9adf02d145872cfad72
+  metadata.gz: 11c9d49a540be98afedb19678fc4e85ac0de227eec0784916ce9279c9b37bba96922593a56096e56d058eb8b862c70684e827d292d60820f1fd5ee37f6f9c2e7
+  data.tar.gz: b75d171a9a4947d22f41efed6917e7e66b25636bf82fa2250b449978c0a0e6cf48868e1161a8292be7a1adbda4a0890b05cccdbb3f92e2a3f24af753b973caec

data/README.md

@@ -116,7 +116,30 @@ result.has_more?
 
 The instance of `Client` we've initialized is the one you'll be using to
 perform API calls. You can check the class' documentation to find
-[all available endpoints](http://jesus.github.io/dropbox_api/DropboxApi/Client.html)
+[all available endpoints](http://jesus.github.io/dropbox_api/DropboxApi/Client.html).
+
+### Large file uploads
+
+If you need to upload files larger than 150MB the default `#upload` endpoint
+won't work. Instead, you need to start a upload session and upload
+the file in small chunks.
+
+To make this easier, the method `upload_by_chunks` will handle this for you,
+example:
+
+```ruby
+client = DropboxApi::Client.new("VofXAX8D...")
+#=> #<DropboxApi::Client ...>
+File.open("large_file.avi") do |f|
+  client.upload_by_chunks "/remote_path.txt", f
+end
+```
+
+Check out the
+[method documentation](http://www.xuuso.com/dropbox_api/DropboxApi/Client.html#upload_by_chunks-instance_method)
+to find out all available options.
+
+
 
 ## Development
 
@@ -161,14 +184,3 @@ command line.
 Any help will be much appreciated. The easiest way to help is to implement one
 or more of the [endpoints that are still pending](http://jesus.github.io/dropbox_api/file.api_coverage.html). To see how the
 endpoints are implemented, check out the `lib/dropbox_api/endpoints` folder.
-
-If you want to help but you're unsure how to get started, please get in touch
-by opening an issue.
-
-Here's the standard way to submit code updates:
-
-1. Fork it ( https://github.com/Jesus/dropbox_api/fork )
-2. Create your feature branch (`git checkout -b my-new-feature`)
-3. Commit your changes (`git commit -am 'Add some feature'`)
-4. Push to the branch (`git push origin my-new-feature`)
-5. Create a new Pull Request

data/RELEASING.md

@@ -0,0 +1,5 @@
+ 1. Bump version in `lib/dropbox_api/version.rb`.
+ 2. Tag a new release in Github, summarize the changes since the last release.
+ 3. Build gem: `gem build dropbox_api.gemspec`.
+ 4. Publish gem: `gem push dropbox_api-[...].gem`.
+ 5. Update documentation.

data/api_coverage.md

@@ -103,6 +103,15 @@ API call | Status
 `/get_current_account` | 🌕
 `/get_space_usage` | 🌕
 
+## File Requests namespace
+
+API call | Status
+--- | :---:
+`/create` | 🌕
+`/get` | 🌑
+`/list` | 🌑
+`/update` | 🌑
+
 
 ## Dropbox Business API
 Unfortunately, none of the Dropbox Business endpoints have been implemented.

data/lib/dropbox_api.rb

@@ -12,7 +12,7 @@ require 'dropbox_api/middleware/stack'
 require 'dropbox_api/metadata/field'
 require 'dropbox_api/metadata/base'
 
-require 'dropbox_api/metadata/symbol'
+require 'dropbox_api/metadata/tag'
 require 'dropbox_api/metadata/access_level'
 require 'dropbox_api/metadata/member_action'
 
@@ -42,14 +42,18 @@ require 'dropbox_api/metadata/deleted'
 require 'dropbox_api/metadata/resource'
 require 'dropbox_api/metadata/shared_folder_policy'
 require 'dropbox_api/metadata/shared_folder'
-require 'dropbox_api/metadata/file_link'
-require 'dropbox_api/metadata/folder_link'
+require 'dropbox_api/metadata/file_link_metadata'
+require 'dropbox_api/metadata/folder_link_metadata'
+require 'dropbox_api/metadata/shared_link_metadata'
 require 'dropbox_api/metadata/shared_link'
 require 'dropbox_api/metadata/space_allocation'
 require 'dropbox_api/metadata/space_usage'
 require 'dropbox_api/metadata/upload_session_cursor'
 require 'dropbox_api/metadata/write_mode'
 require 'dropbox_api/metadata/commit_info'
+require 'dropbox_api/metadata/thumbnail_batch_result_entry'
+require 'dropbox_api/metadata/thumbnail_batch_result_data'
+require 'dropbox_api/metadata/file_request'
 
 require 'dropbox_api/errors/http_error'
 require 'dropbox_api/errors/basic_error'
@@ -93,6 +97,9 @@ require 'dropbox_api/errors/add_file_member_error'
 require 'dropbox_api/errors/add_folder_member_error'
 require 'dropbox_api/errors/too_many_requests_error'
 require 'dropbox_api/errors/get_account_error'
+require 'dropbox_api/errors/thumbnail_batch_error'
+require 'dropbox_api/errors/thumbnail_error'
+require 'dropbox_api/errors/create_file_request_error'
 
 require 'dropbox_api/result_builder'
 require 'dropbox_api/results/base'
@@ -101,6 +108,7 @@ require 'dropbox_api/results/get_copy_reference_result'
 require 'dropbox_api/results/save_copy_reference_result'
 require 'dropbox_api/results/add_file_member_result_list'
 require 'dropbox_api/results/get_temporary_link_result'
+require 'dropbox_api/results/get_thumbnail_batch_result'
 require 'dropbox_api/results/list_folder_result'
 require 'dropbox_api/results/list_revisions_result'
 require 'dropbox_api/results/list_folder_longpoll_result'
@@ -117,13 +125,15 @@ require 'dropbox_api/results/upload_session_start'
 
 require 'dropbox_api/client'
 require 'dropbox_api/connection_builder'
+require 'dropbox_api/options_validator'
 
 require 'dropbox_api/endpoints/base'
 require 'dropbox_api/endpoints/rpc'
+require 'dropbox_api/endpoints/rpc_content'
 require 'dropbox_api/endpoints/rpc_notify'
 require 'dropbox_api/endpoints/content_download'
 require 'dropbox_api/endpoints/content_upload'
-require 'dropbox_api/endpoints/options_validator'
+
 require 'dropbox_api/endpoints/files/copy'
 require 'dropbox_api/endpoints/files/copy_reference_get'
 require 'dropbox_api/endpoints/files/copy_reference_save'
@@ -134,6 +144,7 @@ require 'dropbox_api/endpoints/files/get_metadata'
 require 'dropbox_api/endpoints/files/get_preview'
 require 'dropbox_api/endpoints/files/get_temporary_link'
 require 'dropbox_api/endpoints/files/get_thumbnail'
+require 'dropbox_api/endpoints/files/get_thumbnail_batch'
 require 'dropbox_api/endpoints/files/list_folder'
 require 'dropbox_api/endpoints/files/list_folder_continue'
 require 'dropbox_api/endpoints/files/list_folder_longpoll'
@@ -148,6 +159,7 @@ require 'dropbox_api/endpoints/files/upload'
 require 'dropbox_api/endpoints/files/upload_session_start'
 require 'dropbox_api/endpoints/files/upload_session_append_v2'
 require 'dropbox_api/endpoints/files/upload_session_finish'
+
 require 'dropbox_api/endpoints/sharing/add_file_member'
 require 'dropbox_api/endpoints/sharing/add_folder_member'
 require 'dropbox_api/endpoints/sharing/list_folder_members'
@@ -155,7 +167,14 @@ require 'dropbox_api/endpoints/sharing/share_folder'
 require 'dropbox_api/endpoints/sharing/list_shared_links'
 require 'dropbox_api/endpoints/sharing/create_shared_link_with_settings'
 require 'dropbox_api/endpoints/sharing/unshare_file'
+
 require 'dropbox_api/endpoints/users/get_account'
 require 'dropbox_api/endpoints/users/get_account_batch'
 require 'dropbox_api/endpoints/users/get_current_account'
 require 'dropbox_api/endpoints/users/get_space_usage'
+
+require 'dropbox_api/endpoints/file_requests/create_file_request'
+
+require 'dropbox_api/chunked_uploader'
+
+require 'dropbox_api/endpoints/virtual/upload_by_chunks'

data/lib/dropbox_api/chunked_uploader.rb

@@ -0,0 +1,48 @@
+module DropboxApi
+  class ChunkedUploader
+    include DropboxApi::OptionsValidator
+
+    def initialize(client, path, i_stream, options = {})
+      @chunk_size = options.delete(:chunk_size) || 4 * 1024 * 1024 # 4 MiB
+
+      @client = client
+      @i_stream = i_stream
+
+      init_commit_info(path, options)
+    end
+
+    def start
+      chunk = @i_stream.read @chunk_size
+
+      @cursor = @client.upload_session_start chunk
+    end
+
+    def upload
+      loop do
+        chunk = @i_stream.read @chunk_size
+        break if chunk.nil?
+
+        @client.upload_session_append_v2 @cursor, chunk
+        break if chunk.size < @chunk_size
+      end
+    end
+
+    def finish
+      @client.upload_session_finish @cursor, @commit_info
+    end
+
+    private
+
+    def init_commit_info(path, options)
+      validate_options([
+        :mode,
+        :autorename,
+        :client_modified,
+        :mute
+      ], options)
+
+      options[:path] = path
+      @commit_info = DropboxApi::Metadata::CommitInfo.build_from_options options
+    end
+  end
+end

data/lib/dropbox_api/endpoints/content_upload.rb

@@ -6,19 +6,14 @@ module DropboxApi::Endpoints
       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
+    def build_request(params, body)
       headers = {
         'Dropbox-API-Arg' => JSON.dump(params),
         'Content-Type' => 'application/octet-stream'
       }
-      if body.respond_to?(:length)
-        headers['Content-Length'] = body.length.to_s
-      elsif body.respond_to?(:stat)
-        headers['Content-Length'] = body.stat.size.to_s
-      end
+
+      content_length = get_content_length body
+      headers['Content-Length'] = content_length unless content_length.nil?
 
       return body, headers
     end
@@ -26,5 +21,17 @@ module DropboxApi::Endpoints
     def perform_request(params, content)
       process_response(get_response(params, content))
     end
+
+    private
+
+    def get_content_length(content)
+      if content.respond_to?(:bytesize)
+        content.bytesize.to_s
+      elsif content.respond_to?(:length)
+        content.length.to_s
+      elsif content.respond_to?(:stat)
+        content.stat.size.to_s
+      end
+    end
   end
 end

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

@@ -0,0 +1,21 @@
+module DropboxApi::Endpoints::Files
+  class CreateFileRequest < DropboxApi::Endpoints::Rpc
+    Method      = :post
+    Path        = "/2/file_requests/create".freeze
+    ResultType  = DropboxApi::Metadata::FileRequest
+    ErrorType   = DropboxApi::Errors::CreateFileRequestError
+
+    # Create a file request for a given path.
+    #
+    # @param title [String] The title of the file request. Must not be empty.
+    # @param destination [String] The path of the folder in the Dropbox where
+    #   uploaded files will be sent. For apps with the app folder permission,
+    #   this will be relative to the app folder.
+    add_endpoint :create_file_request do |title, destination|
+      perform_request({
+        title: title,
+        destination: destination
+      })
+    end
+  end
+end

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

@@ -5,7 +5,7 @@ module DropboxApi::Endpoints::Files
     ResultType  = DropboxApi::Metadata::Resource
     ErrorType   = DropboxApi::Errors::GetMetadataError
 
-    include DropboxApi::Endpoints::OptionsValidator
+    include DropboxApi::OptionsValidator
 
     # Returns the metadata for a file or folder.
     #

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

@@ -5,7 +5,7 @@ module DropboxApi::Endpoints::Files
     ResultType  = DropboxApi::Metadata::File
     ErrorType   = DropboxApi::Errors::PreviewError
 
-    include DropboxApi::Endpoints::OptionsValidator
+    include DropboxApi::OptionsValidator
 
     # Get a thumbnail for an image.
     #
@@ -39,11 +39,11 @@ module DropboxApi::Endpoints::Files
     #   end
     # @param path [String] The path to the image file you want to thumbnail.
     # @option options format [:jpeg, :png] The format for the thumbnail image,
-    #   +:jpeg+ (default) or +:png+. For images that are photos, +:jpeg+ should be
+    #   `: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+.
+    #   default is `:jpeg`.
     # @option options size [:w32h32, :w64h64, :w128h128, :w640h480, :w1024h768]
-    #   The size for the thumbnail image. The default is +:w64h64+.
+    #   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

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

@@ -0,0 +1,38 @@
+module DropboxApi::Endpoints::Files
+  class GetThumbnailBatch < DropboxApi::Endpoints::RpcContent
+    Method      = :post
+    Path        = "/2/files/get_thumbnail_batch".freeze
+    ResultType  = DropboxApi::Results::GetThumbnailBatchResult
+    ErrorType   = DropboxApi::Errors::ThumbnailBatchError
+
+    include DropboxApi::OptionsValidator
+
+    # Get a thumbnails for a batch of images.
+    #
+    # @param paths [Array<String>] The paths to the image files you want thumbnails for.
+    # @option options 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 options size [:w32h32, :w64h64, :w128h128, :w640h480, :w1024h768]
+    #   The size for the thumbnail image. The default is `:w64h64`.
+    # @option options mode [:strict, :bestfit, :fitone_bestfit]
+    #   How to resize and crop the image to achieve the desired size. The default
+    #   for this union is strict.
+    add_endpoint :get_thumbnail_batch do |paths, options = {}|
+      validate_options([:format, :size, :mode], options)
+      options[:format] ||= :jpeg
+      options[:size] ||= :w64h64
+      options[:mode] ||= :strict
+
+      perform_request :entries => build_entries_params(paths, options)
+    end
+
+    def build_entries_params(paths, options)
+      paths.map do |path|
+        options.merge({ :path => path })
+      end
+    end
+
+  end
+end

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

@@ -5,7 +5,7 @@ module DropboxApi::Endpoints::Files
     ResultType  = DropboxApi::Results::ListFolderResult
     ErrorType   = DropboxApi::Errors::ListFolderError
 
-    include DropboxApi::Endpoints::OptionsValidator
+    include DropboxApi::OptionsValidator
 
     # Returns the contents of a folder.
     #
@@ -23,15 +23,30 @@ module DropboxApi::Endpoints::Files
         :recursive,
         :include_media_info,
         :include_deleted,
+        :shared_link,
         :include_has_explicit_shared_members
       ], options)
       options[:recursive] ||= false
       options[:include_media_info] ||= false
       options[:include_deleted] ||= false
+      options[:shared_link] = build_shared_link_param(options[:shared_link]) if options[:shared_link]
 
       perform_request options.merge({
         :path => path
       })
     end
+
+    private
+
+    def build_shared_link_param(shared_link_param)
+      case shared_link_param
+      when String, Symbol
+        DropboxApi::Metadata::SharedLink.new shared_link_param
+      when DropboxApi::Metadata::SharedLink
+        shared_link_param
+      else
+        raise ArgumentError, "Invalid `shared_link`: #{shared_link.inspect}"
+      end.to_hash
+    end
   end
 end

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

@@ -5,7 +5,7 @@ module DropboxApi::Endpoints::Files
     ResultType  = DropboxApi::Results::ListFolderGetLatestCursorResult
     ErrorType   = DropboxApi::Errors::ListFolderError
 
-    include DropboxApi::Endpoints::OptionsValidator
+    include DropboxApi::OptionsValidator
 
     # A way to quickly get a cursor for the folder's state. Unlike
     # {DropboxApi::API#list_folder}, this doesn't return any entries. This
@@ -14,17 +14,16 @@ module DropboxApi::Endpoints::Files
     # Dropbox.
     #
     # @option options path [String] The path to the folder you want to read.
-    # @option options recursive [Boolean] If +true+, the list folder operation
+    # @option options 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 options include_media_info [Boolean] If +true+,
-    #   +FileMetadata.media_info+ is set for photo and video. The default for
-    #   this field is +false+.
-    # @option options include_deleted [Boolean] If +true+,
-    #   {DropboxApi::Metadata::DeletedMetadata} will be returned for deleted
+    #   `false`.
+    # @option options include_media_info [Boolean] If `true`, `media_info` is
+    #   set for photo and video. The default for this field is `false`.
+    # @option options include_deleted [Boolean] If `true`,
+    #   {DropboxApi::Metadata::Deleted} will be returned for deleted
     #   file or folder, otherwise {DropboxApi::Errors::LookupError} will be
-    #   returned. The default for this field is +false+.
+    #   returned. The default for this field is `false`.
     add_endpoint :list_folder_get_latest_cursor do |options = {}|
       validate_options([
         :path,

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

@@ -5,7 +5,7 @@ module DropboxApi::Endpoints::Files
     ResultType  = DropboxApi::Results::ListFolderLongpollResult
     ErrorType   = DropboxApi::Errors::ListFolderLongpollError
 
-    include DropboxApi::Endpoints::OptionsValidator
+    include DropboxApi::OptionsValidator
 
     # A longpoll endpoint to wait for changes on an account. In conjunction
     # with list_folder, this call gives you a low-latency way to monitor an