@releval/tracker 1.0.0-bootstrap.0

package/dist/tracker.cjs

@@ -0,0 +1,1663 @@
+/*! @releval/tracker | Apache-2.0 | https://github.com/releval/tracker */
+let ulidx = require("ulidx");
+//#region src/utils/index.ts
+const debounce = (func, wait = 100, immediate = false) => {
+	let timeout = null;
+	let args = null;
+	let context = null;
+	let result;
+	const later = () => {
+		timeout = null;
+		if (args) {
+			result = func.apply(context, args);
+			context = args = null;
+		}
+	};
+	const debounced = function(...callArgs) {
+		context = this;
+		args = callArgs;
+		const callNow = immediate && !timeout;
+		if (timeout) clearTimeout(timeout);
+		if (callNow) {
+			result = func.apply(context, args);
+			context = args = null;
+		} else timeout = setTimeout(later, wait);
+		return result;
+	};
+	debounced.clear = () => {
+		if (timeout) {
+			clearTimeout(timeout);
+			timeout = null;
+		}
+	};
+	debounced.flush = () => {
+		if (timeout) {
+			result = func.apply(context, args);
+			context = args = null;
+			clearTimeout(timeout);
+			timeout = null;
+		}
+	};
+	return debounced;
+};
+/**
+* Creates a MutationObserver that invokes `addHandler`/`removeHandler` for every element
+* matching `selector` that is added to or removed from the DOM - including matches nested
+* inside an added/removed subtree. When a container is inserted or removed as a unit, only
+* its root appears in the mutation record, so its descendants must be scanned too (otherwise
+* results rendered as a subtree would be missed and subtree removals would leak listeners).
+*/
+const createMutationObserver = (selector, addHandler, removeHandler) => {
+	const forEachMatch = (node, handler) => {
+		if (node.nodeType !== Node.ELEMENT_NODE) return;
+		const element = node;
+		if (element.matches(selector)) handler(element);
+		for (const descendant of element.querySelectorAll(selector)) handler(descendant);
+	};
+	return new MutationObserver((mutations) => {
+		for (const mutation of mutations) {
+			if (mutation.type !== "childList") continue;
+			mutation.addedNodes.forEach((node) => {
+				forEachMatch(node, addHandler);
+			});
+			mutation.removedNodes.forEach((node) => {
+				forEachMatch(node, removeHandler);
+			});
+		}
+	});
+};
+/**
+* A valid UBI rank: a positive integer (1-based, absolute across pages:
+* `(page - 1) * pageSize + positionOnPage`). Anything else - 0, negative,
+* fractional, NaN - is not a rank and must never be sent: a fabricated
+* ordinal is indistinguishable from data downstream.
+*/
+const isValidOrdinal = (value) => typeof value === "number" && Number.isInteger(value) && value >= 1;
+//#endregion
+//#region src/collectors/resolveResult.ts
+let hasWarnedMalformedJson = false;
+/**
+* A `data-event-*` value that looks like a JSON object or array is parsed as
+* one, so markup can carry structured attributes
+* (`data-event-filters='{"brand":"acme"}'`). Anything else - scalars
+* included - stays a string; typed scalars use the direct API. A malformed
+* candidate falls back to the raw string with a one-time warning.
+*/
+const parseAttributeValue = (raw, datasetKey, logger) => {
+	const trimmed = raw.trim();
+	if (!trimmed.startsWith("{") && !trimmed.startsWith("[")) return raw;
+	try {
+		return JSON.parse(trimmed);
+	} catch (_exception) {
+		if (!hasWarnedMalformedJson) {
+			hasWarnedMalformedJson = true;
+			const attribute = `data-${datasetKey.replace(/[A-Z]/g, (c) => `-${c.toLowerCase()}`)}`;
+			logger === null || logger === void 0 || logger.warn(`readResultData: the value of ${attribute} looks like JSON but does not parse; it is kept as a string. Further malformed values are kept silently.`);
+		}
+		return raw;
+	}
+};
+/**
+* Reads the documented data-attribute convention off a result element:
+*
+* - `data-object-id`, `data-ordinal`, `data-object-id-field` and (optionally)
+*   `data-action-name` on the result element itself;
+* - `data-event-*` on the result element for custom event attributes:
+*   `data-event-badge="sale"` becomes `badge: "sale"` (hyphens camelCase,
+*   underscores survive - `data-event-sale_price` -> `sale_price`); a value
+*   that looks like a JSON object or array is parsed as one
+*   (`data-event-filters='{"brand":"acme"}'`), any other value - scalars
+*   included - stays a string;
+* - `data-query-id` and `data-query` on the nearest ancestor carrying
+*   `data-query-id` (typically the results container, rendered server-side).
+*
+* A missing, empty or non-positive-integer `data-ordinal` yields
+* `undefined`, never 0 - a
+* fabricated rank is indistinguishable from data downstream. The collectors
+* validate what they need and warn (once) when a required field is absent.
+*
+* @param logger receives the one-time malformed-JSON warning; the collectors
+*   pass the tracker's logger.
+*/
+const readResultData = (element, logger) => {
+	var _element$dataset$ordi;
+	const container = element.closest("[data-query-id]");
+	const trimmed = (_element$dataset$ordi = element.dataset.ordinal) === null || _element$dataset$ordi === void 0 ? void 0 : _element$dataset$ordi.trim();
+	const parsed = trimmed ? Number(trimmed) : NaN;
+	const extras = {};
+	for (const key of Object.keys(element.dataset)) if (/^event[A-Z]/.test(key)) extras[key.charAt(5).toLowerCase() + key.slice(6)] = parseAttributeValue(element.dataset[key], key, logger);
+	return {
+		...extras,
+		objectId: element.dataset.objectId,
+		ordinal: isValidOrdinal(parsed) ? parsed : void 0,
+		objectIdField: element.dataset.objectIdField,
+		actionName: element.dataset.actionName,
+		queryId: container === null || container === void 0 ? void 0 : container.dataset.queryId,
+		query: container === null || container === void 0 ? void 0 : container.dataset.query
+	};
+};
+//#endregion
+//#region src/collectors/ResultClickCollector.ts
+/**
+* Declarative result-click collection for server-rendered markup.
+*
+* A single delegated, capture-phase listener on the root resolves the clicked
+* result and emits it in the canonical joinable shape via the tracker's
+* high-level API - the integrator never hand-builds a UBI event. Delegation
+* means results added or re-rendered after `start()` are covered with no
+* rebinding and no leaked listeners; capture phase means a descendant calling
+* `stopPropagation()` during bubbling cannot lose the click.
+*/
+var ResultClickCollector = class {
+	constructor(options, emit) {
+		this.hasWarnedUnresolvable = false;
+		this.hasWarnedBodyScope = false;
+		this.options = options;
+		this.emit = emit;
+	}
+	attach(dispatcher) {
+		var _this$options$root, _this$options$resolve;
+		const { selector, ignore } = this.options;
+		const root = (_this$options$root = this.options.root) !== null && _this$options$root !== void 0 ? _this$options$root : document;
+		const resolve = (_this$options$resolve = this.options.resolve) !== null && _this$options$resolve !== void 0 ? _this$options$resolve : ((el) => readResultData(el, dispatcher.logger));
+		const handler = (event) => {
+			try {
+				var _event$composedPath, _resolved$actionName;
+				const path = (_event$composedPath = event.composedPath) === null || _event$composedPath === void 0 ? void 0 : _event$composedPath.call(event)[0];
+				const target = path instanceof Element ? path : event.target;
+				const matched = target === null || target === void 0 ? void 0 : target.closest(selector);
+				if (!matched) return;
+				if (!this.options.resolve && (matched === document.body || matched === document.documentElement)) {
+					if (!this.hasWarnedBodyScope) {
+						var _dispatcher$logger;
+						this.hasWarnedBodyScope = true;
+						(_dispatcher$logger = dispatcher.logger) === null || _dispatcher$logger === void 0 || _dispatcher$logger.warn(`trackResultClicks: the selector "${selector}" matched the page body itself; these clicks are skipped. Narrow the selector to your result elements.`);
+					}
+					return;
+				}
+				if (ignore) {
+					const ignored = target === null || target === void 0 ? void 0 : target.closest(ignore);
+					if (ignored && ignored !== matched && matched.contains(ignored)) return;
+				}
+				const resolved = resolve(matched, event);
+				if (!resolved) return;
+				const actionName = (_resolved$actionName = resolved.actionName) !== null && _resolved$actionName !== void 0 ? _resolved$actionName : "click";
+				const unresolvableClick = actionName === "click" && (!isValidOrdinal(resolved.ordinal) || !resolved.queryId);
+				if (!resolved.objectId || unresolvableClick) {
+					if (!this.hasWarnedUnresolvable) {
+						var _dispatcher$logger2;
+						this.hasWarnedUnresolvable = true;
+						(_dispatcher$logger2 = dispatcher.logger) === null || _dispatcher$logger2 === void 0 || _dispatcher$logger2.warn(`trackResultClicks: skipped a click matching "${selector}" because objectId, ordinal or queryId could not be resolved. Add data-object-id and data-ordinal to the result element and data-query-id to an ancestor, or supply a resolve callback. Further unresolvable clicks are skipped silently.`);
+					}
+					return;
+				}
+				this.emit({
+					...resolved,
+					actionName
+				});
+			} catch (e) {
+				var _dispatcher$logger3;
+				(_dispatcher$logger3 = dispatcher.logger) === null || _dispatcher$logger3 === void 0 || _dispatcher$logger3.error("Error during handler execution: ", e);
+			}
+		};
+		root.addEventListener("click", handler, { capture: true });
+		return () => {
+			root.removeEventListener("click", handler, { capture: true });
+		};
+	}
+};
+//#endregion
+//#region src/collectors/ResultImpressionCollector.ts
+const FLUSH_DEBOUNCE_MS = 250;
+/**
+* Declarative result-impression collection for server-rendered markup.
+*
+* An `IntersectionObserver` (threshold 0) reports the first time each matching
+* element enters the viewport - once per element, so a card scrolled out and
+* back does not re-fire - and a `MutationObserver` on the root discovers
+* elements added or re-rendered after `start()`, so a results grid re-rendered
+* for a new query is picked up automatically. Resolved impressions are
+* coalesced in memory for a beat and emitted per query in the canonical
+* joinable shape via the tracker's high-level API. Nothing is persisted:
+* impressions pending at detach are dropped deliberately, because after the
+* page moves on their query context can no longer be trusted.
+*/
+var ResultImpressionCollector = class {
+	constructor(options, emit) {
+		this.hasWarnedUnresolvable = false;
+		this.hasWarnedBodyScope = false;
+		this.options = options;
+		this.emit = emit;
+	}
+	attach(dispatcher) {
+		var _this$options$root, _this$options$resolve;
+		const { selector } = this.options;
+		const root = (_this$options$root = this.options.root) !== null && _this$options$root !== void 0 ? _this$options$root : document;
+		const resolve = (_this$options$resolve = this.options.resolve) !== null && _this$options$resolve !== void 0 ? _this$options$resolve : ((el) => readResultData(el, dispatcher.logger));
+		const pending = [];
+		const flush = debounce(() => {
+			const groups = /* @__PURE__ */ new Map();
+			for (const entry of pending) {
+				var _entry$query;
+				const key = JSON.stringify([entry.queryId, (_entry$query = entry.query) !== null && _entry$query !== void 0 ? _entry$query : null]);
+				let group = groups.get(key);
+				if (!group) {
+					group = {
+						queryId: entry.queryId,
+						query: entry.query,
+						items: []
+					};
+					groups.set(key, group);
+				}
+				group.items.push(entry.item);
+			}
+			pending.length = 0;
+			for (const group of groups.values()) try {
+				this.emit(group.items, group.queryId, group.query);
+			} catch (e) {
+				var _dispatcher$logger;
+				(_dispatcher$logger = dispatcher.logger) === null || _dispatcher$logger === void 0 || _dispatcher$logger.error("Error emitting impressions: ", e);
+			}
+		}, FLUSH_DEBOUNCE_MS);
+		const observedElements = /* @__PURE__ */ new Set();
+		const observer = new IntersectionObserver((entries) => {
+			for (const entry of entries) {
+				if (!entry.isIntersecting) continue;
+				const element = entry.target;
+				observer.unobserve(element);
+				observedElements.delete(element);
+				try {
+					const resolved = resolve(element);
+					if (!resolved) continue;
+					if (!resolved.objectId || !isValidOrdinal(resolved.ordinal) || !resolved.queryId) {
+						if (!this.hasWarnedUnresolvable) {
+							var _dispatcher$logger2;
+							this.hasWarnedUnresolvable = true;
+							(_dispatcher$logger2 = dispatcher.logger) === null || _dispatcher$logger2 === void 0 || _dispatcher$logger2.warn(`trackResultImpressions: skipped an impression matching "${selector}" because objectId, ordinal or queryId could not be resolved. Add data-object-id and data-ordinal to the result element and data-query-id to an ancestor, or supply a resolve callback. Further unresolvable impressions are skipped silently.`);
+						}
+						continue;
+					}
+					const { actionName: _actionName, queryId: _queryId, query: _query, ...itemData } = resolved;
+					const item = {
+						...itemData,
+						objectId: resolved.objectId,
+						ordinal: resolved.ordinal
+					};
+					if (resolved.objectIdField) item.objectIdField = resolved.objectIdField;
+					pending.push({
+						item,
+						queryId: resolved.queryId,
+						query: resolved.query
+					});
+					flush();
+				} catch (e) {
+					var _dispatcher$logger3;
+					(_dispatcher$logger3 = dispatcher.logger) === null || _dispatcher$logger3 === void 0 || _dispatcher$logger3.error("Error resolving impression: ", e);
+				}
+			}
+		}, { threshold: 0 });
+		const addHandler = (element) => {
+			if (!this.options.resolve && (element === document.body || element === document.documentElement)) {
+				if (!this.hasWarnedBodyScope) {
+					var _dispatcher$logger4;
+					this.hasWarnedBodyScope = true;
+					(_dispatcher$logger4 = dispatcher.logger) === null || _dispatcher$logger4 === void 0 || _dispatcher$logger4.warn(`trackResultImpressions: the selector "${selector}" matched the page body itself; it is not observed. Narrow the selector to your result elements.`);
+				}
+				return;
+			}
+			if (!observedElements.has(element)) {
+				observedElements.add(element);
+				observer.observe(element);
+			}
+		};
+		const removeHandler = (element) => {
+			if (observedElements.has(element)) {
+				observer.unobserve(element);
+				observedElements.delete(element);
+			}
+		};
+		root.querySelectorAll(selector).forEach(addHandler);
+		const mutationObserver = createMutationObserver(selector, addHandler, removeHandler);
+		mutationObserver.observe(root, {
+			childList: true,
+			subtree: true
+		});
+		return () => {
+			mutationObserver.disconnect();
+			flush.clear();
+			observer.disconnect();
+			observedElements.clear();
+		};
+	}
+};
+//#endregion
+//#region src/logging/ConsoleLogger.ts
+/**
+* The default {@link Logger}. Routes tracker diagnostics to the browser console
+* so that an integrator can see, without any extra wiring, why events are not
+* arriving (bad site_id, non-retryable server response, storage failures, ...).
+* `debug`/`info` are suppressed unless `verbose` is set.
+*/
+var ConsoleLogger = class {
+	constructor(options = {}) {
+		var _options$verbose;
+		this.verbose = (_options$verbose = options.verbose) !== null && _options$verbose !== void 0 ? _options$verbose : false;
+	}
+	debug(msg, ...data) {
+		if (this.verbose) console.debug(msg, ...data);
+	}
+	info(msg, ...data) {
+		if (this.verbose) console.info(msg, ...data);
+	}
+	warn(msg, ...data) {
+		console.warn(msg, ...data);
+	}
+	error(msg, ...data) {
+		console.error(msg, ...data);
+	}
+};
+//#endregion
+//#region src/logging/safeLogger.ts
+const report = (e) => {
+	try {
+		console.error("The configured tracker logger threw: ", e);
+	} catch {}
+};
+/**
+* Wraps a logger so a throwing consumer logger can never escape the tracker's
+* own catch blocks (which themselves log) or `dispatch()`. The original
+* failure is surfaced via `console.error` rather than swallowed. Internal.
+*/
+const safeLogger = (logger) => ({
+	debug(msg, ...data) {
+		try {
+			logger.debug(msg, ...data);
+		} catch (e) {
+			report(e);
+		}
+	},
+	info(msg, ...data) {
+		try {
+			logger.info(msg, ...data);
+		} catch (e) {
+			report(e);
+		}
+	},
+	warn(msg, ...data) {
+		try {
+			logger.warn(msg, ...data);
+		} catch (e) {
+			report(e);
+		}
+	},
+	error(msg, ...data) {
+		try {
+			logger.error(msg, ...data);
+		} catch (e) {
+			report(e);
+		}
+	}
+});
+//#endregion
+//#region src/sinks/AggregateSink.ts
+/**
+* Emits events to multiple sinks
+*/
+var AggregateSink = class {
+	constructor(sinks, logger) {
+		this.sinks = sinks;
+		this.logger = logger;
+	}
+	add(sink) {
+		this.sinks.add(sink);
+	}
+	delete(sink) {
+		this.sinks.delete(sink);
+	}
+	emit(data) {
+		this.sinks.forEach((sink) => {
+			try {
+				sink.emit(data);
+			} catch (error) {
+				var _this$logger;
+				(_this$logger = this.logger) === null || _this$logger === void 0 || _this$logger.error("Error emitting event to sink", {
+					error,
+					sink,
+					data
+				});
+			}
+		});
+	}
+};
+//#endregion
+//#region src/sinks/BatchSink.ts
+const STORAGE_KEY$1 = "_ubi_batch_retry_";
+const TRACK_EVENT_PATH = "/api/v1/ubi/track-event";
+const MAX_PERSISTED_BATCHES = 10;
+const MAX_PERSISTED_AGE_MS = 864e5;
+/**
+* A sink that batches events, retries failures with exponential backoff,
+* and uses the Beacon API for reliable delivery on page unload.
+*/
+var BatchSink = class {
+	constructor(options) {
+		this.queue = [];
+		this.flushTimer = null;
+		this.pendingRetries = /* @__PURE__ */ new Map();
+		this.disposed = false;
+		const { endpointHost, flushSize = 30, flushIntervalMs = 1e3, maxRetries = 5, retryBaseDelayMs = 1e3, retryMaxDelayMs = 3e4, storage, logger } = options;
+		this.url = `${endpointHost.replace(/\/+$/, "")}${TRACK_EVENT_PATH}`;
+		this.storageKey = `${STORAGE_KEY$1}${endpointHost.replace(/[^a-zA-Z0-9]+/g, "-")}_`;
+		this.flushSize = flushSize;
+		this.flushIntervalMs = flushIntervalMs;
+		this.maxRetries = maxRetries;
+		this.retryBaseDelayMs = retryBaseDelayMs;
+		this.retryMaxDelayMs = retryMaxDelayMs;
+		this.storage = storage;
+		this.logger = logger;
+		this.boundOnVisibilityChange = this.onVisibilityChange.bind(this);
+		this.boundOnPageHide = this.onPageHide.bind(this);
+		this.start();
+		this.drainStoredRetries();
+	}
+	/**
+	* Add an event to the batch queue. Triggers a flush if the queue reaches flushSize.
+	*/
+	emit(event) {
+		if (this.disposed) return;
+		this.queue.push(event);
+		if (this.queue.length >= this.flushSize) this.flush();
+	}
+	/**
+	* Flush the current queue immediately via fetch.
+	* Returns a promise that resolves when the batch is sent (or scheduled for retry).
+	*/
+	flush() {
+		if (this.queue.length === 0) return Promise.resolve();
+		const batch = this.queue;
+		this.queue = [];
+		return this.sendBatch(batch, 0);
+	}
+	/**
+	* Start the flush timer and unload listeners.
+	*/
+	start() {
+		if (this.flushTimer) return;
+		this.flushTimer = setInterval(() => {
+			this.flush();
+		}, this.flushIntervalMs);
+		if (typeof document !== "undefined") document.addEventListener("visibilitychange", this.boundOnVisibilityChange);
+		if (typeof window !== "undefined") window.addEventListener("pagehide", this.boundOnPageHide);
+	}
+	/**
+	* Stop the flush timer, flush remaining events, and clean up.
+	*/
+	dispose() {
+		this.disposed = true;
+		if (this.flushTimer) {
+			clearInterval(this.flushTimer);
+			this.flushTimer = null;
+		}
+		this.persistPendingRetries();
+		if (typeof document !== "undefined") document.removeEventListener("visibilitychange", this.boundOnVisibilityChange);
+		if (typeof window !== "undefined") window.removeEventListener("pagehide", this.boundOnPageHide);
+		if (this.queue.length > 0) {
+			this.sendViaBeacon(this.queue);
+			this.queue = [];
+		}
+	}
+	/** Visible for testing - returns the current queue length */
+	get pendingCount() {
+		return this.queue.length;
+	}
+	onVisibilityChange() {
+		if (typeof document === "undefined") return;
+		if (document.visibilityState === "hidden") {
+			this.flushViaBeacon();
+			this.persistPendingRetries();
+		} else if (document.visibilityState === "visible") this.drainStoredRetries();
+	}
+	onPageHide(event) {
+		this.flushViaBeacon();
+		if (!event.persisted) this.persistPendingRetries();
+	}
+	/**
+	* Clear and persist any in-flight retry batches so a page discard or unload
+	* does not lose them. Empties the map, so it is safe to call more than once.
+	*/
+	persistPendingRetries() {
+		for (const [timer, batch] of this.pendingRetries) {
+			clearTimeout(timer);
+			this.persistForRetry(batch.events, batch.attempt);
+		}
+		this.pendingRetries.clear();
+	}
+	/**
+	* Flush all queued events using the Beacon API (reliable on page unload).
+	*/
+	flushViaBeacon() {
+		if (this.queue.length === 0) return;
+		const batch = this.queue;
+		this.queue = [];
+		this.sendViaBeacon(batch);
+	}
+	sendViaBeacon(events) {
+		if (typeof navigator !== "undefined" && typeof navigator.sendBeacon === "function") try {
+			const blob = new Blob([JSON.stringify({ events })], { type: "application/json" });
+			if (navigator.sendBeacon(this.url, blob)) {
+				var _this$logger;
+				(_this$logger = this.logger) === null || _this$logger === void 0 || _this$logger.info(`ubi: queued ${events.length} event(s) via beacon to ${this.url}`);
+				return;
+			}
+		} catch (e) {
+			var _this$logger2;
+			(_this$logger2 = this.logger) === null || _this$logger2 === void 0 || _this$logger2.error("Beacon API failed: ", e);
+		}
+		this.sendViaKeepaliveFetch(events);
+	}
+	/**
+	* Fallback delivery on unload when the beacon is unavailable or refused.
+	* Persists the batch for the next page load if the fetch fails.
+	*/
+	sendViaKeepaliveFetch(events) {
+		try {
+			fetch(this.url, {
+				method: "POST",
+				headers: { "Content-Type": "application/json" },
+				body: JSON.stringify({ events }),
+				keepalive: true
+			}).then((response) => {
+				if (!response.ok) this.persistForRetry(events, 0);
+			}).catch(() => {
+				this.persistForRetry(events, 0);
+			});
+		} catch (e) {
+			var _this$logger3;
+			(_this$logger3 = this.logger) === null || _this$logger3 === void 0 || _this$logger3.error("Keepalive fetch failed: ", e);
+			this.persistForRetry(events, 0);
+		}
+	}
+	async sendBatch(events, attempt) {
+		try {
+			const response = await fetch(this.url, {
+				method: "POST",
+				headers: { "Content-Type": "application/json" },
+				body: JSON.stringify({ events })
+			});
+			if (!response.ok) {
+				if (this.isRetryable(response.status)) this.scheduleRetry(events, attempt);
+				else {
+					var _this$logger4;
+					(_this$logger4 = this.logger) === null || _this$logger4 === void 0 || _this$logger4.error(`Batch send failed with status ${response.status}, not retrying`);
+				}
+			} else {
+				var _this$logger5;
+				(_this$logger5 = this.logger) === null || _this$logger5 === void 0 || _this$logger5.info(`ubi: sent ${events.length} event(s) to ${this.url} (${response.status})`);
+			}
+		} catch (_e) {
+			this.scheduleRetry(events, attempt);
+		}
+	}
+	isRetryable(status) {
+		return status >= 500 || status === 429;
+	}
+	scheduleRetry(events, attempt) {
+		var _this$logger7;
+		if (this.disposed) {
+			this.persistForRetry(events, attempt);
+			return;
+		}
+		if (attempt >= this.maxRetries) {
+			var _this$logger6;
+			(_this$logger6 = this.logger) === null || _this$logger6 === void 0 || _this$logger6.error(`Batch send failed after ${this.maxRetries} attempts, discarding ${events.length} events`);
+			return;
+		}
+		const delay = this.calculateBackoff(attempt);
+		(_this$logger7 = this.logger) === null || _this$logger7 === void 0 || _this$logger7.warn(`Retrying batch (attempt ${attempt + 1}/${this.maxRetries}) in ${delay}ms`);
+		const timer = setTimeout(() => {
+			this.pendingRetries.delete(timer);
+			this.sendBatch(events, attempt + 1);
+		}, delay);
+		this.pendingRetries.set(timer, {
+			events,
+			attempt
+		});
+	}
+	calculateBackoff(attempt) {
+		const exponentialDelay = this.retryBaseDelayMs * 2 ** attempt;
+		const cappedDelay = Math.min(exponentialDelay, this.retryMaxDelayMs);
+		return Math.random() * cappedDelay;
+	}
+	persistForRetry(events, attempt) {
+		if (!this.storage) return;
+		try {
+			const stored = this.loadStoredRetries();
+			stored.push({
+				events,
+				attempt,
+				ts: Date.now()
+			});
+			const bounded = stored.slice(-10);
+			if (bounded.length < stored.length) {
+				var _this$logger8;
+				(_this$logger8 = this.logger) === null || _this$logger8 === void 0 || _this$logger8.warn(`ubi: dropped ${stored.length - bounded.length} oldest persisted retry batch(es) (cap ${MAX_PERSISTED_BATCHES})`);
+			}
+			this.storage.setItem(this.storageKey, JSON.stringify(bounded));
+		} catch (e) {
+			var _this$logger9;
+			(_this$logger9 = this.logger) === null || _this$logger9 === void 0 || _this$logger9.error("Failed to persist retry queue: ", e);
+		}
+	}
+	loadStoredRetries() {
+		if (!this.storage) return [];
+		try {
+			const data = this.storage.getItem(this.storageKey);
+			const parsed = data ? JSON.parse(data) : [];
+			if (!Array.isArray(parsed)) return [];
+			return parsed.filter((batch) => Array.isArray(batch === null || batch === void 0 ? void 0 : batch.events) && typeof (batch === null || batch === void 0 ? void 0 : batch.ts) === "number" && Date.now() - batch.ts <= MAX_PERSISTED_AGE_MS);
+		} catch {
+			return [];
+		}
+	}
+	drainStoredRetries() {
+		var _this$logger10;
+		if (!this.storage) return;
+		const batches = this.loadStoredRetries();
+		if (batches.length === 0) return;
+		this.storage.removeItem(this.storageKey);
+		(_this$logger10 = this.logger) === null || _this$logger10 === void 0 || _this$logger10.info(`ubi: resuming ${batches.length} persisted retry batch(es)`);
+		for (const batch of batches) this.sendBatch(batch.events, batch.attempt);
+	}
+};
+//#endregion
+//#region src/sinks/ConsoleSink.ts
+/**
+* Logs every event to the browser console. The development default: used
+* automatically when no `endpointHost` is configured and no sink has been
+* added, so events are visible without anything leaving the page. With an
+* endpoint configured, delivery goes through `BatchSink` instead.
+*/
+var ConsoleSink = class {
+	emit(event) {
+		console.log(event);
+	}
+};
+//#endregion
+//#region src/attribution/AttributionStore.ts
+const STORAGE_KEY = "_ubi_attribution_";
+const MAX_AGE_MS = 864e5;
+const MAX_ENTRIES = 50;
+/**
+* Object-keyed attribution store: `objectId -> { queryId, ordinal, query }`.
+*
+* Written by `Tracker.trackResultClick` and read by `Tracker.trackResultEvent`
+* (and `getResultAttribution`), so a conversion on a later page - including
+* after a full document navigation - resolves the query that produced the
+* clicked result without the integrator threading `query_id` by hand.
+*
+* Records go to BOTH sessionStorage and localStorage: sessionStorage covers
+* same-tab navigation, and the localStorage copy covers a result opened in a
+* new tab (which does not inherit sessionStorage). Resolution is scoped to the
+* session that registered the record, so the shared localStorage copy can
+* never re-attribute a later visit in a different session.
+*
+* The store performs no storage IO at construction; it reads on `get` and
+* writes on `register` only.
+*/
+var AttributionStore = class {
+	constructor(options) {
+		this.options = options;
+	}
+	/** Records the attribution for a clicked result. */
+	register(objectId, record) {
+		const stored = {
+			queryId: record.queryId,
+			ordinal: record.ordinal,
+			query: record.query,
+			sessionId: this.options.sessionId(),
+			ts: Date.now()
+		};
+		for (const storage of [this.options.sessionStorage, this.options.localStorage]) {
+			const map = this.pruneStale(this.load(storage));
+			if (!(objectId in map)) this.enforceCap(map);
+			map[objectId] = stored;
+			this.save(storage, map);
+		}
+	}
+	/**
+	* Returns the attribution recorded for an object in the current session, or
+	* undefined. Stale entries (other session, over age) are pruned on read.
+	*/
+	get(objectId) {
+		for (const storage of [this.options.sessionStorage, this.options.localStorage]) {
+			const map = this.load(storage);
+			const stored = map[objectId];
+			if (!stored) continue;
+			if (this.isStale(stored)) {
+				delete map[objectId];
+				this.save(storage, map);
+				continue;
+			}
+			const record = { queryId: stored.queryId };
+			if (stored.ordinal !== void 0) record.ordinal = stored.ordinal;
+			if (stored.query !== void 0) record.query = stored.query;
+			return record;
+		}
+	}
+	isStale(stored) {
+		return typeof stored.queryId !== "string" || stored.sessionId !== this.options.sessionId() || Date.now() - stored.ts > MAX_AGE_MS;
+	}
+	/** Drops stale entries (other session, over age, malformed). */
+	pruneStale(map) {
+		for (const key of Object.keys(map)) {
+			var _map$key;
+			if (typeof ((_map$key = map[key]) === null || _map$key === void 0 ? void 0 : _map$key.ts) !== "number" || this.isStale(map[key])) delete map[key];
+		}
+		return map;
+	}
+	/** Makes room for one new entry, evicting the oldest beyond the cap. */
+	enforceCap(map) {
+		const keys = Object.keys(map);
+		if (keys.length >= MAX_ENTRIES) keys.sort((a, b) => map[a].ts - map[b].ts).slice(0, keys.length - MAX_ENTRIES + 1).forEach((key) => {
+			delete map[key];
+		});
+	}
+	load(storage) {
+		try {
+			const raw = storage.getItem(STORAGE_KEY);
+			if (!raw) return {};
+			const parsed = JSON.parse(raw);
+			if (typeof parsed !== "object" || parsed === null) {
+				storage.removeItem(STORAGE_KEY);
+				return {};
+			}
+			return parsed;
+		} catch (e) {
+			this.logError("Error reading the attribution store: ", e);
+			try {
+				storage.removeItem(STORAGE_KEY);
+			} catch {}
+			return {};
+		}
+	}
+	save(storage, map) {
+		try {
+			storage.setItem(STORAGE_KEY, JSON.stringify(map));
+		} catch (e) {
+			this.logError("Error writing the attribution store: ", e);
+		}
+	}
+	logError(message, e) {
+		var _this$options$logger, _this$options;
+		(_this$options$logger = (_this$options = this.options).logger) === null || _this$options$logger === void 0 || (_this$options$logger = _this$options$logger.call(_this$options)) === null || _this$options$logger === void 0 || _this$options$logger.error(message, e);
+	}
+};
+//#endregion
+//#region src/dispatcher.ts
+const TRACKER_VERSION = "1.0.0-bootstrap.0";
+/**
+* Enriches events and dispatches to the sink
+*/
+var DefaultDispatcher = class {
+	constructor(enrichers, sink, logger) {
+		this.logger = logger;
+		this.sink = sink;
+		this.enrichers = enrichers;
+	}
+	dispatch(event) {
+		var _this$logger2;
+		if (!event.timestamp) event.timestamp = (/* @__PURE__ */ new Date()).toISOString();
+		if (!event.event_attributes) event.event_attributes = {};
+		if (!event.event_attributes.event_id) event.event_attributes.event_id = (0, ulidx.ulid)();
+		if (!event.event_attributes.tracker) event.event_attributes.tracker = { version: TRACKER_VERSION };
+		this.enrichers.forEach((enricher) => {
+			try {
+				enricher.enrich(event);
+			} catch (e) {
+				var _this$logger;
+				(_this$logger = this.logger) === null || _this$logger === void 0 || _this$logger.error("Error enriching event: ", e);
+			}
+		});
+		(_this$logger2 = this.logger) === null || _this$logger2 === void 0 || _this$logger2.debug("ubi: dispatching event", event);
+		try {
+			this.sink.emit(event);
+		} catch (e) {
+			var _this$logger3;
+			(_this$logger3 = this.logger) === null || _this$logger3 === void 0 || _this$logger3.error("Error emitting event to sink: ", e);
+		}
+	}
+};
+//#endregion
+//#region src/enrichers/BrowserEnricher.ts
+/**
+* Enriches the event with information about the browser:
+* - user_agent
+* - language
+* - screen resolution
+* - webdriver (only when set: the one cheap automation signal, so analysis
+*   can filter bot and headless traffic that would distort CTR)
+*/
+var BrowserEnricher = class {
+	enrich(event) {
+		if (!event.event_attributes) event.event_attributes = {};
+		const browser = {
+			...event.event_attributes.browser,
+			user_agent: navigator.userAgent,
+			language: navigator.language,
+			resolution: {
+				width: screen.width,
+				height: screen.height
+			}
+		};
+		if (navigator.webdriver) browser.webdriver = true;
+		event.event_attributes.browser = browser;
+	}
+};
+//#endregion
+//#region src/enrichers/ClientIdEnricher.ts
+/**
+* Enriches the event with
+* - client_id
+*/
+var ClientIdEnricher = class {
+	constructor(clientIdProvider) {
+		this.clientIdProvider = clientIdProvider;
+	}
+	enrich(event) {
+		if (!event.client_id) event.client_id = this.clientIdProvider();
+	}
+};
+//#endregion
+//#region src/enrichers/OptionsEnricher.ts
+/**
+* Enriches the event with configured values:
+* - application
+* - user_id (late-bound via the getter)
+* - siteId (stamped as `site_id` on the event)
+*/
+var OptionsEnricher = class {
+	constructor(values) {
+		this.values = values;
+	}
+	enrich(data) {
+		if (!data.application) data.application = this.values.application;
+		const userId = this.values.userId();
+		if (!data.user_id && userId) data.user_id = userId;
+		if (!data.site_id && this.values.siteId) data.site_id = this.values.siteId;
+	}
+};
+//#endregion
+//#region src/enrichers/PageEnricher.ts
+/**
+* Enriches the event with information about the page:
+* - url
+* - title
+* - referrer
+*/
+var PageEnricher = class {
+	enrich(event) {
+		if (!event.event_attributes) event.event_attributes = {};
+		event.event_attributes.page = {
+			...event.event_attributes.page,
+			url: location.href,
+			title: document.title,
+			referrer: document.referrer || ""
+		};
+	}
+};
+//#endregion
+//#region src/enrichers/SessionEnricher.ts
+/**
+* Enriches the event with
+* - session_id
+*
+* Optionally calls onActivity to update the session's last activity timestamp.
+*/
+var SessionEnricher = class {
+	constructor(sessionIdProvider, onActivity) {
+		this.sessionIdProvider = sessionIdProvider;
+		this.onActivity = onActivity;
+	}
+	enrich(event) {
+		var _this$onActivity;
+		if (!event.session_id) event.session_id = this.sessionIdProvider();
+		(_this$onActivity = this.onActivity) === null || _this$onActivity === void 0 || _this$onActivity.call(this);
+	}
+};
+//#endregion
+//#region src/storage/MemoryStorage.ts
+/**
+* An in-memory {@link Storage} implementation used when no real Web Storage is
+* available - most importantly under server-side rendering (no `window`), where
+* touching `localStorage`/`document.cookie` would throw. It provides page-scoped
+* state with no cross-page persistence, so the tracker constructs and runs
+* inertly on the server and starts persisting once it hydrates in the browser.
+*/
+var MemoryStorage = class {
+	constructor() {
+		this.store = /* @__PURE__ */ new Map();
+	}
+	get length() {
+		return this.store.size;
+	}
+	clear() {
+		this.store.clear();
+	}
+	getItem(key) {
+		var _this$store$get;
+		return (_this$store$get = this.store.get(key)) !== null && _this$store$get !== void 0 ? _this$store$get : null;
+	}
+	key(index) {
+		var _Array$from$index;
+		return (_Array$from$index = Array.from(this.store.keys())[index]) !== null && _Array$from$index !== void 0 ? _Array$from$index : null;
+	}
+	removeItem(key) {
+		this.store.delete(key);
+	}
+	setItem(key, value) {
+		this.store.set(key, String(value));
+	}
+};
+//#endregion
+//#region src/storage/ClientId.ts
+const CLIENT_ID_KEY = "_ubi_client_id_";
+/**
+* Gets or creates a stable anonymous client ID persisted in localStorage.
+* This ID survives across sessions and is used to identify the device/browser.
+* A failing storage read or write is logged and a freshly generated id is
+* still returned, so tracking continues (per page) without persistence.
+*/
+function getOrCreateClientId(storage, logger) {
+	let clientId = null;
+	try {
+		clientId = storage.getItem(CLIENT_ID_KEY);
+	} catch (e) {
+		logger === null || logger === void 0 || logger.error("Error reading the client id: ", e);
+	}
+	if (!clientId) {
+		clientId = (0, ulidx.ulid)();
+		try {
+			storage.setItem(CLIENT_ID_KEY, clientId);
+		} catch (e) {
+			logger === null || logger === void 0 || logger.error("Error persisting the client id: ", e);
+		}
+	}
+	return clientId;
+}
+//#endregion
+//#region src/storage/SessionManager.ts
+const SESSION_KEY = "_ubi_session_";
+const MAX_CLOCK_SKEW_MS = 3e5;
+const THIRTY_MINUTES = 18e5;
+const TWENTY_FOUR_HOURS = 864e5;
+/**
+* Manages session IDs with inactivity timeout and maximum duration.
+*/
+var SessionManager = class {
+	constructor(options) {
+		var _options$inactivityTi, _options$maxSessionDu;
+		this.storage = options.storage;
+		this.inactivityTimeoutMs = (_options$inactivityTi = options.inactivityTimeoutMs) !== null && _options$inactivityTi !== void 0 ? _options$inactivityTi : THIRTY_MINUTES;
+		this.maxSessionDurationMs = (_options$maxSessionDu = options.maxSessionDurationMs) !== null && _options$maxSessionDu !== void 0 ? _options$maxSessionDu : TWENTY_FOUR_HOURS;
+		this.logger = options.logger;
+		this.session = this.loadOrCreate();
+	}
+	get sessionId() {
+		this.syncFromStorage();
+		if (this.isExpired()) this.rotate();
+		return this.session.id;
+	}
+	syncFromStorage() {
+		try {
+			const stored = this.storage.getItem(SESSION_KEY);
+			if (!stored) return;
+			const data = JSON.parse(stored);
+			if (!this.isUsable(data, Date.now())) return;
+			if (data.id !== this.session.id || data.lastActivity > this.session.lastActivity) this.session = data;
+		} catch {}
+	}
+	/** Update the last activity timestamp. Call on every event. */
+	touch() {
+		this.session.lastActivity = Date.now();
+		this.persist();
+	}
+	/**
+	* Marks user activity that is not an event: reconciles with storage,
+	* rotates if genuinely expired, then refreshes the activity timestamp.
+	* Called from `Tracker.start()` so that on a classic multi-page site every
+	* page load counts as a hit - the GA-style 30-minute convention - instead
+	* of only dispatched events keeping the session alive. Without it, reading
+	* a product page for 31 minutes rotates the session and drops attribution.
+	*/
+	activity() {
+		this.sessionId;
+		this.touch();
+	}
+	/** True when stored session data is well-formed and temporally sane. */
+	isUsable(data, now) {
+		return typeof data.id === "string" && data.id.length > 0 && Number.isFinite(data.createdAt) && Number.isFinite(data.lastActivity) && data.createdAt <= now + MAX_CLOCK_SKEW_MS && data.lastActivity <= now + MAX_CLOCK_SKEW_MS;
+	}
+	isExpired() {
+		const now = Date.now();
+		const inactivityExpired = now - this.session.lastActivity > this.inactivityTimeoutMs;
+		const maxDurationExpired = now - this.session.createdAt > this.maxSessionDurationMs;
+		return inactivityExpired || maxDurationExpired;
+	}
+	rotate() {
+		this.session = this.createSession();
+		this.persist();
+	}
+	loadOrCreate() {
+		try {
+			const stored = this.storage.getItem(SESSION_KEY);
+			if (stored) {
+				const data = JSON.parse(stored);
+				if (this.isUsable(data, Date.now())) return data;
+			}
+		} catch {}
+		const session = this.createSession();
+		this.persist(session);
+		return session;
+	}
+	createSession() {
+		const now = Date.now();
+		return {
+			id: (0, ulidx.ulid)(),
+			createdAt: now,
+			lastActivity: now
+		};
+	}
+	persist(session) {
+		try {
+			this.storage.setItem(SESSION_KEY, JSON.stringify(session !== null && session !== void 0 ? session : this.session));
+		} catch (e) {
+			var _this$logger;
+			(_this$logger = this.logger) === null || _this$logger === void 0 || _this$logger.error("Error persisting the session: ", e);
+		}
+	}
+};
+//#endregion
+//#region src/storage/index.ts
+function tryGetStorage(storageName) {
+	if (typeof window === "undefined") return;
+	try {
+		if (!(storageName in window)) return;
+		const storage = window[storageName];
+		if (!storage) return;
+		const uid = `_ubi_probe_${Date.now()}`;
+		storage.setItem(uid, uid);
+		const result = storage.getItem(uid) === uid;
+		storage.removeItem(uid);
+		return result ? storage : void 0;
+	} catch (_exception) {
+		return;
+	}
+}
+const initLocalStorage = () => {
+	var _tryGetStorage;
+	return (_tryGetStorage = tryGetStorage("localStorage")) !== null && _tryGetStorage !== void 0 ? _tryGetStorage : new MemoryStorage();
+};
+const initSessionStorage = () => {
+	var _tryGetStorage2;
+	return (_tryGetStorage2 = tryGetStorage("sessionStorage")) !== null && _tryGetStorage2 !== void 0 ? _tryGetStorage2 : new MemoryStorage();
+};
+//#endregion
+//#region src/tracker.ts
+const PRE_START_BUFFER_LIMIT = 100;
+const IMPRESSION_DEDUP_LIMIT = 1e3;
+/**
+* The entry point of `@releval/tracker`: collects User Behavior Insights
+* events - searches, result impressions, result clicks and the conversions
+* that follow - in the canonical joinable shape
+* (`query_id` + `object_id` + `ordinal`) and delivers them to a Releval
+* deployment's track-event API.
+*
+* Events flow through a small pipeline: the high-level `track*` methods (or
+* the declarative collectors) build canonical events, enrichers stamp
+* context (application, session, client id, page, browser), and sinks
+* deliver - batched with retry to the endpoint, or to the console in
+* development. Nothing is delivered before {@link Tracker.start}; earlier
+* dispatches are buffered and replayed.
+*
+* @example
+* ```ts
+* const tracker = new Tracker({
+*   application: "primary-search",
+*   siteId: "YOUR_SITE_ID",
+*   endpointHost: "https://releval.example.com",
+* });
+* tracker.start();
+*
+* tracker.trackSearch({ query, queryId }); // ids come from your backend
+* tracker.trackResultClick({ objectId, ordinal, queryId });
+* tracker.trackResultEvent({ actionName: "add_to_cart", objectId });
+* ```
+*
+* The full integration flow is documented at
+* https://releval.co/docs/user-behavior-insights/browser-tracker
+*/
+var Tracker = class {
+	constructor(options) {
+		var _options$logger;
+		this.hasEverStarted = false;
+		this.detaches = /* @__PURE__ */ new Map();
+		this.hasWarnedMissingQueryId = false;
+		this.hasWarnedUnattributedResult = false;
+		this.hasWarnedInvalidOrdinal = false;
+		this.preStartBuffer = [];
+		this.hasWarnedPreStartOverflow = false;
+		this.seenImpressions = /* @__PURE__ */ new Set();
+		this.extraSinks = /* @__PURE__ */ new Set();
+		this.options = options;
+		this.collectors = /* @__PURE__ */ new Set();
+		this.started = false;
+		this.logger = safeLogger((_options$logger = options.logger) !== null && _options$logger !== void 0 ? _options$logger : new ConsoleLogger({ verbose: options.debug }));
+		this._sessionManager = new SessionManager({
+			storage: this.localStorage,
+			inactivityTimeoutMs: options.sessionInactivityTimeoutMs,
+			maxSessionDurationMs: options.maxSessionDurationMs,
+			logger: this.logger
+		});
+		this._userId = options.userId;
+		this.enrichers = /* @__PURE__ */ new Set([
+			new OptionsEnricher({
+				application: options.application,
+				siteId: options.siteId,
+				userId: () => this._userId
+			}),
+			new BrowserEnricher(),
+			new PageEnricher(),
+			new SessionEnricher(() => this.sessionId, () => this._sessionManager.touch()),
+			new ClientIdEnricher(() => this.clientId)
+		]);
+	}
+	/**
+	* The tracker's local storage (with fallbacks when Web Storage is
+	* unavailable). Internal: collectors and stores receive it via options.
+	*/
+	get localStorage() {
+		if (!this._localStorage) this._localStorage = initLocalStorage();
+		return this._localStorage;
+	}
+	/**
+	* The tracker's session storage (with fallbacks when Web Storage is
+	* unavailable). Internal: collectors and stores receive it via options.
+	*/
+	get sessionStorage() {
+		if (!this._sessionStorage) this._sessionStorage = initSessionStorage();
+		return this._sessionStorage;
+	}
+	/**
+	* Gets the session identifier. Automatically rotates on inactivity or max duration.
+	*/
+	get sessionId() {
+		return this._sessionManager.sessionId;
+	}
+	/**
+	* Gets the stable anonymous client/device ID. Persisted in localStorage across sessions.
+	*/
+	get clientId() {
+		if (!this._clientId) this._clientId = getOrCreateClientId(this.localStorage, this.logger);
+		return this._clientId;
+	}
+	/**
+	* Sets (or clears, with `undefined`) the user id stamped on events - for a
+	* login or logout that happens without a page reload. Applies to events
+	* dispatched after the call; events already queued or persisted for retry
+	* keep the identity they were stamped with. An explicit `user_id` on a
+	* dispatched event still wins. Callable before `start()`. Does not rotate
+	* the session or touch the client id. The value must be an opaque,
+	* pseudonymous identifier - never an email address or name.
+	*/
+	setUserId(userId) {
+		this._userId = userId;
+	}
+	/**
+	* The object-keyed attribution store, created on first use so construction
+	* performs no storage IO for it.
+	*/
+	get attribution() {
+		if (!this._attribution) this._attribution = new AttributionStore({
+			localStorage: this.localStorage,
+			sessionStorage: this.sessionStorage,
+			sessionId: () => this.sessionId,
+			logger: () => this.logger
+		});
+		return this._attribution;
+	}
+	/**
+	* Returns the attribution recorded by {@link Tracker.trackResultClick} for
+	* an object in the current session, or undefined. Use it to build custom
+	* conversion payloads (e.g. a checkout page resolving several line items).
+	*/
+	getResultAttribution(objectId) {
+		try {
+			return this.attribution.get(objectId);
+		} catch (e) {
+			this.logger.error("Error reading result attribution: ", e);
+			return;
+		}
+	}
+	/**
+	* Reports that a search ran, with the server-issued `query_id`. Call this
+	* after your search backend returns results.
+	*
+	* Dispatches a `search` event (`message_type: "QUERY"`) carrying `query_id`
+	* and `user_query`. Without it a query that gets no impression and no click
+	* leaves no event at all, so abandonment and reformulation cannot be
+	* analysed downstream.
+	*/
+	trackSearch(options) {
+		try {
+			const { query, queryId, ...extras } = options;
+			if (!queryId && !this.hasWarnedMissingQueryId) {
+				this.hasWarnedMissingQueryId = true;
+				this.logger.warn("Tracker.trackSearch: called without a queryId. The search event is still emitted but result clicks and impressions cannot be attributed back to this query. Pass the query_id issued by your search backend (Releval track-query): tracker.trackSearch({ query, queryId }).");
+			}
+			const event = {
+				action_name: "search",
+				message_type: "QUERY",
+				user_query: query
+			};
+			if (queryId) event.query_id = queryId;
+			if (Object.keys(extras).length > 0) event.event_attributes = { ...extras };
+			this.dispatch(event);
+		} catch (e) {
+			this.logger.error("Error tracking search: ", e);
+		}
+	}
+	/**
+	* Dispatches a UBI event for a search result in the canonical shape
+	* (`query_id`, `event_attributes.object.object_id`, `event_attributes.position.ordinal`),
+	* so callers never hand-build it. Prefer {@link Tracker.trackResultClick} /
+	* {@link Tracker.trackResultImpression}; use this directly for conversions
+	* (e.g. `actionName: "add_to_cart"` or `"purchase"`), where `queryId` and
+	* `ordinal` may be omitted and are resolved from the attribution recorded
+	* when the result was clicked - including on a later page. When `queryId`
+	* IS supplied and matches the recorded click, a missing `ordinal`/`query`
+	* is still borrowed from it, so the row shape does not depend on which
+	* page supplied the id.
+	*/
+	trackResultEvent(options) {
+		try {
+			const { actionName, objectId, objectIdField, ordinal: suppliedOrdinal, queryId: suppliedQueryId, query: suppliedQuery, ...extras } = options;
+			let ordinal = suppliedOrdinal;
+			let queryId = suppliedQueryId;
+			let query = suppliedQuery;
+			if (queryId === void 0 || ordinal === void 0 || query === void 0) {
+				const attribution = this.attribution.get(objectId);
+				if (attribution) {
+					if (queryId === void 0) {
+						var _ordinal, _query;
+						queryId = attribution.queryId;
+						ordinal = (_ordinal = ordinal) !== null && _ordinal !== void 0 ? _ordinal : attribution.ordinal;
+						query = (_query = query) !== null && _query !== void 0 ? _query : attribution.query;
+					} else if (attribution.queryId === queryId) {
+						var _ordinal2, _query2;
+						ordinal = (_ordinal2 = ordinal) !== null && _ordinal2 !== void 0 ? _ordinal2 : attribution.ordinal;
+						query = (_query2 = query) !== null && _query2 !== void 0 ? _query2 : attribution.query;
+					}
+				}
+			}
+			if (ordinal !== void 0 && !isValidOrdinal(ordinal)) {
+				if (!this.hasWarnedInvalidOrdinal) {
+					this.hasWarnedInvalidOrdinal = true;
+					this.logger.warn(`Tracker: ignoring invalid ordinal ${String(ordinal)} for "${objectId}" - an ordinal is a positive integer: (page - 1) * pageSize + positionOnPage.`);
+				}
+				ordinal = void 0;
+			}
+			if (!queryId && !this.hasWarnedUnattributedResult) {
+				this.hasWarnedUnattributedResult = true;
+				this.logger.warn(`Tracker.trackResultEvent: no queryId was supplied and no attribution is recorded for "${objectId}" in this session, so the event is sent unattributed. Either pass queryId explicitly or report the originating click with tracker.trackResultClick so conversions resolve automatically.`);
+			}
+			const object = { object_id: objectId };
+			if (objectIdField) object.object_id_field = objectIdField;
+			const event = {
+				action_name: actionName,
+				event_attributes: {
+					...extras,
+					object
+				}
+			};
+			if (typeof ordinal === "number") event.event_attributes.position = { ordinal };
+			if (queryId) event.query_id = queryId;
+			if (query) event.user_query = query;
+			this.dispatch(event);
+		} catch (e) {
+			this.logger.error("Error tracking result event: ", e);
+		}
+	}
+	/**
+	* Dispatches a `click` event for a clicked search result, attributed to
+	* `queryId` (required at the call site by design), and records the
+	* attribution for the object so later conversion events for it - on this
+	* page or a later one - resolve the originating query automatically.
+	*/
+	trackResultClick(options) {
+		try {
+			var _options$actionName;
+			const { objectId, ordinal, queryId, query } = options;
+			this.trackResultEvent({
+				...options,
+				actionName: (_options$actionName = options.actionName) !== null && _options$actionName !== void 0 ? _options$actionName : "click"
+			});
+			this.attribution.register(objectId, {
+				queryId,
+				ordinal,
+				query
+			});
+		} catch (e) {
+			this.logger.error("Error tracking result click: ", e);
+		}
+	}
+	/**
+	* Dispatches an `impression` event for each result that became visible,
+	* attributed to `queryId`. Emits one canonical event per item so impressions
+	* join to clicks on `object_id`/`ordinal`.
+	*
+	* Each `(queryId, objectId)` pair is reported ONCE per Tracker instance:
+	* re-renders, virtualized-list remounts and re-discovered elements do not
+	* inflate the impression count (the CTR denominator), while a new `queryId`
+	* re-fires for results returned by consecutive searches. A full page load
+	* builds a fresh Tracker and so starts fresh; when revisits matter,
+	* deduplicate downstream on distinct `(query_id, object_id)`.
+	*/
+	trackResultImpression(options) {
+		try {
+			for (const item of options.items) {
+				const key = `${options.queryId}\u0000${item.objectId}`;
+				if (this.seenImpressions.has(key)) continue;
+				if (this.seenImpressions.size >= IMPRESSION_DEDUP_LIMIT) {
+					const oldest = this.seenImpressions.values().next().value;
+					if (oldest !== void 0) this.seenImpressions.delete(oldest);
+				}
+				this.seenImpressions.add(key);
+				this.trackResultEvent({
+					...item,
+					actionName: "impression",
+					queryId: options.queryId,
+					query: options.query
+				});
+			}
+		} catch (e) {
+			this.logger.error("Error tracking result impression: ", e);
+		}
+	}
+	/**
+	* Adds an enricher that runs on every event before emission (e.g. stamping
+	* an A/B variant, store or locale - the split key for any comparison).
+	* Returns a disposer that removes it again.
+	*/
+	addEnricher(enricher) {
+		try {
+			this.enrichers.add(enricher);
+			return () => {
+				this.enrichers.delete(enricher);
+			};
+		} catch (e) {
+			this.logger.error("Error adding enricher: ", e);
+			return () => {};
+		}
+	}
+	/**
+	* Registers a collector so it attaches at start() (or immediately when the
+	* tracker is already started), and returns a function that detaches and
+	* unregisters it again.
+	*/
+	registerCollector(collector) {
+		try {
+			if (!this.collectors.has(collector)) {
+				if (this.started) try {
+					this.detaches.set(collector, collector.attach(this.dispatcher));
+				} catch (e) {
+					this.logger.error("Error attaching collector: ", e);
+				}
+				this.collectors.add(collector);
+			}
+		} catch (e) {
+			this.logger.error("Error adding collector: ", e);
+		}
+		return () => {
+			try {
+				const detach = this.detaches.get(collector);
+				this.detaches.delete(collector);
+				this.collectors.delete(collector);
+				detach === null || detach === void 0 || detach();
+			} catch (e) {
+				this.logger.error("Error detaching collector: ", e);
+			}
+		};
+	}
+	/**
+	* Binds declarative result-click collection to the DOM: one delegated
+	* listener reports clicks on elements matching `selector` in the canonical
+	* joinable shape, reading `data-object-id` / `data-ordinal` from the result
+	* element and `data-query-id` from its nearest ancestor (or a custom
+	* `resolve`). A resolved `data-action-name` other than `click` (e.g.
+	* `add_to_cart`) is routed through {@link Tracker.trackResultEvent}, so its
+	* attribution can resolve from the recorded click.
+	*
+	* Use `ignore` for interactive descendants of a result (an add-to-cart
+	* button inside the card) so their clicks are not double-reported as result
+	* clicks.
+	*
+	* @returns a function that stops this collection again.
+	*/
+	trackResultClicks(options) {
+		try {
+			const collector = new ResultClickCollector(options, (resolved) => this.emitResolvedResultClick(resolved));
+			return this.registerCollector(collector);
+		} catch (e) {
+			this.logger.error("Error creating result click collector: ", e);
+			return () => {};
+		}
+	}
+	/** Routes a resolved declarative click through the high-level API. */
+	emitResolvedResultClick(resolved) {
+		const { actionName: resolvedAction, ...data } = resolved;
+		const actionName = resolvedAction !== null && resolvedAction !== void 0 ? resolvedAction : "click";
+		if (actionName === "click" && resolved.queryId && typeof resolved.ordinal === "number") {
+			this.trackResultClick({
+				...data,
+				objectId: resolved.objectId,
+				ordinal: resolved.ordinal,
+				queryId: resolved.queryId
+			});
+			return;
+		}
+		this.trackResultEvent({
+			...data,
+			actionName
+		});
+	}
+	/**
+	* Binds declarative result-impression collection to the DOM: each element
+	* matching `selector` emits one canonical `impression` event the first time
+	* it enters the viewport, attributed via the same data-attribute convention
+	* as {@link Tracker.trackResultClicks} (or a custom `resolve`). Elements
+	* added or re-rendered after `start()` are discovered automatically.
+	*
+	* @returns a function that stops this collection again.
+	*/
+	trackResultImpressions(options) {
+		try {
+			const collector = new ResultImpressionCollector(options, (items, queryId, query) => this.trackResultImpression({
+				items,
+				queryId,
+				query
+			}));
+			return this.registerCollector(collector);
+		} catch (e) {
+			this.logger.error("Error creating result impression collector: ", e);
+			return () => {};
+		}
+	}
+	/**
+	* Adds a sink that receives every emitted event (e.g. mirroring into your
+	* own analytics, or a test spy). Returns a disposer that removes it again.
+	*/
+	addSink(sink) {
+		try {
+			this.extraSinks.add(sink);
+			if (this.started && this.sink) this.sink.add(sink);
+			return () => {
+				var _this$sink;
+				this.extraSinks.delete(sink);
+				(_this$sink = this.sink) === null || _this$sink === void 0 || _this$sink.delete(sink);
+			};
+		} catch (e) {
+			this.logger.error("Error adding sink: ", e);
+			return () => {};
+		}
+	}
+	/**
+	* starts the tracker and attaches all collectors.
+	*/
+	start() {
+		try {
+			if (this.started) return;
+			const { endpointHost, siteId } = this.options;
+			if (endpointHost && !siteId) this.logger.error("Tracker.start: endpointHost is set but siteId is missing. Every event will be dropped by the server. Set `siteId` to the public Site identifier issued by Releval.");
+			this._sessionManager.activity();
+			this.sink = this.buildSink();
+			this.dispatcher = new DefaultDispatcher(this.enrichers, this.sink, this.logger);
+			this.collectors.forEach((collector) => {
+				try {
+					this.detaches.set(collector, collector.attach(this.dispatcher));
+				} catch (e) {
+					this.logger.error("Error attaching collector: ", e);
+				}
+			});
+			this.started = true;
+			this.hasEverStarted = true;
+			if (this.preStartBuffer.length > 0) {
+				const buffered = this.preStartBuffer.splice(0);
+				this.logger.debug(`ubi: replaying ${buffered.length} event(s) dispatched before start()`);
+				for (const event of buffered) this.dispatcher.dispatch(event);
+			}
+		} catch (e) {
+			this.logger.error("Error starting tracker: ", e);
+		}
+	}
+	/**
+	* Builds the effective sink from the configured endpoint plus any user sinks.
+	* ConsoleSink is used only when there is neither an endpoint nor a user sink
+	* (the development default). The result is always an AggregateSink so its
+	* reference stays stable across addSink() calls.
+	*/
+	buildSink() {
+		const { endpointHost } = this.options;
+		const sinks = /* @__PURE__ */ new Set();
+		if (endpointHost) {
+			this.batchSink = new BatchSink({
+				endpointHost,
+				storage: this.localStorage,
+				logger: this.logger
+			});
+			sinks.add(this.batchSink);
+		}
+		for (const sink of this.extraSinks) sinks.add(sink);
+		if (sinks.size === 0) sinks.add(new ConsoleSink());
+		return new AggregateSink(sinks, this.logger);
+	}
+	/**
+	* Dispatches an event through the tracker pipeline (enrichers → sinks).
+	* Use this to send custom events that aren't captured by a collector.
+	* Safe to call before start(): the event is buffered (bounded), stamped
+	* with the timestamp of the moment it happened, and replayed once start()
+	* runs.
+	* @param event The event to dispatch.
+	*/
+	dispatch(event) {
+		if (!this.started || !this.dispatcher) {
+			if (this.hasEverStarted) {
+				this.logger.debug("ubi: tracker is stopped; event dropped", event);
+				return;
+			}
+			if (!event.timestamp) event.timestamp = (/* @__PURE__ */ new Date()).toISOString();
+			if (!event.user_id && this._userId) event.user_id = this._userId;
+			if (this.preStartBuffer.length >= PRE_START_BUFFER_LIMIT) {
+				if (!this.hasWarnedPreStartOverflow) {
+					this.hasWarnedPreStartOverflow = true;
+					this.logger.warn(`More than ${PRE_START_BUFFER_LIMIT} events were dispatched before start(); dropping the oldest. Call start() earlier.`);
+				}
+				this.preStartBuffer.shift();
+			}
+			this.preStartBuffer.push(event);
+			return;
+		}
+		this.dispatcher.dispatch(event);
+	}
+	/**
+	* Forces immediate delivery of any queued events, rather than waiting for the
+	* next batch interval. Useful before a critical action or a hard navigation.
+	* Resolves once the current batch has been sent (or scheduled for retry).
+	* A no-op that resolves immediately when there is no batching sink (events go
+	* to the console) or the tracker is stopped.
+	*/
+	flush() {
+		try {
+			var _this$batchSink$flush, _this$batchSink;
+			return (_this$batchSink$flush = (_this$batchSink = this.batchSink) === null || _this$batchSink === void 0 ? void 0 : _this$batchSink.flush()) !== null && _this$batchSink$flush !== void 0 ? _this$batchSink$flush : Promise.resolve();
+		} catch (e) {
+			this.logger.error("Error flushing events: ", e);
+			return Promise.resolve();
+		}
+	}
+	/**
+	* stops the tracker and detaches all collectors.
+	*/
+	stop() {
+		try {
+			if (!this.started) return;
+			this.detaches.forEach((detach) => {
+				try {
+					detach();
+				} catch (e) {
+					this.logger.error("Error detaching collector: ", e);
+				}
+			});
+			this.detaches.clear();
+			if (this.batchSink) this.batchSink.dispose();
+			this.sink = void 0;
+			this.batchSink = void 0;
+			this.dispatcher = void 0;
+			this.started = false;
+		} catch (e) {
+			this.logger.error("Error stopping tracker: ", e);
+		}
+	}
+};
+//#endregion
+Object.defineProperty(exports, "BatchSink", {
+	enumerable: true,
+	get: function() {
+		return BatchSink;
+	}
+});
+Object.defineProperty(exports, "ConsoleLogger", {
+	enumerable: true,
+	get: function() {
+		return ConsoleLogger;
+	}
+});
+Object.defineProperty(exports, "ConsoleSink", {
+	enumerable: true,
+	get: function() {
+		return ConsoleSink;
+	}
+});
+Object.defineProperty(exports, "Tracker", {
+	enumerable: true,
+	get: function() {
+		return Tracker;
+	}
+});
+Object.defineProperty(exports, "readResultData", {
+	enumerable: true,
+	get: function() {
+		return readResultData;
+	}
+});
+
+//# sourceMappingURL=tracker.cjs.map