npm package: @shoutem/fetch-token-intercept
Description: Fetch interceptor for managing refresh token flow.
Author: Shoutem
Latest version: 0.2.2

[![CircleCI](https://img.shields.io/circleci/project/github/shoutem/fetch-token-intercept.svg)](https://github.com/shoutem/fetch-token-intercept)
[![Code Climate](https://img.shields.io/codeclimate/github/shoutem/fetch-token-intercept.svg)]()
[![GitHub license](https://img.shields.io/badge/license-New%20BSD-blue.svg)](https://raw.githubusercontent.com/shoutem/fetch-token-intercept/master/LICENSE)

# fetch-token-intercept
Library for easy renewing of access tokens in OAuth's refresh token flow. This library will monkey
patch fetch on your target environment and will try to resolve unauthorized requests automatically
by renewing the current access token and then retrying an initial fetch operation.

If you are not familiar with refresh token flow you should check some of the following resources:
- [RFC standards track regarding refresh token flow](https://tools.ietf.org/html/rfc6749#page-10)
- [Auth0 blog - Refresh Tokens: When to Use Them and How They Interact with JWTs](https://auth0.com/blog/refresh-tokens-what-are-they-and-when-to-use-them/)
- [Shoutem blog - Keeping your tokens fresh](https://medium.com/shoutem/keeping-your-api-tokens-fresh-72059a7b0586)

>Note:
This library expects that fetch and promise api's are available at target environment. You should
provide a polyfill when necessary.

## Installation

`fetch-token-intercept` is available on [npm](https://www.npmjs.com/package/@shoutem/fetch-token-intercept).

```
$ npm install @shoutem/fetch-token-intercept --save
```

## Getting started

Before making any fetch requests you should `configure` and `authorize` this library to support
interception.

Configuration is provided via `config` object:

```
config: {
  // (Required) Prepare fetch request for renewing new access token
  createAccessTokenRequest: (refreshToken) => request,
   
  // (Required) Parses access token from access token response
  parseAccessToken: (response) => accessToken,
   
  // (Required) Defines whether interceptor will intercept this request or just let it pass through
  shouldIntercept: (request) => boolean,
   
  // (Required) Defines whether access token will be invalidated after this response
  shouldInvalidateAccessToken: (response) => boolean,
  
  // When set, response which invalidates token will be resolved after the token has been renewed
  // in effect, token will be loaded in sync with response, otherwise renew will run async to response
  shouldWaitForTokenRenewal: boolean,
  
  // Checks if response should be considered unauthorized (by default only 401 responses are 
  // considered unauthorized). Override this method if you need to trigger token renewal for 
  // other response statuses. Check API reference for helper method which defines default behaviour
  isResponseUnauthorized: (response) => boolean,
   
  // (Required) Adds authorization for intercepted requests
  authorizeRequest: (request, accessToken) => authorizedRequest,
   
  // Number of retries after initial request was unauthorized
  fetchRetryCount: 1,
  
  // Event invoked when access token has changed
  onAccessTokenChange: null,
   
  // Event invoked when response is resolved
  onResponse: null,
}
```

All required methods return a promise to enable reading of request or response body.
You should avoid reading the body directly on provided requests and responses and instead clone 
them first. The library does not clone objects to avoid unnecessary overhead in cases where 
reading a body is not required to provide data.

To configure the interceptor you should import and call `configure` function. And when you obtain
a refresh token you should call `authorize`, which accepts refresh and access tokens.

```
   import { configure, authorize } from '@shoutem/fetch-token-intercept';

   ...
   configure(configuration);
   // perform authentication with user credentials against your auth server
   // when you recieve refresh token (and optionally access token) provide them to interceptor lib
   authorize(refreshToken, accessToken);
   ...
```

User is now logged in with provided refresh token. If refresh token invalidates interceptor
will automatically clear both tokens and further requests won't be intercepted. You should redirect
user to authentication screen and re-authorize interceptor on successful authentication.

To manually clear tokens you can call clear method. You should call this when user log outs manually
to stop fetch interception.

```
   import { clear } from '@shoutem/fetch-token-intercept';

   ...
   clear();
   ...
```

## API reference <a name="api-reference"></a>

### Exports
 `configure(configuration)`
 
 Configures fetch token interceptor with provided configuration object.
 
 `authorize(refreshToken, accessToken)` 
  
  Authorizes fetch token interceptor with provided tokens.
  
 `clear()`
 
 Clears all tokens from interceptor.
 
 `isResponseUnauthorized(response)`
 
 Utility method which determines if given response should be considered unauthorized. 
 By default, responses with status code `401` are considered unauthorized.
 You can use this method in `isResponseUnauthorized` of `config` object 
 when you want to extend default behaviour.
 
 
## Tests

```
$ npm install && npm run test
``` 

## License
 
 BSD