@faststats/web 0.2.7 → 0.2.9

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,29 +131,34 @@ 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(
 	externalId: string,
 	email: string,
 	options?: IdentifyOptions,
-): void {
-	if (typeof window === "undefined" || isTrackingDisabled()) return;
-	_instance?.identify(externalId, email, options ?? {});
+): 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;
-	_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 +171,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 +202,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 +223,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 +323,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 +340,7 @@ export class WebAnalytics {
 			this.log("disabled");
 			return;
 		}
-		_instance = this;
+		moduleState.instance = this;
 		setCookielessMode(this.isCookielessMode());
 		setTimeout(() => void this.start(), 0);
 	}
@@ -408,7 +420,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 +432,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 +459,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 +469,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 +485,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 +502,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 +512,7 @@ export class WebAnalytics {
 		}
 
 		this.started = true;
-		_instance = this;
+		moduleState.instance = this;
 		setCookielessMode(this.isCookielessMode());
 		getOrCreateSessionId();
 
@@ -551,8 +569,8 @@ export class WebAnalytics {
 		}
 
 		this.stopChildTrackers();
-		if (_instance === this) {
-			_instance = null;
+		if (moduleState.instance === this) {
+			moduleState.instance = null;
 		}
 		this.started = false;
 		this.destroyed = true;
@@ -575,13 +593,13 @@ export class WebAnalytics {
 		externalId: string,
 		email: string,
 		options: IdentifyOptions = {},
-	): void {
-		if (!this.ensureStarted()) return;
-		if (this.isCookielessMode()) return;
+	): 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;
+		if (!trimmedExternalId || !trimmedEmail) return Promise.resolve(false);
 
 		const identifyEndpoint = identifyEventsUrl(this.baseUrl);
 		const payload = JSON.stringify({
@@ -595,12 +613,13 @@ export class WebAnalytics {
 			traits: options.traits ?? {},
 		});
 
-		void sendData({
+		return sendData({
 			url: identifyEndpoint,
 			data: payload,
 			contentType: "text/plain",
 			debug: this.debug,
 			debugPrefix: "[Analytics] identify",
+			useBeacon: false,
 		});
 	}
 
@@ -646,23 +665,17 @@ 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) {
+		if (!externalId && !identifier) {
 			return { value: "false" };
 		}
+
+		const { fetchFeatureFlagEvaluation } = await import("./feature-flags");
 		return fetchFeatureFlagEvaluation(key, {
 			baseUrl: this.featureFlagsBaseUrl,
 			projectToken: this.options.siteKey,
-			identifier,
+			...(identifier ? { identifier } : {}),
+			...(externalId ? { externalId } : {}),
 			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/feature-flags.ts

@@ -23,9 +23,6 @@ export async function fetchFeatureFlagEvaluation(
 	if (context.projectToken && context.projectId) {
 		throw new Error("provide either projectToken or projectId, not both");
 	}
-	if (context.identifier && context.externalId) {
-		throw new Error("provide either serverId or externalId, not both");
-	}
 
 	const projectToken = context.projectToken;
 	const projectId = context.projectId;
@@ -42,7 +39,8 @@ export async function fetchFeatureFlagEvaluation(
 	const body: Record<string, unknown> = {
 		key: flagKey,
 		...(projectId ? { projectId } : {}),
-		...(identifier ? { identifier } : { externalId }),
+		...(identifier ? { identifier } : {}),
+		...(externalId ? { externalId } : {}),
 	};
 
 	if (context.attributes && Object.keys(context.attributes).length > 0) {

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,6 +81,7 @@ 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;
@@ -112,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 {
@@ -131,6 +140,37 @@ export default class ReplayTracker {
 		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,
@@ -147,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 {
@@ -284,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,
@@ -298,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,
 			};
 		}
@@ -319,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);
 			}
 		}
 
@@ -331,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,
@@ -339,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 {
@@ -363,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;