@magicfeedback/popup-sdk 1.1.1 → 1.1.3

package/dist/react-native.d.mts

@@ -21,10 +21,11 @@ interface KeyValueStorage {
 /**
  * Device info para el context de analytics (Technology #11–13).
  *
- * En Web enviamos `device_type` (heurística fiable) + `user_agent` crudo, y dejamos
- * que el backend derive OS/modelo/navegador del UA (como hace GA) — el parseo de UA en
- * cliente es frágil. `app_version` lo provee el cliente (una web no tiene versión de app
- * nativa). En KMP las APIs nativas dan os_version/device_model reales.
+ * En Web enviamos `device_type` + `user_agent` crudo y dejamos que el backend
+ * derive OS/navegador del UA (como hace GA). Los campos adicionales (timezone,
+ * referrer, viewport, etc.) se recogen de las APIs del navegador sin permisos.
+ * `country`/`city` se rellenan de forma asíncrona (ver geo-info.ts).
+ * En KMP las APIs nativas dan os_version/device_model reales.
  */
 interface DeviceInfo {
     device_type: 'mobile' | 'tablet' | 'desktop';
@@ -32,6 +33,16 @@ interface DeviceInfo {
     device_model?: string;
     app_version?: string;
     user_agent?: string;
+    timezone?: string;
+    referrer?: string;
+    viewport_size?: string;
+    screen_resolution?: string;
+    pixel_ratio?: number;
+    entry_type?: string;
+    page_load_ms?: number;
+    connection_type?: string;
+    country?: string;
+    city?: string;
 }
 
 /**
@@ -76,11 +87,12 @@ interface AnalyticsEnvelope {
  * 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`.
  *
- * Encoding (decisión 2026-06-22):
- *  - cada evento (dato recabado) → una `metric` {key: nombre_evento, value: JSON(timestamp + params)}
+ * Encoding:
+ *  - todo va en `feedback.metadata`: contexto (user_id, session_id, platform…) + eventos
+ *  - cada entrada usa `value: string[]` (array de un elemento)
+ *  - eventos: {key: nombre_evento, value: [JSON(timestamp + params)]}
  *  - identidad (user_id) → `profile` como `external-user-id`
- *  - contexto (user_id, session_id, platform, language, device, attributes) → `metadata`
- *  - `answers` vacío
+ *  - `answers` vacío, `metrics` no se usa
  *  - `text` vacío
  */
 
@@ -195,7 +207,7 @@ interface PopupRenderer {
     /** Preparar recursos si aplica */
     init?(): void;
     /** Mostrar popup */
-    show(surveyId: string, productId: string, actions: PopupActions | undefined, emit: (type: DeepdotsEventType, surveyId: string, data?: Record<string, unknown>) => void, onClose: () => void, env?: string, userId?: string, style?: PopupStyle, sessionId?: string, miniService?: string): void;
+    show(surveyId: string, productId: string, actions: PopupActions | undefined, emit: (type: DeepdotsEventType, surveyId: string, data?: Record<string, unknown>) => void, onClose: () => void, env?: string, userId?: string, style?: PopupStyle, sessionId?: string, miniService?: string, analyticsFeedbackSessionId?: string): void;
     /** Ocultar popup */
     hide(): void;
 }
@@ -204,6 +216,30 @@ interface PopupRenderer {
 type ContactAttributeValue = string | number | boolean;
 type ContactAttributes = Record<string, ContactAttributeValue>;
 
+/**
+ * Crash & error reporting (Stability #14–17) — captura de errores GESTIONADOS.
+ *
+ * - `reportError()`: API pública para el host (app viva) → emite `deepdots_app_crash` ya.
+ * - handlers de `window` (errores no capturados): persisten a disco y se reenvían
+ *   en el siguiente arranque (el proceso puede morir antes del flush normal).
+ *
+ * El contexto de device/sesión se captura EN EL MOMENTO del crash y se guarda en el
+ * record — no se lee del envelope en el replay (el replay puede ocurrir en otra
+ * app_version/OS). Las dims OS/device en Web suelen ir vacías (se derivan del UA en backend).
+ */
+
+type CrashSeverity = 'fatal' | 'error' | 'warning';
+interface ReportErrorOptions {
+    severity?: CrashSeverity;
+    handled?: boolean;
+    context?: Record<string, unknown>;
+}
+/** Forma mínima de `global.ErrorUtils` de React Native. */
+interface ReactNativeErrorUtils {
+    getGlobalHandler?(): ((error: unknown, isFatal?: boolean) => void) | undefined;
+    setGlobalHandler(handler: (error: unknown, isFatal?: boolean) => void): void;
+}
+
 /**
  * Main class for managing survey popups
  */
@@ -228,6 +264,12 @@ declare class DeepdotsPopups {
     private tracking;
     /** Capa de analytics (canal separado del feedback). Null hasta init(). */
     private analytics;
+    /** feedbackSessionId cacheado del canal de analytics (devuelto por POST /sdk/feedback). */
+    private analyticsFeedbackSessionId;
+    /** Timer del flush periódico de analytics (cada ANALYTICS_FLUSH_INTERVAL_MS). */
+    private analyticsFlushTimer;
+    /** Crash & error reporting (#14–17). Null hasta init(). */
+    private crashReporter;
     /** Observador de navegación (Fase 2): emite page_view por el canal de analytics. */
     private navObserver;
     /** Tiempo activo (engagement time, #8). */
@@ -248,6 +290,10 @@ declare class DeepdotsPopups {
     track(name: string, params?: Record<string, unknown>): void;
     /** User attributes para breakdowns (registration_status, pass_type, sector, pass_status…). */
     setUserAttributes(attributes: Record<string, 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. */
+    installReactNativeCrashHandler(errorUtils: ReactNativeErrorUtils): void;
     /**
      * 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
@@ -257,8 +303,8 @@ declare class DeepdotsPopups {
     setContactAttributes(attributes: ContactAttributes): Promise<boolean>;
     /** Marca el inicio de un mini-service; etiqueta los eventos siguientes. No-op si tracking off. */
     enterMiniService(name: string, entryPointType?: string): void;
-    /** Cierra el mini-service activo (emite `mini_service_exit` con duración, #27). No-op si tracking off. */
-    exitMiniService(): void;
+    /** Cierra el mini-service `name` (emite `mini_service_exit` con duración, #27). No-op si tracking off o si ese no está activo. */
+    exitMiniService(name: string): void;
     /** Findability (#31/#35): registra una búsqueda. `has_results` se deriva de `resultsCount`. */
     trackSearch(query: string, resultsCount: number, params?: Record<string, unknown>): void;
     /** Findability friction (#34/#35): señal de fricción con su `friction_topic`. */
@@ -390,6 +436,8 @@ interface ReactNativeSetupDeps {
     appState?: AppStateLike | null;
     platform?: 'web' | 'android' | 'ios';
     renderer?: PopupRenderer;
+    /** `global.ErrorUtils` de RN (para capturar errores JS no manejados). Default: `globalThis.ErrorUtils`. */
+    errorUtils?: ReactNativeErrorUtils | null;
 }
 /**
  * Configura el SDK para React Native en una sola llamada: storage persistente (MMKV),
@@ -437,7 +485,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): 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

package/dist/react-native.d.ts

@@ -21,10 +21,11 @@ interface KeyValueStorage {
 /**
  * Device info para el context de analytics (Technology #11–13).
  *
- * En Web enviamos `device_type` (heurística fiable) + `user_agent` crudo, y dejamos
- * que el backend derive OS/modelo/navegador del UA (como hace GA) — el parseo de UA en
- * cliente es frágil. `app_version` lo provee el cliente (una web no tiene versión de app
- * nativa). En KMP las APIs nativas dan os_version/device_model reales.
+ * En Web enviamos `device_type` + `user_agent` crudo y dejamos que el backend
+ * derive OS/navegador del UA (como hace GA). Los campos adicionales (timezone,
+ * referrer, viewport, etc.) se recogen de las APIs del navegador sin permisos.
+ * `country`/`city` se rellenan de forma asíncrona (ver geo-info.ts).
+ * En KMP las APIs nativas dan os_version/device_model reales.
  */
 interface DeviceInfo {
     device_type: 'mobile' | 'tablet' | 'desktop';
@@ -32,6 +33,16 @@ interface DeviceInfo {
     device_model?: string;
     app_version?: string;
     user_agent?: string;
+    timezone?: string;
+    referrer?: string;
+    viewport_size?: string;
+    screen_resolution?: string;
+    pixel_ratio?: number;
+    entry_type?: string;
+    page_load_ms?: number;
+    connection_type?: string;
+    country?: string;
+    city?: string;
 }
 
 /**
@@ -76,11 +87,12 @@ interface AnalyticsEnvelope {
  * 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`.
  *
- * Encoding (decisión 2026-06-22):
- *  - cada evento (dato recabado) → una `metric` {key: nombre_evento, value: JSON(timestamp + params)}
+ * Encoding:
+ *  - todo va en `feedback.metadata`: contexto (user_id, session_id, platform…) + eventos
+ *  - cada entrada usa `value: string[]` (array de un elemento)
+ *  - eventos: {key: nombre_evento, value: [JSON(timestamp + params)]}
  *  - identidad (user_id) → `profile` como `external-user-id`
- *  - contexto (user_id, session_id, platform, language, device, attributes) → `metadata`
- *  - `answers` vacío
+ *  - `answers` vacío, `metrics` no se usa
  *  - `text` vacío
  */
 
@@ -195,7 +207,7 @@ interface PopupRenderer {
     /** Preparar recursos si aplica */
     init?(): void;
     /** Mostrar popup */
-    show(surveyId: string, productId: string, actions: PopupActions | undefined, emit: (type: DeepdotsEventType, surveyId: string, data?: Record<string, unknown>) => void, onClose: () => void, env?: string, userId?: string, style?: PopupStyle, sessionId?: string, miniService?: string): void;
+    show(surveyId: string, productId: string, actions: PopupActions | undefined, emit: (type: DeepdotsEventType, surveyId: string, data?: Record<string, unknown>) => void, onClose: () => void, env?: string, userId?: string, style?: PopupStyle, sessionId?: string, miniService?: string, analyticsFeedbackSessionId?: string): void;
     /** Ocultar popup */
     hide(): void;
 }
@@ -204,6 +216,30 @@ interface PopupRenderer {
 type ContactAttributeValue = string | number | boolean;
 type ContactAttributes = Record<string, ContactAttributeValue>;
 
+/**
+ * Crash & error reporting (Stability #14–17) — captura de errores GESTIONADOS.
+ *
+ * - `reportError()`: API pública para el host (app viva) → emite `deepdots_app_crash` ya.
+ * - handlers de `window` (errores no capturados): persisten a disco y se reenvían
+ *   en el siguiente arranque (el proceso puede morir antes del flush normal).
+ *
+ * El contexto de device/sesión se captura EN EL MOMENTO del crash y se guarda en el
+ * record — no se lee del envelope en el replay (el replay puede ocurrir en otra
+ * app_version/OS). Las dims OS/device en Web suelen ir vacías (se derivan del UA en backend).
+ */
+
+type CrashSeverity = 'fatal' | 'error' | 'warning';
+interface ReportErrorOptions {
+    severity?: CrashSeverity;
+    handled?: boolean;
+    context?: Record<string, unknown>;
+}
+/** Forma mínima de `global.ErrorUtils` de React Native. */
+interface ReactNativeErrorUtils {
+    getGlobalHandler?(): ((error: unknown, isFatal?: boolean) => void) | undefined;
+    setGlobalHandler(handler: (error: unknown, isFatal?: boolean) => void): void;
+}
+
 /**
  * Main class for managing survey popups
  */
@@ -228,6 +264,12 @@ declare class DeepdotsPopups {
     private tracking;
     /** Capa de analytics (canal separado del feedback). Null hasta init(). */
     private analytics;
+    /** feedbackSessionId cacheado del canal de analytics (devuelto por POST /sdk/feedback). */
+    private analyticsFeedbackSessionId;
+    /** Timer del flush periódico de analytics (cada ANALYTICS_FLUSH_INTERVAL_MS). */
+    private analyticsFlushTimer;
+    /** Crash & error reporting (#14–17). Null hasta init(). */
+    private crashReporter;
     /** Observador de navegación (Fase 2): emite page_view por el canal de analytics. */
     private navObserver;
     /** Tiempo activo (engagement time, #8). */
@@ -248,6 +290,10 @@ declare class DeepdotsPopups {
     track(name: string, params?: Record<string, unknown>): void;
     /** User attributes para breakdowns (registration_status, pass_type, sector, pass_status…). */
     setUserAttributes(attributes: Record<string, 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. */
+    installReactNativeCrashHandler(errorUtils: ReactNativeErrorUtils): void;
     /**
      * 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
@@ -257,8 +303,8 @@ declare class DeepdotsPopups {
     setContactAttributes(attributes: ContactAttributes): Promise<boolean>;
     /** Marca el inicio de un mini-service; etiqueta los eventos siguientes. No-op si tracking off. */
     enterMiniService(name: string, entryPointType?: string): void;
-    /** Cierra el mini-service activo (emite `mini_service_exit` con duración, #27). No-op si tracking off. */
-    exitMiniService(): void;
+    /** Cierra el mini-service `name` (emite `mini_service_exit` con duración, #27). No-op si tracking off o si ese no está activo. */
+    exitMiniService(name: string): void;
     /** Findability (#31/#35): registra una búsqueda. `has_results` se deriva de `resultsCount`. */
     trackSearch(query: string, resultsCount: number, params?: Record<string, unknown>): void;
     /** Findability friction (#34/#35): señal de fricción con su `friction_topic`. */
@@ -390,6 +436,8 @@ interface ReactNativeSetupDeps {
     appState?: AppStateLike | null;
     platform?: 'web' | 'android' | 'ios';
     renderer?: PopupRenderer;
+    /** `global.ErrorUtils` de RN (para capturar errores JS no manejados). Default: `globalThis.ErrorUtils`. */
+    errorUtils?: ReactNativeErrorUtils | null;
 }
 /**
  * Configura el SDK para React Native en una sola llamada: storage persistente (MMKV),
@@ -437,7 +485,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): 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