dropbox_api 0.1.19 → 0.1.20

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9c59970ce358c1a706d47040336547ea3df770fe97194122011f5695d69a4bc9
-  data.tar.gz: caff55f6ba1ae50d6487450c2f12ac2df2a72a2cf3573ce6d8610664de404012
+  metadata.gz: e61a99956b140b0c8b5fe982a62e1595f68f1f4b49033f023121792582121eba
+  data.tar.gz: bad01ce29cb518859008b0e71464a46cb452b348432ae8bc162e587834dee5f6
 SHA512:
-  metadata.gz: 7fc4add7446cec7d25627719dffa3b293173c7ce02356d514c7ac49f17673207da670d563e63ba0bf2690376beec98325ce84fbb6843f4bedab0ec6ff1b000b9
-  data.tar.gz: 4d2a098c291bc47d501ba90dcce05ae43e42ab77fa1c5fe8ad83d329aec3408d1ac987d2b931fbf25fe64a1f8c51584620306b06c32e9ebe7d5bf7c0a0efc6a1
+  metadata.gz: 02afaffdf0c402aa40233ee75742de02ebd9eb54f2bd962ca934c317abe29192ef846c159a0f2536bd35b2d1c319e0a9f0ddff6d0d260a9b76bf4886bc34e721
+  data.tar.gz: 5bf772b6b13e147323c932ec7abf731f6c846b1da43de3e763dd51a755e64776407b42565835896f2f6ff3af092b3f15b8eff75902bb50191801c2ea5946f695

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..."
+
+# Keep this token, you'll need it to initialize a `DropboxApi::Client` object:
+client = DropboxApi::Client.new(access_token: access_token)
 
-#### Standard OAuth 2 flow
+# 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

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>
@@ -165,7 +165,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,20 +180,20 @@
       <pre class="lines">
 
 
-7
 8
 9
 10
 11
-12</pre>
+12
+13</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 8</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='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='period'>.</span><span class='id identifier rubyid_auth_code'>auth_code</span>
 <span class='kw'>end</span></pre>
     </td>
@@ -207,9 +207,9 @@
 </div>
 
       <div id="footer">
-  Generated on Fri May 31 17:53:32 2019 by
+  Generated on Sun Feb  7 11:51:55 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.5.1).
 </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 Sun Feb  7 11:51:55 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.5.1).
 </div>
 
     </div>