@faststats/web 0.1.3 → 0.1.5

package/src/analytics.ts

@@ -1,4 +1,11 @@
+import type ErrorTracker from "./error";
+import type ReplayTracker from "./replay";
 import type { ReplayTrackerOptions } from "./replay";
+import {
+	identifyEventsUrl,
+	normalizeAnalyticsBaseUrl,
+	webEventsUrl,
+} from "./utils/api-urls";
 import {
 	getAnonymousId,
 	getOrCreateSessionId,
@@ -12,9 +19,59 @@ import {
 	normalizeSamplingPercentage,
 	type SendDataOptions,
 } from "./utils/types";
+import type WebVitalsTracker from "./web-vitals";
 
 export type { SendDataOptions };
 
+type ChildTracker = {
+	start(): void;
+	stop?(): void;
+};
+
+type Dict = Record<string, unknown>;
+
+interface SamplingOptions {
+	percentage?: number;
+}
+
+interface WebVitalsConfig {
+	sampling?: SamplingOptions;
+}
+
+interface SessionReplayConfig {
+	sampling?: SamplingOptions;
+}
+
+export type ConsentMode = "pending" | "granted" | "denied";
+
+interface ConsentConfig {
+	mode?: ConsentMode;
+	cookielessWhilePending?: boolean;
+}
+
+export interface IdentifyOptions {
+	name?: string;
+	phone?: string;
+	avatarUrl?: string;
+	traits?: Record<string, unknown>;
+}
+
+export interface WebAnalyticsOptions {
+	siteKey: string;
+	baseUrl?: string;
+	debug?: boolean;
+	autoTrack?: boolean;
+	trackHash?: boolean;
+	trackErrors?: boolean;
+	trackWebVitals?: boolean;
+	trackReplay?: boolean;
+	cookieless?: boolean;
+	consent?: ConsentConfig;
+	webVitals?: WebVitalsConfig;
+	sessionReplays?: SessionReplayConfig;
+	replayOptions?: Partial<ReplayTrackerOptions>;
+}
+
 let _instance: WebAnalytics | null = null;
 
 export function getInstance(): WebAnalytics | null {
@@ -55,6 +112,11 @@ export function optOut(): void {
 	setConsentMode("denied");
 }
 
+export function reportError(error: Error): void {
+	if (typeof window === "undefined" || isTrackingDisabled()) return;
+	_instance?.reportError(error);
+}
+
 export function isTrackingDisabled(): boolean {
 	if (typeof localStorage === "undefined") return false;
 	const value = localStorage.getItem("disable-faststats");
@@ -76,7 +138,7 @@ export async function sendData(options: SendDataOptions): Promise<boolean> {
 
 	if (navigator.sendBeacon?.(url, blob)) {
 		if (debug) {
-			console.log(`${debugPrefix} ✓ Sent via beacon`);
+			console.log(`${debugPrefix} Sent via beacon`);
 		}
 		return true;
 	}
@@ -94,15 +156,15 @@ export async function sendData(options: SendDataOptions): Promise<boolean> {
 		const success = response.ok;
 		if (debug) {
 			if (success) {
-				console.log(`${debugPrefix} ✓ Sent via fetch`);
+				console.log(`${debugPrefix} Sent via fetch`);
 			} else {
-				console.warn(`${debugPrefix} ✗ Failed: ${response.status}`);
+				console.warn(`${debugPrefix} Failed: ${response.status}`);
 			}
 		}
 		return success;
 	} catch {
 		if (debug) {
-			console.warn(`${debugPrefix} ✗ Failed to send`);
+			console.warn(`${debugPrefix} Failed to send`);
 		}
 		return false;
 	}
@@ -133,59 +195,12 @@ function getUTM(): Record<string, string> {
 	return params;
 }
 
-type Dict = Record<string, unknown>;
-
-interface SamplingOptions {
-	percentage?: number;
-}
-
-interface ErrorTrackingConfig {
-	enabled?: boolean;
-}
-
-interface WebVitalsConfig {
-	sampling?: SamplingOptions;
-}
-
-interface SessionReplayConfig {
-	sampling?: SamplingOptions;
-}
-
-export type ConsentMode = "pending" | "granted" | "denied";
-
-interface ConsentConfig {
-	mode?: ConsentMode;
-	cookielessWhilePending?: boolean;
-}
-
-export interface IdentifyOptions {
-	name?: string;
-	phone?: string;
-	avatarUrl?: string;
-	traits?: Record<string, unknown>;
-}
-
-export interface WebAnalyticsOptions {
-	siteKey: string;
-	endpoint?: string;
-	debug?: boolean;
-	autoTrack?: boolean;
-	trackHash?: boolean;
-	trackErrors?: boolean;
-	trackWebVitals?: boolean;
-	trackReplay?: boolean;
-	cookieless?: boolean;
-	consent?: ConsentConfig;
-	errorTracking?: ErrorTrackingConfig;
-	webVitals?: WebVitalsConfig;
-	sessionReplays?: SessionReplayConfig;
-	replayOptions?: Partial<ReplayTrackerOptions>;
-}
-
 export class WebAnalytics {
-	private readonly endpoint: string;
+	private readonly webEndpoint: string;
+	private readonly baseUrl: string;
 	private readonly debug: boolean;
 	private started = false;
+	private destroyed = false;
 	private pageKey = "";
 	private navTimer: ReturnType<typeof setTimeout> | null = null;
 	private heartbeatTimer: ReturnType<typeof setInterval> | null = null;
@@ -198,9 +213,30 @@ export class WebAnalytics {
 	private scrollHandler: (() => void) | null = null;
 	private consentMode: ConsentMode;
 	private readonly cookielessWhilePending: boolean;
+	private readonly cleanupCallbacks: Array<() => void> = [];
+	private readonly childTrackers: ChildTracker[] = [];
+	private readonly pendingReportedErrors: Error[] = [];
+	private readonly handleVisibilityChange = (): void => {
+		if (document.visibilityState === "hidden") {
+			this.leavePage();
+			this.stopHeartbeat();
+		} else {
+			this.startHeartbeat();
+		}
+	};
+	private readonly handlePageHide = (): void => {
+		this.leavePage();
+	};
+	private readonly handlePopState = (): void => {
+		this.navigate();
+	};
+	private readonly handleHashChange = (): void => {
+		this.navigate();
+	};
 
 	constructor(private readonly options: WebAnalyticsOptions) {
-		this.endpoint = options.endpoint ?? "https://metrics.faststats.dev/v1/web";
+		this.baseUrl = normalizeAnalyticsBaseUrl(options.baseUrl);
+		this.webEndpoint = webEventsUrl(this.baseUrl);
 		this.debug = options.debug ?? false;
 		this.consentMode = options.consent?.mode ?? "granted";
 		this.cookielessWhilePending =
@@ -219,11 +255,92 @@ export class WebAnalytics {
 			return;
 		}
 		_instance = this;
+		setCookielessMode(this.isCookielessMode());
 		setTimeout(() => void this.start(), 0);
 	}
 
+	private registerCleanup(cleanup: () => void): void {
+		this.cleanupCallbacks.push(cleanup);
+	}
+
+	private addWindowListener<K extends keyof WindowEventMap>(
+		type: K,
+		listener: (event: WindowEventMap[K]) => void,
+	): void {
+		window.addEventListener(type, listener);
+		this.registerCleanup(() => window.removeEventListener(type, listener));
+	}
+
+	private addDocumentListener<K extends keyof DocumentEventMap>(
+		type: K,
+		listener: (event: DocumentEventMap[K]) => void,
+	): void {
+		document.addEventListener(type, listener);
+		this.registerCleanup(() => document.removeEventListener(type, listener));
+	}
+
+	private patchHistory(): void {
+		const originalPushState = history.pushState.bind(history);
+		const originalReplaceState = history.replaceState.bind(history);
+
+		history.pushState = (data, unused, url) => {
+			originalPushState(data, unused, url);
+			this.navigate();
+		};
+		history.replaceState = (data, unused, url) => {
+			originalReplaceState(data, unused, url);
+			this.navigate();
+		};
+
+		this.registerCleanup(() => {
+			history.pushState = originalPushState;
+			history.replaceState = originalReplaceState;
+		});
+	}
+
+	private ensureStarted(): boolean {
+		if (
+			typeof window === "undefined" ||
+			this.destroyed ||
+			isTrackingDisabled()
+		) {
+			return false;
+		}
+		if (!this.started) {
+			void this.start();
+		}
+		return true;
+	}
+
+	private stopHeartbeat(): void {
+		if (this.heartbeatTimer) {
+			clearInterval(this.heartbeatTimer);
+			this.heartbeatTimer = null;
+		}
+	}
+
+	private stopNavigationTimer(): void {
+		if (this.navTimer) {
+			clearTimeout(this.navTimer);
+			this.navTimer = null;
+		}
+	}
+
+	private stopChildTrackers(): void {
+		for (const tracker of this.childTrackers.splice(0)) {
+			tracker.stop?.();
+		}
+	}
+
+	private getErrorTracker(): ErrorTracker | null {
+		for (const t of this.childTrackers) {
+			if ("captureError" in t) return t as ErrorTracker;
+		}
+		return null;
+	}
+
 	async start(): Promise<void> {
-		if (this.started || typeof window === "undefined") return;
+		if (this.started || this.destroyed || typeof window === "undefined") return;
 		if (_instance && _instance !== this) {
 			this.log("already started by another instance");
 			return;
@@ -232,42 +349,58 @@ export class WebAnalytics {
 			this.log("disabled");
 			return;
 		}
+
 		this.started = true;
 		_instance = this;
-
 		setCookielessMode(this.isCookielessMode());
-		const opts = this.options;
 
-		if (opts.errorTracking?.enabled ?? opts.trackErrors) {
-			const { default: ErrorTracker } = await import("./error");
-			new ErrorTracker({
-				siteKey: opts.siteKey,
-				endpoint: this.endpoint,
-				debug: this.debug,
-			}).start();
-			this.log("error loaded");
-		}
-		if (opts.trackWebVitals) {
-			const { default: WebVitalsTracker } = await import("./web-vitals");
-			new WebVitalsTracker({
-				siteKey: opts.siteKey,
-				endpoint: this.endpoint,
-				debug: this.debug,
-				samplingPercentage: normalizeSamplingPercentage(
-					opts.webVitals?.sampling?.percentage,
-				),
-			}).start();
-			this.log("web-vitals loaded");
-		}
-		if (opts.trackReplay) {
-			const { default: ReplayTracker } = await import("./replay");
-			new ReplayTracker({
-				siteKey: opts.siteKey,
-				endpoint: this.endpoint,
-				debug: this.debug,
-				...opts.replayOptions,
-			}).start();
-			this.log("replay loaded");
+		const opts = this.options;
+		try {
+			if (opts.trackErrors) {
+				const { default: ErrorTrackerClass } = await import("./error");
+				const errorTracker: ErrorTracker = new ErrorTrackerClass({
+					siteKey: opts.siteKey,
+					baseUrl: this.baseUrl,
+					debug: this.debug,
+				});
+				errorTracker.start();
+				this.childTrackers.push(errorTracker);
+				while (this.pendingReportedErrors.length > 0) {
+					const pending = this.pendingReportedErrors.shift();
+					if (pending) errorTracker.captureError(pending);
+				}
+				this.log("error loaded");
+			}
+			if (opts.trackWebVitals) {
+				const { default: WebVitalsTrackerClass } = await import("./web-vitals");
+				const webVitalsTracker: WebVitalsTracker = new WebVitalsTrackerClass({
+					siteKey: opts.siteKey,
+					baseUrl: this.baseUrl,
+					debug: this.debug,
+					samplingPercentage: normalizeSamplingPercentage(
+						opts.webVitals?.sampling?.percentage,
+					),
+				});
+				webVitalsTracker.start();
+				this.childTrackers.push(webVitalsTracker);
+				this.log("web-vitals loaded");
+			}
+			if (opts.trackReplay) {
+				const { default: ReplayTrackerClass } = await import("./replay");
+				const replayTracker: ReplayTracker = new ReplayTrackerClass({
+					siteKey: opts.siteKey,
+					baseUrl: this.baseUrl,
+					debug: this.debug,
+					...opts.replayOptions,
+				});
+				replayTracker.start();
+				this.childTrackers.push(replayTracker);
+				this.log("replay loaded");
+			}
+		} catch (error) {
+			this.log(`failed to initialize trackers: ${String(error)}`);
+			this.destroy();
+			return;
 		}
 
 		this.enterPage();
@@ -276,18 +409,46 @@ export class WebAnalytics {
 		this.trackScroll();
 		this.startHeartbeat();
 
-		document.addEventListener("visibilitychange", () => {
-			if (document.visibilityState === "hidden") this.leavePage();
-			else this.startHeartbeat();
-		});
-		window.addEventListener("pagehide", () => this.leavePage());
-		window.addEventListener("popstate", () => this.navigate());
-		if (opts.trackHash)
-			window.addEventListener("hashchange", () => this.navigate());
-		this.patch();
+		this.addDocumentListener("visibilitychange", this.handleVisibilityChange);
+		this.addWindowListener("pagehide", this.handlePageHide);
+		this.addWindowListener("popstate", this.handlePopState);
+		if (opts.trackHash) {
+			this.addWindowListener("hashchange", this.handleHashChange);
+		}
+		this.patchHistory();
+	}
+
+	destroy(): void {
+		if (this.destroyed) return;
+		if (this.started && typeof window !== "undefined") {
+			this.leavePage();
+		}
+
+		this.pendingReportedErrors.length = 0;
+
+		this.stopNavigationTimer();
+		this.stopHeartbeat();
+
+		if (this.scrollHandler && typeof window !== "undefined") {
+			window.removeEventListener("scroll", this.scrollHandler);
+			this.scrollHandler = null;
+		}
+
+		while (this.cleanupCallbacks.length > 0) {
+			const cleanup = this.cleanupCallbacks.pop();
+			cleanup?.();
+		}
+
+		this.stopChildTrackers();
+		if (_instance === this) {
+			_instance = null;
+		}
+		this.started = false;
+		this.destroyed = true;
 	}
 
 	pageview(extra: Dict = {}): void {
+		if (!this.ensureStarted()) return;
 		const key = `${location.pathname}|${(this.options.trackHash ?? false) ? location.hash : ""}`;
 		if (key === this.pageKey) return;
 		this.pageKey = key;
@@ -295,6 +456,7 @@ export class WebAnalytics {
 	}
 
 	track(name: string, extra: Dict = {}): void {
+		if (!this.ensureStarted()) return;
 		this.send(name, extra);
 	}
 
@@ -303,17 +465,14 @@ export class WebAnalytics {
 		email: string,
 		options: IdentifyOptions = {},
 	): void {
-		if (isTrackingDisabled()) return;
+		if (!this.ensureStarted()) return;
 		if (this.isCookielessMode()) return;
 
 		const trimmedExternalId = externalId.trim();
 		const trimmedEmail = email.trim();
 		if (!trimmedExternalId || !trimmedEmail) return;
 
-		const identifyEndpoint = this.endpoint.replace(
-			/\/v1\/web$/,
-			"/v1/identify",
-		);
+		const identifyEndpoint = identifyEventsUrl(this.baseUrl);
 		const payload = JSON.stringify({
 			token: this.options.siteKey,
 			identifier: getAnonymousId(false),
@@ -325,7 +484,7 @@ export class WebAnalytics {
 			traits: options.traits ?? {},
 		});
 
-		sendData({
+		void sendData({
 			url: identifyEndpoint,
 			data: payload,
 			contentType: "text/plain",
@@ -335,7 +494,7 @@ export class WebAnalytics {
 	}
 
 	logout(resetAnonymousIdentity = true): void {
-		if (isTrackingDisabled()) return;
+		if (!this.ensureStarted()) return;
 		if (resetAnonymousIdentity) {
 			resetAnonymousId(this.isCookielessMode());
 		}
@@ -367,6 +526,27 @@ export class WebAnalytics {
 		return getOrCreateSessionId();
 	}
 
+	reportError(error: Error): void {
+		if (
+			this.destroyed ||
+			typeof window === "undefined" ||
+			isTrackingDisabled()
+		) {
+			return;
+		}
+		if (!(this.options.trackErrors ?? false)) return;
+		if (!this.ensureStarted()) return;
+		const tracker = this.getErrorTracker();
+		if (tracker) {
+			tracker.captureError(error);
+			return;
+		}
+		if (this.pendingReportedErrors.length >= 50) {
+			this.pendingReportedErrors.shift();
+		}
+		this.pendingReportedErrors.push(error);
+	}
+
 	private isCookielessMode(): boolean {
 		if (this.options.cookieless) return true;
 		if (this.consentMode === "denied") return true;
@@ -375,6 +555,14 @@ export class WebAnalytics {
 	}
 
 	private send(event: string, extra: Dict = {}): void {
+		if (
+			typeof window === "undefined" ||
+			this.destroyed ||
+			isTrackingDisabled()
+		) {
+			return;
+		}
+
 		const identifier = getAnonymousId(this.isCookielessMode());
 		const payload = JSON.stringify({
 			token: this.options.siteKey,
@@ -391,8 +579,8 @@ export class WebAnalytics {
 			},
 		});
 		this.log(event);
-		sendData({
-			url: this.endpoint,
+		void sendData({
+			url: this.webEndpoint,
 			data: payload,
 			contentType: "text/plain",
 			debug: this.debug,
@@ -410,7 +598,7 @@ export class WebAnalytics {
 	}
 
 	private leavePage(): void {
-		if (this.hasLeftCurrentPage) return;
+		if (this.destroyed || this.hasLeftCurrentPage) return;
 		this.hasLeftCurrentPage = true;
 		const now = Date.now();
 		this.send("page_leave", {
@@ -449,12 +637,11 @@ export class WebAnalytics {
 	}
 
 	private startHeartbeat(): void {
-		if (this.heartbeatTimer) clearInterval(this.heartbeatTimer);
+		this.stopHeartbeat();
 		this.heartbeatTimer = setInterval(
 			() => {
 				if (document.visibilityState === "hidden") {
-					clearInterval(this.heartbeatTimer as ReturnType<typeof setInterval>);
-					this.heartbeatTimer = null;
+					this.stopHeartbeat();
 					return;
 				}
 				refreshSessionTimestamp();
@@ -464,7 +651,8 @@ export class WebAnalytics {
 	}
 
 	private navigate(): void {
-		if (this.navTimer) clearTimeout(this.navTimer);
+		if (!this.started || this.destroyed) return;
+		this.stopNavigationTimer();
 		this.navTimer = setTimeout(() => {
 			this.navTimer = null;
 			const pathChanged = location.pathname !== this.pagePath;
@@ -478,28 +666,14 @@ export class WebAnalytics {
 		}, 300);
 	}
 
-	private patch(): void {
-		const fire = () => this.navigate();
-		for (const method of ["pushState", "replaceState"] as const) {
-			const orig = history[method];
-			history[method] = function (
-				this: History,
-				...args: Parameters<typeof orig>
-			) {
-				const result = orig.apply(this, args);
-				fire();
-				return result;
-			};
-		}
-	}
-
 	private links(): void {
 		const handler = (event: MouseEvent) => {
 			const link = getLinkEl(event.target as Node);
-			if (link && link.host !== location.host)
+			if (link && link.host !== location.host) {
 				this.track("outbound_link", { outbound_link: link.href });
+			}
 		};
-		document.addEventListener("click", handler);
-		document.addEventListener("auxclick", handler);
+		this.addDocumentListener("click", handler);
+		this.addDocumentListener("auxclick", handler);
 	}
 }