@explorins/pers-sdk 2.1.21 → 2.1.24

package/dist/chunks/{pers-sdk-BTLsI3bU.js → pers-sdk-DkCRHY5i.js}

@@ -1,14 +1,14 @@
 import { AccountOwnerType, MembershipRole, WebhookMethod, WebhookExecutionStatus } from '@explorins/pers-shared';
-import { i as isTokenExpired, E as ErrorUtils, A as AuthenticationError, b as PersApiError } from './index-DgTEdUgC.js';
+import { i as isTokenExpired, E as ErrorUtils, A as AuthenticationError, b as PersApiError } from './index-8y63MFOX.js';
 import { UserService, UserApi } from '../user.js';
 import { createUserStatusSDK } from '../user-status.js';
 import { a as TokenService, T as TokenApi } from './token-service-BxEO5YVN.js';
-import { B as BusinessApi, b as BusinessService, a as BusinessMembershipApi, c as BusinessMembershipService } from './business-membership-service-CFa-TI39.js';
+import { B as BusinessApi, b as BusinessService, a as BusinessMembershipApi, c as BusinessMembershipService } from './business-membership-service-IyY5CkL0.js';
 import { CampaignService, CampaignApi } from '../campaign.js';
-import { a as RedemptionService, R as RedemptionApi } from './redemption-service-CoyjUi8C.js';
+import { a as RedemptionService, R as RedemptionApi } from './redemption-service-CoODony4.js';
 import { a as TransactionService, T as TransactionApi } from './transaction-request.builder-BZ6Uq6Qe.js';
 import { a as PaymentService, P as PurchaseApi } from './payment-service-IvM6rryM.js';
-import { T as TenantManager } from './tenant-manager-DkWkZfCF.js';
+import { T as TenantManager } from './tenant-manager-D8-eD2CZ.js';
 import { b as buildPaginationParams, n as normalizeToPaginated } from './pagination-utils-9vQ-Npkr.js';
 import { a as AnalyticsService, A as AnalyticsApi } from './analytics-service-vm7B7LhS.js';
 import { DonationService, DonationApi } from '../donation.js';
@@ -30,7 +30,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
@@ -97,11 +98,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: AccountOwnerType.TENANT
+            authType: AccountOwnerType.TENANT,
+            context: options?.tenantId ? { tenantId: options.tenantId } : undefined
         };
         return this.apiClient.post(`${this.basePath}/token`, body, { bypassAuth: true });
     }
@@ -159,6 +177,30 @@ 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');
+    }
 }
 
 /**
@@ -183,6 +225,12 @@ var AuthStatus;
     AuthStatus["SESSION_RESTORATION_FAILED"] = "session_restoration_failed";
 })(AuthStatus || (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
@@ -194,6 +242,12 @@ class AuthService {
         this.activeRefreshPromise = null;
         this.currentAuthStatus = 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
      */
@@ -201,9 +255,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);
@@ -215,9 +270,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, AccountOwnerType.TENANT, jwt);
         }
@@ -298,9 +358,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;
     }
@@ -338,6 +402,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
     // ==========================================
     /**
@@ -351,17 +436,18 @@ 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);
@@ -1401,6 +1487,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
@@ -1424,6 +1511,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();
  * ```
@@ -1431,6 +1525,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;
     }
@@ -1441,7 +1537,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
@@ -1465,10 +1561,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);
     }
     /**
@@ -1493,6 +1614,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
@@ -1513,6 +1635,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;
     }
@@ -1540,6 +1671,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;
     }
@@ -1663,7 +1798,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;
     }
@@ -1711,7 +1847,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
@@ -1729,7 +1924,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
@@ -1773,7 +1988,8 @@ class AuthManager {
      * ```
      */
     async getCurrentUser() {
-        return this.apiClient.get('/users/me');
+        const authService = this.apiClient.getAuthService();
+        return authService.getCurrentUser();
     }
     /**
      * Check if user is authenticated
@@ -3575,7 +3791,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
@@ -3605,18 +3821,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
      * });
      *
-     * // Include related data (trigger sources and businesses)
+     * // 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, businesses, and claim count)
      * const campaignsWithRelations = await sdk.campaigns.getCampaigns({
-     *   include: ['triggerSources', 'businesses']
+     *   include: ['triggerSources', 'businesses', 'claimCount']
      * });
      * ```
      */
@@ -4067,58 +4287,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
+     * const { data: allClaims, pagination } = await sdk.campaigns.getCampaignClaims();
+     * console.log(`Total: ${pagination.total}`);
+     * ```
+     *
+     * @example Filter by User
      * ```typescript
-     * // Get all claims
-     * const allClaims = await sdk.campaigns.getCampaignClaims();
+     * const { data: userClaims } = await sdk.campaigns.getCampaignClaims({ userId: 'user-123' });
+     * ```
      *
-     * // Get claims for specific user
-     * const userClaims = await sdk.campaigns.getCampaignClaims({ userId: 'user-123' });
+     * @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`);
+     * ```
      *
-     * // Get claims for specific campaign with pagination
-     * const page1 = await sdk.campaigns.getCampaignClaims({
+     * @example With Pagination and Campaign Filter
+     * ```typescript
+     * const { data: page1 } = await sdk.campaigns.getCampaignClaims({
      *   campaignId: 'campaign-456',
      *   page: 1,
      *   limit: 50
@@ -4723,9 +4937,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
@@ -4750,6 +4974,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(
@@ -8686,7 +8922,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)
@@ -8709,7 +8946,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
@@ -9019,6 +9257,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
@@ -9096,22 +9352,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);
@@ -9125,25 +9382,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 === 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() : AccountOwnerType.USER;
+        if (authType === 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 === 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;
         }
@@ -9648,4 +9937,4 @@ function createPersSDK(httpClient, config) {
 }
 
 export { AuthStatus as A, BusinessManager as B, CampaignManager as C, DefaultAuthProvider as D, FileApi as E, FileManager as F, FileService as G, ApiKeyApi as H, WebhookApi as I, WebhookService as J, PersEventsClient as K, LocalStorageTokenStorage as L, MemoryTokenStorage as M, createPersEventsClient as N, PersSDK as P, RedemptionManager as R, SDK_NAME as S, TokenManager as T, UserManager as U, WebDPoPCryptoProvider as W, AuthTokenManager as a, AUTH_STORAGE_KEYS as b, createPersSDK as c, DPOP_STORAGE_KEYS as d, SDK_VERSION as e, SDK_USER_AGENT as f, PersApiClient as g, DEFAULT_PERS_CONFIG as h, buildApiRoot as i, buildWalletEventsWsUrl as j, StaticJwtAuthProvider as k, AuthApi as l, mergeWithDefaults as m, AuthService as n, DPoPManager as o, PersEventEmitter as p, AuthManager as q, UserStatusManager as r, TransactionManager as s, PurchaseManager as t, ApiKeyManager as u, AnalyticsManager as v, DonationManager as w, TriggerSourceManager as x, WebhookManager as y, WalletEventsManager as z };
-//# sourceMappingURL=pers-sdk-BTLsI3bU.js.map
+//# sourceMappingURL=pers-sdk-DkCRHY5i.js.map