class Dropbox::Client

Client contains all the methods that map to the Dropbox API endpoints.

Public Class Methods

new(access_token) click to toggle source

@param [String] access_token

# File lib/dropbox/client.rb, line 9
def initialize(access_token)
  unless access_token =~ /^[a-z0-9_-]{64}$/i
    raise ClientError.invalid_access_token
  end

  @access_token = access_token
end

Public Instance Methods

append_upload_session(cursor, body, close=false) click to toggle source

Append more data to an upload session.

@param [Dropbox::UploadSessionCursor] cursor @param [String, Enumerable] body @param [Boolean] close @return [Dropbox::UploadSessionCursor] cursor

# File lib/dropbox/client.rb, line 260
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
check_save_url_job_status(async_job_id) click to toggle source

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.

# File lib/dropbox/client.rb, line 209
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
continue_list_folder(cursor) click to toggle source

Get the contents of a folder that are after a cursor.

@param [String] cursor @return [Array<Dropbox::Metadata>]

# File lib/dropbox/client.rb, line 138
def continue_list_folder(cursor)
  resp = request('/files/list_folder/continue', cursor: cursor)
  resp['entries'].map { |e| parse_tagged_response(e) }
end
copy(from_path, to_path) click to toggle source

Copy a file or folder to a different location in the user's Dropbox.

@param [String] from_path @param [String] to_path @return [Dropbox::Metadata]

# File lib/dropbox/client.rb, line 30
def copy(from_path, to_path)
  resp = request('/files/copy', from_path: from_path, to_path: to_path)
  parse_tagged_response(resp)
end
create_folder(path) click to toggle source

Create a folder at a given path.

@param [String] path @return [Dropbox::FolderMetadata]

# File lib/dropbox/client.rb, line 60
def create_folder(path)
  resp = request('/files/create_folder', path: path)
  FolderMetadata.new(resp)
end
delete(path) click to toggle source

Delete the file or folder at a given path.

@param [String] path @return [Dropbox::Metadata]

# File lib/dropbox/client.rb, line 69
def delete(path)
  resp = request('/files/delete', path: path)
  parse_tagged_response(resp)
end
download(path) click to toggle source

Download a file from a user's Dropbox.

@param [String] path @return [Dropbox::FileMetadata] metadata @return [HTTP::Response::Body] body

# File lib/dropbox/client.rb, line 79
def download(path)
  resp, body = content_request('/files/download', path: path)
  return FileMetadata.new(resp), body
end
finish_upload_session(cursor, path, body, options={}) click to toggle source

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]

# File lib/dropbox/client.rb, line 275
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_account(account_id) click to toggle source

Get information about a user's account.

@param [String] account_id @return [Dropbox::BasicAccount]

# File lib/dropbox/client.rb, line 287
def get_account(account_id)
  resp = request('/users/get_account', account_id: account_id)
  BasicAccount.new(resp)
end
get_account_batch(account_ids) click to toggle source

Get information about multiple user accounts.

@param [Array<String>] account_ids @return [Array<Dropbox::BasicAccount>]

# File lib/dropbox/client.rb, line 296
def get_account_batch(account_ids)
  resp = request('/users/get_account_batch', account_ids: account_ids)
  resp.map { |a| BasicAccount.new(a) }
end
get_copy_reference(path) click to toggle source

Get a copy reference to a file or folder.

@param [String] path @return [Dropbox::Metadata] metadata @return [String] copy_reference

# File lib/dropbox/client.rb, line 40
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
get_current_account() click to toggle source

Get information about the current user's account.

@return [Dropbox::FullAccount]

# File lib/dropbox/client.rb, line 304
def get_current_account
  resp = request('/users/get_current_account')
  FullAccount.new(resp)
end
get_latest_list_folder_cursor(path) click to toggle source

Get a cursor for a folder's current state.

@param [String] path @return [String] cursor

# File lib/dropbox/client.rb, line 147
def get_latest_list_folder_cursor(path)
  resp = request('/files/list_folder/get_latest_cursor', path: path)
  resp['cursor']
end
get_metadata(path) click to toggle source

Get the metadata for a file or folder.

@param [String] path @return [Dropbox::Metadata]

# File lib/dropbox/client.rb, line 88
def get_metadata(path)
  resp = request('/files/get_metadata', path: path)
  parse_tagged_response(resp)
end
get_preview(path) click to toggle source

Get a preview for a file.

@param [String] path @return [Dropbox::FileMetadata] metadata @return [HTTP::Response::Body] body

# File lib/dropbox/client.rb, line 98
def get_preview(path)
  resp, body = content_request('/files/get_preview', path: path)
  return FileMetadata.new(resp), body
end
get_space_usage() click to toggle source

Get the space usage information for the current user's account.

@return [Dropbox::SpaceUsage]

# File lib/dropbox/client.rb, line 312
def get_space_usage
  resp = request('/users/get_space_usage')
  SpaceUsage.new(resp)
end
get_thumbnail(path, format='jpeg', size='w64h64') click to toggle source

Get a thumbnail for an image.

@param [String] path @param [String] format @param [String] size @return [Dropbox::FileMetadata] metadata @return [HTTP::Response::Body] body

# File lib/dropbox/client.rb, line 120
def get_thumbnail(path, format='jpeg', size='w64h64')
  resp, body = content_request('/files/get_thumbnail', path: path, format: format, size: size)
  return FileMetadata.new(resp), body
end
list_folder(path) click to toggle source

Get the contents of a folder.

@param [String] path @return [Array<Dropbox::Metadata>]

# File lib/dropbox/client.rb, line 129
def list_folder(path)
  resp = request('/files/list_folder', path: path)
  resp['entries'].map { |e| parse_tagged_response(e) }
end
list_revisions(path) click to toggle source

Get the revisions of a file.

@param [String] path @return [Array<Dropbox::FileMetadata>] entries @return [Boolean] is_deleted

# File lib/dropbox/client.rb, line 157
def list_revisions(path)
  resp = request('/files/list_revisions', path: path)
  entries = resp['entries'].map { |e| FileMetadata.new(e) }
  return entries, resp['is_deleted']
end
move(from_path, to_path) click to toggle source

Move a file or folder to a different location in the user's Dropbox.

@param [String] from_path @param [String] to_path @return [Dropbox::Metadata]

# File lib/dropbox/client.rb, line 168
def move(from_path, to_path)
  resp = request('/files/move', from_path: from_path, to_path: to_path)
  parse_tagged_response(resp)
end
permanently_delete(path) click to toggle source

Permanently delete the file or folder at a given path.

@param [String] path @return [void]

# File lib/dropbox/client.rb, line 177
def permanently_delete(path)
  request('/files/permanently_delete', path: path)
  nil
end
restore(path, rev) click to toggle source

Restore a file to a specific revision.

@param [String] path @param [String] rev @return [Dropbox::FileMetadata]

# File lib/dropbox/client.rb, line 187
def restore(path, rev)
  resp = request('/files/restore', path: path, rev: rev)
  FileMetadata.new(resp)
end
revoke_token() click to toggle source

Disable the access token used to authenticate the call.

@return [void]

# File lib/dropbox/client.rb, line 20
def revoke_token
  r = HTTP.auth('Bearer ' + @access_token).post(API + '/auth/token/revoke')
  raise ApiError.new(r) if r.code != 200
end
save_copy_reference(copy_reference, path) click to toggle source

Save a copy reference to the user's Dropbox.

@param [String] copy_reference @param [String] path @return [Dropbox::Metadata] metadata

# File lib/dropbox/client.rb, line 51
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
save_url(path, url) click to toggle source

Save a specified URL into a file in user's Dropbox.

@param [String] path @param [String] url @return [String] the job id, if the processing is asynchronous. @return [Dropbox::FileMetadata] if the processing is synchronous.

# File lib/dropbox/client.rb, line 198
def save_url(path, url)
  resp = request('/files/save_url', path: path, url: url)
  parse_tagged_response(resp)
end
start_upload_session(body, close=false) click to toggle source

Start an upload session to upload a file using multiple requests.

@param [String, Enumerable] body @param [Boolean] close @return [Dropbox::UploadSessionCursor] cursor

# File lib/dropbox/client.rb, line 249
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
upload(path, body, options={}) click to toggle source

Create a new file.

@param [String] path @param [String, Enumerable] body @option options [String] :mode @option options [Boolean] :autorename @option options [Boolean] :mute @return [Dropbox::FileMetadata]

# File lib/dropbox/client.rb, line 237
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

Private Instance Methods

content_request(action, args={}) click to toggle source
# File lib/dropbox/client.rb, line 353
def content_request(action, args={})
  url = CONTENT_API + action
  resp = HTTP.auth('Bearer ' + @access_token)
    .headers('Dropbox-API-Arg' => args.to_json).get(url)

  raise ApiError.new(resp) if resp.code != 200
  file = JSON.parse(resp.headers['Dropbox-API-Result'])
  return file, resp.body
end
parse_tagged_response(resp) click to toggle source
# File lib/dropbox/client.rb, line 318
def parse_tagged_response(resp)
  case resp['.tag']
  when 'file'
    FileMetadata.new(resp)
  when 'folder'
    FolderMetadata.new(resp)
  when 'deleted'
    DeletedMetadata.new(resp)
  when 'basic_account'
    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(resp['.tag'])
  end
end
request(action, data=nil) click to toggle source
# File lib/dropbox/client.rb, line 343
def request(action, data=nil)
  url = API + action
  resp = HTTP.auth('Bearer ' + @access_token)
    .headers(content_type: ('application/json' if data))
    .post(url, json: data)

  raise ApiError.new(resp) if resp.code != 200
  JSON.parse(resp.to_s)
end
upload_request(action, body, args={}) click to toggle source
# File lib/dropbox/client.rb, line 363
def upload_request(action, body, args={})
  resp = HTTP.auth('Bearer ' + @access_token).headers({
    'Content-Type' => 'application/octet-stream',
    'Dropbox-API-Arg' => args.to_json,
    '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) unless resp.to_s == 'null'
end