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

package/dist/chunks/{pers-sdk-DAllRtm3.js → pers-sdk-Dds2lB27.js}

@@ -1,16 +1,16 @@
 import { AccountOwnerType, MembershipRole, WebhookMethod, WebhookExecutionStatus } from '@explorins/pers-shared';
-import { i as isTokenExpired, E as ErrorUtils, A as AuthenticationError, b as PersApiError } from './index-8y63MFOX.js';
+import { i as isTokenExpired, d as decodeJwtPayload, e as getTokenTimeToLive, E as ErrorUtils, A as AuthenticationError, b as PersApiError } from './index--OssIds0.js';
 import { UserService, UserApi } from '../user.js';
 import { createUserStatusSDK } from '../user-status.js';
-import { a as TokenService, T as TokenApi } from './token-service-BxEO5YVN.js';
-import { B as BusinessApi, b as BusinessService, a as BusinessMembershipApi, c as BusinessMembershipService } from './business-membership-service-IyY5CkL0.js';
+import { a as TokenService, T as TokenApi } from './token-service-qRSYG9uT.js';
+import { B as BusinessApi, b as BusinessService, a as BusinessMembershipApi, c as BusinessMembershipService } from './business-membership-service-CPcE-AW0.js';
 import { CampaignService, CampaignApi } from '../campaign.js';
-import { a as RedemptionService, R as RedemptionApi } from './redemption-service-czBfCP-3.js';
+import { a as RedemptionService, R as RedemptionApi } from './redemption-service-DWhZgrZT.js';
 import { a as TransactionService, T as TransactionApi } from './transaction-request.builder-BZ6Uq6Qe.js';
 import { a as PaymentService, P as PurchaseApi } from './payment-service-IvM6rryM.js';
-import { T as TenantManager } from './tenant-manager-D9ihQLhf.js';
+import { T as TenantManager } from './tenant-manager-xmYKBFGu.js';
 import { b as buildPaginationParams, n as normalizeToPaginated } from './pagination-utils-9vQ-Npkr.js';
-import { a as AnalyticsService, A as AnalyticsApi } from './analytics-service-vm7B7LhS.js';
+import { a as AnalyticsService, A as AnalyticsApi } from './analytics-service-CF7hSwhy.js';
 import { DonationService, DonationApi } from '../donation.js';
 import { TriggerSourceService, TriggerSourceApi } from '../trigger-source.js';
 
@@ -237,6 +237,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',
@@ -244,6 +246,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
@@ -399,8 +408,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
@@ -416,7 +475,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;
         }
@@ -424,6 +483,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 (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
+            // Note: In AuthJWTPayload, when accountType=BUSINESS, sub contains the businessId
+            switch (authType) {
+                case AccountOwnerType.USER:
+                    await this.loginUser(providerToken);
+                    break;
+                case AccountOwnerType.BUSINESS:
+                    // For BUSINESS auth, sub contains the businessId when accountType is BUSINESS
+                    const businessId = contextClaims?.accountType === AccountOwnerType.BUSINESS
+                        ? contextClaims.sub
+                        : undefined;
+                    await this.loginBusiness(providerToken, businessId ? { businessId } : undefined);
+                    break;
+                case 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
      */
@@ -503,16 +633,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)
@@ -524,35 +670,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;
     }
 }
 
@@ -700,6 +906,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) {
@@ -730,13 +952,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'));
@@ -764,8 +985,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) {
@@ -961,6 +1186,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 || {};
     }
@@ -969,8 +1196,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);
@@ -984,8 +1212,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) {
@@ -997,18 +1252,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);
@@ -1042,6 +1302,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)
      */
@@ -1090,13 +1364,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);
                     });
                 }
             });
@@ -1238,6 +1514,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();
+    }
 }
 
 /**
@@ -1253,7 +1564,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}`;
 
@@ -1402,7 +1713,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();
@@ -1462,9 +1775,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,
@@ -3100,6 +3413,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
      *
@@ -5004,6 +5418,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
      *
@@ -7529,6 +7989,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
      *
@@ -10310,5 +10819,5 @@ function createPersSDK(httpClient, config) {
     return new PersSDK(httpClient, config);
 }
 
-export { AuthStatus as A, BusinessManager as B, CampaignManager as C, DefaultAuthProvider as D, FileApi as E, FileManager as F, FileService as G, ApiKeyApi as H, IndexedDBTokenStorage as I, WebhookApi as J, WebhookService as K, LocalStorageTokenStorage as L, MemoryTokenStorage as M, PersEventsClient as N, createPersEventsClient as O, PersSDK as P, RedemptionManager as R, SDK_NAME as S, TokenManager as T, UserManager as U, WebDPoPCryptoProvider as W, AuthTokenManager as a, AUTH_STORAGE_KEYS as b, createPersSDK as c, DPOP_STORAGE_KEYS as d, SDK_VERSION as e, SDK_USER_AGENT as f, PersApiClient as g, DEFAULT_PERS_CONFIG as h, buildApiRoot as i, buildWalletEventsWsUrl as j, StaticJwtAuthProvider as k, AuthApi as l, mergeWithDefaults as m, AuthService as n, DPoPManager as o, PersEventEmitter as p, AuthManager as q, UserStatusManager as r, TransactionManager as s, PurchaseManager as t, ApiKeyManager as u, AnalyticsManager as v, DonationManager as w, TriggerSourceManager as x, WebhookManager as y, WalletEventsManager as z };
-//# sourceMappingURL=pers-sdk-DAllRtm3.js.map
+export { AuthStatus as A, BusinessManager as B, CampaignManager as C, DefaultAuthProvider as D, WebhookManager as E, FATAL_AUTH_CODES as F, WalletEventsManager as G, FileApi as H, IndexedDBTokenStorage as I, FileService as J, ApiKeyApi as K, LocalStorageTokenStorage as L, MemoryTokenStorage as M, WebhookApi as N, WebhookService as O, PersSDK as P, PersEventsClient as Q, RedemptionManager as R, SDK_NAME as S, TokenManager as T, UserManager as U, createPersEventsClient as V, WebDPoPCryptoProvider as W, AuthTokenManager as a, AUTH_STORAGE_KEYS as b, createPersSDK as c, DPOP_STORAGE_KEYS as d, SDK_VERSION as e, SDK_USER_AGENT as f, PersApiClient as g, DEFAULT_PERS_CONFIG as h, buildApiRoot as i, buildWalletEventsWsUrl as j, StaticJwtAuthProvider as k, AuthApi as l, mergeWithDefaults as m, isFatalAuthErrorInMessage as n, AuthService as o, DPoPManager as p, PersEventEmitter as q, AuthManager as r, UserStatusManager as s, TransactionManager as t, PurchaseManager as u, FileManager as v, ApiKeyManager as w, AnalyticsManager as x, DonationManager as y, TriggerSourceManager as z };
+//# sourceMappingURL=pers-sdk-Dds2lB27.js.map