@monoscopetech/browser 0.6.1 → 0.7.2

package/README.md

@@ -1,6 +1,6 @@
 # Monoscope Browser SDK
 
-The **Monoscope Browser SDK** is a lightweight JavaScript library for adding **session replay**, **performance tracing**, and **frontend logging** to your web applications.
+The **Monoscope Browser SDK** is a lightweight JavaScript library for adding **session replay**, **performance tracing**, **error tracking**, and **web vitals** to your web applications.
 
 When used together with the [Monoscope Server SDKs](https://apitoolkit.io/docs/sdks/), you gain **end-to-end observability** — seamlessly connecting user interactions in the browser to backend services, APIs, and databases.
 
@@ -8,9 +8,9 @@ This means you can:
 
 - **Replay user sessions** to see exactly what happened.
 - **Trace requests** from the frontend, through your backend, and into your database.
-- **Capture logs and errors** with full context for faster debugging.
-
-With the sdk, you can seamlessly monitor how users interact with your app, measure performance, and gain insights into issues — all in one place.
+- **Capture errors and console logs** with full context and breadcrumbs for faster debugging.
+- **Collect Web Vitals** (CLS, INP, LCP, FCP, TTFB) automatically.
+- **Track SPA navigations** across pushState, replaceState, and popstate.
 
 ---
 
@@ -40,7 +40,12 @@ import Monoscope from "@monoscopetech/browser";
 const monoscope = new Monoscope({
   projectId: "YOUR_PROJECT_ID",
   serviceName: "my-web-app",
-  // ...other configuration options
+});
+
+// Identify the current user
+monoscope.setUser({
+  id: "user-123",
+  email: "user@example.com",
 });
 ```
 
@@ -50,16 +55,23 @@ const monoscope = new Monoscope({
 
 The `Monoscope` constructor accepts the following options:
 
-| Name                           | Type                  | Description                                                                  |
-| ------------------------------ | --------------------- | ---------------------------------------------------------------------------- |
-| `projectId`                    | `string`              | **Required** – Your Monoscope project ID.                                    |
-| `serviceName`                  | `string`              | **Required** – Name of your service or application.                          |
-| `exporterEndpoint`             | `string`              | Endpoint for exporting traces/logs. Defaults to Monoscope's ingest endpoint. |
-| `propagateTraceHeaderCorsUrls` | `RegExp[]`            | Array of regex patterns for URLs where trace headers should be propagated.   |
-| `resourceAttributes`           | `Record<string, any>` | Additional resource-level attributes.                                        |
-| `instrumentations`             | `any[]`               | OpenTelemetry instrumentations to enable.                                    |
-| `replayEventsBaseUrl`          | `string`              | Base URL for session replay events. Defaults to Monoscope's ingest endpoint. |
-| `user`                         | `MonoscopeUser`       | Default user information for the session.                                    |
+| Name | Type | Description |
+| --- | --- | --- |
+| `projectId` | `string` | **Required** – Your Monoscope project ID. |
+| `serviceName` | `string` | **Required** – Name of your service or application. |
+| `exporterEndpoint` | `string` | Endpoint for exporting traces. Defaults to Monoscope's ingest endpoint. |
+| `propagateTraceHeaderCorsUrls` | `RegExp[]` | URL patterns where trace context headers should be propagated. Defaults to same-origin only. |
+| `resourceAttributes` | `Record<string, string>` | Additional OpenTelemetry resource attributes. |
+| `instrumentations` | `unknown[]` | Additional OpenTelemetry instrumentations to register. |
+| `replayEventsBaseUrl` | `string` | Base URL for session replay events. Defaults to Monoscope's ingest endpoint. |
+| `enableNetworkEvents` | `boolean` | Include network timing events in document load spans. |
+| `user` | `MonoscopeUser` | Default user information for the session. |
+| `debug` | `boolean` | Enable debug logging to the console. |
+| `sampleRate` | `number` | Trace sampling rate from `0` to `1`. Default `1` (100%). |
+| `replaySampleRate` | `number` | Replay sampling rate from `0` to `1`. Default `1` (100%). |
+| `enabled` | `boolean` | Whether to start collecting data immediately. Default `true`. |
+| `resourceTimingThresholdMs` | `number` | Minimum resource duration (ms) to report. Default `200`. |
+| `enableUserInteraction` | `boolean` | Trace user clicks and interactions, linking them to downstream network calls. Default `false`. |
 
 ---
 
@@ -67,13 +79,15 @@ The `Monoscope` constructor accepts the following options:
 
 The `MonoscopeUser` object can contain:
 
-| Name       | Type       | Description               |
-| ---------- | ---------- | ------------------------- |
-| `email`    | `string`   | User's email address.     |
-| `fullName` | `string`   | User's full name.         |
-| `name`     | `string`   | User's preferred name.    |
-| `id`       | `string`   | User's unique identifier. |
-| `roles`    | `string[]` | User's roles.             |
+| Name | Type | Description |
+| --- | --- | --- |
+| `email` | `string` | User's email address. |
+| `full_name` | `string` | User's full name. |
+| `name` | `string` | User's preferred name. |
+| `id` | `string` | User's unique identifier. |
+| `roles` | `string[]` | User's roles. |
+
+Additional string-keyed attributes are also accepted and forwarded as custom user attributes.
 
 ---
 
@@ -81,7 +95,7 @@ The `MonoscopeUser` object can contain:
 
 ### `setUser(user: MonoscopeUser)`
 
-Associates the given user with the current session.
+Associates the given user with the current session. Can be called at any time.
 
 ```javascript
 monoscope.setUser({
@@ -90,17 +104,191 @@ monoscope.setUser({
 });
 ```
 
----
+### `startSpan<T>(name: string, fn: (span: Span) => T): T`
+
+Creates a custom OpenTelemetry span. The span is automatically ended when the function returns. Supports async functions.
+
+```javascript
+monoscope.startSpan("checkout", (span) => {
+  span.setAttribute("cart.items", 3);
+  // ... your logic
+});
+```
+
+### `recordEvent(name: string, attributes?: Record<string, string | number | boolean>)`
+
+Records a custom event as a span with the given attributes.
+
+```javascript
+monoscope.recordEvent("button_click", {
+  "button.name": "subscribe",
+  "button.variant": "primary",
+});
+```
 
 ### `getSessionId(): string`
 
-Retrieves the current session ID — useful for tagging custom spans or events.
+Returns the current session ID.
+
+### `getTabId(): string`
+
+Returns the current tab ID (unique per browser tab).
+
+### `enable()` / `disable()`
+
+Dynamically enable or disable all data collection.
 
 ```javascript
-const sessionId = monoscope.getSessionId();
-console.log(sessionId);
+monoscope.disable(); // pause collection
+monoscope.enable();  // resume collection
 ```
 
+### `isEnabled(): boolean`
+
+Returns whether the SDK is currently enabled.
+
+### `destroy(): Promise<void>`
+
+Stops all collection, flushes pending data, and shuts down the OpenTelemetry provider. Call this when your application is being torn down.
+
+```javascript
+await monoscope.destroy();
+```
+
+---
+
+## React / Next.js
+
+For React apps, use the `@monoscopetech/browser/react` subpath export for idiomatic integration with hooks and context.
+
+```tsx
+import { MonoscopeProvider, useMonoscope, useMonoscopeUser, MonoscopeErrorBoundary } from "@monoscopetech/browser/react";
+
+// Wrap your app with MonoscopeProvider
+function App() {
+  return (
+    <MonoscopeProvider config={{ projectId: "YOUR_PROJECT_ID", serviceName: "my-react-app" }}>
+      <MonoscopeErrorBoundary fallback={<div>Something went wrong</div>}>
+        <MyApp />
+      </MonoscopeErrorBoundary>
+    </MonoscopeProvider>
+  );
+}
+
+// Access the instance via hook
+function MyApp() {
+  const monoscope = useMonoscope();
+
+  // Reactively set user when auth state changes
+  useMonoscopeUser(currentUser ? { id: currentUser.id, email: currentUser.email } : null);
+
+  return <div>...</div>;
+}
+```
+
+**Next.js App Router**: The provider includes `"use client"` — import it in a client component or your root layout.
+
+### React API
+
+| Export | Description |
+| --- | --- |
+| `MonoscopeProvider` | Context provider. Creates and destroys the SDK instance. Strict Mode safe. |
+| `useMonoscope()` | Returns the `Monoscope` instance (or `null` during SSR). |
+| `useMonoscopeUser(user)` | Calls `setUser` reactively when the user object changes. |
+| `MonoscopeErrorBoundary` | Error boundary that reports caught errors to Monoscope. Accepts `fallback` prop. |
+
+---
+
+## Custom Instrumentation
+
+### Custom Spans
+
+Use `startSpan()` to instrument specific operations with timing and attributes. It supports both sync and async functions — the span is automatically ended when the function returns or the promise resolves.
+
+```javascript
+// Sync
+monoscope.startSpan("parse-config", (span) => {
+  span.setAttribute("config.size", rawConfig.length);
+  return parseConfig(rawConfig);
+});
+
+// Async
+const data = await monoscope.startSpan("fetch-dashboard", async (span) => {
+  span.setAttribute("dashboard.id", dashboardId);
+  const res = await fetch(`/api/dashboards/${dashboardId}`);
+  span.setAttribute("http.status", res.status);
+  return res.json();
+});
+```
+
+### Custom Events
+
+Use `recordEvent()` to track discrete events without wrapping a code block:
+
+```javascript
+monoscope.recordEvent("feature_flag_evaluated", {
+  "flag.name": "new-checkout",
+  "flag.value": true,
+});
+```
+
+### React Components
+
+Use the `useMonoscope()` hook to instrument React components:
+
+```tsx
+import { useMonoscope } from "@monoscopetech/browser/react";
+
+function CheckoutButton() {
+  const monoscope = useMonoscope();
+
+  const handleClick = () => {
+    monoscope?.startSpan("checkout.submit", async (span) => {
+      span.setAttribute("cart.items", cartItems.length);
+      await submitOrder();
+    });
+  };
+
+  return <button onClick={handleClick}>Checkout</button>;
+}
+```
+
+### Additional OpenTelemetry Instrumentations
+
+Pass extra OTel instrumentations via the `instrumentations` config to extend tracing beyond the built-in set:
+
+```javascript
+import { LongTaskInstrumentation } from "@opentelemetry/instrumentation-long-task";
+
+const monoscope = new Monoscope({
+  projectId: "YOUR_PROJECT_ID",
+  serviceName: "my-app",
+  instrumentations: [new LongTaskInstrumentation()],
+});
+```
+
+---
+
+## Features
+
+### Session Replay
+Captures DOM changes via [rrweb](https://github.com/rrweb-io/rrweb) to enable full session replay. Sensitive inputs are masked by default.
+
+### Error Tracking
+Automatically captures `window.onerror`, unhandled promise rejections, and `console.error` calls with stack traces and breadcrumbs.
+
+### SPA Navigation Tracking
+Detects client-side navigations (`pushState`, `replaceState`, `popstate`) and emits navigation spans.
+
+### Web Vitals
+Collects Core Web Vitals (CLS, INP, LCP) and additional metrics (FCP, TTFB) via the [web-vitals](https://github.com/GoogleChrome/web-vitals) library.
+
+### Performance Observers
+Reports long tasks and slow resource loads as spans for performance debugging.
+
+### Session Management
+Sessions persist across page reloads via `sessionStorage` and automatically rotate after 30 minutes of inactivity.
+
 ---
 
 ## License

package/dist/breadcrumbs.d.ts

@@ -0,0 +1,9 @@
+export type Breadcrumb = {
+    type: "click" | "navigation" | "console.error" | "http" | "custom";
+    message: string;
+    timestamp: number;
+    data?: Record<string, string>;
+};
+export declare function addBreadcrumb(crumb: Omit<Breadcrumb, "timestamp">): void;
+export declare function getBreadcrumbs(): Breadcrumb[];
+export declare function clearBreadcrumbs(): void;

package/dist/breadcrumbs.js

@@ -0,0 +1,13 @@
+const MAX_BREADCRUMBS = 20;
+const buffer = [];
+export function addBreadcrumb(crumb) {
+    buffer.push({ ...crumb, timestamp: Date.now() });
+    if (buffer.length > MAX_BREADCRUMBS)
+        buffer.shift();
+}
+export function getBreadcrumbs() {
+    return buffer.slice();
+}
+export function clearBreadcrumbs() {
+    buffer.length = 0;
+}

package/dist/errors.d.ts

@@ -0,0 +1,17 @@
+import { Span } from "@opentelemetry/api";
+type EmitFn = (name: string, attrs: Record<string, string | number>, configure?: (span: Span) => void) => void;
+export declare class ErrorTracker {
+    private emit;
+    private errorCount;
+    private _active;
+    private prevOnError;
+    private onUnhandledRejection;
+    private origConsoleError;
+    private _processing;
+    constructor(emit: EmitFn);
+    private createErrorSpan;
+    start(): void;
+    stop(): void;
+    getErrorCount(): number;
+}
+export {};

package/dist/errors.js

@@ -0,0 +1,107 @@
+import { SpanStatusCode } from "@opentelemetry/api";
+import { addBreadcrumb, getBreadcrumbs } from "./breadcrumbs";
+function safeStringify(val) {
+    try {
+        return JSON.stringify(val);
+    }
+    catch {
+        return `[unserializable: ${typeof val}]`;
+    }
+}
+export class ErrorTracker {
+    constructor(emit) {
+        this.errorCount = 0;
+        this._active = false;
+        this.prevOnError = null;
+        this.onUnhandledRejection = null;
+        this.origConsoleError = null;
+        this._processing = false;
+        this.emit = emit;
+    }
+    createErrorSpan(spanName, errorType, attrs) {
+        this.errorCount++;
+        const crumbs = getBreadcrumbs();
+        this.emit(spanName, { "error.type": errorType, "error.count": this.errorCount, ...attrs }, (s) => {
+            s.setStatus({ code: SpanStatusCode.ERROR });
+            if (crumbs.length > 0)
+                s.setAttribute("breadcrumbs", safeStringify(crumbs));
+        });
+    }
+    start() {
+        if (typeof window === "undefined" || this._active)
+            return;
+        this._active = true;
+        this.prevOnError = window.onerror;
+        window.onerror = (event, source, lineno, colno, error) => {
+            const attrs = {
+                "error.message": typeof event === "string" ? event : event.type,
+            };
+            if (source)
+                attrs["error.source"] = source;
+            if (lineno !== undefined)
+                attrs["error.lineno"] = lineno;
+            if (colno !== undefined)
+                attrs["error.colno"] = colno;
+            if (error?.stack)
+                attrs["error.stack"] = error.stack;
+            if (error?.name)
+                attrs["error.name"] = error.name;
+            this.createErrorSpan("exception", "uncaught_exception", attrs);
+            if (typeof this.prevOnError === "function") {
+                return this.prevOnError.call(window, event, source, lineno, colno, error);
+            }
+        };
+        this.onUnhandledRejection = (event) => {
+            const reason = event.reason;
+            const attrs = {};
+            if (reason instanceof Error) {
+                attrs["error.message"] = reason.message;
+                attrs["error.name"] = reason.name;
+                if (reason.stack)
+                    attrs["error.stack"] = reason.stack;
+            }
+            else {
+                attrs["error.message"] = String(reason);
+            }
+            this.createErrorSpan("unhandled_rejection", "unhandled_rejection", attrs);
+        };
+        this.origConsoleError = console.error;
+        console.error = (...args) => {
+            this.origConsoleError?.apply(console, args);
+            if (this._processing)
+                return;
+            this._processing = true;
+            try {
+                const message = args.map((a) => a instanceof Error ? a.message : typeof a === "string" ? a : safeStringify(a)).join(" ");
+                const attrs = { "error.message": message };
+                const errorArg = args.find((a) => a instanceof Error);
+                if (errorArg) {
+                    attrs["error.name"] = errorArg.name;
+                    if (errorArg.stack)
+                        attrs["error.stack"] = errorArg.stack;
+                }
+                addBreadcrumb({ type: "console.error", message });
+                this.createErrorSpan("console.error", "console_error", attrs);
+            }
+            finally {
+                this._processing = false;
+            }
+        };
+        window.addEventListener("unhandledrejection", this.onUnhandledRejection);
+    }
+    stop() {
+        if (typeof window === "undefined" || !this._active)
+            return;
+        this._active = false;
+        window.onerror = this.prevOnError;
+        this.prevOnError = null;
+        if (this.onUnhandledRejection) {
+            window.removeEventListener("unhandledrejection", this.onUnhandledRejection);
+        }
+        if (this.origConsoleError) {
+            console.error = this.origConsoleError;
+            this.origConsoleError = null;
+        }
+    }
+    getErrorCount() { return this.errorCount; }
+}

package/dist/index.d.ts

@@ -1,13 +1,32 @@
 import { MonoscopeReplay } from "./replay";
 import { OpenTelemetryManager } from "./tracing";
 import { MonoscopeConfig, MonoscopeUser } from "./types";
+import type { Span } from "@opentelemetry/api";
 declare class Monoscope {
     replay: MonoscopeReplay;
-    config: MonoscopeConfig;
+    private config;
     otel: OpenTelemetryManager;
     sessionId: string;
+    tabId: string;
+    private lastActivityTime;
+    private errors;
+    private vitals;
+    private router;
+    private _enabled;
     constructor(config: MonoscopeConfig);
+    private resolveSessionId;
+    private persistActivity;
+    private rotateSession;
+    private checkAndRefreshSession;
+    private setupActivityTracking;
     getSessionId(): string;
+    getTabId(): string;
     setUser(u: MonoscopeUser): void;
+    startSpan<T>(name: string, fn: (span: Span) => T): T;
+    recordEvent(name: string, attributes?: Record<string, string | number | boolean>): void;
+    disable(): void;
+    enable(): void;
+    isEnabled(): boolean;
+    destroy(): Promise<void>;
 }
 export default Monoscope;

package/dist/index.js

@@ -1,30 +1,177 @@
 import { MonoscopeReplay } from "./replay";
 import { OpenTelemetryManager } from "./tracing";
-import { v4 as uuidv4 } from "uuid";
+import { ErrorTracker } from "./errors";
+import { WebVitalsCollector } from "./web-vitals";
+import { SPARouter } from "./router";
+import { addBreadcrumb, clearBreadcrumbs } from "./breadcrumbs";
+const SESSION_TIMEOUT_MS = 30 * 60 * 1000;
+const LAST_ACTIVITY_KEY = "monoscope-last-activity";
+const isBrowser = typeof window !== "undefined";
 class Monoscope {
     constructor(config) {
-        if (!config.projectId) {
+        if (!config.projectId)
             throw new Error("MonoscopeConfig must include projectId");
+        if (!config.serviceName)
+            throw new Error("MonoscopeConfig must include serviceName");
+        this.config = config;
+        this._enabled = config.enabled !== false;
+        this.tabId = crypto.randomUUID();
+        this.sessionId = isBrowser ? this.resolveSessionId() : crypto.randomUUID();
+        this.lastActivityTime = Date.now();
+        if (isBrowser)
+            this.persistActivity();
+        this.replay = new MonoscopeReplay(config, this.sessionId, this.tabId);
+        this.otel = new OpenTelemetryManager(config, this.sessionId, this.tabId);
+        const emit = (...args) => this.otel.emitSpan(...args);
+        this.errors = new ErrorTracker(emit);
+        this.vitals = new WebVitalsCollector(emit);
+        this.router = new SPARouter(emit);
+        if (this._enabled) {
+            this.otel.configure();
+            this.replay.configure();
+            this.errors.start();
+            this.vitals.start().catch((e) => {
+                if (this.config.debug)
+                    console.warn("Monoscope: web-vitals init failed", e);
+            });
+            this.router.start();
+        }
+        if (isBrowser)
+            this.setupActivityTracking();
+    }
+    resolveSessionId() {
+        try {
+            const storedId = sessionStorage.getItem("monoscope-session-id");
+            const lastActivity = sessionStorage.getItem(LAST_ACTIVITY_KEY);
+            if (storedId && lastActivity) {
+                const elapsed = Date.now() - parseInt(lastActivity, 10);
+                if (elapsed < SESSION_TIMEOUT_MS)
+                    return storedId;
+            }
+            const newId = crypto.randomUUID();
+            sessionStorage.setItem("monoscope-session-id", newId);
+            return newId;
+        }
+        catch (e) {
+            if (this.config.debug)
+                console.warn("Monoscope: sessionStorage unavailable, using ephemeral session", e);
+            return crypto.randomUUID();
+        }
+    }
+    persistActivity() {
+        try {
+            sessionStorage.setItem(LAST_ACTIVITY_KEY, Date.now().toString());
         }
-        const storedSessionId = sessionStorage.getItem("monoscope-session-id");
-        if (storedSessionId) {
-            this.sessionId = storedSessionId;
+        catch (e) {
+            if (this.config.debug)
+                console.warn("Monoscope: failed to persist activity", e);
         }
-        else {
-            this.sessionId = uuidv4();
+    }
+    rotateSession() {
+        this.replay.save().catch((e) => {
+            if (this.config.debug)
+                console.warn("Monoscope: failed to save replay on session rotation", e);
+        });
+        clearBreadcrumbs();
+        this.sessionId = crypto.randomUUID();
+        try {
             sessionStorage.setItem("monoscope-session-id", this.sessionId);
         }
-        this.config = config;
-        this.replay = new MonoscopeReplay(config, this.sessionId);
-        this.otel = new OpenTelemetryManager(config, this.sessionId);
-        this.otel.configure();
-        this.replay.configure();
+        catch (e) {
+            if (this.config.debug)
+                console.warn("Monoscope: failed to persist session ID", e);
+        }
+        this.replay.updateSessionId(this.sessionId);
+        this.otel.updateSessionId(this.sessionId);
+        if (this.config.debug)
+            console.log("Monoscope: session rotated due to inactivity");
     }
-    getSessionId() {
-        return this.sessionId;
+    checkAndRefreshSession() {
+        const now = Date.now();
+        if (now - this.lastActivityTime >= SESSION_TIMEOUT_MS) {
+            this.rotateSession();
+        }
+        this.lastActivityTime = now;
+        this.persistActivity();
     }
+    setupActivityTracking() {
+        document.addEventListener("visibilitychange", () => {
+            if (document.visibilityState === "visible") {
+                this.checkAndRefreshSession();
+            }
+        });
+        let lastTracked = Date.now();
+        const trackActivity = () => {
+            const now = Date.now();
+            if (now - lastTracked > 5000) {
+                lastTracked = now;
+                this.lastActivityTime = now;
+                this.persistActivity();
+            }
+        };
+        document.addEventListener("click", (e) => {
+            trackActivity();
+            const el = e.target;
+            if (!el)
+                return;
+            const tag = el.tagName?.toLowerCase() || "";
+            const text = (el.textContent || "").trim().slice(0, 50);
+            const cls = el.getAttribute("class") || "";
+            const selector = el.id ? `#${el.id}` : cls ? `.${cls.split(" ")[0]}` : tag;
+            addBreadcrumb({ type: "click", message: `${tag} "${text}"`, data: { selector } });
+        }, { capture: true, passive: true });
+        document.addEventListener("keydown", trackActivity, { capture: true, passive: true });
+    }
+    getSessionId() { return this.sessionId; }
+    getTabId() { return this.tabId; }
     setUser(u) {
+        if (this.config.debug) {
+            const known = new Set(["email", "full_name", "name", "id", "roles"]);
+            const extra = Object.keys(u).filter(k => !known.has(k));
+            if (extra.length)
+                console.warn(`Monoscope: unknown user attributes will be sent to collectors: ${extra.join(", ")}`);
+        }
         this.otel.setUser(u);
+        this.replay.setUser(u);
+    }
+    startSpan(name, fn) {
+        return this.otel.startSpan(name, fn);
+    }
+    recordEvent(name, attributes) {
+        this.otel.recordEvent(name, attributes);
+    }
+    disable() {
+        this._enabled = false;
+        this.replay.setEnabled(false);
+        this.otel.setEnabled(false);
+        this.vitals.setEnabled(false);
+        this.errors.stop();
+        this.router.stop();
+    }
+    enable() {
+        this._enabled = true;
+        this.otel.setEnabled(true);
+        this.otel.configure();
+        this.replay.setEnabled(true);
+        this.replay.configure();
+        this.vitals.setEnabled(true);
+        this.vitals.start().catch(() => { });
+        this.errors.start();
+        this.router.start();
+    }
+    isEnabled() { return this._enabled; }
+    async destroy() {
+        this.errors.stop();
+        this.router.stop();
+        this.replay.stop();
+        this.vitals.setEnabled(false);
+        try {
+            await this.otel.shutdown();
+        }
+        catch (e) {
+            console.warn("Monoscope: provider shutdown failed, some trace data may be lost", e);
+        }
+        this._enabled = false;
     }
 }
 export default Monoscope;