@explorins/pers-sdk-react-native 2.2.1 → 2.3.0-alpha.1

package/dist/index.js

@@ -2624,6 +2624,8 @@ exports.ApiKeyType = void 0;
     ApiKeyType["BLOCKCHAIN_READER_JWT"] = "BLOCKCHAIN_READER_JWT";
     ApiKeyType["TRANSACTION_JWT_ACCESS_TOKEN"] = "TRANSACTION_JWT_ACCESS_TOKEN";
     ApiKeyType["WEBHOOK_OUTBOUND_JWT"] = "WEBHOOK_OUTBOUND_JWT";
+    /** One-Time Token for passwordless auth flows (magic link, SMS, etc.) */
+    ApiKeyType["ONE_TIME_TOKEN"] = "ONE_TIME_TOKEN";
     // TODO: this needs to be removed. However, there is still dependency
     ApiKeyType["TENANT_LEGACY_ADMIN"] = "TENANT_ADMIN_JWT";
     // TENANT_SYSTEM_API_SECRET    = 'TENANT_SYSTEM_API_SECRET',
@@ -3152,6 +3154,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)
@@ -3182,6 +3186,629 @@ exports.WebhookCallbackStatus = void 0;
     WebhookCallbackStatus["CANCELLED"] = "CANCELLED";
 })(exports.WebhookCallbackStatus || (exports.WebhookCallbackStatus = {}));
 
+/**
+ * One-Time Token Authentication Methods
+ *
+ * Defines the passwordless authentication methods supported by OTT flow.
+ * Used in magic link, SMS verification, and email code authentication.
+ */
+const OttAuthMethod = {
+    /** Magic link sent via email */
+    MAGIC_LINK: 'magic-link',
+    /** Verification code sent via SMS */
+    SMS: 'sms',
+    /** Verification code sent via email */
+    EMAIL_CODE: 'email-code',
+};
+
+/**
+ * Base array of all string-valued user model property keys.
+ * Single source of truth for user field names across the codebase.
+ */
+const userModelFieldsArray = [
+    'id',
+    'email',
+    'identifierEmail',
+    'firstName',
+    'lastName',
+    'externalId',
+    'instagramAccountId',
+    'googleAccountName',
+];
+/** Iterable array of all user model fields */
+const userModelFields = [...userModelFieldsArray];
+/**
+ * Fields that can be used to uniquely identify/lookup a user.
+ * Used for wildcard search, user lookup queries.
+ */
+const uniqueUserIdentifierKeysArray = [
+    'id',
+    'email',
+    'identifierEmail',
+    'instagramAccountId',
+    'externalId',
+];
+// Export the array
+const uniqueUserIdentifierKeys = [...uniqueUserIdentifierKeysArray];
+// Define identifier type configurations
+const identifierTypes = {
+    id: {
+        key: 'id',
+        detect: (value) => /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(value), // UUID pattern
+        process: (value) => value
+    },
+    email: {
+        key: 'email',
+        detect: (value) => /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(value),
+        process: (value) => value
+    },
+    instagramAccountId: {
+        key: 'instagramAccountId',
+        detect: (value) => /^@/.test(value) || value.toLowerCase().includes('instagram'),
+        process: (value) => value.replace(/^@/, '') // Remove @ if present for consistency
+    },
+    externalId: {
+        key: 'externalId',
+        detect: () => true, // Default fallback
+        process: (value) => value
+    }
+};
+/**
+ * Register a new identifier type configuration
+ * @param key The identifier key
+ * @param config The identifier configuration (without the key)
+ */
+const registerIdentifierType = (key, config) => {
+    if (!uniqueUserIdentifierKeysArray.includes(key)) {
+        console.warn(`Warning: Registering identifier type '${key}' that is not in uniqueUserIdentifierKeys`);
+    }
+    identifierTypes[key] = {
+        key,
+        ...config
+    };
+};
+/**
+ * Detects the type of identifier from a wildcard input
+ * @param wildcardValue The value to analyze
+ * @returns Object containing the type and processed value
+ */
+const detectIdentifierType = (wildcardValue) => {
+    if (wildcardValue === null || wildcardValue === undefined) {
+        return { type: 'externalId', value: '' };
+    }
+    const value = String(wildcardValue);
+    // Try each identifier type in priority order (id first to catch UUIDs)
+    for (const type of ['id', 'email', 'instagramAccountId', 'externalId']) {
+        const config = identifierTypes[type];
+        if (config.detect(value)) {
+            return { type, value: config.process(value) };
+        }
+    }
+    // Default fallback should never be reached due to externalId's detect always returning true
+    return { type: 'externalId', value };
+};
+/**
+ * Checks if an object is a properly formed UserIdentifierObject
+ * @param obj Object to check
+ * @returns Boolean indicating if the object is a UserIdentifierObject
+ */
+const isUserIdentifierObject = (obj) => {
+    return obj &&
+        obj.type === 'identifierObject' &&
+        uniqueUserIdentifierKeys.every(key => key in obj);
+};
+/**
+ * Creates a UserIdentifierObject with all required fields, setting missing values to null
+ * @param params Partial parameters for the identifier object
+ * @returns A properly formed UserIdentifierObject
+ */
+const createUserIdentifierObject = (params) => {
+    // Extract the wildcard or use empty string
+    const wildcard = params.wildcard || '';
+    // Create base object with all identifier fields set to null
+    const identifierObject = {
+        type: 'identifierObject',
+        id: null,
+        email: null,
+        instagramAccountId: null,
+        externalId: null,
+        identifierEmail: null,
+        wildcard
+    };
+    // Override nulls with any provided values
+    uniqueUserIdentifierKeys.forEach(key => {
+        if (params[key]) {
+            identifierObject[key] = params[key];
+        }
+    });
+    // If wildcard is provided but no specific fields, auto-detect the field type
+    if (wildcard && !params.id && !params.email && !params.instagramAccountId && !params.externalId) {
+        const detected = detectIdentifierType(wildcard);
+        identifierObject[detected.type] = detected.value;
+    }
+    return identifierObject;
+};
+
+/**
+ * Validation Types
+ * Shared type definitions for field validation.
+ */
+// ============================================================================
+// Operator Text Mapping
+// ============================================================================
+const operatorText = {
+    '<': 'less than',
+    '<=': 'less than or equal to',
+    '>': 'greater than',
+    '>=': 'greater than or equal to',
+    '==': 'equal to',
+    '!=': 'not equal to',
+};
+
+/**
+ * Standalone Validators
+ * Pure validation functions that can be used independently.
+ * Shared between backend and frontend.
+ */
+// ============================================================================
+// Regex Patterns
+// ============================================================================
+/** RFC-compliant email regex */
+const EMAIL_REGEX = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+const EMAIL_MAX_LENGTH = 254; // RFC 5321
+/** Basic URL pattern - http(s) with domain */
+const URL_REGEX = /^https?:\/\/[^\s/$.?#].[^\s]*$/i;
+/** Ethereum address format: 0x followed by 40 hexadecimal characters */
+const WALLET_ADDRESS_REGEX = /^0x[a-fA-F0-9]{40}$/;
+/** UUID v4 format */
+const UUID_REGEX = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+// ============================================================================
+// Validators
+// ============================================================================
+/**
+ * Validates email format according to RFC standards.
+ * RFC 5321 length limit (254 characters) enforced.
+ */
+function isValidEmail(email) {
+    if (!email || email.length > EMAIL_MAX_LENGTH)
+        return false;
+    return EMAIL_REGEX.test(email);
+}
+/**
+ * Validates URL format (http/https only).
+ */
+function isValidUrl(url) {
+    if (!url)
+        return false;
+    return URL_REGEX.test(url);
+}
+/**
+ * Validates Ethereum wallet address format.
+ * Format: 0x followed by 40 hexadecimal characters.
+ */
+function isValidWalletAddress(address) {
+    if (!address)
+        return false;
+    return WALLET_ADDRESS_REGEX.test(address);
+}
+/**
+ * Validates that a string is not empty and meets minimum length.
+ */
+function isValidNonEmptyString(value, minLength = 1) {
+    return typeof value === 'string' && value.trim().length >= minLength;
+}
+/**
+ * Validates UUID v4 format.
+ */
+function isValidUuid(uuid) {
+    if (!uuid)
+        return false;
+    return UUID_REGEX.test(uuid);
+}
+
+// ============================================================================
+// Comparison Functions
+// ============================================================================
+/**
+ * Compare two values using the specified operator.
+ * Works with numbers, dates, and strings.
+ */
+const compareValues = (a, b, op) => {
+    switch (op) {
+        case '<': return a < b;
+        case '<=': return a <= b;
+        case '>': return a > b;
+        case '>=': return a >= b;
+        case '==': return a === b;
+        case '!=': return a !== b;
+    }
+};
+/** Get human-readable operator text for error messages. */
+const getOperatorText = (op) => operatorText[op];
+// ============================================================================
+// Single Field Validation
+// ============================================================================
+/**
+ * Validate a single field value against validation rules.
+ * Does not check cross-field comparisons (use validateFieldComparisons for that).
+ */
+const validateFieldValue = (value, rules, fieldType) => {
+    // No rules = valid
+    if (!rules) {
+        return null;
+    }
+    const stringValue = value !== null && value !== undefined ? String(value) : '';
+    const isEmpty = value === null || value === undefined || value === '';
+    // Skip validation if empty - required-ness is determined by requiredUserFields
+    // (the merged field on RedemptionDTO), not by a validation rule.
+    if (isEmpty) {
+        return null;
+    }
+    // Type-specific validation
+    switch (fieldType) {
+        case 'text':
+            if (rules.minLength && stringValue.length < rules.minLength) {
+                return { field: '', message: `Minimum ${rules.minLength} characters required`, code: 'minLength' };
+            }
+            if (rules.maxLength && stringValue.length > rules.maxLength) {
+                return { field: '', message: `Maximum ${rules.maxLength} characters allowed`, code: 'maxLength' };
+            }
+            if (rules.pattern && !new RegExp(rules.pattern).test(stringValue)) {
+                return { field: '', message: rules.patternMessage || 'Invalid format', code: 'pattern' };
+            }
+            break;
+        case 'email':
+            if (stringValue.length > EMAIL_MAX_LENGTH || !EMAIL_REGEX.test(stringValue)) {
+                return { field: '', message: 'Invalid email format', code: 'email' };
+            }
+            if (rules.maxLength && stringValue.length > rules.maxLength) {
+                return { field: '', message: `Maximum ${rules.maxLength} characters allowed`, code: 'maxLength' };
+            }
+            break;
+        case 'url':
+            if (!URL_REGEX.test(stringValue)) {
+                return { field: '', message: 'Invalid URL format', code: 'url' };
+            }
+            if (rules.maxLength && stringValue.length > rules.maxLength) {
+                return { field: '', message: `Maximum ${rules.maxLength} characters allowed`, code: 'maxLength' };
+            }
+            break;
+        case 'number':
+            const numValue = typeof value === 'number' ? value : parseFloat(stringValue);
+            if (isNaN(numValue)) {
+                return { field: '', message: 'Must be a valid number', code: 'type' };
+            }
+            if (rules.min !== undefined && numValue < rules.min) {
+                return { field: '', message: `Minimum value is ${rules.min}`, code: 'min' };
+            }
+            if (rules.max !== undefined && numValue > rules.max) {
+                return { field: '', message: `Maximum value is ${rules.max}`, code: 'max' };
+            }
+            break;
+        case 'boolean':
+            if (typeof value !== 'boolean' && stringValue !== 'true' && stringValue !== 'false') {
+                return { field: '', message: 'Must be true or false', code: 'type' };
+            }
+            break;
+        case 'date':
+            const dateValue = new Date(stringValue);
+            if (isNaN(dateValue.getTime())) {
+                return { field: '', message: 'Must be a valid date', code: 'type' };
+            }
+            const now = new Date();
+            if (rules.minDate) {
+                const minDate = rules.minDate === 'now' ? now : new Date(rules.minDate);
+                if (dateValue < minDate) {
+                    return {
+                        field: '',
+                        message: rules.minDate === 'now' ? 'Date must be in the future' : `Date must be after ${rules.minDate}`,
+                        code: 'minDate'
+                    };
+                }
+            }
+            if (rules.maxDate) {
+                const maxDate = rules.maxDate === 'now' ? now : new Date(rules.maxDate);
+                if (dateValue > maxDate) {
+                    return {
+                        field: '',
+                        message: rules.maxDate === 'now' ? 'Date must be in the past' : `Date must be before ${rules.maxDate}`,
+                        code: 'maxDate'
+                    };
+                }
+            }
+            break;
+        case 'objectArray':
+            if (!Array.isArray(value)) {
+                return { field: '', message: 'Must be an array', code: 'type' };
+            }
+            if (rules.minItems !== undefined && value.length < rules.minItems) {
+                return { field: '', message: `Minimum ${rules.minItems} items required`, code: 'minItems' };
+            }
+            if (rules.maxItems !== undefined && value.length > rules.maxItems) {
+                return { field: '', message: `Maximum ${rules.maxItems} items allowed`, code: 'maxItems' };
+            }
+            break;
+    }
+    return null;
+};
+// ============================================================================
+// Cross-Field / Literal Comparison Validation
+// ============================================================================
+/** Type guard for field comparison */
+const isFieldComparison = (c) => 'field' in c && c.field !== undefined;
+/**
+ * Validate comparison rules for a single field.
+ * Supports comparing to another field OR a literal value.
+ */
+const validateFieldComparisons = (fieldKey, value, comparisons, allData, fieldType) => {
+    if (!comparisons || comparisons.length === 0)
+        return [];
+    const errors = [];
+    for (const comparison of comparisons) {
+        // Skip if this field's value is empty
+        if (value === null || value === undefined || value === '')
+            continue;
+        // Get the comparison target (field value or literal)
+        const isField = isFieldComparison(comparison);
+        const targetValue = isField ? allData[comparison.field] : comparison.value;
+        const targetLabel = isField ? comparison.field : String(comparison.value);
+        // Skip if comparing to field and that field is empty
+        if (isField && (targetValue === null || targetValue === undefined || targetValue === ''))
+            continue;
+        let isValid = true;
+        const { operator, message } = comparison;
+        switch (fieldType) {
+            case 'date': {
+                const thisDate = new Date(String(value));
+                const otherDate = new Date(String(targetValue));
+                if (isNaN(thisDate.getTime()) || isNaN(otherDate.getTime()))
+                    continue;
+                isValid = compareValues(thisDate.getTime(), otherDate.getTime(), operator);
+                break;
+            }
+            case 'number': {
+                const thisNum = typeof value === 'number' ? value : parseFloat(String(value));
+                const otherNum = typeof targetValue === 'number' ? targetValue : parseFloat(String(targetValue));
+                if (isNaN(thisNum) || isNaN(otherNum))
+                    continue;
+                isValid = compareValues(thisNum, otherNum, operator);
+                break;
+            }
+            case 'boolean': {
+                const thisBool = typeof value === 'boolean' ? value : value === 'true';
+                const otherBool = typeof targetValue === 'boolean' ? targetValue : targetValue === 'true';
+                isValid = operator === '==' ? thisBool === otherBool :
+                    operator === '!=' ? thisBool !== otherBool : true;
+                break;
+            }
+            default: {
+                isValid = compareValues(String(value), String(targetValue), operator);
+                break;
+            }
+        }
+        if (!isValid) {
+            errors.push({
+                field: fieldKey,
+                message: message || `Must be ${getOperatorText(operator)} ${targetLabel}`,
+                code: `comparison:${operator}:${targetLabel}`,
+            });
+        }
+    }
+    return errors;
+};
+// ============================================================================
+// Object Array Item Validation
+// ============================================================================
+/**
+ * Validate each item in an object array against the object schema.
+ * Checks required properties, type validation, and validates each property.
+ *
+ * @param fieldKey - Parent field key (for error reporting)
+ * @param items - Array of objects to validate
+ * @param schema - Schema defining expected properties
+ * @returns Array of validation errors with item index in field path (e.g., "contacts[0].phone")
+ */
+const validateObjectArrayItems = (fieldKey, items, schema) => {
+    const errors = [];
+    if (!Array.isArray(items))
+        return errors;
+    items.forEach((item, index) => {
+        if (typeof item !== 'object' || item === null) {
+            errors.push({
+                field: `${fieldKey}[${index}]`,
+                code: 'type',
+                message: 'Item must be an object',
+            });
+            return;
+        }
+        const obj = item;
+        // Check each schema property
+        for (const prop of schema) {
+            const value = obj[prop.key];
+            const propPath = `${fieldKey}[${index}].${prop.key}`;
+            const isEmpty = value === null || value === undefined || value === '';
+            // Required check for nested properties (ObjectFieldSchema.required)
+            if (prop.required && isEmpty) {
+                errors.push({
+                    field: propPath,
+                    code: 'required',
+                    message: `${prop.label} is required`,
+                });
+                continue;
+            }
+            if (isEmpty)
+                continue;
+            // Convert ObjectFieldSchema inline rules to FieldValidationRules
+            const rules = {
+                min: prop.min,
+                max: prop.max,
+                minLength: prop.minLength,
+                maxLength: prop.maxLength,
+                pattern: prop.pattern,
+                patternMessage: prop.patternMessage,
+            };
+            // Validate the property value
+            const error = validateFieldValue(value, rules, prop.fieldType);
+            if (error) {
+                errors.push({ ...error, field: propPath });
+            }
+        }
+        // Cross-property comparisons within the same object item
+        // e.g., checkOutDate > checkInDate within each reservation
+        for (const prop of schema) {
+            const value = obj[prop.key];
+            if (value === null || value === undefined || value === '')
+                continue;
+            // ObjectFieldSchema doesn't currently have comparisons, but we could
+            // validate date fields against 'now' using minDate/maxDate if we extend the schema
+        }
+    });
+    return errors;
+};
+// ============================================================================
+// Full Data Validation
+// ============================================================================
+/**
+ * Validate all fields in a data object against their definitions.
+ * Runs both single-field and comparison validations.
+ *
+ * @param data - The data object to validate
+ * @param definitions - Field definitions with validation rules
+ * @returns Array of all validation errors
+ */
+const validateAllFields = (data, definitions) => {
+    const errors = [];
+    const definitionMap = new Map(definitions.map(d => [d.key, d]));
+    for (const [key, value] of Object.entries(data)) {
+        const def = definitionMap.get(key);
+        if (!def)
+            continue;
+        // Single-field validation
+        const error = validateFieldValue(value, def.validation, def.fieldType);
+        if (error) {
+            errors.push({ ...error, field: key });
+        }
+        // Comparison validation
+        if (def.validation?.comparisons) {
+            const comparisonErrors = validateFieldComparisons(key, value, def.validation.comparisons, data, def.fieldType);
+            errors.push(...comparisonErrors);
+        }
+        // Object array item validation (validate each item's properties against objectSchema)
+        if (def.fieldType === 'objectArray' && def.objectSchema && Array.isArray(value)) {
+            const itemErrors = validateObjectArrayItems(key, value, def.objectSchema);
+            errors.push(...itemErrors);
+        }
+    }
+    return errors;
+};
+
+/**
+ * Built-in user profile fields that can be required for redemptions.
+ * These are a subset of UserModelField - excludes 'id' and 'identifierEmail'
+ * since those are system-managed, not user-fillable profile fields.
+ *
+ * Used for:
+ * - RedemptionType base required fields (RedemptionType.baseRequiredUserFields)
+ * - Redemption specific required fields (Redemption.specificRequiredUserFields)
+ * - User profile validation before redemption claims
+ * - Form generation for missing field prompts
+ */
+// Fields that can be required for user profile validation (excludes system fields)
+const builtInUserFieldsArray = [
+    'email',
+    'firstName',
+    'lastName',
+    'externalId',
+    'instagramAccountId',
+    'googleAccountName',
+];
+// Export the array for iteration
+const builtInUserFields = [...builtInUserFieldsArray];
+/**
+ * Static metadata mapping for all built-in user fields.
+ * Used by validation services and UI form generation.
+ */
+const builtInUserFieldMetadata = {
+    email: {
+        label: 'Email Address',
+        description: 'User email address',
+        fieldType: 'email',
+    },
+    firstName: {
+        label: 'First Name',
+        description: 'User first name',
+        fieldType: 'text',
+    },
+    lastName: {
+        label: 'Last Name',
+        description: 'User last name',
+        fieldType: 'text',
+    },
+    externalId: {
+        label: 'External ID',
+        description: 'External identifier from third-party system',
+        fieldType: 'text',
+    },
+    instagramAccountId: {
+        label: 'Instagram Account',
+        description: 'Instagram account ID',
+        fieldType: 'text',
+    },
+    googleAccountName: {
+        label: 'Google Account',
+        description: 'Google account name',
+        fieldType: 'text',
+    },
+};
+/**
+ * Check if a string is a valid built-in user field
+ */
+const isBuiltInUserField = (value) => {
+    return builtInUserFields.includes(value);
+};
+const getBuiltInFieldDefinition = (field) => {
+    if (!isBuiltInUserField(field)) {
+        return null;
+    }
+    const metadata = builtInUserFieldMetadata[field];
+    const sortOrder = builtInUserFields.indexOf(field);
+    return {
+        id: `builtin:${field}`,
+        tenantId: null,
+        entityType: 'user',
+        key: field,
+        label: metadata.label,
+        description: metadata.description,
+        fieldType: metadata.fieldType,
+        objectSchema: null,
+        selectOptions: null,
+        selectOptionsSource: null,
+        validation: null,
+        sortOrder,
+        createdAt: null,
+        updatedAt: null,
+        isBuiltIn: true,
+    };
+};
+/**
+ * Get all built-in field definitions as an array.
+ * Useful for populating field definitions list.
+ */
+const getAllBuiltInFieldDefinitions = () => {
+    return builtInUserFields.map(field => getBuiltInFieldDefinition(field));
+};
+/**
+ * Entity types for custom fields and dynamic select options.
+ * Used for both field definitions (entityType) and select option sources.
+ * - 'user': User profile fields (stored in user.customData)
+ * - 'business': Business profile fields (stored in business.customData)
+ * - 'campaign': Campaign-specific custom fields
+ * - 'redemption': Redemption-specific custom fields
+ */
+const customFieldEntityTypesArray = ['user', 'business', 'campaign', 'redemption'];
+/** All supported custom field entity types for iteration/validation */
+const customFieldEntityTypes = [...customFieldEntityTypesArray];
+
 /**
  * Core Entity Types
  *
@@ -3344,119 +3971,17 @@ function isPingMessage(msg) {
     return msg.type === 'ping';
 }
 
-const apiPublicKeyTestPrefix = 'pk_test_';
-const testnetPrefix = 'testnet-';
-const testnetShortPrefix = 'tn-';
-
-// Define the keys as a constant array
-const uniqueUserIdentifierKeysArray = [
-    'id',
-    'email',
-    'identifierEmail',
-    'instagramAccountId',
-    'externalId', // This is a special key that can be used to search all fields
-];
-// Export the array
-const uniqueUserIdentifierKeys = [...uniqueUserIdentifierKeysArray];
-// Define identifier type configurations
-const identifierTypes = {
-    id: {
-        key: 'id',
-        detect: (value) => /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(value), // UUID pattern
-        process: (value) => value
-    },
-    email: {
-        key: 'email',
-        detect: (value) => /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(value),
-        process: (value) => value
-    },
-    instagramAccountId: {
-        key: 'instagramAccountId',
-        detect: (value) => /^@/.test(value) || value.toLowerCase().includes('instagram'),
-        process: (value) => value.replace(/^@/, '') // Remove @ if present for consistency
-    },
-    externalId: {
-        key: 'externalId',
-        detect: () => true, // Default fallback
-        process: (value) => value
-    }
-};
-/**
- * Register a new identifier type configuration
- * @param key The identifier key
- * @param config The identifier configuration (without the key)
- */
-const registerIdentifierType = (key, config) => {
-    if (!uniqueUserIdentifierKeysArray.includes(key)) {
-        console.warn(`Warning: Registering identifier type '${key}' that is not in uniqueUserIdentifierKeys`);
-    }
-    identifierTypes[key] = {
-        key,
-        ...config
-    };
-};
 /**
- * Detects the type of identifier from a wildcard input
- * @param wildcardValue The value to analyze
- * @returns Object containing the type and processed value
+ * Check if a string matches UUID format
  */
-const detectIdentifierType = (wildcardValue) => {
-    if (wildcardValue === null || wildcardValue === undefined) {
-        return { type: 'externalId', value: '' };
-    }
-    const value = String(wildcardValue);
-    // Try each identifier type in priority order (id first to catch UUIDs)
-    for (const type of ['id', 'email', 'instagramAccountId', 'externalId']) {
-        const config = identifierTypes[type];
-        if (config.detect(value)) {
-            return { type, value: config.process(value) };
-        }
-    }
-    // Default fallback should never be reached due to externalId's detect always returning true
-    return { type: 'externalId', value };
-};
-/**
- * Checks if an object is a properly formed UserIdentifierObject
- * @param obj Object to check
- * @returns Boolean indicating if the object is a UserIdentifierObject
- */
-const isUserIdentifierObject = (obj) => {
-    return obj &&
-        obj.type === 'identifierObject' &&
-        uniqueUserIdentifierKeys.every(key => key in obj);
-};
-/**
- * Creates a UserIdentifierObject with all required fields, setting missing values to null
- * @param params Partial parameters for the identifier object
- * @returns A properly formed UserIdentifierObject
- */
-const createUserIdentifierObject = (params) => {
-    // Extract the wildcard or use empty string
-    const wildcard = params.wildcard || '';
-    // Create base object with all identifier fields set to null
-    const identifierObject = {
-        type: 'identifierObject',
-        id: null,
-        email: null,
-        instagramAccountId: null,
-        externalId: null,
-        identifierEmail: null,
-        wildcard
-    };
-    // Override nulls with any provided values
-    uniqueUserIdentifierKeys.forEach(key => {
-        if (params[key]) {
-            identifierObject[key] = params[key];
-        }
-    });
-    // If wildcard is provided but no specific fields, auto-detect the field type
-    if (wildcard && !params.id && !params.email && !params.instagramAccountId && !params.externalId) {
-        const detected = detectIdentifierType(wildcard);
-        identifierObject[detected.type] = detected.value;
-    }
-    return identifierObject;
+const isUUID = (value) => {
+    return /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(value);
 };
 
+const apiPublicKeyTestPrefix = 'pk_test_';
+const testnetPrefix = 'testnet-';
+const testnetShortPrefix = 'tn-';
+
 // Use this pattern:
 const NativeTokenTypes = {
     ERC20: 'ERC20', // default; should be used for fungible tokens eg. credit tokens; There should be only one active ERC20 token per programme
@@ -3557,7 +4082,8 @@ function isValidTransactionRelation(value) {
 const VALID_CAMPAIGN_RELATIONS = [
     'triggerSources',
     'businesses',
-    'claimCount'
+    'claimCount',
+    'ownerBusiness'
 ];
 /**
  * Type guard to validate campaign include relation at runtime
@@ -3595,7 +4121,9 @@ function isValidCampaignClaimRelation(value) {
  * Used for runtime validation
  */
 const VALID_REDEMPTION_RELATIONS = [
-    'redeemCount'
+    'redeemCount',
+    'ownerBusiness',
+    'requiredUserFieldDefinitions'
 ];
 /**
  * Type guard to validate redemption include relation at runtime
@@ -3653,6 +4181,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.
@@ -3673,6 +4221,134 @@ function normalizeFilters(filters) {
     };
 }
 
+/**
+ * Analytics Constants
+ *
+ * Shared definitions for consistent analytics across frontend and backend.
+ */
+/**
+ * Active User Definition
+ *
+ * A user qualifies as "active" in a given period if they performed
+ * any of the qualifying actions during that period.
+ *
+ * @example
+ * // Display in UI
+ * `${engagementRate}% engagement. ${ACTIVE_USER_DEFINITION.description}`
+ *
+ * // Result: "25.5% engagement. Active = sent transaction, claimed, or redeemed in period"
+ */
+const ACTIVE_USER_DEFINITION = {
+    /** Actions that qualify a user as "active" */
+    qualifyingActions: ['TRANSACTION_SEND', 'CLAIM_COMPLETED', 'REDEMPTION_COMPLETED'],
+    /** Short description for UI display */
+    description: 'Active = sent transaction, claimed, or redeemed in period',
+    /** Detailed explanation for tooltips/documentation */
+    details: {
+        TRANSACTION_SEND: 'User initiated a transaction (spending, transferring, or purchasing)',
+        CLAIM_COMPLETED: 'User successfully claimed a campaign reward',
+        REDEMPTION_COMPLETED: 'User successfully redeemed an offer',
+    },
+    /** What does NOT count as active */
+    excluded: [
+        'Receiving tokens (passive)',
+        'Failed or pending claims/redemptions',
+        'System-generated transactions (REDEMPTION_RECEIVE)',
+    ],
+};
+/**
+ * Engagement rate formula
+ * engagementRate = (activeUsers / totalUsers) × 100
+ */
+const ENGAGEMENT_RATE_FORMULA = 'activeUsers / totalUsers × 100';
+/**
+ * Transaction statuses that count for analytics
+ */
+const ANALYTICS_VALID_TRANSACTION_STATUSES = ['SUCCEEDED', 'BROADCASTED'];
+/**
+ * Process statuses that count for analytics (claims, redemptions)
+ */
+const ANALYTICS_VALID_PROCESS_STATUS = 'COMPLETED';
+
+/**
+ * Image CDN Configuration
+ *
+ * Shared constants and types for Image CDN (CloudFront + Lambda@Edge)
+ * Used by backend Lambda handler and frontend SDKs.
+ *
+ * @see documentation/api-docs/image-cdn.md
+ */
+// ============================================
+// CONSTANTS
+// ============================================
+/** Maximum output dimension when no preset specified */
+const IMAGE_CDN_MAX_DIMENSION = 2048;
+/** Default quality percentage */
+const IMAGE_CDN_DEFAULT_QUALITY = 80;
+/** Default fit mode */
+const IMAGE_CDN_DEFAULT_FIT = 'inside';
+/** Default format (auto-detect based on browser Accept header) */
+const IMAGE_CDN_DEFAULT_FORMAT = 'auto';
+/** Available presets with their dimensions */
+const IMAGE_CDN_PRESETS = {
+    thumb: { width: 150, height: 150 },
+    medium: { width: 600, height: 600 },
+    large: { width: 1200, height: 1200 },
+    hero: { width: 1920, height: 800 },
+    avatar: { width: 200, height: 200 },
+    card: { width: 400, height: 300 },
+};
+/** Supported input/output formats */
+const IMAGE_CDN_SUPPORTED_FORMATS = ['jpeg', 'jpg', 'png', 'webp', 'gif', 'avif'];
+/** Cache TTL in seconds (1 year) */
+const IMAGE_CDN_CACHE_TTL = 31536000;
+/** Maximum input file size in bytes (10MB) */
+const IMAGE_CDN_MAX_INPUT_SIZE = 10 * 1024 * 1024;
+// ============================================
+// HELPER FUNCTIONS
+// ============================================
+/**
+ * Build CDN URL with options
+ *
+ * @example
+ * buildImageCdnUrl('https://cdn.example.com/photo.jpg', { preset: 'thumb' })
+ * // => 'https://cdn.example.com/photo.jpg?preset=thumb'
+ *
+ * buildImageCdnUrl('https://cdn.example.com/photo.jpg', { preset: 'large', q: 95 })
+ * // => 'https://cdn.example.com/photo.jpg?preset=large&q=95'
+ */
+function buildImageCdnUrl(baseUrl, options = {}) {
+    const params = new URLSearchParams();
+    if (options.preset)
+        params.set('preset', options.preset);
+    if (options.q !== undefined)
+        params.set('q', options.q.toString());
+    if (options.f)
+        params.set('f', options.f);
+    if (options.fit)
+        params.set('fit', options.fit);
+    const query = params.toString();
+    return query ? `${baseUrl}?${query}` : baseUrl;
+}
+/**
+ * Check if a preset name is valid
+ */
+function isValidPreset(preset) {
+    return preset in IMAGE_CDN_PRESETS;
+}
+/**
+ * Get dimensions for a preset
+ */
+function getPresetDimensions(preset) {
+    return IMAGE_CDN_PRESETS[preset];
+}
+/**
+ * Check if a file extension is a supported image format
+ */
+function isSupportedImageFormat(extension) {
+    return IMAGE_CDN_SUPPORTED_FORMATS.includes(extension.toLowerCase());
+}
+
 /**
  * Chain Data Types
  *
@@ -3807,6 +4483,12 @@ const CommonErrorCodes = {
     FIREBASE_AUTH_ERROR: 'FIREBASE_AUTH_ERROR',
     MULTIPLE_CONTEXT_SELECTION_REQUIRED: 'MULTIPLE_CONTEXT_SELECTION_REQUIRED',
     ADMIN_TENANT_REQUIRED: 'ADMIN_TENANT_REQUIRED',
+    // Magic link errors
+    MAGIC_LINK_EMAIL_SEND_FAILED: 'MAGIC_LINK_EMAIL_SEND_FAILED',
+    MAGIC_LINK_EMAIL_MISMATCH: 'MAGIC_LINK_EMAIL_MISMATCH',
+    MAGIC_LINK_VERIFICATION_FAILED: 'MAGIC_LINK_VERIFICATION_FAILED',
+    // Rate limiting (generic)
+    RATE_LIMITED: 'RATE_LIMITED',
     // Generic fallbacks
     INTERNAL_ERROR: 'INTERNAL_ERROR',
     VALIDATION_ERROR: 'VALIDATION_ERROR',
@@ -5166,30 +5848,30 @@ class TokenApi {
         return this.apiClient.get(url);
     }
     /**
-     * Get all token metadata with filtering and pagination
+     * 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 and pagination options
+     * @param options - Filter, pagination, and include options
      * @returns Paginated response with token metadata
      *
-     * @example Get all active rewards
+     * @example Get all active rewards with mint/burn counts
      * ```typescript
      * const rewards = await tokenApi.getTokenMetadata({
      *   tokenType: 'ERC1155',
      *   active: true,
-     *   limit: 10
+     *   limit: 10,
+     *   include: ['mintCount', 'burnCount', 'token']
      * });
      * ```
      *
-     * @example Get stamps with search
+     * @example Get stamps with owner business included
      * ```typescript
      * const stamps = await tokenApi.getTokenMetadata({
      *   tokenType: 'ERC721',
      *   search: 'gold',
-     *   sortBy: 'name',
-     *   sortOrder: 'ASC'
+     *   include: ['ownerBusiness', 'token']
      * });
      * ```
      */
@@ -5214,6 +5896,14 @@ class TokenApi {
                 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);
     }
@@ -5273,6 +5963,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}`);
+    }
 }
 
 /**
@@ -5327,35 +6041,57 @@ class TokenService {
         return this.tokenApi.getTokenByContractAddress(contractAddress, contractTokenId);
     }
     /**
-     * Get all token metadata with filtering and pagination
+     * 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 and pagination options
+     * @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 and pagination
+     * Get rewards (ERC1155 token metadata) with filtering, pagination, and include relations
      *
      * Convenience method for fetching reward metadata.
      *
-     * @param options - Filter and pagination options (tokenType is set automatically)
+     * @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 and pagination
+     * Get stamps (ERC721 token metadata) with filtering, pagination, and include relations
      *
      * Convenience method for fetching stamp metadata.
      *
-     * @param options - Filter and pagination options (tokenType is set automatically)
+     * @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 });
@@ -5412,6 +6148,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);
+    }
 }
 
 /**
@@ -5514,6 +6261,10 @@ class BusinessApi {
      *
      * // 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) {
@@ -5536,6 +6287,22 @@ class BusinessApi {
         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);
     }
@@ -7237,6 +8004,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
      */
@@ -9172,7 +9945,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
@@ -9186,6 +9959,12 @@ class TriggerSourceApi {
      *   page: 1,
      *   limit: 20
      * });
+     *
+     * // Filter by location (geocoding)
+     * const dubaiSources = await triggerSourceApi.getTriggerSources({
+     *   city: 'Dubai',
+     *   countryCode: 'AE'
+     * });
      * ```
      */
     async getTriggerSources(options) {
@@ -9198,6 +9977,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);
     }
@@ -9782,6 +10574,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() {
@@ -9934,6 +10729,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.
@@ -10034,11 +10831,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;
+        }
     }
 }
 
@@ -10844,7 +11657,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.2.0-alpha.1";
 /** Full SDK identifier for headers */
 const SDK_USER_AGENT = `${SDK_NAME}/${SDK_VERSION}`;
 
@@ -10954,12 +11767,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),
@@ -10987,49 +11804,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);
             }
@@ -12542,10 +13373,11 @@ class UserStatusManager {
  * ```
  */
 class TokenManager {
-    constructor(apiClient) {
+    constructor(apiClient, eventEmitter) {
         this.apiClient = apiClient;
         const tokenApi = new TokenApi(apiClient);
         this.tokenService = new TokenService(tokenApi);
+        this.eventEmitter = eventEmitter;
     }
     /**
      * Get all available tokens
@@ -12694,16 +13526,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',
@@ -12711,19 +13544,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}`);
      * });
      * ```
      */
@@ -12731,31 +13571,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}`);
+     *   }
      * });
      * ```
      */
@@ -12763,31 +13599,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}`);
+     *   }
      * });
      * ```
      */
@@ -12885,6 +13717,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
      *
@@ -15278,6 +16136,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
      *
@@ -19305,6 +20178,429 @@ class WalletEventsManager {
     }
 }
 
+/**
+ * Custom Field Definitions API
+ *
+ * Low-level API for custom field definition CRUD operations.
+ * Used internally by CustomFieldDefinitionManager.
+ *
+ * @internal
+ */
+class CustomFieldApi {
+    constructor(apiClient) {
+        this.apiClient = apiClient;
+        this.basePath = '/custom-field-definitions';
+    }
+    /**
+     * List all custom field definitions
+     * Backend returns non-paginated array sorted by sortOrder
+     */
+    async getDefinitions(entityType) {
+        const params = new URLSearchParams();
+        if (entityType) {
+            params.append('entityType', entityType);
+        }
+        const query = params.toString();
+        const url = query ? `${this.basePath}?${query}` : this.basePath;
+        return this.apiClient.get(url);
+    }
+    /**
+     * Get a single custom field definition by ID
+     */
+    async getDefinition(id) {
+        return this.apiClient.get(`${this.basePath}/${id}`);
+    }
+    /**
+     * Create a new custom field definition
+     */
+    async createDefinition(data) {
+        return this.apiClient.post(this.basePath, data);
+    }
+    /**
+     * Update an existing custom field definition
+     */
+    async updateDefinition(id, data) {
+        return this.apiClient.put(`${this.basePath}/${id}`, data);
+    }
+    /**
+     * Delete a custom field definition
+     */
+    async deleteDefinition(id) {
+        return this.apiClient.delete(`${this.basePath}/${id}`);
+    }
+    /**
+     * Get usage count for a field definition
+     */
+    async getUsages(id) {
+        return this.apiClient.get(`${this.basePath}/${id}/usages`);
+    }
+    /**
+     * Resolve dynamic select options for a field
+     */
+    async resolveSelectOptions(id) {
+        return this.apiClient.get(`${this.basePath}/${id}/options`);
+    }
+}
+
+/**
+ * Custom Field Definition Manager - Manage tenant-specific custom fields
+ *
+ * Provides CRUD operations for custom field definitions that extend the built-in
+ * user profile fields. Custom fields are defined per-tenant and can be used for
+ * additional user data collection, redemption requirements, and form validation.
+ *
+ * @group Managers
+ * @category Custom Fields
+ *
+ * @example Basic Operations
+ * ```typescript
+ * // List all user custom fields
+ * const fields = await sdk.customFields.getDefinitions();
+ *
+ * // Create a new custom field
+ * const field = await sdk.customFields.createDefinition({
+ *   key: 'employee_id',
+ *   label: 'Employee ID',
+ *   fieldType: 'text',
+ *   validation: { required: true, pattern: '^E[0-9]{5}$' }
+ * });
+ *
+ * // Update a field
+ * await sdk.customFields.updateDefinition(field.id, {
+ *   label: 'Company Employee ID'
+ * });
+ *
+ * // Delete a field
+ * await sdk.customFields.deleteDefinition(field.id);
+ * ```
+ *
+ * @example Validation
+ * ```typescript
+ * // Validate user custom data against definitions
+ * const definitions = await sdk.customFields.getDefinitions();
+ * const errors = sdk.customFields.validateUserData(
+ *   { employee_id: 'INVALID' },
+ *   definitions
+ * );
+ * if (errors.length > 0) {
+ *   console.log('Validation errors:', errors);
+ * }
+ * ```
+ */
+class CustomFieldDefinitionManager {
+    constructor(apiClient, events) {
+        this.events = events;
+        this.api = new CustomFieldApi(apiClient);
+    }
+    /**
+     * List all custom field definitions for the tenant
+     *
+     * Retrieves all custom field definitions, optionally filtered by entity type.
+     * Results are sorted by sortOrder (ascending).
+     *
+     * @param options - Query options including entity type filter
+     * @returns Array of custom field definitions
+     *
+     * @example List All User Fields
+     * ```typescript
+     * const fields = await sdk.customFields.getDefinitions();
+     * console.log(`Found ${fields.length} custom fields`);
+     *
+     * fields.forEach(field => {
+     *   console.log(`${field.key}: ${field.label} (${field.fieldType})`);
+     * });
+     * ```
+     *
+     * @example Filter by Entity Type
+     * ```typescript
+     * // Get only business custom fields
+     * const businessFields = await sdk.customFields.getDefinitions({
+     *   entityType: 'business'
+     * });
+     * ```
+     */
+    async getDefinitions(options) {
+        return this.api.getDefinitions(options?.entityType);
+    }
+    /**
+     * Get a single custom field definition by ID
+     *
+     * @param id - The UUID of the custom field definition
+     * @returns The custom field definition
+     * @throws {PersApiError} When definition not found (404)
+     *
+     * @example
+     * ```typescript
+     * try {
+     *   const field = await sdk.customFields.getDefinition('uuid-here');
+     *   console.log('Field:', field.label);
+     * } catch (error) {
+     *   if (error.statusCode === 404) {
+     *     console.log('Field not found');
+     *   }
+     * }
+     * ```
+     */
+    async getDefinition(id) {
+        return this.api.getDefinition(id);
+    }
+    /**
+     * Create a new custom field definition
+     *
+     * Creates a new custom field for the tenant. The field key must be unique
+     * within the tenant and entity type combination.
+     *
+     * @param data - The field definition data
+     * @returns The created custom field definition
+     * @throws {PersApiError} When key already exists (409) or validation fails (400)
+     *
+     * @example Text Field with Pattern
+     * ```typescript
+     * const employeeIdField = await sdk.customFields.createDefinition({
+     *   key: 'employee_id',
+     *   label: 'Employee ID',
+     *   description: 'Your company employee ID (E + 5 digits)',
+     *   fieldType: 'text',
+     *   validation: {
+     *     required: true,
+     *     pattern: '^E[0-9]{5}$',
+     *     patternMessage: 'Must be E followed by 5 digits'
+     *   },
+     *   sortOrder: 1
+     * });
+     * ```
+     *
+     * @example Date Field with Comparison
+     * ```typescript
+     * const checkOutField = await sdk.customFields.createDefinition({
+     *   key: 'check_out',
+     *   label: 'Check-out Date',
+     *   fieldType: 'date',
+     *   validation: {
+     *     required: true,
+     *     comparisons: [
+     *       { field: 'check_in', operator: '>', message: 'Must be after check-in' }
+     *     ]
+     *   },
+     *   sortOrder: 2
+     * });
+     * ```
+     *
+     * @example Select Field with Static Options
+     * ```typescript
+     * const departmentField = await sdk.customFields.createDefinition({
+     *   key: 'department',
+     *   label: 'Department',
+     *   fieldType: 'select',
+     *   selectOptions: [
+     *     { value: 'engineering', label: 'Engineering' },
+     *     { value: 'sales', label: 'Sales' },
+     *     { value: 'hr', label: 'Human Resources' }
+     *   ],
+     *   validation: { required: true }
+     * });
+     * ```
+     *
+     * @example Select Field with Dynamic Options
+     * ```typescript
+     * const hotelField = await sdk.customFields.createDefinition({
+     *   key: 'preferred_hotel',
+     *   label: 'Preferred Hotel',
+     *   fieldType: 'select',
+     *   selectOptionsSource: {
+     *     entity: 'business',
+     *     valueField: 'id',
+     *     labelField: 'name',
+     *     filter: { tags: ['hotel'], isActive: true }
+     *   },
+     *   validation: { required: true }
+     * });
+     * ```
+     */
+    async createDefinition(data) {
+        const result = await this.api.createDefinition(data);
+        // Using 'user' domain until pers-shared adds 'customField' domain
+        this.events?.emitSuccess({
+            domain: 'user',
+            type: 'definition_created',
+            userMessage: `Custom field "${result.label}" created`,
+            details: { id: result.id, key: result.key }
+        });
+        return result;
+    }
+    /**
+     * Update an existing custom field definition
+     *
+     * Updates a custom field definition. Note that key and entityType cannot
+     * be changed after creation.
+     *
+     * @param id - The UUID of the custom field definition to update
+     * @param data - The fields to update (partial update supported)
+     * @returns The updated custom field definition
+     * @throws {PersApiError} When definition not found (404) or validation fails (400)
+     *
+     * @example Update Label and Validation
+     * ```typescript
+     * const updated = await sdk.customFields.updateDefinition('uuid-here', {
+     *   label: 'Employee ID (Required)',
+     *   validation: {
+     *     required: true,
+     *     minLength: 6,
+     *     maxLength: 6
+     *   }
+     * });
+     * ```
+     *
+     * @example Update Sort Order
+     * ```typescript
+     * await sdk.customFields.updateDefinition('uuid-here', {
+     *   sortOrder: 5
+     * });
+     * ```
+     */
+    async updateDefinition(id, data) {
+        const result = await this.api.updateDefinition(id, data);
+        // Using 'user' domain until pers-shared adds 'customField' domain
+        this.events?.emitSuccess({
+            domain: 'user',
+            type: 'definition_updated',
+            userMessage: `Custom field "${result.label}" updated`,
+            details: { id: result.id, key: result.key }
+        });
+        return result;
+    }
+    /**
+     * Delete a custom field definition (soft delete)
+     *
+     * Soft deletes a custom field definition. Existing user data in customData
+     * is preserved, but the field will no longer appear in forms or validation.
+     *
+     * ⚠️ Consider the impact on existing user data before deleting.
+     *
+     * @param id - The UUID of the custom field definition to delete
+     * @throws {PersApiError} When definition not found (404)
+     *
+     * @example
+     * ```typescript
+     * try {
+     *   await sdk.customFields.deleteDefinition('uuid-here');
+     *   console.log('Field deleted');
+     * } catch (error) {
+     *   console.log('Failed to delete:', error.message);
+     * }
+     * ```
+     */
+    async deleteDefinition(id) {
+        await this.api.deleteDefinition(id);
+        // Using 'user' domain until pers-shared adds 'customField' domain
+        this.events?.emitSuccess({
+            domain: 'user',
+            type: 'definition_deleted',
+            userMessage: 'Custom field deleted',
+            details: { id }
+        });
+    }
+    /**
+     * Resolve dynamic select options for a field
+     *
+     * For fields with selectOptionsSource (dynamic options from entities),
+     * this resolves the actual options by querying the source entity.
+     *
+     * @param id - The UUID of the custom field definition
+     * @returns Array of select options
+     *
+     * @example
+     * ```typescript
+     * const field = await sdk.customFields.getDefinition('hotel-field-id');
+     *
+     * if (field.selectOptionsSource) {
+     *   // Options come from entity - need to resolve
+     *   const options = await sdk.customFields.resolveSelectOptions(field.id);
+     *   console.log('Available hotels:', options);
+     * } else {
+     *   // Static options
+     *   console.log('Options:', field.selectOptions);
+     * }
+     * ```
+     */
+    async resolveSelectOptions(id) {
+        const response = await this.api.resolveSelectOptions(id);
+        return response.options;
+    }
+    /**
+     * Validate user custom data against field definitions
+     *
+     * Client-side validation using the same rules as the backend. Use this
+     * to validate form data before submission.
+     *
+     * @param data - User's custom data (key-value pairs)
+     * @param definitions - Custom field definitions to validate against
+     * @returns Array of validation errors (empty if valid)
+     *
+     * @example Form Validation
+     * ```typescript
+     * const definitions = await sdk.customFields.getDefinitions();
+     * const formData = {
+     *   employee_id: 'E123', // Missing a digit
+     *   department: 'engineering'
+     * };
+     *
+     * const errors = sdk.customFields.validateUserData(formData, definitions);
+     * if (errors.length > 0) {
+     *   errors.forEach(err => {
+     *     console.log(`${err.field}: ${err.message}`);
+     *   });
+     *   return; // Don't submit
+     * }
+     *
+     * // No errors, safe to submit
+     * await sdk.users.updateCurrentUser({ customData: formData });
+     * ```
+     */
+    validateUserData(data, definitions) {
+        // Convert CustomFieldDefinitionDTO to FieldDefinition for validation
+        const fieldDefinitions = definitions.map(def => ({
+            key: def.key,
+            fieldType: def.fieldType,
+            label: def.label,
+            validation: def.validation ?? undefined,
+        }));
+        return validateAllFields(data, fieldDefinitions);
+    }
+    /**
+     * Validate a single field value
+     *
+     * Validates a single value against a field's rules. Useful for
+     * real-time validation as the user types.
+     *
+     * @param value - The value to validate
+     * @param definition - The field definition
+     * @returns Validation error or null if valid
+     *
+     * @example Real-time Validation
+     * ```typescript
+     * const employeeIdField = definitions.find(d => d.key === 'employee_id');
+     *
+     * const handleBlur = (value: string) => {
+     *   const error = sdk.customFields.validateFieldValue(value, employeeIdField);
+     *   if (error) {
+     *     setFieldError('employee_id', error.message);
+     *   } else {
+     *     clearFieldError('employee_id');
+     *   }
+     * };
+     * ```
+     */
+    validateFieldValue(value, definition) {
+        const error = validateFieldValue(value, definition.validation ?? null, definition.fieldType);
+        if (error) {
+            // Add field key to error
+            return { ...error, field: definition.key };
+        }
+        return null;
+    }
+}
+
 /**
  * @fileoverview PERS SDK - Platform-agnostic TypeScript SDK with High-Level Managers
  *
@@ -19748,7 +21044,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;
     }
@@ -19993,6 +21289,37 @@ class PersSDK {
         }
         return this._webhooks;
     }
+    /**
+     * Custom Field Definition Manager - Manage tenant-specific custom fields
+     *
+     * Provides CRUD operations for custom field definitions that extend the built-in
+     * user profile fields. Custom fields are tenant-specific and support validation.
+     *
+     * @returns CustomFieldDefinitionManager instance
+     *
+     * @example Basic Operations
+     * ```typescript
+     * // List all custom fields
+     * const fields = await sdk.customFields.getDefinitions();
+     *
+     * // Create a new field
+     * const field = await sdk.customFields.createDefinition({
+     *   key: 'employee_id',
+     *   label: 'Employee ID',
+     *   fieldType: 'text',
+     *   validation: { required: true }
+     * });
+     *
+     * // Validate user data
+     * const errors = sdk.customFields.validateUserData(formData, fields.data);
+     * ```
+     */
+    get customFields() {
+        if (!this._customFields) {
+            this._customFields = new CustomFieldDefinitionManager(this.apiClient, this._events);
+        }
+        return this._customFields;
+    }
     /**
      * Wallet Events Manager - Real-time blockchain events for user's wallets
      *
@@ -40680,6 +42007,122 @@ function spelunkMessage(value) {
     return result;
 }
 
+/**
+ * Get multiple ERC-1155 token balances using native balanceOfBatch function.
+ * This is the most efficient method - it's built into the ERC-1155 standard.
+ *
+ * @param contract - ERC-1155 contract instance
+ * @param accountAddress - Account to check balances for
+ * @param tokenIds - Array of tokenIds to check
+ * @returns Array of BatchBalanceResult with balance for each tokenId
+ *
+ * @example
+ * ```typescript
+ * const results = await getERC1155BalanceOfBatch(
+ *   contract,
+ *   '0xabc...',
+ *   ['1', '2', '3', '4', '5']
+ * );
+ * // 1 RPC call returns all balances
+ * ```
+ */
+async function getERC1155BalanceOfBatch(contract, accountAddress, tokenIds) {
+    if (tokenIds.length === 0) {
+        return [];
+    }
+    try {
+        // ERC-1155 balanceOfBatch requires arrays of same length
+        // accounts[i] corresponds to ids[i]
+        const accounts = tokenIds.map(() => accountAddress);
+        // Call native balanceOfBatch - 1 RPC call for ALL tokenIds
+        const balances = await contract.balanceOfBatch(accounts, tokenIds);
+        return tokenIds.map((tokenId, index) => ({
+            tokenId,
+            balance: balances[index],
+            success: true
+        }));
+    }
+    catch (error) {
+        console.warn('[ERC1155] balanceOfBatch failed:', error);
+        return tokenIds.map(tokenId => ({
+            tokenId,
+            balance: 0n,
+            success: false,
+            error: `balanceOfBatch failed: ${error}`
+        }));
+    }
+}
+/**
+ * Get multiple token balances for ERC-1155 contracts.
+ * Uses the native balanceOfBatch function (1 RPC call for ALL tokens).
+ * Falls back to individual calls only if balanceOfBatch fails.
+ *
+ * @param provider - Ethers provider
+ * @param contractAddress - Token contract address
+ * @param contractInterface - Contract interface (must include balanceOfBatch for ERC-1155)
+ * @param accountAddress - Account to check balances for
+ * @param tokenIds - Array of tokenIds to check
+ * @param isERC1155 - Whether the contract is ERC-1155 (default: true)
+ * @returns Array of BatchBalanceResult
+ */
+async function getBatchBalancesWithFallback(provider, contractAddress, contractInterface, accountAddress, tokenIds, isERC1155 = true) {
+    if (tokenIds.length === 0)
+        return [];
+    const contract = new Contract(contractAddress, contractInterface, provider);
+    // For single token, direct call is more efficient
+    if (tokenIds.length === 1) {
+        try {
+            const balance = isERC1155
+                ? await contract.balanceOf(accountAddress, tokenIds[0])
+                : await contract.balanceOf(accountAddress);
+            return [{
+                    tokenId: tokenIds[0],
+                    balance: balance,
+                    success: true
+                }];
+        }
+        catch (error) {
+            return [{
+                    tokenId: tokenIds[0],
+                    balance: 0n,
+                    success: false,
+                    error: `${error}`
+                }];
+        }
+    }
+    // For ERC-1155: Use native balanceOfBatch (1 RPC call for ALL tokens)
+    if (isERC1155) {
+        const results = await getERC1155BalanceOfBatch(contract, accountAddress, tokenIds);
+        // If native call succeeded, return results
+        if (results.some(r => r.success)) {
+            return results;
+        }
+        // Otherwise fall through to individual calls
+    }
+    // Fallback: individual calls in parallel (for non-ERC1155 or if balanceOfBatch failed)
+    const promises = tokenIds.map(async (tokenId) => {
+        try {
+            const balance = isERC1155
+                ? await contract.balanceOf(accountAddress, tokenId)
+                : await contract.balanceOf(accountAddress);
+            return {
+                tokenId,
+                balance: balance,
+                success: true
+            };
+        }
+        catch (error) {
+            return {
+                tokenId,
+                balance: 0n,
+                success: false,
+                error: `${error}`
+            };
+        }
+    });
+    return Promise.all(promises);
+}
+
 const PERS_STATUS_TOKEN_ETHERS_METHOD_BUILDER = (contract, methodName) => {
     try {
         // Use unknown first, then cast to the expected type
@@ -41291,7 +42734,10 @@ class TokenDomainService {
         try {
             const abi = convertAbiToInterface(params.abi);
             const analysis = this.contractService.analyzeContract(abi);
-            const batchSize = Math.min(params.batchSize || 10, 20); // Cap at 20 for safety
+            // ERC-1155 balanceOfBatch can handle large batches efficiently (1 RPC call)
+            // Default to 100 for ERC-1155, 20 for ERC-721 (which has no batch function)
+            const defaultBatchSize = analysis.isERC1155 ? 100 : 20;
+            const batchSize = Math.min(params.batchSize || defaultBatchSize, analysis.isERC1155 ? 200 : 50);
             // ERC-1155: Requires specific token IDs
             if (analysis.isERC1155) {
                 if (!params.tokenIds?.length) {
@@ -41345,31 +42791,44 @@ class TokenDomainService {
     async processTokenBatch(params, tokenIds, batchSize, tokenStandard) {
         const tokens = [];
         const errors = [];
+        const abi = convertAbiToInterface(params.abi);
         // Process in batches
         for (let i = 0; i < tokenIds.length; i += batchSize) {
             const batch = tokenIds.slice(i, i + batchSize);
-            // Step 1: Check balance for each token (handle ERC-721 vs ERC-1155 differences)
-            const balancePromises = batch.map(tokenId => {
-                if (tokenStandard === 'ERC-721') {
-                    // For ERC-721: Skip balance check, we know ownership from enumeration or explicit tokenIds
-                    return Promise.resolve({
-                        tokenId,
-                        balance: 1,
-                        hasBalance: true,
-                        metadata: null
-                    });
-                }
-                else {
-                    // For ERC-1155: Check actual balance
-                    return this.getTokenBalance({ ...params, tokenId })
-                        .catch(error => {
-                        errors.push(`${tokenId}: ${error.message}`);
-                        return null;
-                    });
-                }
-            });
-            const balanceResults = await Promise.all(balancePromises);
-            const validTokens = balanceResults.filter((token) => token !== null && token.hasBalance);
+            let validTokens;
+            if (tokenStandard === 'ERC-721') {
+                // For ERC-721: Skip balance check, we know ownership from enumeration or explicit tokenIds
+                validTokens = batch.map(tokenId => ({
+                    tokenId,
+                    balance: 1,
+                    hasBalance: true,
+                    metadata: null
+                }));
+            }
+            else {
+                // For ERC-1155: Use native balanceOfBatch (1 RPC call for entire batch)
+                const batchResults = await this.web3Api.getBatchTokenBalances({
+                    accountAddress: params.accountAddress,
+                    contractAddress: params.contractAddress,
+                    abi,
+                    tokenIds: batch,
+                    chainId: params.chainId,
+                    isERC1155: true
+                });
+                // Convert batch results to TokenBalance format
+                validTokens = batchResults
+                    .filter(r => r.success && r.balance > 0n)
+                    .map(r => ({
+                    tokenId: r.tokenId,
+                    balance: Number(r.balance),
+                    hasBalance: true,
+                    metadata: null
+                }));
+                // Track errors
+                batchResults.filter(r => !r.success).forEach(r => {
+                    errors.push(`${r.tokenId}: ${r.error}`);
+                });
+            }
             // Step 2: Get metadata for tokens that have balance
             if (validTokens.length > 0) {
                 const metadataPromises = validTokens.map(token => this.getTokenMetadata({
@@ -41493,6 +42952,627 @@ class ContractDomainService {
     }
 }
 
+/**
+ * TokenCollectionManager - Auto-refresh token collections on wallet events
+ *
+ * This manager provides:
+ * 1. Cached token collection storage with automatic refresh
+ * 2. Auto-subscription to wallet events (transfers, mints, burns)
+ * 3. Targeted invalidation based on contract address
+ * 4. Subscriber pattern for reactive updates
+ *
+ * @example
+ * ```typescript
+ * // Get from SDK
+ * const manager = sdk.tokens.collectionManager;
+ *
+ * // Subscribe to collection updates
+ * const unsubscribe = manager.subscribe((collection, contractAddress) => {
+ *   console.log(`Collection updated for ${contractAddress}`);
+ *   updateUI(collection);
+ * });
+ *
+ * // Fetch collection (auto-cached, auto-refreshed on wallet events)
+ * const collection = await manager.getCollection({
+ *   accountAddress: '0x...',
+ *   contractAddress: '0x...',
+ *   abi: contractAbi,
+ *   chainId: 39123,
+ *   tokenIds: ['1', '2', '3']
+ * });
+ *
+ * // Cleanup
+ * unsubscribe();
+ * ```
+ */
+/**
+ * Manages token collections with automatic refresh on wallet events
+ */
+class TokenCollectionManager {
+    constructor(tokenService, eventEmitter, config) {
+        this.tokenService = tokenService;
+        this.eventEmitter = eventEmitter;
+        this.collections = new Map();
+        this.handlers = new Set();
+        this.pendingRefresh = new Map();
+        this.config = {
+            autoRefreshOnWalletEvents: config?.autoRefreshOnWalletEvents ?? true,
+            eventDebounceMs: config?.eventDebounceMs ?? 500,
+            debug: config?.debug ?? false
+        };
+        if (this.config.autoRefreshOnWalletEvents && eventEmitter) {
+            this.setupEventSubscription();
+        }
+    }
+    /**
+     * Subscribe to wallet events for auto-refresh
+     */
+    setupEventSubscription() {
+        if (!this.eventEmitter) {
+            return;
+        }
+        this.eventUnsubscribe = this.eventEmitter.subscribe((event) => {
+            const contractAddress = event.details?.contractAddress;
+            this.handleWalletEvent(contractAddress, event.type);
+        }, { domains: ['wallet'] });
+    }
+    /**
+     * Get a token collection (cached, auto-refreshed on wallet events)
+     *
+     * @param params - Collection parameters
+     * @returns Promise resolving to the token collection
+     */
+    async getCollection(params) {
+        const key = this.getCacheKey(params);
+        const cached = this.collections.get(key);
+        // Return cached if available and not stale
+        if (cached?.lastCollection) {
+            this.log(`Cache HIT for ${key}`);
+            return cached.lastCollection;
+        }
+        this.log(`Cache MISS for ${key}, fetching...`);
+        return this.fetchAndCache(params);
+    }
+    /**
+     * Force refresh a specific collection
+     *
+     * @param contractAddress - Contract address to refresh
+     * @param accountAddress - Account address to refresh
+     * @returns Promise that resolves when refresh is complete
+     */
+    async refreshCollection(contractAddress, accountAddress) {
+        const toRefresh = [];
+        for (const [key, entry] of this.collections) {
+            if (entry.params.contractAddress === contractAddress) {
+                if (!accountAddress || entry.params.accountAddress === accountAddress) {
+                    toRefresh.push(key);
+                }
+            }
+        }
+        await Promise.all(toRefresh.map(key => {
+            const entry = this.collections.get(key);
+            if (entry) {
+                return this.refreshEntry(key, entry, 'refresh');
+            }
+        }));
+    }
+    /**
+     * Subscribe to collection change events
+     *
+     * @param handler - Callback when any tracked collection changes
+     * @returns Unsubscribe function
+     */
+    subscribe(handler) {
+        this.handlers.add(handler);
+        return () => this.handlers.delete(handler);
+    }
+    /**
+     * Get all currently tracked collections
+     */
+    getTrackedCollections() {
+        return Array.from(this.collections.entries()).map(([_, entry]) => ({
+            contractAddress: entry.params.contractAddress,
+            accountAddress: entry.params.accountAddress,
+            collection: entry.lastCollection
+        }));
+    }
+    /**
+     * Check if a collection is currently being tracked
+     */
+    isTracking(contractAddress, accountAddress) {
+        const key = `${contractAddress}:${accountAddress}`;
+        return this.collections.has(key);
+    }
+    /**
+     * Clear tracking for a specific collection
+     */
+    untrack(contractAddress, accountAddress) {
+        if (accountAddress) {
+            const key = `${contractAddress}:${accountAddress}`;
+            this.collections.delete(key);
+            this.log(`Untracked ${key}`);
+        }
+        else {
+            // Untrack all for this contract
+            for (const key of this.collections.keys()) {
+                if (key.startsWith(`${contractAddress}:`)) {
+                    this.collections.delete(key);
+                }
+            }
+            this.log(`Untracked all collections for ${contractAddress}`);
+        }
+    }
+    /**
+     * Clear all tracked collections
+     */
+    clearAll() {
+        this.collections.clear();
+        this.log('Cleared all tracked collections');
+    }
+    /**
+     * Handle wallet events (with debouncing)
+     */
+    handleWalletEvent(contractAddress, eventType) {
+        // Determine which collections to refresh
+        const keysToRefresh = [];
+        for (const [key, entry] of this.collections) {
+            // If no specific contract, refresh all; otherwise match contract
+            if (!contractAddress || entry.params.contractAddress.toLowerCase() === contractAddress.toLowerCase()) {
+                keysToRefresh.push(key);
+            }
+        }
+        if (keysToRefresh.length === 0) {
+            this.log(`No tracked collections affected by event for ${contractAddress || 'all contracts'}`);
+            return;
+        }
+        // Debounce refresh per key
+        for (const key of keysToRefresh) {
+            const existing = this.pendingRefresh.get(key);
+            if (existing) {
+                clearTimeout(existing);
+            }
+            const timeout = setTimeout(async () => {
+                this.pendingRefresh.delete(key);
+                const entry = this.collections.get(key);
+                if (entry) {
+                    this.log(`Refreshing ${key} due to wallet event: ${eventType}`);
+                    await this.refreshEntry(key, entry, eventType);
+                }
+            }, this.config.eventDebounceMs);
+            this.pendingRefresh.set(key, timeout);
+        }
+    }
+    /**
+     * Fetch and cache a collection
+     */
+    async fetchAndCache(params) {
+        const key = this.getCacheKey(params);
+        // Mark as refreshing to prevent duplicate fetches
+        const existing = this.collections.get(key);
+        if (existing?.refreshing) {
+            // Wait for existing refresh to complete
+            return existing.lastCollection || this.emptyCollection(params);
+        }
+        this.collections.set(key, {
+            params,
+            lastCollection: null,
+            timestamp: Date.now(),
+            refreshing: true
+        });
+        try {
+            const collection = await this.tokenService.getTokenCollection(params);
+            this.collections.set(key, {
+                params,
+                lastCollection: collection,
+                timestamp: Date.now(),
+                refreshing: false
+            });
+            this.log(`Cached collection for ${key}: ${collection.tokensRetrieved} tokens`);
+            return collection;
+        }
+        catch (error) {
+            // Remove failed entry
+            this.collections.delete(key);
+            throw error;
+        }
+    }
+    /**
+     * Refresh a cached entry and notify handlers
+     */
+    async refreshEntry(key, entry, source) {
+        if (entry.refreshing) {
+            this.log(`Skipping refresh for ${key} - already refreshing`);
+            return;
+        }
+        entry.refreshing = true;
+        try {
+            const newCollection = await this.tokenService.getTokenCollection(entry.params);
+            entry.lastCollection = newCollection;
+            entry.timestamp = Date.now();
+            entry.refreshing = false;
+            this.log(`Refreshed ${key}: ${newCollection.tokensRetrieved} tokens`);
+            // Notify subscribers
+            for (const handler of this.handlers) {
+                try {
+                    handler(newCollection, entry.params.contractAddress, {
+                        type: source === 'refresh' ? 'refresh' : 'wallet_event',
+                        source
+                    });
+                }
+                catch (handlerError) {
+                    console.error('[TokenCollectionManager] Handler error:', handlerError);
+                }
+            }
+        }
+        catch (error) {
+            entry.refreshing = false;
+            console.error(`[TokenCollectionManager] Refresh failed for ${key}:`, error);
+        }
+    }
+    /**
+     * Generate cache key from params
+     */
+    getCacheKey(params) {
+        return `${params.contractAddress}:${params.accountAddress}`;
+    }
+    /**
+     * Create empty collection placeholder
+     */
+    emptyCollection(params) {
+        return {
+            accountAddress: params.accountAddress,
+            contractAddress: params.contractAddress,
+            totalBalance: 0,
+            tokensRetrieved: 0,
+            tokens: [],
+            note: 'Loading...'
+        };
+    }
+    /**
+     * Debug logging
+     */
+    log(message, data) {
+        if (this.config.debug) {
+            console.log(`[TokenCollectionManager] ${message}`, data || '');
+        }
+    }
+    /**
+     * Cleanup resources
+     */
+    destroy() {
+        // Clear pending refreshes
+        for (const timeout of this.pendingRefresh.values()) {
+            clearTimeout(timeout);
+        }
+        this.pendingRefresh.clear();
+        // Unsubscribe from events
+        this.eventUnsubscribe?.();
+        // Clear handlers and collections
+        this.handlers.clear();
+        this.collections.clear();
+        this.log('Destroyed');
+    }
+}
+
+/**
+ * BalanceManager - Auto-refresh ERC-20 token balances on wallet events
+ *
+ * This manager provides:
+ * 1. Cached balance storage with automatic refresh
+ * 2. Auto-subscription to wallet events (transfers)
+ * 3. Targeted invalidation based on contract address
+ * 4. Subscriber pattern for reactive updates
+ *
+ * @example
+ * ```typescript
+ * // Get from SDK
+ * const manager = sdk.tokens.balanceManager;
+ *
+ * // Subscribe to balance updates
+ * const unsubscribe = manager.subscribe((balance, contractAddress) => {
+ *   console.log(`Balance updated for ${contractAddress}: ${balance}`);
+ *   updateUI(balance);
+ * });
+ *
+ * // Fetch balance (auto-cached, auto-refreshed on wallet events)
+ * const balance = await manager.getBalance({
+ *   accountAddress: '0x...',
+ *   contractAddress: '0x...',
+ *   abi: contractAbi,
+ *   chainId: 39123
+ * });
+ *
+ * // Manual refresh
+ * await manager.refreshBalance(contractAddress);
+ *
+ * // Cleanup
+ * unsubscribe();
+ * ```
+ */
+/**
+ * Manages ERC-20 token balances with automatic refresh on wallet events
+ */
+class BalanceManager {
+    constructor(tokenService, eventEmitter, config) {
+        this.tokenService = tokenService;
+        this.eventEmitter = eventEmitter;
+        this.balances = new Map();
+        this.handlers = new Set();
+        this.pendingRefresh = new Map();
+        this.config = {
+            autoRefreshOnWalletEvents: config?.autoRefreshOnWalletEvents ?? true,
+            eventDebounceMs: config?.eventDebounceMs ?? 500,
+            debug: config?.debug ?? false
+        };
+        if (this.config.autoRefreshOnWalletEvents && eventEmitter) {
+            this.setupEventSubscription();
+        }
+    }
+    /**
+     * Subscribe to wallet events for auto-refresh
+     */
+    setupEventSubscription() {
+        if (!this.eventEmitter) {
+            return;
+        }
+        this.eventUnsubscribe = this.eventEmitter.subscribe((event) => {
+            const contractAddress = event.details?.contractAddress;
+            this.handleWalletEvent(contractAddress, event.type);
+        }, { domains: ['wallet'] });
+    }
+    /**
+     * Get a token balance (cached, auto-refreshed on wallet events)
+     *
+     * @param params - Balance parameters
+     * @returns Promise resolving to the token balance
+     */
+    async getBalance(params) {
+        const key = this.getCacheKey(params);
+        const cached = this.balances.get(key);
+        // Return cached if available and not stale
+        if (cached?.lastBalance) {
+            this.log(`Cache HIT for ${key}`);
+            return cached.lastBalance;
+        }
+        this.log(`Cache MISS for ${key}, fetching...`);
+        return this.fetchAndCache(params);
+    }
+    /**
+     * Force refresh a specific balance
+     *
+     * @param contractAddress - Contract address to refresh
+     * @param accountAddress - Account address to refresh (optional, refreshes all if not provided)
+     * @returns Promise that resolves when refresh is complete
+     */
+    async refreshBalance(contractAddress, accountAddress) {
+        const toRefresh = [];
+        for (const [key, entry] of this.balances) {
+            if (entry.params.contractAddress.toLowerCase() === contractAddress.toLowerCase()) {
+                if (!accountAddress || entry.params.accountAddress.toLowerCase() === accountAddress.toLowerCase()) {
+                    toRefresh.push(key);
+                }
+            }
+        }
+        await Promise.all(toRefresh.map(key => {
+            const entry = this.balances.get(key);
+            if (entry) {
+                return this.refreshEntry(key, entry, 'refresh');
+            }
+        }));
+    }
+    /**
+     * Force refresh all tracked balances
+     *
+     * @returns Promise that resolves when all refreshes are complete
+     */
+    async refreshAll() {
+        const refreshPromises = Array.from(this.balances.entries()).map(([key, entry]) => this.refreshEntry(key, entry, 'refresh'));
+        await Promise.all(refreshPromises);
+    }
+    /**
+     * Subscribe to balance change events
+     *
+     * @param handler - Callback when any tracked balance changes
+     * @returns Unsubscribe function
+     */
+    subscribe(handler) {
+        this.handlers.add(handler);
+        return () => this.handlers.delete(handler);
+    }
+    /**
+     * Get all currently tracked balances
+     */
+    getTrackedBalances() {
+        return Array.from(this.balances.entries()).map(([_, entry]) => ({
+            contractAddress: entry.params.contractAddress,
+            accountAddress: entry.params.accountAddress,
+            balance: entry.lastBalance
+        }));
+    }
+    /**
+     * Check if a balance is currently being tracked
+     */
+    isTracking(contractAddress, accountAddress) {
+        const key = `${contractAddress.toLowerCase()}:${accountAddress.toLowerCase()}`;
+        return this.balances.has(key);
+    }
+    /**
+     * Clear tracking for a specific balance
+     */
+    untrack(contractAddress, accountAddress) {
+        if (accountAddress) {
+            const key = `${contractAddress.toLowerCase()}:${accountAddress.toLowerCase()}`;
+            this.balances.delete(key);
+            this.log(`Untracked ${key}`);
+        }
+        else {
+            // Untrack all for this contract
+            const toDelete = [];
+            for (const key of this.balances.keys()) {
+                if (key.startsWith(`${contractAddress.toLowerCase()}:`)) {
+                    toDelete.push(key);
+                }
+            }
+            toDelete.forEach(key => this.balances.delete(key));
+            this.log(`Untracked all balances for ${contractAddress}`);
+        }
+    }
+    /**
+     * Clear all tracked balances
+     */
+    clearAll() {
+        this.balances.clear();
+        this.log('Cleared all tracked balances');
+    }
+    /**
+     * Handle wallet events (with debouncing)
+     */
+    handleWalletEvent(contractAddress, eventType) {
+        // Determine which balances to refresh
+        const keysToRefresh = [];
+        for (const [key, entry] of this.balances) {
+            // If no specific contract, refresh all; otherwise match contract
+            if (!contractAddress || entry.params.contractAddress.toLowerCase() === contractAddress.toLowerCase()) {
+                keysToRefresh.push(key);
+            }
+        }
+        if (keysToRefresh.length === 0) {
+            this.log(`No tracked balances affected by event for ${contractAddress || 'all contracts'}`);
+            return;
+        }
+        // Debounce refresh per key
+        for (const key of keysToRefresh) {
+            const existing = this.pendingRefresh.get(key);
+            if (existing) {
+                clearTimeout(existing);
+            }
+            const timeout = setTimeout(async () => {
+                this.pendingRefresh.delete(key);
+                const entry = this.balances.get(key);
+                if (entry) {
+                    this.log(`Refreshing ${key} due to wallet event: ${eventType}`);
+                    await this.refreshEntry(key, entry, eventType);
+                }
+            }, this.config.eventDebounceMs);
+            this.pendingRefresh.set(key, timeout);
+        }
+    }
+    /**
+     * Fetch and cache a balance
+     */
+    async fetchAndCache(params) {
+        const key = this.getCacheKey(params);
+        // Mark as refreshing to prevent duplicate fetches
+        const existing = this.balances.get(key);
+        if (existing?.refreshing) {
+            // Wait for existing refresh to complete
+            return existing.lastBalance || this.emptyBalance();
+        }
+        this.balances.set(key, {
+            params,
+            lastBalance: null,
+            timestamp: Date.now(),
+            refreshing: true
+        });
+        try {
+            const balance = await this.tokenService.getTokenBalance({
+                ...params,
+                tokenId: null // ERC-20 has no tokenId
+            });
+            this.balances.set(key, {
+                params,
+                lastBalance: balance,
+                timestamp: Date.now(),
+                refreshing: false
+            });
+            this.log(`Cached balance for ${key}: ${balance.balance}`);
+            return balance;
+        }
+        catch (error) {
+            // Remove failed entry
+            this.balances.delete(key);
+            throw error;
+        }
+    }
+    /**
+     * Refresh a cached entry and notify handlers
+     */
+    async refreshEntry(key, entry, source) {
+        if (entry.refreshing) {
+            this.log(`Skipping refresh for ${key} - already refreshing`);
+            return;
+        }
+        entry.refreshing = true;
+        try {
+            const newBalance = await this.tokenService.getTokenBalance({
+                ...entry.params,
+                tokenId: null // ERC-20 has no tokenId
+            });
+            entry.lastBalance = newBalance;
+            entry.timestamp = Date.now();
+            entry.refreshing = false;
+            this.log(`Refreshed ${key}: ${newBalance.balance}`);
+            // Notify subscribers
+            for (const handler of this.handlers) {
+                try {
+                    handler(newBalance, entry.params.contractAddress, {
+                        type: source === 'refresh' ? 'refresh' : 'wallet_event',
+                        source
+                    });
+                }
+                catch (handlerError) {
+                    console.error('[BalanceManager] Handler error:', handlerError);
+                }
+            }
+        }
+        catch (error) {
+            entry.refreshing = false;
+            console.error(`[BalanceManager] Refresh failed for ${key}:`, error);
+        }
+    }
+    /**
+     * Generate cache key from params
+     */
+    getCacheKey(params) {
+        return `${params.contractAddress.toLowerCase()}:${params.accountAddress.toLowerCase()}`;
+    }
+    /**
+     * Create empty balance placeholder
+     */
+    emptyBalance() {
+        return {
+            tokenId: null,
+            balance: 0,
+            hasBalance: false,
+            metadata: null
+        };
+    }
+    /**
+     * Debug logging
+     */
+    log(message, data) {
+        if (this.config.debug) {
+            console.log(`[BalanceManager] ${message}`, data || '');
+        }
+    }
+    /**
+     * Cleanup resources
+     */
+    destroy() {
+        // Clear pending refreshes
+        for (const timeout of this.pendingRefresh.values()) {
+            clearTimeout(timeout);
+        }
+        this.pendingRefresh.clear();
+        // Unsubscribe from events
+        this.eventUnsubscribe?.();
+        // Clear handlers and balances
+        this.handlers.clear();
+        this.balances.clear();
+        this.log('Destroyed');
+    }
+}
+
 /**
  * Web3ApplicationService - Application layer entrance point
  * Orchestrates domain services and provides clean public interface
@@ -41601,6 +43681,30 @@ class Web3InfrastructureApi {
             return 0;
         }
     }
+    /**
+     * Get multiple ERC-1155 token balances in a single RPC call using native balanceOfBatch.
+     * Falls back to individual calls if balanceOfBatch fails.
+     *
+     * @param request - Batch balance request
+     * @returns Array of balance results per tokenId
+     */
+    async getBatchTokenBalances(request) {
+        try {
+            const ethersProvider = await this.web3ChainService.getEthersProviderByChainId(request.chainId);
+            const results = await getBatchBalancesWithFallback(ethersProvider, request.contractAddress, request.abi, request.accountAddress, request.tokenIds, request.isERC1155 ?? true);
+            return results;
+        }
+        catch (error) {
+            console.error(`Failed to get batch token balances:`, error);
+            // Return empty results on failure
+            return request.tokenIds.map(tokenId => ({
+                tokenId,
+                balance: 0n,
+                success: false,
+                error: `${error}`
+            }));
+        }
+    }
     async getTokenUri(request) {
         try {
             const ethersProvider = await this.web3ChainService.getEthersProviderByChainId(request.chainId);
@@ -41838,17 +43942,11 @@ async function getExplorerUrlByChainId(getChainData, chainId, address, type) {
  * ```
  */
 class Web3Manager {
-    // TODO: Add PersEventEmitter support for blockchain events
-    // When ready, add:
-    // 1. constructor param: private events?: PersEventEmitter
-    // 2. Subscribe to contract events (Transfer, Approval, etc.)
-    // 3. Emit via: this.events?.emitSuccess({ domain: 'web3', type: 'NFT_TRANSFERRED', ... })
-    // 4. Filter to only user's address (not all transfers)
-    // 5. Add cleanup for event listeners on SDK destroy
-    constructor(apiClient, tenantManager) {
+    constructor(apiClient, tenantManager, eventEmitter) {
         this.apiClient = apiClient;
         // Use provided TenantManager or create one
         this.tenantManager = tenantManager || new TenantManager(apiClient);
+        this.eventEmitter = eventEmitter;
         // Initialize Web3 Chain service
         const web3ChainApi = new Web3ChainApi(apiClient);
         this.web3ChainService = new Web3ChainService(web3ChainApi);
@@ -41856,6 +43954,75 @@ class Web3Manager {
         const web3InfrastructureApi = new Web3InfrastructureApi(this.web3ChainService);
         const ipfsInfrastructureApi = new IPFSInfrastructureApi(this.tenantManager);
         this.web3ApplicationService = new Web3ApplicationService(web3InfrastructureApi, ipfsInfrastructureApi);
+        // Initialize domain services for managers
+        const contractDomainService = new ContractDomainService();
+        const metadataDomainService = new MetadataDomainService(ipfsInfrastructureApi);
+        this.tokenDomainService = new TokenDomainService(web3InfrastructureApi, metadataDomainService, contractDomainService);
+    }
+    /**
+     * Get the TokenCollectionManager for NFT collection operations.
+     *
+     * Features:
+     * - Auto-refresh on wallet events (transfers, mints, burns)
+     * - Cached collections
+     * - Subscriber pattern for reactive updates
+     *
+     * @example
+     * ```typescript
+     * const manager = sdk.web3.collectionManager;
+     *
+     * // Subscribe to updates
+     * const unsubscribe = manager.subscribe((collection, contractAddress) => {
+     *   console.log(`Collection updated for ${contractAddress}`);
+     * });
+     *
+     * // Fetch collection (auto-cached, auto-refreshed)
+     * const collection = await manager.getCollection({...});
+     *
+     * // Manual refresh
+     * await manager.refreshCollection(contractAddress);
+     * ```
+     */
+    get collectionManager() {
+        if (!this._collectionManager) {
+            this._collectionManager = new TokenCollectionManager(this.tokenDomainService, this.eventEmitter);
+        }
+        return this._collectionManager;
+    }
+    /**
+     * Get the BalanceManager for ERC-20 (credit token) balance operations.
+     *
+     * Features:
+     * - Auto-refresh on wallet events (transfers)
+     * - Cached balances
+     * - Subscriber pattern for reactive updates
+     *
+     * @example
+     * ```typescript
+     * const manager = sdk.web3.balanceManager;
+     *
+     * // Subscribe to balance updates
+     * const unsubscribe = manager.subscribe((balance, contractAddress) => {
+     *   console.log(`Balance updated: ${balance.balance}`);
+     * });
+     *
+     * // Fetch balance (auto-cached, auto-refreshed)
+     * const balance = await manager.getBalance({
+     *   accountAddress: '0x...',
+     *   contractAddress: '0x...',
+     *   abi: creditTokenAbi,
+     *   chainId: 39123
+     * });
+     *
+     * // Manual refresh
+     * await manager.refreshBalance(contractAddress);
+     * ```
+     */
+    get balanceManager() {
+        if (!this._balanceManager) {
+            this._balanceManager = new BalanceManager(this.tokenDomainService, this.eventEmitter);
+        }
+        return this._balanceManager;
     }
     /**
      * Get token balance for a specific token
@@ -42054,6 +44221,18 @@ class Web3Manager {
             maxTokens
         };
     }
+    /**
+     * Cleanup resources.
+     *
+     * Call this when the SDK is being destroyed to clean up
+     * event subscriptions and cached data.
+     */
+    destroy() {
+        this._collectionManager?.destroy();
+        this._balanceManager?.destroy();
+        this._collectionManager = undefined;
+        this._balanceManager = undefined;
+    }
 }
 
 /**
@@ -42945,6 +45124,83 @@ class BrowserFetchClientAdapter {
     }
 }
 
+/**
+ * Build optimized image URL with automatic IPFS resolution and CDN options
+ *
+ * Single entry point for all image URL building:
+ * - IPFS URIs → resolved via gateway + CDN options applied
+ * - HTTP URLs → CDN options applied directly
+ *
+ * @param url - Image URL (ipfs://, https://, or any URL)
+ * @param options - CDN optimization options (preset, quality, format, fit)
+ * @param gateway - IPFS gateway domain (required for ipfs:// URLs)
+ * @returns Optimized URL with query parameters
+ *
+ * @example
+ * ```typescript
+ * // IPFS thumbnail
+ * buildImageUrl('ipfs://QmHash', { preset: 'thumb' }, 'cdn.example.com')
+ * // => 'https://cdn.example.com/ipfs/QmHash?preset=thumb'
+ *
+ * // IPFS hero with high quality
+ * buildImageUrl('ipfs://QmHash', { preset: 'hero', q: 95, fit: 'cover' }, 'cdn.example.com')
+ * // => 'https://cdn.example.com/ipfs/QmHash?preset=hero&q=95&fit=cover'
+ *
+ * // HTTP URL (gateway ignored)
+ * buildImageUrl('https://example.com/photo.jpg', { preset: 'card' })
+ * // => 'https://example.com/photo.jpg?preset=card'
+ *
+ * // No options - just IPFS resolution
+ * buildImageUrl('ipfs://QmHash', undefined, 'cdn.example.com')
+ * // => 'https://cdn.example.com/ipfs/QmHash'
+ * ```
+ */
+function buildImageUrl(url, options, gateway) {
+    if (!url)
+        return '';
+    let resolvedUrl = url;
+    // Resolve IPFS to HTTP via gateway
+    if (url.startsWith('ipfs://')) {
+        if (!gateway) {
+            console.warn('[buildImageUrl] IPFS URL requires gateway parameter');
+            return url;
+        }
+        const cid = url.replace('ipfs://', '');
+        resolvedUrl = `https://${gateway}/ipfs/${cid}`;
+    }
+    // Apply CDN options
+    return buildImageCdnUrl(resolvedUrl, options);
+}
+/**
+ * Check if a URL is an IPFS URI
+ *
+ * @param url - URL to check
+ * @returns True if URL starts with ipfs://
+ */
+function isIpfsUrl(url) {
+    return !!url && url.startsWith('ipfs://');
+}
+/**
+ * Extract CID from IPFS URI
+ *
+ * @param ipfsUri - IPFS URI (ipfs://Qm... or ipfs://baf...)
+ * @returns CID string, or null if not a valid IPFS URI
+ *
+ * @example
+ * ```typescript
+ * extractIpfsCid('ipfs://QmHash123')
+ * // => 'QmHash123'
+ *
+ * extractIpfsCid('https://example.com/image.jpg')
+ * // => null
+ * ```
+ */
+function extractIpfsCid(ipfsUri) {
+    if (!isIpfsUrl(ipfsUri))
+        return null;
+    return ipfsUri.replace('ipfs://', '');
+}
+
 /**
  * React hook for loading and managing token balances
  *
@@ -46619,8 +48875,11 @@ const useTriggerSources = () => {
     };
 };
 
+exports.ACTIVE_USER_DEFINITION = ACTIVE_USER_DEFINITION;
 exports.ANALYTICS_GROUP_BY_TYPES = ANALYTICS_GROUP_BY_TYPES;
 exports.ANALYTICS_METRIC_TYPES = ANALYTICS_METRIC_TYPES;
+exports.ANALYTICS_VALID_PROCESS_STATUS = ANALYTICS_VALID_PROCESS_STATUS;
+exports.ANALYTICS_VALID_TRANSACTION_STATUSES = ANALYTICS_VALID_TRANSACTION_STATUSES;
 exports.AUTH_STORAGE_KEYS = AUTH_STORAGE_KEYS;
 exports.AnalyticsApi = AnalyticsApi;
 exports.AnalyticsManager = AnalyticsManager;
@@ -46651,6 +48910,7 @@ exports.CampaignService = CampaignService;
 exports.ChainTypes = ChainTypes;
 exports.ClientTransactionType = ClientTransactionType;
 exports.CommonErrorCodes = CommonErrorCodes;
+exports.CustomFieldDefinitionManager = CustomFieldDefinitionManager;
 exports.DEFAULT_PERS_CONFIG = DEFAULT_PERS_CONFIG;
 exports.DPOP_STORAGE_KEYS = DPOP_STORAGE_KEYS;
 exports.DPoPManager = DPoPManager;
@@ -46659,6 +48919,9 @@ exports.Domains = Domains;
 exports.DonationApi = DonationApi;
 exports.DonationManager = DonationManager;
 exports.DonationService = DonationService;
+exports.EMAIL_MAX_LENGTH = EMAIL_MAX_LENGTH;
+exports.EMAIL_REGEX = EMAIL_REGEX;
+exports.ENGAGEMENT_RATE_FORMULA = ENGAGEMENT_RATE_FORMULA;
 exports.EntityTypes = EntityTypes;
 exports.ErrorDomains = ErrorDomains;
 exports.ErrorUtils = ErrorUtils;
@@ -46666,6 +48929,14 @@ exports.FATAL_AUTH_CODES = FATAL_AUTH_CODES;
 exports.FileApi = FileApi;
 exports.FileManager = FileManager;
 exports.FileService = FileService;
+exports.IMAGE_CDN_CACHE_TTL = IMAGE_CDN_CACHE_TTL;
+exports.IMAGE_CDN_DEFAULT_FIT = IMAGE_CDN_DEFAULT_FIT;
+exports.IMAGE_CDN_DEFAULT_FORMAT = IMAGE_CDN_DEFAULT_FORMAT;
+exports.IMAGE_CDN_DEFAULT_QUALITY = IMAGE_CDN_DEFAULT_QUALITY;
+exports.IMAGE_CDN_MAX_DIMENSION = IMAGE_CDN_MAX_DIMENSION;
+exports.IMAGE_CDN_MAX_INPUT_SIZE = IMAGE_CDN_MAX_INPUT_SIZE;
+exports.IMAGE_CDN_PRESETS = IMAGE_CDN_PRESETS;
+exports.IMAGE_CDN_SUPPORTED_FORMATS = IMAGE_CDN_SUPPORTED_FORMATS;
 exports.IndexedDBTokenStorage = IndexedDBTokenStorage;
 exports.LocalStorageTokenStorage = LocalStorageTokenStorage;
 exports.LogoutRequired = LogoutRequired;
@@ -46674,6 +48945,7 @@ exports.MemoryTokenStorage = MemoryTokenStorage;
 exports.NativeTokenTypes = NativeTokenTypes;
 exports.NetworkError = NetworkError;
 exports.NodeHttpClientAdapter = NodeHttpClientAdapter;
+exports.OttAuthMethod = OttAuthMethod;
 exports.PaymentApi = PurchaseApi;
 exports.PaymentService = PaymentService;
 exports.PersApiClient = PersApiClient;
@@ -46718,6 +48990,8 @@ exports.TransactionService = TransactionService;
 exports.TriggerSourceApi = TriggerSourceApi;
 exports.TriggerSourceManager = TriggerSourceManager;
 exports.TriggerSourceService = TriggerSourceService;
+exports.URL_REGEX = URL_REGEX;
+exports.UUID_REGEX = UUID_REGEX;
 exports.UserApi = UserApi;
 exports.UserManager = UserManager;
 exports.UserService = UserService;
@@ -46730,8 +49004,10 @@ 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.WALLET_ADDRESS_REGEX = WALLET_ADDRESS_REGEX;
 exports.WalletEventsManager = WalletEventsManager;
 exports.WebDPoPCryptoProvider = WebDPoPCryptoProvider;
 exports.WebhookApi = WebhookApi;
@@ -46740,6 +49016,8 @@ exports.WebhookService = WebhookService;
 exports.apiPublicKeyTestPrefix = apiPublicKeyTestPrefix;
 exports.buildApiRoot = buildApiRoot;
 exports.buildBurnRequest = buildBurnRequest;
+exports.buildImageCdnUrl = buildImageCdnUrl;
+exports.buildImageUrl = buildImageUrl;
 exports.buildMintRequest = buildMintRequest;
 exports.buildPOSBurnRequest = buildPOSBurnRequest;
 exports.buildPOSTransferRequest = buildPOSTransferRequest;
@@ -46748,46 +49026,67 @@ exports.buildPendingTransactionData = buildPendingTransactionData;
 exports.buildSubmissionRequest = buildSubmissionRequest;
 exports.buildTransferRequest = buildTransferRequest;
 exports.buildWalletEventsWsUrl = buildWalletEventsWsUrl;
+exports.builtInUserFieldMetadata = builtInUserFieldMetadata;
+exports.builtInUserFields = builtInUserFields;
+exports.compareValues = compareValues;
 exports.createPersEventsClient = createPersEventsClient;
 exports.createPersSDK = createPersSDK;
 exports.createReactNativeAuthProvider = createReactNativeAuthProvider;
 exports.createUserIdentifierObject = createUserIdentifierObject;
 exports.createUserStatusSDK = createUserStatusSDK;
+exports.customFieldEntityTypes = customFieldEntityTypes;
 exports.detectEnvironment = detectEnvironment;
 exports.detectIdentifierType = detectIdentifierType;
 exports.environment = environment;
 exports.extractData = extractData;
 exports.extractDeadlineFromSigningData = extractDeadlineFromSigningData;
+exports.extractIpfsCid = extractIpfsCid;
 exports.extractPagination = extractPagination;
 exports.fetchAllPages = fetchAllPages;
+exports.getAllBuiltInFieldDefinitions = getAllBuiltInFieldDefinitions;
+exports.getBuiltInFieldDefinition = getBuiltInFieldDefinition;
 exports.getMetadataFromTokenUnitResponse = getMetadataFromTokenUnitResponse;
+exports.getOperatorText = getOperatorText;
+exports.getPresetDimensions = getPresetDimensions;
 exports.getSigningUrl = getSigningUrl;
 exports.globalCacheService = globalCacheService;
 exports.hasMinimumRole = hasMinimumRole;
 exports.initializeReactNativePolyfills = initializeReactNativePolyfills;
+exports.isBuiltInUserField = isBuiltInUserField;
 exports.isConnectedMessage = isConnectedMessage;
 exports.isErrorMessage = isErrorMessage;
 exports.isEventMessage = isEventMessage;
 exports.isFatalAuthErrorInMessage = isFatalAuthErrorInMessage;
+exports.isIpfsUrl = isIpfsUrl;
 exports.isPaginatedResponse = isPaginatedResponse;
 exports.isPingMessage = isPingMessage;
 exports.isServerMessage = isServerMessage;
 exports.isSubscribedMessage = isSubscribedMessage;
+exports.isSupportedImageFormat = isSupportedImageFormat;
+exports.isUUID = isUUID;
 exports.isUnsubscribedMessage = isUnsubscribedMessage;
 exports.isUserIdentifierObject = isUserIdentifierObject;
 exports.isValidBusinessMembershipRelation = isValidBusinessMembershipRelation;
 exports.isValidCampaignClaimRelation = isValidCampaignClaimRelation;
 exports.isValidCampaignRelation = isValidCampaignRelation;
+exports.isValidEmail = isValidEmail;
+exports.isValidNonEmptyString = isValidNonEmptyString;
+exports.isValidPreset = isValidPreset;
 exports.isValidRedemptionRedeemRelation = isValidRedemptionRedeemRelation;
 exports.isValidRedemptionRelation = isValidRedemptionRelation;
 exports.isValidRelation = isValidRelation;
+exports.isValidTokenMetadataRelation = isValidTokenMetadataRelation;
 exports.isValidTransactionRelation = isValidTransactionRelation;
+exports.isValidUrl = isValidUrl;
 exports.isValidUserRelation = isValidUserRelation;
+exports.isValidUuid = isValidUuid;
+exports.isValidWalletAddress = isValidWalletAddress;
 exports.mergeWithDefaults = mergeWithDefaults;
 exports.needsExternalSigning = needsExternalSigning;
 exports.needsSubmission = needsSubmission;
 exports.normalizeFilters = normalizeFilters;
 exports.normalizeToPaginated = normalizeToPaginated;
+exports.operatorText = operatorText;
 exports.registerIdentifierType = registerIdentifierType;
 exports.testnetPrefix = testnetPrefix;
 exports.testnetShortPrefix = testnetShortPrefix;
@@ -46815,5 +49114,10 @@ exports.useTriggerSources = useTriggerSources;
 exports.useUserStatus = useUserStatus;
 exports.useUsers = useUsers;
 exports.useWeb3 = useWeb3;
+exports.userModelFields = userModelFields;
+exports.validateAllFields = validateAllFields;
+exports.validateFieldComparisons = validateFieldComparisons;
+exports.validateFieldValue = validateFieldValue;
+exports.validateObjectArrayItems = validateObjectArrayItems;
 exports.warnIfProblematicEnvironment = warnIfProblematicEnvironment;
 //# sourceMappingURL=index.js.map