@explorins/pers-sdk 2.1.33-alpha.0 → 2.1.37

package/dist/chunks/{pers-sdk-CEAAI2U0.cjs → pers-sdk-DemghJ3a.cjs}

@@ -1,18 +1,18 @@
 'use strict';
 
 var persShared = require('@explorins/pers-shared');
-var index = require('./index-CVuttuU8.cjs');
+var index = require('./index-C4K-jkRO.cjs');
 var user = require('../user.cjs');
 var userStatus = require('../user-status.cjs');
-var tokenService = require('./token-service-C1xe11OX.cjs');
-var businessMembershipService = require('./business-membership-service-DXLG5fP9.cjs');
+var tokenService = require('./token-service-BJqu5Xap.cjs');
+var businessMembershipService = require('./business-membership-service-B9ItWZ2_.cjs');
 var campaign = require('../campaign.cjs');
-var redemptionService = require('./redemption-service-CVD2PzBO.cjs');
+var redemptionService = require('./redemption-service-Dc_0Kzd0.cjs');
 var transactionRequest_builder = require('./transaction-request.builder-D8pIzjYD.cjs');
 var paymentService = require('./payment-service-Bkw7ZXev.cjs');
-var tenantManager = require('./tenant-manager-BdJYwIgL.cjs');
+var tenantManager = require('./tenant-manager-DR5eSEJw.cjs');
 var paginationUtils = require('./pagination-utils-B2jRHMSO.cjs');
-var analyticsService = require('./analytics-service-CF9AsMQH.cjs');
+var analyticsService = require('./analytics-service-CRs9cpkg.cjs');
 var donation = require('../donation.cjs');
 var triggerSource = require('../trigger-source.cjs');
 
@@ -239,6 +239,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',
@@ -246,6 +248,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
@@ -401,8 +410,58 @@ 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)
+     *
+     * Returns false for (retryable/recoverable):
+     * - Network errors
+     * - Timeouts
+     * - 5xx server errors
+     * - TOKEN_EXPIRED (normal refresh trigger)
+     * - Raw 401/403 without fatal code (should try refresh first)
+     *
+     * NOTE: We intentionally DO NOT treat raw 401/403 status as fatal.
+     * The HTTP client handles 401 by attempting token refresh first.
+     * Only if refresh fails WITH a fatal code do we logout.
+     */
+    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;
+        }
+        // NOTE: We intentionally DO NOT check HTTP status codes here.
+        // A raw 401/403 without a fatal error code should trigger a refresh attempt,
+        // not an immediate logout. The HTTP client (pers-api-client.ts) handles this:
+        // 1. 401 received → try refresh token
+        // 2. Refresh succeeds → retry original request
+        // 3. Refresh fails with fatal CODE → then logout
+        // 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
@@ -418,7 +477,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;
         }
@@ -426,6 +485,77 @@ 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 (index.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 ? index.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
+            // Note: In AuthJWTPayload, when accountType=BUSINESS, sub contains the businessId
+            switch (authType) {
+                case persShared.AccountOwnerType.USER:
+                    await this.loginUser(providerToken);
+                    break;
+                case persShared.AccountOwnerType.BUSINESS:
+                    // For BUSINESS auth, sub contains the businessId when accountType is BUSINESS
+                    const businessId = contextClaims?.accountType === persShared.AccountOwnerType.BUSINESS
+                        ? contextClaims.sub
+                        : undefined;
+                    await this.loginBusiness(providerToken, businessId ? { businessId } : undefined);
+                    break;
+                case persShared.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
      */
@@ -505,16 +635,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)
@@ -526,35 +672,95 @@ class TokenRefreshManager {
             if (!token) {
                 return;
             }
-            if (index.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 (index.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 = index.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;
     }
 }
 
@@ -702,6 +908,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) {
@@ -732,13 +954,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'));
@@ -766,8 +987,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) {
@@ -963,6 +1188,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 || {};
     }
@@ -971,8 +1198,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);
@@ -986,8 +1214,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) {
@@ -999,18 +1254,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);
@@ -1044,6 +1304,20 @@ 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
+     */
+    /* private getPublicKeyFingerprint(publicKey: JsonWebKey): string {
+      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)
      */
@@ -1092,13 +1366,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);
                     });
                 }
             });
@@ -1240,6 +1516,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();
+    }
 }
 
 /**
@@ -1255,7 +1566,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.33-alpha.0";
+const SDK_VERSION = "2.1.37";
 /** Full SDK identifier for headers */
 const SDK_USER_AGENT = `${SDK_NAME}/${SDK_VERSION}`;
 
@@ -1404,7 +1715,9 @@ class PersApiClient {
             // Handle 401 errors centrally through AuthService
             if (status === 401) {
                 const backendError = index.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();
@@ -1464,9 +1777,9 @@ class PersApiClient {
         }); */
         this._events?.emitError({
             domain: errorDetails.domain || 'external',
-            type: errorDetails.code || 'API_ERROR',
-            userMessage: errorDetails.message || errorMessage, // Event system uses userMessage for display
-            code: errorDetails.code,
+            type: 'api_error', // Event type discriminator (fixed value)
+            userMessage: errorDetails.message || errorMessage,
+            code: errorDetails.code, // Actual error code from backend
             details: {
                 endpoint,
                 method,
@@ -3102,6 +3415,107 @@ class TokenManager {
     async getTokenByContract(contractAddress, contractTokenId = null) {
         return this.tokenService.getTokenByContractAddress(contractAddress, contractTokenId);
     }
+    /**
+     * Get all token metadata with filtering and pagination
+     *
+     * Retrieves token metadata (rewards/stamps) with server-side filtering and pagination.
+     * Useful for displaying rewards (ERC1155) or stamps (ERC721) in admin tables.
+     * Non-admin users always get active metadata only.
+     *
+     * @param options - Filter and pagination options
+     * @returns Promise resolving to paginated token metadata
+     *
+     * @example Get paginated rewards
+     * ```typescript
+     * const rewards = await sdk.tokens.getTokenMetadata({
+     *   tokenType: 'ERC1155',
+     *   active: true,
+     *   page: 1,
+     *   limit: 10,
+     *   sortBy: 'name',
+     *   sortOrder: 'ASC'
+     * });
+     *
+     * console.log(`Page 1 of ${rewards.pagination.pages}`);
+     * rewards.data.forEach(r => console.log(r.name));
+     * ```
+     *
+     * @example Get stamps with search
+     * ```typescript
+     * const stamps = await sdk.tokens.getTokenMetadata({
+     *   tokenType: 'ERC721',
+     *   search: 'gold',
+     *   limit: 25
+     * });
+     * ```
+     */
+    async getTokenMetadata(options) {
+        return this.tokenService.getTokenMetadata(options);
+    }
+    /**
+     * Get rewards (ERC1155 token metadata) with filtering and pagination
+     *
+     * Convenience method for fetching reward metadata. Rewards are ERC1155 tokens
+     * that represent collectible items, vouchers, or other redeemable rewards.
+     *
+     * @param options - Filter and pagination options (tokenType is set automatically)
+     * @returns Promise resolving to paginated reward metadata
+     *
+     * @example Get active rewards
+     * ```typescript
+     * const rewards = await sdk.tokens.getRewards({
+     *   active: true,
+     *   limit: 10
+     * });
+     *
+     * console.log(`Found ${rewards.pagination.total} rewards`);
+     * rewards.data.forEach(r => console.log(`${r.name}: ${r.description}`));
+     * ```
+     *
+     * @example Search rewards
+     * ```typescript
+     * const discountRewards = await sdk.tokens.getRewards({
+     *   search: 'discount',
+     *   sortBy: 'name',
+     *   sortOrder: 'ASC'
+     * });
+     * ```
+     */
+    async getRewards(options) {
+        return this.tokenService.getRewards(options);
+    }
+    /**
+     * Get stamps (ERC721 token metadata) with filtering and pagination
+     *
+     * Convenience method for fetching stamp metadata. Stamps are ERC721 tokens
+     * that represent achievements, badges, or collectible status markers.
+     *
+     * @param options - Filter and pagination options (tokenType is set automatically)
+     * @returns Promise resolving to paginated stamp metadata
+     *
+     * @example Get active stamps
+     * ```typescript
+     * const stamps = await sdk.tokens.getStamps({
+     *   active: true,
+     *   limit: 10
+     * });
+     *
+     * console.log(`Found ${stamps.pagination.total} stamps`);
+     * stamps.data.forEach(s => console.log(`${s.name}: ${s.description}`));
+     * ```
+     *
+     * @example Filter stamps by tags
+     * ```typescript
+     * const goldStamps = await sdk.tokens.getStamps({
+     *   tags: ['gold', 'premium'],
+     *   sortBy: 'createdAt',
+     *   sortOrder: 'DESC'
+     * });
+     * ```
+     */
+    async getStamps(options) {
+        return this.tokenService.getStamps(options);
+    }
     /**
      * Admin: Create new token
      *
@@ -5006,6 +5420,52 @@ class RedemptionManager {
     async getRedemptions(options) {
         return this.redemptionService.getRedemptions(options);
     }
+    /**
+     * Get a specific redemption by ID
+     *
+     * Retrieves detailed information about a specific redemption offer.
+     * Useful when you already have the redemption ID and need full details.
+     *
+     * @param id - Redemption UUID
+     * @param include - Optional relations to include: 'redeemCount'
+     * @returns Promise resolving to the redemption
+     *
+     * @example Basic usage
+     * ```typescript
+     * const redemption = await sdk.redemptions.getRedemptionById('7baf4d39-0bd6-45ca-9c66-8c0d655767c3');
+     * console.log(redemption.name);
+     * console.log(redemption.description);
+     * ```
+     *
+     * @example With redeem count
+     * ```typescript
+     * const redemption = await sdk.redemptions.getRedemptionById(
+     *   'redemption-123',
+     *   ['redeemCount']
+     * );
+     * console.log(`${redemption.name} has been redeemed ${redemption.redeemCount} times`);
+     * ```
+     *
+     * @example Get redemption details for display
+     * ```typescript
+     * const redemption = await sdk.redemptions.getRedemptionById(id);
+     *
+     * console.log('Redemption Details:');
+     * console.log(`Name: ${redemption.name}`);
+     * console.log(`Description: ${redemption.description}`);
+     * console.log(`Active: ${redemption.isActive}`);
+     *
+     * if (redemption.tokenUnits?.length) {
+     *   console.log('Cost:');
+     *   redemption.tokenUnits.forEach(unit => {
+     *     console.log(`  ${unit.amount} ${unit.token.symbol}`);
+     *   });
+     * }
+     * ```
+     */
+    async getRedemptionById(id, include) {
+        return this.redemptionService.getRedemptionById(id, include);
+    }
     /**
      * Get available redemption types
      *
@@ -7531,6 +7991,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
      *
@@ -10327,6 +10836,7 @@ exports.DPOP_STORAGE_KEYS = DPOP_STORAGE_KEYS;
 exports.DPoPManager = DPoPManager;
 exports.DefaultAuthProvider = DefaultAuthProvider;
 exports.DonationManager = DonationManager;
+exports.FATAL_AUTH_CODES = FATAL_AUTH_CODES;
 exports.FileApi = FileApi;
 exports.FileManager = FileManager;
 exports.FileService = FileService;
@@ -10357,5 +10867,6 @@ exports.buildApiRoot = buildApiRoot;
 exports.buildWalletEventsWsUrl = buildWalletEventsWsUrl;
 exports.createPersEventsClient = createPersEventsClient;
 exports.createPersSDK = createPersSDK;
+exports.isFatalAuthErrorInMessage = isFatalAuthErrorInMessage;
 exports.mergeWithDefaults = mergeWithDefaults;
-//# sourceMappingURL=pers-sdk-CEAAI2U0.cjs.map
+//# sourceMappingURL=pers-sdk-DemghJ3a.cjs.map