dropbox_api 0.1.1 → 0.1.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: e2ad8b305ace1f2190948fc945fa0858cde13892
-  data.tar.gz: e939597633dfa2b79d9a2032722ab9ba33543f55
+  metadata.gz: fd04df06e2b79e0a102c34ada12761d414d92484
+  data.tar.gz: 2d71c761e4b9c05e0207633d2b0d984f434ffd4e
 SHA512:
-  metadata.gz: c1ffbfd944bdf036ba31c0527fbc4fc28713d852788e696fb8a12bf07756a46d7ba99259cf5f6f5b3aa54cecf87ee5a112ddf57fbc91af2ae6a1945244d3604a
-  data.tar.gz: d4aed46a8ab64d10d03e153c5a22e0aed0f874f682150f19277d8b9ba2ed0ad2fe5815a9a71a6ae29b22b2eec7454344cb95bf178bd1611ba538f4345e4bd90d
+  metadata.gz: 7cfaf692c3c6625378951ddd42108e12d667477fb9468b5d1648e0891b7cb45cedd93fb7a06dd5e018625baf1955c330824dba14604569e323ceb0ea3aae5ba2
+  data.tar.gz: 26d60eb6ddfb03c8e3c8b3219d0b1698c4360215b5edbdb39d096f8c7adffa131dbf1e470cb8be911ca58e3322b143d18939e360017e4f4eda6e1a9e170e5331

data/.yardopts

@@ -0,0 +1 @@
+- api_coverage.md api_reference.md rails_setup.md

data/CHANGES.md

@@ -0,0 +1,7 @@
+This file aims to compile all the breaking changes introduced in each version.
+
+### Version 0.2
+
+- `list_folder_members` changed its signature from
+  `list_folder_members(folder_id, options = {})` to
+  `list_folder_members(folder_id, actions = [], options = {})`

data/README.md

@@ -40,6 +40,9 @@ DropboxApi::Client.new
 #=> #<DropboxApi::Client ...>
 ```
 
+Note that setting an ENV variable is only a feasible choice if you're only
+using one account.
+
 #### Option A: Get your access token from the website
 
 The easiest way to obtain an access token is to get it from the Dropbox website.
@@ -54,17 +57,26 @@ to generate an access token.
 
 You can obtain an authorization code with this library:
 
-1. `require "dropbox_api/authenticator"`
-1. `authenticator = DropboxApi::Authenticator.new(CLIENT_ID, CLIENT_SECRET)`
-2. `authenticator.authorize_url  #=> "https://www.dropbox.com/..."`
-3. Open the authorization URL in your browser, authorize the application and
-   copy your code.
-4. `auth_bearer = authenticator.get_token(CODE) #=> #<OAuth2::AccessToken ...>`
-5. `auth_bearer.token #=> "VofXAX8D..."`. Keep this token!
+```ruby
+authenticator = DropboxApi::Authenticator.new(CLIENT_ID, CLIENT_SECRET)
+authenticator.authorize_url #=> "https://www.dropbox.com/..."
+
+# Now you need to open the authorization URL in your browser,
+# authorize the application and copy your code.
+
+auth_bearer = authenticator.get_token(CODE) #=> #<OAuth2::AccessToken ...>`
+auth_bearer.token #=> "VofXAX8D..."
+# Keep this token, you'll need it to initialize a `DropboxApi::Client` object
+```
+
+#### Standard OAuth 2 flow
+
+This is what many web applications will use. The process is described in
+Dropbox's [OAuth guide](https://www.dropbox.com/developers/reference/oauth-guide#oauth-2-on-the-web).
 
-#### Standard OAuth flow
+If you have a Rails application, you might be interested in this [setup
+ guide](rails_setup.md).
 
-Not implemented yet. :(
 
 ### Performing API calls
 
@@ -86,11 +98,18 @@ result.has_more?
 #=> false
 ```
 
-Refer to the documentation to see the details for each endpoint.
+Refer to the
+[documentation](http://www.rubydoc.info/gems/dropbox_api)
+to see the details for each endpoint, you can find them all in the following
+3 modules:
+
+ - [Files](http://www.rubydoc.info/gems/dropbox_api/DropboxApi/Endpoints/Files)
+ - [Sharing](http://www.rubydoc.info/gems/dropbox_api/DropboxApi/Endpoints/Sharing)
+ - [Users](http://www.rubydoc.info/gems/dropbox_api/DropboxApi/Endpoints/Users)
 
 ## Dependencies
 
-###Network adapter
+### Network adapter
 
 This gem uses [faraday](https://github.com/lostisland/faraday#faraday).
 So it should work on any network library.
@@ -109,7 +128,13 @@ commits and tags, and push the `.gem` file to
 ## Contributing
 
 Any help will be much appreciated. It should be quite easy to implement most
-of the [endpoints that are still pending](api_coverage.md).
+of the [endpoints that are still pending](api_coverage.md) by looking at the
+exising implementations (check out the `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`)

data/TODO.md

@@ -1,8 +1,38 @@
-# Goals to publish v0.1
+# Week
 
-- Write a tutorial showing how to set up authentication in a Rails app.
-- Add a small module for configuration. Needs to contain the OAuth bearer.
+TOKEN: VofXAX8DO1sAAAAAAAADiXbd__inZjFI0OTsK9ao8AAKmshXqdbnjOnXz7XylBbf
+
+- 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
+- list_shared_folders
+- continue_list_shared_folders
+- share_folder
+- add_folder_member
+- mount_folder
+- list_folder_members
+- relinquish_folder_membership
+- transfer_folder
+
+# Short term goals
+
+- Remove dependency on faraday.
+- Complete full [API coverage](api_coverage.md).
 
 # Further on
 
+- Improve the  API reference page, help here:
+  http://gnuu.org/2009/11/18/customizing-yard-templates/
 - Supporting streams would be great.
+- Add a layer to handle pagination, use `Enumerable`.
+
+# Release guide
+
+1. Bump version in `version.rb`.
+2. Create tag and write release notes in Github.com.
+3. 

data/api_coverage.md

@@ -1,3 +1,5 @@
+# @title API Implementation Coverage
+
 **IMPORTANT: This document is work in progress. Information isn't accurate.**
 
 The Dropbox API changes frequently, so you may find out that the feature that
@@ -38,7 +40,7 @@ API call | Status
 `/save_url` | 🌑
 `/save_url/check_job_status` | 🌑
 `/search` | 🌕
-`/upload` | 🌕
+`/upload` | 🌔
 `/upload_session/append` | 🌑
 `/upload_session/append_v2` | 🌑
 `/upload_session/finish` | 🌑
@@ -49,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` | 🌑
@@ -66,7 +68,7 @@ API call | Status
 `/list_file_members` | 🌑
 `/list_file_members/batch` | 🌑
 `/list_file_members/continue` | 🌑
-`/list_folder_members` | 🌓
+`/list_folder_members` | 🌕
 `/list_folder_members/continue` | 🌑
 `/list_folders` | 🌑
 `/list_folders/continue` | 🌑
@@ -96,9 +98,9 @@ API call | Status
 API call | Status
 --- | :---:
 `/get_account` | 🌕
-`/get_account_batch` | 🌑
-`/get_current_account` | 🌑
-`/get_space_usage` | 🌑
+`/get_account_batch` | 🌕
+`/get_current_account` | 🌕
+`/get_space_usage` | 🌕
 
 
 ## Dropbox Business API

data/api_reference.md

@@ -0,0 +1,25 @@
+# @title API Reference
+
+{render:DropboxApi::Endpoints::Files::Copy#copy}
+{render:DropboxApi::Endpoints::Files::CreateFolder#create_folder}
+{render:DropboxApi::Endpoints::Files::Delete#delete}
+{render:DropboxApi::Endpoints::Files::Download#download}
+{render:DropboxApi::Endpoints::Files::GetMetadata#get_metadata}
+{render:DropboxApi::Endpoints::Files::GetPreview#get_preview}
+{render:DropboxApi::Endpoints::Files::GetTemporaryLink#get_temporary_link}
+{render:DropboxApi::Endpoints::Files::GetThumbnail#get_thumbnail}
+{render:DropboxApi::Endpoints::Files::ListFolder#list_folder}
+{render:DropboxApi::Endpoints::Files::ListFolderContinue#list_folder_continue}
+{render:DropboxApi::Endpoints::Files::ListFolderGetLatestCursor#list_folder_get_latest_cursor}
+{render:DropboxApi::Endpoints::Files::ListFolderLongpoll#list_folder_longpoll}
+{render:DropboxApi::Endpoints::Files::ListRevisions#list_revisions}
+{render:DropboxApi::Endpoints::Files::Move#move}
+{render:DropboxApi::Endpoints::Files::Restore#restore}
+{render:DropboxApi::Endpoints::Files::Search#search}
+{render:DropboxApi::Endpoints::Files::Upload#upload}
+
+{render:DropboxApi::Endpoints::Sharing::AddFolderMember#add_folder_member}
+{render:DropboxApi::Endpoints::Sharing::CreateSharedLinkWithSettings#create_shared_link_with_settings}
+{render:DropboxApi::Endpoints::Sharing::ListFolderMembers#list_folder_members}
+{render:DropboxApi::Endpoints::Sharing::ListSharedLinks#list_shared_links}
+{render:DropboxApi::Endpoints::Sharing::ShareFolder#share_folder}

data/lib/dropbox_api.rb

@@ -1,16 +1,28 @@
 require 'dropbox_api/version'
 
+require 'time'
 require 'json'
 require 'faraday'
 
+require 'dropbox_api/authenticator'
+
 require 'dropbox_api/middleware/decode_result'
 
 require 'dropbox_api/metadata/field'
-require 'dropbox_api/metadata/add_member'
 require 'dropbox_api/metadata/base'
+
+require 'dropbox_api/metadata/access_level'
+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_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'
@@ -23,6 +35,8 @@ require 'dropbox_api/metadata/shared_folder'
 require 'dropbox_api/metadata/file_link'
 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/errors/http_error'
 require 'dropbox_api/errors/basic_error'
@@ -40,6 +54,8 @@ require 'dropbox_api/errors/create_folder_error'
 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/file_member_action_error'
 require 'dropbox_api/errors/get_metadata_error'
 require 'dropbox_api/errors/list_folder_error'
 require 'dropbox_api/errors/list_revisions_error'
@@ -51,11 +67,15 @@ 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/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/result_builder'
 require 'dropbox_api/results/base'
+require 'dropbox_api/results/basic_account_batch'
+require 'dropbox_api/results/add_file_member_result_list'
 require 'dropbox_api/results/get_temporary_link_result'
 require 'dropbox_api/results/list_folder_result'
 require 'dropbox_api/results/list_revisions_result'
@@ -94,9 +114,13 @@ require 'dropbox_api/endpoints/files/move'
 require 'dropbox_api/endpoints/files/restore'
 require 'dropbox_api/endpoints/files/search'
 require 'dropbox_api/endpoints/files/upload'
+require 'dropbox_api/endpoints/sharing/add_file_member'
 require 'dropbox_api/endpoints/sharing/add_folder_member'
 require 'dropbox_api/endpoints/sharing/list_folder_members'
 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/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'

data/lib/dropbox_api/authenticator.rb

@@ -2,19 +2,15 @@ require 'oauth2'
 
 module DropboxApi
   class Authenticator < OAuth2::Client
+    extend Forwardable
+
     def initialize(client_id, client_secret)
-      @oauth_client = OAuth2::Client.new(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'
-      })
-    end
-
-    def authorize_url
-      @oauth_client.auth_code.authorize_url
+      }).auth_code
     end
 
-    def get_token(oauth_code)
-      @oauth_client.auth_code.get_token oauth_code
-    end
+    def_delegators :@auth_code, :authorize_url, :get_token
   end
 end

data/lib/dropbox_api/endpoints/base.rb

@@ -16,11 +16,22 @@ module DropboxApi::Endpoints
     end
 
     def process_response(raw_response)
+      # Official Dropbox documentation for HTTP error codes:
+      # https://www.dropbox.com/developers/documentation/http/documentation#error-handling
       case raw_response.status
       when 200, 409
         # Status code 409 is "Endpoint-specific error". We need to look at
         # the response body to build an exception.
         build_result(raw_response.env[:api_result])
+      when 429
+        error = DropboxApi::Errors::TooManyRequestsError.build(
+          raw_response.env[:api_result]["error_summary"],
+          raw_response.env[:api_result]["error"]["reason"]
+        )
+
+        error.retry_after = raw_response.headers["retry-after"].to_i
+
+        raise error
       else
         raise DropboxApi::Errors::HttpError,
           "HTTP #{raw_response.status}: #{raw_response.body}"

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

@@ -14,13 +14,37 @@ module DropboxApi::Endpoints::Files
     # jpg, jpeg, png, tiff, tif, gif and bmp. Photos that are larger than 20MB
     # in size won't be converted to a thumbnail.
     #
+    # @example
+    #   # Save thumbnail to a local file
+    #   client = DropboxApi::Client.new
+    #   file = File.open("thumbnail.png", "w")
+    #   client.get_thumbnail "/dropbox_image.png" do |thumbnail_content|
+    #     file.write thumbnail_content
+    #   end
+    #   file.close
+    # @example
+    #   # Save thumbnail to a local file with .jpg format
+    #   client = DropboxApi::Client.new
+    #   file = File.open("thumbnail.jpg", "w")
+    #   client.get_thumbnail("/dropbox_image.png", :format => :jpeg) do |thumbnail_content|
+    #     file.write thumbnail_content
+    #   end
+    #   file.close
+    # @example
+    #   # Upload thumbnail to Amazon S3 (assuming you're using their SDK)
+    #   s3_object = AWS::S3.new.s3.buckets['my-bucket'].objects['key']
+    #   #=> <AWS::S3::S3Object ...>
+    #   client = DropboxApi::Client.new
+    #   client.get_thumbnail "/dropbox_image.png" do |thumbnail_content|
+    #     s3_object.write thumbnail_content
+    #   end
     # @param path [String] The path to the image file you want to thumbnail.
-    # @option format [:jpeg, :png] The format for the thumbnail image, jpeg
-    #   (default) or png. For images that are photos, jpeg should be preferred,
-    #   while png is better for screenshots and digital arts. The default is
-    #   :jpeg.
-    # @option size [:w32h32, :w64h64, :w128h128, :w640h480, :w1024h768] The
-    #   size for the thumbnail image. The default is :w64h64
+    # @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+.
     add_endpoint :get_thumbnail do |path, options = {}, &block|
       validate_options([:format, :size], options)
       options[:format] ||= :jpeg

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

@@ -5,16 +5,28 @@ module DropboxApi::Endpoints::Files
     ResultType  = DropboxApi::Metadata::File
     ErrorType   = DropboxApi::Errors::UploadError
 
-    # @method upload(path)
-    # Create a new file with the contents provided in the request.
+    # @method upload(path, content, options = {})
+    # 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().
     #
+    # @example
+    #   client = DropboxApi::Client.new
+    #   file_content = IO.read "local_image.png"
+    #   client.upload "/image.png", file_content
+    #   #=> #<DropboxApi::Metadata::File: @name="image.png" ...>
+    # @example
+    #   client = DropboxApi::Client.new
+    #   client.upload "/file.txt", "Contents of a plain text file."
+    #   #=> #<DropboxApi::Metadata::File: @name="file.txt" ...>
     # @param path [String] Path in the user's Dropbox to save the file.
-    # @option 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 mute [Boolean] Normally, users are made aware of any 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

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

@@ -0,0 +1,60 @@
+module DropboxApi::Endpoints::Sharing
+  class AddFileMember < DropboxApi::Endpoints::Rpc
+    Method      = :post
+    Path        = "/2/sharing/add_file_member".freeze
+    ResultType  = DropboxApi::Results::AddFileMemberResultList
+    ErrorType   = DropboxApi::Errors::AddFileMemberError
+
+    include DropboxApi::Endpoints::OptionsValidator
+
+    # @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.
+    #
+    # @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.
+    # @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+.
+    # @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+.
+    # @option options add_message_as_comment [String] Optional message to
+    #   display to added members in their invitation. This field is optional.
+    add_endpoint :add_file_member do |file, members, options = {}|
+      validate_options([:quiet, :custom_message], options)
+      options[:quiet] ||= false
+      options[:custom_message] ||= nil
+      options[:access_level] ||= :viewer
+      options[:add_message_as_comment] ||= false
+
+      perform_request options.merge({
+        :file => file,
+        :members => build_members_param(members)
+      })
+    end
+
+    private
+
+    def build_members_param(members)
+      members.map do |member|
+        case member
+        when String
+          DropboxApi::Metadata::Member.build_from_email_or_dropbox_id member
+        when DropboxApi::Metadata::Member
+          member
+        else
+          raise ArgumentError, "Invalid argument type `#{member.class.name}`"
+        end
+      end.map(&:to_hash)
+    end
+  end
+end