dropbox_api 0.1.3 → 0.1.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: fd04df06e2b79e0a102c34ada12761d414d92484
-  data.tar.gz: 2d71c761e4b9c05e0207633d2b0d984f434ffd4e
+  metadata.gz: 71bc2fe09bb0680e07ef7267a199993f8aa93cc5
+  data.tar.gz: 31df4bc163d59790a448e37cb695617fe168d99d
 SHA512:
-  metadata.gz: 7cfaf692c3c6625378951ddd42108e12d667477fb9468b5d1648e0891b7cb45cedd93fb7a06dd5e018625baf1955c330824dba14604569e323ceb0ea3aae5ba2
-  data.tar.gz: 26d60eb6ddfb03c8e3c8b3219d0b1698c4360215b5edbdb39d096f8c7adffa131dbf1e470cb8be911ca58e3322b143d18939e360017e4f4eda6e1a9e170e5331
+  metadata.gz: e05027a2944af74b33f56a1a7a6a124459fd0a1c604ebd4ebaa5db3403eed396247aeea1344c69f8828b1172eac17ee32a3fcce60f3a8f280d30d02d4c95e1fa
+  data.tar.gz: 99c5f3c37144305dc4a689902e7c61468ef2991ddf4713c4354e4dee7076a83ea87434a5cc6d19122e2de6c0f21bb3a4b96144b60cb94c919a0d3ae7c895bc25

data/TODO.md

@@ -1,15 +1,9 @@
-# Week
+# Upcoming
 
-TOKEN: VofXAX8DO1sAAAAAAAADiXbd__inZjFI0OTsK9ao8AAKmshXqdbnjOnXz7XylBbf
+TOKEN: VofXAX8DO1sAAAAAAAAEEyqrmzbYmFVaDQKj48yVUfhyhfOomXiG8emqP1xQGRnJ
 
-- add_file_member
-- Refactor MemberActionCollection
-- Implement DropboxApi::Metadata::Base#to_hash
-
-- get_file_metadata
-- get_folder_metadata
-- get_shared_link_file
-- get_shared_link_metadata
+- Create website with comparison with other libraries.
+- Implement PermissionDeniedReason
 - list_shared_folders
 - continue_list_shared_folders
 - share_folder
@@ -18,8 +12,12 @@ TOKEN: VofXAX8DO1sAAAAAAAADiXbd__inZjFI0OTsK9ao8AAKmshXqdbnjOnXz7XylBbf
 - list_folder_members
 - relinquish_folder_membership
 - transfer_folder
+- get_file_metadata
+- get_folder_metadata
+- get_shared_link_file
+- get_shared_link_metadata
 
-# Short term goals
+# Mid-term goals
 
 - Remove dependency on faraday.
 - Complete full [API coverage](api_coverage.md).
@@ -35,4 +33,6 @@ TOKEN: VofXAX8DO1sAAAAAAAADiXbd__inZjFI0OTsK9ao8AAKmshXqdbnjOnXz7XylBbf
 
 1. Bump version in `version.rb`.
 2. Create tag and write release notes in Github.com.
-3. 
+3. `git fetch`
+4. `gem build dropbox_api.gemspec`
+5. `gem push dropbox_api-version.gem`

data/api_coverage.md

@@ -36,11 +36,11 @@ API call | Status
 `/properties/template/get` | 🌑
 `/properties/template/list` | 🌑
 `/properties/update` | 🌑
-`/restore` | 🌑
-`/save_url` | 🌑
-`/save_url/check_job_status` | 🌑
-`/search` | 🌕
-`/upload` | 🌔
+`/restore` | 🌕
+`/save_url` | 🌕
+`/save_url/check_job_status` | 🌕
+`/search` | 🌔
+`/upload` | 🌕
 `/upload_session/append` | 🌑
 `/upload_session/append_v2` | 🌑
 `/upload_session/finish` | 🌑
@@ -51,7 +51,7 @@ API call | Status
 ## Sharing namespace
 API call | Status
 --- | :---:
-`/add_file_member` | 🌔
+`/add_file_member` | 🌕
 `/add_folder_member` | 🌕
 `/change_file_member_access` | 🌑
 `/check_job_status` | 🌑

data/lib/dropbox_api.rb

@@ -11,18 +11,21 @@ require 'dropbox_api/middleware/decode_result'
 require 'dropbox_api/metadata/field'
 require 'dropbox_api/metadata/base'
 
+require 'dropbox_api/metadata/symbol'
 require 'dropbox_api/metadata/access_level'
+require 'dropbox_api/metadata/member_action'
+
 require 'dropbox_api/metadata/member'
 require 'dropbox_api/metadata/add_member'
 require 'dropbox_api/metadata/name'
 require 'dropbox_api/metadata/file_member_action'
+require 'dropbox_api/metadata/member_action_list'
 require 'dropbox_api/metadata/member_permission'
 require 'dropbox_api/metadata/member_permission_list'
 require 'dropbox_api/metadata/add_file_member_result'
 require 'dropbox_api/metadata/parent_folder_access_info'
 require 'dropbox_api/metadata/basic_account'
 require 'dropbox_api/metadata/link_permissions'
-require 'dropbox_api/metadata/member_action_collection'
 require 'dropbox_api/metadata/team'
 require 'dropbox_api/metadata/team_member_info'
 require 'dropbox_api/metadata/file'
@@ -37,6 +40,7 @@ require 'dropbox_api/metadata/folder_link'
 require 'dropbox_api/metadata/shared_link'
 require 'dropbox_api/metadata/space_allocation'
 require 'dropbox_api/metadata/space_usage'
+require 'dropbox_api/metadata/write_mode'
 
 require 'dropbox_api/errors/http_error'
 require 'dropbox_api/errors/basic_error'
@@ -46,6 +50,7 @@ require 'dropbox_api/errors/write_conflict_error'
 require 'dropbox_api/errors/write_error'
 require 'dropbox_api/errors/relocation_error'
 require 'dropbox_api/errors/restore_error'
+require 'dropbox_api/errors/save_url_error'
 require 'dropbox_api/errors/search_error'
 require 'dropbox_api/errors/settings_error'
 require 'dropbox_api/errors/share_path_error'
@@ -55,6 +60,7 @@ require 'dropbox_api/errors/create_shared_link_with_settings_error'
 require 'dropbox_api/errors/delete_error'
 require 'dropbox_api/errors/download_error'
 require 'dropbox_api/errors/sharing_file_access_error'
+require 'dropbox_api/errors/sharing_user_error'
 require 'dropbox_api/errors/file_member_action_error'
 require 'dropbox_api/errors/get_metadata_error'
 require 'dropbox_api/errors/list_folder_error'
@@ -67,6 +73,7 @@ require 'dropbox_api/errors/add_member_selector_error'
 require 'dropbox_api/errors/shared_folder_access_error'
 require 'dropbox_api/errors/upload_write_failed_error'
 require 'dropbox_api/errors/upload_error'
+require 'dropbox_api/errors/poll_error'
 require 'dropbox_api/errors/add_file_member_error'
 require 'dropbox_api/errors/add_folder_member_error'
 require 'dropbox_api/errors/too_many_requests_error'
@@ -82,6 +89,8 @@ require 'dropbox_api/results/list_revisions_result'
 require 'dropbox_api/results/list_folder_longpoll_result'
 require 'dropbox_api/results/list_folder_get_latest_cursor_result'
 require 'dropbox_api/results/list_shared_links_result'
+require 'dropbox_api/results/save_url_result'
+require 'dropbox_api/results/save_url_job_status'
 require 'dropbox_api/results/search/match'
 require 'dropbox_api/results/search_result'
 require 'dropbox_api/results/share_folder_launch'
@@ -112,6 +121,8 @@ require 'dropbox_api/endpoints/files/list_folder_get_latest_cursor'
 require 'dropbox_api/endpoints/files/list_revisions'
 require 'dropbox_api/endpoints/files/move'
 require 'dropbox_api/endpoints/files/restore'
+require 'dropbox_api/endpoints/files/save_url'
+require 'dropbox_api/endpoints/files/save_url_check_job_status'
 require 'dropbox_api/endpoints/files/search'
 require 'dropbox_api/endpoints/files/upload'
 require 'dropbox_api/endpoints/sharing/add_file_member'

data/lib/dropbox_api/authenticator.rb

@@ -6,8 +6,8 @@ module DropboxApi
 
     def initialize(client_id, client_secret)
       @auth_code = 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'
+        :authorize_url => 'https://www.dropbox.com/oauth2/authorize',
+        :token_url => 'https://api.dropboxapi.com/oauth2/token'
       }).auth_code
     end
 

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

@@ -5,15 +5,27 @@ module DropboxApi::Endpoints::Files
     ResultType  = DropboxApi::Metadata::Resource
     ErrorType   = DropboxApi::Errors::RelocationError
 
-    # @method move(from, to)
+    include DropboxApi::Endpoints::OptionsValidator
+
+    # @method move(from, to, options)
     # Move 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 moved.
     #
     # @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.
-    add_endpoint :move do |from, to|
-      perform_request({
+    # @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+.
+    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
+      # true for move".
+      validate_options([
+        :autorename
+      ], options)
+
+      perform_request options.merge({
         :from_path => from,
         :to_path => to
       })

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

@@ -0,0 +1,23 @@
+module DropboxApi::Endpoints::Files
+  class SaveUrl < DropboxApi::Endpoints::Rpc
+    Method      = :post
+    Path        = "/2/files/save_url".freeze
+    ResultType  = DropboxApi::Results::SaveUrlResult
+    ErrorType   = DropboxApi::Errors::SaveUrlError
+
+    # @method save_url(path, url)
+    # Save a specified URL into a file in user's Dropbox. If the given path
+    # already exists, the file will be renamed to avoid the conflict (e.g.
+    # myfile (1).txt).
+    #
+    # @param path [String] The path in Dropbox where the URL will be saved to.
+    # @param url [String] The URL to be saved.
+    # @return Either the saved file or a reference to the async job.
+    add_endpoint :save_url do |path, url|
+      perform_request({
+        :path => path,
+        :url => url
+      })
+    end
+  end
+end

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

@@ -0,0 +1,20 @@
+module DropboxApi::Endpoints::Files
+  class SaveUrlCheckJobStatus < DropboxApi::Endpoints::Rpc
+    Method      = :post
+    Path        = "/2/files/save_url/check_job_status".freeze
+    ResultType  = DropboxApi::Results::SaveUrlJobStatus
+    ErrorType   = DropboxApi::Errors::PollError
+
+    # @method save_url_check_job_status(job_id)
+    # 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.
+    # @return The current status of the job.
+    add_endpoint :save_url_check_job_status do |job_id|
+      perform_request({
+        :async_job_id => job_id
+      })
+    end
+  end
+end

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

@@ -5,6 +5,8 @@ module DropboxApi::Endpoints::Files
     ResultType  = DropboxApi::Metadata::File
     ErrorType   = DropboxApi::Errors::UploadError
 
+    include DropboxApi::Endpoints::OptionsValidator
+
     # @method upload(path, content, options = {})
     # Creates a new file.
     #
@@ -20,19 +22,52 @@ module DropboxApi::Endpoints::Files
     #   client = DropboxApi::Client.new
     #   client.upload "/file.txt", "Contents of a plain text file."
     #   #=> #<DropboxApi::Metadata::File: @name="file.txt" ...>
+    # @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 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 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 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.
+    # @see DropboxApi::Metadata::WriteMode
     add_endpoint :upload do |path, content, options = {}|
-      perform_request({:path => path}, content)
+      validate_options([
+        :mode,
+        :autorename,
+        :client_modified,
+        :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
     end
   end
 end

data/lib/dropbox_api/endpoints/options_validator.rb

@@ -1,5 +1,10 @@
 module DropboxApi::Endpoints
   module OptionsValidator
+    # Takes in a list of valid option keys and a hash of options. If one of the
+    # keys in the hash is invalid an ArgumentError will be raised.
+    #
+    # @param valid_option_keys List of valid keys for the options hash.
+    # @param options [Hash] Options hash.
     def validate_options(valid_option_keys, options)
       options.keys.each do |key|
         unless valid_option_keys.include? key.to_sym

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

@@ -10,15 +10,16 @@ module DropboxApi::Endpoints::Sharing
     # @method add_file_member(file, members, options = {})
     # Adds specified members to a file.
     #
-    # The +members+ parameter must be an Array. Each item in the array could
-    # be either a String or a {Metadata::Member} object, which allows more
-    # advanced options.
+    # 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+.
-    # @param members [Array<Member,String>] Members to add. Note that even
-    #   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.
+    # @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+.
@@ -29,8 +30,9 @@ module DropboxApi::Endpoints::Sharing
     #   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
     add_endpoint :add_file_member do |file, members, options = {}|
-      validate_options([:quiet, :custom_message], options)
+      validate_options([:quiet, :custom_message, :access_level, :add_message_as_comment], options)
       options[:quiet] ||= false
       options[:custom_message] ||= nil
       options[:access_level] ||= :viewer
@@ -45,10 +47,10 @@ module DropboxApi::Endpoints::Sharing
     private
 
     def build_members_param(members)
-      members.map do |member|
+      Array(members).map do |member|
         case member
         when String
-          DropboxApi::Metadata::Member.build_from_email_or_dropbox_id member
+          DropboxApi::Metadata::Member.new member
         when DropboxApi::Metadata::Member
           member
         else

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

@@ -12,13 +12,21 @@ module DropboxApi::Endpoints::Sharing
     # 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 must be an Array. Each item in the array could
-    # be either a String or a {Metadata::AddMember} object.
+    # 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.
+    #
+    # @example
+    #   client = DropboxApi::Client.new
+    #   client.add_folder_member "1363389221", "somebody@test.com"
     # @param folder_id [String] The ID for the shared folder.
     # @param members [Array<AddMember,String>] The intended list of members to
     #   add. Added members will receive invites to join the shared folder.
@@ -27,14 +35,14 @@ module DropboxApi::Endpoints::Sharing
     #   this field is False.
     # @option options custom_message [String] Optional message to display to
     #   added members in their invitation. This field is optional.
-    # @see DropboxApi::Metadata::Member
+    # @see DropboxApi::Metadata::AddMember
     add_endpoint :add_folder_member do |folder_id, members, options = {}|
       validate_options([:quiet, :custom_message], options)
       options[:quiet] ||= false
       options[:custom_message] ||= nil
 
       perform_request options.merge({
-        :shared_folder_id => folder_id,
+        :shared_folder_id => folder_id.to_s,
         :members => build_members_param(members)
       })
     end
@@ -42,7 +50,7 @@ module DropboxApi::Endpoints::Sharing
     private
 
     def build_members_param(members)
-      members.map do |member|
+      Array(members).map do |member|
         case member
         when String
           DropboxApi::Metadata::AddMember.build_from_string member

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

@@ -22,19 +22,18 @@ module DropboxApi::Endpoints::Sharing
     # @param actions [Array]
     #   This is an optional list of actions. The permissions for the actions
     #   requested will be included in the result.
-    # @option options
-    #   limit [Numeric] The maximum number of results that include
-    #   members, groups and invitees to return per request. The default for
-    #   this field is 1000.
+    # @option options limit [Numeric] The maximum number of results that
+    #   include members, groups and invitees to return per request. The default
+    #   for this field is 1000.
     # @return [SharedFolderMembers] Shared folder user and group membership.
-    # @see DropboxApi::Metadata::MemberActionCollection
+    # @see Metadata::MemberActionList
     add_endpoint :list_folder_members do |folder_id, actions = [], options = {}|
       validate_options([:limit], options)
       options[:limit] ||= 100
 
       perform_request options.merge({
         :shared_folder_id => folder_id,
-        :actions => DropboxApi::Metadata::MemberActionCollection.new(actions)
+        :actions => DropboxApi::Metadata::MemberActionList.new(actions)
       })
     end
   end

data/lib/dropbox_api/errors/add_file_member_error.rb

@@ -1,6 +1,10 @@
 module DropboxApi::Errors
   class AddFileMemberError < BasicError
     ErrorSubtypes = {
+      :user_error => SharingUserError,
+      :access_error => SharingFileAccessError,
+      :rate_limit => RateLimitError,
+      :invalid_comment => InvalidCommentError
     }.freeze
   end
 end

data/lib/dropbox_api/errors/basic_error.rb

@@ -36,6 +36,7 @@ module DropboxApi::Errors
   class ContainsSharedFolderError < BasicError; end
   class DisallowedNameError < BasicError; end
   class DisallowedSharedLinkPolicyError < BasicError; end
+  class DownloadFailedError < BasicError; end
   class EmailUnverifiedError < BasicError; end
   class FileAncestorConflictError < BasicError; end
   class FileConflictError < BasicError; end
@@ -49,6 +50,8 @@ module DropboxApi::Errors
   class InsideSharedFolderError < BasicError; end
   class InsufficientPlanError < BasicError; end
   class InsufficientSpaceError < BasicError; end
+  class InternalError < BasicError; end
+  class InvalidCommentError < BasicError; end
   class InvalidCursorError < BasicError; end
   class InvalidDropboxIdError < BasicError; end
   class InvalidEmailError < BasicError; end
@@ -58,6 +61,7 @@ module DropboxApi::Errors
   class InvalidPathError < BasicError; end
   class InvalidRevisionError < BasicError; end
   class InvalidSettingsError < BasicError; end
+  class InvalidUrlError < BasicError; end
   class IsAppFolderError < BasicError; end
   class IsFileError < BasicError; end
   class IsFolderError < BasicError; end

data/lib/dropbox_api/errors/poll_error.rb

@@ -0,0 +1,8 @@
+module DropboxApi::Errors
+  class PollError < BasicError
+    ErrorSubtypes = {
+      :invalid_async_job_id => InvalidIdError,
+      :internal_error => InternalError
+    }.freeze
+  end
+end

data/lib/dropbox_api/errors/save_url_error.rb

@@ -0,0 +1,10 @@
+module DropboxApi::Errors
+  class SaveUrlError < BasicError
+    ErrorSubtypes = {
+      :path => WriteError,
+      :download_failed => DownloadFailedError,
+      :invalid_url => InvalidUrlError,
+      :not_found => NotFoundError
+    }.freeze
+  end
+end

data/lib/dropbox_api/errors/sharing_user_error.rb

@@ -0,0 +1,7 @@
+module DropboxApi::Errors
+  class SharingUserError < BasicError
+    ErrorSubtypes = {
+      :email_unverified => EmailUnverifiedError
+    }.freeze
+  end
+end

data/lib/dropbox_api/metadata/access_level.rb

@@ -3,16 +3,16 @@ module DropboxApi::Metadata
   #   {
   #     ".tag": "viewer"
   #   }
-  class AccessLevel < Base
-    def self.new(data)
-      case data
-      when Symbol
-        data
-      when Hash
-        data[".tag"].to_sym
-      else
-        raise ArgumentError, "Invalid value for AccessLevel: #{data.inspect}."
-      end
+  class AccessLevel < DropboxApi::Metadata::Symbol
+    VALID_ACCESS_LEVELS = [
+      :owner,
+      :editor,
+      :viewer,
+      :viewer_no_comment
+    ]
+
+    def self.valid_values
+      VALID_ACCESS_LEVELS
     end
   end
 end

data/lib/dropbox_api/metadata/add_member.rb

@@ -22,7 +22,7 @@ module DropboxApi::Metadata
     class << self
       def build_from_string(member, access_level = :editor)
         new({
-          "member" => Member.build_from_email_or_dropbox_id(member),
+          "member" => Member.new(member),
           "access_level" => access_level
         })
       end

data/lib/dropbox_api/metadata/base.rb

@@ -47,7 +47,7 @@ module DropboxApi::Metadata
       case value
       when Time
         value.utc.strftime("%FT%TZ")
-      when DropboxApi::Metadata
+      when DropboxApi::Metadata::Base
         value.to_hash
       else
         value

data/lib/dropbox_api/metadata/member.rb

@@ -10,38 +10,47 @@ module DropboxApi::Metadata
   #     }
   #   ]
   class Member < Base
-    class << self
-      def build_from_email_or_dropbox_id(email_or_id)
-        if email_or_id.start_with? "dbid:"
-          build_from_dropbox_id email_or_id
-        elsif email_or_id =~ /\A[^@\s]+@[^@\s]+\z/
-          build_from_email email_or_id
+    def initialize(member)
+      @member_hash = case member
+        when Hash
+          member
+        when String
+          hash_from_email_or_dropbox_id member
+        when DropboxApi::Metadata::Member
+          member.to_hash
         else
-          raise ArgumentError, "Invalid email or Dropbox ID: #{email_or_id}"
+          raise ArgumentError, "Invalid object for Member: #{member.inspect}"
         end
-      end
+    end
 
-      def build_from_dropbox_id(dropbox_id)
-        new({
-          :".tag" => :dropbox_id,
-          :dropbox_id => dropbox_id
-        })
-      end
+    def to_hash
+      @member_hash
+    end
+
+    private
 
-      def build_from_email(email)
-        new({
-          :".tag" => :email,
-          :email => email
-        })
+    def hash_from_email_or_dropbox_id(email_or_id)
+      if email_or_id.start_with? "dbid:"
+        hash_from_dropbox_id email_or_id
+      elsif email_or_id =~ /\A[^@\s]+@[^@\s]+\z/
+        hash_from_email email_or_id
+      else
+        raise ArgumentError, "Invalid email or Dropbox ID: #{email_or_id}"
       end
     end
 
-    def initialize(member)
-      @member = member
+    def hash_from_dropbox_id(dropbox_id)
+      {
+        :".tag" => :dropbox_id,
+        :dropbox_id => dropbox_id
+      }
     end
 
-    def to_hash
-      @member
+    def hash_from_email(email)
+      {
+        :".tag" => :email,
+        :email => email
+      }
     end
   end
 end

data/lib/dropbox_api/metadata/member_action.rb

@@ -0,0 +1,31 @@
+module DropboxApi::Metadata
+  # An action will be one of the following:
+  #
+  # - +:leave_a_copy+: Allow the member to keep a copy of the folder when
+  #   removing.
+  # - +:make_editor+: Make the member an editor of the folder.
+  # - +:make_owner+: Make the member an owner of the folder.
+  # - +:make_viewer+: Make the member a viewer of the folder.
+  # - +:make_viewer_no_comment+: Make the member a viewer of the folder without
+  #   commenting permissions.
+  # - +:remove+: Remove the member from the folder.
+  #
+  # Example of a serialized {MemberAction} object:
+  #   {
+  #     ".tag": "leave_a_copy"
+  #   }
+  class MemberAction < DropboxApi::Metadata::Symbol
+    VALID_MEMBER_ACTIONS = [
+      :leave_a_copy,
+      :make_editor,
+      :make_owner,
+      :make_viewer,
+      :make_viewer_no_comment,
+      :remove
+    ]
+
+    def self.valid_values
+      VALID_MEMBER_ACTIONS
+    end
+  end
+end

data/lib/dropbox_api/metadata/member_action_list.rb

@@ -0,0 +1,13 @@
+module DropboxApi::Metadata
+  class MemberActionList < Array
+    # Builds a list of actions for a shared folder.
+    #
+    # @example
+    #   DropboxApi::Metadata::MemberActionList.new([:leave_a_copy, :make_editor])
+    #   # => [:leave_a_copy, :make_editor]
+    # @see Metadata::MemberAction
+    def initialize(list)
+      super(list.map { |a| DropboxApi::Metadata::MemberAction.new a })
+    end
+  end
+end

data/lib/dropbox_api/metadata/member_permission.rb

@@ -1,6 +1,18 @@
 module DropboxApi::Metadata
+  # This is an example of a serialized {MemberPermission}:
+  #   {
+  #     "action": {
+  #       ".tag": "remove"
+  #     },
+  #     "allow": false,
+  #     "reason": {
+  #       ".tag": "target_is_self"
+  #     }
+  #   }
+  #
+  # This is normally contained in a {MemberPermissionList} object.
   class MemberPermission < Base
-    field :action, String # This is actually a MemberAction object
+    field :action, DropboxApi::Metadata::MemberAction
     field :allow, :boolean
     field :reason, String # This is actually a PermissionDeniedReason object
   end

data/lib/dropbox_api/metadata/member_permission_list.rb

@@ -1,4 +1,25 @@
 module DropboxApi::Metadata
+  # This represents a collection of permissions on allowed on a
+  # shared file or folder.
+  #
+  # This is an example of a serialized {MemberActionList}:
+  #   [{
+  #     "action": {
+  #       ".tag": "remove"
+  #     },
+  #     "allow": false,
+  #     "reason": {
+  #       ".tag": "target_is_self"
+  #     }
+  #   }, {
+  #     "action": {
+  #       ".tag": "make_owner"
+  #     },
+  #     "allow": false,
+  #     "reason": {
+  #       ".tag": "target_is_self"
+  #     }
+  #   }]
   class MemberPermissionList < Array
     def initialize(list)
       super(list.map { |i| DropboxApi::Metadata::MemberPermission.new i })

data/lib/dropbox_api/metadata/symbol.rb

@@ -0,0 +1,24 @@
+module DropboxApi::Metadata
+  class Symbol < DropboxApi::Metadata::Base
+    def self.new(data)
+      case data
+      when ::Symbol
+        validate(data)
+      when Hash
+        new(data[".tag"].to_sym)
+      when String
+        new(data.to_sym)
+      else
+        raise ArgumentError, "Invalid object for #{name}: #{data.inspect}."
+      end
+    end
+
+    def self.validate(value)
+      if valid_values.include? value
+        value
+      else
+        raise ArgumentError, "Invalid value for #{name}: #{value.inspect}"
+      end
+    end
+  end
+end

data/lib/dropbox_api/metadata/write_mode.rb

@@ -0,0 +1,74 @@
+module DropboxApi::Metadata
+  # Your intent when writing a file to some path. This is used to determine
+  # what constitutes a conflict and what the autorename strategy is.
+  #
+  # In some situations, the conflict behavior is identical:
+  #
+  #   - If the target path doesn't contain anything, the file is always
+  #     written; no conflict.
+  #   - If the target path contains a folder, it's always a conflict.
+  #   - If the target path contains a file with identical contents, nothing
+  #     gets written; no conflict.
+  #
+  # The conflict checking differs in the case where there's a file at the
+  # target path with contents different from the contents you're trying to
+  # write. The value will be one of the following datatypes:
+  #
+  # - +:add+: Do not overwrite an existing file if there is a conflict. The
+  #   autorename strategy is to append a number to the file name. For example,
+  #   "document.txt" might become "document (2).txt".
+  # - +:overwrite+: Always overwrite the existing file. The autorename strategy
+  #   is the same as it is for add.
+  # - +:update+: Overwrite if the given "rev" matches the existing file's
+  #   "rev". The autorename strategy is to append the string "conflicted copy"
+  #   to the file name. For example, "document.txt" might become
+  #   "document (conflicted copy).txt" or
+  #   "document (Panda's conflicted copy).txt".
+  class WriteMode < Base
+    VALID_WRITE_MODES = [
+      :add,
+      :overwrite,
+      :update
+    ]
+
+    # @example
+    #   DropboxApi::Metadata::WriteMode.new :add
+    #
+    # @example
+    #   DropboxApi::Metadata::WriteMode.new :overwrite
+    #
+    # @example
+    #   DropboxApi::Metadata::WriteMode.new :update, "a1c10ce0dd78"
+    def initialize(write_mode, rev = nil)
+      @write_mode = write_mode.to_sym
+      @rev = rev
+
+      check_validity
+    end
+
+    def check_validity
+      unless valid_mode? @write_mode
+        raise ArgumentError, "Invalid write mode: #{value}"
+      end
+
+      if @write_mode == :update && @rev.nil?
+        raise ArgumentError, "Mode `:update` expects a `rev` number"
+      end
+    end
+
+    def to_hash
+      hash = {
+        ".tag" => @write_mode
+      }
+      hash["update"] = @rev if @write_mode == :update
+
+      hash
+    end
+
+    private
+
+    def valid_mode?(value)
+      VALID_WRITE_MODES.include? value.to_sym
+    end
+  end
+end

data/lib/dropbox_api/results/save_url_job_status.rb

@@ -0,0 +1,17 @@
+module DropboxApi::Results
+  class SaveUrlJobStatus < DropboxApi::Results::Base
+    def self.new(result_data)
+      case result_data[".tag"]
+      when "in_progress"
+        :in_progress
+      when "complete"
+        DropboxApi::Metadata::File.new result_data
+      when "failed"
+        DropboxApi::Errors::SaveUrlError.build("Async job failed",
+                                               result_data["failed"])
+      else
+        raise NotImplementedError, "Unknown result type: #{result_data[".tag"]}"
+      end
+    end
+  end
+end

data/lib/dropbox_api/results/save_url_result.rb

@@ -0,0 +1,14 @@
+module DropboxApi::Results
+  class SaveUrlResult < DropboxApi::Results::Base
+    # Example with an async job:
+    #   {
+    #     ".tag": "async_job_id",
+    #     "async_job_id": "VofXAX8DO1sAAAAAAAAD_Q"
+    #   }
+    #
+    # I couldn't manage to get anything other than an async job.
+    def async_job_id
+      @data["async_job_id"]
+    end
+  end
+end

data/lib/dropbox_api/results/share_folder_launch.rb

@@ -1,5 +1,5 @@
 module DropboxApi::Results
-  class ShareFolderLaunch < DropboxApi::Results::Base
+  class ShareFolderLaunch
     def self.new(result_data)
       case result_data[".tag"]
       when "complete"

data/lib/dropbox_api/version.rb

@@ -1,3 +1,3 @@
 module DropboxApi
-  VERSION = '0.1.3'.freeze
+  VERSION = '0.1.4'.freeze
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: dropbox_api
 version: !ruby/object:Gem::Version
-  version: 0.1.3
+  version: 0.1.4
 platform: ruby
 authors:
 - Jesús Burgos
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2016-11-28 00:00:00.000000000 Z
+date: 2016-12-26 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -158,6 +158,8 @@ files:
 - lib/dropbox_api/endpoints/files/list_revisions.rb
 - lib/dropbox_api/endpoints/files/move.rb
 - lib/dropbox_api/endpoints/files/restore.rb
+- lib/dropbox_api/endpoints/files/save_url.rb
+- lib/dropbox_api/endpoints/files/save_url_check_job_status.rb
 - lib/dropbox_api/endpoints/files/search.rb
 - lib/dropbox_api/endpoints/files/upload.rb
 - lib/dropbox_api/endpoints/options_validator.rb
@@ -192,15 +194,18 @@ files:
 - lib/dropbox_api/errors/list_revisions_error.rb
 - lib/dropbox_api/errors/list_shared_links_error.rb
 - lib/dropbox_api/errors/lookup_error.rb
+- lib/dropbox_api/errors/poll_error.rb
 - lib/dropbox_api/errors/preview_error.rb
 - lib/dropbox_api/errors/relocation_error.rb
 - lib/dropbox_api/errors/restore_error.rb
+- lib/dropbox_api/errors/save_url_error.rb
 - lib/dropbox_api/errors/search_error.rb
 - lib/dropbox_api/errors/settings_error.rb
 - lib/dropbox_api/errors/share_folder_error.rb
 - lib/dropbox_api/errors/share_path_error.rb
 - lib/dropbox_api/errors/shared_folder_access_error.rb
 - lib/dropbox_api/errors/sharing_file_access_error.rb
+- lib/dropbox_api/errors/sharing_user_error.rb
 - lib/dropbox_api/errors/too_many_requests_error.rb
 - lib/dropbox_api/errors/upload_error.rb
 - lib/dropbox_api/errors/upload_write_failed_error.rb
@@ -221,7 +226,8 @@ files:
 - lib/dropbox_api/metadata/folder_sharing_info.rb
 - lib/dropbox_api/metadata/link_permissions.rb
 - lib/dropbox_api/metadata/member.rb
-- lib/dropbox_api/metadata/member_action_collection.rb
+- lib/dropbox_api/metadata/member_action.rb
+- lib/dropbox_api/metadata/member_action_list.rb
 - lib/dropbox_api/metadata/member_permission.rb
 - lib/dropbox_api/metadata/member_permission_list.rb
 - lib/dropbox_api/metadata/name.rb
@@ -232,8 +238,10 @@ files:
 - lib/dropbox_api/metadata/shared_link.rb
 - lib/dropbox_api/metadata/space_allocation.rb
 - lib/dropbox_api/metadata/space_usage.rb
+- lib/dropbox_api/metadata/symbol.rb
 - lib/dropbox_api/metadata/team.rb
 - lib/dropbox_api/metadata/team_member_info.rb
+- lib/dropbox_api/metadata/write_mode.rb
 - lib/dropbox_api/middleware/decode_result.rb
 - lib/dropbox_api/result_builder.rb
 - lib/dropbox_api/results/add_file_member_result_list.rb
@@ -245,6 +253,8 @@ files:
 - lib/dropbox_api/results/list_folder_result.rb
 - lib/dropbox_api/results/list_revisions_result.rb
 - lib/dropbox_api/results/list_shared_links_result.rb
+- lib/dropbox_api/results/save_url_job_status.rb
+- lib/dropbox_api/results/save_url_result.rb
 - lib/dropbox_api/results/search/match.rb
 - lib/dropbox_api/results/search_result.rb
 - lib/dropbox_api/results/share_folder_launch.rb

data/lib/dropbox_api/metadata/member_action_collection.rb

@@ -1,44 +0,0 @@
-module DropboxApi::Metadata
-  # This represents a collection of actions that may be taken on members of a
-  # shared folder. Each action will be one of the following:
-  #
-  # - leave_a_copy: Allow the member to keep a copy of the folder when removing.
-  # - make_editor: Make the member an editor of the folder.
-  # - make_owner: Make the member an owner of the folder.
-  # - make_viewer: Make the member a viewer of the folder.
-  # - make_viewer_no_comment: Make the member a viewer of the folder without commenting permissions.
-  # - remove: Remove the member from the folder.
-  #
-  # TODO: Split this object in two: MemberAction & MemberActionList,
-  #       DropboxApi::Metadata::MemberPermission will use it.
-  class MemberActionCollection < Array
-    ValidActions = [
-      :leave_a_copy,
-      :make_editor,
-      :make_owner,
-      :make_viewer,
-      :make_viewer_no_comment,
-      :remove
-    ]
-
-    def initialize(actions)
-      actions = symbolize actions
-      validate actions
-
-      super(actions)
-    end
-
-    private
-
-    def symbolize(actions)
-      actions.map &:to_sym
-    end
-
-    def validate(actions)
-      actions.each do |action|
-        raise ArgumentError,
-          "Invalid action: `#{action}`" unless ValidActions.include? action
-      end
-    end
-  end
-end