@inspira-npm/events 0.0.0-stage → 0.1.0

package/dist/catalog.d.ts

@@ -0,0 +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";
+export { BrowserEventName, Catalog, CatalogJson, type EventDefinition, EventName, EventProps, type EventSource, ImpressionEventName, catalog, isEventName, toJsonCatalog, validateEventProps };

package/dist/catalog.js

@@ -0,0 +1,251 @@
+import { n as SDK_VERSION } from "./version-Cqps0u2Y.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"),
+	ad_type: z.string().min(1).max(50).describe("`adType` del engine: resort, hotel, destinations, promotions, banner…"),
+	placement,
+	position: position.optional(),
+	campaign_id: z.string().max(100).optional().describe("Campaña que sirvió el ad, si se conoce"),
+	token: z.string().max(2e3).optional().describe("Token firmado que el engine devuelve con cada ad (cuando exista); valida el evento")
+};
+const adEvents = {
+	ad_impression: defineEvent({
+		domain: "ads",
+		source: "browser",
+		since: "0.1.0",
+		description: "Impresión VISIBLE de un ad: ≥50% del ad en pantalla durante ≥1 s (estándar IAB). Una por ad y montaje.",
+		props: z.strictObject(adProps)
+	}),
+	ad_click: defineEvent({
+		domain: "ads",
+		source: "browser",
+		since: "0.1.0",
+		description: "Click en un ad. `click_id` viaja en la URL de destino (`?ipc=`) para atribuir conversiones.",
+		props: z.strictObject({
+			...adProps,
+			click_id: z.uuid().describe("Id único del click; también va en la URL de destino como ?ipc="),
+			destination_url: z.string().max(2e3).optional().describe("URL a la que lleva el ad")
+		})
+	})
+};
+// src/catalog/events/cards.ts
+const cardProps = {
+	card_type: z.string().min(1).max(50).describe("Qué representa la card: hotel, resort, destination, activity, car, promotion…"),
+	item_id: itemId.describe("Id del ítem que representa la card"),
+	placement,
+	position: position.optional(),
+	list_id: z.string().max(100).optional().describe("Id de la lista o búsqueda que la contiene")
+};
+const cardEvents = {
+	card_impression: defineEvent({
+		domain: "cards",
+		source: "browser",
+		since: "0.1.0",
+		description: "Impresión VISIBLE de una card (≥50% en pantalla durante ≥1 s). Una por card y montaje.",
+		props: z.strictObject(cardProps)
+	}),
+	card_click: defineEvent({
+		domain: "cards",
+		source: "browser",
+		since: "0.1.0",
+		description: "Click en una card o en una de sus acciones.",
+		props: z.strictObject({
+			...cardProps,
+			action: z.enum([
+				"open",
+				"book",
+				"favorite",
+				"share",
+				"map"
+			]).optional().describe("Qué parte de la card se clickeó; sin valor = la card completa (open)")
+		})
+	})
+};
+// src/catalog/events/conversions.ts
+const conversionEvents = { conversion: defineEvent({
+	domain: "conversions",
+	source: "server",
+	since: "0.1.0",
+	description: "Conversión confirmada (reserva, lead, registro). La envía un BACKEND server-to-server, nunca el navegador. Idempotente por `conversion_id`.",
+	props: z.strictObject({
+		conversion_id: z.string().min(1).max(100).describe("Referencia única (n.º de reserva/lead); reenviar el mismo id no duplica"),
+		type: z.enum([
+			"booking",
+			"lead",
+			"signup",
+			"purchase"
+		]).describe("Qué se convirtió: reserva, lead, registro o compra"),
+		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")
+	})
+}) };
+// src/catalog/events/map.ts
+const zoom = z.number().min(0).max(22).describe("Nivel de zoom del mapa al momento del evento");
+const mapEvents = {
+	map_marker_click: defineEvent({
+		domain: "map",
+		source: "browser",
+		since: "0.1.0",
+		description: "Click en un marcador del mapa (hotel, resort, punto de interés…).",
+		props: z.strictObject({
+			placement,
+			item_type: z.string().min(1).max(50).describe("Qué representa el marcador: hotel, resort, poi…"),
+			item_id: itemId.describe("Id del ítem que representa el marcador"),
+			zoom: zoom.optional()
+		})
+	}),
+	map_interaction: defineEvent({
+		domain: "map",
+		source: "browser",
+		since: "0.1.0",
+		description: "Interacción con el mapa que no es click en marcador. No se trackea el paneo (demasiado ruido).",
+		props: z.strictObject({
+			placement,
+			action: z.enum([
+				"zoom",
+				"cluster_click",
+				"search_area",
+				"popup_open",
+				"fullscreen"
+			]).describe("search_area = botón 'buscar en esta zona'"),
+			zoom: zoom.optional()
+		})
+	})
+};
+// src/catalog/events/page.ts
+const pageEvents = { page_view: defineEvent({
+	domain: "page",
+	source: "browser",
+	since: "0.1.0",
+	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.",
+	props: z.strictObject({ page_type: z.string().max(50).optional().describe("Tipo de página estable: home, hotels-srp, hotel-details, checkout, landing…") })
+}) };
+// src/catalog/events/search.ts
+const location = z.strictObject({
+	id: z.string().max(100).optional().describe("Id del destino/origen en el proveedor"),
+	name: z.string().max(200).optional().describe("Nombre de la sugerencia SELECCIONADA"),
+	type: z.enum([
+		"city",
+		"region",
+		"country",
+		"hotel",
+		"airport",
+		"poi"
+	]).optional().describe("Tipo de lugar de la sugerencia")
+}).describe("Destino u origen elegido de las sugerencias");
+const searchId = z.uuid().describe("Id de la búsqueda (generado en el cliente); une resultados y clicks de la misma búsqueda");
+const searchEvents = {
+	search_performed: defineEvent({
+		domain: "search",
+		source: "browser",
+		since: "0.1.0",
+		description: "Búsqueda ejecutada (al recibir resultados). Una por búsqueda; un cambio de filtros que vuelve a buscar es otra.",
+		props: z.strictObject({
+			search_id: searchId,
+			service,
+			destination: location.optional(),
+			origin: location.optional().describe("Solo vuelos/traslados"),
+			check_in: z.iso.date().optional().describe("YYYY-MM-DD (o fecha de salida)"),
+			check_out: z.iso.date().optional().describe("YYYY-MM-DD (o fecha de regreso)"),
+			rooms: z.int().min(1).max(20).optional().describe("Habitaciones pedidas"),
+			adults: z.int().min(0).max(50).optional().describe("Adultos (total de la búsqueda)"),
+			children: z.int().min(0).max(50).optional().describe("Menores (total de la búsqueda)"),
+			results_count: z.int().nonnegative().optional().describe("Resultados devueltos; 0 = sin resultados"),
+			filters: z.record(z.string().max(50), z.union([
+				z.string().max(100),
+				z.number(),
+				z.boolean(),
+				z.array(z.string().max(100)).max(50)
+			])).optional().describe("Filtros activos: { stars: [4,5] → ['4','5'], price_max: 300, all_inclusive: true }"),
+			sort: z.string().max(50).optional().describe("Orden aplicado: price_asc, rating_desc…"),
+			page: z.int().min(1).optional().describe("Página de resultados (1-based)")
+		})
+	}),
+	search_result_click: defineEvent({
+		domain: "search",
+		source: "browser",
+		since: "0.1.0",
+		description: "Click en un resultado de búsqueda.",
+		props: z.strictObject({
+			search_id: searchId,
+			service,
+			item_id: itemId.describe("Id del resultado clickeado (hotel, vuelo, auto…)"),
+			position,
+			price: z.number().nonnegative().optional().describe("Precio mostrado en el resultado"),
+			currency: currency.optional()
+		})
+	})
+};
+// src/catalog/index.ts
+/**
+* Catálogo de eventos: la ÚNICA fuente de verdad de qué eventos existen y qué props llevan.
+* El collector (inspira-promotions-laravel) valida contra `dist/catalog.json`, que se genera
+* de aquí en el build. Para agregar un evento ver `docs/catalog.md`.
+*/
+const catalog = {
+	...pageEvents,
+	...adEvents,
+	...cardEvents,
+	...mapEvents,
+	...searchEvents,
+	...conversionEvents
+};
+function isEventName(name) {
+	return Object.hasOwn(catalog, name);
+}
+/** Valida las props de un evento contra el catálogo (tests, herramientas server-side). */
+function validateEventProps(name, props) {
+	if (!isEventName(name)) return {
+		success: false,
+		error: `unknown event: ${name}`
+	};
+	const result = catalog[name].props.safeParse(props);
+	return result.success ? { success: true } : {
+		success: false,
+		error: z.prettifyError(result.error)
+	};
+}
+/** Catálogo serializado como JSON Schema (draft 2020-12) para el backend, el MCP y la skill. */
+function toJsonCatalog() {
+	const events = {};
+	for (const [name, definition] of Object.entries(catalog)) events[name] = {
+		description: definition.description,
+		domain: definition.domain,
+		source: definition.source,
+		since: definition.since,
+		schema: z.toJSONSchema(definition.props, { io: "input" })
+	};
+	return {
+		sdk_version: SDK_VERSION,
+		events
+	};
+}
+export { catalog, isEventName, toJsonCatalog, validateEventProps };