@elu-labs/analytics-browser 1.410.3 → 1.411.0

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,11 +70,96 @@ interface V1JsonObject {
 interface PerformanceCaptureConfig {
     readonly memory?: boolean;
     readonly long_tasks?: boolean;
+    /**
+     * Core Web Vitals (LCP, FCP, CLS, INP) reported as `$web_vitals`, which the ELU project's
+     * setting grants. `false` turns them off for this page; `true` does not turn them on.
+     */
+    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;
+    /** `false` keeps request and response headers out of replay network capture. */
+    readonly recordHeaders?: boolean;
+    /** `false` keeps request and response bodies out of replay network capture. */
+    readonly recordBody?: boolean;
+    /** `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 (`captureCanvas`, `collectFonts`, ...) 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;
@@ -114,7 +248,18 @@ 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.
+     * Off unless `true`. `autocapture.capture_copied_text`, when it is a boolean, decides first.
+     */
+    readonly capture_copied_text?: boolean;
+    /**
+     * Automatic unhandled errors and rejections, which the ELU project grants. `false` turns them
+     * off for this page; `true` does not turn them on.
+     */
     readonly capture_exceptions?: boolean;
     /**
      * Report each fetch/XHR as `$network_request` (method, status, timing and a
@@ -122,7 +267,56 @@ interface EluInitializationOptions {
      */
     readonly capture_network_requests?: boolean;
     readonly capture_performance?: EluPerformanceCaptureOptions;
+    /**
+     * Click, rage-click, dead-click and mouse-move positions as `$$heatmap` events, which the
+     * project's heatmap setting in ELU grants. `false` turns them off for this page and
+     * `{ flush_interval_milliseconds }` sets their interval; `true` does not turn them on.
+     */
+    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, which the ELU project's setting
+     * grants. `false` never records them; `true` does not record them when the
+     * project does not ask for it. 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, and `recordHeaders` or `recordBody: false` narrow
+     * replay network capture. 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[];
 }
 
 /**