@elu-labs/analytics-browser 1.410.4 → 1.411.1

package/dist/index.d.ts

@@ -1,3 +1,52 @@
+/**
+ * The `autocapture` initialization option as the 1.409.5 bundle read it: `true` or omitted turns
+ * interaction capture on, `false` turns it off, and an object turns it on narrowed by its lists.
+ * A page written for that bundle passes the object; before this reader an object counted as
+ * `false` and silently switched autocapture off.
+ *
+ * Only own data values are read, never accessors or inherited keys. A list the bundle could not
+ * have used either (not an array, an unreadable entry, a URL pattern that does not compile) turns
+ * autocapture off: the bundle threw on every event under such a configuration and captured
+ * nothing, and a filter that cannot be applied must not widen capture.
+ *
+ * The object's `capture_copied_text` is read here as well, so the option has one reader: a boolean
+ * in the object decides for the copied-text collector before the page's top-level
+ * `capture_copied_text`, and an object autocapture cannot run under never asks for copied text.
+ *
+ * `element_attribute_ignorelist` names attributes that must not leave the page when an element-content
+ * grant sends attributes; `createEluAttributeAdmission` judges one attribute name by it exactly as the
+ * bundle did. At this base every chain is structural (tag and position only), so the admission has
+ * no attribute to refuse yet; the element-content reader that sends attributes consults it.
+ */
+/**
+ * The event types the 1.409.5 `DomAutocaptureEvents` named. As in that bundle, a `dom_event_allowlist`
+ * is applied to `copy` and `cut` as well: a list that does not name them refuses copied text.
+ */
+type EluAutocaptureDomEvent = 'click' | 'change' | 'submit';
+/** The 1.409.5 `AutocaptureConfig` object. `capture_copied_text` is accepted here; its collector is separate. */
+interface EluAutocaptureConfigInput {
+    /** Capture only on pages whose URL matches one entry (a regular expression, or a string compiled as one). */
+    readonly url_allowlist?: readonly (string | RegExp)[];
+    /** Never capture on pages whose URL matches an entry; checked after the allowlist. */
+    readonly url_ignorelist?: readonly (string | RegExp)[];
+    /** Capture only these DOM events. */
+    readonly dom_event_allowlist?: readonly EluAutocaptureDomEvent[];
+    /** Capture only when the target or an ancestor has one of these lower-case tag names. */
+    readonly element_allowlist?: readonly string[];
+    /** Capture only when the target or an ancestor matches one of these selectors; `[]` captures nothing. */
+    readonly css_selector_allowlist?: readonly string[];
+    /** Never capture when the target or an ancestor matches one of these selectors. The SDK's own no-capture markers always apply. */
+    readonly css_selector_ignorelist?: readonly string[];
+    /**
+     * Attribute names an element-content grant must not send, matched by exact name as the bundle
+     * matched them (`data-user-email` does not cover `data-User-Email`). Judged through
+     * `createEluAttributeAdmission` wherever attributes are read; a structural chain carries none.
+     */
+    readonly element_attribute_ignorelist?: readonly string[];
+    /** Asks for `$copy_autocapture`; a boolean here decides before the page's top-level `capture_copied_text`. */
+    readonly capture_copied_text?: boolean;
+}
+
 /** Exact declared source configuration; source key/token inference across sites is forbidden. */
 interface LegacyStorageOptions {
     readonly sourceArtifactSha256: string;
@@ -21,13 +70,108 @@ interface V1JsonObject {
 interface PerformanceCaptureConfig {
     readonly memory?: boolean;
     readonly long_tasks?: boolean;
-    /** Core Web Vitals (LCP, FCP, CLS, INP) reported as `$web_vitals`. On when omitted or `true`; any other value turns them off. */
+    /**
+     * Core Web Vitals (LCP, FCP, CLS, INP) reported as `$web_vitals`. `true` turns them on for this
+     * page and `false` off; omitted, the ELU project's `captureWebVitals` decides. A boolean
+     * `capture_performance` decides the same way.
+     */
     readonly web_vitals?: boolean;
     /** Milliseconds between visible-page samples. Defaults to 30,000; minimum 5,000. */
     readonly sample_interval_ms?: number;
 }
 type EluPerformanceCaptureOptions = boolean | Readonly<PerformanceCaptureConfig>;
 
+/**
+ * The `session_recording` members a page may set: the full-snapshot cadence, the replay network
+ * narrowing and the masking members below. Every other member is ignored.
+ */
+interface EluSessionRecordingOptions {
+    /**
+     * Milliseconds of activity between full snapshots of the page. The recorder takes one when it
+     * starts and another at the first change after this long, so a replay can always be rebuilt
+     * from a recent checkpoint: seeking lands on one, and a player that cannot apply an
+     * incremental change recovers at the next. Default 300 000 (five minutes); a value is kept
+     * between 10 000 and 1 800 000. The earlier script's `0` no longer turns checkpoints off.
+     */
+    readonly full_snapshot_interval_millis?: number;
+    /** Request and response headers in replay network capture: `true` records them, `false` never does; omitted, the instance decides. */
+    readonly recordHeaders?: boolean;
+    /** Request and response bodies in replay network capture: `true` records them, `false` never does; omitted, the instance decides. */
+    readonly recordBody?: boolean;
+    /**
+     * Canvas pixels in replay, as the earlier bundle read it: `recordCanvas` decides for the page
+     * (omitted, the instance decides), `canvasFps` (1 to 12) and `canvasQuality` (above 0, at most 1)
+     * replace the instance's rate and WebP quality. Pixels are recorded only while the instance's
+     * masking allows images.
+     */
+    readonly captureCanvas?: Readonly<{
+        recordCanvas?: boolean;
+        canvasFps?: number;
+        canvasQuality?: number;
+    }>;
+    /** `true` masks every input value. `false` cannot unmask what the site's profile masks. */
+    readonly maskAllInputs?: boolean;
+    /** rrweb input kinds set to `true` are masked in addition to the site's rule; passwords always are. */
+    readonly maskInputOptions?: Readonly<Partial<Record<string, boolean>>>;
+    /** Text under matching elements is masked, in addition to the site's rules. */
+    readonly maskTextSelector?: string | null;
+    /**
+     * A class name whose elements' text is masked; `ph-mask` and `elu-mask` always are. A RegExp
+     * is read only in the earlier bundle's exact-class shape, `/^(a|b)$/`, as `.a, .b`.
+     */
+    readonly maskTextClass?: string | RegExp;
+    /** Matching elements are recorded as placeholders, in addition to the site's rules. */
+    readonly blockSelector?: string | null;
+    /**
+     * A class name whose elements are blocked; `ph-no-capture` and `elu-no-capture` always are. A
+     * RegExp is read as for `maskTextClass`, so the earlier bundle's own default,
+     * `/^(ph-no-capture|elu-no-capture)$/`, is honoured.
+     */
+    readonly blockClass?: string | RegExp;
+    /**
+     * A class name whose input changes are not recorded; `ph-ignore-input` and `elu-ignore-input`
+     * always are. A RegExp is read as for `maskTextClass`.
+     */
+    readonly ignoreClass?: string | RegExp;
+    /** Inputs matching it have their changes left out of the recording. */
+    readonly ignoreSelector?: string | null;
+    /** The earlier bundle's other members (`collectFonts`, `inlineStylesheet`, ...) are accepted and ignored. */
+    readonly [member: string]: unknown;
+}
+
+/**
+ * The page's own scrubbing hooks, as the 1.409.5 bundle ran them on every event: `capture`,
+ * `captureException` and each automatic collector alike. They run once per event, in the
+ * bundle's order, right before the event is queued:
+ *
+ * 1. `property_denylist` (and its `property_blacklist` alias) deletes those keys from the
+ *    event properties;
+ * 2. `sanitize_properties(properties, eventName)` replaces the event properties;
+ * 3. `before_send`, a function or an array called in order, receives the event and returns it
+ *    (edited in place or replaced) or `null` to drop it.
+ *
+ * The bundle let a hook's exception escape from `capture`, so the event was never sent. The
+ * native client keeps that outcome without the exception: a hook that throws, or returns
+ * something that is not an event, drops the event with one console error, and the caller's
+ * page never sees the error. A scrubber that fails must not leak what it was written to remove.
+ */
+/**
+ * The event as `before_send` sees it: the bundle's `CaptureResult` without `uuid`, because the
+ * durable stream assigns event ids after the hooks. `$set` and `$set_once` are present when the
+ * capture call passed them; `timestamp` is the caller's, or the time the hook runs.
+ */
+interface EluCaptureResult {
+    event: string;
+    properties: Record<string, unknown>;
+    $set?: Record<string, unknown>;
+    $set_once?: Record<string, unknown>;
+    timestamp: Date;
+}
+/** Returns the event to send, edited in place or replaced, or `null` to drop it. */
+type EluBeforeSendFn = (result: EluCaptureResult) => EluCaptureResult | null | undefined;
+/** @deprecated The bundle deprecated it in favour of `before_send`; it still runs before `before_send`. */
+type EluSanitizePropertiesFn = (properties: Record<string, unknown>, eventName: string) => Record<string, unknown>;
+
 type V1FacadeProperties = Readonly<Record<string, unknown>>;
 interface V1FacadeCaptureOptions {
     readonly $set?: V1FacadeProperties;
@@ -116,7 +260,22 @@ interface EluInitializationOptions {
     readonly assets_host?: string;
     readonly legacy_storage?: LegacyStorageOptions;
     readonly capture_pageview?: EluPageviewMode;
-    readonly autocapture?: boolean;
+    /** `true` or omitted: on; `false`: off; an object: on, narrowed by the 1.409.5 `AutocaptureConfig` lists. */
+    readonly autocapture?: boolean | EluAutocaptureConfigInput;
+    /**
+     * `$copy_autocapture` with the selected text when a visitor copies or cuts, as the 1.409.5
+     * bundle sent it for `autocapture.capture_copied_text`; the ELU Cloud loader passes it here.
+     * `true` turns it on for this page and `false` keeps it off, whatever ELU's configuration
+     * grants; a page that says nothing leaves it to the configuration's `captureCopiedText`. Always
+     * off under `mask_all_text`, and every copy is judged under the configuration's masking.
+     * `autocapture.capture_copied_text`, when it is a boolean, decides first.
+     */
+    readonly capture_copied_text?: boolean;
+    /**
+     * Automatic unhandled errors and rejections. `true` turns them on for this page and `false`
+     * off; omitted, the ELU project's `captureExceptions` grant decides, as the 1.409.5 bundle read
+     * it. The project's suppression rules apply whenever it grants exceptions.
+     */
     readonly capture_exceptions?: boolean;
     /**
      * Report each fetch/XHR as `$network_request` (method, status, timing and a
@@ -124,7 +283,58 @@ interface EluInitializationOptions {
      */
     readonly capture_network_requests?: boolean;
     readonly capture_performance?: EluPerformanceCaptureOptions;
+    /**
+     * Click, rage-click, dead-click and mouse-move positions as `$$heatmap` events. `true` or
+     * `{ flush_interval_milliseconds }` turns them on for this page and `false` off; omitted, the
+     * project's heatmap setting in ELU decides.
+     */
+    readonly capture_heatmaps?: boolean | Readonly<{
+        flush_interval_milliseconds?: number;
+    }>;
+    /** The older spelling of `capture_heatmaps: true | false`, read only when that is omitted. */
+    readonly enable_heatmaps?: boolean;
+    /**
+     * The page's console calls in session replay. `true` records them on this page and
+     * `false` never does; omitted, the ELU project's setting decides. Replay itself
+     * still comes from ELU.
+     */
+    readonly enable_recording_console_log?: boolean;
+    /**
+     * `true` keeps session replay off on this page even when ELU's configuration grants it. There
+     * is no `startSessionRecording()` on this client, so it stays off until a page initializes
+     * without it. Events are unaffected.
+     */
+    readonly disable_session_recording?: boolean;
+    /**
+     * The earlier script's `session_recording` options. `full_snapshot_interval_millis` sets the
+     * activity between full snapshots of the page; `recordHeaders` and `recordBody` decide replay
+     * network capture for the page (`true` records without the project's grant, `false` never does),
+     * as does `captureCanvas` (`{ recordCanvas, canvasFps, canvasQuality }`) for canvas pixels,
+     * within the site's masking profile. Page-level masking is applied on top of the site's masking profile and
+     * is only ever stricter than it: `maskAllInputs: true`, `maskInputOptions`, `maskTextSelector`,
+     * `maskTextClass`, `blockSelector`, `blockClass`, `ignoreClass` and `ignoreSelector`. Other
+     * members are ignored; a masking member the recorder cannot honour keeps replay off on this page.
+     */
+    readonly session_recording?: EluSessionRecordingOptions;
+    /** `true` masks every text node in replay and keeps element text out of interaction events. */
+    readonly mask_all_text?: boolean;
+    /** `true` keeps element attributes out of interaction events. */
+    readonly mask_all_element_attributes?: boolean;
     readonly loaded?: (client: EluClient) => unknown;
+    /**
+     * Runs on every event before it is queued — `capture`, `captureException` and the automatic
+     * events alike — after `property_denylist` and `sanitize_properties`. A function, or an
+     * array of functions called in order, receives the event and returns it (edited in place or
+     * replaced) or `null` to drop it. A hook that throws drops the event and never reaches the
+     * page. Replay data does not pass through it.
+     */
+    readonly before_send?: EluBeforeSendFn | readonly EluBeforeSendFn[] | null;
+    /** @deprecated Use `before_send`. Still runs before it: `(properties, eventName)` returns the properties to send. */
+    readonly sanitize_properties?: EluSanitizePropertiesFn | null;
+    /** Property names removed from every event before `sanitize_properties` and `before_send`. */
+    readonly property_denylist?: readonly string[];
+    /** @deprecated Use `property_denylist`; both lists apply when given. */
+    readonly property_blacklist?: readonly string[];
 }
 
 /**