@explorins/pers-sdk-react-native 2.2.0 → 2.2.2

package/dist/index.js

@@ -3152,6 +3152,8 @@ exports.WebhookSource = void 0;
     WebhookSource["USER"] = "USER";
     WebhookSource["BUSINESS"] = "BUSINESS";
     WebhookSource["TENANT"] = "TENANT";
+    // System-level internal invocation (e.g., token metadata webhook fetch)
+    WebhookSource["INTERNAL"] = "INTERNAL";
     // External verified sources
     WebhookSource["STRIPE"] = "STRIPE";
     // Allow any external traffic (no verification)
@@ -3216,6 +3218,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)
@@ -3551,7 +3559,8 @@ function isValidTransactionRelation(value) {
 const VALID_CAMPAIGN_RELATIONS = [
     'triggerSources',
     'businesses',
-    'claimCount'
+    'claimCount',
+    'ownerBusiness'
 ];
 /**
  * Type guard to validate campaign include relation at runtime
@@ -3589,7 +3598,8 @@ function isValidCampaignClaimRelation(value) {
  * Used for runtime validation
  */
 const VALID_REDEMPTION_RELATIONS = [
-    'redeemCount'
+    'redeemCount',
+    'ownerBusiness'
 ];
 /**
  * Type guard to validate redemption include relation at runtime
@@ -3647,6 +3657,26 @@ function isValidUserRelation(value) {
     return VALID_USER_RELATIONS.includes(value);
 }
 
+/**
+ * Array of all valid token metadata include relations
+ * Used for runtime validation
+ */
+const VALID_TOKEN_METADATA_RELATIONS = [
+    'ownerBusiness',
+    'mintCount',
+    'burnCount',
+    'token'
+];
+/**
+ * Type guard to validate token metadata include relation at runtime
+ *
+ * @param value - String to validate
+ * @returns True if value is a valid TokenMetadataIncludeRelation
+ */
+function isValidTokenMetadataRelation(value) {
+    return VALID_TOKEN_METADATA_RELATIONS.includes(value);
+}
+
 /**
  * Normalizes filter options to use new field names while accepting deprecated ones.
  * Use at controller level to support both old and new API contracts.
@@ -3726,6 +3756,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 +3798,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 +3816,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 +3829,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',
@@ -3883,12 +3927,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
@@ -3958,7 +4002,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
             ];
@@ -3977,8 +4023,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
@@ -3989,9 +4036,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)
         };
     }
@@ -4070,7 +4117,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);
@@ -4094,7 +4141,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;
@@ -5142,6 +5189,66 @@ class TokenApi {
         }
         return this.apiClient.get(url);
     }
+    /**
+     * Get all token metadata with filtering, pagination, and include relations
+     *
+     * Useful for displaying rewards (ERC1155) or stamps (ERC721) in tables.
+     * Non-admin users always get active metadata only.
+     *
+     * @param options - Filter, pagination, and include options
+     * @returns Paginated response with token metadata
+     *
+     * @example Get all active rewards with mint/burn counts
+     * ```typescript
+     * const rewards = await tokenApi.getTokenMetadata({
+     *   tokenType: 'ERC1155',
+     *   active: true,
+     *   limit: 10,
+     *   include: ['mintCount', 'burnCount', 'token']
+     * });
+     * ```
+     *
+     * @example Get stamps with owner business included
+     * ```typescript
+     * const stamps = await tokenApi.getTokenMetadata({
+     *   tokenType: 'ERC721',
+     *   search: 'gold',
+     *   include: ['ownerBusiness', 'token']
+     * });
+     * ```
+     */
+    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(','));
+            }
+        }
+        // Filter by owner business
+        if (options?.ownerBusinessId) {
+            params.set('ownerBusinessId', options.ownerBusinessId);
+        }
+        // Include relations (ownerBusiness, mintCount, burnCount, token)
+        if (options?.include && options.include.length > 0) {
+            params.set('include', options.include.join(','));
+        }
+        const response = await this.apiClient.get(`${this.basePath}/metadata?${params.toString()}`);
+        return normalizeToPaginated(response);
+    }
     // ==========================================
     // ADMIN OPERATIONS
     // ==========================================
@@ -5198,6 +5305,30 @@ class TokenApi {
     async createTokenType(tokenType) {
         return this.apiClient.post(`${this.basePath}/types`, tokenType);
     }
+    /**
+     * ADMIN: Delete token metadata (soft delete)
+     *
+     * Soft deletes token metadata by setting deletedAt timestamp.
+     * Will fail with 409 Conflict if metadata is in use by active campaigns or redemptions.
+     *
+     * @param metadataId - ID of the token metadata to delete
+     * @throws {PersApiError} 409 Conflict if metadata is in use
+     *
+     * @example
+     * ```typescript
+     * try {
+     *   await tokenApi.deleteTokenMetadata('metadata-123');
+     *   console.log('Metadata deleted');
+     * } catch (error) {
+     *   if (error.statusCode === 409) {
+     *     console.log('Cannot delete: metadata is in use');
+     *   }
+     * }
+     * ```
+     */
+    async deleteTokenMetadata(metadataId) {
+        return this.apiClient.delete(`${this.basePath}/metadata/${metadataId}`);
+    }
 }
 
 /**
@@ -5251,6 +5382,62 @@ class TokenService {
     async getTokenByContractAddress(contractAddress, contractTokenId) {
         return this.tokenApi.getTokenByContractAddress(contractAddress, contractTokenId);
     }
+    /**
+     * Get all token metadata with filtering, pagination, and include relations
+     *
+     * Useful for displaying rewards (ERC1155) or stamps (ERC721) in tables.
+     * Non-admin users always get active metadata only.
+     *
+     * @param options - Filter, pagination, and include options
+     * @returns Paginated response with token metadata
+     *
+     * @example Get rewards with counts
+     * ```typescript
+     * const rewards = await tokenService.getTokenMetadata({
+     *   tokenType: 'ERC1155',
+     *   include: ['mintCount', 'burnCount', 'token']
+     * });
+     * ```
+     */
+    async getTokenMetadata(options) {
+        return this.tokenApi.getTokenMetadata(options);
+    }
+    /**
+     * Get rewards (ERC1155 token metadata) with filtering, pagination, and include relations
+     *
+     * Convenience method for fetching reward metadata.
+     *
+     * @param options - Filter, pagination, and include options (tokenType is set automatically)
+     * @returns Paginated response with reward metadata
+     *
+     * @example Get rewards with mint/burn counts and token info
+     * ```typescript
+     * const rewards = await tokenService.getRewards({
+     *   include: ['mintCount', 'burnCount', 'token', 'ownerBusiness']
+     * });
+     * ```
+     */
+    async getRewards(options) {
+        return this.tokenApi.getTokenMetadata({ ...options, tokenType: NativeTokenTypes.ERC1155 });
+    }
+    /**
+     * Get stamps (ERC721 token metadata) with filtering, pagination, and include relations
+     *
+     * Convenience method for fetching stamp metadata.
+     *
+     * @param options - Filter, pagination, and include options (tokenType is set automatically)
+     * @returns Paginated response with stamp metadata
+     *
+     * @example Get stamps with mint/burn counts and token info
+     * ```typescript
+     * const stamps = await tokenService.getStamps({
+     *   include: ['mintCount', 'burnCount', 'token', 'ownerBusiness']
+     * });
+     * ```
+     */
+    async getStamps(options) {
+        return this.tokenApi.getTokenMetadata({ ...options, tokenType: NativeTokenTypes.ERC721 });
+    }
     // ==========================================
     // ADMIN OPERATIONS
     // ==========================================
@@ -5303,6 +5490,17 @@ class TokenService {
     async createTokenType(tokenType) {
         return this.tokenApi.createTokenType(tokenType);
     }
+    /**
+     * ADMIN: Delete token metadata (soft delete)
+     *
+     * Soft deletes token metadata. Will fail if metadata is in use.
+     *
+     * @param metadataId - ID of the token metadata to delete
+     * @throws {PersApiError} 409 Conflict if metadata is in use by campaigns/redemptions
+     */
+    async deleteTokenMetadata(metadataId) {
+        return this.tokenApi.deleteTokenMetadata(metadataId);
+    }
 }
 
 /**
@@ -5377,7 +5575,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:
@@ -5400,8 +5598,15 @@ 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 });
+     *
+     * // Filter by location (geocoding)
+     * const dohaBusinesses = await businessApi.getBusinesses({ city: 'Doha', countryCode: 'QA' });
+     * const westBay = await businessApi.getBusinesses({ neighborhood: 'West Bay' });
      * ```
      */
     async getBusinesses(options) {
@@ -5421,6 +5626,25 @@ class BusinessApi {
         if (options?.sanitize) {
             params.set('sanitize', options.sanitize);
         }
+        if (options?.businessTypeId !== undefined) {
+            params.set('businessTypeId', String(options.businessTypeId));
+        }
+        // Location filter options (geocoding)
+        if (options?.city) {
+            params.set('city', options.city);
+        }
+        if (options?.countryCode) {
+            params.set('countryCode', options.countryCode);
+        }
+        if (options?.country) {
+            params.set('country', options.country);
+        }
+        if (options?.neighborhood) {
+            params.set('neighborhood', options.neighborhood);
+        }
+        if (options?.district) {
+            params.set('district', options.district);
+        }
         const response = await this.apiClient.get(`${this.basePath}?${params.toString()}`);
         return normalizeToPaginated(response);
     }
@@ -5767,20 +5991,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
@@ -7019,6 +7239,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)
      */
@@ -7118,6 +7346,12 @@ class RedemptionService {
     async updateRedemptionType(data) {
         return this.redemptionApi.updateRedemptionType(data);
     }
+    /**
+     * ADMIN: Delete redemption
+     */
+    async deleteRedemption(id) {
+        return this.redemptionApi.deleteRedemption(id);
+    }
     /**
      * ADMIN: Delete redemption type
      */
@@ -9053,7 +9287,7 @@ class TriggerSourceApi {
     /**
      * PUBLIC: Get trigger sources with optional filters and pagination
      *
-     * @param options - Filter and pagination options
+     * @param options - Filter and pagination options (includes location filters)
      * @returns Paginated list of trigger sources
      *
      * @example
@@ -9067,6 +9301,12 @@ class TriggerSourceApi {
      *   page: 1,
      *   limit: 20
      * });
+     *
+     * // Filter by location (geocoding)
+     * const dubaiSources = await triggerSourceApi.getTriggerSources({
+     *   city: 'Dubai',
+     *   countryCode: 'AE'
+     * });
      * ```
      */
     async getTriggerSources(options) {
@@ -9079,6 +9319,19 @@ class TriggerSourceApi {
             params.set('campaignId', options.campaignId);
         if (options?.active !== undefined)
             params.set('active', String(options.active));
+        if (options?.includeDeleted)
+            params.set('includeDeleted', String(options.includeDeleted));
+        // Location filter options (geocoding)
+        if (options?.city)
+            params.set('city', options.city);
+        if (options?.countryCode)
+            params.set('countryCode', options.countryCode);
+        if (options?.country)
+            params.set('country', options.country);
+        if (options?.neighborhood)
+            params.set('neighborhood', options.neighborhood);
+        if (options?.district)
+            params.set('district', options.district);
         const response = await this.apiClient.get(`/trigger-sources?${params.toString()}`);
         return normalizeToPaginated(response);
     }
@@ -9575,13 +9828,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)
@@ -9596,11 +9853,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;
     }
@@ -9658,6 +9916,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() {
@@ -9684,12 +9945,17 @@ class AuthService {
             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:
-                    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 === 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);
@@ -9805,6 +10071,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.
@@ -9905,11 +10173,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;
+        }
     }
 }
 
@@ -10457,17 +10741,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)
      */
@@ -10716,7 +10999,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}`;
 
@@ -10826,12 +11109,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),
@@ -10859,49 +11146,63 @@ class PersApiClient {
             return result;
         }
         catch (error) {
-            // Error handling - proactive token refresh should prevent most 401s
             const status = ErrorUtils.getStatus(error);
             const errorMessage = ErrorUtils.getMessage(error);
-            // Handle 401 errors centrally through AuthService
+            // Handle 401 Unauthorized errors
             if (status === 401) {
                 const backendError = 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 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 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 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 AuthenticationError(errorMessage, endpoint, method, backendError);
             }
@@ -10927,9 +11228,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,
@@ -12565,6 +12866,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
      *
@@ -12656,6 +13058,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
      *
@@ -14469,6 +14897,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
      *
@@ -15003,6 +15477,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
      *
@@ -21157,6 +21646,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,
@@ -21164,6 +21746,9 @@ const useTokens = () => {
         getTokenTypes,
         getStatusTokens,
         getTokenByContract,
+        getTokenMetadata,
+        getRewards,
+        getStamps,
         isAvailable: isInitialized && !!sdk?.tokens,
     };
 };
@@ -44400,6 +44985,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.
@@ -44408,11 +45012,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)
@@ -44443,6 +45057,8 @@ const useRedemptions = () => {
      *   }
      * });
      * ```
+     *
+     * @see {@link useTransactions.createTransaction | createTransaction()} for direct transfers without redemption flow
      */
     const redeem = react.useCallback(async (redemptionId, options) => {
         if (!isInitialized || !sdk) {
@@ -44592,8 +45208,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,
@@ -46293,6 +46944,7 @@ exports.VALID_CAMPAIGN_RELATIONS = VALID_CAMPAIGN_RELATIONS;
 exports.VALID_REDEMPTION_REDEEM_RELATIONS = VALID_REDEMPTION_REDEEM_RELATIONS;
 exports.VALID_REDEMPTION_RELATIONS = VALID_REDEMPTION_RELATIONS;
 exports.VALID_RELATIONS = VALID_RELATIONS;
+exports.VALID_TOKEN_METADATA_RELATIONS = VALID_TOKEN_METADATA_RELATIONS;
 exports.VALID_TRANSACTION_RELATIONS = VALID_TRANSACTION_RELATIONS;
 exports.VALID_USER_RELATIONS = VALID_USER_RELATIONS;
 exports.WalletEventsManager = WalletEventsManager;
@@ -46344,6 +46996,7 @@ exports.isValidCampaignRelation = isValidCampaignRelation;
 exports.isValidRedemptionRedeemRelation = isValidRedemptionRedeemRelation;
 exports.isValidRedemptionRelation = isValidRedemptionRelation;
 exports.isValidRelation = isValidRelation;
+exports.isValidTokenMetadataRelation = isValidTokenMetadataRelation;
 exports.isValidTransactionRelation = isValidTransactionRelation;
 exports.isValidUserRelation = isValidUserRelation;
 exports.mergeWithDefaults = mergeWithDefaults;