@explorins/pers-sdk 2.1.37 → 2.1.40

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

@@ -4,10 +4,10 @@ var persShared = require('@explorins/pers-shared');
 var index = require('./index-C4K-jkRO.cjs');
 var user = require('../user.cjs');
 var userStatus = require('../user-status.cjs');
-var tokenService = require('./token-service-BJqu5Xap.cjs');
-var businessMembershipService = require('./business-membership-service-B9ItWZ2_.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-Dc_0Kzd0.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-DR5eSEJw.cjs');
@@ -504,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() {
@@ -656,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.
@@ -756,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;
+        }
     }
 }
 
@@ -1566,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.37";
+const SDK_VERSION = "2.1.40";
 /** Full SDK identifier for headers */
 const SDK_USER_AGENT = `${SDK_NAME}/${SDK_VERSION}`;
 
@@ -1676,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),
@@ -1709,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 });
                     }
-                    catch (refreshError) {
-                        // Refresh failed - fall through to handleAuthFailure
+                    // 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();
                     }
+                    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);
             }
@@ -3264,10 +3303,11 @@ class UserStatusManager {
  * ```
  */
 class TokenManager {
-    constructor(apiClient) {
+    constructor(apiClient, eventEmitter) {
         this.apiClient = apiClient;
         const tokenApi = new tokenService.TokenApi(apiClient);
         this.tokenService = new tokenService.TokenService(tokenApi);
+        this.eventEmitter = eventEmitter;
     }
     /**
      * Get all available tokens
@@ -3416,16 +3456,17 @@ class TokenManager {
         return this.tokenService.getTokenByContractAddress(contractAddress, contractTokenId);
     }
     /**
-     * Get all token metadata with filtering and pagination
+     * Get all token metadata with filtering, pagination, and include relations
      *
-     * Retrieves token metadata (rewards/stamps) with server-side filtering and pagination.
+     * 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 and pagination options
+     * @param options - Filter, pagination, and include options
      * @returns Promise resolving to paginated token metadata
      *
-     * @example Get paginated rewards
+     * @example Get paginated rewards with counts
      * ```typescript
      * const rewards = await sdk.tokens.getTokenMetadata({
      *   tokenType: 'ERC1155',
@@ -3433,19 +3474,26 @@ class TokenManager {
      *   page: 1,
      *   limit: 10,
      *   sortBy: 'name',
-     *   sortOrder: 'ASC'
+     *   sortOrder: 'ASC',
+     *   include: ['mintCount', 'burnCount', 'token']
      * });
      *
-     * console.log(`Page 1 of ${rewards.pagination.pages}`);
-     * rewards.data.forEach(r => console.log(r.name));
+     * 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 search
+     * @example Get stamps with owner business
      * ```typescript
      * const stamps = await sdk.tokens.getTokenMetadata({
      *   tokenType: 'ERC721',
      *   search: 'gold',
-     *   limit: 25
+     *   include: ['ownerBusiness', 'token']
+     * });
+     *
+     * stamps.data.forEach(s => {
+     *   console.log(`${s.name} owned by ${s.included?.ownerBusiness?.displayName}`);
      * });
      * ```
      */
@@ -3453,31 +3501,27 @@ class TokenManager {
         return this.tokenService.getTokenMetadata(options);
     }
     /**
-     * Get rewards (ERC1155 token metadata) with filtering and pagination
+     * 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 and pagination options (tokenType is set automatically)
+     * @param options - Filter, pagination, and include options (tokenType is set automatically)
      * @returns Promise resolving to paginated reward metadata
      *
-     * @example Get active rewards
+     * @example Get active rewards with mint counts
      * ```typescript
      * const rewards = await sdk.tokens.getRewards({
      *   active: true,
-     *   limit: 10
+     *   limit: 10,
+     *   include: ['mintCount', 'burnCount', 'token', 'ownerBusiness']
      * });
      *
-     * 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'
+     * 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}`);
+     *   }
      * });
      * ```
      */
@@ -3485,31 +3529,27 @@ class TokenManager {
         return this.tokenService.getRewards(options);
     }
     /**
-     * Get stamps (ERC721 token metadata) with filtering and pagination
+     * 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 and pagination options (tokenType is set automatically)
+     * @param options - Filter, pagination, and include options (tokenType is set automatically)
      * @returns Promise resolving to paginated stamp metadata
      *
-     * @example Get active stamps
+     * @example Get active stamps with all includes
      * ```typescript
      * const stamps = await sdk.tokens.getStamps({
      *   active: true,
-     *   limit: 10
+     *   limit: 10,
+     *   include: ['mintCount', 'burnCount', 'token', 'ownerBusiness']
      * });
      *
-     * 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'
+     * stamps.data.forEach(s => {
+     *   console.log(`${s.name}: ${s.mintCount ?? 0} minted`);
+     *   if (s.included?.ownerBusiness) {
+     *     console.log(`  Owner: ${s.included.ownerBusiness.displayName}`);
+     *   }
      * });
      * ```
      */
@@ -3607,6 +3647,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
      *
@@ -6000,6 +6066,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
      *
@@ -10470,7 +10551,7 @@ class PersSDK {
      */
     get tokens() {
         if (!this._tokens) {
-            this._tokens = new TokenManager(this.apiClient);
+            this._tokens = new TokenManager(this.apiClient, this._events);
         }
         return this._tokens;
     }
@@ -10869,4 +10950,4 @@ exports.createPersEventsClient = createPersEventsClient;
 exports.createPersSDK = createPersSDK;
 exports.isFatalAuthErrorInMessage = isFatalAuthErrorInMessage;
 exports.mergeWithDefaults = mergeWithDefaults;
-//# sourceMappingURL=pers-sdk-DemghJ3a.cjs.map
+//# sourceMappingURL=pers-sdk-CBvzmlL_.cjs.map