dropbox-sdk-v2 0.0.2 → 0.0.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 3012cc4be1ed874d4eb5584f39564e7812d93803
-  data.tar.gz: 7d0d205741968270914b5e4a719fa18dc7488edc
+  metadata.gz: 1e9ebfa28c6f64384eb59cacf9dc1d7d9540e07f
+  data.tar.gz: cafd6c08e23ac9a3367447433b91f2050b93dcb2
 SHA512:
-  metadata.gz: d21f8305e1a3b66d2d81219201df04bcecee3355067d92f83204b936371431cec2c718ec4db124048e4b39d6e79dff248212445785575440e014d5374cbb412d
-  data.tar.gz: 52723a3ae802a78155e8af7db3f37c940f70d6a356fbe2e648f357ad95684172e99b34a1271ab77b052d1d4be1da3a2cb9473cabed156fa3d1264e764dc7491e
+  metadata.gz: a0c84b39b60423ced2aea4e112e01c5ce1034b3d470bc0cb81467f6c597239e228271a4f2dea8a7dcc73ce17c4acfb5189f111ba2ca7dbc0bdff8dc2820a7ff6
+  data.tar.gz: 3f1663941133696025b32c435cdbb9892182ce400bfec44d8a36975c0bce1f14a2994bbff4f8fde537c569cc12816f7ad7c537c6bbbca75fa78ee667b13ac714

data/README.md

@@ -1,6 +1,8 @@
 # Dropbox SDK for Ruby
 
+[![Gem Version](https://img.shields.io/gem/v/dropbox-sdk-v2.svg)](https://rubygems.org/gems/dropbox-sdk-v2)
 [![Build Status](https://travis-ci.org/waits/dropbox-sdk-ruby.svg?branch=master)](https://travis-ci.org/waits/dropbox-sdk-ruby)
+[![MIT licensed](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/waits/dropbox-sdk-ruby/blob/master/LICENSE)
 
 This is a small Ruby library for accessing the new [Dropbox API](https://www.dropbox.com/developers/documentation/http/overview). It provides a single class, `Dropbox::Client`, with methods that map to most of the Dropbox API endpoints. Currently all of the endpoints in the `auth`, `files`, and `users` namespaces are supported. Sharing methods are planned.
 
@@ -27,7 +29,7 @@ gem 'dropbox-sdk-v2'
 
 ## Usage
 
-Also see the [full method documentation](http://www.rubydoc.info/gems/dropbox-sdk-v2/Dropbox/Client).
+Also see the [full YARD documentation](http://www.rubydoc.info/github/waits/dropbox-sdk-ruby).
 
 Set up a client:
 ```ruby
@@ -46,16 +48,16 @@ folder.path_lower # => "/myfolder"
 
 Upload a file:
 ```ruby
-file = dbx.upload('/myfolder/file.txt', 'the file contents') # Accepts a String or File
-file.class # => Dropbox::FileMetadata
-file.size # => 17
+# File body can be a String, File, or any Enumerable.
+file = dbx.upload('/myfolder/file.txt', 'file body') # => Dropbox::FileMetadata
+file.size # => 9
 file.rev # => a1c10ce0dd78
 ```
 
 Download a file:
 ```ruby
 file, body = dbx.download('/myfolder/file.txt') # => Dropbox::FileMetadata, HTTP::Response::Body
-body.to_s # => "the file contents"
+body.to_s # => "file body"
 ```
 
 Delete a file:

data/lib/dropbox.rb

@@ -2,8 +2,14 @@ require_relative 'dropbox/client'
 require_relative 'dropbox/errors'
 require_relative 'dropbox/account'
 require_relative 'dropbox/metadata'
+require_relative 'dropbox/upload_session_cursor'
 
+# A small library for accessing the new Dropbox API. All of the Dropbox API
+# endpoints are implemented as methods on {Dropbox::Client}.
 module Dropbox
-  API = 'https://api.dropboxapi.com/2'
-  CONTENT_API = 'https://content.dropboxapi.com/2'
+  # The main API endpoint used for most calls.
+  API = 'https://api.dropboxapi.com/2'.freeze
+
+  # The content API endpoint used for upload/download calls.
+  CONTENT_API = 'https://content.dropboxapi.com/2'.freeze
 end

data/lib/dropbox/client.rb

@@ -5,8 +5,6 @@ require 'time'
 module Dropbox
   # Client contains all the methods that map to the Dropbox API endpoints.
   class Client
-    # Initialize a new client.
-    #
     # @param [String] access_token
     def initialize(access_token)
       unless access_token =~ /^[a-z0-9_-]{64}$/i
@@ -16,6 +14,14 @@ module Dropbox
       @access_token = access_token
     end
 
+    # Disable the access token used to authenticate the call.
+    #
+    # @return [void]
+    def revoke_token
+      r = HTTP.auth('Bearer ' + @access_token).post(API + '/auth/token/revoke')
+      raise ApiError.new(r) if r.code != 200
+    end
+
     # Copy a file or folder to a different location in the user's Dropbox.
     #
     # @param [String] from_path
@@ -26,13 +32,34 @@ module Dropbox
       parse_tagged_response(resp)
     end
 
+    # Get a copy reference to a file or folder.
+    #
+    # @param [String] path
+    # @return [Dropbox::Metadata] metadata
+    # @return [String] copy_reference
+    def get_copy_reference(path)
+      resp = request('/files/copy_reference/get', path: path)
+      metadata = parse_tagged_response(resp['metadata'])
+      return metadata, resp['copy_reference']
+    end
+
+    # Save a copy reference to the user's Dropbox.
+    #
+    # @param [String] copy_reference
+    # @param [String] path
+    # @return [Dropbox::Metadata] metadata
+    def save_copy_reference(copy_reference, path)
+      resp = request('/files/copy_reference/save', copy_reference: copy_reference, path: path)
+      parse_tagged_response(resp['metadata'])
+    end
+
     # Create a folder at a given path.
     #
     # @param [String] path
     # @return [Dropbox::FolderMetadata]
     def create_folder(path)
       resp = request('/files/create_folder', path: path)
-      parse_tagged_response(resp, 'folder')
+      FolderMetadata.new(resp)
     end
 
     # Delete the file or folder at a given path.
@@ -51,33 +78,7 @@ module Dropbox
     # @return [HTTP::Response::Body] body
     def download(path)
       resp, body = content_request('/files/download', path: path)
-      return parse_tagged_response(resp, 'file'), body
-    end
-
-    # Get information about a user's account.
-    #
-    # @param [String] account_id
-    # @return [Dropbox::BasicAccount]
-    def get_account(account_id)
-      resp = request('/users/get_account', account_id: account_id)
-      parse_tagged_response(resp, 'basic_account')
-    end
-
-    # Get information about multiple user accounts.
-    #
-    # @param [Array<String>] account_ids
-    # @return [Array<Dropbox::BasicAccount>]
-    def get_account_batch(account_ids)
-      resp = request('/users/get_account_batch', account_ids: ids)
-      resp.map { |a| parse_tagged_response(a, 'basic_account') }
-    end
-
-    # Get information about the current user's account.
-    #
-    # @return [Dropbox::FullAccount]
-    def get_current_account
-      resp = request('/users/get_current_account')
-      parse_tagged_response(resp, 'full_account')
+      return FileMetadata.new(resp), body
     end
 
     # Get the metadata for a file or folder.
@@ -96,15 +97,7 @@ module Dropbox
     # @return [HTTP::Response::Body] body
     def get_preview(path)
       resp, body = content_request('/files/get_preview', path: path)
-      return parse_tagged_response(resp, 'file'), body
-    end
-
-    # Get the space usage information for the current user's account.
-    #
-    # @return [Dropbox::SpaceUsage]
-    def get_space_usage
-      resp = request('/users/get_space_usage')
-      SpaceUsage.new(resp)
+      return FileMetadata.new(resp), body
     end
 
     # Get a temporary link to stream content of a file.
@@ -114,7 +107,7 @@ module Dropbox
     # @return [String] link
     def get_temporary_link(path)
       resp = request('/files/get_temporary_link', path: path)
-      return parse_tagged_response(resp['metadata'], 'file'), resp['link']
+      return FileMetadata.new(resp['metadata']), resp['link']
     end
 
     # Get a thumbnail for an image.
@@ -126,18 +119,36 @@ module Dropbox
     # @return [HTTP::Response::Body] body
     def get_thumbnail(path, format='jpeg', size='w64h64')
       resp, body = content_request('/files/get_thumbnail', path: path, format: format, size: size)
-      return parse_tagged_response(resp, 'file'), body
+      return FileMetadata.new(resp), body
     end
 
     # Get the contents of a folder.
     #
     # @param [String] path
-    # @return [Array<Dropbox::Metadata]
+    # @return [Array<Dropbox::Metadata>]
     def list_folder(path)
       resp = request('/files/list_folder', path: path)
       resp['entries'].map { |e| parse_tagged_response(e) }
     end
 
+    # Get the contents of a folder that are after a cursor.
+    #
+    # @param [String] cursor
+    # @return [Array<Dropbox::Metadata>]
+    def continue_list_folder(cursor)
+      resp = request('/files/list_folder/continue', cursor: cursor)
+      resp['entries'].map { |e| parse_tagged_response(e) }
+    end
+
+    # Get a cursor for a folder's current state.
+    #
+    # @param [String] path
+    # @return [String] cursor
+    def get_latest_list_folder_cursor(path)
+      resp = request('/files/list_folder/get_latest_cursor', path: path)
+      resp['cursor']
+    end
+
     # Get the revisions of a file.
     #
     # @param [String] path
@@ -145,7 +156,7 @@ module Dropbox
     # @return [Boolean] is_deleted
     def list_revisions(path)
       resp = request('/files/list_revisions', path: path)
-      entries = resp['entries'].map { |e| parse_tagged_response(e, 'file') }
+      entries = resp['entries'].map { |e| FileMetadata.new(e) }
       return entries, resp['is_deleted']
     end
 
@@ -155,10 +166,19 @@ module Dropbox
     # @param [String] to_path
     # @return [Dropbox::Metadata]
     def move(from_path, to_path)
-      resp = request('/files/move', from_path: from, to_path: to)
+      resp = request('/files/move', from_path: from_path, to_path: to_path)
       parse_tagged_response(resp)
     end
 
+    # Permanently delete the file or folder at a given path.
+    #
+    # @param [String] path
+    # @return [void]
+    def permanently_delete(path)
+      request('/files/permanently_delete', path: path)
+      nil
+    end
+
     # Restore a file to a specific revision.
     #
     # @param [String] path
@@ -166,15 +186,7 @@ module Dropbox
     # @return [Dropbox::FileMetadata]
     def restore(path, rev)
       resp = request('/files/restore', path: path, rev: rev)
-      parse_tagged_response(resp, 'file')
-    end
-
-    # Disable the access token used to authenticate the call.
-    #
-    # @return [void]
-    def revoke_token
-      r = HTTP.auth('Bearer ' + @access_token).post(API + '/auth/token/revoke')
-      raise APIError.new(r) if r.code != 200
+      FileMetadata.new(resp)
     end
 
     # Save a specified URL into a file in user's Dropbox.
@@ -185,46 +197,126 @@ module Dropbox
     # @return [Dropbox::FileMetadata] if the processing is synchronous.
     def save_url(path, url)
       resp = request('/files/save_url', path: path, url: url)
-      case resp['.tag']
-      when 'complete'
-        parse_tagged_response(resp['complete'], 'file')
-      when 'async_job_id'
-        resp['async_job_id']
-      else
-        raise ClientError.unknown_response_type(resp['.tag'])
-      end
+      parse_tagged_response(resp)
+    end
+
+    # Check the status of a save_url job.
+    #
+    # @param [String] async_job_id
+    # @return [nil] if the job is still in progress.
+    # @return [Dropbox::FileMetadata] if the job is complete.
+    # @return [String] an error message, if the job failed.
+    def check_save_url_job_status(async_job_id)
+      resp = request('/files/save_url/check_job_status', async_job_id: async_job_id)
+      parse_tagged_response(resp)
     end
 
     # Search for files and folders.
     #
-    # @param [String] query
     # @param [String] path
+    # @param [String] query
+    # @param [Integer] start
     # @param [Integer] max_results
+    # @param [String] mode
     # @return [Array<Dropbox::Metadata>] matches
-    def search(query, path='', max_results=100)
-      resp = request('/files/search', path: path, query: query, max_results: max)
-      resp['matches'].map { |m| parse_tagged_response(m['metadata']) }
+    def search(path, query, start=0, max_results=100, mode='filename')
+      resp = request('/files/search', path: path, query: query, start: start,
+        max_results: max_results, mode: mode)
+      matches = resp['matches'].map { |m| parse_tagged_response(m['metadata']) }
+      return matches
     end
 
     # Create a new file.
     #
     # @param [String] path
     # @param [String, Enumerable] body
-    # @param [String] mode
-    # @param [Boolean] autorename
-    # @param [String, Time] client_modified
-    # @param [Boolean] mute
+    # @option options [String] :mode
+    # @option options [Boolean] :autorename
+    # @option options [Boolean] :mute
     # @return [Dropbox::FileMetadata]
-    def upload(path, body, mode='add', autorename=false, client_modified=nil, mute=false)
-      client_modified = client_modified.iso8601 if client_modified.is_a?(Time)
-      resp = upload_request('/files/upload', body, path: path, mode: mode,
-        autorename: autorename, client_modified: client_modified, mute: mute)
-      parse_tagged_response(resp, 'file')
+    def upload(path, body, options={})
+      options[:client_modified] = Time.now.utc.iso8601
+      options[:path] = path
+      resp = upload_request('/files/upload', body, options.merge(path: path))
+      FileMetadata.new(resp)
+    end
+
+    # Start an upload session to upload a file using multiple requests.
+    #
+    # @param [String, Enumerable] body
+    # @param [Boolean] close
+    # @return [Dropbox::UploadSessionCursor] cursor
+    def start_upload_session(body, close=false)
+      resp = upload_request('/files/upload_session/start', body, close: close)
+      UploadSessionCursor.new(resp['session_id'], body.length)
+    end
+
+    # Append more data to an upload session.
+    #
+    # @param [Dropbox::UploadSessionCursor] cursor
+    # @param [String, Enumerable] body
+    # @param [Boolean] close
+    # @return [Dropbox::UploadSessionCursor] cursor
+    def append_upload_session(cursor, body, close=false)
+      args = {cursor: cursor.to_h, close: close}
+      resp = upload_request('/files/upload_session/append_v2', body, args)
+      cursor.offset += body.length
+      cursor
+    end
+
+    # Finish an upload session and save the uploaded data to the given file path.
+    #
+    # @param [Dropbox::UploadSessionCursor] cursor
+    # @param [String] path
+    # @param [String, Enumerable] body
+    # @param [Hash] options
+    # @option (see #upload)
+    # @return [Dropbox::FileMetadata]
+    def finish_upload_session(cursor, path, body, options={})
+      options[:client_modified] = Time.now.utc.iso8601
+      options[:path] = path
+      args = {cursor: cursor.to_h, commit: options}
+      resp = upload_request('/files/upload_session/finish', body, args)
+      FileMetadata.new(resp)
+    end
+
+    # Get information about a user's account.
+    #
+    # @param [String] account_id
+    # @return [Dropbox::BasicAccount]
+    def get_account(account_id)
+      resp = request('/users/get_account', account_id: account_id)
+      BasicAccount.new(resp)
+    end
+
+    # Get information about multiple user accounts.
+    #
+    # @param [Array<String>] account_ids
+    # @return [Array<Dropbox::BasicAccount>]
+    def get_account_batch(account_ids)
+      resp = request('/users/get_account_batch', account_ids: account_ids)
+      resp.map { |a| BasicAccount.new(a) }
+    end
+
+    # Get information about the current user's account.
+    #
+    # @return [Dropbox::FullAccount]
+    def get_current_account
+      resp = request('/users/get_current_account')
+      FullAccount.new(resp)
+    end
+
+    # Get the space usage information for the current user's account.
+    #
+    # @return [Dropbox::SpaceUsage]
+    def get_space_usage
+      resp = request('/users/get_space_usage')
+      SpaceUsage.new(resp)
     end
 
     private
-      def parse_tagged_response(resp, tag=resp['.tag'])
-        case tag
+      def parse_tagged_response(resp)
+        case resp['.tag']
         when 'file'
           FileMetadata.new(resp)
         when 'folder'
@@ -235,8 +327,16 @@ module Dropbox
           BasicAccount.new(resp)
         when 'full_account'
           FullAccount.new(resp)
+        when 'complete'
+          FileMetadata.new(resp)
+        when 'async_job_id'
+          resp['async_job_id']
+        when 'in_progress'
+          nil
+        when 'failed'
+          resp['failed']['.tag']
         else
-          raise ClientError.unknown_response_type(tag)
+          raise ClientError.unknown_response_type(resp['.tag'])
         end
       end
 
@@ -246,7 +346,7 @@ module Dropbox
           .headers(content_type: ('application/json' if data))
           .post(url, json: data)
 
-        raise APIError.new(resp) if resp.code != 200
+        raise ApiError.new(resp) if resp.code != 200
         JSON.parse(resp.to_s)
       end
 
@@ -255,7 +355,7 @@ module Dropbox
         resp = HTTP.auth('Bearer ' + @access_token)
           .headers('Dropbox-API-Arg' => args.to_json).get(url)
 
-        raise APIError.new(resp) if resp.code != 200
+        raise ApiError.new(resp) if resp.code != 200
         file = JSON.parse(resp.headers['Dropbox-API-Result'])
         return file, resp.body
       end
@@ -267,8 +367,8 @@ module Dropbox
           'Transfer-Encoding' => ('chunked' unless body.is_a?(String))
         }).post(CONTENT_API + action, body: body)
 
-        raise APIError.new(resp) if resp.code != 200
-        JSON.parse(resp.to_s)
+        raise ApiError.new(resp) if resp.code != 200
+        JSON.parse(resp.to_s) unless resp.to_s == 'null'
       end
   end
 end

data/lib/dropbox/errors.rb

@@ -1,6 +1,7 @@
 require 'json'
 
 module Dropbox
+  # Thrown when Dropbox::Client encounters an error unrelated to the API.
   class ClientError < StandardError
     attr_reader :message
 
@@ -21,7 +22,8 @@ module Dropbox
     end
   end
 
-  class APIError < StandardError
+  # Thrown when the API returns an error response.
+  class ApiError < StandardError
     attr_reader :message
 
     def initialize(response)

data/lib/dropbox/metadata.rb

@@ -1,6 +1,7 @@
 require 'time'
 
 module Dropbox
+  # Abstract class inherited by the other metadata classes.
   class Metadata
     attr_reader :name, :path_lower, :path_display
 
@@ -11,6 +12,7 @@ module Dropbox
     end
   end
 
+  # Contains the metadata (but not contents) of a file.
   class FileMetadata < Metadata
     attr_reader :id, :client_modified, :server_modified, :rev, :size
 
@@ -24,8 +26,13 @@ module Dropbox
       @size = attrs.delete('size')
       super(attrs)
     end
+
+    def ==(cmp)
+      cmp.is_a?(self.class) && self.id == cmp.id
+    end
   end
 
+  # Contains the metadata (but not contents) of a folder.
   class FolderMetadata < Metadata
     attr_reader :id
 
@@ -33,8 +40,13 @@ module Dropbox
       @id = attrs.delete('id')
       super(attrs)
     end
+
+    def ==(cmp)
+      cmp.is_a?(self.class) && self.id == cmp.id
+    end
   end
 
+  # Contains the metadata of a deleted file.
   class DeletedMetadata < Metadata
   end
 end

data/lib/dropbox/upload_session_cursor.rb

@@ -0,0 +1,22 @@
+module Dropbox
+  # UploadSessionCursor holds information about an in-progress upload session.
+  #
+  # @attr [String] session_id A unique identifier for the session.
+  # @attr [Integer] offset The size of the data uploaded so far.
+  class UploadSessionCursor
+    attr_reader :session_id
+    attr_accessor :offset
+
+    # @param [String] session_id
+    # @param [Integer] offset
+    def initialize(session_id, offset)
+      @session_id = session_id
+      @offset = offset
+    end
+
+    # @return [Hash]
+    def to_h
+      {session_id: session_id, offset: offset}
+    end
+  end
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: dropbox-sdk-v2
 version: !ruby/object:Gem::Version
-  version: 0.0.2
+  version: 0.0.3
 platform: ruby
 authors:
 - Dylan Waits
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2016-06-20 00:00:00.000000000 Z
+date: 2016-07-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: minitest
@@ -51,6 +51,7 @@ files:
 - lib/dropbox/client.rb
 - lib/dropbox/errors.rb
 - lib/dropbox/metadata.rb
+- lib/dropbox/upload_session_cursor.rb
 homepage: https://github.com/waits/dropbox-sdk-ruby
 licenses:
 - MIT