@explorins/pers-sdk-react-native 2.1.14-beta.0 → 2.1.18

package/dist/index.js

@@ -3563,7 +3563,8 @@ function isValidTransactionRelation(value) {
  */
 const VALID_CAMPAIGN_RELATIONS = [
     'triggerSources',
-    'businesses'
+    'businesses',
+    'claimCount'
 ];
 /**
  * Type guard to validate campaign include relation at runtime
@@ -3596,6 +3597,23 @@ function isValidCampaignClaimRelation(value) {
     return VALID_CAMPAIGN_CLAIM_RELATIONS.includes(value);
 }
 
+/**
+ * Array of all valid redemption include relations
+ * Used for runtime validation
+ */
+const VALID_REDEMPTION_RELATIONS = [
+    'redeemCount'
+];
+/**
+ * Type guard to validate redemption include relation at runtime
+ *
+ * @param value - String to validate
+ * @returns True if value is a valid RedemptionIncludeRelation
+ */
+function isValidRedemptionRelation(value) {
+    return VALID_REDEMPTION_RELATIONS.includes(value);
+}
+
 /**
  * Array of all valid redemption redeem include relations
  * Used for runtime validation
@@ -3642,6 +3660,26 @@ function isValidUserRelation(value) {
     return VALID_USER_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.
+ *
+ * @example
+ * // In controller
+ * const filters = normalizeFilters({ isActive: true, sort: 'name' });
+ * // Result: { active: true, sortBy: 'name', isActive: true, sort: 'name' }
+ */
+function normalizeFilters(filters) {
+    if (!filters)
+        return undefined;
+    return {
+        ...filters,
+        active: filters.active ?? filters.isActive,
+        sortBy: filters.sortBy ?? filters.sort,
+        sortOrder: filters.sortOrder ?? filters.order,
+    };
+}
+
 /**
  * Chain Data Types
  *
@@ -3711,6 +3749,17 @@ const isTokenExpired = (token, margin = 60) => {
  * Consolidated API and auth errors for fast SDK performance
  * Uses @explorins/pers-shared when available, fallback to SDK errors
  */
+/**
+ * SDK-internal error codes for auth flow control
+ * These are not backend errors - they're used for SDK-internal state management
+ */
+const SdkErrorCodes = {
+    TOKEN_REFRESH_NEEDED: 'TOKEN_REFRESH_NEEDED',
+    PROVIDER_TOKEN_REFRESH_NEEDED: 'PROVIDER_TOKEN_REFRESH_NEEDED',
+    LOGOUT_REQUIRED: 'LOGOUT_REQUIRED',
+    NETWORK_ERROR: 'NETWORK_ERROR',
+    API_ERROR: 'API_ERROR',
+};
 // Fast type guards and utilities
 class ErrorUtils {
     /**
@@ -3870,9 +3919,9 @@ class TokenRefreshNeeded extends Error {
     constructor(refreshToken) {
         super('Token refresh needed');
         this.refreshToken = refreshToken;
-        this.errorCode = 'TOKEN_REFRESH_NEEDED';
-        this.domain = 'auth';
-        this.category = 'SECURITY';
+        this.errorCode = SdkErrorCodes.TOKEN_REFRESH_NEEDED;
+        this.domain = Domains.AUTHENTICATION;
+        this.category = exports.ErrorCategory.SECURITY;
         this.retryable = true;
         this.name = 'TokenRefreshNeeded';
     }
@@ -3881,9 +3930,9 @@ class ProviderTokenRefreshNeeded extends Error {
     constructor(providerToken) {
         super('Provider token refresh needed');
         this.providerToken = providerToken;
-        this.errorCode = 'PROVIDER_TOKEN_REFRESH_NEEDED';
-        this.domain = 'auth';
-        this.category = 'SECURITY';
+        this.errorCode = SdkErrorCodes.PROVIDER_TOKEN_REFRESH_NEEDED;
+        this.domain = Domains.AUTHENTICATION;
+        this.category = exports.ErrorCategory.SECURITY;
         this.retryable = true;
         this.name = 'ProviderTokenRefreshNeeded';
     }
@@ -3891,9 +3940,9 @@ class ProviderTokenRefreshNeeded extends Error {
 class LogoutRequired extends Error {
     constructor(message) {
         super(message);
-        this.errorCode = 'LOGOUT_REQUIRED';
-        this.domain = 'auth';
-        this.category = 'SECURITY';
+        this.errorCode = SdkErrorCodes.LOGOUT_REQUIRED;
+        this.domain = Domains.AUTHENTICATION;
+        this.category = exports.ErrorCategory.SECURITY;
         this.retryable = false;
         this.name = 'LogoutRequired';
     }
@@ -3909,25 +3958,40 @@ class PersApiError extends Error {
         this.name = 'PersApiError';
         // Use backend error details directly
         this.code = backendError?.code || 'API_ERROR';
-        this.domain = backendError?.domain || 'api';
+        this.domain = backendError?.domain || ErrorDomains.EXTERNAL;
         this.category = backendError?.category || exports.ErrorCategory.TECHNICAL;
         this.retryable = backendError?.retryable ?? (statusCode ? statusCode >= 500 : false);
         this.message = backendError?.message || message;
         this.status = backendError?.status || statusCode || 500;
         this.title = backendError?.title || 'Request failed';
         this.detail = backendError?.detail || backendError?.message || message;
+        this.details = backendError?.details;
     }
 }
 class AuthenticationError extends PersApiError {
     constructor(message, endpoint, method, backendError) {
         super(message, endpoint, method, 401, {
             ...backendError,
-            domain: 'authentication',
+            domain: Domains.AUTHENTICATION,
             category: exports.ErrorCategory.SECURITY
         });
         this.name = 'AuthenticationError';
     }
 }
+class NetworkError extends Error {
+    constructor(message) {
+        super(message);
+        this.code = SdkErrorCodes.NETWORK_ERROR;
+        this.domain = ErrorDomains.EXTERNAL;
+        this.category = exports.ErrorCategory.INFRASTRUCTURE;
+        this.retryable = true;
+        this.status = 0;
+        this.title = 'Network error';
+        this.name = 'NetworkError';
+        this.message = message;
+        this.detail = message;
+    }
+}
 const ApiErrorDetector = {
     getErrorMessage: (error) => ErrorUtils.getMessage(error),
     getStatusCode: (error) => ErrorUtils.getStatus(error),
@@ -5221,6 +5285,10 @@ class BusinessApi {
      *   limit: 25,
      *   sanitize: 'soft'
      * });
+     *
+     * // Filter by tag(s)
+     * const tagged = await businessApi.getBusinesses({ tag: 'restaurant' });
+     * const multiTag = await businessApi.getBusinesses({ tag: ['restaurant', 'cafe'] });
      * ```
      */
     async getBusinesses(options) {
@@ -5228,6 +5296,15 @@ class BusinessApi {
         if (options?.active !== undefined) {
             params.set('active', String(options.active));
         }
+        if (options?.search) {
+            params.set('search', options.search);
+        }
+        // Support single tag or array of tags (multiple ?tags=a&tags=b)
+        if (options?.tags) {
+            const tagsArray = Array.isArray(options.tags) ? options.tags : [options.tags];
+            // URLSearchParams supports multiple values with same key via append
+            tagsArray.forEach(t => params.append('tags', t));
+        }
         if (options?.sanitize) {
             params.set('sanitize', options.sanitize);
         }
@@ -5596,7 +5673,9 @@ class BusinessService {
     // ADMIN OPERATIONS
     // ==========================================
     /**
-     * ADMIN: Get all businesses with pagination (active and inactive)
+     * ADMIN: Get all businesses with filtering and pagination
+     * @param options - Filter and pagination options
+     * @see BusinessFilterOptions for available filter options
      */
     async getBusinesses(options) {
         return this.businessApi.getBusinesses(options);
@@ -5915,7 +5994,9 @@ class CampaignApi {
      * Intelligent access: Public gets active only, Business gets own campaigns, Admin gets all
      *
      * @param options - Filter, pagination, and include options
-     * @param options.include - Relations to include: 'triggerSources', 'businesses'
+     * @param options.include - Relations to include: 'triggerSources', 'businesses', 'claimCount'
+     * @param options.startDate - Filter campaigns starting on or after this date
+     * @param options.endDate - Filter campaigns ending on or before this date
      *
      * @example
      * ```typescript
@@ -5923,8 +6004,15 @@ class CampaignApi {
      * const campaigns = await api.getCampaigns({ include: ['triggerSources'] });
      * campaigns.data.forEach(c => console.log(c.included?.triggerSources));
      *
-     * // Get campaigns with both relations
-     * const full = await api.getCampaigns({ include: ['triggerSources', 'businesses'] });
+     * // Get campaigns with claim count
+     * const withCounts = await api.getCampaigns({ include: ['claimCount'] });
+     * withCounts.data.forEach(c => console.log(c.claimCount));
+     *
+     * // Filter by date range
+     * const dateFiltered = await api.getCampaigns({
+     *   startDate: new Date('2026-05-01'),
+     *   endDate: new Date('2026-12-31')
+     * });
      * ```
      */
     async getCampaigns(options) {
@@ -5934,12 +6022,23 @@ class CampaignApi {
         params.push(`limit=${options?.limit || 50}`);
         if (options?.active !== undefined)
             params.push(`active=${options.active}`);
-        if (options?.tag)
-            params.push(`tag=${encodeURIComponent(options.tag)}`);
+        // Support single tag or array of tags (multiple ?tags=a&tags=b)
+        if (options?.tags) {
+            const tagsArray = Array.isArray(options.tags) ? options.tags : [options.tags];
+            tagsArray.forEach(t => params.push(`tags=${encodeURIComponent(t)}`));
+        }
         if (options?.businessId)
             params.push(`businessId=${encodeURIComponent(options.businessId)}`);
         if (options?.search)
             params.push(`search=${encodeURIComponent(options.search)}`);
+        if (options?.startDate) {
+            const dateStr = options.startDate instanceof Date ? options.startDate.toISOString() : options.startDate;
+            params.push(`startDate=${encodeURIComponent(dateStr)}`);
+        }
+        if (options?.endDate) {
+            const dateStr = options.endDate instanceof Date ? options.endDate.toISOString() : options.endDate;
+            params.push(`endDate=${encodeURIComponent(dateStr)}`);
+        }
         if (options?.sortBy)
             params.push(`sortBy=${options.sortBy}`);
         if (options?.sortOrder)
@@ -5953,7 +6052,7 @@ class CampaignApi {
      * NEW: /campaigns/{id}
      *
      * @param id - Campaign UUID
-     * @param include - Relations to include: 'triggerSources', 'businesses'
+     * @param include - Relations to include: 'triggerSources', 'businesses', 'claimCount'
      *
      * @example
      * ```typescript
@@ -5961,6 +6060,10 @@ class CampaignApi {
      * const campaign = await api.getCampaignById('123', ['triggerSources', 'businesses']);
      * console.log(campaign.included?.triggerSources);
      * console.log(campaign.included?.businesses);
+     *
+     * // Get campaign with claim count
+     * const withCount = await api.getCampaignById('123', ['claimCount']);
+     * console.log(withCount.claimCount);
      * ```
      */
     async getCampaignById(id, include) {
@@ -6209,6 +6312,10 @@ class CampaignApi {
             params.set('userId', filters.userId);
         if (filters?.businessId)
             params.set('businessId', filters.businessId);
+        if (filters?.dateFrom)
+            params.set('dateFrom', filters.dateFrom instanceof Date ? filters.dateFrom.toISOString() : filters.dateFrom);
+        if (filters?.dateTo)
+            params.set('dateTo', filters.dateTo instanceof Date ? filters.dateTo.toISOString() : filters.dateTo);
         // Add include parameter
         if (include && include.length > 0) {
             include.forEach(relation => params.append('include', relation));
@@ -6306,15 +6413,7 @@ class CampaignService {
     /**
      * Get campaigns with pagination support
      * Intelligent access: Public gets active only, Business gets own campaigns, Admin gets all
-     * @param options.active - Filter by active status (Admin only)
-     * @param options.tag - Filter by tag
-     * @param options.search - Free text search across name, description, and tags (case-insensitive)
-     * @param options.businessId - Filter by business engagement
-     * @param options.page - Page number (1-based, default: 1)
-     * @param options.limit - Items per page (default: 50)
-     * @param options.sortBy - Sort field
-     * @param options.sortOrder - Sort direction
-     * @param options.include - Relations to include: 'triggerSources', 'businesses'
+     * @see CampaignFilterOptions for available filter options
      */
     async getCampaigns(options) {
         return this.campaignApi.getCampaigns(options);
@@ -6414,7 +6513,7 @@ class CampaignService {
     }
     /**
      * ADMIN: Get campaign claims with optional filters and pagination
-     * @param filters - Filter and pagination options
+     * @param filters - Filter and pagination options including date range
      * @param include - Optional relations to include (campaign, user, business)
      */
     async getCampaignClaims(filters, include) {
@@ -6484,8 +6583,20 @@ class RedemptionApi {
      * - Public users: Get active redemptions only
      * - Admin users: Get all redemptions with optional filtering
      *
-     * @param options - Filter and pagination options (active, search, adminAccess, page, limit, sortBy, sortOrder)
+     * @param options - Filter and pagination options (active, search, adminAccess, startDate, endDate, include, page, limit, sortBy, sortOrder)
      * @returns Paginated response with redemptions
+     *
+     * @example
+     * ```typescript
+     * // Get redemptions with redeem count included
+     * const redemptions = await api.getRedemptions({ include: ['redeemCount'] });
+     *
+     * // Filter by date range
+     * const dateFiltered = await api.getRedemptions({
+     *   startDate: new Date('2026-05-01'),
+     *   endDate: new Date('2026-06-30')
+     * });
+     * ```
      */
     async getRedemptions(options) {
         const params = [];
@@ -6496,10 +6607,25 @@ class RedemptionApi {
             params.push(`active=${options.active}`);
         if (options?.search)
             params.push(`search=${encodeURIComponent(options.search)}`);
+        // Support single tag or array of tags (multiple ?tags=a&tags=b)
+        if (options?.tags) {
+            const tagsArray = Array.isArray(options.tags) ? options.tags : [options.tags];
+            tagsArray.forEach(t => params.push(`tags=${encodeURIComponent(t)}`));
+        }
+        if (options?.startDate) {
+            const dateStr = options.startDate instanceof Date ? options.startDate.toISOString() : options.startDate;
+            params.push(`startDate=${encodeURIComponent(dateStr)}`);
+        }
+        if (options?.endDate) {
+            const dateStr = options.endDate instanceof Date ? options.endDate.toISOString() : options.endDate;
+            params.push(`endDate=${encodeURIComponent(dateStr)}`);
+        }
         if (options?.sortBy)
             params.push(`sortBy=${options.sortBy}`);
         if (options?.sortOrder)
             params.push(`sortOrder=${options.sortOrder}`);
+        if (options?.include?.length)
+            params.push(`include=${options.include.join(',')}`);
         const response = await this.apiClient.get(`${this.basePath}?${params.join('&')}`);
         return normalizeToPaginated(response);
     }
@@ -6519,9 +6645,20 @@ class RedemptionApi {
      * PUBLIC: Get redemption by ID
      *
      * Updated: /redemption/:id → /redemptions/:id
+     *
+     * @param id - Redemption UUID
+     * @param include - Relations to include: 'redeemCount'
+     *
+     * @example
+     * ```typescript
+     * // Get redemption with redeem count
+     * const redemption = await api.getRedemptionById('123', ['redeemCount']);
+     * console.log(redemption.redeemCount);
+     * ```
      */
-    async getRedemptionById(id) {
-        return this.apiClient.get(`${this.basePath}/${id}`);
+    async getRedemptionById(id, include) {
+        const params = include?.length ? `?include=${include.join(',')}` : '';
+        return this.apiClient.get(`${this.basePath}/${id}${params}`);
     }
     /**
      * PUBLIC: Get available supply for redemption
@@ -6558,7 +6695,7 @@ class RedemptionApi {
      * - Users: See only their own redeems (userId/businessId filters ignored)
      * - Admins: Can filter by userId, businessId, redemptionId, or status
      *
-     * @param filters - Filter and pagination options (redemptionId, userId, businessId, status, myRedeems, page, limit, sortBy, sortOrder)
+     * @param filters - Filter and pagination options (redemptionId, userId, businessId, status, dateFrom, dateTo, myRedeems, page, limit, sortBy, sortOrder)
      * @param include - Optional relations to include (redemption, user, business, transactions)
      * @returns Paginated response with redemption redeems
      */
@@ -6574,6 +6711,12 @@ class RedemptionApi {
             if (filters?.status) {
                 params.append('status', filters.status);
             }
+            if (filters?.dateFrom) {
+                params.append('dateFrom', filters.dateFrom instanceof Date ? filters.dateFrom.toISOString() : filters.dateFrom);
+            }
+            if (filters?.dateTo) {
+                params.append('dateTo', filters.dateTo instanceof Date ? filters.dateTo.toISOString() : filters.dateTo);
+            }
             // Add include parameter
             if (include && include.length > 0) {
                 include.forEach(relation => params.append('include', relation));
@@ -6590,6 +6733,10 @@ class RedemptionApi {
             params.append('businessId', filters.businessId);
         if (filters?.status)
             params.append('status', filters.status);
+        if (filters?.dateFrom)
+            params.append('dateFrom', filters.dateFrom instanceof Date ? filters.dateFrom.toISOString() : filters.dateFrom);
+        if (filters?.dateTo)
+            params.append('dateTo', filters.dateTo instanceof Date ? filters.dateTo.toISOString() : filters.dateTo);
         // Add include parameter
         if (include && include.length > 0) {
             include.forEach(relation => params.append('include', relation));
@@ -6730,10 +6877,14 @@ class RedemptionService {
      * UNIFIED: Get redemptions with intelligent access control and pagination
      * @param options.active - Filter by active status
      * @param options.search - Free text search across name, description, tags (case-insensitive)
+     * @param options.tags - Filter by tag(s) - single tag or array for OR match
      * @param options.adminAccess - Force admin access
+     * @param options.startDate - Filter redemptions starting on or after this date
+     * @param options.endDate - Filter redemptions ending on or before this date
+     * @param options.include - Include relations: 'redeemCount'
      * @param options.page - Page number (1-indexed)
      * @param options.limit - Results per page
-     * @param options.sortBy - Field to sort by ('name' | 'createdAt')
+     * @param options.sortBy - Field to sort by ('name' | 'createdAt' | 'startDate')
      * @param options.sortOrder - Sort direction ('ASC' | 'DESC')
      */
     async getRedemptions(options) {
@@ -6768,7 +6919,7 @@ class RedemptionService {
     }
     /**
      * UNIFIED: Get redemption redeems with filtering and pagination
-     * @param filters - Filter options (redemptionId, userId, businessId, status, myRedeems)
+     * @param filters - Filter options (redemptionId, userId, businessId, status, dateFrom, dateTo, myRedeems)
      * @param include - Optional relations to include (redemption, user, business, transactions)
      */
     async getRedemptionRedeems(filters, include) {
@@ -6788,7 +6939,7 @@ class RedemptionService {
     // ==========================================
     /**
      * Convenience: Get redemptions as admin with filtering and search
-     * @param options - Filter options (active, search, pagination)
+     * @param options - Filter options (active, search, tags, pagination)
      */
     async getRedemptionsAsAdmin(options) {
         return this.redemptionApi.getRedemptions({ ...options, adminAccess: true });
@@ -7239,6 +7390,82 @@ class TransactionService {
         return this.transactionApi.getTransactionAnalytics(analyticsRequest);
     }
 }
+
+// ============================================================================
+// TRANSACTION RESPONSE HELPERS
+// ============================================================================
+/**
+ * 🔍 Check if a transaction response requires external wallet signing
+ *
+ * Returns true when the user needs to sign the transaction externally
+ * (e.g., via WebAuthn signer app) before it can be submitted.
+ *
+ * @example
+ * ```typescript
+ * const response = await sdk.transactions.createTransaction(request);
+ * if (needsExternalSigning(response)) {
+ *   const signingUrl = getSigningUrl(response);
+ *   // Show "Click to Sign" button with signingUrl
+ * }
+ * ```
+ */
+function needsExternalSigning(response) {
+    if (!response)
+        return false;
+    return response.walletSigningStatus === 'WALLET_MISSING_SIGNING_ACCOUNT' ||
+        response.transactionStatus === exports.TransactionStatus.PENDING_SIGNATURE;
+}
+/**
+ * 🔍 Check if a transaction response is signed and ready for submission
+ *
+ * Returns true when the user has signed the transaction and it's waiting
+ * to be submitted to the blockchain (typically by a business in POS flows).
+ *
+ * @example
+ * ```typescript
+ * const response = await sdk.transactions.getTransaction(transactionId);
+ * if (needsSubmission(response)) {
+ *   // Transaction is signed, ready to submit
+ *   await sdk.transactions.submitSignedTransaction({ ... });
+ * }
+ * ```
+ */
+function needsSubmission(response) {
+    if (!response)
+        return false;
+    return response.walletSigningStatus === 'WALLET_HAS_SIGNED' &&
+        response.transactionStatus === exports.TransactionStatus.PENDING_SUBMISSION;
+}
+/**
+ * 🔗 Get the signing URL from a transaction response
+ *
+ * Returns the URL where the user should be redirected to sign the transaction.
+ * Optionally appends `signOnly=true` for POS flows where the signer app
+ * should skip the confirmation UI.
+ *
+ * @param response - Transaction response from API
+ * @param options - Optional configuration
+ * @param options.signOnly - If true, appends signOnly param for POS flows (default: false)
+ * @returns Signing URL or null if not available
+ *
+ * @example
+ * ```typescript
+ * const signingUrl = getSigningUrl(response, { signOnly: isPOSTransaction });
+ * if (signingUrl) {
+ *   window.open(signingUrl, '_blank');
+ * }
+ * ```
+ */
+function getSigningUrl(response, options) {
+    if (!response?.actionable?.actionUrl)
+        return null;
+    const baseUrl = response.actionable.actionUrl;
+    // For POS transactions, append signOnly to skip confirmation in signer app
+    if (options?.signOnly) {
+        return baseUrl + '&signOnly=true';
+    }
+    return baseUrl;
+}
 // ============================================================================
 // CLIENT TRANSACTION TYPES
 // ============================================================================
@@ -7885,6 +8112,15 @@ class TenantApi {
     // ==========================================
     // ADMIN OPERATIONS
     // ==========================================
+    /**
+     * ADMIN: Get current admin info (tenant admin authentication required)
+     *
+     * Endpoint: GET /admins/me
+     * Auth: @Admin()
+     */
+    async getCurrentAdmin() {
+        return this.apiClient.get(`${this.adminPath}/me`);
+    }
     /**
      * ADMIN: Update tenant information
      * UPDATED: Uses PUT /tenants (admin endpoint)
@@ -7959,6 +8195,12 @@ class TenantService {
     // ==========================================
     // ADMIN OPERATIONS
     // ==========================================
+    /**
+     * ADMIN: Get current admin info (tenant admin authentication required)
+     */
+    async getCurrentAdmin() {
+        return this.tenantApi.getCurrentAdmin();
+    }
     /**
      * ADMIN: Update tenant information
      * Returns full TenantDTO including sensitive config
@@ -8097,6 +8339,24 @@ class TenantManager {
     // ==========================================
     // ADMIN OPERATIONS
     // ==========================================
+    /**
+     * Admin: Get current admin info
+     *
+     * Retrieves the authenticated admin's profile information.
+     * Requires tenant admin authentication.
+     *
+     * @returns Promise resolving to current admin data
+     * @throws {PersApiError} When not authenticated as tenant admin
+     *
+     * @example
+     * ```typescript
+     * const admin = await sdk.tenants.getCurrentAdmin();
+     * console.log('Current admin:', admin.email);
+     * ```
+     */
+    async getCurrentAdmin() {
+        return this.tenantService.getCurrentAdmin();
+    }
     /**
      * Admin: Update tenant data
      *
@@ -8683,7 +8943,8 @@ const DEFAULT_PERS_CONFIG = {
     retries: 3,
     tokenRefreshMargin: 60, // Refresh tokens 60 seconds before expiry
     backgroundRefreshThreshold: 30, // Use background refresh if >30s remaining
-    captureWalletEvents: true // Auto-connect to wallet events after auth
+    captureWalletEvents: true, // Auto-connect to wallet events after auth
+    autoRestoreSession: true // Auto-restore session from stored tokens on init
 };
 /**
  * Build the API root URL based on config
@@ -8711,6 +8972,9 @@ function buildApiRoot(environment = 'production', version = 'v2', customApiUrl)
  * @internal
  */
 function buildWalletEventsWsUrl(environment = 'production', customWsUrl) {
+    if (customWsUrl) {
+        return customWsUrl;
+    }
     const wsUrls = {
         staging: 'wss://events-staging.pers.ninja',
         production: 'wss://events.pers.ninja'
@@ -8747,11 +9011,28 @@ class AuthApi {
     }
     /**
      * Login tenant admin with JWT
+     *
+     * Authenticates an admin in a tenant context.
+     *
+     * @param jwt - Authentication token (Firebase JWT)
+     * @param options - Tenant authentication options (tenantId for multi-tenant admins)
+     * @returns Session response with tenant context
+     * @throws MultipleContextSelectionError when tenantId is required but not provided
+     *
+     * @example
+     * ```typescript
+     * // Single tenant - auto-selects
+     * const response = await authApi.loginTenantAdmin(jwt);
+     *
+     * // Multiple tenants - explicit selection
+     * const response = await authApi.loginTenantAdmin(jwt, { tenantId: 'tenant-123' });
+     * ```
      */
-    async loginTenantAdmin(jwt) {
+    async loginTenantAdmin(jwt, options) {
         const body = {
             authToken: jwt,
-            authType: exports.AccountOwnerType.TENANT
+            authType: exports.AccountOwnerType.TENANT,
+            context: options?.tenantId ? { tenantId: options.tenantId } : undefined
         };
         return this.apiClient.post(`${this.basePath}/token`, body, { bypassAuth: true });
     }
@@ -8809,13 +9090,37 @@ class AuthApi {
     async refreshAccessToken(refreshToken) {
         return this.apiClient.post(`${this.basePath}/refresh`, { refreshToken }, { bypassAuth: true, isRefreshRequest: true });
     }
+    // ==========================================
+    // IDENTITY VERIFICATION (for session restore)
+    // Note: These duplicate calls in domain APIs (user-api, business-api)
+    // but are kept here to avoid circular dependencies during initialization.
+    // If endpoints change, update both locations.
+    // ==========================================
+    /**
+     * Get current authenticated user
+     */
+    async getCurrentUser() {
+        return this.apiClient.get('/users/me');
+    }
+    /**
+     * Get current business context
+     */
+    async getCurrentBusiness() {
+        return this.apiClient.get('/businesses/me');
+    }
+    /**
+     * Get current admin context
+     */
+    async getCurrentAdmin() {
+        return this.apiClient.get('/admins/me');
+    }
 }
 
 /**
  * Authentication status enumeration
  * Represents the current state of the authentication system
  */
-var AuthStatus;
+exports.AuthStatus = void 0;
 (function (AuthStatus) {
     /** User is authenticated with valid tokens */
     AuthStatus["AUTHENTICATED"] = "authenticated";
@@ -8831,8 +9136,14 @@ var AuthStatus;
     AuthStatus["SESSION_RESTORED"] = "session_restored";
     /** Session restoration determined no valid session exists */
     AuthStatus["SESSION_RESTORATION_FAILED"] = "session_restoration_failed";
-})(AuthStatus || (AuthStatus = {}));
+})(exports.AuthStatus || (exports.AuthStatus = {}));
 
+/**
+ * Type guard to check if provider implements extended storage methods
+ */
+function isExtendedProvider(provider) {
+    return 'setAuthType' in provider && typeof provider.setAuthType === 'function';
+}
 /**
  * Platform-agnostic authentication service
  * Handles login, token refresh, and storage operations
@@ -8842,7 +9153,13 @@ class AuthService {
         this.authApi = authApi;
         this.authProvider = authProvider;
         this.activeRefreshPromise = null;
-        this.currentAuthStatus = AuthStatus.UNAUTHENTICATED;
+        this.currentAuthStatus = exports.AuthStatus.UNAUTHENTICATED;
+    }
+    /**
+     * Get extended provider if available, null otherwise
+     */
+    get extendedProvider() {
+        return this.authProvider && isExtendedProvider(this.authProvider) ? this.authProvider : null;
     }
     /**
      * Emit auth status change to the app
@@ -8851,9 +9168,10 @@ class AuthService {
         if (this.currentAuthStatus === status)
             return; // No change
         this.currentAuthStatus = status;
-        if (this.authProvider && typeof this.authProvider.onAuthStatusChange === 'function') {
+        const extended = this.extendedProvider;
+        if (extended?.onAuthStatusChange) {
             try {
-                await this.authProvider.onAuthStatusChange(status);
+                await extended.onAuthStatusChange(status);
             }
             catch (error) {
                 console.warn('[AuthService] Auth status change callback failed:', error);
@@ -8865,9 +9183,14 @@ class AuthService {
     // ==========================================
     /**
      * Login tenant admin with JWT
+     *
+     * @param jwt - Authentication token (Firebase JWT)
+     * @param options - Tenant authentication options (tenantId for multi-tenant admins)
+     * @returns Session response with tenant context
+     * @throws Error with code MULTIPLE_CONTEXT_SELECTION_REQUIRED when tenantId is required but not provided
      */
-    async loginTenantAdmin(jwt) {
-        const response = await this.authApi.loginTenantAdmin(jwt);
+    async loginTenantAdmin(jwt, options) {
+        const response = await this.authApi.loginTenantAdmin(jwt, options);
         if (this.authProvider && response.accessToken) {
             await this.storeTokens(response.accessToken, response.refreshToken, exports.AccountOwnerType.TENANT, jwt);
         }
@@ -8925,7 +9248,7 @@ class AuthService {
      * Refresh access token with race condition protection
      */
     async refreshAccessToken(refreshToken) {
-        if (this.currentAuthStatus === AuthStatus.AUTH_FAILED) {
+        if (this.currentAuthStatus === exports.AuthStatus.AUTH_FAILED) {
             throw new Error('Auth failure has occurred, cannot refresh token');
         }
         if (this.activeRefreshPromise) {
@@ -8948,9 +9271,13 @@ class AuthService {
         if (!tokenToUse) {
             throw new Error('No refresh token available for token refresh');
         }
+        // Get the current authType to preserve it after refresh
+        const extended = this.extendedProvider;
+        const currentAuthType = extended?.getAuthType ? await extended.getAuthType() ?? undefined : undefined;
         const response = await this.authApi.refreshAccessToken(tokenToUse);
         if (this.authProvider && response.accessToken) {
-            await this.storeTokens(response.accessToken, response.refreshToken);
+            // Preserve the authType during refresh
+            await this.storeTokens(response.accessToken, response.refreshToken, currentAuthType);
         }
         return response;
     }
@@ -8968,7 +9295,7 @@ class AuthService {
      * Centralized method to avoid redundant token cleanup logic
      */
     async handleAuthFailure() {
-        if (this.currentAuthStatus === AuthStatus.AUTH_FAILED) {
+        if (this.currentAuthStatus === exports.AuthStatus.AUTH_FAILED) {
             return;
         }
         // Clear active refresh operations to prevent hanging promises
@@ -8976,7 +9303,7 @@ class AuthService {
         // Clear all stored tokens
         await this.clearTokens();
         // Emit auth failure status to notify the app
-        await this.emitAuthStatus(AuthStatus.AUTH_FAILED);
+        await this.emitAuthStatus(exports.AuthStatus.AUTH_FAILED);
     }
     /**
      * Check if we have valid authentication tokens
@@ -8988,6 +9315,27 @@ class AuthService {
         return !!token;
     }
     // ==========================================
+    // CONTEXT RETRIEVAL
+    // ==========================================
+    /**
+     * Get current authenticated user
+     */
+    async getCurrentUser() {
+        return this.authApi.getCurrentUser();
+    }
+    /**
+     * Get current business context
+     */
+    async getCurrentBusiness() {
+        return this.authApi.getCurrentBusiness();
+    }
+    /**
+     * Get current admin context
+     */
+    async getCurrentAdmin() {
+        return this.authApi.getCurrentAdmin();
+    }
+    // ==========================================
     // PRIVATE HELPERS
     // ==========================================
     /**
@@ -9001,20 +9349,21 @@ class AuthService {
             if (refreshToken) {
                 await this.authProvider.setRefreshToken(refreshToken);
             }
-            // Type-safe handling of extended token storage features
-            const extendedProvider = this.authProvider;
-            if (providerToken && extendedProvider.setProviderToken) {
-                await extendedProvider.setProviderToken(providerToken);
-            }
-            if (authType && extendedProvider.setAuthType) {
-                console.log('[AuthService] Storing auth type:', authType);
-                await extendedProvider.setAuthType(authType);
+            // Handle optional extended storage methods
+            const extended = this.extendedProvider;
+            if (extended) {
+                if (providerToken && extended.setProviderToken) {
+                    await extended.setProviderToken(providerToken);
+                }
+                if (authType && extended.setAuthType) {
+                    await extended.setAuthType(authType);
+                }
             }
-            else {
-                console.warn('[AuthService] Auth type not stored - authType:', authType, 'has setAuthType:', !!extendedProvider.setAuthType);
+            else if (authType) {
+                console.warn('[AuthService] Auth type not stored - provider does not implement setAuthType');
             }
             // Emit authenticated status on successful token storage
-            await this.emitAuthStatus(AuthStatus.AUTHENTICATED);
+            await this.emitAuthStatus(exports.AuthStatus.AUTHENTICATED);
         }
         catch (error) {
             console.warn('[AuthService] Failed to store tokens:', error);
@@ -9505,7 +9854,7 @@ class DefaultAuthProvider {
     async onAuthStatusChange(status) {
         try {
             // Handle provider-level responsibilities first
-            if (status === AuthStatus.TOKEN_EXPIRED && this.config.tokenProvider) {
+            if (status === exports.AuthStatus.TOKEN_EXPIRED && this.config.tokenProvider) {
                 const newToken = await this.config.tokenProvider();
                 if (newToken) {
                     await this.tokenManager.setAccessToken(newToken);
@@ -9556,6 +9905,11 @@ class DefaultAuthProvider {
     async hasValidToken() {
         return this.tokenManager.hasAccessToken();
     }
+    async setAuthType(authType) {
+        // Auth type is derived from JWT, so this is a no-op
+        // The authType in JWT is the source of truth
+        // This method exists to satisfy the ExtendedTokenStorageProvider interface
+    }
     async getAuthType() {
         // Read from JWT instead of separate storage for single source of truth
         const token = await this.tokenManager.getAccessToken();
@@ -9930,6 +10284,108 @@ class PersApiClient {
     }
 }
 
+/**
+ * Static JWT Authentication Provider
+ * For server-side integrations with long-lived JWT tokens
+ *
+ * Use this provider when:
+ * - Running in server environments (Node.js, serverless functions)
+ * - Using static/long-lived JWT tokens (not OAuth flow)
+ * - No token refresh mechanism needed
+ * - JWT rotation handled externally (e.g., environment variables)
+ *
+ * @example Server-side usage
+ * ```typescript
+ * const sdk = new PersSdk(httpClient, {
+ *   environment: 'production',
+ *   apiProjectKey: 'your-project',
+ *   authProvider: new StaticJwtAuthProvider(
+ *     process.env.PERS_JWT_TOKEN!,
+ *     'your-project',
+ *     'business' // or 'admin'
+ *   )
+ * });
+ * ```
+ */
+/**
+ * Simple authentication provider for static JWT tokens
+ * No token storage, refresh, or DPoP - designed for server-side use
+ */
+class StaticJwtAuthProvider {
+    constructor(configOrJwt, projectKey, authType) {
+        if (typeof configOrJwt === 'string') {
+            // Legacy constructor: (jwt, projectKey, authType)
+            this.jwt = configOrJwt;
+            this.projectKey = projectKey;
+            this.authType = authType || exports.AccountOwnerType.BUSINESS;
+        }
+        else {
+            // New constructor: (config)
+            this.jwt = configOrJwt.jwt;
+            this.projectKey = configOrJwt.projectKey;
+            this.authType = configOrJwt.authType || exports.AccountOwnerType.BUSINESS;
+            this.statusChangeCallback = configOrJwt.onAuthStatusChange;
+        }
+        if (!this.jwt) {
+            throw new Error('StaticJwtAuthProvider: JWT token is required');
+        }
+        if (!this.projectKey) {
+            throw new Error('StaticJwtAuthProvider: Project key is required');
+        }
+    }
+    /**
+     * Get the static JWT token
+     * @returns The configured JWT token
+     */
+    async getToken() {
+        return this.jwt;
+    }
+    /**
+     * Get project key for API requests
+     * @returns The configured project key
+     */
+    async getProjectKey() {
+        return this.projectKey;
+    }
+    /**
+     * Get authentication headers (Bearer token)
+     * Note: No DPoP support for server-side static tokens
+     *
+     * @param token - The access token (ignored, uses configured JWT)
+     * @returns Headers with Bearer authorization
+     */
+    async getAuthHeaders(token) {
+        const actualToken = token || this.jwt;
+        return actualToken ? { 'Authorization': `Bearer ${actualToken}` } : {};
+    }
+    /**
+     * Handle authentication status changes
+     *
+     * Note: Static JWTs cannot be refreshed automatically.
+     * TOKEN_EXPIRED status indicates manual JWT rotation is needed.
+     *
+     * @param status - The new authentication status
+     */
+    async onAuthStatusChange(status) {
+        if (status === exports.AuthStatus.TOKEN_EXPIRED) {
+            console.warn('[StaticJwtAuthProvider] JWT token expired. Manual rotation required. ' +
+                'Update the JWT in your environment configuration.');
+        }
+        // Delegate to custom callback if provided
+        if (this.statusChangeCallback) {
+            await this.statusChangeCallback(status);
+        }
+    }
+    /**
+     * Clear tokens (no-op for static provider)
+     * Static JWTs are immutable and managed externally
+     */
+    async clearTokens() {
+        // No-op: Static JWTs cannot be cleared, they must be rotated externally
+        console.warn('[StaticJwtAuthProvider] clearTokens() called but static JWTs cannot be cleared. Rotate JWT externally.');
+    }
+}
+
 /**
  * PERS SDK Event Emitter
  *
@@ -9949,6 +10405,7 @@ function generateEventId() {
  *
  * All events flow through one subscription point.
  * Optional filtering at subscription level.
+ * Supports replay of last auth event for late subscribers.
  *
  * @example Basic Usage
  * ```typescript
@@ -9972,6 +10429,13 @@ function generateEventId() {
  *   showNotification(event.userMessage);
  * }, { excludeDomains: ['validation'] });
  *
+ * // Subscribe with replay - get last auth event if missed
+ * sdk.events.subscribe((event) => {
+ *   if (event.type === 'session_restored') {
+ *     setUser(event.details.user);
+ *   }
+ * }, { domains: ['authentication'], replay: true });
+ *
  * // Cleanup
  * unsubscribe();
  * ```
@@ -9979,6 +10443,8 @@ function generateEventId() {
 let emitterInstanceCounter = 0;
 class PersEventEmitter {
     constructor() {
+        // Store last auth event for replay to late subscribers
+        this.lastAuthEvent = null;
         this.handlers = new Set();
         this._instanceId = ++emitterInstanceCounter;
     }
@@ -9989,7 +10455,7 @@ class PersEventEmitter {
      * Subscribe to events
      *
      * @param handler - Callback for matching events
-     * @param filter - Optional filter by domain and/or level
+     * @param filter - Optional filter by domain and/or level. Set `replay: true` to receive last auth event if missed.
      * @returns Unsubscribe function
      *
      * @example All events
@@ -10013,10 +10479,35 @@ class PersEventEmitter {
      *   confetti();
      * }, { domains: ['transaction'], levels: ['success'] });
      * ```
+     *
+     * @example Auth events with replay (catches session_restored even if emitted before subscription)
+     * ```typescript
+     * sdk.events.subscribe((event) => {
+     *   if (event.type === 'session_restored') {
+     *     const { user } = event.details;
+     *     setUser(user);
+     *   }
+     * }, { domains: ['authentication'], replay: true });
+     * ```
      */
     subscribe(handler, filter) {
         const filteredHandler = { handler, filter };
         this.handlers.add(filteredHandler);
+        // If replay is requested and we have a cached auth event, replay it immediately
+        if (filter?.replay && this.lastAuthEvent) {
+            // Check if event matches the filter
+            if (!filter || this.matchesFilter(this.lastAuthEvent, filter)) {
+                // Use queueMicrotask to ensure handler runs after subscribe returns
+                queueMicrotask(() => {
+                    try {
+                        handler(this.lastAuthEvent);
+                    }
+                    catch (error) {
+                        console.error('[PersEventEmitter] Replay handler error:', error);
+                    }
+                });
+            }
+        }
         return () => this.handlers.delete(filteredHandler);
     }
     /**
@@ -10041,6 +10532,7 @@ class PersEventEmitter {
      * Emit a success event
      *
      * Domain is restricted to business domains only (Domain type).
+     * Auth events (login_success, session_restored) are cached for replay to late subscribers.
      *
      * @param event - Success event data (id and timestamp auto-generated)
      * @returns The complete event object
@@ -10061,6 +10553,15 @@ class PersEventEmitter {
             id: generateEventId(),
             timestamp: Date.now()
         };
+        // Cache auth events for replay to late subscribers
+        if (event.domain === 'authentication' &&
+            (event.type === 'login_success' || event.type === 'session_restored')) {
+            this.lastAuthEvent = fullEvent;
+        }
+        // Clear cached auth on logout
+        if (event.domain === 'authentication' && event.type === 'logout_success') {
+            this.lastAuthEvent = null;
+        }
         this.notifyHandlers(fullEvent);
         return fullEvent;
     }
@@ -10088,6 +10589,10 @@ class PersEventEmitter {
             id: generateEventId(),
             timestamp: Date.now()
         };
+        // Clear cached auth on auth failure (session invalid)
+        if (event.domain === 'authentication' && event.type === 'session_restoration_failed') {
+            this.lastAuthEvent = null;
+        }
         this.notifyHandlers(fullEvent);
         return fullEvent;
     }
@@ -10211,7 +10716,8 @@ class AuthManager {
         this.events?.emitSuccess({
             domain: 'authentication',
             type: 'login_success',
-            userMessage: 'Successfully logged in'
+            userMessage: 'Successfully logged in',
+            details: { user: result.user }
         });
         return result;
     }
@@ -10259,7 +10765,66 @@ class AuthManager {
      */
     async loginAsBusiness(jwtToken, options) {
         const authService = this.apiClient.getAuthService();
-        return authService.loginBusiness(jwtToken, options);
+        const result = await authService.loginBusiness(jwtToken, options);
+        this.events?.emitSuccess({
+            domain: 'authentication',
+            type: 'login_success',
+            userMessage: 'Successfully logged in as business',
+            details: { user: result.user, business: result.business }
+        });
+        return result;
+    }
+    /**
+     * Login as tenant admin with JWT token
+     *
+     * Authenticates an admin in a tenant context.
+     *
+     * **Auto-Selection Behavior:**
+     * - If admin has access to a single tenant, it's auto-selected
+     * - If admin has access to multiple tenants and no tenantId is provided,
+     *   throws `MULTIPLE_CONTEXT_SELECTION_REQUIRED` error with available options
+     *
+     * @param jwtToken - JWT token from auth provider (Firebase, etc.)
+     * @param options - Tenant authentication options (tenantId for multi-tenant admins)
+     * @returns Promise resolving to authentication response with tenant context
+     * @throws Error with code `MULTIPLE_CONTEXT_SELECTION_REQUIRED` when tenantId is needed
+     *
+     * @example Single Tenant Access
+     * ```typescript
+     * // Auto-selects the admin's only tenant
+     * const result = await sdk.auth.loginAsTenant(jwt);
+     * console.log('Tenant:', result.admin?.tenantId);
+     * ```
+     *
+     * @example Multiple Tenant Access
+     * ```typescript
+     * try {
+     *   const result = await sdk.auth.loginAsTenant(jwt);
+     * } catch (error) {
+     *   if (error.code === 'MULTIPLE_CONTEXT_SELECTION_REQUIRED') {
+     *     // Show tenant selector UI
+     *     const selectedId = await showTenantSelector(error.details.availableOptions);
+     *     const result = await sdk.auth.loginAsTenant(jwt, { tenantId: selectedId });
+     *   }
+     * }
+     * ```
+     *
+     * @example Direct Tenant Selection
+     * ```typescript
+     * const result = await sdk.auth.loginAsTenant(jwt, { tenantId: 'tenant-123' });
+     * console.log('Authenticated as admin for tenant:', result.admin?.tenantId);
+     * ```
+     */
+    async loginAsTenant(jwtToken, options) {
+        const authService = this.apiClient.getAuthService();
+        const result = await authService.loginTenantAdmin(jwtToken, options);
+        this.events?.emitSuccess({
+            domain: 'authentication',
+            type: 'login_success',
+            userMessage: 'Successfully logged in as tenant admin',
+            details: { admin: result.admin }
+        });
+        return result;
     }
     /**
      * Get current business context
@@ -10277,7 +10842,27 @@ class AuthManager {
      * ```
      */
     async getCurrentBusiness() {
-        return this.apiClient.get('/businesses/me');
+        const authService = this.apiClient.getAuthService();
+        return authService.getCurrentBusiness();
+    }
+    /**
+     * Get current admin context
+     *
+     * Retrieves the current admin data if authenticated as tenant admin.
+     * Requires prior tenant authentication via {@link loginAsTenant}.
+     *
+     * @returns Promise resolving to current admin data
+     * @throws {PersApiError} When not authenticated as tenant admin
+     *
+     * @example
+     * ```typescript
+     * const admin = await sdk.auth.getCurrentAdmin();
+     * console.log('Current admin:', admin.email);
+     * ```
+     */
+    async getCurrentAdmin() {
+        const authService = this.apiClient.getAuthService();
+        return authService.getCurrentAdmin();
     }
     /**
      * Login with raw user data
@@ -10321,7 +10906,8 @@ class AuthManager {
      * ```
      */
     async getCurrentUser() {
-        return this.apiClient.get('/users/me');
+        const authService = this.apiClient.getAuthService();
+        return authService.getCurrentUser();
     }
     /**
      * Check if user is authenticated
@@ -10399,6 +10985,11 @@ class AuthManager {
     async clearAuth() {
         const authService = this.apiClient.getAuthService();
         await authService.clearTokens();
+        this.events?.emitSuccess({
+            domain: 'authentication',
+            type: 'logout_success',
+            userMessage: 'Successfully logged out'
+        });
     }
     /**
      * Ensure authentication token is valid
@@ -12123,7 +12714,7 @@ class CampaignManager {
      * Returns campaigns with pagination metadata for efficient data loading.
      * Intelligent access: Public gets active only, Business gets own campaigns, Admin gets all.
      *
-     * @param options - Pagination and filter options (page, limit, sortBy, sortOrder, active, tag, search, businessId, include)
+     * @param options - Pagination and filter options (page, limit, sortBy, sortOrder, active, tag, search, businessId, startDate, endDate, include)
      * @returns Promise resolving to paginated campaigns with metadata
      *
      * @example
@@ -12153,18 +12744,22 @@ class CampaignManager {
      *   active: true
      * });
      *
-     * // Get active campaigns sorted by creation date
-     * const activeCampaigns = await sdk.campaigns.getCampaigns({
-     *   active: true,
-     *   sortBy: 'createdAt',
-     *   sortOrder: 'DESC',
-     *   page: 1,
-     *   limit: 25
+     * // Filter by date range
+     * const dateFiltered = await sdk.campaigns.getCampaigns({
+     *   startDate: new Date('2026-05-01'),
+     *   endDate: new Date('2026-12-31'),
+     *   active: true
+     * });
+     *
+     * // Get campaigns with claim count
+     * const withCounts = await sdk.campaigns.getCampaigns({
+     *   include: ['claimCount']
      * });
+     * withCounts.data.forEach(c => console.log(`${c.name}: ${c.claimCount} claims`));
      *
-     * // Include related data (trigger sources and businesses)
+     * // Include related data (trigger sources, businesses, and claim count)
      * const campaignsWithRelations = await sdk.campaigns.getCampaigns({
-     *   include: ['triggerSources', 'businesses']
+     *   include: ['triggerSources', 'businesses', 'claimCount']
      * });
      * ```
      */
@@ -12615,58 +13210,52 @@ class CampaignManager {
     async deleteCampaignBusinessEngagement(campaignId, engagementId) {
         return this.campaignService.deleteCampaignBusinessEngagement(campaignId, engagementId);
     }
-    /**
-     * Admin: Get all campaign claims
-     *
-     * Retrieves all campaign claims across the system for comprehensive reporting
-     * and analytics. This operation requires administrator privileges and provides
-     * system-wide visibility into campaign performance and user engagement.
-     *
-     * @returns Promise resolving to array of all campaign claims
-     * @throws {PersApiError} When not authenticated as administrator
-     *
-     * @example
-     * ```typescript
-     * // Admin operation - get campaign performance data
-     * const allClaims = await sdk.campaigns.getCampaignClaims();
-     *
-     * console.log(`Campaign Performance Report:`);
-     * console.log(`Total claims: ${allClaims.length}`);
-     *
-     * // Analyze claims by campaign
-     * const claimsByCampaign = allClaims.reduce((acc, claim) => {
-     *   const campaignId = claim.campaignId;
-     *   acc[campaignId] = (acc[campaignId] || 0) + 1;
-     *   return acc;
-     * }, {});
-     *
-     * console.log('\nClaims by Campaign:');
-     * Object.entries(claimsByCampaign).forEach(([campaignId, count]) => {
-     *   console.log(`${campaignId}: ${count} claims`);
-     * });
-     * ```
-     */
     /**
      * Admin: Get campaign claims with optional filters
      *
-     * Retrieves campaign claims with optional filtering by campaign, user, or business.
+     * Retrieves campaign claims with optional filtering by campaign, user, business, or date range.
      * This operation requires administrator privileges and provides system-wide
      * visibility into campaign performance and user engagement.
      *
      * @param filters - Optional filters and pagination options
+     * @param filters.campaignId - Filter by specific campaign ID
+     * @param filters.userId - Filter by specific user ID
+     * @param filters.businessId - Filter by specific business ID
+     * @param filters.dateFrom - Filter claims from this date (inclusive)
+     * @param filters.dateTo - Filter claims until this date (inclusive)
+     * @param filters.page - Page number for pagination
+     * @param filters.limit - Items per page
+     * @param filters.sortBy - Field to sort by
+     * @param filters.sortOrder - Sort direction ('asc' or 'desc')
+     * @param include - Optional relations to include for enrichment
      * @returns Promise resolving to paginated campaign claims
      * @throws {PersApiError} When not authenticated as administrator
      *
-     * @example
+     * @example Get All Claims
      * ```typescript
-     * // Get all claims
-     * const allClaims = await sdk.campaigns.getCampaignClaims();
+     * const { data: allClaims, pagination } = await sdk.campaigns.getCampaignClaims();
+     * console.log(`Total: ${pagination.total}`);
+     * ```
      *
-     * // Get claims for specific user
-     * const userClaims = await sdk.campaigns.getCampaignClaims({ userId: 'user-123' });
+     * @example Filter by User
+     * ```typescript
+     * const { data: userClaims } = await sdk.campaigns.getCampaignClaims({ userId: 'user-123' });
+     * ```
      *
-     * // Get claims for specific campaign with pagination
-     * const page1 = await sdk.campaigns.getCampaignClaims({
+     * @example Filter by Date Range
+     * ```typescript
+     * // Get claims within a specific date range
+     * const { data: monthClaims } = await sdk.campaigns.getCampaignClaims({
+     *   dateFrom: new Date('2024-01-01'),
+     *   dateTo: new Date('2024-01-31'),
+     *   limit: 100
+     * });
+     * console.log(`${monthClaims.length} claims in January 2024`);
+     * ```
+     *
+     * @example With Pagination and Campaign Filter
+     * ```typescript
+     * const { data: page1 } = await sdk.campaigns.getCampaignClaims({
      *   campaignId: 'campaign-456',
      *   page: 1,
      *   limit: 50
@@ -13271,9 +13860,19 @@ class RedemptionManager {
      *
      * Retrieves all redemption redeems across the platform with filtering capabilities.
      * This is an admin-level operation that allows monitoring and analytics of redemption
-     * activity. Supports filtering by user, redemption offer, and enrichment of related entities.
-     *
-     * @param filters - Filter options (userId, redemptionId, pagination)
+     * activity. Supports filtering by user, redemption offer, date range, and enrichment of related entities.
+     *
+     * @param filters - Filter options (userId, redemptionId, businessId, status, dateFrom, dateTo, pagination)
+     * @param filters.userId - Filter by specific user ID
+     * @param filters.redemptionId - Filter by specific redemption offer ID
+     * @param filters.businessId - Filter by specific business ID
+     * @param filters.status - Filter by redeem status
+     * @param filters.dateFrom - Filter redeems from this date (inclusive)
+     * @param filters.dateTo - Filter redeems until this date (inclusive)
+     * @param filters.page - Page number for pagination
+     * @param filters.limit - Items per page
+     * @param filters.sortBy - Field to sort by
+     * @param filters.sortOrder - Sort direction ('asc' or 'desc')
      * @param include - Optional relations to include for enrichment
      * @returns Promise resolving to paginated list of redemption redeems
      * @throws {PersApiError} When not authenticated as admin
@@ -13298,6 +13897,18 @@ class RedemptionManager {
      * console.log(`User has ${userRedeems.length} redemptions`);
      * ```
      *
+     * @example Filter by Date Range
+     * ```typescript
+     * // Get redeems within a specific date range
+     * const { data: recentRedeems } = await sdk.redemptions.getRedemptionRedeems({
+     *   dateFrom: new Date('2024-01-01'),
+     *   dateTo: new Date('2024-01-31'),
+     *   limit: 100
+     * });
+     *
+     * console.log(`${recentRedeems.length} redeems in January 2024`);
+     * ```
+     *
      * @example With Enriched Data
      * ```typescript
      * const { data: redeems } = await sdk.redemptions.getRedemptionRedeems(
@@ -17026,6 +17637,12 @@ class PersEventsClient {
         }
     }
 }
+/**
+ * Create a PERS Events client instance
+ */
+function createPersEventsClient(config) {
+    return new PersEventsClient(config);
+}
 
 /**
  * Wallet Events Manager - Real-time blockchain events for user's wallets
@@ -17228,7 +17845,8 @@ class WalletEventsManager {
         }
         // Save subscriptions for auto-resubscribe on reconnect
         this.lastSubscriptions.wallets = wallets;
-        return this.client.subscribeWallets(wallets);
+        const result = await this.client.subscribeWallets(wallets);
+        return result;
     }
     /**
      * Subscribe to chain events (Admin Dashboard)
@@ -17251,7 +17869,8 @@ class WalletEventsManager {
         }
         // Save subscriptions for auto-resubscribe on reconnect
         this.lastSubscriptions.chains = chains;
-        return this.client.subscribeChains(chains);
+        const result = await this.client.subscribeChains(chains);
+        return result;
     }
     /**
      * Unsubscribe from wallet events
@@ -17561,6 +18180,24 @@ class PersSDK {
         this.apiClient.setEvents(this._events);
         // Auto-connect to wallet events on successful login (if enabled)
         this.setupWalletEventsAutoConnect();
+        // Auto-restore session from stored tokens (if enabled, default: true)
+        this.setupAutoRestoreSession();
+    }
+    /**
+     * Setup automatic session restoration from stored tokens
+     * @internal
+     */
+    setupAutoRestoreSession() {
+        const config = this.apiClient.getConfig();
+        // Check if autoRestoreSession is enabled (default: true)
+        if (config.autoRestoreSession === false) {
+            return;
+        }
+        // Fire-and-forget: restore session asynchronously
+        // Events will be emitted on success/failure
+        this.restoreSession().catch(() => {
+            // Error already emitted via session_restoration_failed event
+        });
     }
     /**
      * Setup auto-connect for wallet events on authentication
@@ -17638,22 +18275,23 @@ class PersSDK {
     /**
      * Restore user session from stored tokens
      *
-     * Call this method after SDK initialization to restore the user's session
-     * if valid tokens exist. This is useful for maintaining login state across
-     * app restarts.
+     * **Note:** This method is called automatically on SDK initialization when
+     * `autoRestoreSession` is enabled (default: true). You only need to call this
+     * manually if you disabled auto-restore or need to force a session refresh.
+     *
+     * Validates stored tokens and fetches user data to restore the session.
+     * Emits `session_restored` event on success, `session_restoration_failed` on error.
      *
      * **Important:** Only works for USER and BUSINESS accounts. Admin/tenant
      * accounts don't support user data fetching, so this will return null for them
      * (though their tokens remain valid for API calls).
      *
-     * Emits auth domain success event when session is restored.
-     *
      * @returns Promise resolving to User data if session restored, null if no session or admin account
      * @throws {PersError} If token validation or user fetch fails
      *
      * @example
      * ```typescript
-     * // Call after initial render for better perceived performance
+     * // Manual restore (only needed if autoRestoreSession: false)
      * const user = await sdk.restoreSession();
      * if (user) {
      *   console.log('Welcome back,', user.name);
@@ -17667,25 +18305,57 @@ class PersSDK {
         }
         // Check auth type - only restore session for user and business accounts
         const authProvider = this.apiClient.getConfig().authProvider;
-        if (authProvider?.getAuthType) {
-            const authType = await authProvider.getAuthType();
-            if (authType === exports.AccountOwnerType.TENANT) {
-                // Admin sessions don't support getCurrentUser(), skip restoration
-                // Tokens are valid and will be used for API calls
+        const authType = authProvider?.getAuthType ? await authProvider.getAuthType() : exports.AccountOwnerType.USER;
+        if (authType === exports.AccountOwnerType.TENANT) {
+            // Ensure token is valid (refresh if expired) before fetching admin
+            try {
+                await this.auth.ensureValidToken();
+                // Fetch current admin data
+                const adminData = await this.auth.getCurrentAdmin();
+                // Emit session restored for tenant admin
+                this._events.emitSuccess({
+                    type: 'session_restored',
+                    domain: 'authentication',
+                    userMessage: 'Admin session restored successfully',
+                    details: { admin: adminData }
+                });
                 return null;
             }
+            catch (error) {
+                await this.auth.clearAuth();
+                this._events.emitError({
+                    type: 'session_restoration_failed',
+                    domain: 'authentication',
+                    userMessage: 'Admin session restoration failed',
+                    code: 'SESSION_INVALID',
+                    details: { error }
+                });
+                throw error;
+            }
         }
         try {
             // Ensure token is valid (refresh if expired) before fetching user
             await this.auth.ensureValidToken();
-            // Fetch user data to restore session
+            // For BUSINESS auth, only fetch business context (no access to /users/me)
+            if (authType === exports.AccountOwnerType.BUSINESS) {
+                const businessData = await this.auth.getCurrentBusiness();
+                // Emit event with business data (no user data for business auth)
+                this._events.emitSuccess({
+                    type: 'session_restored',
+                    domain: 'authentication',
+                    userMessage: 'Business session restored successfully',
+                    details: { business: businessData }
+                });
+                return null; // No user data for business auth
+            }
+            // For USER auth, fetch user data
             const userData = await this.auth.getCurrentUser();
-            // Emit event through proper event emitter
+            // Emit event with user data
             this._events.emitSuccess({
                 type: 'session_restored',
                 domain: 'authentication',
                 userMessage: 'Session restored successfully',
-                details: { userId: userData.id }
+                details: { user: userData }
             });
             return userData;
         }
@@ -18178,6 +18848,114 @@ class PersSDK {
         return !!this.apiClient.getConfig().authProvider;
     }
 }
+/**
+ * Factory function for creating PERS SDK
+ *
+ * @param httpClient Platform-specific HTTP client implementation
+ * @param config SDK configuration options
+ * @returns PERS SDK instance
+ */
+function createPersSDK(httpClient, config) {
+    return new PersSDK(httpClient, config);
+}
+
+class IndexedDBTokenStorage {
+    constructor() {
+        this.supportsObjects = true;
+        this.dbPromise = null;
+        if (typeof indexedDB === 'undefined') {
+            console.warn('IndexedDB is not available in this environment');
+        }
+    }
+    getDB() {
+        if (this.dbPromise)
+            return this.dbPromise;
+        this.dbPromise = new Promise((resolve, reject) => {
+            if (typeof indexedDB === 'undefined') {
+                return reject(new Error('IndexedDB not supported'));
+            }
+            const request = indexedDB.open(IndexedDBTokenStorage.DB_NAME, IndexedDBTokenStorage.DB_VERSION);
+            request.onupgradeneeded = (event) => {
+                const db = event.target.result;
+                if (!db.objectStoreNames.contains(IndexedDBTokenStorage.STORE_NAME)) {
+                    db.createObjectStore(IndexedDBTokenStorage.STORE_NAME);
+                }
+            };
+            request.onsuccess = (event) => {
+                resolve(event.target.result);
+            };
+            request.onerror = (event) => {
+                reject(event.target.error);
+            };
+        });
+        return this.dbPromise;
+    }
+    async get(key) {
+        try {
+            const db = await this.getDB();
+            return new Promise((resolve, reject) => {
+                const transaction = db.transaction(IndexedDBTokenStorage.STORE_NAME, 'readonly');
+                const store = transaction.objectStore(IndexedDBTokenStorage.STORE_NAME);
+                const request = store.get(key);
+                request.onsuccess = () => resolve(request.result || null);
+                request.onerror = () => reject(request.error);
+            });
+        }
+        catch (e) {
+            console.warn('[IndexedDBTokenStorage] Failed to get key', key, e);
+            return null;
+        }
+    }
+    async set(key, value) {
+        try {
+            const db = await this.getDB();
+            return new Promise((resolve, reject) => {
+                const transaction = db.transaction(IndexedDBTokenStorage.STORE_NAME, 'readwrite');
+                const store = transaction.objectStore(IndexedDBTokenStorage.STORE_NAME);
+                const request = store.put(value, key);
+                request.onsuccess = () => resolve();
+                request.onerror = () => reject(request.error);
+            });
+        }
+        catch (e) {
+            console.error('[IndexedDBTokenStorage] Failed to set key', key, e);
+            throw e;
+        }
+    }
+    async remove(key) {
+        try {
+            const db = await this.getDB();
+            return new Promise((resolve, reject) => {
+                const transaction = db.transaction(IndexedDBTokenStorage.STORE_NAME, 'readwrite');
+                const store = transaction.objectStore(IndexedDBTokenStorage.STORE_NAME);
+                const request = store.delete(key);
+                request.onsuccess = () => resolve();
+                request.onerror = () => reject(request.error);
+            });
+        }
+        catch (e) {
+            console.warn('[IndexedDBTokenStorage] Failed to remove key', key, e);
+        }
+    }
+    async clear() {
+        try {
+            const db = await this.getDB();
+            return new Promise((resolve, reject) => {
+                const transaction = db.transaction(IndexedDBTokenStorage.STORE_NAME, 'readwrite');
+                const store = transaction.objectStore(IndexedDBTokenStorage.STORE_NAME);
+                const request = store.clear();
+                request.onsuccess = () => resolve();
+                request.onerror = () => reject(request.error);
+            });
+        }
+        catch (e) {
+            console.warn('[IndexedDBTokenStorage] Failed to clear storage', e);
+        }
+    }
+}
+IndexedDBTokenStorage.DB_NAME = 'pers-sdk-storage';
+IndexedDBTokenStorage.STORE_NAME = 'auth-tokens';
+IndexedDBTokenStorage.DB_VERSION = 1;
 
 /**
  * Environment Detection Utility
@@ -18208,7 +18986,16 @@ function detectEnvironment() {
 /**
  * Global environment info (cached)
  */
-detectEnvironment();
+const environment = detectEnvironment();
+/**
+ * Warns if environment might have bundling issues
+ */
+function warnIfProblematicEnvironment(feature) {
+    if (environment.needsNodeStreamPolyfills) {
+        console.warn(`[PERS SDK] ${feature} may require additional polyfills in web environments. ` +
+            `If you encounter 'readable-stream' errors, ensure proper polyfills are configured.`);
+    }
+}
 
 /**
  * AsyncStorage Token Storage for React Native Mobile Platforms
@@ -18821,6 +19608,7 @@ const SDKContext = react.createContext(null);
  */
 const PersSDKProvider = ({ children, config }) => {
     const initializingRef = react.useRef(false);
+    const eventUnsubscribeRef = react.useRef(null);
     // State refs for stable functions to read current values
     const sdkRef = react.useRef(null);
     const isInitializedRef = react.useRef(false);
@@ -18874,6 +19662,21 @@ const PersSDKProvider = ({ children, config }) => {
             };
             // Initialize PersSDK with platform-aware auth provider
             const sdkInstance = new PersSDK(httpClient, sdkConfig);
+            // Subscribe to auth events BEFORE exposing SDK to consumers
+            // This ensures no events are missed due to React timing
+            eventUnsubscribeRef.current = sdkInstance.events.subscribe((event) => {
+                if (event.type === 'session_restored' || event.type === 'login_success') {
+                    const details = event.details;
+                    if (details?.user) {
+                        setUser(details.user);
+                        setIsAuthenticated(true);
+                    }
+                }
+                if (event.type === 'logout_success' || event.type === 'session_restoration_failed' || event.code === 'AUTH_FAILED') {
+                    setUser(null);
+                    setIsAuthenticated(false);
+                }
+            }, { domains: ['authentication'], replay: true });
             setAuthProvider(authProvider);
             setSdk(sdkInstance);
             setIsInitialized(true);
@@ -18887,6 +19690,15 @@ const PersSDKProvider = ({ children, config }) => {
             initializingRef.current = false;
         }
     }, [isInitialized]);
+    // Cleanup subscription on unmount
+    react.useEffect(() => {
+        return () => {
+            if (eventUnsubscribeRef.current) {
+                eventUnsubscribeRef.current();
+                eventUnsubscribeRef.current = null;
+            }
+        };
+    }, []);
     const setAuthenticationState = react.useCallback((user, isAuthenticated) => {
         setUser(user);
         setIsAuthenticated(isAuthenticated);
@@ -18933,42 +19745,7 @@ const PersSDKProvider = ({ children, config }) => {
             console.error('[PersSDK] Failed to restore session:', error);
             throw error;
         }
-    }, [setAuthenticationState]); // Depends on setAuthenticationState
-    // Listen for authentication events from core SDK
-    // Set up immediately when SDK is created (don't wait for isInitialized)
-    // to catch session_restored events that fire during SDK initialization
-    react.useEffect(() => {
-        if (!sdk)
-            return;
-        const unsubscribe = sdk.events.subscribe((event) => {
-            if (event.domain !== 'authentication')
-                return;
-            // Session restored successfully - sync React state
-            if (event.type === 'session_restored') {
-                console.log('[PersSDK] Session restoration event received, syncing state...');
-                // Read user from event details if available, otherwise fetch
-                const userId = event.details?.userId;
-                if (userId) {
-                    // User ID available, fetch user data
-                    sdk.users.getCurrentUser()
-                        .then(userData => {
-                        setAuthenticationState(userData, true);
-                    })
-                        .catch(error => {
-                        console.error('[PersSDK] Failed to sync restored session:', error);
-                    });
-                }
-            }
-            // Session restoration failed or auth error - clear React state
-            if (event.type === 'session_restoration_failed' || event.code === 'AUTH_FAILED') {
-                console.log('[PersSDK] Authentication failed - clearing session');
-                setAuthenticationState(null, false);
-            }
-        }, { domains: ['authentication'] });
-        return () => {
-            unsubscribe();
-        };
-    }, [sdk, setAuthenticationState]);
+    }, [setAuthenticationState]);
     // iOS/Android: Monitor app state and validate tokens when app becomes active
     react.useEffect(() => {
         if (!sdk || reactNative.Platform.OS === 'web') {
@@ -18976,7 +19753,6 @@ const PersSDKProvider = ({ children, config }) => {
         }
         const handleAppStateChange = async (nextAppState) => {
             if (nextAppState === 'active' && isAuthenticated) {
-                console.log('[PersSDK] App became active - validating tokens');
                 try {
                     // Trigger token validation when app resumes from background
                     // This ensures tokens are checked after extended inactivity
@@ -19066,7 +19842,7 @@ const usePersSDK = () => {
  * ```
  */
 const useAuth = () => {
-    const { sdk, authProvider, isInitialized, isAuthenticated, user, setAuthenticationState, refreshUserData } = usePersSDK();
+    const { sdk, authProvider, isInitialized, isAuthenticated, user, refreshUserData } = usePersSDK();
     /**
      * Authenticates a user with a JWT token
      *
@@ -19089,22 +19865,15 @@ const useAuth = () => {
         try {
             // Set token in auth provider
             await authProvider.setAccessToken(jwtToken);
-            // Perform login using the manager
+            // Perform login - emits login_success event which Provider handles
             const result = await sdk.auth.loginWithToken(jwtToken, userType);
-            const userData = result.user || result.admin;
-            if (userData) {
-                setAuthenticationState(userData, true);
-                return result;
-            }
-            else {
-                throw new Error('No user data returned from login');
-            }
+            return result;
         }
         catch (error) {
             console.error('Login failed:', error);
             throw error;
         }
-    }, [sdk, authProvider, setAuthenticationState]);
+    }, [sdk, authProvider]);
     /**
      * Logs in a user using raw user data (direct authentication bypass)
      *
@@ -19122,25 +19891,18 @@ const useAuth = () => {
             throw new Error('SDK not initialized. Call initialize() first.');
         }
         try {
-            // Use the raw data login from the auth manager
+            // Use the raw data login - emits login_success event which Provider handles
             const result = await sdk.auth.loginWithRawData(rawUserData);
             // Set token from result
             if (result.accessToken) {
                 await authProvider.setAccessToken(result.accessToken);
             }
-            const userData = result.user;
-            if (userData) {
-                setAuthenticationState(userData, true);
-            }
-            else {
-                throw new Error('No user data returned from raw data login');
-            }
         }
         catch (error) {
             console.error('Raw data login failed:', error);
             throw error;
         }
-    }, [sdk, authProvider, setAuthenticationState]);
+    }, [sdk, authProvider]);
     /**
      * Logs out the current user and clears authentication state
      *
@@ -19154,17 +19916,18 @@ const useAuth = () => {
      * ```
      */
     const logout = react.useCallback(async () => {
+        if (!sdk) {
+            throw new Error('SDK not initialized. Call initialize() first.');
+        }
         try {
-            if (authProvider) {
-                await authProvider.clearTokens();
-            }
-            setAuthenticationState(null, false);
+            // clearAuth emits logout_success event which Provider handles
+            await sdk.auth.clearAuth();
         }
         catch (error) {
             console.error('Logout failed:', error);
             throw error;
         }
-    }, [authProvider, setAuthenticationState]);
+    }, [sdk]);
     /**
      * Retrieves the current authenticated user data
      *
@@ -19238,9 +20001,9 @@ const useAuth = () => {
         if (!sdk) {
             throw new Error('SDK not initialized. Call initialize() first.');
         }
+        // clearAuth emits logout_success event which Provider handles
         await sdk.auth.clearAuth();
-        setAuthenticationState(null, false);
-    }, [sdk, setAuthenticationState]);
+    }, [sdk]);
     /**
      * Checks if the current authentication is valid (non-expired)
      *
@@ -40275,6 +41038,581 @@ const useWeb3 = () => {
     };
 };
 
+/**
+ * Token SDK - Class-based Promise SDK for Token Operations
+ *
+ * Modern, performant SDK with direct method access and excellent TypeScript support.
+ * Optimized for bundle size, performance, and developer experience.
+ *
+ * Usage:
+ *   const tokenSDK = new TokenSDK(apiClient);
+ *   const tokens = await tokenSDK.getTokens();
+ *   const creditToken = await tokenSDK.getActiveCreditToken();
+ */
+class TokenSDK {
+    constructor(apiClient) {
+        this.tokenApi = new TokenApi(apiClient);
+        this.tokenService = new TokenService(this.tokenApi);
+    }
+    // ==========================================
+    // CONVENIENCE METHODS - Direct Promise API
+    // ==========================================
+    // Simplified method names for better developer experience
+    /**
+     * Get all tokens
+     * @returns Promise with all available tokens
+     */
+    async getTokens() {
+        return this.tokenService.getRemoteTokens();
+    }
+    /**
+     * Get all token types
+     * @returns Promise with all available token types
+     */
+    async getTokenTypes() {
+        return this.tokenService.getRemoteTokenTypes();
+    }
+    /**
+     * Get the active credit token
+     * @returns Promise with the current active credit token
+     */
+    async getActiveCreditToken() {
+        return this.tokenService.getRemoteActiveCreditToken();
+    }
+    /**
+     * Get all reward tokens
+     * @returns Promise with all reward tokens
+     */
+    async getRewardTokens() {
+        return this.tokenService.getRemoteRewardTokens();
+    }
+    /**
+     * Get all status tokens
+     * @returns Promise with all status tokens
+     */
+    async getStatusTokens() {
+        return this.tokenService.getRemoteStatusTokens();
+    }
+    /**
+     * Get token by contract address
+     * @param contractAddress - The contract address to search for
+     * @param contractTokenId - Optional contract token ID
+     * @returns Promise with the matching token
+     */
+    async getTokenByContract(contractAddress, contractTokenId = null) {
+        return this.tokenService.getTokenByContractAddress(contractAddress, contractTokenId);
+    }
+    // ==========================================
+    // ADMIN METHODS - Token Management
+    // ==========================================
+    /**
+     * Create token metadata
+     * @param tokenId - The token ID
+     * @param tokenData - The token metadata request data
+     * @returns Promise with the updated token
+     */
+    async createTokenMetadata(tokenId, tokenData) {
+        return this.tokenService.createTokenMetadata(tokenId, tokenData);
+    }
+    /**
+     * Update token metadata (ERC721 only)
+     * Note: Existing minted NFTs retain their original metadata - this only affects future mints
+     * @param metadataId - The metadata ID to update
+     * @param tokenData - The token metadata request data
+     * @returns Promise with the updated metadata
+     */
+    async updateTokenMetadata(metadataId, tokenData) {
+        return this.tokenService.updateTokenMetadata(metadataId, tokenData);
+    }
+    /**
+     * Toggle token active status
+     * @param tokenId - The token ID to toggle
+     * @returns Promise with the updated token
+     */
+    async toggleTokenActive(tokenId) {
+        return this.tokenService.toggleTokenActive(tokenId);
+    }
+    /**
+     * Create a new token
+     * @param tokenData - The token creation data
+     * @returns Promise with the created token
+     */
+    async createToken(tokenData) {
+        return this.tokenService.createToken(tokenData);
+    }
+    /**
+     * Update an existing token
+     * @param tokenId - The token ID to update
+     * @param tokenData - The token update data
+     * @returns Promise with the updated token
+     */
+    async updateToken(tokenId, tokenData) {
+        return this.tokenService.updateToken(tokenId, tokenData);
+    }
+    /**
+     * Set mainnet contract address for a token
+     * @param tokenId - The token ID
+     * @param contractAddress - The contract address
+     * @param chainId - The blockchain chain ID
+     * @returns Promise with the updated token
+     */
+    async setMainnetContract(tokenId, contractAddress, chainId) {
+        return this.tokenService.setMainnetContract(tokenId, contractAddress, chainId);
+    }
+    /**
+     * Toggle token metadata status
+     * @param metadataId - The metadata ID to toggle
+     * @returns Promise with the updated metadata
+     */
+    async toggleTokenMetadataStatus(metadataId) {
+        return this.tokenService.toggleTokenMetadataStatus(metadataId);
+    }
+    /**
+     * Create a new token type
+     * @param tokenType - The token type data
+     * @returns Promise with the created token type
+     */
+    async createTokenType(tokenType) {
+        return this.tokenService.createTokenType(tokenType);
+    }
+    // ==========================================
+    // ADVANCED ACCESS - For Complex Operations
+    // ==========================================
+    /**
+     * Get direct access to the token service for advanced operations
+     * @returns The underlying TokenService instance
+     */
+    getTokenService() {
+        return this.tokenService;
+    }
+    /**
+     * Get direct access to the token API for low-level operations
+     * @returns The underlying TokenApi instance
+     */
+    getTokenApi() {
+        return this.tokenApi;
+    }
+}
+
+// ==========================================
+// TOKEN UTILITY FUNCTIONS
+// ==========================================
+/**
+ * Get metadata from a token unit response
+ * Handles metadata-based tokens (ERC-1155 with metadata array)
+ *
+ * For metadata-based tokens:
+ * - Returns the metadata object from token.metadata array
+ * - Uses provided incrementalId or tokenMetadataIncrementalId from tokenUnit
+ * - Defaults to index 0 if no incrementalId specified
+ *
+ * For standard tokens (no metadata):
+ * - Returns null
+ *
+ * @param tokenUnit - The token unit from campaign or balance
+ * @param incrementalId - Optional metadata index to use (overrides tokenUnit.tokenMetadataIncrementalId)
+ * @returns Token metadata object or null
+ *
+ * @example
+ * ```typescript
+ * // Get metadata using tokenUnit's incrementalId
+ * const tokenUnit = {
+ *   tokenMetadataIncrementalId: 3,
+ *   token: {
+ *     metadata: [
+ *       { name: 'Bronze Pass', imageUrl: '...' },
+ *       { name: 'Silver Pass', imageUrl: '...' },
+ *       { name: 'Gold Pass', imageUrl: '...' }
+ *     ]
+ *   }
+ * };
+ * const metadata = getMetadataFromTokenUnitResponse(tokenUnit);
+ * // Returns: { name: 'Bronze Pass', imageUrl: '...' } (index 0 - default)
+ *
+ * // Override incrementalId
+ * const metadata2 = getMetadataFromTokenUnitResponse(tokenUnit, 2);
+ * // Returns: { name: 'Gold Pass', imageUrl: '...' } (index 2)
+ *
+ * // Standard token (no metadata)
+ * const tokenUnit2 = {
+ *   token: { symbol: 'VQP', name: 'Visit Qatar Points' }
+ * };
+ * const metadata3 = getMetadataFromTokenUnitResponse(tokenUnit2);
+ * // Returns: null
+ *
+ * // Display name with fallback
+ * const displayName = metadata?.name || tokenUnit.token?.symbol || 'Reward';
+ *
+ * // Display image
+ * const imageUrl = metadata?.imageUrl;
+ * ```
+ */
+function getMetadataFromTokenUnitResponse(tokenUnit, incrementalId) {
+    // If no metadata array exists, return null
+    if (!tokenUnit.token?.metadata || tokenUnit.token.metadata.length === 0) {
+        return null;
+    }
+    const metadata = tokenUnit.token.metadata;
+    // Use provided incrementalId or tokenUnit's incrementalId to find matching metadata
+    const targetId = incrementalId ?? tokenUnit.tokenMetadataIncrementalId;
+    if (targetId !== undefined) {
+        const found = metadata.find((m) => m.incrementalId === targetId);
+        if (found)
+            return found;
+    }
+    // Fallback to first metadata item
+    return metadata[0];
+}
+
+/**
+ * Abstract Base Token Service - Explicit Initialization Pattern
+ *
+ * Platform-agnostic token operations with Promise-based API.
+ * Framework services extend this and control initialization lifecycle.
+ *
+ * Benefits:
+ * - Explicit initialization control
+ * - Better error boundaries
+ * - Clear lifecycle management
+ * - Testable initialization state
+ * - Zero framework dependencies
+ */
+class BaseTokenService {
+    constructor() {
+        this._isInitialized = false;
+    }
+    // ==========================================
+    // INITIALIZATION LIFECYCLE
+    // ==========================================
+    /**
+     * LIFECYCLE: Initialize token service with API client
+     * Must be called before using any token operations
+     */
+    initializeTokenService(apiClient) {
+        if (!apiClient) {
+            throw new Error('Cannot initialize TokenService: apiClient is null or undefined');
+        }
+        if (!this._isInitialized) {
+            this._tokenApi = new TokenApi(apiClient);
+            this._tokenBusinessService = new TokenService(this._tokenApi);
+            this._isInitialized = true;
+        }
+    }
+    /**
+     * LIFECYCLE: Check if token service is initialized
+     */
+    get isTokenServiceInitialized() {
+        return this._isInitialized;
+    }
+    /**
+     * INTERNAL: Get token business service (throws if not initialized)
+     */
+    get tokenBusinessService() {
+        if (!this._tokenBusinessService) {
+            throw new Error('TokenService not initialized. Call initializeTokenService(apiClient) first.');
+        }
+        return this._tokenBusinessService;
+    }
+    // ==========================================
+    // PUBLIC OPERATIONS
+    // ==========================================
+    /**
+     * PUBLIC: Get all remote tokens
+     */
+    getRemoteTokens() {
+        return this.tokenBusinessService.getRemoteTokens();
+    }
+    /**
+     * PUBLIC: Get all remote token types
+     */
+    getRemoteTokenTypes() {
+        return this.tokenBusinessService.getRemoteTokenTypes();
+    }
+    /**
+     * PUBLIC: Get active credit token
+     */
+    getRemoteActiveCreditToken() {
+        return this.tokenBusinessService.getRemoteActiveCreditToken();
+    }
+    /**
+     * PUBLIC: Get reward tokens
+     */
+    getRemoteRewardTokens() {
+        return this.tokenBusinessService.getRemoteRewardTokens();
+    }
+    /**
+     * PUBLIC: Get status tokens
+     */
+    getRemoteStatusTokens() {
+        return this.tokenBusinessService.getRemoteStatusTokens();
+    }
+    /**
+     * PUBLIC: Get token by contract address
+     */
+    getTokenByContractAddress(contractAddress, contractTokenId) {
+        return this.tokenBusinessService.getTokenByContractAddress(contractAddress, contractTokenId);
+    }
+    // ==========================================
+    // ADMIN OPERATIONS
+    // ==========================================
+    /**
+     * ADMIN: Create token metadata
+     */
+    createTokenMetadata(tokenId, tokenData) {
+        return this.tokenBusinessService.createTokenMetadata(tokenId, tokenData);
+    }
+    /**
+     * ADMIN: Toggle token active status
+     */
+    toggleTokenActive(tokenId) {
+        return this.tokenBusinessService.toggleTokenActive(tokenId);
+    }
+    /**
+     * ADMIN: Create new token
+     */
+    createToken(tokenData) {
+        return this.tokenBusinessService.createToken(tokenData);
+    }
+    /**
+     * ADMIN: Update token
+     */
+    updateToken(tokenId, tokenData) {
+        return this.tokenBusinessService.updateToken(tokenId, tokenData);
+    }
+    /**
+     * ADMIN: Set mainnet contract address
+     */
+    setMainnetContract(tokenId, contractAddress, chainId) {
+        return this.tokenBusinessService.setMainnetContract(tokenId, contractAddress, chainId);
+    }
+    /**
+     * ADMIN: Toggle token metadata status
+     */
+    toggleTokenMetadataStatus(metadataId) {
+        return this.tokenBusinessService.toggleTokenMetadataStatus(metadataId);
+    }
+    /**
+     * ADMIN: Create token type
+     */
+    createTokenType(tokenType) {
+        return this.tokenBusinessService.createTokenType(tokenType);
+    }
+}
+
+/**
+ * Node.js HTTP Client adapter for PERS SDK
+ *
+ * Simple HTTP client for Node.js environments using native fetch (Node 18+) or a polyfill.
+ * Works with Express, Next.js API routes, or any Node.js-based backend.
+ *
+ * @example
+ * ```typescript
+ * import { createPersSDK } from '@explorins/pers-sdk';
+ * import { NodeHttpClientAdapter } from '@explorins/pers-sdk/platform-adapters';
+ *
+ * const sdk = createPersSDK(
+ *   new NodeHttpClientAdapter(),
+ *   { environment: 'production', apiProjectKey: 'your-key' }
+ * );
+ *
+ * // Use managers directly
+ * await sdk.user.getCurrentUser();
+ * ```
+ */
+class NodeHttpClientAdapter {
+    async get(url, options = {}) {
+        return this.request(url, 'GET', undefined, options);
+    }
+    async post(url, data = null, options = {}) {
+        return this.request(url, 'POST', data, options);
+    }
+    async put(url, data = null, options = {}) {
+        return this.request(url, 'PUT', data, options);
+    }
+    async delete(url, options = {}) {
+        return this.request(url, 'DELETE', undefined, options);
+    }
+    async patch(url, data = null, options = {}) {
+        return this.request(url, 'PATCH', data, options);
+    }
+    async request(url, method, data, options = {}) {
+        // Use native fetch in Node 18+ or require a polyfill for older versions
+        const fetchImpl = globalThis.fetch || require('node-fetch');
+        const headers = {
+            'Content-Type': 'application/json',
+            'User-Agent': 'PERS-SDK-Node/1.0',
+            ...options.headers
+        };
+        const fetchOptions = {
+            method,
+            headers,
+            ...options
+        };
+        if (data !== undefined && method !== 'GET') {
+            fetchOptions.body = JSON.stringify(data);
+        }
+        const response = await fetchImpl(url, fetchOptions);
+        if (!response.ok) {
+            // Extract backend error response if available
+            let errorData;
+            try {
+                const contentType = response.headers.get('content-type');
+                if (contentType?.includes('application/json')) {
+                    errorData = await response.json();
+                }
+            }
+            catch {
+                // If parsing fails, continue with basic error
+            }
+            // Create error with backend data attached
+            const error = new Error(errorData?.message || `HTTP ${response.status}: ${response.statusText}`);
+            error.status = response.status;
+            error.statusText = response.statusText;
+            // Attach backend error response for extraction
+            if (errorData) {
+                Object.assign(error, errorData);
+            }
+            throw error;
+        }
+        // Handle different response types
+        const contentType = response.headers.get('content-type');
+        if (contentType?.includes('application/json')) {
+            return response.json();
+        }
+        return response.text();
+    }
+}
+
+/**
+ * Angular HTTP Client adapter for PERS SDK
+ *
+ * Simple bridge between Angular's HttpClient and PERS SDK's HttpClient interface.
+ * Use this for easy integration with Angular applications without requiring Angular as a dependency.
+ *
+ * @example
+ * ```typescript
+ * import { inject } from '@angular/core';
+ * import { HttpClient } from '@angular/common/http';
+ * import { createPersSDK } from '@explorins/pers-sdk';
+ * import { AngularHttpClientAdapter } from '@explorins/pers-sdk/platform-adapters';
+ *
+ * const sdk = createPersSDK(
+ *   new AngularHttpClientAdapter(inject(HttpClient)),
+ *   { environment: 'production', apiProjectKey: 'your-key' }
+ * );
+ *
+ * // Use managers directly
+ * await sdk.user.getCurrentUser();
+ * ```
+ */
+class AngularHttpClientAdapter {
+    constructor(httpClient) {
+        this.httpClient = httpClient;
+    }
+    async get(url, options = {}) {
+        const mergedOptions = this.mergeOptions(options);
+        const request$ = this.httpClient.get(url, mergedOptions);
+        return this.convertObservableToPromise(request$);
+    }
+    async post(url, data = null, options = {}) {
+        const mergedOptions = this.mergeOptions(options);
+        const request$ = this.httpClient.post(url, data, mergedOptions);
+        return this.convertObservableToPromise(request$);
+    }
+    async put(url, data = null, options = {}) {
+        const mergedOptions = this.mergeOptions(options);
+        const request$ = this.httpClient.put(url, data, mergedOptions);
+        return this.convertObservableToPromise(request$);
+    }
+    async delete(url, options = {}) {
+        const mergedOptions = this.mergeOptions(options);
+        const request$ = this.httpClient.delete(url, mergedOptions);
+        return this.convertObservableToPromise(request$);
+    }
+    async patch(url, data = null, options = {}) {
+        const mergedOptions = this.mergeOptions(options);
+        const request$ = this.httpClient.patch(url, data, mergedOptions);
+        return this.convertObservableToPromise(request$);
+    }
+    async convertObservableToPromise(observable) {
+        // Dynamically import firstValueFrom to avoid build-time dependency
+        const { firstValueFrom } = await Promise.resolve().then(function () { return require('./index-CzLxqePZ.js'); }).then(function (n) { return n.index; });
+        return firstValueFrom(observable);
+    }
+    mergeOptions(options) {
+        // Create headers object without importing HttpHeaders
+        const defaultHeaders = { 'Content-Type': 'application/json' };
+        const headers = { ...defaultHeaders, ...options.headers };
+        return {
+            headers,
+            observe: 'body',
+            ...options
+        };
+    }
+}
+
+/**
+ * Browser Fetch HTTP Client adapter for PERS SDK
+ *
+ * Simple fetch-based HTTP client for browser environments.
+ * Works with vanilla JavaScript, React, Vue, or any browser-based framework.
+ *
+ * @example
+ * ```typescript
+ * import { createPersSDK } from '@explorins/pers-sdk';
+ * import { BrowserFetchClientAdapter } from '@explorins/pers-sdk/platform-adapters';
+ *
+ * const sdk = createPersSDK(
+ *   new BrowserFetchClientAdapter(),
+ *   { environment: 'production', apiProjectKey: 'your-key' }
+ * );
+ *
+ * // Use managers directly
+ * await sdk.user.getCurrentUser();
+ * ```
+ */
+class BrowserFetchClientAdapter {
+    async get(url, options = {}) {
+        return this.request(url, 'GET', undefined, options);
+    }
+    async post(url, data = null, options = {}) {
+        return this.request(url, 'POST', data, options);
+    }
+    async put(url, data = null, options = {}) {
+        return this.request(url, 'PUT', data, options);
+    }
+    async delete(url, options = {}) {
+        return this.request(url, 'DELETE', undefined, options);
+    }
+    async patch(url, data = null, options = {}) {
+        return this.request(url, 'PATCH', data, options);
+    }
+    async request(url, method, data, options = {}) {
+        const headers = {
+            'Content-Type': 'application/json',
+            ...options.headers
+        };
+        const fetchOptions = {
+            method,
+            headers,
+            ...options
+        };
+        if (data !== undefined && method !== 'GET') {
+            fetchOptions.body = JSON.stringify(data);
+        }
+        const response = await fetch(url, fetchOptions);
+        if (!response.ok) {
+            throw new Error(`HTTP ${response.status}: ${response.statusText}`);
+        }
+        // Handle different response types
+        const contentType = response.headers.get('content-type');
+        if (contentType?.includes('application/json')) {
+            return response.json();
+        }
+        return response.text();
+    }
+}
+
 /**
  * React hook for loading and managing token balances
  *
@@ -41438,12 +42776,38 @@ const useBusiness = () => {
             throw error;
         }
     }, [sdk, isInitialized]);
-    const getBusinesses = react.useCallback(async () => {
+    /**
+     * Admin: Get all businesses with optional filtering
+     *
+     * @param options - Filter and pagination options
+     * @returns Promise resolving to paginated businesses
+     *
+     * @example
+     * ```typescript
+     * // Get all businesses
+     * const { data } = await getBusinesses();
+     *
+     * // Filter by tag
+     * const tagged = await getBusinesses({ tag: 'restaurant' });
+     *
+     * // Multiple tags (OR match)
+     * const multiTag = await getBusinesses({ tag: ['restaurant', 'cafe'] });
+     *
+     * // With search and pagination
+     * const filtered = await getBusinesses({
+     *   search: 'coffee',
+     *   active: true,
+     *   page: 1,
+     *   limit: 20
+     * });
+     * ```
+     */
+    const getBusinesses = react.useCallback(async (options) => {
         if (!isInitialized || !sdk) {
             throw new Error('SDK not initialized. Call initialize() first.');
         }
         try {
-            const result = await sdk.businesses.getBusinesses();
+            const result = await sdk.businesses.getBusinesses(options);
             return result;
         }
         catch (error) {
@@ -41565,11 +42929,15 @@ const useCampaigns = () => {
      *   include: ['triggerSources', 'businesses']
      * });
      *
-     * // Filter by tag
-     * const { data } = await getActiveCampaigns({ tag: 'summer-promo' });
+     * // Filter by date range
+     * const { data } = await getActiveCampaigns({
+     *   startDate: '2026-05-01',
+     *   endDate: '2026-12-31'
+     * });
      *
-     * // Filter by business
-     * const { data } = await getActiveCampaigns({ businessId: 'business-123' });
+     * // Get campaigns with claim count
+     * const { data } = await getActiveCampaigns({ include: ['claimCount'] });
+     * data.forEach(c => console.log(`${c.name}: ${c.claimCount} claims`));
      * ```
      */
     const getActiveCampaigns = react.useCallback(async (options) => {
@@ -41592,7 +42960,7 @@ const useCampaigns = () => {
      * Get campaign by ID with optional include relations
      *
      * @param campaignId - The campaign ID
-     * @param include - Relations to include: 'triggerSources', 'businesses'
+     * @param include - Relations to include: 'triggerSources', 'businesses', 'claimCount'
      * @returns Promise resolving to campaign data
      *
      * @example
@@ -41600,6 +42968,10 @@ const useCampaigns = () => {
      * // Get campaign with all related data
      * const campaign = await getCampaignById('campaign-123', ['triggerSources', 'businesses']);
      * console.log('Trigger sources:', campaign.included?.triggerSources);
+     *
+     * // Get campaign with claim count
+     * const campaign = await getCampaignById('campaign-123', ['claimCount']);
+     * console.log('Total claims:', campaign.claimCount);
      * ```
      */
     const getCampaignById = react.useCallback(async (campaignId, include) => {
@@ -41751,8 +43123,13 @@ const useCampaigns = () => {
      * // Get only active campaigns with trigger sources
      * const { data } = await getAllCampaigns({ active: true, include: ['triggerSources'] });
      *
-     * // Get inactive campaigns
-     * const { data } = await getAllCampaigns({ active: false });
+     * // Filter by date range with claim count
+     * const { data } = await getAllCampaigns({
+     *   startDate: '2026-05-01',
+     *   endDate: '2026-12-31',
+     *   include: ['claimCount']
+     * });
+     * data.forEach(c => console.log(`${c.name}: ${c.claimCount} claims`));
      *
      * // With pagination and sorting
      * const { data } = await getAllCampaigns({
@@ -41779,7 +43156,16 @@ const useCampaigns = () => {
     /**
      * Admin: Get campaign claims with optional filters and include relations
      *
-     * @param filters - Optional filters for campaign, user, or business
+     * @param filters - Optional filters for campaign, user, business, and date range
+     * @param filters.campaignId - Filter by specific campaign ID
+     * @param filters.userId - Filter by user ID
+     * @param filters.businessId - Filter by business ID
+     * @param filters.dateFrom - Filter claims created on or after this date (ISO 8601 format)
+     * @param filters.dateTo - Filter claims created on or before this date (ISO 8601 format)
+     * @param filters.page - Page number (1-indexed)
+     * @param filters.limit - Items per page
+     * @param filters.sortBy - Field to sort by
+     * @param filters.sortOrder - Sort direction
      * @param include - Relations to include: 'campaign', 'user', 'business'
      * @returns Promise resolving to paginated campaign claims
      *
@@ -41790,6 +43176,12 @@ const useCampaigns = () => {
      *
      * // Get claims for a specific campaign
      * const { data } = await getCampaignClaims({ campaignId: 'campaign-123' }, ['user', 'business']);
+     *
+     * // Filter by date range
+     * const { data } = await getCampaignClaims({
+     *   dateFrom: '2026-01-01',
+     *   dateTo: '2026-03-31'
+     * }, ['campaign']);
      * ```
      */
     const getCampaignClaims = react.useCallback(async (filters, include) => {
@@ -41945,6 +43337,9 @@ const useRedemptions = () => {
      * @param options - Filter and pagination options
      * @param options.active - Filter by active status (Admin only)
      * @param options.search - Free text search across name, description, tags
+     * @param options.startDate - Filter redemptions starting on or after this date
+     * @param options.endDate - Filter redemptions ending on or before this date
+     * @param options.include - Relations to include: 'redeemCount'
      * @param options.page - Page number (1-indexed)
      * @param options.limit - Results per page
      * @param options.sortBy - Field to sort by ('name' | 'createdAt')
@@ -41955,12 +43350,21 @@ const useRedemptions = () => {
      * const { data: offers } = await getRedemptions();
      * ```
      *
-     * @example Search redemptions
+     * @example Filter by date range
+     * ```typescript
+     * const { data: dateFiltered } = await getRedemptions({
+     *   startDate: '2026-05-01',
+     *   endDate: '2026-06-30'
+     * });
+     * ```
+     *
+     * @example Get redemptions with redeem count
      * ```typescript
-     * const { data: coffeeOffers } = await getRedemptions({ search: 'coffee' });
+     * const { data: offers } = await getRedemptions({ include: ['redeemCount'] });
+     * offers.forEach(o => console.log(`${o.name}: ${o.redeemCount} redeems`));
      * ```
      *
-     * @example With pagination and sorting
+     * @example Search with pagination
      * ```typescript
      * const { data, pagination } = await getRedemptions({
      *   search: 'discount',
@@ -42125,7 +43529,17 @@ const useRedemptions = () => {
      *
      * Retrieves all redemption redeems across the platform with filtering.
      *
-     * @param filters - Optional filters for user, redemption, and pagination
+     * @param filters - Optional filters for user, redemption, date range, and pagination
+     * @param filters.userId - Filter by user ID
+     * @param filters.redemptionId - Filter by redemption offer ID
+     * @param filters.businessId - Filter by business ID (admin only)
+     * @param filters.status - Filter by processing status (PENDING, PROCESSING, COMPLETED, FAILED)
+     * @param filters.dateFrom - Filter redeems created on or after this date (ISO 8601 format)
+     * @param filters.dateTo - Filter redeems created on or before this date (ISO 8601 format)
+     * @param filters.page - Page number (1-indexed)
+     * @param filters.limit - Items per page
+     * @param filters.sortBy - Field to sort by
+     * @param filters.sortOrder - Sort direction
      * @param include - Relations to include: 'redemption', 'user', 'business'
      * @returns Promise resolving to paginated redemption redeems
      *
@@ -42139,6 +43553,12 @@ const useRedemptions = () => {
      *   { userId: 'user-123' },
      *   ['redemption']
      * );
+     *
+     * // Filter by date range
+     * const { data } = await getRedemptionRedeems({
+     *   dateFrom: '2026-01-01',
+     *   dateTo: '2026-03-31'
+     * }, ['user', 'redemption']);
      * ```
      */
     const getRedemptionRedeems = react.useCallback(async (filters, include) => {
@@ -43621,112 +45041,125 @@ const useTriggerSources = () => {
     };
 };
 
-// ==========================================
-// TOKEN UTILITY FUNCTIONS
-// ==========================================
-/**
- * Get metadata from a token unit response
- * Handles metadata-based tokens (ERC-1155 with metadata array)
- *
- * For metadata-based tokens:
- * - Returns the metadata object from token.metadata array
- * - Uses provided incrementalId or tokenMetadataIncrementalId from tokenUnit
- * - Defaults to index 0 if no incrementalId specified
- *
- * For standard tokens (no metadata):
- * - Returns null
- *
- * @param tokenUnit - The token unit from campaign or balance
- * @param incrementalId - Optional metadata index to use (overrides tokenUnit.tokenMetadataIncrementalId)
- * @returns Token metadata object or null
- *
- * @example
- * ```typescript
- * // Get metadata using tokenUnit's incrementalId
- * const tokenUnit = {
- *   tokenMetadataIncrementalId: 3,
- *   token: {
- *     metadata: [
- *       { name: 'Bronze Pass', imageUrl: '...' },
- *       { name: 'Silver Pass', imageUrl: '...' },
- *       { name: 'Gold Pass', imageUrl: '...' }
- *     ]
- *   }
- * };
- * const metadata = getMetadataFromTokenUnitResponse(tokenUnit);
- * // Returns: { name: 'Bronze Pass', imageUrl: '...' } (index 0 - default)
- *
- * // Override incrementalId
- * const metadata2 = getMetadataFromTokenUnitResponse(tokenUnit, 2);
- * // Returns: { name: 'Gold Pass', imageUrl: '...' } (index 2)
- *
- * // Standard token (no metadata)
- * const tokenUnit2 = {
- *   token: { symbol: 'VQP', name: 'Visit Qatar Points' }
- * };
- * const metadata3 = getMetadataFromTokenUnitResponse(tokenUnit2);
- * // Returns: null
- *
- * // Display name with fallback
- * const displayName = metadata?.name || tokenUnit.token?.symbol || 'Reward';
- *
- * // Display image
- * const imageUrl = metadata?.imageUrl;
- * ```
- */
-function getMetadataFromTokenUnitResponse(tokenUnit, incrementalId) {
-    // If no metadata array exists, return null
-    if (!tokenUnit.token?.metadata || tokenUnit.token.metadata.length === 0) {
-        return null;
-    }
-    const metadata = tokenUnit.token.metadata;
-    // Use provided incrementalId or tokenUnit's incrementalId to find matching metadata
-    const targetId = incrementalId ?? tokenUnit.tokenMetadataIncrementalId;
-    if (targetId !== undefined) {
-        const found = metadata.find((m) => m.incrementalId === targetId);
-        if (found)
-            return found;
-    }
-    // Fallback to first metadata item
-    return metadata[0];
-}
-
 exports.ANALYTICS_GROUP_BY_TYPES = ANALYTICS_GROUP_BY_TYPES;
 exports.ANALYTICS_METRIC_TYPES = ANALYTICS_METRIC_TYPES;
+exports.AUTH_STORAGE_KEYS = AUTH_STORAGE_KEYS;
+exports.AnalyticsApi = AnalyticsApi;
+exports.AnalyticsManager = AnalyticsManager;
+exports.AnalyticsService = AnalyticsService;
+exports.AngularHttpClientAdapter = AngularHttpClientAdapter;
+exports.ApiErrorDetector = ApiErrorDetector;
+exports.ApiKeyApi = ApiKeyApi;
+exports.ApiKeyManager = ApiKeyManager;
 exports.AsyncStorageTokenStorage = AsyncStorageTokenStorage;
 exports.AuditEntityTypes = AuditEntityTypes;
+exports.AuthApi = AuthApi;
+exports.AuthManager = AuthManager;
+exports.AuthService = AuthService;
+exports.AuthTokenManager = AuthTokenManager;
 exports.AuthenticationError = AuthenticationError;
+exports.BaseTokenService = BaseTokenService;
+exports.BrowserFetchClientAdapter = BrowserFetchClientAdapter;
+exports.BusinessApi = BusinessApi;
+exports.BusinessManager = BusinessManager;
+exports.BusinessMembershipApi = BusinessMembershipApi;
+exports.BusinessMembershipService = BusinessMembershipService;
+exports.BusinessService = BusinessService;
+exports.CacheService = CacheService;
+exports.CacheTTL = CacheTTL;
+exports.CampaignApi = CampaignApi;
+exports.CampaignManager = CampaignManager;
+exports.CampaignService = CampaignService;
 exports.ChainTypes = ChainTypes;
 exports.ClientTransactionType = ClientTransactionType;
+exports.DEFAULT_PERS_CONFIG = DEFAULT_PERS_CONFIG;
+exports.DPOP_STORAGE_KEYS = DPOP_STORAGE_KEYS;
+exports.DPoPManager = DPoPManager;
+exports.DefaultAuthProvider = DefaultAuthProvider;
 exports.Domains = Domains;
+exports.DonationApi = DonationApi;
+exports.DonationManager = DonationManager;
+exports.DonationService = DonationService;
 exports.EntityTypes = EntityTypes;
 exports.ErrorDomains = ErrorDomains;
 exports.ErrorUtils = ErrorUtils;
+exports.FileApi = FileApi;
+exports.FileManager = FileManager;
+exports.FileService = FileService;
+exports.IndexedDBTokenStorage = IndexedDBTokenStorage;
+exports.LocalStorageTokenStorage = LocalStorageTokenStorage;
+exports.LogoutRequired = LogoutRequired;
 exports.MEMBERSHIP_ROLE_HIERARCHY = MEMBERSHIP_ROLE_HIERARCHY;
+exports.MemoryTokenStorage = MemoryTokenStorage;
 exports.NativeTokenTypes = NativeTokenTypes;
+exports.NetworkError = NetworkError;
+exports.NodeHttpClientAdapter = NodeHttpClientAdapter;
+exports.PaymentApi = PurchaseApi;
+exports.PaymentService = PaymentService;
+exports.PersApiClient = PersApiClient;
 exports.PersApiError = PersApiError;
+exports.PersEventEmitter = PersEventEmitter;
+exports.PersEventsClient = PersEventsClient;
+exports.PersSDK = PersSDK;
 exports.PersSDKProvider = PersSDKProvider;
+exports.ProviderTokenRefreshNeeded = ProviderTokenRefreshNeeded;
+exports.PurchaseManager = PurchaseManager;
 exports.QUERY_OPERATOR_SQL_MAP = QUERY_OPERATOR_SQL_MAP;
 exports.ReactNativeDPoPProvider = ReactNativeDPoPProvider;
 exports.ReactNativeHttpClient = ReactNativeHttpClient;
 exports.ReactNativeSecureStorage = ReactNativeSecureStorage;
+exports.RedemptionApi = RedemptionApi;
+exports.RedemptionManager = RedemptionManager;
+exports.RedemptionService = RedemptionService;
+exports.SDK_NAME = SDK_NAME;
+exports.SDK_USER_AGENT = SDK_USER_AGENT;
+exports.SDK_VERSION = SDK_VERSION;
 exports.SOURCE_LOGIC_TYPES = SOURCE_LOGIC_TYPES;
 exports.SOURCE_LOGIC_TYPE_VALUES = SOURCE_LOGIC_TYPE_VALUES;
+exports.SdkErrorCodes = SdkErrorCodes;
 exports.SigningStatus = SigningStatus;
+exports.StaticJwtAuthProvider = StaticJwtAuthProvider;
 exports.TOKEN_VALIDITY_TYPE_VALUES = TOKEN_VALIDITY_TYPE_VALUES;
 exports.TRANSACTION_FORMATS = TRANSACTION_FORMATS;
 exports.TRANSACTION_FORMAT_DESCRIPTIONS = TRANSACTION_FORMAT_DESCRIPTIONS;
 exports.TRIGGER_SOURCE_TYPES = TRIGGER_SOURCE_TYPES;
 exports.TRIGGER_SOURCE_TYPE_VALUES = TRIGGER_SOURCE_TYPE_VALUES;
+exports.TenantApi = TenantApi;
+exports.TenantManager = TenantManager;
+exports.TenantService = TenantService;
+exports.TokenApi = TokenApi;
+exports.TokenManager = TokenManager;
+exports.TokenRefreshNeeded = TokenRefreshNeeded;
+exports.TokenSDK = TokenSDK;
+exports.TokenService = TokenService;
 exports.TokenValidityTypes = TokenValidityTypes;
+exports.TransactionApi = TransactionApi;
+exports.TransactionManager = TransactionManager;
+exports.TransactionService = TransactionService;
+exports.TriggerSourceApi = TriggerSourceApi;
+exports.TriggerSourceManager = TriggerSourceManager;
+exports.TriggerSourceService = TriggerSourceService;
+exports.UserApi = UserApi;
+exports.UserManager = UserManager;
+exports.UserService = UserService;
+exports.UserStatusApi = UserStatusApi;
+exports.UserStatusManager = UserStatusManager;
+exports.UserStatusService = UserStatusService;
 exports.VALID_BUSINESS_MEMBERSHIP_RELATIONS = VALID_BUSINESS_MEMBERSHIP_RELATIONS;
 exports.VALID_CAMPAIGN_CLAIM_RELATIONS = VALID_CAMPAIGN_CLAIM_RELATIONS;
 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_TRANSACTION_RELATIONS = VALID_TRANSACTION_RELATIONS;
 exports.VALID_USER_RELATIONS = VALID_USER_RELATIONS;
+exports.WalletEventsManager = WalletEventsManager;
+exports.WebDPoPCryptoProvider = WebDPoPCryptoProvider;
+exports.WebhookApi = WebhookApi;
+exports.WebhookManager = WebhookManager;
+exports.WebhookService = WebhookService;
 exports.apiPublicKeyTestPrefix = apiPublicKeyTestPrefix;
+exports.buildApiRoot = buildApiRoot;
 exports.buildBurnRequest = buildBurnRequest;
 exports.buildMintRequest = buildMintRequest;
 exports.buildPOSBurnRequest = buildPOSBurnRequest;
@@ -43735,14 +45168,22 @@ exports.buildPaginationParams = buildPaginationParams;
 exports.buildPendingTransactionData = buildPendingTransactionData;
 exports.buildSubmissionRequest = buildSubmissionRequest;
 exports.buildTransferRequest = buildTransferRequest;
+exports.buildWalletEventsWsUrl = buildWalletEventsWsUrl;
+exports.createPersEventsClient = createPersEventsClient;
+exports.createPersSDK = createPersSDK;
 exports.createReactNativeAuthProvider = createReactNativeAuthProvider;
 exports.createUserIdentifierObject = createUserIdentifierObject;
+exports.createUserStatusSDK = createUserStatusSDK;
+exports.detectEnvironment = detectEnvironment;
 exports.detectIdentifierType = detectIdentifierType;
+exports.environment = environment;
 exports.extractData = extractData;
 exports.extractDeadlineFromSigningData = extractDeadlineFromSigningData;
 exports.extractPagination = extractPagination;
 exports.fetchAllPages = fetchAllPages;
 exports.getMetadataFromTokenUnitResponse = getMetadataFromTokenUnitResponse;
+exports.getSigningUrl = getSigningUrl;
+exports.globalCacheService = globalCacheService;
 exports.hasMinimumRole = hasMinimumRole;
 exports.initializeReactNativePolyfills = initializeReactNativePolyfills;
 exports.isConnectedMessage = isConnectedMessage;
@@ -43758,9 +45199,14 @@ exports.isValidBusinessMembershipRelation = isValidBusinessMembershipRelation;
 exports.isValidCampaignClaimRelation = isValidCampaignClaimRelation;
 exports.isValidCampaignRelation = isValidCampaignRelation;
 exports.isValidRedemptionRedeemRelation = isValidRedemptionRedeemRelation;
+exports.isValidRedemptionRelation = isValidRedemptionRelation;
 exports.isValidRelation = isValidRelation;
 exports.isValidTransactionRelation = isValidTransactionRelation;
 exports.isValidUserRelation = isValidUserRelation;
+exports.mergeWithDefaults = mergeWithDefaults;
+exports.needsExternalSigning = needsExternalSigning;
+exports.needsSubmission = needsSubmission;
+exports.normalizeFilters = normalizeFilters;
 exports.normalizeToPaginated = normalizeToPaginated;
 exports.registerIdentifierType = registerIdentifierType;
 exports.testnetPrefix = testnetPrefix;
@@ -43785,4 +45231,5 @@ exports.useTriggerSources = useTriggerSources;
 exports.useUserStatus = useUserStatus;
 exports.useUsers = useUsers;
 exports.useWeb3 = useWeb3;
+exports.warnIfProblematicEnvironment = warnIfProblematicEnvironment;
 //# sourceMappingURL=index.js.map