@inspira-npm/events 0.0.0-stage → 0.3.0

package/dist/index-BShrVaIU.d.ts

@@ -0,0 +1,203 @@
+import { z } from "zod";
+/**
+ * Quién emite el evento:
+ * - `browser`: el SDK desde el navegador (`tracker.track`).
+ * - `server`: un backend, server-to-server (p. ej. conversiones). El SDK de navegador
+ *   no lo puede emitir: su tipo queda fuera de `BrowserEventName`.
+ */
+type EventSource = "browser" | "server";
+interface EventDefinition<Props extends z.ZodType = z.ZodType, Source extends EventSource = EventSource> {
+  /** Qué significa el evento y CUÁNDO se dispara. Lo leen el backend, el MCP y la skill. */
+  readonly description: string;
+  /** Agrupa eventos para reportes y permisos: `ads`, `cards`, `map`, `search`, … */
+  readonly domain: string;
+  readonly source: Source;
+  /** Versión del SDK que introdujo el evento (o el último cambio de su esquema). */
+  readonly since: string;
+  /** Esquema de `props`. Siempre `z.strictObject`: una prop desconocida es un error. */
+  readonly props: Props;
+}
+/**
+ * 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`.
+ */
+declare const catalog: {
+  conversion: EventDefinition<z.ZodObject<{
+    conversion_id: z.ZodString;
+    type: z.ZodEnum<{
+      booking: "booking";
+      lead: "lead";
+      signup: "signup";
+      purchase: "purchase";
+    }>;
+    service: z.ZodOptional<z.ZodEnum<{
+      hotels: "hotels";
+      resorts: "resorts";
+      flights: "flights";
+      cars: "cars";
+      activities: "activities";
+      transfers: "transfers";
+      cruises: "cruises";
+    }>>;
+    value: z.ZodOptional<z.ZodNumber>;
+    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<{
+      hotels: "hotels";
+      resorts: "resorts";
+      flights: "flights";
+      cars: "cars";
+      activities: "activities";
+      transfers: "transfers";
+      cruises: "cruises";
+    }>;
+    destination: z.ZodOptional<z.ZodObject<{
+      id: z.ZodOptional<z.ZodString>;
+      name: z.ZodOptional<z.ZodString>;
+      type: z.ZodOptional<z.ZodEnum<{
+        city: "city";
+        region: "region";
+        country: "country";
+        hotel: "hotel";
+        airport: "airport";
+        poi: "poi";
+      }>>;
+    }, z.core.$strict>>;
+    origin: z.ZodOptional<z.ZodObject<{
+      id: z.ZodOptional<z.ZodString>;
+      name: z.ZodOptional<z.ZodString>;
+      type: z.ZodOptional<z.ZodEnum<{
+        city: "city";
+        region: "region";
+        country: "country";
+        hotel: "hotel";
+        airport: "airport";
+        poi: "poi";
+      }>>;
+    }, z.core.$strict>>;
+    check_in: z.ZodOptional<z.ZodISODate>;
+    check_out: z.ZodOptional<z.ZodISODate>;
+    rooms: z.ZodOptional<z.ZodInt>;
+    adults: z.ZodOptional<z.ZodInt>;
+    children: z.ZodOptional<z.ZodInt>;
+    results_count: z.ZodOptional<z.ZodInt>;
+    filters: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodArray<z.ZodString>]>>>;
+    sort: z.ZodOptional<z.ZodString>;
+    page: z.ZodOptional<z.ZodInt>;
+  }, z.core.$strict>, "browser">;
+  search_result_click: EventDefinition<z.ZodObject<{
+    search_id: z.ZodUUID;
+    service: z.ZodEnum<{
+      hotels: "hotels";
+      resorts: "resorts";
+      flights: "flights";
+      cars: "cars";
+      activities: "activities";
+      transfers: "transfers";
+      cruises: "cruises";
+    }>;
+    item_id: z.ZodString;
+    position: z.ZodInt;
+    price: z.ZodOptional<z.ZodNumber>;
+    currency: z.ZodOptional<z.ZodString>;
+  }, z.core.$strict>, "browser">;
+  map_marker_click: EventDefinition<z.ZodObject<{
+    placement: z.ZodString;
+    item_type: z.ZodString;
+    item_id: z.ZodString;
+    zoom: z.ZodOptional<z.ZodNumber>;
+  }, z.core.$strict>, "browser">;
+  map_interaction: EventDefinition<z.ZodObject<{
+    placement: z.ZodString;
+    action: z.ZodEnum<{
+      zoom: "zoom";
+      cluster_click: "cluster_click";
+      search_area: "search_area";
+      popup_open: "popup_open";
+      fullscreen: "fullscreen";
+    }>;
+    zoom: z.ZodOptional<z.ZodNumber>;
+  }, z.core.$strict>, "browser">;
+  card_impression: EventDefinition<z.ZodObject<{
+    card_type: z.ZodString;
+    item_id: z.ZodString;
+    placement: z.ZodString;
+    position: z.ZodOptional<z.ZodInt>;
+    list_id: z.ZodOptional<z.ZodString>;
+  }, z.core.$strict>, "browser">;
+  card_click: EventDefinition<z.ZodObject<{
+    action: z.ZodOptional<z.ZodEnum<{
+      map: "map";
+      open: "open";
+      book: "book";
+      favorite: "favorite";
+      share: "share";
+    }>>;
+    card_type: z.ZodString;
+    item_id: z.ZodString;
+    placement: z.ZodString;
+    position: z.ZodOptional<z.ZodInt>;
+    list_id: z.ZodOptional<z.ZodString>;
+  }, z.core.$strict>, "browser">;
+  ad_impression: EventDefinition<z.ZodObject<{
+    ad_id: z.ZodString;
+    ad_type: z.ZodString;
+    placement: z.ZodString;
+    position: z.ZodOptional<z.ZodInt>;
+    campaign_id: z.ZodOptional<z.ZodString>;
+    token: z.ZodOptional<z.ZodString>;
+  }, z.core.$strict>, "browser">;
+  ad_click: EventDefinition<z.ZodObject<{
+    click_id: z.ZodUUID;
+    destination_url: z.ZodOptional<z.ZodString>;
+    ad_id: z.ZodString;
+    ad_type: z.ZodString;
+    placement: z.ZodString;
+    position: z.ZodOptional<z.ZodInt>;
+    campaign_id: z.ZodOptional<z.ZodString>;
+    token: z.ZodOptional<z.ZodString>;
+  }, z.core.$strict>, "browser">;
+  page_view: EventDefinition<z.ZodObject<{
+    page_type: z.ZodOptional<z.ZodString>;
+  }, z.core.$strict>, "browser">;
+};
+type Catalog = typeof catalog;
+type EventName = keyof Catalog;
+/** Eventos que puede emitir el navegador (excluye los `source: "server"`, p. ej. conversiones). */
+type BrowserEventName = { [N in EventName]: Catalog[N]["source"] extends "browser" ? N : never; }[EventName];
+/** Eventos que se miden con `observeImpression` / `useImpression`. */
+type ImpressionEventName = Extract<BrowserEventName, `${string}_impression`>;
+type EventProps<N extends EventName> = z.input<Catalog[N]["props"]>;
+declare function isEventName(name: string): name is EventName;
+/** Valida las props de un evento contra el catálogo (tests, herramientas server-side). */
+declare function validateEventProps(name: string, props: unknown): {
+  success: false;
+  error: string;
+} | {
+  success: true;
+  error?: undefined;
+};
+interface CatalogJson {
+  sdk_version: string;
+  events: Record<string, {
+    description: string;
+    domain: string;
+    source: string;
+    since: string;
+    schema: Record<string, unknown>;
+  }>;
+}
+/** Catálogo serializado como JSON Schema (draft 2020-12) para el backend, el MCP y la skill. */
+declare function toJsonCatalog(): CatalogJson;
+export { EventProps as a, isEventName as c, EventDefinition as d, EventSource as f, EventName as i, toJsonCatalog as l, Catalog as n, ImpressionEventName as o, CatalogJson as r, catalog as s, BrowserEventName as t, validateEventProps as u };

package/dist/index.d.ts

@@ -0,0 +1,202 @@
+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;
+/**
+ * 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.
+ */
+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.
+ * - `unknown`: aún no decidió → igual que `denied`.
+ */
+type ConsentState = "granted" | "denied" | "unknown";
+export declare const DEFAULT_CONSENT_COOKIE = "CookieConsent";
+/** Evento que dispara el banner de inspira-frontend-v2 al guardar el consentimiento. */
+export declare const CONSENT_CHANGE_EVENT = "cookie-consent-change";
+/** Interpreta el valor crudo de la cookie de consentimiento (puede venir URL-encoded). */
+export declare function parseConsentValue(raw: string | null | undefined): ConsentState;
+/**
+ * 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.
+ */
+export declare function cookieConsent(cookieName?: string): () => ConsentState;
+interface EventContext {
+  /** URL sin query, salvo los parámetros de la allowlist (utm_*, ipc, gclid…). */
+  url: string;
+  path: string;
+  /** Solo origin + path del referrer (nunca su query). */
+  referrer: string | null;
+  locale: string | null;
+  tz: string | null;
+  screen: {
+    w: number;
+    h: number;
+  } | null;
+  viewport: {
+    w: number;
+    h: number;
+  } | null;
+}
+/**
+ * Query params que SÍ se conservan en `ctx.url`. El resto se descarta: las URLs pueden
+ * traer tokens, emails o ids de reserva.
+ */
+export declare const DEFAULT_URL_PARAM_ALLOWLIST: string[];
+export declare function sanitizeUrl(href: string, allowlist: readonly string[]): string;
+interface ImpressionOptions {
+  /** Fracción del elemento que debe verse (0–1). Default 0.5 (estándar IAB display). */
+  threshold?: number;
+  /** Tiempo CONTINUO visible, en ms, antes de contar la impresión. Default 1000 (IAB). */
+  minVisibleMs?: number;
+  /** Contar una sola vez por observación (por montaje del componente). Default true. */
+  once?: boolean;
+}
+/**
+ * - `sent`: el collector lo aceptó (o se encoló un beacon, que no da respuesta).
+ * - `retry`: error de red, 429 o 5xx → se reintenta más tarde.
+ * - `drop`: 4xx (payload inválido, site key desconocida) → reintentar no ayuda.
+ */
+type SendResult = "sent" | "retry" | "drop";
+interface TransportOptions {
+  /** La página se está ocultando/cerrando: usar `sendBeacon`, no se espera respuesta. */
+  beacon: boolean;
+  debug: boolean;
+}
+interface Transport {
+  send(url: string, body: string, options: TransportOptions): SendResult | Promise<SendResult>;
+}
+export declare const fetchTransport: Transport;
+interface TrackerConfig {
+  /** Base URL del collector, p. ej. `https://events.inspiratest.com`. */
+  endpoint: string;
+  /** Clave PÚBLICA del sitio: identifica el sitio y su allowlist de orígenes. No es secreta. */
+  siteKey: string;
+  /** Organización/whitelabel del tenant actual. Se puede cambiar luego con `setWl`. */
+  wl?: number | null;
+  /** Estado de consentimiento, evaluado en cada evento. Default: siempre `unknown`. */
+  consent?: () => ConsentState;
+  /** Espera máxima antes de enviar un lote incompleto. Default 5000 ms. */
+  flushIntervalMs?: number;
+  /** Eventos por request. Default 20. */
+  maxBatchSize?: number;
+  /** Eventos en cola como máximo (si el collector no responde se descartan los más viejos). Default 500. */
+  maxQueueSize?: number;
+  /**
+   * Query params que se conservan en `ctx.url` (nombres exactos, sin comodines). Default:
+   * 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). */
+  transport?: Transport;
+}
+/** Un evento tal como viaja al collector (ver docs/protocol.md). */
+interface EventEnvelope {
+  id: string;
+  name: string;
+  /** ISO 8601 del reloj del cliente; el collector guarda además su propia hora de recepción. */
+  ts: string;
+  props: Record<string, unknown>;
+  ctx: EventContext;
+  wl: number | null;
+  consent: ConsentState;
+  anon_id: string | null;
+  session_id: string | null;
+  user_id: string | null;
+}
+interface BatchPayload {
+  sdk: {
+    name: string;
+    version: string;
+  };
+  sent_at: string;
+  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),
+   * después de `shutdown()`, o props no serializables a JSON.
+   */
+  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>`. 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 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 ids guardados. */
+  reset(): void;
+  /** Envía lo que haya en cola. */
+  flush(): Promise<void>;
+  /** Envía lo pendiente por beacon y desconecta listeners/observers. */
+  shutdown(): void;
+}
+export declare function createNoopTracker(): Tracker;
+/**
+ * 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.
+ */
+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.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 };