@magicfeedback/popup-sdk 1.1.7 → 1.2.0

package/README.md

@@ -177,6 +177,11 @@ Config fields:
 - `mode?: 'server' | 'client'`
 - `debug?: boolean`
 - `popups?: PopupDefinition[]`
+- `language?: string` — BCP-47 tag (`'en'`, `'en-US'`, …) used for popup language
+  segmentation (`segments.lang`) and for the analytics context. If omitted it is
+  auto-detected from `navigator.language`, falling back to the `Intl` locale (which is
+  what makes it work in React Native, where `navigator.language` does not exist). If no
+  source resolves a language, popups with `segments.lang` cannot be filtered and are shown.
 
 ### `autoLaunch()`
 

package/dist/index.d.mts

@@ -91,14 +91,36 @@ interface AnalyticsEnvelope {
     };
     events: AnalyticsEvent[];
 }
-type AnalyticsSink = (payload: AnalyticsEnvelope) => void;
+/** Contexto del flush, para que el sink pueda adaptar el transporte. */
+interface AnalyticsFlushMeta {
+    /**
+     * `true` cuando el flush ocurre porque la página/app se está cerrando. El sink debe usar
+     * un transporte que sobreviva al unload (sendBeacon) y no puede esperar respuestas.
+     */
+    final?: boolean;
+    /**
+     * `true` cuando este es el ÚLTIMO lote de la sesión (cierre de página, app a background,
+     * cambio de usuario, tracking desactivado). El sink lo envía con `completed:true` y olvida
+     * el `sessionId`, para que el lote siguiente abra un registro nuevo.
+     */
+    sessionEnd?: boolean;
+}
+/**
+ * Envío del lote. Si devuelve una promesa que **rechaza**, el manager re-encola los
+ * eventos para reintentarlos en el siguiente flush (fallo transitorio: red o 5xx).
+ * Resolver = lote entregado o descartado definitivamente (no se reintenta).
+ */
+type AnalyticsSink = (payload: AnalyticsEnvelope, meta?: AnalyticsFlushMeta) => void | Promise<void>;
 
 /**
  * Mapeo del envelope de analytics → body de `POST /sdk/feedback`.
  *
  * La analítica se envía como un Feedback del modelo del Surveys SDK, agrupado por una
- * INTEGRACIÓN creada en la plataforma. Se manda en streaming con `completed:false` y
- * `finished:false` (nunca se "cierra"); el backend cose por `sessionId` + `user_id`.
+ * INTEGRACIÓN creada en la plataforma. Se manda en streaming con `completed:false`; el
+ * backend cose por `sessionId` + `user_id`. El ÚLTIMO lote de una sesión (cierre de página,
+ * app a background, cambio de usuario) va con `completed:true`: cierra el registro y el
+ * siguiente lote omite el `sessionId` viejo para que el backend abra uno nuevo.
+ * `feedback.finished` se queda siempre en `false` (no es la señal de cierre acordada).
  *
  * Encoding:
  *  - todo va en `feedback.metadata`: contexto (user_id, session_id, platform…) + eventos
@@ -134,7 +156,15 @@ interface AnalyticsFeedbackBody {
     /** sessionId devuelto por el primer POST; permite que el backend agrupe todos los eventos en un solo registro. */
     sessionId?: string;
 }
-declare function buildAnalyticsFeedbackBody(envelope: AnalyticsEnvelope, keys: AnalyticsKeys, feedbackSessionId?: string): AnalyticsFeedbackBody;
+interface BuildBodyOptions {
+    /**
+     * `true` en el último lote de la sesión → `completed:true` (cierra el registro en backend).
+     * El body SÍ lleva el `sessionId` actual (es el registro que se cierra); es el lote
+     * SIGUIENTE el que lo omite.
+     */
+    sessionEnd?: boolean;
+}
+declare function buildAnalyticsFeedbackBody(envelope: AnalyticsEnvelope, keys: AnalyticsKeys, feedbackSessionId?: string, options?: BuildBodyOptions): AnalyticsFeedbackBody;
 interface FeedbackSinkOptions {
     /** Base URL del backend (api(.|-dev.)deepdots.com) ya resuelta por el entorno. */
     baseUrl: string;
@@ -143,15 +173,31 @@ interface FeedbackSinkOptions {
     log?: (...args: unknown[]) => void;
     /** fetch inyectable (tests / RN). */
     fetchImpl?: typeof fetch;
+    /**
+     * `navigator.sendBeacon` inyectable. Solo se usa en el flush final (cierre de página):
+     * sobrevive al unload, a cambio de no poder leer la respuesta. Si no se pasa, el flush
+     * final usa `fetch` con `keepalive`.
+     */
+    sendBeaconImpl?: (url: string, body: Blob | string) => boolean;
     /** Callback invocado cuando el backend devuelve un nuevo sessionId (primer POST). */
     onSessionId?: (id: string) => void;
+    /** Callback invocado al cerrar la sesión (`completed:true`): el sessionId cacheado se olvida. */
+    onSessionReset?: () => void;
 }
 /**
  * Sink real: transforma el envelope y hace `POST {baseUrl}/sdk/feedback`.
- * Fire-and-forget (no bloquea el flush); errores solo se loguean.
- * Stateful: cachea el `sessionId` que devuelve el backend en la primera respuesta
- * y lo envía en los siguientes POSTs para que el backend agrupe todos los eventos
- * en un único registro de feedback.
+ *
+ * Stateful: cachea el `sessionId` que devuelve el backend en la primera respuesta y lo
+ * envía en los siguientes POSTs para que el backend agrupe todos los eventos en un único
+ * registro de feedback.
+ *
+ * Garantías de entrega:
+ *  - mientras no se conozca el `sessionId`, los lotes se **serializan** (esperan la primera
+ *    respuesta): dos POSTs a la vez sin `sessionId` crearían dos registros y partirían los datos;
+ *  - `keepalive` para que el navegador no cancele el POST al navegar fuera, y `sendBeacon`
+ *    en el flush final (cierre de página), donde `fetch` puede morir con el documento;
+ *  - la promesa **rechaza** en fallo transitorio (red, 5xx, 408, 429) para que el
+ *    `AnalyticsManager` re-encole el lote; un 4xx se loguea y se descarta.
  */
 declare function createFeedbackSink(options: FeedbackSinkOptions): AnalyticsSink;
 
@@ -190,9 +236,11 @@ interface DeepdotsInitParams {
     /** Platform used in the analytics envelope. Default is 'web'; in RN pass 'android'/'ios'. */
     platform?: 'web' | 'android' | 'ios';
     /**
-     * BCP-47 language tag for the analytics context (e.g. 'es-ES'). If omitted, the SDK
-     * auto-detects: `navigator.language` on web, or the `Intl` locale as a fallback (works in
-     * React Native with Hermes, where `navigator.language` is absent).
+     * BCP-47 language tag (e.g. 'es-ES') used for the analytics context AND for popup
+     * language segmentation (`segments.lang`). If omitted, the SDK auto-detects:
+     * `navigator.language` on web, or the `Intl` locale as a fallback (works in
+     * React Native with Hermes, where `navigator.language` is absent). If no source
+     * resolves a language, popups with `segments.lang` cannot be filtered and are shown.
      */
     language?: string;
     /** Injectable device info (RN: from react-native-device-info). If missing, it is derived from the browser. */
@@ -247,6 +295,16 @@ interface DeepdotsEvent {
  * Event listener callback
  */
 type EventListener = (event: DeepdotsEvent) => void;
+/**
+ * Motivo del `deepdots_session_end` (último lote de la sesión, enviado con `completed:true`):
+ *  - `page_hide`: la página web se cierra o se navega fuera (`pagehide`).
+ *  - `background`: la app pasa a background (RN/nativo). Única señal disponible en móvil:
+ *    el kill de la app por el usuario o el SO NO produce ningún callback.
+ *  - `user_change`: `setUserId()` o un `init()` con otro `userId` (login/logout del host).
+ *  - `tracking_disabled`: `setTrackingEnabled(false)` (consentimiento revocado).
+ *  - `manual`: `endSession()` llamado por el host.
+ */
+type SessionEndReason = 'page_hide' | 'background' | 'user_change' | 'tracking_disabled' | 'manual';
 /** Trigger type used by remote popup definitions */
 type PopupTriggerType = 'time_on_page' | 'scroll' | 'exit' | 'click' | 'event';
 type PopupTriggerConditionStatus = 'SHOWED' | 'PARTIAL' | 'COMPLETED';
@@ -469,13 +527,16 @@ declare class CrashReporter {
  * el funnel se correlaciona por `message_id` y se agrupa por `message_title`.
  */
 type MessageStage = 'delivered' | 'clicked' | 'converted';
+/** Canales válidos. Un mensaje tiene UN canal: se valida en runtime porque el host puede no ser TS. */
+declare const MESSAGE_CHANNELS: readonly ["push", "in_app"];
+type MessageChannel = (typeof MESSAGE_CHANNELS)[number];
 interface TrackMessageOptions {
     /** Identificador del mensaje/notificación — correlaciona el funnel delivered→clicked→converted. */
     id: string;
     /** Título del mensaje — dimensión de agrupación de #18–22. */
     title: string;
     /** Canal de entrega. */
-    channel: 'push' | 'in_app';
+    channel: MessageChannel;
     /** Nombre de la campaña (opcional). */
     campaign?: string;
     /** Valor de conversión (opcional, típico en `stage: 'converted'`). */
@@ -486,6 +547,38 @@ interface TrackMessageOptions {
 }
 /** Construye los params del evento `deepdots_message` (omite opcionales ausentes). */
 declare function buildMessageParams(stage: MessageStage, o: TrackMessageOptions): Record<string, unknown>;
+/** Techo de `message_id` vigilados por sesión; los más antiguos se evictan (memoria acotada). */
+declare const MAX_TRACKED_MESSAGES = 500;
+type MessageRejectionReason = 'invalid_channel' | 'duplicate_stage' | 'channel_conflict';
+type MessageGuardVerdict = {
+    emit: true;
+} | {
+    emit: false;
+    reason: MessageRejectionReason;
+    detail: string;
+};
+/**
+ * Protege el funnel de Messaging de las formas imposibles que el host puede producir por error
+ * (visto en producción: CTR > 100% por falta de `delivered` + el mismo `message_id` reportado en
+ * dos canales). Tres reglas, todas dentro de la sesión (se reinicia en cada `init()`):
+ *
+ *  1. `channel` fuera de `MESSAGE_CHANNELS` → se descarta el evento.
+ *  2. Un `(message_id, stage)` ya emitido → se emite una sola vez.
+ *  3. Un `message_id` ya visto en un canal → se descartan los eventos de otro canal.
+ *
+ * Los eventos rechazados NO mutan el estado: un rechazo nunca "consume" el stage bueno.
+ * Lo que el SDK no puede arreglar es la ausencia de `delivered`: eso lo instrumenta el host.
+ */
+declare class MessageGuard {
+    private maxTrackedMessages;
+    /** message_id → canal fijado + stages ya emitidos. El orden de inserción marca la eviction. */
+    private seen;
+    constructor(maxTrackedMessages?: number);
+    evaluate(stage: MessageStage, options: TrackMessageOptions): MessageGuardVerdict;
+    /** Olvida todo lo vigilado (nueva sesión). */
+    reset(): void;
+    private remember;
+}
 
 /**
  * Main class for managing survey popups
@@ -519,14 +612,29 @@ declare class DeepdotsPopups {
     private analyticsFlushTimer;
     /** Crash & error reporting (#14–17). Null hasta init(). */
     private crashReporter;
+    /** Protecciones del funnel de Messaging (#18–22). Vigencia de sesión: se reinicia en init(). */
+    private messageGuard;
     /** Observador de navegación (Fase 2): emite page_view por el canal de analytics. */
     private navObserver;
     /** Tiempo activo (engagement time, #8). */
     private engagement;
     /** Atributos internos del usuario identificado → POST /sdk/popups/contact. Null si no hay userId. */
     private contact;
+    /** Storage resuelto en init() (inyectado por el host o localStorage). Reusado al cambiar de usuario. */
+    private storage;
     /** Marca si ya se inició la navegación manual (setScreen) — para RN sin History API. */
     private navStarted;
+    /**
+     * `true` entre `session_start` y `session_end`. Hace idempotente tanto la apertura como
+     * el cierre (p. ej. `visibilitychange` + `pagehide` seguidos) y permite abrir una sesión
+     * nueva al volver a foreground o al conceder el consentimiento más tarde.
+     */
+    private sessionOpen;
+    /**
+     * Idioma resuelto en init() (explícito > navigator.language > Intl). Única fuente de
+     * verdad para el context de analytics Y para la segmentación por idioma de los popups.
+     */
+    private language;
     /** Initialize the SDK with configuration */
     init(config: DeepdotsInitParams): void;
     /** User id actual (generado por el SDK o provisto por el cliente). Null si tracking off. */
@@ -565,24 +673,66 @@ declare class DeepdotsPopups {
     trackFindabilityFriction(frictionTopic: string, params?: Record<string, unknown>): void;
     /** Funnel: un paso del embudo, correlacionado por `taskId`. El backend reconstruye conversión/drop-off/tiempo. */
     trackFunnelStep(funnel: string, step: string, taskId: string, params?: Record<string, unknown>): void;
-    /** Messaging (#18–22): registra una etapa del funnel de una notificación (push/in-app). No-op si tracking off. */
+    /**
+     * Messaging (#18–22): registra una etapa del funnel de una notificación (push/in-app).
+     * No-op si tracking off. El evento se descarta (con warning) si el `channel` no es válido,
+     * si ese `(message_id, stage)` ya se emitió en la sesión, o si el `message_id` ya se reportó
+     * en otro canal — ver `MessageGuard`.
+     */
     trackMessage(stage: MessageStage, options: TrackMessageOptions): void;
     /**
      * Navegación MANUAL (entornos sin History API, p. ej. React Native con React Navigation).
      * El host la llama en cada cambio de pantalla; emite `page_view` al salir de la anterior.
      */
     setScreen(name: string): void;
-    /** App a foreground (RN: AppState 'active'): reanuda el engagement time. */
+    /** App a foreground (RN: AppState 'active'): reanuda el engagement time y abre sesión nueva. */
     onForeground(): void;
     /**
-     * App a background (RN: AppState 'background'): cierra pantalla actual (page_view),
-     * mini-service (mini_service_exit), emite engagement y hace flush del lote.
+     * App a background (RN: AppState 'background'): FIN DE SESIÓN. Cierra pantalla actual
+     * (page_view), mini-services (mini_service_exit), emite engagement + `session_end` y
+     * envía el último lote con `completed:true`.
+     *
+     * Es la única señal disponible en móvil: el kill de la app (swipe) NO da callback.
      */
     onBackground(): void;
+    /**
+     * Cierre EXPLÍCITO de la sesión por parte del host (logout, fin de flujo…): emite
+     * `session_end` y envía el último lote con `completed:true`.
+     */
+    endSession(): void;
+    /**
+     * Cambio de usuario (login / logout / cambio de cuenta). Cierra la sesión del usuario
+     * anterior (`session_end` con `reason: 'user_change'` + `completed:true`), cambia la
+     * identidad y abre una sesión nueva. Sin `userId` vuelve al id anónimo del SDK.
+     *
+     * Equivale a llamar a `init()` otra vez con otro `userId`.
+     */
+    setUserId(userId?: string): void;
+    /**
+     * Cierra la sesión actual: vuelca todo lo que quedaba abierto y envía el último lote
+     * marcado con `completed:true`, para que el backend cierre el registro. El `sessionId`
+     * cacheado se olvida → el lote siguiente abre un registro nuevo.
+     *
+     * Idempotente: dos cierres seguidos (p. ej. `visibilitychange` + `pagehide`) no duplican
+     * el `session_end`.
+     */
+    private closeSession;
+    /**
+     * Abre sesión (`session_start`) si no hay una abierta y el tracking está activo. Idempotente:
+     * se llama en init(), al volver a foreground y al conceder el consentimiento.
+     */
+    private openSession;
     /** Payload que se ENVIARÍA al endpoint de analytics (no envía ni vacía el buffer). */
     previewAnalytics(): AnalyticsEnvelope;
-    /** Envía (hoy dry-run → console.log) el lote acumulado de analytics y vacía el buffer. */
-    flushAnalytics(): void;
+    /**
+     * Envía el lote acumulado de analytics y vacía el buffer.
+     * `final: true` (cierre de página/app) cambia el transporte a `sendBeacon`, que sobrevive
+     * al unload; un lote que falle por red o 5xx se re-encola para el siguiente flush.
+     */
+    flushAnalytics(options?: {
+        final?: boolean;
+        sessionEnd?: boolean;
+    }): void;
     /** Emite un evento `user_engagement` con el tiempo activo acumulado (#8). */
     private flushEngagement;
     private analyticsIdentity;
@@ -775,4 +925,4 @@ declare function collectRnDevice(d: DeviceInfoLike): DeviceInfo;
  */
 declare function setupReactNative(sdk: DeepdotsPopups, config: DeepdotsInitParams, deps?: ReactNativeSetupDeps): () => void;
 
-export { type AnalyticsFeedbackBody, type AnalyticsKeys, type AppStateLike, BrowserPopupRenderer, type ContactAttributeValue, type ContactAttributes, type ContactBody, ContactManager, type CrashRecord, CrashReporter, type CrashSeverity, type DeepdotsConfig, type DeepdotsEvent, type DeepdotsEventType, type DeepdotsInitParams, type DeepdotsLogger, DeepdotsPopups, type DeviceInfo, type DeviceInfoLike, type DeviceSnapshot, type EventListener, type FeedbackKV, InMemoryStorage, type KeyValueStorage, type MessageStage, type MmkvLike, NoopPopupRenderer, POPUP_TRIGGER_CONDITION_STATUSES, type PopupDefinition, type PopupRenderer, type PopupTrigger, type PopupTriggerCondition, type PopupTriggerConditionStatus, type ReactNativeErrorUtils, ReactNativePopupRenderer, type ReactNativeRendererOptions, type ReactNativeSetupDeps, type ReactNativeSurveyPayload, type ReportErrorOptions, type TrackMessageOptions, type TriggerConfig, buildAnalyticsFeedbackBody, buildMessageParams, buildSurveyHtml, collectRnDevice, crashRecordToParams, createDefaultRenderer, createFeedbackSink, mmkvStorage, setupReactNative };
+export { type AnalyticsFeedbackBody, type AnalyticsKeys, type AppStateLike, BrowserPopupRenderer, type BuildBodyOptions, type ContactAttributeValue, type ContactAttributes, type ContactBody, ContactManager, type CrashRecord, CrashReporter, type CrashSeverity, type DeepdotsConfig, type DeepdotsEvent, type DeepdotsEventType, type DeepdotsInitParams, type DeepdotsLogger, DeepdotsPopups, type DeviceInfo, type DeviceInfoLike, type DeviceSnapshot, type EventListener, type FeedbackKV, InMemoryStorage, type KeyValueStorage, MAX_TRACKED_MESSAGES, MESSAGE_CHANNELS, type MessageChannel, MessageGuard, type MessageGuardVerdict, type MessageRejectionReason, type MessageStage, type MmkvLike, NoopPopupRenderer, POPUP_TRIGGER_CONDITION_STATUSES, type PopupDefinition, type PopupRenderer, type PopupTrigger, type PopupTriggerCondition, type PopupTriggerConditionStatus, type ReactNativeErrorUtils, ReactNativePopupRenderer, type ReactNativeRendererOptions, type ReactNativeSetupDeps, type ReactNativeSurveyPayload, type ReportErrorOptions, type SessionEndReason, type TrackMessageOptions, type TriggerConfig, buildAnalyticsFeedbackBody, buildMessageParams, buildSurveyHtml, collectRnDevice, crashRecordToParams, createDefaultRenderer, createFeedbackSink, mmkvStorage, setupReactNative };

package/dist/index.d.ts

@@ -91,14 +91,36 @@ interface AnalyticsEnvelope {
     };
     events: AnalyticsEvent[];
 }
-type AnalyticsSink = (payload: AnalyticsEnvelope) => void;
+/** Contexto del flush, para que el sink pueda adaptar el transporte. */
+interface AnalyticsFlushMeta {
+    /**
+     * `true` cuando el flush ocurre porque la página/app se está cerrando. El sink debe usar
+     * un transporte que sobreviva al unload (sendBeacon) y no puede esperar respuestas.
+     */
+    final?: boolean;
+    /**
+     * `true` cuando este es el ÚLTIMO lote de la sesión (cierre de página, app a background,
+     * cambio de usuario, tracking desactivado). El sink lo envía con `completed:true` y olvida
+     * el `sessionId`, para que el lote siguiente abra un registro nuevo.
+     */
+    sessionEnd?: boolean;
+}
+/**
+ * Envío del lote. Si devuelve una promesa que **rechaza**, el manager re-encola los
+ * eventos para reintentarlos en el siguiente flush (fallo transitorio: red o 5xx).
+ * Resolver = lote entregado o descartado definitivamente (no se reintenta).
+ */
+type AnalyticsSink = (payload: AnalyticsEnvelope, meta?: AnalyticsFlushMeta) => void | Promise<void>;
 
 /**
  * Mapeo del envelope de analytics → body de `POST /sdk/feedback`.
  *
  * La analítica se envía como un Feedback del modelo del Surveys SDK, agrupado por una
- * INTEGRACIÓN creada en la plataforma. Se manda en streaming con `completed:false` y
- * `finished:false` (nunca se "cierra"); el backend cose por `sessionId` + `user_id`.
+ * INTEGRACIÓN creada en la plataforma. Se manda en streaming con `completed:false`; el
+ * backend cose por `sessionId` + `user_id`. El ÚLTIMO lote de una sesión (cierre de página,
+ * app a background, cambio de usuario) va con `completed:true`: cierra el registro y el
+ * siguiente lote omite el `sessionId` viejo para que el backend abra uno nuevo.
+ * `feedback.finished` se queda siempre en `false` (no es la señal de cierre acordada).
  *
  * Encoding:
  *  - todo va en `feedback.metadata`: contexto (user_id, session_id, platform…) + eventos
@@ -134,7 +156,15 @@ interface AnalyticsFeedbackBody {
     /** sessionId devuelto por el primer POST; permite que el backend agrupe todos los eventos en un solo registro. */
     sessionId?: string;
 }
-declare function buildAnalyticsFeedbackBody(envelope: AnalyticsEnvelope, keys: AnalyticsKeys, feedbackSessionId?: string): AnalyticsFeedbackBody;
+interface BuildBodyOptions {
+    /**
+     * `true` en el último lote de la sesión → `completed:true` (cierra el registro en backend).
+     * El body SÍ lleva el `sessionId` actual (es el registro que se cierra); es el lote
+     * SIGUIENTE el que lo omite.
+     */
+    sessionEnd?: boolean;
+}
+declare function buildAnalyticsFeedbackBody(envelope: AnalyticsEnvelope, keys: AnalyticsKeys, feedbackSessionId?: string, options?: BuildBodyOptions): AnalyticsFeedbackBody;
 interface FeedbackSinkOptions {
     /** Base URL del backend (api(.|-dev.)deepdots.com) ya resuelta por el entorno. */
     baseUrl: string;
@@ -143,15 +173,31 @@ interface FeedbackSinkOptions {
     log?: (...args: unknown[]) => void;
     /** fetch inyectable (tests / RN). */
     fetchImpl?: typeof fetch;
+    /**
+     * `navigator.sendBeacon` inyectable. Solo se usa en el flush final (cierre de página):
+     * sobrevive al unload, a cambio de no poder leer la respuesta. Si no se pasa, el flush
+     * final usa `fetch` con `keepalive`.
+     */
+    sendBeaconImpl?: (url: string, body: Blob | string) => boolean;
     /** Callback invocado cuando el backend devuelve un nuevo sessionId (primer POST). */
     onSessionId?: (id: string) => void;
+    /** Callback invocado al cerrar la sesión (`completed:true`): el sessionId cacheado se olvida. */
+    onSessionReset?: () => void;
 }
 /**
  * Sink real: transforma el envelope y hace `POST {baseUrl}/sdk/feedback`.
- * Fire-and-forget (no bloquea el flush); errores solo se loguean.
- * Stateful: cachea el `sessionId` que devuelve el backend en la primera respuesta
- * y lo envía en los siguientes POSTs para que el backend agrupe todos los eventos
- * en un único registro de feedback.
+ *
+ * Stateful: cachea el `sessionId` que devuelve el backend en la primera respuesta y lo
+ * envía en los siguientes POSTs para que el backend agrupe todos los eventos en un único
+ * registro de feedback.
+ *
+ * Garantías de entrega:
+ *  - mientras no se conozca el `sessionId`, los lotes se **serializan** (esperan la primera
+ *    respuesta): dos POSTs a la vez sin `sessionId` crearían dos registros y partirían los datos;
+ *  - `keepalive` para que el navegador no cancele el POST al navegar fuera, y `sendBeacon`
+ *    en el flush final (cierre de página), donde `fetch` puede morir con el documento;
+ *  - la promesa **rechaza** en fallo transitorio (red, 5xx, 408, 429) para que el
+ *    `AnalyticsManager` re-encole el lote; un 4xx se loguea y se descarta.
  */
 declare function createFeedbackSink(options: FeedbackSinkOptions): AnalyticsSink;
 
@@ -190,9 +236,11 @@ interface DeepdotsInitParams {
     /** Platform used in the analytics envelope. Default is 'web'; in RN pass 'android'/'ios'. */
     platform?: 'web' | 'android' | 'ios';
     /**
-     * BCP-47 language tag for the analytics context (e.g. 'es-ES'). If omitted, the SDK
-     * auto-detects: `navigator.language` on web, or the `Intl` locale as a fallback (works in
-     * React Native with Hermes, where `navigator.language` is absent).
+     * BCP-47 language tag (e.g. 'es-ES') used for the analytics context AND for popup
+     * language segmentation (`segments.lang`). If omitted, the SDK auto-detects:
+     * `navigator.language` on web, or the `Intl` locale as a fallback (works in
+     * React Native with Hermes, where `navigator.language` is absent). If no source
+     * resolves a language, popups with `segments.lang` cannot be filtered and are shown.
      */
     language?: string;
     /** Injectable device info (RN: from react-native-device-info). If missing, it is derived from the browser. */
@@ -247,6 +295,16 @@ interface DeepdotsEvent {
  * Event listener callback
  */
 type EventListener = (event: DeepdotsEvent) => void;
+/**
+ * Motivo del `deepdots_session_end` (último lote de la sesión, enviado con `completed:true`):
+ *  - `page_hide`: la página web se cierra o se navega fuera (`pagehide`).
+ *  - `background`: la app pasa a background (RN/nativo). Única señal disponible en móvil:
+ *    el kill de la app por el usuario o el SO NO produce ningún callback.
+ *  - `user_change`: `setUserId()` o un `init()` con otro `userId` (login/logout del host).
+ *  - `tracking_disabled`: `setTrackingEnabled(false)` (consentimiento revocado).
+ *  - `manual`: `endSession()` llamado por el host.
+ */
+type SessionEndReason = 'page_hide' | 'background' | 'user_change' | 'tracking_disabled' | 'manual';
 /** Trigger type used by remote popup definitions */
 type PopupTriggerType = 'time_on_page' | 'scroll' | 'exit' | 'click' | 'event';
 type PopupTriggerConditionStatus = 'SHOWED' | 'PARTIAL' | 'COMPLETED';
@@ -469,13 +527,16 @@ declare class CrashReporter {
  * el funnel se correlaciona por `message_id` y se agrupa por `message_title`.
  */
 type MessageStage = 'delivered' | 'clicked' | 'converted';
+/** Canales válidos. Un mensaje tiene UN canal: se valida en runtime porque el host puede no ser TS. */
+declare const MESSAGE_CHANNELS: readonly ["push", "in_app"];
+type MessageChannel = (typeof MESSAGE_CHANNELS)[number];
 interface TrackMessageOptions {
     /** Identificador del mensaje/notificación — correlaciona el funnel delivered→clicked→converted. */
     id: string;
     /** Título del mensaje — dimensión de agrupación de #18–22. */
     title: string;
     /** Canal de entrega. */
-    channel: 'push' | 'in_app';
+    channel: MessageChannel;
     /** Nombre de la campaña (opcional). */
     campaign?: string;
     /** Valor de conversión (opcional, típico en `stage: 'converted'`). */
@@ -486,6 +547,38 @@ interface TrackMessageOptions {
 }
 /** Construye los params del evento `deepdots_message` (omite opcionales ausentes). */
 declare function buildMessageParams(stage: MessageStage, o: TrackMessageOptions): Record<string, unknown>;
+/** Techo de `message_id` vigilados por sesión; los más antiguos se evictan (memoria acotada). */
+declare const MAX_TRACKED_MESSAGES = 500;
+type MessageRejectionReason = 'invalid_channel' | 'duplicate_stage' | 'channel_conflict';
+type MessageGuardVerdict = {
+    emit: true;
+} | {
+    emit: false;
+    reason: MessageRejectionReason;
+    detail: string;
+};
+/**
+ * Protege el funnel de Messaging de las formas imposibles que el host puede producir por error
+ * (visto en producción: CTR > 100% por falta de `delivered` + el mismo `message_id` reportado en
+ * dos canales). Tres reglas, todas dentro de la sesión (se reinicia en cada `init()`):
+ *
+ *  1. `channel` fuera de `MESSAGE_CHANNELS` → se descarta el evento.
+ *  2. Un `(message_id, stage)` ya emitido → se emite una sola vez.
+ *  3. Un `message_id` ya visto en un canal → se descartan los eventos de otro canal.
+ *
+ * Los eventos rechazados NO mutan el estado: un rechazo nunca "consume" el stage bueno.
+ * Lo que el SDK no puede arreglar es la ausencia de `delivered`: eso lo instrumenta el host.
+ */
+declare class MessageGuard {
+    private maxTrackedMessages;
+    /** message_id → canal fijado + stages ya emitidos. El orden de inserción marca la eviction. */
+    private seen;
+    constructor(maxTrackedMessages?: number);
+    evaluate(stage: MessageStage, options: TrackMessageOptions): MessageGuardVerdict;
+    /** Olvida todo lo vigilado (nueva sesión). */
+    reset(): void;
+    private remember;
+}
 
 /**
  * Main class for managing survey popups
@@ -519,14 +612,29 @@ declare class DeepdotsPopups {
     private analyticsFlushTimer;
     /** Crash & error reporting (#14–17). Null hasta init(). */
     private crashReporter;
+    /** Protecciones del funnel de Messaging (#18–22). Vigencia de sesión: se reinicia en init(). */
+    private messageGuard;
     /** Observador de navegación (Fase 2): emite page_view por el canal de analytics. */
     private navObserver;
     /** Tiempo activo (engagement time, #8). */
     private engagement;
     /** Atributos internos del usuario identificado → POST /sdk/popups/contact. Null si no hay userId. */
     private contact;
+    /** Storage resuelto en init() (inyectado por el host o localStorage). Reusado al cambiar de usuario. */
+    private storage;
     /** Marca si ya se inició la navegación manual (setScreen) — para RN sin History API. */
     private navStarted;
+    /**
+     * `true` entre `session_start` y `session_end`. Hace idempotente tanto la apertura como
+     * el cierre (p. ej. `visibilitychange` + `pagehide` seguidos) y permite abrir una sesión
+     * nueva al volver a foreground o al conceder el consentimiento más tarde.
+     */
+    private sessionOpen;
+    /**
+     * Idioma resuelto en init() (explícito > navigator.language > Intl). Única fuente de
+     * verdad para el context de analytics Y para la segmentación por idioma de los popups.
+     */
+    private language;
     /** Initialize the SDK with configuration */
     init(config: DeepdotsInitParams): void;
     /** User id actual (generado por el SDK o provisto por el cliente). Null si tracking off. */
@@ -565,24 +673,66 @@ declare class DeepdotsPopups {
     trackFindabilityFriction(frictionTopic: string, params?: Record<string, unknown>): void;
     /** Funnel: un paso del embudo, correlacionado por `taskId`. El backend reconstruye conversión/drop-off/tiempo. */
     trackFunnelStep(funnel: string, step: string, taskId: string, params?: Record<string, unknown>): void;
-    /** Messaging (#18–22): registra una etapa del funnel de una notificación (push/in-app). No-op si tracking off. */
+    /**
+     * Messaging (#18–22): registra una etapa del funnel de una notificación (push/in-app).
+     * No-op si tracking off. El evento se descarta (con warning) si el `channel` no es válido,
+     * si ese `(message_id, stage)` ya se emitió en la sesión, o si el `message_id` ya se reportó
+     * en otro canal — ver `MessageGuard`.
+     */
     trackMessage(stage: MessageStage, options: TrackMessageOptions): void;
     /**
      * Navegación MANUAL (entornos sin History API, p. ej. React Native con React Navigation).
      * El host la llama en cada cambio de pantalla; emite `page_view` al salir de la anterior.
      */
     setScreen(name: string): void;
-    /** App a foreground (RN: AppState 'active'): reanuda el engagement time. */
+    /** App a foreground (RN: AppState 'active'): reanuda el engagement time y abre sesión nueva. */
     onForeground(): void;
     /**
-     * App a background (RN: AppState 'background'): cierra pantalla actual (page_view),
-     * mini-service (mini_service_exit), emite engagement y hace flush del lote.
+     * App a background (RN: AppState 'background'): FIN DE SESIÓN. Cierra pantalla actual
+     * (page_view), mini-services (mini_service_exit), emite engagement + `session_end` y
+     * envía el último lote con `completed:true`.
+     *
+     * Es la única señal disponible en móvil: el kill de la app (swipe) NO da callback.
      */
     onBackground(): void;
+    /**
+     * Cierre EXPLÍCITO de la sesión por parte del host (logout, fin de flujo…): emite
+     * `session_end` y envía el último lote con `completed:true`.
+     */
+    endSession(): void;
+    /**
+     * Cambio de usuario (login / logout / cambio de cuenta). Cierra la sesión del usuario
+     * anterior (`session_end` con `reason: 'user_change'` + `completed:true`), cambia la
+     * identidad y abre una sesión nueva. Sin `userId` vuelve al id anónimo del SDK.
+     *
+     * Equivale a llamar a `init()` otra vez con otro `userId`.
+     */
+    setUserId(userId?: string): void;
+    /**
+     * Cierra la sesión actual: vuelca todo lo que quedaba abierto y envía el último lote
+     * marcado con `completed:true`, para que el backend cierre el registro. El `sessionId`
+     * cacheado se olvida → el lote siguiente abre un registro nuevo.
+     *
+     * Idempotente: dos cierres seguidos (p. ej. `visibilitychange` + `pagehide`) no duplican
+     * el `session_end`.
+     */
+    private closeSession;
+    /**
+     * Abre sesión (`session_start`) si no hay una abierta y el tracking está activo. Idempotente:
+     * se llama en init(), al volver a foreground y al conceder el consentimiento.
+     */
+    private openSession;
     /** Payload que se ENVIARÍA al endpoint de analytics (no envía ni vacía el buffer). */
     previewAnalytics(): AnalyticsEnvelope;
-    /** Envía (hoy dry-run → console.log) el lote acumulado de analytics y vacía el buffer. */
-    flushAnalytics(): void;
+    /**
+     * Envía el lote acumulado de analytics y vacía el buffer.
+     * `final: true` (cierre de página/app) cambia el transporte a `sendBeacon`, que sobrevive
+     * al unload; un lote que falle por red o 5xx se re-encola para el siguiente flush.
+     */
+    flushAnalytics(options?: {
+        final?: boolean;
+        sessionEnd?: boolean;
+    }): void;
     /** Emite un evento `user_engagement` con el tiempo activo acumulado (#8). */
     private flushEngagement;
     private analyticsIdentity;
@@ -775,4 +925,4 @@ declare function collectRnDevice(d: DeviceInfoLike): DeviceInfo;
  */
 declare function setupReactNative(sdk: DeepdotsPopups, config: DeepdotsInitParams, deps?: ReactNativeSetupDeps): () => void;
 
-export { type AnalyticsFeedbackBody, type AnalyticsKeys, type AppStateLike, BrowserPopupRenderer, type ContactAttributeValue, type ContactAttributes, type ContactBody, ContactManager, type CrashRecord, CrashReporter, type CrashSeverity, type DeepdotsConfig, type DeepdotsEvent, type DeepdotsEventType, type DeepdotsInitParams, type DeepdotsLogger, DeepdotsPopups, type DeviceInfo, type DeviceInfoLike, type DeviceSnapshot, type EventListener, type FeedbackKV, InMemoryStorage, type KeyValueStorage, type MessageStage, type MmkvLike, NoopPopupRenderer, POPUP_TRIGGER_CONDITION_STATUSES, type PopupDefinition, type PopupRenderer, type PopupTrigger, type PopupTriggerCondition, type PopupTriggerConditionStatus, type ReactNativeErrorUtils, ReactNativePopupRenderer, type ReactNativeRendererOptions, type ReactNativeSetupDeps, type ReactNativeSurveyPayload, type ReportErrorOptions, type TrackMessageOptions, type TriggerConfig, buildAnalyticsFeedbackBody, buildMessageParams, buildSurveyHtml, collectRnDevice, crashRecordToParams, createDefaultRenderer, createFeedbackSink, mmkvStorage, setupReactNative };
+export { type AnalyticsFeedbackBody, type AnalyticsKeys, type AppStateLike, BrowserPopupRenderer, type BuildBodyOptions, type ContactAttributeValue, type ContactAttributes, type ContactBody, ContactManager, type CrashRecord, CrashReporter, type CrashSeverity, type DeepdotsConfig, type DeepdotsEvent, type DeepdotsEventType, type DeepdotsInitParams, type DeepdotsLogger, DeepdotsPopups, type DeviceInfo, type DeviceInfoLike, type DeviceSnapshot, type EventListener, type FeedbackKV, InMemoryStorage, type KeyValueStorage, MAX_TRACKED_MESSAGES, MESSAGE_CHANNELS, type MessageChannel, MessageGuard, type MessageGuardVerdict, type MessageRejectionReason, type MessageStage, type MmkvLike, NoopPopupRenderer, POPUP_TRIGGER_CONDITION_STATUSES, type PopupDefinition, type PopupRenderer, type PopupTrigger, type PopupTriggerCondition, type PopupTriggerConditionStatus, type ReactNativeErrorUtils, ReactNativePopupRenderer, type ReactNativeRendererOptions, type ReactNativeSetupDeps, type ReactNativeSurveyPayload, type ReportErrorOptions, type SessionEndReason, type TrackMessageOptions, type TriggerConfig, buildAnalyticsFeedbackBody, buildMessageParams, buildSurveyHtml, collectRnDevice, crashRecordToParams, createDefaultRenderer, createFeedbackSink, mmkvStorage, setupReactNative };