@obsrviq/tracker 0.3.0

package/src/network.ts

@@ -0,0 +1,439 @@
+import type { NetworkEvent, NetworkResourceType, NetworkTiming } from '@obsrviq/types';
+import type { InstrumentCtx, Teardown } from './context.js';
+import { maskString } from './mask.js';
+import { uuid } from './util.js';
+
+const BODY_CAP = 4 * 1024; // 4 KB body preview cap
+// Response/request header allowlist — everything else is dropped.
+const HEADER_ALLOW = new Set([
+  'content-type',
+  'content-length',
+  'accept',
+  'accept-encoding',
+  'cache-control',
+  'etag',
+  'last-modified',
+  'content-encoding',
+  'x-request-id',
+  'x-correlation-id',
+  'server',
+  'vary',
+]);
+
+function redactUrl(raw: string): string {
+  try {
+    const u = new URL(raw, location.href);
+    if (u.search) u.search = '?…';
+    return u.toString();
+  } catch {
+    return raw.split('?')[0] ?? raw;
+  }
+}
+
+function classifyHttp(status: number): string | undefined {
+  if (status === 0) return 'network';
+  if (status >= 500) return 'http_5xx';
+  if (status >= 400) return 'http_4xx';
+  return undefined;
+}
+
+function pickHeaders(
+  redact: string[],
+  entries: Iterable<[string, string]>,
+): Record<string, string> {
+  const out: Record<string, string> = {};
+  const redactSet = new Set(redact.map((h) => h.toLowerCase()));
+  for (const [k, v] of entries) {
+    const key = k.toLowerCase();
+    if (redactSet.has(key)) out[key] = 'redacted';
+    else if (HEADER_ALLOW.has(key)) out[key] = v;
+  }
+  return out;
+}
+
+function bodyPreview(
+  text: string | undefined,
+  contentType: string | undefined,
+): NetworkEvent['requestBody'] {
+  if (text == null) return undefined;
+  const masked = maskString(text);
+  const truncated = masked.length > BODY_CAP;
+  return {
+    contentType,
+    preview: truncated ? masked.slice(0, BODY_CAP) : masked,
+    truncated,
+    redacted: masked !== text,
+  };
+}
+
+function enrichTiming(ctx: InstrumentCtx, url: string, base: NetworkTiming): NetworkTiming {
+  try {
+    const entries = performance.getEntriesByType('resource') as PerformanceResourceTiming[];
+    // newest matching entry by URL
+    const match = entries.filter((e) => e.name === url).pop();
+    if (!match) return base;
+    const t: NetworkTiming = { ...base };
+    if (match.domainLookupEnd && match.domainLookupStart)
+      t.dns = Math.max(0, match.domainLookupEnd - match.domainLookupStart);
+    if (match.connectEnd && match.connectStart)
+      t.tcp = Math.max(0, match.connectEnd - match.connectStart);
+    if (match.secureConnectionStart)
+      t.tls = Math.max(0, match.connectEnd - match.secureConnectionStart);
+    if (match.responseStart && match.requestStart)
+      t.ttfb = Math.max(0, match.responseStart - match.requestStart);
+    if (match.responseEnd && match.responseStart)
+      t.download = Math.max(0, match.responseEnd - match.responseStart);
+    return t;
+  } catch {
+    return base;
+  }
+}
+
+export function instrumentNetwork(ctx: InstrumentCtx): Teardown {
+  const teardowns: Teardown[] = [];
+  teardowns.push(wrapFetch(ctx));
+  teardowns.push(wrapXhr(ctx));
+  teardowns.push(wrapBeacon(ctx));
+  teardowns.push(observeResources(ctx));
+  return () => teardowns.forEach((t) => t());
+}
+
+// ───────────────────────────── fetch ────────────────────────────────
+function wrapFetch(ctx: InstrumentCtx): Teardown {
+  const orig = window.fetch;
+  if (!orig) return () => {};
+  window.fetch = async function (input: RequestInfo | URL, init?: RequestInit) {
+    const rawUrl = input instanceof Request ? input.url : String(input);
+    // Never record our own telemetry round-trips to the ingest endpoint.
+    if (rawUrl.includes('/v1/batch')) return orig.call(window, input as RequestInfo, init);
+    const startT = ctx.clock.now();
+    const method = (init?.method || (input instanceof Request ? input.method : 'GET')).toUpperCase();
+    const url = redactUrl(rawUrl);
+    const reqHeaders = pickHeaders(
+      ctx.config.redactHeaders,
+      headerEntries(init?.headers ?? (input instanceof Request ? input.headers : undefined)),
+    );
+
+    const emit = (partial: Partial<NetworkEvent>) => {
+      const endT = ctx.clock.now();
+      const timing = enrichTiming(ctx, rawUrl, { startT, endT, duration: endT - startT });
+      const ev: NetworkEvent = {
+        id: uuid(),
+        sessionId: ctx.sessionId,
+        type: 'network',
+        t: startT,
+        ts: ctx.clock.wall(),
+        initiator: 'fetch',
+        method,
+        url,
+        status: 0,
+        ok: false,
+        resourceType: 'fetch',
+        requestHeaders: reqHeaders,
+        timing,
+        ...partial,
+      };
+      ctx.emit(ev);
+      ctx.markActivity();
+    };
+
+    try {
+      const res = await orig.call(window, input as RequestInfo, init);
+      const status = res.status;
+      const respHeaders = pickHeaders(ctx.config.redactHeaders, res.headers.entries());
+      const len = res.headers.get('content-length');
+      let responseBody: NetworkEvent['responseBody'];
+      if (ctx.config.captureNetworkBodies && isTexty(res.headers.get('content-type'))) {
+        try {
+          const text = await res.clone().text();
+          responseBody = bodyPreview(text, res.headers.get('content-type') || undefined);
+        } catch {
+          /* ignore */
+        }
+      }
+      emit({
+        status,
+        ok: res.ok,
+        responseSize: len ? Number(len) : undefined,
+        responseHeaders: respHeaders,
+        requestBody: ctx.config.captureNetworkBodies
+          ? bodyPreview(stringifyBody(init?.body), undefined)
+          : undefined,
+        responseBody,
+        error: classifyHttp(status),
+      });
+      return res;
+    } catch (err) {
+      emit({ status: 0, ok: false, error: classifyFetchError(err) });
+      throw err;
+    }
+  } as typeof window.fetch;
+  return () => {
+    window.fetch = orig;
+  };
+}
+
+function classifyFetchError(err: unknown): string {
+  const name = (err as { name?: string })?.name;
+  if (name === 'AbortError') return 'aborted';
+  const msg = String((err as { message?: string })?.message || '').toLowerCase();
+  if (msg.includes('cors')) return 'cors';
+  if (msg.includes('timeout')) return 'timeout';
+  return 'network';
+}
+
+// ────────────────────────────── XHR ─────────────────────────────────
+interface XhrMeta {
+  method: string;
+  url: string;
+  rawUrl: string;
+  startT: number;
+  reqHeaders: Record<string, string>;
+  body?: string;
+}
+
+function wrapXhr(ctx: InstrumentCtx): Teardown {
+  const XHR = XMLHttpRequest.prototype;
+  const origOpen = XHR.open;
+  const origSend = XHR.send;
+  const origSetHeader = XHR.setRequestHeader;
+  const META = new WeakMap<XMLHttpRequest, XhrMeta>();
+
+  XHR.open = function (this: XMLHttpRequest, method: string, url: string | URL, ...rest: unknown[]) {
+    const rawUrl = String(url);
+    META.set(this, {
+      method: String(method).toUpperCase(),
+      rawUrl,
+      url: redactUrl(rawUrl),
+      startT: 0,
+      reqHeaders: {},
+    });
+    return origOpen.apply(this, [method, url, ...rest] as never);
+  } as typeof XHR.open;
+
+  XHR.setRequestHeader = function (this: XMLHttpRequest, name: string, value: string) {
+    const meta = META.get(this);
+    if (meta) {
+      const key = name.toLowerCase();
+      if (ctx.config.redactHeaders.map((h) => h.toLowerCase()).includes(key))
+        meta.reqHeaders[key] = 'redacted';
+      else if (HEADER_ALLOW.has(key)) meta.reqHeaders[key] = value;
+    }
+    return origSetHeader.apply(this, [name, value] as never);
+  } as typeof XHR.setRequestHeader;
+
+  XHR.send = function (this: XMLHttpRequest, body?: Document | XMLHttpRequestBodyInit | null) {
+    const meta = META.get(this);
+    if (meta) {
+      meta.startT = ctx.clock.now();
+      if (ctx.config.captureNetworkBodies) meta.body = stringifyBody(body);
+      const finish = (error?: string) => {
+        const endT = ctx.clock.now();
+        const timing = enrichTiming(ctx, meta.rawUrl, {
+          startT: meta.startT,
+          endT,
+          duration: endT - meta.startT,
+        });
+        const status = this.status;
+        const respHeaders = parseRawHeaders(ctx, this.getAllResponseHeaders());
+        // Response body (texty + readable responseType only), parallel to fetch.
+        let responseBody: NetworkEvent['responseBody'];
+        if (ctx.config.captureNetworkBodies && isTexty(this.getResponseHeader('content-type'))) {
+          try {
+            if (this.responseType === '' || this.responseType === 'text') {
+              responseBody = bodyPreview(this.responseText, this.getResponseHeader('content-type') || undefined);
+            }
+          } catch {
+            /* opaque/cross-origin response — skip the body */
+          }
+        }
+        const ev: NetworkEvent = {
+          id: uuid(),
+          sessionId: ctx.sessionId,
+          type: 'network',
+          t: meta.startT,
+          ts: ctx.clock.wall(),
+          initiator: 'xhr',
+          method: meta.method,
+          url: meta.url,
+          status,
+          ok: status >= 200 && status < 400,
+          resourceType: 'xhr',
+          requestHeaders: meta.reqHeaders,
+          responseHeaders: respHeaders,
+          responseSize: safeLen(this),
+          requestBody: ctx.config.captureNetworkBodies ? bodyPreview(meta.body, undefined) : undefined,
+          responseBody,
+          timing,
+          error: error || classifyHttp(status),
+        };
+        ctx.emit(ev);
+        ctx.markActivity();
+      };
+      this.addEventListener('loadend', () => finish());
+      this.addEventListener('error', () => finish('network'));
+      this.addEventListener('timeout', () => finish('timeout'));
+      this.addEventListener('abort', () => finish('aborted'));
+    }
+    return origSend.apply(this, [body] as never);
+  } as typeof XHR.send;
+
+  return () => {
+    XHR.open = origOpen;
+    XHR.send = origSend;
+    XHR.setRequestHeader = origSetHeader;
+  };
+}
+
+function safeLen(xhr: XMLHttpRequest): number | undefined {
+  try {
+    if (xhr.responseType === '' || xhr.responseType === 'text')
+      return new Blob([xhr.responseText]).size;
+  } catch {
+    /* opaque */
+  }
+  const len = xhr.getResponseHeader('content-length');
+  return len ? Number(len) : undefined;
+}
+
+function parseRawHeaders(ctx: InstrumentCtx, raw: string): Record<string, string> {
+  const entries: [string, string][] = [];
+  for (const line of raw.trim().split(/[\r\n]+/)) {
+    const idx = line.indexOf(':');
+    if (idx > 0) entries.push([line.slice(0, idx).trim(), line.slice(idx + 1).trim()]);
+  }
+  return pickHeaders(ctx.config.redactHeaders, entries);
+}
+
+// ──────────────────────────── sendBeacon ────────────────────────────
+function wrapBeacon(ctx: InstrumentCtx): Teardown {
+  const orig = navigator.sendBeacon;
+  if (!orig) return () => {};
+  navigator.sendBeacon = function (url: string | URL, data?: BodyInit | null): boolean {
+    const startT = ctx.clock.now();
+    let ok = false;
+    try {
+      ok = orig.call(navigator, url, data);
+    } finally {
+      // Don't record beacons to our own ingest endpoint.
+      const u = String(url);
+      if (!u.includes('/v1/batch')) {
+        const ev: NetworkEvent = {
+          id: uuid(),
+          sessionId: ctx.sessionId,
+          type: 'network',
+          t: startT,
+          ts: ctx.clock.wall(),
+          initiator: 'beacon',
+          method: 'POST',
+          url: redactUrl(u),
+          status: ok ? 202 : 0,
+          ok,
+          resourceType: 'other',
+          timing: { startT, endT: ctx.clock.now(), duration: 0 },
+          error: ok ? undefined : 'network',
+        };
+        ctx.emit(ev);
+      }
+    }
+    return ok;
+  };
+  return () => {
+    navigator.sendBeacon = orig;
+  };
+}
+
+// ─────────────────── PerformanceObserver (resources) ────────────────
+const RESOURCE_TYPE_MAP: Record<string, NetworkResourceType> = {
+  script: 'script',
+  link: 'stylesheet',
+  css: 'stylesheet',
+  img: 'image',
+  image: 'image',
+  font: 'font',
+  audio: 'media',
+  video: 'media',
+  track: 'media',
+};
+
+function observeResources(ctx: InstrumentCtx): Teardown {
+  if (typeof PerformanceObserver === 'undefined') return () => {};
+  let obs: PerformanceObserver | undefined;
+  try {
+    obs = new PerformanceObserver((list) => {
+      for (const entry of list.getEntries() as PerformanceResourceTiming[]) {
+        const it = entry.initiatorType;
+        // fetch/XHR are captured by our wrappers — skip to avoid duplicates.
+        if (it === 'fetch' || it === 'xmlhttprequest' || it === 'beacon') continue;
+        const resourceType = RESOURCE_TYPE_MAP[it] || 'other';
+        const startT = ctx.clock.fromPerf(entry.startTime);
+        const endT = ctx.clock.fromPerf(entry.responseEnd || entry.startTime);
+        const timing: NetworkTiming = {
+          startT,
+          endT,
+          duration: Math.max(0, endT - startT),
+          dns: nz(entry.domainLookupEnd - entry.domainLookupStart),
+          tcp: nz(entry.connectEnd - entry.connectStart),
+          tls: entry.secureConnectionStart ? nz(entry.connectEnd - entry.secureConnectionStart) : undefined,
+          ttfb: nz(entry.responseStart - entry.requestStart),
+          download: nz(entry.responseEnd - entry.responseStart),
+        };
+        const ev: NetworkEvent = {
+          id: uuid(),
+          sessionId: ctx.sessionId,
+          type: 'network',
+          t: startT,
+          ts: ctx.clock.wall(),
+          initiator: 'resource',
+          method: 'GET',
+          url: redactUrl(entry.name),
+          status: entry.responseStatus || 200,
+          ok: !entry.responseStatus || entry.responseStatus < 400,
+          resourceType,
+          responseSize: entry.transferSize || entry.encodedBodySize || undefined,
+          timing,
+        };
+        ctx.emit(ev);
+      }
+    });
+    obs.observe({ type: 'resource', buffered: true });
+  } catch {
+    return () => {};
+  }
+  return () => obs?.disconnect();
+}
+
+// ────────────────────────────── helpers ─────────────────────────────
+function nz(n: number): number | undefined {
+  return Number.isFinite(n) && n > 0 ? Math.round(n) : undefined;
+}
+
+function isTexty(contentType: string | null): boolean {
+  if (!contentType) return false;
+  return /json|text|xml|x-www-form-urlencoded/i.test(contentType);
+}
+
+function stringifyBody(body: unknown): string | undefined {
+  if (body == null) return undefined;
+  if (typeof body === 'string') return body;
+  if (body instanceof URLSearchParams) return body.toString();
+  if (body instanceof FormData) {
+    const obj: Record<string, string> = {};
+    body.forEach((v, k) => (obj[k] = typeof v === 'string' ? v : '«file»'));
+    return JSON.stringify(obj);
+  }
+  try {
+    return JSON.stringify(body);
+  } catch {
+    return undefined;
+  }
+}
+
+function headerEntries(
+  headers: HeadersInit | Headers | undefined,
+): Iterable<[string, string]> {
+  if (!headers) return [];
+  if (headers instanceof Headers) return headers.entries();
+  if (Array.isArray(headers)) return headers as [string, string][];
+  return Object.entries(headers);
+}

package/src/pageviews.ts

@@ -0,0 +1,67 @@
+import type { PageviewEvent } from '@obsrviq/types';
+import type { InstrumentCtx, Teardown } from './context.js';
+import { uuid } from './util.js';
+
+/**
+ * Auto-captures a `pageview` event on the initial load and on every SPA route
+ * change — history.pushState / replaceState (patched, since neither fires a
+ * native event), popstate (back/forward), and hashchange.
+ *
+ * The "page" identity is the pathname, plus a hash-router segment when the hash
+ * looks like a route (`#/checkout`) but NOT a plain anchor (`#section`) — so
+ * anchor jumps don't masquerade as page views. Same-path repeats are de-duped.
+ * Each view records the previous in-app path as its `referrer`: the "from" edge
+ * that Path / Journey analysis chains.
+ */
+export function instrumentPageviews(ctx: InstrumentCtx): Teardown {
+  let lastPath: string | null = null;
+
+  const currentPath = (): string => {
+    const hash = location.hash;
+    return location.pathname + (hash.startsWith('#/') ? hash : '');
+  };
+
+  const fire = () => {
+    const path = currentPath();
+    if (path === lastPath) return; // de-dupe no-op navigations / anchor jumps
+    const referrer = lastPath ?? '';
+    lastPath = path;
+    const e: PageviewEvent = {
+      id: uuid(),
+      sessionId: ctx.sessionId,
+      type: 'pageview',
+      t: ctx.clock.now(),
+      ts: ctx.clock.wall(),
+      url: location.href,
+      path,
+      title: document.title || undefined,
+      referrer: referrer || undefined,
+    };
+    ctx.emit(e);
+    ctx.markActivity();
+  };
+
+  // Patch history so SPA navigations (which fire no native event) are observed.
+  const origPush = history.pushState;
+  const origReplace = history.replaceState;
+  const wrap = (orig: History['pushState']): History['pushState'] =>
+    function patched(this: History, data, unused, url) {
+      const ret = orig.call(this, data, unused, url);
+      // Defer one microtask so location.* already reflects the new URL.
+      queueMicrotask(fire);
+      return ret;
+    };
+  history.pushState = wrap(origPush);
+  history.replaceState = wrap(origReplace);
+  window.addEventListener('popstate', fire);
+  window.addEventListener('hashchange', fire);
+
+  fire(); // the entry view
+
+  return () => {
+    history.pushState = origPush;
+    history.replaceState = origReplace;
+    window.removeEventListener('popstate', fire);
+    window.removeEventListener('hashchange', fire);
+  };
+}

package/src/recorder.ts

@@ -0,0 +1,53 @@
+import { record } from 'rrweb';
+import type { eventWithTime } from '@rrweb/types';
+import type { DomEvent } from '@obsrviq/types';
+import type { InstrumentCtx, Teardown } from './context.js';
+import { uuid } from './util.js';
+
+// rrweb EventType.IncrementalSnapshot === 3 (a real DOM mutation/interaction).
+const INCREMENTAL = 3;
+
+export function instrumentDom(ctx: InstrumentCtx): Teardown {
+  const stop = record({
+    emit(event: eventWithTime) {
+      const dom: DomEvent = {
+        id: uuid(),
+        sessionId: ctx.sessionId,
+        type: 'dom',
+        t: ctx.clock.fromPerf(performanceNow()),
+        ts: ctx.clock.wall(),
+        data: event,
+      };
+      ctx.emit(dom);
+      if (event.type === INCREMENTAL) ctx.markActivity();
+    },
+    maskAllInputs: ctx.config.maskAllInputs,
+    // Password inputs stay masked even in no-privacy mode (maskAllInputs:false) —
+    // a hard floor so recordings never store plaintext passwords.
+    maskInputOptions: { password: true },
+    maskTextSelector: ctx.config.maskTextSelector,
+    blockSelector: ctx.config.blockSelector,
+    recordCanvas: ctx.config.recordCanvas,
+    // Periodic full snapshots → the player can start replay from the nearest
+    // checkpoint, enabling progressive buffering + reliable seeking (§8.6).
+    checkoutEveryNms: 30_000,
+    sampling: {
+      // Don't record every mousemove point; sample for a smaller payload.
+      mousemove: 50,
+      scroll: 150,
+      input: 'last',
+    },
+  });
+
+  return () => {
+    try {
+      stop?.();
+    } catch {
+      /* already stopped */
+    }
+  };
+}
+
+function performanceNow(): number {
+  return typeof performance !== 'undefined' ? performance.now() : Date.now();
+}

package/src/scroll.ts

@@ -0,0 +1,65 @@
+import type { CustomEvent as ObsrviqCustomEvent } from '@obsrviq/types';
+import type { InstrumentCtx, Teardown } from './context.js';
+import { uuid } from './util.js';
+
+/**
+ * Scroll-depth capture, per page path. Emits a `_scroll` event whenever the
+ * visitor reaches a new, deeper 10% band of the page, so the server can take
+ * each session's max depth per page. Cheap (a handful of events per page at
+ * most) and value-free. The page identity is the pathname; depth resets on SPA
+ * route changes.
+ */
+export function instrumentScrollDepth(ctx: InstrumentCtx): Teardown {
+  let path = location.pathname;
+  let maxBand = 0; // deepest 10% band reached on the current path
+  let scheduled = false;
+
+  const emit = (depth: number) => {
+    const e: ObsrviqCustomEvent = {
+      id: uuid(),
+      sessionId: ctx.sessionId,
+      type: 'custom',
+      t: ctx.clock.now(),
+      ts: ctx.clock.wall(),
+      name: '_scroll',
+      props: { path, depth },
+    };
+    ctx.emit(e);
+  };
+
+  const docHeight = (): number => {
+    const d = document.documentElement;
+    const b = document.body;
+    return Math.max(d.scrollHeight, b ? b.scrollHeight : 0, d.clientHeight) || 1;
+  };
+
+  const measure = () => {
+    scheduled = false;
+    // Reset depth tracking when the SPA route changes.
+    if (location.pathname !== path) {
+      path = location.pathname;
+      maxBand = 0;
+    }
+    const vh = window.innerHeight || document.documentElement.clientHeight || 1;
+    const reached = Math.min(1, (window.scrollY + vh) / docHeight());
+    const band = Math.min(100, Math.round(reached * 10) * 10);
+    if (band > maxBand) {
+      maxBand = band;
+      emit(band);
+    }
+  };
+
+  const onScroll = () => {
+    if (scheduled) return;
+    scheduled = true;
+    requestAnimationFrame(measure);
+  };
+
+  window.addEventListener('scroll', onScroll, { passive: true, capture: true });
+  // Capture the entry fold immediately (a session that never scrolls still has a depth).
+  measure();
+
+  return () => {
+    window.removeEventListener('scroll', onScroll, true);
+  };
+}