@groundcover/browser 1.0.9 → 2.0.0-rc.1

package/dist/index.d.ts

@@ -1,19 +1,9 @@
 /**
- * The event kinds the browser SDK ships today. This is the DEFAULT vocabulary,
- * not the only permitted one — see `BaseEvent`.
+ * `TType` lets a platform name its own event kinds without editing core, and every core class
+ * flows it through. Defaults to `string`, because the set of NAMES is open — a platform that
+ * wants a closed union passes its own. Shared shapes stay shared; only the vocabulary is open.
  */
-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 BaseEvent<TType extends string = string> = {
     type: TType;
     timestamp?: number;
     end_timestamp?: number;
@@ -33,30 +23,6 @@ type UserIdentifiers = {
     organization: string;
     properties: Record<string, unknown>;
 };
-type DomEventAttributes = {
-    dom_event_type: string;
-    dom_event_coordinates: {
-        clientX: number;
-        clientY: number;
-    };
-    dom_event_target: {
-        tagName: string;
-        id: string;
-        className: string;
-        text: string;
-        role: string;
-        accessibleName: string;
-        ariaLabel: string;
-        title: string;
-        alt: string;
-        placeholder: string;
-        name: string;
-        inputType: string;
-        href: string;
-    };
-    dom_event_selector: string;
-    dom_event_key_code: string;
-};
 type NetworkEventAttributes = {
     type: "HTTP";
     resource_name: string;
@@ -119,31 +85,6 @@ type LogEventAttributes = {
     message: string;
     level: string;
 } & Record<string, unknown>;
-type PageLoadEventAttributes = {
-    page_url: string;
-    page_resources: {
-        count: number;
-        totalSize: number;
-        totalDuration: number;
-        byType: {
-            [key: string]: {
-                count: number;
-                size: number;
-                duration: number;
-            };
-        };
-    };
-    page_referrer: string;
-    page_load_time: number;
-};
-type NavigationEventAttributes = {
-    page_url: string;
-    from_url?: string;
-    metadata?: Record<string, unknown>;
-    duration_ms: number;
-    start_timestamp: number;
-    end_timestamp: number;
-};
 type UserDefinedEventAttributes = {
     custom_event_name: string;
     custom_event_attributes?: Record<string, unknown>;
@@ -154,44 +95,9 @@ type PerformanceEventAttributes = {
     performance_metric_id: string;
     performance_metric_navigation_type: string;
 };
-type ReplayEventAttributes = {
-    /**
-     * Groundcover session replay payload.
-     *
-     * NOTE: This key is intentionally prefixed to avoid collisions with customer attributes.
-     */
-    _gc_replay_data: {
-        events: string[];
-    };
-    /**
-     * Indicates this batch starts with a full DOM snapshot.
-     * Full snapshots are taken at regular intervals to allow seeking directly to any point.
-     * Queryable for filtering/indexing purposes.
-     */
-    replay_is_full_snapshot?: boolean;
-    /**
-     * Timestamp when the full snapshot was taken (if replay_is_full_snapshot is true).
-     */
-    replay_full_snapshot_timestamp?: number;
-};
 
-type Event$1<T extends string, A> = Omit<BaseEvent<T>, "attributes"> & {
-    type: T;
-    attributes: A;
-};
-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. */
+/** The event surface a redactor field belongs to. */
 type RedactKind = "request-body" | "response-body" | "query" | "header" | "log" | "error";
 interface RedactField {
     /** Immediate key of the value; `""` for whole-string fields (log/error message). */
@@ -233,23 +139,19 @@ interface PrivacyOptions$1 {
     /** Extra case-insensitive key substrings treated as sensitive, merged with the built-in patterns. */
     sensitiveKeys?: string[];
     /**
-     * Per-field custom redaction hook for non-replay events. Called on each leaf
+     * Per-field custom redaction hook for captured events. Called on each leaf
      * value during the redaction walk with the original typed value; see
      * {@link Redactor}. For arbitrary whole-event changes use `enrichEvent`.
      */
     redact?: Redactor;
-    /**
-     * 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 {
-    /** Request URLs (prefix match) that receive injected tracing headers. */
+    /**
+     * Request URLs that receive injected tracing headers: whole-URL matches where
+     * only `*` is a wildcard. Which strings a pattern is matched against is the
+     * platform's (the browser adds a same-origin request's path).
+     */
     propagationUrls?: string[];
     /** Inbound header names to read/propagate onto traced requests. */
     propagationHeaders?: string[];
@@ -269,25 +171,23 @@ interface TransportOptions {
     batchSize?: number;
     /** Max ms a batch waits before flushing regardless of size (default 10000). */
     batchTimeout?: number;
-    /** Gzip-compress outgoing batches; offloaded to the Web Worker when available (default true). */
+    /** Gzip-compress outgoing batches; offloaded to the platform's async encoder when it has one (default true). */
     compression?: boolean;
 }
-interface SDKOptions$1<TEvent extends BaseEvent<string> = EventTypes$1[keyof EventTypes$1]> {
+interface SDKOptions$1<TEvent extends BaseEvent<string> = BaseEvent<string>> {
     /**
      * 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`).
+     * platform package narrows this to its literal union.
      */
     enabledEvents: string[];
-    eventSampleRate: number;
     sessionSampleRate: number;
     debug: boolean;
     excludedUrls?: Array<string | RegExp>;
-    beforeSend?: (event: TEvent) => boolean;
-    enrichEvent?: (event: TEvent) => TEvent;
+    beforeSend?(event: TEvent): boolean;
+    enrichEvent?(event: TEvent): TEvent;
     /**
-     * Unified privacy / data-masking config driving replay + non-replay masking.
+     * Unified privacy / data-masking config for every captured surface.
      * ON by default (`level: 'mask-sensitive'`); see {@link PrivacyOptions}.
      */
     privacy?: PrivacyOptions$1;
@@ -296,51 +196,16 @@ interface SDKOptions$1<TEvent extends BaseEvent<string> = EventTypes$1[keyof Eve
     /** Batching & delivery of outgoing events; see {@link TransportOptions}. */
     transport?: TransportOptions;
     /**
-     * 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?: unknown;
-    /**
-     * Target maximum wall-clock duration of a session, in milliseconds.
-     *
-     * Enforced LAZILY, on activity — not by a background timer. Once the cap has
-     * elapsed, the next user/business event (click, navigation, log, custom,
-     * network, exception, …) flushes buffered events under the current session
-     * id, then mints a fresh session id and restarts replay recording if it was
-     * active.
-     *
-     * Because it is activity-gated, this is NOT a hard upper bound: a session
-     * only rotates when the next qualifying event arrives. An idle or
-     * backgrounded tab that produces no such events — including one that is only
-     * emitting session-replay heartbeats, which never trigger rotation on their
-     * own — keeps the same session id past the cap until activity resumes. This
-     * is deliberate: it avoids minting "phantom" sessions for dormant tabs. (An
-     * idle tab with replay on is ultimately bounded by the 30-minute user-idle
-     * pause — recording stops when no user presence is detected — not by this
-     * cap.)
+     * Target maximum wall-clock duration of a session, in ms. Enforced LAZILY on activity, so NOT
+     * a hard bound — an idle session keeps its id past the cap, which deliberately avoids minting
+     * phantom sessions. Also bounded by a 30-minute inactivity gap, counting raw input as
+     * presence so passive reading does not end a session.
      *
-     * Sessions are also bounded by a 30-minute inactivity gap, enforced the same
-     * lazy way: when a user-interaction event (click, navigation, pageload,
-     * custom — not background network/log/performance traffic) arrives after 30+
-     * minutes without one, the session rotates first and replay recording
-     * restarts for the returning user. Raw user input (scroll, pointer, key,
-     * touch) also counts as presence even when it produces no SDK event, so
-     * passive engagement — reading, watching — doesn't end the session. The
-     * same gap check runs at init, so a reload after a long break also starts a
-     * fresh session.
-     *
-     * The flush is best-effort and the rotation always proceeds — it does not
-     * wait for or depend on successful delivery, so if that network request
-     * fails the batch may be lost while the new session id still takes effect.
-     *
-     * Defaults to 4 hours when omitted; must be between 1 minute and 8 hours.
-     * Values outside that range or otherwise invalid fall back to the 4-hour
-     * default with a `console.warn`.
+     * Defaults to 4 hours; must be 1 minute to 8 hours, else falls back with a warning.
      */
     sessionMaxDuration?: number;
 }
-interface SDKConfigInput$1<TEvent extends BaseEvent<string> = EventTypes$1[keyof EventTypes$1]> {
+interface SDKConfigInput$1<TEvent extends BaseEvent<string> = BaseEvent<string>> {
     apiKey: string;
     cluster: string;
     environment: string;
@@ -353,6 +218,76 @@ interface SDKConfigInput$1<TEvent extends BaseEvent<string> = EventTypes$1[keyof
     sessionId?: string;
 }
 
+type DomEventAttributes = {
+    dom_event_type: string;
+    dom_event_coordinates: {
+        clientX: number;
+        clientY: number;
+    };
+    dom_event_target: {
+        tagName: string;
+        id: string;
+        className: string;
+        text: string;
+        role: string;
+        accessibleName: string;
+        ariaLabel: string;
+        title: string;
+        alt: string;
+        placeholder: string;
+        name: string;
+        inputType: string;
+        href: string;
+    };
+    dom_event_selector: string;
+    dom_event_key_code: string;
+};
+type PageLoadEventAttributes = {
+    page_url: string;
+    page_resources: {
+        count: number;
+        totalSize: number;
+        totalDuration: number;
+        byType: {
+            [key: string]: {
+                count: number;
+                size: number;
+                duration: number;
+            };
+        };
+    };
+    page_referrer: string;
+    page_load_time: number;
+};
+type NavigationEventAttributes = {
+    page_url: string;
+    from_url?: string;
+    metadata?: Record<string, unknown>;
+    duration_ms: number;
+    start_timestamp: number;
+    end_timestamp: number;
+};
+type ReplayEventAttributes = {
+    /**
+     * Groundcover session replay payload.
+     *
+     * NOTE: This key is intentionally prefixed to avoid collisions with customer attributes.
+     */
+    _gc_replay_data: {
+        events: string[];
+    };
+    /**
+     * Indicates this batch starts with a full DOM snapshot.
+     * Full snapshots are taken at regular intervals to allow seeking directly to any point.
+     * Queryable for filtering/indexing purposes.
+     */
+    replay_is_full_snapshot?: boolean;
+    /**
+     * Timestamp when the full snapshot was taken (if replay_is_full_snapshot is true).
+     */
+    replay_full_snapshot_timestamp?: number;
+};
+
 /**
  * The view an event was captured on. Browser-owned: core has no notion of a
  * "current view" — it merges whatever the platform's `enrichAttributes`
@@ -412,13 +347,13 @@ interface ReplayMaskingOptions {
     /** rrweb `maskInputFn` pass-through. */
     maskInputFn?: (text: string, el: HTMLElement) => string;
 }
-interface PrivacyOptions extends Omit<PrivacyOptions$1, "replay"> {
+interface PrivacyOptions extends PrivacyOptions$1 {
     /** 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"> {
+interface SDKOptions extends Omit<SDKOptions$1, "privacy" | "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.
@@ -442,7 +377,7 @@ interface SDKOptions extends Omit<SDKOptions$1, "privacy" | "replay" | "enabledE
 interface SDKConfigInput extends Omit<SDKConfigInput$1, "options"> {
     options?: Partial<SDKOptions>;
 }
-type SDKConfigUpdate = Partial<Omit<SDKConfigInput, "sessionId" | "user">> & {
+type SDKConfigUpdate = Partial<Omit<SDKConfigInput, "appId" | "sessionId" | "user">> & {
     user?: SDKConfigInput["user"] | null;
 };
 
@@ -470,7 +405,6 @@ declare class SessionManager {
     setSessionId(newSessionId?: string): Promise<void>;
     startReplayRecording(): void;
     stopReplayRecording(): void;
-    handoffForReinit(): void;
     destroy(): void;
 }
 
@@ -491,11 +425,11 @@ declare global {
         groundcover?: typeof groundcover;
     }
 }
-declare function init(params?: {
+declare function init(params: {
     cluster?: string;
     environment?: string;
     namespace?: string;
-    appId?: string;
+    appId: string;
     releaseId?: string;
     user?: Partial<UserIdentifiers>;
     dsn?: string;