@anyreplay/browser 0.1.4 → 0.2.0

package/dist/index.d.ts

@@ -1,3 +1,335 @@
+interface RecordedEvent {
+    type: number;
+    timestamp: number;
+    data?: unknown;
+}
+interface SessionMeta {
+    startedAt: number;
+    url?: string;
+    lang?: string;
+    userAgent?: string;
+    screenWidth?: number;
+    screenHeight?: number;
+    referrer?: string;
+    /** `maxSessionsPerMonth`, sent only with chunk 0 of a new session. */
+    sessionCap?: number;
+    /** What this SDK records on — always `web` for this one. */
+    platform?: string;
+    /** This SDK, so a session says which release recorded it. */
+    sdk?: {
+        name: string;
+        version: string;
+    };
+    /** Only from a wrapper that knows the app (`ShellInfo` in recorder.ts). */
+    appVersion?: string;
+    deviceModel?: string;
+}
+interface ChunkFlags {
+    hasError?: boolean;
+    hasRageClick?: boolean;
+    pageCount?: number;
+}
+interface TransportContext {
+    projectKey: string;
+    sessionId: string;
+    visitorId: string;
+    /** The first chunk number to use. Non-zero when a page resumes a session. */
+    initialSeq?: number;
+}
+interface TransportHooks {
+    onStopped?: (reason: string) => void;
+    onSent?: (seq: number, eventCount: number) => void;
+    /** Called with the next free chunk number before a request using the current one leaves. */
+    onSeqReserved?: (nextSeq: number) => void;
+    /**
+     * Called when events had to be dropped and the recording needs a fresh
+     * full snapshot to make sense again. The recorder answers by taking one
+     * (`record.takeFullSnapshot`); until it arrives, DOM changes are not kept,
+     * since they would describe nodes the server never saw.
+     */
+    onResyncNeeded?: () => void;
+    /** Debug-only explanations: an event dropped, a body limit lowered. */
+    onWarning?: (message: string) => void;
+}
+/**
+ * Ships buffered events to ingest.
+ *
+ * Three properties matter more than throughput here, because this code runs
+ * inside somebody else's product:
+ *
+ *  - It must never throw into the host page.
+ *  - It must never keep retrying a request the server has rejected on its
+ *    merits (a bad key, a disallowed origin) — that is an infinite loop.
+ *  - It must not lose the session to a network that is merely away: a train
+ *    tunnel, a laptop lid, a flaky café connection. It backs off and waits
+ *    instead of giving up, and keeps a bounded buffer meanwhile.
+ *
+ * And one property of every body it sends: under ingest's size limit. An
+ * outage leaves up to 2000 events waiting; they go out as a run of chunks of
+ * at most 200 events and about 256 KB each, in order, never as one body ingest
+ * would refuse.
+ */
+declare class Transport {
+    private readonly options;
+    private readonly context;
+    private readonly hooks;
+    private buffer;
+    /** The chunk being delivered: built, numbered, maybe already attempted. */
+    private pending;
+    /** The next unused chunk number. */
+    private seq;
+    private consecutiveFailures;
+    private consecutiveRefusals;
+    private state;
+    private timer;
+    private retryTimer;
+    private pendingMeta;
+    private flags;
+    private inFlight;
+    private staleRecoveries;
+    /** Our own backoff after a failure. Cleared when the network comes back. */
+    private backoffUntil;
+    /** What the server asked for in `Retry-After`. Not cleared by anything but time. */
+    private serverWaitUntil;
+    /** Largest body this transport will build; lowered by a `413`. */
+    private bodyLimit;
+    private targetBytes;
+    /**
+     * Set when events were dropped and a full snapshot has been asked for:
+     * DOM changes are not kept until it arrives.
+     */
+    private awaitingSnapshot;
+    /** Serialised events, so a retry or a re-split does not stringify a snapshot twice. */
+    private readonly serialised;
+    constructor(options: ResolvedOptions, context: TransportContext, hooks?: TransportHooks);
+    get isStopped(): boolean;
+    /** Events not yet delivered, including a chunk waiting to be retried. */
+    get bufferedCount(): number;
+    /** The number the next undelivered chunk will carry — the count of chunks delivered, for a fresh session. */
+    get sentChunks(): number;
+    /** The most events kept while deliveries fail. Older ones are dropped first. */
+    private get bufferLimit();
+    /** Attaches metadata to the next chunk. Sent once, with the session's first chunk. */
+    setMeta(meta: SessionMeta): void;
+    mergeFlags(flags: ChunkFlags): void;
+    start(): void;
+    stop(reason: string): void;
+    push(event: RecordedEvent): void;
+    /**
+     * The network is back (`online`), or the page is visible again: try now
+     * rather than at the end of the backoff. A server's `Retry-After` still
+     * holds — it was not about our connection.
+     */
+    resume(): void;
+    /**
+     * Sends whatever is buffered, as as many chunks as it takes. Safe to call
+     * when there is nothing to send, and while waiting out a failure, when it
+     * does nothing. `force` skips our own backoff (an explicit `flush()` from
+     * the page) but never the server's `Retry-After`.
+     */
+    flush(force?: boolean): Promise<void>;
+    /**
+     * Builds the next chunk from the front of the buffer: at most
+     * `maxEventsPerChunk` events and `target` bytes, or one event alone up to
+     * `limit`. An event too large for any chunk is dropped here — it would be
+     * refused, and refused again, and hold up everything behind it. For a
+     * beacon (`forBeacon`) it is left where it is instead: an ordinary request
+     * can still carry what a beacon cannot.
+     */
+    private nextChunk;
+    /**
+     * An event that no chunk can carry. A DOM change or a custom event is
+     * dropped, and the DOM is re-sent whole if the dropped one described it.
+     * A full snapshot that alone exceeds the limit is a page this transport
+     * cannot record — re-taking it would only be refused again — so recording
+     * stops instead of uploading a snapshot every few seconds forever.
+     */
+    private dropOversized;
+    private serialise;
+    /** Everything in a chunk's body except its events, as a JSON object. */
+    private envelope;
+    /**
+     * The body, assembled from the events' cached JSON rather than by
+     * stringifying them again: a retry resends exactly the bytes the first
+     * attempt sent, which is also what lets ingest read it as a retry.
+     */
+    private body;
+    /** One request, and what to do next. */
+    private send;
+    /**
+     * `413`: this ingest takes less than we thought. The chunk was not stored,
+     * so its events go back to the front of the queue and are re-cut under a
+     * lower limit; its number is not reused, so no number ever carries two
+     * different sets of events. A chunk of one event that is still too large is
+     * dropped by `nextChunk` on the way back out.
+     */
+    private shrink;
+    /**
+     * Counts a failed delivery and schedules the next attempt: 2 s, 4 s, 8 s …
+     * up to a minute, each with jitter so a thousand tabs that lost the same
+     * Wi-Fi do not all come back in the same second. The chunk stays pending,
+     * to be resent under the same number.
+     *
+     * Recording does not stop over this unless the page asked for it with
+     * `maxConsecutiveFailures`: the buffer exists for exactly this, and a
+     * phone in a tunnel for half a minute must not end the visit's recording.
+     */
+    private registerFailure;
+    /**
+     * The attempt at the end of a backoff. It skips the backoff check itself:
+     * a timer may fire a fraction of a millisecond "early" against `Date.now`,
+     * and refusing then would leave nothing scheduled until the next tick.
+     */
+    private scheduleRetry;
+    /**
+     * Keeps the buffer bounded during a long outage. Older events go first — a
+     * replay missing a stretch is still useful; a crashed page is not. A chunk
+     * waiting to be retried is the oldest of all, and goes whole: sending part
+     * of it under its number could clash with an attempt that did arrive.
+     */
+    private dropOldest;
+    /**
+     * After events were dropped: DOM changes left before the next full snapshot
+     * may describe nodes whose creation was dropped, and a replay applying them
+     * breaks. They go, and when the buffer holds no snapshot to start again
+     * from, the recorder is asked for one. Custom events, errors and the like
+     * do not depend on the DOM and stay.
+     */
+    private afterGap;
+    /**
+     * Last-gasp send when the page is going away or hidden.
+     *
+     * `fetch` is cancelled once the document unloads, so the tail of every
+     * session would be lost. `sendBeacon` hands the payload to the browser, which
+     * delivers it after the page is gone — but only up to 64 KB in flight, so
+     * the tail goes as a run of small chunks, oldest first, until the browser
+     * says it has no room. What it refuses stays buffered for the page's next
+     * flush, should there be one (a hidden tab that comes back, a page restored
+     * from the back/forward cache).
+     *
+     * For a tab that is only hidden, and so likely to come back, nothing goes
+     * while deliveries are failing or the server asked us to wait: a beacon
+     * "queued" while offline is usually a beacon lost, where the buffer and the
+     * backoff would have delivered it. On `pagehide` (`final`), the last
+     * chance there is, it goes regardless.
+     */
+    flushWithBeacon(final?: boolean): boolean;
+    /** Hands one chunk to the browser. False when its beacon queue is full. */
+    private beacon;
+}
+
+/**
+ * Making a recording carry the files a page loaded from inside an app.
+ *
+ * A website's replay loads its stylesheets, fonts and images from the site,
+ * later, in the reviewer's browser: the snapshot records `https://shop.com/
+ * logo.png` and the dashboard asks shop.com for it. That is `'reference'`, and
+ * it is right for anything on a public origin.
+ *
+ * A page inside an app has no such origin. Capacitor serves the app from
+ * `capacitor://localhost` (iOS) or `https://localhost` (Android), Cordova from
+ * `app://localhost`, `https://localhost` or `file://`, Ionic's older shells
+ * from `ionic://localhost`, Tauri from `tauri://localhost`, Electron often from
+ * `file://`. Those addresses mean "inside this phone" — no reviewer can load
+ * them — so the replay came out as bare HTML.
+ *
+ * `'inline'` makes the recording carry what it needs instead:
+ *
+ * - **Stylesheets** were already inside it: rrweb copies every readable
+ *   stylesheet into the snapshot as text (`inlineStylesheet`, on in both
+ *   modes), and an app's own CSS is always readable.
+ * - **Images** (PNG, JPEG, GIF, WebP) are uploaded once per project by
+ *   content hash through the same routes the native SDKs use (contract §9),
+ *   at most 3 MB each, and the session says which file stood at which URL.
+ * - **Fonts** (WOFF2, WOFF, TTF, OTF) and **SVG images** cannot be uploaded —
+ *   ingest stores raster images only — so they travel inside the recording as
+ *   `data:` URLs, each in its own event, under a per-file cap and a per-page
+ *   budget that keep every chunk inside the transport's 256 KB target.
+ *
+ * In both cases the recording keeps the original URL wherever the page used
+ * it, and an `anyreplay.asset` custom event maps that URL to the uploaded
+ * hash or to the inline data. The dashboard's player rewrites those URLs
+ * before it builds the replay. Nothing in the DOM snapshot is changed, so a
+ * recording made with this on replays exactly as before in a player that does
+ * not know about it — unstyled, as it always was.
+ *
+ * Only the app's own files are read: URLs under the page's own origin (for
+ * `file://`, under the page's own folder). Capacitor's and Cordova's bridges
+ * to the device's files (`/_capacitor_file_/…`, `/__cdvfile_…`) are excluded
+ * by path, because what they serve is the user's photos and downloads, not
+ * the app. Anything that fails — a fetch, an upload, a cap — leaves that one
+ * file as it was: missing from the replay, and nothing else.
+ */
+type AssetMode = 'reference' | 'inline';
+/** The custom event that maps a URL the page used to the file that was there. */
+declare const ASSET_TAG = "anyreplay.asset";
+/** `{ url, sha256 }` for an uploaded image, `{ url, data }` for a file carried inline. */
+type AssetPayload = {
+    url: string;
+    sha256: string;
+} | {
+    url: string;
+    data: string;
+};
+interface AssetLimits {
+    /** An image larger than this is not uploaded (ingest's own limit). */
+    maxImageBytes: number;
+    /** A font larger than this is not carried inline. */
+    maxFontBytes: number;
+    /** An SVG larger than this is not carried inline. */
+    maxSvgBytes: number;
+    /** All inline files of one page together, before base64. */
+    inlineBudgetBytes: number;
+    /** Distinct URLs looked at per page; anything after is left as it is. */
+    maxUrls: number;
+}
+/**
+ * The caps, and why each is what it is.
+ *
+ * A font of 160 KB is 214 KB as base64: alone in its chunk with the envelope
+ * it stays under the transport's 256 KB target, so no chunk is ever built
+ * around something ingest could refuse. Almost every WOFF2 an app ships is
+ * well under it; an icon font or a CJK font that is not is left out, and the
+ * replay falls back to the next font in the stack. One megabyte across a page
+ * is about six fonts and a few icons, which is more than an app uses, and
+ * small enough that a page with a hundred SVG icons does not turn its first
+ * minute into a download.
+ */
+declare const ASSET_LIMITS: AssetLimits;
+interface LocationLike {
+    protocol: string;
+    host: string;
+    hostname: string;
+    pathname: string;
+}
+/**
+ * What `assets` is when the page does not say.
+ *
+ * `'inline'` for any scheme that is not `http:` or `https:` — `capacitor:`,
+ * `ionic:`, `app:`, `tauri:`, `file:` and whatever a shell invents next. No
+ * website is served that way, so nobody outside the device could load the
+ * page's own files.
+ *
+ * `'reference'` for every `http(s)` page, `localhost` included. A developer
+ * trying their website on `http://localhost:3000` should not upload its
+ * images into the project's quota — the replay of a page on their own machine
+ * loads fine on that machine. The shells that serve an app from an
+ * `http(s)://localhost` address (Capacitor and Cordova on Android, Tauri on
+ * Windows) say `'inline'` themselves: `@anyreplay/capacitor`,
+ * `@anyreplay/cordova` and `@anyreplay/tauri` pass it, and so does
+ * `@anyreplay/electron`.
+ */
+declare function defaultAssetMode(loc?: LocationLike | undefined): AssetMode;
+/**
+ * The start every URL of the app's own files shares, or null when there is
+ * nothing to look for.
+ *
+ * `scheme://host/` for anything with a host. For `file:` it is the page's own
+ * folder: `file://` alone would match every file on the disk, and an Electron
+ * app showing a document the user opened must not upload that document.
+ */
+declare function localAssetPrefix(loc?: LocationLike | undefined): string | null;
+
 interface AnyReplayOptions {
     /** Public project key from the dashboard. */
     projectKey: string;
@@ -51,8 +383,44 @@ interface AnyReplayOptions {
     maxEventsPerChunk?: number;
     /** Flush at least this often, in milliseconds. */
     flushIntervalMs?: number;
-    /** Recording stops after this many consecutive transport failures. */
+    /**
+     * Stop recording after this many failed deliveries in a row (offline, a
+     * timeout, `429`, `5xx`). `0`, the default, never stops: failed chunks are
+     * kept (up to ten chunks' worth of events, oldest dropped first) and
+     * retried with a backoff of 2 s doubling to a minute, and at once when the
+     * browser comes back online or the tab becomes visible.
+     */
     maxConsecutiveFailures?: number;
+    /**
+     * Record uncaught exceptions and unhandled rejections, with their stacks.
+     *
+     * On by default: a replay of a page that broke is worth far more with the
+     * error beside it, and an exception is the page's own diagnostic rather than
+     * anything a visitor typed. The message, the error name and the stack are
+     * recorded; secrets, addresses and card-shaped numbers are taken out of all
+     * three first (see `diagnostics.ts`).
+     */
+    recordErrors?: boolean;
+    /**
+     * Record `console.error` and `console.warn` calls.
+     *
+     * On by default, and the one stream here with no predictable contents: a
+     * console line is whatever the page chose to print, which on some sites
+     * includes data about the person using it. The same redaction runs over
+     * every line, but a page that prints something it would not want a
+     * teammate to read should turn this off. `log`, `info` and `debug` are
+     * never recorded at any setting.
+     */
+    recordConsole?: boolean;
+    /**
+     * Record one entry per `fetch`/`XMLHttpRequest`: method, URL, status code
+     * and duration.
+     *
+     * On by default. **No request or response body is ever recorded**, and no
+     * headers — not a sampled copy, not a truncated one. The URL is redacted
+     * before it is kept. Requests to the ingest endpoint are skipped.
+     */
+    recordNetwork?: boolean;
     /**
      * The most sessions this project may record per calendar month (UTC).
      *
@@ -62,17 +430,81 @@ interface AnyReplayOptions {
      * wins. Positive integer, at most 1,000,000.
      */
     maxSessionsPerMonth?: number;
+    /**
+     * The app this page runs inside, when it runs inside one: the bundle id or
+     * package name of a Capacitor, Cordova or Electron app
+     * (`com.example.shop`).
+     *
+     * Leave it out on a website. An app's web view has no real web origin —
+     * `capacitor://localhost`, `https://localhost`, `file://` — so a project
+     * that lists allowed domains refuses it; listing the same id under the
+     * project's allowed apps, and passing it here, lets it record. Sent in
+     * every request body, never as a header: a header would cost a CORS
+     * preflight per request, and `sendBeacon` cannot send one.
+     *
+     * A filter, not a secret. Ingest ignores it on a request from a real
+     * website, so it cannot open a web project's allow-list, and anyone holding
+     * the public key can send any id from outside a browser.
+     */
+    appId?: string;
+    /**
+     * Whether the recording refers to the page's images and fonts by URL, or
+     * carries them.
+     *
+     * `'reference'` records URLs, and the replay loads each file from where the
+     * page did: right for a website, whose files anyone can load later.
+     * `'inline'` is for a page whose files nobody else can load — an app's web
+     * view (`capacitor://localhost`, `https://localhost`, `file://`) or a
+     * desktop shell. Images the app ships are uploaded once per project by
+     * content hash (PNG, JPEG, GIF, WebP, up to 3 MB each), and its fonts and
+     * SVGs travel inside the recording (up to 160 KB per font, 48 KB per SVG and
+     * 1 MB per page), so the replay looks like the app instead of bare HTML.
+     * Stylesheets are copied into the recording in both modes.
+     *
+     * Leave it out and it is `'inline'` when the page is served from anything
+     * other than `http:`/`https:`, or from `localhost`, `127.0.0.1`, `[::1]` or a
+     * `*.localhost` host; `'reference'` everywhere else. Only files under the
+     * page's own origin (for `file:`, its own folder) are ever read, and never
+     * the device-file bridges Capacitor and Cordova serve user files through.
+     * See `assets.ts`.
+     */
+    assets?: AssetMode;
     debug?: boolean;
 }
-interface ResolvedOptions extends Required<Omit<AnyReplayOptions, 'ingestUrl' | 'maxSessionsPerMonth'>> {
+interface ResolvedOptions extends Required<Omit<AnyReplayOptions, 'ingestUrl' | 'maxSessionsPerMonth' | 'appId' | 'assets'>> {
+    /** Always decided: the page's choice, or what `defaultAssetMode` reads from its address. */
+    assets: AssetMode;
     ingestUrl: string;
     maxSessionsPerMonth?: number;
+    appId?: string;
 }
-declare const DEFAULTS: Omit<ResolvedOptions, 'projectKey'>;
+declare const DEFAULTS: Omit<ResolvedOptions, 'projectKey' | 'assets'>;
 declare class ConfigError extends Error {
 }
 declare function resolveOptions(input: AnyReplayOptions): ResolvedOptions;
 
+/**
+ * What an SDK that wraps this one says about the app the page runs in.
+ *
+ * Not an option: a website never has one. `@anyreplay/capacitor`,
+ * `@anyreplay/cordova` and the desktop shells pass it as `createRecorder`'s
+ * second argument, so a session names the SDK that was installed and the
+ * platform it runs on (contract §2.3–§2.5) while the recording itself — rrweb,
+ * masking, transport — stays this package's, unchanged (contract §4).
+ */
+interface ShellInfo {
+    /** One of the web family's platforms: `capacitor`, `cordova`, `electron`, `tauri`. */
+    platform: string;
+    /** The wrapper's own npm name and version. */
+    sdk: {
+        name: string;
+        version: string;
+    };
+    /** The app's user-visible version (`CFBundleShortVersionString`, `versionName`), ≤ 40. */
+    appVersion?: string;
+    /** The hardware model (`iPhone15,2`, `Pixel 8`), ≤ 64. */
+    deviceModel?: string;
+}
 type RecorderStatus = 'idle' | 'awaiting-consent' | 'recording' | 'sampled-out' | 'stopped';
 interface IdentifyTraits {
     userId?: string;
@@ -92,10 +524,19 @@ interface RecorderHandle {
      * own handlers.
      */
     track: (name: string, properties?: Record<string, unknown>) => void;
+    /**
+     * Records an error the page caught itself — a failed checkout handled with a
+     * message, an error another tracker saw first — as the same `anyreplay.error`
+     * event an uncaught one becomes: redacted by the same rules, counted against
+     * the same ceiling, and setting the session's `hasError`. Accepts anything
+     * that can be thrown. Ignored with `recordErrors: false`. Before recording
+     * starts it is held like `track` and still flags the session once it does.
+     */
+    trackError: (error: unknown) => void;
     stop: () => void;
     flush: () => Promise<void>;
 }
-declare function createRecorder(rawOptions: AnyReplayOptions): RecorderHandle;
+declare function createRecorder(rawOptions: AnyReplayOptions, shell?: ShellInfo): RecorderHandle;
 
 /**
  * FNV-1a. Small, fast, and good enough to spread visitor ids uniformly across
@@ -111,98 +552,6 @@ declare function hashToUnitInterval(input: string): number;
  */
 declare function isSampledIn(visitorId: string, sampleRate: number): boolean;
 
-interface RecordedEvent {
-    type: number;
-    timestamp: number;
-    data?: unknown;
-}
-interface SessionMeta {
-    startedAt: number;
-    url?: string;
-    lang?: string;
-    userAgent?: string;
-    screenWidth?: number;
-    screenHeight?: number;
-    referrer?: string;
-    /** `maxSessionsPerMonth`, sent only with chunk 0 of a new session. */
-    sessionCap?: number;
-}
-interface ChunkFlags {
-    hasError?: boolean;
-    hasRageClick?: boolean;
-    pageCount?: number;
-}
-interface TransportContext {
-    projectKey: string;
-    sessionId: string;
-    visitorId: string;
-    /** The first chunk number to use. Non-zero when a page resumes a session. */
-    initialSeq?: number;
-}
-interface TransportHooks {
-    onStopped?: (reason: string) => void;
-    onSent?: (seq: number, eventCount: number) => void;
-    /** Called with the next free chunk number before a request using the current one leaves. */
-    onSeqReserved?: (nextSeq: number) => void;
-}
-/**
- * Ships buffered events to ingest.
- *
- * Three properties matter more than throughput here, because this code runs
- * inside somebody else's product:
- *
- *  - It must never throw into the host page.
- *  - It must never keep retrying a request the server has rejected on its
- *    merits (a bad key, a disallowed origin) — that is an infinite loop.
- *  - It must not lose the tail of a session when the tab closes.
- */
-declare class Transport {
-    private readonly options;
-    private readonly context;
-    private readonly hooks;
-    private buffer;
-    private seq;
-    private consecutiveFailures;
-    private state;
-    private timer;
-    private pendingMeta;
-    private flags;
-    private inFlight;
-    /** The chunk number of the last request that left, to tell a retry from a first attempt. */
-    private lastAttemptedSeq;
-    private staleRecoveries;
-    constructor(options: ResolvedOptions, context: TransportContext, hooks?: TransportHooks);
-    get isStopped(): boolean;
-    get bufferedCount(): number;
-    get sentChunks(): number;
-    /** Attaches metadata to the next chunk. Sent once, with the session's first chunk. */
-    setMeta(meta: SessionMeta): void;
-    mergeFlags(flags: ChunkFlags): void;
-    start(): void;
-    stop(reason: string): void;
-    push(event: RecordedEvent): void;
-    private body;
-    /** Sends whatever is buffered. Safe to call when there is nothing to send. */
-    flush(): Promise<void>;
-    /**
-     * Puts a failed batch back at the front of the queue.
-     *
-     * Bounded on purpose: a long offline period must not grow the buffer until
-     * the tab runs out of memory. Older events are dropped first — a replay
-     * missing its beginning is still useful; a crashed page is not.
-     */
-    private requeue;
-    private registerFailure;
-    /**
-     * Last-gasp send when the page is going away.
-     *
-     * `fetch` is cancelled once the document unloads, so the tail of every
-     * session would be lost. `sendBeacon` hands the payload to the browser, which
-     * delivers it after the page is gone.
-     */
-    flushWithBeacon(): boolean;
-}
-
 /** RFC 4122 v4, formatted. Ingest requires a UUID for the session id. */
 declare function uuidv4(): string;
 interface Storage {
@@ -272,4 +621,157 @@ interface TrackPayload {
  */
 declare function validateTrack(name: unknown, properties: unknown): TrackPayload | string;
 
-export { type AnyReplayOptions, ConfigError, DEFAULTS, EVENT_NAME_PATTERN, MAX_PROPERTIES_BYTES, NAVIGATE_TAG, type RecordedEvent, type RecorderHandle, type RecorderStatus, type ResolvedOptions, type SessionMeta, TRACK_TAG, type TrackPayload, Transport, createRecorder, forgetVisitor, hashToUnitInterval, isSampledIn, resolveIdentity, resolveOptions, safeStorage, uuidv4, validateTrack };
+/**
+ * What a developer opens a replay to find out: what broke.
+ *
+ * Three streams, each a reserved custom-event tag inside the rrweb stream so
+ * they carry the recording's own clock and replay in order with the clicks
+ * that caused them:
+ *
+ * - `anyreplay.error`   — uncaught exceptions and unhandled rejections.
+ * - `anyreplay.console` — `console.error` and `console.warn` calls.
+ * - `anyreplay.network` — one entry per fetch/XHR, metadata only.
+ *
+ * `anyreplay.error` and `anyreplay.network` are a contract that already has a
+ * reader: `packages/insights/src/rrweb.ts` has been looking for those tags,
+ * and the `js_error`, `error_click` and `network_error` detectors have been
+ * waiting for them. The payload field names here are the ones that file reads
+ * (`message`; `url`, `status`, `method`) — renaming one silently empties three
+ * signals, so they are pinned by a test in both packages.
+ *
+ * ## What never leaves the page
+ *
+ * No request or response bodies, no request headers, no cookies. A URL is
+ * recorded, so a URL is redacted first: a query value whose key names a
+ * secret, anything shaped like an email address, a long opaque token and
+ * anything that passes the card-number check are replaced before the entry is
+ * built. The same redaction runs over console messages, which are arbitrary
+ * strings a page chose to print and so the least predictable thing here.
+ *
+ * ## Why the caps are low
+ *
+ * A page in a render loop can print thousands of warnings a second, and a
+ * dashboard polling four endpoints makes a request a second for an hour. The
+ * value of all of it is in the first few of each kind near the moment
+ * something went wrong, so each stream has a per-session ceiling and drops
+ * quietly once it is reached. Nothing here grows without bound, and nothing
+ * here throws: every entry point is wrapped, because this code runs inside
+ * the page's own `fetch` and its own `console`.
+ */
+/** Contract with `packages/insights/src/rrweb.ts` and `apps/ingest/src/custom-events.ts`. */
+declare const ERROR_TAG = "anyreplay.error";
+declare const CONSOLE_TAG = "anyreplay.console";
+declare const NETWORK_TAG = "anyreplay.network";
+/**
+ * Per-session ceilings.
+ *
+ * Errors are the point of the feature and the rarest, so they get the most
+ * room relative to how often they happen; network is the chattiest and so is
+ * capped hardest per unit of value.
+ */
+declare const LIMITS: {
+    readonly error: 100;
+    readonly console: 200;
+    readonly network: 500;
+};
+declare const REDACTED = "[redacted]";
+/**
+ * Removes from free text the three things that turn up in it by accident:
+ * an address, a token, a card number.
+ *
+ * Deliberately blunt. This is applied to strings a page printed or a URL it
+ * requested, where there is no structure to reason about and the cost of a
+ * false positive — a redacted order id — is far below the cost of a miss.
+ */
+declare function redactText(text: string): string;
+/**
+ * A URL with its secrets taken out, kept absolute so the host is still visible.
+ *
+ * Query values are replaced by key first — `?token=abc` is a secret even when
+ * `abc` is three letters — and then the whole thing goes through the free-text
+ * redaction, which catches an address or a token sitting in the path. The hash
+ * is dropped: it never reaches a server, and on a hash-routed app it is the
+ * one part most likely to hold an id.
+ */
+declare function redactUrl(raw: string): string;
+interface ErrorPayload {
+    /** Read by the insights timeline. Redacted and clipped. */
+    message: string;
+    /** `Error`, `TypeError`, … when the thrown value was an Error. */
+    name?: string;
+    /** Redacted and clipped; absent when the thrown value carried none. */
+    stack?: string;
+    /** How it reached us, which is how severe it is: a rejection nobody handled is not a thrown error. */
+    kind: 'error' | 'rejection';
+    /** Where it was thrown, when the browser said. Already a redacted URL. */
+    source?: string;
+    line?: number;
+    column?: number;
+}
+interface ConsolePayload {
+    level: 'error' | 'warn';
+    /** The arguments, joined and redacted. */
+    message: string;
+}
+interface NetworkPayload {
+    /** Read by the insights timeline. A redacted absolute URL. */
+    url: string;
+    /** Read by the insights timeline. Upper case. */
+    method: string;
+    /** Read by the insights timeline. 0 when the request never got a response. */
+    status: number;
+    /** Wall-clock milliseconds from call to settled, rounded. */
+    durationMs: number;
+    /** Which API the page used, which is all the panel needs to group them. */
+    initiator: 'fetch' | 'xhr';
+    /** Present and true when the request failed outright (network error, CORS, abort). */
+    failed?: boolean;
+}
+/** The thrown value, described however it arrived — pages throw strings. */
+declare function errorPayload(kind: ErrorPayload['kind'], value: unknown, where?: {
+    source?: unknown;
+    line?: unknown;
+    column?: unknown;
+}): ErrorPayload;
+declare function consolePayload(level: ConsolePayload['level'], args: readonly unknown[]): ConsolePayload;
+interface DiagnosticsOptions {
+    /** Emit uncaught errors and unhandled rejections. */
+    errors: boolean;
+    /** Emit `console.error` and `console.warn`. */
+    console: boolean;
+    /** Emit one entry per fetch/XHR. */
+    network: boolean;
+    /** Where entries go. Called with a reserved tag and a payload. */
+    emit: (tag: string, payload: unknown) => void;
+    /** Called the first time an error or a failed request is seen, so the session is flagged. */
+    onError: () => void;
+    /** Ingest's own endpoint, so the recorder never records itself. */
+    ingestUrl: string;
+}
+interface DiagnosticsHandle {
+    /** Puts back every patched global, in reverse order. Safe to call twice. */
+    stop: () => void;
+    /**
+     * An error the page caught itself (`trackError`): redacted, counted against
+     * the same per-session ceiling and flagging the session exactly as an
+     * uncaught one would.
+     */
+    error: (value: unknown) => void;
+}
+/**
+ * Patches `console`, `window` and the two request APIs, and gives back the
+ * single function that undoes all of it.
+ *
+ * Patching is the only way to see any of this from a library, so the rules
+ * are strict: the original is captured once and always called, its return
+ * value is always passed through untouched, and everything this adds sits in
+ * a `try` so that a bug here cannot break a page's error handling or its
+ * network layer. Requests to the ingest endpoint are skipped — recording the
+ * recorder is noise that also grows with itself.
+ */
+declare function startDiagnostics(options: DiagnosticsOptions): DiagnosticsHandle;
+
+declare const SDK_NAME = "@anyreplay/browser";
+declare const SDK_VERSION: string;
+
+export { ASSET_LIMITS, ASSET_TAG, type AnyReplayOptions, type AssetLimits, type AssetMode, type AssetPayload, CONSOLE_TAG, ConfigError, type ConsolePayload, DEFAULTS, type DiagnosticsHandle, ERROR_TAG, EVENT_NAME_PATTERN, type ErrorPayload, LIMITS, MAX_PROPERTIES_BYTES, NAVIGATE_TAG, NETWORK_TAG, type NetworkPayload, REDACTED, type RecordedEvent, type RecorderHandle, type RecorderStatus, type ResolvedOptions, SDK_NAME, SDK_VERSION, type SessionMeta, type ShellInfo, TRACK_TAG, type TrackPayload, Transport, consolePayload, createRecorder, defaultAssetMode, errorPayload, forgetVisitor, hashToUnitInterval, isSampledIn, localAssetPrefix, redactText, redactUrl, resolveIdentity, resolveOptions, safeStorage, startDiagnostics, uuidv4, validateTrack };