@sendoracloud/sdk-react-native 0.10.2 → 0.10.4

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();
@@ -72,6 +89,31 @@ SendoraCloud.reset();
 }
 ```
 
+## 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

@@ -231,9 +231,14 @@ var Auth = class {
     this.inflight = Promise.resolve();
     this.refreshInflight = null;
     this.hooks = hooks;
+    this.readyPromise = new Promise((res) => {
+      this.resolveReady = res;
+    });
   }
   /** Re-hydrate session from storage. Called by the parent SDK
-   *  during init() after Storage.hydrate() has run. */
+   *  during init() after Storage.hydrate() has run. Marks the
+   *  internal ready promise as resolved so queued auth calls
+   *  unblock. */
   hydrate() {
     const cachedUser = this.hooks.storage.get(USER_KEY);
     const cachedToken = this.hooks.storage.get(TOKEN_KEY);
@@ -253,6 +258,7 @@ var Auth = class {
         this.hooks.storage.remove(REFRESH_KEY);
       }
     }
+    this.resolveReady();
   }
   getCurrentUser() {
     return this.user;
@@ -705,7 +711,11 @@ var Auth = class {
   }
   // --- internals ---
   serialize(op) {
-    const next = this.inflight.then(op, op);
+    const guarded = async () => {
+      await this.readyPromise;
+      return op();
+    };
+    const next = this.inflight.then(guarded, guarded);
     this.inflight = next.catch(() => void 0);
     return next;
   }
@@ -790,7 +800,7 @@ function decodeJwtPayload(token) {
 }
 
 // src/index.ts
-var SDK_VERSION = "0.10.2";
+var SDK_VERSION = "0.10.4";
 var DEFAULT_API_URL = "https://api.sendoracloud.com";
 var ANON_KEY = "anon_id";
 var USER_ID_KEY = "user_id";
@@ -806,15 +816,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("");
@@ -839,6 +867,7 @@ var SendoraSDK = class {
   }
   /** 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(
@@ -978,7 +1007,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.");
     }
@@ -988,7 +1019,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",
       {
@@ -1001,6 +1032,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

package/dist/index.d.cts

@@ -106,9 +106,26 @@ declare class Auth {
     private accessExpiresAt;
     private inflight;
     private refreshInflight;
+    /**
+     * Resolves when the parent SDK has finished its async init() —
+     * AsyncStorage hydrated + auth.hydrate() restored the cached
+     * session. All public auth methods await this internally so a
+     * customer who forgets `await sendora.init()` before showing the
+     * signup UI doesn't hit the cold-start race where the upgrade
+     * path's `storage.get(REFRESH_KEY)` returns null even though a
+     * valid anonymous session is sitting on disk.
+     *
+     * Industry-standard "SDK gates on internal readiness" pattern
+     * (Firebase Auth, Auth0, Clerk all do equivalent internal
+     * gating).
+     */
+    private readyPromise;
+    private resolveReady;
     constructor(hooks: AuthHooks);
     /** Re-hydrate session from storage. Called by the parent SDK
-     *  during init() after Storage.hydrate() has run. */
+     *  during init() after Storage.hydrate() has run. Marks the
+     *  internal ready promise as resolved so queued auth calls
+     *  unblock. */
     hydrate(): void;
     getCurrentUser(): AuthUser | null;
     /**
@@ -307,11 +324,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.
@@ -368,7 +399,7 @@ 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
@@ -380,4 +411,4 @@ declare class SendoraSDK {
 }
 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

@@ -106,9 +106,26 @@ declare class Auth {
     private accessExpiresAt;
     private inflight;
     private refreshInflight;
+    /**
+     * Resolves when the parent SDK has finished its async init() —
+     * AsyncStorage hydrated + auth.hydrate() restored the cached
+     * session. All public auth methods await this internally so a
+     * customer who forgets `await sendora.init()` before showing the
+     * signup UI doesn't hit the cold-start race where the upgrade
+     * path's `storage.get(REFRESH_KEY)` returns null even though a
+     * valid anonymous session is sitting on disk.
+     *
+     * Industry-standard "SDK gates on internal readiness" pattern
+     * (Firebase Auth, Auth0, Clerk all do equivalent internal
+     * gating).
+     */
+    private readyPromise;
+    private resolveReady;
     constructor(hooks: AuthHooks);
     /** Re-hydrate session from storage. Called by the parent SDK
-     *  during init() after Storage.hydrate() has run. */
+     *  during init() after Storage.hydrate() has run. Marks the
+     *  internal ready promise as resolved so queued auth calls
+     *  unblock. */
     hydrate(): void;
     getCurrentUser(): AuthUser | null;
     /**
@@ -307,11 +324,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.
@@ -368,7 +399,7 @@ 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
@@ -380,4 +411,4 @@ declare class SendoraSDK {
 }
 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

@@ -191,9 +191,14 @@ var Auth = class {
     this.inflight = Promise.resolve();
     this.refreshInflight = null;
     this.hooks = hooks;
+    this.readyPromise = new Promise((res) => {
+      this.resolveReady = res;
+    });
   }
   /** Re-hydrate session from storage. Called by the parent SDK
-   *  during init() after Storage.hydrate() has run. */
+   *  during init() after Storage.hydrate() has run. Marks the
+   *  internal ready promise as resolved so queued auth calls
+   *  unblock. */
   hydrate() {
     const cachedUser = this.hooks.storage.get(USER_KEY);
     const cachedToken = this.hooks.storage.get(TOKEN_KEY);
@@ -213,6 +218,7 @@ var Auth = class {
         this.hooks.storage.remove(REFRESH_KEY);
       }
     }
+    this.resolveReady();
   }
   getCurrentUser() {
     return this.user;
@@ -665,7 +671,11 @@ var Auth = class {
   }
   // --- internals ---
   serialize(op) {
-    const next = this.inflight.then(op, op);
+    const guarded = async () => {
+      await this.readyPromise;
+      return op();
+    };
+    const next = this.inflight.then(guarded, guarded);
     this.inflight = next.catch(() => void 0);
     return next;
   }
@@ -750,7 +760,7 @@ function decodeJwtPayload(token) {
 }
 
 // src/index.ts
-var SDK_VERSION = "0.10.2";
+var SDK_VERSION = "0.10.4";
 var DEFAULT_API_URL = "https://api.sendoracloud.com";
 var ANON_KEY = "anon_id";
 var USER_ID_KEY = "user_id";
@@ -766,15 +776,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("");
@@ -799,6 +827,7 @@ var SendoraSDK = class {
   }
   /** 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(
@@ -938,7 +967,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.");
     }
@@ -948,7 +979,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",
       {
@@ -961,6 +992,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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sendoracloud/sdk-react-native",
-  "version": "0.10.2",
+  "version": "0.10.4",
   "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",