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

package/dist/index.js

@@ -3216,6 +3216,12 @@ const EntityTypes = {
     SIGNING_ACCOUNT: 'signing_account',
     API_KEY: 'api_key',
     WEBHOOK: 'webhook',
+    // Service domains
+    ANALYTICS: 'analytics',
+    CHAIN: 'chain',
+    FILE: 'file',
+    JWKS: 'jwks',
+    PROJECT: 'project',
 };
 /**
  * Error-specific domains (extends EntityTypes)
@@ -3726,6 +3732,9 @@ const CommonErrorCodes = {
     TOKEN_NOT_ACTIVE: 'TOKEN_NOT_ACTIVE',
     TOKEN_ID_REQUIRED: 'TOKEN_ID_REQUIRED',
     TOKEN_TYPE_NOT_FOUND: 'TOKEN_TYPE_NOT_FOUND',
+    TOKEN_UNIT_NOT_FOUND: 'TOKEN_UNIT_NOT_FOUND',
+    NFT_EXPIRED: 'NFT_EXPIRED',
+    NFT_BUSINESS_RESTRICTION: 'NFT_BUSINESS_RESTRICTION',
     // Wallet domain
     WALLET_MISSING_SIGNING: 'WALLET_MISSING_SIGNING',
     WALLET_NOT_FOUND: 'WALLET_NOT_FOUND',
@@ -3765,6 +3774,9 @@ const CommonErrorCodes = {
     CAMPAIGN_DAILY_LIMIT_REACHED: 'CAMPAIGN_DAILY_LIMIT_REACHED',
     CAMPAIGN_GLOBAL_LIMIT_REACHED: 'CAMPAIGN_GLOBAL_LIMIT_REACHED',
     CAMPAIGN_GLOBAL_DAILY_LIMIT_REACHED: 'CAMPAIGN_GLOBAL_DAILY_LIMIT_REACHED',
+    CAMPAIGN_NOT_FOUND: 'CAMPAIGN_NOT_FOUND',
+    GEOGRAPHIC_RESTRICTION: 'GEOGRAPHIC_RESTRICTION',
+    LOCATION_VERIFICATION_REQUIRED: 'LOCATION_VERIFICATION_REQUIRED',
     // Trigger domain
     TRIGGER_NOT_FOUND: 'TRIGGER_NOT_FOUND',
     // Trigger Source domain
@@ -3780,6 +3792,12 @@ const CommonErrorCodes = {
     EXTERNAL_SERVICE_ERROR: 'EXTERNAL_SERVICE_ERROR',
     AUTHENTICATION_REQUIRED: 'AUTHENTICATION_REQUIRED',
     AUTHORIZATION_FAILED: 'AUTHORIZATION_FAILED',
+    CONFIGURATION_MISSING: 'CONFIGURATION_MISSING',
+    // Redemption domain
+    USER_STATUS_RESTRICTED: 'USER_STATUS_RESTRICTED',
+    REDEMPTION_ALREADY_PROCESSING: 'REDEMPTION_ALREADY_PROCESSING',
+    MAX_REDEMPTION: 'MAX_REDEMPTION',
+    USER_LIMIT: 'USER_LIMIT',
     // Authentication errors
     INVALID_TOKEN: 'INVALID_TOKEN',
     TOKEN_EXPIRED: 'TOKEN_EXPIRED',
@@ -3787,6 +3805,8 @@ const CommonErrorCodes = {
     REFRESH_TOKEN_EXPIRED: 'REFRESH_TOKEN_EXPIRED',
     REFRESH_TOKEN_REVOKED: 'REFRESH_TOKEN_REVOKED',
     FIREBASE_AUTH_ERROR: 'FIREBASE_AUTH_ERROR',
+    MULTIPLE_CONTEXT_SELECTION_REQUIRED: 'MULTIPLE_CONTEXT_SELECTION_REQUIRED',
+    ADMIN_TENANT_REQUIRED: 'ADMIN_TENANT_REQUIRED',
     // Generic fallbacks
     INTERNAL_ERROR: 'INTERNAL_ERROR',
     VALIDATION_ERROR: 'VALIDATION_ERROR',
@@ -3812,26 +3832,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
@@ -3860,12 +3903,12 @@ class ErrorUtils {
             return false;
         const err = error;
         // Check for explicit token expired indicators
-        if (err?.code === 'TOKEN_EXPIRED' || err?.errorCode === 'TOKEN_EXPIRED') {
+        if (err?.code === CommonErrorCodes.TOKEN_EXPIRED || err?.errorCode === CommonErrorCodes.TOKEN_EXPIRED) {
             return true;
         }
         // Check in response data
         const apiError = err?.response?.data || err;
-        if (apiError?.code === 'TOKEN_EXPIRED' || apiError?.errorCode === 'TOKEN_EXPIRED') {
+        if (apiError?.code === CommonErrorCodes.TOKEN_EXPIRED || apiError?.errorCode === CommonErrorCodes.TOKEN_EXPIRED) {
             return true;
         }
         // Any 401 error is treated as token expiration
@@ -3935,7 +3978,9 @@ class ErrorUtils {
             // Try extraction strategies in priority order
             const candidates = [
                 this.parseHttpClientError(error), // React Native format
-                httpError.response?.data, // Axios/fetch format
+                httpError.response && typeof httpError.response === 'object'
+                    ? httpError.response.data
+                    : undefined, // Axios/fetch format
                 httpError.error, // Angular HttpErrorResponse
                 httpError // Direct error object
             ];
@@ -3954,8 +3999,9 @@ class ErrorUtils {
      * Check if object has structured error fields from backend (StructuredError)
      */
     static hasStructuredErrorFields(obj) {
-        return obj && typeof obj === 'object' &&
-            ((obj.code && obj.category) || (obj.status && (obj.detail || obj.message || obj.title)));
+        return obj !== null && typeof obj === 'object' &&
+            (('code' in obj && 'category' in obj) ||
+                ('status' in obj && ('detail' in obj || 'message' in obj || 'title' in obj)));
     }
     /**
      * Create fallback error structure when no structured error found
@@ -3966,9 +4012,9 @@ class ErrorUtils {
             title: 'Request failed',
             message: this.getMessage(error),
             detail: this.getMessage(error),
-            code: 'REQUEST_FAILED',
+            code: CommonErrorCodes.TECHNICAL_ERROR,
             category: exports.ErrorCategory.TECHNICAL,
-            domain: 'api',
+            domain: ErrorDomains.EXTERNAL,
             retryable: this.isRetryable(error)
         };
     }
@@ -4047,7 +4093,7 @@ class PersApiError extends Error {
         this.method = method;
         this.name = 'PersApiError';
         // Use backend error details directly
-        this.code = backendError?.code || 'API_ERROR';
+        this.code = backendError?.code || CommonErrorCodes.TECHNICAL_ERROR;
         this.domain = backendError?.domain || ErrorDomains.EXTERNAL;
         this.category = backendError?.category || exports.ErrorCategory.TECHNICAL;
         this.retryable = backendError?.retryable ?? (statusCode ? statusCode >= 500 : false);
@@ -4071,7 +4117,7 @@ class AuthenticationError extends PersApiError {
 class NetworkError extends Error {
     constructor(message) {
         super(message);
-        this.code = SdkErrorCodes.NETWORK_ERROR;
+        this.code = CommonErrorCodes.EXTERNAL_SERVICE_ERROR;
         this.domain = ErrorDomains.EXTERNAL;
         this.category = exports.ErrorCategory.INFRASTRUCTURE;
         this.retryable = true;
@@ -5119,6 +5165,58 @@ class TokenApi {
         }
         return this.apiClient.get(url);
     }
+    /**
+     * Get all token metadata with filtering and pagination
+     *
+     * Useful for displaying rewards (ERC1155) or stamps (ERC721) in tables.
+     * Non-admin users always get active metadata only.
+     *
+     * @param options - Filter and pagination options
+     * @returns Paginated response with token metadata
+     *
+     * @example Get all active rewards
+     * ```typescript
+     * const rewards = await tokenApi.getTokenMetadata({
+     *   tokenType: 'ERC1155',
+     *   active: true,
+     *   limit: 10
+     * });
+     * ```
+     *
+     * @example Get stamps with search
+     * ```typescript
+     * const stamps = await tokenApi.getTokenMetadata({
+     *   tokenType: 'ERC721',
+     *   search: 'gold',
+     *   sortBy: 'name',
+     *   sortOrder: 'ASC'
+     * });
+     * ```
+     */
+    async getTokenMetadata(options) {
+        const params = buildPaginationParams(options);
+        if (options?.active !== undefined) {
+            params.set('active', String(options.active));
+        }
+        if (options?.tokenType) {
+            params.set('tokenType', options.tokenType);
+        }
+        if (options?.tokenId) {
+            params.set('tokenId', options.tokenId);
+        }
+        if (options?.search) {
+            params.set('search', options.search);
+        }
+        // Handle tags as string or array
+        if (options?.tags) {
+            const tagsArray = Array.isArray(options.tags) ? options.tags : [options.tags];
+            if (tagsArray.length > 0) {
+                params.set('tags', tagsArray.join(','));
+            }
+        }
+        const response = await this.apiClient.get(`${this.basePath}/metadata?${params.toString()}`);
+        return normalizeToPaginated(response);
+    }
     // ==========================================
     // ADMIN OPERATIONS
     // ==========================================
@@ -5228,6 +5326,40 @@ class TokenService {
     async getTokenByContractAddress(contractAddress, contractTokenId) {
         return this.tokenApi.getTokenByContractAddress(contractAddress, contractTokenId);
     }
+    /**
+     * Get all token metadata with filtering and pagination
+     *
+     * Useful for displaying rewards (ERC1155) or stamps (ERC721) in tables.
+     * Non-admin users always get active metadata only.
+     *
+     * @param options - Filter and pagination options
+     * @returns Paginated response with token metadata
+     */
+    async getTokenMetadata(options) {
+        return this.tokenApi.getTokenMetadata(options);
+    }
+    /**
+     * Get rewards (ERC1155 token metadata) with filtering and pagination
+     *
+     * Convenience method for fetching reward metadata.
+     *
+     * @param options - Filter and pagination options (tokenType is set automatically)
+     * @returns Paginated response with reward metadata
+     */
+    async getRewards(options) {
+        return this.tokenApi.getTokenMetadata({ ...options, tokenType: NativeTokenTypes.ERC1155 });
+    }
+    /**
+     * Get stamps (ERC721 token metadata) with filtering and pagination
+     *
+     * Convenience method for fetching stamp metadata.
+     *
+     * @param options - Filter and pagination options (tokenType is set automatically)
+     * @returns Paginated response with stamp metadata
+     */
+    async getStamps(options) {
+        return this.tokenApi.getTokenMetadata({ ...options, tokenType: NativeTokenTypes.ERC721 });
+    }
     // ==========================================
     // ADMIN OPERATIONS
     // ==========================================
@@ -5354,7 +5486,7 @@ class BusinessApi {
     /**
      * Get all businesses with role-based filtering and pagination
      *
-     * Endpoint: GET /businesses?active={boolean}&sanitize={mode}&page={number}&limit={number}
+     * Endpoint: GET /businesses?active={boolean}&sanitize={mode}&page={number}&limit={number}&businessTypeId={number}
      * Auth: @ApiSecurity('projectKey') (enhanced with role-based filtering)
      *
      * Note:
@@ -5377,8 +5509,11 @@ class BusinessApi {
      * });
      *
      * // Filter by tag(s)
-     * const tagged = await businessApi.getBusinesses({ tag: 'restaurant' });
-     * const multiTag = await businessApi.getBusinesses({ tag: ['restaurant', 'cafe'] });
+     * const tagged = await businessApi.getBusinesses({ tags: 'restaurant' });
+     * const multiTag = await businessApi.getBusinesses({ tags: ['restaurant', 'cafe'] });
+     *
+     * // Filter by business type
+     * const hotels = await businessApi.getBusinesses({ businessTypeId: 1 });
      * ```
      */
     async getBusinesses(options) {
@@ -5398,6 +5533,9 @@ class BusinessApi {
         if (options?.sanitize) {
             params.set('sanitize', options.sanitize);
         }
+        if (options?.businessTypeId !== undefined) {
+            params.set('businessTypeId', String(options.businessTypeId));
+        }
         const response = await this.apiClient.get(`${this.basePath}?${params.toString()}`);
         return normalizeToPaginated(response);
     }
@@ -5744,20 +5882,16 @@ class BusinessService {
         return this.businessApi.getBusinessByAccount(accountAddress);
     }
     /**
-     * Get businesses by type (client-side filtering)
-     * @deprecated Consider implementing server-side filtering for better performance
+     * Get businesses by type (server-side filtering)
+     * Uses the businessTypeId parameter for efficient server-side filtering.
      */
     async getBusinessesByType(typeId, options) {
-        const response = await this.getActiveBusinesses(options);
-        const filtered = response.data.filter((business) => business.businessType && business.businessType.id === parseInt(typeId));
-        return {
-            data: filtered,
-            pagination: {
-                ...response.pagination,
-                total: filtered.length,
-                pages: Math.ceil(filtered.length / (response.pagination.limit || 20))
-            }
-        };
+        const businessTypeId = parseInt(typeId, 10);
+        return this.businessApi.getBusinesses({
+            ...options,
+            businessTypeId,
+            active: options?.active ?? true // Default to active businesses
+        });
     }
     // ==========================================
     // ADMIN OPERATIONS
@@ -6996,6 +7130,14 @@ class RedemptionService {
     async getRedemptions(options) {
         return this.redemptionApi.getRedemptions(options);
     }
+    /**
+     * Get a specific redemption by ID
+     * @param id - Redemption UUID
+     * @param include - Optional relations to include: 'redeemCount'
+     */
+    async getRedemptionById(id, include) {
+        return this.redemptionApi.getRedemptionById(id, include);
+    }
     /**
      * Convenience: Get active redemptions (public)
      */
@@ -8635,6 +8777,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 +9051,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 +9517,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 +9526,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 +9688,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
@@ -9502,7 +9755,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 +9763,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 exports.AccountOwnerType.USER:
+                    await this.loginUser(providerToken);
+                    break;
+                case exports.AccountOwnerType.BUSINESS:
+                    // For BUSINESS auth, sub contains the businessId when accountType is BUSINESS
+                    const businessId = contextClaims?.accountType === exports.AccountOwnerType.BUSINESS
+                        ? contextClaims.sub
+                        : undefined;
+                    await this.loginBusiness(providerToken, businessId ? { 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 +9913,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 +9950,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 +10186,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 +10232,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 +10265,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 +10466,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 +10476,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 +10492,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 +10532,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 +10582,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)
      */
@@ -10176,13 +10644,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 +10794,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 +10844,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.37";
 /** Full SDK identifier for headers */
 const SDK_USER_AGENT = `${SDK_NAME}/${SDK_VERSION}`;
 
@@ -10488,7 +10993,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();
@@ -10548,9 +11055,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,
@@ -12186,6 +12693,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
      *
@@ -14090,6 +14698,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
      *
@@ -16615,6 +17269,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 +20873,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);
                 }
@@ -20729,6 +21432,99 @@ const useTokens = () => {
             throw error;
         }
     }, [sdk, isInitialized]);
+    /**
+     * Get all token metadata with filtering and pagination
+     *
+     * Retrieves token metadata (rewards/stamps) with server-side filtering.
+     * Use tokenType: 'ERC1155' for rewards, 'ERC721' for stamps.
+     *
+     * @param options - Filter and pagination options
+     * @returns Promise resolving to paginated token metadata
+     * @throws Error if SDK is not initialized
+     *
+     * @example
+     * ```typescript
+     * const { getTokenMetadata } = useTokens();
+     * const rewards = await getTokenMetadata({
+     *   tokenType: 'ERC1155',
+     *   active: true,
+     *   limit: 10
+     * });
+     * ```
+     */
+    const getTokenMetadata = react.useCallback(async (options) => {
+        if (!isInitialized || !sdk) {
+            throw new Error('SDK not initialized. Call initialize() first.');
+        }
+        try {
+            const result = await sdk.tokens.getTokenMetadata(options);
+            return result;
+        }
+        catch (error) {
+            console.error('Failed to fetch token metadata:', error);
+            throw error;
+        }
+    }, [sdk, isInitialized]);
+    /**
+     * 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
+     * @returns Promise resolving to paginated reward metadata
+     * @throws Error if SDK is not initialized
+     *
+     * @example
+     * ```typescript
+     * const { getRewards } = useTokens();
+     * const rewards = await getRewards({ active: true, limit: 10 });
+     * console.log(`Found ${rewards.pagination.total} rewards`);
+     * ```
+     */
+    const getRewards = react.useCallback(async (options) => {
+        if (!isInitialized || !sdk) {
+            throw new Error('SDK not initialized. Call initialize() first.');
+        }
+        try {
+            const result = await sdk.tokens.getRewards(options);
+            return result;
+        }
+        catch (error) {
+            console.error('Failed to fetch rewards:', error);
+            throw error;
+        }
+    }, [sdk, isInitialized]);
+    /**
+     * 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
+     * @returns Promise resolving to paginated stamp metadata
+     * @throws Error if SDK is not initialized
+     *
+     * @example
+     * ```typescript
+     * const { getStamps } = useTokens();
+     * const stamps = await getStamps({ active: true, limit: 10 });
+     * console.log(`Found ${stamps.pagination.total} stamps`);
+     * ```
+     */
+    const getStamps = react.useCallback(async (options) => {
+        if (!isInitialized || !sdk) {
+            throw new Error('SDK not initialized. Call initialize() first.');
+        }
+        try {
+            const result = await sdk.tokens.getStamps(options);
+            return result;
+        }
+        catch (error) {
+            console.error('Failed to fetch stamps:', error);
+            throw error;
+        }
+    }, [sdk, isInitialized]);
     return {
         getTokens,
         getActiveCreditToken,
@@ -20736,6 +21532,9 @@ const useTokens = () => {
         getTokenTypes,
         getStatusTokens,
         getTokenByContract,
+        getTokenMetadata,
+        getRewards,
+        getStamps,
         isAvailable: isInitialized && !!sdk?.tokens,
     };
 };
@@ -43972,6 +44771,25 @@ const useRedemptions = () => {
     /**
      * Redeem a redemption offer with optional dynamic context
      *
+     * ## When to use `redeem()` vs `createTransaction()`
+     *
+     * | Use Case | Method | Auto-Signs |
+     * |----------|--------|------------|
+     * | **Voucher redemption** | `redeem()` | ✅ Yes |
+     * | **Reward redemption** | `redeem()` | ✅ Yes |
+     * | **Direct token transfer** | `createTransaction()` | ⚠️ Depends |
+     * | **POS burn with QR** | `buildPOSBurnRequest()` | ❌ Manual |
+     *
+     * **Use `redeem()` for voucher/reward redemptions.** It automatically:
+     * 1. Creates redemption record
+     * 2. Triggers passkey/biometric prompt
+     * 3. Signs the transaction
+     * 4. Submits to blockchain
+     * 5. Returns result with `transactionHash`
+     *
+     * **No admin approval required** - The "PENDING" state is brief (seconds).
+     * The user's passkey signature IS the approval.
+     *
      * Supports dynamic context for personalized NFT generation when the redemption
      * issues ERC721 tokens. Context can include validity dates, AI prompt placeholders,
      * and custom metadata.
@@ -43980,11 +44798,21 @@ const useRedemptions = () => {
      * @param options - Optional settings
      * @param options.context - Dynamic context for NFT personalization (validity dates, AI prompts)
      * @param options.onStatusUpdate - Callback for transaction signing status updates
-     * @returns Promise resolving to redemption result
+     * @returns Promise resolving to redemption result with `transactionHash` on success
      *
-     * @example Basic redemption
+     * @example Basic redemption (most common)
      * ```typescript
-     * const result = await redeem('redemption-123');
+     * const { redeem } = useRedemptions();
+     *
+     * const result = await redeem('redemption-123', {
+     *   onStatusUpdate: (status, message) => {
+     *     console.log(`Status: ${status} - ${message}`);
+     *   }
+     * });
+     *
+     * if (result.transactionHash) {
+     *   console.log('Redemption complete!', result.transactionHash);
+     * }
      * ```
      *
      * @example Redemption with dynamic context (personalized NFT)
@@ -44015,6 +44843,8 @@ const useRedemptions = () => {
      *   }
      * });
      * ```
+     *
+     * @see {@link useTransactions.createTransaction | createTransaction()} for direct transfers without redemption flow
      */
     const redeem = react.useCallback(async (redemptionId, options) => {
         if (!isInitialized || !sdk) {
@@ -44164,8 +44994,43 @@ const useRedemptions = () => {
             throw error;
         }
     }, [sdk, isInitialized]);
+    /**
+     * Get a specific redemption by ID
+     *
+     * Retrieves detailed information about a specific redemption offer.
+     *
+     * @param id - Redemption UUID
+     * @param include - Optional relations to include: 'redeemCount'
+     * @returns Promise resolving to the redemption
+     *
+     * @example Basic usage
+     * ```typescript
+     * const redemption = await getRedemptionById('7baf4d39-0bd6-45ca-9c66-8c0d655767c3');
+     * console.log(redemption.name);
+     * ```
+     *
+     * @example With redeem count
+     * ```typescript
+     * const redemption = await getRedemptionById('redemption-123', ['redeemCount']);
+     * console.log(`${redemption.name} has been redeemed ${redemption.redeemCount} times`);
+     * ```
+     */
+    const getRedemptionById = react.useCallback(async (id, include) => {
+        if (!isInitialized || !sdk) {
+            throw new Error('SDK not initialized. Call initialize() first.');
+        }
+        try {
+            const result = await sdk.redemptions.getRedemptionById(id, include);
+            return result;
+        }
+        catch (error) {
+            console.error('Failed to fetch redemption by ID:', error);
+            throw error;
+        }
+    }, [sdk, isInitialized]);
     return {
         getRedemptions,
+        getRedemptionById,
         getUserRedemptions,
         redeem,
         getRedemptionTypes,
@@ -45797,6 +46662,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 +46768,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;