@faststats/web 0.12.1 → 0.13.1

package/README.md

@@ -48,8 +48,8 @@ Consent remains client-local: use `"anonymous"` for cookieless collection,
 
 ### Visit duration
 
-`page_leave.properties.time_on_page` is the accumulated time in milliseconds
-that the page was visible and its document had focus. It pauses when the tab is
+`properties.time_on_page` on `page_ping` and `page_leave` is the accumulated
+time in milliseconds that the page was visible and its document had focus. It pauses when the tab is
 hidden, the window loses focus, or the page enters the back-forward cache, and
 resets on navigation, logout, or session rotation. A monotonic clock keeps
 system-clock changes from affecting this duration. It also pauses after 60
@@ -60,11 +60,24 @@ the device spent asleep or the tab frozen is not counted.
 Pageviews wait until the page becomes visible. Pages replaced or closed before
 being shown do not emit pageviews or page-leave events.
 
-The SDK sends cumulative `page_leave` checkpoints every 15 seconds while active
-and when activity pauses or the visit ends. Unchanged checkpoints are suppressed.
-Pageviews and their checkpoints share `properties.visit_id`; consumers should use
-the maximum `time_on_page` per visit, never sum its checkpoints. The existing
-session-duration and bounce-rate queries already use maximum values.
+The SDK sends a cumulative `page_ping` when activity pauses and periodically
+while active: after 15 and 45 seconds, then every 60 seconds. A ping that adds no
+time is suppressed. A visit ends with
+exactly one `page_leave`, on navigation, a terminal `pagehide`, logout, a consent
+change, or session rotation. A page the browser discards without notice never
+sends one, so its last ping holds its duration. A pageview, its pings, and its
+leave share `properties.visit_id`; consumers should use the maximum
+`time_on_page` per visit across both events, never sum them.
+
+Before 0.13 the pings were sent as `page_leave` every 15 seconds. The collector
+and dashboards read both shapes; deploy them before releasing this SDK.
+
+### Default context
+
+Every event carries `timezone` (IANA name), `language`, and `screen`
+(`1920x1080`, CSS pixels) beside the page context, separate from its properties.
+Custom events and outbound links also carry the `visit_id` of the page view they
+happened during.
 
 Each visit retains its original identity, session, and page metadata. A session
 or identity change starts a new visit, even on the same route. Both persistent
@@ -76,7 +89,7 @@ session, so it is separate from active time on the page. An idle visitor stops
 extending the session, which then expires after 30 minutes like any other.
 
 Delivery is best effort: a sudden process kill or network failure can lose time
-since the last delivered checkpoint. The collector must accept successive events
+since the last delivered ping. The collector must accept successive events
 for the same visitor and URL; deploy the removal of its five-second debounce
 before releasing this SDK.
 

package/dist/chunks/identifiers-3X8XI1pD.js

@@ -0,0 +1,16 @@
+import { o as getStorageItem, s as setStorageItem, t as createId } from "./session-manager-VM5RZj9H.js";
+//#region src/utils/identifiers.ts
+const key = (siteKey) => `faststats_anon_id_${siteKey}`;
+/** The visitor's persisted anonymous ID, or "" when it cannot be stored. */
+function getAnonymousId(siteKey, cookieless = false) {
+	if (cookieless) return "";
+	const existing = getStorageItem("localStorage", key(siteKey));
+	if (existing) return existing;
+	const id = createId();
+	return setStorageItem("localStorage", key(siteKey), id) ? id : "";
+}
+function resetAnonymousId(siteKey, cookieless = false) {
+	return !cookieless && setStorageItem("localStorage", key(siteKey), null) ? getAnonymousId(siteKey) : "";
+}
+//#endregion
+export { resetAnonymousId as n, getAnonymousId as t };

package/dist/chunks/send-data-B7P3f5PT.js

@@ -0,0 +1,177 @@
+//#region src/extensions.ts
+/** Runs a built-in tracker with the client's settings and page lifecycle. */
+function trackerExtension(name, create, hook) {
+	return {
+		name,
+		setup(context) {
+			const { siteKey, baseUrl, debug, trackHash, sdkName, sdkVersion } = context;
+			const tracker = create({
+				siteKey,
+				baseUrl,
+				debug,
+				trackHash,
+				cookieless: context.isCookieless(),
+				sdkName,
+				sdkVersion
+			});
+			context.on("pageHide", ({ persisted, terminal }) => tracker.onPageHidden(persisted, terminal));
+			context.on("consentChange", ({ cookieless }) => tracker.setCookielessMode(cookieless));
+			hook?.(tracker, context);
+			tracker.start();
+			return ({ discard }) => tracker.stop(discard);
+		}
+	};
+}
+var ExtensionHost = class {
+	context;
+	log;
+	handlers = /* @__PURE__ */ new Map();
+	cleanups = [];
+	stopped = false;
+	constructor(extensions, context, log) {
+		this.context = context;
+		this.log = log;
+		for (const extension of extensions) this.setup(extension);
+	}
+	emit(hook, event) {
+		if (this.stopped) return;
+		for (const handler of this.handlers.get(hook) ?? []) try {
+			handler(event)?.catch((error) => this.log(`${hook} failed`, error));
+		} catch (error) {
+			this.log(`${hook} failed`, error);
+		}
+	}
+	stop(discard = false) {
+		if (this.stopped) return;
+		this.stopped = true;
+		for (const cleanup of this.cleanups.reverse()) try {
+			cleanup({ discard });
+		} catch (error) {
+			this.log("cleanup failed", error);
+		}
+		this.cleanups.length = 0;
+		this.handlers.clear();
+	}
+	async setup(extension) {
+		if (this.stopped) return;
+		const subscriptions = [];
+		try {
+			const cleanup = await extension.setup({
+				...this.context,
+				on: (hook, handler) => {
+					if (this.stopped) return () => {};
+					const handlers = this.handlers.get(hook) ?? /* @__PURE__ */ new Set();
+					this.handlers.set(hook, handlers);
+					handlers.add(handler);
+					const off = () => handlers.delete(handler);
+					subscriptions.push(off);
+					return off;
+				}
+			});
+			if (this.stopped) cleanup?.({ discard: true });
+			else if (cleanup) this.cleanups.push(cleanup);
+		} catch (error) {
+			for (const off of subscriptions) off();
+			this.log(`${extension.name} setup failed`, error);
+		}
+	}
+};
+//#endregion
+//#region src/utils/api-urls.ts
+function resolveBaseUrl(baseUrl) {
+	return baseUrl?.replace(/\/+$/, "") || "https://metrics.faststats.dev";
+}
+const URLS = {
+	events: "/v1/web",
+	identify: "/v1/identify",
+	replay: "/v1/replay",
+	vitals: "/v1/vitals"
+};
+function sanitizeUrl(url, includeHash = false) {
+	try {
+		const parsed = new URL(url, location.href);
+		return `${parsed.origin}${parsed.pathname}${includeHash ? parsed.hash : ""}`;
+	} catch {
+		return url.split(includeHash ? "?" : /[?#]/, 1)[0] ?? "";
+	}
+}
+const UTM_KEYS = [
+	"utm_source",
+	"utm_medium",
+	"utm_campaign",
+	"utm_term",
+	"utm_content"
+];
+function getReferrer() {
+	const raw = document.referrer;
+	if (!raw) return null;
+	try {
+		if (new URL(raw, location.href).origin === location.origin) return null;
+	} catch {}
+	return sanitizeUrl(raw);
+}
+/** Visitor environment sent with every event; unavailable values are omitted. */
+function getClientContext() {
+	let timezone;
+	try {
+		timezone = Intl.DateTimeFormat().resolvedOptions().timeZone;
+	} catch {}
+	const { width, height } = globalThis.screen ?? {};
+	return {
+		timezone,
+		language: globalThis.navigator?.language,
+		screen: width && height ? `${width}x${height}` : void 0
+	};
+}
+function getPageContext(includeHash = false) {
+	const hash = includeHash ? location.hash : "";
+	const ctx = {
+		page: `${location.pathname}${hash}`,
+		url: sanitizeUrl(location.href, includeHash),
+		referrer: getReferrer(),
+		title: document.title
+	};
+	if (!location.search) return ctx;
+	const sp = new URLSearchParams(location.search);
+	for (const key of UTM_KEYS) {
+		const value = sp.get(key);
+		if (value) ctx[key] = value;
+	}
+	return ctx;
+}
+//#endregion
+//#region src/utils/send-data.ts
+async function sendData(options) {
+	const { url, data, contentType = "application/json", debug = false, debugPrefix = "[Analytics]", useBeacon = true, keepalive = true, settleRejected } = options;
+	const log = (...details) => {
+		if (debug) console.log(debugPrefix, ...details);
+	};
+	if (useBeacon) try {
+		const body = data instanceof Blob ? data : new Blob([data], { type: contentType });
+		if (navigator.sendBeacon(url, body)) {
+			log("Sent via beacon");
+			return true;
+		}
+	} catch {}
+	const post = (keepalive) => fetch(url, {
+		method: "POST",
+		body: data,
+		headers: { "Content-Type": contentType },
+		keepalive,
+		credentials: "omit"
+	});
+	try {
+		const useKeepalive = keepalive && new Blob([data]).size <= 61440;
+		const { ok, status } = await post(useKeepalive).catch((error) => {
+			if (!useKeepalive) throw error;
+			return post(false);
+		});
+		log(ok ? "Sent via fetch" : status);
+		return ok || !!settleRejected && status < 500 && status !== 429;
+	} catch {
+		log("Failed to send");
+		return false;
+	}
+}
+//#endregion
+export { resolveBaseUrl as a, trackerExtension as c, getPageContext as i, URLS as n, sanitizeUrl as o, getClientContext as r, ExtensionHost as s, sendData as t };

package/dist/chunks/session-manager-VM5RZj9H.js

@@ -0,0 +1,116 @@
+//#region src/utils/storage.ts
+function getStorageItem(name, key) {
+	try {
+		return globalThis[name]?.getItem(key) ?? null;
+	} catch {
+		return null;
+	}
+}
+/** Stores `value`, or removes the item for null. False when storage fails. */
+function setStorageItem(name, key, value) {
+	try {
+		const storage = globalThis[name];
+		if (!storage) return false;
+		if (value === null) storage.removeItem(key);
+		else storage.setItem(key, value);
+		return true;
+	} catch {
+		return false;
+	}
+}
+//#endregion
+//#region src/utils/session-manager.ts
+const IDLE_MS = 18e5;
+const MAX_AGE_MS = 864e5;
+const SESSION_KEY = "faststats_session_";
+const WINDOW_KEY = "faststats_window_id_";
+const memory = /* @__PURE__ */ new Map();
+const listeners = /* @__PURE__ */ new Map();
+const NO_STORAGE = {};
+const slot = (siteKey, cookieless) => `${siteKey}:${cookieless ? "memory" : "persistent"}`;
+function storageScope() {
+	try {
+		return globalThis.localStorage ?? NO_STORAGE;
+	} catch {
+		return NO_STORAGE;
+	}
+}
+function createId() {
+	if (typeof crypto !== "undefined" && "randomUUID" in crypto) return crypto.randomUUID();
+	return `${Date.now().toString(36)}-${Math.random().toString(36).slice(2)}`;
+}
+function load(siteKey, cookieless) {
+	if (!cookieless) try {
+		const session = JSON.parse(getStorageItem("localStorage", `${SESSION_KEY}${siteKey}`) ?? "null");
+		if (typeof session?.id === "string" && session.id && Number.isFinite(session.start) && Number.isFinite(session.activity)) return session;
+	} catch {}
+	const entry = memory.get(slot(siteKey, cookieless));
+	return entry?.scope === storageScope() ? entry.session : null;
+}
+function save(siteKey, cookieless, session) {
+	const json = JSON.stringify(session);
+	if (cookieless || !setStorageItem("localStorage", SESSION_KEY + siteKey, json)) memory.set(slot(siteKey, cookieless), {
+		scope: storageScope(),
+		session
+	});
+}
+function toContext(siteKey, cookieless, { id, start }) {
+	let windowId = cookieless ? id : getStorageItem("sessionStorage", WINDOW_KEY + siteKey);
+	if (!windowId) {
+		windowId = createId();
+		if (!setStorageItem("sessionStorage", WINDOW_KEY + siteKey, windowId)) windowId = id;
+	}
+	return {
+		sessionId: id,
+		windowId,
+		sessionStart: start
+	};
+}
+function emit(siteKey, cookieless, prev, next) {
+	for (const listener of listeners.get(slot(siteKey, cookieless)) ?? []) listener(prev, next);
+}
+function resolveSession(siteKey, cookieless, touch) {
+	const now = Date.now();
+	const existing = load(siteKey, cookieless);
+	const expired = !!existing && (now - existing.activity >= IDLE_MS || now - existing.start >= MAX_AGE_MS);
+	const session = existing && !expired ? existing : {
+		id: createId(),
+		start: now,
+		activity: now
+	};
+	if (touch) session.activity = now;
+	if (touch || session !== existing) save(siteKey, cookieless, session);
+	const context = toContext(siteKey, cookieless, session);
+	if (existing && expired) emit(siteKey, cookieless, toContext(siteKey, cookieless, existing), context);
+	return context;
+}
+/** The current session, replacing an expired one without counting activity. */
+function getSessionContext(siteKey, cookieless = false) {
+	return resolveSession(siteKey, cookieless, false);
+}
+/** Counts visitor activity in the current session, which it returns. */
+function touchActivity(siteKey, cookieless = false) {
+	return resolveSession(siteKey, cookieless, true);
+}
+function resetSession(siteKey, cookieless = false) {
+	const prev = getSessionContext(siteKey, cookieless);
+	memory.delete(slot(siteKey, cookieless));
+	if (!cookieless) {
+		setStorageItem("localStorage", SESSION_KEY + siteKey, null);
+		setStorageItem("sessionStorage", WINDOW_KEY + siteKey, null);
+	}
+	const next = getSessionContext(siteKey, cookieless);
+	if (prev.sessionId !== next.sessionId) emit(siteKey, cookieless, prev, next);
+	return next;
+}
+function onSessionRotated(siteKey, cookieless, listener) {
+	const key = slot(siteKey, cookieless);
+	const set = listeners.get(key) ?? /* @__PURE__ */ new Set();
+	listeners.set(key, set.add(listener));
+	return () => {
+		set.delete(listener);
+		if (!set.size) listeners.delete(key);
+	};
+}
+//#endregion
+export { touchActivity as a, resetSession as i, getSessionContext as n, getStorageItem as o, onSessionRotated as r, setStorageItem as s, createId as t };

package/dist/error.d.ts

@@ -39,6 +39,8 @@ export default class ErrorTracker {
   private onError;
   private onRejection;
   private enqueue;
+  /** Returns true when the error was already queued. */
+  private add;
   private flush;
 }
 //#endregion

package/dist/error.js

@@ -1,30 +1,14 @@
-import { i as resolveBaseUrl, n as URLS, r as getPageContext, t as sendData } from "./chunks/send-data-gBIF6DTb.js";
-import { n as getSessionContext } from "./chunks/session-manager-DUpF3mi3.js";
-import { t as getAnonymousId } from "./chunks/identifiers-DOtve3E5.js";
+import { a as resolveBaseUrl, c as trackerExtension, i as getPageContext, n as URLS, t as sendData } from "./chunks/send-data-B7P3f5PT.js";
+import { n as getSessionContext } from "./chunks/session-manager-VM5RZj9H.js";
+import { t as getAnonymousId } from "./chunks/identifiers-3X8XI1pD.js";
 //#region src/error.ts
 const SDK_NAME = "@faststats/web";
-const SDK_VERSION = "0.12.1";
+const SDK_VERSION = "0.13.1";
 function errorTracking(options = {}) {
-	return {
-		name: "error-tracking",
-		setup(context) {
-			const tracker = new ErrorTracker({
-				...options,
-				siteKey: context.siteKey,
-				baseUrl: context.baseUrl,
-				debug: context.debug,
-				trackHash: context.trackHash,
-				cookieless: context.isCookieless(),
-				sdkName: context.sdkName,
-				sdkVersion: context.sdkVersion
-			});
-			context.on("pageHide", ({ persisted }) => tracker.onPageHidden(persisted));
-			context.on("error", ({ error }) => tracker.captureError(error));
-			context.on("consentChange", ({ cookieless }) => tracker.setCookielessMode(cookieless));
-			tracker.start();
-			return ({ discard }) => tracker.stop(discard);
-		}
-	};
+	return trackerExtension("error-tracking", (context) => new ErrorTracker({
+		...options,
+		...context
+	}), (tracker, context) => context.on("error", ({ error }) => tracker.captureError(error)));
 }
 const EXTENSION_URL = /(?:^|\()(chrome|moz|ms-browser|safari-web)-extension:\/\//;
 function toEntry(kind, source, handled, fallback) {
@@ -103,23 +87,34 @@ var ErrorTracker = class {
 		const buildId = globalThis.__SOURCEMAPS_BUILD__?.buildId;
 		const userId = getAnonymousId(this.options.siteKey, this.cookieless);
 		const ctx = getSessionContext(this.options.siteKey, this.cookieless);
-		this.queue.push({
+		const context = {
+			token: this.options.siteKey,
+			...userId ? { userId } : {},
+			sessionId: ctx.sessionId,
+			windowId: ctx.windowId,
+			...typeof buildId === "string" && buildId.trim() ? { buildId } : {},
+			sdkName: this.options.sdkName ?? SDK_NAME,
+			sdkVersion: this.options.sdkVersion ?? SDK_VERSION,
+			event: "error",
+			...getPageContext(this.options.trackHash ?? false),
+			properties: {}
+		};
+		const key = JSON.stringify([context, error]);
+		if (this.add({
+			key,
+			context,
 			error,
-			context: {
-				token: this.options.siteKey,
-				...userId ? { userId } : {},
-				sessionId: ctx.sessionId,
-				windowId: ctx.windowId,
-				...typeof buildId === "string" && buildId.trim() ? { buildId } : {},
-				sdkName: this.options.sdkName ?? SDK_NAME,
-				sdkVersion: this.options.sdkVersion ?? SDK_VERSION,
-				event: "error",
-				...getPageContext(this.options.trackHash ?? false),
-				properties: {}
-			}
-		});
+			count: 1
+		})) return;
 		if (this.queue.length >= this.maxQueueSize) this.flush();
 	}
+	/** Returns true when the error was already queued. */
+	add(item) {
+		const queued = this.queue.find(({ key }) => key === item.key);
+		if (queued) queued.count += item.count;
+		else this.queue.push(item);
+		return !!queued;
+	}
 	async flush() {
 		if (this.flushing || !this.queue.length) return;
 		this.flushing = true;
@@ -129,42 +124,35 @@ var ErrorTracker = class {
 		const groups = /* @__PURE__ */ new Map();
 		for (const item of batch) {
 			const key = JSON.stringify(item.context);
-			const group = groups.get(key) ?? {
-				context: item.context,
-				items: []
-			};
-			group.items.push(item);
-			groups.set(key, group);
+			const group = groups.get(key);
+			if (group) group.push(item);
+			else groups.set(key, [item]);
 		}
 		let failed = [];
 		try {
-			failed = (await Promise.all([...groups.values()].map(async (group) => {
-				const errors = /* @__PURE__ */ new Map();
-				for (const { error } of group.items) {
-					const key = JSON.stringify(error);
-					const existing = errors.get(key);
-					if (existing) existing.count++;
-					else errors.set(key, {
-						...error,
-						count: 1
-					});
-				}
+			failed = (await Promise.all([...groups.values()].map(async (items) => {
 				return await sendData({
 					url: this.endpoint,
 					data: JSON.stringify({
-						...group.context,
-						errors: [...errors.values()]
+						...items[0]?.context,
+						errors: items.map(({ error, count }) => ({
+							...error,
+							count
+						}))
 					}),
 					debug: this.options.debug,
 					debugPrefix: "[ErrorTracker]",
 					settleRejected: true
-				}) ? [] : group.items;
+				}) ? [] : items;
 			}))).flat();
 		} finally {
 			this.flushing = false;
 		}
 		if (generation !== this.generation) return;
-		this.queue = [...failed, ...this.queue].slice(-this.maxQueueSize);
+		const captured = this.queue;
+		this.queue = [...failed];
+		for (const item of captured) this.add(item);
+		this.queue = this.queue.slice(-this.maxQueueSize);
 		if (!this.started && !failed.length) this.flush();
 	}
 };

package/dist/flags.js

@@ -1,5 +1,5 @@
-import { n as getSessionContext } from "./chunks/session-manager-DUpF3mi3.js";
-import { t as getAnonymousId } from "./chunks/identifiers-DOtve3E5.js";
+import { n as getSessionContext } from "./chunks/session-manager-VM5RZj9H.js";
+import { t as getAnonymousId } from "./chunks/identifiers-3X8XI1pD.js";
 //#region src/flags.ts
 const DEFAULT_ENDPOINT = "https://flags.faststats.dev";
 const DEFAULT_TIMEOUT_MS = 3e3;

package/dist/index.d.ts

@@ -66,6 +66,7 @@ export declare class WebAnalytics {
   private readonly onPageHide;
   private readonly onPageShow;
   private readonly onResume;
+  private readonly onBlur;
   private readonly onActivity;
   private isIdle;
   private leavePage;