@inspira-npm/events 0.0.0-stage → 0.1.0

package/dist/index.js

@@ -0,0 +1,579 @@
+import { n as SDK_VERSION, t as SDK_NAME } from "./version-Cqps0u2Y.js";
+// src/click-id.ts
+/** Query param que lleva el click id de un ad hasta el sitio destino. */
+const CLICK_ID_PARAM = "ipc";
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+function isClickId(value) {
+	return typeof value === "string" && UUID.test(value);
+}
+/**
+* Agrega `?ipc=<clickId>` a una URL conservando el resto de la query y el hash.
+* Las URLs relativas siguen siendo relativas. Si la URL no se puede parsear se devuelve igual.
+*/
+function withClickId(url, clickId, param = "ipc") {
+	const isAbsolute = /^[a-z][a-z\d+.-]*:/i.test(url) || url.startsWith("//");
+	try {
+		const base = typeof location !== "undefined" ? location.href : "https://placeholder.invalid/";
+		const parsed = new URL(url, base);
+		const kept = parsed.search.slice(1).split("&").filter((pair) => pair !== "" && pair.split("=", 1)[0] !== param);
+		kept.push(`${encodeURIComponent(param)}=${encodeURIComponent(clickId)}`);
+		parsed.search = kept.join("&");
+		return isAbsolute ? parsed.toString() : `${parsed.pathname}${parsed.search}${parsed.hash}`;
+	} catch {
+		return url;
+	}
+}
+/** Lee un click id válido de una URL (o null). */
+function readClickIdFromUrl(href, param = "ipc") {
+	try {
+		const value = new URL(href).searchParams.get(param);
+		return isClickId(value) ? value : null;
+	} catch {
+		return null;
+	}
+}
+// src/consent.ts
+const DEFAULT_CONSENT_COOKIE = "CookieConsent";
+/** Evento que dispara el banner de inspira-frontend-v2 al guardar el consentimiento. */
+const CONSENT_CHANGE_EVENT = "cookie-consent-change";
+const ANALYTICS_CATEGORY = /^(all|statistic|estad[íi]stic|analytic|anal[íi]tic)/;
+/** Interpreta el valor crudo de la cookie de consentimiento (puede venir URL-encoded). */
+function parseConsentValue(raw) {
+	if (!raw) return "unknown";
+	let decoded = raw;
+	try {
+		decoded = decodeURIComponent(raw);
+	} catch {}
+	return decoded.split(",").map((name) => name.trim().toLowerCase()).some((name) => ANALYTICS_CATEGORY.test(name)) ? "granted" : "denied";
+}
+/**
+* Lector de consentimiento basado en la cookie del banner de Inspira. Pásalo como
+* `consent` a `createTracker`. Se evalúa en cada evento, así que un cambio de
+* consentimiento aplica al siguiente evento sin recargar.
+*/
+function cookieConsent(cookieName = DEFAULT_CONSENT_COOKIE) {
+	const escaped = cookieName.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+	const pattern = new RegExp(`(?:^|;\\s*)${escaped}=([^;]*)`);
+	return () => {
+		if (typeof document === "undefined") return "unknown";
+		return parseConsentValue(pattern.exec(document.cookie)?.[1]);
+	};
+}
+// src/context.ts
+/**
+* Query params que SÍ se conservan en `ctx.url`. El resto se descarta: las URLs pueden
+* traer tokens, emails o ids de reserva.
+*/
+const DEFAULT_URL_PARAM_ALLOWLIST = [
+	"utm_source",
+	"utm_medium",
+	"utm_campaign",
+	"utm_term",
+	"utm_content",
+	"ipc",
+	"gclid",
+	"fbclid"
+];
+function sanitizeUrl(href, allowlist) {
+	try {
+		const url = new URL(href);
+		const kept = new URLSearchParams();
+		for (const [key, value] of url.searchParams) if (allowlist.includes(key)) kept.append(key, value);
+		const query = kept.toString();
+		return `${url.origin}${url.pathname}${query ? `?${query}` : ""}`;
+	} catch {
+		return "";
+	}
+}
+function originAndPath(href) {
+	if (!href) return null;
+	try {
+		const url = new URL(href);
+		return `${url.origin}${url.pathname}`;
+	} catch {
+		return null;
+	}
+}
+function collectContext(allowlist) {
+	let tz = null;
+	try {
+		tz = Intl.DateTimeFormat().resolvedOptions().timeZone ?? null;
+	} catch {
+		tz = null;
+	}
+	return {
+		url: sanitizeUrl(location.href, allowlist),
+		path: location.pathname,
+		referrer: originAndPath(document.referrer),
+		locale: document.documentElement.lang || navigator.language || null,
+		tz,
+		screen: typeof screen !== "undefined" ? {
+			w: screen.width,
+			h: screen.height
+		} : null,
+		viewport: {
+			w: window.innerWidth,
+			h: window.innerHeight
+		}
+	};
+}
+// src/storage.ts
+/**
+* localStorage/sessionStorage que nunca lanza: en Safari privado, con storage bloqueado o
+* cuota llena cae a memoria (los ids duran lo que dure la página).
+*/
+function safeStorage(kind) {
+	const memory = /* @__PURE__ */ new Map();
+	const backend = () => {
+		try {
+			return kind === "local" ? window.localStorage : window.sessionStorage;
+		} catch {
+			return null;
+		}
+	};
+	return {
+		get(key) {
+			try {
+				const value = backend()?.getItem(key);
+				if (value !== null && value !== void 0) return value;
+			} catch {}
+			return memory.get(key) ?? null;
+		},
+		set(key, value) {
+			try {
+				const storage = backend();
+				if (storage) {
+					storage.setItem(key, value);
+					memory.delete(key);
+					return;
+				}
+			} catch {}
+			memory.set(key, value);
+		},
+		remove(key) {
+			memory.delete(key);
+			try {
+				backend()?.removeItem(key);
+			} catch {}
+		}
+	};
+}
+// src/uuid.ts
+/** UUID v4. `crypto.randomUUID` solo existe en contextos seguros (https/localhost). */
+function uuid() {
+	const cryptoApi = globalThis.crypto;
+	if (typeof cryptoApi?.randomUUID === "function") return cryptoApi.randomUUID();
+	const bytes = /* @__PURE__ */ new Uint8Array(16);
+	if (typeof cryptoApi?.getRandomValues === "function") cryptoApi.getRandomValues(bytes);
+	else for (let i = 0; i < bytes.length; i++) bytes[i] = Math.floor(Math.random() * 256);
+	bytes[6] = (bytes[6] ?? 0) & 15 | 64;
+	bytes[8] = (bytes[8] ?? 0) & 63 | 128;
+	const hex = Array.from(bytes, (b) => b.toString(16).padStart(2, "0")).join("");
+	return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
+}
+// src/identity.ts
+const ANON_KEY = "ievt_aid";
+const SESSION_KEY = "ievt_sid";
+const SESSION_IDLE_MS = 18e5;
+/**
+* Ids first-party. SOLO se llama con consentimiento `granted`: sin consentimiento el SDK
+* no escribe nada en storage y el collector calcula un hash diario sin cookie.
+* - anon id: persistente por sitio (localStorage).
+* - session id: por pestaña (sessionStorage), rota tras 30 min de inactividad.
+*/
+function createIdentity(now = Date.now) {
+	const local = safeStorage("local");
+	const session = safeStorage("session");
+	return {
+		ensure() {
+			let anonId = local.get(ANON_KEY);
+			if (!anonId) {
+				anonId = uuid();
+				local.set(ANON_KEY, anonId);
+			}
+			const t = now();
+			let current = null;
+			try {
+				current = JSON.parse(session.get(SESSION_KEY) ?? "null");
+			} catch {
+				current = null;
+			}
+			if (!current || typeof current.id !== "string" || t - current.last > SESSION_IDLE_MS) current = {
+				id: uuid(),
+				last: t
+			};
+			else current.last = t;
+			session.set(SESSION_KEY, JSON.stringify(current));
+			return {
+				anonId,
+				sessionId: current.id
+			};
+		},
+		/** Borra los ids (consentimiento retirado o `reset()` al cerrar sesión). */
+		clear() {
+			if (local.get(ANON_KEY) !== null) local.remove(ANON_KEY);
+			if (session.get(SESSION_KEY) !== null) session.remove(SESSION_KEY);
+		}
+	};
+}
+// src/impressions.ts
+const STEPS = Array.from({ length: 11 }, (_, i) => i / 10);
+const EPSILON = .001;
+function isViewable(entry, threshold) {
+	if (!entry.isIntersecting) return false;
+	if (entry.intersectionRatio >= threshold - EPSILON) return true;
+	const root = entry.rootBounds;
+	if (!root || root.width === 0 || root.height === 0) return false;
+	return entry.intersectionRect.width * entry.intersectionRect.height / (root.width * root.height) >= threshold - EPSILON;
+}
+function createImpressionObserver(log) {
+	let observer = null;
+	const targets = /* @__PURE__ */ new Map();
+	const stop = (target) => {
+		if (target.timer !== null) {
+			clearTimeout(target.timer);
+			target.timer = null;
+		}
+	};
+	const remove = (target) => {
+		stop(target);
+		const set = targets.get(target.element);
+		if (!set?.delete(target)) return;
+		if (set.size === 0) {
+			targets.delete(target.element);
+			observer?.unobserve(target.element);
+		}
+	};
+	const start = (target) => {
+		if (target.done || target.timer !== null || document.visibilityState === "hidden") return;
+		target.timer = setTimeout(() => {
+			target.timer = null;
+			if (target.done || !target.inView) return;
+			target.done = true;
+			if (target.once) remove(target);
+			target.fire();
+		}, target.minVisibleMs);
+	};
+	const onEntries = (entries) => {
+		for (const entry of entries) {
+			const set = targets.get(entry.target);
+			if (!set) continue;
+			for (const target of set) {
+				target.inView = isViewable(entry, target.threshold);
+				if (target.inView) start(target);
+				else {
+					stop(target);
+					if (!target.once) target.done = false;
+				}
+			}
+		}
+	};
+	const onVisibilityChange = () => {
+		const hidden = document.visibilityState === "hidden";
+		for (const set of targets.values()) for (const target of set) if (hidden) stop(target);
+		else if (target.inView) start(target);
+	};
+	const ensureObserver = () => {
+		if (!observer) {
+			observer = new IntersectionObserver(onEntries, { threshold: STEPS });
+			document.addEventListener("visibilitychange", onVisibilityChange);
+		}
+		return observer;
+	};
+	return {
+		/** Observa `element` y llama `fire` cuando cumple la regla de visibilidad. Devuelve el cleanup. */
+		observe(element, fire, options = {}) {
+			if (typeof IntersectionObserver === "undefined") {
+				log("IntersectionObserver no disponible: impresión no medida");
+				return () => {};
+			}
+			const target = {
+				element,
+				threshold: Math.min(Math.max(options.threshold ?? .5, 0), 1),
+				minVisibleMs: Math.max(options.minVisibleMs ?? 1e3, 0),
+				once: options.once ?? true,
+				fire,
+				inView: false,
+				timer: null,
+				done: false
+			};
+			const io = ensureObserver();
+			let set = targets.get(element);
+			if (!set) {
+				set = /* @__PURE__ */ new Set();
+				targets.set(element, set);
+			} else io.unobserve(element);
+			set.add(target);
+			io.observe(element);
+			return () => remove(target);
+		},
+		disconnect() {
+			for (const set of targets.values()) for (const target of set) stop(target);
+			targets.clear();
+			observer?.disconnect();
+			observer = null;
+			document.removeEventListener("visibilitychange", onVisibilityChange);
+		}
+	};
+}
+// src/transport.ts
+const CONTENT_TYPE = "text/plain;charset=UTF-8";
+const fetchTransport = { send(url, body, { beacon, debug }) {
+	if (beacon && typeof navigator !== "undefined" && typeof navigator.sendBeacon === "function") try {
+		if (navigator.sendBeacon(url, new Blob([body], { type: CONTENT_TYPE }))) return "sent";
+	} catch {}
+	return fetch(url, {
+		method: "POST",
+		body,
+		headers: { "Content-Type": CONTENT_TYPE },
+		keepalive: true,
+		credentials: "omit",
+		mode: "cors"
+	}).then(async (response) => {
+		if (response.ok) {
+			if (debug) await logRejected(response);
+			return "sent";
+		}
+		if (debug) console.warn("[inspira-events] collector respondió", response.status);
+		return response.status === 429 || response.status >= 500 ? "retry" : "drop";
+	}, () => "retry");
+} };
+async function logRejected(response) {
+	try {
+		const data = await response.json();
+		if (Array.isArray(data.rejected) && data.rejected.length > 0) console.warn("[inspira-events] eventos rechazados por el collector", data.rejected);
+	} catch {}
+}
+// src/tracker.ts
+const MAX_ATTEMPTS = 3;
+const CLICK_ID_STORAGE_KEY = "ievt_ipc";
+const MAX_DESTINATION_URL_LENGTH = 2e3;
+const DAY_MS = 864e5;
+function createNoopTracker() {
+	return {
+		track: () => null,
+		observeImpression: () => () => {},
+		trackAdClick: (_props, url) => url,
+		captureClickId: () => null,
+		getClickId: () => null,
+		identify: () => {},
+		setWl: () => {},
+		reset: () => {},
+		flush: () => Promise.resolve(),
+		shutdown: () => {}
+	};
+}
+/**
+* Crea el tracker. En el servidor (SSR, sin `window`) devuelve un tracker no-op, así que es
+* seguro crearlo a nivel de módulo en un client component de Next.js.
+*/
+function createTracker(config) {
+	if (typeof window === "undefined" || typeof document === "undefined") return createNoopTracker();
+	const flushIntervalMs = config.flushIntervalMs ?? 5e3;
+	const maxBatchSize = Math.max(config.maxBatchSize ?? 20, 1);
+	const maxQueueSize = Math.max(config.maxQueueSize ?? 500, maxBatchSize);
+	const allowlist = config.urlParamAllowlist ?? DEFAULT_URL_PARAM_ALLOWLIST;
+	const transport = config.transport ?? fetchTransport;
+	const debug = config.debug ?? false;
+	const url = `${config.endpoint.replace(/\/+$/, "")}/e/v1/batch?k=${encodeURIComponent(config.siteKey)}`;
+	const identity = createIdentity();
+	const clickStore = safeStorage("local");
+	const log = (...args) => {
+		if (debug) console.debug("[inspira-events]", ...args);
+	};
+	const impressions = createImpressionObserver(log);
+	let wl = config.wl ?? null;
+	let userId = null;
+	let queue = [];
+	let timer = null;
+	let inflight = null;
+	let closed = false;
+	const consent = () => {
+		try {
+			return config.consent?.() ?? "unknown";
+		} catch {
+			return "unknown";
+		}
+	};
+	const schedule = (delay) => {
+		if (timer === null && !closed) timer = setTimeout(() => {
+			timer = null;
+			flush();
+		}, delay);
+	};
+	const trimQueue = () => {
+		const overflow = queue.length - maxQueueSize;
+		if (overflow > 0) {
+			queue.splice(0, overflow);
+			log(`cola llena: ${overflow} eventos descartados`);
+		}
+	};
+	const payload = (batch) => {
+		const body = {
+			sdk: {
+				name: SDK_NAME,
+				version: SDK_VERSION
+			},
+			sent_at: (/* @__PURE__ */ new Date()).toISOString(),
+			events: batch.map((q) => q.event)
+		};
+		return JSON.stringify(body);
+	};
+	const drain = async () => {
+		while (queue.length > 0) {
+			const batch = queue.splice(0, maxBatchSize);
+			let result;
+			try {
+				result = await transport.send(url, payload(batch), {
+					beacon: false,
+					debug
+				});
+			} catch {
+				result = "retry";
+			}
+			if (result === "sent") continue;
+			if (result === "drop") {
+				log(`lote de ${batch.length} eventos descartado por el collector`);
+				continue;
+			}
+			queue = [...batch.filter((q) => ++q.attempts < MAX_ATTEMPTS), ...queue];
+			trimQueue();
+			schedule(flushIntervalMs * 2);
+			return;
+		}
+	};
+	const flush = () => {
+		if (timer !== null) {
+			clearTimeout(timer);
+			timer = null;
+		}
+		if (!inflight) inflight = drain().finally(() => {
+			inflight = null;
+			if (queue.length > 0) schedule(flushIntervalMs);
+		});
+		return inflight;
+	};
+	const flushBeacon = () => {
+		if (timer !== null) {
+			clearTimeout(timer);
+			timer = null;
+		}
+		while (queue.length > 0) {
+			const batch = queue.splice(0, maxBatchSize);
+			try {
+				Promise.resolve(transport.send(url, payload(batch), {
+					beacon: true,
+					debug
+				})).catch(() => {});
+			} catch {}
+		}
+	};
+	const onVisibilityChange = () => {
+		if (document.visibilityState === "hidden") flushBeacon();
+	};
+	document.addEventListener("visibilitychange", onVisibilityChange);
+	window.addEventListener("pagehide", flushBeacon);
+	const enqueue = (event) => {
+		queue.push({
+			event,
+			attempts: 0
+		});
+		trimQueue();
+		if (queue.length >= maxBatchSize) flush();
+		else schedule(flushIntervalMs);
+	};
+	const forgetStoredIds = () => {
+		identity.clear();
+		if (clickStore.get(CLICK_ID_STORAGE_KEY) !== null) clickStore.remove(CLICK_ID_STORAGE_KEY);
+	};
+	const captureClickId = () => {
+		const clickId = readClickIdFromUrl(location.href);
+		if (clickId && consent() === "granted") clickStore.set(CLICK_ID_STORAGE_KEY, JSON.stringify({
+			id: clickId,
+			ts: Date.now()
+		}));
+		return clickId;
+	};
+	const onConsentChange = () => {
+		if (consent() === "granted") captureClickId();
+		else forgetStoredIds();
+	};
+	window.addEventListener(CONSENT_CHANGE_EVENT, onConsentChange);
+	const track = (name, props) => {
+		if (closed) return null;
+		let snapshot;
+		try {
+			snapshot = JSON.parse(JSON.stringify(props ?? {}));
+		} catch (error) {
+			log("props no serializables: evento descartado", name, error);
+			return null;
+		}
+		const state = consent();
+		const granted = state === "granted";
+		if (!granted) forgetStoredIds();
+		const ids = granted ? identity.ensure() : null;
+		const event = {
+			id: uuid(),
+			name,
+			ts: (/* @__PURE__ */ new Date()).toISOString(),
+			props: snapshot,
+			ctx: collectContext(allowlist),
+			wl,
+			consent: state,
+			anon_id: ids?.anonId ?? null,
+			session_id: ids?.sessionId ?? null,
+			user_id: granted ? userId : null
+		};
+		log("track", event.name, event);
+		enqueue(event);
+		return event.id;
+	};
+	return {
+		track,
+		observeImpression(element, name, props, options) {
+			if (closed) return () => {};
+			return impressions.observe(element, () => track(name, props), options);
+		},
+		trackAdClick(props, destination) {
+			const clickId = uuid();
+			track("ad_click", {
+				...props,
+				click_id: clickId,
+				destination_url: destination.slice(0, MAX_DESTINATION_URL_LENGTH)
+			});
+			return withClickId(destination, clickId);
+		},
+		captureClickId,
+		getClickId({ maxAgeDays = 7 } = {}) {
+			const fromUrl = readClickIdFromUrl(location.href);
+			if (fromUrl) return fromUrl;
+			if (consent() !== "granted") return null;
+			try {
+				const stored = JSON.parse(clickStore.get(CLICK_ID_STORAGE_KEY) ?? "null");
+				if (stored && isClickId(stored.id) && typeof stored.ts === "number" && Date.now() - stored.ts <= maxAgeDays * DAY_MS) return stored.id;
+			} catch {}
+			return null;
+		},
+		identify(id) {
+			userId = id === null ? null : String(id);
+		},
+		setWl(next) {
+			wl = next;
+		},
+		reset() {
+			userId = null;
+			forgetStoredIds();
+		},
+		flush,
+		shutdown() {
+			if (closed) return;
+			flushBeacon();
+			closed = true;
+			impressions.disconnect();
+			document.removeEventListener("visibilitychange", onVisibilityChange);
+			window.removeEventListener("pagehide", flushBeacon);
+			window.removeEventListener(CONSENT_CHANGE_EVENT, onConsentChange);
+		}
+	};
+}
+export { CLICK_ID_PARAM, CONSENT_CHANGE_EVENT, DEFAULT_CONSENT_COOKIE, DEFAULT_URL_PARAM_ALLOWLIST, SDK_NAME, SDK_VERSION, cookieConsent, createNoopTracker, createTracker, fetchTransport, isClickId, uuid as newId, parseConsentValue, readClickIdFromUrl, sanitizeUrl, withClickId };

package/dist/version-Cqps0u2Y.js

@@ -0,0 +1,4 @@
+// src/version.ts
+const SDK_NAME = "@inspira-npm/events";
+const SDK_VERSION = "0.1.0";
+export { SDK_VERSION as n, SDK_NAME as t };

package/package.json

@@ -1,6 +1,37 @@
 {
   "name": "@inspira-npm/events",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "SDK de tracking de eventos de Inspira (ads, cards, mapas, búsquedas) para navegador.",
+  "license": "UNLICENSED",
+  "type": "module",
+  "sideEffects": false,
+  "files": [
+    "dist",
+    "!dist/**/*.map"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./catalog": {
+      "types": "./dist/catalog.d.ts",
+      "import": "./dist/catalog.js"
+    },
+    "./catalog.json": "./dist/catalog.json",
+    "./package.json": "./package.json"
+  },
+  "types": "./dist/index.d.ts",
+  "scripts": {
+    "build": "tsdown && node scripts/build-catalog.mjs && node scripts/build-catalog-docs.mjs",
+    "test": "vitest run",
+    "typecheck": "tsc -p tsconfig.json",
+    "prepublishOnly": "npm run typecheck && npm run test && npm run build"
+  },
+  "dependencies": {
+    "zod": "^4.6.7"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.