Renamed function to getNewAccessTokenUsingRefreshToken and added more documentation in the README

Author: lmammino

README.md

@@ -31,14 +31,14 @@ fastify.register(oauthPlugin, {
 })
 
 fastify.get('/login/facebook/callback', async function (request, reply) {
-  const result = await this.getAccessTokenFromAuthorizationCodeFlow(request)
+  const token = await this.getAccessTokenFromAuthorizationCodeFlow(request)
 
-  console.log(result.access_token)
+  console.log(token.access_token)
 
   // if later you need to refresh the token you can use
-  // this.getNewAccessTokenWithRefreshToken(result.refresh_token)
+  // const newToken = await this.getNewAccessTokenUsingRefreshToken(token.refresh_token)
 
-  reply.send({ access_token: result.access_token })
+  reply.send({ access_token: token.access_token })
 })
 ```
 
@@ -51,6 +51,17 @@ See [facebook example](./examples/facebook.js) for an example.
 This fastify plugin decorates the fastify instance with the [`simple-oauth2`](https://github.com/lelylan/simple-oauth2)
 instance.
 
+## Utilities
+
+This fastify plugin adds 2 utility decorators to your fastify instance:
+
+  - `getAccessTokenFromAuthorizationCodeFlow(request, callback)`: A function that uses the Authorization code flow to fetch an OAuth2 token using the data in the last request of the flow. If the callback is not passed it will return a promise. The object resulting from the callback call or the promise resolution is a *token response* object containing the following keys:
+    - `access_token`
+    - `refresh_token` (optional, only if the `offline scope` was originally requested)
+    - `token_type` (generally `'bearer'`)
+    -  `expires_in` (number of seconds for the token to expire, e.g. `240000`)
+  - `getNewAccessTokenUsingRefreshToken(refreshToken, params, callback)`: A function that takes a refresh token and retrieves a new *token response* object. This is generally useful with background processing workers to re-issue a new token when the original token has expired. The `params` argument is optional and it's an object that can be used to pass in extra parameters to the refresh request (e.g. a stricter set of scopes). If the callback is not passed this function will return a promise. The object resulting from the callback call or the promise resolution is a new *token response* object (see fields above).
+
 ## License
 
 Licensed under [MIT](./LICENSE).

index.js

@@ -94,25 +94,25 @@ const oauthPlugin = fp(function (fastify, options, next) {
     getAccessTokenFromAuthorizationCodeFlowCallbacked(request, callback)
   }
 
-  function getNewAccessTokenWithRefreshTokenCallbacked (refreshToken, params, callback) {
+  function getNewAccessTokenUsingRefreshTokenCallbacked (refreshToken, params, callback) {
     const accessToken = fastify[name].accessToken.create({ refresh_token: refreshToken })
     accessToken.refresh(params, callback)
   }
-  const getNewAccessTokenWithRefreshTokenPromisified = promisify(getNewAccessTokenWithRefreshTokenCallbacked)
+  const getNewAccessTokenUsingRefreshTokenPromisified = promisify(getNewAccessTokenUsingRefreshTokenCallbacked)
 
-  function getNewAccessTokenWithRefreshToken (refreshToken, params, callback) {
+  function getNewAccessTokenUsingRefreshToken (refreshToken, params, callback) {
     if (!callback) {
-      return getNewAccessTokenWithRefreshTokenPromisified(refreshToken, params)
+      return getNewAccessTokenUsingRefreshTokenPromisified(refreshToken, params)
     }
-    getNewAccessTokenWithRefreshTokenCallbacked(refreshToken, params, callback)
+    getNewAccessTokenUsingRefreshTokenCallbacked(refreshToken, params, callback)
   }
 
   const oauth2 = oauth2Module.create(credentials)
 
   if (startRedirectPath) {
     fastify.get(startRedirectPath, startRedirectHandler)
     fastify.decorate('getAccessTokenFromAuthorizationCodeFlow', getAccessTokenFromAuthorizationCodeFlow)
-    fastify.decorate('getNewAccessTokenWithRefreshToken', getNewAccessTokenWithRefreshToken)
+    fastify.decorate('getNewAccessTokenUsingRefreshToken', getNewAccessTokenUsingRefreshToken)
   }
 
   try {

test.js

@@ -84,7 +84,7 @@ t.test('fastify-oauth2', t => {
         if (err) throw err
 
         // attempts to refresh the token
-        this.getNewAccessTokenWithRefreshToken(result.refresh_token, undefined, (err, result) => {
+        this.getNewAccessTokenUsingRefreshToken(result.refresh_token, undefined, (err, result) => {
           if (err) throw err
 
           const newToken = result
@@ -125,7 +125,7 @@ t.test('fastify-oauth2', t => {
       return this.getAccessTokenFromAuthorizationCodeFlow(request)
         .then(result => {
           // attempts to refresh the token
-          return this.getNewAccessTokenWithRefreshToken(result.refresh_token)
+          return this.getNewAccessTokenUsingRefreshToken(result.refresh_token)
         })
         .then(token => {
           return {