@sendoracloud/sdk-react-native 1.16.0 → 1.18.0

package/dist/index.cjs

@@ -64,20 +64,30 @@ async function getAsyncStorage() {
   return asyncStoragePromise;
 }
 var Storage = class {
-  constructor() {
+  constructor(opts = {}) {
     this.cache = /* @__PURE__ */ new Map();
     this.hydrated = false;
+    this.secure = opts.secureAdapter ?? null;
+    this.secureKeys = new Set(opts.secureKeys ?? []);
+  }
+  isSecure(key) {
+    return this.secure !== null && this.secureKeys.has(key);
   }
   /**
-   * Populate the memory cache from AsyncStorage. Must be awaited
+   * Populate the memory cache from persistent storage. Must be awaited
    * once at SDK init — after that, `get` returns synchronously from
-   * the cache and `set` fire-and-forgets to AsyncStorage.
+   * the cache and `set` fire-and-forgets. For secure keys, reads the
+   * adapter first, then falls back to (and migrates from) any legacy
+   * plaintext AsyncStorage value written by a pre-secure SDK version —
+   * so enabling secure storage never signs an existing user out.
    */
   async hydrate(keys) {
     if (this.hydrated) return;
     const store = await getAsyncStorage();
-    if (store) {
-      for (const k of keys) {
+    for (const k of keys) {
+      if (this.isSecure(k)) {
+        await this.hydrateSecureKey(k, store);
+      } else if (store) {
         try {
           const v = await store.getItem(PREFIX + k);
           if (v !== null) this.cache.set(k, v);
@@ -87,11 +97,50 @@ var Storage = class {
     }
     this.hydrated = true;
   }
+  /** Read a secure key: adapter first, else migrate legacy plaintext. Never throws. */
+  async hydrateSecureKey(k, store) {
+    try {
+      const secureVal = await this.secure.getItem(k);
+      if (secureVal !== null) {
+        this.cache.set(k, secureVal);
+        return;
+      }
+      if (store) {
+        const legacy = await store.getItem(PREFIX + k).catch(() => null);
+        if (legacy !== null) {
+          this.cache.set(k, legacy);
+          try {
+            await this.secure.setItem(k, legacy);
+            await store.removeItem(PREFIX + k).catch(() => {
+            });
+          } catch {
+          }
+        }
+      }
+    } catch {
+      if (store) {
+        try {
+          const legacy = await store.getItem(PREFIX + k);
+          if (legacy !== null) this.cache.set(k, legacy);
+        } catch {
+        }
+      }
+    }
+  }
   get(key) {
     return this.cache.get(key) ?? null;
   }
   set(key, value) {
     this.cache.set(key, value);
+    if (this.isSecure(key)) {
+      void this.secure.setItem(key, value).catch(() => {
+        void getAsyncStorage().then((store) => {
+          if (store) store.setItem(PREFIX + key, value).catch(() => {
+          });
+        });
+      });
+      return;
+    }
     void getAsyncStorage().then((store) => {
       if (store) store.setItem(PREFIX + key, value).catch(() => {
       });
@@ -99,6 +148,10 @@ var Storage = class {
   }
   remove(key) {
     this.cache.delete(key);
+    if (this.isSecure(key)) {
+      void this.secure.removeItem(key).catch(() => {
+      });
+    }
     void getAsyncStorage().then((store) => {
       if (store) store.removeItem(PREFIX + key).catch(() => {
       });
@@ -106,13 +159,21 @@ var Storage = class {
   }
   /**
    * Remove every sendora_*-prefixed key from both memory AND
-   * AsyncStorage. Uses getAllKeys() to find keys this process never
-   * cached (e.g. orphaned writes from a prior SDK version that added
-   * a key not in our hydrate list). Falls back to cache enumeration
+   * AsyncStorage, plus every secure key from the adapter. Uses
+   * getAllKeys() to find keys this process never cached (e.g. orphaned
+   * writes from a prior SDK version). Falls back to cache enumeration
    * if the AsyncStorage backend doesn't expose getAllKeys.
    */
   async clearAll() {
     this.cache.clear();
+    if (this.secure) {
+      for (const k of this.secureKeys) {
+        try {
+          await this.secure.removeItem(k);
+        } catch {
+        }
+      }
+    }
     const store = await getAsyncStorage();
     if (!store) return;
     let keys = [];
@@ -125,7 +186,7 @@ var Storage = class {
       }
     }
     if (keys.length === 0) {
-      keys = Array.from(this.cache.keys()).map((k) => PREFIX + k);
+      keys = Array.from(this.secureKeys).map((k) => PREFIX + k);
     }
     for (const k of keys) {
       try {
@@ -139,7 +200,7 @@ var Storage = class {
 // package.json
 var package_default = {
   name: "@sendoracloud/sdk-react-native",
-  version: "1.16.0",
+  version: "1.18.0",
   description: "Sendora Cloud React Native + Expo SDK \u2014 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",
@@ -192,13 +253,15 @@ var package_default = {
   },
   scripts: {
     build: "tsup src/index.ts src/contact-widget.tsx --format esm,cjs --dts --clean --external react --external react-native --external react-native-webview",
-    typecheck: "tsc --noEmit"
+    typecheck: "tsc --noEmit",
+    test: "tsx test/secure-storage.test.ts && tsx test/integration-storage.test.ts"
   },
   devDependencies: {
     "@types/react": "^19.2.16",
     "react-native": "^0.85.3",
     "react-native-webview": "^13.16.1",
     tsup: "^8.0.0",
+    tsx: "^4.21.0",
     typescript: "^5.0.0"
   },
   license: "MIT",
@@ -1999,6 +2062,7 @@ var AUTH_HYDRATE_KEYS = [
   "auth_refresh_token",
   "auth_user"
 ];
+var SECURE_KEYS = ["auth_refresh_token", "auth_access_token", "auth_user"];
 var PUBLIC_KEY_RE = /^pk_(prod|staging|dev|live|test)_[A-Za-z0-9]{16,}$/;
 var MAX_PUSH_TOKEN_BYTES = 4096;
 var MAX_PUSH_METADATA_BYTES = 4096;
@@ -2193,6 +2257,9 @@ var SendoraSDK = class {
         `[sendoracloud] apiUrl override active: ${apiUrl} \u2014 confirm this is intentional. Tokens + events will be sent here.`
       );
     }
+    if (config.secureStorage) {
+      this.storage = new Storage({ secureAdapter: config.secureStorage, secureKeys: SECURE_KEYS });
+    }
     await this.storage.hydrate([
       ANON_KEY,
       USER_ID_KEY,
@@ -2274,6 +2341,19 @@ var SendoraSDK = class {
     this.assertReady();
     return this.anonId;
   }
+  /**
+   * Non-throwing, synchronous read of the anonymous id. Returns `null`
+   * until `init()` has resolved — the id lives in AsyncStorage and is
+   * hydrated (or minted) during `init()`, so there is nothing to read
+   * before that. Unlike `getAnonymousId()`, this never throws, so an
+   * offline-first caller can read-or-fallback at cold start without a
+   * try/catch. `init()` itself needs no network (disk-only hydrate), so
+   * awaiting it once at boot makes this return a value even offline.
+   * Once ready it returns the same stable id as `getAnonymousId()`.
+   */
+  getAnonymousIdSync() {
+    return this.anonId || null;
+  }
   /** Current identified user id, if any. */
   getUserId() {
     return this.userId;

package/dist/index.d.cts

@@ -1,3 +1,156 @@
+interface SendoraConfig {
+    /**
+     * Public API key (`pk_live_…` or `pk_test_…`). Secret keys are refused.
+     * Canonical name as of 0.10.0 — pre-0.10.0 callers using `publicKey`
+     * still work via the deprecated alias below.
+     */
+    apiKey?: string;
+    /**
+     * @deprecated Use `apiKey` instead (0.10.0+ canonical name across
+     * sdk-web / sdk-ios / sdk-android). Kept for back-compat — when
+     * both are set, `apiKey` wins.
+     */
+    publicKey?: string;
+    /** Backend base URL. Defaults to Sendora's production API. */
+    apiUrl?: string;
+    /** `"prod"` | `"staging"` | `"dev"` routing hint. For API-key auth this
+     *  is IGNORED — the backend forcibly tags events with the environment
+     *  encoded in the key prefix (pk_prod_* / pk_staging_* / pk_dev_*). See
+     *  ADR-014. Kept for session-authed callers and test harnesses that
+     *  don't use API keys. Defaults to `"prod"`. */
+    environment?: "prod" | "staging" | "dev";
+    /** Optional project id scoping. */
+    projectId?: string;
+    /** If false, events drop until setConsent(true) is called. Default true (mobile apps usually collect OS-level consent). */
+    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.
+     * - `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.
+     */
+    autoTrack?: boolean | {
+        appOpen?: boolean;
+        sessionStart?: boolean;
+        appBackground?: boolean;
+        engagement?: boolean;
+    };
+    /** Idle threshold (ms) for session expiry; default 30 minutes. */
+    sessionIdleMs?: number;
+    /**
+     * iOS bundle id (e.g. `com.pulse.news`). Forwarded to backend on
+     * `links.create()` / `links.matchDeferred()` for the bundle-id gate —
+     * blocks a leaked public key from being used by a different app.
+     */
+    iosBundleId?: string;
+    /**
+     * Android package name (e.g. `com.pulse.news`). Same purpose as
+     * `iosBundleId` above.
+     */
+    androidPackageName?: string;
+    /**
+     * Optional share-link host (e.g. `pulse.link`). When set, the deep
+     * links module's URL extractor only treats Sendora-routed URLs whose
+     * host matches this domain (or a subdomain). Leave unset on apps that
+     * use the default Sendora-hosted share domain (`go.sendoracloud.com`).
+     * Added 0.16.0.
+     */
+    linkDomain?: string;
+    /**
+     * Your app's version (e.g. "2.4.0"). Attached to every event's
+     * `context.device.appVersion` so the dashboard can break analytics down by
+     * release (ADR-022). Optional — RN has no zero-dep way to auto-read the
+     * host app version, so supply it (e.g. from `expo-constants` /
+     * `react-native-device-info`) if you want app-version analytics.
+     */
+    appVersion?: string;
+    /**
+     * App build number (iOS `CFBundleVersion` / Android `versionCode`). Auto-read
+     * from expo-application's `nativeBuildVersion` when present; supply here to
+     * override or for non-Expo apps. Shown as "version (build)" on the dashboard.
+     */
+    appBuild?: string;
+    /**
+     * Optional encrypted-at-rest storage for sensitive auth material (refresh
+     * token, access token, cached user). When provided, the SDK routes ONLY those
+     * keys through this adapter instead of plain AsyncStorage; everything else
+     * (analytics anon id, session flags) stays in AsyncStorage. Existing plaintext
+     * tokens are migrated into the adapter transparently on the first launch after
+     * you enable it (dual-read), so no one is signed out.
+     *
+     * Pass a Keychain/Keystore-backed adapter — e.g. an `expo-secure-store`
+     * hybrid (AES key in SecureStore encrypting the value in AsyncStorage, the
+     * "LargeSecureStore" pattern). The SDK does NOT depend on `expo-secure-store`
+     * itself — you supply the adapter, mirroring Supabase's `auth.storage` model —
+     * so bare-RN apps stay Metro-safe. Omit to keep the default AsyncStorage
+     * behaviour (OWASP MASVS-L1). See docs/backend-identity + docs/sdks.
+     *
+     * Guidance: this is a defense-in-depth (OWASP L2) upgrade — refresh tokens are
+     * long-lived and high-value, so encrypt them on a rooted/jailbroken-device
+     * threat model. It is opt-in: adding it never changes an app that doesn't pass it.
+     */
+    secureStorage?: SecureStorageAdapter;
+}
+/**
+ * Async key/value adapter for encrypted-at-rest auth storage. Compatible with a
+ * thin wrapper over `expo-secure-store` or `react-native-keychain`. All methods
+ * are async; the SDK awaits them during `init()` hydrate and fire-and-forgets on
+ * write (identical to its AsyncStorage handling). A throwing adapter degrades
+ * gracefully to AsyncStorage — the SDK never loses a session on adapter failure.
+ */
+interface SecureStorageAdapter {
+    getItem(key: string): Promise<string | null>;
+    setItem(key: string, value: string): Promise<void>;
+    removeItem(key: string): Promise<void>;
+}
+type TraitValue = string | number | boolean | null | undefined;
+interface IdentifyTraits {
+    email?: string;
+    name?: string;
+    avatarUrl?: string;
+    [key: string]: TraitValue;
+}
+interface TrackProperties {
+    [key: string]: TraitValue | TraitValue[];
+}
+type PushPlatform = "ios" | "android";
+interface PushTokenRegistration {
+    token: string;
+    platform: PushPlatform;
+    /**
+     * 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;
+}
+
 /**
  * Hybrid storage for React Native: read-through memory cache backed
  * by AsyncStorage for persistence. Callers can read synchronously
@@ -7,24 +160,51 @@
  * AsyncStorage is a required peer dependency — we import it lazily
  * so the package itself doesn't hard-fail if the user hasn't
  * installed it yet (they'll see an explicit runtime error instead).
+ *
+ * Optional encrypted-at-rest storage (1.18.0): the caller may pass a
+ * `SecureStorageAdapter` (Keychain/Keystore-backed, e.g. an
+ * expo-secure-store hybrid) plus the set of "secure keys" — the
+ * sensitive auth material (refresh token, access token, cached user).
+ * When present, those keys are routed through the adapter instead of
+ * plain AsyncStorage; every other key stays in AsyncStorage. The SDK
+ * never depends on expo-secure-store itself — the app supplies the
+ * adapter (Supabase `auth.storage` model), so bare-RN stays Metro-safe.
+ * Every adapter op is try/catch-guarded: an adapter failure degrades to
+ * AsyncStorage rather than losing the session.
  */
+
+type StorageOptions = {
+    /** Encrypted-at-rest adapter for the `secureKeys` below. Null/undefined → plain AsyncStorage for everything (default). */
+    secureAdapter?: SecureStorageAdapter | null;
+    /** Keys routed through `secureAdapter` when it is present. Everything else stays in AsyncStorage. */
+    secureKeys?: Iterable<string>;
+};
 declare class Storage {
     private cache;
     private hydrated;
+    private readonly secure;
+    private readonly secureKeys;
+    constructor(opts?: StorageOptions);
+    private isSecure;
     /**
-     * Populate the memory cache from AsyncStorage. Must be awaited
+     * Populate the memory cache from persistent storage. Must be awaited
      * once at SDK init — after that, `get` returns synchronously from
-     * the cache and `set` fire-and-forgets to AsyncStorage.
+     * the cache and `set` fire-and-forgets. For secure keys, reads the
+     * adapter first, then falls back to (and migrates from) any legacy
+     * plaintext AsyncStorage value written by a pre-secure SDK version —
+     * so enabling secure storage never signs an existing user out.
      */
     hydrate(keys: string[]): Promise<void>;
+    /** Read a secure key: adapter first, else migrate legacy plaintext. Never throws. */
+    private hydrateSecureKey;
     get(key: string): string | null;
     set(key: string, value: string): void;
     remove(key: string): void;
     /**
      * Remove every sendora_*-prefixed key from both memory AND
-     * AsyncStorage. Uses getAllKeys() to find keys this process never
-     * cached (e.g. orphaned writes from a prior SDK version that added
-     * a key not in our hydrate list). Falls back to cache enumeration
+     * AsyncStorage, plus every secure key from the adapter. Uses
+     * getAllKeys() to find keys this process never cached (e.g. orphaned
+     * writes from a prior SDK version). Falls back to cache enumeration
      * if the AsyncStorage backend doesn't expose getAllKeys.
      */
     clearAll(): Promise<void>;
@@ -744,127 +924,6 @@ declare class Links {
     attachLinkingApi(opts?: AttachLinkingApiOptions): Promise<() => void>;
 }
 
-interface SendoraConfig {
-    /**
-     * Public API key (`pk_live_…` or `pk_test_…`). Secret keys are refused.
-     * Canonical name as of 0.10.0 — pre-0.10.0 callers using `publicKey`
-     * still work via the deprecated alias below.
-     */
-    apiKey?: string;
-    /**
-     * @deprecated Use `apiKey` instead (0.10.0+ canonical name across
-     * sdk-web / sdk-ios / sdk-android). Kept for back-compat — when
-     * both are set, `apiKey` wins.
-     */
-    publicKey?: string;
-    /** Backend base URL. Defaults to Sendora's production API. */
-    apiUrl?: string;
-    /** `"prod"` | `"staging"` | `"dev"` routing hint. For API-key auth this
-     *  is IGNORED — the backend forcibly tags events with the environment
-     *  encoded in the key prefix (pk_prod_* / pk_staging_* / pk_dev_*). See
-     *  ADR-014. Kept for session-authed callers and test harnesses that
-     *  don't use API keys. Defaults to `"prod"`. */
-    environment?: "prod" | "staging" | "dev";
-    /** Optional project id scoping. */
-    projectId?: string;
-    /** If false, events drop until setConsent(true) is called. Default true (mobile apps usually collect OS-level consent). */
-    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.
-     * - `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.
-     */
-    autoTrack?: boolean | {
-        appOpen?: boolean;
-        sessionStart?: boolean;
-        appBackground?: boolean;
-        engagement?: boolean;
-    };
-    /** Idle threshold (ms) for session expiry; default 30 minutes. */
-    sessionIdleMs?: number;
-    /**
-     * iOS bundle id (e.g. `com.pulse.news`). Forwarded to backend on
-     * `links.create()` / `links.matchDeferred()` for the bundle-id gate —
-     * blocks a leaked public key from being used by a different app.
-     */
-    iosBundleId?: string;
-    /**
-     * Android package name (e.g. `com.pulse.news`). Same purpose as
-     * `iosBundleId` above.
-     */
-    androidPackageName?: string;
-    /**
-     * Optional share-link host (e.g. `pulse.link`). When set, the deep
-     * links module's URL extractor only treats Sendora-routed URLs whose
-     * host matches this domain (or a subdomain). Leave unset on apps that
-     * use the default Sendora-hosted share domain (`go.sendoracloud.com`).
-     * Added 0.16.0.
-     */
-    linkDomain?: string;
-    /**
-     * Your app's version (e.g. "2.4.0"). Attached to every event's
-     * `context.device.appVersion` so the dashboard can break analytics down by
-     * release (ADR-022). Optional — RN has no zero-dep way to auto-read the
-     * host app version, so supply it (e.g. from `expo-constants` /
-     * `react-native-device-info`) if you want app-version analytics.
-     */
-    appVersion?: string;
-    /**
-     * App build number (iOS `CFBundleVersion` / Android `versionCode`). Auto-read
-     * from expo-application's `nativeBuildVersion` when present; supply here to
-     * override or for non-Expo apps. Shown as "version (build)" on the dashboard.
-     */
-    appBuild?: string;
-}
-type TraitValue = string | number | boolean | null | undefined;
-interface IdentifyTraits {
-    email?: string;
-    name?: string;
-    avatarUrl?: string;
-    [key: string]: TraitValue;
-}
-interface TrackProperties {
-    [key: string]: TraitValue | TraitValue[];
-}
-type PushPlatform = "ios" | "android";
-interface PushTokenRegistration {
-    token: string;
-    platform: PushPlatform;
-    /**
-     * 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.
  *
@@ -913,6 +972,17 @@ declare class SendoraSDK {
     getSessionId(): string;
     /** Stable anonymous identifier for this install — survives app restarts via AsyncStorage. */
     getAnonymousId(): string;
+    /**
+     * Non-throwing, synchronous read of the anonymous id. Returns `null`
+     * until `init()` has resolved — the id lives in AsyncStorage and is
+     * hydrated (or minted) during `init()`, so there is nothing to read
+     * before that. Unlike `getAnonymousId()`, this never throws, so an
+     * offline-first caller can read-or-fallback at cold start without a
+     * try/catch. `init()` itself needs no network (disk-only hydrate), so
+     * awaiting it once at boot makes this return a value even offline.
+     * Once ready it returns the same stable id as `getAnonymousId()`.
+     */
+    getAnonymousIdSync(): string | null;
     /** Current identified user id, if any. */
     getUserId(): string | null;
     /** Toggle consent at runtime — when false, events drop instead of fire. */

package/dist/index.d.ts

@@ -1,3 +1,156 @@
+interface SendoraConfig {
+    /**
+     * Public API key (`pk_live_…` or `pk_test_…`). Secret keys are refused.
+     * Canonical name as of 0.10.0 — pre-0.10.0 callers using `publicKey`
+     * still work via the deprecated alias below.
+     */
+    apiKey?: string;
+    /**
+     * @deprecated Use `apiKey` instead (0.10.0+ canonical name across
+     * sdk-web / sdk-ios / sdk-android). Kept for back-compat — when
+     * both are set, `apiKey` wins.
+     */
+    publicKey?: string;
+    /** Backend base URL. Defaults to Sendora's production API. */
+    apiUrl?: string;
+    /** `"prod"` | `"staging"` | `"dev"` routing hint. For API-key auth this
+     *  is IGNORED — the backend forcibly tags events with the environment
+     *  encoded in the key prefix (pk_prod_* / pk_staging_* / pk_dev_*). See
+     *  ADR-014. Kept for session-authed callers and test harnesses that
+     *  don't use API keys. Defaults to `"prod"`. */
+    environment?: "prod" | "staging" | "dev";
+    /** Optional project id scoping. */
+    projectId?: string;
+    /** If false, events drop until setConsent(true) is called. Default true (mobile apps usually collect OS-level consent). */
+    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.
+     * - `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.
+     */
+    autoTrack?: boolean | {
+        appOpen?: boolean;
+        sessionStart?: boolean;
+        appBackground?: boolean;
+        engagement?: boolean;
+    };
+    /** Idle threshold (ms) for session expiry; default 30 minutes. */
+    sessionIdleMs?: number;
+    /**
+     * iOS bundle id (e.g. `com.pulse.news`). Forwarded to backend on
+     * `links.create()` / `links.matchDeferred()` for the bundle-id gate —
+     * blocks a leaked public key from being used by a different app.
+     */
+    iosBundleId?: string;
+    /**
+     * Android package name (e.g. `com.pulse.news`). Same purpose as
+     * `iosBundleId` above.
+     */
+    androidPackageName?: string;
+    /**
+     * Optional share-link host (e.g. `pulse.link`). When set, the deep
+     * links module's URL extractor only treats Sendora-routed URLs whose
+     * host matches this domain (or a subdomain). Leave unset on apps that
+     * use the default Sendora-hosted share domain (`go.sendoracloud.com`).
+     * Added 0.16.0.
+     */
+    linkDomain?: string;
+    /**
+     * Your app's version (e.g. "2.4.0"). Attached to every event's
+     * `context.device.appVersion` so the dashboard can break analytics down by
+     * release (ADR-022). Optional — RN has no zero-dep way to auto-read the
+     * host app version, so supply it (e.g. from `expo-constants` /
+     * `react-native-device-info`) if you want app-version analytics.
+     */
+    appVersion?: string;
+    /**
+     * App build number (iOS `CFBundleVersion` / Android `versionCode`). Auto-read
+     * from expo-application's `nativeBuildVersion` when present; supply here to
+     * override or for non-Expo apps. Shown as "version (build)" on the dashboard.
+     */
+    appBuild?: string;
+    /**
+     * Optional encrypted-at-rest storage for sensitive auth material (refresh
+     * token, access token, cached user). When provided, the SDK routes ONLY those
+     * keys through this adapter instead of plain AsyncStorage; everything else
+     * (analytics anon id, session flags) stays in AsyncStorage. Existing plaintext
+     * tokens are migrated into the adapter transparently on the first launch after
+     * you enable it (dual-read), so no one is signed out.
+     *
+     * Pass a Keychain/Keystore-backed adapter — e.g. an `expo-secure-store`
+     * hybrid (AES key in SecureStore encrypting the value in AsyncStorage, the
+     * "LargeSecureStore" pattern). The SDK does NOT depend on `expo-secure-store`
+     * itself — you supply the adapter, mirroring Supabase's `auth.storage` model —
+     * so bare-RN apps stay Metro-safe. Omit to keep the default AsyncStorage
+     * behaviour (OWASP MASVS-L1). See docs/backend-identity + docs/sdks.
+     *
+     * Guidance: this is a defense-in-depth (OWASP L2) upgrade — refresh tokens are
+     * long-lived and high-value, so encrypt them on a rooted/jailbroken-device
+     * threat model. It is opt-in: adding it never changes an app that doesn't pass it.
+     */
+    secureStorage?: SecureStorageAdapter;
+}
+/**
+ * Async key/value adapter for encrypted-at-rest auth storage. Compatible with a
+ * thin wrapper over `expo-secure-store` or `react-native-keychain`. All methods
+ * are async; the SDK awaits them during `init()` hydrate and fire-and-forgets on
+ * write (identical to its AsyncStorage handling). A throwing adapter degrades
+ * gracefully to AsyncStorage — the SDK never loses a session on adapter failure.
+ */
+interface SecureStorageAdapter {
+    getItem(key: string): Promise<string | null>;
+    setItem(key: string, value: string): Promise<void>;
+    removeItem(key: string): Promise<void>;
+}
+type TraitValue = string | number | boolean | null | undefined;
+interface IdentifyTraits {
+    email?: string;
+    name?: string;
+    avatarUrl?: string;
+    [key: string]: TraitValue;
+}
+interface TrackProperties {
+    [key: string]: TraitValue | TraitValue[];
+}
+type PushPlatform = "ios" | "android";
+interface PushTokenRegistration {
+    token: string;
+    platform: PushPlatform;
+    /**
+     * 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;
+}
+
 /**
  * Hybrid storage for React Native: read-through memory cache backed
  * by AsyncStorage for persistence. Callers can read synchronously
@@ -7,24 +160,51 @@
  * AsyncStorage is a required peer dependency — we import it lazily
  * so the package itself doesn't hard-fail if the user hasn't
  * installed it yet (they'll see an explicit runtime error instead).
+ *
+ * Optional encrypted-at-rest storage (1.18.0): the caller may pass a
+ * `SecureStorageAdapter` (Keychain/Keystore-backed, e.g. an
+ * expo-secure-store hybrid) plus the set of "secure keys" — the
+ * sensitive auth material (refresh token, access token, cached user).
+ * When present, those keys are routed through the adapter instead of
+ * plain AsyncStorage; every other key stays in AsyncStorage. The SDK
+ * never depends on expo-secure-store itself — the app supplies the
+ * adapter (Supabase `auth.storage` model), so bare-RN stays Metro-safe.
+ * Every adapter op is try/catch-guarded: an adapter failure degrades to
+ * AsyncStorage rather than losing the session.
  */
+
+type StorageOptions = {
+    /** Encrypted-at-rest adapter for the `secureKeys` below. Null/undefined → plain AsyncStorage for everything (default). */
+    secureAdapter?: SecureStorageAdapter | null;
+    /** Keys routed through `secureAdapter` when it is present. Everything else stays in AsyncStorage. */
+    secureKeys?: Iterable<string>;
+};
 declare class Storage {
     private cache;
     private hydrated;
+    private readonly secure;
+    private readonly secureKeys;
+    constructor(opts?: StorageOptions);
+    private isSecure;
     /**
-     * Populate the memory cache from AsyncStorage. Must be awaited
+     * Populate the memory cache from persistent storage. Must be awaited
      * once at SDK init — after that, `get` returns synchronously from
-     * the cache and `set` fire-and-forgets to AsyncStorage.
+     * the cache and `set` fire-and-forgets. For secure keys, reads the
+     * adapter first, then falls back to (and migrates from) any legacy
+     * plaintext AsyncStorage value written by a pre-secure SDK version —
+     * so enabling secure storage never signs an existing user out.
      */
     hydrate(keys: string[]): Promise<void>;
+    /** Read a secure key: adapter first, else migrate legacy plaintext. Never throws. */
+    private hydrateSecureKey;
     get(key: string): string | null;
     set(key: string, value: string): void;
     remove(key: string): void;
     /**
      * Remove every sendora_*-prefixed key from both memory AND
-     * AsyncStorage. Uses getAllKeys() to find keys this process never
-     * cached (e.g. orphaned writes from a prior SDK version that added
-     * a key not in our hydrate list). Falls back to cache enumeration
+     * AsyncStorage, plus every secure key from the adapter. Uses
+     * getAllKeys() to find keys this process never cached (e.g. orphaned
+     * writes from a prior SDK version). Falls back to cache enumeration
      * if the AsyncStorage backend doesn't expose getAllKeys.
      */
     clearAll(): Promise<void>;
@@ -744,127 +924,6 @@ declare class Links {
     attachLinkingApi(opts?: AttachLinkingApiOptions): Promise<() => void>;
 }
 
-interface SendoraConfig {
-    /**
-     * Public API key (`pk_live_…` or `pk_test_…`). Secret keys are refused.
-     * Canonical name as of 0.10.0 — pre-0.10.0 callers using `publicKey`
-     * still work via the deprecated alias below.
-     */
-    apiKey?: string;
-    /**
-     * @deprecated Use `apiKey` instead (0.10.0+ canonical name across
-     * sdk-web / sdk-ios / sdk-android). Kept for back-compat — when
-     * both are set, `apiKey` wins.
-     */
-    publicKey?: string;
-    /** Backend base URL. Defaults to Sendora's production API. */
-    apiUrl?: string;
-    /** `"prod"` | `"staging"` | `"dev"` routing hint. For API-key auth this
-     *  is IGNORED — the backend forcibly tags events with the environment
-     *  encoded in the key prefix (pk_prod_* / pk_staging_* / pk_dev_*). See
-     *  ADR-014. Kept for session-authed callers and test harnesses that
-     *  don't use API keys. Defaults to `"prod"`. */
-    environment?: "prod" | "staging" | "dev";
-    /** Optional project id scoping. */
-    projectId?: string;
-    /** If false, events drop until setConsent(true) is called. Default true (mobile apps usually collect OS-level consent). */
-    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.
-     * - `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.
-     */
-    autoTrack?: boolean | {
-        appOpen?: boolean;
-        sessionStart?: boolean;
-        appBackground?: boolean;
-        engagement?: boolean;
-    };
-    /** Idle threshold (ms) for session expiry; default 30 minutes. */
-    sessionIdleMs?: number;
-    /**
-     * iOS bundle id (e.g. `com.pulse.news`). Forwarded to backend on
-     * `links.create()` / `links.matchDeferred()` for the bundle-id gate —
-     * blocks a leaked public key from being used by a different app.
-     */
-    iosBundleId?: string;
-    /**
-     * Android package name (e.g. `com.pulse.news`). Same purpose as
-     * `iosBundleId` above.
-     */
-    androidPackageName?: string;
-    /**
-     * Optional share-link host (e.g. `pulse.link`). When set, the deep
-     * links module's URL extractor only treats Sendora-routed URLs whose
-     * host matches this domain (or a subdomain). Leave unset on apps that
-     * use the default Sendora-hosted share domain (`go.sendoracloud.com`).
-     * Added 0.16.0.
-     */
-    linkDomain?: string;
-    /**
-     * Your app's version (e.g. "2.4.0"). Attached to every event's
-     * `context.device.appVersion` so the dashboard can break analytics down by
-     * release (ADR-022). Optional — RN has no zero-dep way to auto-read the
-     * host app version, so supply it (e.g. from `expo-constants` /
-     * `react-native-device-info`) if you want app-version analytics.
-     */
-    appVersion?: string;
-    /**
-     * App build number (iOS `CFBundleVersion` / Android `versionCode`). Auto-read
-     * from expo-application's `nativeBuildVersion` when present; supply here to
-     * override or for non-Expo apps. Shown as "version (build)" on the dashboard.
-     */
-    appBuild?: string;
-}
-type TraitValue = string | number | boolean | null | undefined;
-interface IdentifyTraits {
-    email?: string;
-    name?: string;
-    avatarUrl?: string;
-    [key: string]: TraitValue;
-}
-interface TrackProperties {
-    [key: string]: TraitValue | TraitValue[];
-}
-type PushPlatform = "ios" | "android";
-interface PushTokenRegistration {
-    token: string;
-    platform: PushPlatform;
-    /**
-     * 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.
  *
@@ -913,6 +972,17 @@ declare class SendoraSDK {
     getSessionId(): string;
     /** Stable anonymous identifier for this install — survives app restarts via AsyncStorage. */
     getAnonymousId(): string;
+    /**
+     * Non-throwing, synchronous read of the anonymous id. Returns `null`
+     * until `init()` has resolved — the id lives in AsyncStorage and is
+     * hydrated (or minted) during `init()`, so there is nothing to read
+     * before that. Unlike `getAnonymousId()`, this never throws, so an
+     * offline-first caller can read-or-fallback at cold start without a
+     * try/catch. `init()` itself needs no network (disk-only hydrate), so
+     * awaiting it once at boot makes this return a value even offline.
+     * Once ready it returns the same stable id as `getAnonymousId()`.
+     */
+    getAnonymousIdSync(): string | null;
     /** Current identified user id, if any. */
     getUserId(): string | null;
     /** Toggle consent at runtime — when false, events drop instead of fire. */

package/dist/index.js

@@ -21,20 +21,30 @@ async function getAsyncStorage() {
   return asyncStoragePromise;
 }
 var Storage = class {
-  constructor() {
+  constructor(opts = {}) {
     this.cache = /* @__PURE__ */ new Map();
     this.hydrated = false;
+    this.secure = opts.secureAdapter ?? null;
+    this.secureKeys = new Set(opts.secureKeys ?? []);
+  }
+  isSecure(key) {
+    return this.secure !== null && this.secureKeys.has(key);
   }
   /**
-   * Populate the memory cache from AsyncStorage. Must be awaited
+   * Populate the memory cache from persistent storage. Must be awaited
    * once at SDK init — after that, `get` returns synchronously from
-   * the cache and `set` fire-and-forgets to AsyncStorage.
+   * the cache and `set` fire-and-forgets. For secure keys, reads the
+   * adapter first, then falls back to (and migrates from) any legacy
+   * plaintext AsyncStorage value written by a pre-secure SDK version —
+   * so enabling secure storage never signs an existing user out.
    */
   async hydrate(keys) {
     if (this.hydrated) return;
     const store = await getAsyncStorage();
-    if (store) {
-      for (const k of keys) {
+    for (const k of keys) {
+      if (this.isSecure(k)) {
+        await this.hydrateSecureKey(k, store);
+      } else if (store) {
         try {
           const v = await store.getItem(PREFIX + k);
           if (v !== null) this.cache.set(k, v);
@@ -44,11 +54,50 @@ var Storage = class {
     }
     this.hydrated = true;
   }
+  /** Read a secure key: adapter first, else migrate legacy plaintext. Never throws. */
+  async hydrateSecureKey(k, store) {
+    try {
+      const secureVal = await this.secure.getItem(k);
+      if (secureVal !== null) {
+        this.cache.set(k, secureVal);
+        return;
+      }
+      if (store) {
+        const legacy = await store.getItem(PREFIX + k).catch(() => null);
+        if (legacy !== null) {
+          this.cache.set(k, legacy);
+          try {
+            await this.secure.setItem(k, legacy);
+            await store.removeItem(PREFIX + k).catch(() => {
+            });
+          } catch {
+          }
+        }
+      }
+    } catch {
+      if (store) {
+        try {
+          const legacy = await store.getItem(PREFIX + k);
+          if (legacy !== null) this.cache.set(k, legacy);
+        } catch {
+        }
+      }
+    }
+  }
   get(key) {
     return this.cache.get(key) ?? null;
   }
   set(key, value) {
     this.cache.set(key, value);
+    if (this.isSecure(key)) {
+      void this.secure.setItem(key, value).catch(() => {
+        void getAsyncStorage().then((store) => {
+          if (store) store.setItem(PREFIX + key, value).catch(() => {
+          });
+        });
+      });
+      return;
+    }
     void getAsyncStorage().then((store) => {
       if (store) store.setItem(PREFIX + key, value).catch(() => {
       });
@@ -56,6 +105,10 @@ var Storage = class {
   }
   remove(key) {
     this.cache.delete(key);
+    if (this.isSecure(key)) {
+      void this.secure.removeItem(key).catch(() => {
+      });
+    }
     void getAsyncStorage().then((store) => {
       if (store) store.removeItem(PREFIX + key).catch(() => {
       });
@@ -63,13 +116,21 @@ var Storage = class {
   }
   /**
    * Remove every sendora_*-prefixed key from both memory AND
-   * AsyncStorage. Uses getAllKeys() to find keys this process never
-   * cached (e.g. orphaned writes from a prior SDK version that added
-   * a key not in our hydrate list). Falls back to cache enumeration
+   * AsyncStorage, plus every secure key from the adapter. Uses
+   * getAllKeys() to find keys this process never cached (e.g. orphaned
+   * writes from a prior SDK version). Falls back to cache enumeration
    * if the AsyncStorage backend doesn't expose getAllKeys.
    */
   async clearAll() {
     this.cache.clear();
+    if (this.secure) {
+      for (const k of this.secureKeys) {
+        try {
+          await this.secure.removeItem(k);
+        } catch {
+        }
+      }
+    }
     const store = await getAsyncStorage();
     if (!store) return;
     let keys = [];
@@ -82,7 +143,7 @@ var Storage = class {
       }
     }
     if (keys.length === 0) {
-      keys = Array.from(this.cache.keys()).map((k) => PREFIX + k);
+      keys = Array.from(this.secureKeys).map((k) => PREFIX + k);
     }
     for (const k of keys) {
       try {
@@ -96,7 +157,7 @@ var Storage = class {
 // package.json
 var package_default = {
   name: "@sendoracloud/sdk-react-native",
-  version: "1.16.0",
+  version: "1.18.0",
   description: "Sendora Cloud React Native + Expo SDK \u2014 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",
@@ -149,13 +210,15 @@ var package_default = {
   },
   scripts: {
     build: "tsup src/index.ts src/contact-widget.tsx --format esm,cjs --dts --clean --external react --external react-native --external react-native-webview",
-    typecheck: "tsc --noEmit"
+    typecheck: "tsc --noEmit",
+    test: "tsx test/secure-storage.test.ts && tsx test/integration-storage.test.ts"
   },
   devDependencies: {
     "@types/react": "^19.2.16",
     "react-native": "^0.85.3",
     "react-native-webview": "^13.16.1",
     tsup: "^8.0.0",
+    tsx: "^4.21.0",
     typescript: "^5.0.0"
   },
   license: "MIT",
@@ -1961,6 +2024,7 @@ var AUTH_HYDRATE_KEYS = [
   "auth_refresh_token",
   "auth_user"
 ];
+var SECURE_KEYS = ["auth_refresh_token", "auth_access_token", "auth_user"];
 var PUBLIC_KEY_RE = /^pk_(prod|staging|dev|live|test)_[A-Za-z0-9]{16,}$/;
 var MAX_PUSH_TOKEN_BYTES = 4096;
 var MAX_PUSH_METADATA_BYTES = 4096;
@@ -2155,6 +2219,9 @@ var SendoraSDK = class {
         `[sendoracloud] apiUrl override active: ${apiUrl} \u2014 confirm this is intentional. Tokens + events will be sent here.`
       );
     }
+    if (config.secureStorage) {
+      this.storage = new Storage({ secureAdapter: config.secureStorage, secureKeys: SECURE_KEYS });
+    }
     await this.storage.hydrate([
       ANON_KEY,
       USER_ID_KEY,
@@ -2236,6 +2303,19 @@ var SendoraSDK = class {
     this.assertReady();
     return this.anonId;
   }
+  /**
+   * Non-throwing, synchronous read of the anonymous id. Returns `null`
+   * until `init()` has resolved — the id lives in AsyncStorage and is
+   * hydrated (or minted) during `init()`, so there is nothing to read
+   * before that. Unlike `getAnonymousId()`, this never throws, so an
+   * offline-first caller can read-or-fallback at cold start without a
+   * try/catch. `init()` itself needs no network (disk-only hydrate), so
+   * awaiting it once at boot makes this return a value even offline.
+   * Once ready it returns the same stable id as `getAnonymousId()`.
+   */
+  getAnonymousIdSync() {
+    return this.anonId || null;
+  }
   /** Current identified user id, if any. */
   getUserId() {
     return this.userId;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sendoracloud/sdk-react-native",
-  "version": "1.16.0",
+  "version": "1.18.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",
@@ -53,13 +53,15 @@
   },
   "scripts": {
     "build": "tsup src/index.ts src/contact-widget.tsx --format esm,cjs --dts --clean --external react --external react-native --external react-native-webview",
-    "typecheck": "tsc --noEmit"
+    "typecheck": "tsc --noEmit",
+    "test": "tsx test/secure-storage.test.ts && tsx test/integration-storage.test.ts"
   },
   "devDependencies": {
     "@types/react": "^19.2.16",
     "react-native": "^0.85.3",
     "react-native-webview": "^13.16.1",
     "tsup": "^8.0.0",
+    "tsx": "^4.21.0",
     "typescript": "^5.0.0"
   },
   "license": "MIT",