@explorins/pers-sdk 1.6.43 → 1.6.47

package/dist/chunks/{pers-sdk-Nu2KgiJf.js → pers-sdk-VmeBqUEP.js}

@@ -1,10 +1,10 @@
-import { AccountOwnerType, NativeTokenTypes } from '@explorins/pers-shared';
-import { i as isTokenExpired, E as ErrorUtils, A as AuthenticationError, P as PersApiError, a as Web3ChainService, W as Web3ChainApi } from './web3-chain-service-JRSwxr-s.js';
-import { a as UserService, U as UserApi } from './user-service-D6mTa_WZ.js';
+import { AccountOwnerType, MembershipRole, NativeTokenTypes } from '@explorins/pers-shared';
+import { i as isTokenExpired, E as ErrorUtils, A as AuthenticationError, a as PersApiError, c as Web3ChainService, W as Web3ChainApi } from './web3-chain-service-BcUeeujC.js';
+import { a as UserService, U as UserApi } from './user-service-doT5vsBD.js';
 import { createUserStatusSDK } from '../user-status.js';
 import { a as TokenService, T as TokenApi } from './token-service-CpVwC5Eb.js';
-import { B as BusinessApi, a as BusinessService } from './business-service-8Xd3d5oY.js';
-import { a as CampaignService, C as CampaignApi } from './campaign-service-CJPXgFBe.js';
+import { BusinessApi, BusinessService, BusinessMembershipApi, BusinessMembershipService } from '../business.js';
+import { a as CampaignService, C as CampaignApi } from './campaign-service-CKwkiOLx.js';
 import { a as RedemptionService, R as RedemptionApi } from './redemption-service-BT0J5Iy7.js';
 import { a as TransactionService, T as TransactionApi } from './transaction-service-B7h_4Hg3.js';
 import { a as PaymentService, P as PurchaseApi } from './payment-service-DfCBFosx.js';
@@ -59,6 +59,11 @@ function mergeWithDefaults(config) {
 /**
  * Platform-Agnostic Auth API Client
  * Handles authentication operations using the PERS backend
+ *
+ * Supports the universal token endpoint:
+ * - User authentication (default)
+ * - Business authentication with context selection
+ * - Admin/Tenant authentication
  */
 class AuthApi {
     constructor(apiClient) {
@@ -85,6 +90,36 @@ class AuthApi {
         };
         return this.apiClient.post(`${this.basePath}/token`, body, { bypassAuth: true });
     }
+    /**
+     * Login as business with JWT
+     *
+     * Authenticates a user in a business context with role included in JWT.
+     *
+     * @param jwt - Authentication token (passkey or Firebase JWT)
+     * @param options - Business authentication options
+     * @param options.businessId - The business ID to authenticate as
+     *   - If user has single business membership, auto-selected
+     *   - If user has multiple memberships without businessId, throws MULTIPLE_CONTEXT_SELECTION_REQUIRED
+     * @returns Session response with business context and role in JWT
+     * @throws MultipleContextSelectionError when businessId is required but not provided
+     *
+     * @example
+     * ```typescript
+     * // Single business membership - auto-selects
+     * const response = await authApi.loginBusiness(jwt);
+     *
+     * // Multiple memberships - explicit selection
+     * const response = await authApi.loginBusiness(jwt, { businessId: 'biz-123' });
+     * ```
+     */
+    async loginBusiness(jwt, options) {
+        const body = {
+            authToken: jwt,
+            authType: AccountOwnerType.BUSINESS,
+            context: options?.businessId ? { businessId: options.businessId } : undefined
+        };
+        return this.apiClient.post(`${this.basePath}/token`, body, { bypassAuth: true });
+    }
     /**
      * Login user with raw data (no external authentication)
      */
@@ -172,6 +207,37 @@ class AuthService {
         }
         return response;
     }
+    /**
+     * Login as business with JWT
+     *
+     * Authenticates a user in a business context. The returned JWT contains
+     * the user's role within that business.
+     *
+     * @param jwt - Authentication token (passkey or Firebase JWT)
+     * @param options - Business authentication options
+     * @param options.businessId - The business ID to authenticate as
+     *   - If user has single business membership, auto-selected
+     *   - If user has multiple memberships without businessId, throws MULTIPLE_CONTEXT_SELECTION_REQUIRED
+     * @returns Session response with business context and role baked into JWT
+     * @throws MultipleContextSelectionRequiredError when businessId is required but not provided
+     *
+     * @example
+     * ```typescript
+     * // Auto-select if single membership
+     * const response = await authService.loginBusiness(jwt);
+     *
+     * // Explicit business selection
+     * const response = await authService.loginBusiness(jwt, { businessId: 'biz-123' });
+     * console.log('Business:', response.business?.displayName);
+     * ```
+     */
+    async loginBusiness(jwt, options) {
+        const response = await this.authApi.loginBusiness(jwt, options);
+        if (this.authProvider && response.accessToken) {
+            await this.storeTokens(response.accessToken, response.refreshToken, 'business', jwt);
+        }
+        return response;
+    }
     /**
      * Login user with raw data (no external auth)
      */
@@ -741,6 +807,21 @@ class DefaultAuthProvider {
     }
 }
 
+/**
+ * SDK Version Information
+ *
+ * Exported for consumers who need version info.
+ * Used internally for X-SDK-Version header.
+ *
+ * @module @explorins/pers-sdk/core
+ */
+/** SDK package name */
+const SDK_NAME = '@explorins/pers-sdk';
+/** SDK version - update on each release (should match package.json) */
+const SDK_VERSION = '1.6.48';
+/** Full SDK identifier for headers */
+const SDK_USER_AGENT = `${SDK_NAME}/${SDK_VERSION}`;
+
 // packages/pers-sdk/src/core/pers-api-client.ts
 /**
  * PERS API Client - Platform-agnostic HTTP client with authentication
@@ -881,6 +962,7 @@ class PersApiClient {
                 const backendError = ErrorUtils.extractBackendErrorDetails(error);
                 // If this IS a refresh request that failed with 401, don't retry to avoid infinite loop
                 if (options?.isRefreshRequest) {
+                    this.emitErrorEvent(backendError, errorMessage, endpoint, method, status, error);
                     throw new AuthenticationError(backendError.userMessage || backendError.message || 'Refresh token expired', endpoint, method, backendError.code, backendError.userMessage, backendError.title);
                 }
                 // For regular requests: try refresh once, then fail
@@ -898,11 +980,47 @@ class PersApiClient {
                 }
                 // Auth failure - let AuthService handle cleanup and notify app
                 await this.authService.handleAuthFailure();
+                this.emitErrorEvent(backendError, errorMessage, endpoint, method, status, error);
                 throw new AuthenticationError(backendError.userMessage || backendError.message || 'Authentication required', endpoint, method, backendError.code, backendError.userMessage, backendError.title);
             }
-            throw new PersApiError(errorMessage, endpoint, method, status || undefined, ErrorUtils.isRetryable(error));
+            // Extract backend error details for non-401 errors
+            const errorDetails = ErrorUtils.extractBackendErrorDetails(error);
+            this.emitErrorEvent(errorDetails, errorMessage, endpoint, method, status, error);
+            throw new PersApiError(errorMessage, endpoint, method, status || undefined, ErrorUtils.isRetryable(error), errorDetails);
         }
     }
+    /**
+     * Emit error event if events emitter is available
+     * @internal
+     */
+    emitErrorEvent(errorDetails, errorMessage, endpoint, method, status, error) {
+        console.log('[PersApiClient] emitErrorEvent called', {
+            hasEvents: !!this._events,
+            instanceId: this._events?.instanceId ?? 'none',
+            subscriberCount: this._events?.subscriberCount ?? 0,
+            domain: errorDetails.domain,
+            userMessage: errorDetails.userMessage || errorMessage
+        });
+        this._events?.emitError({
+            domain: errorDetails.domain || 'external',
+            type: errorDetails.code || 'API_ERROR',
+            userMessage: errorDetails.userMessage || errorMessage,
+            code: errorDetails.code,
+            details: {
+                endpoint,
+                method,
+                status: status || undefined,
+                retryable: ErrorUtils.isRetryable(error)
+            }
+        });
+    }
+    /**
+     * Set event emitter for error event emission
+     * @internal
+     */
+    setEvents(events) {
+        this._events = events;
+    }
     /**
      * Performs an authenticated GET request
      *
@@ -948,6 +1066,7 @@ class PersApiClient {
     async getHeaders(includeAuth = true, method, url) {
         const headers = {
             'Content-Type': 'application/json',
+            'X-SDK-Version': SDK_USER_AGENT,
         };
         if (this.mergedConfig.authProvider) {
             let token = null;
@@ -1154,12 +1273,231 @@ function warnIfProblematicEnvironment(feature) {
     }
 }
 
+/**
+ * PERS SDK Event Emitter
+ *
+ * Simplified global event stream.
+ * Platform-agnostic, zero dependencies.
+ *
+ * @module @explorins/pers-sdk/events
+ */
+/**
+ * Generates a unique event ID
+ */
+function generateEventId() {
+    return `evt_${Date.now()}_${Math.random().toString(36).slice(2, 9)}`;
+}
+/**
+ * Simplified event emitter - single global stream
+ *
+ * All events flow through one subscription point.
+ * Optional filtering at subscription level.
+ *
+ * @example Basic Usage
+ * ```typescript
+ * // Subscribe to ALL events - one handler
+ * const unsubscribe = sdk.events.subscribe((event) => {
+ *   showNotification(event.userMessage, event.level);
+ * });
+ *
+ * // With filter - only transaction errors
+ * sdk.events.subscribe((event) => {
+ *   showErrorToast(event.userMessage);
+ * }, { domains: ['transaction'], levels: ['error'] });
+ *
+ * // Multiple domains (whitelist)
+ * sdk.events.subscribe((event) => {
+ *   showNotification(event.userMessage);
+ * }, { domains: ['transaction', 'campaign', 'redemption'] });
+ *
+ * // Exclude domains (blacklist)
+ * sdk.events.subscribe((event) => {
+ *   showNotification(event.userMessage);
+ * }, { excludeDomains: ['validation'] });
+ *
+ * // Cleanup
+ * unsubscribe();
+ * ```
+ */
+let emitterInstanceCounter = 0;
+class PersEventEmitter {
+    constructor() {
+        this.handlers = new Set();
+        this._instanceId = ++emitterInstanceCounter;
+        console.log(`[PersEventEmitter] Instance #${this._instanceId} created`);
+    }
+    get instanceId() {
+        return this._instanceId;
+    }
+    /**
+     * Subscribe to events
+     *
+     * @param handler - Callback for matching events
+     * @param filter - Optional filter by domain and/or level
+     * @returns Unsubscribe function
+     *
+     * @example All events
+     * ```typescript
+     * const unsub = sdk.events.subscribe((event) => {
+     *   console.log(`[${event.domain}] ${event.type}: ${event.userMessage}`);
+     * });
+     * ```
+     *
+     * @example Only errors
+     * ```typescript
+     * sdk.events.subscribe((event) => {
+     *   logToSentry(event);
+     * }, { levels: ['error'] });
+     * ```
+     *
+     * @example Only transaction successes
+     * ```typescript
+     * sdk.events.subscribe((event) => {
+     *   playSuccessSound();
+     *   confetti();
+     * }, { domains: ['transaction'], levels: ['success'] });
+     * ```
+     */
+    subscribe(handler, filter) {
+        const filteredHandler = { handler, filter };
+        this.handlers.add(filteredHandler);
+        return () => this.handlers.delete(filteredHandler);
+    }
+    /**
+     * Subscribe and auto-unsubscribe after first matching event
+     *
+     * @param handler - Callback for the first matching event
+     * @param filter - Optional filter by domain and/or level
+     * @returns Unsubscribe function
+     */
+    once(handler, filter) {
+        const filteredHandler = {
+            handler: (event) => {
+                this.handlers.delete(filteredHandler);
+                handler(event);
+            },
+            filter
+        };
+        this.handlers.add(filteredHandler);
+        return () => this.handlers.delete(filteredHandler);
+    }
+    /**
+     * Emit a success event
+     *
+     * Domain is restricted to business domains only (Domain type).
+     *
+     * @param event - Success event data (id and timestamp auto-generated)
+     * @returns The complete event object
+     *
+     * @example
+     * ```typescript
+     * sdk.events.emitSuccess({
+     *   domain: 'transaction',  // Only business domains allowed
+     *   type: 'CONFIRMED',
+     *   userMessage: 'Transaction confirmed!'
+     * });
+     * ```
+     */
+    emitSuccess(event) {
+        const fullEvent = {
+            ...event,
+            level: 'success',
+            id: generateEventId(),
+            timestamp: Date.now()
+        };
+        this.notifyHandlers(fullEvent);
+        return fullEvent;
+    }
+    /**
+     * Emit an error event
+     *
+     * Domain can be any domain including technical (ErrorDomain type).
+     *
+     * @param event - Error event data (id and timestamp auto-generated)
+     * @returns The complete event object
+     *
+     * @example
+     * ```typescript
+     * sdk.events.emitError({
+     *   domain: 'validation',  // Technical domains allowed
+     *   type: 'INVALID_INPUT',
+     *   userMessage: 'Please check your input'
+     * });
+     * ```
+     */
+    emitError(event) {
+        const fullEvent = {
+            ...event,
+            level: 'error',
+            id: generateEventId(),
+            timestamp: Date.now()
+        };
+        this.notifyHandlers(fullEvent);
+        return fullEvent;
+    }
+    /**
+     * Check if event matches filter
+     */
+    matchesFilter(event, filter) {
+        // Level filtering
+        if (filter.levels && !filter.levels.includes(event.level))
+            return false;
+        // Domain exclusion (blacklist) - checked first
+        if (filter.excludeDomains && filter.excludeDomains.includes(event.domain))
+            return false;
+        // Domain inclusion (whitelist)
+        if (filter.domains && !filter.domains.includes(event.domain))
+            return false;
+        return true;
+    }
+    /**
+     * Notify all handlers of an event (applying filters)
+     */
+    notifyHandlers(event) {
+        for (const { handler, filter } of this.handlers) {
+            // Apply filter if present
+            if (filter && !this.matchesFilter(event, filter)) {
+                continue;
+            }
+            try {
+                const result = handler(event);
+                // Catch async handler errors too
+                if (result && typeof result.catch === 'function') {
+                    result.catch(error => {
+                        console.error('[PersEventEmitter] Async handler error:', error);
+                    });
+                }
+            }
+            catch (error) {
+                console.error('[PersEventEmitter] Handler error:', error);
+            }
+        }
+    }
+    /**
+     * Remove all handlers
+     */
+    clear() {
+        this.handlers.clear();
+    }
+    /**
+     * Get count of active subscriptions
+     */
+    get subscriberCount() {
+        return this.handlers.size;
+    }
+}
+
 /**
  * Authentication Manager - Clean, high-level interface for authentication operations
  *
  * Provides a simplified API for common authentication tasks while maintaining
  * access to the underlying API client for advanced use cases.
  *
+ * Supports the universal token endpoint (POST /auth/token):
+ * - User authentication (default)
+ * - Business authentication with role in JWT
+ * - Admin/Tenant authentication
+ *
  * @group Managers
  * @category Authentication
  *
@@ -1168,6 +1506,10 @@ function warnIfProblematicEnvironment(feature) {
  * // Login with external JWT
  * const authResult = await sdk.auth.loginWithToken(firebaseJWT, 'user');
  *
+ * // Login as business (with role in JWT)
+ * const bizResult = await sdk.auth.loginAsBusiness(jwt, { businessId: 'biz-123' });
+ * console.log('Business:', bizResult.business?.displayName);
+ *
  * // Check authentication
  * if (await sdk.auth.isAuthenticated()) {
  *   const user = await sdk.auth.getCurrentUser();
@@ -1179,8 +1521,9 @@ function warnIfProblematicEnvironment(feature) {
  * ```
  */
 class AuthManager {
-    constructor(apiClient) {
+    constructor(apiClient, events) {
         this.apiClient = apiClient;
+        this.events = events;
     }
     /**
      * Login with JWT token
@@ -1209,8 +1552,78 @@ class AuthManager {
         const result = userType === 'admin'
             ? await authService.loginTenantAdmin(jwtToken)
             : await authService.loginUser(jwtToken);
+        this.events?.emitSuccess({
+            domain: 'authentication',
+            type: 'LOGIN_SUCCESS',
+            userMessage: 'Successfully logged in'
+        });
         return result;
     }
+    /**
+     * Login as business with JWT token
+     *
+     * Authenticates a user in a business context. The returned JWT contains
+     * the user's role (OWNER, ADMIN, EDITOR, VIEWER) within that business.
+     *
+     * **Auto-Selection Behavior:**
+     * - If user has a single business membership, it's auto-selected
+     * - If user has multiple memberships and no businessId is provided,
+     *   throws `MULTIPLE_CONTEXT_SELECTION_REQUIRED` error with available options
+     *
+     * @param jwtToken - JWT token from auth provider (passkey, Firebase, etc.)
+     * @param options - Business authentication options
+     * @param options.businessId - The business ID to authenticate as (required for multi-business users)
+     * @returns Promise resolving to authentication response with business context and role in JWT
+     * @throws Error with code `MULTIPLE_CONTEXT_SELECTION_REQUIRED` when businessId is needed
+     *
+     * @example Single Business Membership
+     * ```typescript
+     * // Auto-selects the user's only business
+     * const result = await sdk.auth.loginAsBusiness(jwt);
+     * console.log('Business:', result.business?.displayName);
+     * ```
+     *
+     * @example Multiple Business Memberships
+     * ```typescript
+     * try {
+     *   const result = await sdk.auth.loginAsBusiness(jwt);
+     * } catch (error) {
+     *   if (error.code === 'MULTIPLE_CONTEXT_SELECTION_REQUIRED') {
+     *     // Show business selector UI
+     *     const selectedId = await showBusinessSelector(error.availableOptions);
+     *     const result = await sdk.auth.loginAsBusiness(jwt, { businessId: selectedId });
+     *   }
+     * }
+     * ```
+     *
+     * @example Direct Business Selection
+     * ```typescript
+     * const result = await sdk.auth.loginAsBusiness(jwt, { businessId: 'biz-123' });
+     * console.log('Authenticated as:', result.business?.displayName);
+     * ```
+     */
+    async loginAsBusiness(jwtToken, options) {
+        const authService = this.apiClient.getAuthService();
+        return authService.loginBusiness(jwtToken, options);
+    }
+    /**
+     * Get current business context
+     *
+     * Retrieves the current business context if authenticated as business.
+     * Requires prior business authentication via {@link loginAsBusiness}.
+     *
+     * @returns Promise resolving to current business data
+     * @throws {PersApiError} When not authenticated as business
+     *
+     * @example
+     * ```typescript
+     * const business = await sdk.auth.getCurrentBusiness();
+     * console.log('Current business:', business.displayName);
+     * ```
+     */
+    async getCurrentBusiness() {
+        return this.apiClient.get('/businesses/me');
+    }
     /**
      * Login with raw user data
      *
@@ -1412,8 +1825,9 @@ class AuthManager {
  * ```
  */
 class UserManager {
-    constructor(apiClient) {
+    constructor(apiClient, events) {
         this.apiClient = apiClient;
+        this.events = events;
         const userApi = new UserApi(apiClient);
         this.userService = new UserService(userApi);
     }
@@ -1469,7 +1883,14 @@ class UserManager {
      * ```
      */
     async updateCurrentUser(userData) {
-        return this.userService.updateRemoteUser(userData);
+        const result = await this.userService.updateRemoteUser(userData);
+        this.events?.emitSuccess({
+            domain: 'user',
+            type: 'PROFILE_UPDATED',
+            userMessage: 'Profile updated successfully',
+            details: { userId: result.id }
+        });
+        return result;
     }
     /**
      * Get user by unique identifier
@@ -1566,6 +1987,64 @@ class UserManager {
     async getAllUsers() {
         return this.userService.getAllRemoteUsers();
     }
+    /**
+     * Business/Admin: Create or update a user
+     *
+     * Creates a new user or updates an existing one. This method requires
+     * business authentication (with canManageUsers permission) or admin authentication.
+     *
+     * @param userData - User data for creation/update
+     * @returns Promise resolving to created or updated user
+     * @throws {PersApiError} When not authenticated or insufficient permissions
+     *
+     * @example Create New User
+     * ```typescript
+     * // Business or Admin operation - create a new user
+     * const newUser = await sdk.users.createOrUpdateUser({
+     *   identifierEmail: 'newuser@example.com',
+     *   firstName: 'John',
+     *   lastName: 'Doe',
+     *   externalId: 'external-123'
+     * });
+     * console.log('User created:', newUser.id);
+     * ```
+     *
+     * @example Update Existing User
+     * ```typescript
+     * // If user with same identifier exists, it will be updated
+     * const updated = await sdk.users.createOrUpdateUser({
+     *   identifierEmail: 'existing@example.com',
+     *   firstName: 'Updated Name'
+     * });
+     * ```
+     */
+    async createOrUpdateUser(userData) {
+        return this.userService.createOrUpdateUser(userData);
+    }
+    /**
+     * Admin: Bulk create or update users
+     *
+     * Creates or updates multiple users in a single operation. This method
+     * requires admin authentication - business users cannot perform bulk operations.
+     *
+     * @param users - Array of user data for creation/update
+     * @returns Promise resolving to array of created/updated users
+     * @throws {PersApiError} When not authenticated as admin
+     *
+     * @example Bulk User Creation
+     * ```typescript
+     * // Admin-only operation - bulk create users
+     * const users = await sdk.users.createOrUpdateUsers([
+     *   { identifierEmail: 'user1@example.com', firstName: 'User', lastName: 'One' },
+     *   { identifierEmail: 'user2@example.com', firstName: 'User', lastName: 'Two' },
+     *   { identifierEmail: 'user3@example.com', firstName: 'User', lastName: 'Three' }
+     * ]);
+     * console.log(`Created ${users.length} users`);
+     * ```
+     */
+    async createOrUpdateUsers(users) {
+        return this.userService.createOrUpdateUsers(users);
+    }
     /**
      * Admin: Update user data
      *
@@ -2070,10 +2549,14 @@ class TokenManager {
  * ```
  */
 class BusinessManager {
-    constructor(apiClient) {
+    constructor(apiClient, events) {
         this.apiClient = apiClient;
+        this.events = events;
         this.businessApi = new BusinessApi(apiClient);
         this.businessService = new BusinessService(this.businessApi);
+        this.membershipApi = new BusinessMembershipApi(apiClient);
+        this.membershipService = new BusinessMembershipService(this.membershipApi);
+        this.userApi = new UserApi(apiClient);
     }
     /**
      * Get all active businesses
@@ -2153,7 +2636,7 @@ class BusinessManager {
      *
      * // Use for transaction verification
      * if (business.isActive) {
-     *   console.log('✅ Verified business partner');
+     *   console.log('Verified business partner');
      * }
      * ```
      */
@@ -2282,7 +2765,14 @@ class BusinessManager {
      * ```
      */
     async createBusiness(displayName) {
-        return this.businessService.createBusinessByDisplayName(displayName);
+        const result = await this.businessService.createBusinessByDisplayName(displayName);
+        this.events?.emitSuccess({
+            domain: 'business',
+            type: 'BUSINESS_CREATED',
+            userMessage: 'Business created successfully',
+            details: { businessId: result.id, displayName: result.displayName }
+        });
+        return result;
     }
     /**
      * Admin: Update business
@@ -2310,7 +2800,14 @@ class BusinessManager {
      * ```
      */
     async updateBusiness(businessId, businessData) {
-        return this.businessService.updateBusiness(businessId, businessData);
+        const result = await this.businessService.updateBusiness(businessId, businessData);
+        this.events?.emitSuccess({
+            domain: 'business',
+            type: 'BUSINESS_UPDATED',
+            userMessage: 'Business updated successfully',
+            details: { businessId: result.id, displayName: result.displayName }
+        });
+        return result;
     }
     /**
      * Admin: Toggle business active status
@@ -2368,6 +2865,209 @@ class BusinessManager {
     getBusinessService() {
         return this.businessService;
     }
+    // ==========================================
+    // BUSINESS MEMBERSHIP MANAGEMENT
+    // ==========================================
+    /**
+     * Get all members of a business
+     *
+     * Retrieves all users who have access to the specified business with their roles.
+     * Any member of the business can view the member list.
+     *
+     * @param businessId - The business UUID
+     * @returns Promise resolving to array of business memberships
+     * @throws {PersApiError} 401 - Not authenticated
+     * @throws {PersApiError} 403 - Not a member of this business
+     *
+     * @example
+     * ```typescript
+     * const members = await sdk.business.getMembers('business-123');
+     *
+     * console.log('Business Members:');
+     * members.forEach(member => {
+     *   console.log(`- User ${member.userId}: ${member.role}`);
+     * });
+     *
+     * // Count members by role
+     * const admins = members.filter(m => m.role === 'ADMIN' || m.role === 'OWNER');
+     * console.log(`Administrators: ${admins.length}`);
+     * ```
+     */
+    async getMembers(businessId) {
+        return this.membershipService.getMembers(businessId);
+    }
+    /**
+     * Get members filtered by role
+     *
+     * @param businessId - The business UUID
+     * @param role - The role to filter by
+     * @returns Promise resolving to array of memberships with the specified role
+     *
+     * @example
+     * ```typescript
+     * const owners = await sdk.business.getMembersByRole('business-123', 'OWNER');
+     * console.log(`Business has ${owners.length} owner(s)`);
+     * ```
+     */
+    async getMembersByRole(businessId, role) {
+        return this.membershipService.getMembersByRole(businessId, role);
+    }
+    /**
+     * Add a new member to a business
+     *
+     * Adds a user as a member of the business with the specified role.
+     * Requires ADMIN role or higher.
+     *
+     * @param businessId - The business UUID
+     * @param userId - The user UUID to add
+     * @param role - The role to assign (defaults to VIEWER)
+     * @returns Promise resolving to the created membership
+     * @throws {PersApiError} 401 - Not authenticated
+     * @throws {PersApiError} 403 - Insufficient role (requires ADMIN)
+     * @throws {PersApiError} 404 - User not found
+     * @throws {PersApiError} 409 - User is already a member
+     *
+     * @example
+     * ```typescript
+     * // Add a new editor to the business
+     * const newMember = await sdk.business.addMember(
+     *   'business-123',
+     *   'user-456',
+     *   'EDITOR'
+     * );
+     *
+     * console.log(`Added ${newMember.userId} as ${newMember.role}`);
+     * ```
+     */
+    async addMember(businessId, userId, role = MembershipRole.VIEWER) {
+        return this.membershipService.addMember(businessId, userId, role);
+    }
+    /**
+     * Update a member's role
+     *
+     * Changes the role of an existing business member.
+     * Requires ADMIN role or higher. Cannot demote the last OWNER.
+     * Can only assign roles up to your own level (ADMIN cannot create OWNER).
+     *
+     * @param businessId - The business UUID
+     * @param userId - The user UUID to update
+     * @param newRole - The new role to assign
+     * @returns Promise resolving to the updated membership
+     * @throws {PersApiError} 401 - Not authenticated
+     * @throws {PersApiError} 403 - Insufficient role (requires ADMIN)
+     * @throws {PersApiError} 404 - Membership not found
+     * @throws {PersApiError} 400 - Cannot demote last OWNER
+     *
+     * @example
+     * ```typescript
+     * // Promote an editor to admin
+     * const updated = await sdk.business.updateMemberRole(
+     *   'business-123',
+     *   'user-456',
+     *   'ADMIN'
+     * );
+     *
+     * console.log(`${updated.userId} is now ${updated.role}`);
+     * ```
+     */
+    async updateMemberRole(businessId, userId, newRole) {
+        const result = await this.membershipService.updateMemberRole(businessId, userId, newRole);
+        this.events?.emitSuccess({
+            domain: 'business',
+            type: 'MEMBERSHIP_UPDATED',
+            userMessage: 'Membership role updated',
+            details: { businessId, userId, role: newRole }
+        });
+        return result;
+    }
+    /**
+     * Remove a member from a business
+     *
+     * Removes a user's access to the business.
+     * Requires ADMIN role or higher. Cannot remove the last OWNER.
+     *
+     * @param businessId - The business UUID
+     * @param userId - The user UUID to remove
+     * @returns Promise resolving to success confirmation
+     * @throws {PersApiError} 401 - Not authenticated
+     * @throws {PersApiError} 403 - Insufficient role (requires ADMIN)
+     * @throws {PersApiError} 404 - Membership not found
+     * @throws {PersApiError} 400 - Cannot remove last OWNER
+     *
+     * @example
+     * ```typescript
+     * const result = await sdk.business.removeMember('business-123', 'user-456');
+     *
+     * if (result.success) {
+     *   console.log('Member removed successfully');
+     * }
+     * ```
+     */
+    async removeMember(businessId, userId) {
+        return this.membershipService.removeMember(businessId, userId);
+    }
+    /**
+     * Get permission flags for a role
+     *
+     * Returns an object with boolean flags indicating what actions
+     * a user with the given role can perform. Useful for UI rendering.
+     *
+     * @param role - The membership role (or null if not a member)
+     * @returns Object with permission flags
+     *
+     * @example
+     * ```typescript
+     * const permissions = sdk.business.getPermissions('EDITOR');
+     * // { canViewMembers: true, canManageMembers: false, canEditContent: true, canDeleteBusiness: false }
+     *
+     * if (permissions.canManageMembers) {
+     *   showAddMemberButton();
+     * }
+     * ```
+     */
+    getPermissions(role) {
+        return this.membershipService.getPermissions(role);
+    }
+    /**
+     * Add a member to a business by email address
+     *
+     * Convenience method that creates or retrieves a user by email and adds them
+     * as a member of the business. If the user doesn't exist, they will be created.
+     * Requires ADMIN role or higher.
+     *
+     * @param businessId - The business UUID
+     * @param email - The email address of the user to add
+     * @param role - The role to assign (defaults to VIEWER)
+     * @returns Promise resolving to the created membership
+     * @throws {PersApiError} 401 - Not authenticated
+     * @throws {PersApiError} 403 - Insufficient role (requires ADMIN)
+     * @throws {PersApiError} 409 - User is already a member
+     *
+     * @example
+     * ```typescript
+     * // Add a new editor by email - user is created if they don't exist
+     * const membership = await sdk.business.addMemberByEmail(
+     *   'business-123',
+     *   'newuser@example.com',
+     *   'EDITOR'
+     * );
+     *
+     * console.log(`Added user ${membership.userId} as ${membership.role}`);
+     * ```
+     */
+    async addMemberByEmail(businessId, email, role = MembershipRole.VIEWER) {
+        // POST /users is an upsert - creates user if not exists, returns existing if found
+        const user = await this.userApi.createOrUpdateUser({ email });
+        return this.membershipService.addMember(businessId, user.id, role);
+    }
+    /**
+     * Get the membership service for advanced operations
+     *
+     * @returns BusinessMembershipService instance
+     */
+    getMembershipService() {
+        return this.membershipService;
+    }
 }
 
 /**
@@ -2383,9 +3083,9 @@ class BusinessManager {
  *
  * @example Basic Campaign Operations
  * ```typescript
- * // Get all available campaigns for users
- * const campaigns = await sdk.campaigns.getActiveCampaigns();
- * console.log(`${campaigns.length} active campaigns available`);
+ * // Get all available campaigns (paginated)
+ * const result = await sdk.campaigns.getCampaigns({ page: 1, limit: 20 });
+ * console.log(`${result.data.length} of ${result.total} campaigns`);
  *
  * // Get specific campaign details
  * const campaign = await sdk.campaigns.getCampaignById('summer-promo-2024');
@@ -2411,7 +3111,8 @@ class BusinessManager {
  * });
  *
  * // Check if user can claim specific campaign
- * const eligibleCampaigns = campaigns.filter(c =>
+ * const campaigns = await sdk.campaigns.getCampaigns({ active: true });
+ * const eligibleCampaigns = campaigns.data.filter(c =>
  *   !userClaims.some(claim => claim.campaignId === c.id)
  * );
  * ```
@@ -2436,47 +3137,12 @@ class BusinessManager {
  * ```
  */
 class CampaignManager {
-    constructor(apiClient) {
+    constructor(apiClient, events) {
         this.apiClient = apiClient;
+        this.events = events;
         const campaignApi = new CampaignApi(apiClient);
         this.campaignService = new CampaignService(campaignApi);
     }
-    /**
-     * Get all active campaigns
-     *
-     * Retrieves all currently active campaigns that users can discover and claim.
-     * Active campaigns are live promotional offers with valid date ranges and
-     * available rewards. Includes campaign details, eligibility requirements, and reward information.
-     *
-     * @returns Promise resolving to array of active campaign data
-     *
-     * @example
-     * ```typescript
-     * const activeCampaigns = await sdk.campaigns.getActiveCampaigns();
-     *
-     * console.log('Available Campaigns:');
-     * activeCampaigns.forEach(campaign => {
-     *   console.log(`\n📢 ${campaign.title}`);
-     *   console.log(`   ${campaign.description}`);
-     *   console.log(`   Valid: ${campaign.startDate} to ${campaign.endDate}`);
-     *   console.log(`   Rewards: ${campaign.tokenUnits?.length || 0} types`);
-     *
-     *   if (campaign.businessEngagements?.length) {
-     *     console.log(`   Partner businesses: ${campaign.businessEngagements.length}`);
-     *   }
-     * });
-     *
-     * // Filter campaigns by type or business
-     * const hotelCampaigns = activeCampaigns.filter(c =>
-     *   c.businessEngagements?.some(be =>
-     *     be.business?.businessType?.name?.includes('Hotel')
-     *   )
-     * );
-     * ```
-     */
-    async getActiveCampaigns() {
-        return this.campaignService.getActiveCampaigns();
-    }
     /**
      * Get campaign by ID
      *
@@ -2574,7 +3240,14 @@ class CampaignManager {
      * ```
      */
     async claimCampaign(claimRequest) {
-        return this.campaignService.claimCampaign(claimRequest);
+        const result = await this.campaignService.claimCampaign(claimRequest);
+        this.events?.emitSuccess({
+            domain: 'campaign',
+            type: 'CLAIM_SUCCESS',
+            userMessage: 'Campaign reward claimed successfully',
+            details: { campaignId: claimRequest.campaignId }
+        });
+        return result;
     }
     /**
      * Get user's campaign claims
@@ -2616,40 +3289,46 @@ class CampaignManager {
         return this.campaignService.getClaimsForLoggedUser();
     }
     /**
-     * Admin: Get all campaigns
+     * Get campaigns with pagination support
      *
-     * Retrieves all campaigns in the system regardless of status. This operation
-     * requires administrator privileges and is used for comprehensive campaign
-     * management, reporting, and lifecycle operations.
+     * Returns campaigns with pagination metadata for efficient data loading.
+     * Intelligent access: Public gets active only, Business gets own campaigns, Admin gets all.
      *
-     * @param active - Optional filter to show only active or inactive campaigns
-     * @returns Promise resolving to array of campaigns
-     * @throws {PersApiError} When not authenticated as administrator
+     * @param options - Pagination and filter options
+     * @param options.active - Filter by active status (true/false/undefined for all)
+     * @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 ('name', 'createdAt', 'startDate')
+     * @param options.sortOrder - Sort direction ('ASC' or 'DESC')
+     * @returns Promise resolving to paginated campaigns with metadata
      *
      * @example
      * ```typescript
-     * // Admin operation - get campaign overview
-     * const allCampaigns = await sdk.campaigns.getAllCampaigns();
-     * const activeCampaigns = await sdk.campaigns.getAllCampaigns(true);
-     * const inactiveCampaigns = await sdk.campaigns.getAllCampaigns(false);
-     *
-     * console.log('📊 Campaign Statistics:');
-     * console.log(`Total campaigns: ${allCampaigns.length}`);
-     * console.log(`Active campaigns: ${activeCampaigns.length}`);
-     * console.log(`Inactive campaigns: ${inactiveCampaigns.length}`);
-     *
-     * // Generate campaign performance report
-     * const campaignReport = allCampaigns.map(campaign => ({
-     *   title: campaign.title,
-     *   status: campaign.isActive ? 'Active' : 'Inactive',
-     *   period: `${campaign.startDate} to ${campaign.endDate}`,
-     *   businesses: campaign.businessEngagements?.length || 0,
-     *   rewardTypes: campaign.tokenUnits?.length || 0
-     * }));
+     * // Get first page of campaigns
+     * const result = await sdk.campaigns.getCampaigns({ page: 1, limit: 10 });
+     * console.log(`Showing ${result.data.length} of ${result.total} campaigns`);
+     * console.log(`Has more pages: ${result.hasMore}`);
+     *
+     * // Get campaigns for a specific business
+     * const businessCampaigns = await sdk.campaigns.getCampaigns({
+     *   businessId: 'business-123',
+     *   page: 1,
+     *   limit: 20
+     * });
+     *
+     * // Get active campaigns sorted by creation date
+     * const activeCampaigns = await sdk.campaigns.getCampaigns({
+     *   active: true,
+     *   sortBy: 'createdAt',
+     *   sortOrder: 'DESC',
+     *   page: 1,
+     *   limit: 25
+     * });
      * ```
      */
-    async getAllCampaigns(active) {
-        return this.campaignService.getCampaigns(active);
+    async getCampaigns(options) {
+        return this.campaignService.getCampaigns(options);
     }
     /**
      * Admin: Create new campaign
@@ -3168,8 +3847,9 @@ class CampaignManager {
  * ```
  */
 class RedemptionManager {
-    constructor(apiClient) {
+    constructor(apiClient, events) {
         this.apiClient = apiClient;
+        this.events = events;
         const redemptionApi = new RedemptionApi(apiClient);
         this.redemptionService = new RedemptionService(redemptionApi);
     }
@@ -3333,7 +4013,14 @@ class RedemptionManager {
      * ```
      */
     async redeem(redemptionId) {
-        return this.redemptionService.redeemRedemption(redemptionId);
+        const result = await this.redemptionService.redeemRedemption(redemptionId);
+        this.events?.emitSuccess({
+            domain: 'redemption',
+            type: 'REDEEM_SUCCESS',
+            userMessage: 'Reward redeemed successfully',
+            details: { redemptionId }
+        });
+        return result;
     }
     /**
      * Get user's redemption history
@@ -3697,8 +4384,9 @@ class RedemptionManager {
  * ```
  */
 class TransactionManager {
-    constructor(apiClient) {
+    constructor(apiClient, events) {
         this.apiClient = apiClient;
+        this.events = events;
         const transactionApi = new TransactionApi(apiClient);
         this.transactionService = new TransactionService(transactionApi);
     }
@@ -3834,7 +4522,14 @@ class TransactionManager {
      * ```
      */
     async createTransaction(transactionData) {
-        return this.transactionService.createTransaction(transactionData);
+        const result = await this.transactionService.createTransaction(transactionData);
+        this.events?.emitSuccess({
+            domain: 'transaction',
+            type: 'TRANSACTION_CREATED',
+            userMessage: 'Transaction created successfully',
+            details: { transactionId: result.transaction?.id }
+        });
+        return result;
     }
     /**
      * Get user's transaction history
@@ -3851,7 +4546,7 @@ class TransactionManager {
      * ```typescript
      * const allTransactions = await sdk.transactions.getUserTransactionHistory('ALL');
      *
-     * console.log(`📜 Transaction History (${allTransactions.length} transactions):`);
+     * console.log(` Transaction History (${allTransactions.length} transactions):`);
      *
      * allTransactions.forEach((transaction, index) => {
      *   const date = new Date(transaction.createdAt).toLocaleDateString();
@@ -4139,7 +4834,14 @@ class TransactionManager {
      * @returns Promise resolving to the submission result
      */
     async submitSignedTransaction(signedTxData) {
-        return this.transactionService.submitSignedTransaction(signedTxData);
+        const result = await this.transactionService.submitSignedTransaction(signedTxData);
+        this.events?.emitSuccess({
+            domain: 'transaction',
+            type: 'TRANSACTION_SUBMITTED',
+            userMessage: 'Transaction submitted successfully',
+            details: { transactionId: result.transaction?.id }
+        });
+        return result;
     }
     /**
      * Query transactions by sender
@@ -5803,38 +6505,45 @@ class DonationManager {
  * Provides a simplified API for common Web3 blockchain tasks while maintaining
  * access to the full Web3 SDK for advanced use cases.
  *
- * ## ERC-1155 Token Handling
+ * ## Supported Token Standards
+ *
+ * - **ERC-20**: Fungible tokens (credits, points). Query balance with `getTokenBalance()`.
+ * - **ERC-721**: Non-fungible tokens (unique NFTs). Supports enumeration - no tokenIds needed.
+ * - **ERC-1155**: Multi-token standard (rewards, collectibles). Requires specific tokenIds.
  *
- * ERC-1155 tokens require specific tokenIds to query balances (unlike ERC-721 which
- * supports enumeration). When working with ERC-1155 reward tokens:
+ * ## Recommended: Use Helper Methods
  *
- * 1. Use `getTokenCollection()` with `tokenIds` extracted from `token.metadata`
- * 2. Each metadata item has `tokenMetadataIncrementalId` which is the on-chain tokenId
+ * For most use cases, use `getAccountOwnedTokensFromContract()` which automatically
+ * handles token type detection and tokenId extraction:
  *
- * @example ERC-1155 Reward Token Balance
  * ```typescript
- * // Get reward token definition (includes metadata with tokenIds)
- * const rewardTokens = await sdk.tokens.getRewardTokens();
- * const rewardToken = rewardTokens[0];
+ * const result = await sdk.web3.getAccountOwnedTokensFromContract(walletAddress, token);
+ * console.log(`Wallet owns ${result.totalOwned} tokens`);
+ * ```
  *
- * // Extract tokenIds from metadata for ERC-1155
- * const tokenIds = rewardToken.metadata?.map(
- *   meta => meta.tokenMetadataIncrementalId.toString()
- * );
+ * ## Manual Approach (Advanced)
+ *
+ * For ERC-1155 tokens, tokenIds are extracted from `token.metadata[].tokenMetadataIncrementalId`:
  *
- * // Get user's owned tokens
+ * ```typescript
+ * const tokenIds = token.metadata?.map(meta => meta.tokenMetadataIncrementalId.toString());
  * const collection = await sdk.web3.getTokenCollection({
  *   accountAddress: walletAddress,
- *   contractAddress: rewardToken.contractAddress,
- *   abi: rewardToken.abi,
- *   chainId: rewardToken.chainId,
- *   tokenIds: tokenIds  // Required for ERC-1155!
+ *   contractAddress: token.contractAddress,
+ *   abi: token.abi,
+ *   chainId: token.chainId,
+ *   tokenIds  // Required for ERC-1155, optional for ERC-721
  * });
- *
- * const ownedTokens = collection.tokens.filter(t => t.hasBalance);
  * ```
  */
 class Web3Manager {
+    // TODO: Add PersEventEmitter support for blockchain events
+    // When ready, add:
+    // 1. constructor param: private events?: PersEventEmitter
+    // 2. Subscribe to contract events (Transfer, Approval, etc.)
+    // 3. Emit via: this.events?.emitSuccess({ domain: 'web3', type: 'NFT_TRANSFERRED', ... })
+    // 4. Filter to only user's address (not all transfers)
+    // 5. Add cleanup for event listeners on SDK destroy
     constructor(apiClient) {
         this.apiClient = apiClient;
         // Initialize Web3 Chain service
@@ -5924,17 +6633,21 @@ class Web3Manager {
     // HELPER METHODS
     // ==========================================
     /**
-     * Extract tokenIds from a TokenDTO for use with ERC-1155 contracts.
+     * Extract tokenIds from a TokenDTO's metadata.
+     *
+     * Extracts `tokenMetadataIncrementalId` from each metadata entry. This is
+     * particularly useful for ERC-1155 tokens which require specific tokenIds
+     * to query balances, but works with any token that has metadata.
      *
-     * ERC-1155 tokens require specific tokenIds to query balances. This helper
-     * extracts the `tokenMetadataIncrementalId` from each metadata entry.
+     * **Note:** For most use cases, prefer `getAccountOwnedTokensFromContract()`
+     * which handles tokenId extraction automatically.
      *
      * @param token - Token definition containing metadata array
      * @returns Array of tokenId strings, or undefined if no metadata
      *
-     * @example
+     * @example Manual token collection request
      * ```typescript
-     * const rewardToken = await sdk.tokens.getRewardTokens()[0];
+     * const rewardToken = (await sdk.tokens.getRewardTokens())[0];
      * const tokenIds = sdk.web3.extractTokenIds(rewardToken);
      *
      * if (tokenIds) {
@@ -5943,10 +6656,12 @@ class Web3Manager {
      *     contractAddress: rewardToken.contractAddress,
      *     abi: rewardToken.abi,
      *     chainId: rewardToken.chainId,
-     *     tokenIds: tokenIds
+     *     tokenIds
      *   });
      * }
      * ```
+     *
+     * @see {@link getAccountOwnedTokensFromContract} - Recommended helper that handles this automatically
      */
     extractTokenIds(token) {
         if (!token.metadata || token.metadata.length === 0) {
@@ -5955,40 +6670,44 @@ class Web3Manager {
         return token.metadata.map(meta => meta.tokenMetadataIncrementalId.toString());
     }
     /**
-     * Get user's owned tokens from a specific token contract.
+     * Get owned tokens from a specific token contract for any blockchain address.
      *
-     * This is a convenience method that automatically handles:
-     * - ERC-1155 tokenId extraction from metadata
+     * **Recommended method** for querying token balances. Automatically handles:
+     * - Token type detection (ERC-20, ERC-721, ERC-1155)
+     * - TokenId extraction from metadata (uses `extractTokenIds()` internally for ERC-1155)
      * - Building the collection request
      * - Filtering to only tokens with balance > 0
      *
-     * @param walletAddress - User's wallet address
+     * Works with any valid blockchain address - can query user wallets, external
+     * wallets, contract addresses, or any other address holding tokens.
+     *
+     * @param accountAddress - Any valid blockchain address (wallet, contract, etc.)
      * @param token - Token definition (from getRewardTokens, getStatusTokens, etc.)
      * @param maxTokens - Maximum tokens to retrieve (default: 50)
      * @returns Promise resolving to collection result with owned tokens
      *
-     * @example
+     * @example Query user's wallet
      * ```typescript
-     * const rewardTokens = await sdk.tokens.getRewardTokens();
-     * const rewardToken = rewardTokens[0];
-     *
-     * const result = await sdk.web3.getUserOwnedTokensFromContract(
-     *   walletAddress,
-     *   rewardToken
-     * );
+     * const userWallet = user.wallets[0].address;
+     * const result = await sdk.web3.getAccountOwnedTokensFromContract(userWallet, rewardToken);
+     * console.log(`User owns ${result.totalOwned} tokens`);
+     * ```
      *
-     * console.log(`User owns ${result.ownedTokens.length} reward tokens`);
-     * result.ownedTokens.forEach(token => {
-     *   console.log(`- TokenId ${token.tokenId}: ${token.balance} owned`);
-     *   console.log(`  Name: ${token.metadata?.name}`);
-     * });
+     * @example Query any external wallet
+     * ```typescript
+     * const externalWallet = '0x1234...abcd';
+     * const result = await sdk.web3.getAccountOwnedTokensFromContract(externalWallet, rewardToken);
+     * console.log(`Wallet owns ${result.totalOwned} tokens`);
      * ```
+     *
+     * @see {@link extractTokenIds} - Low-level helper used internally for ERC-1155
+     * @see {@link buildCollectionRequest} - For manual request building
      */
-    async getUserOwnedTokensFromContract(walletAddress, token, maxTokens = 50) {
+    async getAccountOwnedTokensFromContract(accountAddress, token, maxTokens = 50) {
         // For ERC-1155, extract tokenIds from metadata
         const tokenIds = token.type === NativeTokenTypes.ERC1155 ? this.extractTokenIds(token) : undefined;
         const collection = await this.getTokenCollection({
-            accountAddress: walletAddress,
+            accountAddress: accountAddress,
             contractAddress: token.contractAddress,
             abi: token.abi,
             chainId: token.chainId,
@@ -6011,9 +6730,11 @@ class Web3Manager {
      *
      * Automatically handles ERC-1155 tokenId extraction from metadata.
      * Use this when you need more control over the request than
-     * `getUserOwnedTokensFromContract` provides.
+     * `getAccountOwnedTokensFromContract` provides.
      *
-     * @param walletAddress - User's wallet address
+     * Works with any valid blockchain address - user wallets, external wallets, etc.
+     *
+     * @param accountAddress - Any valid blockchain address (wallet, contract, etc.)
      * @param token - Token definition
      * @param maxTokens - Maximum tokens to retrieve
      * @returns TokenCollectionRequest ready for getTokenCollection()
@@ -6024,9 +6745,9 @@ class Web3Manager {
      * const collection = await sdk.web3.getTokenCollection(request);
      * ```
      */
-    buildCollectionRequest(walletAddress, token, maxTokens = 50) {
+    buildCollectionRequest(accountAddress, token, maxTokens = 50) {
         return {
-            accountAddress: walletAddress,
+            accountAddress: accountAddress,
             contractAddress: token.contractAddress,
             abi: token.abi,
             chainId: token.chainId,
@@ -6146,15 +6867,18 @@ class PersSDK {
      */
     constructor(httpClient, config) {
         this.apiClient = new PersApiClient(httpClient, config);
-        // Initialize domain managers
-        this._auth = new AuthManager(this.apiClient);
-        this._users = new UserManager(this.apiClient);
+        // Initialize event emitter and wire to API client for error events
+        this._events = new PersEventEmitter();
+        this.apiClient.setEvents(this._events);
+        // Initialize domain managers (pass events to managers that emit success events)
+        this._auth = new AuthManager(this.apiClient, this._events);
+        this._users = new UserManager(this.apiClient, this._events);
         this._userStatus = new UserStatusManager(this.apiClient);
         this._tokens = new TokenManager(this.apiClient);
-        this._businesses = new BusinessManager(this.apiClient);
-        this._campaigns = new CampaignManager(this.apiClient);
-        this._redemptions = new RedemptionManager(this.apiClient);
-        this._transactions = new TransactionManager(this.apiClient);
+        this._businesses = new BusinessManager(this.apiClient, this._events);
+        this._campaigns = new CampaignManager(this.apiClient, this._events);
+        this._redemptions = new RedemptionManager(this.apiClient, this._events);
+        this._transactions = new TransactionManager(this.apiClient, this._events);
         this._purchases = new PurchaseManager(this.apiClient);
         this._files = new FileManager(this.apiClient);
         this._tenants = new TenantManager(this.apiClient);
@@ -6163,6 +6887,55 @@ class PersSDK {
         this._donations = new DonationManager(this.apiClient);
         this._web3 = new Web3Manager(this.apiClient);
     }
+    /**
+     * Event emitter - Subscribe to SDK-wide events
+     *
+     * Provides a platform-agnostic event system for subscribing to transaction,
+     * authentication, campaign, and system events. Use this to display
+     * notifications, update UI, or trigger side effects in your application.
+     *
+     * All events have a `userMessage` field ready for display.
+     *
+     * @returns PersEventEmitter instance
+     *
+     * @example Basic Usage - Show All Notifications
+     * ```typescript
+     * const unsubscribe = sdk.events.subscribe((event) => {
+     *   // userMessage is always present and UI-ready
+     *   showNotification(event.userMessage, event.level);
+     * });
+     *
+     * // Later: cleanup
+     * unsubscribe();
+     * ```
+     *
+     * @example Filter by Domain and Level
+     * ```typescript
+     * sdk.events.subscribe((event) => {
+     *   if (event.level === 'success' && event.domain === 'transaction') {
+     *     playSuccessSound();
+     *     confetti();
+     *   }
+     *
+     *   if (event.level === 'error') {
+     *     logToSentry(event);
+     *   }
+     * });
+     * ```
+     *
+     * @example One-time Event
+     * ```typescript
+     * // Auto-unsubscribe after first event
+     * sdk.events.once((event) => {
+     *   console.log('First event received:', event.type);
+     * });
+     * ```
+     *
+     * @see {@link PersEventEmitter} for detailed documentation
+     */
+    get events() {
+        return this._events;
+    }
     /**
      * Authentication manager - High-level authentication operations
      *
@@ -6440,5 +7213,5 @@ function createPersSDK(httpClient, config) {
     return new PersSDK(httpClient, config);
 }
 
-export { AuthStatus as A, BusinessManager as B, CampaignManager as C, DefaultAuthProvider as D, FileManager as F, IndexedDBTokenStorage as I, LocalStorageTokenStorage as L, MemoryTokenStorage as M, PersSDK as P, RedemptionManager as R, 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, PersApiClient as e, DEFAULT_PERS_CONFIG as f, buildApiRoot as g, detectEnvironment as h, environment as i, AuthApi as j, AuthService as k, DPoPManager as l, mergeWithDefaults as m, AuthManager as n, UserStatusManager as o, TransactionManager as p, PurchaseManager as q, TenantManager as r, ApiKeyManager as s, AnalyticsManager as t, DonationManager as u, Web3Manager as v, warnIfProblematicEnvironment as w, FileApi as x, FileService as y, ApiKeyApi as z };
-//# sourceMappingURL=pers-sdk-Nu2KgiJf.js.map
+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, IndexedDBTokenStorage as I, LocalStorageTokenStorage as L, MemoryTokenStorage as M, 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, detectEnvironment as j, environment 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, TenantManager as u, ApiKeyManager as v, warnIfProblematicEnvironment as w, AnalyticsManager as x, DonationManager as y, Web3Manager as z };
+//# sourceMappingURL=pers-sdk-VmeBqUEP.js.map