@groundcover/browser 1.0.9 → 2.0.0-rc.0

package/README.md

@@ -32,6 +32,7 @@ for the full product guide.
 - [Session lifecycle](#session-lifecycle)
 - [Performance considerations](#performance-considerations)
 - [API reference](#api-reference)
+- [Migrating from 1.x to 2.0.0](#migrating-from-1x-to-200)
 - [Migrating to 1.0.0](#migrating-to-100)
 
 ---
@@ -80,6 +81,11 @@ groundcover.sendCustomEvent({ event: "plan_upgraded", attributes: { plan: "pro"
 `init()` takes connection/identity fields at the top level and all behavioral knobs under
 `options`, grouped by concern.
 
+The first successful `init()` initializes the SDK. Every later call is silently ignored, even with
+a different `appId` or config. Calls made during initialization are also ignored; if initialization
+fails, a later call can retry. Use [`updateConfig()`](#updating-config-at-runtime) or the other runtime
+APIs for supported changes.
+
 ```ts
 groundcover.init({
   // ── Connection & identity ──
@@ -89,7 +95,7 @@ groundcover.init({
 
   options: {
     debug,
-    sessionSampleRate, eventSampleRate,
+    sessionSampleRate,
     enabledEvents, excludedUrls,
     sessionMaxDuration,
     beforeSend, enrichEvent,
@@ -108,7 +114,7 @@ groundcover.init({
 | `apiKey` | `string` | ✅ | Your groundcover RUM API key. |
 | `dsn` | `string` | ✅ | RUM intake endpoint. A bare host is upgraded to `https://`. |
 | `cluster` | `string` | ✅ | Target groundcover cluster. |
-| `appId` | `string` | ✅ | Application identifier; reported as `service.name`. |
+| `appId` | `string` | ✅ | Required application identifier; cannot be empty or whitespace-only. Reported unchanged as `service.name`. |
 | `environment` | `string` | — | Deployment environment (e.g. `production`, `staging`). |
 | `namespace` | `string` | — | Logical grouping/namespace for the app. |
 | `releaseId` | `string` | — | Release/version identifier (e.g. a semver or commit hash). |
@@ -122,7 +128,6 @@ groundcover.init({
 |---|---|---|---|
 | `debug` | `boolean` | `false` | Verbose SDK console logging. |
 | `sessionSampleRate` | `number` | `1` | Fraction of sessions captured (0–1). |
-| `eventSampleRate` | `number` | `1` | Fraction of events captured (0–1). |
 | `enabledEvents` | `Array<…>` | `[]` | Instrumentations to enable. **Empty = all.** Members: `dom`, `network`, `exceptions`, `logs`, `pageload`, `navigation`, `performance`, `replay`. Note: `replay` still requires an explicit [`startReplayRecording()`](#session-replay) call — it never auto-starts. |
 | `excludedUrls` | `Array<string \| RegExp>` | — | Network requests matching these are not captured. |
 | `sessionMaxDuration` | `number` | `4h` | Target max session length in ms (1 min – 8 h). See [session lifecycle](#session-lifecycle). |
@@ -181,7 +186,9 @@ content use [`privacy`](#privacy--data-masking).
 
 ### Updating config at runtime
 
-`updateConfig` mirrors the `init` shape; nested groups merge one level deep (and `tracing.origin` /
+`updateConfig` accepts these optional fields: `cluster`, `environment`, `namespace`, `releaseId`,
+`dsn`, `apiKey`, `options`, and `user`. `appId` cannot be updated. `sessionId` is not accepted;
+use the separate `setSessionId()` API. Nested groups merge one level deep (and `tracing.origin` /
 `privacy.replay` one level deeper), so a partial update preserves the other keys in the group:
 
 ```ts
@@ -423,14 +430,20 @@ every other guarantee here is stated for that case.
 
 ### Micro-frontend session synchronization
 
-Pass a shared `sessionId` so multiple frontends report under one session:
+Initialize the shared SDK once in the shell with a shared `sessionId` so the micro-frontends report
+under one session. Each micro-frontend uses that same SDK to capture events:
 
 ```ts
+// Shell
 const sharedSessionId = "session-12345";
-groundcover.init({ /* …app… */ apiKey, dsn, cluster, appId: "shell", sessionId: sharedSessionId });
-groundcover.init({ /* …mfe… */ apiKey, dsn, cluster, appId: "micro-frontend", sessionId: sharedSessionId });
+groundcover.init({ apiKey, dsn, cluster, appId: "your-app-id", sessionId: sharedSessionId });
+
+// Micro-frontend using the shared SDK
+groundcover.sendCustomEvent({ event: "checkout_opened", attributes: { cartId: "cart-123" } });
 ```
 
+If you need to explicitly rebind the shared SDK to another session, use `setSessionId()`.
+
 ---
 
 ## Performance considerations
@@ -438,7 +451,8 @@ groundcover.init({ /* …mfe… */ apiKey, dsn, cluster, appId: "micro-frontend"
 - **Batching & compression** — events are buffered (`transport.batchSize` / `transport.batchTimeout`) and
   gzipped (`transport.compression`) to minimize request count and payload size.
 - **Web Worker offload** — replay packing and gzip run off the main thread (see above).
-- **Sampling** — cap volume with `sessionSampleRate` / `eventSampleRate`.
+- **Sampling** — use `sessionSampleRate` to select whole sessions. Events within selected
+  sessions are not randomly sampled; enabled-event settings, filtering, and privacy controls still apply.
 - **Scope what you capture** — drop noisy endpoints with `excludedUrls`, and disable unused
   instrumentations via `enabledEvents`.
 - **Lazy session rotation** — no background timers; rotation work happens only on real activity.
@@ -453,7 +467,7 @@ All methods are available on the default export and on `window.groundcover`.
 
 | Method | Description |
 |---|---|
-| `init(config)` | Initialize the SDK and install instrumentation. |
+| `init(config)` | Initialize the SDK and install instrumentation once; calls after successful initialization are ignored. |
 | `identifyUser(user)` | Attach user identity to subsequent events. |
 | `sendCustomEvent({ event, attributes })` | Emit a custom business event. |
 | `captureException(error, metadata?)` | Capture a handled error with optional context. |
@@ -500,6 +514,68 @@ groundcover.captureException(new Error("Payment failed"), {
 
 ---
 
+## Migrating from 1.x to 2.0.0
+
+`2.0.0` removes event-level sampling and makes browser application identity fixed after the first
+successful initialization. These are breaking changes; review your initialization and runtime
+updates before upgrading:
+
+```bash
+npm install @groundcover/browser@2.0.0-rc.0
+```
+
+| Change | Migration |
+|---|---|
+| `options.eventSampleRate` is removed | Delete it from initialization and runtime updates. Choose `options.sessionSampleRate` explicitly if you need to limit capture volume. |
+| `appId` is required and cannot be blank | Supply a non-empty, non-whitespace string at initialization. Its value is preserved exactly. |
+| Each SDK instance initializes once | Initialize in your application's bootstrap code. Use runtime APIs instead of calling `init()` again. |
+| `appId` cannot be updated | Exclude it from `updateConfig()`, including when spreading an initialization config. Its presence rejects the entire update, even if its value is unchanged or `undefined`. |
+
+### Why event-level sampling was removed
+
+Randomly dropping individual events leaves gaps in user journeys and can distort funnel analysis.
+The SDK now uses `sessionSampleRate` to select sessions without randomly dropping individual events
+within them. Enabled-event settings, filtering, and privacy controls still apply; session replay
+still requires an explicit start.
+
+> **Volume warning:** If you previously set `eventSampleRate` below `1`, upgrading can increase event
+> volume. The removed option has no effect: passing it warns and strips it from stored configuration.
+> `sessionSampleRate` is not a rename or an equivalent numeric replacement: `0.1` selects roughly 10%
+> of sessions, rather than sampling 10% of events within sessions. Rates are never automatically
+> converted. If event sampling was left at its default of `1`, this removal does not increase capture
+> through sampling alone.
+
+For example, if you deliberately choose to capture 10% of sessions:
+
+```ts
+groundcover.init({
+  apiKey, dsn, cluster,
+  appId: "checkout",
+  options: { sessionSampleRate: 0.1 },
+});
+```
+
+### Initialize once; update supported fields explicitly
+
+Missing, non-string, or blank `appId` values produce a warning and leave the SDK uninitialized.
+After correcting the input, call `init()` again. A failed initialization also permits an explicit
+retry; calls during initialization or after success are silently ignored, regardless of `appId`.
+
+Do not spread your initialization config into a runtime update:
+
+```ts
+// Pass only the fields you intend to change, without appId.
+groundcover.updateConfig({ dsn: newDsn, apiKey: newApiKey, cluster: newCluster });
+groundcover.identifyUser({ id: "user-123" });
+await groundcover.setSessionId("shared-session-id");
+```
+
+An update containing `appId` warns and applies **none** of its fields. Use `identifyUser()` for user
+identity and `setSessionId()` for session identity; neither changes the application identity.
+For micro-frontends, initialize the shared SDK once in the shell and reuse it in each frontend.
+
+---
+
 ## Migrating to 1.0.0
 
 `1.0.0` restructures `options` by concern (a clean break from `0.x`) and removes the deprecated

package/dist/index.d.mts

@@ -4,14 +4,9 @@
  */
 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.
+ * `TType` lets a platform name its own event kinds without editing core, and every core class
+ * flows it through. Defaults to `KnownEventType`, so callers dealing only in browser kinds need
+ * not spell it out. Shared shapes stay shared — the set of NAMES is open, not the envelope.
  */
 type BaseEvent<TType extends string = KnownEventType> = {
     type: TType;
@@ -280,7 +275,6 @@ interface SDKOptions$1<TEvent extends BaseEvent<string> = EventTypes$1[keyof Eve
      * package's `config/types.ts`).
      */
     enabledEvents: string[];
-    eventSampleRate: number;
     sessionSampleRate: number;
     debug: boolean;
     excludedUrls?: Array<string | RegExp>;
@@ -302,41 +296,12 @@ interface SDKOptions$1<TEvent extends BaseEvent<string> = EventTypes$1[keyof Eve
      */
     replay?: unknown;
     /**
-     * Target maximum wall-clock duration of a session, in milliseconds.
+     * Target maximum wall-clock duration of a session, in ms. Enforced LAZILY on activity, so NOT
+     * a hard bound — an idle tab 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.
      *
-     * 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.)
-     *
-     * 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;
 }
@@ -442,7 +407,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 +435,6 @@ declare class SessionManager {
     setSessionId(newSessionId?: string): Promise<void>;
     startReplayRecording(): void;
     stopReplayRecording(): void;
-    handoffForReinit(): void;
     destroy(): void;
 }
 
@@ -491,11 +455,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;

package/dist/index.d.ts

@@ -4,14 +4,9 @@
  */
 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.
+ * `TType` lets a platform name its own event kinds without editing core, and every core class
+ * flows it through. Defaults to `KnownEventType`, so callers dealing only in browser kinds need
+ * not spell it out. Shared shapes stay shared — the set of NAMES is open, not the envelope.
  */
 type BaseEvent<TType extends string = KnownEventType> = {
     type: TType;
@@ -280,7 +275,6 @@ interface SDKOptions$1<TEvent extends BaseEvent<string> = EventTypes$1[keyof Eve
      * package's `config/types.ts`).
      */
     enabledEvents: string[];
-    eventSampleRate: number;
     sessionSampleRate: number;
     debug: boolean;
     excludedUrls?: Array<string | RegExp>;
@@ -302,41 +296,12 @@ interface SDKOptions$1<TEvent extends BaseEvent<string> = EventTypes$1[keyof Eve
      */
     replay?: unknown;
     /**
-     * Target maximum wall-clock duration of a session, in milliseconds.
+     * Target maximum wall-clock duration of a session, in ms. Enforced LAZILY on activity, so NOT
+     * a hard bound — an idle tab 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.
      *
-     * 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.)
-     *
-     * 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;
 }
@@ -442,7 +407,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 +435,6 @@ declare class SessionManager {
     setSessionId(newSessionId?: string): Promise<void>;
     startReplayRecording(): void;
     stopReplayRecording(): void;
-    handoffForReinit(): void;
     destroy(): void;
 }
 
@@ -491,11 +455,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;