@explorins/pers-sdk 2.1.33 → 2.1.39

package/dist/chunks/{pers-sdk-DgsYyo1X.cjs → pers-sdk-Cwlrl8jb.cjs}

@@ -1,16 +1,16 @@
 'use strict';
 
 var persShared = require('@explorins/pers-shared');
-var index = require('./index-B_n8XiMt.cjs');
+var index = require('./index-C4K-jkRO.cjs');
 var user = require('../user.cjs');
 var userStatus = require('../user-status.cjs');
-var tokenService = require('./token-service-C1xe11OX.cjs');
-var businessMembershipService = require('./business-membership-service-DXLG5fP9.cjs');
+var tokenService = require('./token-service-CnnrCOsg.cjs');
+var businessMembershipService = require('./business-membership-service-Dkb780NX.cjs');
 var campaign = require('../campaign.cjs');
-var redemptionService = require('./redemption-service-CVD2PzBO.cjs');
+var redemptionService = require('./redemption-service-KamEndzB.cjs');
 var transactionRequest_builder = require('./transaction-request.builder-D8pIzjYD.cjs');
 var paymentService = require('./payment-service-Bkw7ZXev.cjs');
-var tenantManager = require('./tenant-manager-DeEuSlk7.cjs');
+var tenantManager = require('./tenant-manager-DR5eSEJw.cjs');
 var paginationUtils = require('./pagination-utils-B2jRHMSO.cjs');
 var analyticsService = require('./analytics-service-CRs9cpkg.cjs');
 var donation = require('../donation.cjs');
@@ -416,13 +416,17 @@ class AuthService {
      * Returns true for:
      * - Known fatal error codes (REFRESH_TOKEN_EXPIRED, TOKEN_REVOKED, etc.)
      * - Fatal error codes in error messages (wrapped errors)
-     * - 401/403 HTTP status codes
      *
-     * Returns false for (retryable errors):
+     * 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)
@@ -437,11 +441,12 @@ class AuthService {
         if (isFatalAuthErrorInMessage(errorMessage)) {
             return true;
         }
-        // Check HTTP status if available
-        const status = errorAny?.status || errorAny?.response?.status;
-        if (status === 401 || status === 403) {
-            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;
     }
@@ -499,6 +504,9 @@ class AuthService {
      * Extracts context (tenantId/businessId) from the current refresh token to ensure
      * the recovered session maintains the same context.
      *
+     * This is a PUBLIC method that can be called by TokenRefreshManager when internal
+     * refresh fails, to try external (provider token) recovery before giving up.
+     *
      * @returns true if session was successfully recovered
      */
     async attemptProviderTokenRecovery() {
@@ -525,12 +533,17 @@ class AuthService {
             const contextClaims = refreshToken ? index.decodeJwtPayload(refreshToken) : null;
             // Re-authenticate using provider token based on auth type
             // Pass the context from the previous session to avoid MULTIPLE_CONTEXT_SELECTION_REQUIRED
+            // Note: In AuthJWTPayload, when accountType=BUSINESS, sub contains the businessId
             switch (authType) {
                 case persShared.AccountOwnerType.USER:
                     await this.loginUser(providerToken);
                     break;
                 case persShared.AccountOwnerType.BUSINESS:
-                    await this.loginBusiness(providerToken, contextClaims?.businessId ? { businessId: contextClaims.businessId } : undefined);
+                    // For BUSINESS auth, sub contains the businessId when accountType is BUSINESS
+                    const businessId = contextClaims?.accountType === persShared.AccountOwnerType.BUSINESS
+                        ? contextClaims.sub
+                        : undefined;
+                    await this.loginBusiness(providerToken, businessId ? { businessId } : undefined);
                     break;
                 case persShared.AccountOwnerType.TENANT:
                     await this.loginTenantAdmin(providerToken, contextClaims?.tenantId ? { tenantId: contextClaims.tenantId } : undefined);
@@ -646,6 +659,8 @@ class TokenRefreshManager {
         // Retry configuration for transient failures
         this.MAX_RETRY_ATTEMPTS = 3;
         this.RETRY_DELAY_MS = 1000;
+        // Active refresh promise for deduplication
+        this.activeRefreshPromise = null;
     }
     /**
      * Ensures the access token is valid, refreshing if needed.
@@ -746,11 +761,27 @@ class TokenRefreshManager {
         return new Promise(resolve => setTimeout(resolve, ms));
     }
     /**
-     * @deprecated Use ensureValidToken() instead
+     * Attempt token refresh: internal first, then provider token fallback.
+     * DEDUPLICATES concurrent calls - all callers share the same promise.
      */
     async attemptInternalRefresh() {
-        const result = await this.attemptRefreshWithRetry();
-        return result.success;
+        if (this.activeRefreshPromise) {
+            return this.activeRefreshPromise;
+        }
+        this.activeRefreshPromise = (async () => {
+            const result = await this.attemptRefreshWithRetry();
+            if (result.success)
+                return result;
+            // Internal failed - try provider token recovery
+            const recovered = await this.authService.attemptProviderTokenRecovery();
+            return recovered ? { success: true, retryable: false } : result;
+        })();
+        try {
+            return await this.activeRefreshPromise;
+        }
+        finally {
+            this.activeRefreshPromise = null;
+        }
     }
 }
 
@@ -1298,17 +1329,16 @@ class DPoPManager {
      * Generate a short fingerprint of the public key for debugging
      * This helps identify if the same key is being used across operations
      */
-    getPublicKeyFingerprint(publicKey) {
-        try {
-            // Use the 'x' coordinate of the EC key as a fingerprint
-            const x = publicKey.x || '';
-            const y = publicKey.y || '';
-            return `${x.substring(0, 8)}...${y.substring(0, 4)}`;
-        }
-        catch {
-            return 'unknown';
-        }
-    }
+    /* 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)
      */
@@ -1557,7 +1587,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";
+const SDK_VERSION = "2.1.39";
 /** Full SDK identifier for headers */
 const SDK_USER_AGENT = `${SDK_NAME}/${SDK_VERSION}`;
 
@@ -1667,12 +1697,16 @@ class PersApiClient {
         }
         const { retryCount = 0, responseType = 'json', bypassAuth = false } = options || {};
         const url = `${this.apiRoot}${endpoint}`;
-        // SMART TOKEN VALIDATION: Only check if we suspect the token might be expired
+        // TOKEN VALIDATION: Ensure token is valid before request
+        // This blocks the request until token validation completes - prevents 401s from expired tokens
         if (!bypassAuth && this.mergedConfig.authProvider && retryCount === 0) {
-            // Fire-and-forget validation - don't block the request unless we know there's an issue
-            this.ensureValidToken().catch(error => {
-                console.debug('[PersApiClient] Background token validation failed:', error);
-            });
+            try {
+                await this.ensureValidToken();
+            }
+            catch (error) {
+                console.debug('[PersApiClient] Token validation failed:', error);
+                // Continue with request - it will fail with 401 and trigger retry logic
+            }
         }
         const requestOptions = {
             headers: await this.getHeaders(!bypassAuth, method, url),
@@ -1700,49 +1734,63 @@ class PersApiClient {
             return result;
         }
         catch (error) {
-            // Error handling - proactive token refresh should prevent most 401s
             const status = index.ErrorUtils.getStatus(error);
             const errorMessage = index.ErrorUtils.getMessage(error);
-            // Handle 401 errors centrally through AuthService
+            // Handle 401 Unauthorized errors
             if (status === 401) {
                 const backendError = index.ErrorUtils.extractBackendErrorDetails(error);
-                // 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
+                // ===========================================
+                // FATAL AUTH ERRORS → Immediate logout
+                // ===========================================
+                // Fatal codes: REFRESH_TOKEN_EXPIRED, TOKEN_REVOKED, INVALID_REFRESH_TOKEN, etc.
                 if (this.authService.isFatalAuthError(backendError.code)) {
-                    // Definitive auth failure - no retry, session is invalid
+                    console.warn(`[PersApiClient] Fatal auth error: ${backendError.code}`);
                     await this.authService.handleAuthFailure();
                     this.emitErrorEvent(backendError, errorMessage, endpoint, method, status, error);
                     throw new index.AuthenticationError(errorMessage, endpoint, method, backendError);
                 }
-                // If this IS a refresh request that failed with 401, don't retry to avoid infinite loop
+                // ===========================================
+                // REFRESH REQUEST FAILED → Logout (prevents infinite loop)
+                // ===========================================
                 if (options?.isRefreshRequest) {
-                    // Refresh failed - this is a real auth failure
+                    console.warn('[PersApiClient] Refresh request itself failed with 401');
                     await this.authService.handleAuthFailure();
                     this.emitErrorEvent(backendError, errorMessage, endpoint, method, status, error);
                     throw new index.AuthenticationError(errorMessage, endpoint, method, backendError);
                 }
-                // TOKEN_EXPIRED or unknown 401: try refresh once, then retry
+                // ===========================================
+                // RETRYABLE 401 (TOKEN_EXPIRED) → Try refresh, then retry
+                // ===========================================
                 if (retryCount === 0 && this.mergedConfig.authProvider) {
-                    try {
-                        const refreshSuccessful = await this.refreshManager.attemptInternalRefresh();
-                        if (refreshSuccessful) {
-                            // Emit TOKEN_REFRESHED event so WS clients can retry if they gave up
-                            this._events?.emitSuccess({
-                                type: 'token_refreshed',
-                                domain: 'authentication',
-                                userMessage: 'Authentication token refreshed',
-                            });
-                            // Retry with new token
-                            return await this.request(method, endpoint, body, { ...options, retryCount: 1 });
-                        }
+                    const refreshResult = await this.refreshManager.attemptInternalRefresh();
+                    if (refreshResult.success) {
+                        // Refresh succeeded → retry request with new token
+                        this._events?.emitSuccess({
+                            type: 'token_refreshed',
+                            domain: 'authentication',
+                            userMessage: 'Authentication token refreshed',
+                        });
+                        return await this.request(method, endpoint, body, { ...options, retryCount: 1 });
+                    }
+                    // Refresh failed - check if it's a definitive failure
+                    if (!refreshResult.retryable) {
+                        // Non-retryable failure (e.g., refresh token expired) → logout
+                        console.warn('[PersApiClient] Refresh failed with non-retryable error, logging out');
+                        await this.authService.handleAuthFailure();
                     }
-                    catch (refreshError) {
-                        // Refresh failed - fall through to handleAuthFailure
+                    else {
+                        // Retryable failure (network error, etc.) → DON'T logout, let app retry later
+                        console.warn('[PersApiClient] Refresh failed with retryable error, NOT logging out');
                     }
+                    this.emitErrorEvent(backendError, errorMessage, endpoint, method, status, error);
+                    throw new index.AuthenticationError(errorMessage, endpoint, method, backendError);
                 }
-                // All recovery attempts failed
-                await this.authService.handleAuthFailure();
+                // ===========================================
+                // RETRY FAILED (retryCount > 0) → Something wrong, but DON'T logout
+                // ===========================================
+                // We already refreshed successfully, but retry still got 401
+                // This is unexpected - don't logout, let app investigate
+                console.warn('[PersApiClient] Retry with new token still got 401 - not logging out');
                 this.emitErrorEvent(backendError, errorMessage, endpoint, method, status, error);
                 throw new index.AuthenticationError(errorMessage, endpoint, method, backendError);
             }
@@ -1768,9 +1816,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,
@@ -3406,6 +3454,107 @@ class TokenManager {
     async getTokenByContract(contractAddress, contractTokenId = null) {
         return this.tokenService.getTokenByContractAddress(contractAddress, contractTokenId);
     }
+    /**
+     * Get all token metadata with filtering, pagination, and include relations
+     *
+     * Retrieves token metadata (rewards/stamps) with server-side filtering, pagination,
+     * and optional include relations for additional data.
+     * Useful for displaying rewards (ERC1155) or stamps (ERC721) in admin tables.
+     * Non-admin users always get active metadata only.
+     *
+     * @param options - Filter, pagination, and include options
+     * @returns Promise resolving to paginated token metadata
+     *
+     * @example Get paginated rewards with counts
+     * ```typescript
+     * const rewards = await sdk.tokens.getTokenMetadata({
+     *   tokenType: 'ERC1155',
+     *   active: true,
+     *   page: 1,
+     *   limit: 10,
+     *   sortBy: 'name',
+     *   sortOrder: 'ASC',
+     *   include: ['mintCount', 'burnCount', 'token']
+     * });
+     *
+     * rewards.data.forEach(r => {
+     *   console.log(`${r.name}: ${r.mintCount} minted, ${r.burnCount} burned`);
+     *   console.log(`Contract: ${r.included?.token?.contractAddress}`);
+     * });
+     * ```
+     *
+     * @example Get stamps with owner business
+     * ```typescript
+     * const stamps = await sdk.tokens.getTokenMetadata({
+     *   tokenType: 'ERC721',
+     *   search: 'gold',
+     *   include: ['ownerBusiness', 'token']
+     * });
+     *
+     * stamps.data.forEach(s => {
+     *   console.log(`${s.name} owned by ${s.included?.ownerBusiness?.displayName}`);
+     * });
+     * ```
+     */
+    async getTokenMetadata(options) {
+        return this.tokenService.getTokenMetadata(options);
+    }
+    /**
+     * Get rewards (ERC1155 token metadata) with filtering, pagination, and include relations
+     *
+     * Convenience method for fetching reward metadata. Rewards are ERC1155 tokens
+     * that represent collectible items, vouchers, or other redeemable rewards.
+     *
+     * @param options - Filter, pagination, and include options (tokenType is set automatically)
+     * @returns Promise resolving to paginated reward metadata
+     *
+     * @example Get active rewards with mint counts
+     * ```typescript
+     * const rewards = await sdk.tokens.getRewards({
+     *   active: true,
+     *   limit: 10,
+     *   include: ['mintCount', 'burnCount', 'token', 'ownerBusiness']
+     * });
+     *
+     * rewards.data.forEach(r => {
+     *   console.log(`${r.name}: ${r.mintCount ?? 0} minted`);
+     *   if (r.included?.token) {
+     *     console.log(`  Chain: ${r.included.token.chainId}, Contract: ${r.included.token.contractAddress}`);
+     *   }
+     * });
+     * ```
+     */
+    async getRewards(options) {
+        return this.tokenService.getRewards(options);
+    }
+    /**
+     * Get stamps (ERC721 token metadata) with filtering, pagination, and include relations
+     *
+     * Convenience method for fetching stamp metadata. Stamps are ERC721 tokens
+     * that represent achievements, badges, or collectible status markers.
+     *
+     * @param options - Filter, pagination, and include options (tokenType is set automatically)
+     * @returns Promise resolving to paginated stamp metadata
+     *
+     * @example Get active stamps with all includes
+     * ```typescript
+     * const stamps = await sdk.tokens.getStamps({
+     *   active: true,
+     *   limit: 10,
+     *   include: ['mintCount', 'burnCount', 'token', 'ownerBusiness']
+     * });
+     *
+     * stamps.data.forEach(s => {
+     *   console.log(`${s.name}: ${s.mintCount ?? 0} minted`);
+     *   if (s.included?.ownerBusiness) {
+     *     console.log(`  Owner: ${s.included.ownerBusiness.displayName}`);
+     *   }
+     * });
+     * ```
+     */
+    async getStamps(options) {
+        return this.tokenService.getStamps(options);
+    }
     /**
      * Admin: Create new token
      *
@@ -3497,6 +3646,32 @@ class TokenManager {
     async toggleTokenActive(tokenId) {
         return this.tokenService.toggleTokenActive(tokenId);
     }
+    /**
+     * Admin: Delete token metadata (soft delete)
+     *
+     * Soft deletes token metadata by setting deletedAt timestamp.
+     * Requires administrator privileges. Will fail with 409 Conflict
+     * if metadata is currently in use by active campaigns or redemptions.
+     *
+     * @param metadataId - ID of the token metadata to delete
+     * @throws {PersApiError} When not authenticated as admin
+     * @throws {PersApiError} 409 Conflict if metadata is in use
+     *
+     * @example
+     * ```typescript
+     * try {
+     *   await sdk.tokens.deleteTokenMetadata('metadata-123');
+     *   console.log('Token metadata deleted');
+     * } catch (error) {
+     *   if (error.statusCode === 409) {
+     *     console.log('Cannot delete: metadata is used by campaigns/redemptions');
+     *   }
+     * }
+     * ```
+     */
+    async deleteTokenMetadata(metadataId) {
+        return this.tokenService.deleteTokenMetadata(metadataId);
+    }
     /**
      * Get the full token SDK for advanced operations
      *
@@ -5310,6 +5485,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
      *
@@ -5844,6 +6065,21 @@ class RedemptionManager {
     async deleteRedemptionType(id) {
         return this.redemptionService.deleteRedemptionType(id);
     }
+    /**
+     * Delete a redemption (soft delete)
+     *
+     * @param id - Redemption ID to delete
+     * @returns Promise resolving to true if deleted successfully
+     *
+     * @example
+     * ```typescript
+     * const success = await sdk.redemptions.deleteRedemption('redemption-123');
+     * console.log('Deleted:', success);
+     * ```
+     */
+    async deleteRedemption(id) {
+        return this.redemptionService.deleteRedemption(id);
+    }
     /**
      * Get the full redemption service for advanced operations
      *
@@ -10713,4 +10949,4 @@ exports.createPersEventsClient = createPersEventsClient;
 exports.createPersSDK = createPersSDK;
 exports.isFatalAuthErrorInMessage = isFatalAuthErrorInMessage;
 exports.mergeWithDefaults = mergeWithDefaults;
-//# sourceMappingURL=pers-sdk-DgsYyo1X.cjs.map
+//# sourceMappingURL=pers-sdk-Cwlrl8jb.cjs.map