@magicfeedback/popup-sdk 1.1.2 → 1.1.4

package/dist/index.d.mts

@@ -352,6 +352,109 @@ declare class ContactManager {
     setAttributes(attributes: ContactAttributes): Promise<boolean>;
 }
 
+/**
+ * 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 CrashRecord {
+    crashedAt: number;
+    crashType: string;
+    message: string;
+    stack: string;
+    fatal: boolean;
+    handled: boolean;
+    severity: CrashSeverity;
+    sessionId: string | null;
+    appVersion?: string;
+    osVersion?: string;
+    deviceModel?: string;
+    context?: Record<string, string>;
+}
+interface ReportErrorOptions {
+    severity?: CrashSeverity;
+    handled?: boolean;
+    context?: Record<string, unknown>;
+}
+interface DeviceSnapshot {
+    appVersion?: string;
+    osVersion?: string;
+    deviceModel?: string;
+}
+/** 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;
+}
+interface CrashReporterOptions {
+    storage: KeyValueStorage;
+    /** Emite un evento deepdots_app_crash AHORA (app viva). */
+    emit: (params: Record<string, unknown>) => void;
+    /** Snapshot de device en el momento del crash. */
+    device: () => DeviceSnapshot;
+    /** session_id en el momento del crash. */
+    sessionId: () => string | null;
+    now?: () => number;
+    /** Kill-switch de consentimiento. */
+    enabled?: () => boolean;
+}
+/** Convierte un CrashRecord en los params del evento `deepdots_app_crash` (omite undefined). */
+declare function crashRecordToParams(r: CrashRecord): Record<string, unknown>;
+declare class CrashReporter {
+    private options;
+    private now;
+    constructor(options: CrashReporterOptions);
+    private isEnabled;
+    /** Construye un CrashRecord capturando contexto en el momento del crash. */
+    private buildRecord;
+    /** API pública del host: reporta un error (app viva) → emite el evento ya. */
+    reportError(error: unknown, options?: ReportErrorOptions): void;
+    /** Captura un error no manejado (fatal) → persiste a disco para replay en el siguiente arranque. */
+    captureUnhandled(error: unknown): void;
+    /** Persiste un crash no capturado a disco para reenviarlo en el siguiente arranque. */
+    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`). */
+    install(): void;
+    /** Engancha `global.ErrorUtils` de RN (no hay `window`): persiste y encadena al handler previo. */
+    installReactNative(errorUtils: ReactNativeErrorUtils): void;
+    /** @internal Test seam: ejercita el camino de persistencia (window handlers no son testeables en vitest). */
+    _persistForTest(error: unknown): void;
+}
+
+/**
+ * Messaging (#18–22): tracking de notificaciones del host (push / in-app).
+ * Un único evento reservado `deepdots_message` con un campo `stage` discriminador;
+ * el funnel se correlaciona por `message_id` y se agrupa por `message_title`.
+ */
+type MessageStage = 'delivered' | 'clicked' | 'converted';
+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';
+    /** Nombre de la campaña (opcional). */
+    campaign?: string;
+    /** Valor de conversión (opcional, típico en `stage: 'converted'`). */
+    value?: number;
+    currency?: string;
+    /** Parámetros libres adicionales. */
+    params?: Record<string, unknown>;
+}
+/** Construye los params del evento `deepdots_message` (omite opcionales ausentes). */
+declare function buildMessageParams(stage: MessageStage, o: TrackMessageOptions): Record<string, unknown>;
+
 /**
  * Main class for managing survey popups
  */
@@ -380,6 +483,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). */
@@ -400,6 +505,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
@@ -409,14 +518,16 @@ 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`. */
     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. */
+    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.
@@ -610,6 +721,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;
 }
 /** Adaptador KeyValueStorage (síncrono) sobre una instancia de MMKV. */
 declare function mmkvStorage(mmkv: MmkvLike): KeyValueStorage;
@@ -622,4 +735,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 DeepdotsConfig, type DeepdotsEvent, type DeepdotsEventType, DeepdotsPopups, type DeviceInfo, type DeviceInfoLike, type EventListener, type FeedbackKV, InMemoryStorage, type KeyValueStorage, type MmkvLike, NoopPopupRenderer, POPUP_TRIGGER_CONDITION_STATUSES, type PopupDefinition, type PopupRenderer, type PopupTrigger, type PopupTriggerCondition, type PopupTriggerConditionStatus, ReactNativePopupRenderer, type ReactNativeRendererOptions, type ReactNativeSetupDeps, type ReactNativeSurveyPayload, type TriggerConfig, buildAnalyticsFeedbackBody, buildSurveyHtml, collectRnDevice, createDefaultRenderer, createFeedbackSink, mmkvStorage, setupReactNative };
+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, 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 };

package/dist/index.d.ts

@@ -352,6 +352,109 @@ declare class ContactManager {
     setAttributes(attributes: ContactAttributes): Promise<boolean>;
 }
 
+/**
+ * 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 CrashRecord {
+    crashedAt: number;
+    crashType: string;
+    message: string;
+    stack: string;
+    fatal: boolean;
+    handled: boolean;
+    severity: CrashSeverity;
+    sessionId: string | null;
+    appVersion?: string;
+    osVersion?: string;
+    deviceModel?: string;
+    context?: Record<string, string>;
+}
+interface ReportErrorOptions {
+    severity?: CrashSeverity;
+    handled?: boolean;
+    context?: Record<string, unknown>;
+}
+interface DeviceSnapshot {
+    appVersion?: string;
+    osVersion?: string;
+    deviceModel?: string;
+}
+/** 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;
+}
+interface CrashReporterOptions {
+    storage: KeyValueStorage;
+    /** Emite un evento deepdots_app_crash AHORA (app viva). */
+    emit: (params: Record<string, unknown>) => void;
+    /** Snapshot de device en el momento del crash. */
+    device: () => DeviceSnapshot;
+    /** session_id en el momento del crash. */
+    sessionId: () => string | null;
+    now?: () => number;
+    /** Kill-switch de consentimiento. */
+    enabled?: () => boolean;
+}
+/** Convierte un CrashRecord en los params del evento `deepdots_app_crash` (omite undefined). */
+declare function crashRecordToParams(r: CrashRecord): Record<string, unknown>;
+declare class CrashReporter {
+    private options;
+    private now;
+    constructor(options: CrashReporterOptions);
+    private isEnabled;
+    /** Construye un CrashRecord capturando contexto en el momento del crash. */
+    private buildRecord;
+    /** API pública del host: reporta un error (app viva) → emite el evento ya. */
+    reportError(error: unknown, options?: ReportErrorOptions): void;
+    /** Captura un error no manejado (fatal) → persiste a disco para replay en el siguiente arranque. */
+    captureUnhandled(error: unknown): void;
+    /** Persiste un crash no capturado a disco para reenviarlo en el siguiente arranque. */
+    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`). */
+    install(): void;
+    /** Engancha `global.ErrorUtils` de RN (no hay `window`): persiste y encadena al handler previo. */
+    installReactNative(errorUtils: ReactNativeErrorUtils): void;
+    /** @internal Test seam: ejercita el camino de persistencia (window handlers no son testeables en vitest). */
+    _persistForTest(error: unknown): void;
+}
+
+/**
+ * Messaging (#18–22): tracking de notificaciones del host (push / in-app).
+ * Un único evento reservado `deepdots_message` con un campo `stage` discriminador;
+ * el funnel se correlaciona por `message_id` y se agrupa por `message_title`.
+ */
+type MessageStage = 'delivered' | 'clicked' | 'converted';
+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';
+    /** Nombre de la campaña (opcional). */
+    campaign?: string;
+    /** Valor de conversión (opcional, típico en `stage: 'converted'`). */
+    value?: number;
+    currency?: string;
+    /** Parámetros libres adicionales. */
+    params?: Record<string, unknown>;
+}
+/** Construye los params del evento `deepdots_message` (omite opcionales ausentes). */
+declare function buildMessageParams(stage: MessageStage, o: TrackMessageOptions): Record<string, unknown>;
+
 /**
  * Main class for managing survey popups
  */
@@ -380,6 +483,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). */
@@ -400,6 +505,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
@@ -409,14 +518,16 @@ 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`. */
     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. */
+    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.
@@ -610,6 +721,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;
 }
 /** Adaptador KeyValueStorage (síncrono) sobre una instancia de MMKV. */
 declare function mmkvStorage(mmkv: MmkvLike): KeyValueStorage;
@@ -622,4 +735,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 DeepdotsConfig, type DeepdotsEvent, type DeepdotsEventType, DeepdotsPopups, type DeviceInfo, type DeviceInfoLike, type EventListener, type FeedbackKV, InMemoryStorage, type KeyValueStorage, type MmkvLike, NoopPopupRenderer, POPUP_TRIGGER_CONDITION_STATUSES, type PopupDefinition, type PopupRenderer, type PopupTrigger, type PopupTriggerCondition, type PopupTriggerConditionStatus, ReactNativePopupRenderer, type ReactNativeRendererOptions, type ReactNativeSetupDeps, type ReactNativeSurveyPayload, type TriggerConfig, buildAnalyticsFeedbackBody, buildSurveyHtml, collectRnDevice, createDefaultRenderer, createFeedbackSink, mmkvStorage, setupReactNative };
+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, 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 };