@faststats/web 0.0.1

package/src/web-vitals.ts

@@ -0,0 +1,207 @@
+import {
+	type MetricWithAttribution,
+	onCLS,
+	onFCP,
+	onINP,
+	onLCP,
+	onTTFB,
+} from "web-vitals/attribution";
+import { normalizeSamplingPercentage } from "./utils/types";
+
+export interface WebVitalsOptions {
+	siteKey: string;
+	endpoint?: string;
+	debug?: boolean;
+	samplingPercentage?: number;
+}
+
+type MetricName = "CLS" | "INP" | "LCP" | "FCP" | "TTFB";
+
+type MetricState = {
+	value: number;
+	attributes: Record<string, unknown>;
+	final: boolean;
+};
+
+class WebVitalsTracker {
+	private readonly endpoint: string;
+	private readonly siteKey: string;
+	private readonly debug: boolean;
+	private readonly samplingPercentage: number;
+
+	private started = false;
+	private readonly sessionSamplingSeed: number;
+	private readonly metricsMap = new Map<MetricName, MetricState>();
+	private flushed = false;
+
+	constructor(options: WebVitalsOptions) {
+		this.siteKey = options.siteKey;
+		this.endpoint = this.getVitalsEndpoint(
+			options.endpoint ?? "https://metrics.faststats.dev/v1/web",
+		);
+		this.debug = options.debug ?? false;
+		this.samplingPercentage = normalizeSamplingPercentage(
+			options.samplingPercentage,
+		);
+		this.sessionSamplingSeed = Math.random() * 100;
+	}
+
+	private getVitalsEndpoint(baseEndpoint: string): string {
+		const url = new URL(baseEndpoint);
+		const pathParts = url.pathname.split("/");
+		pathParts[pathParts.length - 1] = "vitals";
+		url.pathname = pathParts.join("/");
+		return url.toString();
+	}
+
+	start(): void {
+		if (this.started || typeof window === "undefined") return;
+
+		if (window.__FA_isTrackingDisabled?.()) {
+			if (this.debug) {
+				console.log("[WebVitals] Tracking disabled");
+			}
+			return;
+		}
+
+		this.started = true;
+
+		document.addEventListener("visibilitychange", () => {
+			if (document.visibilityState === "hidden") {
+				this.finalizeAndFlush();
+			}
+		});
+		window.addEventListener("pagehide", () => {
+			this.finalizeAndFlush();
+		});
+
+		if (this.debug) {
+			console.log("[WebVitals] Tracking started");
+		}
+
+		onCLS((metric) => this.captureMetric(metric));
+		onINP((metric) => this.captureMetric(metric));
+		onLCP((metric) => this.captureMetric(metric));
+		onFCP((metric) => this.captureMetric(metric));
+		onTTFB((metric) => this.captureMetric(metric));
+	}
+
+	private captureMetric(metric: MetricWithAttribution): void {
+		if (this.flushed) return;
+
+		if (
+			this.samplingPercentage < 100 &&
+			this.sessionSamplingSeed >= this.samplingPercentage
+		) {
+			return;
+		}
+
+		const metricName = metric.name as MetricName;
+
+		const attributes: Record<string, unknown> = {
+			id: metric.id,
+			rating: metric.rating,
+			delta: metric.delta,
+			navigationType: metric.navigationType,
+			...(metric.attribution ?? {}),
+		};
+
+		const isFinal = metricName === "FCP" || metricName === "TTFB";
+
+		this.metricsMap.set(metricName, {
+			value: metric.value,
+			attributes,
+			final: isFinal,
+		});
+
+		if (this.debug) {
+			console.log(
+				`[WebVitals] ${metricName} captured: ${metric.value}` +
+					(isFinal ? " (final)" : ""),
+			);
+		}
+	}
+
+	private finalizeAndFlush(): void {
+		if (this.flushed || this.metricsMap.size === 0) {
+			return;
+		}
+
+		for (const [name, metric] of this.metricsMap.entries()) {
+			if (!metric.final) {
+				metric.final = true;
+
+				if (this.debug) {
+					console.log(`[WebVitals] ${name} finalized: ${metric.value}`);
+				}
+			}
+		}
+
+		this.flushWithBeacon();
+	}
+
+	private buildPayload(): { body: string; count: number } | null {
+		if (this.metricsMap.size === 0) return null;
+
+		const vitals = Array.from(this.metricsMap.entries()).map(
+			([metric, data]) => ({
+				metric,
+				value: data.value,
+				attributes: data.attributes,
+			}),
+		);
+
+		return {
+			body: JSON.stringify({
+				sessionId: window.__FA_getSessionId?.(),
+				vitals,
+				metadata: {
+					url: window.location.href,
+				},
+			}),
+			count: vitals.length,
+		};
+	}
+
+	private flushWithBeacon(): void {
+		const payload = this.buildPayload();
+		if (!payload) return;
+
+		this.flushed = true;
+
+		if (this.debug) {
+			const names = Array.from(this.metricsMap.keys()).join(", ");
+			console.log(
+				`[WebVitals] Sending final metrics (${payload.count}): ${names}`,
+			);
+		}
+
+		fetch(this.endpoint, {
+			method: "POST",
+			body: payload.body,
+			headers: {
+				"Content-Type": "application/json",
+				Authorization: `Bearer ${this.siteKey}`,
+			},
+			keepalive: true,
+		}).catch(() => {
+			if (this.debug) {
+				console.warn("[WebVitals] Failed to send metrics");
+			}
+		});
+	}
+}
+
+export default WebVitalsTracker;
+
+declare global {
+	interface Window {
+		__FA_WebVitalsTracker?: typeof WebVitalsTracker;
+		__FA_getSessionId?: () => string;
+		__FA_isTrackingDisabled?: () => boolean;
+	}
+}
+
+if (typeof window !== "undefined") {
+	window.__FA_WebVitalsTracker = WebVitalsTracker;
+}

package/tsconfig.json

@@ -0,0 +1,30 @@
+{
+	"compilerOptions": {
+		// Environment setup & latest features
+		"lib": ["ESNext", "DOM"],
+		"target": "ESNext",
+		"module": "Preserve",
+		"moduleDetection": "force",
+		"jsx": "react-jsx",
+		"allowJs": true,
+
+		// Bundler mode
+		"moduleResolution": "bundler",
+		"allowImportingTsExtensions": true,
+		"verbatimModuleSyntax": true,
+		"noEmit": true,
+
+		// Best practices
+		"strict": true,
+		"skipLibCheck": true,
+		"noFallthroughCasesInSwitch": true,
+		"noUncheckedIndexedAccess": true,
+		"noImplicitOverride": true,
+
+		// Some stricter flags (disabled by default)
+		"noUnusedLocals": false,
+		"noUnusedParameters": false,
+		"noPropertyAccessFromIndexSignature": false
+	},
+	"include": ["src"]
+}

package/tsdown.config.ts

@@ -0,0 +1,51 @@
+import { defineConfig, type UserConfig } from "tsdown";
+
+const iifeBase: UserConfig = {
+	format: ["iife"] as ["iife"],
+	platform: "browser",
+	outDir: "dist",
+	minify: true,
+	noExternal: [
+		"web-vitals",
+		"web-vitals/attribution",
+		"rrweb",
+		"@rrweb/rrweb-plugin-console-record",
+		"@rrweb/types",
+		"rrweb-snapshot",
+	],
+};
+
+export default defineConfig([
+	{
+		...iifeBase,
+		entry: { script: "src/index.ts" },
+		globalName: "FA_Script",
+		clean: true,
+	},
+	{
+		...iifeBase,
+		entry: { error: "src/error.ts" },
+		globalName: "FA_Error",
+	},
+	{
+		...iifeBase,
+		entry: { "web-vitals": "src/web-vitals.ts" },
+		globalName: "FA_WebVitals",
+		inlineOnly: ["web-vitals"],
+	},
+	{
+		...iifeBase,
+		entry: { replay: "src/replay.ts" },
+		globalName: "FA_Replay",
+		inlineOnly: ["rrweb", "@rrweb/rrweb-plugin-console-record"],
+	},
+	{
+		entry: "src/module.ts",
+		format: ["esm"],
+		platform: "browser",
+		outDir: "dist",
+		dts: true,
+		inlineOnly: false,
+		checks: { pluginTimings: false },
+	},
+]);

package/worker/index.ts

@@ -0,0 +1,22 @@
+export default {
+	async fetch(
+		request: Request,
+		env: { ASSETS: { fetch: typeof fetch } },
+	): Promise<Response> {
+		const response = await env.ASSETS.fetch(request);
+
+		if (response.ok) {
+			const newHeaders = new Headers(response.headers);
+			newHeaders.set("Cache-Control", "public, max-age=31536000, immutable");
+			newHeaders.set("Access-Control-Allow-Origin", "*");
+
+			return new Response(response.body, {
+				status: response.status,
+				statusText: response.statusText,
+				headers: newHeaders,
+			});
+		}
+
+		return response;
+	},
+};

package/wrangler.toml

@@ -0,0 +1,8 @@
+name = "web-analytics"
+main = "worker/index.ts"
+compatibility_date = "2024-01-01"
+
+[assets]
+directory = "./dist"
+binding = "ASSETS"
+run_worker_first = true