v0.1.3 - Update the docs, add accessToken property for refreshToken support

LICENSE

@@ -0,0 +1,7 @@
+ 
+Copyright 2017 Nicholas Tay <[email protected]>
+
+Permission to use, copy, modify, and/or distribute this software for any purpose with or without fee is hereby granted, provided that the above copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+ 

README.md

@@ -2,7 +2,9 @@
 
 Passport strategy for authentication with [Discord](http://discordapp.com) through the OAuth 2.0 API.
 
-At time of writing there is no official page/documentation for this, so information can be read off the example project, such as how to set up an API application [here](http://github.com/vishnevskiy/discord-oauth2-example).
+~~At time of writing there is no official page/documentation for this, so information can be read off the example project, such as how to set up an API application [here](http://github.com/vishnevskiy/discord-oauth2-example).~~ This is actually no longer the case! Docs hooray!
+
+Before using this strategy, it is strongly recommended that you read through the official docs page [here](https://discordapp.com/developers/docs/topics/oauth2), especially about the scopes and understand how the auth works.
 
 ## Usage
 `npm install passport-discord --save`
@@ -13,18 +15,19 @@ The Discord authentication strategy authenticates users via a Discord user accou
 ```javascript
 var DiscordStrategy = require('passport-discord').Strategy;
 
-passport.use(new DiscordStrategy(
-    {
-        clientID: 'id',
-        clientSecret: 'secret',
-        callbackURL: 'callbackURL'
-    },
-    function(accessToken, refreshToken, profile, cb) {
-        User.findOrCreate({ discordId: profile.id }, function(err, user) {
-            return cb(err, user);
-        });
-    }
-));
+passport.use(new DiscordStrategy({
+    clientID: 'id',
+    clientSecret: 'secret',
+    callbackURL: 'callbackURL'
+},
+function(accessToken, refreshToken, profile, cb) {
+    if (err)
+        return done(err);
+
+    User.findOrCreate({ discordId: profile.id }, function(err, user) {
+        return cb(err, user);
+    });
+}));
 ```
 
 #### Authentication Requests
@@ -45,7 +48,48 @@ If using the `bot` scope, the `permissions` option can be set to indicate
 specific permissions your bot needs on the server ([permission codes](https://discordapp.com/developers/docs/topics/permissions)):
 
 ```javascript
-app.get("/auth/discord", passport.authenticate("discord", {permissions: 66321471}));
+app.get("/auth/discord", passport.authenticate("discord", { permissions: 66321471 }));
+```
+
+#### Refresh Token Usage
+In some use cases where the profile may be fetched more than once or you want to keep the user authenticated, refresh tokens may wish to be used. A package such as `passport-oauth2-refresh` can assist in doing this.
+
+Example:
+
+`npm install passport-oauth2-refresh --save`
+
+```javascript
+var DiscordStrategy = require('passport-discord').Strategy
+  , refresh = require('passport-oauth2-refresh');
+
+var discordStrat = new DiscordStrategy({
+    clientID: 'id',
+    clientSecret: 'secret',
+    callbackURL: 'callbackURL'
+},
+function(accessToken, refreshToken, profile, cb) {
+    profile.refreshToken = refreshToken; // store this for later refreshes
+    User.findOrCreate({ discordId: profile.id }, function(err, user) {
+        if (err)
+            return done(err);
+
+        return cb(err, user);
+    });
+});
+
+passport.use(discordStrat);
+refresh.use(discordStrat);
+```
+
+... then if we require refreshing when fetching an update or something ...
+
+```javascript
+refresh.requestNewAccessToken('discord', profile.refreshToken, function(err, accessToken, refreshToken) {
+    if (err)
+        throw; // boys, we have an error here.
+    
+    profile.accessToken = accessToken; // store this new one for our new requests!
+});
 ```
 
 
@@ -54,3 +98,6 @@ An Express server example can be found in the `/example` directory. Be sure to `
 
 ## Credits
 * Jared Hanson - used passport-github to understand passport more and kind of as a base.
+
+## License
+Licensed under the ISC license. The full license text can be found in the root of the project repository.

lib/strategy.js

@@ -21,7 +21,7 @@ var OAuth2Strategy      = require('passport-oauth2')
  *   - `clientSecret`   OAuth Secret to verify client to discord
  *   - `callbackURL`    URL that discord will redirect to after auth
  *   - `scope`          Array of permission scopes to request
- *                      Valid discord scopes include: 'identity', 'email', 'connections', 'guilds', 'guilds.join'
+ *                      Check the official documentation for valid scopes to pass as an array.
  * 
  * @constructor
  * @param {object} options
@@ -47,9 +47,12 @@ util.inherits(Strategy, OAuth2Strategy);
 /**
  * Retrieve user profile from Discord.
  *
- * This function constructs a normalized profile, with the following properties:
- *
- *   - `something`      ayy lmao
+ * This function constructs a normalized profile.
+ * Along with the properties returned from /users/@me, properties returned include:
+ *   - `connections`      Connections data if you requested this scope
+ *   - `guilds`           Guilds data if you requested this scope
+ *   - `fetchedAt`        When the data was fetched as a `Date`
+ *   - `accessToken`      The access token used to fetch the (may be useful for refresh)
  *
  * @param {string} accessToken
  * @param {function} done
@@ -71,6 +74,7 @@ Strategy.prototype.userProfile = function(accessToken, done) {
 
         var profile = parsedData; // has the basic user stuff
         profile.provider = 'discord';
+        profile.accessToken = accessToken;
 
         self.checkScope('connections', accessToken, function(errx, connections) {
             if (errx) done(errx);
@@ -79,6 +83,7 @@ Strategy.prototype.userProfile = function(accessToken, done) {
                 if (erry) done(erry);
                 if (guilds) profile.guilds = guilds;
 
+                profile.fetchedAt = new Date();
                 return done(null, profile)
             });
         });
@@ -111,7 +116,7 @@ Strategy.prototype.checkScope = function(scope, accessToken, cb) {
  */
 Strategy.prototype.authorizationParams = function(options) {
     var params = {};
-    if (typeof options.permissions !== "undefined") {
+    if (typeof options.permissions !== 'undefined') {
         params.permissions = options.permissions;
     }
     return params;

package.json

@@ -1,6 +1,6 @@
 {
   "name": "passport-discord",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "Passport strategy for authentication with Discord (discordapp.com)",
   "main": "lib/index.js",
   "repository": {