# REVU Developers - Full Documentation

> Official documentation for the REVU SDKs. One-line autocapture, first-party identity, and durable batched transport. Built so any developer, LLM, or AI agent can integrate REVU effortlessly.

---

# Web SDK: Overview
Source: https://developers.revu.ai/web/

# Documentation

The reference manual for `@revu-ai/core`. The [package README](/web/)
covers the pitch, install, and your first event in 60 seconds; this tree
covers everything else.

## A short tour

If you have five minutes, read in this order:

1. **[Concepts](/web/concepts/)** for the mental model: two ids
   (`anonymous_id` for the device, `user_id` for the person), one
   rolling session, and one canonical event shape that the rest of the
   SDK is just plumbing for.
2. **[Public API](/web/api/)** for the public surface you will actually
   call: the methods `init`, `capture`, `identify`, `alias`, `reset`,
   `flush`, and `use`, plus the `version` property. Most hosts only ever
   touch `init`, `identify`, `capture`, and `reset`.
3. **[Configuration](/web/configuration/)** for every option, with
   defaults and "use when" notes. Includes the
   [sessionTimeoutMs callout](/web/configuration/#sessiontimeoutms-sessions-are-engagement-not-page-visits)
   on why a session continues across reloads, SPA route changes, and
   second tabs by default (and how to change that).

The other four pages are reference material you reach for when you need
them, not front-to-back reading.

## All pages

### Using the SDK

- **[Install](/web/install/)** - the CDN `<script>` snippet, the npm
  install, version pinning on `cdn.revu.ai`, and SRI hashes.
- **[Public API](/web/api/)** - `init`, `capture`, `identify`, `alias`,
  `reset`, `flush`, `use`, `version`, and the `RevuClient` class.
  Signature, example, and edge cases per method.
- **[Configuration](/web/configuration/)** - every option you can pass
  to `init()`. Default, type, and a one-line "use when" note. The
  `sessionTimeoutMs` callout is here.

### Understanding the SDK

- **[Concepts](/web/concepts/)** - `anonymous_id` vs `user_id`,
  session continuation, the canonical event shape, and the
  "interactions, never values" rule.
- **[Privacy and data](/web/privacy/)** - what is masked by default,
  `data-revu-mask` for opting subtrees out, what the SDK does not
  parse client-side, opt-out patterns.
- **[Transport and offline](/web/transport/)** - the ingest endpoint,
  flush triggers, the durable localStorage queue, retry and backoff,
  and the dual-signal terminal flush that makes mobile Safari reliable.
- **[First-party ingest](/web/first-party-ingest/)** - route events
  through your own domain for first-party data completeness, with
  copy-paste reverse-proxy recipes (Cloudflare, nginx, Caddy, Next.js).

### Extending and operating the SDK

- **[Plugins](/web/plugins/)** - the plugin contract, how to register,
  when to ship as a subpath plugin vs a separate package, and a worked
  example.
- **[Troubleshooting](/web/troubleshooting/)** - common failures and
  how to isolate them: CSP, `sendBeacon` Content-Type, mobile Safari
  terminal events, durable queue origin scoping, identify and reset
  semantics, unexpected session rotation.

## Common starting points

Looking for something specific?

- **"My events do not arrive."** Start at
  [troubleshooting.md - events do not appear in the dashboard](/web/troubleshooting/#events-do-not-appear-in-the-dashboard).
- **"Why does every page load not start a new session?"** Read
  [configuration.md - sessions are engagement, not page visits](/web/configuration/#sessiontimeoutms-sessions-are-engagement-not-page-visits).
- **"How do I track the same user across two devices?"** See
  [`revu.alias()`](/web/api/#revualiasauthoritativeid).
- **"What does the SDK send, exactly?"** See
  [the canonical event shape](/web/concepts/#the-canonical-event-shape).
- **"How do I mask a PII region or a sensitive form?"** See
  [`data-revu-mask`](/web/privacy/#data-revu-mask).
- **"How do I add my own event type without bloating core?"** See
  [the plugin contract](/web/plugins/#the-contract).

## A note on the source

JSDoc in `src/types.js` is the source of truth for parameter and
return types. These pages document semantics, defaults, and edge cases.
For the canonical type signatures, look at the JSDoc or the emitted
`.d.ts` after `bun run types`.

---

# Web SDK: Install
Source: https://developers.revu.ai/web/install/

# Install

Two paths, pick the one that matches how your site is built.

## Path 1: CDN snippet

Paste these tags into your `<head>`:

```html
<script async src="https://cdn.revu.ai/behavior"></script>
<script>
  window.revu = window.revu || new Proxy({q:[]}, {
    get: (t, m) => m in t ? t[m] : (...a) => t.q.push([m, ...a]),
  });
  revu.init({ apiKey: "revu_pk_..." });
</script>
```

What this does:

1. The first tag starts fetching the SDK bundle in parallel with HTML
   parsing (`async`). It does not block the browser.
2. The inline `<script>` runs immediately. It installs a small `Proxy`
   stub at `window.revu` that buffers any `revu.x(...)` call into a
   queue (`revu.q`), then calls `revu.init(...)`, which gets queued like
   any other call.
3. When the bundle finishes loading, it reads the queue, replays every
   call against the real SDK in arrival order (so the queued
   `revu.init` actually runs, the SDK comes online, autocapture starts),
   then replaces the stub with the live singleton. Subsequent calls go
   straight through.

The stub queue is what makes the install bulletproof. Anything that
fires between "snippet runs" and "SDK finishes loading" - a tag manager
call, an inline `onclick="revu.capture(...)"` handler, a cookie banner
consent event, a server-rendered identity injection, a click on a CTA
before the page settles - is queued and replayed instead of silently
lost. The stub is ~100 bytes inline, future-proof for any method we
add later (the `Proxy` covers method names dynamically), and disappears
entirely once the SDK takes over.

### Version pinning on the CDN

The `cdn.revu.ai` URL path encodes how tightly you pin to a release.
Pick the form that matches your stability needs.

| URL form | Resolves to | Cache | Use when |
|---|---|---|---|
| `cdn.revu.ai/behavior/1.2.3` | The exact 1.2.3 release | One year, immutable | Maximum stability; you opt into every version bump by editing the URL. |
| `cdn.revu.ai/behavior/latest` | The newest published release | Five minutes | You want updates automatically and accept the responsibility of testing across releases. |
| `cdn.revu.ai/behavior` | Same as `behavior/latest`, shortest form | Five minutes | Same as above, shortest URL. The snippet above uses this form. |

Each pinned URL is paired with `.map` for source maps. The response
also carries a `Content-Encoding` of `br` or `gzip` when your browser
advertises support, and a `SourceMap` header pointing at the companion
map for production debugging.

### Subresource Integrity (SRI)

Pin the script with an `integrity` attribute for tamper detection. SRI
only works against the exact-version URL; the `latest` and bare-product
forms serve different bytes over time and would invalidate the hash on
every release.

```html
<script
  async
  src="https://cdn.revu.ai/behavior/1.2.3"
  integrity="sha384-..."
  crossorigin="anonymous"
></script>
<script>
  window.revu = window.revu || new Proxy({q:[]}, {
    get: (t, m) => m in t ? t[m] : (...a) => t.q.push([m, ...a]),
  });
  revu.init({ apiKey: "revu_pk_..." });
</script>
```

The hash for each release is in the release notes. The CDN also returns
it on every response as an `X-Content-Integrity` header, so you can
verify or fetch it programmatically.

## Path 2: npm install (bundler-based apps)

For React, Vue, Svelte, Next.js, Nuxt, and similar bundler-based
projects, install from npm and import the SDK like any other module.

```bash
bun add @revu-ai/core
# or: npm install @revu-ai/core
```

```js
import revu from "@revu-ai/core";

revu.init({ apiKey: "revu_pk_..." });
```

The npm distribution is ESM-only. Modern bundlers (Vite, Rollup,
esbuild, webpack 5+) tree-shake against `"sideEffects": false` so a
customer who imports only `revu.init` and `revu.capture` does not pay
for the modules they do not reach.

The CDN bundle and the npm bundle ship the same source, the same public
API, and the same wire shape. Pick whichever fits your build.

## What the bundle does not do

By design, the install path does not:

- Set any cookies on the CDN domain. The bundle is served cookieless.
- Block first paint. The bundle loads asynchronously.
- Require a build step or polyfills. The bundle targets ES2020 (Chrome
  85+, Safari 13.1+, Firefox 79+, Edge 85+), which covers ~97% of
  browsers globally without transpilation overhead.
- Force a specific module loader. Modern bundler, legacy `<script>` tag,
  or hybrid setups all work.

## Where to next

- **[Configuration](/web/configuration/)** for every option you can pass
  to `init()`.
- **[Concepts](/web/concepts/)** for the mental model behind `anonymous_id`,
  `user_id`, sessions, and the canonical event shape.
- **[Privacy and data](/web/privacy/)** for what is masked by default and
  how to mark additional regions sensitive.

---

# Web SDK: Concepts
Source: https://developers.revu.ai/web/concepts/

# Concepts

[Docs index](/web/) - [package README](/web/)

The mental model behind the SDK. Four ideas cover almost everything you
will run into: identity, sessions, the canonical event shape, and the
"interactions, never values" rule.

## Contents

- [`anonymous_id` vs `user_id`](#anonymous_id-vs-user_id)
- [Sessions: engagement, not page visits](#sessions-engagement-not-page-visits)
- [The canonical event shape](#the-canonical-event-shape)
- [Interactions, never values](#interactions-never-values)

## `anonymous_id` vs `user_id`

Two ids, two layers:

- **`anonymous_id`** is the **device** id. A UUID generated on first
  visit and persisted across reloads. It never changes by user action.
  Logging out does not rotate it; `reset()` preserves it on purpose.
- **`user_id`** is the **person** id. With `autoIdentify` (the default),
  a UUID is auto-generated on first visit so every event arrives
  attributed to a stable visitor before login. `identify()` replaces
  it with your real auth id and persists. `reset()` rotates the auto id
  (logout becomes a new anonymous person from analytics' perspective)
  or clears it to `null` when `autoIdentify` is off.

Both ids are mirrored to localStorage and a first-party cookie by
default. If one store is evicted (Safari ITP can wipe localStorage
without touching cookies), the surviving store rehydrates the other on
the next read. When both stores are blocked (private mode, strict
quotas), the SDK falls back to in-memory ids for the page lifetime; it
never crashes the host.

Cross-device identity (the same person on two browsers) is joined via
[`revu.alias()`](/web/api/#revualiasauthoritativeid).

## Sessions: engagement, not page visits

The single most common point of confusion. The short version:

A session is a span of continuous engagement with your product, not a
single page visit. With the default `sessionTimeoutMs` of 30 minutes,
all of the following stay inside one session:

- A page reload.
- An SPA route change.
- Opening a second tab on the same site.
- Closing the tab and reopening it within 30 minutes.
- Coming back from a 28-minute background while reading something else.

The session only rotates once the gap since the last recorded activity
exceeds the timeout. 30 minutes is the conventional default in
behavioral analytics; it is the value behind "average session duration"
numbers you have seen elsewhere.

Full discussion (including how to switch to per-load sessions or shorten
the window) is in [configuration.md](/web/configuration/#sessiontimeoutms-sessions-are-engagement-not-page-visits).

### Engagement clock vs idle clock

Engagement time on `$page_leave` is the time the tab was **visible**,
not the time the user was **active**. A page where the user reads
silently for two minutes before scrolling still has two minutes of
engagement; the `$idle` and `$active` events are a separate signal that
the user stopped or resumed interacting. The two are orthogonal so that
content products and tool products can both reason about engagement
without one model contaminating the other.

A `$page_leave` fires on every `visibilitychange -> hidden`, not only on
a true exit, so one page view can produce several `$page_leave` events
(one per visible span) as the user tabs away and back. The `trigger`
property says what the SDK knew at emit time:

- `"navigation"` - an SPA route change closed the previous page. A
  transition, not an exit.
- `"pagehide"` - the definitive terminal signal fired (tab close,
  navigation, bfcache). The page is gone.
- `"hidden"` - the tab was backgrounded. The SDK cannot yet tell a
  blur from a close: on a real desktop close `visibilitychange ->
  hidden` fires *before* `pagehide`, so a `"hidden"` checkpoint is
  emitted first and then upgraded by a following `"pagehide"`. On
  mobile, where `pagehide` is unreliable, a `"hidden"` with no
  upgrade is often the only signal a terminal close ever produces.

Engagement is banked on the first emit for a span, so a `"pagehide"`
that upgrades a `"hidden"` carries ~0 additional `engagement_time_ms`.

For the server: sum `engagement_time_ms` grouped by `(session_id,
properties.path)` for total engagement (the upgrade's 0 is a no-op).
Count an exit when a span ends in `"pagehide"`, OR ends in `"hidden"`
with no subsequent activity on that `session_id` (the page was left and
never resumed) - do not treat every `"hidden"` as an exit, since a
blurred-then-resumed tab also produces one.

### Scroll depth: max + final on `$page_leave`

Every `$page_leave` carries two scroll-depth scalars alongside
`engagement_time_ms`:

- `max_scroll_percent` (0-100): the furthest depth reached on the page.
- `final_scroll_percent` (0-100): the depth at the moment of leave.

Together they answer three questions the milestone events cannot:

1. **Exact percentile depth** instead of buckets. Distinguishes "reached
   98%" from "stopped at 76%" instead of collapsing both to the 75%
   milestone.
2. **Scrollback**. `max_scroll_percent - final_scroll_percent > 0` means
   the user scrolled back up before leaving (re-reading, refer-back,
   abandoning after reaching the bottom). The size of the gap encodes
   how far back they went.
3. **Drop-off depth**. `final_scroll_percent` is the page position the
   user actually left from, useful for content quality grading.

A page shorter than the viewport reports `max = final = 100` on the
first `$page_leave` even if the user never scrolled, because the entire
document was already visible.

## The canonical event shape

Every event the SDK emits, autocaptured or explicit, has the same
shape:

```json
{
  "event_id": "11111111-1111-4111-8111-111111111111",
  "anonymous_id": "22222222-2222-4222-8222-222222222222",
  "user_id": "u_4b9a2",
  "session_id": "33333333-3333-4333-8333-333333333333",
  "sequence_no": 17,
  "platform": "web",
  "event_type": "$autocapture",
  "screen": "/pricing",
  "fingerprint": {
    "tag": "button",
    "text": "Start free trial",
    "selector": "button.primary",
    "ordinal": 0
  },
  "context": {
    "user_agent": "...",
    "language": "en-US",
    "timezone": "Europe/London",
    "viewport_width": 1440,
    "viewport_height": 900,
    "environment": "production",
    "sdk_version": "0.1.0",
    "consent": { "analytics": "granted", "marketing": "granted", "functional": "granted" }
  },
  "properties": {
    "path": "/pricing"
  },
  "device_time": "2026-06-15T10:21:33.014Z"
}
```

- **`event_id`** is a client-generated UUID and the idempotency key.
  The ingest endpoint dedupes on it if the SDK ever retries a batch
  that actually landed.
- **`sequence_no`** is a per-page-load monotonic counter, starting at 0
  on each SDK construction. A gap within one page load is evidence of
  loss. It does not span a session: a session continued across reloads
  or tabs restarts the counter at 0 each load, so cross-load loss
  detection relies on `event_id` (the dedupe key), not this field. A
  true per-session counter is deferred until the cross-tab queue mutex
  lands (sharing one counter across tabs without it would race).
- **`screen`** is the route at the moment the event is recorded and is
  the canonical page field. It equals `properties.path` for every event
  with one deliberate exception: on `$page_leave`, `screen` is the route
  being arrived at while `properties.path` is the page being left (on an
  SPA navigation the two differ). Group page-leave metrics (engagement
  time, scroll depth) by `properties.path`, not `screen`.
- **`fingerprint`** is present for `$autocapture` and `$rightclick`; it
  is a semantic, weighted summary of the clicked element so the server
  can name the action and survive DOM rewrites without an exact
  selector.
- **`context`** is the engine environment - the signals the SDK
  auto-populates, describing where the event happened. Keys are
  unprefixed and live in their own bucket, so they never collide with
  your `capture()` properties. It includes `user_agent`, `language`,
  `timezone`, `environment`, `sdk_version`, `viewport_width`,
  `viewport_height`, `screen_width`, `screen_height`,
  `screen_pixel_ratio`, `initial_referrer`, and `consent` (the
  per-category consent state), plus `connection_type`,
  `connection_downlink_mbps`, `connection_rtt_ms`, and `save_data` when
  the browser exposes the Network Information API, `gpc` when the browser
  advertises a Global Privacy Control signal, and the
  [attribution](#attribution-first-touch-and-last-touch) fields
  (`initial_utm_*` / `utm_*` and friends) when a visitor arrived from a
  campaign. The example above shows a representative subset.
- **`properties`** is the event's own payload: the capture layer's
  per-event fields (`path`, `url`, `depth_percent`, form structure, ...)
  and the custom properties you pass to `capture()`. Separate from
  `context`, so the two never collide.

JSDoc in `src/types.js` is the source of truth for the full type. Run
`bun run types` from the repo root to emit the corresponding `.d.ts`.

## Attribution: first touch and last touch

Campaign attribution has two halves. The server derives the immediate
attribution of a `$pageview` by parsing its captured URL. The SDK adds
the half the server cannot reconstruct on its own: persistence across
the visitor's lifetime, so a conversion that happens pages or days later
on a URL with no params still carries the campaign that drove it.

The SDK persists two records (in the same first-party store as identity)
and stamps both into every event's `context`, but only the keys actually
present:

- **First touch** (`context.initial_*`) is written once and never
  overwritten: the campaign that originally acquired the visitor. Fields:
  `initial_utm_source`, `initial_utm_medium`, `initial_utm_campaign`,
  `initial_utm_term`, `initial_utm_content`, `initial_gclid`,
  `initial_fbclid`, plus `initial_landing_path` and `initial_seen_at`
  (recorded even for a direct first visit).
- **Last touch** (`context.utm_source`, `utm_medium`, `utm_campaign`,
  `utm_term`, `utm_content`, `gclid`, `fbclid`) is rewritten whenever
  a new touch occurs - a landing that carries campaign params or arrives
  from an external referrer. Internal navigation does not overwrite it.

A direct visitor with no campaign carries almost nothing (just the first
landing path and time). Reading the stable `utm_*` / click-id keys is the
only client-side URL parsing the SDK does; everything else (user-agent,
geo) stays server-side.

## Interactions, never values

The SDK records what happened, not what was entered:

- No input value is ever read from `<input>`, `<textarea>`, `<select>`,
  or any `contenteditable` element.
- Form submits capture form structure only (`form_id`, `form_name`,
  `action`, `method`, `field_names[]`, `field_types[]`, `field_count`).
  Never values.
- Click fingerprints on sensitive targets (the elements above, plus
  anything inside a `[data-revu-mask]` subtree) are redacted: tag,
  role, and a fragile selector survive; text, `aria-label`, and `title`
  do not.
- When fingerprinting a non-sensitive container, the visible-text walker
  skips any sensitive descendant so a card's `innerText` cannot leak a
  child input's value.

This is not a tuning knob. It is the invariant the SDK exists to
enforce. Full details (including how to opt arbitrary regions out with
`data-revu-mask`) are in [privacy.md](/web/privacy/).

## Event catalog

Autocaptured events, grouped by category. All carry the canonical
envelope above; the rows below describe what's distinctive about each.

**Lifecycle**

| Event | Fires when | Notable properties |
|---|---|---|
| `$pageview` | First load and on every SPA route change | `url`, `path`, `referrer`, `title` |
| `$page_leave` | SPA route change, tab close, navigation, or `visibilitychange -> hidden` | `path` (the page being left), `trigger` (`"navigation"` / `"hidden"` / `"pagehide"`), `engagement_time_ms`, `max_scroll_percent`, `final_scroll_percent`, `persisted` |
| `$page_restore` | `pageshow` with `persisted: true` (bfcache restore via Back button) | `path` |
| `$tab_hidden` / `$tab_visible` | Visibility flips | `visible_ms` / `hidden_ms` |
| `$idle` / `$active` | User stops or resumes interacting (gated by `idleTimeoutMs`) | `active_ms` / `idle_ms` |

**Interactions**

| Event | Fires when | Notable properties |
|---|---|---|
| `$autocapture` | Any click (with `fingerprint`) | `path` |
| `$rightclick` | Right-click / context menu | `path` |
| `$rageclick` | A burst of repeated clicks on the same element | `click_count`, `window_ms`, `path` |
| `$file_download` | Click on an anchor classified as a download | `url`, `filename`, `extension`, `path` |
| `$outbound_link` | Click on an anchor leaving the current host | `url`, `target_host`, `path` |
| `$form_submit` | Form submitted | `form_id`, `form_name`, `action`, `method`, `field_names[]`, `field_types[]`, `field_count` (no values) |
| `$change` | `change` on `<input>`, `<select>`, `<textarea>` (skips password / file / hidden) | `control_type`, `checked` for boolean controls, `fingerprint`. **Never** the entered value; inside a `data-revu-mask` region `checked` is withheld too. |
| `$scroll` | Reaching 25% / 50% / 75% / 100% depth, once per milestone per page | `depth_percent`, `path` |
| `$resize` | Viewport resize (debounced) | `from_width`, `from_height`, `to_width`, `to_height` |

**Identity**

| Event | Fires when | Notable properties |
|---|---|---|
| `$identify` | `identify(userId)` ties the anonymous visitor to a known user | `previous_user_id` (when an already-identified user changes) |
| `$alias` | `alias(authoritativeId)` merges the current ids under one authoritative id | `authoritative_id`, `current_user_id`, `current_anonymous_id` |
| `$reset` | `reset()` ends the identified session (sign-out) | `previous_user_id` |

**Quality**

| Event | Fires when | Notable properties |
|---|---|---|
| `$web_vital` | LCP / INP / CLS report on page hide | `name`, `value`, `unit` (`"ms"` or `"score"`) |

---

# Web SDK: API reference
Source: https://developers.revu.ai/web/api/

# Public API

[Docs index](/web/) - [package README](/web/)

The default export of `@revu-ai/core` is a singleton bound to a single
client. Every public method is wrapped so internal errors are swallowed
and (in `debug: true`) logged. The SDK never throws into the host page.

JSDoc in `src/types.js` is the source of truth for parameter and return
types. This page documents semantics, examples, and edge cases.

## Contents

- [`revu.init(config)`](#revuinitconfig)
- [`revu.capture(eventType, properties?)`](#revucaptureeventtype-properties)
- [`revu.identify(userId)`](#revuidentifyuserid)
- [`revu.alias(authoritativeId)`](#revualiasauthoritativeid)
- [`revu.reset()`](#revureset)
- [`revu.optOut()` / `revu.optIn()` / `revu.hasOptedOut()`](#revuoptout--revuoptin--revuhasoptedout)
- [`revu.consent.set()` / `revu.consent.get()`](#revuconsentset--revuconsentget)
- [`revu.flush()`](#revuflush)
- [`revu.use(plugin)`](#revuuseplugin)
- [`revu.version`](#revuversion)
- [`RevuClient`](#revuclient)

## `revu.init(config)`

Initialize the SDK. Safe to call once per page. Subsequent calls are
ignored (the first config wins).

```js
revu.init({
  apiKey: "revu_pk_your_write_key", // required
  environment: "production", // optional
  cookieDomain: ".example.com", // share visitor across subdomains
});
```

Every other option is documented in [configuration.md](/web/configuration/).

**Edge cases.**

- Missing or non-string `apiKey` is a configuration error. In production
  the SDK fails closed (no events ship). With `debug: true` the error
  is logged with a `[REVU]` prefix.
- Invalid `host` (not a string, not http or https, malformed URL) is also
  a configuration error and fails closed.
- Plugins registered via `revu.use(...)` before `init()` are queued and
  installed when `init()` runs.

## `revu.capture(eventType, properties?)`

Record an explicit event. Use this for signals autocapture cannot see:
server-confirmed completions, async results, wizard steps that do not
change the URL.

```js
revu.capture("checkout_completed", {
  plan: "pro",
  amount_cents: 4900,
  currency: "USD",
});
revu.capture("report_exported", { format: "pdf", pages: 12 });
```

**Property values.** Properties are sanitized to a JSON-safe shape at the
source before the event is queued, so a stray value can never break the
transport:

- Keep: strings, finite numbers, booleans, `null`, and nested plain
  objects / arrays of those.
- Dropped: functions, symbols, `BigInt`, `undefined`, and circular
  references (the cycle is dropped, the rest of the object is kept). A
  non-finite number (`NaN`, `Infinity`) becomes `null`, matching JSON.
- Depth: nesting is kept up to **6 levels**; anything deeper is dropped.
  Event properties are meant to be shallow, but this is worth knowing if
  you pass a deeply nested object - flatten what you need before sending.

**Edge cases.**

- An empty or non-string `eventType` is silently ignored.
- Properties you pass always win over engine-attached context on
  collision, so a host that knows better can override anything the SDK
  auto-populates.
- For interactions autocapture already names (a button click, a form
  submit, a pageview), prefer letting the server-side feature catalog
  group them. Calling `capture()` on top duplicates the signal.

## `revu.identify(userId)`

Replace the current `user_id` with your authoritative auth id (call on
login or register).

```js
revu.identify("u_4b9a2");
```

Emits a synthetic `$identify` event so the dashboard can mark the exact
moment the visitor became known. If a prior `user_id` existed, the event
carries `properties.previous_user_id` so the transition is visible on
the timeline.

**Edge cases.**

- Idempotent: calling `identify` repeatedly with the same id is a no-op
  (no duplicate `$identify` events).
- Empty string or non-string id is a no-op.
- The id is persisted, so a reload restores it without a second call.

See also: [concepts.md - anonymous_id vs user_id](/web/concepts/#anonymous_id-vs-user_id).

## `revu.alias(authoritativeId)`

Join the current device's identity to a separate, authoritative identity
for the same person, without changing the local `user_id`.

The motivating flow is cross-device. A visitor signs up on desktop and
gets a magic link by email. They open the link on their phone, which
has its own auto-assigned `user_id`. After auth resolves on the phone,
call:

```js
revu.alias("u_4b9a2");
```

The server records that the phone's current id and `u_4b9a2` are the
same human, and dashboards stitch both journeys. The phone's local
`user_id` stays the same so already-queued events still ship under it.

**Edge cases.**

- Idempotent: the server upserts on `(organization, alias_user_id)`,
  so repeated calls produce one mapping, not duplicates.
- Empty string or non-string id is a no-op.
- No-op when `authoritativeId` already equals the current local id.

## `revu.reset()`

Sign-out counterpart to `identify`. Emits a `$reset` event marking the
end of the identified session, then clears the user id and rotates the
session id. The anonymous device id is preserved.

```js
function onLogout() {
  revu.reset();
}
```

**Order matters.** The `$reset` event ships with the OLD `session_id`
and `user_id`, so it sorts as the final marker of the logged-in session
on the timeline. Subsequent events use a fresh session id with
`user_id: null` (or a fresh auto id when `autoIdentify` is on).

**Edge cases.**

- No-op when there is no identified user. A redundant sign-out path
  (multiple components calling reset on logout) will not accidentally
  rotate the session for an anonymous visitor.
- The `anonymous_id` is never rotated by `reset()`. The browser remains
  a known device.

## `revu.optOut()` / `revu.optIn()` / `revu.hasOptedOut()`

The master capture switch. A cookie banner routes its state through these
rather than wrapping every call in a consent check.

```js
revu.optOut();        // stop all capture (reject / withdraw consent)
revu.optIn();         // resume capture (accept)
revu.hasOptedOut();   // -> boolean
```

While opted out, every interaction (autocapture, pageviews, custom
`capture()` calls, identity events) is suppressed before an event is
built, so nothing leaves the browser. The choice is persisted in the
same first-party store as identity, so a reload honors it without
re-prompting.

These are aliases for the `analytics` consent category: `optOut()` is
`consent.set({ analytics: "denied" })` and `optIn()` is
`consent.set({ analytics: "granted" })`. Use them for a simple binary
banner; use [`consent.set()`](#revuconsentset--revuconsentget) when you
need per-category control.

**Behavior.**

- Opting out does **not** clear identity. Opting back in resumes the same
  visitor; call `revu.reset()` if you want a clean break instead.
- `optOut()` stops new capture but leaves events already queued under
  prior consent to flush. To also discard locally-buffered events, see
  [Privacy and data](/web/privacy/#dropping-locally-buffered-events).
- `hasOptedOut()` returns `false` before `init()`.

## `revu.consent.set()` / `revu.consent.get()`

Per-category consent control. The SDK understands three categories -
`analytics`, `marketing`, and `functional` - each `"granted"` or
`"denied"`.

```js
// Map a cookie banner's result straight through (partial maps merge):
revu.consent.set({ analytics: "granted", marketing: "denied" });

revu.consent.get();
// -> { analytics: "granted", marketing: "denied", functional: "granted" }
```

Only `analytics` gates capture: denying it suppresses every event,
exactly like `optOut()`. `marketing` and `functional` are declarative -
the SDK stamps the full state on every event as `context.consent` so
the server can honor the visitor's choices on downstream destinations,
but it never acts on them itself.

**Behavior.**

- `set()` merges a partial map over the current state and persists the
  result in the same first-party store as identity. Unknown categories
  and values other than `"granted"` / `"denied"` are ignored.
- `get()` returns a copy of the current state. Before `init()`, `set()`
  is a no-op and `get()` returns the all-granted default.
- A pre-existing binary opt-out from an earlier SDK version is read on
  the first load after upgrade, so a prior reject keeps being honored.
- See [Global Privacy Control](/web/configuration/#consent-and-gpc) for
  how the `honorGpc` option feeds this state.

## `revu.flush()`

Send any buffered events now. Returns a promise that resolves to `true`
when the batch is accepted, `false` if the send fails, and `undefined`
if called before `init()`.

```js
await revu.flush();
```

You rarely need to call this. Events flush automatically on a size
threshold (`flushAt`, default 20), on an interval (`flushIntervalMs`,
default 5000 ms), when connectivity returns (`online`), and on page
hide. Manual `flush()` is useful when you are about to do something
destructive (full reload, navigate away to a non-instrumented page)
and want the buffer drained first.

## `revu.use(plugin)`

Register a plugin. Equivalent to passing it via `init({ plugins: [...] })`,
but available as a separate call so plugins can be wired conditionally
(behind a feature flag, after a config fetch).

```js
import revu from "@revu-ai/core";
import { myPlugin } from "./my-plugin.js"; // your own plugin, see plugins.md

revu.use(myPlugin());
revu.init({ apiKey: "revu_pk_..." });
```

Pre-init `use()` calls are queued and drained when `init()` runs. The
same plugin name registered twice is a no-op so a redundant wiring path
does not cause double listeners.

See [plugins.md](/web/plugins/) for the plugin contract.

## `revu.version`

The build string of the bundle (for example `"0.1.0"`). The same string
ships on every event as `context.sdk_version`, and it is useful for
support tickets (paste it in) and console introspection.

```js
console.log(revu.version);
```

## `RevuClient`

The named export `RevuClient` is the class behind the singleton. The
singleton is the right answer for almost every host: it removes a layer
of wiring and guarantees one source of identity per page. Construct
`RevuClient` directly only when you genuinely need multiple isolated
clients in the same page (a rare case, typically embedded analytics in
a multi-tenant editor).

```js
import { RevuClient, VERSION } from "@revu-ai/core";

const client = new RevuClient({
  apiKey: "revu_pk_...",
  host: "https://api.revu.ai",
  /* every option from configuration.md */
});
client.start();
client.capture("event_name", { foo: "bar" });
```

`RevuClient`'s public methods are `start`, `capture`, `identify`,
`alias`, `reset`, `optOut`, `optIn`, `hasOptedOut`, `setConsent`,
`getConsent`, `flush`, and `use`.
The capture and identity methods
mirror the singleton (the singleton calls `start()` for you inside
`init()`); they are not wrapped with the `safe()` boundary, so a host
using the class directly is responsible for catching errors at their own
boundary.

---

# Web SDK: Configuration
Source: https://developers.revu.ai/web/configuration/

# Configuration

[Docs index](/web/) - [package README](/web/)

Every option passed to `revu.init({ ... })` is optional except `apiKey`.
Defaults are tuned to be the right answer for a typical product surface.

## Options

| Option              | Type                                         | Default                 | Use when                                                                                                                                                                                                                                                            |
| ------------------- | -------------------------------------------- | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `apiKey`            | `string`                                     | required                | Your public write key. Starts with `revu_pk_`. Resolves to org and entity server-side.                                                                                                                                                                              |
| `host`              | `string`                                     | `"https://api.revu.ai"` | Override only when self-hosting the ingest service, running a regional endpoint, pointing at a local dev server, or routing through your own domain for [first-party ingest](/web/first-party-ingest/). Must be http or https.                                          |
| `environment`       | `"production" \| "staging" \| "development"` | `"production"`          | Stamped on every event as `context.environment`. The default dashboard view filters out non-production, so set this to `"staging"` or `"development"` on those builds to keep them out of production analytics.                                                            |
| `autocapture`       | `boolean`                                    | `true`                  | Auto-capture pageviews and clicks. Disable only when you want a fully manual `capture()`-only instrumentation.                                                                                                                                                      |
| `autoIdentify`      | `boolean`                                    | `true`                  | Auto-assign a persistent `user_id` on first visit so every event arrives attributed to a stable visitor even before login. Disable when your privacy posture requires anonymous-until-login.                                                                        |
| `persistentStorage` | `"localStorage" \| "cookie" \| "both"`       | `"both"`                | Where identity ids live. `"both"` mirrors to localStorage and a first-party cookie so eviction of one is recoverable from the other. Pick `"localStorage"` to drop the per-request cookie bandwidth, or `"cookie"` to share ids across subdomains exclusively.      |
| `cookieDomain`      | `string \| null`                             | `null`                  | Set to `".example.com"` to share one visitor across `app.example.com` and `www.example.com`. Leave unset to keep the cookie host-only.                                                                                                                              |
| `sessionTimeoutMs`  | `number`                                     | `1_800_000` (30 min)    | How long a session can sit idle before the next SDK construction rotates `session_id`. See the [callout below](#sessiontimeoutms-sessions-are-engagement-not-page-visits). Set to `0` to disable continuation entirely so every page load gets a brand new session. |
| `sessionMaxMs`      | `number`                                     | `86_400_000` (24 h)     | Absolute cap on a session's total length. Even a continuously-active session rotates once it has been alive this long, so a long-lived tab, kiosk, or always-on dashboard does not accumulate one multi-day session that skews duration and engagement. Set to `0` to disable the cap. |
| `captureAttention`  | `boolean`                                    | `true`                  | Emit `$tab_hidden`, `$tab_visible`, `$idle`, `$active`. Disable to halve attention-event volume if you do not use the corresponding insights; engagement time on `$page_leave` always works regardless.                                                             |
| `idleTimeoutMs`     | `number`                                     | `30_000`                | Inactivity threshold (mouse, keyboard, scroll, touch) before `$idle` fires. Set to `0` to disable idle detection entirely.                                                                                                                                          |
| `captureWebVitals`  | `boolean`                                    | `true`                  | Emit `$web_vital` for LCP, INP, CLS on page hide. Disable only when you have a separate vitals pipeline.                                                                                                                                                            |
| `flushIntervalMs`   | `number`                                     | `5000`                  | Max time a partial batch sits before going out. Lower it for low-volume pages where you want events to land faster.                                                                                                                                                 |
| `flushAt`           | `number`                                     | `20`                    | Queue size that triggers an immediate flush. Lower it for chatty pages where you want smaller, more frequent batches.                                                                                                                                               |
| `maxBatch`          | `number`                                     | `50`                    | Hard cap on events per request body. Bound exists so a single network round-trip never sends an oversized payload.                                                                                                                                                  |
| `maxQueue`          | `number`                                     | `1000`                  | Hard cap on durably-queued events. When the cap is hit, the oldest events are pruned first (recent behavior is more valuable than stale backlog).                                                                                                                   |
| `sampleRate`        | `number`                                     | `1`                     | Fraction of sessions to capture, in `[0, 1]`. `1` keeps everything; `0.1` keeps ~10% of sessions and drops the rest before they queue, trading dashboard precision for ingest volume on high-traffic sites. Session-sticky (a whole session is kept or dropped), identity events always send (and never carry `context.sample_rate`), and kept sampled events carry `context.sample_rate` so the server scales aggregates. Out-of-range values throw at init. |
| `honorGpc`          | `boolean`                                    | `false`                 | When `true`, a browser [Global Privacy Control](#consent-and-gpc) signal defaults the `analytics` consent category to denied (suppressing capture) unless the visitor has made an explicit choice. Left `false` by default: honoring GPC is a jurisdictional decision for you to make (it is a valid opt-out under CCPA/CPRA but not the consent mechanism under GDPR), and auto-denying would silently drop data on upgrade. The signal is stamped on every event as `context.gpc` regardless of this flag. |
| `debug`             | `boolean`                                    | `false`                 | Log every captured event and internal error to the console with a `[REVU]` prefix.                                                                                                                                                                                  |
| `onEvent`           | `(event) => void`                            | `() => {}`              | Local hook called with every captured event. Useful for debug overlays, screenshot annotations, and tests.                                                                                                                                                          |
| `beforeSend`        | `(event) => event \| null \| false \| void`  | `null`                  | [Last-mile hook](#beforesend-enrich-redact-or-drop) called with each built event before it queues. Return the event (mutated or replaced) to send it, `null` / `false` to drop it, or nothing to send it unchanged. Use it to enrich, redact, or filter. Fail-open: a throwing hook sends the event unchanged rather than dropping it. |
| `autocaptureAllowSelectors` | `string[]`                           | `[]`                    | When non-empty, only elements matching (or nested inside) one of these CSS selectors are autocaptured for clicks, right-clicks, and form-control changes. See [selector filtering](#autocapture-selector-filtering).                                                  |
| `autocaptureDenySelectors`  | `string[]`                           | `[]`                    | CSS selectors whose elements (and descendants) are excluded from element-targeted autocapture. Deny wins over allow. See [selector filtering](#autocapture-selector-filtering).                                                                                      |
| `plugins`           | `RevuPlugin[]`                               | `[]`                    | Plugins to install during `init()`. Equivalent to a `revu.use(plugin)` for each, but co-located with the rest of the config.                                                                                                                                        |

## `sessionTimeoutMs`: sessions are engagement, not page visits

This is the single most common point of confusion, so the default is
worth stating explicitly.

A **session** is a span of continuous engagement with your product, not
a single page visit. With the default `sessionTimeoutMs` of 30 minutes,
the SDK continues the previous session whenever the gap since the last
recorded activity is under 30 minutes. That means all of the following
stay inside one session:

- A page reload (refresh).
- An SPA route change.
- Opening a second tab on the same site.
- Closing the tab and reopening it within 30 minutes.
- Coming back from a 28-minute background while reading something else.

The session only rotates (gets a fresh `session_id`) once the gap since
the last recorded activity exceeds the timeout. 30 minutes is the
conventional default in behavioral analytics; it is the value behind
"average session duration" numbers you have seen elsewhere.

If you want every page load to start a new session (rarely the right
choice, but available for parity with very old per-load instrumentation
patterns), set:

```js
revu.init({ apiKey: "...", sessionTimeoutMs: 0 });
```

If your product is more like a content site where each visit really is a
distinct intent, shorten the window:

```js
revu.init({ apiKey: "...", sessionTimeoutMs: 10 * 60 * 1000 }); // 10 minutes
```

The session id is persisted (per `persistentStorage`) along with a
`last_seen` timestamp; on every event the SDK touches `last_seen`
(throttled so a chatty page does not pay a write per event), and the
next construction reads both to decide whether to continue or rotate.

## Consent and GPC

Capture is gated on a per-category consent state the host controls at
runtime, so a cookie banner routes its choices through the SDK rather
than wrapping every call in a check. There are three categories:

- **`analytics`** - the SDK's own bucket. This is the only category that
  gates capture: while it is `"denied"`, every interaction is suppressed
  before an event is built, so nothing leaves the browser.
- **`marketing`** and **`functional`** - declarative. The SDK does not
  act on them; it stamps the full consent state on every event
  (`context.consent`) so the server honors the visitor's choices on
  the destinations downstream.

```js
// Map a cookie banner's result straight through:
revu.consent.set({ analytics: "granted", marketing: "denied" });

revu.consent.get();
// -> { analytics: "granted", marketing: "denied", functional: "granted" }
```

`revu.optOut()` / `revu.optIn()` are aliases for denying / granting the
`analytics` category, so existing wiring keeps working. The state is
persisted in the same first-party store as identity, and a pre-existing
binary opt-out from an earlier SDK version is honored on upgrade.

**Global Privacy Control.** Some browsers advertise a GPC signal
(`navigator.globalPrivacyControl`). The SDK always stamps it on events as
`context.gpc` so the server sees it. With `honorGpc: true`, a GPC signal also
defaults the `analytics` category to denied - unless the visitor has
already made an explicit choice through your banner, which always wins.
The default is `honorGpc: false`: whether GPC legally requires
suppression depends on your jurisdiction, so the decision is left to you.

```js
revu.init({ apiKey: "...", honorGpc: true }); // auto-deny on a GPC signal
```

## `beforeSend`: enrich, redact, or drop

`beforeSend` runs once per event, after the SDK has built the full event
but before it is queued. It is the place to add host context the SDK
cannot know, strip a field, or filter events you never want to store.

```js
revu.init({
  apiKey: "...",
  beforeSend(event) {
    // Enrich: attach something only the host knows.
    event.properties.tenant_plan = window.__APP__.plan;

    // Redact: drop a field you do not want stored.
    delete event.properties.some_internal_id;

    // Drop: filter noisy events entirely.
    if (event.event_type === "$autocapture" && event.screen === "/debug") {
      return null;
    }

    return event; // send it (mutated in place, or return a new object)
  },
});
```

- Return the event (the same one mutated, or a replacement object) to
  send it; return `null` or `false` to drop it; return nothing to send it
  unchanged.
- It is **fail-open**: if the hook throws, the original event is sent
  unchanged (and the error is logged when `debug` is on), so a bug in the
  hook never silently deletes analytics.
- The returned event's `properties` are re-sanitized to a JSON-safe shape,
  so the hook cannot poison the durable queue with an unserializable value.
- It does not run for events that were never built - capture suppressed by
  consent or sampling never reaches `beforeSend`.

## Autocapture selector filtering

`autocaptureDenySelectors` and `autocaptureAllowSelectors` scope which
elements element-targeted autocapture (clicks, right-clicks, form-control
changes) observes. Matching walks ancestors, so a selector on a container
also covers the elements inside it.

```js
revu.init({
  apiKey: "...",
  // Never autocapture anything inside these:
  autocaptureDenySelectors: [".sensitive-widget", "[data-no-track]"],
});

// Or capture ONLY inside an explicit set (everything else is ignored):
revu.init({
  apiKey: "...",
  autocaptureAllowSelectors: ["main", ".tracked"],
});
```

- **Deny wins.** An element matching a deny selector is never captured,
  even if it also matches an allow selector.
- A deny selector suppresses the event **entirely**, including the
  file-download, outbound-link, and rage-click events derived from a
  click. This is the difference from `data-revu-mask`, which still emits
  the event but redacts its fingerprint - use a deny selector when you
  want no event at all, and `data-revu-mask` when you want the interaction
  recorded without its labels. An invalid selector is ignored, not thrown.

---

# Web SDK: Privacy and data
Source: https://developers.revu.ai/web/privacy/

# Privacy and data

[Docs index](/web/) - [package README](/web/)

The SDK captures interactions, not values. The boundary is deliberately
broad and enforced at the source of capture, not at the ingest endpoint.

## What is masked by default

- **Inputs are never read.** Form fields (`<input>`, `<textarea>`,
  `<select>`) and any `contenteditable` region are sensitive; their
  values do not leave the browser.
- **Form submits carry metadata only.** Structure (`form_id`,
  `form_name`, `action`, `method`, `field_names[]`, `field_types[]`,
  `field_count`), never values.
- **Every form-entry element is sensitive by tag, not by type.** Every
  `<input>` (regardless of its `type`), `<textarea>`, and `<select>` is
  treated as sensitive, so no text or value is read from it. There is no
  type allowlist: a plain `text` or `number` field is masked exactly
  like a `password` field. As an extra layer, the `$change` interaction
  event skips `password`, `file`, and `hidden` inputs entirely.
- **Click fingerprints on sensitive targets are redacted.** Tag, role,
  and a fragile selector survive; `text`, `aria_label`, and `title` do
  not.
- **Container text never leaks child input values.** When fingerprinting
  a non-sensitive container, the visible-text walker skips any
  sensitive descendant, so a card's `innerText` cannot include a child
  input's value.

## `data-revu-mask`

Add the attribute to any element (or any ancestor) to mark its subtree
sensitive. The SDK honors it everywhere a sensitive element would be
honored:

- Click fingerprints inside the subtree redact text, `aria-label`, and
  `title`.
- Form submits inside the subtree skip field-name capture entirely.
- Container text extraction skips the subtree.

```html
<!-- Mask a PII summary card -->
<aside data-revu-mask>
  <h3>Account balance</h3>
  <p>$1,234.56</p>
</aside>

<!-- Mask one field on a form (or the whole form) -->
<form data-revu-mask>
  <input name="ssn" type="text" />
</form>
```

The attribute also crosses Shadow DOM boundaries: a `data-revu-mask` on
a custom element's host applies to every element in its shadow tree.

`data-revu-mask` still emits the interaction, just with its labels
redacted. When you want no event at all for a region - not even a
redacted one - use the
[`autocaptureDenySelectors`](/web/configuration/#autocapture-selector-filtering)
config option instead; it suppresses the event entirely, including any
file-download / outbound-link / rage events derived from the click.

## URLs and query strings

Captured URLs (the `$pageview` `url`, the referrer, and `$outbound_link` /
`$file_download` targets) routinely carry secrets in their query string or
fragment: a password-reset token, an email address in `?email=`, an
OAuth/OIDC implicit-flow `#access_token=...`. The SDK redacts the
**values** of sensitive parameters at the source - in both the query and
the fragment - replacing them with `[redacted]` before the event is built.

The redaction is by parameter name, not wholesale, because the server
derives campaign attribution (UTM, click ids) from the captured URL. So
`utm_source`, `utm_medium`, `gclid`, `fbclid`, and other attribution and
benign params are preserved, while `token`, `password`, `secret`, `auth`,
`api_key`, `session`, `email`, and similar credential / PII keys (matched
case-insensitively, including `_`/`-`-delimited variants like
`access_token` and `user_email`) have their values stripped.

This is redaction at source, not a toggle: there is no option to capture
raw query values. The page identity (`screen` / `path`) is the pathname
plus hash and never includes the query string; the hash itself is run
through the same redaction, so a credential-bearing fragment (an OAuth
implicit-flow `#access_token=...` landing) never lands in `screen` or
`path`. Hash-router routes (`#/pricing`) and anchors (`#section`) are
preserved unchanged.

## What the SDK does not parse client-side

By design, several categories of work live server-side:

- **URL query parsing.** Campaign attribution (UTM, click ids) is
  derived server-side from the `$pageview` URL on the first event of
  each session. The SDK does not ship a parser for these.
- **User agent parsing.** The SDK ships the raw `navigator.userAgent`
  string; the server parses it into os, browser, and device. UA strings
  drift; the server can iterate on the parser without a customer
  redeploy.
- **IP-based geo.** The SDK never reads or sends client geolocation.
  The server enriches based on the request's IP, which is also more
  durable than client APIs and never requires a permission prompt.

This is a hard boundary, not a temporary state. Anything that would
require shipping a dictionary, an algorithm, or a model to the browser
stays server-side. That is what keeps the bundle in single-digit
kilobytes.

## Consent

Capture is gated on a per-category consent state the host controls at
runtime, so a cookie banner routes its choices through the SDK rather
than wrapping every call in a check. The simplest form is the binary
master switch:

```js
revu.optOut();        // stop all capture (reject / withdraw consent)
revu.optIn();         // resume capture (accept)
revu.hasOptedOut();   // -> boolean
```

For per-category control, use the consent API. There are three
categories - `analytics`, `marketing`, and `functional` - each
`"granted"` or `"denied"`:

```js
revu.consent.set({ analytics: "granted", marketing: "denied" });
revu.consent.get();
// -> { analytics: "granted", marketing: "denied", functional: "granted" }
```

Only `analytics` gates capture: while it is denied, every interaction
(autocapture, pageviews, custom `capture()` calls, identity events) is
suppressed before an event is built, so nothing leaves the browser.
`optOut()` / `optIn()` are aliases for denying / granting it.
`marketing` and `functional` are declarative: the SDK does not act on
them, it stamps the full state on every event (`context.consent`) so
the server honors the visitor's choices on the destinations downstream.

The choice is persisted in the same first-party store as identity, so a
reload honors it without re-prompting. A binary opt-out persisted by an
earlier SDK version is read on the first load after upgrade, so a prior
reject keeps being honored.

Changing consent does not clear identity: granting again resumes the
same visitor. That is the right default for a consent toggle (a user who
re-accepts is the same person). Call `revu.reset()` if you instead want
a clean break to a new anonymous visitor.

For per-element opt-out, use `data-revu-mask` on the subtree.

### Global Privacy Control

Some browsers advertise a Global Privacy Control signal
(`navigator.globalPrivacyControl`). The SDK always stamps it on events as
`context.gpc` so the server sees it. With `honorGpc: true` (off by
default), a GPC signal also defaults the `analytics` category to denied,
unless the visitor has already made an explicit choice through your
banner - an explicit choice always wins. The default is off because
whether GPC legally requires suppression depends on your jurisdiction
(it is a valid opt-out signal under CCPA/CPRA, but not the consent
mechanism under GDPR), so the decision is left to you.

### Dropping locally-buffered events

`optOut()` stops new capture but leaves events already queued under prior
consent to flush. To also discard any locally-buffered events and stored
ids for a user who withdraws consent, clear the durable queue and
identity stores:

```js
revu.optOut();
// Keep `revu_consent` so the opt-out itself is honored on the next load.
const keys = [
  "revu_event_queue",
  "revu_anonymous_id",
  "revu_user_id",
  "revu_session_id",
  "revu_session_last_seen",
  "revu_attribution_first",
  "revu_attribution_last",
];
try {
  for (const key of keys) localStorage.removeItem(key);
} catch {}
for (const key of keys) {
  document.cookie = `${key}=; Path=/; Max-Age=0; SameSite=Lax`;
}
```

A server-side right-to-be-forgotten helper that also purges already-ingested
events is planned; until then, the above fully disables capture and clears
local state.

---

# Web SDK: Transport and offline
Source: https://developers.revu.ai/web/transport/

# Transport and offline

[Docs index](/web/) - [package README](/web/)

Events do not get lost when the network is hostile or the page is
closing. Three layers cooperate to make that true: a durable queue, a
retrying transport, and two terminal flush paths for unload.

## What the transport sends

- **Endpoint.** `POST ${host}/v1/behavior/events`. One endpoint, one
  path; a single `connect-src` entry covers every request the SDK
  makes. `host` defaults to `https://api.revu.ai`; point it at your own
  domain for [first-party ingest](/web/first-party-ingest/).
- **Body.** JSON with `{ api_key, batch }`, content type
  `application/json`.
- **Method.** `fetch` with `keepalive: true` while the page is live;
  `sendBeacon` (with an explicit `application/json` Blob) on
  `pagehide` and `visibilitychange -> hidden`.

## When the transport flushes

The transport flushes on any of:

- **Size threshold.** The queue size reaches `flushAt` (default 20).
- **Time interval.** Every `flushIntervalMs` (default 5000 ms) a
  background timer drains whatever is in the queue.
- **Connectivity returns.** On the `online` event, the failure counter
  and backoff reset and a flush attempts immediately.
- **Terminal lifecycle.** `pagehide` and `visibilitychange -> hidden`
  both trigger a `sendBeacon` flush so the final batch survives unload.
- **Manual.** [`revu.flush()`](/web/api/#revuflush) drains the buffer
  immediately and resolves to `true` on success.

Each flush sends at most `maxBatch` events per request (default 50). If
the queue holds more, it drains across several requests rather than one
oversized body.

## The durable queue

Events are appended to a localStorage-backed FIFO queue on every
`record()` call, before any send is attempted. That means:

- An offline period buffers locally and ships on the next `online`.
- A crash, a hard reload, or a closed laptop lid does not lose events;
  the next page load drains what was left.
- The queue is bounded by `maxQueue` (default 1000). When the cap is
  hit, the oldest events are pruned first (recent behavior is more
  valuable than stale backlog).
- A successful send only commits the batch (removes it from the queue)
  after the server acknowledges. A failed send leaves events queued
  for the next attempt.

When localStorage is unavailable (private mode in some engines, strict
quotas, storage disabled), the queue transparently falls back to an
in-memory array. The SDK keeps capturing; it just loses durability
across reloads. With `debug: true` the fallback is logged.

## Retries and backoff

Transient failures (network error, 429, 503, any non-2xx) keep the
batch in the queue and schedule a retry with capped exponential
backoff:

- Base delay: 1 s.
- Doubles per consecutive failure.
- Capped at 60 s.

The first success resets the counter, so a flapping network does not
ratchet the delay indefinitely.

The ingest endpoint dedupes on `event_id` (every event carries a
client-generated UUID and that UUID is the idempotency key), so a retry
that overlaps a send that actually landed is safe.

## Terminal flush ordering

The terminal flush is installed last in the SDK boot sequence, on
purpose. `pagehide` and `visibilitychange` listeners on the same
target fire in registration order during the bubble phase, so the
transport's terminal handler runs after every emit-on-terminal module
(autocapture's `$page_leave`, vitals' LCP / INP / CLS report, any
plugin doing the same). That ordering guarantees the final batch
already contains those last events when `sendBeacon` ships it.

iOS Safari is the reason two terminal events are wired instead of one.
On desktop, `pagehide` covers tab close, navigation, and bfcache
eviction. On mobile (especially iOS Safari), `pagehide` is often
skipped when the user backgrounds the app or closes the tab; the only
reliable terminal signal there is `visibilitychange -> hidden`. The
transport listens on both and dedupes so each real terminal close
emits one batch.

---

# Web SDK: First-party ingest
Source: https://developers.revu.ai/web/first-party-ingest/

# First-party ingest

[Docs index](/web/) - [package README](/web/)

By default the SDK sends events to `https://api.revu.ai`. You can instead
route them through your own domain so the requests are first-party. This
is a data-completeness measure: some browser extensions and network-level
filters block requests to third-party analytics domains by domain name,
so a portion of your traffic never reaches a third-party endpoint.
Serving ingest from your own origin keeps that data first-party and
intact.

This is purely a routing change. It collects nothing extra and changes
nothing about what is captured: events stay consent-gated, redacted at
source, and value-free exactly as before. The SDK does not obfuscate or
rotate its request path - the goal is first-party data, not hiding
network calls from the person using the browser.

## How it works

Point the SDK's [`host`](/web/configuration/#options) at a path on your
own domain:

```js
revu.init({
  apiKey: "revu_pk_...",
  host: "https://yourapp.com/ingest",
});
```

The SDK then posts to `https://yourapp.com/ingest/v1/behavior/events`.
You run a thin reverse proxy at `/ingest/*` that forwards to
`https://api.revu.ai/*`. Two things fall out of this for free:

- **The browser request is same-origin** (`yourapp.com` to
  `yourapp.com`), so there is no CORS preflight to worry about.
- **The proxy-to-api hop is server-to-server**, so it is unaffected by
  anything in the browser.

No SDK changes beyond `host`, and no REVU api changes: the ingest
endpoint already accepts requests from any origin (per-key origin
allowlists are enforced server-side) and authenticates on the public key
in the request body, not on the request host.

Both transport paths - the live `fetch` (with `keepalive`) and the
`sendBeacon` terminal flush on page hide - target `host`, so both are
proxied identically. The durable queue is scoped to the page origin and
is unaffected.

## Proxy recipes

Each recipe forwards `/ingest/*` on your domain to
`https://api.revu.ai/*`, preserving the rest of the path
(`/v1/behavior/events`). Use any path prefix you like; just keep it
stable and match it to the `host` you pass to `init()`.

**Restrict the forward to the behavior path** (`/v1/behavior/`) rather
than proxying everything, so the rule is not an open relay.

### Cloudflare Worker

Route `yourapp.com/ingest/*` to this Worker:

```js
export default {
  async fetch(request) {
    const url = new URL(request.url);
    // Strip the "/ingest" prefix, keep the rest (/v1/behavior/events).
    const path = url.pathname.replace(/^\/ingest/, "");
    if (!path.startsWith("/v1/behavior/")) {
      return new Response("Not found", { status: 404 });
    }
    const upstream = new URL("https://api.revu.ai" + path + url.search);
    return fetch(upstream, {
      method: request.method,
      headers: request.headers,
      body: request.body,
    });
  },
};
```

### nginx

Trailing slashes on both sides strip the `/ingest/` prefix:

```nginx
location /ingest/ {
  proxy_pass https://api.revu.ai/;
  proxy_set_header Host api.revu.ai;
  proxy_ssl_server_name on;
}
```

### Caddy

`handle_path` strips the matched prefix before proxying:

```caddy
handle_path /ingest/* {
  reverse_proxy https://api.revu.ai {
    header_up Host api.revu.ai
  }
}
```

### Vercel / Next.js

In `next.config.js`, a rewrite keeps the request first-party from the
browser's point of view:

```js
module.exports = {
  async rewrites() {
    return [
      {
        source: "/ingest/:path*",
        destination: "https://api.revu.ai/:path*",
      },
    ];
  },
};
```

## Self-hosting the SDK script

The same domain-based filtering can apply to the SDK file itself. The
build is a static asset, so you can serve it from your own domain (or
keep loading it from `cdn.revu.ai`). If you self-host, pin a version and
update deliberately rather than tracking latest, so a capture change
never ships to your users without your say-so. See
[Install](/web/install/) for version pinning and SRI.

## Notes

- Keep the proxy path **stable**. The SDK does not rotate or randomize
  it, and a stable path is what keeps your own caching, logging, and SRI
  predictable.
- This does not change consent. A visitor who has denied the `analytics`
  category still produces no events; first-party routing only affects
  where the events that *do* ship are sent. See
  [Consent](/web/privacy/#consent).
- Point your monitoring at the proxy: a misconfigured rewrite shows up as
  events disappearing, the same symptom as a wrong `host`. See
  [Troubleshooting](/web/troubleshooting/#events-do-not-appear-in-the-dashboard).

---

# Web SDK: Plugins
Source: https://developers.revu.ai/web/plugins/

# Plugins

[Docs index](/web/) - [package README](/web/)

A plugin extends the SDK with new event types or behaviors without
bloating the core. Every plugin implements the same minimal contract,
regardless of how it is distributed.

## The contract

```js
/** @type {import("@revu-ai/core").RevuPlugin} */
export function myPlugin(options = {}) {
  return {
    name: "my-plugin", // unique id; double-install is a no-op
    install({ record, identity, context, config }) {
      // Wire listeners, observers, timers. Emit through `record()` so
      // events go through the standard pipeline (identity + context +
      // transport).
      record("$my_event", { properties: { foo: "bar" } });
    },
    uninstall() {
      // Optional. Tear down anything install() wired up.
    },
  };
}
```

The `install` API is the minimum a plugin needs:

- **`record(eventType, data?)`** to emit an event through the standard
  pipeline. `data` accepts `fingerprint` and `properties` (the latter
  wins over engine context on collision).
- **`identity`** for read access to `anonymousId`, `userId`, `sessionId`.
- **`context`** for read access to the environment context builder.
- **`config`** for the resolved config (host, environment, debug, etc).

## Registering a plugin

Two equivalent paths (`exceptions()` and `replay()` here stand in for
plugins you author or install; they are not shipped exports of this
package):

```js
revu.init({ apiKey: "revu_pk_...", plugins: [exceptions(), replay()] });
```

```js
revu.use(exceptions());
revu.use(replay());
revu.init({ apiKey: "revu_pk_..." });
```

Both paths queue pre-init `use()` calls and drain them when `init()`
runs. The same plugin name registered twice is a no-op so a redundant
wiring path does not cause double listeners.

## When to ship a feature as a plugin vs put it in core

Core stays universal. Anything every customer uses regardless of segment
or use case (autocapture, identity, transport, attention, web vitals)
lives in core. Anything **segment-specific** (B2B-only signals,
framework adapters, industry compliance, paid-plan capabilities) ships
as a plugin so customers who do not use it carry **zero bytes** after
tree-shaking.

The rule of thumb on distribution:

- **Subpath plugin** (`@revu-ai/core/<name>`) when the feature is small,
  uses no separate ingest, and shares the privacy posture of core. It
  ships in the same package and tree-shakes out when not imported.
- **Separate npm package** (a future `@revu-ai/replay` and so on) when
  the feature exceeds ~5 kB gzipped, has its own ingest endpoint, has a
  materially different privacy posture, or needs independent
  versioning.

The plugin contract is identical either way.

## A worked example

A small plugin that captures uncaught exceptions (an illustrative plugin
you would author yourself, not a shipped export):

```js
/** @type {import("@revu-ai/core").RevuPlugin} */
export function exceptions() {
  return {
    name: "exceptions",
    install({ record }) {
      if (typeof window === "undefined") return;
      window.addEventListener("error", (e) => {
        record("$exception", {
          properties: {
            message: e.message,
            filename: e.filename,
            line: e.lineno,
            column: e.colno,
            stack: e.error?.stack,
          },
        });
      });
      window.addEventListener("unhandledrejection", (e) => {
        record("$unhandled_rejection", {
          properties: { reason: String(e.reason) },
        });
      });
    },
  };
}
```

Three things worth noting:

- The plugin emits through `record()`, so the event picks up identity,
  session, and environment context just like an autocaptured event.
- It does its own DOM work (`window.addEventListener`). The plugin API
  is deliberately minimal; everything the plugin needs from the host
  environment comes from platform APIs, not from a wrapper layer.
- It is SSR-safe (guards on `typeof window`). Plugins are responsible
  for their own environment guards, same as core.

---

# Web SDK: Troubleshooting
Source: https://developers.revu.ai/web/troubleshooting/

# Troubleshooting

[Docs index](/web/) - [package README](/web/)

The SDK fails closed and never throws into the host page, so most
problems show up as "no events arrive" rather than as a stack trace.
The flow below isolates the cause.

## Events do not appear in the dashboard

1. **Confirm init ran.** With `debug: true`, you should see at least
   one `[REVU] event` log on first interaction.
2. **Confirm `environment` matches your dashboard filter.** The default
   dashboard view shows `production` only, so a `staging` or
   `development` build is hidden until you switch the filter.
3. **Check the network panel** for a POST to
   `${host}/v1/behavior/events`. A pending, blocked, or failed request
   points at one of the next sections.

## CSP blocks the ingest request

Symptom: console message about Content Security Policy. The SDK never
throws, but no events reach ingest. Fix by allowing the ingest host in
your `connect-src` directive:

```http
Content-Security-Policy: connect-src 'self' https://api.revu.ai
```

If you have set a custom `host`, allow that origin instead. The SDK
issues exactly one type of request (POST `/v1/behavior/events`), so a
single `connect-src` entry covers every path.

## The request returns 403

Symptom: the network panel shows a POST to `/v1/behavior/events` that
returns `403`. The key is valid but the request `Origin` is not on that
key's allowed-origin list, so ingest rejects it. Add your site's origin
(for example `https://app.example.com`) to the allowed origins for the
key. This is distinct from a CSP block, which fails inside the browser
before any request leaves the page.

## `sendBeacon` returns false on unload

Symptom: the terminal `$page_leave` and `$web_vital` events do not
arrive on tab close. Two common causes:

- **Content type.** `sendBeacon` defaults a string body to
  `text/plain`, which strict ingest endpoints reject. The SDK already
  wraps the body in a `Blob` with `application/json`, so an upgrade to
  the current version fixes this. If you front the SDK with your own
  proxy, make sure it accepts `application/json`.
- **Cross-origin and CSP.** `sendBeacon` honors `connect-src` just like
  `fetch`. See the section above.

## Mobile Safari does not deliver the final batch

iOS Safari frequently skips `pagehide` when the user backgrounds the
app or closes the tab. The SDK works around this by listening on
**both** `pagehide` and `visibilitychange -> hidden`, deduping so each
real terminal close emits one `$page_leave` and one transport flush.
If you still see missing terminal events, check:

- Are you wrapping the SDK in another layer that intercepts page
  lifecycle events? A wrapper that swallows `visibilitychange` removes
  the only reliable terminal signal on iOS Safari.
- Is the page being killed by the OS before the SDK can flush? The
  events are durably queued; they ship on the next visit to the same
  origin in the same browser.

## Events disappear after a page reload

Unlikely: the durable queue is backed by localStorage and `add()`
persists on every mutation. If you see this, check:

- **Are events queued in a different storage origin?** localStorage is
  scoped to the origin, so a hop from `app.example.com` to
  `www.example.com` is a different store. Identity is the same unless
  `cookieDomain` is set; the queue is per-origin and cannot be shared
  across subdomains.
- **Is localStorage disabled?** Private mode, third-party storage
  blocked inside an iframe, or strict quotas force the SDK to fall
  back to an in-memory queue, which does not survive a reload. The
  fallback is logged in `debug: true`.
- **Has the queue hit `maxQueue` and pruned oldest?** Recent events
  still ship. If this happens steadily, you are buffering offline
  longer than `maxQueue` can hold; raise the cap.

## `revu.identify()` does not seem to take effect

- The call is idempotent. Calling `identify("u_4b9a2")` when the
  current id is already `u_4b9a2` is a no-op, including the synthetic
  `$identify` event. This is by design.
- Empty string or non-string id is a no-op.
- A persisted id survives reloads, so a prior `identify` is restored on
  the next page load even without a fresh call.

## `revu.reset()` does nothing

`reset()` is a no-op when there is no identified user. The intent is
that a redundant sign-out path (multiple components calling reset on
logout) does not accidentally rotate the session for an anonymous
visitor. If you want to force-rotate the session id, prefer
`sessionTimeoutMs: 0` for a session-per-load model.

## I see a `$pageview` per route, but no `$autocapture` clicks

- **Confirm autocapture is on.** `autocapture: false` disables click and
  pageview capture entirely; you would only see explicit `capture()`
  calls.
- **Confirm clicks are reaching the document.** The SDK installs at
  capture phase, so it observes interactions even when the host stops
  propagation at a lower handler. But a higher capture-phase wrapper
  above the SDK can still preempt it.

## Sessions rotate when I do not expect them to

If `session_id` rotates between page loads inside what you think of as
one visit, check:

- **Has the gap exceeded `sessionTimeoutMs`?** The default is 30
  minutes; a 35-minute gap rotates as designed. See
  [concepts.md - sessions](/web/concepts/#sessions-engagement-not-page-visits).
- **Is `sessionTimeoutMs: 0` set?** That explicitly disables
  continuation so every page load gets a brand new session.
- **Is storage being cleared between loads?** If localStorage and
  cookies are both blocked, the session id is in-memory only and rotates
  on every load.

## Type errors against `.d.ts`

JSDoc in `src/types.js` is the single source of truth for both runtime
behavior and emitted types. `bun run types` (from the repo root)
rebuilds the `.d.ts`. If your IDE shows stale types after pulling,
restart the TS server and rerun `bun run types`.

---

# Web SDK: Changelog
Source: https://developers.revu.ai/web/changelog/

# Changelog

All notable changes to `@revu-ai/core` are documented here.

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [0.1.0] - 2026-06-21

First public release. Lean capture core for web behavioral analytics: one-line install, autocapture out of the box, category consent with GPC, client-side campaign attribution, a durable offline queue, persistent first-party identity, and zero runtime dependencies.

### Added

- **One-line boot.** `revu.init({ apiKey })` wires capture, identity, consent, attribution, transport, and the queue in a single call. Every public entry (`init`, `capture`, `identify`, `alias`, `reset`, `optOut`, `optIn`, `hasOptedOut`, `consent.set` / `consent.get`, `flush`, `use`) is wrapped with `safe()` so the SDK can never throw into the host page.
- **Autocapture.** `$pageview` (initial load plus SPA route changes via pushState / replaceState / popstate / hashchange), `$autocapture` (clicks anywhere), `$rightclick`, `$rageclick` (3 clicks on the same target within 1 s), `$scroll` milestones (25 / 50 / 75 / 100%), `$resize` (debounced to settled value), `$form_submit` (field metadata only, never values), `$change` (control type plus checkbox / radio `checked`, never values), `$file_download`, `$outbound_link`, and `$page_restore` (back-forward cache restore). Each element event carries a stable selector fingerprint (tag, text, role, id, classes, ordinal) plus the route path.
- **Engagement layer.** `$page_leave` with `engagement_time_ms` (visible time on the page; hidden time excluded, idle time included), `$tab_hidden` / `$tab_visible` with paired durations, `$idle` / `$active` with paired durations (default `idleTimeoutMs: 30_000`, off when set to `0`). `captureAttention: false` keeps the engagement clock but suppresses the synthetic events.
- **Web Vitals.** `$web_vital` events for LCP, INP, and CLS emitted on terminal page lifecycle (`pagehide` / visibility-hidden). Pure PerformanceObserver, zero runtime dependencies. Disable with `captureWebVitals: false`.
- **Category consent + GPC.** Three consent categories (`analytics`, `marketing`, `functional`) via `revu.consent.set({ ... })` / `revu.consent.get()`, with `revu.optOut()` / `revu.optIn()` / `revu.hasOptedOut()` as aliases for denying / granting `analytics`. Only `analytics` gates capture (a denied analytics category suppresses every event before it is built); `marketing` and `functional` are declarative and stamped on every event as `context.consent` for the server to honor on downstream destinations. Global Privacy Control is stamped as `context.gpc`, and `honorGpc` (default off) defaults `analytics` to denied on a GPC signal unless the visitor has made an explicit choice. State persists in the first-party store; a legacy binary opt-out is honored on upgrade.
- **Campaign attribution.** First touch (`context.initial_utm_*`, `initial_gclid`, `initial_fbclid`, plus `initial_landing_path` / `initial_seen_at`) is captured once and never overwritten; last touch (`context.utm_*`, `gclid`, `fbclid`) refreshes on each new campaign or external-referrer landing. Both persist client-side so a conversion pages or days later still carries the campaign that acquired the visitor; the server still derives a session's immediate landing from the `$pageview` URL.
- **Persistent identity.**
  - `anonymousId` (device-level) generated on first visit and persisted across reloads.
  - `userId` (person-level) with `autoIdentify` default-on: a UUID is auto-generated and persisted; a later `revu.identify("real-id")` replaces it. `revu.reset()` rotates to a fresh auto id.
  - `sessionId` rolls forward across reloads inside a 30-minute continuation window (`sessionTimeoutMs`); set to `0` to give every page load a fresh session. An absolute cap (`sessionMaxMs`, default 24 h) rotates even a continuously-active session so a long-lived tab or kiosk does not accumulate one multi-day session.
  - Both persistent ids mirrored to `localStorage` and a first-party cookie by default, so eviction of one store recovers from the other. Switch with `persistentStorage: "localStorage"` to drop the cookie.
  - `cookieDomain` config shares one visitor across subdomains.
- **Identity transitions.** `$identify`, `$reset` (with `previous_user_id`), and `$alias` events so the server can join the pre- and post-login behavioral graph and stitch a person across devices. `revu.alias(authoritativeId)` declares "the current id is the same person as `authoritativeId`" without changing the local user id (motivating flow: sign up on desktop, click an email link on phone). Idempotent on the server; distinct from `identify()`, which replaces the local id.
- **Pipeline hooks.** `beforeSend(event)` runs on every built event just before it is queued: return the event (mutated or replaced) to send it, `null` / `false` to drop it, or nothing to send it unchanged. Fail-open (a throwing hook sends the original event), and the returned `properties` are re-sanitized so a hook cannot poison the durable queue. `autocaptureAllowSelectors` / `autocaptureDenySelectors` scope element-targeted autocapture by CSS selector; deny wins and suppresses the file-download / outbound-link / rage events derived from a click too.
- **Session sampling.** `sampleRate` (0-1, default `1`) drops whole sessions before they queue. The decision is session-sticky (a session is captured or skipped whole, never half), identity events are always sent, and kept sampled events carry `context.sample_rate` so the server can scale aggregates.
- **Durable transport.** Batched JSON POST to `/v1/behavior/events`. `fetch` with `keepalive: true` while the page is live; `navigator.sendBeacon` on `pagehide` / `visibilitychange=hidden` to flush the last batch on unload. Capped exponential backoff on transient failures; `event_id` is the idempotency key so a retried batch de-dupes server-side.
- **Durable offline queue.** `localStorage`-backed buffer survives reloads and offline gaps. Auto-flushes on the `online` event so events captured offline ship the moment connectivity returns. An unserializable event is quarantined so one bad event never blocks the queue.
- **First-party ingest.** Point `host` at your own domain to route events first-party (data-completeness measure); reverse-proxy recipes (Cloudflare, nginx, Caddy, Next.js) are in `docs/first-party-ingest.md`.
- **Plugin contract.** `revu.use(plugin)` or `init({ plugins: [...] })`. Plugins registered before init are queued and drained on init. The Web Vitals layer ships through this contract as a built-in plugin.
- **Event shape: `context` + `properties`.** Every event carries a top-level `context` object (engine environment, unprefixed: `user_agent`, `language`, `timezone`, `screen_*`, `viewport_*`, `online`, `connection_*`, `environment`, `sdk_version`, `consent`, `gpc`, `sample_rate`, and attribution) separate from `properties` (the event's own payload plus caller `capture()` props). The two buckets never collide, so there is no `$`-prefix and no caller-vs-engine merge - the de-facto context-vs-properties shape every warehouse / BI / SQL consumer expects. `properties.path` remains the per-event path; `screen` is the top-level route.
- **SDK build version.** `context.sdk_version` is stamped on every event so the server can correlate behavior with SDK versions when investigating a regression or rolling out a fix. The same string is exposed as `revu.version`. Source of truth is `package.json`; `src/version.js` is regenerated by `scripts/sync-version.js` (the `prebuild` hook) so a release-day bump touches one file. The generated file is committed so the vanilla example runs straight from `src/`.
- **Environment label.** `environment: "production" | "staging" | "development"` config field (default `"production"`) stamps `context.environment` so the dashboard can keep dev and staging traffic out of the production view. Invalid values throw at init.
- **Input masking and redaction.** Input values are never read from any field. Click fingerprints on `<input>` / `<textarea>` / `<select>` / `contenteditable` / `[data-revu-mask]` subtrees are redacted (tag, role, and selector survive; text, `aria-label`, and `title` are dropped); `$change` skips password / file / hidden inputs entirely; form submits emit metadata only (`field_names`, `field_types`, `field_count`), never values. Credential and PII values in captured URLs and referrers - in both the query string and the fragment (e.g. an OAuth implicit-flow `#access_token=...`) - are scrubbed at source while UTM and click ids are preserved.
- **Shadow DOM coverage.** Clicks inside open Shadow DOM custom elements are captured against the actual internal element via `composedPath()` instead of the retargeted host. Ancestor walks in the fingerprint (selector path) and masking check (`data-revu-mask`) cross the shadow boundary via `ShadowRoot.host`, so a mask on the host applies to its shadow tree and selectors keep their full ancestor context across Web Components and component-library UIs.

### Architecture

- **Vanilla JavaScript (ESM) with JSDoc** as the single source of truth for both runtime and emitted `.d.ts` types.
- **Zero runtime dependencies.** No published package declares a `dependencies` entry. Platform and Web APIs only.
- **Tree-shakeable.** `"sideEffects": false`; unused modules drop out at the consumer's bundler.
- **Bundle size: 32.41 kB minified / 10.22 kB gzipped** (around 9 kB brotli on the wire), under the 34 kB / 12 kB CI gate.
- **Defensive boundary.** Every public entry is `safe()`-wrapped; internal errors are swallowed and (in `debug: true`) logged, never propagated to the host page.

### Security

- Input values are never read from any field (`<input>`, `<textarea>`, `<select>`, `contenteditable`) - only interactions and structure.
- Form submit events carry shape metadata only, never values.
- `data-revu-mask` opts a subtree out of text and label capture; `autocaptureDenySelectors` suppresses capture for a region entirely.
- Credential and PII values in captured URLs and referrers are scrubbed at source - in both the query string and the fragment (UTM and click ids preserved).
- Consent is enforced before an event is built (a denied `analytics` category produces no event); Global Privacy Control is honored when `honorGpc` is set.
- The transport sends only fields explicitly built by the client; no DOM serialization, no cookie reads other than the SDK's own first-party identity cookie.

[0.1.0]: https://github.com/revu-ai/sdk-web/releases/tag/v0.1.0

---

# Android SDK: Overview
Source: https://developers.revu.ai/android/

# Android SDK

The REVU Android SDK is in development. It ports the same contract as the
**[Web SDK](/web/)**: one-line autocapture, first-party identity, durable
batched transport, and the same canonical event shape sent to the shared
**[Ingest API](/api/)**.

The intelligence stays server-side; the SDK stays a small capture-and-transport
layer. Patterns proven in the web reference implementation are carried over
rather than reinvented.

## Status

In active development. This page will fill out with install, configuration, and
API reference as the SDK stabilizes. Until then, the **[Web SDK docs](/web/)**
are the best guide to the shared concepts (identity, sessions, the event shape,
and "interactions, never values"), all of which apply across platforms.

---

# iOS SDK: Overview
Source: https://developers.revu.ai/ios/

# iOS SDK

The REVU iOS SDK is in development. It ports the same contract as the
**[Web SDK](/web/)**: one-line autocapture, first-party identity, durable
batched transport, and the same canonical event shape sent to the shared
**[Ingest API](/api/)**.

The intelligence stays server-side; the SDK stays a small capture-and-transport
layer. Patterns proven in the web reference implementation are carried over
rather than reinvented.

## Status

In active development. This page will fill out with install, configuration, and
API reference as the SDK stabilizes. Until then, the **[Web SDK docs](/web/)**
are the best guide to the shared concepts (identity, sessions, the event shape,
and "interactions, never values"), all of which apply across platforms.

---

# Ingest API: Overview
Source: https://developers.revu.ai/api/

# Ingest API

Every REVU SDK targets the same ingest contract. The SDK captures behavioral
events client-side, batches them, and sends them to a single endpoint; the
server validates, attributes, and stores them. The SDK only captures, never
computes metrics, so this contract is the boundary between the two.

## Endpoint

```http
POST /v1/behavior/events
```

Authenticated with your public write key (`revu_pk_...`), which resolves to your
organization and touchpoint server-side. Requests carry a batch of events in the
canonical event shape.

## The event shape

The canonical event shape is shared across every SDK and documented, with a
worked example, on the Web SDK page:

- **[The canonical event shape](/web/concepts/#the-canonical-event-shape)** -
  `event_id`, `anonymous_id`, `user_id`, `session_id`, `sequence_no`,
  `platform`, `event_type`, `screen`, `fingerprint`, `properties`,
  `device_time`.

## Transport behavior

How the web SDK batches, retries, and flushes against this endpoint (durable
offline queue, capped backoff, terminal flush on unload) is covered in:

- **[Transport and offline](/web/transport/)** - flush triggers, retry and
  backoff, and the dual-signal terminal flush.
- **[First-party ingest](/web/first-party-ingest/)** - route events through your
  own domain with reverse-proxy recipes.

## Reference and spec

- **[API reference](/api/reference/)** - the full endpoint reference (request
  body schema, every field, responses, and copy-paste examples), generated from
  the OpenAPI specification.
- **[openapi.json](/api/openapi.json)** - the machine-readable OpenAPI 3.1
  specification. Point a client generator, a mock server, or an AI agent at it.

---

# Ingest API: API reference
Source: https://developers.revu.ai/api/reference/

# REVU Behavior Ingest API

> The single endpoint every REVU SDK targets to push captured events.

REVU SDKs capture behavioral events client-side, batch them, and POST them to this endpoint. The SDK only captures; the server validates, attributes, and stores. Authentication is a public, browser-embeddable write key (`revu_pk_...`) carried in the request body, not a secret header: it is a tenant identifier that grants only append access to one organization's event log. Ingest is idempotent on (organization, event_id), so retried batches are de-duplicated server-side.

This page is generated from the OpenAPI specification. Download it as
[openapi.json](/api/openapi.json) to drive a client generator, a mock
server, or an AI agent integration.

## Servers

- `https://api.revu.ai` - Production ingest
- `https://{host}` - First-party ingest through your own domain (reverse proxy). See the web SDK first-party-ingest guide.

## Authentication

Authentication is a public write key (`revu_pk_...`) sent in the request
body as `api_key`, not an `Authorization` header. The key is a tenant
identifier safe to embed in client bundles; it grants only append access to
one organization's event log. There are no cookies and no session.

## POST /v1/behavior/events

**Ingest a batch of behavioral events**

Accept a batch of captured events from a REVU SDK. The body carries the public `api_key` and a `batch` of 1 to 200 events. Returns 204 with an empty body on success. The SDK sends `Content-Type: application/json`; on page unload it uses `navigator.sendBeacon` with an `application/json` Blob so the terminal batch still parses.

### Request body

Content type: `application/json`

#### IngestBody

| Field | Type | Required | Constraints | Description |
| ----- | ---- | -------- | ----------- | ----------- |
| `api_key` | string | yes | pattern: `^revu_pk_[A-Za-z0-9_-]{8,120}$` | Public ingest write key (prefix revu_pk_). |
| `batch` | array<BehaviorEvent> | yes | items 1-200 | Up to 200 events per request. |

#### BehaviorEvent

| Field | Type | Required | Constraints | Description |
| ----- | ---- | -------- | ----------- | ----------- |
| `event_id` | string | yes | format: uuid | Client-generated UUID. Unique per organization; the idempotency / dedupe key for retried batches. |
| `anonymous_id` | string | yes | length 1-128 | First-party anonymous visitor (device) id assigned by the SDK. |
| `user_id` | string \| null | no | length 0-128 | Identified user id, if any. Null when the visitor is not yet identified. |
| `session_id` | string | yes | length 1-128 | Per-session id. |
| `sequence_no` | integer | yes | min: 0 | Per-page-load monotonic counter starting at 0. Gaps indicate dropped events within a page load. |
| `platform` | enum | yes | one of: web, ios, android | Capture platform. |
| `event_type` | string | yes | length 1-120 | Event type: '$pageview', '$autocapture', or a custom name. |
| `screen` | string | yes | length 0-2048 | Route / path at capture time. |
| `fingerprint` | object \| null | no |  | Element descriptor, present for $autocapture interactions. Used server-side to name the interacted element. |
| `properties` | object | yes |  | Event payload: capture-layer fields (path, url, depth_percent, form structure, ...) plus caller-supplied custom properties. Client-side masked, PII-free, never input values. |
| `context` | object | no |  | Engine environment bucket (unprefixed): user_agent, language, timezone, screen_* / viewport_*, online, connection_*, environment, sdk_version, consent, gpc, sample_rate, and first/last-touch attribution. Optional: a client that omits it still validates. |
| `device_time` | string | yes | format: date-time | ISO-8601 capture timestamp from the client device. |

##### BehaviorEvent.fingerprint

| Field | Type | Required | Constraints | Description |
| ----- | ---- | -------- | ----------- | ----------- |
| `tag` | string | yes |  | Element tag, e.g. 'button'. |
| `text` | string \| null | no |  | Visible text (truncated; masked if sensitive). |
| `role` | string \| null | no |  | ARIA role / type. |
| `id` | string \| null | no |  | Element id, if present. |
| `classes` | array \| null | no |  | Class list. |
| `selector` | string | yes |  | Best-effort CSS selector (fragile; a tiebreaker). |
| `ordinal` | number | no |  | Position among siblings. |

### Example requests

A `curl` call (the SDK does this for you, batched and retried):

```bash
curl -X POST https://api.revu.ai/v1/behavior/events \
  -H "Content-Type: application/json" \
  -d '{"api_key":"revu_pk_example12345678","batch":[{"event_id":"f1d2c3b4-a5e6-4789-9abc-de0123456789","anonymous_id":"a0e1d2c3-b4a5-4677-8899-aabbccddeeff","user_id":null,"session_id":"11112222-3333-4444-5555-666677778888","sequence_no":0,"platform":"web","event_type":"$pageview","screen":"/pricing","properties":{"path":"/pricing","url":"https://acme.com/pricing"},"context":{"user_agent":"Mozilla/5.0 ...","language":"en-US","timezone":"Europe/Berlin","environment":"production","sdk_version":"0.1.0"},"device_time":"2026-06-21T18:04:05.123Z"}]}'
```

#### A single $pageview event

```json
{
  "api_key": "revu_pk_example12345678",
  "batch": [
    {
      "event_id": "f1d2c3b4-a5e6-4789-9abc-de0123456789",
      "anonymous_id": "a0e1d2c3-b4a5-4677-8899-aabbccddeeff",
      "user_id": null,
      "session_id": "11112222-3333-4444-5555-666677778888",
      "sequence_no": 0,
      "platform": "web",
      "event_type": "$pageview",
      "screen": "/pricing",
      "properties": {
        "path": "/pricing",
        "url": "https://acme.com/pricing"
      },
      "context": {
        "user_agent": "Mozilla/5.0 ...",
        "language": "en-US",
        "timezone": "Europe/Berlin",
        "environment": "production",
        "sdk_version": "0.1.0"
      },
      "device_time": "2026-06-21T18:04:05.123Z"
    }
  ]
}
```

#### An $autocapture click with an element fingerprint

```json
{
  "api_key": "revu_pk_example12345678",
  "batch": [
    {
      "event_id": "0a1b2c3d-4e5f-4061-8273-8495a6b7c8d9",
      "anonymous_id": "a0e1d2c3-b4a5-4677-8899-aabbccddeeff",
      "user_id": "user_8675309",
      "session_id": "11112222-3333-4444-5555-666677778888",
      "sequence_no": 4,
      "platform": "web",
      "event_type": "$autocapture",
      "screen": "/pricing",
      "fingerprint": {
        "tag": "button",
        "text": "Start free trial",
        "role": "button",
        "selector": "main > section.cta button.primary",
        "ordinal": 0
      },
      "properties": {
        "path": "/pricing"
      },
      "context": {
        "environment": "production",
        "sdk_version": "0.1.0"
      },
      "device_time": "2026-06-21T18:04:11.880Z"
    }
  ]
}
```

### Responses

| Status | Meaning |
| ------ | ------- |
| `204` | Batch accepted. Empty body. Already-seen event_ids in the batch are de-duplicated. |
| `401` | The api_key is unknown, or its environment is inactive. |
| `403` | The api_key is valid but the request Origin is not in the key's allowed-origins allowlist. |
| `422` | The body failed schema validation (a missing or malformed field, or a batch outside 1 to 200 events). |
| `429` | The api_key's per-minute rate limit is exhausted. Carries a Retry-After header (seconds). SDK transport treats this as a backoff-and-retry signal; events stay queued. |
| `500` | Unexpected server error. The SDK backs off and retries; events stay queued client-side. |

Every non-204 response carries this body:

#### Error

| Field | Type | Required | Constraints | Description |
| ----- | ---- | -------- | ----------- | ----------- |
| `error` | string | yes |  | Human-readable error message. |
| `code` | string | yes |  | Stable machine-readable code: UNAUTHORIZED, FORBIDDEN, VALIDATION_ERROR, RATE_LIMIT_EXCEEDED, or OPERATION_FAILED. |
| `timestamp` | string | yes | format: date-time | ISO-8601 time the error was produced. |

---