@magicfeedback/popup-sdk 1.16.0 → 1.17.0

package/dist/index.d.mts

@@ -124,9 +124,9 @@ type AnalyticsSink = (payload: AnalyticsEnvelope, meta?: AnalyticsFlushMeta) =>
  *
  * 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`; 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.
+ * backend agrupa los lotes por `sessionId`, que genera el SDK al abrir cada sesión. 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 lote siguiente abre otro con un sessionId nuevo.
  * `feedback.finished` se queda siempre en `false` (no es la señal de cierre acordada).
  *
  * Encoding:
@@ -160,14 +160,14 @@ interface AnalyticsFeedbackBody {
     integration: string;
     completed: boolean;
     finished?: boolean;
-    /** sessionId devuelto por el primer POST; permite que el backend agrupe todos los eventos en un solo registro. */
+    /** sessionId de la sesión (lo genera el SDK): el backend agrupa todos sus lotes en un solo registro. */
     sessionId?: string;
 }
 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.
+     * El body lleva el `sessionId` de la sesión que se cierra; el lote siguiente abre otro
+     * registro con un sessionId nuevo.
      */
     sessionEnd?: boolean;
 }
@@ -193,32 +193,49 @@ interface FeedbackSinkOptions {
      * `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). */
+    /**
+     * Genera el sessionId de cada sesión (default: UUID v4). Inyectable para tests.
+     */
+    newSessionId?: () => string;
+    /**
+     * Persistencia de los lotes pendientes (React Native: MMKV). Con él, el lote de cierre se
+     * guarda antes de enviarse y cualquier lote que falle sobrevive a que la app muera: el sink
+     * del arranque siguiente lo reenvía a su registro. Sin él, los pendientes viven en memoria.
+     */
+    storage?: KeyValueStorage;
+    /** Reloj inyectable (tests). */
+    now?: () => number;
+    /** Callback invocado cuando la API acepta el primer lote de una sesión (registro abierto). */
     onSessionId?: (id: string) => void;
     /** Callback invocado al cerrar la sesión (`completed:true`): el sessionId cacheado se olvida. */
     onSessionReset?: () => void;
     /**
      * Callback invocado cuando el backend acepta el lote de cierre, con el sessionId del
-     * registro cerrado: el que llevaba el lote o, en una sesión de un solo lote, el que
-     * devuelve la respuesta. Ese registro se convierte en Feedback en segundos.
+     * registro cerrado. Ese registro se convierte en Feedback en segundos.
      */
     onSessionClosed?: (id: string) => void;
 }
 /**
  * Sink real: transforma el envelope y hace `POST {baseUrl}/sdk/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.
+ * El `sessionId` de cada sesión lo genera el SDK (UUID) y va en TODOS sus lotes, desde el
+ * primero. La API guarda cada lote bajo el sessionId que recibe, así que una sesión es un
+ * registro aunque no llegue ninguna respuesta. Antes lo asignaba la API en la respuesta del
+ * primer POST: si esa respuesta se perdía (la app pasaba a background con el POST en vuelo),
+ * el resto de la sesión acababa en otro registro.
  *
  * 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;
+ *  - un lote que falla de forma transitoria (red, 5xx, 408, 429, sin respuesta en
+ *    POST_TIMEOUT_MS) se guarda TAL CUAL —con su sessionId y su `completed`— y se reenvía
+ *    antes del lote siguiente. Nunca vuelve al buffer del manager: allí se mezclaba con la
+ *    sesión siguiente y viajaba con su registro. La promesa del sink no rechaza;
+ *  - con `storage` (React Native) los pendientes sobreviven a que la app muera: el lote de
+ *    cierre se guarda ANTES de enviarse y el sink del arranque siguiente lo reenvía. La API
+ *    descarta los eventos repetidos de una misma sesión al ensamblarla;
  *  - `keepalive` para que el navegador no cancele el POST al navegar fuera ni al cerrar la
- *    página, también en el flush final (sin `sendBeacon`: ver `sendBeaconImpl`);
+ *    página (sin `sendBeacon`: ver `sendBeaconImpl`);
  *  - sin credenciales, que es lo único que pasa el CORS de la API (`Allow-Origin: *`);
- *  - 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.
+ *  - un 4xx se loguea y se descarta.
  */
 declare function createFeedbackSink(options: FeedbackSinkOptions): AnalyticsSink;
 
@@ -572,7 +589,11 @@ interface ContactManagerOptions {
     storage: KeyValueStorage;
     publicKey: string;
     userId: string;
-    /** Envío real (inyectable para tests): hace el `POST /sdk/popups/contact`. */
+    /**
+     * Envío real (inyectable para tests): hace el `POST /sdk/popups/contact`. Tiene que
+     * RECHAZAR si la API no acepta el envío (sin red o respuesta no-2xx): solo así se sabe
+     * que no hay que guardar la caché y que la llamada siguiente debe reintentar.
+     */
     post: (body: ContactBody) => Promise<void>;
 }
 /**
@@ -587,8 +608,9 @@ declare class ContactManager {
     private readonly post;
     constructor(options: ContactManagerOptions);
     /**
-     * Envía los atributos si cambiaron respecto a lo último enviado.
-     * @returns `true` si se envió, `false` si no hubo cambios.
+     * Envía los atributos si cambiaron respecto a lo último enviado. La caché solo se guarda
+     * cuando la API acepta el envío; si falla, la llamada siguiente reintenta. Nunca rechaza.
+     * @returns `true` si se envió, `false` si no hubo cambios o el envío falló.
      */
     setAttributes(attributes: ContactAttributes): Promise<boolean>;
 }
@@ -652,6 +674,10 @@ declare function crashRecordToParams(r: CrashRecord): Record<string, unknown>;
 declare class CrashReporter {
     private options;
     private now;
+    /** Los handlers de `window` ya están puestos: `install()` es idempotente. */
+    private windowInstalled;
+    /** ErrorUtils ya enganchados: engancharlos dos veces capturaría cada error dos veces. */
+    private hookedErrorUtils;
     constructor(options: CrashReporterOptions);
     private isEnabled;
     /** Construye un CrashRecord capturando contexto en el momento del crash. */
@@ -664,9 +690,9 @@ declare class CrashReporter {
     private persist;
     /** Lee y vacía la cola de crashes pendientes (llamado en init para el replay). */
     drainPendingCrashes(): CrashRecord[];
-    /** Instala los handlers globales de errores no capturados (no-op sin `window`). */
+    /** Instala los handlers globales de errores no capturados (no-op sin `window`). Idempotente. */
     install(): void;
-    /** Engancha `global.ErrorUtils` de RN (no hay `window`): persiste y encadena al handler previo. */
+    /** Engancha `global.ErrorUtils` de RN (no hay `window`): persiste y encadena al handler previo. Idempotente por instancia de ErrorUtils. */
     installReactNative(errorUtils: ReactNativeErrorUtils): void;
     /** @internal Test seam: ejercita el camino de persistencia (window handlers no son testeables en vitest). */
     _persistForTest(error: unknown): void;
@@ -779,6 +805,8 @@ declare class DeepdotsPopups {
     private analyticsFlushTimer;
     /** Crash & error reporting (#14–17). Null hasta init(). */
     private crashReporter;
+    /** ErrorUtils de RN recibido del host (o del Provider); se engancha en cuanto haya consentimiento. */
+    private rnErrorUtils;
     /** 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. */
@@ -847,8 +875,18 @@ declare class DeepdotsPopups {
     setMetric(key: string, value: string | number | boolean): void;
     /** Reporta un error del host (manejado o no) → evento `deepdots_app_crash`. No-op si tracking off. */
     reportError(error: unknown, options?: ReportErrorOptions): void;
-    /** Engancha `global.ErrorUtils` de RN para capturar errores JS no manejados. No-op si tracking off. */
+    /**
+     * Engancha `global.ErrorUtils` de RN para capturar errores JS no manejados. Con tracking off
+     * se recuerda y se engancha cuando se conceda el consentimiento (`setTrackingEnabled(true)`).
+     */
     installReactNativeCrashHandler(errorUtils: ReactNativeErrorUtils): void;
+    /**
+     * Pone los handlers de errores no capturados: `window` en web y `ErrorUtils` en RN (el que
+     * pasó el host o, si no pasó ninguno, `globalThis.ErrorUtils`, para que un `init()` sin
+     * `setupReactNative` también capture). Solo con consentimiento; idempotente, así que se
+     * llama en `init()` y cada vez que se activa el tracking.
+     */
+    private installCrashHandlers;
     /**
      * Info interna del usuario que solo conoce el host (idioma, edad, plan…), persistida en el
      * Contact del backend para segmentación/targeting de popups. Identificada por el `userId` del
@@ -1071,7 +1109,11 @@ declare class DeepdotsPopups {
     private setDeferredExitQueue;
     /** 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`). */
+    /**
+     * Envía los atributos de contact a la API (`POST /sdk/popups/contact`). Rechaza si no se
+     * pudo enviar (sin red o respuesta no-2xx), para que `ContactManager` no guarde la caché
+     * y la llamada siguiente reintente.
+     */
     private postContact;
     /** Notifica eventos de popup a la API */
     private postPopupEvent;

package/dist/index.d.ts

@@ -124,9 +124,9 @@ type AnalyticsSink = (payload: AnalyticsEnvelope, meta?: AnalyticsFlushMeta) =>
  *
  * 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`; 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.
+ * backend agrupa los lotes por `sessionId`, que genera el SDK al abrir cada sesión. 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 lote siguiente abre otro con un sessionId nuevo.
  * `feedback.finished` se queda siempre en `false` (no es la señal de cierre acordada).
  *
  * Encoding:
@@ -160,14 +160,14 @@ interface AnalyticsFeedbackBody {
     integration: string;
     completed: boolean;
     finished?: boolean;
-    /** sessionId devuelto por el primer POST; permite que el backend agrupe todos los eventos en un solo registro. */
+    /** sessionId de la sesión (lo genera el SDK): el backend agrupa todos sus lotes en un solo registro. */
     sessionId?: string;
 }
 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.
+     * El body lleva el `sessionId` de la sesión que se cierra; el lote siguiente abre otro
+     * registro con un sessionId nuevo.
      */
     sessionEnd?: boolean;
 }
@@ -193,32 +193,49 @@ interface FeedbackSinkOptions {
      * `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). */
+    /**
+     * Genera el sessionId de cada sesión (default: UUID v4). Inyectable para tests.
+     */
+    newSessionId?: () => string;
+    /**
+     * Persistencia de los lotes pendientes (React Native: MMKV). Con él, el lote de cierre se
+     * guarda antes de enviarse y cualquier lote que falle sobrevive a que la app muera: el sink
+     * del arranque siguiente lo reenvía a su registro. Sin él, los pendientes viven en memoria.
+     */
+    storage?: KeyValueStorage;
+    /** Reloj inyectable (tests). */
+    now?: () => number;
+    /** Callback invocado cuando la API acepta el primer lote de una sesión (registro abierto). */
     onSessionId?: (id: string) => void;
     /** Callback invocado al cerrar la sesión (`completed:true`): el sessionId cacheado se olvida. */
     onSessionReset?: () => void;
     /**
      * Callback invocado cuando el backend acepta el lote de cierre, con el sessionId del
-     * registro cerrado: el que llevaba el lote o, en una sesión de un solo lote, el que
-     * devuelve la respuesta. Ese registro se convierte en Feedback en segundos.
+     * registro cerrado. Ese registro se convierte en Feedback en segundos.
      */
     onSessionClosed?: (id: string) => void;
 }
 /**
  * Sink real: transforma el envelope y hace `POST {baseUrl}/sdk/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.
+ * El `sessionId` de cada sesión lo genera el SDK (UUID) y va en TODOS sus lotes, desde el
+ * primero. La API guarda cada lote bajo el sessionId que recibe, así que una sesión es un
+ * registro aunque no llegue ninguna respuesta. Antes lo asignaba la API en la respuesta del
+ * primer POST: si esa respuesta se perdía (la app pasaba a background con el POST en vuelo),
+ * el resto de la sesión acababa en otro registro.
  *
  * 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;
+ *  - un lote que falla de forma transitoria (red, 5xx, 408, 429, sin respuesta en
+ *    POST_TIMEOUT_MS) se guarda TAL CUAL —con su sessionId y su `completed`— y se reenvía
+ *    antes del lote siguiente. Nunca vuelve al buffer del manager: allí se mezclaba con la
+ *    sesión siguiente y viajaba con su registro. La promesa del sink no rechaza;
+ *  - con `storage` (React Native) los pendientes sobreviven a que la app muera: el lote de
+ *    cierre se guarda ANTES de enviarse y el sink del arranque siguiente lo reenvía. La API
+ *    descarta los eventos repetidos de una misma sesión al ensamblarla;
  *  - `keepalive` para que el navegador no cancele el POST al navegar fuera ni al cerrar la
- *    página, también en el flush final (sin `sendBeacon`: ver `sendBeaconImpl`);
+ *    página (sin `sendBeacon`: ver `sendBeaconImpl`);
  *  - sin credenciales, que es lo único que pasa el CORS de la API (`Allow-Origin: *`);
- *  - 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.
+ *  - un 4xx se loguea y se descarta.
  */
 declare function createFeedbackSink(options: FeedbackSinkOptions): AnalyticsSink;
 
@@ -572,7 +589,11 @@ interface ContactManagerOptions {
     storage: KeyValueStorage;
     publicKey: string;
     userId: string;
-    /** Envío real (inyectable para tests): hace el `POST /sdk/popups/contact`. */
+    /**
+     * Envío real (inyectable para tests): hace el `POST /sdk/popups/contact`. Tiene que
+     * RECHAZAR si la API no acepta el envío (sin red o respuesta no-2xx): solo así se sabe
+     * que no hay que guardar la caché y que la llamada siguiente debe reintentar.
+     */
     post: (body: ContactBody) => Promise<void>;
 }
 /**
@@ -587,8 +608,9 @@ declare class ContactManager {
     private readonly post;
     constructor(options: ContactManagerOptions);
     /**
-     * Envía los atributos si cambiaron respecto a lo último enviado.
-     * @returns `true` si se envió, `false` si no hubo cambios.
+     * Envía los atributos si cambiaron respecto a lo último enviado. La caché solo se guarda
+     * cuando la API acepta el envío; si falla, la llamada siguiente reintenta. Nunca rechaza.
+     * @returns `true` si se envió, `false` si no hubo cambios o el envío falló.
      */
     setAttributes(attributes: ContactAttributes): Promise<boolean>;
 }
@@ -652,6 +674,10 @@ declare function crashRecordToParams(r: CrashRecord): Record<string, unknown>;
 declare class CrashReporter {
     private options;
     private now;
+    /** Los handlers de `window` ya están puestos: `install()` es idempotente. */
+    private windowInstalled;
+    /** ErrorUtils ya enganchados: engancharlos dos veces capturaría cada error dos veces. */
+    private hookedErrorUtils;
     constructor(options: CrashReporterOptions);
     private isEnabled;
     /** Construye un CrashRecord capturando contexto en el momento del crash. */
@@ -664,9 +690,9 @@ declare class CrashReporter {
     private persist;
     /** Lee y vacía la cola de crashes pendientes (llamado en init para el replay). */
     drainPendingCrashes(): CrashRecord[];
-    /** Instala los handlers globales de errores no capturados (no-op sin `window`). */
+    /** Instala los handlers globales de errores no capturados (no-op sin `window`). Idempotente. */
     install(): void;
-    /** Engancha `global.ErrorUtils` de RN (no hay `window`): persiste y encadena al handler previo. */
+    /** Engancha `global.ErrorUtils` de RN (no hay `window`): persiste y encadena al handler previo. Idempotente por instancia de ErrorUtils. */
     installReactNative(errorUtils: ReactNativeErrorUtils): void;
     /** @internal Test seam: ejercita el camino de persistencia (window handlers no son testeables en vitest). */
     _persistForTest(error: unknown): void;
@@ -779,6 +805,8 @@ declare class DeepdotsPopups {
     private analyticsFlushTimer;
     /** Crash & error reporting (#14–17). Null hasta init(). */
     private crashReporter;
+    /** ErrorUtils de RN recibido del host (o del Provider); se engancha en cuanto haya consentimiento. */
+    private rnErrorUtils;
     /** 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. */
@@ -847,8 +875,18 @@ declare class DeepdotsPopups {
     setMetric(key: string, value: string | number | boolean): void;
     /** Reporta un error del host (manejado o no) → evento `deepdots_app_crash`. No-op si tracking off. */
     reportError(error: unknown, options?: ReportErrorOptions): void;
-    /** Engancha `global.ErrorUtils` de RN para capturar errores JS no manejados. No-op si tracking off. */
+    /**
+     * Engancha `global.ErrorUtils` de RN para capturar errores JS no manejados. Con tracking off
+     * se recuerda y se engancha cuando se conceda el consentimiento (`setTrackingEnabled(true)`).
+     */
     installReactNativeCrashHandler(errorUtils: ReactNativeErrorUtils): void;
+    /**
+     * Pone los handlers de errores no capturados: `window` en web y `ErrorUtils` en RN (el que
+     * pasó el host o, si no pasó ninguno, `globalThis.ErrorUtils`, para que un `init()` sin
+     * `setupReactNative` también capture). Solo con consentimiento; idempotente, así que se
+     * llama en `init()` y cada vez que se activa el tracking.
+     */
+    private installCrashHandlers;
     /**
      * Info interna del usuario que solo conoce el host (idioma, edad, plan…), persistida en el
      * Contact del backend para segmentación/targeting de popups. Identificada por el `userId` del
@@ -1071,7 +1109,11 @@ declare class DeepdotsPopups {
     private setDeferredExitQueue;
     /** 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`). */
+    /**
+     * Envía los atributos de contact a la API (`POST /sdk/popups/contact`). Rechaza si no se
+     * pudo enviar (sin red o respuesta no-2xx), para que `ContactManager` no guarde la caché
+     * y la llamada siguiente reintente.
+     */
     private postContact;
     /** Notifica eventos de popup a la API */
     private postPopupEvent;