@obsrviq/tracker 0.3.0

package/src/util.ts

@@ -0,0 +1,96 @@
+// Small browser utilities shared across the SDK.
+
+export function uuid(): string {
+  if (typeof crypto !== 'undefined' && 'randomUUID' in crypto) {
+    return crypto.randomUUID();
+  }
+  // RFC4122-ish fallback.
+  return 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx'.replace(/[xy]/g, (c) => {
+    const r = (Math.random() * 16) | 0;
+    const v = c === 'x' ? r : (r & 0x3) | 0x8;
+    return v.toString(16);
+  });
+}
+
+/** A monotonic-ish session clock: ms since the session started. */
+export class Clock {
+  readonly startedAt: number;
+  private perfStart: number;
+  /** Wall ms elapsed between the ORIGINAL session start and this page's start —
+   *  added to every `t` so a resumed (continued) session's timeline keeps climbing
+   *  across the inactivity gap instead of restarting at 0. 0 for a fresh session. */
+  private baseT: number;
+  /** @param resumeStartedAt epoch ms of the original session start when RESUMING a
+   *  continued session; omit for a fresh session.
+   *  @param floorT highest `t` the prior page reached — guarantees this page's
+   *  timeline starts after it, so a backward wall-clock jump between loads can't
+   *  produce overlapping timestamps (which would corrupt replay ordering). */
+  constructor(resumeStartedAt?: number, floorT?: number) {
+    const wallNow = Date.now();
+    this.startedAt = resumeStartedAt ?? wallNow;
+    this.perfStart = typeof performance !== 'undefined' ? performance.now() : 0;
+    this.baseT = Math.max(0, wallNow - this.startedAt, floorT ?? 0);
+  }
+  /** ms since the (original) session start — the master clock `t`. */
+  now(): number {
+    const p = typeof performance !== 'undefined' ? performance.now() : Date.now() - this.startedAt;
+    return Math.max(0, this.baseT + Math.round(p - this.perfStart));
+  }
+  /** wall-clock epoch ms for display (`ts`). */
+  wall(): number {
+    return Date.now();
+  }
+  /** Convert a performance-timeline timestamp (since timeOrigin) to session t. */
+  fromPerf(perfTs: number): number {
+    return Math.max(0, this.baseT + Math.round(perfTs - this.perfStart));
+  }
+}
+
+export async function sha256Hex(input: string): Promise<string> {
+  if (typeof crypto !== 'undefined' && crypto.subtle) {
+    const buf = await crypto.subtle.digest('SHA-256', new TextEncoder().encode(input));
+    return Array.from(new Uint8Array(buf))
+      .map((b) => b.toString(16).padStart(2, '0'))
+      .join('');
+  }
+  // Non-crypto fallback (still one-way enough for an opaque id).
+  let h = 0;
+  for (let i = 0; i < input.length; i++) h = (Math.imul(31, h) + input.charCodeAt(i)) | 0;
+  return (h >>> 0).toString(16);
+}
+
+export function detectDevice(): {
+  type: 'desktop' | 'mobile' | 'tablet';
+  os?: string;
+  browser?: string;
+  viewport: { w: number; h: number };
+} {
+  const ua = navigator.userAgent;
+  const viewport = { w: window.innerWidth, h: window.innerHeight };
+  let type: 'desktop' | 'mobile' | 'tablet' = 'desktop';
+  if (/iPad|Tablet/i.test(ua)) type = 'tablet';
+  else if (/Mobi|Android|iPhone/i.test(ua)) type = 'mobile';
+
+  let os: string | undefined;
+  if (/Windows/i.test(ua)) os = 'Windows';
+  else if (/Mac OS X|Macintosh/i.test(ua)) os = 'macOS';
+  else if (/Android/i.test(ua)) os = 'Android';
+  else if (/iPhone|iPad|iOS/i.test(ua)) os = 'iOS';
+  else if (/Linux/i.test(ua)) os = 'Linux';
+
+  let browser: string | undefined;
+  if (/Edg\//.test(ua)) browser = 'Edge';
+  else if (/Chrome\//.test(ua)) browser = 'Chrome';
+  else if (/Firefox\//.test(ua)) browser = 'Firefox';
+  else if (/Safari\//.test(ua)) browser = 'Safari';
+
+  return { type, os, browser, viewport };
+}
+
+/** Global Privacy Control / Do Not Track. */
+export function privacySignalsOptOut(): boolean {
+  const nav = navigator as Navigator & { globalPrivacyControl?: boolean; doNotTrack?: string };
+  if (nav.globalPrivacyControl === true) return true;
+  if (nav.doNotTrack === '1' || (window as { doNotTrack?: string }).doNotTrack === '1') return true;
+  return false;
+}

package/src/vitals.ts

@@ -0,0 +1,111 @@
+import type { PerfEvent } from '@obsrviq/types';
+import type { InstrumentCtx, Teardown } from './context.js';
+import { uuid } from './util.js';
+
+// Lightweight web-vitals capture via PerformanceObserver — no extra dependency.
+// Emits LCP, CLS, INP (approx), FCP, TTFB, and a navigation summary (§5/§11).
+
+function rate(metric: PerfEvent['metric'], value: number): PerfEvent['rating'] {
+  const t: Partial<Record<PerfEvent['metric'], [number, number]>> = {
+    LCP: [2500, 4000],
+    INP: [200, 500],
+    CLS: [0.1, 0.25],
+    FCP: [1800, 3000],
+    TTFB: [800, 1800],
+  };
+  const pair = t[metric];
+  if (!pair) return undefined;
+  if (value <= pair[0]) return 'good';
+  if (value <= pair[1]) return 'needs-improvement';
+  return 'poor';
+}
+
+export function instrumentVitals(ctx: InstrumentCtx): Teardown {
+  if (typeof PerformanceObserver === 'undefined') return () => {};
+  const observers: PerformanceObserver[] = [];
+
+  const emit = (metric: PerfEvent['metric'], value: number, detail?: Record<string, number>) => {
+    const e: PerfEvent = {
+      id: uuid(),
+      sessionId: ctx.sessionId,
+      type: 'perf',
+      t: ctx.clock.now(),
+      ts: ctx.clock.wall(),
+      metric,
+      value: Math.round(value * 1000) / 1000,
+      rating: rate(metric, value),
+      detail,
+    };
+    ctx.emit(e);
+  };
+
+  const obs = (type: string, cb: (entries: PerformanceEntryList) => void, extra?: object) => {
+    try {
+      const o = new PerformanceObserver((list) => cb(list.getEntries()));
+      o.observe({ type, buffered: true, ...extra });
+      observers.push(o);
+    } catch {
+      /* unsupported */
+    }
+  };
+
+  // FCP
+  obs('paint', (entries) => {
+    for (const e of entries) if (e.name === 'first-contentful-paint') emit('FCP', e.startTime);
+  });
+
+  // LCP — keep the largest seen.
+  let lcp = 0;
+  obs('largest-contentful-paint', (entries) => {
+    const last = entries[entries.length - 1];
+    if (last) lcp = last.startTime;
+  });
+
+  // CLS — accumulate session layout shift.
+  let cls = 0;
+  obs('layout-shift', (entries) => {
+    for (const e of entries as (PerformanceEntry & { value: number; hadRecentInput: boolean })[]) {
+      if (!e.hadRecentInput) cls += e.value;
+    }
+  });
+
+  // INP (approx via event timing — track max interaction delay).
+  let inp = 0;
+  obs(
+    'event',
+    (entries) => {
+      for (const e of entries as (PerformanceEntry & { duration: number })[]) {
+        if (e.duration > inp) inp = e.duration;
+      }
+    },
+    { durationThreshold: 40 },
+  );
+
+  // Navigation timing → TTFB + a navigation summary.
+  obs('navigation', (entries) => {
+    const nav = entries[0] as PerformanceNavigationTiming | undefined;
+    if (!nav) return;
+    emit('TTFB', nav.responseStart);
+    emit('navigation', nav.duration, {
+      domInteractive: Math.round(nav.domInteractive),
+      domComplete: Math.round(nav.domComplete),
+      loadEvent: Math.round(nav.loadEventEnd),
+    });
+  });
+
+  // Flush LCP/CLS/INP on the way out (their final values).
+  const flushFinal = () => {
+    if (lcp) emit('LCP', lcp);
+    emit('CLS', cls);
+    if (inp) emit('INP', inp);
+  };
+  const onHide = () => {
+    if (document.visibilityState === 'hidden') flushFinal();
+  };
+  document.addEventListener('visibilitychange', onHide, true);
+
+  return () => {
+    observers.forEach((o) => o.disconnect());
+    document.removeEventListener('visibilitychange', onHide, true);
+  };
+}