@sendoracloud/sdk-react-native 0.10.4 → 0.12.0

package/README.md

@@ -86,6 +86,18 @@ SendoraCloud.reset();
   environment?: "prod" | "staging" | "dev";  // Routing hint.
   projectId?: string;          // Optional project scoping.
   consentedByDefault?: boolean; // Defaults to true.
+  /**
+   * Auto-collect lifecycle events. Default true. Object form:
+   * { appOpen?, sessionStart?, appBackground? } for granular control.
+   * - appOpen — `app.opened` once per init.
+   * - sessionStart — `session.start` once per session (idle >sessionIdleMs).
+   * - appBackground — AppState 'change' fires `app.foregrounded` /
+   *   `app.backgrounded`.
+   * Note: `screen.viewed` is NOT auto — call `SendoraCloud.screen(name)`
+   * from your navigation listener (RN has no canonical router).
+   */
+  autoTrack?: boolean | { appOpen?: boolean; sessionStart?: boolean; appBackground?: boolean };
+  sessionIdleMs?: number; // Idle threshold for session expiry. Default 30 min.
 }
 ```
 

package/dist/index.cjs

@@ -799,8 +799,90 @@ function decodeJwtPayload(token) {
   }
 }
 
+// src/auto-track.ts
+var DEFAULT_IDLE_MS = 30 * 60 * 1e3;
+function resolveFlags(cfg) {
+  if (cfg === false) {
+    return { appOpen: false, sessionStart: false, appBackground: false };
+  }
+  if (cfg === true || cfg === void 0) {
+    return { appOpen: true, sessionStart: true, appBackground: true };
+  }
+  return {
+    appOpen: cfg.appOpen ?? true,
+    sessionStart: cfg.sessionStart ?? true,
+    appBackground: cfg.appBackground ?? true
+  };
+}
+function installAutoTrack(args) {
+  const flags = resolveFlags(args.config.autoTrack);
+  const idleMs = args.config.sessionIdleMs ?? DEFAULT_IDLE_MS;
+  let lastActivity = Date.now();
+  const cleanups = [];
+  function newSessionId() {
+    return `sess_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 10)}`;
+  }
+  function ensureSession(emitStart) {
+    const now = Date.now();
+    let id = args.getSessionId();
+    if (!id || now - lastActivity > idleMs) {
+      id = newSessionId();
+      args.setSessionId(id);
+      if (emitStart && flags.sessionStart) {
+        args.fire("session.start", { sessionId: id });
+      }
+    }
+    lastActivity = now;
+    return id;
+  }
+  const sessionId = ensureSession(
+    /* emitStart */
+    flags.sessionStart
+  );
+  if (flags.appOpen) {
+    args.fire("app.opened", { sessionId });
+  }
+  if (flags.appBackground) {
+    let AppState = null;
+    try {
+      const dyn = globalThis.require;
+      const mod = dyn ? dyn("react-native") : null;
+      AppState = mod?.AppState ?? null;
+    } catch {
+      AppState = null;
+    }
+    if (AppState && typeof AppState.addEventListener === "function") {
+      const handler = (state) => {
+        ensureSession(true);
+        if (state === "background" || state === "inactive") {
+          args.fire("app.backgrounded", { sessionId: args.getSessionId() });
+        } else if (state === "active") {
+          args.fire("app.foregrounded", { sessionId: args.getSessionId() });
+        }
+      };
+      const sub = AppState.addEventListener("change", handler);
+      cleanups.push(() => {
+        if (typeof sub === "function") {
+          return;
+        }
+        if (sub && typeof sub.remove === "function") {
+          sub.remove();
+        }
+      });
+    }
+  }
+  return () => {
+    for (const fn of cleanups) {
+      try {
+        fn();
+      } catch {
+      }
+    }
+  };
+}
+
 // src/index.ts
-var SDK_VERSION = "0.10.4";
+var SDK_VERSION = "0.11.0";
 var DEFAULT_API_URL = "https://api.sendoracloud.com";
 var ANON_KEY = "anon_id";
 var USER_ID_KEY = "user_id";
@@ -864,6 +946,8 @@ var SendoraSDK = class {
     this.userId = null;
     this.consentGranted = true;
     this.debug = false;
+    this.sessionId = "";
+    this.autoTrackCleanup = null;
   }
   /** Initialize the SDK. Must be awaited at app startup before identify/track. */
   async init(config) {
@@ -938,6 +1022,20 @@ var SendoraSDK = class {
     });
     this.auth.hydrate();
     this.ready = true;
+    if (config.autoTrack !== false) {
+      this.autoTrackCleanup = installAutoTrack({
+        config: this.config,
+        fire: (eventType, properties) => this.track(eventType, properties),
+        getSessionId: () => this.sessionId,
+        setSessionId: (id) => {
+          this.sessionId = id;
+        }
+      });
+    }
+  }
+  /** Current logical session id, if auto-track is enabled. */
+  getSessionId() {
+    return this.sessionId;
   }
   /** Stable anonymous identifier for this install — survives app restarts via AsyncStorage. */
   getAnonymousId() {
@@ -1037,6 +1135,28 @@ var SendoraSDK = class {
     }
     return { tokenId: data.tokenId, created: data.created === true };
   }
+  /**
+   * Push namespace — mirrors the iOS / Android / Web SDK shape so
+   * `sendora.push.registerToken(...)` works consistently across all 5 SDKs.
+   * Backed by the same registerPushToken() implementation; kept top-level
+   * too for backwards compatibility with the s47 release.
+   */
+  get push() {
+    const self = this;
+    return {
+      registerToken: (reg) => self.registerPushToken(reg),
+      trackOpen: async (sendId, clickAction) => {
+        if (!self.config) throw new Error("[sendoracloud] init() must complete before push.trackOpen().");
+        const body = { sendId };
+        if (clickAction !== void 0) body.clickAction = clickAction;
+        await post(
+          { apiUrl: self.config.apiUrl, publicKey: self.config.publicKey, debug: self.debug },
+          "/push/track-open",
+          body
+        );
+      }
+    };
+  }
   /**
    * Clear identity + rotate the anonymous id. Call on logout. Awaits
    * the AsyncStorage writes so a caller who kills the app immediately
@@ -1045,9 +1165,17 @@ var SendoraSDK = class {
   async reset() {
     this.userId = null;
     this.anonId = uuid();
+    this.sessionId = "";
     await this.storage.clearAll();
     this.storage.set(ANON_KEY, this.anonId);
   }
+  /** Tear down auto-track listeners. Call in test harnesses. */
+  destroy() {
+    if (this.autoTrackCleanup) {
+      this.autoTrackCleanup();
+      this.autoTrackCleanup = null;
+    }
+  }
   async sendEvent(kind, payload) {
     if (!this.config) return;
     if (!this.consentGranted) return;

package/dist/index.d.cts

@@ -309,6 +309,27 @@ interface SendoraConfig {
     consentedByDefault?: boolean;
     /** Verbose error logging (auth-error codes + Zod field errors). Default false. */
     debug?: boolean;
+    /**
+     * Auto-collect lifecycle events. Mirrors Firebase Analytics' auto-collected
+     * surface. `true` = all enabled (default). Pass an object for granular
+     * control or `false` to disable.
+     *
+     * - `appOpen` — fire `app.opened` on init. Default true.
+     * - `sessionStart` — emit `session.start` once per logical session
+     *   (idle >`sessionIdleMs` closes session). Default true.
+     * - `appBackground` — emit `app.backgrounded`/`app.foregrounded` on
+     *   AppState transitions. Default true.
+     *
+     * Note: screen view tracking is NOT auto — RN has no canonical router.
+     * Call `SendoraCloud.screen(name)` from your navigation listener.
+     */
+    autoTrack?: boolean | {
+        appOpen?: boolean;
+        sessionStart?: boolean;
+        appBackground?: boolean;
+    };
+    /** Idle threshold (ms) for session expiry; default 30 minutes. */
+    sessionIdleMs?: number;
 }
 type TraitValue = string | number | boolean | null | undefined;
 interface IdentifyTraits {
@@ -377,10 +398,14 @@ declare class SendoraSDK {
     private userId;
     private consentGranted;
     private debug;
+    private sessionId;
+    private autoTrackCleanup;
     /** Lazy-initialised in init() once we know the apiUrl + publicKey. */
     auth: Auth;
     /** Initialize the SDK. Must be awaited at app startup before identify/track. */
     init(config: SendoraConfig): Promise<void>;
+    /** Current logical session id, if auto-track is enabled. */
+    getSessionId(): string;
     /** Stable anonymous identifier for this install — survives app restarts via AsyncStorage. */
     getAnonymousId(): string;
     /** Current identified user id, if any. */
@@ -400,12 +425,24 @@ declare class SendoraSDK {
      * `@react-native-firebase/messaging`.
      */
     registerPushToken(reg: PushTokenRegistration): Promise<PushTokenReceipt>;
+    /**
+     * Push namespace — mirrors the iOS / Android / Web SDK shape so
+     * `sendora.push.registerToken(...)` works consistently across all 5 SDKs.
+     * Backed by the same registerPushToken() implementation; kept top-level
+     * too for backwards compatibility with the s47 release.
+     */
+    get push(): {
+        registerToken: (reg: PushTokenRegistration) => Promise<PushTokenReceipt>;
+        trackOpen: (sendId: string, clickAction?: string) => Promise<void>;
+    };
     /**
      * Clear identity + rotate the anonymous id. Call on logout. Awaits
      * the AsyncStorage writes so a caller who kills the app immediately
      * after doesn't leave stale identity on disk.
      */
     reset(): Promise<void>;
+    /** Tear down auto-track listeners. Call in test harnesses. */
+    destroy(): void;
     private sendEvent;
     private assertReady;
 }

package/dist/index.d.ts

@@ -309,6 +309,27 @@ interface SendoraConfig {
     consentedByDefault?: boolean;
     /** Verbose error logging (auth-error codes + Zod field errors). Default false. */
     debug?: boolean;
+    /**
+     * Auto-collect lifecycle events. Mirrors Firebase Analytics' auto-collected
+     * surface. `true` = all enabled (default). Pass an object for granular
+     * control or `false` to disable.
+     *
+     * - `appOpen` — fire `app.opened` on init. Default true.
+     * - `sessionStart` — emit `session.start` once per logical session
+     *   (idle >`sessionIdleMs` closes session). Default true.
+     * - `appBackground` — emit `app.backgrounded`/`app.foregrounded` on
+     *   AppState transitions. Default true.
+     *
+     * Note: screen view tracking is NOT auto — RN has no canonical router.
+     * Call `SendoraCloud.screen(name)` from your navigation listener.
+     */
+    autoTrack?: boolean | {
+        appOpen?: boolean;
+        sessionStart?: boolean;
+        appBackground?: boolean;
+    };
+    /** Idle threshold (ms) for session expiry; default 30 minutes. */
+    sessionIdleMs?: number;
 }
 type TraitValue = string | number | boolean | null | undefined;
 interface IdentifyTraits {
@@ -377,10 +398,14 @@ declare class SendoraSDK {
     private userId;
     private consentGranted;
     private debug;
+    private sessionId;
+    private autoTrackCleanup;
     /** Lazy-initialised in init() once we know the apiUrl + publicKey. */
     auth: Auth;
     /** Initialize the SDK. Must be awaited at app startup before identify/track. */
     init(config: SendoraConfig): Promise<void>;
+    /** Current logical session id, if auto-track is enabled. */
+    getSessionId(): string;
     /** Stable anonymous identifier for this install — survives app restarts via AsyncStorage. */
     getAnonymousId(): string;
     /** Current identified user id, if any. */
@@ -400,12 +425,24 @@ declare class SendoraSDK {
      * `@react-native-firebase/messaging`.
      */
     registerPushToken(reg: PushTokenRegistration): Promise<PushTokenReceipt>;
+    /**
+     * Push namespace — mirrors the iOS / Android / Web SDK shape so
+     * `sendora.push.registerToken(...)` works consistently across all 5 SDKs.
+     * Backed by the same registerPushToken() implementation; kept top-level
+     * too for backwards compatibility with the s47 release.
+     */
+    get push(): {
+        registerToken: (reg: PushTokenRegistration) => Promise<PushTokenReceipt>;
+        trackOpen: (sendId: string, clickAction?: string) => Promise<void>;
+    };
     /**
      * Clear identity + rotate the anonymous id. Call on logout. Awaits
      * the AsyncStorage writes so a caller who kills the app immediately
      * after doesn't leave stale identity on disk.
      */
     reset(): Promise<void>;
+    /** Tear down auto-track listeners. Call in test harnesses. */
+    destroy(): void;
     private sendEvent;
     private assertReady;
 }

package/dist/index.js

@@ -759,8 +759,90 @@ function decodeJwtPayload(token) {
   }
 }
 
+// src/auto-track.ts
+var DEFAULT_IDLE_MS = 30 * 60 * 1e3;
+function resolveFlags(cfg) {
+  if (cfg === false) {
+    return { appOpen: false, sessionStart: false, appBackground: false };
+  }
+  if (cfg === true || cfg === void 0) {
+    return { appOpen: true, sessionStart: true, appBackground: true };
+  }
+  return {
+    appOpen: cfg.appOpen ?? true,
+    sessionStart: cfg.sessionStart ?? true,
+    appBackground: cfg.appBackground ?? true
+  };
+}
+function installAutoTrack(args) {
+  const flags = resolveFlags(args.config.autoTrack);
+  const idleMs = args.config.sessionIdleMs ?? DEFAULT_IDLE_MS;
+  let lastActivity = Date.now();
+  const cleanups = [];
+  function newSessionId() {
+    return `sess_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 10)}`;
+  }
+  function ensureSession(emitStart) {
+    const now = Date.now();
+    let id = args.getSessionId();
+    if (!id || now - lastActivity > idleMs) {
+      id = newSessionId();
+      args.setSessionId(id);
+      if (emitStart && flags.sessionStart) {
+        args.fire("session.start", { sessionId: id });
+      }
+    }
+    lastActivity = now;
+    return id;
+  }
+  const sessionId = ensureSession(
+    /* emitStart */
+    flags.sessionStart
+  );
+  if (flags.appOpen) {
+    args.fire("app.opened", { sessionId });
+  }
+  if (flags.appBackground) {
+    let AppState = null;
+    try {
+      const dyn = globalThis.require;
+      const mod = dyn ? dyn("react-native") : null;
+      AppState = mod?.AppState ?? null;
+    } catch {
+      AppState = null;
+    }
+    if (AppState && typeof AppState.addEventListener === "function") {
+      const handler = (state) => {
+        ensureSession(true);
+        if (state === "background" || state === "inactive") {
+          args.fire("app.backgrounded", { sessionId: args.getSessionId() });
+        } else if (state === "active") {
+          args.fire("app.foregrounded", { sessionId: args.getSessionId() });
+        }
+      };
+      const sub = AppState.addEventListener("change", handler);
+      cleanups.push(() => {
+        if (typeof sub === "function") {
+          return;
+        }
+        if (sub && typeof sub.remove === "function") {
+          sub.remove();
+        }
+      });
+    }
+  }
+  return () => {
+    for (const fn of cleanups) {
+      try {
+        fn();
+      } catch {
+      }
+    }
+  };
+}
+
 // src/index.ts
-var SDK_VERSION = "0.10.4";
+var SDK_VERSION = "0.11.0";
 var DEFAULT_API_URL = "https://api.sendoracloud.com";
 var ANON_KEY = "anon_id";
 var USER_ID_KEY = "user_id";
@@ -824,6 +906,8 @@ var SendoraSDK = class {
     this.userId = null;
     this.consentGranted = true;
     this.debug = false;
+    this.sessionId = "";
+    this.autoTrackCleanup = null;
   }
   /** Initialize the SDK. Must be awaited at app startup before identify/track. */
   async init(config) {
@@ -898,6 +982,20 @@ var SendoraSDK = class {
     });
     this.auth.hydrate();
     this.ready = true;
+    if (config.autoTrack !== false) {
+      this.autoTrackCleanup = installAutoTrack({
+        config: this.config,
+        fire: (eventType, properties) => this.track(eventType, properties),
+        getSessionId: () => this.sessionId,
+        setSessionId: (id) => {
+          this.sessionId = id;
+        }
+      });
+    }
+  }
+  /** Current logical session id, if auto-track is enabled. */
+  getSessionId() {
+    return this.sessionId;
   }
   /** Stable anonymous identifier for this install — survives app restarts via AsyncStorage. */
   getAnonymousId() {
@@ -997,6 +1095,28 @@ var SendoraSDK = class {
     }
     return { tokenId: data.tokenId, created: data.created === true };
   }
+  /**
+   * Push namespace — mirrors the iOS / Android / Web SDK shape so
+   * `sendora.push.registerToken(...)` works consistently across all 5 SDKs.
+   * Backed by the same registerPushToken() implementation; kept top-level
+   * too for backwards compatibility with the s47 release.
+   */
+  get push() {
+    const self = this;
+    return {
+      registerToken: (reg) => self.registerPushToken(reg),
+      trackOpen: async (sendId, clickAction) => {
+        if (!self.config) throw new Error("[sendoracloud] init() must complete before push.trackOpen().");
+        const body = { sendId };
+        if (clickAction !== void 0) body.clickAction = clickAction;
+        await post(
+          { apiUrl: self.config.apiUrl, publicKey: self.config.publicKey, debug: self.debug },
+          "/push/track-open",
+          body
+        );
+      }
+    };
+  }
   /**
    * Clear identity + rotate the anonymous id. Call on logout. Awaits
    * the AsyncStorage writes so a caller who kills the app immediately
@@ -1005,9 +1125,17 @@ var SendoraSDK = class {
   async reset() {
     this.userId = null;
     this.anonId = uuid();
+    this.sessionId = "";
     await this.storage.clearAll();
     this.storage.set(ANON_KEY, this.anonId);
   }
+  /** Tear down auto-track listeners. Call in test harnesses. */
+  destroy() {
+    if (this.autoTrackCleanup) {
+      this.autoTrackCleanup();
+      this.autoTrackCleanup = null;
+    }
+  }
   async sendEvent(kind, payload) {
     if (!this.config) return;
     if (!this.consentGranted) return;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sendoracloud/sdk-react-native",
-  "version": "0.10.4",
+  "version": "0.12.0",
   "description": "Sendora Cloud React Native + Expo SDK — analytics, identity, push-token registration, auth. Expo Go compatible, no native modules beyond AsyncStorage.",
   "type": "module",
   "main": "./dist/index.cjs",