@explorins/pers-sdk 2.1.21 → 2.1.24

package/dist/chunks/{pers-sdk-DHohtBN8.cjs → pers-sdk-DXCcAgUS.cjs}

@@ -1,16 +1,16 @@
 'use strict';
 
 var persShared = require('@explorins/pers-shared');
-var index = require('./index-CGaKfZNU.cjs');
+var index = require('./index-CVuttuU8.cjs');
 var user = require('../user.cjs');
 var userStatus = require('../user-status.cjs');
 var tokenService = require('./token-service-C1xe11OX.cjs');
-var businessMembershipService = require('./business-membership-service-BfHzIQlc.cjs');
+var businessMembershipService = require('./business-membership-service-DXLG5fP9.cjs');
 var campaign = require('../campaign.cjs');
-var redemptionService = require('./redemption-service-OY_JjwCL.cjs');
+var redemptionService = require('./redemption-service-5Mu78Sne.cjs');
 var transactionRequest_builder = require('./transaction-request.builder-D8pIzjYD.cjs');
 var paymentService = require('./payment-service-Bkw7ZXev.cjs');
-var tenantManager = require('./tenant-manager-B4FygDMF.cjs');
+var tenantManager = require('./tenant-manager-D3toTiB9.cjs');
 var paginationUtils = require('./pagination-utils-B2jRHMSO.cjs');
 var analyticsService = require('./analytics-service-CF9AsMQH.cjs');
 var donation = require('../donation.cjs');
@@ -32,7 +32,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
@@ -99,11 +100,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: persShared.AccountOwnerType.TENANT
+            authType: persShared.AccountOwnerType.TENANT,
+            context: options?.tenantId ? { tenantId: options.tenantId } : undefined
         };
         return this.apiClient.post(`${this.basePath}/token`, body, { bypassAuth: true });
     }
@@ -161,6 +179,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');
+    }
 }
 
 /**
@@ -185,6 +227,12 @@ exports.AuthStatus = void 0;
     AuthStatus["SESSION_RESTORATION_FAILED"] = "session_restoration_failed";
 })(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
@@ -196,6 +244,12 @@ class AuthService {
         this.activeRefreshPromise = null;
         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
      */
@@ -203,9 +257,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);
@@ -217,9 +272,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, persShared.AccountOwnerType.TENANT, jwt);
         }
@@ -300,9 +360,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;
     }
@@ -340,6 +404,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
     // ==========================================
     /**
@@ -353,17 +438,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(exports.AuthStatus.AUTHENTICATED);
@@ -1403,6 +1489,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
@@ -1426,6 +1513,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();
  * ```
@@ -1433,6 +1527,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;
     }
@@ -1443,7 +1539,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
@@ -1467,10 +1563,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);
     }
     /**
@@ -1495,6 +1616,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
@@ -1515,6 +1637,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;
     }
@@ -1542,6 +1673,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;
     }
@@ -1665,7 +1800,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;
     }
@@ -1713,7 +1849,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
@@ -1731,7 +1926,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
@@ -1775,7 +1990,8 @@ class AuthManager {
      * ```
      */
     async getCurrentUser() {
-        return this.apiClient.get('/users/me');
+        const authService = this.apiClient.getAuthService();
+        return authService.getCurrentUser();
     }
     /**
      * Check if user is authenticated
@@ -3577,7 +3793,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
@@ -3607,18 +3823,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']
      * });
      * ```
      */
@@ -4069,58 +4289,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
@@ -4725,9 +4939,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
@@ -4752,6 +4976,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(
@@ -8688,7 +8924,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)
@@ -8711,7 +8948,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
@@ -9021,6 +9259,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
@@ -9098,22 +9354,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);
@@ -9127,25 +9384,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 === persShared.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() : persShared.AccountOwnerType.USER;
+        if (authType === persShared.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 === persShared.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;
         }
@@ -9694,4 +9983,4 @@ exports.buildWalletEventsWsUrl = buildWalletEventsWsUrl;
 exports.createPersEventsClient = createPersEventsClient;
 exports.createPersSDK = createPersSDK;
 exports.mergeWithDefaults = mergeWithDefaults;
-//# sourceMappingURL=pers-sdk-DHohtBN8.cjs.map
+//# sourceMappingURL=pers-sdk-DXCcAgUS.cjs.map