@magicfeedback/popup-sdk 1.1.8 → 1.3.0

package/dist/index.d.ts

@@ -98,6 +98,12 @@ interface AnalyticsFlushMeta {
      * 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
@@ -110,8 +116,11 @@ type AnalyticsSink = (payload: AnalyticsEnvelope, meta?: AnalyticsFlushMeta) =>
  * 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
@@ -147,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;
@@ -164,6 +181,8 @@ interface FeedbackSinkOptions {
     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`.
@@ -276,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';
@@ -498,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'`). */
@@ -515,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
@@ -548,14 +612,24 @@ 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.
@@ -599,20 +673,55 @@ 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;
     /**
@@ -622,6 +731,7 @@ declare class DeepdotsPopups {
      */
     flushAnalytics(options?: {
         final?: boolean;
+        sessionEnd?: boolean;
     }): void;
     /** Emite un evento `user_engagement` con el tiempo activo acumulado (#8). */
     private flushEngagement;
@@ -737,7 +847,7 @@ declare class ReactNativePopupRenderer implements PopupRenderer {
     private partialEmitted;
     constructor(options?: ReactNativeRendererOptions);
     init(): void;
-    show(surveyId: string, productId: string, _actions: PopupActions | undefined, emit: EmitFn, onClose: () => void, env?: string, userId?: string, style?: PopupStyle, sessionId?: string, miniService?: string, analyticsFeedbackSessionId?: string): void;
+    show(surveyId: string, productId: string, actions: PopupActions | undefined, emit: EmitFn, onClose: () => void, env?: string, userId?: string, style?: PopupStyle, sessionId?: string, miniService?: string, analyticsFeedbackSessionId?: string): void;
     hide(): void;
     /**
      * El host la conecta al `onMessage` del WebView. Traduce los mensajes del survey a
@@ -748,10 +858,13 @@ declare class ReactNativePopupRenderer implements PopupRenderer {
 }
 
 /**
- * Construye un HTML autocontenido que renderiza el survey de `@magicfeedback/native`
- * dentro de un WebView (React Native). Carga el bundle desde CDN, crea el form con la
- * identidad inyectada (`profile`/`metadata`) y reenvía los eventos del survey al host
- * vía el puente de react-native-webview: `window.ReactNativeWebView.postMessage`.
+ * Construye un HTML autocontenido que renderiza el popup (chrome + survey de
+ * `@magicfeedback/native`) dentro de un WebView (React Native). Es el equivalente RN de
+ * `renderPopup.ts` (DOM real, solo navegador): mismo header con botón cerrar, spinner,
+ * footer con back/start/send, gate "Start survey" y colores/logo desde `formData.style`.
+ * Carga el bundle del survey desde CDN, crea el form con la identidad inyectada
+ * (`profile`/`metadata`) y reenvía los eventos al host vía el puente de
+ * react-native-webview: `window.ReactNativeWebView.postMessage`.
  *
  * Mensajes emitidos (JSON `{name, payload}`): `loaded`, `before_submit`, `after_submit`,
  * `survey_completed`, `back`, `popup_close`.
@@ -764,6 +877,9 @@ interface BuildSurveyHtmlOptions {
     metadata?: IdentityAnswer[];
     version?: string;
     font?: PopupFont;
+    theme?: 'light' | 'dark';
+    position?: 'bottom' | 'bottom-right' | 'bottom-left' | 'top' | 'top-right' | 'top-left' | 'center';
+    actions?: PopupActions;
 }
 declare function buildSurveyHtml(opts: BuildSurveyHtmlOptions): string;
 
@@ -815,4 +931,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 };