@obsrviq/tracker 0.3.0

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@obsrviq/tracker",
+  "version": "0.3.0",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "description": "Obsrviq capture SDK — privacy-first DOM, console, network, error & web-vitals recording.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "unpkg": "./dist/obsrviq.global.js",
+  "jsdelivr": "./dist/obsrviq.global.js",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./global": "./dist/obsrviq.global.js"
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "dependencies": {
+    "@rrweb/types": "2.0.1",
+    "fflate": "^0.8.2",
+    "rrweb": "2.0.1",
+    "@obsrviq/types": "0.3.0"
+  },
+  "devDependencies": {
+    "tsup": "^8.3.5",
+    "typescript": "^5.7.2"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "typecheck": "tsc --noEmit"
+  }
+}

package/src/console.ts

@@ -0,0 +1,96 @@
+import type { ConsoleEvent, ConsoleLevel, ErrorEvent } from '@obsrviq/types';
+import type { InstrumentCtx, Teardown } from './context.js';
+import { serializeArg, parseSource } from './serialize.js';
+import { uuid } from './util.js';
+
+const LEVELS: ConsoleLevel[] = ['log', 'info', 'warn', 'error', 'debug'];
+const MAX_PER_SEC = 100; // flood cap (§6.1)
+
+export function instrumentConsole(ctx: InstrumentCtx): Teardown {
+  const original: Partial<Record<ConsoleLevel, (...a: unknown[]) => void>> = {};
+  let windowStart = ctx.clock.now();
+  let inWindow = 0;
+  let suppressed = 0;
+
+  function rateLimited(): boolean {
+    const now = ctx.clock.now();
+    if (now - windowStart >= 1000) {
+      if (suppressed > 0) {
+        // surface a single synthetic note that we dropped a flood
+        emitConsole('warn', [
+          { kind: 'string', value: `Obsrviq: suppressed ${suppressed} console messages (flood cap)` },
+        ]);
+        suppressed = 0;
+      }
+      windowStart = now;
+      inWindow = 0;
+    }
+    if (inWindow >= MAX_PER_SEC) {
+      suppressed++;
+      return true;
+    }
+    inWindow++;
+    return false;
+  }
+
+  function emitConsole(level: ConsoleLevel, args: ConsoleEvent['args'], stack?: string) {
+    const source = parseSource(stack);
+    const e: ConsoleEvent = {
+      id: uuid(),
+      sessionId: ctx.sessionId,
+      type: 'console',
+      t: ctx.clock.now(),
+      ts: ctx.clock.wall(),
+      level,
+      args,
+      stack: level === 'error' ? stack : undefined,
+      source,
+    };
+    ctx.emit(e);
+  }
+
+  for (const level of LEVELS) {
+    const orig = console[level] as (...a: unknown[]) => void;
+    original[level] = orig;
+    console[level] = (...args: unknown[]) => {
+      try {
+        orig.apply(console, args);
+      } catch {
+        /* never let our wrapper break the original */
+      }
+      try {
+        if (rateLimited()) return;
+        const serialized = args.map((a) => serializeArg(a, ctx.config.maxArgBytes));
+        let stack: string | undefined;
+        if (level === 'error') {
+          const errArg = args.find((a) => a instanceof Error) as Error | undefined;
+          stack = errArg?.stack ?? new Error().stack;
+        }
+        emitConsole(level, serialized, stack);
+      } catch {
+        /* swallow */
+      }
+    };
+  }
+
+  return () => {
+    for (const level of LEVELS) {
+      if (original[level]) console[level] = original[level]!;
+    }
+  };
+}
+
+/** Shared helper used by errors.ts to also surface uncaught errors in console. */
+export function errorToConsoleEvent(ctx: InstrumentCtx, err: ErrorEvent): ConsoleEvent {
+  return {
+    id: uuid(),
+    sessionId: ctx.sessionId,
+    type: 'console',
+    t: err.t,
+    ts: err.ts,
+    level: 'error',
+    args: [{ kind: 'error', name: err.name, message: err.message, stack: err.stack }],
+    stack: err.stack,
+    source: err.source,
+  };
+}

package/src/context.ts

@@ -0,0 +1,44 @@
+import type { IngestBatch, ObsrviqEvent } from '@obsrviq/types';
+import type { Clock } from './util.js';
+
+export interface ResolvedConfig {
+  siteKey: string;
+  userId?: string;
+  metadata?: Record<string, unknown>;
+  maskAllInputs: boolean;
+  maskTextSelector?: string;
+  blockSelector: string;
+  /** No-privacy capture (record input values + text verbatim). Passwords stay
+   *  masked regardless via the recorder's maskInputOptions. */
+  noPrivacy: boolean;
+  captureNetworkBodies: boolean;
+  redactHeaders: string[];
+  /** Opt-in: resume the same session for a returning visit within the window. */
+  continueSession: boolean;
+  /** Inactivity window (ms) for continueSession. */
+  sessionTimeoutMs: number;
+  sampleRate: number;
+  recordCanvas: boolean;
+  endpoint: string;
+  flushIntervalMs: number;
+  requireConsent: boolean;
+  askPermission: boolean;
+  showRecording: boolean;
+  consentText?: { title?: string; body?: string; allow?: string; deny?: string };
+  beforeSend?: (batch: IngestBatch) => IngestBatch | null;
+  maxArgBytes: number;
+}
+
+export interface InstrumentCtx {
+  clock: Clock;
+  sessionId: string;
+  config: ResolvedConfig;
+  emit: (event: ObsrviqEvent) => void;
+  /** record that the app "did something" (DOM mutation / nav / network) — used
+   *  by dead-click detection. */
+  markActivity: () => void;
+  /** the last time markActivity ran (ms since session start). */
+  lastActivityT: () => number;
+}
+
+export type Teardown = () => void;

package/src/errors.ts

@@ -0,0 +1,78 @@
+import type { ErrorEvent as ObsrviqErrorEvent } from '@obsrviq/types';
+import type { InstrumentCtx, Teardown } from './context.js';
+import { errorToConsoleEvent } from './console.js';
+import { maskString } from './mask.js';
+import { parseSource } from './serialize.js';
+import { uuid } from './util.js';
+
+export function instrumentErrors(ctx: InstrumentCtx): Teardown {
+  function emitError(args: {
+    name: string;
+    message: string;
+    stack?: string;
+    source?: { url?: string; line?: number; col?: number };
+    handled: boolean;
+  }) {
+    const e: ObsrviqErrorEvent = {
+      id: uuid(),
+      sessionId: ctx.sessionId,
+      type: 'error',
+      t: ctx.clock.now(),
+      ts: ctx.clock.wall(),
+      name: args.name,
+      message: maskString(args.message),
+      stack: args.stack ? maskString(args.stack) : undefined,
+      source: args.source,
+      handled: args.handled,
+    };
+    ctx.emit(e);
+    // Surface uncaught errors in the Console panel too (§9 C-6).
+    ctx.emit(errorToConsoleEvent(ctx, e));
+  }
+
+  const onError = (ev: ErrorEvent) => {
+    const err = ev.error as Error | undefined;
+    emitError({
+      name: err?.name || 'Error',
+      message: err?.message || ev.message || 'Unknown error',
+      stack: err?.stack,
+      source: { url: ev.filename, line: ev.lineno, col: ev.colno },
+      handled: false,
+    });
+  };
+
+  const onRejection = (ev: PromiseRejectionEvent) => {
+    const reason = ev.reason;
+    if (reason instanceof Error) {
+      emitError({
+        name: reason.name,
+        message: reason.message,
+        stack: reason.stack,
+        source: parseSource(reason.stack),
+        handled: false,
+      });
+    } else {
+      emitError({
+        name: 'UnhandledRejection',
+        message: typeof reason === 'string' ? reason : safeStringify(reason),
+        handled: false,
+      });
+    }
+  };
+
+  window.addEventListener('error', onError, true);
+  window.addEventListener('unhandledrejection', onRejection, true);
+
+  return () => {
+    window.removeEventListener('error', onError, true);
+    window.removeEventListener('unhandledrejection', onRejection, true);
+  };
+}
+
+function safeStringify(v: unknown): string {
+  try {
+    return JSON.stringify(v) ?? String(v);
+  } catch {
+    return String(v);
+  }
+}

package/src/forms.ts

@@ -0,0 +1,189 @@
+import type { CustomEvent as ObsrviqCustomEvent } from '@obsrviq/types';
+import type { InstrumentCtx, Teardown } from './context.js';
+import { cssPath } from './serialize.js';
+import { uuid } from './util.js';
+
+/**
+ * Form-field analytics. Watches every form control (input / textarea / select)
+ * and, on each blur, emits a lightweight `form_field` custom event describing
+ * the *interaction* — never the value:
+ *
+ *   { form, field, type, ms, changed, filled }
+ *
+ * One event per focus→blur, carrying that focus's duration (`ms`). The server
+ * sums `ms` across events for total time-on-field, counts events per session
+ * for re-entries, and reads `filled` to find fields people leave blank. A
+ * `form_submit` event is emitted when a form is submitted; the last field
+ * touched in a session whose form never submitted is the drop-off point.
+ *
+ * Privacy: values are never read. `filled` is a boolean derived from value
+ * length (or `checked`); the field key comes from structural attributes
+ * (name / id / label), exactly as form-analytics tools do. Controls inside a
+ * blocked region (the configured block selector) are skipped entirely.
+ */
+
+const TRACKED = new Set(['INPUT', 'TEXTAREA', 'SELECT']);
+// Non-data inputs: buttons and hidden/file fields carry no fill behaviour worth
+// measuring (and file is privacy-adjacent), so they're left out.
+const SKIP_INPUT_TYPES = new Set(['hidden', 'submit', 'button', 'reset', 'image', 'file']);
+const MAX_KEY = 80;
+const MAX_FOCUS_MS = 300_000; // cap idle-inflated focus time (walked-away tab)
+const MIN_FOCUS_MS = 100; // ignore sub-100ms programmatic focus blips
+
+type FormControl = HTMLInputElement | HTMLTextAreaElement | HTMLSelectElement;
+
+function isTracked(el: EventTarget | null): el is FormControl {
+  if (!(el instanceof HTMLElement) || !TRACKED.has(el.tagName)) return false;
+  if (el instanceof HTMLInputElement && SKIP_INPUT_TYPES.has(el.type)) return false;
+  return true;
+}
+
+function controlType(el: FormControl): string {
+  if (el instanceof HTMLTextAreaElement) return 'textarea';
+  if (el instanceof HTMLSelectElement) return 'select';
+  return el.type || 'text';
+}
+
+/** Non-empty / checked — a boolean only, the value itself is never read. */
+function isFilled(el: FormControl): boolean {
+  if (el instanceof HTMLInputElement) {
+    if (el.type === 'checkbox' || el.type === 'radio') return el.checked;
+    return el.value.trim().length > 0;
+  }
+  if (el instanceof HTMLSelectElement) return el.value !== '';
+  return el.value.trim().length > 0;
+}
+
+function clip(s: string): string {
+  const t = s.trim().replace(/\s+/g, ' ');
+  return t.length > MAX_KEY ? t.slice(0, MAX_KEY) : t;
+}
+
+/** A stable, human-readable field identity from structural attributes only. */
+function fieldKey(el: FormControl): string {
+  const name = el.getAttribute('name');
+  if (name) return clip(name);
+  if (el.id) return clip(el.id);
+  const aria = el.getAttribute('aria-label');
+  if (aria) return clip(aria);
+  const labelledby = el.getAttribute('aria-labelledby');
+  if (labelledby) {
+    const lbl = labelledby.split(/\s+/).map((id) => el.ownerDocument.getElementById(id)?.textContent || '').join(' ').trim();
+    if (lbl) return clip(lbl);
+  }
+  if (el.labels && el.labels.length) {
+    const lbl = el.labels[0]!.textContent?.trim();
+    if (lbl) return clip(lbl);
+  }
+  const ph = el.getAttribute('placeholder');
+  if (ph) return clip(ph);
+  return clip(cssPath(el));
+}
+
+/** A stable identity for the owning form (or a per-page bucket for loose fields). */
+function formKey(el: FormControl): string {
+  const form = el.form;
+  if (form) {
+    if (form.getAttribute('name')) return clip(form.getAttribute('name')!);
+    if (form.id) return clip(form.id);
+    const aria = form.getAttribute('aria-label');
+    if (aria) return clip(aria);
+    const action = form.getAttribute('action');
+    if (action) {
+      try {
+        return clip(new URL(action, location.href).pathname);
+      } catch {
+        return clip(action);
+      }
+    }
+    return clip(cssPath(form));
+  }
+  // Form-less controls (common in SPAs) bucket by page path.
+  return clip(`page:${location.pathname}`);
+}
+
+export function instrumentForms(ctx: InstrumentCtx): Teardown {
+  const block = ctx.config.blockSelector;
+  // Per-focus state for the currently-focused control.
+  let focused: { el: FormControl; start: number; changed: boolean } | null = null;
+
+  const emit = (name: string, props: Record<string, unknown>) => {
+    const e: ObsrviqCustomEvent = {
+      id: uuid(),
+      sessionId: ctx.sessionId,
+      type: 'custom',
+      t: ctx.clock.now(),
+      ts: ctx.clock.wall(),
+      name,
+      props,
+    };
+    ctx.emit(e);
+  };
+
+  const blocked = (el: Element): boolean => {
+    try {
+      return !!block && !!el.closest(block);
+    } catch {
+      return false;
+    }
+  };
+
+  const flush = () => {
+    if (!focused) return;
+    const { el, start, changed } = focused;
+    focused = null;
+    const ms = Math.min(MAX_FOCUS_MS, Math.max(0, ctx.clock.now() - start));
+    // Drop pass-through blips that weren't real interactions.
+    if (ms < MIN_FOCUS_MS && !changed) return;
+    emit('form_field', {
+      form: formKey(el),
+      field: fieldKey(el),
+      type: controlType(el),
+      ms,
+      changed,
+      filled: isFilled(el),
+    });
+  };
+
+  const onFocusIn = (ev: FocusEvent) => {
+    const el = ev.target;
+    if (!isTracked(el) || blocked(el)) return;
+    if (focused && focused.el !== el) flush(); // safety: blur may have been missed
+    focused = { el, start: ctx.clock.now(), changed: false };
+  };
+
+  const onInput = (ev: Event) => {
+    if (focused && ev.target === focused.el) focused.changed = true;
+  };
+
+  const onFocusOut = (ev: FocusEvent) => {
+    if (focused && ev.target === focused.el) flush();
+  };
+
+  const onSubmit = (ev: Event) => {
+    const form = ev.target;
+    if (!(form instanceof HTMLFormElement) || blocked(form)) return;
+    // Flush the in-progress field so its time lands before the submit marker.
+    flush();
+    // Reuse a tracked control to derive the key consistently; else fall back to the form itself.
+    const probe = form.querySelector<FormControl>('input,textarea,select');
+    const key = probe && !blocked(probe) ? formKey(probe) : clip(form.getAttribute('name') || form.id || cssPath(form));
+    emit('form_submit', { form: key });
+  };
+
+  document.addEventListener('focusin', onFocusIn, true);
+  document.addEventListener('focusout', onFocusOut, true);
+  document.addEventListener('input', onInput, true);
+  document.addEventListener('submit', onSubmit, true);
+  // A navigation/unload can steal focus without a focusout — flush what we have.
+  window.addEventListener('pagehide', flush, true);
+
+  return () => {
+    flush();
+    document.removeEventListener('focusin', onFocusIn, true);
+    document.removeEventListener('focusout', onFocusOut, true);
+    document.removeEventListener('input', onInput, true);
+    document.removeEventListener('submit', onSubmit, true);
+    window.removeEventListener('pagehide', flush, true);
+  };
+}

package/src/global.ts

@@ -0,0 +1,61 @@
+/**
+ * IIFE entry for plain <script> embedding. Auto-initialises from data-* attrs:
+ *
+ *   <script src="https://cdn.example.com/obsrviq.global.js"
+ *           data-obsrviq-key="pk_live_xxx"
+ *           data-obsrviq-endpoint="https://in.lumera.app"
+ *           data-obsrviq-mask-inputs="true"
+ *           data-obsrviq-require-consent="false"></script>
+ *
+ * Exposes `window.Obsrviq` for manual identify()/track()/setConsent() calls.
+ */
+import { Obsrviq } from './index.js';
+import type { ObsrviqInitConfig } from '@obsrviq/types';
+
+declare global {
+  interface Window {
+    Obsrviq: typeof Obsrviq;
+  }
+}
+
+const current = document.currentScript as HTMLScriptElement | null;
+
+function bool(v: string | null | undefined, fallback: boolean): boolean {
+  if (v == null) return fallback;
+  return v === 'true' || v === '1';
+}
+
+if (current) {
+  const key = current.getAttribute('data-obsrviq-key');
+  if (key) {
+    const cfg: ObsrviqInitConfig = {
+      siteKey: key,
+      endpoint: current.getAttribute('data-obsrviq-endpoint') || undefined,
+      maskAllInputs: bool(current.getAttribute('data-obsrviq-mask-inputs'), true),
+      captureNetworkBodies: bool(current.getAttribute('data-obsrviq-capture-bodies'), false),
+      requireConsent: bool(current.getAttribute('data-obsrviq-require-consent'), false),
+      askPermission: bool(current.getAttribute('data-obsrviq-ask-permission'), false),
+      showRecording: bool(current.getAttribute('data-obsrviq-show-recording'), false),
+      recordCanvas: bool(current.getAttribute('data-obsrviq-record-canvas'), false),
+    };
+    const rate = current.getAttribute('data-obsrviq-sample-rate');
+    if (rate) cfg.sampleRate = Number(rate);
+    // Identity is usually set later via Obsrviq.identify() (post-login), but can be
+    // seeded here when known at load time.
+    const userId = current.getAttribute('data-obsrviq-user-id');
+    if (userId) cfg.userId = userId;
+    const metaAttr = current.getAttribute('data-obsrviq-metadata');
+    if (metaAttr) {
+      try {
+        cfg.metadata = JSON.parse(metaAttr) as Record<string, unknown>;
+      } catch {
+        console.warn('[obsrviq] data-obsrviq-metadata is not valid JSON — ignored.');
+      }
+    }
+    Obsrviq.init(cfg);
+  }
+}
+
+window.Obsrviq = Obsrviq;
+
+export { Obsrviq };