@sendoracloud/sdk-react-native 0.4.0 → 0.7.0

package/dist/index.d.cts

@@ -21,9 +21,11 @@ declare class Storage {
     set(key: string, value: string): void;
     remove(key: string): void;
     /**
-     * Remove every sendora_*-prefixed key we know about from both
-     * memory and AsyncStorage. Used by reset() so no stale identity
-     * survives a logout, including keys future SDK versions might add.
+     * 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
+     * if the AsyncStorage backend doesn't expose getAllKeys.
      */
     clearAll(): Promise<void>;
 }
@@ -39,12 +41,25 @@ declare class Storage {
  *       user_id is preserved on success. Throws
  *       EmailAlreadyTakenError on 409. Otherwise calls
  *       /auth-service/signup as a fresh account.
- *   signIn(email, password) — POST /auth-service/login. If the SDK
- *       was anonymous, wipes local identity (anonId rotated, userId
- *       cleared, tokens dropped) BEFORE installing the new session.
+ *   signIn(email, password) — POST /auth-service/login. Wipes local
+ *       identity (anonId rotated, userId cleared, tokens dropped)
+ *       BEFORE the network call so any track() fired during the
+ *       round-trip can't attach to the prior identity.
  *
- * Tokens persist in AsyncStorage so a cold app launch re-hydrates
- * the active session.
+ * All public auth ops are serialized through a single-flight chain
+ * so a UI double-submit can't mint two anonymous users or interleave
+ * a signIn + signOut.
+ *
+ * Tokens persist via the configured secure-storage adapter (defaults
+ * to AsyncStorage; consumers handling sensitive accounts should pass
+ * a Keychain / SecureStore-backed adapter via `secureStorage`).
+ *
+ * Response payloads are validated non-empty before persisting so a
+ * malformed/MITM'd response can't install an `id = ""` user.
+ *
+ * Access token expiry is tracked locally — getAccessToken() returns
+ * null past expiry and triggers a single-flight refresh on the next
+ * call.
  */
 
 interface AuthUser {
@@ -74,24 +89,36 @@ interface AuthHooks {
      *  identity (analytics userId, push token registration, etc). */
     onIdentityChange: (userId: string | null) => void;
     /**
-     * Called when the SDK switches from an anonymous user to a real
-     * account via signIn(). The parent rotates anonId so events from
-     * the new user can't carry over orphaned attribution.
+     * Called when the SDK switches from one identity to another via
+     * signIn() or non-anonymous signUp(). The parent rotates anonId
+     * + drops any pending events so the new user can't carry over
+     * orphaned attribution.
      */
     onAnonymousWipe: () => Promise<void>;
     apiUrl: string;
     publicKey: string;
+    debug: boolean;
 }
 declare class Auth {
     private hooks;
     private user;
     private accessToken;
+    private accessExpiresAt;
+    private inflight;
+    private refreshInflight;
     constructor(hooks: AuthHooks);
-    /** Re-hydrate session from AsyncStorage. Called by the parent SDK
+    /** Re-hydrate session from storage. Called by the parent SDK
      *  during init() after Storage.hydrate() has run. */
     hydrate(): void;
     getCurrentUser(): AuthUser | null;
-    getAccessToken(): string | null;
+    /**
+     * Returns a non-expired access token or null. If the cached token
+     * is expired but a refresh token exists, transparently refreshes
+     * (single-flight — concurrent callers share one network call).
+     */
+    getAccessToken(): Promise<string | null>;
+    /** Sync read — returns whatever's cached even if expired. Prefer the async variant. */
+    getAccessTokenSync(): string | null;
     signInAnonymously(opts?: {
         name?: string;
         metadata?: Record<string, unknown>;
@@ -100,8 +127,71 @@ declare class Auth {
         name?: string;
         metadata?: Record<string, unknown>;
     }): Promise<AuthUser>;
-    signIn(email: string, password: string): Promise<AuthUser>;
+    /**
+     * Sign in with email + password. When the user has confirmed MFA,
+     * returns `{mfaRequired, mfaChallengeToken}` instead of an
+     * `AuthUser`; caller must follow up with `challengeMfa()`.
+     */
+    signIn(email: string, password: string): Promise<AuthUser | {
+        mfaRequired: true;
+        mfaChallengeToken: string;
+        userId: string;
+    }>;
+    /**
+     * Exchange the MFA challenge token from `signIn` for a real session
+     * by submitting a TOTP or recovery code from the user's authenticator.
+     */
+    challengeMfa(mfaChallengeToken: string, code: string): Promise<AuthUser>;
+    sendMagicLink(email: string): Promise<void>;
+    verifyMagicLink(token: string): Promise<AuthUser>;
+    enrollMfa(): Promise<{
+        secret: string;
+        otpauthUrl: string;
+        recoveryCodes: string[];
+    }>;
+    confirmMfa(code: string): Promise<boolean>;
+    disableMfa(): Promise<void>;
+    listMySessions(): Promise<Array<{
+        id: string;
+        deviceInfo: string | null;
+        ipHash: string | null;
+        lastUsedAt: string | null;
+        createdAt: string;
+    }>>;
+    revokeSession(sessionId: string): Promise<void>;
+    revokeAllSessions(): Promise<void>;
+    /**
+     * Start OIDC sign-in. Returns the IdP's authorization URL — caller
+     * opens it via React Native's `Linking.openURL()` (or
+     * `WebBrowser.openAuthSessionAsync` from `expo-web-browser` when
+     * inside Expo). The IdP redirects through Sendora's callback to the
+     * `returnTo` URL with `#sendora_oidc_token=...` in the fragment.
+     *
+     * On the customer's app side, `returnTo` MUST be a custom URL scheme
+     * registered in Info.plist (iOS) / AndroidManifest.xml intent-filter
+     * (Android), e.g. `myapp://oidc-callback`. When the deep link fires,
+     * call `consumeSsoFragment(url)` on the captured URL.
+     */
+    startSso(returnTo: string): Promise<{
+        authorizationUrl: string;
+    }>;
+    /**
+     * Consume an OIDC callback URL captured via React Native's
+     * `Linking.addEventListener('url', ...)`. Reads the fragment for
+     * `sendora_oidc_token`, exchanges it for a session, and persists.
+     * Throws AuthError on `sendora_oidc_error=...` fragment.
+     */
+    consumeSsoFragment(callbackUrl: string): Promise<AuthUser>;
+    private bearerHeaders;
+    private unwrap;
+    /**
+     * Sign out: wipe local identity FIRST so the user is logged out on
+     * device even if the revoke network call hangs (airplane mode, 5xx).
+     * Revoke is fire-and-forget after the wipe.
+     */
     signOut(): Promise<void>;
+    private serialize;
+    private refreshAccessToken;
     private callAuth;
     private persist;
     private wipeLocalIdentity;
@@ -122,8 +212,10 @@ interface SendoraConfig {
     environment?: "prod" | "staging" | "dev";
     /** Optional project id scoping. */
     projectId?: string;
-    /** If false, events buffer until consent.grant() is called. Default true (mobile apps usually collect OS-level consent). */
+    /** 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;
 }
 type TraitValue = string | number | boolean | null | undefined;
 interface IdentifyTraits {
@@ -176,6 +268,8 @@ declare class SendoraSDK {
     private storage;
     private anonId;
     private userId;
+    private consentGranted;
+    private debug;
     /** Lazy-initialised in init() once we know the apiUrl + publicKey. */
     auth: Auth;
     /** Initialize the SDK. Must be awaited at app startup before identify/track. */
@@ -184,6 +278,8 @@ declare class SendoraSDK {
     getAnonymousId(): string;
     /** Current identified user id, if any. */
     getUserId(): string | null;
+    /** Toggle consent at runtime — when false, events drop instead of fire. */
+    setConsent(granted: boolean): void;
     /** Associate a user id + traits with the current anonymous install. */
     identify(userId: string, traits?: IdentifyTraits): void;
     /** Fire a custom product event. */

package/dist/index.d.ts

@@ -21,9 +21,11 @@ declare class Storage {
     set(key: string, value: string): void;
     remove(key: string): void;
     /**
-     * Remove every sendora_*-prefixed key we know about from both
-     * memory and AsyncStorage. Used by reset() so no stale identity
-     * survives a logout, including keys future SDK versions might add.
+     * 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
+     * if the AsyncStorage backend doesn't expose getAllKeys.
      */
     clearAll(): Promise<void>;
 }
@@ -39,12 +41,25 @@ declare class Storage {
  *       user_id is preserved on success. Throws
  *       EmailAlreadyTakenError on 409. Otherwise calls
  *       /auth-service/signup as a fresh account.
- *   signIn(email, password) — POST /auth-service/login. If the SDK
- *       was anonymous, wipes local identity (anonId rotated, userId
- *       cleared, tokens dropped) BEFORE installing the new session.
+ *   signIn(email, password) — POST /auth-service/login. Wipes local
+ *       identity (anonId rotated, userId cleared, tokens dropped)
+ *       BEFORE the network call so any track() fired during the
+ *       round-trip can't attach to the prior identity.
  *
- * Tokens persist in AsyncStorage so a cold app launch re-hydrates
- * the active session.
+ * All public auth ops are serialized through a single-flight chain
+ * so a UI double-submit can't mint two anonymous users or interleave
+ * a signIn + signOut.
+ *
+ * Tokens persist via the configured secure-storage adapter (defaults
+ * to AsyncStorage; consumers handling sensitive accounts should pass
+ * a Keychain / SecureStore-backed adapter via `secureStorage`).
+ *
+ * Response payloads are validated non-empty before persisting so a
+ * malformed/MITM'd response can't install an `id = ""` user.
+ *
+ * Access token expiry is tracked locally — getAccessToken() returns
+ * null past expiry and triggers a single-flight refresh on the next
+ * call.
  */
 
 interface AuthUser {
@@ -74,24 +89,36 @@ interface AuthHooks {
      *  identity (analytics userId, push token registration, etc). */
     onIdentityChange: (userId: string | null) => void;
     /**
-     * Called when the SDK switches from an anonymous user to a real
-     * account via signIn(). The parent rotates anonId so events from
-     * the new user can't carry over orphaned attribution.
+     * Called when the SDK switches from one identity to another via
+     * signIn() or non-anonymous signUp(). The parent rotates anonId
+     * + drops any pending events so the new user can't carry over
+     * orphaned attribution.
      */
     onAnonymousWipe: () => Promise<void>;
     apiUrl: string;
     publicKey: string;
+    debug: boolean;
 }
 declare class Auth {
     private hooks;
     private user;
     private accessToken;
+    private accessExpiresAt;
+    private inflight;
+    private refreshInflight;
     constructor(hooks: AuthHooks);
-    /** Re-hydrate session from AsyncStorage. Called by the parent SDK
+    /** Re-hydrate session from storage. Called by the parent SDK
      *  during init() after Storage.hydrate() has run. */
     hydrate(): void;
     getCurrentUser(): AuthUser | null;
-    getAccessToken(): string | null;
+    /**
+     * Returns a non-expired access token or null. If the cached token
+     * is expired but a refresh token exists, transparently refreshes
+     * (single-flight — concurrent callers share one network call).
+     */
+    getAccessToken(): Promise<string | null>;
+    /** Sync read — returns whatever's cached even if expired. Prefer the async variant. */
+    getAccessTokenSync(): string | null;
     signInAnonymously(opts?: {
         name?: string;
         metadata?: Record<string, unknown>;
@@ -100,8 +127,71 @@ declare class Auth {
         name?: string;
         metadata?: Record<string, unknown>;
     }): Promise<AuthUser>;
-    signIn(email: string, password: string): Promise<AuthUser>;
+    /**
+     * Sign in with email + password. When the user has confirmed MFA,
+     * returns `{mfaRequired, mfaChallengeToken}` instead of an
+     * `AuthUser`; caller must follow up with `challengeMfa()`.
+     */
+    signIn(email: string, password: string): Promise<AuthUser | {
+        mfaRequired: true;
+        mfaChallengeToken: string;
+        userId: string;
+    }>;
+    /**
+     * Exchange the MFA challenge token from `signIn` for a real session
+     * by submitting a TOTP or recovery code from the user's authenticator.
+     */
+    challengeMfa(mfaChallengeToken: string, code: string): Promise<AuthUser>;
+    sendMagicLink(email: string): Promise<void>;
+    verifyMagicLink(token: string): Promise<AuthUser>;
+    enrollMfa(): Promise<{
+        secret: string;
+        otpauthUrl: string;
+        recoveryCodes: string[];
+    }>;
+    confirmMfa(code: string): Promise<boolean>;
+    disableMfa(): Promise<void>;
+    listMySessions(): Promise<Array<{
+        id: string;
+        deviceInfo: string | null;
+        ipHash: string | null;
+        lastUsedAt: string | null;
+        createdAt: string;
+    }>>;
+    revokeSession(sessionId: string): Promise<void>;
+    revokeAllSessions(): Promise<void>;
+    /**
+     * Start OIDC sign-in. Returns the IdP's authorization URL — caller
+     * opens it via React Native's `Linking.openURL()` (or
+     * `WebBrowser.openAuthSessionAsync` from `expo-web-browser` when
+     * inside Expo). The IdP redirects through Sendora's callback to the
+     * `returnTo` URL with `#sendora_oidc_token=...` in the fragment.
+     *
+     * On the customer's app side, `returnTo` MUST be a custom URL scheme
+     * registered in Info.plist (iOS) / AndroidManifest.xml intent-filter
+     * (Android), e.g. `myapp://oidc-callback`. When the deep link fires,
+     * call `consumeSsoFragment(url)` on the captured URL.
+     */
+    startSso(returnTo: string): Promise<{
+        authorizationUrl: string;
+    }>;
+    /**
+     * Consume an OIDC callback URL captured via React Native's
+     * `Linking.addEventListener('url', ...)`. Reads the fragment for
+     * `sendora_oidc_token`, exchanges it for a session, and persists.
+     * Throws AuthError on `sendora_oidc_error=...` fragment.
+     */
+    consumeSsoFragment(callbackUrl: string): Promise<AuthUser>;
+    private bearerHeaders;
+    private unwrap;
+    /**
+     * Sign out: wipe local identity FIRST so the user is logged out on
+     * device even if the revoke network call hangs (airplane mode, 5xx).
+     * Revoke is fire-and-forget after the wipe.
+     */
     signOut(): Promise<void>;
+    private serialize;
+    private refreshAccessToken;
     private callAuth;
     private persist;
     private wipeLocalIdentity;
@@ -122,8 +212,10 @@ interface SendoraConfig {
     environment?: "prod" | "staging" | "dev";
     /** Optional project id scoping. */
     projectId?: string;
-    /** If false, events buffer until consent.grant() is called. Default true (mobile apps usually collect OS-level consent). */
+    /** 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;
 }
 type TraitValue = string | number | boolean | null | undefined;
 interface IdentifyTraits {
@@ -176,6 +268,8 @@ declare class SendoraSDK {
     private storage;
     private anonId;
     private userId;
+    private consentGranted;
+    private debug;
     /** Lazy-initialised in init() once we know the apiUrl + publicKey. */
     auth: Auth;
     /** Initialize the SDK. Must be awaited at app startup before identify/track. */
@@ -184,6 +278,8 @@ declare class SendoraSDK {
     getAnonymousId(): string;
     /** Current identified user id, if any. */
     getUserId(): string | null;
+    /** Toggle consent at runtime — when false, events drop instead of fire. */
+    setConsent(granted: boolean): void;
     /** Associate a user id + traits with the current anonymous install. */
     identify(userId: string, traits?: IdentifyTraits): void;
     /** Fire a custom product event. */