Skip to content

Commit

Permalink
1.36.0
Browse files Browse the repository at this point in the history
  • Loading branch information
Eric Koleda committed Feb 27, 2020
1 parent e590134 commit 053d3e7
Show file tree
Hide file tree
Showing 7 changed files with 51 additions and 190 deletions.
39 changes: 12 additions & 27 deletions dist/OAuth2.gs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -32,23 +32,6 @@ var TOKEN_FORMAT = {
FORM_URL_ENCODED: 'application/x-www-form-urlencoded'
};

/**
* The supported locations for passing the state parameter.
* @enum {string}
*/
var STATE_PARAMETER_LOCATION = {
/**
* Pass the state parameter in the authorization URL.
* @default
*/
AUTHORIZATION_URL: 'authorization-url',
/**
* Pass the state token in the redirect URL, as a workaround for APIs that
* don't support the state parameter.
*/
REDIRECT_URL: 'redirect-url'
};

/**
* Creates a new OAuth2 service with the name specified. It's usually best to
* create and configure your service once at the start of your script, and then
Expand Down Expand Up @@ -692,9 +675,6 @@ Service_.prototype.refresh = function() {
* @return {Storage} The service's storage.
*/
Service_.prototype.getStorage = function() {
validate_({
'Property store': this.propertyStore_
});
if (!this.storage_) {
var prefix = 'oauth2.' + this.serviceName_;
this.storage_ = new Storage_(prefix, this.propertyStore_, this.cache_);
Expand Down Expand Up @@ -894,14 +874,14 @@ Service_.prototype.exchangeGrant_ = function() {
* related information.
* @param {string} prefix The prefix to use for keys in the properties and
* cache.
* @param {PropertiesService.Properties} properties The properties instance to
* use.
* @param {PropertiesService.Properties} optProperties The optional properties
* instance to use.
* @param {CacheService.Cache} [optCache] The optional cache instance to use.
* @constructor
*/
function Storage_(prefix, properties, optCache) {
function Storage_(prefix, optProperties, optCache) {
this.prefix_ = prefix;
this.properties_ = properties;
this.properties_ = optProperties;
this.cache_ = optCache;
this.memory_ = {};
}
Expand Down Expand Up @@ -953,7 +933,8 @@ Storage_.prototype.getValue = function(key, optSkipMemoryCheck) {
}

// Check properties.
if (jsonValue = this.properties_.getProperty(prefixedKey)) {
if (this.properties_ &&
(jsonValue = this.properties_.getProperty(prefixedKey))) {
if (this.cache_) {
this.cache_.put(prefixedKey,
jsonValue, Storage_.CACHE_EXPIRATION_TIME_SECONDS);
Expand Down Expand Up @@ -981,7 +962,9 @@ Storage_.prototype.getValue = function(key, optSkipMemoryCheck) {
Storage_.prototype.setValue = function(key, value) {
var prefixedKey = this.getPrefixedKey_(key);
var jsonValue = JSON.stringify(value);
this.properties_.setProperty(prefixedKey, jsonValue);
if (this.properties_) {
this.properties_.setProperty(prefixedKey, jsonValue);
}
if (this.cache_) {
this.cache_.put(prefixedKey, jsonValue,
Storage_.CACHE_EXPIRATION_TIME_SECONDS);
Expand All @@ -995,7 +978,9 @@ Storage_.prototype.setValue = function(key, value) {
*/
Storage_.prototype.removeValue = function(key) {
var prefixedKey = this.getPrefixedKey_(key);
this.properties_.deleteProperty(prefixedKey);
if (this.properties_) {
this.properties_.deleteProperty(prefixedKey);
}
if (this.cache_) {
this.cache_.remove(prefixedKey);
}
Expand Down
4 changes: 2 additions & 2 deletions docs/Service_.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5074,13 +5074,13 @@ <h5>Returns:</h5>
</div>

<nav>
<h2><a href="index.html">Home</a></h2><h3>Classes</h3><ul><li><a href="Service_.html">Service_</a></li><li><a href="Storage_.html">Storage_</a></li></ul><h3>Global</h3><ul><li><a href="global.html#createService">createService</a></li><li><a href="global.html#extend_">extend_</a></li><li><a href="global.html#getRedirectUri">getRedirectUri</a></li><li><a href="global.html#STATE_PARAMETER_LOCATION">STATE_PARAMETER_LOCATION</a></li><li><a href="global.html#TOKEN_FORMAT">TOKEN_FORMAT</a></li><li><a href="global.html#toLowerCaseKeys_">toLowerCaseKeys_</a></li></ul>
<h2><a href="index.html">Home</a></h2><h3>Classes</h3><ul><li><a href="Service_.html">Service_</a></li><li><a href="Storage_.html">Storage_</a></li></ul><h3>Global</h3><ul><li><a href="global.html#createService">createService</a></li><li><a href="global.html#extend_">extend_</a></li><li><a href="global.html#getRedirectUri">getRedirectUri</a></li><li><a href="global.html#TOKEN_FORMAT">TOKEN_FORMAT</a></li><li><a href="global.html#toLowerCaseKeys_">toLowerCaseKeys_</a></li></ul>
</nav>

<br class="clear">

<footer>
Documentation generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 3.5.5</a> on Tue Oct 01 2019 13:52:47 GMT-0400 (EDT)
Documentation generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 3.5.5</a> on Thu Feb 27 2020 17:41:34 GMT-0500 (EST)
</footer>

<script> prettyPrint(); </script>
Expand Down
14 changes: 7 additions & 7 deletions docs/Storage_.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -28,7 +28,7 @@ <h1 class="page-title">Class: Storage_</h1>

<header>

<h2><span class="attribs"><span class="type-signature"></span></span>Storage_<span class="signature">(prefix, properties, optCache<span class="signature-attributes">opt</span>)</span><span class="type-signature"></span></h2>
<h2><span class="attribs"><span class="type-signature"></span></span>Storage_<span class="signature">(prefix, optProperties, optCache<span class="signature-attributes">opt</span>)</span><span class="type-signature"></span></h2>


</header>
Expand All @@ -41,7 +41,7 @@ <h2><span class="attribs"><span class="type-signature"></span></span>Storage_<sp



<h4 class="name" id="Storage_"><span class="type-signature"></span>new Storage_<span class="signature">(prefix, properties, optCache<span class="signature-attributes">opt</span>)</span><span class="type-signature"></span></h4>
<h4 class="name" id="Storage_"><span class="type-signature"></span>new Storage_<span class="signature">(prefix, optProperties, optCache<span class="signature-attributes">opt</span>)</span><span class="type-signature"></span></h4>



Expand Down Expand Up @@ -120,7 +120,7 @@ <h5>Parameters:</h5>

<tr>

<td class="name"><code>properties</code></td>
<td class="name"><code>optProperties</code></td>


<td class="type">
Expand All @@ -144,8 +144,8 @@ <h5>Parameters:</h5>



<td class="description last">The properties instance to
use.</td>
<td class="description last">The optional properties
instance to use.</td>
</tr>


Expand Down Expand Up @@ -757,13 +757,13 @@ <h5>Parameters:</h5>
</div>

<nav>
<h2><a href="index.html">Home</a></h2><h3>Classes</h3><ul><li><a href="Service_.html">Service_</a></li><li><a href="Storage_.html">Storage_</a></li></ul><h3>Global</h3><ul><li><a href="global.html#createService">createService</a></li><li><a href="global.html#extend_">extend_</a></li><li><a href="global.html#getRedirectUri">getRedirectUri</a></li><li><a href="global.html#STATE_PARAMETER_LOCATION">STATE_PARAMETER_LOCATION</a></li><li><a href="global.html#TOKEN_FORMAT">TOKEN_FORMAT</a></li><li><a href="global.html#toLowerCaseKeys_">toLowerCaseKeys_</a></li></ul>
<h2><a href="index.html">Home</a></h2><h3>Classes</h3><ul><li><a href="Service_.html">Service_</a></li><li><a href="Storage_.html">Storage_</a></li></ul><h3>Global</h3><ul><li><a href="global.html#createService">createService</a></li><li><a href="global.html#extend_">extend_</a></li><li><a href="global.html#getRedirectUri">getRedirectUri</a></li><li><a href="global.html#TOKEN_FORMAT">TOKEN_FORMAT</a></li><li><a href="global.html#toLowerCaseKeys_">toLowerCaseKeys_</a></li></ul>
</nav>

<br class="clear">

<footer>
Documentation generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 3.5.5</a> on Tue Oct 01 2019 13:52:47 GMT-0400 (EDT)
Documentation generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 3.5.5</a> on Thu Feb 27 2020 17:41:34 GMT-0500 (EST)
</footer>

<script> prettyPrint(); </script>
Expand Down
147 changes: 2 additions & 145 deletions docs/global.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -98,149 +98,6 @@ <h3 class="subsection-title">Members</h3>



<h4 class="name" id="STATE_PARAMETER_LOCATION"><span class="type-signature"></span>STATE_PARAMETER_LOCATION<span class="type-signature"> :string</span></h4>




<div class="description">
The supported locations for passing the state parameter.
</div>



<h5>Type:</h5>
<ul>
<li>

<span class="param-type">string</span>


</li>
</ul>





<h5 class="subsection-title">Properties:</h5>



<table class="props">
<thead>
<tr>

<th>Name</th>


<th>Type</th>





<th class="last">Description</th>
</tr>
</thead>

<tbody>


<tr>

<td class="name"><code>AUTHORIZATION_URL</code></td>


<td class="type">


<span class="param-type">string</span>



</td>





<td class="description last">Pass the state parameter in the authorization URL.</td>
</tr>



<tr>

<td class="name"><code>REDIRECT_URL</code></td>


<td class="type">


<span class="param-type">string</span>



</td>





<td class="description last">Pass the state token in the redirect URL, as a workaround for APIs that
don't support the state parameter.</td>
</tr>


</tbody>
</table>




<dl class="details">
































</dl>








<h4 class="name" id="TOKEN_FORMAT"><span class="type-signature"></span>TOKEN_FORMAT<span class="type-signature"> :string</span></h4>


Expand Down Expand Up @@ -1355,13 +1212,13 @@ <h5>Returns:</h5>
</div>

<nav>
<h2><a href="index.html">Home</a></h2><h3>Classes</h3><ul><li><a href="Service_.html">Service_</a></li><li><a href="Storage_.html">Storage_</a></li></ul><h3>Global</h3><ul><li><a href="global.html#createService">createService</a></li><li><a href="global.html#extend_">extend_</a></li><li><a href="global.html#getRedirectUri">getRedirectUri</a></li><li><a href="global.html#STATE_PARAMETER_LOCATION">STATE_PARAMETER_LOCATION</a></li><li><a href="global.html#TOKEN_FORMAT">TOKEN_FORMAT</a></li><li><a href="global.html#toLowerCaseKeys_">toLowerCaseKeys_</a></li></ul>
<h2><a href="index.html">Home</a></h2><h3>Classes</h3><ul><li><a href="Service_.html">Service_</a></li><li><a href="Storage_.html">Storage_</a></li></ul><h3>Global</h3><ul><li><a href="global.html#createService">createService</a></li><li><a href="global.html#extend_">extend_</a></li><li><a href="global.html#getRedirectUri">getRedirectUri</a></li><li><a href="global.html#TOKEN_FORMAT">TOKEN_FORMAT</a></li><li><a href="global.html#toLowerCaseKeys_">toLowerCaseKeys_</a></li></ul>
</nav>

<br class="clear">

<footer>
Documentation generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 3.5.5</a> on Tue Oct 01 2019 13:52:47 GMT-0400 (EDT)
Documentation generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 3.5.5</a> on Thu Feb 27 2020 17:41:34 GMT-0500 (EST)
</footer>

<script> prettyPrint(); </script>
Expand Down
33 changes: 26 additions & 7 deletions docs/index.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -133,14 +133,14 @@ <h3>1. Create the OAuth2 service</h3><p>The OAuth2Service class contains the con

// Sets the login hint, which will prevent the account chooser screen
// from being shown to users logged in with multiple accounts.
.setParam('login_hint', Session.getActiveUser().getEmail())
.setParam('login_hint', Session.getEffectiveUser().getEmail())

// Requests offline access.
.setParam('access_type', 'offline')

// Forces the approval prompt every time. This is useful for testing,
// but not desirable in a production application.
.setParam('approval_prompt', 'force');
// Consent prompt is required to ensure a refresh token is always
// returned when requesting offline access.
.setParam('prompt', 'consent');
}</code></pre><h3>2. Direct the user to the authorization URL</h3><p>Apps Script UI's are not allowed to redirect the user's window to a new URL, so
you'll need to present the authorization URL as a link for the user to click.
The URL is generated by the service, using the function <code>getAuthorizationUrl()</code>.</p>
Expand Down Expand Up @@ -189,7 +189,26 @@ <h3>4. Get the access token</h3><p>Now that the service is authorized you can us
<pre class="prettyprint source lang-js"><code>function logout() {
var service = getDriveService()
service.reset();
}</code></pre><h2>Best practices</h2><h3>Caching</h3><p>Scripts that use the library heavily should enable caching on the service, so as
}</code></pre><h2>Best practices</h2><h3>Token storage</h3><p>In almost all cases you'll want to persist the OAuth tokens after you retrieve
them. This prevents having to request access from the user every time you want
to call the API. To do so, make sure you set a properties store when you define
your service:</p>
<pre class="prettyprint source lang-js"><code>return OAuth2.createService('Foo')
.setPropertyStore(PropertiesService.getUserProperties())
// ...</code></pre><p>Apps Script has <a href="https://developers.google.com/apps-script/reference/properties/properties-service">property stores</a> scoped to the user, script,
or document. In most cases you'll want to choose user-scoped properties, as it
is most common to have each user of your script authorize access to their own
account. However there are uses cases where you'd want to authorize access to
a shared resource and then have all users of the script (or on the same
document) share that access.</p>
<p>When using a service account or 2-legged OAuth flow, where users aren't prompted
for authorization, storing tokens is still beneficial as there can be rate
limits on generating new tokens. However there are edge cases where you need to
generate lots of different tokens in a short amount of time, and persisting
those tokens to properties can exceed your <code>PropertiesService</code> quota. In those
cases you can omit any form of token storage and just retrieve new ones as
needed.</p>
<h3>Caching</h3><p>Scripts that use the library heavily should enable caching on the service, so as
to not exhaust their <code>PropertiesService</code> quotas. To enable caching, simply add
a <code>CacheService</code> cache when configuring the service:</p>
<pre class="prettyprint source lang-js"><code>return OAuth2.createService('Foo')
Expand Down Expand Up @@ -699,13 +718,13 @@ <h2>Utilities.js</h2>
</div>

<nav>
<h2><a href="index.html">Home</a></h2><h3>Classes</h3><ul><li><a href="Service_.html">Service_</a></li><li><a href="Storage_.html">Storage_</a></li></ul><h3>Global</h3><ul><li><a href="global.html#createService">createService</a></li><li><a href="global.html#extend_">extend_</a></li><li><a href="global.html#getRedirectUri">getRedirectUri</a></li><li><a href="global.html#STATE_PARAMETER_LOCATION">STATE_PARAMETER_LOCATION</a></li><li><a href="global.html#TOKEN_FORMAT">TOKEN_FORMAT</a></li><li><a href="global.html#toLowerCaseKeys_">toLowerCaseKeys_</a></li></ul>
<h2><a href="index.html">Home</a></h2><h3>Classes</h3><ul><li><a href="Service_.html">Service_</a></li><li><a href="Storage_.html">Storage_</a></li></ul><h3>Global</h3><ul><li><a href="global.html#createService">createService</a></li><li><a href="global.html#extend_">extend_</a></li><li><a href="global.html#getRedirectUri">getRedirectUri</a></li><li><a href="global.html#TOKEN_FORMAT">TOKEN_FORMAT</a></li><li><a href="global.html#toLowerCaseKeys_">toLowerCaseKeys_</a></li></ul>
</nav>

<br class="clear">

<footer>
Documentation generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 3.5.5</a> on Tue Oct 01 2019 13:52:47 GMT-0400 (EDT)
Documentation generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 3.5.5</a> on Thu Feb 27 2020 17:41:34 GMT-0500 (EST)
</footer>

<script> prettyPrint(); </script>
Expand Down
2 changes: 1 addition & 1 deletion package-lock.json
View file

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

2 changes: 1 addition & 1 deletion package.json
View file
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
{
"name": "apps-script-oauth2",
"version": "1.35.0",
"version": "1.36.0",
"description": "OAuth2 for Apps Script is a library for Google Apps Script that provides the ability to create and authorize OAuth2 tokens as well as refresh them when they expire.",
"repository": {
"type": "git",
Expand Down

0 comments on commit 053d3e7

Please sign in to comment.