Browser SDK

Install

npm install @mybeast/sessions

Plain ES modules, with no build step and no framework of its own: it works on any page, React or not. It brings @rrweb/record, pinned to one version. Pages need an evergreen browser; without CompressionStream the recorder does nothing. Build with Node 20 or later.

rrweb is about 160 KB, and only the recorder imports it. To keep it out of your main bundle, import the SDK later:

// Keep rrweb out of your main bundle: load the recorder once the page has loaded.
window.addEventListener('load', async () => {
    const { init, createRecorder } = await import('@mybeast/sessions');
    createRecorder(init(config), options).start();
});

init and the recorder

import { init, createRecorder } from '@mybeast/sessions';

// config: what your server made with Sessions::clientConfig(): {url, key, env, token}
const client = init(config); // null when anything is malformed: the recorder then does nothing

const recorder = createRecorder(client, {
    getToken: async () => (await fetch('/sessions/token')).text(), // your route: a fresh token, or null
    dictionary: () => messages,                // the only words a masked recording keeps readable
    currentPage: () => currentRouteName,       // your page name for the page marks
    onChange: (state) => {},                   // {status, recording, upload}
});
recorder.start();

// Each response that brings a new token, before the new page is drawn:
recorder.setToken(newToken);
// A page change without a page load:
recorder.pageChanged('Invoice/Show');

init(config) reads what your server made with Sessions::clientConfig(). It returns null when anything is malformed: a service URL that isn't https (plain http only on localhost, 127.0.0.1, *.localhost and *.test), or a key that isn't a public key. A token for another project, or one it can't read, counts as no token.

createRecorder(client, options) makes the recorder of one page load: call it once. With a null client it gives a recorder that does nothing, so your code needs no checks.

Options

All optional.

The masking options are explained in Mask what a recording shows.

The recorder's methods

What it sends and when

• One recording per tab, carried across full page loads. A duplicated tab takes its own. A new recording starts after idleMinutes without input, after maxMinutes, for another person or account, and for another mask.
• A chunk every 5 seconds and on every page change, one request at a time: the compressed JSON of rrweb's events, with the token it was recorded under.
• As the page goes away, the last chunk rides a keepalive request when it's under 60,000 bytes. What couldn't be sent waits in the tab for the next page, without its token.
• Before the yes, nothing: while the browser's clock is behind the token's consent_at, recording waits.

Each chunk is a plain request, with no cookies and no headers of your page's:

POST {url}/v1/parts/{recording}?key=pk_…&t=<token>&doc=<n>&seq=<n>

While recording, your page's own fetch and XMLHttpRequest calls to its own origin carry X-Recording-Id and X-Recording-At (milliseconds into the recording), never a request to another origin or to Sessions. A header your page set itself is kept.

The service's answers

A 403's body says why, in refused:

The last answer is in state().upload, and answerFor(status, refused) is exported.

Marks

The recorder marks moments in the recording on its own: env at each page load (path, screen size, language, theme, whether the browser translated it, whether it's masked), page, press (a control's spoken label), dialog (opened or closed, with its title), hidden and visible, pagehide, and error (the browser's errors and unhandled rejections: the name and masked message only).

Add your own with mark(tag, payload). A host that knows its requests and forms can add visit, refused and broken; visitPayload() and refusedPayload() build their payloads:

import { refusedPayload } from '@mybeast/sessions';

// The server sent a form back: the refused fields' names, and the first message,
// which a masked recording keeps only when it's an i18n key such as 'rules.email'.
recorder.mark('refused', refusedPayload(errors));

The masking helpers

@mybeast/sessions/mask is the masking alone, without rrweb: mask your own telemetry the same way as the recordings, such as an error report's button labels. Both entry points export uiStrings, buildUiMasker, createTextMask, createMask, maskUrl, dropIds, scrubFreeText, star, urlRules, PRIVATE_SELECTORS, BLOCK_SELECTORS and EXAMPLE_KEY.

TypeScript

The types are in the package, for @mybeast/sessions and @mybeast/sessions/mask: SessionsConfig, SessionsClient, RecorderOptions, Recorder, RecorderState, CurrentRecording, UploadAnswer, Dictionary and the rest. Nothing to install.