@faststats/web 0.2.6 → 0.2.8

package/src/analytics.ts

@@ -1,8 +1,5 @@
 import type ErrorTracker from "./error";
-import {
-	type FeatureFlagEvaluation,
-	fetchFeatureFlagEvaluation,
-} from "./feature-flags";
+import type { FeatureFlagEvaluation } from "./feature-flags";
 import type ReplayTracker from "./replay";
 import type { ReplayTrackerOptions } from "./replay";
 import {
@@ -41,6 +38,7 @@ interface SamplingOptions {
 
 interface WebVitalsConfig {
 	sampling?: SamplingOptions;
+	attribution?: boolean;
 }
 
 interface SessionReplayConfig {
@@ -77,6 +75,10 @@ export interface WebAnalyticsOptions {
 	webVitals?: WebVitalsConfig;
 	sessionReplays?: SessionReplayConfig;
 	replayOptions?: Partial<ReplayTrackerOptions>;
+	/** @internal */
+	sdkName?: string;
+	/** @internal */
+	sdkVersion?: string;
 }
 
 function hasReplaySamplingConfig(options: WebAnalyticsOptions): boolean {
@@ -112,11 +114,16 @@ export function resolveReplayTrackerOptions(
 	};
 }
 
-let _instance: WebAnalytics | null = null;
-let pendingConsentMode: ConsentMode | undefined;
+const moduleState: {
+	instance: WebAnalytics | null;
+	pendingConsentMode: ConsentMode | undefined;
+} = {
+	instance: null,
+	pendingConsentMode: undefined,
+};
 
 export function getInstance(): WebAnalytics | null {
-	return _instance;
+	return moduleState.instance;
 }
 
 export function trackEvent(
@@ -124,7 +131,7 @@ export function trackEvent(
 	properties?: Record<string, unknown>,
 ): void {
 	if (typeof window === "undefined" || isTrackingDisabled()) return;
-	_instance?.track(eventName, properties ?? {});
+	moduleState.instance?.track(eventName, properties ?? {});
 }
 
 export function identify(
@@ -133,20 +140,20 @@ export function identify(
 	options?: IdentifyOptions,
 ): void {
 	if (typeof window === "undefined" || isTrackingDisabled()) return;
-	_instance?.identify(externalId, email, options ?? {});
+	moduleState.instance?.identify(externalId, email, options ?? {});
 }
 
 export function logout(resetAnonymousIdentity = true): void {
 	if (typeof window === "undefined" || isTrackingDisabled()) return;
-	_instance?.logout(resetAnonymousIdentity);
+	moduleState.instance?.logout(resetAnonymousIdentity);
 }
 
 export function setConsentMode(mode: ConsentMode): void {
-	if (_instance) {
-		_instance.setConsentMode(mode);
+	if (moduleState.instance) {
+		moduleState.instance.setConsentMode(mode);
 		return;
 	}
-	pendingConsentMode = mode;
+	moduleState.pendingConsentMode = mode;
 }
 
 export function optIn(): void {
@@ -159,7 +166,7 @@ export function optOut(): void {
 
 export function reportError(error: Error): void {
 	if (typeof window === "undefined" || isTrackingDisabled()) return;
-	_instance?.reportError(error);
+	moduleState.instance?.reportError(error);
 }
 
 export function isTrackingDisabled(): boolean {
@@ -190,9 +197,9 @@ export async function sendData(options: SendDataOptions): Promise<boolean> {
 				data instanceof Blob
 					? data
 					: typeof Blob !== "undefined"
-						? new Blob([data], { type: contentType })
+						? new Blob([data as BlobPart], { type: contentType })
 						: data;
-			if (navigator.sendBeacon(url, beaconBody)) {
+			if (navigator.sendBeacon(url, beaconBody as BodyInit)) {
 				if (debug) {
 					console.log(`${debugPrefix} Sent via beacon`);
 				}
@@ -211,7 +218,7 @@ export async function sendData(options: SendDataOptions): Promise<boolean> {
 	try {
 		const response = await fetch(url, {
 			method: "POST",
-			body: data,
+			body: data as BodyInit,
 			headers: {
 				"Content-Type": contentType,
 				...headers,
@@ -311,9 +318,9 @@ export class WebAnalytics {
 		this.consentMode = options.consent?.mode ?? "granted";
 		this.cookielessWhilePending =
 			options.consent?.cookielessWhilePending ?? true;
-		if (pendingConsentMode !== undefined) {
-			this.consentMode = pendingConsentMode;
-			pendingConsentMode = undefined;
+		if (moduleState.pendingConsentMode !== undefined) {
+			this.consentMode = moduleState.pendingConsentMode;
+			moduleState.pendingConsentMode = undefined;
 		}
 		if (options.autoTrack ?? true) this.init();
 	}
@@ -328,7 +335,7 @@ export class WebAnalytics {
 			this.log("disabled");
 			return;
 		}
-		_instance = this;
+		moduleState.instance = this;
 		setCookielessMode(this.isCookielessMode());
 		setTimeout(() => void this.start(), 0);
 	}
@@ -408,7 +415,7 @@ export class WebAnalytics {
 	}
 
 	private registerChildTracker(tracker: ChildTracker): boolean {
-		if (!this.started || this.destroyed || _instance !== this) {
+		if (!this.started || this.destroyed || moduleState.instance !== this) {
 			tracker.stop?.();
 			return false;
 		}
@@ -420,12 +427,15 @@ export class WebAnalytics {
 	private async startErrorTracker(): Promise<void> {
 		try {
 			const { default: ErrorTrackerClass } = await import("./error");
-			if (!this.started || this.destroyed || _instance !== this) return;
+			if (!this.started || this.destroyed || moduleState.instance !== this)
+				return;
 
 			const errorTracker: ErrorTracker = new ErrorTrackerClass({
 				siteKey: this.options.siteKey,
 				baseUrl: this.baseUrl,
 				debug: this.debug,
+				sdkName: this.options.sdkName,
+				sdkVersion: this.options.sdkVersion,
 			});
 			errorTracker.start();
 			if (!this.registerChildTracker(errorTracker)) return;
@@ -444,7 +454,8 @@ export class WebAnalytics {
 	private async startWebVitalsTracker(): Promise<void> {
 		try {
 			const { default: WebVitalsTrackerClass } = await import("./web-vitals");
-			if (!this.started || this.destroyed || _instance !== this) return;
+			if (!this.started || this.destroyed || moduleState.instance !== this)
+				return;
 
 			const webVitalsTracker: WebVitalsTracker = new WebVitalsTrackerClass({
 				siteKey: this.options.siteKey,
@@ -453,6 +464,7 @@ export class WebAnalytics {
 				samplingPercentage: normalizeSamplingPercentage(
 					this.options.webVitals?.sampling?.percentage,
 				),
+				attribution: this.options.webVitals?.attribution ?? false,
 			});
 			webVitalsTracker.start();
 			if (!this.registerChildTracker(webVitalsTracker)) return;
@@ -468,7 +480,8 @@ export class WebAnalytics {
 	): Promise<void> {
 		try {
 			const { default: ReplayTrackerClass } = await import("./replay");
-			if (!this.started || this.destroyed || _instance !== this) return;
+			if (!this.started || this.destroyed || moduleState.instance !== this)
+				return;
 
 			const replayTracker: ReplayTracker = new ReplayTrackerClass(
 				replayOptions,
@@ -484,7 +497,7 @@ export class WebAnalytics {
 
 	async start(): Promise<void> {
 		if (this.started || this.destroyed || typeof window === "undefined") return;
-		if (_instance && _instance !== this) {
+		if (moduleState.instance && moduleState.instance !== this) {
 			this.log("already started by another instance");
 			return;
 		}
@@ -494,7 +507,7 @@ export class WebAnalytics {
 		}
 
 		this.started = true;
-		_instance = this;
+		moduleState.instance = this;
 		setCookielessMode(this.isCookielessMode());
 		getOrCreateSessionId();
 
@@ -551,8 +564,8 @@ export class WebAnalytics {
 		}
 
 		this.stopChildTrackers();
-		if (_instance === this) {
-			_instance = null;
+		if (moduleState.instance === this) {
+			moduleState.instance = null;
 		}
 		this.started = false;
 		this.destroyed = true;
@@ -646,23 +659,16 @@ export class WebAnalytics {
 			return { value: "false" };
 		}
 		const externalId = opts?.externalId?.trim();
-		if (externalId) {
-			return fetchFeatureFlagEvaluation(key, {
-				baseUrl: this.featureFlagsBaseUrl,
-				projectToken: this.options.siteKey,
-				externalId,
-				attributes,
-				signal: opts?.signal,
-			});
-		}
-		const identifier = this.getAnonymousId();
-		if (!identifier) {
+		const identifier = externalId ? undefined : 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,
+			...(externalId ? { externalId } : { identifier }),
 			attributes,
 			signal: opts?.signal,
 		});

package/src/entries/error.ts

@@ -0,0 +1,6 @@
+export {
+	default,
+	type ErrorEntry,
+	type ErrorTracking,
+	type ErrorTrackingOptions,
+} from "../error";

package/src/entries/feature-flags.ts

@@ -0,0 +1,5 @@
+export type {
+	FeatureFlagCheckContext,
+	FeatureFlagEvaluation,
+} from "../feature-flags";
+export { fetchFeatureFlagEvaluation } from "../feature-flags";

package/src/entries/main.ts

@@ -0,0 +1,21 @@
+export {
+	type ConsentMode,
+	getInstance,
+	type IdentifyOptions,
+	identify,
+	isTrackingDisabled,
+	logout,
+	optIn,
+	optOut,
+	reportError,
+	sendData,
+	setConsentMode,
+	trackEvent,
+	WebAnalytics,
+	type WebAnalyticsOptions,
+} from "../analytics";
+export type {
+	FeatureFlagCheckContext,
+	FeatureFlagEvaluation,
+} from "../feature-flags";
+export { fetchFeatureFlagEvaluation } from "../feature-flags";

package/src/entries/replay.ts

@@ -0,0 +1 @@
+export { default, type ReplayTrackerOptions } from "../replay";

package/src/entries/web-vitals.ts

@@ -0,0 +1 @@
+export { default, type WebVitalsOptions } from "../web-vitals";

package/src/env.d.ts

@@ -0,0 +1,2 @@
+declare const __FASTSTATS_SDK_NAME__: string;
+declare const __FASTSTATS_SDK_VERSION__: string;

package/src/error.ts

@@ -1,4 +1,5 @@
 import { sendData } from "./analytics";
+import { SDK_NAME, SDK_VERSION } from "./sdk";
 import { webEventsUrl } from "./utils/api-urls";
 import { getAnonymousId, getOrCreateSessionId } from "./utils/identifiers";
 
@@ -33,6 +34,8 @@ export interface ErrorTrackingOptions {
 	debug?: boolean;
 	flushInterval?: number;
 	maxQueueSize?: number;
+	sdkName?: string;
+	sdkVersion?: string;
 }
 
 const EXTENSION_URL =
@@ -256,6 +259,8 @@ export default class ErrorTracker {
 			...(identifier ? { userId: identifier } : {}),
 			sessionId: getOrCreateSessionId(),
 			...(buildId ? { buildId } : {}),
+			sdkName: this.options.sdkName ?? SDK_NAME,
+			sdkVersion: this.options.sdkVersion ?? SDK_VERSION,
 			data: {
 				url: location.href,
 				page: location.pathname,

package/src/replay.ts

@@ -1,7 +1,9 @@
-import { getRecordConsolePlugin } from "@rrweb/rrweb-plugin-console-record";
-import { getRecordSequentialIdPlugin } from "@rrweb/rrweb-plugin-sequential-id-record";
-import type { eventWithTime, listenerHandler } from "@rrweb/types";
-import { EventType, record } from "rrweb";
+import {
+	EventType,
+	type eventWithTime,
+	type listenerHandler,
+} from "@rrweb/types";
+import { record } from "rrweb";
 import type { recordOptions } from "rrweb/typings/types";
 import type { SlimDOMOptions } from "rrweb-snapshot";
 import { sendData } from "./analytics";
@@ -15,6 +17,7 @@ import { normalizeSamplingPercentage } from "./utils/types";
 
 const RRWEB_SEQUENTIAL_ID_KEY = "_faststatsSeqId";
 const MAX_TIMEOUT_MS = 2_147_483_647;
+const DEFAULT_MAX_QUEUE_SIZE_BYTES = 2 * 1024 * 1024;
 
 export interface ReplayTrackerOptions {
 	siteKey: string;
@@ -25,6 +28,7 @@ export interface ReplayTrackerOptions {
 	flushInterval?: number;
 	maxEvents?: number;
 	maxPendingBatches?: number;
+	maxQueueSizeBytes?: number;
 	minReplayLengthMs?: number;
 	sampling?: recordOptions<eventWithTime>["sampling"];
 	slimDOMOptions?: SlimDOMOptions;
@@ -77,7 +81,9 @@ export default class ReplayTracker {
 	private readonly sampled: boolean;
 	private readonly events: eventWithTime[] = [];
 	private readonly pending: ReplayBatch[] = [];
+	private pendingSizeBytes = 0;
 
+	private sessionId: string | undefined;
 	private started = false;
 	private startTime = 0;
 	private sequence = 0;
@@ -111,12 +117,16 @@ export default class ReplayTracker {
 		return this.options.maxPendingBatches ?? 30;
 	}
 
+	private get maxQueueSizeBytes(): number {
+		return this.options.maxQueueSizeBytes ?? DEFAULT_MAX_QUEUE_SIZE_BYTES;
+	}
+
 	private get minReplayLengthMs(): number {
 		return this.options.minReplayLengthMs ?? 3000;
 	}
 
 	private get shouldCompress(): boolean {
-		return this.options.compress ?? false;
+		return this.options.compress ?? true;
 	}
 
 	private log(...args: unknown[]): void {
@@ -127,9 +137,40 @@ export default class ReplayTracker {
 		if (this.started || typeof window === "undefined" || !this.sampled) return;
 
 		this.started = true;
-		getOrCreateSessionId();
+		this.sessionId = getOrCreateSessionId();
 		this.startTime = getSessionStart();
 
+		void this.beginRecording();
+
+		this.intervalId = setInterval(this.requestFlush, this.flushInterval);
+
+		window.addEventListener("beforeunload", this.onUnload);
+		window.addEventListener("pagehide", this.onUnload);
+		document.addEventListener("visibilitychange", this.onVisibilityChange);
+
+		this.log("Recording started");
+	}
+
+	private async beginRecording(): Promise<void> {
+		const wantsConsole = this.options.recordConsole ?? true;
+
+		const [{ getRecordSequentialIdPlugin }, consolePluginModule] =
+			await Promise.all([
+				import("@rrweb/rrweb-plugin-sequential-id-record"),
+				wantsConsole
+					? import("@rrweb/rrweb-plugin-console-record")
+					: Promise.resolve(null),
+			]);
+
+		if (!this.started) return;
+
+		const plugins = [
+			getRecordSequentialIdPlugin({ key: RRWEB_SEQUENTIAL_ID_KEY }),
+		];
+		if (consolePluginModule) {
+			plugins.push(consolePluginModule.getRecordConsolePlugin());
+		}
+
 		this.stopRecording = record({
 			emit: this.onEvent,
 			sampling: this.options.sampling ?? defaultSampling,
@@ -146,21 +187,8 @@ export default class ReplayTracker {
 			maskTextSelector: this.options.maskTextSelector,
 			checkoutEveryNms: this.options.checkoutEveryNms ?? 60_000,
 			checkoutEveryNth: this.options.checkoutEveryNth,
-			plugins: [
-				getRecordSequentialIdPlugin({ key: RRWEB_SEQUENTIAL_ID_KEY }),
-				...((this.options.recordConsole ?? true)
-					? [getRecordConsolePlugin()]
-					: []),
-			],
+			plugins,
 		});
-
-		this.intervalId = setInterval(this.requestFlush, this.flushInterval);
-
-		window.addEventListener("beforeunload", this.onUnload);
-		window.addEventListener("pagehide", this.onUnload);
-		document.addEventListener("visibilitychange", this.onVisibilityChange);
-
-		this.log("Recording started");
 	}
 
 	stop(): void {
@@ -186,6 +214,7 @@ export default class ReplayTracker {
 
 		if (!this.hasReachedMinLength()) {
 			this.events.length = 0;
+			this.sessionId = undefined;
 			this.log(
 				`Session too short (${Date.now() - this.startTime}ms), discarding events`,
 			);
@@ -193,11 +222,12 @@ export default class ReplayTracker {
 		}
 
 		void this.flush(true);
+		this.sessionId = undefined;
 		this.log("Recording stopped");
 	}
 
 	getSessionId(): string | undefined {
-		return getOrCreateSessionId();
+		return this.sessionId ?? getOrCreateSessionId();
 	}
 
 	private onEvent = (event: eventWithTime, isCheckout?: boolean): void => {
@@ -272,7 +302,7 @@ export default class ReplayTracker {
 
 		return {
 			token: this.options.siteKey,
-			sessionId: getOrCreateSessionId(),
+			sessionId: this.getSessionId(),
 			...(identifier ? { identifier } : {}),
 			sequence: this.sequence++,
 			timestamp: Date.now(),
@@ -281,13 +311,52 @@ export default class ReplayTracker {
 		};
 	}
 
+	private getBatchSizeBytes(batch: ReplayBatch): number {
+		return new TextEncoder().encode(JSON.stringify(batch)).byteLength;
+	}
+
+	private dropOldestPendingBatch(reason: string): void {
+		const dropped = this.pending.shift();
+		if (!dropped) return;
+
+		this.pendingSizeBytes = Math.max(
+			0,
+			this.pendingSizeBytes - this.getBatchSizeBytes(dropped),
+		);
+		this.log(`${reason}, dropping batch ${dropped.sequence}`);
+	}
+
+	private enqueueBatch(batch: ReplayBatch): void {
+		const batchSizeBytes = this.getBatchSizeBytes(batch);
+
+		if (batchSizeBytes > this.maxQueueSizeBytes) {
+			this.log(
+				`Replay batch ${batch.sequence} is ${batchSizeBytes}B, exceeding ${this.maxQueueSizeBytes}B queue limit; dropping`,
+			);
+			return;
+		}
+
+		while (
+			this.pending.length > 0 &&
+			this.pendingSizeBytes + batchSizeBytes > this.maxQueueSizeBytes
+		) {
+			this.dropOldestPendingBatch("Pending queue size limit reached");
+		}
+
+		while (this.pending.length >= this.maxPendingBatches) {
+			this.dropOldestPendingBatch("Pending batch limit reached");
+		}
+
+		this.pending.push(batch);
+		this.pendingSizeBytes += batchSizeBytes;
+	}
+
 	private async encodeBatch(
 		batch: ReplayBatch,
-		lowLatency: boolean,
-	): Promise<{ data: string | Blob; isCompressed: boolean }> {
+	): Promise<{ data: string | Uint8Array; isCompressed: boolean }> {
 		const json = JSON.stringify(batch);
 
-		if (!this.shouldCompress || !this.compressionSupported || lowLatency) {
+		if (!this.shouldCompress || !this.compressionSupported) {
 			return {
 				data: json,
 				isCompressed: false,
@@ -295,14 +364,18 @@ export default class ReplayTracker {
 		}
 
 		try {
+			const compressed = await this.compress(json);
+			this.log(
+				`Compressed ${json.length}B -> ${compressed.byteLength}B (${Math.round((compressed.byteLength / json.length) * 100)}%)`,
+			);
 			return {
-				data: await this.compress(json),
+				data: compressed,
 				isCompressed: true,
 			};
 		} catch {
 			this.log("Compression failed, using uncompressed");
 			return {
-				data: new Blob([json], { type: "application/json" }),
+				data: json,
 				isCompressed: false,
 			};
 		}
@@ -316,7 +389,7 @@ export default class ReplayTracker {
 				this.scheduleMinLengthFlush();
 			} else {
 				const batch = this.createBatch(this.events.splice(0));
-				this.pending.push(batch);
+				this.enqueueBatch(batch);
 			}
 		}
 
@@ -328,7 +401,7 @@ export default class ReplayTracker {
 				const batch = this.pending[0];
 				if (!batch) break;
 
-				const encoded = await this.encodeBatch(batch, lowLatency);
+				const encoded = await this.encodeBatch(batch);
 				const ok = await this.send(
 					encoded.data,
 					encoded.isCompressed,
@@ -336,15 +409,11 @@ export default class ReplayTracker {
 				);
 
 				if (!ok) {
-					if (this.pending.length >= this.maxPendingBatches) {
-						this.log(`Pending buffer full, dropping batch ${batch.sequence}`);
-						this.pending.shift();
-					}
 					this.log(`Failed to send replay batch ${batch.sequence}, retrying`);
 					this.scheduleRetry();
 					break;
 				}
-				this.pending.shift();
+				this.dropOldestPendingBatch("Sent replay batch");
 				lowLatency = false;
 			}
 		} finally {
@@ -360,37 +429,16 @@ export default class ReplayTracker {
 		}, 1000);
 	}
 
-	private async compress(data: string): Promise<Blob> {
-		const input = new TextEncoder().encode(data);
-		const cs = new CompressionStream("gzip");
-		const writer = cs.writable.getWriter();
-
-		await writer.write(input);
-		await writer.close();
-
-		const chunks: Uint8Array[] = [];
-		const reader = cs.readable.getReader();
-
-		while (true) {
-			const { done, value } = await reader.read();
-			if (done) break;
-			if (value) chunks.push(value);
-		}
-
-		const size = chunks.reduce((sum, chunk) => sum + chunk.length, 0);
-		const output = new Uint8Array(size);
-
-		let offset = 0;
-		for (const chunk of chunks) {
-			output.set(chunk, offset);
-			offset += chunk.length;
-		}
-
-		return new Blob([output], { type: "application/octet-stream" });
+	private async compress(data: string): Promise<Uint8Array> {
+		const stream = new Blob([data])
+			.stream()
+			.pipeThrough(new CompressionStream("gzip"));
+		const buffer = await new Response(stream).arrayBuffer();
+		return new Uint8Array(buffer);
 	}
 
 	private send(
-		data: string | Blob,
+		data: string | Uint8Array,
 		isCompressed: boolean,
 		lowLatency: boolean,
 	): Promise<boolean> {

package/src/sdk.ts

@@ -0,0 +1,8 @@
+export const SDK_NAME =
+	typeof __FASTSTATS_SDK_NAME__ === "string"
+		? __FASTSTATS_SDK_NAME__
+		: "@faststats/web";
+export const SDK_VERSION =
+	typeof __FASTSTATS_SDK_VERSION__ === "string"
+		? __FASTSTATS_SDK_VERSION__
+		: "0.2.7";

package/src/utils/types.ts

@@ -1,6 +1,6 @@
 export interface SendDataOptions {
 	url: string;
-	data: string | Blob;
+	data: string | Blob | Uint8Array;
 	contentType?: string;
 	headers?: Record<string, string>;
 	debug?: boolean;