@groundcover/browser 1.0.7 → 1.0.8-rc.0

package/CHANGELOG.md

@@ -4,6 +4,50 @@ All notable changes to `@groundcover/browser` are documented here. This project
 [Semantic Versioning](https://semver.org/spec/v2.0.0.html) and the
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) format.
 
+## [1.0.8-rc.0]
+
+Release candidate. Published under the `rc` dist-tag — `npm install @groundcover/browser@rc`.
+
+The public API is unchanged: the generated type declarations are byte-identical to 1.0.7, the
+published bundle contains the same 10 files, and the `/json/rum` wire format is unchanged (pinned by
+a golden characterization suite). The two behaviour changes below are the reason this ships as an
+RC rather than a patch.
+
+### Changed
+
+- **`sessionSampleRate: 0` now samples nothing.** It was previously treated as "unset" by a falsy
+  check, so configuring `0` sampled *every* session — the exact opposite of the intent. If you set
+  `sessionSampleRate: 0` today and rely on the current (inverted) behaviour, sessions will stop
+  being collected when you upgrade.
+- **The session sampling verdict is now re-rolled per session.** It is documented as "decided once
+  per session", but nothing ever removed the stored decision, so in practice it was decided once per
+  browser-storage lifetime and every session after the first rotation inherited the original
+  verdict. The decision is now cleared when a session rotates (inactivity gap, max-duration cap, or
+  a new session id supplied by the host). Re-supplying the *same* session id is still a continuation
+  and keeps its verdict.
+
+### Fixed
+
+- **Session rotation could stop permanently if a host hook threw.** The in-progress flag was set
+  before the host's rotation-context hook ran but only cleared in a `finally` that the hook sat
+  outside, so a throw left it stuck — silently disabling all further session rotation for the life
+  of the page. Not reachable through the browser SDK's own hook, but the surrounding error handling
+  swallowed the throw without resetting the flag, so it would have failed invisibly.
+- **Configuration option groups were shared between SDK instances.** `privacy`, `tracing`,
+  `transport` and `replay` groups the caller didn't supply were held by reference from the shared
+  defaults, so multiple SDK instances in one page aliased the same objects (and the module-level
+  defaults themselves).
+- **A failed batch send could raise an unhandled promise rejection** instead of logging, when
+  `options` was absent on the resolved config.
+
+### Internal
+
+- The platform-agnostic pipeline (config, session policy, event enrichment, batching, redaction,
+  transport) now lives in a private `@groundcover/rum-core` package, inlined into this bundle at
+  build time. It compiles with no DOM lib so platform coupling fails the build, and the network
+  send, storage, device metadata and view derivation are injected by this package. Groundwork for
+  the React Native SDK; no effect on the published browser artifact.
+
 ## [1.0.5]
 
 ### Added

package/dist/index.d.mts

@@ -1,5 +1,20 @@
-type BaseEvent = {
-    type: "dom.event" | "exception" | "network" | "log" | "pageload" | "navigation" | "custom" | "performance" | "replay";
+/**
+ * The event kinds the browser SDK ships today. This is the DEFAULT vocabulary,
+ * not the only permitted one — see `BaseEvent`.
+ */
+type KnownEventType = "dom.event" | "exception" | "network" | "log" | "pageload" | "navigation" | "custom" | "performance" | "replay";
+/**
+ * `TType` is what lets a platform package name its own event kinds without
+ * editing core: React Native can pass `KnownEventType | "tap" | "screen_view"`
+ * and every core class below flows it through. It defaults to
+ * `KnownEventType`, so nothing that only deals in the shipped browser kinds
+ * has to spell it out.
+ *
+ * Shared shapes are still shared — the point is that the set of names is open,
+ * not that each platform reinvents the envelope.
+ */
+type BaseEvent<TType extends string = KnownEventType> = {
+    type: TType;
     timestamp?: number;
     end_timestamp?: number;
     start_timestamp?: number;
@@ -10,11 +25,6 @@ type BaseEvent = {
     traceId: string | undefined;
     attributes?: Record<string, unknown>;
 };
-type LocationAttributes = {
-    path: string;
-    url: string;
-    title: string;
-};
 type UserIdentifiers = {
     id: string;
     email: string;
@@ -165,22 +175,20 @@ type ReplayEventAttributes = {
     replay_full_snapshot_timestamp?: number;
 };
 
-type Event<T extends BaseEvent["type"], A> = Omit<BaseEvent, "attributes"> & {
+type Event$1<T extends string, A> = Omit<BaseEvent<T>, "attributes"> & {
     type: T;
-    attributes: A & {
-        location?: LocationAttributes;
-    };
+    attributes: A;
 };
-type EventTypes = {
-    "dom.event": Event<"dom.event", DomEventAttributes>;
-    exception: Event<"exception", ErrorEventAttributes>;
-    network: Event<"network", NetworkEventAttributes>;
-    log: Event<"log", LogEventAttributes>;
-    pageload: Event<"pageload", PageLoadEventAttributes>;
-    navigation: Event<"navigation", NavigationEventAttributes>;
-    custom: Event<"custom", UserDefinedEventAttributes>;
-    performance: Event<"performance", PerformanceEventAttributes>;
-    replay: Event<"replay", ReplayEventAttributes>;
+type EventTypes$1 = {
+    "dom.event": Event$1<"dom.event", DomEventAttributes>;
+    exception: Event$1<"exception", ErrorEventAttributes>;
+    network: Event$1<"network", NetworkEventAttributes>;
+    log: Event$1<"log", LogEventAttributes>;
+    pageload: Event$1<"pageload", PageLoadEventAttributes>;
+    navigation: Event$1<"navigation", NavigationEventAttributes>;
+    custom: Event$1<"custom", UserDefinedEventAttributes>;
+    performance: Event$1<"performance", PerformanceEventAttributes>;
+    replay: Event$1<"replay", ReplayEventAttributes>;
 };
 type PrivacyLevel = "mask-sensitive" | "mask-all" | "allow";
 /** The non-replay event surface a redactor field belongs to. */
@@ -205,18 +213,15 @@ interface RedactField {
  * only cares about one field can't accidentally disable masking elsewhere.
  */
 type Redactor = (field: RedactField) => string | number | boolean | null | undefined;
-interface PrivacyOptions {
+interface PrivacyOptions$1 {
     /**
-     * Master switch for replay + non-replay masking. `'mask-sensitive'`
-     * (default) masks only SENSITIVE inputs/keystrokes (password type,
-     * `data-private`, `maskSelectors`, or a sensitive-key attribute match) and
-     * redacts network/log/error payloads, while capturing non-secret inputs and
-     * keeping static text; `'mask-all'` also masks all inputs and all text;
-     * `'allow'` opts out.
+     * Master switch for data masking. `'mask-sensitive'` (default) masks only
+     * SENSITIVE data (sensitive-key matches, platform-flagged UI elements) and
+     * redacts network/log/error payloads while capturing the rest;
+     * `'mask-all'` also masks all captured input/text; `'allow'` opts out.
+     * Platform packages define what "sensitive UI element" means on their host.
      */
     level?: PrivacyLevel;
-    /** CSS selectors whose text/inputs are always masked (replay + DOM), regardless of `level` except `'allow'`. */
-    maskSelectors?: string[];
     /** Redact network request/response bodies. Default on unless `level` is `'allow'`. */
     maskNetworkBodies?: boolean;
     /** Redact network URL query params. Default on unless `level` is `'allow'`. */
@@ -233,13 +238,14 @@ interface PrivacyOptions {
      * {@link Redactor}. For arbitrary whole-event changes use `enrichEvent`.
      */
     redact?: Redactor;
-    /** Session-recording (rrweb replay) masking — the only place replay can be masked. */
-    replay?: {
-        /** rrweb `maskTextFn` pass-through. */
-        maskTextFn?: (text: string, el: HTMLElement | null) => string;
-        /** rrweb `maskInputFn` pass-through. */
-        maskInputFn?: (text: string, el: HTMLElement) => string;
-    };
+    /**
+     * Session-recording masking — replay is a platform feature (rrweb on the
+     * browser), so its masking surface is typed by the platform package: the
+     * browser SDK narrows this to `{ maskTextFn?, maskInputFn? }` over
+     * HTMLElement (see the browser package's `config/types.ts`). Core never
+     * reads it — it is resolved platform-side at record() time.
+     */
+    replay?: unknown;
 }
 /** Distributed-tracing header propagation for outgoing network requests. */
 interface TracingOptions {
@@ -266,44 +272,35 @@ interface TransportOptions {
     /** Gzip-compress outgoing batches; offloaded to the Web Worker when available (default true). */
     compression?: boolean;
 }
-/**
- * Session-replay (rrweb) recording controls. This is NOT a privacy surface —
- * to mask sensitive content use `privacy`.
- */
-interface ReplayOptions {
+interface SDKOptions$1 {
     /**
-     * CSS selectors whose matching elements (and their subtrees) are excluded
-     * from session recording. Matching elements appear in the replay as empty
-     * placeholders of their original size. Useful for skipping noisy DOM injected
-     * by browser extensions (e.g. Grammarly).
-     *
-     * NOTE: this is a noise-reduction control, NOT a privacy control. To mask
-     * sensitive content use `privacy` instead.
+     * Which signal listeners to enable, by name. Empty array = all. The NAMES
+     * are platform-defined (each platform ships its own listener set) — the
+     * platform package narrows this to its literal union (see the browser
+     * package's `config/types.ts`).
      */
-    blockedSelectors?: string[];
-}
-interface SDKOptions {
-    enabledEvents: Array<"dom" | "network" | "exceptions" | "logs" | "pageload" | "navigation" | "performance" | "replay">;
+    enabledEvents: string[];
     eventSampleRate: number;
     sessionSampleRate: number;
     debug: boolean;
     excludedUrls?: Array<string | RegExp>;
-    beforeSend?: (event: EventTypes[keyof EventTypes]) => boolean;
-    enrichEvent?: (event: EventTypes[keyof EventTypes]) => EventTypes[keyof EventTypes];
+    beforeSend?: (event: EventTypes$1[keyof EventTypes$1]) => boolean;
+    enrichEvent?: (event: EventTypes$1[keyof EventTypes$1]) => EventTypes$1[keyof EventTypes$1];
     /**
      * Unified privacy / data-masking config driving replay + non-replay masking.
      * ON by default (`level: 'mask-sensitive'`); see {@link PrivacyOptions}.
      */
-    privacy?: PrivacyOptions;
+    privacy?: PrivacyOptions$1;
     /** Distributed-tracing header propagation; see {@link TracingOptions}. */
     tracing?: TracingOptions;
     /** Batching & delivery of outgoing events; see {@link TransportOptions}. */
     transport?: TransportOptions;
     /**
-     * Session-replay recording controls (noise reduction). For replay MASKING use
-     * `privacy` instead. See {@link ReplayOptions}.
+     * Session-recording controls — a platform feature slot core never reads.
+     * The platform package types it (the browser SDK narrows this to its
+     * rrweb `ReplayOptions`; platforms without recording ignore it).
      */
-    replay?: ReplayOptions;
+    replay?: unknown;
     /**
      * Target maximum wall-clock duration of a session, in milliseconds.
      *
@@ -343,7 +340,7 @@ interface SDKOptions {
      */
     sessionMaxDuration?: number;
 }
-interface SDKConfigInput {
+interface SDKConfigInput$1 {
     apiKey: string;
     cluster: string;
     environment: string;
@@ -352,7 +349,7 @@ interface SDKConfigInput {
     namespace?: string;
     releaseId?: string;
     user?: Partial<UserIdentifiers>;
-    options?: Partial<SDKOptions>;
+    options?: Partial<SDKOptions$1>;
     sessionId?: string;
 }
 
@@ -365,9 +362,9 @@ declare class SDKConfig {
     releaseId?: string;
     apiKey: string;
     user: Partial<UserIdentifiers> | null;
-    options: Partial<SDKOptions>;
-    providedOptions?: Partial<SDKOptions>;
-    constructor(input?: SDKConfigInput);
+    options: Partial<SDKOptions$1>;
+    providedOptions?: Partial<SDKOptions$1>;
+    constructor(input?: SDKConfigInput$1);
     private static readonly REMOVED_OPTION_KEYS;
     private static stripRemovedOptions;
     private static warnRemovedOptions;
@@ -376,13 +373,106 @@ declare class SDKConfig {
     updateConfig(updates: Partial<SDKConfig>): void;
 }
 
+/**
+ * The view an event was captured on. Browser-owned: core has no notion of a
+ * "current view" — it merges whatever the platform's `enrichAttributes`
+ * contributor returns. `makeWebViewProvider` derives these (hash-route
+ * detection, query-param redaction) and the SessionManager contributes them
+ * under the `location` key.
+ */
+type LocationAttributes = {
+    path: string;
+    url: string;
+    title: string;
+};
+/**
+ * The browser's event shape. Identical to core's `Event` plus the `location`
+ * this platform stamps during enrichment — which is why `beforeSend` /
+ * `enrichEvent` below are re-declared over THIS map rather than core's.
+ */
+type Event<T extends string, A> = Omit<BaseEvent<T>, "attributes"> & {
+    type: T;
+    attributes: A & {
+        location?: LocationAttributes;
+    };
+};
+type EventTypes = {
+    "dom.event": Event<"dom.event", DomEventAttributes>;
+    exception: Event<"exception", ErrorEventAttributes>;
+    network: Event<"network", NetworkEventAttributes>;
+    log: Event<"log", LogEventAttributes>;
+    pageload: Event<"pageload", PageLoadEventAttributes>;
+    navigation: Event<"navigation", NavigationEventAttributes>;
+    custom: Event<"custom", UserDefinedEventAttributes>;
+    performance: Event<"performance", PerformanceEventAttributes>;
+    replay: Event<"replay", ReplayEventAttributes>;
+};
+/** The browser SDK's listener names for `enabledEvents`. */
+type BrowserEventName = "dom" | "network" | "exceptions" | "logs" | "pageload" | "navigation" | "performance" | "replay";
+/**
+ * Session-replay (rrweb) recording controls. This is NOT a privacy surface —
+ * to mask sensitive content use `privacy`.
+ */
+interface ReplayOptions {
+    /**
+     * CSS selectors whose matching elements (and their subtrees) are excluded
+     * from session recording. Matching elements appear in the replay as empty
+     * placeholders of their original size. Useful for skipping noisy DOM injected
+     * by browser extensions (e.g. Grammarly).
+     *
+     * NOTE: this is a noise-reduction control, NOT a privacy control. To mask
+     * sensitive content use `privacy` instead.
+     */
+    blockedSelectors?: string[];
+}
+/** Session-recording (rrweb replay) masking — the only place replay can be masked. */
+interface ReplayMaskingOptions {
+    /** rrweb `maskTextFn` pass-through. */
+    maskTextFn?: (text: string, el: HTMLElement | null) => string;
+    /** rrweb `maskInputFn` pass-through. */
+    maskInputFn?: (text: string, el: HTMLElement) => string;
+}
+interface PrivacyOptions extends Omit<PrivacyOptions$1, "replay"> {
+    /** CSS selectors whose text/inputs are always masked (replay + DOM), regardless of `level` except `'allow'`. */
+    maskSelectors?: string[];
+    /** Session-recording (rrweb replay) masking — the only place replay can be masked. */
+    replay?: ReplayMaskingOptions;
+}
+interface SDKOptions extends Omit<SDKOptions$1, "privacy" | "replay" | "enabledEvents" | "beforeSend" | "enrichEvent"> {
+    /**
+     * Inspect each event before it is queued; return false to drop it. Typed
+     * over the BROWSER event map, so `attributes.location` is visible here.
+     */
+    beforeSend?: (event: EventTypes[keyof EventTypes]) => boolean;
+    /** Modify each event before it is queued. Typed over the browser event map. */
+    enrichEvent?: (event: EventTypes[keyof EventTypes]) => EventTypes[keyof EventTypes];
+    /** Which browser listeners to enable. Empty array = all. */
+    enabledEvents: BrowserEventName[];
+    /**
+     * Unified privacy / data-masking config driving replay + non-replay masking.
+     * ON by default (`level: 'mask-sensitive'`); see {@link PrivacyOptions}.
+     */
+    privacy?: PrivacyOptions;
+    /**
+     * Session-replay recording controls (noise reduction). For replay MASKING use
+     * `privacy` instead. See {@link ReplayOptions}.
+     */
+    replay?: ReplayOptions;
+}
+interface SDKConfigInput extends Omit<SDKConfigInput$1, "options"> {
+    options?: Partial<SDKOptions>;
+}
+
 declare class SessionManager {
-    private initialized;
     private logger;
-    private instrumentationManager;
+    private readonly storage;
     private idGenerator;
+    private core;
+    private hideWired;
+    private hideHandler;
     constructor(config: SDKConfigInput);
-    private getSamplingDecision;
+    private wireHideHandler;
+    private unwireHideHandler;
     identifyUser(userIdentifier: Partial<UserIdentifiers>): void;
     updateConfig(params: Partial<SDKConfig>): void;
     sendCustomEvent(event: {