vident-rum 0.8.0

package/README.md

@@ -0,0 +1,424 @@
+# @spanwise/rum
+
+Real User Monitoring SDK for browser applications. Captures page views, clicks, errors, Web Vitals, and session replays.
+
+## Installation
+
+```bash
+npm install @spanwise/rum
+# or
+pnpm add @spanwise/rum
+# or
+yarn add @spanwise/rum
+```
+
+## Quick Start
+
+```typescript
+import { createSpanwiseBrowser } from "@spanwise/rum"
+
+const spanwise = createSpanwiseBrowser({
+  apiKey: "sw_...",
+  serviceName: "my-app",
+})
+
+// That's it! Page views, clicks, errors, and vitals are tracked automatically.
+```
+
+## Configuration
+
+```typescript
+const spanwise = createSpanwiseBrowser({
+  // Required
+  apiKey: "sw_...",
+
+  // Optional
+  serviceName: "my-app",           // Service name for filtering
+  sampleRate: 1.0,                 // Sample 100% of sessions (default: 1.0)
+  trackPageViews: true,            // Track page views (default: true)
+  trackClicks: true,               // Track clicks (default: true)
+  trackVitals: true,               // Track Web Vitals (default: true)
+  trackErrors: true,               // Track errors (default: true)
+  trackResources: true,            // Track fetch/XHR requests (default: true)
+  sessionStorage: "cookie",        // "cookie" or "sessionStorage" (default: "cookie")
+
+  // Distributed Tracing
+  tracing: {
+    enabled: true,                 // Inject traceparent headers (default: true)
+    propagateToOrigins: [          // Origins to propagate trace context to
+      "https://api.example.com",
+      /\.example\.com$/,
+    ],
+  },
+
+  // Session Replay (opt-in)
+  replay: {
+    enabled: true,                 // Enable replay recording (default: false)
+    sampleRate: 0.1,               // Record 10% of sessions (default: 0.1)
+    onErrorSampleRate: 1.0,        // Record 100% of sessions with errors (default: 1.0)
+    privacyMode: "strict",         // Privacy mode (default: "strict")
+  },
+})
+```
+
+## API
+
+### `spanwise.trackEvent(name, properties?)`
+
+Track a custom event.
+
+```typescript
+spanwise.trackEvent("purchase", {
+  productId: "123",
+  amount: 99.99,
+})
+```
+
+### `spanwise.trackPageView(url?)`
+
+Manually track a page view. Called automatically on navigation.
+
+```typescript
+spanwise.trackPageView("/checkout")
+```
+
+### `spanwise.trackError(error, options?)`
+
+Manually track an error.
+
+```typescript
+try {
+  await riskyOperation()
+} catch (error) {
+  spanwise.trackError(error, {
+    requestId: "req_123",
+    traceId: "trace_abc",
+  })
+}
+```
+
+### `spanwise.setUser(id, traits?)`
+
+Identify the current user.
+
+```typescript
+spanwise.setUser("user_123", {
+  email: "user@example.com",
+  plan: "pro",
+})
+```
+
+### `spanwise.getSessionId()`
+
+Get the current session ID.
+
+```typescript
+const sessionId = spanwise.getSessionId()
+```
+
+### `spanwise.forceReplayUpload()`
+
+Force replay upload for specific users (bypasses sampling).
+
+```typescript
+// Force upload for VIP users regardless of sample rate
+if (user.isVIP) {
+  spanwise.forceReplayUpload()
+}
+```
+
+### `spanwise.stopReplay()`
+
+Stop replay recording entirely.
+
+### `spanwise.isReplayUploading()`
+
+Check if replay is currently uploading to server (vs buffering in memory).
+
+---
+
+## Session Replay
+
+Session Replay records user interactions as a video-like playback. It captures DOM mutations, mouse movements, clicks, and scrolls.
+
+### Enabling Replay
+
+```typescript
+const spanwise = createSpanwiseBrowser({
+  apiKey: "sw_...",
+  replay: {
+    enabled: true,
+  },
+})
+```
+
+### How It Works: Rolling Buffer
+
+Session Replay uses a **rolling buffer architecture** (similar to Sentry):
+
+1. **Always recording** - When enabled, the SDK always records to a 60-second memory buffer
+2. **Sampled sessions** (default 10%) - Upload immediately to server
+3. **Non-sampled sessions** (90%) - Keep buffer in memory, zero network cost
+4. **On error** - Flush the 60-second buffer and start uploading
+
+This means you **always capture what happened before an error**, not just after.
+
+### Sampling
+
+```typescript
+replay: {
+  enabled: true,
+  sampleRate: 0.1,         // 10% upload immediately
+  onErrorSampleRate: 1.0,  // 100% upload on error (includes 60s buffer)
+}
+```
+
+| Scenario | What's Captured |
+|----------|-----------------|
+| Sampled (10%) | Full session from start |
+| Not sampled + error | 60 seconds before error + everything after |
+| Not sampled + no error | Nothing sent (zero network cost) |
+
+---
+
+## Privacy & Data Protection
+
+Session Replay is designed with privacy as the default. **No configuration is required for most applications** - sensitive data is automatically protected.
+
+### Privacy Modes
+
+| Mode | Text | Inputs | Use Case |
+|------|------|--------|----------|
+| `"strict"` (default) | Masked | Masked | Most applications |
+| `"balanced"` | Visible | Masked | Marketing sites, blogs |
+| `"permissive"` | Visible | Visible | Internal tools only |
+
+```typescript
+replay: {
+  enabled: true,
+  privacyMode: "strict",  // Default - masks everything
+}
+```
+
+### What Each Mode Does
+
+#### Strict Mode (Default)
+
+All text content is replaced with `****`. Form inputs show `•••••`. You see the page structure and user interactions, but no actual content.
+
+```
+┌─────────────────────────────┐
+│  **** ********              │  ← Masked heading
+│                             │
+│  ******** **** ** *******   │  ← Masked paragraph
+│  ******* ** *** ****        │
+│                             │
+│  Email: [•••••••••••••]     │  ← Masked input
+│  Password: [••••••••]       │
+│                             │
+│  [**********]               │  ← Masked button
+└─────────────────────────────┘
+```
+
+#### Balanced Mode
+
+Text is visible, but all form inputs are masked. Good for content-heavy sites.
+
+```
+┌─────────────────────────────┐
+│  Welcome Back               │  ← Visible heading
+│                             │
+│  Please sign in to continue │  ← Visible text
+│                             │
+│  Email: [•••••••••••••]     │  ← Masked input
+│  Password: [••••••••]       │
+│                             │
+│  [Sign In]                  │  ← Visible button
+└─────────────────────────────┘
+```
+
+#### Permissive Mode
+
+Everything is recorded as-is. **Only use for internal tools or with explicit user consent.**
+
+### Fine-Grained Control with HTML Attributes
+
+Regardless of privacy mode, you can control specific elements:
+
+#### Block Elements Completely
+
+Use `data-sw-block` to completely hide an element. It will appear as a gray placeholder in replays.
+
+```html
+<!-- Credit card form - never record -->
+<div data-sw-block>
+  <input type="text" placeholder="Card number" />
+  <input type="text" placeholder="CVV" />
+</div>
+
+<!-- Sensitive user data -->
+<div data-sw-block class="user-profile">
+  <p>SSN: 123-45-6789</p>
+</div>
+```
+
+#### Mask Specific Elements
+
+Use `data-sw-mask` to mask text while preserving structure (useful in balanced/permissive modes).
+
+```html
+<!-- Mask email in a visible section -->
+<p>Contact: <span data-sw-mask>user@example.com</span></p>
+```
+
+#### Unmask Elements in Strict Mode
+
+Use `data-sw-unmask` to show content even when using strict mode.
+
+```html
+<!-- Show navigation labels in strict mode -->
+<nav data-sw-unmask>
+  <a href="/">Home</a>
+  <a href="/products">Products</a>
+  <a href="/about">About</a>
+</nav>
+
+<!-- Show static content -->
+<footer data-sw-unmask>
+  <p>© 2024 My Company</p>
+</footer>
+```
+
+#### rrweb Classes (Alternative)
+
+The standard rrweb classes also work:
+
+```html
+<div class="rr-block">Hidden content</div>
+<div class="rr-mask">Masked content</div>
+```
+
+### Best Practices
+
+1. **Start with strict mode** - It's the safest default. Only relax if needed.
+
+2. **Block sensitive sections entirely** - For areas with PII (profile pages, account settings), use `data-sw-block`.
+
+3. **Review before production** - Test your app with replay enabled and verify no sensitive data appears.
+
+4. **Consider user consent** - For GDPR compliance, inform users that sessions may be recorded.
+
+5. **Use unmask sparingly** - Only unmask truly static, non-sensitive content like navigation labels.
+
+### What's Automatically Protected
+
+Even without configuration:
+
+- All `<input>` values are masked (except in permissive mode)
+- Password fields are always masked
+- Credit card patterns are detected and masked
+- `<script>` content is never recorded
+- `<head>` metadata is stripped
+
+### Sensitive Data Checklist
+
+Before enabling replay, ensure these are blocked or masked:
+
+- [ ] User profile information (name, email, phone)
+- [ ] Payment forms and credit card inputs
+- [ ] Social security numbers, government IDs
+- [ ] Medical or health information
+- [ ] Authentication tokens displayed on screen
+- [ ] Private messages or chat content
+- [ ] Financial account numbers
+- [ ] Any PII in confirmation pages
+
+---
+
+## Distributed Tracing
+
+The SDK automatically injects `traceparent` headers into fetch/XHR requests, connecting frontend sessions to backend traces.
+
+```typescript
+const spanwise = createSpanwiseBrowser({
+  apiKey: "sw_...",
+  tracing: {
+    enabled: true,
+    propagateToOrigins: [
+      "https://api.myapp.com",
+      /\.myapp\.com$/,
+    ],
+  },
+})
+```
+
+Your backend will receive headers like:
+
+```
+traceparent: 00-{traceId}-{spanId}-01
+```
+
+---
+
+## Browser Support
+
+- Chrome 64+
+- Firefox 67+
+- Safari 12+
+- Edge 79+
+
+Session Replay requires:
+- MutationObserver
+- WeakMap
+- requestAnimationFrame
+
+---
+
+## Bundle Size
+
+The base SDK is ~8KB gzipped. Session Replay adds ~40KB gzipped (rrweb).
+
+Replay is dynamically imported only when enabled, so it won't affect your bundle if not used.
+
+---
+
+## TypeScript
+
+Full TypeScript support with exported types:
+
+```typescript
+import {
+  createSpanwiseBrowser,
+  type BrowserConfig,
+  type SpanwiseBrowser,
+  type ReplayConfig,
+  type PrivacyMode,
+  type TracingConfig,
+} from "@spanwise/rum"
+```
+
+---
+
+## Troubleshooting
+
+### Replay not recording
+
+1. Check that `replay.enabled` is `true`
+2. Verify you're within the sample rate (try `sampleRate: 1.0` for testing)
+3. Check browser console for errors
+
+### High data volume
+
+1. Reduce `sampleRate` (e.g., `0.05` for 5%)
+2. Use `"strict"` privacy mode (smaller payloads due to masked content)
+
+### Missing trace correlation
+
+1. Ensure `tracing.propagateToOrigins` includes your API domain
+2. Check that your backend parses the `traceparent` header
+
+---
+
+## License
+
+MIT

package/dist/client.d.ts

@@ -0,0 +1,67 @@
+import { type ReplayConfig } from "./replay.js";
+import { type StorageMode } from "./session.js";
+export type TracingConfig = {
+    /** Enable distributed tracing (default: true) */
+    enabled?: boolean;
+    /** Origins to propagate trace context to (default: same-origin only) */
+    propagateToOrigins?: (string | RegExp)[];
+    /** Trace fetch requests (default: true) */
+    traceFetch?: boolean;
+    /** Trace XMLHttpRequest (default: true) */
+    traceXHR?: boolean;
+};
+export type BrowserConfig = {
+    apiKey: string;
+    appName?: string;
+    baseUrl?: string;
+    sampleRate?: number;
+    trackClicks?: boolean;
+    trackPageViews?: boolean;
+    trackVitals?: boolean;
+    trackErrors?: boolean;
+    /** Track HTTP resources (fetch/XHR) with timing (default: true) */
+    trackResources?: boolean;
+    /** Distributed tracing configuration */
+    tracing?: TracingConfig;
+    /**
+     * Session storage mode (default: "cookie")
+     * - "cookie": Uses cookies with localStorage fallback. Survives OAuth redirects.
+     *             Requires cookie consent in GDPR regions.
+     * - "sessionStorage": Original behavior. Tab-isolated, cleared on tab close.
+     *                     No cookie consent required.
+     */
+    sessionStorage?: StorageMode;
+    /** Session replay configuration */
+    replay?: ReplayConfig;
+};
+export declare function createVidentBrowser(config: BrowserConfig): {
+    trackEvent: () => void;
+    trackPageView: () => void;
+    trackError: () => void;
+    setUser: () => void;
+    getSessionId: () => null;
+    startReplay: () => void;
+    stopReplay: () => void;
+    /** Force replay upload (e.g., for VIP users) - overrides sampling */
+    forceReplayUpload?: undefined;
+    /** Check if replay is currently uploading to server */
+    isReplayUploading?: undefined;
+} | {
+    trackEvent: (name: string, properties?: Record<string, unknown>) => void;
+    trackPageView: (url?: string) => void;
+    trackError: (error: Error, options?: {
+        requestId?: string;
+        traceId?: string;
+    }) => void;
+    setUser: (id: string, traits?: Record<string, unknown>) => void;
+    getSessionId: () => string;
+    /** Force replay upload (e.g., for VIP users) - overrides sampling */
+    forceReplayUpload: () => void | undefined;
+    /** Stop replay recording */
+    stopReplay: () => void | undefined;
+    /** Check if replay is currently uploading to server */
+    isReplayUploading: () => boolean;
+    startReplay?: undefined;
+};
+export type VidentBrowser = ReturnType<typeof createVidentBrowser>;
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAYA,OAAO,EAAE,KAAK,YAAY,EAAwB,MAAM,aAAa,CAAA;AACrE,OAAO,EACN,KAAK,WAAW,EAIhB,MAAM,cAAc,CAAA;AAIrB,MAAM,MAAM,aAAa,GAAG;IAC3B,iDAAiD;IACjD,OAAO,CAAC,EAAE,OAAO,CAAA;IACjB,wEAAwE;IACxE,kBAAkB,CAAC,EAAE,CAAC,MAAM,GAAG,MAAM,CAAC,EAAE,CAAA;IACxC,2CAA2C;IAC3C,UAAU,CAAC,EAAE,OAAO,CAAA;IACpB,2CAA2C;IAC3C,QAAQ,CAAC,EAAE,OAAO,CAAA;CAClB,CAAA;AAED,MAAM,MAAM,aAAa,GAAG;IAC3B,MAAM,EAAE,MAAM,CAAA;IACd,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,WAAW,CAAC,EAAE,OAAO,CAAA;IACrB,cAAc,CAAC,EAAE,OAAO,CAAA;IACxB,WAAW,CAAC,EAAE,OAAO,CAAA;IACrB,WAAW,CAAC,EAAE,OAAO,CAAA;IACrB,mEAAmE;IACnE,cAAc,CAAC,EAAE,OAAO,CAAA;IACxB,wCAAwC;IACxC,OAAO,CAAC,EAAE,aAAa,CAAA;IACvB;;;;;;OAMG;IACH,cAAc,CAAC,EAAE,WAAW,CAAA;IAC5B,mCAAmC;IACnC,MAAM,CAAC,EAAE,YAAY,CAAA;CACrB,CAAA;AAmBD,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,aAAa;;;;;;;;IA2NvD,qEAAqE;;IAIrE,uDAAuD;;;uBAxKjD,MAAM,eACC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAClC,IAAI;0BAhBsB,MAAM,KAAG,IAAI;wBA6BlC,KAAK,YACF;QAAE,SAAS,CAAC,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,KAChD,IAAI;kBAOc,MAAM,WAAW,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAG,IAAI;wBAWtC,MAAM;IAiInC,qEAAqE;;IAErE,4BAA4B;;IAE5B,uDAAuD;;;EAGxD;AAED,MAAM,MAAM,aAAa,GAAG,UAAU,CAAC,OAAO,mBAAmB,CAAC,CAAA"}

package/dist/client.js

@@ -0,0 +1,207 @@
+import { captureError, setupErrorTracking } from "./errors.js";
+import { createBaseEvent } from "./events.js";
+import { instrumentFetch, updateFetchConfig } from "./instrumentation/fetch.js";
+import { instrumentXHR, updateXHRConfig } from "./instrumentation/xhr.js";
+import { createReplayRecorder } from "./replay.js";
+import { getOrCreateSession, refreshSession, setStorageMode, } from "./session.js";
+import { createTransport } from "./transport.js";
+import { setupVitalsTracking } from "./vitals.js";
+const DEFAULT_BASE_URL = "https://api.vident.dev";
+function getClickTarget(element) {
+    if (element.id)
+        return `#${element.id}`;
+    const tag = element.tagName.toLowerCase();
+    const classes = Array.from(element.classList).slice(0, 3).join(".");
+    if (classes)
+        return `${tag}.${classes}`;
+    return tag;
+}
+function getClickText(element) {
+    const text = element.textContent?.trim().slice(0, 50);
+    return text || undefined;
+}
+export function createVidentBrowser(config) {
+    // Apply sampling
+    const sampleRate = config.sampleRate ?? 1;
+    if (Math.random() > sampleRate) {
+        // Return no-op client
+        return {
+            trackEvent: () => { },
+            trackPageView: () => { },
+            trackError: () => { },
+            setUser: () => { },
+            getSessionId: () => null,
+            startReplay: () => { },
+            stopReplay: () => { },
+        };
+    }
+    const baseUrl = config.baseUrl ?? DEFAULT_BASE_URL;
+    setStorageMode(config.sessionStorage ?? "cookie");
+    const { sessionId } = getOrCreateSession();
+    let userId;
+    const transport = createTransport({
+        apiKey: config.apiKey,
+        baseUrl,
+        appName: config.appName,
+    });
+    // Initialize replay recorder if configured
+    const replayRecorder = config.replay?.enabled
+        ? createReplayRecorder(config.replay, {
+            apiKey: config.apiKey,
+            baseUrl,
+            sessionId,
+        })
+        : null;
+    function enqueueEvent(event) {
+        refreshSession();
+        transport.enqueue(event);
+    }
+    function trackPageView(url) {
+        const event = {
+            ...createBaseEvent("page_view", sessionId, userId),
+            type: "page_view",
+            url: url ?? window.location.href,
+            data: {
+                referrer: document.referrer || undefined,
+                title: document.title,
+            },
+        };
+        enqueueEvent(event);
+    }
+    function trackEvent(name, properties) {
+        const event = {
+            ...createBaseEvent("custom", sessionId, userId),
+            type: "custom",
+            data: {
+                name,
+                properties,
+            },
+        };
+        enqueueEvent(event);
+    }
+    function trackError(error, options) {
+        const event = captureError(error, sessionId, userId, options);
+        enqueueEvent(event);
+        // Mark replay for error correlation
+        replayRecorder?.markError();
+    }
+    function setUser(id, traits) {
+        userId = id;
+        // Update instrumentation configs with new userId
+        updateFetchConfig(userId);
+        updateXHRConfig(userId);
+        // Optionally track user identification as custom event
+        if (traits) {
+            trackEvent("user_identified", { userId: id, ...traits });
+        }
+    }
+    function getSessionIdValue() {
+        return sessionId;
+    }
+    // Auto-tracking setup
+    if (config.trackPageViews !== false) {
+        // Track initial page view
+        trackPageView();
+        // Track SPA navigation
+        const originalPushState = history.pushState.bind(history);
+        const originalReplaceState = history.replaceState.bind(history);
+        history.pushState = (...args) => {
+            originalPushState(...args);
+            trackPageView();
+        };
+        history.replaceState = (...args) => {
+            originalReplaceState(...args);
+            trackPageView();
+        };
+        window.addEventListener("popstate", () => {
+            trackPageView();
+        });
+    }
+    if (config.trackClicks !== false) {
+        document.addEventListener("click", (event) => {
+            const target = event.target;
+            if (!target)
+                return;
+            // Only track interactive elements
+            const interactiveElements = [
+                "A",
+                "BUTTON",
+                "INPUT",
+                "SELECT",
+                "TEXTAREA",
+            ];
+            const isInteractive = interactiveElements.includes(target.tagName) ||
+                target.closest("a, button") !== null ||
+                target.getAttribute("role") === "button";
+            if (!isInteractive)
+                return;
+            const clickEvent = {
+                ...createBaseEvent("click", sessionId, userId),
+                type: "click",
+                data: {
+                    target: getClickTarget(target),
+                    text: getClickText(target),
+                    x: event.clientX,
+                    y: event.clientY,
+                },
+            };
+            enqueueEvent(clickEvent);
+        }, { capture: true });
+    }
+    if (config.trackVitals !== false) {
+        setupVitalsTracking(sessionId, userId, (event) => {
+            enqueueEvent(event);
+        }, () => {
+            transport.flushBeacon();
+        });
+    }
+    if (config.trackErrors !== false) {
+        setupErrorTracking(sessionId, userId, (event) => {
+            enqueueEvent(event);
+            // Mark replay for error correlation (auto-captured errors)
+            replayRecorder?.markError();
+        });
+    }
+    // Resource tracking: capture HTTP requests with timing and trace correlation
+    // - trackResources: store resource events in RUM (default: true)
+    // - tracing.enabled: inject traceparent headers for backend correlation (default: true)
+    // If either is enabled, we instrument fetch/XHR
+    const shouldInstrument = config.trackResources !== false || config.tracing?.enabled !== false;
+    const shouldStoreResources = config.trackResources !== false;
+    if (shouldInstrument) {
+        const ingestUrl = `${baseUrl}/v1/ingest`;
+        const instrumentationConfig = {
+            propagateToOrigins: config.tracing?.propagateToOrigins,
+            sessionId,
+            userId,
+            ingestUrl,
+        };
+        const onResource = shouldStoreResources
+            ? (event) => enqueueEvent(event)
+            : () => { }; // traceparent injected but events not stored
+        // Capture network errors with URL context (only if error tracking enabled)
+        const onNetworkError = config.trackErrors !== false
+            ? (event) => enqueueEvent(event)
+            : undefined;
+        if (config.tracing?.traceFetch !== false) {
+            instrumentFetch(instrumentationConfig, onResource, onNetworkError);
+        }
+        if (config.tracing?.traceXHR !== false) {
+            instrumentXHR(instrumentationConfig, onResource, onNetworkError);
+        }
+    }
+    return {
+        trackEvent,
+        trackPageView,
+        trackError,
+        setUser,
+        getSessionId: getSessionIdValue,
+        /** Force replay upload (e.g., for VIP users) - overrides sampling */
+        forceReplayUpload: () => replayRecorder?.startUploading(),
+        /** Stop replay recording */
+        stopReplay: () => replayRecorder?.stop(),
+        /** Check if replay is currently uploading to server */
+        isReplayUploading: () => replayRecorder?.isUploading() ?? false,
+    };
+}
+//# sourceMappingURL=client.js.map