@obsrviq/tracker 0.4.0 → 0.4.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@obsrviq/tracker",
-  "version": "0.4.0",
+  "version": "0.4.2",
   "license": "MIT",
   "publishConfig": {
     "access": "public"

package/src/global.ts

@@ -28,27 +28,34 @@ function bool(v: string | null | undefined, fallback: boolean): boolean {
   return v === 'true' || v === '1';
 }
 
+/** Read `data-obsrviq-<name>`, falling back to the pre-rebrand `data-lumera-<name>`
+ *  so old embeds (which still use the Lumera attribute names + filename) keep
+ *  initialising. Mirrors the ingest accepting the legacy x-lumera-key header. */
+function attr(el: HTMLScriptElement, name: string): string | null {
+  return el.getAttribute(`data-obsrviq-${name}`) ?? el.getAttribute(`data-lumera-${name}`);
+}
+
 if (current) {
-  const key = current.getAttribute('data-obsrviq-key');
+  const key = attr(current, '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),
-      autoStart: bool(current.getAttribute('data-obsrviq-auto-start'), true),
+      endpoint: attr(current, 'endpoint') || undefined,
+      maskAllInputs: bool(attr(current, 'mask-inputs'), true),
+      captureNetworkBodies: bool(attr(current, 'capture-bodies'), false),
+      requireConsent: bool(attr(current, 'require-consent'), false),
+      askPermission: bool(attr(current, 'ask-permission'), false),
+      showRecording: bool(attr(current, 'show-recording'), false),
+      recordCanvas: bool(attr(current, 'record-canvas'), false),
+      autoStart: bool(attr(current, 'auto-start'), true),
     };
-    const rate = current.getAttribute('data-obsrviq-sample-rate');
+    const rate = attr(current, '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');
+    const userId = attr(current, 'user-id');
     if (userId) cfg.userId = userId;
-    const metaAttr = current.getAttribute('data-obsrviq-metadata');
+    const metaAttr = attr(current, 'metadata');
     if (metaAttr) {
       try {
         cfg.metadata = JSON.parse(metaAttr) as Record<string, unknown>;
@@ -61,5 +68,7 @@ if (current) {
 }
 
 window.Obsrviq = Obsrviq;
+// Legacy global alias: pre-rebrand embeds call window.Lumera.identify()/track()/etc.
+(window as unknown as { Lumera: typeof Obsrviq }).Lumera = Obsrviq;
 
 export { Obsrviq };

package/src/network.ts

@@ -66,40 +66,205 @@ function bodyPreview(
   };
 }
 
-function enrichTiming(ctx: InstrumentCtx, url: string, base: NetworkTiming): NetworkTiming {
+function perfNow(): number {
+  return typeof performance !== 'undefined' ? performance.now() : 0;
+}
+
+/** Resource Timing `entry.name` is always absolute; requests may be issued with a
+ *  relative URL. Absolutize (query preserved) so the two can be matched. */
+function absUrl(raw: string): string {
   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;
+    return new URL(raw, typeof location !== 'undefined' ? location.href : undefined).href;
   } catch {
-    return base;
+    return raw;
+  }
+}
+
+/** Extract the DNS/TCP/TLS/TTFB/Download breakdown from a matched Resource Timing
+ *  entry, layered onto the SDK-measured `base` (startT/endT/duration). Phases that
+ *  are zero — a reused keep-alive connection, or a cross-origin resource without a
+ *  `Timing-Allow-Origin` header (browser zeroes them for privacy) — are left
+ *  undefined so the player shows "—" rather than a misleading 0. */
+function phasesFrom(m: PerformanceResourceTiming, base: NetworkTiming): NetworkTiming {
+  const t: NetworkTiming = { ...base };
+  const r = (n: number) => Math.round(n);
+  // Every phase is guarded on its START marker being > 0. A cross-origin resource
+  // without `Timing-Allow-Origin` has its start markers (domainLookupStart,
+  // connectStart, secureConnectionStart, requestStart, responseStart) zeroed by the
+  // browser while responseEnd stays real — so a bare `end > start` check would
+  // compute a garbage phase (e.g. download = responseEnd − 0). Requiring start > 0
+  // omits those phases instead.
+  if (m.domainLookupStart > 0 && m.domainLookupEnd > m.domainLookupStart)
+    t.dns = r(m.domainLookupEnd - m.domainLookupStart);
+  if (m.connectStart > 0 && m.connectEnd > m.connectStart) t.tcp = r(m.connectEnd - m.connectStart);
+  if (m.secureConnectionStart > 0 && m.connectEnd > m.secureConnectionStart)
+    t.tls = r(m.connectEnd - m.secureConnectionStart);
+  if (m.requestStart > 0 && m.responseStart > m.requestStart)
+    t.ttfb = r(m.responseStart - m.requestStart);
+  if (m.responseStart > 0 && m.responseEnd > m.responseStart)
+    t.download = r(m.responseEnd - m.responseStart);
+  return t;
+}
+
+/** Pick the Resource Timing entry that best corresponds to a request that started
+ *  at `perfStart` (performance-timeline ms): same URL, started at ~the same time.
+ *  Guards against mis-attributing timing when the same URL is hit repeatedly. */
+function matchEntry(
+  name: string,
+  perfStart: number,
+  entries: PerformanceResourceTiming[],
+): PerformanceResourceTiming | undefined {
+  let best: PerformanceResourceTiming | undefined;
+  let bestDelta = Infinity;
+  for (const e of entries) {
+    if (e.name !== name) continue;
+    if (e.startTime < perfStart - 4) continue; // started before our request → not ours
+    const d = e.startTime - perfStart;
+    if (d < bestDelta) {
+      bestDelta = d;
+      best = e;
+    }
   }
+  return best;
+}
+
+interface PendingTiming {
+  name: string; // absolute URL, to match against PerformanceResourceTiming.name
+  perfStart: number;
+  base: NetworkTiming;
+  resolve: (t: NetworkTiming) => void;
+  timer: ReturnType<typeof setTimeout>;
+}
+
+/** How long to wait for a Resource Timing entry to be published before giving up
+ *  and emitting with duration-only timing. The browser adds the entry to the
+ *  performance buffer *slightly after* fetch/XHR completion, so a synchronous
+ *  lookup at completion almost always misses it — hence this short async wait. */
+const TIMING_WAIT_MS = 300;
+
+interface TimingResolver {
+  resolve(rawUrl: string, perfStart: number, base: NetworkTiming): Promise<NetworkTiming>;
+  flushPending(): void;
+  teardown(): void;
+}
+
+/** Resolves the phase breakdown for a fetch/XHR asynchronously. A single shared
+ *  PerformanceObserver watches for resource entries as they land and settles the
+ *  matching pending request; unmatched requests settle on a short timeout. */
+function createTimingResolver(): TimingResolver {
+  const pending: PendingTiming[] = [];
+  let obs: PerformanceObserver | undefined;
+
+  const stopObs = () => {
+    if (obs) {
+      try {
+        obs.disconnect();
+      } catch {
+        /* ignore */
+      }
+      obs = undefined;
+    }
+  };
+
+  const settle = (p: PendingTiming, t: NetworkTiming) => {
+    const i = pending.indexOf(p);
+    if (i === -1) return; // already settled
+    pending.splice(i, 1);
+    clearTimeout(p.timer);
+    p.resolve(t);
+    if (pending.length === 0) stopObs();
+  };
+
+  const consume = (entries: PerformanceEntryList) => {
+    for (const e of entries as PerformanceResourceTiming[]) {
+      let best: PendingTiming | undefined;
+      let bestDelta = Infinity;
+      for (const p of pending) {
+        if (e.name !== p.name || e.startTime < p.perfStart - 4) continue;
+        const d = e.startTime - p.perfStart;
+        if (d < bestDelta) {
+          bestDelta = d;
+          best = p;
+        }
+      }
+      if (best) settle(best, phasesFrom(e, best.base));
+    }
+  };
+
+  const ensureObserver = () => {
+    if (obs || typeof PerformanceObserver === 'undefined') return;
+    try {
+      obs = new PerformanceObserver((list) => consume(list.getEntries()));
+      obs.observe({ type: 'resource', buffered: false });
+    } catch {
+      obs = undefined;
+    }
+  };
+
+  return {
+    resolve(rawUrl, perfStart, base) {
+      if (typeof performance === 'undefined') return Promise.resolve(base);
+      const name = absUrl(rawUrl);
+      // Fast path: the entry may already be buffered (cached / same-tick resources).
+      try {
+        const now = performance.getEntriesByType('resource') as PerformanceResourceTiming[];
+        const immediate = matchEntry(name, perfStart, now);
+        if (immediate) return Promise.resolve(phasesFrom(immediate, base));
+      } catch {
+        /* ignore */
+      }
+      if (typeof PerformanceObserver === 'undefined') return Promise.resolve(base);
+      // Slow path: wait for the entry to be published (or time out).
+      return new Promise<NetworkTiming>((resolve) => {
+        const p: PendingTiming = {
+          name,
+          perfStart,
+          base,
+          resolve,
+          timer: setTimeout(() => settle(p, base), TIMING_WAIT_MS),
+        };
+        pending.push(p);
+        ensureObserver();
+      });
+    },
+    // Force-settle everything still in flight (with duration-only timing) so their
+    // events are emitted into the transport buffer before an unload beacon fires.
+    flushPending() {
+      for (const p of [...pending]) settle(p, p.base);
+    },
+    teardown() {
+      this.flushPending();
+      stopObs();
+    },
+  };
 }
 
 export function instrumentNetwork(ctx: InstrumentCtx): Teardown {
+  const timing = createTimingResolver();
+  // On page hide, settle any request whose Resource Timing hasn't arrived yet so
+  // its event lands in the transport buffer before the unload flush.
+  const onPageHide = () => timing.flushPending();
+  const onVisibility = () => {
+    if (typeof document !== 'undefined' && document.visibilityState === 'hidden') timing.flushPending();
+  };
+  if (typeof window !== 'undefined') window.addEventListener('pagehide', onPageHide);
+  if (typeof document !== 'undefined') document.addEventListener('visibilitychange', onVisibility);
+
   const teardowns: Teardown[] = [];
-  teardowns.push(wrapFetch(ctx));
-  teardowns.push(wrapXhr(ctx));
+  teardowns.push(wrapFetch(ctx, timing));
+  teardowns.push(wrapXhr(ctx, timing));
   teardowns.push(wrapBeacon(ctx));
   teardowns.push(observeResources(ctx));
+  teardowns.push(() => {
+    if (typeof window !== 'undefined') window.removeEventListener('pagehide', onPageHide);
+    if (typeof document !== 'undefined') document.removeEventListener('visibilitychange', onVisibility);
+    timing.teardown();
+  });
   return () => teardowns.forEach((t) => t());
 }
 
 // ───────────────────────────── fetch ────────────────────────────────
-function wrapFetch(ctx: InstrumentCtx): Teardown {
+function wrapFetch(ctx: InstrumentCtx, tr: TimingResolver): Teardown {
   const orig = window.fetch;
   if (!orig) return () => {};
   window.fetch = async function (input: RequestInfo | URL, init?: RequestInit) {
@@ -107,6 +272,7 @@ function wrapFetch(ctx: InstrumentCtx): Teardown {
     // 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 perfStart = perfNow();
     const method = (init?.method || (input instanceof Request ? input.method : 'GET')).toUpperCase();
     const url = redactUrl(rawUrl);
     const reqHeaders = pickHeaders(
@@ -116,25 +282,29 @@ function wrapFetch(ctx: InstrumentCtx): Teardown {
 
     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);
+      const base: NetworkTiming = { startT, endT, duration: endT - startT };
       ctx.markActivity();
+      // Resolve the phase breakdown asynchronously — the Resource Timing entry is
+      // published just after completion, so a synchronous read would miss it.
+      void tr.resolve(rawUrl, perfStart, base).then((timing) => {
+        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);
+      });
     };
 
     try {
@@ -188,11 +358,12 @@ interface XhrMeta {
   url: string;
   rawUrl: string;
   startT: number;
+  perfStart: number;
   reqHeaders: Record<string, string>;
   body?: string;
 }
 
-function wrapXhr(ctx: InstrumentCtx): Teardown {
+function wrapXhr(ctx: InstrumentCtx, tr: TimingResolver): Teardown {
   const XHR = XMLHttpRequest.prototype;
   const origOpen = XHR.open;
   const origSend = XHR.send;
@@ -206,6 +377,7 @@ function wrapXhr(ctx: InstrumentCtx): Teardown {
       rawUrl,
       url: redactUrl(rawUrl),
       startT: 0,
+      perfStart: 0,
       reqHeaders: {},
     });
     return origOpen.apply(this, [method, url, ...rest] as never);
@@ -226,14 +398,15 @@ function wrapXhr(ctx: InstrumentCtx): Teardown {
     const meta = META.get(this);
     if (meta) {
       meta.startT = ctx.clock.now();
+      meta.perfStart = perfNow();
       if (ctx.config.captureNetworkBodies) meta.body = stringifyBody(body);
       const finish = (error?: string) => {
         const endT = ctx.clock.now();
-        const timing = enrichTiming(ctx, meta.rawUrl, {
+        const base: NetworkTiming = {
           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.
@@ -247,28 +420,32 @@ function wrapXhr(ctx: InstrumentCtx): Teardown {
             /* 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);
+        const responseSize = safeLen(this);
         ctx.markActivity();
+        // Resolve the phase breakdown asynchronously (see wrapFetch).
+        void tr.resolve(meta.rawUrl, meta.perfStart, base).then((timing) => {
+          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,
+            requestBody: ctx.config.captureNetworkBodies ? bodyPreview(meta.body, undefined) : undefined,
+            responseBody,
+            timing,
+            error: error || classifyHttp(status),
+          };
+          ctx.emit(ev);
+        });
       };
       this.addEventListener('loadend', () => finish());
       this.addEventListener('error', () => finish('network'));