@sendoracloud/sdk-react-native 0.10.3 → 0.11.0

package/README.md

@@ -2,14 +2,26 @@
 
 Official React Native + Expo SDK for [SendoraCloud](https://sendoracloud.com). Works in Expo Go, managed dev clients, and bare React Native apps.
 
+> 📖 **First time on React Native?** Read the [5-minute quickstart](https://sendoracloud.com/docs/quickstart-react-native) — it covers the Hermes CSPRNG polyfill, anonymous-first auth, push token receipts, and the demo end-to-end push send.
+
 ## Install
 
 ```bash
 npx expo install @sendoracloud/sdk-react-native @react-native-async-storage/async-storage
+npm install react-native-get-random-values
 ```
 
 `@react-native-async-storage/async-storage` is a required peer dependency — used to persist the anonymous device id across app restarts.
 
+`react-native-get-random-values` is a required runtime polyfill — Hermes (and JavaScriptCore) doesn't expose `crypto.getRandomValues` reliably, and Sendora refuses to mint anonymous IDs from `Math.random`. Add this as the **first import** in your entry file (`index.js` or `index.tsx`):
+
+```ts
+// MUST be the first import in your entry file
+import "react-native-get-random-values";
+```
+
+If you forget, `init()` throws with a paste-ready remediation block — it never fails silently.
+
 ## Quick start
 
 ```ts
@@ -36,11 +48,16 @@ SendoraCloud.screen("Pricing");
 // Register the device push token (get it from expo-notifications)
 import * as Notifications from "expo-notifications";
 const { data } = await Notifications.getExpoPushTokenAsync();
-await SendoraCloud.registerPushToken({
+const receipt = await SendoraCloud.registerPushToken({
   token: data,
   platform: Platform.OS as "ios" | "android",
+  // bundleId is OPTIONAL but strongly recommended for multi-env apps:
+  // Sendora uses it to route to the right APNs / FCM credentials so a
+  // dev token never receives a prod push.
   bundleId: "com.yourcompany.app",
 });
+// Returns { tokenId, created } — log it for debugging fan-out issues.
+console.log("registered:", receipt.tokenId, "new?", receipt.created);
 
 // On logout
 SendoraCloud.reset();
@@ -69,9 +86,46 @@ 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.
+}
+```
+
+## Stability
+
+This SDK is on the **0.10.x line**. Patch bumps (0.10.x → 0.10.y) are backwards-compatible; minor bumps may include breaking changes — always read the [CHANGELOG](https://github.com/sendoracloud/sdk-react-native/blob/main/CHANGELOG.md) before upgrading. The next major (1.0) is targeted once the HttpOnly-cookie SSR auth + auto-trait extraction features have soaked in production for two consecutive months without a schema change. Once 1.0 ships, semver is strict.
+
+## JWT verification (custom backend)
+
+If your backend verifies Sendora-issued access tokens directly (rather than calling Sendora APIs that re-verify on every hit), use the OIDC-standard JWKS auto-discovery pattern — never hardcode the JWKS URL:
+
+```ts
+import { createRemoteJWKSet, jwtVerify, decodeJwt } from "jose";
+
+const JWKS_BY_ISS = new Map<string, ReturnType<typeof createRemoteJWKSet>>();
+function getJwks(iss: string) {
+  if (!JWKS_BY_ISS.has(iss)) {
+    JWKS_BY_ISS.set(iss, createRemoteJWKSet(new URL(`${iss}/.well-known/jwks.json`)));
+  }
+  return JWKS_BY_ISS.get(iss)!;
 }
+
+const claims = decodeJwt(token);
+const { payload } = await jwtVerify(token, getJwks(claims.iss as string));
 ```
 
+The `iss` claim is a per-org Sendora URL (e.g. `https://api.sendoracloud.com/api/v1/auth-service/<orgId>`); appending `/.well-known/jwks.json` resolves on the same host. This means a customer can rotate signing keys without your code redeploying. **Don't** copy a hardcoded JWKS URL from a tutorial — it'll break in 12 months when an org rotates.
+
 ## Security
 
 - **Secret keys refused on the client.** The SDK only accepts `pk_(live|test)_<alphanumerics>` keys — `sk_*` (any case) or malformed values throw at init. Secret keys must stay on your backend.

package/dist/index.cjs

@@ -799,8 +799,88 @@ 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 {
+      AppState = require("react-native").AppState;
+    } 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.3";
+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";
@@ -816,15 +896,33 @@ var MAX_PUSH_METADATA_BYTES = 4096;
 var MAX_USER_ID_LEN = 256;
 var MAX_TRAITS_BYTES = 32 * 1024;
 var MAX_PROPERTIES_BYTES = 32 * 1024;
+function assertCSPRNG() {
+  const g = globalThis;
+  if (g.crypto?.getRandomValues) {
+    return g.crypto;
+  }
+  const msg = [
+    "[sendoracloud] crypto.getRandomValues is unavailable in this runtime.",
+    "",
+    "Sendora refuses to mint anonymous IDs from Math.random \u2014 predictable IDs",
+    "are a security floor regression, not a tradeoff.",
+    "",
+    "Fix (React Native + Expo):",
+    "  1) npm install react-native-get-random-values",
+    "  2) Add this as the FIRST line of your app's entry file (index.js or",
+    "     index.tsx \u2014 before any other import including Sendora):",
+    "",
+    "       import 'react-native-get-random-values';",
+    "",
+    "  3) Reload the JS bundle (full restart, not Fast Refresh).",
+    "",
+    "Docs: https://sendoracloud.com/docs/quickstart-react-native#csprng"
+  ].join("\n");
+  throw new Error(msg);
+}
 function uuid() {
   const bytes = new Uint8Array(16);
-  const g = globalThis;
-  if (!g.crypto?.getRandomValues) {
-    throw new Error(
-      "[sendoracloud] crypto.getRandomValues unavailable \u2014 refusing to mint IDs without a CSPRNG. Upgrade Hermes / your RN runtime."
-    );
-  }
-  g.crypto.getRandomValues(bytes);
+  assertCSPRNG().getRandomValues(bytes);
   bytes[6] = bytes[6] & 15 | 64;
   bytes[8] = bytes[8] & 63 | 128;
   const hex = Array.from(bytes, (b) => b.toString(16).padStart(2, "0")).join("");
@@ -846,9 +944,12 @@ 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) {
+    assertCSPRNG();
     const rawKey = String(config.apiKey ?? config.publicKey ?? "").trim();
     if (/^sk_/i.test(rawKey) || /sk_(prod|staging|dev|live|test)_/i.test(rawKey)) {
       throw new Error(
@@ -919,6 +1020,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() {
@@ -988,7 +1103,9 @@ var SendoraSDK = class {
    */
   async registerPushToken(reg) {
     this.assertReady();
-    if (!this.config) return;
+    if (!this.config) {
+      throw new Error("[sendoracloud] init() must complete before registerPushToken().");
+    }
     if (!reg.token || byteLength(reg.token) > MAX_PUSH_TOKEN_BYTES) {
       throw new Error("[sendoracloud] push token is empty or exceeds 4KB.");
     }
@@ -998,7 +1115,7 @@ var SendoraSDK = class {
         throw new Error("[sendoracloud] push token metadata exceeds 4KB.");
       }
     }
-    await post(
+    const data = await post(
       { apiUrl: this.config.apiUrl, publicKey: this.config.publicKey, debug: this.debug },
       "/api/v1/push/tokens",
       {
@@ -1011,6 +1128,10 @@ var SendoraSDK = class {
         metadata: reg.metadata ?? {}
       }
     );
+    if (!data?.tokenId) {
+      throw new Error("[sendoracloud] push token registered but server returned no tokenId \u2014 upgrade backend to >= s58.16.");
+    }
+    return { tokenId: data.tokenId, created: data.created === true };
   }
   /**
    * Clear identity + rotate the anonymous id. Call on logout. Awaits
@@ -1020,9 +1141,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 {
@@ -324,11 +345,25 @@ type PushPlatform = "ios" | "android";
 interface PushTokenRegistration {
     token: string;
     platform: PushPlatform;
-    /** App bundle / package identifier, for fan-out to the right credentials. */
+    /**
+     * App bundle / package identifier, for fan-out to the right credentials.
+     * Optional but strongly recommended for multi-env apps so dev / staging
+     * tokens never get a prod APNs / FCM push.
+     */
     bundleId?: string;
     /** Arbitrary device metadata stored alongside the token. */
     metadata?: Record<string, string>;
 }
+/**
+ * Returned by `registerPushToken` so the caller can log a receipt or run
+ * a follow-up `testPush(userId)` against the freshly stored token. `created`
+ * distinguishes a brand-new token row from an idempotent re-registration of
+ * a token Sendora already had on file.
+ */
+interface PushTokenReceipt {
+    tokenId: string;
+    created: boolean;
+}
 
 /**
  * @sendoracloud/sdk-react-native — React Native + Expo SDK.
@@ -363,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. */
@@ -385,16 +424,18 @@ declare class SendoraSDK {
      * obtaining the token — typically via `expo-notifications` or
      * `@react-native-firebase/messaging`.
      */
-    registerPushToken(reg: PushTokenRegistration): Promise<void>;
+    registerPushToken(reg: PushTokenRegistration): Promise<PushTokenReceipt>;
     /**
      * 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;
 }
 declare const SendoraCloud: SendoraSDK;
 
-export { Auth, AuthError, type AuthTokens, type AuthUser, EmailAlreadyTakenError, type IdentifyTraits, type PushTokenRegistration, SendoraCloud, type SendoraConfig, type TrackProperties, SendoraCloud as default };
+export { Auth, AuthError, type AuthTokens, type AuthUser, EmailAlreadyTakenError, type IdentifyTraits, type PushTokenReceipt, type PushTokenRegistration, SendoraCloud, type SendoraConfig, type TrackProperties, SendoraCloud as default };

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 {
@@ -324,11 +345,25 @@ type PushPlatform = "ios" | "android";
 interface PushTokenRegistration {
     token: string;
     platform: PushPlatform;
-    /** App bundle / package identifier, for fan-out to the right credentials. */
+    /**
+     * App bundle / package identifier, for fan-out to the right credentials.
+     * Optional but strongly recommended for multi-env apps so dev / staging
+     * tokens never get a prod APNs / FCM push.
+     */
     bundleId?: string;
     /** Arbitrary device metadata stored alongside the token. */
     metadata?: Record<string, string>;
 }
+/**
+ * Returned by `registerPushToken` so the caller can log a receipt or run
+ * a follow-up `testPush(userId)` against the freshly stored token. `created`
+ * distinguishes a brand-new token row from an idempotent re-registration of
+ * a token Sendora already had on file.
+ */
+interface PushTokenReceipt {
+    tokenId: string;
+    created: boolean;
+}
 
 /**
  * @sendoracloud/sdk-react-native — React Native + Expo SDK.
@@ -363,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. */
@@ -385,16 +424,18 @@ declare class SendoraSDK {
      * obtaining the token — typically via `expo-notifications` or
      * `@react-native-firebase/messaging`.
      */
-    registerPushToken(reg: PushTokenRegistration): Promise<void>;
+    registerPushToken(reg: PushTokenRegistration): Promise<PushTokenReceipt>;
     /**
      * 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;
 }
 declare const SendoraCloud: SendoraSDK;
 
-export { Auth, AuthError, type AuthTokens, type AuthUser, EmailAlreadyTakenError, type IdentifyTraits, type PushTokenRegistration, SendoraCloud, type SendoraConfig, type TrackProperties, SendoraCloud as default };
+export { Auth, AuthError, type AuthTokens, type AuthUser, EmailAlreadyTakenError, type IdentifyTraits, type PushTokenReceipt, type PushTokenRegistration, SendoraCloud, type SendoraConfig, type TrackProperties, SendoraCloud as default };

package/dist/index.js

@@ -1,3 +1,10 @@
+var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require : typeof Proxy !== "undefined" ? new Proxy(x, {
+  get: (a, b) => (typeof require !== "undefined" ? require : a)[b]
+}) : x)(function(x) {
+  if (typeof require !== "undefined") return require.apply(this, arguments);
+  throw Error('Dynamic require of "' + x + '" is not supported');
+});
+
 // src/storage.ts
 var PREFIX = "sendora_";
 var asyncStoragePromise = null;
@@ -759,8 +766,88 @@ 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 {
+      AppState = __require("react-native").AppState;
+    } 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.3";
+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";
@@ -776,15 +863,33 @@ var MAX_PUSH_METADATA_BYTES = 4096;
 var MAX_USER_ID_LEN = 256;
 var MAX_TRAITS_BYTES = 32 * 1024;
 var MAX_PROPERTIES_BYTES = 32 * 1024;
+function assertCSPRNG() {
+  const g = globalThis;
+  if (g.crypto?.getRandomValues) {
+    return g.crypto;
+  }
+  const msg = [
+    "[sendoracloud] crypto.getRandomValues is unavailable in this runtime.",
+    "",
+    "Sendora refuses to mint anonymous IDs from Math.random \u2014 predictable IDs",
+    "are a security floor regression, not a tradeoff.",
+    "",
+    "Fix (React Native + Expo):",
+    "  1) npm install react-native-get-random-values",
+    "  2) Add this as the FIRST line of your app's entry file (index.js or",
+    "     index.tsx \u2014 before any other import including Sendora):",
+    "",
+    "       import 'react-native-get-random-values';",
+    "",
+    "  3) Reload the JS bundle (full restart, not Fast Refresh).",
+    "",
+    "Docs: https://sendoracloud.com/docs/quickstart-react-native#csprng"
+  ].join("\n");
+  throw new Error(msg);
+}
 function uuid() {
   const bytes = new Uint8Array(16);
-  const g = globalThis;
-  if (!g.crypto?.getRandomValues) {
-    throw new Error(
-      "[sendoracloud] crypto.getRandomValues unavailable \u2014 refusing to mint IDs without a CSPRNG. Upgrade Hermes / your RN runtime."
-    );
-  }
-  g.crypto.getRandomValues(bytes);
+  assertCSPRNG().getRandomValues(bytes);
   bytes[6] = bytes[6] & 15 | 64;
   bytes[8] = bytes[8] & 63 | 128;
   const hex = Array.from(bytes, (b) => b.toString(16).padStart(2, "0")).join("");
@@ -806,9 +911,12 @@ 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) {
+    assertCSPRNG();
     const rawKey = String(config.apiKey ?? config.publicKey ?? "").trim();
     if (/^sk_/i.test(rawKey) || /sk_(prod|staging|dev|live|test)_/i.test(rawKey)) {
       throw new Error(
@@ -879,6 +987,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() {
@@ -948,7 +1070,9 @@ var SendoraSDK = class {
    */
   async registerPushToken(reg) {
     this.assertReady();
-    if (!this.config) return;
+    if (!this.config) {
+      throw new Error("[sendoracloud] init() must complete before registerPushToken().");
+    }
     if (!reg.token || byteLength(reg.token) > MAX_PUSH_TOKEN_BYTES) {
       throw new Error("[sendoracloud] push token is empty or exceeds 4KB.");
     }
@@ -958,7 +1082,7 @@ var SendoraSDK = class {
         throw new Error("[sendoracloud] push token metadata exceeds 4KB.");
       }
     }
-    await post(
+    const data = await post(
       { apiUrl: this.config.apiUrl, publicKey: this.config.publicKey, debug: this.debug },
       "/api/v1/push/tokens",
       {
@@ -971,6 +1095,10 @@ var SendoraSDK = class {
         metadata: reg.metadata ?? {}
       }
     );
+    if (!data?.tokenId) {
+      throw new Error("[sendoracloud] push token registered but server returned no tokenId \u2014 upgrade backend to >= s58.16.");
+    }
+    return { tokenId: data.tokenId, created: data.created === true };
   }
   /**
    * Clear identity + rotate the anonymous id. Call on logout. Awaits
@@ -980,9 +1108,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.3",
+  "version": "0.11.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",