dropbox_api 0.1.10 → 0.1.11

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

@@ -5,7 +5,7 @@ module DropboxApi::Endpoints::Files
     ResultType  = DropboxApi::Results::ListRevisionsResult
     ErrorType   = DropboxApi::Errors::ListRevisionsError
 
-    include DropboxApi::Endpoints::OptionsValidator
+    include DropboxApi::OptionsValidator
 
     # Return revisions of a file
     #

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

@@ -5,7 +5,7 @@ module DropboxApi::Endpoints::Files
     ResultType  = DropboxApi::Metadata::Resource
     ErrorType   = DropboxApi::Errors::RelocationError
 
-    include DropboxApi::Endpoints::OptionsValidator
+    include DropboxApi::OptionsValidator
 
     # Move a file or folder to a different location in the user's Dropbox.
     #
@@ -15,7 +15,7 @@ module DropboxApi::Endpoints::Files
     # @param to [String] Path in the user's Dropbox that is the destination.
     # @option options autorename [Boolean] If there's a conflict, have the
     #   Dropbox server try to autorename the file to avoid the conflict. The
-    #   default for this field is +false+.
+    #   default for this field is `false`.
     add_endpoint :move do |from, to, options = {}|
       # We're not implementing support for the `allow_shared_folder` option
       # because according to Dropbox's documentation: "This field is always

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

@@ -5,7 +5,7 @@ module DropboxApi::Endpoints::Files
     ResultType  = DropboxApi::Results::SaveUrlJobStatus
     ErrorType   = DropboxApi::Errors::PollError
 
-    # Check the status of a +save_url+ job.
+    # Check the status of a `save_url` job.
     #
     # @param job_id [String] Id of the asynchronous job. This is the value of
     #   a response returned from the method that launched the job.

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

@@ -5,7 +5,7 @@ module DropboxApi::Endpoints::Files
     ResultType  = DropboxApi::Results::SearchResult
     ErrorType   = DropboxApi::Errors::SearchError
 
-    include DropboxApi::Endpoints::OptionsValidator
+    include DropboxApi::OptionsValidator
 
     # Searches for files and folders.
     #

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

@@ -5,12 +5,13 @@ module DropboxApi::Endpoints::Files
     ResultType  = DropboxApi::Metadata::File
     ErrorType   = DropboxApi::Errors::UploadError
 
-    include DropboxApi::Endpoints::OptionsValidator
+    include DropboxApi::OptionsValidator
 
     # Creates a new file.
     #
-    # Do not use this to upload a file larger than 150 MB. Instead, create an
-    # upload session with #upload_session_start().
+    # Do not use this to upload a file larger than 150 MB.
+    #
+    # For larger files you can use {#upload_by_chunks}.
     #
     # @example
     #   client = DropboxApi::Client.new
@@ -27,18 +28,23 @@ module DropboxApi::Endpoints::Files
     #   #=> #<DropboxApi::Metadata::File: @name="file (1).txt" ...>
     # @param path [String] Path in the user's Dropbox to save the file.
     # @param content The contents of the file that will be uploaded. This
-    #   could be the result of the +IO::read+ method.
+    #   could be the result of the `IO::read` method.
     # @option options mode [DropboxApi::Metadata::WriteMode] Selects what to
-    #   do if the file already exists. The default is +add+.
+    #   do if the file already exists. The default is `add`.
     # @option options autorename [Boolean] If there's a conflict, as determined
-    #   by +mode+, have the Dropbox server try to autorename the file to avoid
-    #   conflict. The default for this field is +false+.
+    #   by `mode`, have the Dropbox server try to autorename the file to avoid
+    #   conflict. The default for this field is `false`.
     # @option options client_modified [DateTime] The value to store as the
-    #   +client_modified+ timestamp. Dropbox automatically records the time at
+    #   `client_modified` timestamp. Dropbox automatically records the time at
     #   which the file was written to the Dropbox servers. It can also record
     #   an additional timestamp, provided by Dropbox desktop clients, mobile
     #   clients, and API apps of when the file was actually created or
     #   modified.
+    # @option options mute [Boolean] Normally, users are made aware of any
+    #   file modifications in their Dropbox account via notifications in the
+    #   client software. If `true`, this tells the clients that this
+    #   modification shouldn't result in a user notification. The default for
+    #   this field is `false`.
     # @see DropboxApi::Metadata::WriteMode
     add_endpoint :upload do |path, content, options = {}|
       validate_options([
@@ -48,25 +54,9 @@ module DropboxApi::Endpoints::Files
         :mute
       ], options)
 
-      options[:mode] = build_write_mode_param(options[:mode]) if options[:mode]
-      options[:client_modified] = options[:client_modified].utc.strftime("%FT%TZ") if options[:client_modified]
-
-      perform_request(options.merge({
-        :path => path
-      }), content)
-    end
-
-    private
-
-    def build_write_mode_param(write_mode)
-      case write_mode
-      when String, Symbol
-        DropboxApi::Metadata::WriteMode.new write_mode
-      when DropboxApi::Metadata::WriteMode
-        write_mode
-      else
-        raise ArgumentError, "Invalid write mode: #{write_mode.inspect}"
-      end.to_hash
+      options[:path] = path
+      commit_info = DropboxApi::Metadata::CommitInfo.build_from_options options
+      perform_request(commit_info.to_hash, content)
     end
   end
 end

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

@@ -5,13 +5,15 @@ module DropboxApi::Endpoints::Files
     ResultType  = DropboxApi::Results::VoidResult
     ErrorType   = DropboxApi::Errors::UploadSessionLookupError
 
-    include DropboxApi::Endpoints::OptionsValidator
+    include DropboxApi::OptionsValidator
 
     # Append more data to an upload session.
     #
-    # When the parameter +close+ is set, this call will close the session.
+    # When the parameter `close` is set, this call will close the session.
     #
-    # A single request should not upload more than 150 MB of file contents.
+    # A single request should not upload more than 150 MB.
+    #
+    # The maximum size of a file one can upload to an upload session is 350 GB.
     #
     # Calling this method may update the cursor received. In particular, the
     # offset variable will be increased to match the new position. This allows
@@ -28,10 +30,10 @@ module DropboxApi::Endpoints::Files
     # @param cursor [DropboxApi::Metadata::UploadSessionCursor] Contains the
     #   upload session ID and the offset. This cursor will have its offset
     #   updated after a successful call.
-    # @option options close [Boolean] If +true+, the current session will be
+    # @option options close [Boolean] If `true`, the current session will be
     #   closed, at which point you won't be able to call
     #   {Client#upload_session_append_v2} anymore with the current session.
-    #   The default for this field is +false+.
+    #   The default for this field is `false`.
     # @see UploadSessionCursor
     add_endpoint :upload_session_append_v2 do |cursor, content, options = {}|
       validate_options([

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

@@ -5,17 +5,19 @@ module DropboxApi::Endpoints::Files
     ResultType  = DropboxApi::Metadata::File
     ErrorType   = DropboxApi::Errors::UploadSessionFinishError
 
-    include DropboxApi::Endpoints::OptionsValidator
+    include DropboxApi::OptionsValidator
 
     # Finish an upload session and save the uploaded data to the given file
     # path.
     #
-    # A single request should not upload more than 150 MB of file contents.
+    # A single request should not upload more than 150 MB.
+    #
+    # The maximum size of a file one can upload to an upload session is 350 GB.
     #
     # @param cursor [DropboxApi::Metadata::UploadSessionCursor] Contains the
     #   upload session ID and the offset.
     # @param commit [DropboxApi::Metadata::CommitInfo] Contains the path and
-    # other optional modifiers for the commit.
+    #   other optional modifiers for the commit.
     add_endpoint :upload_session_finish do |cursor, commit, content = nil|
       perform_request({
         :cursor => cursor.to_hash,

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

@@ -5,7 +5,7 @@ module DropboxApi::Endpoints::Files
     ResultType  = DropboxApi::Results::UploadSessionStart
     ErrorType   = nil
 
-    include DropboxApi::Endpoints::OptionsValidator
+    include DropboxApi::OptionsValidator
 
     # Upload sessions allow you to upload a single file in one or more
     # requests, for example where the size of the file is greater than 150 MB.
@@ -16,10 +16,10 @@ module DropboxApi::Endpoints::Files
     #
     # A single request should not upload more than 150 MB of file contents.
     #
-    # @option options close [Boolean] If +true+, the current session will be
+    # @option options close [Boolean] If `true`, the current session will be
     #   closed, at which point you won't be able to call
     #   {Client#upload_session_append_v2} anymore with the current session.
-    #   The default for this field is +false+.
+    #   The default for this field is `false`.
     # @return [DropboxApi::Metadata::UploadSessionCursor] The session cursor
     #   that you can use to continue the upload afterwards.
     add_endpoint :upload_session_start do |content, options = {}|

data/lib/dropbox_api/endpoints/rpc_content.rb

@@ -0,0 +1,9 @@
+module DropboxApi::Endpoints
+  class RpcContent < DropboxApi::Endpoints::Rpc
+    def initialize(builder)
+      @connection = builder.build("https://content.dropboxapi.com") do |c|
+        c.response :decode_result
+      end
+    end
+  end
+end

data/lib/dropbox_api/endpoints/sharing/add_file_member.rb

@@ -5,28 +5,28 @@ module DropboxApi::Endpoints::Sharing
     ResultType  = DropboxApi::Results::AddFileMemberResultList
     ErrorType   = DropboxApi::Errors::AddFileMemberError
 
-    include DropboxApi::Endpoints::OptionsValidator
+    include DropboxApi::OptionsValidator
 
     # Adds specified members to a file.
     #
-    # The +members+ parameter can be an +Array+ or a single member element. Each
-    # element is represented by either a +String+ or a {Metadata::Member}
+    # The `members` parameter can be an `Array` or a single member element. Each
+    # element is represented by either a `String` or a {Metadata::Member}
     # object. You can identify a member using his email or a Dropbox ID.
     #
     # @param file [String] File to which to add members. It can be a path or
-    #   an ID such as +id:3kmLmQFnf1AAAAAAAAAAAw+.
+    #   an ID such as `id:3kmLmQFnf1AAAAAAAAAAAw`.
     # @param members Members to add. Note
     #   that even if an email address is given, this may result in a user
     #   being directy added to the membership if that email is the user's
     #   main account email.
     # @option options quiet [Boolean] Whether added members should be notified
     #   via email and device notifications of their invite. The default for
-    #   this field is +false+.
+    #   this field is `false`.
     # @option options custom_message [String] Message to send to added members
     #   in their invitation. This field is optional.
     # @option options access_level [AccessLevel] AccessLevel union object,
     #   describing what access level we want to give new members. The default
-    #   for this is +:viewer+.
+    #   for this is `:viewer`.
     # @option options add_message_as_comment [String] Optional message to
     #   display to added members in their invitation. This field is optional.
     # @see DropboxApi::Metadata::Member

data/lib/dropbox_api/endpoints/sharing/add_folder_member.rb

@@ -5,23 +5,23 @@ module DropboxApi::Endpoints::Sharing
     ResultType  = DropboxApi::Results::VoidResult
     ErrorType   = DropboxApi::Errors::AddFolderMemberError
 
-    include DropboxApi::Endpoints::OptionsValidator
+    include DropboxApi::OptionsValidator
 
     # Allows an owner or editor (if the ACL update policy allows) of a shared
     # folder to add another member.
     #
     # For the new member to get access to all the functionality for this folder,
-    # you will need to call +mount_folder+ on their behalf.
+    # you will need to call `mount_folder` on their behalf.
     #
     # Apps must have full Dropbox access to use this endpoint.
     #
-    # The +members+ parameter can be an +Array+ or a single member element.
-    # Each element is represented by either a +String+ or a
+    # The `members` parameter can be an `Array` or a single member element.
+    # Each element is represented by either a `String` or a
     # {Metadata::AddMember} object. This parameter can be just a string with
     # an email.
     #
     # You can also build a {Metadata::AddMember} object and use it in the
-    # +members+ parameter, this allows custom  options for each member.
+    # `members` parameter, this allows custom  options for each member.
     #
     # @example
     #   client = DropboxApi::Client.new

data/lib/dropbox_api/endpoints/sharing/create_shared_link_with_settings.rb

@@ -2,7 +2,7 @@ module DropboxApi::Endpoints::Sharing
   class CreateSharedLinkWithSettings < DropboxApi::Endpoints::Rpc
     Method      = :post
     Path        = "/2/sharing/create_shared_link_with_settings".freeze
-    ResultType  = DropboxApi::Metadata::SharedLink
+    ResultType  = DropboxApi::Metadata::SharedLinkMetadata
     ErrorType   = DropboxApi::Errors::CreateSharedLinkWithSettingsError
 
     # Create a shared link with custom settings. If no settings are given then
@@ -13,7 +13,7 @@ module DropboxApi::Endpoints::Sharing
     # @param path [String] The path to be shared by the shared link.
     # @param settings [SharedLinkSettings] The requested settings for the newly
     #   created shared link This field is optional.
-    # @return [DropboxApi::Metadata::SharedLink]
+    # @return [DropboxApi::Metadata::SharedLinkMetadata]
     add_endpoint :create_shared_link_with_settings do |path, settings = {}|
       # NOTE: This endpoint accepts an additional option `settings` which
       #       hasn't been implemented.

data/lib/dropbox_api/endpoints/sharing/list_folder_members.rb

@@ -5,7 +5,7 @@ module DropboxApi::Endpoints::Sharing
     ResultType  = DropboxApi::Results::SharedFolderMembers
     ErrorType   = DropboxApi::Errors::SharedFolderAccessError
 
-    include DropboxApi::Endpoints::OptionsValidator
+    include DropboxApi::OptionsValidator
 
     # Returns shared folder membership by its folder ID.
     #

data/lib/dropbox_api/endpoints/sharing/list_shared_links.rb

@@ -5,7 +5,7 @@ module DropboxApi::Endpoints::Sharing
     ResultType  = DropboxApi::Results::ListSharedLinksResult
     ErrorType   = DropboxApi::Errors::ListSharedLinksError
 
-    include DropboxApi::Endpoints::OptionsValidator
+    include DropboxApi::OptionsValidator
 
     # List shared links of this user.
     #

data/lib/dropbox_api/endpoints/sharing/share_folder.rb

@@ -5,7 +5,7 @@ module DropboxApi::Endpoints::Sharing
     ResultType  = DropboxApi::Results::ShareFolderLaunch
     ErrorType   = DropboxApi::Errors::ShareFolderError
 
-    include DropboxApi::Endpoints::OptionsValidator
+    include DropboxApi::OptionsValidator
 
     # Share a folder with collaborators.
     #

data/lib/dropbox_api/endpoints/virtual/upload_by_chunks.rb

@@ -0,0 +1,49 @@
+module DropboxApi
+  class Client
+    # Creates a new file using the *upload session* endpoints. You can use
+    # this method to upload files larger than 150 MB.
+    #
+    # @example
+    #   client = DropboxApi::Client.new
+    #   File.open "large file.avi" do |file|
+    #     client.upload "/large file.avi", file
+    #     #=> #<DropboxApi::Metadata::File: @name="large file.avi" ...>
+    #   end
+    # @example
+    #   client = DropboxApi::Client.new
+    #   client.upload "/file.txt", "File contents...", :mode => :add
+    #   #=> #<DropboxApi::Metadata::File: @name="file (1).txt" ...>
+    # @param path [String] Path in the user's Dropbox to save the file.
+    # @param content The contents of the file that will be uploaded. This
+    #   could be the result of the `IO::read` method.
+    # @option options mode [DropboxApi::Metadata::WriteMode] Selects what to
+    #   do if the file already exists. The default is `add`.
+    # @option options autorename [Boolean] If there's a conflict, as determined
+    #   by `mode`, have the Dropbox server try to autorename the file to avoid
+    #   conflict. The default for this field is `false`.
+    # @option options client_modified [DateTime] The value to store as the
+    #   `client_modified` timestamp. Dropbox automatically records the time at
+    #   which the file was written to the Dropbox servers. It can also record
+    #   an additional timestamp, provided by Dropbox desktop clients, mobile
+    #   clients, and API apps of when the file was actually created or
+    #   modified.
+    # @option options mute [Boolean] Normally, users are made aware of any
+    #   file modifications in their Dropbox account via notifications in the
+    #   client software. If `true`, this tells the clients that this
+    #   modification shouldn't result in a user notification. The default for
+    #   this field is `false`.
+    # @option options chunk_size [Numeric] The size of each upload chunk. It
+    #   defaults to 4 MiB.
+    # @see DropboxApi::Metadata::WriteMode
+    #
+    # @!group virtual
+    def upload_by_chunks(path, content, options = {})
+      content = StringIO.new(content) if content.is_a?(String)
+
+      uploader = DropboxApi::ChunkedUploader.new(self, path, content, options)
+      uploader.start
+      uploader.upload
+      uploader.finish
+    end
+  end
+end

data/lib/dropbox_api/errors/basic_error.rb

@@ -34,6 +34,7 @@ module DropboxApi::Errors
   class CantNestSharedFolderError < BasicError; end
   class CantShareOutsideTeamError < BasicError; end
   class ContainsSharedFolderError < BasicError; end
+  class ConversionError < BasicError; end
   class CursorClosedError < BasicError; end
   class CursorNotClosedError < BasicError; end
   class DisallowedNameError < BasicError; end
@@ -90,5 +91,6 @@ module DropboxApi::Errors
   class UnmountedError < BasicError; end
   class UnsupportedContentError < BasicError; end
   class UnsupportedExtensionError < BasicError; end
+  class UnsupportedImageError < BasicError; end
   class UnverifiedDropboxId < BasicError; end
 end

data/lib/dropbox_api/errors/create_file_request_error.rb

@@ -0,0 +1,6 @@
+module DropboxApi::Errors
+  class CreateFileRequestError < BasicError
+    ErrorSubtypes = {
+    }.freeze
+  end
+end

data/lib/dropbox_api/errors/thumbnail_batch_error.rb

@@ -0,0 +1,7 @@
+module DropboxApi::Errors
+  class ThumbnailBatchError < BasicError
+    ErrorSubtypes = {
+      :too_many_files => TooManyFilesError
+    }.freeze
+  end
+end

data/lib/dropbox_api/errors/thumbnail_error.rb

@@ -0,0 +1,10 @@
+module DropboxApi::Errors
+  class ThumbnailError < BasicError
+    ErrorSubtypes = {
+      :path => LookupError,
+      :unsupported_extension => UnsupportedExtensionError,
+      :unsupported_image => UnsupportedImageError,
+      :conversion_error => ConversionError
+    }.freeze
+  end
+end

data/lib/dropbox_api/metadata/access_level.rb

@@ -1,9 +1,12 @@
 module DropboxApi::Metadata
   # Example of a serialized {AccessLevel} object:
-  #   {
-  #     ".tag": "viewer"
-  #   }
-  class AccessLevel < DropboxApi::Metadata::Symbol
+  #
+  # ```json
+  # {
+  #   ".tag": "viewer"
+  # }
+  # ```
+  class AccessLevel < DropboxApi::Metadata::Tag
     VALID_ACCESS_LEVELS = [
       :owner,
       :editor,

data/lib/dropbox_api/metadata/add_file_member_result.rb

@@ -1,17 +1,20 @@
 module DropboxApi::Metadata
   # Example of a {AddFileMemberResult}:
-  #   {
-  #     "member":{
-  #       ".tag": "email",
-  #       "email": "somebody@test.com"
-  #     },
-  #     "result": {
-  #       ".tag": "success",
-  #       "success": {
-  #         ".tag": "viewer"
-  #       }
+  #
+  # ```json
+  # {
+  #   "member":{
+  #     ".tag": "email",
+  #     "email": "somebody@test.com"
+  #   },
+  #   "result": {
+  #     ".tag": "success",
+  #     "success": {
+  #       ".tag": "viewer"
   #     }
   #   }
+  # }
+  # ```
   class AddFileMemberResult < Base
     field :member, DropboxApi::Metadata::Member
     field :result, DropboxApi::Metadata::FileMemberAction