@explorins/pers-sdk-react-native 2.2.0-beta.1 → 2.2.0

package/dist/index.js

@@ -3812,26 +3812,49 @@ const CommonErrorCodes = {
  * Native implementation without external dependencies for optimal performance
  */
 /**
- * Check if JWT token is expired or expiring within margin
+ * Decode JWT payload without verification
  * @param token JWT token (with or without Bearer prefix)
- * @param margin Safety margin in seconds before expiry (default: 60)
+ * @returns Decoded payload or null if invalid
  */
-const isTokenExpired = (token, margin = 60) => {
+const decodeJwtPayload = (token) => {
     const cleanToken = token.replace(/^Bearer\s+/i, '');
     if (!cleanToken || cleanToken.split('.').length !== 3) {
-        return true;
+        return null;
     }
     try {
-        const payload = JSON.parse(atob(cleanToken.split('.')[1]));
-        if (!payload.exp)
-            return false;
-        const currentTime = Math.floor(Date.now() / 1000);
-        return payload.exp < (currentTime + margin);
+        return JSON.parse(atob(cleanToken.split('.')[1]));
     }
     catch {
-        return true;
+        return null;
     }
 };
+/**
+ * Check if JWT token is expired or expiring within margin
+ * @param token JWT token (with or without Bearer prefix)
+ * @param margin Safety margin in seconds before expiry (default: 60)
+ */
+const isTokenExpired = (token, margin = 60) => {
+    const payload = decodeJwtPayload(token);
+    if (!payload)
+        return true;
+    if (!payload.exp)
+        return false;
+    const currentTime = Math.floor(Date.now() / 1000);
+    return payload.exp < (currentTime + margin);
+};
+/**
+ * Get remaining time-to-live for a JWT token in seconds
+ * @param token JWT token (with or without Bearer prefix)
+ * @returns Remaining TTL in seconds, or null if invalid/expired
+ */
+const getTokenTimeToLive = (token) => {
+    const payload = decodeJwtPayload(token);
+    if (!payload?.exp)
+        return null;
+    const currentTime = Math.floor(Date.now() / 1000);
+    const ttl = payload.exp - currentTime;
+    return ttl > 0 ? ttl : null;
+};
 
 /**
  * PERS SDK Error Handling - Optimized for Performance
@@ -8635,6 +8658,49 @@ class AnalyticsApi {
     async getCampaignClaimAnalytics(request) {
         return this.apiClient.post('/analytics/campaign-claims', request);
     }
+    /**
+     * ADMIN: Get redemption redeem analytics with aggregation (charts, metrics, grouping)
+     *
+     * This endpoint is for aggregated analytics only (groupBy/metrics).
+     * For enriched list data with nested objects, use redemption.getRedeems() instead.
+     *
+     * @example Redeems per redemption
+     * ```typescript
+     * const response = await analyticsApi.getRedemptionRedeemAnalytics({
+     *   groupBy: ['redemptionId'],
+     *   metrics: ['count'],
+     *   sortBy: 'count',
+     *   sortOrder: SortOrder.DESC,
+     *   limit: 10
+     * });
+     * ```
+     *
+     * @example Redeems by status over time
+     * ```typescript
+     * const response = await analyticsApi.getRedemptionRedeemAnalytics({
+     *   groupBy: ['month', 'status'],
+     *   metrics: ['count'],
+     *   sortBy: 'month',
+     *   sortOrder: SortOrder.DESC,
+     *   startDate: new Date('2026-01-01'),
+     *   endDate: new Date('2026-12-31')
+     * });
+     * ```
+     *
+     * @example Redeems by business
+     * ```typescript
+     * const response = await analyticsApi.getRedemptionRedeemAnalytics({
+     *   filters: { status: 'COMPLETED' },
+     *   groupBy: ['businessId'],
+     *   metrics: ['count'],
+     *   sortBy: 'count',
+     *   sortOrder: SortOrder.DESC
+     * });
+     * ```
+     */
+    async getRedemptionRedeemAnalytics(request) {
+        return this.apiClient.post('/analytics/redemption-redeems', request);
+    }
     /**
      * ADMIN: Get user analytics with engagement metrics
      *
@@ -8866,6 +8932,15 @@ class AnalyticsService {
     async getCampaignClaimAnalytics(request) {
         return this.analyticsApi.getCampaignClaimAnalytics(request);
     }
+    /**
+     * ADMIN: Get redemption redeem analytics with aggregation
+     *
+     * Returns aggregated redeem data with flexible grouping and metrics.
+     * Perfect for charts and dashboard summaries.
+     */
+    async getRedemptionRedeemAnalytics(request) {
+        return this.analyticsApi.getRedemptionRedeemAnalytics(request);
+    }
     /**
      * ADMIN: Get user analytics with engagement metrics
      *
@@ -9323,6 +9398,8 @@ function isExtendedProvider(provider) {
  * TOKEN_EXPIRED is NOT in this list - it's the normal "please refresh" case.
  *
  * Values validated against CommonErrorCodes from @explorins/pers-shared at compile time.
+ *
+ * SINGLE SOURCE OF TRUTH - use this constant everywhere, never duplicate these values.
  */
 const FATAL_AUTH_CODES = [
     'REFRESH_TOKEN_EXPIRED',
@@ -9330,6 +9407,13 @@ const FATAL_AUTH_CODES = [
     'INVALID_TOKEN',
     'TOKEN_REVOKED'
 ];
+/**
+ * Check if an error message contains any fatal auth error code.
+ * Useful for detecting fatal errors in wrapped/stringified errors.
+ */
+function isFatalAuthErrorInMessage(message) {
+    return FATAL_AUTH_CODES.some(code => message.includes(code));
+}
 /**
  * Platform-agnostic authentication service
  * Handles login, token refresh, and storage operations
@@ -9485,8 +9569,53 @@ class AuthService {
         return FATAL_AUTH_CODES.includes(errorCode);
     }
     /**
-     * Handle authentication failure with proper cleanup.
-     * Called when backend returns fatal auth error codes or refresh fails.
+     * Comprehensive check if an error represents a DEFINITIVE auth failure.
+     * This is the SINGLE SOURCE OF TRUTH for determining if logout is required.
+     *
+     * Returns true for:
+     * - Known fatal error codes (REFRESH_TOKEN_EXPIRED, TOKEN_REVOKED, etc.)
+     * - Fatal error codes in error messages (wrapped errors)
+     * - 401/403 HTTP status codes
+     *
+     * Returns false for (retryable errors):
+     * - Network errors
+     * - Timeouts
+     * - 5xx server errors
+     * - TOKEN_EXPIRED (normal refresh trigger)
+     */
+    isDefinitiveAuthFailure(error) {
+        if (!error)
+            return false;
+        const errorAny = error;
+        // Check error code property against canonical list
+        if (errorAny?.code && this.isFatalAuthError(errorAny.code)) {
+            return true;
+        }
+        // Check if error message contains fatal keywords (fallback for wrapped errors)
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        if (isFatalAuthErrorInMessage(errorMessage)) {
+            return true;
+        }
+        // Check HTTP status if available
+        const status = errorAny?.status || errorAny?.response?.status;
+        if (status === 401 || status === 403) {
+            return true;
+        }
+        // Everything else is considered retryable
+        return false;
+    }
+    /**
+     * Handle authentication failure with provider token recovery.
+     *
+     * Before logging out, attempts to recover the session using the stored
+     * provider token (Firebase JWT, etc.) if it's still valid.
+     *
+     * Recovery Flow:
+     * 1. Check if provider token exists and is not expired
+     * 2. Get the auth type (USER, BUSINESS, TENANT) to know which login to use
+     * 3. Attempt re-authentication with provider token
+     * 4. If successful: Session recovered, stay logged in
+     * 5. If failed: Clear tokens and emit AUTH_FAILED
      */
     async handleAuthFailure() {
         // Already failed - nothing to do
@@ -9502,7 +9631,7 @@ class AuthService {
             return await this.activeAuthFailurePromise;
         }
         // Create the failure promise to deduplicate concurrent calls
-        this.activeAuthFailurePromise = this.performAuthFailure();
+        this.activeAuthFailurePromise = this.performAuthFailureWithRecovery();
         try {
             await this.activeAuthFailurePromise;
         }
@@ -9510,6 +9639,72 @@ class AuthService {
             this.activeAuthFailurePromise = null;
         }
     }
+    /**
+     * Attempts to recover session using provider token before failing.
+     */
+    async performAuthFailureWithRecovery() {
+        // Clear active refresh operations
+        this.activeRefreshPromise = null;
+        // Try to recover using provider token
+        const recovered = await this.attemptProviderTokenRecovery();
+        if (recovered) {
+            return; // Session recovered, don't fail
+        }
+        // Recovery failed - perform actual logout
+        await this.performAuthFailure();
+    }
+    /**
+     * Attempt to recover session using stored provider token.
+     * Extracts context (tenantId/businessId) from the current refresh token to ensure
+     * the recovered session maintains the same context.
+     *
+     * @returns true if session was successfully recovered
+     */
+    async attemptProviderTokenRecovery() {
+        const extended = this.extendedProvider;
+        if (!extended?.getProviderToken || !extended?.getAuthType) {
+            return false; // Provider doesn't support recovery
+        }
+        try {
+            const providerToken = await extended.getProviderToken();
+            if (!providerToken) {
+                return false;
+            }
+            // Check if provider token is still valid (with small margin)
+            if (isTokenExpired(providerToken, 30)) {
+                return false;
+            }
+            const authType = await extended.getAuthType();
+            if (!authType) {
+                return false;
+            }
+            // Extract context (tenantId/businessId) from the current refresh token
+            // This ensures multi-tenant/multi-business users recover to the same context
+            const refreshToken = await this.authProvider?.getRefreshToken?.();
+            const contextClaims = refreshToken ? decodeJwtPayload(refreshToken) : null;
+            // Re-authenticate using provider token based on auth type
+            // Pass the context from the previous session to avoid MULTIPLE_CONTEXT_SELECTION_REQUIRED
+            switch (authType) {
+                case exports.AccountOwnerType.USER:
+                    await this.loginUser(providerToken);
+                    break;
+                case exports.AccountOwnerType.BUSINESS:
+                    await this.loginBusiness(providerToken, contextClaims?.businessId ? { businessId: contextClaims.businessId } : undefined);
+                    break;
+                case exports.AccountOwnerType.TENANT:
+                    await this.loginTenantAdmin(providerToken, contextClaims?.tenantId ? { tenantId: contextClaims.tenantId } : undefined);
+                    break;
+                default:
+                    console.warn(`[AuthService] Unknown auth type for recovery: ${authType}`);
+                    return false;
+            }
+            return true; // Recovery successful
+        }
+        catch (error) {
+            console.warn('[AuthService] Provider token recovery failed:', error);
+            return false;
+        }
+    }
     /**
      * Performs the actual auth failure cleanup
      */
@@ -9589,16 +9784,32 @@ class AuthService {
 
 /**
  * Token Refresh Manager
- * Simple container for token refresh logic with better organization
+ * Industry-standard token lifecycle management with:
+ * - Dynamic refresh margin based on token lifetime
+ * - Retry logic for transient failures
+ * - Only logout on definitive auth failures (not network errors)
  */
 class TokenRefreshManager {
     constructor(authService, authProvider) {
         this.authService = authService;
         this.authProvider = authProvider;
-        this.tokenRefreshMarginSeconds = 120; // 2 minutes
+        // Industry standard: refresh when 25% of token lifetime remains
+        this.REFRESH_THRESHOLD_PERCENT = 0.25;
+        // Minimum margin regardless of token lifetime
+        this.MIN_REFRESH_MARGIN_SECONDS = 30;
+        // Maximum margin (cap for very long-lived tokens)
+        this.MAX_REFRESH_MARGIN_SECONDS = 300; // 5 minutes
+        // Validation cache to avoid redundant checks
         this.lastValidationTime = 0;
         this.validationCacheDurationMs = 30000; // 30 seconds
+        // Retry configuration for transient failures
+        this.MAX_RETRY_ATTEMPTS = 3;
+        this.RETRY_DELAY_MS = 1000;
     }
+    /**
+     * Ensures the access token is valid, refreshing if needed.
+     * Uses dynamic margin based on token lifetime (industry standard).
+     */
     async ensureValidToken() {
         const now = Date.now();
         // Skip validation if we checked recently (within cache duration)
@@ -9610,35 +9821,95 @@ class TokenRefreshManager {
             if (!token) {
                 return;
             }
-            if (isTokenExpired(token, this.tokenRefreshMarginSeconds)) {
-                const refreshSuccess = await this.attemptInternalRefresh();
-                if (!refreshSuccess) {
+            // Calculate dynamic refresh margin based on token lifetime
+            const marginSeconds = this.calculateRefreshMargin(token);
+            if (isTokenExpired(token, marginSeconds)) {
+                const result = await this.attemptRefreshWithRetry();
+                if (!result.success) {
+                    if (result.retryable) {
+                        // Transient error - don't logout, let next request retry
+                        console.warn('[TokenRefreshManager] Refresh failed with retryable error, will retry on next request');
+                        return;
+                    }
+                    // Definitive auth failure - logout required
                     await this.authService.handleAuthFailure();
                 }
                 else {
-                    // Update validation time on successful refresh
+                    // Refresh successful
                     this.lastValidationTime = now;
                 }
             }
             else {
-                // Token is valid, update validation time
+                // Token is valid
                 this.lastValidationTime = now;
             }
         }
         catch (error) {
-            await this.authService.handleAuthFailure();
+            // Unexpected error - log but don't logout (conservative approach)
+            console.error('[TokenRefreshManager] Unexpected error during token validation:', error);
         }
     }
-    async attemptInternalRefresh() {
-        try {
-            await this.authService.refreshAccessToken();
-            return true;
+    /**
+     * Calculate refresh margin dynamically based on token lifetime.
+     * Industry standard: refresh when 25% of lifetime remains.
+     */
+    calculateRefreshMargin(token) {
+        const ttlSeconds = getTokenTimeToLive(token);
+        if (ttlSeconds === null || ttlSeconds <= 0) {
+            // Can't determine TTL, use minimum margin
+            return this.MIN_REFRESH_MARGIN_SECONDS;
         }
-        catch (error) {
-            // Don't call handleAuthFailure here - let the caller decide
-            // This prevents duplicate auth failure handling in race conditions
-            return false;
+        // Calculate 25% of remaining lifetime
+        const dynamicMargin = Math.floor(ttlSeconds * this.REFRESH_THRESHOLD_PERCENT);
+        // Clamp between min and max
+        return Math.max(this.MIN_REFRESH_MARGIN_SECONDS, Math.min(dynamicMargin, this.MAX_REFRESH_MARGIN_SECONDS));
+    }
+    /**
+     * Attempt token refresh with retry logic for transient failures.
+     * Only gives up on definitive auth errors.
+     */
+    async attemptRefreshWithRetry() {
+        let lastError;
+        for (let attempt = 1; attempt <= this.MAX_RETRY_ATTEMPTS; attempt++) {
+            try {
+                await this.authService.refreshAccessToken();
+                return { success: true, retryable: false };
+            }
+            catch (error) {
+                lastError = error instanceof Error ? error : new Error(String(error));
+                // Check if this is a definitive auth failure (non-retryable)
+                if (this.isDefinitiveAuthFailure(error)) {
+                    console.warn(`[TokenRefreshManager] Definitive auth failure: ${lastError.message}`);
+                    return { success: false, retryable: false, error: lastError };
+                }
+                // Retryable error - wait and try again
+                if (attempt < this.MAX_RETRY_ATTEMPTS) {
+                    await this.delay(this.RETRY_DELAY_MS * attempt); // Exponential backoff
+                }
+            }
         }
+        // All retries exhausted - return as retryable so we don't logout
+        console.warn(`[TokenRefreshManager] All ${this.MAX_RETRY_ATTEMPTS} refresh attempts failed`);
+        return { success: false, retryable: true, error: lastError };
+    }
+    /**
+     * Determine if an error is a definitive auth failure that requires logout.
+     * Network errors, timeouts, 5xx errors are NOT definitive - they're retryable.
+     *
+     * Delegates to AuthService.isDefinitiveAuthFailure() - the SINGLE SOURCE OF TRUTH.
+     */
+    isDefinitiveAuthFailure(error) {
+        return this.authService.isDefinitiveAuthFailure(error);
+    }
+    delay(ms) {
+        return new Promise(resolve => setTimeout(resolve, ms));
+    }
+    /**
+     * @deprecated Use ensureValidToken() instead
+     */
+    async attemptInternalRefresh() {
+        const result = await this.attemptRefreshWithRetry();
+        return result.success;
     }
 }
 
@@ -9786,6 +10057,22 @@ class AuthTokenManager {
         this.cache = {};
         await this.storage.clear();
     }
+    /**
+     * Clears only auth tokens (access, refresh, provider, authType), preserving DPoP keys.
+     * Use this when DPoP keys are regenerated - we want to invalidate auth tokens
+     * that were bound to old keys, but keep the newly generated DPoP keys.
+     */
+    async clearAuthTokens() {
+        // Clear cache
+        this.cache = {};
+        // Remove all auth tokens and auth type, NOT DPoP keys
+        await Promise.all([
+            this.storage.remove(AUTH_STORAGE_KEYS.ACCESS_TOKEN),
+            this.storage.remove(AUTH_STORAGE_KEYS.REFRESH_TOKEN),
+            this.storage.remove(AUTH_STORAGE_KEYS.PROVIDER_TOKEN),
+            this.storage.remove(AUTH_STORAGE_KEYS.AUTH_TYPE),
+        ]);
+    }
     async hasAccessToken() {
         // Use cached value if available to avoid storage read
         if (this.cache.accessToken !== undefined) {
@@ -9816,13 +10103,12 @@ class IndexedDBTokenStorage {
     constructor() {
         this.supportsObjects = true;
         this.dbPromise = null;
-        if (typeof indexedDB === 'undefined') {
-            console.warn('IndexedDB is not available in this environment');
-        }
+        // IndexedDB availability is checked lazily on first operation
     }
     getDB() {
-        if (this.dbPromise)
+        if (this.dbPromise) {
             return this.dbPromise;
+        }
         this.dbPromise = new Promise((resolve, reject) => {
             if (typeof indexedDB === 'undefined') {
                 return reject(new Error('IndexedDB not supported'));
@@ -9850,8 +10136,12 @@ class IndexedDBTokenStorage {
                 const transaction = db.transaction(IndexedDBTokenStorage.STORE_NAME, 'readonly');
                 const store = transaction.objectStore(IndexedDBTokenStorage.STORE_NAME);
                 const request = store.get(key);
-                request.onsuccess = () => resolve(request.result || null);
-                request.onerror = () => reject(request.error);
+                request.onsuccess = () => {
+                    resolve(request.result || null);
+                };
+                request.onerror = () => {
+                    reject(request.error);
+                };
             });
         }
         catch (e) {
@@ -10047,6 +10337,8 @@ class DPoPManager {
     constructor(storage, cryptoProvider, callbacks) {
         this.storage = storage;
         this.memoryKeyPair = null;
+        /** Pending key pair promise to prevent concurrent generation race conditions */
+        this.pendingKeyPair = null;
         this.cryptoProvider = cryptoProvider || new WebDPoPCryptoProvider();
         this.callbacks = callbacks || {};
     }
@@ -10055,8 +10347,9 @@ class DPoPManager {
      * Useful for detecting if a key regeneration would be needed.
      */
     async hasStoredKeys() {
-        if (this.memoryKeyPair)
+        if (this.memoryKeyPair) {
             return true;
+        }
         const storedPublic = await this.storage.get(DPOP_STORAGE_KEYS.PUBLIC);
         const storedPrivate = await this.storage.get(DPOP_STORAGE_KEYS.PRIVATE);
         return !!(storedPublic && storedPrivate);
@@ -10070,8 +10363,35 @@ class DPoPManager {
      * match refresh token binding" errors.
      */
     async ensureKeyPair() {
-        if (this.memoryKeyPair)
+        // Fast path: already have keys in memory
+        if (this.memoryKeyPair) {
+            return this.memoryKeyPair;
+        }
+        // Prevent concurrent key generation race condition:
+        // If another call is already generating keys, wait for it instead of starting a new one
+        if (this.pendingKeyPair) {
+            return this.pendingKeyPair;
+        }
+        // Create a promise that subsequent callers will wait on
+        this.pendingKeyPair = this.loadOrGenerateKeyPair();
+        try {
+            const keyPair = await this.pendingKeyPair;
+            return keyPair;
+        }
+        finally {
+            // Clear pending promise so future calls can proceed
+            this.pendingKeyPair = null;
+        }
+    }
+    /**
+     * Internal method that actually loads or generates keys.
+     * Called only once per concurrent batch of ensureKeyPair() calls.
+     */
+    async loadOrGenerateKeyPair() {
+        // Double-check in case keys were set while waiting
+        if (this.memoryKeyPair) {
             return this.memoryKeyPair;
+        }
         const storedPublic = await this.storage.get(DPOP_STORAGE_KEYS.PUBLIC);
         const storedPrivate = await this.storage.get(DPOP_STORAGE_KEYS.PRIVATE);
         if (storedPublic && storedPrivate) {
@@ -10083,18 +10403,23 @@ class DPoPManager {
                 return this.memoryKeyPair;
             }
             catch (e) {
-                console.warn('[DPoPManager] Corrupted DPoP keys in storage, regenerating.');
+                console.warn('[DPoPManager] Corrupted DPoP keys in storage, regenerating');
             }
         }
         // Generate new key pair
         // IMPORTANT: This invalidates any existing refresh tokens bound to the old keys
-        console.info('[DPoPManager] Generating new DPoP key pair');
-        // Adaptation: If storage supports raw objects (like IndexedDB or Native Keychain),
+        // Adaptation: If storage supports raw objects (like Native Keychain on iOS/Android),
         // we can generate Non-Extractable keys for maximum security.
-        // If storage is text-only (LocalStorage), we must use Extractable keys to serialize them.
+        // If storage is text-only (LocalStorage) OR IndexedDB (CryptoKey doesn't survive reload),
+        // we must use Extractable keys to serialize them as JWK.
+        // 
+        // NOTE: IndexedDB CAN store CryptoKey objects, but they don't survive page reloads -
+        // they come back as empty/corrupted objects. Only native secure storage can persist
+        // non-extractable keys. Frontend should set supportsObjects: false for web storage.
         const useHighSecurity = !!this.storage.supportsObjects;
+        const extractable = !useHighSecurity;
         const keyPair = await this.cryptoProvider.generateKeyPair({
-            extractable: !useHighSecurity
+            extractable
         });
         // Save to storage
         await this.storage.set(DPOP_STORAGE_KEYS.PUBLIC, keyPair.publicKey);
@@ -10128,6 +10453,21 @@ class DPoPManager {
         }
         return this.cryptoProvider.signProof(payload, keyPair);
     }
+    /**
+     * Generate a short fingerprint of the public key for debugging
+     * This helps identify if the same key is being used across operations
+     */
+    getPublicKeyFingerprint(publicKey) {
+        try {
+            // Use the 'x' coordinate of the EC key as a fingerprint
+            const x = publicKey.x || '';
+            const y = publicKey.y || '';
+            return `${x.substring(0, 8)}...${y.substring(0, 4)}`;
+        }
+        catch {
+            return 'unknown';
+        }
+    }
     /**
      * Clears DPoP keys (e.g. on logout)
      */
@@ -10176,13 +10516,15 @@ class DefaultAuthProvider {
         this.tokenManager = new AuthTokenManager(storage);
         if (this.dpopEnabled) {
             this.dpopManager = new DPoPManager(storage, config.dpop?.cryptoProvider, {
-                // When DPoP keys are regenerated (corrupted/missing), the refresh token
-                // bound to the old keys becomes invalid. Clear it to prevent
-                // "DPoP proof does not match refresh token binding" errors.
+                // When DPoP keys are regenerated (corrupted/missing), auth tokens
+                // bound to the old keys become invalid. Clear only auth tokens, NOT DPoP keys.
+                // Access token has cnf claim binding it to the old public key.
+                // Refresh token has DPoP binding to the old key pair.
+                // NOTE: Do NOT call clearAllTokens() here - it would wipe the freshly saved DPoP keys!
                 onKeysRegenerated: () => {
-                    console.info('[DefaultAuthProvider] DPoP keys regenerated, clearing invalid refresh token');
-                    this.tokenManager.clearRefreshToken().catch(err => {
-                        console.warn('[DefaultAuthProvider] Failed to clear refresh token:', err);
+                    // Clear only auth tokens, preserve DPoP keys (they were just regenerated and saved)
+                    this.tokenManager.clearAuthTokens().catch(err => {
+                        console.warn('[DefaultAuthProvider] Failed to clear tokens after key regeneration:', err);
                     });
                 }
             });
@@ -10324,6 +10666,41 @@ class DefaultAuthProvider {
             return null;
         }
     }
+    /**
+     * Store the provider token (Firebase JWT, Auth0 token, etc.)
+     * Used for session recovery when refresh tokens expire.
+     *
+     * NOTE: This is called AUTOMATICALLY by loginWithToken(), so you typically
+     * don't need to call this manually. The only reason to call this is if:
+     *
+     * 1. Your auth provider (Firebase, Auth0) refreshes tokens in the background
+     * 2. You want to proactively update the stored token for better recovery chances
+     *
+     * The stored provider token is used as a fallback when:
+     * - PERS refresh token expires (e.g., after 30 days of inactivity)
+     * - SDK attempts recovery using the stored provider token
+     * - If provider token is still valid → session recovered automatically
+     * - If provider token is also expired → user must re-authenticate
+     *
+     * @example
+     * // Optional: Update stored token when Firebase refreshes it
+     * firebase.auth().onIdTokenChanged(async (user) => {
+     *   if (user) {
+     *     const freshToken = await user.getIdToken();
+     *     await sdk.auth.setProviderToken(freshToken);
+     *   }
+     * });
+     */
+    async setProviderToken(token) {
+        await this.tokenManager.setProviderToken(token);
+    }
+    /**
+     * Get the stored provider token (Firebase JWT, Auth0 token, etc.)
+     * Used internally for session recovery when refresh tokens expire.
+     */
+    async getProviderToken() {
+        return this.tokenManager.getProviderToken();
+    }
 }
 
 /**
@@ -10339,7 +10716,7 @@ class DefaultAuthProvider {
 /** SDK package name */
 const SDK_NAME = "@explorins/pers-sdk";
 /** SDK version - injected from package.json at build time */
-const SDK_VERSION = "2.1.32";
+const SDK_VERSION = "2.1.33";
 /** Full SDK identifier for headers */
 const SDK_USER_AGENT = `${SDK_NAME}/${SDK_VERSION}`;
 
@@ -10488,7 +10865,9 @@ class PersApiClient {
             // Handle 401 errors centrally through AuthService
             if (status === 401) {
                 const backendError = ErrorUtils.extractBackendErrorDetails(error);
-                // Check for fatal auth errors that require immediate logout
+                // Check for FATAL auth error CODES (not just 401 status)
+                // Fatal codes: REFRESH_TOKEN_EXPIRED, TOKEN_REVOKED, etc. → immediate logout
+                // Non-fatal codes: TOKEN_EXPIRED → try refresh first
                 if (this.authService.isFatalAuthError(backendError.code)) {
                     // Definitive auth failure - no retry, session is invalid
                     await this.authService.handleAuthFailure();
@@ -16615,6 +16994,55 @@ class AnalyticsManager {
     async getCampaignClaimAnalytics(request) {
         return this.analyticsService.getCampaignClaimAnalytics(request);
     }
+    /**
+     * Get redemption redeem analytics with aggregation
+     *
+     * Retrieves aggregated redemption redeem data with flexible grouping and metrics.
+     * Perfect for charts, dashboards, and redeem pattern analysis across redemptions,
+     * businesses, and time periods.
+     *
+     * @param request - Analytics request with filters, groupBy, and metrics
+     * @returns Promise resolving to redemption redeem analytics data
+     *
+     * @example Redeems per redemption
+     * ```typescript
+     * const analytics = await sdk.analytics.getRedemptionRedeemAnalytics({
+     *   groupBy: ['redemptionId'],
+     *   metrics: ['count'],
+     *   sortBy: 'count',
+     *   sortOrder: 'DESC',
+     *   limit: 10
+     * });
+     *
+     * console.log('Top redemptions by redeems:', analytics.results);
+     * ```
+     *
+     * @example Redeems by status over time
+     * ```typescript
+     * const analytics = await sdk.analytics.getRedemptionRedeemAnalytics({
+     *   groupBy: ['month', 'status'],
+     *   metrics: ['count'],
+     *   sortBy: 'month',
+     *   sortOrder: 'DESC',
+     *   startDate: new Date('2026-01-01'),
+     *   endDate: new Date('2026-12-31')
+     * });
+     * ```
+     *
+     * @example Redeems by business
+     * ```typescript
+     * const analytics = await sdk.analytics.getRedemptionRedeemAnalytics({
+     *   filters: { status: 'COMPLETED' },
+     *   groupBy: ['businessId'],
+     *   metrics: ['count'],
+     *   sortBy: 'count',
+     *   sortOrder: 'DESC'
+     * });
+     * ```
+     */
+    async getRedemptionRedeemAnalytics(request) {
+        return this.analyticsService.getRedemptionRedeemAnalytics(request);
+    }
     /**
      * Get user analytics with engagement metrics
      *
@@ -20170,7 +20598,7 @@ const PersSDKProvider = ({ children, config }) => {
                         setIsAuthenticated(true);
                     }
                 }
-                if (event.type === 'logout_success' || event.type === 'session_restoration_failed' || event.code === 'AUTH_FAILED') {
+                if (event.type === 'logout_success' || event.type === 'session_restoration_failed') {
                     setUser(null);
                     setIsAuthenticated(false);
                 }
@@ -45797,6 +46225,7 @@ exports.DonationService = DonationService;
 exports.EntityTypes = EntityTypes;
 exports.ErrorDomains = ErrorDomains;
 exports.ErrorUtils = ErrorUtils;
+exports.FATAL_AUTH_CODES = FATAL_AUTH_CODES;
 exports.FileApi = FileApi;
 exports.FileManager = FileManager;
 exports.FileService = FileService;
@@ -45902,6 +46331,7 @@ exports.initializeReactNativePolyfills = initializeReactNativePolyfills;
 exports.isConnectedMessage = isConnectedMessage;
 exports.isErrorMessage = isErrorMessage;
 exports.isEventMessage = isEventMessage;
+exports.isFatalAuthErrorInMessage = isFatalAuthErrorInMessage;
 exports.isPaginatedResponse = isPaginatedResponse;
 exports.isPingMessage = isPingMessage;
 exports.isServerMessage = isServerMessage;