@obsrviq/tracker 0.3.0

package/src/index.ts

@@ -0,0 +1,436 @@
+import type { IngestSessionMeta, ObsrviqEvent, ObsrviqInitConfig } from '@obsrviq/types';
+import type { InstrumentCtx, ResolvedConfig, Teardown } from './context.js';
+import { Transport } from './transport.js';
+import { instrumentDom } from './recorder.js';
+import { instrumentConsole } from './console.js';
+import { instrumentNetwork } from './network.js';
+import { instrumentErrors } from './errors.js';
+import { instrumentVitals } from './vitals.js';
+import { instrumentInteractions } from './interactions.js';
+import { instrumentForms } from './forms.js';
+import { instrumentScrollDepth } from './scroll.js';
+import { instrumentPageviews } from './pageviews.js';
+import { showConsent, showRecordingDot } from './ui.js';
+import { clearSession, readSession, registerVisit, writeSession } from './storage.js';
+import { Clock, detectDevice, privacySignalsOptOut, sha256Hex, uuid } from './util.js';
+
+const DEFAULTS = {
+  maskAllInputs: true,
+  blockSelector: '.obsrviq-block',
+  noPrivacy: false,
+  captureNetworkBodies: false,
+  redactHeaders: ['authorization', 'cookie', 'set-cookie'],
+  sampleRate: 1.0,
+  recordCanvas: false,
+  endpoint: 'https://in.lumera.app',
+  flushIntervalMs: 5000,
+  continueSession: false,
+  sessionTimeoutMs: 30 * 60 * 1000,
+  requireConsent: false,
+  askPermission: false,
+  showRecording: false,
+  maxArgBytes: 8 * 1024,
+};
+
+export interface Diagnostics {
+  recording: boolean;
+  sessionId: string | null;
+  flushes: number;
+  bytesSent: number;
+  eventsSent: number;
+  eventsQueued: number;
+}
+
+class ObsrviqClient {
+  private config: ResolvedConfig | null = null;
+  private clock: Clock | null = null;
+  private transport: Transport | null = null;
+  private teardowns: Teardown[] = [];
+  private meta: IngestSessionMeta | null = null;
+  private recording = false;
+  private consent: boolean | null = null;
+  private sampledIn = true;
+  private lastActivity = 0;
+  /** The userId this session is attributed to (for the shared-device split). */
+  private currentUserId: string | undefined;
+  /** Next batch seq — mirrored from the transport so we can persist continuation. */
+  private nextSeq = 0;
+  /** Open task spans keyed by task name → the span id + start time, so endTask()
+   *  can pair with its startTask(). Re-starting the same name supersedes the
+   *  earlier open span (the player pairs by spanId, so this only affects which
+   *  start an unqualified end() resolves to). */
+  private openTasks = new Map<string, { spanId: string; startT: number }>();
+  private consentUnmount: (() => void) | null = null;
+  private recDotUnmount: (() => void) | null = null;
+  private diag: Diagnostics = {
+    recording: false,
+    sessionId: null,
+    flushes: 0,
+    bytesSent: 0,
+    eventsSent: 0,
+    eventsQueued: 0,
+  };
+
+  /** The current session id (null until init). */
+  get sessionId(): string | null {
+    return this.diag.sessionId;
+  }
+
+  init(config: ObsrviqInitConfig): void {
+    if (this.config) return; // idempotent
+    if (!config.siteKey) {
+      console.warn('[obsrviq] init() called without siteKey — recording disabled.');
+      return;
+    }
+    this.config = { ...DEFAULTS, ...stripUndefined(config) } as ResolvedConfig;
+    // No-privacy: record input values verbatim by unmasking inputs — but only if
+    // the host didn't set maskAllInputs explicitly (their choice always wins).
+    // Page text is already verbatim unless maskTextSelector is set. Passwords stay
+    // masked via the recorder's maskInputOptions floor.
+    if (this.config.noPrivacy && config.maskAllInputs === undefined) {
+      this.config.maskAllInputs = false;
+    }
+    // askPermission = "show a built-in consent prompt"; it implies a consent gate.
+    if (this.config.askPermission) this.config.requireConsent = true;
+
+    this.startSession();
+
+    // Init-time identity (rarely known this early — usually set later via identify()).
+    if (config.userId != null) this.applyUserId(config.userId);
+    if (config.metadata && this.meta) this.meta.metadata = { ...config.metadata };
+
+    // GPC / DNT always wins → no recording, no UI (R-1).
+    if (privacySignalsOptOut()) {
+      this.consent = false;
+      return;
+    }
+
+    if (this.config.requireConsent) {
+      // Built-in prompt, if asked; otherwise the host calls setConsent(true) itself.
+      if (this.config.askPermission) {
+        this.consentUnmount = showConsent(
+          this.config.blockSelector,
+          this.config.consentText,
+          () => this.setConsent(true),
+          () => this.setConsent(false),
+        );
+      }
+    } else {
+      this.maybeStart();
+    }
+  }
+
+  /** (Re)create the session id, clock, meta, and transport. Used by init() and
+   *  reset(). Does not start recording — callers decide via maybeStart().
+   *  @param seedInitUser seed identity from the init-time `cfg.userId`. True for
+   *  the initial init() session; FALSE for reset() (logout) — otherwise the fresh
+   *  post-logout session would be re-attributed to the user who just logged out. */
+  private startSession(seedInitUser = true): void {
+    const cfg = this.config!;
+    // Session continuation (opt-in): resume the same session for a same-device
+    // return within the inactivity window — but NOT when a different known user is
+    // at the device (the shared-device split). A resumed session keeps recording
+    // regardless of sampling (it was already sampled in).
+    const now = Date.now();
+    let resume: ReturnType<typeof readSession> = null;
+    if (cfg.continueSession) {
+      const rec = readSession();
+      if (
+        rec &&
+        now - rec.lastActivity < cfg.sessionTimeoutMs &&
+        !(cfg.userId != null && rec.userId != null && rec.userId !== String(cfg.userId))
+      ) {
+        resume = rec;
+      }
+    }
+    const sessionId = resume ? resume.id : uuid();
+    this.clock = resume ? new Clock(resume.startedAt, resume.lastT) : new Clock();
+    this.currentUserId =
+      resume?.userId ?? (seedInitUser && cfg.userId != null ? String(cfg.userId) : undefined);
+    this.nextSeq = resume ? resume.seq : 0;
+    this.diag.sessionId = sessionId;
+    this.meta = {
+      startedAt: this.clock.startedAt,
+      entryUrl: location.href,
+      device: detectDevice(),
+    };
+    // Sampling decision for the whole session — a resumed one stays in.
+    this.sampledIn = resume ? true : Math.random() < (cfg.sampleRate ?? 1);
+    this.transport = new Transport({
+      endpoint: cfg.endpoint,
+      siteKey: cfg.siteKey,
+      sessionId,
+      getMeta: () => this.meta ?? undefined,
+      beforeSend: cfg.beforeSend,
+      flushIntervalMs: cfg.flushIntervalMs,
+      startSeq: this.nextSeq,
+      onSeqDispatch: (next) => {
+        this.nextSeq = next;
+        this.persistSession();
+      },
+      onFlush: ({ bytes, events, ok }) => {
+        if (ok) {
+          this.diag.flushes++;
+          this.diag.bytesSent += bytes;
+          this.diag.eventsSent += events;
+        }
+      },
+    });
+    this.recording = false;
+    this.diag.recording = false;
+  }
+
+  /** Persist the session-continuation record (no-op unless continueSession). Only
+   *  ever writes for a RECORDING session — a sampled-out or pre-consent session must
+   *  not leave a record that a later page would resume (and force back into
+   *  recording), and identify() can fire before recording starts. */
+  private persistSession(): void {
+    if (!this.config?.continueSession || !this.recording || !this.clock || !this.diag.sessionId) return;
+    writeSession({
+      id: this.diag.sessionId,
+      startedAt: this.clock.startedAt,
+      lastActivity: Date.now(),
+      seq: this.nextSeq,
+      lastT: this.clock.now(),
+      userId: this.currentUserId,
+    });
+  }
+
+  private maybeStart(): void {
+    if (this.recording || !this.config || !this.clock || !this.transport) return;
+    if (this.config.requireConsent && this.consent !== true) return;
+    if (this.consent === false) return;
+    if (!this.sampledIn) return;
+
+    // Returning-visitor identity: now that consent is granted and we're about to
+    // record, read-or-create the persistent (anonymous) visitor record and stamp
+    // it onto the session meta. Guarded internally — never blocks recording.
+    if (this.meta && this.meta.visitorId == null) {
+      const visit = registerVisit(Date.now());
+      this.meta.visitorId = visit.id;
+      this.meta.visitCount = visit.visits;
+      this.meta.firstSeenAt = visit.firstSeenAt;
+    }
+
+    const ctx: InstrumentCtx = {
+      clock: this.clock,
+      sessionId: this.diag.sessionId!,
+      config: this.config,
+      emit: (e: ObsrviqEvent) => {
+        this.transport!.enqueue(e);
+        this.diag.eventsQueued++;
+      },
+      markActivity: () => {
+        this.lastActivity = this.clock!.now();
+      },
+      lastActivityT: () => this.lastActivity,
+    };
+
+    this.transport.start();
+    // Order matters slightly: network/console wrappers should be installed
+    // before app code runs more requests; DOM last so its snapshot is current.
+    this.teardowns.push(instrumentConsole(ctx));
+    this.teardowns.push(instrumentNetwork(ctx));
+    this.teardowns.push(instrumentErrors(ctx));
+    this.teardowns.push(instrumentVitals(ctx));
+    this.teardowns.push(instrumentInteractions(ctx));
+    this.teardowns.push(instrumentForms(ctx));
+    this.teardowns.push(instrumentScrollDepth(ctx));
+    this.teardowns.push(instrumentPageviews(ctx));
+    this.teardowns.push(instrumentDom(ctx));
+
+    this.recording = true;
+    this.diag.recording = true;
+
+    // Now that we're actually recording, anchor the continuation record so a next
+    // page can resume this (and ONLY a recording) session, even before any flush.
+    this.persistSession();
+
+    // Transparency: optional visible "recording" indicator.
+    if (this.config.showRecording && !this.recDotUnmount) {
+      this.recDotUnmount = showRecordingDot(this.config.blockSelector);
+    }
+  }
+
+  /** Associate the session with an application user. Stores the RAW userId (for
+   *  search + display) AND a SHA-256 identityHash, merges any traits into metadata,
+   *  and force-flushes so the live session is retro-stamped promptly. Safe to call
+   *  before recording starts (values ride the first batch) and after login. */
+  identify(userId: string, traits?: Record<string, unknown>): void {
+    if (!this.meta) return;
+    const uid = String(userId);
+    // Shared-device split: if this session is already attributed to a DIFFERENT
+    // user (continueSession only), rotate to a fresh session so two people never
+    // merge into one. reset() clears the continuation record so it can't resume
+    // the prior user. (Same user, or first identify on the session → no split.)
+    if (this.config?.continueSession && this.currentUserId != null && this.currentUserId !== uid) {
+      this.reset();
+    }
+    this.currentUserId = uid;
+    this.applyUserId(uid);
+    if (traits) this.mergeMetadata(traits);
+    // track() emits an event only while recording — which also guarantees the
+    // next flush is non-empty so the updated meta actually ships (empty buffers
+    // are skipped by transport.flush()).
+    this.track('identify', { hasTraits: !!traits });
+    void this.flush();
+    // Stamp the userId onto the continuation record so the next page knows it.
+    this.persistSession();
+  }
+
+  /** Merge custom properties onto the session at any time (searchable server-side). */
+  setMetadata(props: Record<string, unknown>): void {
+    if (!this.meta) return;
+    this.mergeMetadata(props);
+    this.track('metadata', { keys: Object.keys(props) });
+    void this.flush();
+  }
+
+  /** Forget the current identity (e.g. on logout) and rotate to a fresh anonymous
+   *  session, so post-logout activity isn't attributed to the prior user. (Identity
+   *  can't be cleared on the existing row — the server merge only fills nulls — so
+   *  we start a new session instead.) */
+  reset(): void {
+    if (!this.config) return;
+    const wasRecording = this.recording;
+    if (this.recording) this.teardown(); // flushes the old session's final batch
+    // An explicit reset (logout / user switch) must NEVER resume the prior
+    // session — drop the continuation record so startSession() begins fresh.
+    clearSession();
+    this.currentUserId = undefined;
+    // Fresh session must stay anonymous — do NOT re-seed the init-time userId, or a
+    // post-logout session would be re-attributed to the user who just logged out.
+    this.startSession(false);
+    if (wasRecording && this.consent !== false && !privacySignalsOptOut()) this.maybeStart();
+  }
+
+  /** Set the raw userId on meta and compute its hash (async). */
+  private applyUserId(userId: string): void {
+    const raw = String(userId);
+    if (this.meta) this.meta.userId = raw;
+    void sha256Hex(raw).then((hash) => {
+      if (this.meta && this.meta.userId === raw) this.meta.identityHash = hash;
+    });
+  }
+
+  private mergeMetadata(props: Record<string, unknown>): void {
+    if (!this.meta) return;
+    this.meta.metadata = { ...(this.meta.metadata ?? {}), ...props };
+  }
+
+  /** Emit a custom event (e.g. conversions). */
+  track(name: string, props?: Record<string, unknown>): void {
+    if (!this.recording || !this.clock || !this.transport) return;
+    this.transport.enqueue({
+      id: uuid(),
+      sessionId: this.diag.sessionId!,
+      type: 'custom',
+      t: this.clock.now(),
+      ts: this.clock.wall(),
+      name,
+      props,
+    });
+    this.diag.eventsQueued++;
+  }
+
+  /** Mark a conversion. Conversion is client-defined, so the NAME matters —
+   *  "checkout", "signup", "trial_started" — and each is denormalised onto the
+   *  session for per-client filtering. Sets props.conversion so the legacy
+   *  'conversion' flag still lights up. Sugar over track(name, {conversion:true}). */
+  conversion(name: string, props?: Record<string, unknown>): void {
+    const clean = String(name).trim();
+    if (!clean) return;
+    this.track(clean, { ...props, conversion: true });
+  }
+
+  /** Attach one or more free-form, searchable labels to the current session.
+   *  Tags are session-level (deduped server-side) — use them to slice sessions
+   *  however a client likes ("vip", "ab_variant_b", "mobile_app"). */
+  tag(...names: string[]): void {
+    const clean = names.map((n) => String(n).trim()).filter(Boolean);
+    if (!clean.length) return;
+    this.track('_tag', { tags: clean });
+    void this.flush();
+  }
+
+  /** Begin a named sub-event span. Pairs with end() / endTask(name) to produce a
+   *  searchable, duration-bearing span on the session timeline. Returns a handle
+   *  so callers can `const t = Obsrviq.startTask('checkout'); …; t.end()`. */
+  startTask(name: string, props?: Record<string, unknown>): { end: (endProps?: Record<string, unknown>) => void } {
+    const clean = String(name).trim();
+    const spanId = uuid();
+    const startT = this.clock ? this.clock.now() : 0;
+    if (clean) {
+      this.openTasks.set(clean, { spanId, startT });
+      this.track(`${clean}:started`, { ...props, spanId, task: clean });
+    }
+    return { end: (endProps?: Record<string, unknown>) => this.endTask(clean, endProps) };
+  }
+
+  /** Close a named sub-event span opened by startTask(name). Safe to call even
+   *  if the start was never seen (renders as an orphan end on the timeline). */
+  endTask(name: string, props?: Record<string, unknown>): void {
+    const clean = String(name).trim();
+    if (!clean) return;
+    const open = this.openTasks.get(clean);
+    this.openTasks.delete(clean);
+    const spanId = open?.spanId ?? uuid();
+    this.track(`${clean}:ended`, {
+      ...props,
+      spanId,
+      task: clean,
+      ...(open ? { startT: open.startT } : {}),
+    });
+  }
+
+  /** Gate recording (PRIV-2). true starts; false stops + flushes. Dismisses the
+   *  built-in consent prompt if one is showing. */
+  setConsent(granted: boolean): void {
+    this.consent = granted;
+    this.consentUnmount?.();
+    this.consentUnmount = null;
+    if (granted) this.maybeStart();
+    else if (this.recording) this.teardown();
+  }
+
+  /** Hard stop + flush. */
+  stop(): void {
+    this.teardown();
+  }
+
+  /** Force a flush now (returns when send is attempted). */
+  flush(): Promise<boolean> {
+    return this.transport ? this.transport.flush('manual') : Promise.resolve(true);
+  }
+
+  getDiagnostics(): Diagnostics {
+    return { ...this.diag };
+  }
+
+  private teardown(): void {
+    for (const t of this.teardowns.splice(0)) {
+      try {
+        t();
+      } catch {
+        /* ignore */
+      }
+    }
+    this.recDotUnmount?.();
+    this.recDotUnmount = null;
+    this.transport?.stop();
+    this.recording = false;
+    this.diag.recording = false;
+  }
+}
+
+function stripUndefined<T extends object>(obj: T): Partial<T> {
+  const out: Partial<T> = {};
+  for (const [k, v] of Object.entries(obj)) {
+    if (v !== undefined) (out as Record<string, unknown>)[k] = v;
+  }
+  return out;
+}
+
+export const Obsrviq = new ObsrviqClient();
+export type { ObsrviqInitConfig } from '@obsrviq/types';
+export default Obsrviq;

package/src/interactions.ts

@@ -0,0 +1,70 @@
+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';
+
+const RAGE_WINDOW_MS = 1000;
+const RAGE_THRESHOLD = 3;
+const DEAD_WAIT_MS = 3000;
+
+function isInteractive(el: Element | null): boolean {
+  if (!el) return false;
+  let node: Element | null = el;
+  for (let i = 0; i < 4 && node; i++) {
+    const tag = node.tagName.toLowerCase();
+    if (['a', 'button', 'input', 'select', 'textarea', 'label', 'summary'].includes(tag))
+      return true;
+    if (node.getAttribute('role') === 'button' || node.hasAttribute('onclick')) return true;
+    if (node.getAttribute('contenteditable') === 'true') return true;
+    node = node.parentElement;
+  }
+  return false;
+}
+
+export function instrumentInteractions(ctx: InstrumentCtx): Teardown {
+  let recent: { el: Element; t: number }[] = [];
+  let lastRageAt = -Infinity;
+
+  const emitCustom = (name: string, props: Record<string, unknown>, t: number) => {
+    const e: ObsrviqCustomEvent = {
+      id: uuid(),
+      sessionId: ctx.sessionId,
+      type: 'custom',
+      t,
+      ts: ctx.clock.wall(),
+      name,
+      props,
+    };
+    ctx.emit(e);
+  };
+
+  const onClick = (ev: MouseEvent) => {
+    const target = ev.target as Element | null;
+    if (!target || !(target instanceof Element)) return;
+    const t = ctx.clock.now();
+    const selector = cssPath(target);
+
+    // ── Rage click detection ──
+    recent = recent.filter((r) => t - r.t <= RAGE_WINDOW_MS);
+    recent.push({ el: target, t });
+    const sameTarget = recent.filter((r) => r.el === target);
+    if (sameTarget.length >= RAGE_THRESHOLD && t - lastRageAt > RAGE_WINDOW_MS) {
+      lastRageAt = t;
+      emitCustom('rage_click', { selector, count: sameTarget.length }, t);
+    }
+
+    // ── Dead click detection ──
+    if (!isInteractive(target)) {
+      const before = ctx.lastActivityT();
+      window.setTimeout(() => {
+        // No app activity (mutation/nav/network) after the click → dead.
+        if (ctx.lastActivityT() <= Math.max(before, t)) {
+          emitCustom('dead_click', { selector }, t);
+        }
+      }, DEAD_WAIT_MS);
+    }
+  };
+
+  window.addEventListener('click', onClick, true);
+  return () => window.removeEventListener('click', onClick, true);
+}

package/src/mask.ts

@@ -0,0 +1,42 @@
+// Masking pipeline (PRIV). Applied to console args and network bodies before
+// anything leaves the page. Heuristics catch the obvious PII; tenants tighten
+// with maskTextSelector / beforeSend.
+
+const EMAIL = /[a-z0-9._%+-]+@[a-z0-9.-]+\.[a-z]{2,}/gi;
+const CC = /\b(?:\d[ -]*?){13,19}\b/g; // candidate card numbers
+const SSN = /\b\d{3}-\d{2}-\d{4}\b/g;
+const LONG_DIGITS = /\b\d{9,}\b/g; // phone-ish / account-ish
+
+// Keys whose values we always redact regardless of content.
+const SENSITIVE_KEYS =
+  /(pass(word)?|secret|token|api[-_]?key|authorization|cookie|ssn|card|cvv|pin|otp)/i;
+
+export function maskString(input: string): string {
+  return input
+    .replace(EMAIL, '«email»')
+    .replace(CC, (m) => (luhnish(m) ? '«card»' : m))
+    .replace(SSN, '«ssn»')
+    .replace(LONG_DIGITS, '«number»');
+}
+
+function luhnish(s: string): boolean {
+  const digits = s.replace(/\D/g, '');
+  return digits.length >= 13 && digits.length <= 19;
+}
+
+export function isSensitiveKey(key: string): boolean {
+  return SENSITIVE_KEYS.test(key);
+}
+
+/** Recursively mask an object's string values and sensitive keys. */
+export function maskValue(value: unknown, depth = 0): unknown {
+  if (depth > 6) return '«depth»';
+  if (typeof value === 'string') return maskString(value);
+  if (value === null || typeof value !== 'object') return value;
+  if (Array.isArray(value)) return value.map((v) => maskValue(v, depth + 1));
+  const out: Record<string, unknown> = {};
+  for (const [k, v] of Object.entries(value as Record<string, unknown>)) {
+    out[k] = isSensitiveKey(k) ? '«redacted»' : maskValue(v, depth + 1);
+  }
+  return out;
+}