dropbox_api 0.1.18 → 0.1.21

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8a3a1a2bc289cebba02099f33f564a26f5534a2103621f8533e1eec22fd12ad6
-  data.tar.gz: b1a9743de1947243db1a0cb17da1d410dcb61a9b196c80ed9fe5f8c617bb7067
+  metadata.gz: 043f63bda514baadbe49335bb7c79dcbe05831e699428f21f0841db6f2541af8
+  data.tar.gz: 8eaffc62aecbc794743cb64a50f1bd19d28df60edc4742771cbb06911c6d91d0
 SHA512:
-  metadata.gz: 5c691510ae44d46099d87cf75d822381fe006ae9b77f45b4c08a6f0d7b2db884c6fdf504acf2df930c344ee0b19b664b4fa6b726c15c21c7117452a8dfcd5c13
-  data.tar.gz: 047bb7cf238a161d4572d23b126c9ba50b35ffaf9a588a2846c613a5c4b317df11e94fb1c16f91a74d30093f37b8452d6ff15c5fbee46b7a2465b93dec28e4b5
+  metadata.gz: 5ef853e21852c114922f799a0478ec23b9a174732c932cee28b4d7708c592a2d39879cc01382f2f1ee5720b0f2b109dc09f2cd9e9c9a2250909246ea7b688980
+  data.tar.gz: f126916d8ea0612619c8b2c1059ce534e6fead18e83892210ec3bb98a31976220bb214d435ddbe687d0700ff87be30c94bfaa6f4232ad24fde5392fa46e16f8c

data/.rubocop.yml

@@ -1,14 +1,15 @@
-inherit_from: .rubocop_todo.yml
+AllCops:
+  DisabledByDefault: true
 
 Style/HashSyntax:
   Enabled: true
-  EnforcedStyle: 'hash_rockets'
+  EnforcedStyle: 'ruby19'
 
-Style/ClassAndModuleChildren:
-  Enabled: false
+Style/FrozenStringLiteralComment:
+  EnforcedStyle: always_true
 
-Style/Documentation:
-  Enabled: false
+Style/RedundantFreeze:
+  Enabled: true
 
-Naming/ConstantName:
-  Enabled: false
+Style/StringLiterals:
+  EnforcedStyle: single_quotes

data/.travis.yml

@@ -1,7 +1,5 @@
 language: ruby
 rvm:
-  - 1.9.3
-  - 2.2.6
   - 2.3.3
   - 2.4.4
   - 2.5.1

data/Gemfile

@@ -1,13 +1,34 @@
+# frozen_string_literal: true
 source 'https://rubygems.org'
 
 gemspec
 
 group :development do
+  gem 'bundler', '>= 1.7'
+  gem 'rake'
+
+  # Test
+  gem 'rspec'
+  gem 'vcr'
+  gem 'webmock'
+
+  # Gem dependencies
+  if RUBY_VERSION >= '2.6'
+    gem 'faraday', '~> 2.0'
+    gem 'faraday-net_http_persistent'
+  else
+    gem 'faraday', '~> 1.0'
+  end
+
+
   # Documentation
   gem 'redcarpet'
-  gem 'yard-tests-rspec', :git => "https://github.com/Jesus/yard-spec-plugin.git"
+  gem 'yard-tests-rspec', git: 'https://github.com/Jesus/yard-spec-plugin.git'
+
+  # Debugging
+  gem 'byebug'
 
   # Code linting
-  gem 'rubocop', :require => false
-  gem 'rubocop-rspec', :require => false
+  gem 'rubocop', require: false
+  gem 'rubocop-rspec', require: false
 end

data/README.md

@@ -56,44 +56,115 @@ DropboxApi::Client.new
 #=> #<DropboxApi::Client ...>
 ```
 
-Note that setting an ENV variable is only a feasible choice if you're only
-using one account.
+The official documentation on the process to get an authorization code is
+[here](https://developers.dropbox.com/es-es/oauth-guide#implementing-oauth),
+it describes the two options listed below.
 
-#### 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.
-You just need to log in to Dropbox and refer to the *developers* section, go to
-*My apps* and select your application, you may need to create one if you
-haven't done so yet.
+#### Option A: Get your access token from the website
 
-Under your application settings, find section *OAuth 2*. You'll find a button
-to generate an access token.
+For a quick test, you can obtain an access token from the App Console in
+[Dropbox's website](https://www.dropbox.com/developers/). Select from
+*My apps* your application, you may need to create one if you
+haven't done so yet. Under your application settings, find section
+*OAuth 2*, there is a button to generate an access token.
 
-#### Option B: Use `DropboxApi::Authenticator`
+#### Option B: OAuth2 Code Flow
 
-You can obtain an authorization code with this library:
+This is typically what you will use in production, you can obtain an
+authorization code with a 3-step process:
 
 ```ruby
+# 1. Get an authorization URL.
 authenticator = DropboxApi::Authenticator.new(CLIENT_ID, CLIENT_SECRET)
-authenticator.authorize_url #=> "https://www.dropbox.com/..."
+authenticator.auth_code.authorize_url #=> "https://www.dropbox.com/..."
 
-# Now you need to open the authorization URL in your browser,
-# authorize the application and copy your code.
+# 2. Log into Dropbox and authorize your app. You need to open the
+# authorization URL in your browser.
 
-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
-```
+# 3. Exchange the authorization code for a reusable access token (not visible
+#    to the user).
+access_token = authenticator.auth_code.get_token(CODE) #=> #<OAuth2::AccessToken ...>`
+access_token.token #=> "VofXAX8D..."
 
-#### Standard OAuth 2 flow
+# Keep this token, you'll need it to initialize a `DropboxApi::Client` object:
+client = DropboxApi::Client.new(access_token: access_token)
+
+# For backwards compatibility, the following also works:
+client = DropboxApi::Client.new(access_token.token)
+```
 
-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).
+##### Integration with Rails
 
 If you have a Rails application, you might be interested in this [setup
 guide](http://jesus.github.io/dropbox_api/file.rails_setup.html).
 
+
+##### Using refresh tokens
+
+Access tokens are short-lived by default (as of September 30th, 2021),
+applications that require long-lived access to the API without additional
+interaction with the user should use refresh tokens.
+
+The process is similar but a token refresh might seamlessly occur as you
+perform API calls. When this happens you'll need to store the
+new token hash if you want to continue using this session, you can use the
+`on_token_refreshed` callback to do this.
+
+```ruby
+# 1. Get an authorization URL, requesting offline access type.
+authenticator = DropboxApi::Authenticator.new(CLIENT_ID, CLIENT_SECRET)
+authenticator.auth_code.authorize_url(token_access_type: 'offline')
+
+# 2. Log into Dropbox and authorize your app. You need to open the
+#    authorization URL in your browser.
+
+# 3. Exchange the authorization code for a reusable access token
+access_token = authenticator.auth_code.get_token(CODE) #=> #<OAuth2::AccessToken ...>`
+
+# You can now use the access token to initialize a DropboxApi::Client, you
+# should also provide a callback function to store the updated access token
+# whenever it's refreshed.
+client = DropboxApi::Client.new(
+  access_token: access_token,
+  on_token_refreshed: lambda { |new_token_hash|
+    # token_hash is a serializable Hash, something like this:
+    # {
+    #   "uid"=>"440",
+    #   "token_type"=>"bearer",
+    #   "scope"=>"account_info.read account_info.write...",
+    #   "account_id"=>"dbid:AABOLtA1rT6rRK4vajKZ...",
+    #   :access_token=>"sl.A5Ez_CBsqJILhDawHlmXSoZEhLZ4nuLFVRs6AJ...",
+    #   :refresh_token=>"iMg4Me_oKYUAAAAAAAAAAapQixCgwfXOxuubCuK_...",
+    #   :expires_at=>1632948328
+    # }
+    SomewhereSafe.save(new_token_hash)
+  }
+)
+```
+
+Once you've gone through the process above, you can skip the steps that require
+user interaction in subsequent initializations of `DropboxApi::Client`. For
+example:
+
+```ruby
+# 1. Initialize an authenticator
+authenticator = DropboxApi::Authenticator.new(CLIENT_ID, CLIENT_SECRET)
+
+# 2. Retrieve the token hash you previously stored somewhere safe, you can use
+#    it to build a new access token.
+access_token = OAuth2::AccessToken.from_hash(authenticator, token_hash)
+
+# 3. You now have an access token, so you can initialize a client like you
+#    would normally:
+client = DropboxApi::Client.new(
+  access_token: access_token,
+  on_token_refreshed: lambda { |new_token_hash|
+    SomewhereSafe.save(new_token_hash)
+  }
+)
+```
+
 ### Performing API calls
 
 Once you've initialized a client, for example:
@@ -139,6 +210,26 @@ Check out the
 [method documentation](http://www.xuuso.com/dropbox_api/DropboxApi/Client.html#upload_by_chunks-instance_method)
 to find out all available options.
 
+### Accessing Team Folders
+
+In order to access your team scope you need to add the namespace_id to you request headers.
+This can be done using the middlewere layer as per the below:
+
+```ruby
+client = DropboxApi::Client.new("VofXAX8D...")
+#=> #<DropboxApi::Client ...>
+client.namespace_id = client.get_current_account.root_info.root_namespace_id
+
+client.list_folder('')
+#=> Now returns the team folders
+```
+
+You could unset the namespace ID at any point afterwards with just:
+
+```ruby
+client.namespace_id = nil
+```
+
 ## Dependencies
 
 This gem depends on
@@ -146,7 +237,7 @@ This gem depends on
 and
 [faraday](https://github.com/lostisland/faraday).
 
-It has official support for Ruby versions `1.9.x` and `2.x`.
+It has official support for Ruby versions `2.x`.
 
 ## Development
 
@@ -172,6 +263,11 @@ would be the procedure to do so:
     DROPBOX_OAUTH_BEARER=YOUR_AUTH_BEARER rake test:build_scaffold[list_folder]
     ```
 
+    Note that you'll have to type `rake test:build_scaffold\[list_folder\]`
+    if you use `zsh`.
+
+    You can build all available scaffolds with just `rake test:build_scaffold`.
+
  3. Run the tests and the cassettes will be written:
 
     ```text
@@ -182,7 +278,7 @@ The OAuth bearer shouldn't have been recorded in the cassette and it should've
 been filtered. However, you may want to double check before pushing your
 updates to Github.
 
-Tip: You can simply run `export DROPBOX_OAUTH_BEARER=YOUR_AUTH_BEARER` at
+Tip: you can simply run `export DROPBOX_OAUTH_BEARER=YOUR_AUTH_BEARER` at
 the beginning of your work session so you don't need to prefix it in every
 command line.
 

data/Rakefile

@@ -1,7 +1,8 @@
-require "bundler/gem_tasks"
-require "rspec/core/rake_task"
+# frozen_string_literal: true
+require 'bundler/gem_tasks'
+require 'rspec/core/rake_task'
 require File.expand_path('../spec/support/rake_tasks', __FILE__)
 
 RSpec::Core::RakeTask.new(:spec)
 
-task :default => :spec
+task default: :spec

data/TODO.md

@@ -1,3 +1,11 @@
+# Pre-release for v0.1.21
+
+- Support Faraday 2.0
+- Chunked downloads?
+- Add instructions to support a new endpoint and send a PR.
+- Release!
+
+
 # Immediate
 
 - Test all added classes since last release.

data/api_coverage.md

@@ -68,7 +68,7 @@ API call | Status
 `/restore` | 🌕
 `/save_url` | 🌕
 `/save_url/check_job_status` | 🌕
-`/search` | 🌔
+`/search_v2` | 🌔
 `/upload` | 🌕
 `/upload_session/append` | alias?
 `/upload_session/append_v2` | 🌕

data/bin/console

@@ -1,7 +1,8 @@
 #!/usr/bin/env ruby
+# frozen_string_literal: true
 
-require "bundler/setup"
-require "dropbox_api"
+require 'bundler/setup'
+require 'dropbox_api'
 
 # You can add fixtures and/or initialization code here to make experimenting
 # with your gem easier. You can also use a different console, if you like.
@@ -10,5 +11,5 @@ require "dropbox_api"
 # require "pry"
 # Pry.start
 
-require "irb"
+require 'irb'
 IRB.start

data/docs/DropboxApi/Authenticator.html

@@ -6,15 +6,15 @@
 <title>
   Class: DropboxApi::Authenticator
   
-    &mdash; Documentation by YARD 0.9.19
+    &mdash; Documentation by YARD 0.9.26
   
 </title>
 
-  <link rel="stylesheet" href="../css/style.css" type="text/css" charset="utf-8" />
+  <link rel="stylesheet" href="../css/style.css" type="text/css" />
 
-  <link rel="stylesheet" href="../css/common.css" type="text/css" charset="utf-8" />
+  <link rel="stylesheet" href="../css/common.css" type="text/css" />
 
-<script type="text/javascript" charset="utf-8">
+<script type="text/javascript">
   pathId = "DropboxApi::Authenticator";
   relpath = '../';
 </script>
@@ -87,11 +87,6 @@
 
   
   
-  <dl>
-      <dt>Extended by:</dt>
-      <dd>Forwardable</dd>
-  </dl>
-  
   
   
   
@@ -150,7 +145,6 @@
   
 
 
-  
   <div id="constructor_details" class="method_details_list">
   <h2>Constructor Details</h2>
   
@@ -165,7 +159,7 @@
   
 </h3><div class="docstring">
   <div class="discussion">
-    <p>Returns a new instance of Authenticator</p>
+    <p>Returns a new instance of Authenticator.</p>
 
 
   </div>
@@ -180,21 +174,21 @@
       <pre class="lines">
 
 
+6
 7
 8
 9
 10
-11
-12</pre>
+11</pre>
     </td>
     <td>
-      <pre class="code"><span class="info file"># File 'lib/dropbox_api/authenticator.rb', line 7</span>
+      <pre class="code"><span class="info file"># File 'lib/dropbox_api/authenticator.rb', line 6</span>
 
 <span class='kw'>def</span> <span class='id identifier rubyid_initialize'>initialize</span><span class='lparen'>(</span><span class='id identifier rubyid_client_id'>client_id</span><span class='comma'>,</span> <span class='id identifier rubyid_client_secret'>client_secret</span><span class='rparen'>)</span>
-  <span class='ivar'>@auth_code</span> <span class='op'>=</span> <span class='const'>OAuth2</span><span class='op'>::</span><span class='const'>Client</span><span class='period'>.</span><span class='id identifier rubyid_new'>new</span><span class='lparen'>(</span><span class='id identifier rubyid_client_id'>client_id</span><span class='comma'>,</span> <span class='id identifier rubyid_client_secret'>client_secret</span><span class='comma'>,</span> <span class='lbrace'>{</span>
-    <span class='symbol'>:authorize_url</span> <span class='op'>=&gt;</span> <span class='tstring'><span class='tstring_beg'>&#39;</span><span class='tstring_content'>https://www.dropbox.com/oauth2/authorize</span><span class='tstring_end'>&#39;</span></span><span class='comma'>,</span>
-    <span class='symbol'>:token_url</span> <span class='op'>=&gt;</span> <span class='tstring'><span class='tstring_beg'>&#39;</span><span class='tstring_content'>https://api.dropboxapi.com/oauth2/token</span><span class='tstring_end'>&#39;</span></span>
-  <span class='rbrace'>}</span><span class='rparen'>)</span><span class='period'>.</span><span class='id identifier rubyid_auth_code'>auth_code</span>
+  <span class='kw'>super</span><span class='lparen'>(</span><span class='id identifier rubyid_client_id'>client_id</span><span class='comma'>,</span> <span class='id identifier rubyid_client_secret'>client_secret</span><span class='comma'>,</span> <span class='lbrace'>{</span>
+    <span class='label'>authorize_url:</span> <span class='tstring'><span class='tstring_beg'>&#39;</span><span class='tstring_content'>https://www.dropbox.com/oauth2/authorize</span><span class='tstring_end'>&#39;</span></span><span class='comma'>,</span>
+    <span class='label'>token_url:</span> <span class='tstring'><span class='tstring_beg'>&#39;</span><span class='tstring_content'>https://api.dropboxapi.com/oauth2/token</span><span class='tstring_end'>&#39;</span></span>
+  <span class='rbrace'>}</span><span class='rparen'>)</span>
 <span class='kw'>end</span></pre>
     </td>
   </tr>
@@ -207,9 +201,9 @@
 </div>
 
       <div id="footer">
-  Generated on Fri May 31 17:53:32 2019 by
+  Generated on Wed Sep 29 23:44:25 2021 by
   <a href="http://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
-  0.9.19 (ruby-2.6.2).
+  0.9.26 (ruby-2.6.5).
 </div>
 
     </div>

data/docs/DropboxApi/ChunkedUploader.html

@@ -6,15 +6,15 @@
 <title>
   Class: DropboxApi::ChunkedUploader
   
-    &mdash; Documentation by YARD 0.9.19
+    &mdash; Documentation by YARD 0.9.26
   
 </title>
 
-  <link rel="stylesheet" href="../css/style.css" type="text/css" charset="utf-8" />
+  <link rel="stylesheet" href="../css/style.css" type="text/css" />
 
-  <link rel="stylesheet" href="../css/common.css" type="text/css" charset="utf-8" />
+  <link rel="stylesheet" href="../css/common.css" type="text/css" />
 
-<script type="text/javascript" charset="utf-8">
+<script type="text/javascript">
   pathId = "DropboxApi::ChunkedUploader";
   relpath = '../';
 </script>
@@ -238,7 +238,7 @@
   
 </h3><div class="docstring">
   <div class="discussion">
-    <p>Returns a new instance of ChunkedUploader</p>
+    <p>Returns a new instance of ChunkedUploader.</p>
 
 
   </div>
@@ -253,17 +253,17 @@
       <pre class="lines">
 
 
-5
 6
 7
 8
 9
 10
 11
-12</pre>
+12
+13</pre>
     </td>
     <td>
-      <pre class="code"><span class="info file"># File 'lib/dropbox_api/chunked_uploader.rb', line 5</span>
+      <pre class="code"><span class="info file"># File 'lib/dropbox_api/chunked_uploader.rb', line 6</span>
 
 <span class='kw'>def</span> <span class='id identifier rubyid_initialize'>initialize</span><span class='lparen'>(</span><span class='id identifier rubyid_client'>client</span><span class='comma'>,</span> <span class='id identifier rubyid_path'>path</span><span class='comma'>,</span> <span class='id identifier rubyid_i_stream'>i_stream</span><span class='comma'>,</span> <span class='id identifier rubyid_options'>options</span> <span class='op'>=</span> <span class='lbrace'>{</span><span class='rbrace'>}</span><span class='rparen'>)</span>
   <span class='ivar'>@chunk_size</span> <span class='op'>=</span> <span class='id identifier rubyid_options'>options</span><span class='period'>.</span><span class='id identifier rubyid_delete'>delete</span><span class='lparen'>(</span><span class='symbol'>:chunk_size</span><span class='rparen'>)</span> <span class='op'>||</span> <span class='int'>4</span> <span class='op'>*</span> <span class='int'>1024</span> <span class='op'>*</span> <span class='int'>1024</span> <span class='comment'># 4 MiB
@@ -301,12 +301,12 @@
       <pre class="lines">
 
 
-31
 32
-33</pre>
+33
+34</pre>
     </td>
     <td>
-      <pre class="code"><span class="info file"># File 'lib/dropbox_api/chunked_uploader.rb', line 31</span>
+      <pre class="code"><span class="info file"># File 'lib/dropbox_api/chunked_uploader.rb', line 32</span>
 
 <span class='kw'>def</span> <span class='id identifier rubyid_finish'>finish</span>
   <span class='ivar'>@client</span><span class='period'>.</span><span class='id identifier rubyid_upload_session_finish'>upload_session_finish</span> <span class='ivar'>@cursor</span><span class='comma'>,</span> <span class='ivar'>@commit_info</span>
@@ -332,19 +332,19 @@
       <pre class="lines">
 
 
-14
 15
 16
 17
 18
-19</pre>
+19
+20</pre>
     </td>
     <td>
-      <pre class="code"><span class="info file"># File 'lib/dropbox_api/chunked_uploader.rb', line 14</span>
+      <pre class="code"><span class="info file"># File 'lib/dropbox_api/chunked_uploader.rb', line 15</span>
 
 <span class='kw'>def</span> <span class='id identifier rubyid_start'>start</span>
   <span class='id identifier rubyid_chunk'>chunk</span> <span class='op'>=</span> <span class='ivar'>@i_stream</span><span class='period'>.</span><span class='id identifier rubyid_read'>read</span> <span class='ivar'>@chunk_size</span>
-  <span class='id identifier rubyid_chunk'>chunk</span> <span class='op'>=</span> <span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_end'>&quot;</span></span> <span class='kw'>if</span> <span class='id identifier rubyid_chunk'>chunk</span><span class='period'>.</span><span class='id identifier rubyid_nil?'>nil?</span>
+  <span class='id identifier rubyid_chunk'>chunk</span> <span class='op'>=</span> <span class='tstring'><span class='tstring_beg'>&#39;</span><span class='tstring_end'>&#39;</span></span> <span class='kw'>if</span> <span class='id identifier rubyid_chunk'>chunk</span><span class='period'>.</span><span class='id identifier rubyid_nil?'>nil?</span>
 
   <span class='ivar'>@cursor</span> <span class='op'>=</span> <span class='ivar'>@client</span><span class='period'>.</span><span class='id identifier rubyid_upload_session_start'>upload_session_start</span> <span class='id identifier rubyid_chunk'>chunk</span>
 <span class='kw'>end</span></pre>
@@ -369,7 +369,6 @@
       <pre class="lines">
 
 
-21
 22
 23
 24
@@ -377,10 +376,11 @@
 26
 27
 28
-29</pre>
+29
+30</pre>
     </td>
     <td>
-      <pre class="code"><span class="info file"># File 'lib/dropbox_api/chunked_uploader.rb', line 21</span>
+      <pre class="code"><span class="info file"># File 'lib/dropbox_api/chunked_uploader.rb', line 22</span>
 
 <span class='kw'>def</span> <span class='id identifier rubyid_upload'>upload</span>
   <span class='id identifier rubyid_loop'>loop</span> <span class='kw'>do</span>
@@ -401,9 +401,9 @@
 </div>
 
       <div id="footer">
-  Generated on Fri May 31 17:53:32 2019 by
+  Generated on Wed Sep 29 23:44:25 2021 by
   <a href="http://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
-  0.9.19 (ruby-2.6.2).
+  0.9.26 (ruby-2.6.5).
 </div>
 
     </div>