Cookie Management

Rezo includes a full-featured cookie system built on top of tough-cookie. The RezoCookieJar class handles automatic cookie injection and extraction for every request, supports multiple serialization formats, and provides file-based persistence.

Automatic Cookie Handling

By default, every Rezo instance has its own cookie jar. Cookies from Set-Cookie response headers are automatically stored, and matching cookies are sent with subsequent requests — no manual intervention required.

import { Rezo } from 'rezo';

const rezo = new Rezo();

// Login -- session cookies are stored automatically
await rezo.post('https://api.example.com/login', {
  username: 'admin',
  password: 'secret'
});

// Subsequent requests include the session cookie
const profile = await rezo.get('https://api.example.com/profile');
console.log(profile.data);

Cookies respect domain, path, secure flag, and expiry rules. Rezo uses tough-cookie internally for full RFC 6265 compliance.

RezoCookieJar

The RezoCookieJar extends tough-cookie’s CookieJar with extra convenience methods. You can also import it as CookieJar.

import { RezoCookieJar, CookieJar } from 'rezo';

// These are the same class
const jar = new RezoCookieJar();
const jar2 = new CookieJar();

Constructor Overloads

// Empty jar
const jar = new RezoCookieJar();

// From an array of Cookie objects
const jar = new RezoCookieJar(cookies);

// From cookies with a default URL for domain resolution
const jar = new RezoCookieJar(cookies, 'https://example.com');

// From a tough-cookie Store (advanced)
const jar = new RezoCookieJar(store, options);

Passing a Jar to Rezo

import { Rezo, RezoCookieJar } from 'rezo';

const jar = new RezoCookieJar();

const rezo = new Rezo({ jar });

All requests from this instance share the same jar. You can also access the jar later:

const rezo = new Rezo();

// Read the jar
const jar = rezo.jar;

// Replace the jar
rezo.jar = new RezoCookieJar();

setCookiesSync()

Load cookies into the jar from various input formats. All overloads return a Cookies object containing the parsed results.

From Set-Cookie String Array

jar.setCookiesSync([
  'session=abc123; Domain=example.com; Path=/; HttpOnly',
  'theme=dark; Domain=example.com; Path=/'
]);

From Set-Cookie Strings with a URL

When cookies lack a Domain attribute, provide a URL so tough-cookie can infer the domain:

jar.setCookiesSync([
  'token=xyz; Path=/; Secure',
  'lang=en; Path=/'
], 'https://api.example.com');

From a Cookie String

A plain key=value; key=value string (the format browsers send in the Cookie header):

jar.setCookiesSync('session=abc123; theme=dark', 'https://example.com');

From Serialized JSON Cookies

const serialized = [
  { key: 'session', value: 'abc123', domain: 'example.com', path: '/' },
  { key: 'theme', value: 'dark', domain: 'example.com', path: '/' }
];

jar.setCookiesSync(serialized);

From Cookie Objects

import { Cookie } from 'rezo';

const cookies = [
  new Cookie({ key: 'session', value: 'abc123', domain: 'example.com' }),
  new Cookie({ key: 'theme', value: 'dark', domain: 'example.com' })
];

jar.setCookiesSync(cookies);

From Netscape Format

Netscape cookie file content (tab-separated format) is also accepted as a string:

const netscape = `.example.com	TRUE	/	FALSE	0	session	abc123`;
jar.setCookiesSync(netscape, 'https://example.com');

getCookies() Formats

The cookies() method returns a Cookies object with five format views of the same data:

const cookies = jar.cookies();

// Or filter by URL
const cookies = jar.cookies('https://api.example.com/v1');

array

An array of Cookie objects with full metadata (domain, path, expires, secure, httpOnly, sameSite):

cookies.array.forEach(cookie => {
  console.log(`${cookie.key}=${cookie.value} (domain: ${cookie.domain})`);
});

serialized

An array of plain JSON-serializable objects — suitable for storing in a database or sending over an API:

const json = JSON.stringify(cookies.serialized);
// Later:
jar.setCookiesSync(JSON.parse(json));

netscape

A string in Netscape cookie file format, ready to write to a .txt file:

console.log(cookies.netscape);
// # Netscape HTTP Cookie File
// # This file was generated by Rezo HTTP client
// .example.com	TRUE	/	FALSE	0	session	abc123

string

A Cookie header value (key=value; key=value):

console.log(cookies.string);
// session=abc123; theme=dark

setCookiesString

An array of Set-Cookie header strings:

console.log(cookies.setCookiesString);
// ['session=abc123; Domain=example.com; Path=/', 'theme=dark; Domain=example.com; Path=/']

Shorthand Methods

jar.toArray();               // Same as jar.cookies().array
jar.toSerializedCookies();   // Same as jar.cookies().serialized
jar.toNetscapeCookie();      // Same as jar.cookies().netscape
jar.toCookieString();        // Same as jar.cookies().string
jar.toSetCookies();          // Same as jar.cookies().setCookiesString

getCookiesForRequest()

Returns only the cookies that should be sent for a specific URL, respecting domain matching, path matching, secure flag, and expiry:

const cookies = jar.getCookiesForRequest('https://api.example.com/v1/users');
console.log(cookies); // Only cookies matching api.example.com with path /v1/users

getCookieHeader()

Returns the ready-to-use Cookie header string for a URL:

const header = jar.getCookieHeader('https://api.example.com/v1/users');
console.log(header); // "session=abc123; api_key=xyz"

Debugging

The debugCookiesForRequest() method shows exactly which cookies would match a given URL:

const debug = jar.debugCookiesForRequest('https://api.example.com/v1');
console.log(debug);
// {
//   url: 'https://api.example.com/v1',
//   matchingCookies: [{ key: 'session', value: 'abc123', domain: 'example.com', path: '/' }],
//   cookieHeader: 'session=abc123',
//   allCookies: [{ key: 'session', domain: 'example.com', path: '/' }, ...]
// }

Cookie File Persistence

Rezo supports automatic cookie persistence to .json or .txt (Netscape) files.

cookieFile Option

The simplest approach — pass a cookieFile path when creating the Rezo instance:

const rezo = new Rezo({
  cookieFile: './cookies.json'
});

// Cookies are loaded from the file on startup.
// After requests, save them back:
rezo.saveCookies();

If the file does not exist, Rezo starts with an empty jar and creates the file on the first save.

JSON Format (.json)

jar.loadFromFile('./cookies.json');

// ... make requests ...

jar.saveToFile('./cookies.json');

The JSON file stores cookies in a structured format:

{
  "version": 1,
  "cookies": [
    { "key": "session", "value": "abc123", "domain": "example.com", "path": "/", ... }
  ]
}

Netscape Format (.txt)

jar.loadFromFile('./cookies.txt');

// ... make requests ...

jar.saveToFile('./cookies.txt');

The format matches what cURL and browsers use for cookie file exchange.

Factory Method

Create a jar directly from a file:

const jar = RezoCookieJar.fromFile('./cookies.json');

const rezo = new Rezo({ jar });

Saving After Requests

const rezo = new Rezo({ cookieFile: './session-cookies.json' });

await rezo.get('https://example.com/login');

// Persist cookies to disk
rezo.saveCookies();

// Or save to a different path
rezo.saveCookies('./backup-cookies.json');

Static Utilities

netscapeCookiesToSetCookieArray

Convert Netscape format text into an array of Set-Cookie header strings:

const setCookies = RezoCookieJar.netscapeCookiesToSetCookieArray(netscapeText);
// ['session=abc123; Domain=.example.com; Path=/; Secure', ...]

toNetscapeCookie (static)

Convert an array of cookies to Netscape format:

const netscape = RezoCookieJar.toNetscapeCookie(cookieArray);

toCookieString (static)

Convert an array of cookies to a cookie string:

const cookieStr = RezoCookieJar.toCookieString(cookieArray);

Disabling the Cookie Jar

To make requests without automatic cookie handling, set disableJar on the instance:

const rezo = new Rezo({
  disableJar: true
});

With disableJar: true, response cookies are not stored and no Cookie header is automatically added to requests.