@explorins/pers-sdk 1.6.45 → 1.6.47

package/dist/chunks/{pers-sdk-DzS7mkm7.cjs → pers-sdk-DULFjOW2.cjs}

@@ -1,12 +1,12 @@
 'use strict';
 
 var persShared = require('@explorins/pers-shared');
-var web3ChainService = require('./web3-chain-service-BLFxB5TA.cjs');
-var userService = require('./user-service-D1Rn4U8u.cjs');
+var web3ChainService = require('./web3-chain-service-6vsVHPjl.cjs');
+var userService = require('./user-service-B89wBOV1.cjs');
 var userStatus = require('../user-status.cjs');
 var tokenService = require('./token-service-BWScn8Qa.cjs');
-var businessService = require('./business-service-P9o4cwQL.cjs');
-var campaignService = require('./campaign-service-B1tQMNqA.cjs');
+var business = require('../business.cjs');
+var campaignService = require('./campaign-service-D-v9ZlUB.cjs');
 var redemptionService = require('./redemption-service-7qbeQxEM.cjs');
 var transactionService = require('./transaction-service-CXjTHCFu.cjs');
 var paymentService = require('./payment-service-B4qx0qiE.cjs');
@@ -61,6 +61,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) {
@@ -87,6 +92,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: persShared.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)
      */
@@ -174,6 +209,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)
      */
@@ -743,6 +809,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
@@ -883,6 +964,7 @@ class PersApiClient {
                 const backendError = web3ChainService.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 web3ChainService.AuthenticationError(backendError.userMessage || backendError.message || 'Refresh token expired', endpoint, method, backendError.code, backendError.userMessage, backendError.title);
                 }
                 // For regular requests: try refresh once, then fail
@@ -900,11 +982,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 web3ChainService.AuthenticationError(backendError.userMessage || backendError.message || 'Authentication required', endpoint, method, backendError.code, backendError.userMessage, backendError.title);
             }
-            throw new web3ChainService.PersApiError(errorMessage, endpoint, method, status || undefined, web3ChainService.ErrorUtils.isRetryable(error));
+            // Extract backend error details for non-401 errors
+            const errorDetails = web3ChainService.ErrorUtils.extractBackendErrorDetails(error);
+            this.emitErrorEvent(errorDetails, errorMessage, endpoint, method, status, error);
+            throw new web3ChainService.PersApiError(errorMessage, endpoint, method, status || undefined, web3ChainService.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: web3ChainService.ErrorUtils.isRetryable(error)
+            }
+        });
+    }
+    /**
+     * Set event emitter for error event emission
+     * @internal
+     */
+    setEvents(events) {
+        this._events = events;
+    }
     /**
      * Performs an authenticated GET request
      *
@@ -950,6 +1068,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;
@@ -1156,12 +1275,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
  *
@@ -1170,6 +1508,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();
@@ -1181,8 +1523,9 @@ function warnIfProblematicEnvironment(feature) {
  * ```
  */
 class AuthManager {
-    constructor(apiClient) {
+    constructor(apiClient, events) {
         this.apiClient = apiClient;
+        this.events = events;
     }
     /**
      * Login with JWT token
@@ -1211,8 +1554,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
      *
@@ -1414,8 +1827,9 @@ class AuthManager {
  * ```
  */
 class UserManager {
-    constructor(apiClient) {
+    constructor(apiClient, events) {
         this.apiClient = apiClient;
+        this.events = events;
         const userApi = new userService.UserApi(apiClient);
         this.userService = new userService.UserService(userApi);
     }
@@ -1471,7 +1885,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
@@ -1568,6 +1989,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
      *
@@ -2072,10 +2551,14 @@ class TokenManager {
  * ```
  */
 class BusinessManager {
-    constructor(apiClient) {
+    constructor(apiClient, events) {
         this.apiClient = apiClient;
-        this.businessApi = new businessService.BusinessApi(apiClient);
-        this.businessService = new businessService.BusinessService(this.businessApi);
+        this.events = events;
+        this.businessApi = new business.BusinessApi(apiClient);
+        this.businessService = new business.BusinessService(this.businessApi);
+        this.membershipApi = new business.BusinessMembershipApi(apiClient);
+        this.membershipService = new business.BusinessMembershipService(this.membershipApi);
+        this.userApi = new userService.UserApi(apiClient);
     }
     /**
      * Get all active businesses
@@ -2155,7 +2638,7 @@ class BusinessManager {
      *
      * // Use for transaction verification
      * if (business.isActive) {
-     *   console.log('✅ Verified business partner');
+     *   console.log('Verified business partner');
      * }
      * ```
      */
@@ -2284,7 +2767,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
@@ -2312,7 +2802,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
@@ -2370,6 +2867,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 = persShared.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 = persShared.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;
+    }
 }
 
 /**
@@ -2385,9 +3085,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');
@@ -2413,7 +3113,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)
  * );
  * ```
@@ -2438,47 +3139,12 @@ class BusinessManager {
  * ```
  */
 class CampaignManager {
-    constructor(apiClient) {
+    constructor(apiClient, events) {
         this.apiClient = apiClient;
+        this.events = events;
         const campaignApi = new campaignService.CampaignApi(apiClient);
         this.campaignService = new campaignService.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
      *
@@ -2576,7 +3242,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
@@ -2618,40 +3291,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
@@ -3170,8 +3849,9 @@ class CampaignManager {
  * ```
  */
 class RedemptionManager {
-    constructor(apiClient) {
+    constructor(apiClient, events) {
         this.apiClient = apiClient;
+        this.events = events;
         const redemptionApi = new redemptionService.RedemptionApi(apiClient);
         this.redemptionService = new redemptionService.RedemptionService(redemptionApi);
     }
@@ -3335,7 +4015,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
@@ -3699,8 +4386,9 @@ class RedemptionManager {
  * ```
  */
 class TransactionManager {
-    constructor(apiClient) {
+    constructor(apiClient, events) {
         this.apiClient = apiClient;
+        this.events = events;
         const transactionApi = new transactionService.TransactionApi(apiClient);
         this.transactionService = new transactionService.TransactionService(transactionApi);
     }
@@ -3836,7 +4524,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
@@ -3853,7 +4548,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();
@@ -4141,7 +4836,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
@@ -5837,6 +6539,13 @@ class DonationManager {
  * ```
  */
 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
@@ -6160,15 +6869,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);
@@ -6177,6 +6889,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
      *
@@ -6476,9 +7237,13 @@ exports.IndexedDBTokenStorage = IndexedDBTokenStorage;
 exports.LocalStorageTokenStorage = LocalStorageTokenStorage;
 exports.MemoryTokenStorage = MemoryTokenStorage;
 exports.PersApiClient = PersApiClient;
+exports.PersEventEmitter = PersEventEmitter;
 exports.PersSDK = PersSDK;
 exports.PurchaseManager = PurchaseManager;
 exports.RedemptionManager = RedemptionManager;
+exports.SDK_NAME = SDK_NAME;
+exports.SDK_USER_AGENT = SDK_USER_AGENT;
+exports.SDK_VERSION = SDK_VERSION;
 exports.TenantManager = TenantManager;
 exports.TokenManager = TokenManager;
 exports.TransactionManager = TransactionManager;
@@ -6492,4 +7257,4 @@ exports.detectEnvironment = detectEnvironment;
 exports.environment = environment;
 exports.mergeWithDefaults = mergeWithDefaults;
 exports.warnIfProblematicEnvironment = warnIfProblematicEnvironment;
-//# sourceMappingURL=pers-sdk-DzS7mkm7.cjs.map
+//# sourceMappingURL=pers-sdk-DULFjOW2.cjs.map