@magicfeedback/popup-sdk 1.1.7 → 1.1.8

package/README.md

@@ -177,6 +177,11 @@ Config fields:
 - `mode?: 'server' | 'client'`
 - `debug?: boolean`
 - `popups?: PopupDefinition[]`
+- `language?: string` — BCP-47 tag (`'en'`, `'en-US'`, …) used for popup language
+  segmentation (`segments.lang`) and for the analytics context. If omitted it is
+  auto-detected from `navigator.language`, falling back to the `Intl` locale (which is
+  what makes it work in React Native, where `navigator.language` does not exist). If no
+  source resolves a language, popups with `segments.lang` cannot be filtered and are shown.
 
 ### `autoLaunch()`
 

package/dist/index.d.mts

@@ -91,7 +91,20 @@ interface AnalyticsEnvelope {
     };
     events: AnalyticsEvent[];
 }
-type AnalyticsSink = (payload: AnalyticsEnvelope) => void;
+/** Contexto del flush, para que el sink pueda adaptar el transporte. */
+interface AnalyticsFlushMeta {
+    /**
+     * `true` cuando el flush ocurre porque la página/app se está cerrando. El sink debe usar
+     * un transporte que sobreviva al unload (sendBeacon) y no puede esperar respuestas.
+     */
+    final?: boolean;
+}
+/**
+ * Envío del lote. Si devuelve una promesa que **rechaza**, el manager re-encola los
+ * eventos para reintentarlos en el siguiente flush (fallo transitorio: red o 5xx).
+ * Resolver = lote entregado o descartado definitivamente (no se reintenta).
+ */
+type AnalyticsSink = (payload: AnalyticsEnvelope, meta?: AnalyticsFlushMeta) => void | Promise<void>;
 
 /**
  * Mapeo del envelope de analytics → body de `POST /sdk/feedback`.
@@ -143,15 +156,29 @@ interface FeedbackSinkOptions {
     log?: (...args: unknown[]) => void;
     /** fetch inyectable (tests / RN). */
     fetchImpl?: typeof fetch;
+    /**
+     * `navigator.sendBeacon` inyectable. Solo se usa en el flush final (cierre de página):
+     * sobrevive al unload, a cambio de no poder leer la respuesta. Si no se pasa, el flush
+     * final usa `fetch` con `keepalive`.
+     */
+    sendBeaconImpl?: (url: string, body: Blob | string) => boolean;
     /** Callback invocado cuando el backend devuelve un nuevo sessionId (primer POST). */
     onSessionId?: (id: string) => void;
 }
 /**
  * Sink real: transforma el envelope y hace `POST {baseUrl}/sdk/feedback`.
- * Fire-and-forget (no bloquea el flush); errores solo se loguean.
- * 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.
+ *
+ * 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.
+ *
+ * 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;
+ *  - `keepalive` para que el navegador no cancele el POST al navegar fuera, y `sendBeacon`
+ *    en el flush final (cierre de página), donde `fetch` puede morir con el documento;
+ *  - 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.
  */
 declare function createFeedbackSink(options: FeedbackSinkOptions): AnalyticsSink;
 
@@ -190,9 +217,11 @@ interface DeepdotsInitParams {
     /** Platform used in the analytics envelope. Default is 'web'; in RN pass 'android'/'ios'. */
     platform?: 'web' | 'android' | 'ios';
     /**
-     * BCP-47 language tag for the analytics context (e.g. 'es-ES'). If omitted, the SDK
-     * auto-detects: `navigator.language` on web, or the `Intl` locale as a fallback (works in
-     * React Native with Hermes, where `navigator.language` is absent).
+     * BCP-47 language tag (e.g. 'es-ES') used for the analytics context AND for popup
+     * language segmentation (`segments.lang`). If omitted, the SDK auto-detects:
+     * `navigator.language` on web, or the `Intl` locale as a fallback (works in
+     * React Native with Hermes, where `navigator.language` is absent). If no source
+     * resolves a language, popups with `segments.lang` cannot be filtered and are shown.
      */
     language?: string;
     /** Injectable device info (RN: from react-native-device-info). If missing, it is derived from the browser. */
@@ -527,6 +556,11 @@ declare class DeepdotsPopups {
     private contact;
     /** Marca si ya se inició la navegación manual (setScreen) — para RN sin History API. */
     private navStarted;
+    /**
+     * 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.
+     */
+    private language;
     /** Initialize the SDK with configuration */
     init(config: DeepdotsInitParams): void;
     /** User id actual (generado por el SDK o provisto por el cliente). Null si tracking off. */
@@ -581,8 +615,14 @@ declare class DeepdotsPopups {
     onBackground(): void;
     /** Payload que se ENVIARÍA al endpoint de analytics (no envía ni vacía el buffer). */
     previewAnalytics(): AnalyticsEnvelope;
-    /** Envía (hoy dry-run → console.log) el lote acumulado de analytics y vacía el buffer. */
-    flushAnalytics(): void;
+    /**
+     * Envía el lote acumulado de analytics y vacía el buffer.
+     * `final: true` (cierre de página/app) cambia el transporte a `sendBeacon`, que sobrevive
+     * al unload; un lote que falle por red o 5xx se re-encola para el siguiente flush.
+     */
+    flushAnalytics(options?: {
+        final?: boolean;
+    }): void;
     /** Emite un evento `user_engagement` con el tiempo activo acumulado (#8). */
     private flushEngagement;
     private analyticsIdentity;

package/dist/index.d.ts

@@ -91,7 +91,20 @@ interface AnalyticsEnvelope {
     };
     events: AnalyticsEvent[];
 }
-type AnalyticsSink = (payload: AnalyticsEnvelope) => void;
+/** Contexto del flush, para que el sink pueda adaptar el transporte. */
+interface AnalyticsFlushMeta {
+    /**
+     * `true` cuando el flush ocurre porque la página/app se está cerrando. El sink debe usar
+     * un transporte que sobreviva al unload (sendBeacon) y no puede esperar respuestas.
+     */
+    final?: boolean;
+}
+/**
+ * Envío del lote. Si devuelve una promesa que **rechaza**, el manager re-encola los
+ * eventos para reintentarlos en el siguiente flush (fallo transitorio: red o 5xx).
+ * Resolver = lote entregado o descartado definitivamente (no se reintenta).
+ */
+type AnalyticsSink = (payload: AnalyticsEnvelope, meta?: AnalyticsFlushMeta) => void | Promise<void>;
 
 /**
  * Mapeo del envelope de analytics → body de `POST /sdk/feedback`.
@@ -143,15 +156,29 @@ interface FeedbackSinkOptions {
     log?: (...args: unknown[]) => void;
     /** fetch inyectable (tests / RN). */
     fetchImpl?: typeof fetch;
+    /**
+     * `navigator.sendBeacon` inyectable. Solo se usa en el flush final (cierre de página):
+     * sobrevive al unload, a cambio de no poder leer la respuesta. Si no se pasa, el flush
+     * final usa `fetch` con `keepalive`.
+     */
+    sendBeaconImpl?: (url: string, body: Blob | string) => boolean;
     /** Callback invocado cuando el backend devuelve un nuevo sessionId (primer POST). */
     onSessionId?: (id: string) => void;
 }
 /**
  * Sink real: transforma el envelope y hace `POST {baseUrl}/sdk/feedback`.
- * Fire-and-forget (no bloquea el flush); errores solo se loguean.
- * 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.
+ *
+ * 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.
+ *
+ * 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;
+ *  - `keepalive` para que el navegador no cancele el POST al navegar fuera, y `sendBeacon`
+ *    en el flush final (cierre de página), donde `fetch` puede morir con el documento;
+ *  - 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.
  */
 declare function createFeedbackSink(options: FeedbackSinkOptions): AnalyticsSink;
 
@@ -190,9 +217,11 @@ interface DeepdotsInitParams {
     /** Platform used in the analytics envelope. Default is 'web'; in RN pass 'android'/'ios'. */
     platform?: 'web' | 'android' | 'ios';
     /**
-     * BCP-47 language tag for the analytics context (e.g. 'es-ES'). If omitted, the SDK
-     * auto-detects: `navigator.language` on web, or the `Intl` locale as a fallback (works in
-     * React Native with Hermes, where `navigator.language` is absent).
+     * BCP-47 language tag (e.g. 'es-ES') used for the analytics context AND for popup
+     * language segmentation (`segments.lang`). If omitted, the SDK auto-detects:
+     * `navigator.language` on web, or the `Intl` locale as a fallback (works in
+     * React Native with Hermes, where `navigator.language` is absent). If no source
+     * resolves a language, popups with `segments.lang` cannot be filtered and are shown.
      */
     language?: string;
     /** Injectable device info (RN: from react-native-device-info). If missing, it is derived from the browser. */
@@ -527,6 +556,11 @@ declare class DeepdotsPopups {
     private contact;
     /** Marca si ya se inició la navegación manual (setScreen) — para RN sin History API. */
     private navStarted;
+    /**
+     * 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.
+     */
+    private language;
     /** Initialize the SDK with configuration */
     init(config: DeepdotsInitParams): void;
     /** User id actual (generado por el SDK o provisto por el cliente). Null si tracking off. */
@@ -581,8 +615,14 @@ declare class DeepdotsPopups {
     onBackground(): void;
     /** Payload que se ENVIARÍA al endpoint de analytics (no envía ni vacía el buffer). */
     previewAnalytics(): AnalyticsEnvelope;
-    /** Envía (hoy dry-run → console.log) el lote acumulado de analytics y vacía el buffer. */
-    flushAnalytics(): void;
+    /**
+     * Envía el lote acumulado de analytics y vacía el buffer.
+     * `final: true` (cierre de página/app) cambia el transporte a `sendBeacon`, que sobrevive
+     * al unload; un lote que falle por red o 5xx se re-encola para el siguiente flush.
+     */
+    flushAnalytics(options?: {
+        final?: boolean;
+    }): void;
     /** Emite un evento `user_engagement` con el tiempo activo acumulado (#8). */
     private flushEngagement;
     private analyticsIdentity;

package/dist/index.js

@@ -3968,6 +3968,7 @@ var AnalyticsManager = class {
     this.device = options.device;
     this.platform = options.platform ?? "web";
     this.maxBatchSize = options.maxBatchSize ?? 20;
+    this.maxBufferedEvents = options.maxBufferedEvents ?? 200;
     this.onFlushNeeded = options.onFlushNeeded;
   }
   /** Actualiza campos de device en runtime (p.ej. country/city tras resolver geo). */
@@ -4028,6 +4029,7 @@ var AnalyticsManager = class {
       timestamp: this.now(),
       params: Object.keys(merged).length ? merged : void 0
     });
+    this.enforceBufferCap();
     if (this.events.length >= this.maxBatchSize) {
       this.onFlushNeeded?.();
     }
@@ -4058,14 +4060,43 @@ var AnalyticsManager = class {
       events: [...this.events]
     };
   }
-  /** Envía (vía sink) el lote acumulado y vacía el buffer. No-op si no hay eventos. */
-  flush(identity) {
+  /**
+   * Envía (vía sink) el lote acumulado y vacía el buffer. No-op si no hay eventos.
+   *
+   * Si el sink falla de forma transitoria (promesa rechazada o excepción síncrona) el lote
+   * se **re-encola** al principio del buffer y se reintenta en el siguiente flush: un error
+   * de red o un 5xx no debe hacer desaparecer los eventos.
+   */
+  flush(identity, meta) {
     if (this.events.length === 0) return null;
+    const batch = this.events;
     const payload = this.buildPayload(identity);
-    this.sink(payload);
     this.events = [];
+    let result;
+    try {
+      result = meta ? this.sink(payload, meta) : this.sink(payload);
+    } catch {
+      this.requeue(batch);
+      return payload;
+    }
+    if (result && typeof result.then === "function") {
+      result.catch(() => this.requeue(batch));
+    }
     return payload;
   }
+  /**
+   * Devuelve un lote fallido al buffer, delante de lo que haya llegado mientras se enviaba
+   * (orden cronológico). Con el buffer lleno se descartan los eventos más antiguos.
+   */
+  requeue(batch) {
+    this.events = [...batch, ...this.events];
+    this.enforceBufferCap();
+  }
+  /** Techo del buffer: si el envío lleva rato fallando, se sacrifica lo más antiguo. */
+  enforceBufferCap() {
+    const overflow = this.events.length - this.maxBufferedEvents;
+    if (overflow > 0) this.events.splice(0, overflow);
+  }
 };
 
 // src/analytics/feedback-payload.ts
@@ -4128,33 +4159,80 @@ function buildAnalyticsFeedbackBody(envelope, keys, feedbackSessionId) {
     ...feedbackSessionId ? { sessionId: feedbackSessionId } : {}
   };
 }
+var KEEPALIVE_MAX_BYTES = 6e4;
+function isRetryableStatus(status) {
+  return status >= 500 || status === 408 || status === 429;
+}
+async function safeBodyText(res) {
+  try {
+    return (await res.text()).slice(0, 500);
+  } catch {
+    return "";
+  }
+}
 function createFeedbackSink(options) {
   let feedbackSessionId;
-  return (envelope) => {
-    const body = buildAnalyticsFeedbackBody(envelope, options.keys, feedbackSessionId);
+  let firstPostInFlight = null;
+  const url = `${options.baseUrl}/sdk/feedback`;
+  const post = async (body, final) => {
+    const json = JSON.stringify(body);
+    const small = json.length <= KEEPALIVE_MAX_BYTES;
+    if (final && options.sendBeaconImpl && small) {
+      const payload = typeof Blob !== "undefined" ? new Blob([json], { type: "application/json" }) : json;
+      if (options.sendBeaconImpl(url, payload)) {
+        options.log?.("[DeepdotsAnalytics] flush final v\xEDa sendBeacon");
+        return;
+      }
+      options.log?.("[DeepdotsAnalytics] sendBeacon rechaz\xF3 el lote; fallback a fetch");
+    }
     const f = options.fetchImpl ?? (typeof fetch !== "undefined" ? fetch : void 0);
     if (!f) {
       options.log?.("[DeepdotsAnalytics] no fetch disponible; payload no enviado", body);
       return;
     }
-    options.log?.("[DeepdotsAnalytics] POST /sdk/feedback \u2192", body);
-    f(`${options.baseUrl}/sdk/feedback`, {
+    const res = await f(url, {
       method: "POST",
       headers: { "Content-Type": "application/json" },
-      body: JSON.stringify(body)
-    }).then(async (res) => {
-      if (res.ok) {
-        try {
-          const data = await res.json();
-          if (data?.sessionId && data.sessionId !== feedbackSessionId) {
-            feedbackSessionId = data.sessionId;
-            options.log?.("[DeepdotsAnalytics] feedbackSessionId cacheado:", feedbackSessionId);
-            options.onSessionId?.(feedbackSessionId);
-          }
-        } catch {
-        }
+      body: json,
+      // keepalive: el POST sobrevive a la navegación mientras el body sea pequeño.
+      ...small ? { keepalive: true } : {}
+    });
+    if (!res.ok) {
+      const detail = await safeBodyText(res);
+      if (isRetryableStatus(res.status)) {
+        throw new Error(`POST /sdk/feedback ${res.status} (reintentable): ${detail}`);
+      }
+      options.log?.(
+        `[DeepdotsAnalytics] POST /sdk/feedback rechazado con ${res.status}; lote DESCARTADO:`,
+        detail
+      );
+      return;
+    }
+    try {
+      const data = await res.json();
+      if (data?.sessionId && data.sessionId !== feedbackSessionId) {
+        feedbackSessionId = data.sessionId;
+        options.log?.("[DeepdotsAnalytics] feedbackSessionId cacheado:", feedbackSessionId);
+        options.onSessionId?.(feedbackSessionId);
       }
-    }).catch((err) => options.log?.("[DeepdotsAnalytics] error enviando feedback", err));
+    } catch {
+    }
+  };
+  return async (envelope, meta) => {
+    const final = meta?.final === true;
+    if (!feedbackSessionId && firstPostInFlight && !final) {
+      await firstPostInFlight;
+    }
+    const body = buildAnalyticsFeedbackBody(envelope, options.keys, feedbackSessionId);
+    options.log?.("[DeepdotsAnalytics] POST /sdk/feedback \u2192", body);
+    const sent = post(body, final);
+    if (!feedbackSessionId) {
+      firstPostInFlight = sent.then(
+        () => void 0,
+        () => void 0
+      );
+    }
+    await sent;
   };
 }
 
@@ -4648,6 +4726,11 @@ var DeepdotsPopups = class {
     this.contact = null;
     /** Marca si ya se inició la navegación manual (setScreen) — para RN sin History API. */
     this.navStarted = false;
+    /**
+     * 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.
+     */
+    this.language = void 0;
   }
   /** Initialize the SDK with configuration */
   init(config) {
@@ -4689,19 +4772,22 @@ var DeepdotsPopups = class {
       baseUrl: this.baseUrl,
       keys: config.analytics,
       log: (...a) => this.log(...a),
+      // sendBeacon: único transporte que sobrevive al cierre de la página.
+      sendBeaconImpl: typeof navigator !== "undefined" && typeof navigator.sendBeacon === "function" ? (url, body) => navigator.sendBeacon(url, body) : void 0,
       onSessionId: (id) => {
         this.analyticsFeedbackSessionId = id;
       }
     }) : createDryRunSink((...a) => this.logger.log(...a));
     const device = config.device ?? collectDeviceInfo(config.appVersion);
+    this.language = resolveLanguage({
+      explicit: config.language,
+      navigator: typeof navigator !== "undefined" ? navigator : void 0,
+      intl: typeof Intl !== "undefined" ? Intl : void 0
+    });
     this.analytics = new AnalyticsManager({
       sink: analyticsSink,
       publicKey: config.analytics?.publicKey ?? this.config.apiKey,
-      language: resolveLanguage({
-        explicit: config.language,
-        navigator: typeof navigator !== "undefined" ? navigator : void 0,
-        intl: typeof Intl !== "undefined" ? Intl : void 0
-      }),
+      language: this.language,
       platform: config.platform ?? "web",
       device,
       maxBatchSize: ANALYTICS_MAX_BATCH_SIZE,
@@ -4877,10 +4963,14 @@ var DeepdotsPopups = class {
       events: []
     };
   }
-  /** Envía (hoy dry-run → console.log) el lote acumulado de analytics y vacía el buffer. */
-  flushAnalytics() {
+  /**
+   * Envía el lote acumulado de analytics y vacía el buffer.
+   * `final: true` (cierre de página/app) cambia el transporte a `sendBeacon`, que sobrevive
+   * al unload; un lote que falle por red o 5xx se re-encola para el siguiente flush.
+   */
+  flushAnalytics(options) {
     if (!this.tracking?.isTrackingEnabled()) return;
-    this.analytics?.flush(this.analyticsIdentity());
+    this.analytics?.flush(this.analyticsIdentity(), options);
   }
   /** Emite un evento `user_engagement` con el tiempo activo acumulado (#8). */
   flushEngagement() {
@@ -4903,7 +4993,7 @@ var DeepdotsPopups = class {
       this.navObserver?.stop();
       if (this.tracking?.isTrackingEnabled()) this.analytics?.exitAllMiniServices();
       this.flushEngagement();
-      this.flushAnalytics();
+      this.flushAnalytics({ final: true });
     });
     document.addEventListener("visibilitychange", () => {
       if (document.visibilityState === "hidden") {
@@ -5024,14 +5114,16 @@ var DeepdotsPopups = class {
   matchesSegmentsLang(def) {
     const langs = def.segments?.lang;
     if (!langs || langs.length === 0) return true;
-    const browserLang = (typeof navigator !== "undefined" ? navigator.language : "").toLowerCase();
-    if (!browserLang) {
-      this.debug("No navigator.language available for lang comparison", { popupId: def.id, langs });
+    const currentLang = (this.language ?? "").toLowerCase();
+    if (!currentLang) {
+      this.debug("No language available for lang comparison", { popupId: def.id, langs });
       return true;
     }
-    const matches = langs.some((lang) => browserLang.startsWith(lang.toLowerCase()));
+    const matches = langs.some(
+      (lang) => typeof lang === "string" && currentLang.startsWith(lang.toLowerCase())
+    );
     if (!matches) {
-      this.debug("Lang mismatch for popup", { popupId: def.id, langs, browserLang });
+      this.debug("Lang mismatch for popup", { popupId: def.id, langs, currentLang });
     }
     return matches;
   }