@faststats/web 0.0.1

package/src/replay.ts

@@ -0,0 +1,488 @@
+import { getRecordConsolePlugin } from "@rrweb/rrweb-plugin-console-record";
+import type { eventWithTime, listenerHandler } from "@rrweb/types";
+import { record } from "rrweb";
+import type { recordOptions } from "rrweb/typings/types";
+import type { SlimDOMOptions } from "rrweb-snapshot";
+import {
+	normalizeSamplingPercentage,
+	type SendDataOptions,
+} from "./utils/types";
+
+export interface ReplayTrackerOptions {
+	siteKey: string;
+	endpoint?: string;
+	debug?: boolean;
+	samplingPercentage?: number;
+	flushInterval?: number;
+	maxEvents?: number;
+	sampling?: recordOptions<eventWithTime>["sampling"];
+	slimDOMOptions?: SlimDOMOptions;
+	maskAllInputs?: boolean;
+	maskInputOptions?: recordOptions<eventWithTime>["maskInputOptions"];
+	blockClass?: string;
+	blockSelector?: string;
+	maskTextClass?: string;
+	maskTextSelector?: string;
+	checkoutEveryNms?: number;
+	checkoutEveryNth?: number;
+	recordConsole?: boolean;
+}
+
+type ReplayTrackerPublicInstance = {
+	start(): void;
+	stop(): void;
+	getSessionId(): string | undefined;
+};
+
+type ReplayTrackerConstructor = new (
+	options: ReplayTrackerOptions,
+) => ReplayTrackerPublicInstance;
+
+interface PendingBatch {
+	batch: {
+		token: string;
+		sessionId: string | undefined;
+		sequence: number;
+		timestamp: number;
+		url: string;
+		events: eventWithTime[];
+	};
+	isCompressed: boolean;
+	retries: number;
+}
+
+class ReplayTracker {
+	private readonly endpoint: string;
+	private readonly siteKey: string;
+	private readonly debug: boolean;
+	private readonly flushInterval: number;
+	private readonly maxEvents: number;
+	private readonly sampling: recordOptions<eventWithTime>["sampling"];
+	private readonly slimDOMOptions: SlimDOMOptions;
+	private readonly maskAllInputs: boolean;
+	private readonly maskInputOptions?: recordOptions<eventWithTime>["maskInputOptions"];
+	private readonly blockClass?: string;
+	private readonly blockSelector?: string;
+	private readonly maskTextClass?: string;
+	private readonly maskTextSelector?: string;
+	private readonly checkoutEveryNms: number;
+	private readonly checkoutEveryNth?: number;
+	private readonly samplingPercentage: number;
+	private readonly recordConsole: boolean;
+
+	private events: eventWithTime[] = [];
+	private flushTimer: ReturnType<typeof setInterval> | null = null;
+	private stopRecording: listenerHandler | undefined = undefined;
+	private started = false;
+	private startTime: number = 0;
+	private sequenceNumber = 0;
+	private pendingBatches: PendingBatch[] = [];
+	private isFlushing = false;
+	private compressionSupported = false;
+	private readonly sessionSamplingSeed: number;
+	private readonly minReplayLengthMs = 3000;
+
+	constructor(options: ReplayTrackerOptions) {
+		this.siteKey = options.siteKey;
+		this.endpoint =
+			options.endpoint?.replace(/\/v1\/web$/, "/v1/replay") ??
+			"https://metrics.faststats.dev/v1/replay";
+		this.debug = options.debug ?? false;
+		this.samplingPercentage = normalizeSamplingPercentage(
+			options.samplingPercentage,
+		);
+		this.flushInterval = options.flushInterval ?? 10_000;
+		this.maxEvents = options.maxEvents ?? 500;
+		this.sampling = options.sampling ?? {
+			mousemove: 50,
+			mouseInteraction: true,
+			scroll: 150,
+			media: 800,
+			input: "last",
+		};
+		this.slimDOMOptions = options.slimDOMOptions ?? {
+			script: true,
+			comment: true,
+			headFavicon: true,
+			headWhitespace: true,
+			headMetaDescKeywords: true,
+			headMetaSocial: true,
+			headMetaRobots: true,
+			headMetaHttpEquiv: true,
+			headMetaAuthorship: true,
+		};
+		this.maskAllInputs = options.maskAllInputs ?? true;
+		this.maskInputOptions = options.maskInputOptions ?? {
+			password: true,
+			email: true,
+			tel: true,
+		};
+		this.blockClass = options.blockClass;
+		this.blockSelector = options.blockSelector;
+		this.maskTextClass = options.maskTextClass;
+		this.maskTextSelector = options.maskTextSelector;
+		this.checkoutEveryNms = options.checkoutEveryNms ?? 60_000;
+		this.checkoutEveryNth = options.checkoutEveryNth;
+		this.recordConsole = options.recordConsole ?? true;
+		this.sessionSamplingSeed = Math.random() * 100;
+
+		if (typeof window !== "undefined") {
+			this.compressionSupported = "CompressionStream" in window;
+		}
+	}
+
+	start(): void {
+		if (this.started || typeof window === "undefined") return;
+		if (window.__FA_isTrackingDisabled?.()) {
+			if (this.debug) {
+				console.log("[Replay] Tracking disabled via localStorage");
+			}
+			return;
+		}
+
+		if (this.samplingPercentage < 100) {
+			if (this.sessionSamplingSeed >= this.samplingPercentage) {
+				return;
+			}
+		}
+
+		this.started = true;
+		this.startTime = Date.now();
+
+		if (this.debug) {
+			console.log("[Replay] Recording started");
+		}
+
+		const recordOptions: recordOptions<eventWithTime> = {
+			emit: (event, isCheckout) => this.handleEvent(event, isCheckout),
+			sampling: this.sampling,
+			slimDOMOptions: this.slimDOMOptions,
+			maskAllInputs: this.maskAllInputs,
+			checkoutEveryNms: this.checkoutEveryNms,
+		};
+
+		if (this.maskInputOptions) {
+			recordOptions.maskInputOptions = this.maskInputOptions;
+		}
+		if (this.blockClass) {
+			recordOptions.blockClass = this.blockClass;
+		}
+		if (this.blockSelector) {
+			recordOptions.blockSelector = this.blockSelector;
+		}
+		if (this.maskTextClass) {
+			recordOptions.maskTextClass = this.maskTextClass;
+		}
+		if (this.maskTextSelector) {
+			recordOptions.maskTextSelector = this.maskTextSelector;
+		}
+		if (this.checkoutEveryNth) {
+			recordOptions.checkoutEveryNth = this.checkoutEveryNth;
+		}
+		if (this.recordConsole) {
+			recordOptions.plugins = [getRecordConsolePlugin()];
+		}
+
+		this.stopRecording = record(recordOptions);
+
+		this.flushTimer = setInterval(() => {
+			this.scheduleFlush();
+		}, this.flushInterval);
+
+		window.addEventListener("beforeunload", this.handleUnload);
+		window.addEventListener("pagehide", this.handleUnload);
+		document.addEventListener("visibilitychange", this.handleVisibilityChange);
+	}
+
+	stop(): void {
+		if (!this.started) return;
+		this.started = false;
+
+		if (this.debug) {
+			console.log("[Replay] Recording stopped");
+		}
+
+		this.stopRecording?.();
+		this.stopRecording = undefined;
+
+		if (this.flushTimer) {
+			clearInterval(this.flushTimer);
+			this.flushTimer = null;
+		}
+
+		window.removeEventListener("beforeunload", this.handleUnload);
+		window.removeEventListener("pagehide", this.handleUnload);
+		document.removeEventListener(
+			"visibilitychange",
+			this.handleVisibilityChange,
+		);
+
+		const elapsedTime = Date.now() - this.startTime;
+		if (elapsedTime < this.minReplayLengthMs) {
+			this.events = [];
+			if (this.debug) {
+				console.log(
+					`[Replay] Session too short (${elapsedTime}ms), discarding events`,
+				);
+			}
+			return;
+		}
+
+		this.flush();
+	}
+
+	private handleEvent(event: eventWithTime, isCheckout?: boolean): void {
+		this.events.push(event);
+
+		if (isCheckout) {
+			this.scheduleFlush();
+		} else if (this.events.length >= this.maxEvents) {
+			this.scheduleFlush();
+		}
+	}
+
+	private scheduleFlush(): void {
+		if (this.isFlushing || this.events.length === 0) return;
+
+		if (typeof window !== "undefined" && "requestIdleCallback" in window) {
+			window.requestIdleCallback(() => this.flush(), { timeout: 2000 });
+		} else {
+			setTimeout(() => this.flush(), 0);
+		}
+	}
+
+	private handleUnload = (): void => {
+		this.flush();
+	};
+
+	private handleVisibilityChange = (): void => {
+		if (document.visibilityState === "hidden") {
+			if (this.flushTimer) {
+				clearInterval(this.flushTimer);
+				this.flushTimer = null;
+			}
+			this.flush();
+		} else if (document.visibilityState === "visible" && this.started) {
+			if (!this.flushTimer) {
+				this.flushTimer = setInterval(() => {
+					this.scheduleFlush();
+				}, this.flushInterval);
+			}
+		}
+	};
+
+	private async flush(): Promise<void> {
+		if (this.events.length === 0) {
+			this.processPendingBatches();
+			return;
+		}
+
+		const elapsedTime = Date.now() - this.startTime;
+		if (elapsedTime < this.minReplayLengthMs) {
+			if (this.debug) {
+				console.log(`[Replay] Too short (${elapsedTime}ms), skipping`);
+			}
+			this.processPendingBatches();
+			return;
+		}
+
+		if (this.isFlushing) return;
+		this.isFlushing = true;
+
+		const eventsToSend = this.events;
+		this.events = [];
+
+		const anonymousId = window.__FA_getAnonymousId?.();
+		const batch = {
+			token: this.siteKey,
+			sessionId: window.__FA_getSessionId?.(),
+			...(anonymousId ? { identifier: anonymousId } : {}),
+			sequence: this.sequenceNumber++,
+			timestamp: Date.now(),
+			url: window.location.href,
+			events: eventsToSend,
+		};
+
+		if (this.debug) {
+			console.log(
+				`[Replay] Sending ${eventsToSend.length} events (seq: ${batch.sequence})`,
+			);
+		}
+
+		try {
+			let compressed: Blob;
+			let isCompressed = false;
+
+			if (this.compressionSupported) {
+				try {
+					compressed = await this.compress(JSON.stringify(batch));
+					isCompressed = true;
+				} catch {
+					if (this.debug) {
+						console.warn("[Replay] Compression failed, using uncompressed");
+					}
+					compressed = new Blob([JSON.stringify(batch)], {
+						type: "application/json",
+					});
+				}
+			} else {
+				compressed = new Blob([JSON.stringify(batch)], {
+					type: "application/json",
+				});
+			}
+
+			const success = await this.send(compressed, isCompressed);
+			if (!success) {
+				this.pendingBatches.push({
+					batch,
+					isCompressed,
+					retries: 0,
+				});
+			}
+		} catch (error) {
+			if (this.debug) {
+				console.warn("[Replay] Flush error:", error);
+			}
+			this.pendingBatches.push({
+				batch,
+				isCompressed: false,
+				retries: 0,
+			});
+		} finally {
+			this.isFlushing = false;
+			this.processPendingBatches();
+		}
+	}
+
+	private async processPendingBatches(): Promise<void> {
+		if (this.pendingBatches.length === 0) return;
+
+		const batch = this.pendingBatches.shift();
+		if (!batch) return;
+
+		if (batch.retries >= 3) {
+			if (this.debug) {
+				console.warn(
+					`[Replay] Max retries reached, dropping batch ${batch.batch.sequence}`,
+				);
+			}
+			this.processPendingBatches();
+			return;
+		}
+
+		batch.retries++;
+
+		try {
+			let blob: Blob;
+			if (batch.isCompressed && this.compressionSupported) {
+				try {
+					blob = await this.compress(JSON.stringify(batch.batch));
+				} catch {
+					blob = new Blob([JSON.stringify(batch.batch)], {
+						type: "application/json",
+					});
+					batch.isCompressed = false;
+				}
+			} else {
+				blob = new Blob([JSON.stringify(batch.batch)], {
+					type: "application/json",
+				});
+			}
+
+			const success = await this.send(blob, batch.isCompressed);
+			if (!success) {
+				this.pendingBatches.push(batch);
+				setTimeout(() => this.processPendingBatches(), 1000 * batch.retries);
+			} else {
+				this.processPendingBatches();
+			}
+		} catch {
+			if (this.debug) {
+				console.warn(`[Replay] Retry ${batch.retries} failed`);
+			}
+			this.pendingBatches.push(batch);
+			setTimeout(() => this.processPendingBatches(), 1000 * batch.retries);
+		}
+	}
+
+	private async compress(data: string): Promise<Blob> {
+		if (!this.compressionSupported) {
+			throw new Error("Compression not supported");
+		}
+
+		const encoder = new TextEncoder();
+		const inputData = encoder.encode(data);
+
+		const cs = new CompressionStream("gzip");
+		const writer = cs.writable.getWriter();
+		writer.write(inputData);
+		writer.close();
+
+		const compressedChunks: Uint8Array[] = [];
+		const reader = cs.readable.getReader();
+
+		while (true) {
+			const { done, value } = await reader.read();
+			if (done) break;
+			if (value) compressedChunks.push(value);
+		}
+
+		const totalLength = compressedChunks.reduce(
+			(acc, chunk) => acc + chunk.length,
+			0,
+		);
+		const compressed = new Uint8Array(totalLength);
+		let offset = 0;
+		for (const chunk of compressedChunks) {
+			compressed.set(chunk, offset);
+			offset += chunk.length;
+		}
+
+		if (this.debug) {
+			const ratio = ((compressed.length / inputData.length) * 100).toFixed(1);
+			console.log(
+				`[Replay] Compressed: ${inputData.length} → ${compressed.length} bytes (${ratio}%)`,
+			);
+		}
+
+		return new Blob([compressed], { type: "application/octet-stream" });
+	}
+
+	private async send(data: Blob, isCompressed: boolean): Promise<boolean> {
+		const url = isCompressed ? `${this.endpoint}?encoding=gzip` : this.endpoint;
+		const sizeKB = (data.size / 1024).toFixed(1);
+
+		return (
+			window.__FA_sendData?.({
+				url,
+				data,
+				contentType: isCompressed
+					? "application/octet-stream"
+					: "application/json",
+				headers: isCompressed ? { "Content-Encoding": "gzip" } : undefined,
+				debug: this.debug,
+				debugPrefix: `[Replay] ${sizeKB}KB`,
+			}) ?? Promise.resolve(false)
+		);
+	}
+
+	getSessionId(): string | undefined {
+		return window.__FA_getSessionId?.();
+	}
+}
+
+export default ReplayTracker;
+
+declare global {
+	interface Window {
+		__FA_ReplayTracker?: ReplayTrackerConstructor;
+		__FA_getAnonymousId?: () => string;
+		__FA_getSessionId?: () => string;
+		__FA_sendData?: (options: SendDataOptions) => Promise<boolean>;
+		__FA_isTrackingDisabled?: () => boolean;
+	}
+}
+
+if (typeof window !== "undefined") {
+	window.__FA_ReplayTracker = ReplayTracker;
+}

package/src/utils/identifiers.ts

@@ -0,0 +1,70 @@
+const SESSION_TIMEOUT = 30 * 60 * 1000;
+
+export function getAnonymousId(cookieless?: boolean): string {
+	if (cookieless) return "";
+	return getOrCreateAnonymousId();
+}
+
+export function getOrCreateAnonymousId(): string {
+	if (typeof localStorage === "undefined") return "";
+	const existingId = localStorage.getItem("faststats_anon_id");
+	if (existingId) return existingId;
+
+	const newId = crypto.randomUUID();
+	localStorage.setItem("faststats_anon_id", newId);
+	return newId;
+}
+
+export function resetAnonymousId(cookieless?: boolean): string {
+	if (cookieless || typeof localStorage === "undefined") return "";
+	localStorage.removeItem("faststats_anon_id");
+	return getOrCreateAnonymousId();
+}
+
+export function getOrCreateSessionId(): string {
+	if (typeof sessionStorage === "undefined") return "";
+	const existingId = sessionStorage.getItem("session_id");
+	const sessionTimestamp = sessionStorage.getItem("session_timestamp");
+
+	if (existingId && sessionTimestamp) {
+		const sessionAge = Date.now() - Number.parseInt(sessionTimestamp, 10);
+		if (sessionAge < SESSION_TIMEOUT) {
+			sessionStorage.setItem("session_timestamp", Date.now().toString());
+			return existingId;
+		}
+		sessionStorage.removeItem("session_id");
+		sessionStorage.removeItem("session_timestamp");
+		sessionStorage.removeItem("session_start");
+	}
+
+	const now = Date.now().toString();
+	const newId = crypto.randomUUID();
+	sessionStorage.setItem("session_id", newId);
+	sessionStorage.setItem("session_timestamp", now);
+	sessionStorage.setItem("session_start", now);
+	return newId;
+}
+
+export function resetSessionId(): string {
+	if (typeof sessionStorage === "undefined") return "";
+	sessionStorage.removeItem("session_id");
+	sessionStorage.removeItem("session_timestamp");
+	sessionStorage.removeItem("session_start");
+	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());
+	}
+}
+
+export function getSessionStart(): number {
+	if (typeof sessionStorage === "undefined") return Date.now();
+	const start = sessionStorage.getItem("session_start");
+	if (start) return Number.parseInt(start, 10);
+	const ts = sessionStorage.getItem("session_timestamp");
+	return ts ? Number.parseInt(ts, 10) : Date.now();
+}

package/src/utils/types.ts

@@ -0,0 +1,13 @@
+export interface SendDataOptions {
+	url: string;
+	data: string | Blob;
+	contentType?: string;
+	headers?: Record<string, string>;
+	debug?: boolean;
+	debugPrefix?: string;
+}
+
+export function normalizeSamplingPercentage(value: number | undefined): number {
+	if (typeof value !== "number" || !Number.isFinite(value)) return 100;
+	return Math.max(0, Math.min(100, value));
+}