@faststats/web 0.2.13 → 0.3.0

package/src/web-vitals.ts

@@ -1,159 +0,0 @@
-import type { Metric, MetricWithAttribution } from "web-vitals";
-import { normalizeAnalyticsBaseUrl, URLS } from "./utils/api-urls";
-import { getOrCreateSessionId } from "./utils/identifiers";
-import { normalizeSamplingPercentage } from "./utils/types";
-
-export interface WebVitalsOptions {
-	siteKey: string;
-	baseUrl?: string;
-	debug?: boolean;
-	samplingPercentage?: number;
-	attribution?: boolean;
-}
-
-type MetricName = "CLS" | "INP" | "LCP" | "FCP" | "TTFB";
-type AnyMetric = Metric | MetricWithAttribution;
-
-type MetricPayload = {
-	metric: MetricName;
-	value: number;
-	attributes: Record<string, unknown>;
-};
-
-export default class WebVitalsTracker {
-	private readonly endpoint: string;
-	private readonly sampled: boolean;
-	private readonly metrics = new Map<MetricName, MetricPayload>();
-	private started = false;
-	private url = "";
-
-	constructor(private readonly options: WebVitalsOptions) {
-		this.endpoint = `${normalizeAnalyticsBaseUrl(options.baseUrl)}${URLS.vitals}`;
-		this.sampled =
-			Math.random() * 100 <
-			normalizeSamplingPercentage(options.samplingPercentage);
-	}
-
-	private get debug(): boolean {
-		return this.options.debug ?? false;
-	}
-
-	private log(...args: unknown[]): void {
-		if (this.debug) console.log("[WebVitals]", ...args);
-	}
-
-	async start(): Promise<void> {
-		if (this.started || typeof window === "undefined") return;
-
-		this.started = true;
-		this.url = window.location.href;
-
-		document.addEventListener("visibilitychange", this.onHidden, {
-			passive: true,
-		});
-		window.addEventListener("pagehide", this.onPageHide, { passive: true });
-
-		const mod = this.options.attribution
-			? await import("web-vitals/attribution")
-			: await import("web-vitals");
-
-		if (!this.started) return;
-
-		mod.onCLS(this.capture, { reportAllChanges: true });
-		mod.onINP(this.capture, { reportAllChanges: true });
-		mod.onLCP(this.capture, { reportAllChanges: true });
-		mod.onFCP(this.capture);
-		mod.onTTFB(this.capture);
-
-		this.log("Tracking started");
-	}
-
-	stop(): void {
-		if (!this.started || typeof window === "undefined") return;
-
-		this.started = false;
-		this.removeListeners();
-		void this.flush();
-	}
-
-	trackPageChange(url?: string): void {
-		if (!this.started || typeof window === "undefined") return;
-
-		const nextUrl = url ?? window.location.href;
-		if (nextUrl === this.url) return;
-
-		void this.flush();
-		this.url = nextUrl;
-	}
-
-	private onHidden = (): void => {
-		if (document.visibilityState === "hidden") {
-			void this.flush();
-		}
-	};
-
-	private onPageHide = (): void => {
-		void this.flush();
-	};
-
-	private capture = (metric: AnyMetric): void => {
-		if (!this.started || !this.sampled) return;
-
-		const name = metric.name as MetricName;
-		const attribution = (metric as MetricWithAttribution).attribution;
-
-		this.metrics.set(name, {
-			metric: name,
-			value: metric.value,
-			attributes: {
-				id: metric.id,
-				rating: metric.rating,
-				delta: metric.delta,
-				navigationType: metric.navigationType,
-				...(attribution ?? {}),
-			},
-		});
-	};
-
-	private async flush(): Promise<void> {
-		if (typeof window === "undefined" || typeof fetch !== "function") return;
-		if (!this.metrics.size) return;
-
-		const vitals = Array.from(this.metrics.values());
-		const url = this.url;
-		this.metrics.clear();
-
-		try {
-			const controller = new AbortController();
-			const timeoutId = window.setTimeout(() => controller.abort(), 3000);
-
-			const response = await fetch(this.endpoint, {
-				method: "POST",
-				body: JSON.stringify({
-					sessionId: getOrCreateSessionId(),
-					vitals,
-					metadata: { url },
-				}),
-				headers: {
-					"Content-Type": "application/json",
-					Authorization: `Bearer ${this.options.siteKey}`,
-				},
-				keepalive: true,
-				signal: controller.signal,
-			});
-
-			clearTimeout(timeoutId);
-
-			if (!response.ok) {
-				throw new Error(`HTTP ${response.status}`);
-			}
-		} catch (error) {
-			this.log("Failed to send metrics", error);
-		}
-	}
-
-	private removeListeners(): void {
-		document.removeEventListener("visibilitychange", this.onHidden);
-		window.removeEventListener("pagehide", this.onPageHide);
-	}
-}

package/tests/analytics.test.ts

@@ -1,450 +0,0 @@
-import { afterEach, beforeEach, describe, expect, test } from "bun:test";
-import {
-	getInstance,
-	resolveReplayTrackerOptions,
-	sendData,
-	setConsentMode,
-	WebAnalytics,
-} from "../src/analytics";
-
-class MockStorage {
-	private readonly store = new Map<string, string>();
-
-	getItem(key: string): string | null {
-		return this.store.get(key) ?? null;
-	}
-
-	setItem(key: string, value: string): void {
-		this.store.set(key, value);
-	}
-
-	removeItem(key: string): void {
-		this.store.delete(key);
-	}
-}
-
-class MockNode {
-	parentNode: MockNode | null = null;
-}
-
-class MockAnchorElement extends MockNode {
-	constructor(
-		public href: string,
-		public host: string,
-	) {
-		super();
-	}
-}
-
-type Listener = EventListenerOrEventListenerObject;
-
-class MockEventTarget {
-	readonly listeners = new Map<string, Set<Listener>>();
-
-	addEventListener(type: string, listener: Listener): void {
-		const existing = this.listeners.get(type) ?? new Set<Listener>();
-		existing.add(listener);
-		this.listeners.set(type, existing);
-	}
-
-	removeEventListener(type: string, listener: Listener): void {
-		this.listeners.get(type)?.delete(listener);
-	}
-
-	listenerCount(type: string): number {
-		return this.listeners.get(type)?.size ?? 0;
-	}
-}
-
-type FetchCall = {
-	url: string;
-	body?: string;
-	headers?: Record<string, string>;
-};
-
-type BrowserHarness = {
-	windowTarget: MockEventTarget;
-	documentTarget: MockEventTarget;
-	fetchCalls: FetchCall[];
-	restore(): void;
-	location: {
-		href: string;
-		pathname: string;
-		hash: string;
-		search: string;
-	};
-	history: History;
-	navigator: {
-		sendBeacon: (url: string, data?: BodyInit | null) => boolean;
-	};
-};
-
-function wait(ms: number): Promise<void> {
-	return new Promise((resolve) => setTimeout(resolve, ms));
-}
-
-function setGlobal(name: keyof typeof globalThis, value: unknown): void {
-	Object.defineProperty(globalThis, name, {
-		configurable: true,
-		writable: true,
-		value,
-	});
-}
-
-function setupBrowser(): BrowserHarness {
-	const originalValues = {
-		window: globalThis.window,
-		document: globalThis.document,
-		location: globalThis.location,
-		history: globalThis.history,
-		localStorage: globalThis.localStorage,
-		sessionStorage: globalThis.sessionStorage,
-		navigator: globalThis.navigator,
-		fetch: globalThis.fetch,
-		Node: globalThis.Node,
-		HTMLAnchorElement: globalThis.HTMLAnchorElement,
-	};
-
-	const fetchCalls: FetchCall[] = [];
-	const windowTarget = new MockEventTarget();
-	const documentTarget = new MockEventTarget();
-	const localStorage = new MockStorage();
-	const sessionStorage = new MockStorage();
-	const locationState = {
-		href: "https://example.com/",
-		pathname: "/",
-		hash: "",
-		search: "",
-	};
-
-	const updateHref = (): void => {
-		locationState.href = `https://example.com${locationState.pathname}${locationState.search}${locationState.hash}`;
-	};
-
-	const history = {
-		pushState(_data: unknown, _unused: string, url?: string | URL | null) {
-			if (typeof url === "string") {
-				const parsed = new URL(url, locationState.href);
-				locationState.pathname = parsed.pathname;
-				locationState.search = parsed.search;
-				locationState.hash = parsed.hash;
-				updateHref();
-			}
-		},
-		replaceState(_data: unknown, _unused: string, url?: string | URL | null) {
-			if (typeof url === "string") {
-				const parsed = new URL(url, locationState.href);
-				locationState.pathname = parsed.pathname;
-				locationState.search = parsed.search;
-				locationState.hash = parsed.hash;
-				updateHref();
-			}
-		},
-	} as unknown as History;
-
-	const document = {
-		addEventListener: documentTarget.addEventListener.bind(documentTarget),
-		removeEventListener:
-			documentTarget.removeEventListener.bind(documentTarget),
-		referrer: "",
-		title: "FastStats",
-		visibilityState: "visible",
-		documentElement: {
-			scrollHeight: 2000,
-			scrollTop: 0,
-		},
-		body: {
-			scrollHeight: 2000,
-		},
-	} as unknown as Document;
-
-	const windowObject = {
-		addEventListener: windowTarget.addEventListener.bind(windowTarget),
-		removeEventListener: windowTarget.removeEventListener.bind(windowTarget),
-		innerHeight: 1000,
-		scrollY: 0,
-		setTimeout,
-		clearTimeout,
-		setInterval,
-		clearInterval,
-		history,
-		location: locationState,
-	} as unknown as Window & typeof globalThis;
-
-	const navigator = {
-		sendBeacon: () => false,
-	};
-
-	setGlobal("window", windowObject);
-	setGlobal("document", document);
-	setGlobal("location", locationState as Location);
-	setGlobal("history", history);
-	setGlobal("localStorage", localStorage);
-	setGlobal("sessionStorage", sessionStorage);
-	setGlobal("navigator", navigator);
-	setGlobal("fetch", (async (
-		url: string | URL | Request,
-		init?: RequestInit,
-	): Promise<Response> => {
-		let body: string | undefined;
-		if (typeof init?.body === "string") {
-			body = init.body;
-		} else if (init?.body instanceof Blob) {
-			body = await init.body.text();
-		}
-		fetchCalls.push({
-			url: String(url),
-			body,
-			headers: init?.headers as Record<string, string> | undefined,
-		});
-		return new Response("", { status: 204 });
-	}) as typeof fetch);
-	setGlobal("Node", MockNode as unknown as typeof Node);
-	setGlobal(
-		"HTMLAnchorElement",
-		MockAnchorElement as unknown as typeof HTMLAnchorElement,
-	);
-
-	return {
-		windowTarget,
-		documentTarget,
-		fetchCalls,
-		location: locationState,
-		history,
-		navigator,
-		restore() {
-			setGlobal("window", originalValues.window);
-			setGlobal("document", originalValues.document);
-			setGlobal("location", originalValues.location);
-			setGlobal("history", originalValues.history);
-			setGlobal("localStorage", originalValues.localStorage);
-			setGlobal("sessionStorage", originalValues.sessionStorage);
-			setGlobal("navigator", originalValues.navigator);
-			setGlobal("fetch", originalValues.fetch);
-			setGlobal("Node", originalValues.Node);
-			setGlobal("HTMLAnchorElement", originalValues.HTMLAnchorElement);
-		},
-	};
-}
-
-let harness: BrowserHarness;
-
-beforeEach(() => {
-	harness = setupBrowser();
-});
-
-afterEach(() => {
-	getInstance()?.destroy();
-	harness.restore();
-});
-
-describe("WebAnalytics lifecycle", () => {
-	test("start installs listeners and destroy removes them", async () => {
-		const analytics = new WebAnalytics({
-			siteKey: "site_test",
-			autoTrack: false,
-		});
-		await analytics.start();
-
-		expect(getInstance()).toBe(analytics);
-		expect(harness.windowTarget.listenerCount("pagehide")).toBe(1);
-		expect(harness.windowTarget.listenerCount("popstate")).toBe(1);
-		expect(harness.documentTarget.listenerCount("visibilitychange")).toBe(1);
-		expect(harness.documentTarget.listenerCount("click")).toBe(1);
-
-		analytics.destroy();
-
-		expect(getInstance()).toBeNull();
-		expect(harness.windowTarget.listenerCount("pagehide")).toBe(0);
-		expect(harness.windowTarget.listenerCount("popstate")).toBe(0);
-		expect(harness.documentTarget.listenerCount("visibilitychange")).toBe(0);
-		expect(harness.documentTarget.listenerCount("click")).toBe(0);
-	});
-
-	test("sendData uses beacon before fetch", async () => {
-		harness.navigator.sendBeacon = () => true;
-		const sent = await sendData({
-			url: "https://example.com/v1/web",
-			data: '{"ok":true}',
-		});
-		expect(sent).toBe(true);
-		expect(harness.fetchCalls.length).toBe(0);
-	});
-
-	test("sendData returns false when fetch is unavailable", async () => {
-		harness.navigator.sendBeacon = () => false;
-		setGlobal("fetch", undefined as unknown as typeof fetch);
-		const sent = await sendData({
-			url: "https://example.com/v1/web",
-			data: '{"ok":true}',
-		});
-		expect(sent).toBe(false);
-	});
-
-	test("sendData can skip beacon and use fetch", async () => {
-		harness.navigator.sendBeacon = () => true;
-		const sent = await sendData({
-			url: "https://example.com/v1/web",
-			data: '{"ok":true}',
-			useBeacon: false,
-		});
-		expect(sent).toBe(true);
-		expect(harness.fetchCalls.length).toBe(1);
-	});
-
-	test("module consent updates apply before instance starts", () => {
-		setConsentMode("denied");
-		const analytics = new WebAnalytics({
-			siteKey: "site_test",
-			autoTrack: false,
-			consent: { mode: "granted" },
-		});
-		expect(analytics.getConsentMode()).toBe("denied");
-	});
-
-	test("consent changes unblock identify payloads", async () => {
-		const analytics = new WebAnalytics({
-			siteKey: "site_test",
-			autoTrack: false,
-			consent: {
-				mode: "pending",
-				cookielessWhilePending: true,
-			},
-		});
-
-		await analytics.start();
-		analytics.identify("user_1", "user@example.com");
-		await wait(0);
-		expect(
-			harness.fetchCalls.some((call) => call.url.endsWith("/v1/identify")),
-		).toBe(false);
-
-		analytics.setConsentMode("granted");
-		const identified = await analytics.identify("user_1", "user@example.com", {
-			name: "User One",
-		});
-
-		const identifyCall = harness.fetchCalls.find((call) =>
-			call.url.endsWith("/v1/identify"),
-		);
-		expect(identified).toBe(true);
-		expect(identifyCall).toBeTruthy();
-		expect(identifyCall?.body).toContain('"externalId":"user_1"');
-		expect(identifyCall?.body).toContain('"email":"user@example.com"');
-	});
-
-	test("feature flag checks send identifier with external id", async () => {
-		const analytics = new WebAnalytics({
-			siteKey: "site_test",
-			autoTrack: false,
-		});
-		setGlobal("fetch", (async (
-			url: string | URL | Request,
-			init?: RequestInit,
-		): Promise<Response> => {
-			harness.fetchCalls.push({
-				url: String(url),
-				body: typeof init?.body === "string" ? init.body : undefined,
-				headers: init?.headers as Record<string, string> | undefined,
-			});
-			return Response.json({ value: "true" });
-		}) as typeof fetch);
-
-		await analytics.start();
-		await analytics.checkFeatureFlag("beta", undefined, {
-			externalId: "user_1",
-		});
-
-		const checkCall = harness.fetchCalls.find((call) =>
-			call.url.endsWith("/v1/check"),
-		);
-		expect(checkCall).toBeTruthy();
-		expect(checkCall?.body).toContain('"key":"beta"');
-		expect(checkCall?.body).toContain('"externalId":"user_1"');
-		expect(checkCall?.body).toContain('"identifier":');
-		expect(checkCall?.body).toContain('"sessionId":');
-	});
-
-	test("navigation sends page leave and navigation pageview", async () => {
-		const analytics = new WebAnalytics({
-			siteKey: "site_test",
-			autoTrack: false,
-		});
-
-		await analytics.start();
-		harness.fetchCalls.length = 0;
-
-		harness.history.pushState({}, "", "/about");
-		await wait(350);
-		await wait(0);
-
-		const payloads = harness.fetchCalls.map((call) => call.body ?? "");
-		expect(payloads.some((body) => body.includes('"event":"page_leave"'))).toBe(
-			true,
-		);
-		expect(
-			payloads.some(
-				(body) =>
-					body.includes('"event":"pageview"') &&
-					body.includes('"trigger":"navigation"') &&
-					body.includes('"page":"/about"'),
-			),
-		).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(
-			{
-				siteKey: "site_test",
-				sessionReplays: {
-					enabled: true,
-					sampling: { percentage: 37 },
-				},
-			},
-			"https://metrics.example.com",
-			true,
-		);
-
-		expect(options).toMatchObject({
-			siteKey: "site_test",
-			baseUrl: "https://metrics.example.com",
-			debug: true,
-			samplingPercentage: 37,
-		});
-	});
-});

package/tests/identifiers.test.ts

@@ -1,95 +0,0 @@
-import { afterEach, beforeEach, describe, expect, test } from "bun:test";
-import {
-	getOrCreateAnonymousId,
-	getOrCreateSessionId,
-	getSessionStart,
-	resetSessionId,
-} from "../src/utils/identifiers";
-
-class MockStorage {
-	private readonly data = new Map<string, string>();
-
-	getItem(key: string): string | null {
-		return this.data.get(key) ?? null;
-	}
-
-	setItem(key: string, value: string): void {
-		this.data.set(key, value);
-	}
-
-	removeItem(key: string): void {
-		this.data.delete(key);
-	}
-}
-
-function setGlobal(name: keyof typeof globalThis, value: unknown): void {
-	Object.defineProperty(globalThis, name, {
-		configurable: true,
-		writable: true,
-		value,
-	});
-}
-
-const original = {
-	localStorage: globalThis.localStorage,
-	sessionStorage: globalThis.sessionStorage,
-};
-
-beforeEach(() => {
-	setGlobal("localStorage", new MockStorage());
-	setGlobal("sessionStorage", new MockStorage());
-});
-
-afterEach(() => {
-	setGlobal("localStorage", original.localStorage);
-	setGlobal("sessionStorage", original.sessionStorage);
-});
-
-describe("identifiers", () => {
-	test("anonymous id is generated and persisted", () => {
-		const id = getOrCreateAnonymousId();
-		const second = getOrCreateAnonymousId();
-		expect(id.length).toBeGreaterThan(0);
-		expect(second).toBe(id);
-	});
-
-	test("session id is recreated when timestamp is invalid", () => {
-		const storage = globalThis.sessionStorage as unknown as MockStorage;
-		storage.setItem("session_id", "old-session");
-		storage.setItem("session_timestamp", "NaN");
-		const id = getOrCreateSessionId();
-		expect(id).not.toBe("old-session");
-	});
-
-	test("session start falls back when stored value is invalid", () => {
-		const storage = globalThis.sessionStorage as unknown as MockStorage;
-		storage.setItem("session_start", "NaN");
-		const start = getSessionStart();
-		expect(Number.isNaN(start)).toBe(true);
-	});
-
-	test("resetSessionId creates a new session id", () => {
-		const first = getOrCreateSessionId();
-		const second = resetSessionId();
-		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("");
-	});
-});