@reservamos/browser-analytics 1.1.7 → 1.1.8-alpha.1

package/src/track.ts

@@ -4,10 +4,14 @@ import type {
   EventMetadata,
 } from './types/eventData';
 import botDetectionRelayService from '@/services/botDetectionRelay';
+import { deferBotDetection } from '@/services/deferredBotDetection';
 import fingerprintService from '@/services/fingerprint';
 import geolocationService from '@/services/geolocation';
 import mixpanelService from '@/services/mixpanel';
+import trackingLifecycle from '@/services/trackingLifecycle';
 import validator from '@/services/validator';
+import { createPendingWorkQueue } from '@/util/pendingWork';
+import { snapshotEventData } from '@/util/snapshotEventData';
 
 /**
  * List of events that trigger the fingerprint to be sent with the event. other events will only fetch the cached fingerprint.
@@ -89,12 +93,44 @@ export function trackEventError(
   });
 }
 
-export async function tryTrackEvent(trackEventCallback: () => Promise<void>) {
-  if (mixpanelService.isReady()) {
+/** Waits for one bounded attempt, then consumes callback failures. */
+export async function tryTrackEvent(
+  trackEventCallback: () => Promise<void>,
+  eventName = 'Track Event Error',
+): Promise<void> {
+  if (!mixpanelService.isReady()) {
+    const ready = await new Promise<boolean>((resolve) => {
+      const finish = (isReady: boolean) => {
+        clearTimeout(timer);
+        window.removeEventListener('Tracker Ready', onReady);
+        unsubscribe();
+        resolve(isReady);
+      };
+      const onReady = () => {
+        if (mixpanelService.isReady()) finish(true);
+      };
+      const timer = setTimeout(() => finish(mixpanelService.isReady()), 5000);
+      const unsubscribe = mixpanelService.onReady(onReady);
+      window.addEventListener('Tracker Ready', onReady);
+      onReady();
+    });
+    if (!ready) {
+      console.error('Tracking diagnostic', {
+        eventName,
+        stage: 'readiness',
+        reason: 'timeout',
+      });
+      return;
+    }
+  }
+
+  try {
     await trackEventCallback();
-  } else {
-    window.addEventListener('Tracker Ready', async () => {
-      await trackEventCallback();
+  } catch {
+    console.error('Tracking diagnostic', {
+      eventName,
+      stage: 'submission',
+      reason: 'failed',
     });
   }
 }
@@ -105,33 +141,120 @@ export async function tryTrackEvent(trackEventCallback: () => Promise<void>) {
  * @param {string} eventName - The name of the event to track.
  * @param {object} eventProperties - The properties of the event to track.
  * @param {EventMetadata} meta - Additional metadata to include in the event.
- * @throws {Error} Throws an error if Mixpanel or Fingerprint is not ready.
+ * Retains unsent events for up to sixty seconds without retrying a started submission.
  */
-export async function trackEvent(
+const pendingEvents = createPendingWorkQueue({
+  isReady: () => mixpanelService.isReady(),
+  subscribe(notify) {
+    const stopReady = mixpanelService.onReady(notify);
+    const stopIdentity = trackingLifecycle.onChange(notify);
+    window.addEventListener('Tracker Ready', notify);
+    return () => {
+      stopReady();
+      stopIdentity();
+      window.removeEventListener('Tracker Ready', notify);
+    };
+  },
+  maxEntries: 100,
+  maxBytes: 1024 * 1024,
+  maxActive: 100,
+  lifetime: 60000,
+  wait: 5000,
+  stage: 'readiness',
+});
+
+/** Resolves within the initial five-second wait; unsent events can remain pending for 60 seconds. */
+export function trackEvent(
   eventName: string,
   eventProperties: object,
   meta: EventMetadata = {},
 ): Promise<void> {
-  if (!mixpanelService.isReady()) {
-    throw new Error('Mixpanel is not initialized.');
+  const isCurrent = trackingLifecycle.capture();
+  const trackingParams = extractTrackingParams();
+  if (mixpanelService.isReady()) {
+    return submitEvent(
+      eventName,
+      eventProperties,
+      meta,
+      isCurrent,
+      trackingParams,
+    );
+  }
+  try {
+    validator.parseEventProps(eventName, eventProperties);
+  } catch (error) {
+    trackEventError(eventName, error, eventProperties);
+    return Promise.resolve();
+  }
+  let snapshot: { eventProperties: object; meta: EventMetadata };
+  let bytes: number;
+  try {
+    const serialized = JSON.stringify(
+      { eventName, eventProperties, meta, trackingParams },
+      (_key, value: unknown) => {
+        if (typeof value === 'function' || typeof value === 'symbol')
+          throw new Error();
+        return value === undefined ? null : value;
+      },
+    );
+    bytes = new Blob([serialized]).size;
+    if (bytes > 1024 * 1024) throw new Error();
+    snapshot = snapshotEventData({ eventProperties, meta });
+  } catch {
+    console.error('Tracking recovery diagnostic', {
+      eventName,
+      stage: 'readiness',
+      reason: 'snapshot_unavailable',
+    });
+    return Promise.resolve();
   }
+  return pendingEvents.enqueue({
+    eventName,
+    bytes,
+    isCurrent,
+    run: (isActive) =>
+      submitEvent(
+        eventName,
+        snapshot.eventProperties,
+        snapshot.meta,
+        isActive,
+        trackingParams,
+      ),
+  });
+}
 
+async function submitEvent(
+  eventName: string,
+  eventProperties: object,
+  meta: EventMetadata,
+  isCurrent: () => boolean,
+  trackingParams: Record<string, string>,
+): Promise<void> {
+  const observationContext = trackingLifecycle.capture();
   try {
     validator.parseEventProps(eventName, eventProperties);
     // Call the Mixpanel service to store the distinct ID in the cache
     const distinctId = mixpanelService.getMixpanelDistinctId();
     const botDetectionEnabled =
       botDetectionRelayService.isEnabledFor(eventName);
-    let fingerprint: string;
-    let fingerprintRequestId: string | undefined;
+    let fingerprint = '';
 
-    if (botDetectionEnabled && fingerprintService.isFingerprintReady()) {
-      const identification = await fingerprintService.identifyVisitor(true);
-      fingerprint = identification.visitorId;
-      fingerprintRequestId = identification.requestId;
+    if (botDetectionEnabled || FP_TRIGGER_EVENTS.includes(eventName)) {
+      try {
+        fingerprint = fingerprintService.getCachedFingerprint() ?? '';
+      } catch (error) {
+        console.error('Error reading cached fingerprint:', error);
+      }
     } else {
-      const cacheOnly = !FP_TRIGGER_EVENTS.includes(eventName);
-      fingerprint = await fingerprintService.getFingerprint(cacheOnly);
+      try {
+        fingerprint = await fingerprintService.getFingerprint(true);
+      } catch {
+        console.error('Tracking diagnostic', {
+          eventName,
+          stage: 'fingerprint',
+          reason: 'failed',
+        });
+      }
     }
     const defaultCoordinates: Record<string, string | number> = {};
     const coordinates = geolocationService.getCoordinates();
@@ -146,7 +269,6 @@ export async function trackEvent(
     const defaultProperties = {
       'User Fingerprint': fingerprint,
     };
-    const trackingParams = extractTrackingParams();
 
     const simplifiedData = flattenEventData(eventProperties);
     const properties = {
@@ -157,15 +279,22 @@ export async function trackEvent(
       ...meta,
     };
 
-    mixpanelService.track(eventName, properties);
-
-    if (fingerprintRequestId) {
-      void botDetectionRelayService.relay({
-        requestId: fingerprintRequestId,
-        visitorId: fingerprint,
-        ...(distinctId && { distinctId }),
+    if (!isCurrent()) return;
+    try {
+      mixpanelService.track(eventName, properties);
+    } catch {
+      console.error('Tracking diagnostic', {
         eventName,
+        stage: 'submission',
+        reason: 'uncertain',
       });
+      return;
+    }
+
+    if (botDetectionEnabled) {
+      deferBotDetection(eventName, distinctId, observationContext);
+    } else if (FP_TRIGGER_EVENTS.includes(eventName)) {
+      void refreshFingerprint(eventName, observationContext);
     }
   } catch (error) {
     console.error(`Error tracking event '${eventName}':`, error);
@@ -173,6 +302,26 @@ export async function trackEvent(
   }
 }
 
+/** Refreshes optional identity after submission without delaying the event. */
+async function refreshFingerprint(
+  eventName: string,
+  isCurrent: () => boolean,
+): Promise<void> {
+  const deadline = Date.now() + 10000;
+  try {
+    await fingerprintService.getFingerprint(false, {
+      isActive: () => isCurrent() && Date.now() < deadline,
+      report: () => undefined,
+    });
+  } catch {
+    console.error('Tracking diagnostic', {
+      eventName,
+      stage: 'fingerprint',
+      reason: 'failed',
+    });
+  }
+}
+
 /**
  * Extracts UTM and other tracking parameters from the current URL that match predefined fields.
  * @returns {Record<string, string>} An object containing matched tracking parameters.

package/src/util/pendingWork.test.ts

@@ -0,0 +1,164 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { createPendingWorkQueue } from './pendingWork';
+
+describe('bounded pending work', () => {
+  let ready: boolean;
+  let signal: () => void;
+  let detach: ReturnType<typeof vi.fn>;
+  beforeEach(() => {
+    vi.useFakeTimers();
+    ready = false;
+    signal = () => undefined;
+    detach = vi.fn();
+    vi.spyOn(console, 'error').mockImplementation(() => undefined);
+  });
+  afterEach(() => {
+    vi.clearAllTimers();
+    vi.useRealTimers();
+    vi.restoreAllMocks();
+  });
+  function queue(maxActive = 1) {
+    return createPendingWorkQueue({
+      isReady: () => ready,
+      subscribe: (notify) => {
+        signal = notify;
+        return detach;
+      },
+      maxEntries: 2,
+      maxBytes: 10,
+      maxActive,
+      lifetime: 60000,
+      wait: 5000,
+      stage: 'readiness',
+    });
+  }
+  const work = (run: () => void | Promise<void>, bytes = 1) => ({
+    eventName: 'Test',
+    bytes,
+    isCurrent: () => true,
+    run,
+  });
+
+  it('resolves the foreground wait but retains unsent work for readiness at 5.2 seconds', async () => {
+    const run = vi.fn();
+    const pending = queue().enqueue(work(run));
+    await vi.advanceTimersByTimeAsync(5000);
+    await expect(pending).resolves.toBeUndefined();
+    expect(run).not.toHaveBeenCalled();
+    await vi.advanceTimersByTimeAsync(200);
+    ready = true;
+    signal();
+    signal();
+    await vi.advanceTimersByTimeAsync(0);
+    expect(run).toHaveBeenCalledOnce();
+    expect(detach).toHaveBeenCalledOnce();
+    expect(vi.getTimerCount()).toBe(0);
+  });
+
+  it('never retries after a provider accepts and throws, including reentrant readiness', async () => {
+    const q = queue();
+    const run = vi.fn(() => {
+      signal();
+      throw new Error('accepted then threw');
+    });
+    const pending = q.enqueue(work(run));
+    ready = true;
+    signal();
+    signal();
+    await pending;
+    await vi.advanceTimersByTimeAsync(60000);
+    signal();
+    expect(run).toHaveBeenCalledOnce();
+    expect(JSON.stringify(vi.mocked(console.error).mock.calls)).not.toContain(
+      'accepted then threw',
+    );
+  });
+
+  it('keeps separate legitimate equal-payload calls', async () => {
+    const q = queue(2);
+    const run = vi.fn();
+    const first = q.enqueue(work(run));
+    const second = q.enqueue(work(run));
+    ready = true;
+    signal();
+    await Promise.all([first, second]);
+    expect(run).toHaveBeenCalledTimes(2);
+  });
+
+  it('expires without submission and cleans up its subscription and timer', async () => {
+    const run = vi.fn();
+    const pending = queue().enqueue(work(run));
+    await vi.advanceTimersByTimeAsync(60000);
+    await pending;
+    ready = true;
+    signal();
+    expect(run).not.toHaveBeenCalled();
+    expect(detach).toHaveBeenCalledOnce();
+    expect(vi.getTimerCount()).toBe(0);
+  });
+
+  it('evicts the oldest waiting work at capacity and rejects oversized work', async () => {
+    const q = queue();
+    const runs = [vi.fn(), vi.fn(), vi.fn(), vi.fn()];
+    const promises = runs.map((run, i) =>
+      q.enqueue(work(run, i === 3 ? 11 : 4)),
+    );
+    ready = true;
+    signal();
+    await Promise.all(promises);
+    expect(runs[0]).not.toHaveBeenCalled();
+    expect(runs[1]).toHaveBeenCalledOnce();
+    expect(runs[2]).toHaveBeenCalledOnce();
+    expect(runs[3]).not.toHaveBeenCalled();
+  });
+
+  it('invalidates waiting work before identity changes can submit it', async () => {
+    let current = true;
+    const run = vi.fn();
+    const pending = queue().enqueue({ ...work(run), isCurrent: () => current });
+    current = false;
+    signal();
+    await pending;
+    ready = true;
+    signal();
+    expect(run).not.toHaveBeenCalled();
+  });
+
+  it('enforces the byte budget before the entry-count budget is reached', async () => {
+    const q = queue();
+    const first = vi.fn();
+    const second = vi.fn();
+    const old = q.enqueue(work(first, 6));
+    const retained = q.enqueue(work(second, 6));
+    ready = true;
+    signal();
+    await Promise.all([old, retained]);
+    expect(first).not.toHaveBeenCalled();
+    expect(second).toHaveBeenCalledOnce();
+  });
+
+  it('suppresses expired active effects without exceeding actual provider concurrency', async () => {
+    const q = queue();
+    ready = true;
+    let finish!: () => void;
+    let active!: () => boolean;
+    const first = q.enqueue({
+      ...work(() => undefined),
+      run: (isActive) => {
+        active = isActive;
+        return new Promise<void>((resolve) => {
+          finish = resolve;
+        });
+      },
+    });
+    await vi.advanceTimersByTimeAsync(60000);
+    await first;
+    expect(active()).toBe(false);
+    const run = vi.fn();
+    const second = q.enqueue(work(run));
+    expect(run).not.toHaveBeenCalled();
+    finish();
+    await second;
+    expect(run).toHaveBeenCalledOnce();
+  });
+});

package/src/util/pendingWork.ts

@@ -0,0 +1,148 @@
+interface PendingWork {
+  eventName: string;
+  bytes: number;
+  isCurrent: () => boolean;
+  run: (isActive: () => boolean) => void | Promise<void>;
+}
+
+interface QueueOptions {
+  isReady: () => boolean;
+  subscribe: (notify: () => void) => () => void;
+  maxEntries: number;
+  maxBytes: number;
+  maxActive: number;
+  lifetime: number;
+  wait: number;
+  stage: 'readiness' | 'fingerprint';
+}
+
+interface Entry extends PendingWork {
+  state: 'waiting' | 'active' | 'closed';
+  deadline: number;
+  foregroundDeadline: number;
+  resolve?: () => void;
+}
+
+/** Retains bounded local work and claims each entry once, before invoking it. */
+export function createPendingWorkQueue(options: QueueOptions) {
+  const entries = new Set<Entry>();
+  let bytes = 0;
+  let active = 0;
+  let draining = false;
+  let unsubscribe: (() => void) | undefined;
+  let timer: ReturnType<typeof setTimeout> | undefined;
+
+  function diagnostic(entry: PendingWork, reason: string): void {
+    console.error('Tracking recovery diagnostic', {
+      eventName: entry.eventName,
+      stage: options.stage,
+      reason,
+    });
+  }
+
+  function resolveForeground(entry: Entry): void {
+    entry.resolve?.();
+    entry.resolve = undefined;
+  }
+
+  function close(entry: Entry, reason?: string): void {
+    if (entry.state === 'closed') return;
+    entry.state = 'closed';
+    entries.delete(entry);
+    bytes -= entry.bytes;
+    resolveForeground(entry);
+    if (reason) diagnostic(entry, reason);
+  }
+
+  function schedule(): void {
+    clearTimeout(timer);
+    timer = undefined;
+    if (entries.size === 0) {
+      unsubscribe?.();
+      unsubscribe = undefined;
+      return;
+    }
+    let next = Infinity;
+    for (const entry of entries) {
+      next = Math.min(next, entry.deadline);
+      if (entry.resolve) next = Math.min(next, entry.foregroundDeadline);
+    }
+    timer = setTimeout(drain, Math.max(0, next - Date.now()));
+  }
+
+  function drain(): void {
+    if (draining) return;
+    draining = true;
+    try {
+      for (const entry of entries) {
+        if (!entry.isCurrent()) close(entry, 'identity_changed');
+        else if (Date.now() >= entry.deadline) close(entry, 'timeout');
+        else if (entry.resolve && Date.now() >= entry.foregroundDeadline) {
+          resolveForeground(entry);
+        }
+      }
+      for (const entry of entries) {
+        if (active >= options.maxActive || !options.isReady()) break;
+        if (entry.state !== 'waiting') continue;
+        // No await before this claim: reentrant or repeated signals cannot replay it.
+        entry.state = 'active';
+        active++;
+        const isActive = () =>
+          entry.state === 'active' &&
+          Date.now() < entry.deadline &&
+          entry.isCurrent();
+        const finish = (failed = false) => {
+          if (failed && isActive()) diagnostic(entry, 'failed');
+          close(entry);
+          // An expired remote call still occupies its physical concurrency slot.
+          active--;
+          drain();
+        };
+        try {
+          void Promise.resolve(entry.run(isActive)).then(
+            () => finish(),
+            () => finish(true),
+          );
+        } catch {
+          finish(true);
+        }
+      }
+    } finally {
+      draining = false;
+      schedule();
+    }
+  }
+
+  function enqueue(work: PendingWork): Promise<void> {
+    if (work.bytes > options.maxBytes) {
+      diagnostic(work, 'capacity');
+      return Promise.resolve();
+    }
+    while (
+      entries.size >= options.maxEntries ||
+      bytes + work.bytes > options.maxBytes
+    ) {
+      const oldest = [...entries].find((entry) => entry.state === 'waiting');
+      if (!oldest) {
+        diagnostic(work, 'capacity');
+        return Promise.resolve();
+      }
+      close(oldest, 'capacity');
+    }
+    return new Promise((resolve) => {
+      const entry: Entry = {
+        ...work,
+        state: 'waiting',
+        deadline: Date.now() + options.lifetime,
+        foregroundDeadline: Date.now() + options.wait,
+        resolve,
+      };
+      entries.add(entry);
+      bytes += entry.bytes;
+      unsubscribe ??= options.subscribe(drain);
+      drain();
+    });
+  }
+
+  return { enqueue };
+}

package/src/util/snapshotEventData.ts

@@ -0,0 +1,15 @@
+/** Copies serializable event structures without replacing array undefined values with null. */
+export function snapshotEventData<T>(value: T): T {
+  if (Array.isArray(value))
+    return value.map((item: unknown) => snapshotEventData(item)) as T;
+  if (value instanceof Date) return new Date(value.getTime()) as T;
+  if (value !== null && typeof value === 'object') {
+    return Object.fromEntries(
+      Object.entries(value).map(([key, item]) => [
+        key,
+        snapshotEventData(item),
+      ]),
+    ) as T;
+  }
+  return value;
+}