@monoscopetech/browser 0.7.1 → 0.8.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. |
@@ -71,6 +78,7 @@ The `Monoscope` constructor accepts the following options:
 | `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`. |
 
 ---
 
@@ -133,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.
@@ -166,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>
@@ -198,6 +215,75 @@ function MyApp() {
 
 ---
 
+## 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({
+  apiKey: "YOUR_API_KEY",
+  instrumentations: [new LongTaskInstrumentation()],
+});
+```
+
+---
+
 ## Features
 
 ### Session Replay

package/dist/index.d.ts

@@ -13,7 +13,9 @@ declare class Monoscope {
     private vitals;
     private router;
     private _enabled;
+    private overlay;
     constructor(config: MonoscopeConfig);
+    private logInitBanner;
     private resolveSessionId;
     private persistActivity;
     private rotateSession;
@@ -24,6 +26,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

@@ -4,15 +4,25 @@ 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();
@@ -36,9 +46,31 @@ 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);
+            }
+        }
         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");
@@ -135,10 +167,28 @@ class Monoscope {
         this.replay.setUser(u);
     }
     startSpan(name, fn) {
+        this.overlay?.incrementEvents();
         return this.otel.startSpan(name, fn);
     }
     recordEvent(name, attributes) {
         this.otel.recordEvent(name, attributes);
+        this.overlay?.incrementEvents();
+    }
+    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;