@faststats/web 0.2.13 → 0.2.14

package/src/utils/session-manager.ts

@@ -0,0 +1,416 @@
+export type SessionContext = {
+	sessionId: string;
+	windowId: string;
+	sessionStart: number;
+};
+
+export type SessionRotation = {
+	prev: SessionContext;
+	next: SessionContext;
+};
+
+const SESSION_IDLE_TIMEOUT_MS = 30 * 60 * 1000;
+const SESSION_MAX_AGE_MS = 24 * 60 * 60 * 1000;
+
+const LS_SESSION_ID = "faststats_session_id";
+const LS_SESSION_ACTIVITY = "faststats_session_activity";
+const LS_SESSION_START = "faststats_session_start";
+
+const LEGACY_SESSION_ID = "session_id";
+const LEGACY_SESSION_TIMESTAMP = "session_timestamp";
+const LEGACY_SESSION_START = "session_start";
+
+let cookielessMode = false;
+let defaultSiteKey = "";
+let ephemeralSession: {
+	sessionId: string;
+	sessionStart: number;
+	activity: number;
+} | null = null;
+
+type RotationListener = (prev: SessionContext, next: SessionContext) => void;
+const rotationListeners = new Set<RotationListener>();
+
+function storageGet(storage: Storage | undefined, key: string): string | null {
+	try {
+		return storage?.getItem(key) ?? null;
+	} catch {
+		return null;
+	}
+}
+
+function storageSet(
+	storage: Storage | undefined,
+	key: string,
+	value: string,
+): boolean {
+	if (!storage) return false;
+	try {
+		storage.setItem(key, value);
+		return true;
+	} catch {
+		return false;
+	}
+}
+
+function storageRemove(storage: Storage | undefined, key: string): void {
+	try {
+		storage?.removeItem(key);
+	} catch {}
+}
+
+function getLocalStorage(): Storage | undefined {
+	try {
+		return globalThis.localStorage;
+	} catch {
+		return undefined;
+	}
+}
+
+function getSessionStorage(): Storage | undefined {
+	try {
+		return globalThis.sessionStorage;
+	} catch {
+		return undefined;
+	}
+}
+
+function notifyRotation(prev: SessionContext, next: SessionContext): void {
+	for (const listener of rotationListeners) {
+		listener(prev, next);
+	}
+}
+
+export function createId(): string {
+	if (typeof crypto !== "undefined" && "randomUUID" in crypto) {
+		return crypto.randomUUID();
+	}
+	return `${Date.now().toString(36)}-${Math.random().toString(36).slice(2)}`;
+}
+
+export function setCookielessMode(mode: boolean): void {
+	cookielessMode = mode;
+	if (mode) ephemeralSession = null;
+}
+
+export function isCookielessMode(): boolean {
+	return cookielessMode;
+}
+
+export function setDefaultSiteKey(siteKey: string): void {
+	defaultSiteKey = siteKey;
+}
+
+function windowIdKey(siteKey: string): string {
+	return `faststats_window_id_${siteKey}`;
+}
+
+function parseTimestamp(value: string | null): number | null {
+	if (!value) return null;
+	const parsed = Number.parseInt(value, 10);
+	return Number.isFinite(parsed) ? parsed : null;
+}
+
+function migrateLegacySession(): void {
+	const session = getSessionStorage();
+	const local = getLocalStorage();
+	const legacyId = storageGet(session, LEGACY_SESSION_ID);
+	if (!legacyId || storageGet(local, LS_SESSION_ID)) {
+		if (legacyId) {
+			storageRemove(session, LEGACY_SESSION_ID);
+			storageRemove(session, LEGACY_SESSION_TIMESTAMP);
+			storageRemove(session, LEGACY_SESSION_START);
+		}
+		return;
+	}
+
+	const legacyActivity = parseTimestamp(
+		storageGet(session, LEGACY_SESSION_TIMESTAMP),
+	);
+	const legacyStart = parseTimestamp(storageGet(session, LEGACY_SESSION_START));
+	const now = Date.now();
+
+	const migrated = storageSet(local, LS_SESSION_ID, legacyId);
+	storageSet(local, LS_SESSION_ACTIVITY, String(legacyActivity ?? now));
+	storageSet(
+		local,
+		LS_SESSION_START,
+		String(legacyStart ?? legacyActivity ?? now),
+	);
+
+	if (migrated) {
+		storageRemove(session, LEGACY_SESSION_ID);
+		storageRemove(session, LEGACY_SESSION_TIMESTAMP);
+		storageRemove(session, LEGACY_SESSION_START);
+	}
+}
+
+function readPersistedSession(): {
+	sessionId: string;
+	activity: number;
+	sessionStart: number;
+} | null {
+	migrateLegacySession();
+
+	const local = getLocalStorage();
+	const sessionId = storageGet(local, LS_SESSION_ID);
+	const activity = parseTimestamp(storageGet(local, LS_SESSION_ACTIVITY));
+	const sessionStart = parseTimestamp(storageGet(local, LS_SESSION_START));
+
+	if (!sessionId || activity === null) return null;
+
+	return {
+		sessionId,
+		activity,
+		sessionStart: sessionStart ?? activity,
+	};
+}
+
+function writePersistedSession(
+	sessionId: string,
+	activity: number,
+	sessionStart: number,
+): void {
+	const local = getLocalStorage();
+	const wroteId = storageSet(local, LS_SESSION_ID, sessionId);
+	storageSet(local, LS_SESSION_ACTIVITY, activity.toString());
+	storageSet(local, LS_SESSION_START, sessionStart.toString());
+
+	if (!wroteId) {
+		ephemeralSession = { sessionId, activity, sessionStart };
+	}
+}
+
+function clearPersistedSession(): void {
+	const local = getLocalStorage();
+	storageRemove(local, LS_SESSION_ID);
+	storageRemove(local, LS_SESSION_ACTIVITY);
+	storageRemove(local, LS_SESSION_START);
+}
+
+function isSessionExpired(
+	activity: number,
+	sessionStart: number,
+	now: number,
+): boolean {
+	if (now - activity >= SESSION_IDLE_TIMEOUT_MS) return true;
+	return now - sessionStart >= SESSION_MAX_AGE_MS;
+}
+
+function ephemeralRecord(now: number): {
+	sessionId: string;
+	sessionStart: number;
+	activity: number;
+} {
+	if (!ephemeralSession) {
+		ephemeralSession = {
+			sessionId: createId(),
+			sessionStart: now,
+			activity: now,
+		};
+	}
+	return ephemeralSession;
+}
+
+function resolveSessionRecord(
+	cookieless: boolean,
+	touch: boolean,
+): {
+	sessionId: string;
+	sessionStart: number;
+	rotated: boolean;
+	previous: { sessionId: string; sessionStart: number } | null;
+} {
+	const now = Date.now();
+
+	if (cookieless) {
+		const record = ephemeralRecord(now);
+		if (touch) record.activity = now;
+		return {
+			sessionId: record.sessionId,
+			sessionStart: record.sessionStart,
+			rotated: false,
+			previous: null,
+		};
+	}
+
+	const existing = readPersistedSession() ?? ephemeralSession;
+	if (
+		existing &&
+		!isSessionExpired(existing.activity, existing.sessionStart, now)
+	) {
+		if (touch) {
+			writePersistedSession(existing.sessionId, now, existing.sessionStart);
+		}
+		return {
+			sessionId: existing.sessionId,
+			sessionStart: existing.sessionStart,
+			rotated: false,
+			previous: null,
+		};
+	}
+
+	const previous =
+		existing !== null
+			? {
+					sessionId: existing.sessionId,
+					sessionStart: existing.sessionStart,
+				}
+			: null;
+
+	const sessionId = createId();
+	writePersistedSession(sessionId, now, now);
+
+	return {
+		sessionId,
+		sessionStart: now,
+		rotated: previous !== null,
+		previous,
+	};
+}
+
+export function getOrCreateWindowId(
+	siteKey: string,
+	cookieless?: boolean,
+): string {
+	if (cookieless ?? cookielessMode) {
+		return resolveSessionRecord(true, false).sessionId;
+	}
+
+	const key = windowIdKey(siteKey);
+	const session = getSessionStorage();
+	if (!session) return resolveSessionRecord(false, false).sessionId;
+
+	const existing = storageGet(session, key);
+	if (existing) return existing;
+
+	const windowId = createId();
+	storageSet(session, key, windowId);
+	return windowId;
+}
+
+function clearWindowId(siteKey: string): void {
+	storageRemove(getSessionStorage(), windowIdKey(siteKey));
+}
+
+export function getSessionContext(
+	siteKey: string,
+	cookieless?: boolean,
+): SessionContext {
+	const useCookieless = cookieless ?? cookielessMode;
+	const record = resolveSessionRecord(useCookieless, false);
+	const windowId = getOrCreateWindowId(siteKey, useCookieless);
+
+	const context: SessionContext = {
+		sessionId: record.sessionId,
+		windowId,
+		sessionStart: record.sessionStart,
+	};
+
+	if (record.rotated && record.previous) {
+		const prev: SessionContext = {
+			sessionId: record.previous.sessionId,
+			windowId,
+			sessionStart: record.previous.sessionStart,
+		};
+		notifyRotation(prev, context);
+	}
+
+	return context;
+}
+
+export function getOrCreateSessionId(cookieless?: boolean): string {
+	return resolveSessionRecord(cookieless ?? cookielessMode, true).sessionId;
+}
+
+export function getSessionStart(cookieless?: boolean): number {
+	return resolveSessionRecord(cookieless ?? cookielessMode, false).sessionStart;
+}
+
+export function touchActivity(cookieless?: boolean): SessionRotation | null {
+	const useCookieless = cookieless ?? cookielessMode;
+	const record = resolveSessionRecord(useCookieless, true);
+	if (record.rotated && record.previous) {
+		const siteKey = defaultSiteKey || "_default";
+		const rotation = {
+			prev: {
+				sessionId: record.previous.sessionId,
+				windowId: getOrCreateWindowId(siteKey, useCookieless),
+				sessionStart: record.previous.sessionStart,
+			},
+			next: {
+				sessionId: record.sessionId,
+				windowId: getOrCreateWindowId(siteKey, useCookieless),
+				sessionStart: record.sessionStart,
+			},
+		};
+		notifyRotation(rotation.prev, rotation.next);
+		return rotation;
+	}
+	return null;
+}
+
+export function refreshSessionTimestamp(cookieless?: boolean): void {
+	const useCookieless = cookieless ?? cookielessMode;
+	const now = Date.now();
+
+	if (useCookieless) {
+		if (ephemeralSession) ephemeralSession.activity = now;
+		return;
+	}
+
+	const existing = readPersistedSession() ?? ephemeralSession;
+	if (!existing) return;
+
+	writePersistedSession(existing.sessionId, now, existing.sessionStart);
+}
+
+export function resetSession(siteKey?: string): SessionContext {
+	const key = siteKey ?? defaultSiteKey ?? "_default";
+	const now = Date.now();
+	let previous: SessionContext | null = null;
+
+	if (cookielessMode) {
+		if (ephemeralSession) {
+			previous = {
+				sessionId: ephemeralSession.sessionId,
+				windowId: ephemeralSession.sessionId,
+				sessionStart: ephemeralSession.sessionStart,
+			};
+		}
+		ephemeralSession = {
+			sessionId: createId(),
+			sessionStart: now,
+			activity: now,
+		};
+	} else {
+		const existing = readPersistedSession();
+		if (existing) {
+			previous = {
+				sessionId: existing.sessionId,
+				windowId: getOrCreateWindowId(key, false),
+				sessionStart: existing.sessionStart,
+			};
+		}
+		clearPersistedSession();
+		ephemeralSession = null;
+	}
+
+	clearWindowId(key);
+	const next = getSessionContext(key, cookielessMode);
+
+	if (previous && previous.sessionId !== next.sessionId) {
+		notifyRotation(previous, next);
+	}
+
+	return next;
+}
+
+export function onSessionRotated(
+	listener: (prev: SessionContext, next: SessionContext) => void,
+): () => void {
+	rotationListeners.add(listener);
+	return () => {
+		rotationListeners.delete(listener);
+	};
+}

package/src/web-vitals.ts

@@ -1,6 +1,6 @@
 import type { Metric, MetricWithAttribution } from "web-vitals";
 import { normalizeAnalyticsBaseUrl, URLS } from "./utils/api-urls";
-import { getOrCreateSessionId } from "./utils/identifiers";
+import { getOrCreateSessionId } from "./utils/session-manager";
 import { normalizeSamplingPercentage } from "./utils/types";
 
 export interface WebVitalsOptions {

package/tests/analytics.test.ts

@@ -399,10 +399,13 @@ describe("WebAnalytics lifecycle", () => {
 		});
 
 		await analytics.start();
-		const storage = globalThis.sessionStorage as unknown as MockStorage;
-		const sessionId = storage.getItem("session_id");
+		const storage = globalThis.localStorage as unknown as MockStorage;
+		const sessionId = storage.getItem("faststats_session_id");
 		expect(sessionId).toBeTruthy();
-		storage.setItem("session_timestamp", "0");
+		storage.setItem(
+			"faststats_session_activity",
+			(Date.now() - 31 * 60 * 1000).toString(),
+		);
 		harness.fetchCalls.length = 0;
 
 		Object.defineProperty(globalThis.document, "visibilityState", {
@@ -420,7 +423,7 @@ describe("WebAnalytics lifecycle", () => {
 		}
 		await wait(0);
 
-		expect(storage.getItem("session_id")).toBe(sessionId);
+		expect(storage.getItem("faststats_session_id")).toBe(sessionId);
 		const pageLeaveCall = harness.fetchCalls.find((call) =>
 			call.body?.includes('"event":"page_leave"'),
 		);

package/tests/identifiers.test.ts

@@ -1,10 +1,10 @@
 import { afterEach, beforeEach, describe, expect, test } from "bun:test";
 import {
+	getAnonymousId,
 	getOrCreateAnonymousId,
-	getOrCreateSessionId,
-	getSessionStart,
-	resetSessionId,
+	resetAnonymousId,
 } from "../src/utils/identifiers";
+import { setCookielessMode } from "../src/utils/session-manager";
 
 class MockStorage {
 	private readonly data = new Map<string, string>();
@@ -32,17 +32,16 @@ function setGlobal(name: keyof typeof globalThis, value: unknown): void {
 
 const original = {
 	localStorage: globalThis.localStorage,
-	sessionStorage: globalThis.sessionStorage,
 };
 
 beforeEach(() => {
 	setGlobal("localStorage", new MockStorage());
-	setGlobal("sessionStorage", new MockStorage());
+	setCookielessMode(false);
 });
 
 afterEach(() => {
 	setGlobal("localStorage", original.localStorage);
-	setGlobal("sessionStorage", original.sessionStorage);
+	setCookielessMode(false);
 });
 
 describe("identifiers", () => {
@@ -53,43 +52,27 @@ describe("identifiers", () => {
 		expect(second).toBe(id);
 	});
 
-	test("session id is recreated when timestamp is invalid", () => {
-		const storage = globalThis.sessionStorage as unknown as MockStorage;
-		storage.setItem("session_id", "old-session");
-		storage.setItem("session_timestamp", "NaN");
-		const id = getOrCreateSessionId();
-		expect(id).not.toBe("old-session");
-	});
-
-	test("session start falls back when stored value is invalid", () => {
-		const storage = globalThis.sessionStorage as unknown as MockStorage;
-		storage.setItem("session_start", "NaN");
-		const start = getSessionStart();
-		expect(Number.isNaN(start)).toBe(true);
-	});
-
-	test("resetSessionId creates a new session id", () => {
-		const first = getOrCreateSessionId();
-		const second = resetSessionId();
+	test("resetAnonymousId creates a new anonymous id", () => {
+		const first = getOrCreateAnonymousId();
+		const second = resetAnonymousId();
 		expect(second.length).toBeGreaterThan(0);
 		expect(second).not.toBe(first);
 	});
 
-	test("storage access failures disable persisted identifiers", () => {
+	test("cookieless mode skips anonymous id persistence", () => {
+		setCookielessMode(true);
+		expect(getAnonymousId()).toBe("");
+	});
+
+	test("storage access failures disable persisted anonymous id", () => {
 		Object.defineProperty(globalThis, "localStorage", {
 			configurable: true,
 			get() {
 				throw new Error("storage blocked");
 			},
 		});
-		Object.defineProperty(globalThis, "sessionStorage", {
-			configurable: true,
-			get() {
-				throw new Error("storage blocked");
-			},
-		});
 
 		expect(getOrCreateAnonymousId()).toBe("");
-		expect(getOrCreateSessionId()).toBe("");
+		expect(resetAnonymousId()).toBe("");
 	});
 });