@sentienguard/apm 1.0.3 → 1.0.4

package/package.json

@@ -1,54 +1,54 @@
-{
-  "name": "@sentienguard/apm",
-  "version": "1.0.3",
-  "description": "SentienGuard APM SDK - Minimal, production-safe application performance monitoring",
-  "main": "src/index.js",
-  "type": "module",
-  "browser": "./src/browser.js",
-  "exports": {
-    ".": {
-      "browser": "./src/browser.js",
-      "default": "./src/index.js"
-    }
-  },
-  "scripts": {
-    "test": "node --experimental-vm-modules node_modules/jest/bin/jest.js",
-    "test:load": "node tests/load.test.js"
-  },
-  "keywords": [
-    "apm",
-    "monitoring",
-    "performance",
-    "metrics",
-    "sentienguard",
-    "mongodb",
-    "circuit-breaker",
-    "observability"
-  ],
-  "author": "SentienGuard",
-  "license": "MIT",
-  "publishConfig": {
-    "access": "public"
-  },
-  "engines": {
-    "node": ">=16.0.0"
-  },
-  "peerDependencies": {
-    "mongoose": ">=6.0.0",
-    "opossum": ">=8.0.0"
-  },
-  "peerDependenciesMeta": {
-    "mongoose": {
-      "optional": true
-    },
-    "opossum": {
-      "optional": true
-    }
-  },
-  "devDependencies": {
-    "jest": "^29.7.0"
-  },
-  "files": [
-    "src/**/*"
-  ]
-}
+{
+  "name": "@sentienguard/apm",
+  "version": "1.0.4",
+  "description": "SentienGuard APM SDK - Minimal, production-safe application performance monitoring",
+  "main": "src/index.js",
+  "type": "module",
+  "browser": "./src/browser.js",
+  "exports": {
+    ".": {
+      "browser": "./src/browser.js",
+      "default": "./src/index.js"
+    }
+  },
+  "scripts": {
+    "test": "node --experimental-vm-modules node_modules/jest/bin/jest.js",
+    "test:load": "node tests/load.test.js"
+  },
+  "keywords": [
+    "apm",
+    "monitoring",
+    "performance",
+    "metrics",
+    "sentienguard",
+    "mongodb",
+    "circuit-breaker",
+    "observability"
+  ],
+  "author": "SentienGuard",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=16.0.0"
+  },
+  "peerDependencies": {
+    "mongoose": ">=6.0.0",
+    "opossum": ">=8.0.0"
+  },
+  "peerDependenciesMeta": {
+    "mongoose": {
+      "optional": true
+    },
+    "opossum": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "jest": "^29.7.0"
+  },
+  "files": [
+    "src/**/*"
+  ]
+}

package/src/browser/aggregator.js

@@ -0,0 +1,187 @@
+/**
+ * Browser Metrics Aggregator
+ *
+ * Batches browser-specific metrics in memory and flushes them periodically.
+ * Produces payloads compatible with the backend's ingestApmData controller.
+ *
+ * Mirrors the Node.js aggregator pattern but tracks browser-relevant metrics:
+ * - Outgoing fetch/XHR requests (as dependencies)
+ * - Page load timing (Navigation Timing API)
+ * - Web Vitals (LCP, FID, INP, CLS)
+ * - Unhandled JS errors
+ * - SPA route changes
+ */
+
+import config from './config.js';
+
+/**
+ * Create an aggregation key for dependency metrics
+ */
+function createDependencyKey(name, type) {
+  return `${name}:${type}`;
+}
+
+export class BrowserMetricsAggregator {
+  constructor() {
+    this.maxRoutes = config.maxRoutes || 100;
+    this.reset();
+  }
+
+  reset() {
+    // Outgoing HTTP requests (fetch/XHR) aggregated by host
+    // Same shape as Node SDK dependencies: { name, type, count, errorCount, latency }
+    this.dependencies = new Map();
+
+    // Page load timing entries from Navigation Timing API
+    this.pageLoads = [];
+
+    // Web Vitals - latest values per metric name
+    this.webVitals = {};
+
+    // Unhandled JS error count
+    this.jsErrors = 0;
+
+    // SPA route change events
+    this.routeChanges = [];
+  }
+
+  /**
+   * Record an outgoing HTTP request (fetch/XHR)
+   * Uses the same dependency shape as the Node.js SDK so the backend
+   * can process it identically.
+   *
+   * @param {string} name - Service/host name
+   * @param {string} type - Dependency type (http)
+   * @param {number} latency - Response time in ms
+   * @param {boolean} isError - Whether the request failed
+   */
+  recordDependency(name, type, latency, isError = false) {
+    const key = createDependencyKey(name, type);
+
+    let metric = this.dependencies.get(key);
+    if (!metric) {
+      if (this.dependencies.size >= this.maxRoutes) return;
+      metric = {
+        name,
+        type,
+        count: 0,
+        errorCount: 0,
+        latency: { sum: 0, min: Infinity, max: 0 }
+      };
+      this.dependencies.set(key, metric);
+    }
+
+    metric.count++;
+    if (isError) metric.errorCount++;
+    metric.latency.sum += latency;
+    metric.latency.min = Math.min(metric.latency.min, latency);
+    metric.latency.max = Math.max(metric.latency.max, latency);
+  }
+
+  /**
+   * Record an unhandled JS error
+   */
+  recordError() {
+    this.jsErrors++;
+  }
+
+  /**
+   * Record page load timing from Navigation Timing API
+   * @param {Object} timing
+   */
+  recordPageLoad(timing) {
+    this.pageLoads.push(timing);
+  }
+
+  /**
+   * Record a Web Vital metric value
+   * @param {string} name - Metric name (lcp, fid, inp, cls)
+   * @param {number} value - Metric value
+   */
+  recordWebVital(name, value) {
+    this.webVitals[name] = value;
+  }
+
+  /**
+   * Record a SPA route change
+   * @param {string} from - Previous route path
+   * @param {string} to - New route path
+   */
+  recordRouteChange(from, to) {
+    if (this.routeChanges.length >= 100) return;
+    this.routeChanges.push({ from, to, timestamp: Date.now() });
+  }
+
+  hasData() {
+    return this.dependencies.size > 0 ||
+      this.pageLoads.length > 0 ||
+      Object.keys(this.webVitals).length > 0 ||
+      this.jsErrors > 0 ||
+      this.routeChanges.length > 0;
+  }
+
+  /**
+   * Flush aggregated metrics and return payload for the backend.
+   * Payload format matches the backend's ingestApmData expectations:
+   *   { interval, service, environment, requests[], dependencies[], browser{} }
+   */
+  flush() {
+    const dependencies = [];
+    for (const metric of this.dependencies.values()) {
+      dependencies.push({
+        name: metric.name,
+        type: metric.type,
+        count: metric.count,
+        errorCount: metric.errorCount,
+        latency: {
+          sum: Math.round(metric.latency.sum),
+          min: metric.latency.min === Infinity ? 0 : Math.round(metric.latency.min),
+          max: Math.round(metric.latency.max)
+        }
+      });
+    }
+
+    const payload = {
+      interval: `${config.flushInterval}s`,
+      service: config.service,
+      environment: config.environment,
+      // requests[] left empty - browser doesn't serve HTTP requests
+      requests: [],
+      dependencies,
+      // Browser-specific metrics in a dedicated field.
+      // The backend safely ignores unknown fields for now;
+      // a future backend update can process these.
+      browser: {
+        pageLoads: [...this.pageLoads],
+        webVitals: { ...this.webVitals },
+        jsErrors: this.jsErrors,
+        routeChanges: [...this.routeChanges]
+      }
+    };
+
+    this.reset();
+    return payload;
+  }
+
+  getStats() {
+    return {
+      dependencyMetrics: this.dependencies.size,
+      pageLoads: this.pageLoads.length,
+      webVitals: Object.keys(this.webVitals).length,
+      jsErrors: this.jsErrors,
+      routeChanges: this.routeChanges.length
+    };
+  }
+}
+
+// Singleton
+let instance = null;
+
+export function getAggregator() {
+  if (!instance) {
+    instance = new BrowserMetricsAggregator();
+  }
+  return instance;
+}
+
+export default { BrowserMetricsAggregator, getAggregator };

package/src/browser/config.js

@@ -0,0 +1,67 @@
+/**
+ * SentienGuard APM SDK - Browser Configuration
+ *
+ * Unlike the Node.js SDK which reads process.env, the browser SDK
+ * requires explicit configuration via the init() call.
+ */
+
+const config = {
+  apiKey: '',
+  service: '',
+  environment: 'production',
+  endpoint: 'https://sentienguard-dev.the-algo.com/api/v1/apm/ingest',
+  flushInterval: 10,
+  maxRoutes: 100,
+  maxPayloadSize: 512 * 1024, // 512KB (smaller than Node SDK; sendBeacon has ~64KB limit)
+  enabled: true,
+  debug: false
+};
+
+/**
+ * Apply user-provided options to config
+ * @param {Object} options
+ * @param {string} options.apiKey - APM application key (required)
+ * @param {string} options.service - Service/app name (required)
+ * @param {string} [options.endpoint] - Backend ingest URL
+ * @param {string} [options.environment] - Environment name
+ * @param {number} [options.flushInterval] - Flush interval in seconds
+ * @param {boolean} [options.debug] - Enable debug logging
+ */
+export function configure(options) {
+  if (!options || typeof options !== 'object') {
+    warn('init() requires a config object');
+    return;
+  }
+
+  if (options.apiKey) config.apiKey = String(options.apiKey);
+  if (options.service) config.service = String(options.service);
+  if (options.endpoint) config.endpoint = String(options.endpoint);
+  if (options.environment) config.environment = String(options.environment);
+  if (typeof options.flushInterval === 'number' && options.flushInterval > 0) {
+    config.flushInterval = options.flushInterval;
+  }
+  if (typeof options.maxRoutes === 'number') config.maxRoutes = options.maxRoutes;
+  if (typeof options.maxPayloadSize === 'number') config.maxPayloadSize = options.maxPayloadSize;
+  if (options.enabled === false) config.enabled = false;
+  if (typeof options.debug === 'boolean') config.debug = options.debug;
+}
+
+export function isEnabled() {
+  return config.enabled && !!config.apiKey && !!config.service;
+}
+
+export function getConfig() {
+  return { ...config };
+}
+
+export function debug(...args) {
+  if (config.debug) {
+    console.log('[SentienGuard APM]', ...args);
+  }
+}
+
+export function warn(...args) {
+  console.warn('[SentienGuard APM]', ...args);
+}
+
+export default config;

package/src/browser/errors.js

@@ -0,0 +1,56 @@
+/**
+ * Browser Error Capture
+ *
+ * Captures unhandled JavaScript errors and promise rejections.
+ * Records error counts in the aggregator (same pattern as Node.js SDK).
+ *
+ * Uses window.addEventListener('error') and window.addEventListener('unhandledrejection')
+ * which are the standard browser equivalents of Node.js process.on('uncaughtException')
+ * and process.on('unhandledRejection').
+ */
+
+import { getAggregator } from './aggregator.js';
+import { debug } from './config.js';
+
+let isCapturing = false;
+
+function handleError(event) {
+  debug('Captured error:', event.message || event.error?.message || 'unknown');
+  getAggregator().recordError();
+}
+
+function handleRejection(event) {
+  const reason = event.reason;
+  const message = reason instanceof Error ? reason.message : String(reason);
+  debug('Captured unhandled rejection:', message);
+  getAggregator().recordError();
+}
+
+/**
+ * Start capturing unhandled errors and promise rejections
+ */
+export function startErrorCapture() {
+  if (isCapturing) return;
+  if (typeof window === 'undefined') return;
+
+  window.addEventListener('error', handleError);
+  window.addEventListener('unhandledrejection', handleRejection);
+
+  isCapturing = true;
+  debug('Error capture enabled');
+}
+
+/**
+ * Stop capturing errors
+ */
+export function stopErrorCapture() {
+  if (!isCapturing) return;
+
+  window.removeEventListener('error', handleError);
+  window.removeEventListener('unhandledrejection', handleRejection);
+
+  isCapturing = false;
+  debug('Error capture disabled');
+}
+
+export default { startErrorCapture, stopErrorCapture };

package/src/browser/instrumentation.js

@@ -0,0 +1,164 @@
+/**
+ * Browser Network Instrumentation
+ *
+ * Monkey-patches window.fetch and XMLHttpRequest to track outgoing HTTP requests.
+ * This is the industry-standard approach used by Datadog, Sentry, New Relic, and Elastic APM.
+ *
+ * Captured data is recorded as dependencies (same shape as Node.js SDK)
+ * so the backend processes them identically.
+ */
+
+import { getAggregator } from './aggregator.js';
+import config, { debug } from './config.js';
+
+let originalFetch = null;
+let originalXhrOpen = null;
+let originalXhrSend = null;
+let isInstrumented = false;
+
+/**
+ * Check if a URL should be excluded from tracking.
+ * Excludes the APM endpoint itself to prevent infinite metric loops.
+ */
+function shouldExclude(url) {
+  if (!url || !config.endpoint) return false;
+  try {
+    const targetUrl = new URL(url, window.location.origin);
+    const endpointUrl = new URL(config.endpoint);
+    return targetUrl.origin === endpointUrl.origin &&
+           targetUrl.pathname === endpointUrl.pathname;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Extract a service name from a URL.
+ * For same-origin requests, returns 'self'.
+ * For cross-origin, returns the hostname.
+ */
+function getServiceName(url) {
+  try {
+    const parsed = new URL(url, window.location.origin);
+    if (parsed.origin === window.location.origin) return 'self';
+    return parsed.hostname;
+  } catch {
+    return 'unknown';
+  }
+}
+
+/**
+ * Instrument window.fetch
+ */
+function instrumentFetch() {
+  if (typeof window === 'undefined' || typeof window.fetch !== 'function') return;
+
+  originalFetch = window.fetch;
+
+  window.fetch = function (input, init) {
+    const url = typeof input === 'string'
+      ? input
+      : (input instanceof Request ? input.url : String(input));
+
+    if (shouldExclude(url)) {
+      return originalFetch.apply(this, arguments);
+    }
+
+    const method = (init?.method || (input instanceof Request ? input.method : 'GET')).toUpperCase();
+    const startTime = performance.now();
+    const serviceName = getServiceName(url);
+
+    return originalFetch.apply(this, arguments).then(
+      (response) => {
+        const latency = performance.now() - startTime;
+        const isError = !response.ok;
+
+        getAggregator().recordDependency(serviceName, 'http', latency, isError);
+        debug(`Fetch: ${method} ${serviceName} ${response.status} ${latency.toFixed(1)}ms`);
+
+        return response;
+      },
+      (error) => {
+        const latency = performance.now() - startTime;
+
+        getAggregator().recordDependency(serviceName, 'http', latency, true);
+        debug(`Fetch error: ${method} ${serviceName} ${latency.toFixed(1)}ms`);
+
+        throw error;
+      }
+    );
+  };
+}
+
+/**
+ * Instrument XMLHttpRequest
+ */
+function instrumentXHR() {
+  if (typeof XMLHttpRequest === 'undefined') return;
+
+  originalXhrOpen = XMLHttpRequest.prototype.open;
+  originalXhrSend = XMLHttpRequest.prototype.send;
+
+  XMLHttpRequest.prototype.open = function (method, url, ...rest) {
+    this._sgMethod = (method || 'GET').toUpperCase();
+    this._sgUrl = String(url);
+    return originalXhrOpen.apply(this, [method, url, ...rest]);
+  };
+
+  XMLHttpRequest.prototype.send = function (body) {
+    if (!this._sgUrl || shouldExclude(this._sgUrl)) {
+      return originalXhrSend.apply(this, arguments);
+    }
+
+    const startTime = performance.now();
+    const url = this._sgUrl;
+    const method = this._sgMethod;
+    const serviceName = getServiceName(url);
+
+    this.addEventListener('loadend', function () {
+      const latency = performance.now() - startTime;
+      const isError = this.status === 0 || this.status >= 400;
+
+      getAggregator().recordDependency(serviceName, 'http', latency, isError);
+      debug(`XHR: ${method} ${serviceName} ${this.status} ${latency.toFixed(1)}ms`);
+    });
+
+    return originalXhrSend.apply(this, arguments);
+  };
+}
+
+/**
+ * Start network instrumentation (fetch + XHR)
+ */
+export function instrumentNetwork() {
+  if (isInstrumented) return;
+  instrumentFetch();
+  instrumentXHR();
+  isInstrumented = true;
+  debug('Network instrumentation enabled');
+}
+
+/**
+ * Remove network instrumentation (for cleanup/testing)
+ */
+export function uninstrumentNetwork() {
+  if (!isInstrumented) return;
+
+  if (originalFetch) {
+    window.fetch = originalFetch;
+    originalFetch = null;
+  }
+  if (originalXhrOpen) {
+    XMLHttpRequest.prototype.open = originalXhrOpen;
+    originalXhrOpen = null;
+  }
+  if (originalXhrSend) {
+    XMLHttpRequest.prototype.send = originalXhrSend;
+    originalXhrSend = null;
+  }
+
+  isInstrumented = false;
+  debug('Network instrumentation disabled');
+}
+
+export default { instrumentNetwork, uninstrumentNetwork };

package/src/browser/router.js

@@ -0,0 +1,86 @@
+/**
+ * SPA Route Change Detection
+ *
+ * Tracks client-side navigation in Single Page Applications by
+ * intercepting History API methods and listening for popstate events.
+ *
+ * This is the standard approach used by all major APM SDKs:
+ * - Monkey-patches history.pushState and history.replaceState
+ * - Listens for popstate (browser back/forward navigation)
+ *
+ * Recorded route changes are flushed with the aggregated payload.
+ */
+
+import { getAggregator } from './aggregator.js';
+import { debug } from './config.js';
+
+let originalPushState = null;
+let originalReplaceState = null;
+let currentRoute = null;
+let isTracking = false;
+
+function handleRouteChange() {
+  const newRoute = window.location.pathname;
+  if (newRoute === currentRoute) return;
+
+  const previousRoute = currentRoute;
+  currentRoute = newRoute;
+
+  getAggregator().recordRouteChange(previousRoute, newRoute);
+  debug(`Route change: ${previousRoute} -> ${newRoute}`);
+}
+
+/**
+ * Start tracking SPA route changes
+ */
+export function startRouteTracking() {
+  if (isTracking) return;
+  if (typeof window === 'undefined' || typeof history === 'undefined') return;
+
+  currentRoute = window.location.pathname;
+
+  // Monkey-patch history.pushState
+  originalPushState = history.pushState;
+  history.pushState = function (...args) {
+    const result = originalPushState.apply(this, args);
+    handleRouteChange();
+    return result;
+  };
+
+  // Monkey-patch history.replaceState
+  originalReplaceState = history.replaceState;
+  history.replaceState = function (...args) {
+    const result = originalReplaceState.apply(this, args);
+    handleRouteChange();
+    return result;
+  };
+
+  // Listen for browser back/forward navigation
+  window.addEventListener('popstate', handleRouteChange);
+
+  isTracking = true;
+  debug('Route tracking enabled');
+}
+
+/**
+ * Stop tracking route changes and restore original History methods
+ */
+export function stopRouteTracking() {
+  if (!isTracking) return;
+
+  if (originalPushState) {
+    history.pushState = originalPushState;
+    originalPushState = null;
+  }
+  if (originalReplaceState) {
+    history.replaceState = originalReplaceState;
+    originalReplaceState = null;
+  }
+
+  window.removeEventListener('popstate', handleRouteChange);
+
+  isTracking = false;
+  debug('Route tracking disabled');
+}
+
+export default { startRouteTracking, stopRouteTracking };

package/src/browser/transport.js

@@ -0,0 +1,152 @@
+/**
+ * Browser Transport Layer
+ *
+ * Handles periodic flush of aggregated metrics to the backend.
+ * Uses fetch() for normal sends (supports custom headers) and
+ * navigator.sendBeacon() for page unload (more reliable but no custom headers).
+ *
+ * Transport strategy (matches Datadog RUM pattern):
+ * - Normal flush: fetch() with X-APM-Key header
+ * - Unload flush: sendBeacon() with ?apmKey= query param
+ * - Listens on visibilitychange (NOT beforeunload/unload which are unreliable on mobile)
+ */
+
+import { getAggregator } from './aggregator.js';
+import config, { debug, warn, isEnabled } from './config.js';
+
+let flushTimer = null;
+let isRunning = false;
+let consecutiveFailures = 0;
+
+const MAX_CONSECUTIVE_FAILURES = 5;
+
+/**
+ * Send payload to backend using fetch (supports custom headers)
+ */
+async function sendToBackend(payload) {
+  const data = JSON.stringify(payload);
+
+  if (data.length > config.maxPayloadSize) {
+    warn(`Payload too large (${data.length} bytes), dropping`);
+    return;
+  }
+
+  const response = await fetch(config.endpoint, {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+      'X-APM-Key': config.apiKey
+    },
+    body: data,
+    keepalive: true
+  });
+
+  if (!response.ok) {
+    throw new Error(`HTTP ${response.status}`);
+  }
+}
+
+/**
+ * Send payload using navigator.sendBeacon (for page unload).
+ * sendBeacon cannot set custom headers, so the API key is passed
+ * as a query parameter — same pattern as Datadog's clientToken.
+ */
+function sendBeacon(payload) {
+  const data = JSON.stringify(payload);
+
+  if (typeof navigator !== 'undefined' && navigator.sendBeacon) {
+    const url = `${config.endpoint}?apmKey=${encodeURIComponent(config.apiKey)}`;
+    const blob = new Blob([data], { type: 'application/json' });
+    return navigator.sendBeacon(url, blob);
+  }
+
+  // Fallback: fetch with keepalive (survives page unload in modern browsers)
+  try {
+    fetch(config.endpoint, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        'X-APM-Key': config.apiKey
+      },
+      body: data,
+      keepalive: true
+    });
+  } catch {
+    // Best effort - data loss is acceptable on unload
+  }
+}
+
+/**
+ * Perform a flush of aggregated metrics
+ */
+export async function flush() {
+  if (!isEnabled()) return;
+
+  const aggregator = getAggregator();
+  if (!aggregator.hasData()) return;
+
+  const payload = aggregator.flush();
+  debug(`Flushing ${payload.dependencies.length} dependency metrics`);
+
+  try {
+    const startTime = performance.now();
+    await sendToBackend(payload);
+    const duration = Math.round(performance.now() - startTime);
+
+    debug(`Flush successful in ${duration}ms`);
+    consecutiveFailures = 0;
+  } catch (error) {
+    consecutiveFailures++;
+    warn(`Flush failed (attempt ${consecutiveFailures}): ${error.message}`);
+
+    if (consecutiveFailures >= MAX_CONSECUTIVE_FAILURES) {
+      warn('Max consecutive failures reached, data will be dropped until backend recovers');
+    }
+  }
+}
+
+/**
+ * Start the periodic flush timer
+ */
+export function startFlushing() {
+  if (isRunning || !isEnabled()) return;
+
+  const intervalMs = config.flushInterval * 1000;
+  flushTimer = setInterval(flush, intervalMs);
+  isRunning = true;
+  debug(`Flush timer started (every ${config.flushInterval}s)`);
+}
+
+/**
+ * Stop the periodic flush timer
+ */
+export function stopFlushing() {
+  if (!isRunning) return;
+  if (flushTimer) {
+    clearInterval(flushTimer);
+    flushTimer = null;
+  }
+  isRunning = false;
+  debug('Flush timer stopped');
+}
+
+/**
+ * Setup page unload flush using visibilitychange event.
+ * visibilitychange is more reliable than beforeunload/unload on mobile.
+ */
+export function setupUnloadFlush() {
+  if (typeof document === 'undefined') return;
+
+  document.addEventListener('visibilitychange', () => {
+    if (document.visibilityState === 'hidden') {
+      const aggregator = getAggregator();
+      if (aggregator.hasData()) {
+        const payload = aggregator.flush();
+        sendBeacon(payload);
+        debug('Unload flush sent via sendBeacon');
+      }
+    }
+  });
+}
+
+export default { startFlushing, stopFlushing, flush, setupUnloadFlush };

package/src/browser/vitals.js

@@ -0,0 +1,202 @@
+/**
+ * Web Vitals Collection
+ *
+ * Captures Core Web Vitals and page load timing using browser-native APIs.
+ * Vendors the approach from Google's web-vitals library:
+ * - Uses PerformanceObserver with { buffered: true } to capture entries from before SDK init
+ * - Finalizes metrics on visibilitychange (metric values may update until page is hidden)
+ * - Handles INP calculation across multiple interactions
+ *
+ * Captured metrics:
+ * - LCP (Largest Contentful Paint) - loading performance
+ * - FID (First Input Delay) - interactivity (legacy, being replaced by INP)
+ * - INP (Interaction to Next Paint) - responsiveness
+ * - CLS (Cumulative Layout Shift) - visual stability
+ * - Navigation Timing - DNS, TCP, TTFB, DOM ready, page load
+ */
+
+import { getAggregator } from './aggregator.js';
+import { debug } from './config.js';
+
+let observers = [];
+
+/**
+ * Safely create a PerformanceObserver for a given entry type.
+ * Returns null if the browser doesn't support the entry type.
+ */
+function createObserver(type, callback) {
+  try {
+    // Check if the entry type is supported
+    if (typeof PerformanceObserver === 'undefined') return null;
+    if (!PerformanceObserver.supportedEntryTypes?.includes(type)) return null;
+
+    const observer = new PerformanceObserver(callback);
+    observer.observe({ type, buffered: true });
+    observers.push(observer);
+    return observer;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Capture Largest Contentful Paint (LCP)
+ * LCP values may update as new larger elements paint; the last entry is the final LCP.
+ * The metric is finalized when the page becomes hidden.
+ */
+function captureLCP() {
+  let lastValue = 0;
+
+  createObserver('largest-contentful-paint', (list) => {
+    const entries = list.getEntries();
+    const lastEntry = entries[entries.length - 1];
+    if (lastEntry) {
+      lastValue = lastEntry.startTime;
+      getAggregator().recordWebVital('lcp', Math.round(lastValue));
+      debug(`LCP: ${lastValue.toFixed(1)}ms`);
+    }
+  });
+}
+
+/**
+ * Capture First Input Delay (FID)
+ * Only the first input event counts. One-shot metric.
+ */
+function captureFID() {
+  createObserver('first-input', (list) => {
+    const entry = list.getEntries()[0];
+    if (entry) {
+      const value = entry.processingStart - entry.startTime;
+      getAggregator().recordWebVital('fid', Math.round(value));
+      debug(`FID: ${value.toFixed(1)}ms`);
+    }
+  });
+}
+
+/**
+ * Capture Interaction to Next Paint (INP)
+ * INP is the worst interaction latency (at the 98th percentile if >=50 interactions).
+ * We track all interactions and report the highest as a conservative estimate.
+ */
+function captureINP() {
+  const interactions = [];
+
+  createObserver('event', (list) => {
+    for (const entry of list.getEntries()) {
+      // Only count discrete interactions (click, keypress, etc.)
+      // Ignore events with 0 duration (non-interactive)
+      if (entry.duration > 0 && entry.interactionId) {
+        interactions.push(entry.duration);
+
+        // Report the current worst interaction as INP approximation
+        // True INP uses p98, but for simplicity we track the max
+        const sorted = [...interactions].sort((a, b) => b - a);
+        // p98: skip top 2% of interactions
+        const p98Index = Math.max(0, Math.floor(sorted.length * 0.02));
+        const inpValue = sorted[p98Index] || sorted[0];
+
+        getAggregator().recordWebVital('inp', Math.round(inpValue));
+      }
+    }
+  });
+}
+
+/**
+ * Capture Cumulative Layout Shift (CLS)
+ * CLS accumulates layout shift values that occur without recent user input.
+ * Uses the "session window" approach: shifts within 1s of each other
+ * and max 5s total form a session. CLS is the max session value.
+ */
+function captureCLS() {
+  let sessionValue = 0;
+  let sessionEntries = [];
+  let maxSessionValue = 0;
+
+  createObserver('layout-shift', (list) => {
+    for (const entry of list.getEntries()) {
+      // Only count shifts without recent input
+      if (entry.hadRecentInput) continue;
+
+      // Check if this shift belongs to the current session window
+      const lastEntry = sessionEntries[sessionEntries.length - 1];
+      if (lastEntry &&
+          entry.startTime - lastEntry.startTime < 1000 &&
+          entry.startTime - sessionEntries[0].startTime < 5000) {
+        // Same session
+        sessionValue += entry.value;
+        sessionEntries.push(entry);
+      } else {
+        // New session
+        sessionValue = entry.value;
+        sessionEntries = [entry];
+      }
+
+      maxSessionValue = Math.max(maxSessionValue, sessionValue);
+      // Round to 4 decimal places (CLS is typically 0.xxxx)
+      getAggregator().recordWebVital('cls', Math.round(maxSessionValue * 10000) / 10000);
+    }
+  });
+}
+
+/**
+ * Capture page load timing from Navigation Timing API
+ */
+function capturePageLoad() {
+  function recordNavTiming() {
+    try {
+      const entries = performance.getEntriesByType('navigation');
+      const nav = entries[0];
+      if (!nav) return;
+
+      getAggregator().recordPageLoad({
+        dns: Math.round(nav.domainLookupEnd - nav.domainLookupStart),
+        tcp: Math.round(nav.connectEnd - nav.connectStart),
+        tls: Math.round(nav.secureConnectionStart > 0 ? nav.connectEnd - nav.secureConnectionStart : 0),
+        ttfb: Math.round(nav.responseStart - nav.requestStart),
+        download: Math.round(nav.responseEnd - nav.responseStart),
+        domInteractive: Math.round(nav.domInteractive - nav.startTime),
+        domContentLoaded: Math.round(nav.domContentLoadedEventEnd - nav.startTime),
+        load: Math.round(nav.loadEventEnd - nav.startTime)
+      });
+
+      debug('Page load timing captured');
+    } catch {
+      // Navigation Timing not available
+    }
+  }
+
+  if (document.readyState === 'complete') {
+    // Page already loaded - small delay to ensure loadEventEnd is populated
+    setTimeout(recordNavTiming, 0);
+  } else {
+    window.addEventListener('load', () => setTimeout(recordNavTiming, 0));
+  }
+}
+
+/**
+ * Start capturing all Web Vitals and page load timing
+ */
+export function startVitalsCapture() {
+  if (typeof window === 'undefined') return;
+
+  captureLCP();
+  captureFID();
+  captureINP();
+  captureCLS();
+  capturePageLoad();
+
+  debug('Web Vitals capture started');
+}
+
+/**
+ * Stop capturing Web Vitals (disconnect all observers)
+ */
+export function stopVitalsCapture() {
+  for (const observer of observers) {
+    try { observer.disconnect(); } catch { /* ignore */ }
+  }
+  observers = [];
+  debug('Web Vitals capture stopped');
+}
+
+export default { startVitalsCapture, stopVitalsCapture };

package/src/browser.js

@@ -1,107 +1,191 @@
-/**
- * SentienGuard APM SDK - Browser No-Op
- *
- * This module is automatically used when the SDK is imported in a browser
- * environment (via bundlers like Webpack, Vite, Rsbuild, etc.).
- *
- * The APM SDK only works in Node.js (it patches http/https modules),
- * so in the browser we export no-op stubs to avoid build errors.
- */
-
-const noop = () => {};
-const asyncNoop = async () => {};
-const noopMiddleware = (_req, _res, next) => next?.();
-
-function initialize() {}
-async function shutdown() {}
-function getStatus() {
-  return {
-    enabled: false,
-    initialized: false,
-    config: { service: '', environment: '', flushInterval: 0 },
-    stats: {}
-  };
-}
-function flush() {}
-function getConfig() {
-  return {};
-}
-function isEnabled() {
-  return false;
-}
-function normalizeRoute(route) {
-  return route;
-}
-function extractRoute(req) {
-  return req?.url || '/';
-}
-function getAggregator() {
-  return {
-    getStats: () => ({}),
-    recordRequest: noop,
-    recordDependency: noop,
-    recordError: noop
-  };
-}
-function instrumentMongoDB() {}
-function instrumentOpenAI() {}
-function createBreaker(fn) {
-  return fn;
-}
-function wrapMongoOperation(fn) {
-  return fn;
-}
-function getBreakerStats() {
-  return {};
-}
-
-const RouteRegistry = {
-  register: noop,
-  match: () => null
-};
-
-const expressMiddleware = noopMiddleware;
-const expressErrorMiddleware = (_err, _req, _res, next) => next?.();
-const fastifyPlugin = noop;
-const fastifyErrorHandler = noop;
-
-export {
-  initialize,
-  shutdown,
-  getStatus,
-  flush,
-  getConfig,
-  isEnabled,
-  expressMiddleware,
-  expressErrorMiddleware,
-  fastifyPlugin,
-  fastifyErrorHandler,
-  normalizeRoute,
-  extractRoute,
-  RouteRegistry,
-  getAggregator,
-  instrumentMongoDB,
-  instrumentOpenAI,
-  createBreaker,
-  wrapMongoOperation,
-  getBreakerStats
-};
-
-export default {
-  initialize,
-  shutdown,
-  getStatus,
-  flush,
-  expressMiddleware,
-  expressErrorMiddleware,
-  fastifyPlugin,
-  fastifyErrorHandler,
-  normalizeRoute,
-  extractRoute,
-  getAggregator,
-  instrumentMongoDB,
-  instrumentOpenAI,
-  createBreaker,
-  wrapMongoOperation,
-  getBreakerStats
-};
+/**
+ * SentienGuard APM SDK - Browser (Real User Monitoring)
+ *
+ * This module is automatically used when the SDK is imported in a browser
+ * environment (via bundlers like Webpack, Vite, Rsbuild, etc.).
+ *
+ * Unlike the Node.js SDK which auto-initializes on import, the browser SDK
+ * requires explicit initialization:
+ *
+ *   import SentienGuard from '@sentienguard/apm';
+ *
+ *   SentienGuard.init({
+ *     apiKey: 'your-apm-key',
+ *     service: 'my-frontend',
+ *     endpoint: 'https://your-backend.com/api/v1/apm/ingest',  // optional
+ *     environment: 'production',  // optional
+ *     debug: false                // optional
+ *   });
+ *
+ * What gets captured automatically after init():
+ * - Outgoing fetch/XHR requests (timing, status, errors)
+ * - Web Vitals (LCP, FID, INP, CLS)
+ * - Page load timing (Navigation Timing API)
+ * - Unhandled JS errors and promise rejections
+ * - SPA route changes (history.pushState/popstate)
+ */
+
+import config, { configure, isEnabled, getConfig, debug, warn } from './browser/config.js';
+import { getAggregator } from './browser/aggregator.js';
+import { startFlushing, stopFlushing, flush, setupUnloadFlush } from './browser/transport.js';
+import { instrumentNetwork, uninstrumentNetwork } from './browser/instrumentation.js';
+import { startErrorCapture, stopErrorCapture } from './browser/errors.js';
+import { startVitalsCapture, stopVitalsCapture } from './browser/vitals.js';
+import { startRouteTracking, stopRouteTracking } from './browser/router.js';
+
+let isInitialized = false;
+
+/**
+ * Initialize the browser SDK.
+ * Must be called explicitly with configuration options.
+ *
+ * @param {Object} options
+ * @param {string} options.apiKey - APM application key (required)
+ * @param {string} options.service - Service/app name (required)
+ * @param {string} [options.endpoint] - Backend ingest URL
+ * @param {string} [options.environment] - Environment name (default: 'production')
+ * @param {number} [options.flushInterval] - Flush interval in seconds (default: 10)
+ * @param {boolean} [options.debug] - Enable debug logging (default: false)
+ */
+function initialize(options = {}) {
+  if (isInitialized) {
+    debug('SDK already initialized');
+    return;
+  }
+
+  configure(options);
+
+  if (!isEnabled()) {
+    warn('SDK disabled (missing apiKey or service). Call init({ apiKey, service })');
+    return;
+  }
+
+  debug(`Initializing browser SDK for service: ${config.service}`);
+  debug(`Environment: ${config.environment}`);
+  debug(`Endpoint: ${config.endpoint}`);
+  debug(`Flush interval: ${config.flushInterval}s`);
+
+  // Instrument outgoing network requests (fetch + XHR)
+  instrumentNetwork();
+
+  // Capture unhandled JS errors
+  startErrorCapture();
+
+  // Capture Web Vitals (LCP, FID, INP, CLS) and page load timing
+  startVitalsCapture();
+
+  // Track SPA route changes
+  startRouteTracking();
+
+  // Start periodic metric flush
+  startFlushing();
+
+  // Setup final flush on page unload (visibilitychange)
+  setupUnloadFlush();
+
+  isInitialized = true;
+  debug('Browser SDK initialized');
+}
+
+/**
+ * Shutdown the SDK and flush remaining data
+ */
+async function shutdown() {
+  if (!isInitialized) return;
+
+  debug('Shutting down browser SDK');
+
+  stopFlushing();
+  stopVitalsCapture();
+  stopRouteTracking();
+  stopErrorCapture();
+  uninstrumentNetwork();
+
+  await flush();
+
+  isInitialized = false;
+  debug('Browser SDK shutdown complete');
+}
+
+/**
+ * Get current SDK status
+ */
+function getStatus() {
+  return {
+    enabled: isEnabled(),
+    initialized: isInitialized,
+    config: {
+      service: config.service,
+      environment: config.environment,
+      flushInterval: config.flushInterval
+    },
+    stats: isInitialized ? getAggregator().getStats() : {}
+  };
+}
+
+// ============================================
+// No-op stubs for Node.js-only features.
+// These maintain API compatibility so isomorphic code doesn't break.
+// ============================================
+const noop = () => {};
+function normalizeRoute(route) { return route; }
+function extractRoute(req) { return req?.url || '/'; }
+function instrumentMongoDB() {}
+function instrumentOpenAI() {}
+function createBreaker(fn) { return fn; }
+function wrapMongoOperation(fn) { return fn; }
+function getBreakerStats() { return {}; }
+
+const RouteRegistry = { register: noop, match: () => null };
+const expressMiddleware = (_req, _res, next) => next?.();
+const expressErrorMiddleware = (_err, _req, _res, next) => next?.();
+const fastifyPlugin = noop;
+const fastifyErrorHandler = noop;
+
+// Named exports (matching Node.js SDK's export surface exactly)
+export {
+  initialize,
+  initialize as init,
+  shutdown,
+  getStatus,
+  flush,
+  getConfig,
+  isEnabled,
+  expressMiddleware,
+  expressErrorMiddleware,
+  fastifyPlugin,
+  fastifyErrorHandler,
+  normalizeRoute,
+  extractRoute,
+  RouteRegistry,
+  getAggregator,
+  instrumentMongoDB,
+  instrumentOpenAI,
+  createBreaker,
+  wrapMongoOperation,
+  getBreakerStats
+};
+
+// Default export
+export default {
+  init: initialize,
+  initialize,
+  shutdown,
+  getStatus,
+  flush,
+  getConfig,
+  isEnabled,
+  getAggregator,
+  // Node.js-only stubs for isomorphic compatibility
+  expressMiddleware,
+  expressErrorMiddleware,
+  fastifyPlugin,
+  fastifyErrorHandler,
+  normalizeRoute,
+  extractRoute,
+  instrumentMongoDB,
+  instrumentOpenAI,
+  createBreaker,
+  wrapMongoOperation,
+  getBreakerStats
+};