@spotify-confidence/session-recording 0.0.0 → 0.17.3

package/CHANGELOG.md

@@ -0,0 +1,52 @@
+# Changelog
+
+## [0.17.3](https://github.com/spotify/confidence-sdk-js/compare/session-recording-v0.17.2...session-recording-v0.17.3) (2026-06-16)
+
+
+### ✨ New Features
+
+* add route parameterization for route change and meta events ([#370](https://github.com/spotify/confidence-sdk-js/issues/370)) ([6efbee0](https://github.com/spotify/confidence-sdk-js/commit/6efbee08776c88b05dfa0949844f6c330bb0bcaa))
+* emit flag evaluations into session recordings ([#369](https://github.com/spotify/confidence-sdk-js/issues/369)) ([3728c6d](https://github.com/spotify/confidence-sdk-js/commit/3728c6d682f97c3b2f18c8979dc91c50328b2345))
+
+
+### Dependencies
+
+* The following workspace dependencies were updated
+  * dependencies
+    * @spotify-confidence/csr-common bumped to 0.17.3
+    * @spotify-confidence/csr-recorder bumped to 0.17.3
+
+## [0.17.2](https://github.com/spotify/confidence-sdk-js/compare/session-recording-v0.17.1...session-recording-v0.17.2) (2026-06-15)
+
+
+### 🐛 Bug Fixes
+
+* improve csr package READMEs ([#367](https://github.com/spotify/confidence-sdk-js/issues/367)) ([3c5a254](https://github.com/spotify/confidence-sdk-js/commit/3c5a254b6b7bd23142ffe7ce6d99f327e67ff478))
+
+
+### Dependencies
+
+* The following workspace dependencies were updated
+  * dependencies
+    * @spotify-confidence/csr-common bumped to 0.17.2
+    * @spotify-confidence/csr-recorder bumped to 0.17.2
+
+## [0.17.1](https://github.com/spotify/confidence-sdk-js/compare/session-recording-v0.17.0...session-recording-v0.17.1) (2026-06-15)
+
+
+### 🐛 Bug Fixes
+
+* add csr packages to release-please ([#363](https://github.com/spotify/confidence-sdk-js/issues/363)) ([f868e03](https://github.com/spotify/confidence-sdk-js/commit/f868e036ee27fcdd26ee26c8a47d2466a47e2a60))
+
+
+### ✨ New Features
+
+* add session recording packages ([#360](https://github.com/spotify/confidence-sdk-js/issues/360)) ([4584f50](https://github.com/spotify/confidence-sdk-js/commit/4584f502f17d01a15390789519c99308797a513d))
+
+
+### Dependencies
+
+* The following workspace dependencies were updated
+  * dependencies
+    * @spotify-confidence/csr-common bumped to 0.17.1
+    * @spotify-confidence/csr-recorder bumped to 0.17.1

package/README.md

@@ -0,0 +1,155 @@
+# @spotify-confidence/session-recording
+
+![](https://img.shields.io/badge/lifecycle-beta-a0c3d2.svg)
+
+Browser SDK for recording user sessions with [Confidence](https://confidence.spotify.com). Captures DOM events in real time and streams them to the Confidence backend for analysis.
+
+## Installation
+
+```bash
+npm install @spotify-confidence/session-recording
+```
+
+## Quick start
+
+```typescript
+import { initSessionRecorder } from '@spotify-confidence/session-recording';
+
+const recorder = initSessionRecorder({
+  clientSecret: '<your-client-secret>',
+});
+```
+
+That's it. In `automatic` mode (the default), recording begins as soon as a session is established with the backend. The SDK handles sampling, transport, and reconnection automatically.
+
+## Privacy: masking and blocking
+
+The SDK provides two mechanisms to prevent sensitive content from being captured:
+
+**Masking** replaces text content with `•` characters while preserving the layout. The element is still visible in the replay, but the actual text is never sent to the backend.
+
+```typescript
+const recorder = initSessionRecorder({
+  clientSecret: '<your-client-secret>',
+  maskSelectors: ['.pii', '[data-sensitive]'],
+  maskInputs: true, // mask all <input>, <textarea>, and contenteditable values (default: true)
+});
+```
+
+**Blocking** replaces entire subtrees with an empty placeholder. The blocked element's dimensions are preserved, but nothing inside it — text, images, child nodes — is serialized or sent.
+
+```typescript
+const recorder = initSessionRecorder({
+  clientSecret: '<your-client-secret>',
+  blockSelectors: ['video', '.third-party-widget', '[data-block]'],
+});
+```
+
+`maskInputs` defaults to `true` — all input values are masked unless you explicitly opt out.
+
+## Context
+
+Context lets you attach custom dimensions to the recording session. These are sent alongside the auto-collected browser metadata (user agent, OS, viewport, language, timezone) in the session init request. Context serves two purposes: it helps you find and filter recordings later, and the backend uses it to target recordings to specific cohorts of your user population (e.g. only record premium users, or users on a specific build version).
+
+```typescript
+const recorder = initSessionRecorder({
+  clientSecret: '<your-client-secret>',
+  targetingKey: 'user-42',
+  context: {
+    buildVersion: '2.3.1',
+    environment: 'production',
+    plan: 'premium',
+    featureFlags: 'new-checkout-enabled',
+  },
+});
+```
+
+`targetingKey` is the end-user identifier (visitor ID, device ID, etc.). The backend uses it for sampling and targeting decisions — it determines whether this user should be recorded.
+
+## Configuration
+
+```typescript
+const recorder = initSessionRecorder({
+  // Required
+  clientSecret: '<your-client-secret>',
+
+  // Identity and context
+  targetingKey: 'user-42',
+  context: { buildVersion: '2.3.1' },
+
+  // Privacy
+  maskSelectors: ['.pii'],
+  blockSelectors: ['video'],
+  maskInputs: true, // default: true
+
+  // Capture options
+  captureConsoleLogs: true, // capture browser console output (default: false)
+  captureNetworkRequests: false, // capture fetch/XHR metadata (default: false)
+  captureRouteChanges: true, // capture client-side route changes (default: true)
+
+  // Recording mode
+  mode: 'automatic', // 'automatic' (default) or 'manual'
+});
+```
+
+## Route parameterization
+
+Routes containing dynamic segments (such as IDs in the URL) are automatically normalized into patterns — for example, `/users/123/profile` becomes `/users/:id/profile`. This ensures that per-page metrics are grouped by route rather than by individual page visit, keeping dashboards meaningful and query performance fast.
+
+If your app uses URL patterns that aren't automatically detected, you can provide a custom `parameterizeRoute` function to control how routes are grouped:
+
+```typescript
+import { defaultParameterizeRoute } from '@spotify-confidence/csr-recorder';
+
+const recorder = initSessionRecorder({
+  clientSecret: '<your-client-secret>',
+  parameterizeRoute: route => {
+    return defaultParameterizeRoute(route).replace(/\/teams\/[^/]+/, '/teams/:slug');
+  },
+});
+```
+
+See the [`@spotify-confidence/csr-recorder` README](../csr-recorder/README.md#route-parameterization) for the full list of default patterns.
+
+## Manual mode
+
+Use `manual` mode to control when recording starts — useful for gating on user consent or feature flags.
+
+```typescript
+const recorder = initSessionRecorder({
+  clientSecret: '<your-client-secret>',
+  mode: 'manual',
+});
+
+// Later, when ready:
+recorder.start();
+```
+
+## Custom tags and measurements
+
+Attach metadata to a recording for filtering and analysis.
+
+```typescript
+recorder.tag('plan', 'premium');
+recorder.measure('checkout_items', 3);
+```
+
+## API
+
+### `initSessionRecorder(options): SessionRecorder`
+
+Creates a session recorder. Always returns a `SessionRecorder` — safe to call, never throws.
+
+### `SessionRecorder`
+
+| Method                 | Description                                                    |
+| ---------------------- | -------------------------------------------------------------- |
+| `start()`              | Start recording. No-op in automatic mode.                      |
+| `stop()`               | Stop recording permanently. Idempotent.                        |
+| `tag(key, value?)`     | Attach a string tag. Tags with the same key accumulate values. |
+| `measure(key, value?)` | Record a numeric measurement. Same key = summed.               |
+| `isRecording`          | Whether the recorder is actively capturing events.             |
+
+## License
+
+Apache 2.0 — see [LICENSE](../../LICENSE).