@faststats/web 0.2.10 → 0.2.12

package/src/utils/identifiers.ts

@@ -1,4 +1,8 @@
 const SESSION_TIMEOUT = 30 * 60 * 1000;
+const ANONYMOUS_ID_KEY = "faststats_anon_id";
+const SESSION_ID_KEY = "session_id";
+const SESSION_TIMESTAMP_KEY = "session_timestamp";
+const SESSION_START_KEY = "session_start";
 
 let cookielessMode = false;
 
@@ -13,65 +17,73 @@ export function getAnonymousId(cookieless?: boolean): string {
 }
 
 export function getOrCreateAnonymousId(): string {
-	if (typeof localStorage === "undefined") return "";
-	const existingId = localStorage.getItem("faststats_anon_id");
+	if (!localStorage) return "";
+	const existingId = localStorage.getItem(ANONYMOUS_ID_KEY);
 	if (existingId) return existingId;
 
 	const newId = crypto.randomUUID();
-	localStorage.setItem("faststats_anon_id", newId);
+	localStorage.setItem(ANONYMOUS_ID_KEY, newId);
 	return newId;
 }
 
 export function resetAnonymousId(cookieless?: boolean): string {
-	if (cookieless || typeof localStorage === "undefined") return "";
-	localStorage.removeItem("faststats_anon_id");
+	if (cookieless) return "";
+
+	if (!localStorage) return "";
+
+	localStorage.removeItem(ANONYMOUS_ID_KEY);
 	return getOrCreateAnonymousId();
 }
 
 export function getOrCreateSessionId(): string {
-	if (typeof sessionStorage === "undefined") return "";
-	const existingId = sessionStorage.getItem("session_id");
-	const sessionTimestamp = sessionStorage.getItem("session_timestamp");
+	if (!sessionStorage) return "";
+
+	const existingId = sessionStorage.getItem(SESSION_ID_KEY);
+	const sessionTimestamp = sessionStorage.getItem(SESSION_TIMESTAMP_KEY);
 
 	if (existingId && sessionTimestamp) {
 		const sessionAge = Date.now() - Number.parseInt(sessionTimestamp, 10);
 		if (sessionAge < SESSION_TIMEOUT) {
-			sessionStorage.setItem("session_timestamp", Date.now().toString());
+			sessionStorage.setItem(SESSION_TIMESTAMP_KEY, Date.now().toString());
 			return existingId;
 		}
-		sessionStorage.removeItem("session_id");
-		sessionStorage.removeItem("session_timestamp");
-		sessionStorage.removeItem("session_start");
+		clearSession(sessionStorage);
 	}
 
 	const now = Date.now().toString();
 	const newId = crypto.randomUUID();
-	sessionStorage.setItem("session_id", newId);
-	sessionStorage.setItem("session_timestamp", now);
-	sessionStorage.setItem("session_start", now);
+	sessionStorage.setItem(SESSION_ID_KEY, newId);
+	sessionStorage.setItem(SESSION_TIMESTAMP_KEY, now);
+	sessionStorage.setItem(SESSION_START_KEY, now);
 	return newId;
 }
 
 export function resetSessionId(): string {
-	if (typeof sessionStorage === "undefined") return "";
-	sessionStorage.removeItem("session_id");
-	sessionStorage.removeItem("session_timestamp");
-	sessionStorage.removeItem("session_start");
+	if (!sessionStorage) return "";
+
+	clearSession(sessionStorage);
 	return getOrCreateSessionId();
 }
 
 export function refreshSessionTimestamp(): void {
-	if (typeof sessionStorage === "undefined") return;
-	const existingId = sessionStorage.getItem("session_id");
-	if (existingId) {
-		sessionStorage.setItem("session_timestamp", Date.now().toString());
+	if (!sessionStorage) return;
+
+	if (sessionStorage.getItem(SESSION_ID_KEY)) {
+		sessionStorage.setItem(SESSION_TIMESTAMP_KEY, Date.now().toString());
 	}
 }
 
 export function getSessionStart(): number {
-	if (typeof sessionStorage === "undefined") return Date.now();
-	const start = sessionStorage.getItem("session_start");
+	if (!sessionStorage) return Date.now();
+
+	const start = sessionStorage.getItem(SESSION_START_KEY);
 	if (start) return Number.parseInt(start, 10);
-	const ts = sessionStorage.getItem("session_timestamp");
+	const ts = sessionStorage.getItem(SESSION_TIMESTAMP_KEY);
 	return ts ? Number.parseInt(ts, 10) : Date.now();
 }
+
+function clearSession(storage: Storage): void {
+	storage.removeItem(SESSION_ID_KEY);
+	storage.removeItem(SESSION_TIMESTAMP_KEY);
+	storage.removeItem(SESSION_START_KEY);
+}

package/src/utils/send-data.ts

@@ -0,0 +1,52 @@
+import type { SendDataOptions } from "./types";
+
+export async function sendData(options: SendDataOptions): Promise<boolean> {
+	const {
+		url,
+		data,
+		contentType = "application/json",
+		headers = {},
+		debug = false,
+		debugPrefix = "[Analytics]",
+		useBeacon = true,
+		keepalive = true,
+	} = options;
+
+	if (useBeacon && typeof globalThis.navigator?.sendBeacon === "function") {
+		try {
+			const beaconBody =
+				data instanceof Blob
+					? data
+					: typeof Blob !== "undefined"
+						? new Blob([data as BlobPart], { type: contentType })
+						: data;
+			if (globalThis.navigator.sendBeacon(url, beaconBody as BodyInit)) {
+				if (debug) console.log(`${debugPrefix} Sent via beacon`);
+				return true;
+			}
+		} catch {}
+	}
+
+	try {
+		const response = await fetch(url, {
+			method: "POST",
+			body: data as BodyInit,
+			headers: {
+				"Content-Type": contentType,
+				...headers,
+			},
+			keepalive,
+		});
+		const success = response.ok;
+		if (debug) {
+			const message = success
+				? `${debugPrefix} Sent via fetch`
+				: `${debugPrefix} Failed: ${response.status}`;
+			console[success ? "log" : "warn"](message);
+		}
+		return success;
+	} catch {
+		if (debug) console.warn(`${debugPrefix} Failed to send`);
+		return false;
+	}
+}

package/src/web-vitals.ts

@@ -19,25 +19,54 @@ type MetricState = {
 };
 
 type AnyMetric = Metric | MetricWithAttribution;
-type Observer = (cb: (metric: AnyMetric) => void) => void;
-
-async function loadObservers(attribution: boolean): Promise<Observer[]> {
-	if (attribution) {
-		const { onCLS, onFCP, onINP, onLCP, onTTFB } = await import(
-			"web-vitals/attribution"
-		);
-		return [onCLS, onFCP, onINP, onLCP, onTTFB] as Observer[];
-	}
-	const { onCLS, onFCP, onINP, onLCP, onTTFB } = await import("web-vitals");
-	return [onCLS, onFCP, onINP, onLCP, onTTFB] as Observer[];
+type ObserverOptions = {
+	reportAllChanges?: boolean;
+};
+type Observer = (
+	cb: (metric: AnyMetric) => void,
+	opts?: ObserverOptions,
+) => void;
+type ObserverTuple = [Observer, Observer, Observer, Observer, Observer];
+type ObserverConfig = {
+	observe: Observer;
+	options?: ObserverOptions;
+};
+
+async function loadObservers(attribution: boolean): Promise<ObserverConfig[]> {
+	const { onCLS, onFCP, onINP, onLCP, onTTFB } = attribution
+		? await import("web-vitals/attribution")
+		: await import("web-vitals");
+	return createObserverConfigs([onCLS, onFCP, onINP, onLCP, onTTFB]);
+}
+
+function createObserverConfigs([
+	onCLS,
+	onFCP,
+	onINP,
+	onLCP,
+	onTTFB,
+]: ObserverTuple): ObserverConfig[] {
+	return [
+		{ observe: onCLS, options: { reportAllChanges: true } },
+		{ observe: onFCP },
+		{ observe: onINP, options: { reportAllChanges: true } },
+		{ observe: onLCP, options: { reportAllChanges: true } },
+		{ observe: onTTFB },
+	];
 }
 
 export default class WebVitalsTracker {
 	private readonly endpoint: string;
-	private readonly metrics = new Map<MetricName, MetricState>();
+	private readonly metricsByUrl = new Map<
+		string,
+		Map<MetricName, MetricState>
+	>();
+	private readonly pendingFlushUrls = new Set<string>();
 	private readonly sampled: boolean;
 	private started = false;
-	private flushed = false;
+	private flushing = false;
+	private finalFlushRequested = false;
+	private currentUrl = "";
 
 	constructor(private readonly options: WebVitalsOptions) {
 		this.endpoint = webVitalsEventsUrl(options.baseUrl);
@@ -56,33 +85,50 @@ export default class WebVitalsTracker {
 
 	start(): void {
 		if (this.started || typeof window === "undefined") return;
+
 		this.started = true;
-		this.flushed = false;
+		this.currentUrl = window.location.href;
 
-		document.addEventListener("visibilitychange", this.onVisibilityChange);
-		window.addEventListener("pagehide", this.flush);
+		document.addEventListener("visibilitychange", this.onVisibilityChange, {
+			passive: true,
+		});
+		window.addEventListener("pagehide", this.onPageHide, { passive: true });
 
 		this.log("Tracking started");
-
 		void this.observe();
 	}
 
 	stop(): void {
 		if (!this.started || typeof window === "undefined") return;
+
 		this.started = false;
+		this.cleanupListeners();
+		this.queueFlush(this.currentUrl, true);
+	}
 
-		document.removeEventListener("visibilitychange", this.onVisibilityChange);
-		window.removeEventListener("pagehide", this.flush);
+	trackPageChange(url?: string): void {
+		if (!this.started || typeof window === "undefined") return;
+		const nextUrl = url ?? window.location.href;
+		if (nextUrl === this.currentUrl) return;
 
-		this.flush();
+		const previousUrl = this.currentUrl;
+		this.currentUrl = nextUrl;
+		this.queueFlush(previousUrl);
+	}
+
+	private cleanupListeners(): void {
+		document.removeEventListener("visibilitychange", this.onVisibilityChange);
+		window.removeEventListener("pagehide", this.onPageHide);
 	}
 
 	private async observe(): Promise<void> {
 		try {
 			const observers = await loadObservers(this.options.attribution ?? false);
+
 			if (!this.started) return;
-			for (const observe of observers) {
-				observe(this.captureMetric);
+
+			for (const { observe, options } of observers) {
+				observe(this.captureMetric, options);
 			}
 		} catch (error) {
 			this.log("Failed to load web-vitals", error);
@@ -90,17 +136,24 @@ export default class WebVitalsTracker {
 	}
 
 	private onVisibilityChange = (): void => {
-		if (document.visibilityState === "hidden") this.flush();
+		if (document.visibilityState === "hidden") {
+			this.queueFlush(this.currentUrl, true);
+		}
+	};
+
+	private onPageHide = (): void => {
+		this.queueFlush(this.currentUrl, true);
 	};
 
 	private captureMetric = (metric: AnyMetric): void => {
-		if (this.flushed || !this.sampled) return;
+		if (!this.started || !this.sampled) return;
 
 		const name = metric.name as MetricName;
 		const attribution =
 			(metric as MetricWithAttribution).attribution ?? undefined;
+		const metrics = this.metricsForUrl(this.currentUrl);
 
-		this.metrics.set(name, {
+		metrics.set(name, {
 			value: metric.value,
 			attributes: {
 				id: metric.id,
@@ -114,40 +167,95 @@ export default class WebVitalsTracker {
 		this.log(`${name} captured: ${metric.value}`);
 	};
 
-	private flush = (): void => {
-		if (this.flushed || this.metrics.size === 0) return;
-		this.flushed = true;
+	private metricsForUrl(url: string): Map<MetricName, MetricState> {
+		let metrics = this.metricsByUrl.get(url);
+		if (!metrics) {
+			metrics = new Map();
+			this.metricsByUrl.set(url, metrics);
+		}
+		return metrics;
+	}
+
+	private queueFlush(url: string, final = false): void {
+		this.finalFlushRequested ||= final;
+		this.pendingFlushUrls.add(url);
+		void this.flushPending();
+	}
 
-		const vitals = [...this.metrics.entries()].map(([metric, data]) => ({
+	private async flushPending(): Promise<void> {
+		if (this.flushing) return;
+		if (typeof window === "undefined" || typeof fetch !== "function") {
+			this.finishFinalFlushIfNeeded();
+			return;
+		}
+
+		this.flushing = true;
+
+		try {
+			const urls = [...this.pendingFlushUrls];
+			this.pendingFlushUrls.clear();
+			for (const url of urls) {
+				if (!(await this.sendMetricsForUrl(url)))
+					this.pendingFlushUrls.add(url);
+			}
+		} finally {
+			this.flushing = false;
+			this.finishFinalFlushIfNeeded();
+		}
+	}
+
+	private async sendMetricsForUrl(url: string): Promise<boolean> {
+		const metrics = this.metricsByUrl.get(url);
+		if (!metrics || metrics.size === 0) return true;
+
+		const vitals = [...metrics.entries()].map(([metric, data]) => ({
 			metric,
 			value: data.value,
 			attributes: data.attributes,
 		}));
-		const metricNames = vitals.map((v) => v.metric).join(", ");
-		this.metrics.clear();
-
 		const body = JSON.stringify({
 			sessionId: getOrCreateSessionId(),
 			vitals,
-			metadata: {
-				url: window.location.href,
-			},
+			metadata: { url },
 		});
 
-		this.log(`Sending final metrics (${vitals.length}): ${metricNames}`);
+		this.log(`Sending metrics for ${url} (${vitals.length})`);
+
+		try {
+			const controller = new AbortController();
+			const timeout = window.setTimeout(() => controller.abort(), 3000);
 
-		if (typeof fetch !== "function") return;
+			try {
+				const response = await fetch(this.endpoint, {
+					method: "POST",
+					body,
+					headers: {
+						"Content-Type": "application/json",
+						Authorization: `Bearer ${this.options.siteKey}`,
+					},
+					keepalive: true,
+					signal: controller.signal,
+				});
 
-		fetch(this.endpoint, {
-			method: "POST",
-			body,
-			headers: {
-				"Content-Type": "application/json",
-				Authorization: `Bearer ${this.options.siteKey}`,
-			},
-			keepalive: true,
-		}).catch(() => {
-			this.log("Failed to send metrics");
-		});
-	};
+				if (!response.ok) {
+					throw new Error(`HTTP ${response.status}`);
+				}
+
+				this.metricsByUrl.delete(url);
+			} finally {
+				clearTimeout(timeout);
+			}
+			return true;
+		} catch (error) {
+			this.log("Failed to send metrics", error);
+			return false;
+		}
+	}
+
+	private finishFinalFlushIfNeeded(): void {
+		if (!this.finalFlushRequested) return;
+		this.finalFlushRequested = false;
+		this.started = false;
+		this.cleanupListeners();
+	}
 }

package/tests/analytics.test.ts

@@ -391,6 +391,41 @@ describe("WebAnalytics lifecycle", () => {
 		).toBe(true);
 	});
 
+	test("visibility hide refreshes stale session before page leave", async () => {
+		const analytics = new WebAnalytics({
+			siteKey: "site_test",
+			autoTrack: false,
+		});
+
+		await analytics.start();
+		const storage = globalThis.sessionStorage as unknown as MockStorage;
+		const sessionId = storage.getItem("session_id");
+		expect(sessionId).toBeTruthy();
+		storage.setItem("session_timestamp", "0");
+		harness.fetchCalls.length = 0;
+
+		Object.defineProperty(globalThis.document, "visibilityState", {
+			configurable: true,
+			value: "hidden",
+		});
+		for (const listener of harness.documentTarget.listeners.get(
+			"visibilitychange",
+		) ?? []) {
+			if (typeof listener === "function") {
+				listener(new Event("visibilitychange"));
+			} else {
+				listener.handleEvent(new Event("visibilitychange"));
+			}
+		}
+		await wait(0);
+
+		expect(storage.getItem("session_id")).toBe(sessionId);
+		const pageLeaveCall = harness.fetchCalls.find((call) =>
+			call.body?.includes('"event":"page_leave"'),
+		);
+		expect(pageLeaveCall?.body).toContain(`"sessionId":"${sessionId}"`);
+	});
+
 	test("resolveReplayTrackerOptions honors sessionReplays config", () => {
 		const options = resolveReplayTrackerOptions(
 			{

package/tests/identifiers.test.ts

@@ -74,4 +74,22 @@ describe("identifiers", () => {
 		expect(second.length).toBeGreaterThan(0);
 		expect(second).not.toBe(first);
 	});
+
+	test("storage access failures disable persisted identifiers", () => {
+		Object.defineProperty(globalThis, "localStorage", {
+			configurable: true,
+			get() {
+				throw new Error("storage blocked");
+			},
+		});
+		Object.defineProperty(globalThis, "sessionStorage", {
+			configurable: true,
+			get() {
+				throw new Error("storage blocked");
+			},
+		});
+
+		expect(getOrCreateAnonymousId()).toBe("");
+		expect(getOrCreateSessionId()).toBe("");
+	});
 });

package/tests/replay.test.ts

@@ -34,6 +34,7 @@ type ReplayBatch = {
 	token: string;
 	sessionId?: string;
 	identifier?: string;
+	batchId: string;
 	sequence: number;
 	timestamp: number;
 	url: string;
@@ -191,11 +192,35 @@ describe("ReplayTracker", () => {
 		expect(captured.payload).not.toBeNull();
 		expect(captured.payload?.token).toBe("site_test");
 		expect(captured.payload?.sessionId).toBeTruthy();
+		expect(captured.payload?.batchId).toBeTruthy();
 		expect(captured.payload?.events).toHaveLength(1);
 		expect(captured.lowLatency).toBe(true);
 		expect(tracker.pending.length).toBe(0);
 	});
 
+	test("emits stable batch ids while queued for retry", async () => {
+		const tracker = createTracker({
+			minReplayLengthMs: 0,
+		});
+
+		const payloads: ReplayBatch[] = [];
+		tracker.send = async (data) => {
+			payloads.push(JSON.parse(decodeBody(data)) as ReplayBatch);
+			return payloads.length > 1;
+		};
+		tracker.startTime = Date.now() - 1000;
+		tracker.onEvent({ type: 2, timestamp: Date.now(), data: {} }, false);
+
+		await tracker.flush(false);
+		await tracker.flush(false);
+
+		expect(payloads).toHaveLength(2);
+		expect(payloads[1]?.batchId).toBe(payloads[0]?.batchId);
+		expect(payloads[1]?.sequence).toBe(payloads[0]?.sequence);
+
+		if (tracker.retryTask) clearTimeout(tracker.retryTask);
+	});
+
 	test("keeps the same replay session id across later batches", async () => {
 		const tracker = createTracker({
 			minReplayLengthMs: 0,