@faststats/web 0.2.14 → 0.3.0

package/src/analytics.ts

@@ -1,787 +0,0 @@
-import type ErrorTracker from "./error";
-import type { FeatureFlagEvaluation } from "./feature-flags";
-import type { ReplayTrackerOptions } from "./replay";
-import {
-	normalizeAnalyticsBaseUrl,
-	normalizeFeatureFlagsBaseUrl,
-	URLS,
-} from "./utils/api-urls";
-import { getAnonymousId, resetAnonymousId } from "./utils/identifiers";
-import { sendData } from "./utils/send-data";
-import {
-	getOrCreateSessionId,
-	getSessionContext,
-	getSessionStart,
-	refreshSessionTimestamp,
-	resetSession,
-	setCookielessMode,
-	setDefaultSiteKey,
-} from "./utils/session-manager";
-import {
-	normalizeSamplingPercentage,
-	type SendDataOptions,
-} from "./utils/types";
-
-export type { SendDataOptions };
-export { sendData };
-
-type ChildTracker = {
-	start(): void;
-	stop?(): void;
-	trackPageChange?(url?: string): void;
-};
-type TrackerFactory<T extends ChildTracker> = () => Promise<T>;
-
-type Dict = Record<string, unknown>;
-
-interface SamplingOptions {
-	percentage?: number;
-}
-
-interface WebVitalsConfig {
-	sampling?: SamplingOptions;
-	attribution?: boolean;
-}
-
-interface SessionReplayConfig {
-	enabled?: boolean;
-	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;
-	featureFlagsBaseUrl?: string;
-	debug?: boolean;
-	autoTrack?: boolean;
-	trackHash?: boolean;
-	trackErrors?: boolean;
-	trackWebVitals?: boolean;
-	trackReplay?: boolean;
-	cookieless?: boolean;
-	consent?: ConsentConfig;
-	webVitals?: WebVitalsConfig;
-	sessionReplays?: SessionReplayConfig;
-	replayOptions?: Partial<ReplayTrackerOptions>;
-	/** @internal */
-	sdkName?: string;
-	/** @internal */
-	sdkVersion?: string;
-}
-
-function hasReplaySamplingConfig(options: WebAnalyticsOptions): boolean {
-	return (
-		options.replayOptions?.samplingPercentage !== undefined ||
-		options.sessionReplays?.sampling?.percentage !== undefined
-	);
-}
-
-export function resolveReplayTrackerOptions(
-	options: WebAnalyticsOptions,
-	baseUrl: string,
-	debug: boolean,
-): ReplayTrackerOptions | null {
-	const replayEnabled =
-		options.sessionReplays?.enabled ??
-		options.trackReplay ??
-		hasReplaySamplingConfig(options);
-
-	if (!replayEnabled) return null;
-
-	const replayOptions = options.replayOptions ?? {};
-
-	return {
-		siteKey: options.siteKey,
-		baseUrl,
-		debug,
-		...replayOptions,
-		samplingPercentage: normalizeSamplingPercentage(
-			replayOptions.samplingPercentage ??
-				options.sessionReplays?.sampling?.percentage,
-		),
-	};
-}
-
-const moduleState: {
-	instance: WebAnalytics | null;
-	pendingConsentMode: ConsentMode | undefined;
-} = {
-	instance: null,
-	pendingConsentMode: undefined,
-};
-
-export function getInstance(): WebAnalytics | null {
-	return moduleState.instance;
-}
-
-export function trackEvent(
-	eventName: string,
-	properties?: Record<string, unknown>,
-): void {
-	if (typeof window === "undefined" || isTrackingDisabled()) return;
-	moduleState.instance?.track(eventName, properties ?? {});
-}
-
-export function identify(
-	externalId: string,
-	email: string,
-	options?: IdentifyOptions,
-): Promise<boolean> {
-	if (typeof window === "undefined" || isTrackingDisabled()) {
-		return Promise.resolve(false);
-	}
-	return (
-		moduleState.instance?.identify(externalId, email, options ?? {}) ??
-		Promise.resolve(false)
-	);
-}
-
-export function logout(resetAnonymousIdentity = true): void {
-	if (typeof window === "undefined" || isTrackingDisabled()) return;
-	moduleState.instance?.logout(resetAnonymousIdentity);
-}
-
-export function setConsentMode(mode: ConsentMode): void {
-	if (moduleState.instance) {
-		moduleState.instance.setConsentMode(mode);
-		return;
-	}
-	moduleState.pendingConsentMode = mode;
-}
-
-export function optIn(): void {
-	setConsentMode("granted");
-}
-
-export function optOut(): void {
-	setConsentMode("denied");
-}
-
-export function reportError(error: Error): void {
-	if (typeof window === "undefined" || isTrackingDisabled()) return;
-	moduleState.instance?.reportError(error);
-}
-
-export function isTrackingDisabled(): boolean {
-	if (typeof localStorage === "undefined") return false;
-	const value = localStorage.getItem("disable-faststats");
-	return value === "true" || value === "1";
-}
-
-function getLinkEl(el: Node | null): HTMLAnchorElement | null {
-	while (el) {
-		if (el instanceof HTMLAnchorElement && el.href) return el;
-		el = el.parentNode;
-	}
-	return null;
-}
-
-function getUTM(): Record<string, string> {
-	const params: Record<string, string> = {};
-	if (!location.search) return params;
-	const sp = new URLSearchParams(location.search);
-	for (const k of [
-		"utm_source",
-		"utm_medium",
-		"utm_campaign",
-		"utm_term",
-		"utm_content",
-	]) {
-		const v = sp.get(k);
-		if (v) params[k] = v;
-	}
-	return params;
-}
-
-export class WebAnalytics {
-	private readonly webEndpoint: string;
-	private readonly baseUrl: string;
-	private readonly featureFlagsBaseUrl: 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;
-	private scrollDepth = 0;
-	private pageEntryTime = 0;
-	private pagePath = "";
-	private pageUrl = "";
-	private pageHash = "";
-	private hasLeftCurrentPage = false;
-	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 errorTracker: ErrorTracker | null = null;
-	private readonly handleVisibilityChange = (): void => {
-		if (document.visibilityState === "hidden") {
-			refreshSessionTimestamp();
-			this.leavePage();
-			this.stopHeartbeat();
-		} else {
-			refreshSessionTimestamp();
-			this.enterPage();
-			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.baseUrl = normalizeAnalyticsBaseUrl(options.baseUrl);
-		this.featureFlagsBaseUrl = normalizeFeatureFlagsBaseUrl(
-			options.featureFlagsBaseUrl,
-		);
-		this.webEndpoint = `${this.baseUrl}${URLS.events}`;
-		this.debug = options.debug ?? false;
-		this.consentMode = options.consent?.mode ?? "granted";
-		this.cookielessWhilePending =
-			options.consent?.cookielessWhilePending ?? true;
-		if (moduleState.pendingConsentMode !== undefined) {
-			this.consentMode = moduleState.pendingConsentMode;
-			moduleState.pendingConsentMode = undefined;
-		}
-		if (options.autoTrack ?? true) this.init();
-	}
-
-	private log(msg: string): void {
-		if (this.debug) console.log(`[Analytics] ${msg}`);
-	}
-
-	private init(): void {
-		if (typeof window === "undefined") return;
-		if (isTrackingDisabled()) {
-			this.log("disabled");
-			return;
-		}
-		moduleState.instance = this;
-		setDefaultSiteKey(this.options.siteKey);
-		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?.();
-		}
-		this.errorTracker = null;
-	}
-
-	private registerChildTracker(tracker: ChildTracker): boolean {
-		if (!this.started || this.destroyed || moduleState.instance !== this) {
-			tracker.stop?.();
-			return false;
-		}
-
-		this.childTrackers.push(tracker);
-		return true;
-	}
-
-	private async startChildTracker<T extends ChildTracker>(
-		name: string,
-		createTracker: TrackerFactory<T>,
-		onStarted?: (tracker: T) => void,
-	): Promise<T | null> {
-		try {
-			const tracker = await createTracker();
-			if (!this.started || this.destroyed || moduleState.instance !== this) {
-				tracker.stop?.();
-				return null;
-			}
-
-			tracker.start();
-			if (!this.registerChildTracker(tracker)) return null;
-
-			onStarted?.(tracker);
-			this.log(`${name} loaded`);
-			return tracker;
-		} catch (error) {
-			this.log(`failed to initialize ${name} tracker: ${String(error)}`);
-			return null;
-		}
-	}
-
-	private async startErrorTracker(): Promise<void> {
-		await this.startChildTracker(
-			"error",
-			async () => {
-				const { default: ErrorTrackerClass } = await import("./error");
-				return new ErrorTrackerClass({
-					siteKey: this.options.siteKey,
-					baseUrl: this.baseUrl,
-					debug: this.debug,
-					sdkName: this.options.sdkName,
-					sdkVersion: this.options.sdkVersion,
-				});
-			},
-			(errorTracker) => {
-				this.errorTracker = errorTracker;
-
-				while (this.pendingReportedErrors.length > 0) {
-					const pending = this.pendingReportedErrors.shift();
-					if (pending) errorTracker.captureError(pending);
-				}
-			},
-		);
-	}
-
-	private async startWebVitalsTracker(): Promise<void> {
-		await this.startChildTracker("web-vitals", async () => {
-			const { default: WebVitalsTrackerClass } = await import("./web-vitals");
-			return new WebVitalsTrackerClass({
-				siteKey: this.options.siteKey,
-				baseUrl: this.baseUrl,
-				debug: this.debug,
-				samplingPercentage: normalizeSamplingPercentage(
-					this.options.webVitals?.sampling?.percentage,
-				),
-				attribution: this.options.webVitals?.attribution ?? false,
-			});
-		});
-	}
-
-	private async startReplayTracker(
-		replayOptions: ReplayTrackerOptions,
-	): Promise<void> {
-		await this.startChildTracker("replay", async () => {
-			const { default: ReplayTrackerClass } = await import("./replay");
-			return new ReplayTrackerClass(replayOptions);
-		});
-	}
-
-	async start(): Promise<void> {
-		if (this.started || this.destroyed || typeof window === "undefined") return;
-		if (moduleState.instance && moduleState.instance !== this) {
-			this.log("already started by another instance");
-			return;
-		}
-		if (isTrackingDisabled()) {
-			this.log("disabled");
-			return;
-		}
-
-		this.started = true;
-		moduleState.instance = this;
-		setDefaultSiteKey(this.options.siteKey);
-		setCookielessMode(this.isCookielessMode());
-		getOrCreateSessionId();
-
-		const opts = this.options;
-		const replayOptions = resolveReplayTrackerOptions(
-			opts,
-			this.baseUrl,
-			this.debug,
-		);
-		if (replayOptions) {
-			void this.startReplayTracker({
-				...replayOptions,
-				cookieless: this.isCookielessMode(),
-			});
-		}
-		if (opts.trackErrors) {
-			void this.startErrorTracker();
-		}
-		if (opts.trackWebVitals) {
-			void this.startWebVitalsTracker();
-		}
-
-		this.enterPage();
-		this.pageview({ trigger: "load" });
-		this.links();
-		this.trackScroll();
-		this.startHeartbeat();
-
-		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 (moduleState.instance === this) {
-			moduleState.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;
-		this.send("pageview", extra);
-	}
-
-	track(name: string, extra: Dict = {}): void {
-		if (!this.ensureStarted()) return;
-		this.send(name, extra);
-	}
-
-	identify(
-		externalId: string,
-		email: string,
-		options: IdentifyOptions = {},
-	): Promise<boolean> {
-		if (!this.ensureStarted()) return Promise.resolve(false);
-		if (this.isCookielessMode()) return Promise.resolve(false);
-
-		const trimmedExternalId = externalId.trim();
-		const trimmedEmail = email.trim();
-		if (!trimmedExternalId || !trimmedEmail) return Promise.resolve(false);
-
-		const identifyEndpoint = `${this.baseUrl}${URLS.identify}`;
-		const payload = JSON.stringify({
-			token: this.options.siteKey,
-			identifier: getAnonymousId(false),
-			externalId: trimmedExternalId,
-			email: trimmedEmail,
-			name: options.name?.trim() || undefined,
-			phone: options.phone?.trim() || undefined,
-			avatarUrl: options.avatarUrl?.trim() || undefined,
-			traits: options.traits ?? {},
-		});
-
-		return sendData({
-			url: identifyEndpoint,
-			data: payload,
-			contentType: "text/plain",
-			debug: this.debug,
-			debugPrefix: "[Analytics] identify",
-			useBeacon: false,
-		});
-	}
-
-	logout(resetAnonymousIdentity = true): void {
-		if (!this.ensureStarted()) return;
-		if (resetAnonymousIdentity) {
-			resetAnonymousId(this.isCookielessMode());
-		}
-		resetSession(this.options.siteKey);
-	}
-
-	setConsentMode(mode: ConsentMode): void {
-		this.consentMode = mode;
-		setCookielessMode(this.isCookielessMode());
-	}
-
-	optIn(): void {
-		this.setConsentMode("granted");
-	}
-
-	optOut(): void {
-		this.setConsentMode("denied");
-	}
-
-	getConsentMode(): ConsentMode {
-		return this.consentMode;
-	}
-
-	getAnonymousId(): string {
-		return getAnonymousId(this.isCookielessMode());
-	}
-
-	getSessionId(): string {
-		return getOrCreateSessionId();
-	}
-
-	getWindowId(): string {
-		return getSessionContext(this.options.siteKey, this.isCookielessMode())
-			.windowId;
-	}
-
-	async checkFeatureFlag(
-		key: string,
-		attributes?: Record<string, unknown>,
-		opts?: { externalId?: string; signal?: AbortSignal },
-	): Promise<FeatureFlagEvaluation> {
-		if (typeof window === "undefined" || isTrackingDisabled()) {
-			return { value: "false" };
-		}
-		const externalId = opts?.externalId?.trim();
-		const identifier = this.getAnonymousId();
-		if (!externalId && !identifier) {
-			return { value: "false" };
-		}
-
-		const { fetchFeatureFlagEvaluation } = await import("./feature-flags");
-		return fetchFeatureFlagEvaluation(key, {
-			baseUrl: this.featureFlagsBaseUrl,
-			projectToken: this.options.siteKey,
-			...(identifier ? { identifier } : {}),
-			...(externalId ? { externalId } : {}),
-			sessionId: this.getSessionId(),
-			attributes,
-			signal: opts?.signal,
-		});
-	}
-
-	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.errorTracker;
-		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;
-		if (this.consentMode === "pending") return this.cookielessWhilePending;
-		return false;
-	}
-
-	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,
-			...(identifier ? { userId: identifier } : {}),
-			sessionId: getOrCreateSessionId(),
-			data: {
-				event,
-				page: location.pathname,
-				referrer: document.referrer || null,
-				title: document.title || "",
-				url: location.href,
-				...getUTM(),
-				...extra,
-			},
-		});
-		this.log(event);
-		void sendData({
-			url: this.webEndpoint,
-			data: payload,
-			contentType: "text/plain",
-			debug: this.debug,
-			debugPrefix: `[Analytics] ${event}`,
-		});
-	}
-
-	private enterPage(): void {
-		this.pageEntryTime = Date.now();
-		this.pagePath = location.pathname;
-		this.pageUrl = location.href;
-		this.pageHash = location.hash;
-		this.scrollDepth = 0;
-		this.hasLeftCurrentPage = false;
-	}
-
-	private leavePage(): void {
-		if (this.destroyed || this.hasLeftCurrentPage) return;
-		this.hasLeftCurrentPage = true;
-		const now = Date.now();
-		this.send("page_leave", {
-			page: this.pagePath,
-			url: this.pageUrl,
-			time_on_page: now - this.pageEntryTime,
-			scroll_depth: this.scrollDepth,
-			session_duration: now - getSessionStart(),
-		});
-	}
-
-	private trackScroll(): void {
-		if (this.scrollHandler) {
-			window.removeEventListener("scroll", this.scrollHandler);
-		}
-		const update = () => {
-			const doc = document.documentElement;
-			const body = document.body;
-			const viewportH = window.innerHeight;
-			const docH = Math.max(doc.scrollHeight, body.scrollHeight);
-			if (docH <= viewportH) {
-				this.scrollDepth = 100;
-				return;
-			}
-			const depth = Math.min(
-				100,
-				Math.round(
-					(((window.scrollY || doc.scrollTop) + viewportH) / docH) * 100,
-				),
-			);
-			if (depth > this.scrollDepth) this.scrollDepth = depth;
-		};
-		this.scrollHandler = update;
-		update();
-		window.addEventListener("scroll", update, { passive: true });
-	}
-
-	private startHeartbeat(): void {
-		this.stopHeartbeat();
-		this.heartbeatTimer = setInterval(
-			() => {
-				if (document.visibilityState === "hidden") {
-					this.stopHeartbeat();
-					return;
-				}
-				refreshSessionTimestamp();
-			},
-			5 * 60 * 1000,
-		);
-	}
-
-	private navigate(): void {
-		if (!this.started || this.destroyed) return;
-		this.stopNavigationTimer();
-		this.navTimer = setTimeout(() => {
-			this.navTimer = null;
-			const pathChanged = location.pathname !== this.pagePath;
-			const hashChanged =
-				(this.options.trackHash ?? false) && location.hash !== this.pageHash;
-			if (!pathChanged && !hashChanged) return;
-			for (const tracker of this.childTrackers) {
-				tracker.trackPageChange?.(location.href);
-			}
-			this.leavePage();
-			this.enterPage();
-			this.trackScroll();
-			this.pageview({ trigger: "navigation" });
-		}, 300);
-	}
-
-	private links(): void {
-		const handler = (event: MouseEvent) => {
-			const link = getLinkEl(event.target as Node);
-			if (link && link.host !== location.host) {
-				this.track("outbound_link", { outbound_link: link.href });
-			}
-		};
-		this.addDocumentListener("click", handler);
-		this.addDocumentListener("auxclick", handler);
-	}
-}