@monoscopetech/browser 0.7.2 → 0.9.0

package/README.md

@@ -2,7 +2,7 @@
 
 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.
+When used together with the [Monoscope Server SDKs](https://monoscope.tech/docs/sdks/), you gain **end-to-end observability** — seamlessly connecting user interactions in the browser to backend services, APIs, and databases.
 
 This means you can:
 
@@ -32,14 +32,13 @@ Or include it directly in your HTML using a `<script>` tag:
 
 ## Quick Start
 
-Initialize Monoscope with your **project ID** and configuration:
+Initialize Monoscope with your **API key** (found in your project settings):
 
 ```javascript
 import Monoscope from "@monoscopetech/browser";
 
 const monoscope = new Monoscope({
-  projectId: "YOUR_PROJECT_ID",
-  serviceName: "my-web-app",
+  apiKey: "YOUR_API_KEY",
 });
 
 // Identify the current user
@@ -49,6 +48,13 @@ monoscope.setUser({
 });
 ```
 
+On `localhost`, debug mode is auto-enabled — you'll see a status overlay and console diagnostics. Call `monoscope.test()` to verify your setup:
+
+```javascript
+const result = await monoscope.test();
+console.log(result); // { success: true, message: "Test span sent successfully." }
+```
+
 ---
 
 ## Configuration
@@ -57,8 +63,9 @@ 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. |
+| `apiKey` | `string` | **Required** – Your Monoscope API key (found in project settings). |
+| `serviceName` | `string` | Service name. Defaults to `location.hostname`. |
+| `projectId` | `string` | Deprecated alias for `apiKey`. |
 | `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. |
@@ -134,6 +141,15 @@ Returns the current session ID.
 
 Returns the current tab ID (unique per browser tab).
 
+### `test(): Promise<{success: boolean, message: string}>`
+
+Sends a test span and flushes it to verify the connection is working.
+
+```javascript
+const result = await monoscope.test();
+console.log(result.success); // true if the span was accepted
+```
+
 ### `enable()` / `disable()`
 
 Dynamically enable or disable all data collection.
@@ -167,7 +183,7 @@ import { MonoscopeProvider, useMonoscope, useMonoscopeUser, MonoscopeErrorBounda
 // Wrap your app with MonoscopeProvider
 function App() {
   return (
-    <MonoscopeProvider config={{ projectId: "YOUR_PROJECT_ID", serviceName: "my-react-app" }}>
+    <MonoscopeProvider config={{ apiKey: "YOUR_API_KEY" }}>
       <MonoscopeErrorBoundary fallback={<div>Something went wrong</div>}>
         <MyApp />
       </MonoscopeErrorBoundary>
@@ -261,8 +277,7 @@ Pass extra OTel instrumentations via the `instrumentations` config to extend tra
 import { LongTaskInstrumentation } from "@opentelemetry/instrumentation-long-task";
 
 const monoscope = new Monoscope({
-  projectId: "YOUR_PROJECT_ID",
-  serviceName: "my-app",
+  apiKey: "YOUR_API_KEY",
   instrumentations: [new LongTaskInstrumentation()],
 });
 ```

package/dist/errors.js

@@ -21,7 +21,15 @@ export class ErrorTracker {
     createErrorSpan(spanName, errorType, attrs) {
         this.errorCount++;
         const crumbs = getBreadcrumbs();
-        this.emit(spanName, { "error.type": errorType, "error.count": this.errorCount, ...attrs }, (s) => {
+        const name = String(attrs["error.name"] || errorType);
+        const msg = String(attrs["error.message"] || "").replace(/\s+/g, " ").slice(0, 80);
+        this.emit(spanName, {
+            "error.type": errorType,
+            "error.count": this.errorCount,
+            "monoscope.kind": "error",
+            "monoscope.display.label": msg ? `${name} · ${msg}` : name,
+            ...attrs,
+        }, (s) => {
             s.setStatus({ code: SpanStatusCode.ERROR });
             if (crumbs.length > 0)
                 s.setAttribute("breadcrumbs", safeStringify(crumbs));

package/dist/index.d.ts

@@ -13,8 +13,11 @@ declare class Monoscope {
     private vitals;
     private router;
     private _enabled;
+    private overlay;
     constructor(config: MonoscopeConfig);
+    private logInitBanner;
     private resolveSessionId;
+    private resolveTabId;
     private persistActivity;
     private rotateSession;
     private checkAndRefreshSession;
@@ -24,6 +27,10 @@ declare class Monoscope {
     setUser(u: MonoscopeUser): void;
     startSpan<T>(name: string, fn: (span: Span) => T): T;
     recordEvent(name: string, attributes?: Record<string, string | number | boolean>): void;
+    test(): Promise<{
+        success: boolean;
+        message: string;
+    }>;
     disable(): void;
     enable(): void;
     isEnabled(): boolean;

package/dist/index.js

@@ -1,22 +1,32 @@
 import { MonoscopeReplay } from "./replay";
-import { OpenTelemetryManager } from "./tracing";
+import { OpenTelemetryManager, newId } from "./tracing";
 import { ErrorTracker } from "./errors";
 import { WebVitalsCollector } from "./web-vitals";
 import { SPARouter } from "./router";
 import { addBreadcrumb, clearBreadcrumbs } from "./breadcrumbs";
+import { DevOverlay } from "./overlay";
 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)
-            throw new Error("MonoscopeConfig must include projectId");
+        this.overlay = null;
+        const resolvedKey = config.apiKey || config.projectId;
+        if (!resolvedKey)
+            throw new Error("MonoscopeConfig must include apiKey (or projectId)");
+        if (config.projectId && !config.apiKey && config.debug) {
+            console.warn("[Monoscope] `projectId` is deprecated. Use `apiKey` instead.");
+        }
+        config = { ...config, apiKey: resolvedKey, projectId: resolvedKey };
+        const isLocalhost = isBrowser && (location.hostname === "localhost" || location.hostname === "127.0.0.1");
+        if (config.debug === undefined && isLocalhost)
+            config = { ...config, debug: true };
         if (!config.serviceName)
-            throw new Error("MonoscopeConfig must include serviceName");
+            config = { ...config, serviceName: isBrowser ? location.hostname : "unknown" };
         this.config = config;
         this._enabled = config.enabled !== false;
-        this.tabId = crypto.randomUUID();
-        this.sessionId = isBrowser ? this.resolveSessionId() : crypto.randomUUID();
+        this.tabId = isBrowser ? this.resolveTabId() : newId();
+        this.sessionId = isBrowser ? this.resolveSessionId() : newId();
         this.lastActivityTime = Date.now();
         if (isBrowser)
             this.persistActivity();
@@ -25,7 +35,7 @@ class Monoscope {
         const emit = (...args) => this.otel.emitSpan(...args);
         this.errors = new ErrorTracker(emit);
         this.vitals = new WebVitalsCollector(emit);
-        this.router = new SPARouter(emit);
+        this.router = new SPARouter((from, to, method) => this.otel.startRouteChange(from, to, method));
         if (this._enabled) {
             this.otel.configure();
             this.replay.configure();
@@ -36,9 +46,32 @@ class Monoscope {
             });
             this.router.start();
         }
+        if (this._enabled && this.config.debug) {
+            this.logInitBanner();
+            if (isBrowser) {
+                this.overlay = new DevOverlay();
+                this.otel.onExportStatus = (ok) => this.overlay?.setConnectionStatus(ok);
+                this.otel.onSpanStart = () => this.overlay?.incrementEvents();
+            }
+        }
         if (isBrowser)
             this.setupActivityTracking();
     }
+    logInitBanner() {
+        const c = this.config;
+        const endpoint = c.exporterEndpoint || "https://otelcol.monoscope.tech/v1/traces";
+        const samplePct = Math.round((c.sampleRate ?? 1) * 100);
+        const replayPct = Math.round((c.replaySampleRate ?? 1) * 100);
+        console.groupCollapsed("%c[Monoscope] ✓ Initialized", "color: #22c55e; font-weight: bold");
+        console.log(`  API Key:   ${c.apiKey}`);
+        console.log(`  Service:   ${c.serviceName}`);
+        console.log(`  Session:   ${this.sessionId}`);
+        console.log(`  Tracing:   ✓ (sample rate: ${samplePct}%)`);
+        console.log(`  Replay:    ✓ (sample rate: ${replayPct}%)`);
+        console.log(`  Errors:    ✓`);
+        console.log(`  Endpoint:  ${endpoint}`);
+        console.groupEnd();
+    }
     resolveSessionId() {
         try {
             const storedId = sessionStorage.getItem("monoscope-session-id");
@@ -48,14 +81,29 @@ class Monoscope {
                 if (elapsed < SESSION_TIMEOUT_MS)
                     return storedId;
             }
-            const newId = crypto.randomUUID();
-            sessionStorage.setItem("monoscope-session-id", newId);
-            return newId;
+            const id = newId();
+            sessionStorage.setItem("monoscope-session-id", id);
+            return id;
         }
         catch (e) {
             if (this.config.debug)
                 console.warn("Monoscope: sessionStorage unavailable, using ephemeral session", e);
-            return crypto.randomUUID();
+            return newId();
+        }
+    }
+    // sessionStorage is tab-scoped, so a persisted id naturally identifies a
+    // single tab across MPA navigations and SPA reloads.
+    resolveTabId() {
+        try {
+            const existing = sessionStorage.getItem("monoscope-tab-id");
+            if (existing)
+                return existing;
+            const id = newId();
+            sessionStorage.setItem("monoscope-tab-id", id);
+            return id;
+        }
+        catch {
+            return newId();
         }
     }
     persistActivity() {
@@ -73,7 +121,7 @@ class Monoscope {
                 console.warn("Monoscope: failed to save replay on session rotation", e);
         });
         clearBreadcrumbs();
-        this.sessionId = crypto.randomUUID();
+        this.sessionId = newId();
         try {
             sessionStorage.setItem("monoscope-session-id", this.sessionId);
         }
@@ -140,6 +188,22 @@ class Monoscope {
     recordEvent(name, attributes) {
         this.otel.recordEvent(name, attributes);
     }
+    async test() {
+        try {
+            this.otel.emitSpan("monoscope.test", { "test.timestamp": Date.now() });
+            await this.otel.forceFlush();
+            const msg = "Test span sent successfully.";
+            if (this.config.debug)
+                console.log(`[Monoscope] ${msg}`);
+            return { success: true, message: msg };
+        }
+        catch (e) {
+            const msg = `Test failed: ${e}`;
+            if (this.config.debug)
+                console.error(`[Monoscope] ${msg}`);
+            return { success: false, message: msg };
+        }
+    }
     disable() {
         this._enabled = false;
         this.replay.setEnabled(false);