@magicfeedback/popup-sdk 1.9.0 → 1.11.0

package/dist/index.d.mts

@@ -188,6 +188,11 @@ interface FeedbackSinkOptions {
      * romper a quien lo pase.
      */
     sendBeaconImpl?: (url: string, body: Blob | string) => boolean;
+    /**
+     * Registro en el que seguir desde el primer lote: el de una sesión suspendida por un
+     * `pagehide` y reanudada tras recargar la página (ver `suspended-session.ts`).
+     */
+    initialSessionId?: string;
     /** 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. */
@@ -708,6 +713,14 @@ declare class DeepdotsPopups {
     private popupContainer;
     private popupDefinitions;
     private popupsLoaded;
+    /**
+     * `true` mientras el `GET /sdk/{apiKey}/popups` de `init()` está en vuelo. En esa ventana los
+     * disparos del host (`triggerEvent`, `triggerSurvey`) no tienen contra qué evaluarse, así que
+     * se guardan en `pendingTriggers` y se reproducen al cargar. Click, scroll, time y exit no
+     * hacen falta: son listeners que `autoLaunch` instala ya con las definiciones cargadas.
+     */
+    private awaitingPopups;
+    private pendingTriggers;
     private pendingAutoLaunch;
     private answeredSurveys;
     private surveyProgress;
@@ -756,6 +769,13 @@ declare class DeepdotsPopups {
     private lastEngagementAt;
     /** Cuándo se ocultó la pestaña por última vez (ms epoch); null si está visible. */
     private hiddenAt;
+    /**
+     * Sesión suspendida por un `pagehide` (ms epoch y `deepdots_user_id`); null si no hay.
+     * `openSession` la reanuda si sigue a tiempo (ver ANALYTICS_RESUME_WINDOW_MS).
+     */
+    private suspended;
+    /** Integración de analytics del init: la sesión suspendida solo la hereda la misma. */
+    private analyticsIntegration;
     /**
      * 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.
@@ -898,6 +918,31 @@ declare class DeepdotsPopups {
      *  - Más: ya la cerró el backend → se descarta sin enviar nada.
      */
     private onDocumentVisible;
+    /**
+     * `pagehide` en web: SUSPENDE la sesión en vez de cerrarla, porque el navegador lo lanza
+     * igual al recargar que al cerrar la pestaña. Vuelca lo pendiente (page_view de la
+     * pantalla, mini-services, engagement) con un `deepdots_session_suspend` y SIN
+     * `completed`, y deja el registro en `sessionStorage` (ver `suspended-session.ts`):
+     *  - si la página vuelve a cargar en esta pestaña, `init()` sigue en el mismo registro;
+     *  - si la pestaña se cerró, el backend lo cierra a los pocos minutos sin otro lote.
+     *
+     * Devuelve false cuando no se puede suspender — aún no se conoce el registro (el primer
+     * POST sigue en vuelo) o no hay `sessionStorage` — y entonces el caller cierra como antes.
+     */
+    private suspendSession;
+    /**
+     * Recoge la sesión que dejó suspendida la carga anterior de esta pestaña (ver
+     * `suspendSession`). Solo con analytics configurado y el tracking activo: sin ellos no hay
+     * registro en el que seguir.
+     */
+    private readResumableSession;
+    /**
+     * Consume la sesión suspendida al abrir: los ms que estuvo suspendida si se puede seguir en
+     * ella (mismo usuario, dentro de ANALYTICS_RESUME_WINDOW_MS); null si no había o ya no toca.
+     * En ese caso se olvida su registro sin enviar nada: lo cierra el backend, y la sesión que
+     * se abre ahora va a uno nuevo.
+     */
+    private takeSuspendedSession;
     /** Olvida la sesión abierta sin enviar nada (ver onDocumentVisible). */
     private discardSession;
     /**
@@ -923,6 +968,17 @@ declare class DeepdotsPopups {
     triggerSurvey(surveyId: string, popupId?: string): void;
     /** Trigger popups configured with trigger.type = 'event' and matching trigger.value */
     triggerEvent(eventName: string): void;
+    private evaluateEvent;
+    /**
+     * Guarda `trigger` si las definiciones aún no han llegado. Devuelve `true` si lo guardó (el
+     * llamador no debe evaluarlo ahora) y `false` si no hay carga en vuelo (se evalúa ya, como
+     * siempre: tras cargar, tras un fallo o sin apiKey).
+     */
+    private bufferIfAwaitingPopups;
+    /** La carga falló: sin definiciones no hay nada que reproducir, se descarta todo. */
+    private dropPendingTriggers;
+    /** Reproduce en orden por la evaluación normal (segmentos, cooldowns y condiciones de AHORA). */
+    private replayPendingTriggers;
     private showDefinition;
     private shouldShow;
     private matchesSegmentsLang;
@@ -961,7 +1017,7 @@ declare class DeepdotsPopups {
     private removeDeferredExitPopup;
     private getDeferredExitQueue;
     private setDeferredExitQueue;
-    /** Fetch al servidor para obtener popups */
+    /** Fetch al servidor para obtener popups. `null` si la carga falló (red, no-2xx, payload inválido). */
     private fetchPopupsFromServer;
     /** Envía los atributos de contact a la API (`POST /sdk/popups/contact`). */
     private postContact;

package/dist/index.d.ts

@@ -188,6 +188,11 @@ interface FeedbackSinkOptions {
      * romper a quien lo pase.
      */
     sendBeaconImpl?: (url: string, body: Blob | string) => boolean;
+    /**
+     * Registro en el que seguir desde el primer lote: el de una sesión suspendida por un
+     * `pagehide` y reanudada tras recargar la página (ver `suspended-session.ts`).
+     */
+    initialSessionId?: string;
     /** 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. */
@@ -708,6 +713,14 @@ declare class DeepdotsPopups {
     private popupContainer;
     private popupDefinitions;
     private popupsLoaded;
+    /**
+     * `true` mientras el `GET /sdk/{apiKey}/popups` de `init()` está en vuelo. En esa ventana los
+     * disparos del host (`triggerEvent`, `triggerSurvey`) no tienen contra qué evaluarse, así que
+     * se guardan en `pendingTriggers` y se reproducen al cargar. Click, scroll, time y exit no
+     * hacen falta: son listeners que `autoLaunch` instala ya con las definiciones cargadas.
+     */
+    private awaitingPopups;
+    private pendingTriggers;
     private pendingAutoLaunch;
     private answeredSurveys;
     private surveyProgress;
@@ -756,6 +769,13 @@ declare class DeepdotsPopups {
     private lastEngagementAt;
     /** Cuándo se ocultó la pestaña por última vez (ms epoch); null si está visible. */
     private hiddenAt;
+    /**
+     * Sesión suspendida por un `pagehide` (ms epoch y `deepdots_user_id`); null si no hay.
+     * `openSession` la reanuda si sigue a tiempo (ver ANALYTICS_RESUME_WINDOW_MS).
+     */
+    private suspended;
+    /** Integración de analytics del init: la sesión suspendida solo la hereda la misma. */
+    private analyticsIntegration;
     /**
      * 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.
@@ -898,6 +918,31 @@ declare class DeepdotsPopups {
      *  - Más: ya la cerró el backend → se descarta sin enviar nada.
      */
     private onDocumentVisible;
+    /**
+     * `pagehide` en web: SUSPENDE la sesión en vez de cerrarla, porque el navegador lo lanza
+     * igual al recargar que al cerrar la pestaña. Vuelca lo pendiente (page_view de la
+     * pantalla, mini-services, engagement) con un `deepdots_session_suspend` y SIN
+     * `completed`, y deja el registro en `sessionStorage` (ver `suspended-session.ts`):
+     *  - si la página vuelve a cargar en esta pestaña, `init()` sigue en el mismo registro;
+     *  - si la pestaña se cerró, el backend lo cierra a los pocos minutos sin otro lote.
+     *
+     * Devuelve false cuando no se puede suspender — aún no se conoce el registro (el primer
+     * POST sigue en vuelo) o no hay `sessionStorage` — y entonces el caller cierra como antes.
+     */
+    private suspendSession;
+    /**
+     * Recoge la sesión que dejó suspendida la carga anterior de esta pestaña (ver
+     * `suspendSession`). Solo con analytics configurado y el tracking activo: sin ellos no hay
+     * registro en el que seguir.
+     */
+    private readResumableSession;
+    /**
+     * Consume la sesión suspendida al abrir: los ms que estuvo suspendida si se puede seguir en
+     * ella (mismo usuario, dentro de ANALYTICS_RESUME_WINDOW_MS); null si no había o ya no toca.
+     * En ese caso se olvida su registro sin enviar nada: lo cierra el backend, y la sesión que
+     * se abre ahora va a uno nuevo.
+     */
+    private takeSuspendedSession;
     /** Olvida la sesión abierta sin enviar nada (ver onDocumentVisible). */
     private discardSession;
     /**
@@ -923,6 +968,17 @@ declare class DeepdotsPopups {
     triggerSurvey(surveyId: string, popupId?: string): void;
     /** Trigger popups configured with trigger.type = 'event' and matching trigger.value */
     triggerEvent(eventName: string): void;
+    private evaluateEvent;
+    /**
+     * Guarda `trigger` si las definiciones aún no han llegado. Devuelve `true` si lo guardó (el
+     * llamador no debe evaluarlo ahora) y `false` si no hay carga en vuelo (se evalúa ya, como
+     * siempre: tras cargar, tras un fallo o sin apiKey).
+     */
+    private bufferIfAwaitingPopups;
+    /** La carga falló: sin definiciones no hay nada que reproducir, se descarta todo. */
+    private dropPendingTriggers;
+    /** Reproduce en orden por la evaluación normal (segmentos, cooldowns y condiciones de AHORA). */
+    private replayPendingTriggers;
     private showDefinition;
     private shouldShow;
     private matchesSegmentsLang;
@@ -961,7 +1017,7 @@ declare class DeepdotsPopups {
     private removeDeferredExitPopup;
     private getDeferredExitQueue;
     private setDeferredExitQueue;
-    /** Fetch al servidor para obtener popups */
+    /** Fetch al servidor para obtener popups. `null` si la carga falló (red, no-2xx, payload inválido). */
     private fetchPopupsFromServer;
     /** Envía los atributos de contact a la API (`POST /sdk/popups/contact`). */
     private postContact;