@sendoracloud/sdk-react-native 1.4.0 → 1.6.0

package/dist/index.cjs

@@ -1760,15 +1760,16 @@ var import_react_native3 = require("react-native");
 var DEFAULT_IDLE_MS = 30 * 60 * 1e3;
 function resolveFlags(cfg) {
   if (cfg === false) {
-    return { appOpen: false, sessionStart: false, appBackground: false };
+    return { appOpen: false, sessionStart: false, appBackground: false, engagement: false };
   }
   if (cfg === true || cfg === void 0) {
-    return { appOpen: true, sessionStart: true, appBackground: true };
+    return { appOpen: true, sessionStart: true, appBackground: true, engagement: true };
   }
   return {
     appOpen: cfg.appOpen ?? true,
     sessionStart: cfg.sessionStart ?? true,
-    appBackground: cfg.appBackground ?? true
+    appBackground: cfg.appBackground ?? true,
+    engagement: cfg.engagement ?? true
   };
 }
 function installAutoTrack(args) {
@@ -1799,15 +1800,21 @@ function installAutoTrack(args) {
   if (flags.appOpen) {
     args.fire("app.opened", { sessionId });
   }
-  if (flags.appBackground) {
+  if (flags.appBackground || flags.engagement) {
     const AppState = import_react_native3.AppState;
     if (AppState && typeof AppState.addEventListener === "function") {
       const handler = (state) => {
         ensureSession(true);
         if (state === "background" || state === "inactive") {
-          args.fire("app.backgrounded", { sessionId: args.getSessionId() });
+          if (flags.engagement) args.onForeground?.(false);
+          if (flags.appBackground) {
+            args.fire("app.backgrounded", { sessionId: args.getSessionId() });
+          }
         } else if (state === "active") {
-          args.fire("app.foregrounded", { sessionId: args.getSessionId() });
+          if (flags.appBackground) {
+            args.fire("app.foregrounded", { sessionId: args.getSessionId() });
+          }
+          if (flags.engagement) args.onForeground?.(true);
         }
       };
       const sub = AppState.addEventListener("change", handler);
@@ -1848,6 +1855,8 @@ var MAX_PUSH_METADATA_BYTES = 4096;
 var MAX_USER_ID_LEN = 256;
 var MAX_TRAITS_BYTES = 32 * 1024;
 var MAX_PROPERTIES_BYTES = 32 * 1024;
+var MIN_ENGAGEMENT_MS = 250;
+var MAX_ENGAGEMENT_MS = 6 * 60 * 60 * 1e3;
 function assertCSPRNG() {
   const g = globalThis;
   if (g.crypto?.getRandomValues) {
@@ -1898,6 +1907,12 @@ var SendoraSDK = class {
     this.debug = false;
     this.sessionId = "";
     this.autoTrackCleanup = null;
+    // --- Engagement time (foreground-only, Wave 75) ---
+    this.engEnabled = false;
+    this.engScreen = null;
+    this.engAccumMs = 0;
+    // >0 = accumulating since this timestamp; 0 = paused (backgrounded).
+    this.engSegmentStart = 0;
     /**
      * Lazy-allocated stable session id for chatbot conversations.
      * Survives only the JS lifetime — chatbot multi-turn context lives
@@ -1988,12 +2003,17 @@ var SendoraSDK = class {
     });
     this.ready = true;
     if (config.autoTrack !== false) {
+      this.engEnabled = config.autoTrack === true || config.autoTrack === void 0 || config.autoTrack.engagement !== false;
       this.autoTrackCleanup = installAutoTrack({
         config: this.config,
         fire: (eventType, properties) => this.track(eventType, properties),
         getSessionId: () => this.sessionId,
         setSessionId: (id) => {
           this.sessionId = id;
+        },
+        onForeground: (active) => {
+          if (active) this.engResume();
+          else this.engFlush();
         }
       });
     }
@@ -2057,10 +2077,53 @@ var SendoraSDK = class {
     if (typeof name !== "string" || name.length === 0 || name.length > 256) {
       throw new Error("[sendoracloud] screen name must be a 1-256 char string.");
     }
+    this.engFlush();
     void this.sendEvent("screen", {
       eventType: "screen.viewed",
       properties: { screenName: name, ...properties ?? {} }
     });
+    this.engEnter(name);
+  }
+  // --- Engagement timer (foreground-only, Wave 75) ---
+  /** Bank the in-flight foreground segment into the accumulator + pause. */
+  engBank() {
+    if (this.engSegmentStart > 0) {
+      this.engAccumMs += Date.now() - this.engSegmentStart;
+      this.engSegmentStart = 0;
+    }
+  }
+  /**
+   * Emit `app.engagement` for the current screen with foreground-only
+   * durationMs, then reset the accumulator. Sub-threshold (redirect
+   * flicker) spans are dropped; absurd spans clamp to a 6h ceiling.
+   * Never throws — engagement is best-effort instrumentation.
+   */
+  engFlush() {
+    if (!this.engEnabled || this.engScreen === null) return;
+    this.engBank();
+    let ms = this.engAccumMs;
+    this.engAccumMs = 0;
+    if (ms < MIN_ENGAGEMENT_MS) return;
+    if (ms > MAX_ENGAGEMENT_MS) ms = MAX_ENGAGEMENT_MS;
+    try {
+      void this.sendEvent("track", {
+        eventType: "app.engagement",
+        properties: { durationMs: Math.round(ms), screen: this.engScreen, sessionId: this.sessionId }
+      });
+    } catch {
+    }
+  }
+  /** Start measuring a new screen (foreground from now). */
+  engEnter(name) {
+    if (!this.engEnabled) return;
+    this.engScreen = name;
+    this.engAccumMs = 0;
+    this.engSegmentStart = Date.now();
+  }
+  /** Resume accumulation after the app returns to foreground. */
+  engResume() {
+    if (!this.engEnabled || this.engScreen === null) return;
+    if (this.engSegmentStart === 0) this.engSegmentStart = Date.now();
   }
   /**
    * Register a device push token (APNs or FCM) so server-side
@@ -2308,6 +2371,22 @@ var SendoraSDK = class {
         const parsed = await res.json();
         if (!parsed.success || !parsed.data) throw new Error("[sendoracloud] support.submitCsat: bad response");
         return parsed.data;
+      },
+      getUnreadCount: async (widgetId) => {
+        if (!self.config || !widgetId) return 0;
+        const token = await self.auth.getAccessToken();
+        if (!token) return 0;
+        try {
+          const res = await fetch(
+            `${self.config.apiUrl}/api/v1/widgets/${encodeURIComponent(widgetId)}/my-tickets/unread-count`,
+            { headers: { Authorization: `Bearer ${token}` } }
+          );
+          if (!res.ok) return 0;
+          const parsed = await res.json();
+          return parsed?.data?.count ?? 0;
+        } catch {
+          return 0;
+        }
       }
     };
   }
@@ -2605,6 +2684,7 @@ var SendoraSDK = class {
   }
   /** Tear down auto-track listeners. Call in test harnesses. */
   destroy() {
+    this.engFlush();
     if (this.autoTrackCleanup) {
       this.autoTrackCleanup();
       this.autoTrackCleanup = null;

package/dist/index.d.cts

@@ -728,6 +728,10 @@ interface SendoraConfig {
      *   (idle >`sessionIdleMs` closes session). Default true.
      * - `appBackground` — emit `app.backgrounded`/`app.foregrounded` on
      *   AppState transitions. Default true.
+     * - `engagement` — emit `app.engagement` with foreground-only `durationMs`
+     *   per screen on the next `screen()` call + on app-background (GA4
+     *   user_engagement parity). Default true. Only measures named screens —
+     *   it has no effect until you start calling `screen()`.
      *
      * Note: screen view tracking is NOT auto — RN has no canonical router.
      * Call `SendoraCloud.screen(name)` from your navigation listener.
@@ -736,6 +740,7 @@ interface SendoraConfig {
         appOpen?: boolean;
         sessionStart?: boolean;
         appBackground?: boolean;
+        engagement?: boolean;
     };
     /** Idle threshold (ms) for session expiry; default 30 minutes. */
     sessionIdleMs?: number;
@@ -827,6 +832,10 @@ declare class SendoraSDK {
     private debug;
     private sessionId;
     private autoTrackCleanup;
+    private engEnabled;
+    private engScreen;
+    private engAccumMs;
+    private engSegmentStart;
     /** Lazy-initialised in init() once we know the apiUrl + publicKey. */
     auth: Auth;
     /** Lazy-initialised in init(). Deep-link surface: create + handleUniversalLink + matchDeferred. */
@@ -847,6 +856,19 @@ declare class SendoraSDK {
     track(eventType: string, properties?: TrackProperties): void;
     /** RN equivalent of page view — call on route / screen change. */
     screen(name: string, properties?: TrackProperties): void;
+    /** Bank the in-flight foreground segment into the accumulator + pause. */
+    private engBank;
+    /**
+     * Emit `app.engagement` for the current screen with foreground-only
+     * durationMs, then reset the accumulator. Sub-threshold (redirect
+     * flicker) spans are dropped; absurd spans clamp to a 6h ceiling.
+     * Never throws — engagement is best-effort instrumentation.
+     */
+    private engFlush;
+    /** Start measuring a new screen (foreground from now). */
+    private engEnter;
+    /** Resume accumulation after the app returns to foreground. */
+    private engResume;
     /**
      * Register a device push token (APNs or FCM) so server-side
      * workflows can target this user. The caller is responsible for
@@ -1008,6 +1030,13 @@ declare class SendoraSDK {
             rating: number;
             comment: string | null;
         }>;
+        /**
+         * Wave 73 — unread support-ticket count for the in-app badge.
+         * Bearer JWT auth via the SDK's current end-user session.
+         * Returns 0 if no auth (anon or identified) is available.
+         * Recommended cadence: AppState foreground + every 60s.
+         */
+        getUnreadCount: (widgetId: string) => Promise<number>;
     };
     /**
      * Knowledge-base search namespace. Mirrors backend `GET /kb/search`

package/dist/index.d.ts

@@ -728,6 +728,10 @@ interface SendoraConfig {
      *   (idle >`sessionIdleMs` closes session). Default true.
      * - `appBackground` — emit `app.backgrounded`/`app.foregrounded` on
      *   AppState transitions. Default true.
+     * - `engagement` — emit `app.engagement` with foreground-only `durationMs`
+     *   per screen on the next `screen()` call + on app-background (GA4
+     *   user_engagement parity). Default true. Only measures named screens —
+     *   it has no effect until you start calling `screen()`.
      *
      * Note: screen view tracking is NOT auto — RN has no canonical router.
      * Call `SendoraCloud.screen(name)` from your navigation listener.
@@ -736,6 +740,7 @@ interface SendoraConfig {
         appOpen?: boolean;
         sessionStart?: boolean;
         appBackground?: boolean;
+        engagement?: boolean;
     };
     /** Idle threshold (ms) for session expiry; default 30 minutes. */
     sessionIdleMs?: number;
@@ -827,6 +832,10 @@ declare class SendoraSDK {
     private debug;
     private sessionId;
     private autoTrackCleanup;
+    private engEnabled;
+    private engScreen;
+    private engAccumMs;
+    private engSegmentStart;
     /** Lazy-initialised in init() once we know the apiUrl + publicKey. */
     auth: Auth;
     /** Lazy-initialised in init(). Deep-link surface: create + handleUniversalLink + matchDeferred. */
@@ -847,6 +856,19 @@ declare class SendoraSDK {
     track(eventType: string, properties?: TrackProperties): void;
     /** RN equivalent of page view — call on route / screen change. */
     screen(name: string, properties?: TrackProperties): void;
+    /** Bank the in-flight foreground segment into the accumulator + pause. */
+    private engBank;
+    /**
+     * Emit `app.engagement` for the current screen with foreground-only
+     * durationMs, then reset the accumulator. Sub-threshold (redirect
+     * flicker) spans are dropped; absurd spans clamp to a 6h ceiling.
+     * Never throws — engagement is best-effort instrumentation.
+     */
+    private engFlush;
+    /** Start measuring a new screen (foreground from now). */
+    private engEnter;
+    /** Resume accumulation after the app returns to foreground. */
+    private engResume;
     /**
      * Register a device push token (APNs or FCM) so server-side
      * workflows can target this user. The caller is responsible for
@@ -1008,6 +1030,13 @@ declare class SendoraSDK {
             rating: number;
             comment: string | null;
         }>;
+        /**
+         * Wave 73 — unread support-ticket count for the in-app badge.
+         * Bearer JWT auth via the SDK's current end-user session.
+         * Returns 0 if no auth (anon or identified) is available.
+         * Recommended cadence: AppState foreground + every 60s.
+         */
+        getUnreadCount: (widgetId: string) => Promise<number>;
     };
     /**
      * Knowledge-base search namespace. Mirrors backend `GET /kb/search`

package/dist/index.js

@@ -1722,15 +1722,16 @@ import { AppState as RnAppState2 } from "react-native";
 var DEFAULT_IDLE_MS = 30 * 60 * 1e3;
 function resolveFlags(cfg) {
   if (cfg === false) {
-    return { appOpen: false, sessionStart: false, appBackground: false };
+    return { appOpen: false, sessionStart: false, appBackground: false, engagement: false };
   }
   if (cfg === true || cfg === void 0) {
-    return { appOpen: true, sessionStart: true, appBackground: true };
+    return { appOpen: true, sessionStart: true, appBackground: true, engagement: true };
   }
   return {
     appOpen: cfg.appOpen ?? true,
     sessionStart: cfg.sessionStart ?? true,
-    appBackground: cfg.appBackground ?? true
+    appBackground: cfg.appBackground ?? true,
+    engagement: cfg.engagement ?? true
   };
 }
 function installAutoTrack(args) {
@@ -1761,15 +1762,21 @@ function installAutoTrack(args) {
   if (flags.appOpen) {
     args.fire("app.opened", { sessionId });
   }
-  if (flags.appBackground) {
+  if (flags.appBackground || flags.engagement) {
     const AppState = RnAppState2;
     if (AppState && typeof AppState.addEventListener === "function") {
       const handler = (state) => {
         ensureSession(true);
         if (state === "background" || state === "inactive") {
-          args.fire("app.backgrounded", { sessionId: args.getSessionId() });
+          if (flags.engagement) args.onForeground?.(false);
+          if (flags.appBackground) {
+            args.fire("app.backgrounded", { sessionId: args.getSessionId() });
+          }
         } else if (state === "active") {
-          args.fire("app.foregrounded", { sessionId: args.getSessionId() });
+          if (flags.appBackground) {
+            args.fire("app.foregrounded", { sessionId: args.getSessionId() });
+          }
+          if (flags.engagement) args.onForeground?.(true);
         }
       };
       const sub = AppState.addEventListener("change", handler);
@@ -1810,6 +1817,8 @@ var MAX_PUSH_METADATA_BYTES = 4096;
 var MAX_USER_ID_LEN = 256;
 var MAX_TRAITS_BYTES = 32 * 1024;
 var MAX_PROPERTIES_BYTES = 32 * 1024;
+var MIN_ENGAGEMENT_MS = 250;
+var MAX_ENGAGEMENT_MS = 6 * 60 * 60 * 1e3;
 function assertCSPRNG() {
   const g = globalThis;
   if (g.crypto?.getRandomValues) {
@@ -1860,6 +1869,12 @@ var SendoraSDK = class {
     this.debug = false;
     this.sessionId = "";
     this.autoTrackCleanup = null;
+    // --- Engagement time (foreground-only, Wave 75) ---
+    this.engEnabled = false;
+    this.engScreen = null;
+    this.engAccumMs = 0;
+    // >0 = accumulating since this timestamp; 0 = paused (backgrounded).
+    this.engSegmentStart = 0;
     /**
      * Lazy-allocated stable session id for chatbot conversations.
      * Survives only the JS lifetime — chatbot multi-turn context lives
@@ -1950,12 +1965,17 @@ var SendoraSDK = class {
     });
     this.ready = true;
     if (config.autoTrack !== false) {
+      this.engEnabled = config.autoTrack === true || config.autoTrack === void 0 || config.autoTrack.engagement !== false;
       this.autoTrackCleanup = installAutoTrack({
         config: this.config,
         fire: (eventType, properties) => this.track(eventType, properties),
         getSessionId: () => this.sessionId,
         setSessionId: (id) => {
           this.sessionId = id;
+        },
+        onForeground: (active) => {
+          if (active) this.engResume();
+          else this.engFlush();
         }
       });
     }
@@ -2019,10 +2039,53 @@ var SendoraSDK = class {
     if (typeof name !== "string" || name.length === 0 || name.length > 256) {
       throw new Error("[sendoracloud] screen name must be a 1-256 char string.");
     }
+    this.engFlush();
     void this.sendEvent("screen", {
       eventType: "screen.viewed",
       properties: { screenName: name, ...properties ?? {} }
     });
+    this.engEnter(name);
+  }
+  // --- Engagement timer (foreground-only, Wave 75) ---
+  /** Bank the in-flight foreground segment into the accumulator + pause. */
+  engBank() {
+    if (this.engSegmentStart > 0) {
+      this.engAccumMs += Date.now() - this.engSegmentStart;
+      this.engSegmentStart = 0;
+    }
+  }
+  /**
+   * Emit `app.engagement` for the current screen with foreground-only
+   * durationMs, then reset the accumulator. Sub-threshold (redirect
+   * flicker) spans are dropped; absurd spans clamp to a 6h ceiling.
+   * Never throws — engagement is best-effort instrumentation.
+   */
+  engFlush() {
+    if (!this.engEnabled || this.engScreen === null) return;
+    this.engBank();
+    let ms = this.engAccumMs;
+    this.engAccumMs = 0;
+    if (ms < MIN_ENGAGEMENT_MS) return;
+    if (ms > MAX_ENGAGEMENT_MS) ms = MAX_ENGAGEMENT_MS;
+    try {
+      void this.sendEvent("track", {
+        eventType: "app.engagement",
+        properties: { durationMs: Math.round(ms), screen: this.engScreen, sessionId: this.sessionId }
+      });
+    } catch {
+    }
+  }
+  /** Start measuring a new screen (foreground from now). */
+  engEnter(name) {
+    if (!this.engEnabled) return;
+    this.engScreen = name;
+    this.engAccumMs = 0;
+    this.engSegmentStart = Date.now();
+  }
+  /** Resume accumulation after the app returns to foreground. */
+  engResume() {
+    if (!this.engEnabled || this.engScreen === null) return;
+    if (this.engSegmentStart === 0) this.engSegmentStart = Date.now();
   }
   /**
    * Register a device push token (APNs or FCM) so server-side
@@ -2270,6 +2333,22 @@ var SendoraSDK = class {
         const parsed = await res.json();
         if (!parsed.success || !parsed.data) throw new Error("[sendoracloud] support.submitCsat: bad response");
         return parsed.data;
+      },
+      getUnreadCount: async (widgetId) => {
+        if (!self.config || !widgetId) return 0;
+        const token = await self.auth.getAccessToken();
+        if (!token) return 0;
+        try {
+          const res = await fetch(
+            `${self.config.apiUrl}/api/v1/widgets/${encodeURIComponent(widgetId)}/my-tickets/unread-count`,
+            { headers: { Authorization: `Bearer ${token}` } }
+          );
+          if (!res.ok) return 0;
+          const parsed = await res.json();
+          return parsed?.data?.count ?? 0;
+        } catch {
+          return 0;
+        }
       }
     };
   }
@@ -2567,6 +2646,7 @@ var SendoraSDK = class {
   }
   /** Tear down auto-track listeners. Call in test harnesses. */
   destroy() {
+    this.engFlush();
     if (this.autoTrackCleanup) {
       this.autoTrackCleanup();
       this.autoTrackCleanup = null;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sendoracloud/sdk-react-native",
-  "version": "1.4.0",
+  "version": "1.6.0",
   "description": "Sendora Cloud React Native + Expo SDK — analytics, identity, push-token registration, auth, deep links (Branch / Firebase Dynamic Links parity). Auth + analytics + deep links work in Expo Go; push token registration requires a Dev Client (EAS Build or `npx expo prebuild`).",
   "type": "module",
   "main": "./dist/index.cjs",