@magicfeedback/popup-sdk 1.1.2 → 1.1.3

package/dist/react-native.d.mts

@@ -216,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
  */
@@ -244,6 +268,8 @@ declare class DeepdotsPopups {
     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). */
@@ -264,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
@@ -273,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`. */
@@ -406,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),

package/dist/react-native.d.ts

@@ -216,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
  */
@@ -244,6 +268,8 @@ declare class DeepdotsPopups {
     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). */
@@ -264,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
@@ -273,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`. */
@@ -406,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),

package/dist/react-native.js

@@ -1925,8 +1925,8 @@ var AnalyticsManager = class {
   constructor(options = {}) {
     this.events = [];
     this.attributes = {};
-    this.miniService = null;
-    this.miniServiceEnteredAt = 0;
+    /** Mini-services activos: nombre → timestamp de entrada. El orden de inserción marca el "más reciente". */
+    this.activeMiniServices = /* @__PURE__ */ new Map();
     this.sink = options.sink ?? dryRunSink;
     this.now = options.now ?? (() => Date.now());
     this.publicKey = options.publicKey;
@@ -1947,24 +1947,38 @@ var AnalyticsManager = class {
       this.attributes[k] = String(v);
     }
   }
-  /** Marca el inicio de un mini-service; etiqueta los eventos siguientes con `mini_service`. */
+  /**
+   * Marca el inicio de un mini-service; etiqueta los eventos siguientes con `mini_service`.
+   * Admite varios activos a la vez (concurrencia); el "actual" para etiquetar es el más reciente.
+   * Reentrar con un nombre ya activo refresca su orden y su tiempo de entrada.
+   */
   enterMiniService(name, entryPointType) {
-    this.miniService = name;
-    this.miniServiceEnteredAt = this.now();
-    this.track("mini_service_enter", { entry_point_type: entryPointType ?? null });
-  }
-  /** Cierra el mini-service activo emitiendo `mini_service_exit` con su duración (#27). No-op si no hay ninguno. */
-  exitMiniService() {
-    const name = this.miniService;
-    if (name == null) return;
-    const durationSeconds = Math.max(0, Math.round((this.now() - this.miniServiceEnteredAt) / 1e3));
-    this.miniService = null;
-    this.track("mini_service_exit", { mini_service: name, duration_seconds: durationSeconds });
+    this.activeMiniServices.delete(name);
+    this.activeMiniServices.set(name, this.now());
+    this.track("deepdots_mini_service_enter", { entry_point_type: entryPointType ?? null });
+  }
+  /**
+   * Cierra el mini-service `name` emitiendo `mini_service_exit` con su duración (#27).
+   * No-op si ese nombre no está activo. Cierre coherente con concurrencia.
+   */
+  exitMiniService(name) {
+    const enteredAt = this.activeMiniServices.get(name);
+    if (enteredAt === void 0) return;
+    const durationSeconds = Math.max(0, Math.round((this.now() - enteredAt) / 1e3));
+    this.activeMiniServices.delete(name);
+    this.track("deepdots_mini_service_exit", { mini_service: name, duration_seconds: durationSeconds });
+  }
+  /** Cierra TODOS los mini-services activos (orden LIFO). Para el cierre por lifecycle (background/cierre). */
+  exitAllMiniServices() {
+    for (const name of Array.from(this.activeMiniServices.keys()).reverse()) {
+      this.exitMiniService(name);
+    }
   }
   /** Registra un evento de analítica (modelo GA: nombre + params). */
   track(name, params) {
+    const current = this.getMiniService();
     const merged = {
-      ...this.miniService ? { mini_service: this.miniService } : {},
+      ...current ? { mini_service: current } : {},
       ...params ?? {}
     };
     this.events.push({
@@ -1976,9 +1990,11 @@ var AnalyticsManager = class {
       this.onFlushNeeded?.();
     }
   }
-  /** Mini-service activo (para inyectarlo en la metadata del survey, #33). */
+  /** Mini-service actual (el más reciente aún activo) para etiquetar eventos + metadata del survey (#33). */
   getMiniService() {
-    return this.miniService;
+    let last = null;
+    for (const name of this.activeMiniServices.keys()) last = name;
+    return last;
   }
   /** Nº de eventos pendientes de flush. */
   pending() {
@@ -2318,6 +2334,132 @@ var ContactManager = class {
   }
 };
 
+// src/analytics/crash-reporter.ts
+var STACK_MAX = 8e3;
+var QUEUE_KEY = "deepdots.crash.queue";
+var MAX_QUEUED = 20;
+function crashRecordToParams(r) {
+  const params = {
+    crashed_at: r.crashedAt,
+    crash_type: r.crashType,
+    message: r.message,
+    stack: r.stack,
+    fatal: r.fatal,
+    handled: r.handled,
+    severity: r.severity
+  };
+  if (r.sessionId) params.crashed_session_id = r.sessionId;
+  if (r.appVersion) params.crashed_app_version = r.appVersion;
+  if (r.osVersion) params.crashed_os_version = r.osVersion;
+  if (r.deviceModel) params.crashed_device_model = r.deviceModel;
+  if (r.context) {
+    for (const [k, v] of Object.entries(r.context)) params[`ctx_${k}`] = v;
+  }
+  return params;
+}
+var CrashReporter = class {
+  constructor(options) {
+    this.options = options;
+    this.now = options.now ?? (() => Date.now());
+  }
+  isEnabled() {
+    return this.options.enabled ? this.options.enabled() : true;
+  }
+  /** Construye un CrashRecord capturando contexto en el momento del crash. */
+  buildRecord(error, severity, handled, fatal, context) {
+    const err = error;
+    const isErr = error instanceof Error;
+    const dev = this.options.device();
+    const ctx = context ? Object.fromEntries(Object.entries(context).map(([k, v]) => [k, String(v)])) : void 0;
+    return {
+      crashedAt: this.now(),
+      crashType: isErr && err.name || "Error",
+      message: isErr ? String(err.message ?? "") : String(error),
+      stack: (isErr && typeof err.stack === "string" ? err.stack : "").slice(0, STACK_MAX),
+      fatal,
+      handled,
+      severity,
+      sessionId: this.options.sessionId(),
+      appVersion: dev.appVersion,
+      osVersion: dev.osVersion,
+      deviceModel: dev.deviceModel,
+      context: ctx
+    };
+  }
+  /** API pública del host: reporta un error (app viva) → emite el evento ya. */
+  reportError(error, options = {}) {
+    if (!this.isEnabled()) return;
+    const severity = options.severity ?? "error";
+    const handled = options.handled ?? true;
+    const fatal = severity === "fatal";
+    const record = this.buildRecord(error, severity, handled, fatal, options.context);
+    this.options.emit(crashRecordToParams(record));
+  }
+  /** Captura un error no manejado (fatal) → persiste a disco para replay en el siguiente arranque. */
+  captureUnhandled(error) {
+    this.persist(this.buildRecord(error, "fatal", false, true));
+  }
+  /** Persiste un crash no capturado a disco para reenviarlo en el siguiente arranque. */
+  persist(record) {
+    let queue = [];
+    try {
+      const raw = this.options.storage.getItem(QUEUE_KEY);
+      if (raw) queue = JSON.parse(raw);
+      if (!Array.isArray(queue)) queue = [];
+    } catch {
+      queue = [];
+    }
+    queue.push(record);
+    if (queue.length > MAX_QUEUED) queue = queue.slice(queue.length - MAX_QUEUED);
+    try {
+      this.options.storage.setItem(QUEUE_KEY, JSON.stringify(queue));
+    } catch {
+    }
+  }
+  /** Lee y vacía la cola de crashes pendientes (llamado en init para el replay). */
+  drainPendingCrashes() {
+    let queue = [];
+    try {
+      const raw = this.options.storage.getItem(QUEUE_KEY);
+      if (raw) queue = JSON.parse(raw);
+      if (!Array.isArray(queue)) queue = [];
+    } catch {
+      queue = [];
+    }
+    if (queue.length) {
+      try {
+        this.options.storage.removeItem(QUEUE_KEY);
+      } catch {
+      }
+    }
+    return queue;
+  }
+  /** Instala los handlers globales de errores no capturados (no-op sin `window`). */
+  install() {
+    if (typeof window === "undefined") return;
+    window.addEventListener("error", (e) => {
+      if (!this.isEnabled()) return;
+      this.captureUnhandled(e.error ?? e.message ?? "error");
+    });
+    window.addEventListener("unhandledrejection", (e) => {
+      if (!this.isEnabled()) return;
+      this.captureUnhandled(e.reason ?? "unhandledrejection");
+    });
+  }
+  /** Engancha `global.ErrorUtils` de RN (no hay `window`): persiste y encadena al handler previo. */
+  installReactNative(errorUtils) {
+    const previous = errorUtils.getGlobalHandler?.();
+    errorUtils.setGlobalHandler((error, isFatal) => {
+      if (this.isEnabled()) this.captureUnhandled(error);
+      previous?.(error, isFatal);
+    });
+  }
+  /** @internal Test seam: ejercita el camino de persistencia (window handlers no son testeables en vitest). */
+  _persistForTest(error) {
+    this.captureUnhandled(error);
+  }
+};
+
 // src/core/deepdots-popups.ts
 var EXIT_QUEUE_STORAGE_KEY = "__deepdots_exit_popup_queue__";
 var DAY_IN_MS = 24 * 60 * 60 * 1e3;
@@ -2352,6 +2494,8 @@ var DeepdotsPopups = class {
     this.analyticsFeedbackSessionId = void 0;
     /** Timer del flush periódico de analytics (cada ANALYTICS_FLUSH_INTERVAL_MS). */
     this.analyticsFlushTimer = void 0;
+    /** Crash & error reporting (#14–17). Null hasta init(). */
+    this.crashReporter = null;
     /** Observador de navegación (Fase 2): emite page_view por el canal de analytics. */
     this.navObserver = null;
     /** Tiempo activo (engagement time, #8). */
@@ -2403,25 +2547,44 @@ var DeepdotsPopups = class {
         this.analyticsFeedbackSessionId = id;
       }
     }) : void 0;
+    const device = config.device ?? collectDeviceInfo(config.appVersion);
     this.analytics = new AnalyticsManager({
       sink: analyticsSink,
       publicKey: config.analytics?.publicKey ?? this.config.apiKey,
       language: typeof navigator !== "undefined" ? navigator.language : void 0,
       platform: config.platform ?? "web",
-      device: config.device ?? collectDeviceInfo(config.appVersion),
+      device,
       maxBatchSize: ANALYTICS_MAX_BATCH_SIZE,
       onFlushNeeded: () => this.flushAnalytics()
     });
+    this.crashReporter = new CrashReporter({
+      storage,
+      emit: (params) => this.track("deepdots_app_crash", params),
+      device: () => ({ appVersion: device.app_version, osVersion: device.os_version, deviceModel: device.device_model }),
+      sessionId: () => this.tracking?.getSessionId() ?? null,
+      now: () => Date.now(),
+      enabled: () => this.tracking?.isTrackingEnabled() ?? false
+    });
+    if (this.tracking?.isTrackingEnabled()) {
+      this.crashReporter.install();
+    }
     collectGeoInfo().then((geo) => {
       if (geo) this.analytics?.updateDevice(geo);
     }).catch(() => {
     });
     this.navObserver = new NavigationObserver();
-    this.navObserver.onVisit((v) => this.track("page_view", { screen: v.screen, duration_seconds: v.durationSeconds }));
+    this.navObserver.onVisit((v) => this.track("deepdots_page_view", { screen: v.screen, duration_seconds: v.durationSeconds }));
     this.navObserver.install();
     this.engagement = new EngagementTracker();
     this.engagement.resume();
     this.setupAnalyticsFlush();
+    this.track("deepdots_session_start", {});
+    const pendingCrashes = this.crashReporter.drainPendingCrashes();
+    if (this.tracking?.isTrackingEnabled()) {
+      for (const rec of pendingCrashes) {
+        this.track("deepdots_app_crash", crashRecordToParams(rec));
+      }
+    }
     this.initialized = true;
     this.log("SDK initialized", this.config);
     if (this.renderer.init) this.renderer.init();
@@ -2462,6 +2625,16 @@ var DeepdotsPopups = class {
     if (!this.tracking?.isTrackingEnabled()) return;
     this.analytics?.setUserAttributes(attributes);
   }
+  /** Reporta un error del host (manejado o no) → evento `deepdots_app_crash`. No-op si tracking off. */
+  reportError(error, options) {
+    if (!this.tracking?.isTrackingEnabled()) return;
+    this.crashReporter?.reportError(error, options);
+  }
+  /** Engancha `global.ErrorUtils` de RN para capturar errores JS no manejados. No-op si tracking off. */
+  installReactNativeCrashHandler(errorUtils) {
+    if (!this.tracking?.isTrackingEnabled()) return;
+    this.crashReporter?.installReactNative(errorUtils);
+  }
   /**
    * 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
@@ -2479,23 +2652,23 @@ var DeepdotsPopups = class {
     this.analytics?.enterMiniService(name, entryPointType);
     this.log("analytics \xB7 enterMiniService:", name, entryPointType ?? "");
   }
-  /** Cierra el mini-service activo (emite `mini_service_exit` con duración, #27). No-op si tracking off. */
-  exitMiniService() {
+  /** 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) {
     if (!this.tracking?.isTrackingEnabled()) return;
-    this.analytics?.exitMiniService();
-    this.log("analytics \xB7 exitMiniService");
+    this.analytics?.exitMiniService(name);
+    this.log("analytics \xB7 exitMiniService:", name);
   }
   /** Findability (#31/#35): registra una búsqueda. `has_results` se deriva de `resultsCount`. */
   trackSearch(query, resultsCount, params) {
-    this.track("search", { query, results_count: resultsCount, has_results: resultsCount > 0, ...params ?? {} });
+    this.track("deepdots_search", { query, results_count: resultsCount, has_results: resultsCount > 0, ...params ?? {} });
   }
   /** Findability friction (#34/#35): señal de fricción con su `friction_topic`. */
   trackFindabilityFriction(frictionTopic, params) {
-    this.track("findability_friction", { friction_topic: frictionTopic, ...params ?? {} });
+    this.track("deepdots_findability_friction", { friction_topic: frictionTopic, ...params ?? {} });
   }
   /** Funnel: un paso del embudo, correlacionado por `taskId`. El backend reconstruye conversión/drop-off/tiempo. */
   trackFunnelStep(funnel, step, taskId, params) {
-    this.track("funnel_step", { funnel, step, task_id: taskId, ...params ?? {} });
+    this.track("deepdots_funnel_step", { funnel, step, task_id: taskId, ...params ?? {} });
   }
   /**
    * Navegación MANUAL (entornos sin History API, p. ej. React Native con React Navigation).
@@ -2521,7 +2694,7 @@ var DeepdotsPopups = class {
   onBackground() {
     this.navObserver?.stop();
     this.navStarted = false;
-    this.exitMiniService();
+    if (this.tracking?.isTrackingEnabled()) this.analytics?.exitAllMiniServices();
     this.flushEngagement();
     this.engagement?.pause();
     this.flushAnalytics();
@@ -2544,7 +2717,7 @@ var DeepdotsPopups = class {
   flushEngagement() {
     if (!this.tracking?.isTrackingEnabled()) return;
     const ms = this.engagement?.consume() ?? 0;
-    if (ms > 0) this.track("user_engagement", { engagement_time_msec: ms });
+    if (ms > 0) this.track("deepdots_user_engagement", { engagement_time_msec: ms });
   }
   analyticsIdentity() {
     return {
@@ -2559,7 +2732,7 @@ var DeepdotsPopups = class {
     window.addEventListener("pagehide", () => {
       clearInterval(this.analyticsFlushTimer);
       this.navObserver?.stop();
-      this.exitMiniService();
+      if (this.tracking?.isTrackingEnabled()) this.analytics?.exitAllMiniServices();
       this.flushEngagement();
       this.flushAnalytics();
     });
@@ -3225,6 +3398,10 @@ function setupReactNative(sdk2, config, deps = {}) {
   const device = deps.deviceInfo ? collectRnDevice(deps.deviceInfo) : config.device;
   const platform = deps.platform ?? config.platform;
   sdk2.init({ ...config, storage, device, platform });
+  const errorUtils = deps.errorUtils ?? globalThis.ErrorUtils;
+  if (errorUtils && typeof errorUtils.setGlobalHandler === "function") {
+    sdk2.installReactNativeCrashHandler(errorUtils);
+  }
   let subscription;
   if (deps.appState?.addEventListener) {
     subscription = deps.appState.addEventListener("change", (state) => {