@obsrviq/tracker 0.3.0

package/src/serialize.ts

@@ -0,0 +1,120 @@
+import type { SerializedArg } from '@obsrviq/types';
+import { maskString, maskValue } from './mask.js';
+
+const DEFAULT_MAX_BYTES = 8 * 1024; // 8 KB string cap (§6.1)
+
+function byteLen(s: string): number {
+  return new Blob([s]).size;
+}
+
+function truncate(s: string, maxBytes: number): { value: string; truncated: boolean } {
+  if (byteLen(s) <= maxBytes) return { value: s, truncated: false };
+  // Cheap char-based cut; good enough for previews.
+  const approx = Math.max(16, Math.floor(maxBytes * 0.95));
+  return { value: s.slice(0, approx), truncated: true };
+}
+
+/** Serialize a single console/track argument into a SerializedArg (§4, §6.1). */
+export function serializeArg(arg: unknown, maxBytes = DEFAULT_MAX_BYTES): SerializedArg {
+  if (arg === null) return { kind: 'primitive', value: null };
+  const type = typeof arg;
+
+  if (type === 'number' || type === 'boolean') {
+    return { kind: 'primitive', value: arg as number | boolean };
+  }
+
+  if (type === 'string') {
+    const masked = maskString(arg as string);
+    const { value, truncated } = truncate(masked, maxBytes);
+    return { kind: 'string', value, truncated };
+  }
+
+  if (arg instanceof Error) {
+    return {
+      kind: 'error',
+      name: arg.name,
+      message: maskString(arg.message),
+      stack: arg.stack ? maskString(arg.stack) : undefined,
+    };
+  }
+
+  if (arg instanceof Element) {
+    return { kind: 'dom', selector: cssPath(arg) };
+  }
+
+  if (type === 'object' || type === 'function' || type === 'symbol' || type === 'bigint') {
+    const masked = maskValue(arg);
+    let json: string | undefined;
+    let truncated = false;
+    try {
+      const full = JSON.stringify(masked, safeReplacer());
+      const cut = truncate(full ?? 'undefined', maxBytes);
+      json = cut.value;
+      truncated = cut.truncated;
+    } catch {
+      json = undefined;
+    }
+    return { kind: 'object', preview: previewOf(masked), json, truncated };
+  }
+
+  // undefined / fallback
+  return { kind: 'primitive', value: String(arg) };
+}
+
+function safeReplacer() {
+  const seen = new WeakSet();
+  return (_key: string, value: unknown) => {
+    if (typeof value === 'bigint') return `${value.toString()}n`;
+    if (typeof value === 'function') return `ƒ ${(value as { name?: string }).name || 'anonymous'}`;
+    if (typeof value === 'object' && value !== null) {
+      if (seen.has(value)) return '«circular»';
+      seen.add(value);
+    }
+    return value;
+  };
+}
+
+function previewOf(value: unknown): string {
+  if (Array.isArray(value)) return `Array(${value.length})`;
+  if (value && typeof value === 'object') {
+    const keys = Object.keys(value as object);
+    const head = keys.slice(0, 4).join(', ');
+    return `{ ${head}${keys.length > 4 ? ', …' : ''} }`;
+  }
+  return String(value);
+}
+
+/** A short, stable CSS-ish selector for a DOM node (no PII). */
+export function cssPath(el: Element): string {
+  const parts: string[] = [];
+  let node: Element | null = el;
+  let depth = 0;
+  while (node && node.nodeType === 1 && depth < 5) {
+    let part = node.tagName.toLowerCase();
+    if (node.id) {
+      part += `#${node.id}`;
+      parts.unshift(part);
+      break;
+    }
+    const cls = (node.getAttribute('class') || '').trim().split(/\s+/).filter(Boolean)[0];
+    if (cls) part += `.${cls}`;
+    parts.unshift(part);
+    node = node.parentElement;
+    depth++;
+  }
+  return parts.join(' > ');
+}
+
+/** Parse the top frame of a stack into a source location. */
+export function parseSource(stack?: string): { url?: string; line?: number; col?: number } | undefined {
+  if (!stack) return undefined;
+  const lines = stack.split('\n').map((l) => l.trim());
+  for (const line of lines) {
+    const m =
+      line.match(/\((https?:\/\/[^)]+):(\d+):(\d+)\)/) ||
+      line.match(/at (https?:\/\/\S+):(\d+):(\d+)/) ||
+      line.match(/(https?:\/\/\S+):(\d+):(\d+)/);
+    if (m) return { url: m[1], line: Number(m[2]), col: Number(m[3]) };
+  }
+  return undefined;
+}

package/src/storage.ts

@@ -0,0 +1,131 @@
+/**
+ * Returning-visitor tracking.
+ *
+ * A single persistent, ANONYMOUS visitor record in localStorage (no PII — just a
+ * random id + counters) lets the backend tell first-time from returning visitors
+ * and stitch a person's repeat visits together. Written only after consent (the
+ * caller gates this), and fully guarded for SSR / private-mode / disabled storage
+ * — visitor tracking silently no-ops rather than ever throwing.
+ */
+import { uuid } from './util.js';
+
+const VISITOR_KEY = 'obsrviq.visitor';
+const SESSION_KEY = 'obsrviq.session';
+
+/** Persisted across page loads so a returning visit within the inactivity window
+ *  can RESUME the same session (opt-in `continueSession`). Same-origin localStorage
+ *  only — graceful no-op when unavailable (→ per-page sessions, today's default). */
+export interface SessionRecord {
+  /** The session id to continue. */
+  id: string;
+  /** Epoch ms the (original) session started — the stable clock anchor. */
+  startedAt: number;
+  /** Epoch ms of the last activity (flush) — the inactivity-gap reference. */
+  lastActivity: number;
+  /** Next batch seq to send (kept monotonic across page loads → no chunk-key
+   *  collision on the (session_id, seq) primary key). */
+  seq: number;
+  /** Highest event `t` (ms since session start) reached so far — used as a floor
+   *  for the resumed clock so the next page's timestamps never overlap the prior
+   *  page's, even if the wall clock moves backward between loads. */
+  lastT?: number;
+  /** The userId this session is attributed to, if any — so a DIFFERENT user on a
+   *  shared device starts a fresh session instead of merging. */
+  userId?: string;
+}
+
+export function readSession(): SessionRecord | null {
+  const raw = readLS(SESSION_KEY);
+  if (!raw) return null;
+  try {
+    const p = JSON.parse(raw) as Partial<SessionRecord>;
+    if (p && typeof p.id === 'string' && p.id && typeof p.startedAt === 'number') {
+      return {
+        id: p.id,
+        startedAt: p.startedAt,
+        lastActivity: typeof p.lastActivity === 'number' ? p.lastActivity : p.startedAt,
+        seq: typeof p.seq === 'number' && p.seq >= 0 ? p.seq : 0,
+        lastT: typeof p.lastT === 'number' && p.lastT >= 0 ? p.lastT : undefined,
+        userId: typeof p.userId === 'string' ? p.userId : undefined,
+      };
+    }
+  } catch {
+    /* corrupted — treat as none */
+  }
+  return null;
+}
+
+export function writeSession(rec: SessionRecord): void {
+  writeLS(SESSION_KEY, JSON.stringify(rec));
+}
+
+export function clearSession(): void {
+  if (typeof window === 'undefined') return;
+  try {
+    window.localStorage.removeItem(SESSION_KEY);
+  } catch {
+    /* ignore */
+  }
+}
+
+export interface VisitorRecord {
+  /** Stable anonymous id for this browser. */
+  id: string;
+  /** Epoch ms first ever seen. */
+  firstSeenAt: number;
+  /** Epoch ms of the most recent visit (this one, after registerVisit). */
+  lastSeenAt: number;
+  /** Lifetime visit count, including the current visit. */
+  visits: number;
+}
+
+function readLS(key: string): string | null {
+  if (typeof window === 'undefined') return null;
+  try {
+    return window.localStorage.getItem(key);
+  } catch {
+    return null; // private mode / disabled / sandboxed
+  }
+}
+
+function writeLS(key: string, value: string): void {
+  if (typeof window === 'undefined') return;
+  try {
+    window.localStorage.setItem(key, value);
+  } catch {
+    /* quota / disabled — visitor tracking degrades to per-session */
+  }
+}
+
+/**
+ * Read-or-create the visitor record and register the current visit (increments
+ * the count, stamps lastSeenAt). Returns the snapshot for THIS session: a fresh
+ * record has visits === 1 (first-time visitor); an existing one has visits > 1
+ * (returning). Never throws.
+ */
+export function registerVisit(now: number): VisitorRecord {
+  let rec: VisitorRecord | null = null;
+  const raw = readLS(VISITOR_KEY);
+  if (raw) {
+    try {
+      const p = JSON.parse(raw) as Partial<VisitorRecord>;
+      if (p && typeof p.id === 'string' && p.id) {
+        rec = {
+          id: p.id,
+          firstSeenAt: typeof p.firstSeenAt === 'number' ? p.firstSeenAt : now,
+          lastSeenAt: typeof p.lastSeenAt === 'number' ? p.lastSeenAt : now,
+          visits: typeof p.visits === 'number' && p.visits > 0 ? p.visits : 1,
+        };
+      }
+    } catch {
+      /* corrupted JSON — fall through and regenerate */
+    }
+  }
+
+  const next: VisitorRecord = rec
+    ? { ...rec, visits: rec.visits + 1, lastSeenAt: now }
+    : { id: uuid(), firstSeenAt: now, lastSeenAt: now, visits: 1 };
+
+  writeLS(VISITOR_KEY, JSON.stringify(next));
+  return next;
+}

package/src/transport.ts

@@ -0,0 +1,181 @@
+import { gzipSync } from 'fflate';
+import type { IngestBatch, IngestSessionMeta, ObsrviqEvent } from '@obsrviq/types';
+
+export interface TransportOptions {
+  endpoint: string;
+  siteKey: string;
+  sessionId: string;
+  getMeta: () => IngestSessionMeta | undefined;
+  beforeSend?: (batch: IngestBatch) => IngestBatch | null;
+  flushIntervalMs: number;
+  /** Resume seq from here (continued session); defaults to 0. Keeps the chunk
+   *  (session_id, seq) key monotonic across page loads. */
+  startSeq?: number;
+  /** Called at DISPATCH (before the network await) with the NEXT seq to use — lets
+   *  the host persist progress synchronously so a later page load resumes without a
+   *  seq collision even if an unload interrupts the in-flight request. */
+  onSeqDispatch?: (nextSeq: number) => void;
+  /** test/observability hook */
+  onFlush?: (info: { bytes: number; events: number; ok: boolean }) => void;
+}
+
+const MAX_BUFFER_EVENTS = 5000; // backpressure cap (R-5)
+
+export class Transport {
+  private buffer: ObsrviqEvent[] = [];
+  private seq: number;
+  private timer: ReturnType<typeof setInterval> | undefined;
+  private sending = false;
+  private retryDelay = 1000;
+  private stopped = false;
+
+  constructor(private opts: TransportOptions) {
+    this.seq = opts.startSeq ?? 0;
+  }
+
+  start() {
+    this.timer = setInterval(() => void this.flush('timer'), this.opts.flushIntervalMs);
+    document.addEventListener('visibilitychange', this.onVisibility, { capture: true });
+    window.addEventListener('pagehide', this.onPageHide, { capture: true });
+  }
+
+  enqueue(event: ObsrviqEvent) {
+    if (this.stopped) return;
+    this.buffer.push(event);
+    // Backpressure: if we've buffered a lot, flush early; if still over after a
+    // failed flush, drop the oldest DOM events (keep structured signal).
+    if (this.buffer.length >= MAX_BUFFER_EVENTS) {
+      void this.flush('backpressure');
+      if (this.buffer.length >= MAX_BUFFER_EVENTS) {
+        this.buffer = this.buffer.filter((e, i) => e.type !== 'dom' || i % 2 === 0);
+      }
+    }
+  }
+
+  /** Build, compress, and send the current buffer. Returns true on success. */
+  async flush(reason: 'timer' | 'hidden' | 'pagehide' | 'manual' | 'backpressure'): Promise<boolean> {
+    if (this.sending || this.buffer.length === 0) return true;
+    this.sending = true;
+    const events = this.buffer;
+    this.buffer = [];
+
+    let batch: IngestBatch | null = {
+      siteKey: this.opts.siteKey,
+      sessionId: this.opts.sessionId,
+      seq: this.seq,
+      meta: this.opts.getMeta(),
+      events,
+    };
+    if (this.opts.beforeSend) {
+      try {
+        batch = this.opts.beforeSend(batch);
+      } catch {
+        batch = null;
+      }
+    }
+    if (!batch) {
+      this.sending = false;
+      return true; // dropped intentionally
+    }
+
+    // Reserve the next seq + stamp activity SYNCHRONOUSLY at dispatch — before any
+    // network await. This is what session continuation persists, so an unload that
+    // interrupts the in-flight request can never let the next page re-use this seq
+    // (which would overwrite a chunk). It also means lastActivity reflects real
+    // dispatch attempts even when the network is down and sends keep failing — so an
+    // active-but-offline session isn't wrongly treated as idle and split.
+    this.opts.onSeqDispatch?.(this.seq + 1);
+
+    const json = JSON.stringify(batch);
+    const gz = gzipSync(new TextEncoder().encode(json));
+    const ok = await this.send(gz, reason === 'pagehide' || reason === 'hidden');
+    this.opts.onFlush?.({ bytes: gz.byteLength, events: events.length, ok });
+
+    if (ok) {
+      this.seq++;
+      this.retryDelay = 1000;
+      this.sending = false;
+      return true;
+    }
+
+    // Failed: re-buffer (capped) and retry with jitter.
+    this.buffer = events.slice(-MAX_BUFFER_EVENTS).concat(this.buffer);
+    this.sending = false;
+    if (!this.stopped) {
+      const jitter = this.retryDelay * (0.5 + Math.random());
+      this.retryDelay = Math.min(this.retryDelay * 2, 30_000);
+      setTimeout(() => void this.flush('timer'), jitter);
+    }
+    return false;
+  }
+
+  private async send(bytes: Uint8Array, unloading: boolean): Promise<boolean> {
+    const url = `${this.opts.endpoint.replace(/\/$/, '')}/v1/batch`;
+    const headers = {
+      'content-type': 'application/octet-stream',
+      'x-obsrviq-key': this.opts.siteKey,
+    };
+    const body = bytes as unknown as BodyInit;
+
+    // Unload path: a normal fetch would be cancelled as the page goes away, so
+    // use sendBeacon (survives navigation) or a keepalive fetch. BOTH cap the
+    // body at ~64KB, so large (snapshot) batches are best-effort here — but the
+    // periodic flushes below send them reliably during normal operation.
+    if (unloading) {
+      const blob = new Blob([bytes as unknown as BlobPart], { type: 'application/octet-stream' });
+      if (typeof navigator.sendBeacon === 'function') {
+        try {
+          if (navigator.sendBeacon(url, blob)) return true;
+        } catch {
+          /* fall through */
+        }
+      }
+      try {
+        void fetch(url, { method: 'POST', body, headers, keepalive: true, credentials: 'omit', mode: 'cors' }).catch(
+          () => {},
+        );
+        return true;
+      } catch {
+        return false;
+      }
+    }
+
+    // Normal flush: a plain fetch — NO `keepalive`, so there's no 64KB body cap
+    // and large FullSnapshot batches actually send. Await the real result so a
+    // failure (rejected / 4xx / 5xx / network) re-buffers and retries instead of
+    // being silently dropped. A timeout aborts a hung request so it can't stall
+    // all future flushes (`sending` stays true until this resolves).
+    const ctrl = new AbortController();
+    const timeout = setTimeout(() => ctrl.abort(), 15_000);
+    try {
+      const res = await fetch(url, {
+        method: 'POST',
+        body,
+        headers,
+        credentials: 'omit',
+        mode: 'cors',
+        signal: ctrl.signal,
+      });
+      return res.ok;
+    } catch {
+      return false;
+    } finally {
+      clearTimeout(timeout);
+    }
+  }
+
+  private onVisibility = () => {
+    if (document.visibilityState === 'hidden') void this.flush('hidden');
+  };
+  private onPageHide = () => {
+    void this.flush('pagehide');
+  };
+
+  stop() {
+    this.stopped = true;
+    if (this.timer) clearInterval(this.timer);
+    document.removeEventListener('visibilitychange', this.onVisibility, { capture: true });
+    window.removeEventListener('pagehide', this.onPageHide, { capture: true });
+    void this.flush('manual');
+  }
+}

package/src/ui.ts

@@ -0,0 +1,182 @@
+/**
+ * Self-contained UI the tracker injects into the host page:
+ *   - showConsent()      — a corner consent card (askPermission)
+ *   - showRecordingDot() — a minimal pulsing "recording" dot (showRecording)
+ *
+ * Isolation rules (the SDK is otherwise headless):
+ *   - attachShadow({mode:'open'}) + adoptedStyleSheets → no host CSS bleed and
+ *     CSP-safe (no inline <style>, so `style-src 'self'` pages don't block it).
+ *   - the host element wears the recorder's block class (default `.obsrviq-block`)
+ *     so the SDK's own rrweb recorder never captures its own UI. The host box is
+ *     zero-size (its children are position:fixed), so no placeholder shows in the
+ *     replay.
+ */
+
+export interface ConsentText {
+  title?: string;
+  body?: string;
+  allow?: string;
+  deny?: string;
+}
+
+/** Derive a class the host can wear so the recorder's blockSelector excludes it.
+ *  blockSelector is usually a class selector (default '.obsrviq-block'). We always
+ *  keep `obsrviq-block` too, so a custom blockSelector can't accidentally un-hide. */
+function blockClassFrom(blockSelector: string): string {
+  const m = /\.([A-Za-z0-9_-]+)/.exec(blockSelector || '');
+  const derived = m && m[1] ? m[1] : '';
+  return ['obsrviq-block', derived].filter(Boolean).join(' ');
+}
+
+function makeHost(blockSelector: string): { host: HTMLElement; root: ShadowRoot } {
+  const host = document.createElement('div');
+  host.className = blockClassFrom(blockSelector);
+  host.setAttribute('data-obsrviq-ui', '');
+  host.style.cssText = 'all:initial';
+  const root = host.attachShadow({ mode: 'open' });
+  return { host, root };
+}
+
+function adopt(root: ShadowRoot, css: string): void {
+  try {
+    const sheet = new CSSStyleSheet();
+    sheet.replaceSync(css);
+    root.adoptedStyleSheets = [sheet];
+  } catch {
+    // Engines without constructable stylesheets — inline <style> inside the shadow
+    // (still isolated; only a concern on host pages with a strict style-src CSP).
+    const style = document.createElement('style');
+    style.textContent = css;
+    root.appendChild(style);
+  }
+}
+
+function mount(host: HTMLElement): void {
+  (document.body || document.documentElement).appendChild(host);
+}
+
+const ACCENT = '#6e76f1';
+
+const CONSENT_CSS = `
+:host { all: initial; }
+.card {
+  position: fixed; bottom: 20px; right: 20px; z-index: 2147483647;
+  max-width: 340px; box-sizing: border-box;
+  display: grid; grid-template-columns: auto 1fr;
+  grid-template-areas: 'dot txt' 'actions actions'; gap: 9px 12px; padding: 16px 18px;
+  font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Helvetica, Arial, sans-serif;
+  color: #f4f5fb; background: #14151b; border: 1px solid rgba(255,255,255,.08);
+  border-radius: 14px; box-shadow: 0 16px 48px rgba(0,0,0,.5);
+  opacity: 0; transform: translateY(10px); transition: opacity .22s ease, transform .22s ease;
+}
+.card.in { opacity: 1; transform: none; }
+.dot { grid-area: dot; width: 9px; height: 9px; margin-top: 5px; border-radius: 50%;
+  background: ${ACCENT}; box-shadow: 0 0 0 4px rgba(110,118,241,.18); }
+.txt { grid-area: txt; min-width: 0; }
+.title { font-size: 13.5px; font-weight: 600; line-height: 1.35; }
+.body { margin-top: 3px; font-size: 12px; line-height: 1.45; color: #a9adbe; }
+.actions { grid-area: actions; display: flex; gap: 8px; justify-content: flex-end; margin-top: 2px; }
+button { font: inherit; font-size: 12.5px; font-weight: 600; padding: 7px 15px; border-radius: 9px;
+  cursor: pointer; border: 1px solid transparent; transition: background .15s ease, color .15s ease; }
+.deny { background: transparent; color: #a9adbe; border-color: rgba(255,255,255,.14); }
+.deny:hover { color: #f4f5fb; background: rgba(255,255,255,.05); }
+.allow { background: ${ACCENT}; color: #fff; }
+.allow:hover { background: #5a62e0; }
+button:focus-visible { outline: 2px solid ${ACCENT}; outline-offset: 2px; }
+@media (prefers-reduced-motion: reduce) { .card { transition: none; } }
+@media (max-width: 480px) { .card { left: 16px; right: 16px; bottom: 16px; max-width: none; } }
+`;
+
+const DOT_CSS = `
+:host { all: initial; }
+.recdot {
+  position: fixed; bottom: 16px; right: 16px; z-index: 2147483647;
+  width: 12px; height: 12px; border-radius: 50%;
+  background: #ef4444; box-shadow: 0 0 0 0 rgba(239,68,68,.5);
+  animation: lum-pulse 2s ease-out infinite;
+}
+@keyframes lum-pulse {
+  0%   { box-shadow: 0 0 0 0 rgba(239,68,68,.5); }
+  70%  { box-shadow: 0 0 0 9px rgba(239,68,68,0); }
+  100% { box-shadow: 0 0 0 0 rgba(239,68,68,0); }
+}
+@media (prefers-reduced-motion: reduce) { .recdot { animation: none; } }
+`;
+
+/** Corner consent card. Resolves via onAllow/onDeny exactly once, then unmounts.
+ *  Returns an unmount fn (e.g. to tear down if consent is set programmatically). */
+export function showConsent(
+  blockSelector: string,
+  text: ConsentText | undefined,
+  onAllow: () => void,
+  onDeny: () => void,
+): () => void {
+  const { host, root } = makeHost(blockSelector);
+  adopt(root, CONSENT_CSS);
+  const t = text ?? {};
+
+  const card = document.createElement('div');
+  card.className = 'card';
+  card.setAttribute('role', 'dialog');
+  card.setAttribute('aria-label', t.title || 'Session recording consent');
+
+  const dot = document.createElement('div');
+  dot.className = 'dot';
+  dot.setAttribute('aria-hidden', 'true');
+
+  const txt = document.createElement('div');
+  txt.className = 'txt';
+  const title = document.createElement('div');
+  title.className = 'title';
+  title.textContent = t.title || 'We record this session to improve the experience.';
+  const body = document.createElement('div');
+  body.className = 'body';
+  body.textContent = t.body || 'No passwords or typed input are captured.';
+  txt.append(title, body);
+
+  const actions = document.createElement('div');
+  actions.className = 'actions';
+  const deny = document.createElement('button');
+  deny.type = 'button';
+  deny.className = 'deny';
+  deny.textContent = t.deny || 'Decline';
+  const allow = document.createElement('button');
+  allow.type = 'button';
+  allow.className = 'allow';
+  allow.textContent = t.allow || 'Allow';
+  actions.append(deny, allow);
+
+  card.append(dot, txt, actions);
+  root.appendChild(card);
+  mount(host);
+  requestAnimationFrame(() => card.classList.add('in'));
+
+  let done = false;
+  const unmount = () => {
+    if (host.parentNode) host.parentNode.removeChild(host);
+  };
+  const choose = (fn: () => void) => () => {
+    if (done) return;
+    done = true;
+    unmount();
+    fn();
+  };
+  allow.addEventListener('click', choose(onAllow));
+  deny.addEventListener('click', choose(onDeny));
+  return unmount;
+}
+
+/** Minimal pulsing "recording" dot (bottom-right). Returns an unmount fn. */
+export function showRecordingDot(blockSelector: string): () => void {
+  const { host, root } = makeHost(blockSelector);
+  adopt(root, DOT_CSS);
+  const dot = document.createElement('div');
+  dot.className = 'recdot';
+  dot.setAttribute('role', 'status');
+  dot.setAttribute('aria-label', 'Session recording in progress');
+  root.appendChild(dot);
+  mount(host);
+  return () => {
+    if (host.parentNode) host.parentNode.removeChild(host);
+  };
+}