# fetch-cookie [![npm version](https://badge.fury.io/js/fetch-cookie.svg)](https://badge.fury.io/js/fetch-cookie) [![Build Status](https://travis-ci.org/valeriangalliat/fetch-cookie.svg?branch=master)](https://travis-ci.org/valeriangalliat/fetch-cookie)

> Decorator for a `fetch` function to support automatic cookie storage and population.

## Description

`fetch-cookie` wraps arround a `fetch` function and **intercepts request options and response
objects to store received cookies and populate request with the appropriate cookies**.

This library is developed with Node.Js and fetch polyfill libraries such as [node-fetch] in mind, since
the browser version is supposed to let a way [to include cookies in requests][include].
Compatibility may not be guaranteed but as long as your library implements the [Fetch Standard] you should be fine.
In case of incompatibilities, please create a new issue.

[Fetch Standard]: https://fetch.spec.whatwg.org/
[node-fetch]: https://www.npmjs.com/package/node-fetch
[include]: http://updates.html5rocks.com/2015/03/introduction-to-fetch#sending-credentials-with-a-fetch-request

Internally the plugin uses a cookie jar. You can insert your own (details below) but [tough-cookie] is preferred.

[tough-cookie]: https://www.npmjs.com/package/tough-cookie

## Usage

### Basic

```js
const nodeFetch = require('node-fetch')
const fetch = require('fetch-cookie')(nodeFetch)
```

### Custom cookie jar

If you want to customize the internal cookie jar instance (for example, with a custom store), you can inject it as a second argument:

```js
const nodeFetch = require('node-fetch')
const tough = require('tough-cookie')
const fetch = require('fetch-cookie')(nodeFetch, new tough.CookieJar())
```

This enables you to create multiple `fetch-cookie` instances that use different cookie jars,
esentially two different HTTP clients with different login sessions on you backend (for example).

All calls to `fetch` will store and send back cookies according to the URL.

> Note: All errors when setting cookies are ignored by default. You can make it to throw errors in cookies by passing a third argument (default is true).

```js
const nodeFetch = require('node-fetch')
const tough = require('tough-cookie')
const fetch = require('fetch-cookie')(nodeFetch, new tough.CookieJar(), false) // default value is true
// false - doesn't ignore errors, throws when an error occurs in setting cookies and breaks the request and execution
// true - silently ignores errors and continues to make requests/redirections
```

If you use a cookie jar that is not tough-cookie, keep in mind that it must implement this interface to be compatible:

```ts
interface CookieJar {
  getCookieString(currentUrl: string, cb: (err: any, cookies: string) => void): void;
  setCookie(cookieString: string, currentUrl: string, cb: (err: any) => void, opts: { ignoreError:boolean }): void;
}
```

### Cookies on redirects

**Details:** By default, cookies are not set correctly in the edge case where a response
sets cookies and redirects to another URL. A real-life example of this behaviour
is a login page setting a session cookie and redirecting.

The reason for this limitation is that the generic fetch API does not allow any way to
hook into redirects. However, the [node-fetch] library does expose its own API which
we can use.

**TLDR:** Ff cookies during indirection turns out to be a requirement for you,
and if you are using [node-fetch], then you can use the custom node-fetch decorator
provided with this library:

```js
const nodeFetch = require('node-fetch')
const fetch = require('fetch-cookie/node-fetch')(nodeFetch)
```