1.31.0

dist/OAuth2.gs

@@ -389,9 +389,11 @@ Service_.prototype.setGrantType = function(grantType) {
  * have the user visit this URL and approve the authorization request. The
  * user will then be redirected back to your application using callback function
  * name specified, so that the flow may continue.
+ * @param {Object} optAdditionalParameters Additional parameters that should be
+ *     stored in the state token and made available in the callback function.
  * @return {string} The authorization URL.
  */
-Service_.prototype.getAuthorizationUrl = function() {
+Service_.prototype.getAuthorizationUrl = function(optAdditionalParameters) {
   validate_({
     'Client ID': this.clientId_,
     'Script ID': this.scriptId_,
@@ -400,16 +402,20 @@ Service_.prototype.getAuthorizationUrl = function() {
   });
 
   var redirectUri = getRedirectUri(this.scriptId_);
-  var state = eval('Script' + 'App').newStateToken()
+  var stateTokenBuilder = eval('Script' + 'App').newStateToken()
       .withMethod(this.callbackFunctionName_)
       .withArgument('serviceName', this.serviceName_)
-      .withTimeout(3600)
-      .createToken();
+      .withTimeout(3600);
+  if (optAdditionalParameters) {
+    Object.keys(optAdditionalParameters).forEach(function(key) {
+      stateTokenBuilder.withArgument(key, optAdditionalParameters[key]);
+    });
+  }
   var params = {
     client_id: this.clientId_,
     response_type: 'code',
     redirect_uri: redirectUri,
-    state: state
+    state: stateTokenBuilder.createToken()
   };
   params = extend_(params, this.params_);
   return buildUrl_(this.authorizationBaseUrl_, params);
@@ -1015,7 +1021,7 @@ function validate_(params) {
   Object.keys(params).forEach(function(name) {
     var value = params[name];
     if (!value) {
-      throw Utilities.formatString('%s is required.', name);
+      throw new Error(name + ' is required.');
     }
   });
 }

docs/Service_.html

@@ -574,7 +574,7 @@ <h5>Returns:</h5>
 
 
 
-    <h4 class="name" id="getAuthorizationUrl"><span class="type-signature"></span>getAuthorizationUrl<span class="signature">()</span><span class="type-signature"> &rarr; {string}</span></h4>
+    <h4 class="name" id="getAuthorizationUrl"><span class="type-signature"></span>getAuthorizationUrl<span class="signature">(optAdditionalParameters)</span><span class="type-signature"> &rarr; {string}</span></h4>
 
 
 
@@ -596,6 +596,56 @@ <h4 class="name" id="getAuthorizationUrl"><span class="type-signature"></span>ge
 
 
 
+    <h5>Parameters:</h5>
+
+
+<table class="params">
+    <thead>
+    <tr>
+
+        <th>Name</th>
+
+
+        <th>Type</th>
+
+
+
+
+
+        <th class="last">Description</th>
+    </tr>
+    </thead>
+
+    <tbody>
+
+
+        <tr>
+
+                <td class="name"><code>optAdditionalParameters</code></td>
+
+
+            <td class="type">
+
+
+<span class="param-type">Object</span>
+
+
+
+            </td>
+
+
+
+
+
+            <td class="description last">Additional parameters that should be
+    stored in the state token and made available in the callback function.</td>
+        </tr>
+
+
+    </tbody>
+</table>
+
+
 
 
 
@@ -4618,7 +4668,7 @@ <h2><a href="index.html">Home</a></h2><h3>Classes</h3><ul><li><a href="Service_.
 <br class="clear">
 
 <footer>
-    Documentation generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 3.5.5</a> on Thu Sep 27 2018 14:12:43 GMT-0700 (PDT)
+    Documentation generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 3.5.5</a> on Wed Nov 14 2018 09:13:44 GMT-0500 (EST)
 </footer>
 
 <script> prettyPrint(); </script>

docs/Storage_.html

@@ -763,7 +763,7 @@ <h2><a href="index.html">Home</a></h2><h3>Classes</h3><ul><li><a href="Service_.
 <br class="clear">
 
 <footer>
-    Documentation generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 3.5.5</a> on Thu Sep 27 2018 14:12:43 GMT-0700 (PDT)
+    Documentation generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 3.5.5</a> on Wed Nov 14 2018 09:13:44 GMT-0500 (EST)
 </footer>
 
 <script> prettyPrint(); </script>

docs/global.html

@@ -1348,7 +1348,7 @@ <h2><a href="index.html">Home</a></h2><h3>Classes</h3><ul><li><a href="Service_.
 <br class="clear">
 
 <footer>
-    Documentation generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 3.5.5</a> on Thu Sep 27 2018 14:12:43 GMT-0700 (PDT)
+    Documentation generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 3.5.5</a> on Wed Nov 14 2018 09:13:44 GMT-0500 (EST)
 </footer>
 
 <script> prettyPrint(); </script>

docs/index.html

@@ -45,7 +45,7 @@ <h3> </h3>
     <section>
         <article><h1>OAuth2 for Apps Script <a href="https://travis-ci.org/gsuitedevs/apps-script-oauth2"><img src="https://travis-ci.org/gsuitedevs/apps-script-oauth2.svg?branch=master" alt="Build Status"></a></h1><p>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. This library uses Apps Script's new
+expire. This library uses Apps Script's
 <a href="https://developers.google.com/apps-script/reference/script/state-token-builder">StateTokenBuilder</a>
 and <code>/usercallback</code> endpoint to handle the redirects.</p>
 <h2>Setup</h2><p>This library is already published as an Apps Script, making it easy to include
@@ -257,7 +257,27 @@ <h4>Storing token-related data</h4><p>Some OAuth providers return IDs and other
     }
   });</code></pre><p>Note that calling <code>Service.reset()</code> will remove all custom values from storage,
 in addition to the token.</p>
-<h4>Using service accounts</h4><p>This library supports the service account authorization flow, also known as the
+<h4>Passing additional parameters to the callback function</h4><p>There are occasionally cases where you need to preserve some data through the
+OAuth flow, so that it is available in your callback function. Although you
+could use the token storage mechanism discussed above for that purpose, writing
+to the PropertiesService is expensive and not neccessary in the case where the
+user doesn't start or fails to complete the OAuth flow.</p>
+<p>As an alternative you can store small amounts of data in the OAuth2 <code>state</code>
+token, which is a standard mechanism for this purpose. To do so, pass an
+optional hash of parameter names and values to the <code>getAuthorizationUrl()</code>
+method:</p>
+<pre class="prettyprint source lang-js"><code>var authorizationUrl = getService().getAuthorizationUrl({
+  // Pass the additional parameter &quot;lang&quot; with the value &quot;fr&quot;.
+  lang: 'fr'
+});</code></pre><p>These values will be stored along-side Apps Script's internal information in the
+encypted <code>state</code> token, which is passed in the authorization URL and passed back
+to the redirect URI. The <code>state</code> token is automatically decrypted in the
+callback function and you can access your parameters using the same
+<code>request.parameter</code> field used in web apps:</p>
+<pre class="prettyprint source lang-js"><code>function authCallback(request) {
+  var lang = request.parameter.lang;
+  // ...
+}</code></pre><h4>Using service accounts</h4><p>This library supports the service account authorization flow, also known as the
 <a href="https://tools.ietf.org/html/draft-ietf-oauth-jwt-bearer-12">JSON Web Token (JWT) Profile</a>.
 This is a two-legged OAuth flow that doesn't require a user to visit a URL and
 authorize access.</p>
@@ -669,7 +689,7 @@ <h2><a href="index.html">Home</a></h2><h3>Classes</h3><ul><li><a href="Service_.
 <br class="clear">
 
 <footer>
-    Documentation generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 3.5.5</a> on Thu Sep 27 2018 14:12:43 GMT-0700 (PDT)
+    Documentation generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 3.5.5</a> on Wed Nov 14 2018 09:13:44 GMT-0500 (EST)
 </footer>
 
 <script> prettyPrint(); </script>

package.json

@@ -1,6 +1,6 @@
 {
   "name": "apps-script-oauth2",
-  "version": "1.30.0",
+  "version": "1.31.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",