@inspira-npm/events 0.1.0 → 0.3.0

package/dist/catalog.d.ts

@@ -1,2 +1,2 @@
-import { a as EventProps, c as isEventName, d as EventDefinition, f as EventSource, i as EventName, l as toJsonCatalog, n as Catalog, o as ImpressionEventName, r as CatalogJson, s as catalog, t as BrowserEventName, u as validateEventProps } from "./index-BdIq1xly.js";
+import { a as EventProps, c as isEventName, d as EventDefinition, f as EventSource, i as EventName, l as toJsonCatalog, n as Catalog, o as ImpressionEventName, r as CatalogJson, s as catalog, t as BrowserEventName, u as validateEventProps } from "./index-BShrVaIU.js";
 export { BrowserEventName, Catalog, CatalogJson, type EventDefinition, EventName, EventProps, type EventSource, ImpressionEventName, catalog, isEventName, toJsonCatalog, validateEventProps };

package/dist/catalog.js

@@ -1,30 +1,10 @@
-import { n as SDK_VERSION } from "./version-Cqps0u2Y.js";
+import { n as SDK_VERSION } from "./version-DPt-j93d.js";
+import { a as service, i as position, n as itemId, r as placement, t as currency } from "./shared-D2s2QSYg.js";
 import { z } from "zod";
 // src/catalog/define.ts
 function defineEvent(definition) {
 	return definition;
 }
-// src/catalog/shared.ts
-/**
-* Dónde se mostró algo, como `<página>.<sección>` en minúsculas: `home.resorts-carousel`,
-* `hotels-srp.side-rail`, `landing-ufc.hero`. Es la dimensión principal de los reportes:
-* mantenla estable (no metas ids ni textos traducidos).
-*/
-const placement = z.string().max(100).regex(/^[a-z0-9_-]+(\.[a-z0-9_-]+)*$/, "placement: <pagina>.<seccion> en minúsculas").describe("Dónde se mostró: <pagina>.<seccion>, p. ej. home.resorts-carousel");
-/** Posición 0-based dentro de un carrusel/lista. */
-const position = z.int().nonnegative().describe("Posición 0-based en la lista o carrusel");
-const itemId = z.string().min(1).max(200);
-/** Servicios de búsqueda/reserva de la plataforma. */
-const service = z.enum([
-	"hotels",
-	"resorts",
-	"flights",
-	"cars",
-	"activities",
-	"transfers",
-	"cruises"
-]).describe("Servicio de la plataforma");
-const currency = z.string().regex(/^[A-Z]{3}$/, "currency: código ISO 4217 en mayúsculas").describe("Código ISO 4217, p. ej. USD");
 // src/catalog/events/ads.ts
 const adProps = {
 	ad_id: z.string().min(1).max(100).describe("`id` del ad tal como lo devuelve el ads engine"),
@@ -104,7 +84,7 @@ const conversionEvents = { conversion: defineEvent({
 		service: service.optional(),
 		value: z.number().nonnegative().optional().describe("Monto de la conversión"),
 		currency: currency.optional(),
-		click_id: z.uuid().optional().describe("`ipc` capturado en el sitio destino; atribuye la conversión al ad clickeado")
+		click_id: z.uuid().optional().describe("`tracker.getClickId()` del front; atribuye la conversión al click (`ad_click` u `outbound_click`) con ese id")
 	})
 }) };
 // src/catalog/events/map.ts
@@ -140,6 +120,20 @@ const mapEvents = {
 		})
 	})
 };
+// src/catalog/events/navigation.ts
+const navigationEvents = { outbound_click: defineEvent({
+	domain: "navigation",
+	source: "browser",
+	since: "0.2.0",
+	description: "Click en un link o CTA medido que lleva a otro sitio o página (p. ej. CTA de una landing → sitio principal). `click_id` viaja en la URL de destino (`?ipc=`); `via_click_id` encadena la atribución con el click por el que llegó el visitante.",
+	props: z.strictObject({
+		placement,
+		item_id: itemId.optional().describe("Id del ítem al que lleva el CTA (hotel, resort, oferta…), si lo hay"),
+		click_id: z.uuid().describe("Id único del click; también va en la URL de destino como ?ipc="),
+		via_click_id: z.uuid().optional().describe("Click id con el que LLEGÓ el visitante (`?ipc=` capturado en este sitio); lo pone el SDK"),
+		destination_url: z.string().max(2e3).optional().describe("URL a la que lleva el click")
+	})
+}) };
 // src/catalog/events/page.ts
 const pageEvents = { page_view: defineEvent({
 	domain: "page",
@@ -216,6 +210,7 @@ const catalog = {
 	...cardEvents,
 	...mapEvents,
 	...searchEvents,
+	...navigationEvents,
 	...conversionEvents
 };
 function isEventName(name) {

package/dist/catalog.json

@@ -1,5 +1,5 @@
 {
-  "sdk_version": "0.1.0",
+  "sdk_version": "0.3.0",
   "events": {
     "page_view": {
       "description": "Vista de página. Se dispara al cargar y en cada navegación del router (SPA). La URL ya va en el contexto del evento.",
@@ -553,6 +553,52 @@
         "additionalProperties": false
       }
     },
+    "outbound_click": {
+      "description": "Click en un link o CTA medido que lleva a otro sitio o página (p. ej. CTA de una landing → sitio principal). `click_id` viaja en la URL de destino (`?ipc=`); `via_click_id` encadena la atribución con el click por el que llegó el visitante.",
+      "domain": "navigation",
+      "source": "browser",
+      "since": "0.2.0",
+      "schema": {
+        "$schema": "https://json-schema.org/draft/2020-12/schema",
+        "type": "object",
+        "properties": {
+          "placement": {
+            "type": "string",
+            "maxLength": 100,
+            "pattern": "^[a-z0-9_-]+(\\.[a-z0-9_-]+)*$",
+            "description": "Dónde se mostró: <pagina>.<seccion>, p. ej. home.resorts-carousel"
+          },
+          "item_id": {
+            "description": "Id del ítem al que lleva el CTA (hotel, resort, oferta…), si lo hay",
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 200
+          },
+          "click_id": {
+            "type": "string",
+            "format": "uuid",
+            "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
+            "description": "Id único del click; también va en la URL de destino como ?ipc="
+          },
+          "via_click_id": {
+            "description": "Click id con el que LLEGÓ el visitante (`?ipc=` capturado en este sitio); lo pone el SDK",
+            "type": "string",
+            "format": "uuid",
+            "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
+          },
+          "destination_url": {
+            "description": "URL a la que lleva el click",
+            "type": "string",
+            "maxLength": 2000
+          }
+        },
+        "required": [
+          "placement",
+          "click_id"
+        ],
+        "additionalProperties": false
+      }
+    },
     "conversion": {
       "description": "Conversión confirmada (reserva, lead, registro). La envía un BACKEND server-to-server, nunca el navegador. Idempotente por `conversion_id`.",
       "domain": "conversions",
@@ -602,7 +648,7 @@
             "description": "Código ISO 4217, p. ej. USD"
           },
           "click_id": {
-            "description": "`ipc` capturado en el sitio destino; atribuye la conversión al ad clickeado",
+            "description": "`tracker.getClickId()` del front; atribuye la conversión al click (`ad_click` u `outbound_click`) con ese id",
             "type": "string",
             "format": "uuid",
             "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"

package/dist/click-record-B8KyALZZ.d.ts

@@ -0,0 +1,31 @@
+/** Opciones de `TrackerConfig.clickRecord`. */
+interface ClickRecordOptions {
+  /**
+   * Ruta del mismo origen que expone el sitio con `createAdClickRoute`, p. ej. `/api/ad-click`.
+   * Una URL de otro origen se ignora (con un aviso en consola): la ruta necesita la cookie de
+   * sesión del sitio.
+   */
+  endpoint: string;
+  /**
+   * `true`: solo se registra el click con consentimiento de estadísticas `granted`. Default
+   * `false`: se registran todos los clicks, con o sin consentimiento (lo pidió negocio; legal
+   * puede pedir activarlo).
+   */
+  requireConsent?: boolean;
+}
+/** Body que el SDK manda a la ruta del sitio por cada `ad_click` (ver docs/protocol.md). */
+interface AdClickRecordPayload {
+  /** Versión del payload. */
+  v: 1;
+  /** El mismo `click_id` del evento `ad_click` (y del `?ipc=`): une el registro con el evento. */
+  click_id: string;
+  ad_id: string;
+  token?: string;
+  placement: string;
+  position?: number;
+  /** Página donde ocurrió el click, saneada igual que `ctx.url` (origin + path + allowlist). */
+  page_url: string;
+  /** Hora del click según el reloj del cliente (ISO 8601). */
+  ts: string;
+}
+export { ClickRecordOptions as n, AdClickRecordPayload as t };

package/dist/{index-BdIq1xly.d.ts → index-BShrVaIU.d.ts}

@@ -44,6 +44,13 @@ declare const catalog: {
     currency: z.ZodOptional<z.ZodString>;
     click_id: z.ZodOptional<z.ZodUUID>;
   }, z.core.$strict>, "server">;
+  outbound_click: EventDefinition<z.ZodObject<{
+    placement: z.ZodString;
+    item_id: z.ZodOptional<z.ZodString>;
+    click_id: z.ZodUUID;
+    via_click_id: z.ZodOptional<z.ZodUUID>;
+    destination_url: z.ZodOptional<z.ZodString>;
+  }, z.core.$strict>, "browser">;
   search_performed: EventDefinition<z.ZodObject<{
     search_id: z.ZodUUID;
     service: z.ZodEnum<{

package/dist/index.d.ts

@@ -1,4 +1,5 @@
-import { a as EventProps, i as EventName, o as ImpressionEventName, t as BrowserEventName } from "./index-BdIq1xly.js";
+import { a as EventProps, i as EventName, o as ImpressionEventName, t as BrowserEventName } from "./index-BShrVaIU.js";
+import { n as ClickRecordOptions, t as AdClickRecordPayload } from "./click-record-B8KyALZZ.js";
 /** Query param que lleva el click id de un ad hasta el sitio destino. */
 export declare const CLICK_ID_PARAM = "ipc";
 export declare function isClickId(value: unknown): value is string;
@@ -9,6 +10,17 @@ export declare function isClickId(value: unknown): value is string;
 export declare function withClickId(url: string, clickId: string, param?: string): string;
 /** Lee un click id válido de una URL (o null). */
 export declare function readClickIdFromUrl(href: string, param?: string): string | null;
+/**
+ * Copia a `url` los params de atribución de `from` (por defecto, la página actual): `ipc`,
+ * `utm_*`, `gclid` y `fbclid`. Los que `url` ya trae no se pisan. Igual que `withClickId`, el
+ * resto de la query y el hash quedan intactos (nada se vuelve a codificar) y las URLs relativas
+ * siguen siendo relativas. Si no hay nada que copiar, o alguna URL no se puede parsear, devuelve
+ * `url` tal cual.
+ *
+ * Para sitios intermedios (landings) que arman la URL de regreso: sin esto el `?ipc=` y las
+ * `utm_*` con las que llegó el visitante se pierden en el siguiente salto.
+ */
+export declare function withTrackingParams(url: string, from?: string): string;
 /**
  * - `granted`: aceptó cookies de estadísticas → ids persistentes (anon/session/user).
  * - `denied`: solo necesarias → eventos sin ningún identificador ni storage.
@@ -92,6 +104,15 @@ interface TrackerConfig {
    * utm_source, utm_medium, utm_campaign, utm_term, utm_content, ipc, gclid, fbclid.
    */
   urlParamAllowlist?: readonly string[];
+  /**
+   * Registro de cada click en un ad (`trackAdClick` / `useAdClick`) en el servidor del sitio,
+   * aparte del evento `ad_click`: ruta del mismo origen (p. ej. `/api/ad-click`) creada con
+   * `createAdClickRoute` de `@inspira-npm/events/server`, que agrega usuario, IP y organización
+   * desde la sesión. Con un string, o sin `requireConsent`, se registran TODOS los clicks, con o
+   * sin consentimiento; `{ endpoint, requireConsent: true }` lo limita a `granted`. Ver README,
+   * "Registro de clicks (servidor)".
+   */
+  clickRecord?: string | ClickRecordOptions;
   /** Loguea en consola los eventos y los rechazos del collector. */
   debug?: boolean;
   /** Reemplaza el envío HTTP (tests, entornos especiales). */
@@ -120,6 +141,11 @@ interface BatchPayload {
   events: EventEnvelope[];
 }
 type AdClickProps = Omit<EventProps<"ad_click">, "click_id" | "destination_url">;
+/**
+ * Props de `outbound_click` que pasa el sitio: `click_id`, `destination_url` y `via_click_id`
+ * los pone el SDK.
+ */
+type OutboundClickProps = Omit<EventProps<"outbound_click">, "click_id" | "destination_url" | "via_click_id">;
 interface Tracker {
   /**
    * Encola un evento del catálogo. Devuelve su id, o null si no se encoló: tracker no-op (SSR),
@@ -128,21 +154,35 @@ interface Tracker {
   track<N extends BrowserEventName>(name: N, props: EventProps<N>): string | null;
   /** Mide una impresión VISIBLE de `element` (≥50% durante ≥1 s por defecto). Devuelve el cleanup. */
   observeImpression<N extends ImpressionEventName>(element: Element, name: N, props: EventProps<N>, options?: ImpressionOptions): () => void;
-  /** Registra `ad_click` con un click id nuevo y devuelve `url` con `?ipc=<clickId>`. */
+  /**
+   * Registra `ad_click` con un click id nuevo y devuelve `url` con `?ipc=<clickId>`. Con
+   * consentimiento, guarda además el click id en este sitio (ver `getClickId`). Con
+   * `clickRecord` configurado, manda también el registro del click al servidor del sitio.
+   */
   trackAdClick(props: AdClickProps, url: string): string;
+  /**
+   * Como `trackAdClick`, para un link o CTA medido hacia otro sitio o página: registra
+   * `outbound_click` (con `via_click_id` = el click id con el que llegó el visitante, si hay) y
+   * devuelve `url` con `?ipc=<clickId>`.
+   */
+  trackOutboundClick(props: OutboundClickProps, url: string): string;
   /**
    * En el sitio destino: lee `?ipc=` de la URL y, con consentimiento, lo guarda para la conversión.
    * Si el usuario acepta el banner después, se vuelve a capturar solo (ver CONSENT_CHANGE_EVENT).
    */
   captureClickId(): string | null;
-  /** Click id vigente (URL actual o guardado hace ≤ `maxAgeDays`, default 7) para enviar con la conversión. */
+  /**
+   * Click id para enviar con la conversión: el `?ipc=` de la URL actual o, si no hay, el más
+   * reciente entre el capturado al llegar y el generado en un click de este sitio, guardados hace
+   * ≤ `maxAgeDays` (default 7). Sin consentimiento solo cuenta el de la URL.
+   */
   getClickId(options?: {
     maxAgeDays?: number;
   }): string | null;
   /** Usuario logueado. Solo se envía con consentimiento `granted`. */
   identify(userId: string | number | null): void;
   setWl(wl: number | null): void;
-  /** Logout: olvida usuario, ids y click id guardado. */
+  /** Logout: olvida usuario, ids y click ids guardados. */
   reset(): void;
   /** Envía lo que haya en cola. */
   flush(): Promise<void>;
@@ -158,5 +198,5 @@ export declare function createTracker(config: TrackerConfig): Tracker;
 /** UUID v4. `crypto.randomUUID` solo existe en contextos seguros (https/localhost). */
 declare function uuid(): string;
 export declare const SDK_NAME = "@inspira-npm/events";
-export declare const SDK_VERSION = "0.1.0";
-export { type AdClickProps, type BatchPayload, type BrowserEventName, type ConsentState, type EventContext, type EventEnvelope, type EventName, type EventProps, type ImpressionEventName, type ImpressionOptions, type SendResult, type Tracker, type TrackerConfig, type Transport, type TransportOptions, uuid as newId };
+export declare const SDK_VERSION = "0.3.0";
+export { type AdClickProps, type AdClickRecordPayload, type BatchPayload, type BrowserEventName, type ClickRecordOptions, type ConsentState, type EventContext, type EventEnvelope, type EventName, type EventProps, type ImpressionEventName, type ImpressionOptions, type OutboundClickProps, type SendResult, type Tracker, type TrackerConfig, type Transport, type TransportOptions, uuid as newId };

package/dist/index.js

@@ -1,4 +1,40 @@
-import { n as SDK_VERSION, t as SDK_NAME } from "./version-Cqps0u2Y.js";
+import { n as SDK_VERSION, t as SDK_NAME } from "./version-DPt-j93d.js";
+// src/query.ts
+/**
+* Reescribe la query de `url` editando sus pares CRUDOS (`clave=valor` tal como están en la URL,
+* sin decodificar). Conserva el hash; las URLs relativas siguen siendo relativas. Si la URL no se
+* puede parsear se devuelve igual.
+*
+* Se edita la query cruda a propósito: `searchParams.set` re-serializa TODOS los params
+* (%20 → +, `flag` → `flag=`, `~` → %7E…) y eso rompe URLs firmadas o de afiliados.
+*/
+function editRawQuery(url, edit) {
+	const isAbsolute = /^[a-z][a-z\d+.-]*:/i.test(url) || url.startsWith("//");
+	try {
+		const parsed = new URL(url, currentHref());
+		parsed.search = edit(rawPairs(parsed.search)).join("&");
+		return isAbsolute ? parsed.toString() : `${parsed.pathname}${parsed.search}${parsed.hash}`;
+	} catch {
+		return url;
+	}
+}
+/** Pares crudos de una query (`?a=1&b` → `["a=1", "b"]`), sin los vacíos. */
+function rawPairs(search) {
+	return search.replace(/^\?/, "").split("&").filter((pair) => pair !== "");
+}
+/** Nombre decodificado de un par crudo (`utm%5Fsource=x` → `utm_source`). */
+function pairKey(pair) {
+	const raw = pair.split("=", 1)[0] ?? "";
+	try {
+		return decodeURIComponent(raw.replace(/\+/g, " "));
+	} catch {
+		return raw;
+	}
+}
+/** Base para resolver URLs relativas: la página actual, o una ficticia en el servidor. */
+function currentHref() {
+	return typeof location !== "undefined" ? location.href : "https://placeholder.invalid/";
+}
 // src/click-id.ts
 /** Query param que lleva el click id de un ad hasta el sitio destino. */
 const CLICK_ID_PARAM = "ipc";
@@ -11,17 +47,7 @@ function isClickId(value) {
 * 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;
-	}
+	return editRawQuery(url, (pairs) => [...pairs.filter((pair) => pairKey(pair) !== param), `${encodeURIComponent(param)}=${encodeURIComponent(clickId)}`]);
 }
 /** Lee un click id válido de una URL (o null). */
 function readClickIdFromUrl(href, param = "ipc") {
@@ -32,6 +58,39 @@ function readClickIdFromUrl(href, param = "ipc") {
 		return null;
 	}
 }
+function isTrackingParam(key) {
+	return key === "ipc" || key === "gclid" || key === "fbclid" || key.startsWith("utm_");
+}
+/**
+* Copia a `url` los params de atribución de `from` (por defecto, la página actual): `ipc`,
+* `utm_*`, `gclid` y `fbclid`. Los que `url` ya trae no se pisan. Igual que `withClickId`, el
+* resto de la query y el hash quedan intactos (nada se vuelve a codificar) y las URLs relativas
+* siguen siendo relativas. Si no hay nada que copiar, o alguna URL no se puede parsear, devuelve
+* `url` tal cual.
+*
+* Para sitios intermedios (landings) que arman la URL de regreso: sin esto el `?ipc=` y las
+* `utm_*` con las que llegó el visitante se pierden en el siguiente salto.
+*/
+function withTrackingParams(url, from) {
+	let search;
+	try {
+		const href = from ?? (typeof location !== "undefined" ? location.href : "");
+		if (!href) return url;
+		search = new URL(href, currentHref()).search;
+	} catch {
+		return url;
+	}
+	const carried = rawPairs(search).filter((pair) => isTrackingParam(pairKey(pair)));
+	if (carried.length === 0) return url;
+	let added = false;
+	const out = editRawQuery(url, (pairs) => {
+		const present = new Set(pairs.map(pairKey));
+		const missing = carried.filter((pair) => !present.has(pairKey(pair)));
+		added = missing.length > 0;
+		return [...pairs, ...missing];
+	});
+	return added ? out : url;
+}
 // src/consent.ts
 const DEFAULT_CONSENT_COOKIE = "CookieConsent";
 /** Evento que dispara el banner de inspira-frontend-v2 al guardar el consentimiento. */
@@ -117,6 +176,50 @@ function collectContext(allowlist) {
 		}
 	};
 }
+// src/click-record.ts
+const MAX_PAGE_URL_LENGTH = 2e3;
+const CONTENT_TYPE$1 = "text/plain;charset=UTF-8";
+/**
+* Normaliza la opción. Devuelve null si no está configurada o no es del mismo origen que la
+* página (el aviso va siempre a consola: un error de configuración perdería registros en
+* silencio).
+*/
+function resolveClickRecord(option) {
+	if (!option) return null;
+	const { endpoint, requireConsent = false } = typeof option === "string" ? { endpoint: option } : option;
+	if (!endpoint) return null;
+	try {
+		const url = new URL(endpoint, location.href);
+		if (url.origin === location.origin) return {
+			url: url.href,
+			requireConsent
+		};
+	} catch {}
+	console.warn("[inspira-events] clickRecord.endpoint debe ser una ruta del mismo origen; registro de clicks desactivado:", endpoint);
+	return null;
+}
+/**
+* Envía el registro sin esperar respuesta: `sendBeacon` (sobrevive a la navegación que dispara
+* el click) o, si el navegador lo rechaza, `fetch` con `keepalive`. Nunca lanza.
+*/
+function sendClickRecord(url, payload) {
+	const body = JSON.stringify(payload);
+	try {
+		if (typeof navigator !== "undefined" && typeof navigator.sendBeacon === "function") {
+			if (navigator.sendBeacon(url, new Blob([body], { type: CONTENT_TYPE$1 }))) return;
+		}
+	} catch {}
+	try {
+		if (typeof fetch !== "function") return;
+		fetch(url, {
+			method: "POST",
+			body,
+			headers: { "Content-Type": CONTENT_TYPE$1 },
+			keepalive: true,
+			credentials: "same-origin"
+		}).catch(() => {});
+	} catch {}
+}
 // src/storage.ts
 /**
 * localStorage/sessionStorage que nunca lanza: en Safari privado, con storage bloqueado o
@@ -347,13 +450,22 @@ async function logRejected(response) {
 // src/tracker.ts
 const MAX_ATTEMPTS = 3;
 const CLICK_ID_STORAGE_KEY = "ievt_ipc";
+const OWN_CLICK_ID_STORAGE_KEY = "ievt_ipc_own";
 const MAX_DESTINATION_URL_LENGTH = 2e3;
 const DAY_MS = 864e5;
+const DEFAULT_MAX_AGE_DAYS = 7;
+function clickProps(clickId, destination) {
+	return {
+		click_id: clickId,
+		destination_url: destination.slice(0, MAX_DESTINATION_URL_LENGTH)
+	};
+}
 function createNoopTracker() {
 	return {
 		track: () => null,
 		observeImpression: () => () => {},
 		trackAdClick: (_props, url) => url,
+		trackOutboundClick: (_props, url) => url,
 		captureClickId: () => null,
 		getClickId: () => null,
 		identify: () => {},
@@ -378,6 +490,7 @@ function createTracker(config) {
 	const url = `${config.endpoint.replace(/\/+$/, "")}/e/v1/batch?k=${encodeURIComponent(config.siteKey)}`;
 	const identity = createIdentity();
 	const clickStore = safeStorage("local");
+	const clickRecord = resolveClickRecord(config.clickRecord);
 	const log = (...args) => {
 		if (debug) console.debug("[inspira-events]", ...args);
 	};
@@ -484,22 +597,51 @@ function createTracker(config) {
 	};
 	const forgetStoredIds = () => {
 		identity.clear();
-		if (clickStore.get(CLICK_ID_STORAGE_KEY) !== null) clickStore.remove(CLICK_ID_STORAGE_KEY);
+		for (const key of [CLICK_ID_STORAGE_KEY, OWN_CLICK_ID_STORAGE_KEY]) if (clickStore.get(key) !== null) clickStore.remove(key);
+	};
+	const readStoredClickId = (key, maxAgeDays) => {
+		try {
+			const stored = JSON.parse(clickStore.get(key) ?? "null");
+			if (stored && isClickId(stored.id) && typeof stored.ts === "number" && Date.now() - stored.ts <= maxAgeDays * DAY_MS) return {
+				id: stored.id,
+				ts: stored.ts
+			};
+		} catch {}
+		return null;
+	};
+	const storeClickId = (key, entry) => {
+		clickStore.set(key, JSON.stringify(entry));
 	};
 	const captureClickId = () => {
 		const clickId = readClickIdFromUrl(location.href);
-		if (clickId && consent() === "granted") clickStore.set(CLICK_ID_STORAGE_KEY, JSON.stringify({
+		if (clickId && consent() === "granted") {
+			const previous = readStoredClickId(CLICK_ID_STORAGE_KEY, Number.POSITIVE_INFINITY);
+			const ts = previous?.id === clickId ? previous.ts : Date.now();
+			storeClickId(CLICK_ID_STORAGE_KEY, {
+				id: clickId,
+				ts
+			});
+		}
+		return clickId;
+	};
+	const arrivedClickId = () => {
+		const fromUrl = readClickIdFromUrl(location.href);
+		if (fromUrl) return fromUrl;
+		if (consent() !== "granted") return null;
+		return readStoredClickId(CLICK_ID_STORAGE_KEY, DEFAULT_MAX_AGE_DAYS)?.id ?? null;
+	};
+	const rememberOwnClickId = (clickId) => {
+		if (consent() === "granted") storeClickId(OWN_CLICK_ID_STORAGE_KEY, {
 			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) => {
+	const emit = (name, props) => {
 		if (closed) return null;
 		let snapshot;
 		try {
@@ -526,7 +668,27 @@ function createTracker(config) {
 		};
 		log("track", event.name, event);
 		enqueue(event);
-		return event.id;
+		return event;
+	};
+	const track = (name, props) => emit(name, props)?.id ?? null;
+	const recordAdClick = (event) => {
+		if (!clickRecord) return;
+		if (clickRecord.requireConsent && event.consent !== "granted") return;
+		try {
+			const props = event.props;
+			const payload = {
+				v: 1,
+				click_id: props.click_id,
+				ad_id: props.ad_id,
+				token: props.token,
+				placement: props.placement,
+				position: props.position,
+				page_url: event.ctx.url.slice(0, MAX_PAGE_URL_LENGTH),
+				ts: event.ts
+			};
+			log("click record", payload);
+			sendClickRecord(clickRecord.url, payload);
+		} catch {}
 	};
 	return {
 		track,
@@ -536,23 +698,35 @@ function createTracker(config) {
 		},
 		trackAdClick(props, destination) {
 			const clickId = uuid();
-			track("ad_click", {
+			const event = emit("ad_click", {
 				...props,
-				click_id: clickId,
-				destination_url: destination.slice(0, MAX_DESTINATION_URL_LENGTH)
+				...clickProps(clickId, destination)
 			});
+			if (event) {
+				rememberOwnClickId(clickId);
+				recordAdClick(event);
+			}
+			return withClickId(destination, clickId);
+		},
+		trackOutboundClick(props, destination) {
+			const clickId = uuid();
+			const event = {
+				...props,
+				...clickProps(clickId, destination),
+				via_click_id: arrivedClickId() ?? void 0
+			};
+			if (track("outbound_click", event)) rememberOwnClickId(clickId);
 			return withClickId(destination, clickId);
 		},
 		captureClickId,
-		getClickId({ maxAgeDays = 7 } = {}) {
+		getClickId({ maxAgeDays = DEFAULT_MAX_AGE_DAYS } = {}) {
 			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;
+			const arrived = readStoredClickId(CLICK_ID_STORAGE_KEY, maxAgeDays);
+			const own = readStoredClickId(OWN_CLICK_ID_STORAGE_KEY, maxAgeDays);
+			if (arrived && own) return own.ts >= arrived.ts ? own.id : arrived.id;
+			return (own ?? arrived)?.id ?? null;
 		},
 		identify(id) {
 			userId = id === null ? null : String(id);
@@ -576,4 +750,4 @@ function createTracker(config) {
 		}
 	};
 }
-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 };
+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, withTrackingParams };

package/dist/server.d.ts

@@ -0,0 +1,141 @@
+import { t as AdClickRecordPayload } from "./click-record-B8KyALZZ.js";
+import { z } from "zod";
+/**
+ * IP del cliente desde los headers del request: `cf-connecting-ip`, `true-client-ip`, el primer
+ * valor de `x-forwarded-for` y `x-real-ip`, en ese orden. Salta los valores vacíos, inválidos o
+ * de relleno (`0`, `::1`, `127.0.0.1`…). Devuelve null si ninguno sirve.
+ */
+export declare function resolveClientIp(headers: Headers): string | null;
+/** Datos del usuario logueado, desde la sesión del sitio. Un campo ausente o vacío viaja `null`. */
+interface AdClickUser {
+  /** Id del usuario en Inspira. */
+  inspira_id?: string | number | null;
+  email?: string | null;
+  phone?: string | null;
+  /** Id del usuario en el sistema del cliente white-label. */
+  external_id?: string | number | null;
+  loyalty_id?: string | number | null;
+}
+/** Body de `POST {apiBase}/api/v1/ad-clicks` (ver docs/protocol.md). */
+interface AdClickRecordBody {
+  click_id: string;
+  ad_id: string;
+  token?: string;
+  placement: string;
+  position?: number;
+  page_url: string;
+  /** `ts` del navegador. */
+  client_ts?: string;
+  /** Hora del servidor del sitio al recibir el click. */
+  clicked_at: string;
+  org: number | null;
+  ip: string | null;
+  user_agent: string | null;
+  user: {
+    inspira_id: string | null;
+    email: string | null;
+    phone: string | null;
+    external_id: string | null;
+    loyalty_id: string | null;
+  } | null;
+}
+/** Credenciales y red para hablar con Laravel (`inspira-promotions-laravel`). */
+interface AdClickApiOptions {
+  /** URL base de Laravel, p. ej. `https://inspirapromotions.com` (sin `/api`). */
+  apiBase: string;
+  /** Cliente OAuth2 (client_credentials, scope `ad-clicks:write`) dado de alta en el admin. */
+  clientId: string;
+  /** Secreto del cliente. Solo servidor: nunca en una variable pública ni en el bundle. */
+  clientSecret: string;
+  /** Tiempo máximo TOTAL del envío (token incluido). Default 3000 ms. */
+  timeoutMs?: number;
+  /** Reemplaza `fetch` (tests). Default: el `fetch` global. */
+  fetch?: typeof fetch;
+}
+interface RecordAdClickOptions extends AdClickApiOptions {
+  /** Body JSON tal como lo mandó el navegador; se valida aquí. */
+  payload: unknown;
+  /** Usuario logueado, o null/omitido si no hay sesión. */
+  user?: AdClickUser | null;
+  /** Organización (whitelabel) del tenant, o null. */
+  org?: number | null;
+  ip?: string | null;
+  userAgent?: string | null;
+  /** Hora del click en el servidor. Default: ahora. */
+  clickedAt?: Date;
+}
+type RecordAdClickFailureReason =
+/** El body del navegador no cumple el contrato (`error` = ZodError). */
+"invalid_payload" |
+/** Falta `apiBase`, `clientId` o `clientSecret`. */
+"not_configured" |
+/** `POST /oauth/token` respondió con error (credenciales o scope). */
+"token_failed" |
+/** 401 aun con un token nuevo. */
+"unauthorized" |
+/** 403: el cliente no tiene el scope `ad-clicks:write`. */
+"forbidden" |
+/** 422: Laravel rechazó el body. */
+"rejected" |
+/** Otro status de error (5xx, 429…). */
+"http_error" | "timeout" | "network_error";
+interface RecordAdClickFailure {
+  ok: false;
+  reason: RecordAdClickFailureReason;
+  /** Status HTTP de la respuesta que falló, si hubo respuesta. */
+  httpStatus?: number;
+  error?: unknown;
+}
+type RecordAdClickResult = {
+  ok: true;
+  status: "recorded" | "duplicate";
+  httpStatus: number;
+} | RecordAdClickFailure;
+/**
+ * Registra un click en Laravel (bajo nivel; `createAdClickRoute` lo usa por dentro): valida el
+ * body del navegador, arma el body con usuario, organización, IP y user agent, y lo envía con un
+ * token client_credentials cacheado. Nunca lanza.
+ */
+export declare function recordAdClick(options: RecordAdClickOptions): Promise<RecordAdClickResult>;
+type MaybePromise<T> = T | Promise<T>;
+interface AdClickRouteErrorInfo {
+  /** Dónde falló: la sesión (`get_user`), el tenant (`get_org`) o el envío a Laravel (`record`). */
+  stage: "get_user" | "get_org" | "record";
+  click_id: string;
+  /** Solo en `record`: el resultado del envío. */
+  result?: RecordAdClickFailure;
+}
+interface AdClickRouteOptions extends AdClickApiOptions {
+  /**
+   * Usuario logueado desde la sesión del SITIO (cookie del mismo origen), o null si no hay
+   * sesión. Si lanza, el click se registra igual con `user: null` (y se avisa a `onError`).
+   */
+  getUser: (request: Request) => MaybePromise<AdClickUser | null | undefined>;
+  /** Organización (whitelabel) del tenant, o null. Si lanza, `org: null`. */
+  getOrg: (request: Request) => MaybePromise<number | null | undefined>;
+  /** IP del cliente. Default: `resolveClientIp(request.headers)`. */
+  getIp?: (request: Request) => string | null | undefined;
+  /**
+   * Errores que no llegan al navegador (siempre recibe 204): sesión, tenant y envío a Laravel.
+   * Nunca recibe datos del usuario.
+   */
+  onError?: (error: unknown, info: AdClickRouteErrorInfo) => void;
+  /**
+   * Para responder sin esperar a Laravel: recibe la promesa del envío y debe mantener viva la
+   * función hasta que termine (`after` de `next/server`, `waitUntil` de Vercel o del runtime
+   * edge). Sin esto, la ruta espera el envío (como máximo `timeoutMs`) antes de responder.
+   */
+  waitUntil?: (task: Promise<unknown>) => void;
+  /** Tamaño máximo del body. Default 8 KB. */
+  maxBodyBytes?: number;
+}
+/**
+ * Handler de la ruta del sitio que recibe el registro de clicks del SDK (`clickRecord`) y lo
+ * reenvía a Laravel con la identidad de la sesión. Para Next.js: `export const POST =
+ * createAdClickRoute({ … })`. Usa solo `Request`/`Response`/`fetch` estándar (Node ≥ 18, edge).
+ *
+ * Respuestas al navegador: 204 (registro aceptado, aunque Laravel falle: se avisa a `onError`),
+ * 400 body inválido, 403 request de otro sitio, 405 método distinto de POST, 413 body grande.
+ */
+export declare function createAdClickRoute(options: AdClickRouteOptions): (request: Request) => Promise<Response>;
+export type { AdClickApiOptions, AdClickRecordBody, AdClickRecordPayload, AdClickRouteErrorInfo, AdClickRouteOptions, AdClickUser, RecordAdClickFailure, RecordAdClickFailureReason, RecordAdClickOptions, RecordAdClickResult };

package/dist/server.js

@@ -0,0 +1,445 @@
+import { r as placement } from "./shared-D2s2QSYg.js";
+import { z } from "zod";
+// src/server/ip.ts
+const IP_HEADERS = [
+	"cf-connecting-ip",
+	"true-client-ip",
+	"x-forwarded-for",
+	"x-real-ip"
+];
+const PLACEHOLDERS = /* @__PURE__ */ new Set([
+	"0",
+	"0.0.0.0",
+	"::",
+	"::1",
+	"127.0.0.1",
+	"::ffff:127.0.0.1"
+]);
+const IPV4 = /^(25[0-5]|2[0-4]\d|1\d\d|[1-9]?\d)(\.(25[0-5]|2[0-4]\d|1\d\d|[1-9]?\d)){3}$/;
+const HEX_GROUP = /^[0-9a-f]{1,4}$/;
+function isIPv4(value) {
+	return IPV4.test(value);
+}
+function isIPv6(value) {
+	if (value.length > 45 || !value.includes(":")) return false;
+	let address = value;
+	const lastColon = address.lastIndexOf(":");
+	const tail = address.slice(lastColon + 1);
+	if (tail.includes(".")) {
+		if (!isIPv4(tail)) return false;
+		address = `${address.slice(0, lastColon + 1)}0:0`;
+	}
+	const halves = address.split("::");
+	if (halves.length > 2) return false;
+	const groups = (part) => part ? part.split(":") : [];
+	const head = groups(halves[0]);
+	const rest = groups(halves[1]);
+	if (![...head, ...rest].every((group) => HEX_GROUP.test(group))) return false;
+	const count = head.length + rest.length;
+	return halves.length === 2 ? count < 8 : count === 8;
+}
+/**
+* Normaliza un valor de header a una IP válida, o null. Acepta `[v6]:puerto` y `v4:puerto`
+* (algunos balanceadores agregan el puerto).
+*/
+function normalizeIp(raw) {
+	let value = raw.trim().toLowerCase();
+	const bracketed = /^\[([^\]]+)\](?::\d+)?$/.exec(value);
+	if (bracketed?.[1]) value = bracketed[1];
+	else if (/^[\d.]+:\d+$/.test(value)) value = value.slice(0, value.lastIndexOf(":"));
+	if (PLACEHOLDERS.has(value)) return null;
+	return isIPv4(value) || isIPv6(value) ? value : null;
+}
+/**
+* IP del cliente desde los headers del request: `cf-connecting-ip`, `true-client-ip`, el primer
+* valor de `x-forwarded-for` y `x-real-ip`, en ese orden. Salta los valores vacíos, inválidos o
+* de relleno (`0`, `::1`, `127.0.0.1`…). Devuelve null si ninguno sirve.
+*/
+function resolveClientIp(headers) {
+	for (const name of IP_HEADERS) {
+		const raw = headers.get(name);
+		if (!raw) continue;
+		const ip = normalizeIp(name === "x-forwarded-for" ? raw.split(",")[0] ?? "" : raw);
+		if (ip) return ip;
+	}
+	return null;
+}
+// src/server/record.ts
+/**
+* Body del navegador (`AdClickRecordPayload`). Los campos desconocidos se descartan: solo viaja a
+* Laravel lo que este esquema conoce.
+*/
+const adClickRecordPayloadSchema = z.object({
+	v: z.literal(1),
+	click_id: z.uuid(),
+	ad_id: z.string().min(1).max(100),
+	token: z.string().max(2e3).optional(),
+	placement,
+	position: z.int().nonnegative().optional(),
+	page_url: z.string().min(1).max(2e3).regex(/^https?:\/\//i, "page_url: URL http(s)"),
+	ts: z.iso.datetime({ offset: true })
+});
+const SCOPE = "ad-clicks:write";
+const DEFAULT_TIMEOUT_MS = 3e3;
+const MAX_USER_AGENT_LENGTH = 500;
+const DEFAULT_TOKEN_TTL_S = 3600;
+function parseAdClickPayload(input) {
+	return adClickRecordPayloadSchema.safeParse(input);
+}
+function text(value) {
+	if (typeof value === "number" && Number.isFinite(value)) return String(value);
+	if (typeof value !== "string") return null;
+	const trimmed = value.trim();
+	return trimmed === "" ? null : trimmed;
+}
+function normalizeUser(user) {
+	if (!user) return null;
+	return {
+		inspira_id: text(user.inspira_id),
+		email: text(user.email),
+		phone: text(user.phone),
+		external_id: text(user.external_id),
+		loyalty_id: text(user.loyalty_id)
+	};
+}
+/** Arma el body para Laravel con un payload ya validado y el contexto del servidor. */
+function buildAdClickBody(payload, context) {
+	const userAgent = text(context.userAgent)?.slice(0, MAX_USER_AGENT_LENGTH) ?? null;
+	return {
+		click_id: payload.click_id,
+		ad_id: payload.ad_id,
+		token: payload.token,
+		placement: payload.placement,
+		position: payload.position,
+		page_url: payload.page_url,
+		client_ts: payload.ts,
+		clicked_at: (context.clickedAt ?? /* @__PURE__ */ new Date()).toISOString(),
+		org: Number.isInteger(context.org) ? context.org : null,
+		ip: typeof context.ip === "string" ? normalizeIp(context.ip) : null,
+		user_agent: userAgent,
+		user: normalizeUser(context.user)
+	};
+}
+const tokens = /* @__PURE__ */ new Map();
+const pendingTokens = /* @__PURE__ */ new Map();
+var TokenError = class extends Error {
+	constructor(httpStatus) {
+		super(`oauth/token respondió ${httpStatus}`);
+		this.httpStatus = httpStatus;
+	}
+};
+const baseUrl = (apiBase) => apiBase.replace(/\/+$/, "");
+const cacheKey = (options) => `${baseUrl(options.apiBase)}\n${options.clientId}`;
+async function requestToken(options, doFetch, signal) {
+	const response = await doFetch(`${baseUrl(options.apiBase)}/oauth/token`, {
+		method: "POST",
+		headers: {
+			"Content-Type": "application/x-www-form-urlencoded",
+			Accept: "application/json"
+		},
+		body: new URLSearchParams({
+			grant_type: "client_credentials",
+			client_id: options.clientId,
+			client_secret: options.clientSecret,
+			scope: SCOPE
+		}).toString(),
+		signal
+	});
+	if (!response.ok) {
+		await discard(response);
+		throw new TokenError(response.status);
+	}
+	const data = await response.json();
+	if (typeof data.access_token !== "string" || data.access_token === "") throw new TokenError(response.status);
+	const ttl = typeof data.expires_in === "number" && data.expires_in > 0 ? data.expires_in : DEFAULT_TOKEN_TTL_S;
+	const margin = Math.min(60, ttl / 10);
+	return {
+		token: data.access_token,
+		refreshAt: Date.now() + (ttl - margin) * 1e3
+	};
+}
+function untilAborted(promise, signal) {
+	if (signal.aborted) return Promise.reject(signal.reason);
+	return new Promise((resolve, reject) => {
+		const onAbort = () => reject(signal.reason);
+		signal.addEventListener("abort", onAbort, { once: true });
+		promise.then(resolve, reject).finally(() => signal.removeEventListener("abort", onAbort));
+	});
+}
+async function accessToken(options, doFetch, signal) {
+	const key = cacheKey(options);
+	const cached = tokens.get(key);
+	if (cached && Date.now() < cached.refreshAt) return cached.token;
+	let pending = pendingTokens.get(key);
+	if (!pending) {
+		pending = requestToken(options, doFetch, signal).then((fresh) => {
+			tokens.set(key, fresh);
+			pendingTokens.delete(key);
+			return fresh;
+		}, (error) => {
+			pendingTokens.delete(key);
+			throw error;
+		});
+		pendingTokens.set(key, pending);
+	}
+	return (await untilAborted(pending, signal)).token;
+}
+function forgetToken(options, token) {
+	const key = cacheKey(options);
+	if (tokens.get(key)?.token === token) tokens.delete(key);
+}
+async function discard(response) {
+	try {
+		await response.text();
+	} catch {}
+}
+function failureFor(status) {
+	return {
+		ok: false,
+		reason: status === 401 ? "unauthorized" : status === 403 ? "forbidden" : status === 422 ? "rejected" : "http_error",
+		httpStatus: status
+	};
+}
+/**
+* Envía un body ya armado a `POST {apiBase}/api/v1/ad-clicks`. Pide (y cachea) el token; ante un
+* 401 lo renueva y reintenta una vez. Nunca lanza: los errores vuelven como `ok: false`.
+*/
+async function deliverAdClick(body, options) {
+	if (!options.apiBase || !options.clientId || !options.clientSecret) return {
+		ok: false,
+		reason: "not_configured"
+	};
+	const doFetch = options.fetch ?? globalThis.fetch;
+	const controller = new AbortController();
+	const timer = setTimeout(() => controller.abort(/* @__PURE__ */ new Error("ad click record: timeout")), options.timeoutMs ?? DEFAULT_TIMEOUT_MS);
+	try {
+		for (let attempt = 1;; attempt++) {
+			const token = await accessToken(options, doFetch, controller.signal);
+			const response = await doFetch(`${baseUrl(options.apiBase)}/api/v1/ad-clicks`, {
+				method: "POST",
+				headers: {
+					Authorization: `Bearer ${token}`,
+					"Content-Type": "application/json",
+					Accept: "application/json"
+				},
+				body: JSON.stringify(body),
+				signal: controller.signal
+			});
+			if (response.status === 401 && attempt === 1) {
+				await discard(response);
+				forgetToken(options, token);
+				continue;
+			}
+			if (!response.ok) {
+				await discard(response);
+				return failureFor(response.status);
+			}
+			let status;
+			try {
+				status = (await response.json())?.status;
+			} catch {
+				status = void 0;
+			}
+			return {
+				ok: true,
+				status: status === "duplicate" || status !== "recorded" && response.status === 200 ? "duplicate" : "recorded",
+				httpStatus: response.status
+			};
+		}
+	} catch (error) {
+		if (controller.signal.aborted) return {
+			ok: false,
+			reason: "timeout",
+			error
+		};
+		if (error instanceof TokenError) return {
+			ok: false,
+			reason: "token_failed",
+			httpStatus: error.httpStatus,
+			error
+		};
+		return {
+			ok: false,
+			reason: "network_error",
+			error
+		};
+	} finally {
+		clearTimeout(timer);
+	}
+}
+/**
+* Registra un click en Laravel (bajo nivel; `createAdClickRoute` lo usa por dentro): valida el
+* body del navegador, arma el body con usuario, organización, IP y user agent, y lo envía con un
+* token client_credentials cacheado. Nunca lanza.
+*/
+async function recordAdClick(options) {
+	try {
+		const parsed = parseAdClickPayload(options.payload);
+		if (!parsed.success) return {
+			ok: false,
+			reason: "invalid_payload",
+			error: parsed.error
+		};
+		return await deliverAdClick(buildAdClickBody(parsed.data, options), options);
+	} catch (error) {
+		return {
+			ok: false,
+			reason: "network_error",
+			error
+		};
+	}
+}
+// src/server/route.ts
+const DEFAULT_MAX_BODY_BYTES = 8192;
+const NO_STORE = { "Cache-Control": "no-store" };
+function reply(status, error, headers = {}) {
+	if (!error) return new Response(null, {
+		status,
+		headers: {
+			...NO_STORE,
+			...headers
+		}
+	});
+	return new Response(JSON.stringify({ error }), {
+		status,
+		headers: {
+			...NO_STORE,
+			"Content-Type": "application/json",
+			...headers
+		}
+	});
+}
+const firstValue = (value) => value?.split(",")[0]?.trim().toLowerCase() || null;
+function requestHosts(request) {
+	const hosts = [firstValue(request.headers.get("host"))];
+	hosts.push(firstValue(request.headers.get("x-forwarded-host")));
+	try {
+		hosts.push(new URL(request.url).host.toLowerCase());
+	} catch {}
+	return hosts.filter((host) => !!host);
+}
+/**
+* Solo requests del propio sitio: la ruta usa la cookie de sesión, así que un POST desde otro
+* sitio (CSRF) registraría clicks a nombre del visitante.
+* - Con `Sec-Fetch-Site` (navegadores actuales; el navegador lo calcula y una página no lo puede
+*   falsear) solo se acepta `same-origin`.
+* - Sin él, el `Origin` (si viene) debe tener el mismo host que el request. Sin ninguno de los dos
+*   no es un navegador actual: no hay cookie de un visitante que proteger.
+*/
+function isSameOrigin(request) {
+	const site = request.headers.get("sec-fetch-site");
+	if (site !== null) return site === "same-origin";
+	const origin = request.headers.get("origin");
+	if (origin === null) return true;
+	let host;
+	try {
+		host = new URL(origin).host.toLowerCase();
+	} catch {
+		return false;
+	}
+	return host !== "" && requestHosts(request).includes(host);
+}
+var BodyTooLarge = class extends Error {};
+async function readBody(request, max) {
+	const declared = Number(request.headers.get("content-length") ?? "");
+	if (Number.isFinite(declared) && declared > max) throw new BodyTooLarge();
+	if (!request.body) return "";
+	const reader = request.body.getReader();
+	const chunks = [];
+	let size = 0;
+	for (;;) {
+		const { done, value } = await reader.read();
+		if (done) break;
+		size += value.byteLength;
+		if (size > max) {
+			reader.cancel().catch(() => {});
+			throw new BodyTooLarge();
+		}
+		chunks.push(value);
+	}
+	const bytes = new Uint8Array(size);
+	let offset = 0;
+	for (const chunk of chunks) {
+		bytes.set(chunk, offset);
+		offset += chunk.byteLength;
+	}
+	return new TextDecoder().decode(bytes);
+}
+/**
+* Handler de la ruta del sitio que recibe el registro de clicks del SDK (`clickRecord`) y lo
+* reenvía a Laravel con la identidad de la sesión. Para Next.js: `export const POST =
+* createAdClickRoute({ … })`. Usa solo `Request`/`Response`/`fetch` estándar (Node ≥ 18, edge).
+*
+* Respuestas al navegador: 204 (registro aceptado, aunque Laravel falle: se avisa a `onError`),
+* 400 body inválido, 403 request de otro sitio, 405 método distinto de POST, 413 body grande.
+*/
+function createAdClickRoute(options) {
+	const maxBodyBytes = options.maxBodyBytes ?? DEFAULT_MAX_BODY_BYTES;
+	const report = (error, info) => {
+		try {
+			options.onError?.(error, info);
+		} catch {}
+	};
+	return async function adClickRoute(request) {
+		if (request.method !== "POST") return reply(405, void 0, { Allow: "POST" });
+		if (!isSameOrigin(request)) return reply(403, "cross_site");
+		let input;
+		try {
+			input = JSON.parse(await readBody(request, maxBodyBytes));
+		} catch (error) {
+			if (error instanceof BodyTooLarge) return reply(413, "payload_too_large");
+			return reply(400, "invalid_payload");
+		}
+		const parsed = parseAdClickPayload(input);
+		if (!parsed.success) return reply(400, "invalid_payload");
+		const payload = parsed.data;
+		const clickId = payload.click_id;
+		let user = null;
+		try {
+			user = await options.getUser(request) ?? null;
+		} catch (error) {
+			report(error, {
+				stage: "get_user",
+				click_id: clickId
+			});
+		}
+		let org = null;
+		try {
+			org = await options.getOrg(request) ?? null;
+		} catch (error) {
+			report(error, {
+				stage: "get_org",
+				click_id: clickId
+			});
+		}
+		let ip = null;
+		try {
+			ip = options.getIp ? options.getIp(request) ?? null : resolveClientIp(request.headers);
+		} catch {
+			ip = null;
+		}
+		const task = deliverAdClick(buildAdClickBody(payload, {
+			user,
+			org,
+			ip,
+			userAgent: request.headers.get("user-agent")
+		}), options).then((result) => {
+			if (!result.ok) {
+				const error = result.error ?? /* @__PURE__ */ new Error(`ad click record: ${result.reason}`);
+				report(error, {
+					stage: "record",
+					click_id: clickId,
+					result
+				});
+			}
+		});
+		if (options.waitUntil) try {
+			options.waitUntil(task);
+		} catch {
+			await task;
+		}
+		else await task;
+		return reply(204);
+	};
+}
+export { createAdClickRoute, recordAdClick, resolveClientIp };

package/dist/shared-D2s2QSYg.js

@@ -0,0 +1,23 @@
+import { z } from "zod";
+// src/catalog/shared.ts
+/**
+* Dónde se mostró algo, como `<página>.<sección>` en minúsculas: `home.resorts-carousel`,
+* `hotels-srp.side-rail`, `landing-ufc.hero`. Es la dimensión principal de los reportes:
+* mantenla estable (no metas ids ni textos traducidos).
+*/
+const placement = z.string().max(100).regex(/^[a-z0-9_-]+(\.[a-z0-9_-]+)*$/, "placement: <pagina>.<seccion> en minúsculas").describe("Dónde se mostró: <pagina>.<seccion>, p. ej. home.resorts-carousel");
+/** Posición 0-based dentro de un carrusel/lista. */
+const position = z.int().nonnegative().describe("Posición 0-based en la lista o carrusel");
+const itemId = z.string().min(1).max(200);
+/** Servicios de búsqueda/reserva de la plataforma. */
+const service = z.enum([
+	"hotels",
+	"resorts",
+	"flights",
+	"cars",
+	"activities",
+	"transfers",
+	"cruises"
+]).describe("Servicio de la plataforma");
+const currency = z.string().regex(/^[A-Z]{3}$/, "currency: código ISO 4217 en mayúsculas").describe("Código ISO 4217, p. ej. USD");
+export { service as a, position as i, itemId as n, placement as r, currency as t };

package/dist/{version-Cqps0u2Y.js → version-DPt-j93d.js}

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

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@inspira-npm/events",
-  "version": "0.1.0",
-  "description": "SDK de tracking de eventos de Inspira (ads, cards, mapas, búsquedas) para navegador.",
+  "version": "0.3.0",
+  "description": "SDK de tracking de eventos de Inspira (ads, cards, mapas, búsquedas) para navegador, con helpers de servidor en /server.",
   "license": "UNLICENSED",
   "type": "module",
   "sideEffects": false,
@@ -18,6 +18,10 @@
       "types": "./dist/catalog.d.ts",
       "import": "./dist/catalog.js"
     },
+    "./server": {
+      "types": "./dist/server.d.ts",
+      "import": "./dist/server.js"
+    },
     "./catalog.json": "./dist/catalog.json",
     "./package.json": "./package.json"
   },