@explorins/pers-sdk 2.1.10 → 2.1.14

package/dist/chunks/{pers-sdk-Co-R9M1O.cjs → pers-sdk-Cv7hM1I7.cjs}

@@ -1,16 +1,16 @@
 'use strict';
 
 var persShared = require('@explorins/pers-shared');
-var index = require('./index-B-g2JPVK.cjs');
+var index = require('./index-CGaKfZNU.cjs');
 var user = require('../user.cjs');
 var userStatus = require('../user-status.cjs');
 var tokenService = require('./token-service-C1xe11OX.cjs');
 var businessMembershipService = require('./business-membership-service-BfHzIQlc.cjs');
 var campaign = require('../campaign.cjs');
 var redemptionService = require('./redemption-service-C61Qr2vI.cjs');
-var transactionRequest_builder = require('./transaction-request.builder-Bjxi0C9F.cjs');
+var transactionRequest_builder = require('./transaction-request.builder-CW3Wwdi3.cjs');
 var paymentService = require('./payment-service-Bkw7ZXev.cjs');
-var tenantService = require('./tenant-service-fj-pkXTw.cjs');
+var tenantManager = require('./tenant-manager-BUiFM33X.cjs');
 var paginationUtils = require('./pagination-utils-B2jRHMSO.cjs');
 var analyticsService = require('./analytics-service-CF9AsMQH.cjs');
 var donation = require('../donation.cjs');
@@ -31,7 +31,8 @@ const DEFAULT_PERS_CONFIG = {
     timeout: 30000,
     retries: 3,
     tokenRefreshMargin: 60, // Refresh tokens 60 seconds before expiry
-    backgroundRefreshThreshold: 30 // Use background refresh if >30s remaining
+    backgroundRefreshThreshold: 30, // Use background refresh if >30s remaining
+    captureWalletEvents: true // Auto-connect to wallet events after auth
 };
 /**
  * Build the API root URL based on config
@@ -53,6 +54,21 @@ function buildApiRoot(environment = 'production', version = 'v2', customApiUrl)
     };
     return baseUrls[environment];
 }
+/**
+ * Build wallet events WebSocket URL based on config
+ *
+ * @internal
+ */
+function buildWalletEventsWsUrl(environment = 'production', customWsUrl) {
+    if (customWsUrl) {
+        return customWsUrl;
+    }
+    const wsUrls = {
+        staging: 'wss://events-staging.pers.ninja',
+        production: 'wss://events.pers.ninja'
+    };
+    return wsUrls[environment];
+}
 /**
  * Merge user config with defaults
  */
@@ -1413,7 +1429,6 @@ class PersEventEmitter {
     constructor() {
         this.handlers = new Set();
         this._instanceId = ++emitterInstanceCounter;
-        console.log(`[PersEventEmitter] Instance #${this._instanceId} created`);
     }
     get instanceId() {
         return this._instanceId;
@@ -2236,34 +2251,37 @@ class UserManager {
         return this.userService.updateUserAsAdmin(userId, userData);
     }
     /**
-     * Admin: Toggle user active status
+     * Admin: Set or toggle user active status
      *
-     * Toggles the active/inactive status of a user account. This is typically
-     * used for account suspension or reactivation. Requires administrator privileges.
+     * Sets the active/inactive status of a user account explicitly, or toggles
+     * if no explicit value is provided. This is typically used for account
+     * suspension or reactivation. Requires administrator privileges.
      *
-     * @param user - User object to toggle status for
+     * @param userId - User ID to update
+     * @param isActive - Optional explicit status. If provided, sets to this value. If omitted, toggles current status.
      * @returns Promise resolving to updated user data
      * @throws {PersApiError} When not authenticated as admin
      *
-     * @example Suspend User
+     * @example Explicit Status
      * ```typescript
-     * // Admin operation - toggle user status
-     * try {
-     *   const user = await sdk.users.getUserById('problematic-user-123');
-     *   const updated = await sdk.users.toggleUserStatus(user);
+     * // Admin operation - explicitly activate user
+     * const activated = await sdk.users.setUserActiveStatus('user-123', true);
+     * console.log('User activated:', activated.isActive); // true
      *
-     *   if (updated.isActive) {
-     *     console.log('User account reactivated');
-     *   } else {
-     *     console.log('User account suspended');
-     *   }
-     * } catch (error) {
-     *   console.log('Failed to update user status');
-     * }
+     * // Explicitly deactivate user
+     * const deactivated = await sdk.users.setUserActiveStatus('user-123', false);
+     * console.log('User deactivated:', deactivated.isActive); // false
+     * ```
+     *
+     * @example Toggle Status
+     * ```typescript
+     * // Admin operation - toggle current status
+     * const toggled = await sdk.users.setUserActiveStatus('user-123');
+     * console.log('User status toggled:', toggled.isActive);
      * ```
      */
-    async toggleUserStatus(user) {
-        return this.userService.toggleUserActiveStatusByUser(user);
+    async setUserActiveStatus(userId, isActive) {
+        return this.userService.setUserActiveStatus(userId, isActive);
     }
     /**
      * Admin: Delete user (soft delete)
@@ -6379,89 +6397,6 @@ class FileManager {
     }
 }
 
-/**
- * Tenant Manager - Clean, high-level interface for tenant operations
- *
- * Provides a simplified API for common tenant management tasks while maintaining
- * access to the full tenant SDK for advanced use cases.
- */
-class TenantManager {
-    constructor(apiClient) {
-        this.apiClient = apiClient;
-        const tenantApi = new tenantService.TenantApi(apiClient);
-        this.tenantService = new tenantService.TenantService(tenantApi);
-    }
-    /**
-     * Get current tenant information
-     *
-     * @returns Promise resolving to tenant data
-     */
-    async getTenantInfo() {
-        return this.tenantService.getRemoteTenant();
-    }
-    /**
-     * Get tenant login token
-     *
-     * @returns Promise resolving to login token
-     */
-    async getLoginToken() {
-        return this.tenantService.getRemoteLoginToken();
-    }
-    /**
-     * Get tenant client configuration
-     *
-     * @returns Promise resolving to client config
-     */
-    async getClientConfig() {
-        return this.tenantService.getRemoteClientConfig();
-    }
-    /**
-     * Admin: Update tenant data
-     *
-     * @param tenantData - Updated tenant data
-     * @returns Promise resolving to updated tenant
-     */
-    async updateTenant(tenantData) {
-        return this.tenantService.updateRemoteTenant(tenantData);
-    }
-    /**
-     * Admin: Get all admins
-     *
-     * @param options - Pagination options
-     * @returns Promise resolving to paginated admins
-     */
-    async getAdmins(options) {
-        return this.tenantService.getAdmins(options);
-    }
-    /**
-     * Admin: Create new admin
-     *
-     * @param adminData - Admin data
-     * @returns Promise resolving to created admin
-     */
-    async createAdmin(adminData) {
-        return this.tenantService.postAdmin(adminData);
-    }
-    /**
-     * Admin: Update existing admin
-     *
-     * @param adminId - ID of the admin to update
-     * @param adminData - Updated admin data
-     * @returns Promise resolving to updated admin
-     */
-    async updateAdmin(adminId, adminData) {
-        return this.tenantService.putAdmin(adminId, adminData);
-    }
-    /**
-     * Get the tenant service for advanced operations
-     *
-     * @returns TenantService instance
-     */
-    getTenantService() {
-        return this.tenantService;
-    }
-}
-
 /**
  * Platform-Agnostic API Key API Client
  *
@@ -7397,102 +7332,1513 @@ class TriggerSourceManager {
 }
 
 /**
- * @fileoverview PERS SDK - Platform-agnostic TypeScript SDK with High-Level Managers
+ * Webhook API - Low-level API client for webhook operations
  *
- * @module @explorins/pers-sdk
- * @version 1.6.4
- * @author Explorins
- * @license MIT
+ * Backend routes:
+ * - Admin CRUD: /hooks (requires tenant auth)
+ * - Proxy/Trigger: /hooks/:projectKey/:hookId (public, identified by projectKey)
+ * - Callback: /hooks/:projectKey/executions/:executionId/callback (public)
+ *
+ * @internal Use WebhookService or WebhookManager for higher-level operations
  */
+class WebhookApi {
+    constructor(apiClient) {
+        this.apiClient = apiClient;
+        this.basePath = '/hooks';
+    }
+    // ================================
+    // ADMIN: Webhook Configuration CRUD
+    // All require tenant auth (handled by apiClient)
+    // ================================
+    /**
+     * List all webhooks (Admin)
+     * GET /hooks
+     */
+    async listWebhooks(options) {
+        const params = new URLSearchParams();
+        if (options?.active !== undefined)
+            params.append('active', String(options.active));
+        if (options?.page)
+            params.append('page', String(options.page));
+        if (options?.limit)
+            params.append('limit', String(options.limit));
+        if (options?.search)
+            params.append('search', options.search);
+        const queryString = params.toString();
+        const url = queryString ? `${this.basePath}?${queryString}` : this.basePath;
+        return this.apiClient.get(url);
+    }
+    /**
+     * Get webhook by ID (Admin)
+     * GET /hooks/:hookId
+     */
+    async getWebhookById(webhookId) {
+        return this.apiClient.get(`${this.basePath}/${webhookId}`);
+    }
+    /**
+     * Create a new webhook (Admin)
+     * POST /hooks
+     */
+    async createWebhook(webhook) {
+        return this.apiClient.post(this.basePath, webhook);
+    }
+    /**
+     * Update a webhook (Admin)
+     * PUT /hooks/:hookId
+     */
+    async updateWebhook(webhookId, webhook) {
+        return this.apiClient.put(`${this.basePath}/${webhookId}`, webhook);
+    }
+    /**
+     * Delete a webhook (Admin)
+     * DELETE /hooks/:hookId
+     */
+    async deleteWebhook(webhookId) {
+        return this.apiClient.delete(`${this.basePath}/${webhookId}`);
+    }
+    // ================================
+    // Webhook Triggering via Proxy
+    // Route: /hooks/:projectKey/:hookId
+    // Public endpoint identified by projectKey in URL
+    // ================================
+    /**
+     * Trigger a webhook programmatically
+     *
+     * Uses the proxy endpoint which requires projectKey in the URL path.
+     * The projectKey is obtained from SDK config.
+     *
+     * ALL /hooks/:projectKey/:hookId
+     */
+    async triggerWebhook(request, projectKey) {
+        const { hookId, method = 'POST', body, queryParams, waitForCallback, callbackTimeoutMs } = request;
+        // Build query string from queryParams
+        const params = new URLSearchParams();
+        if (queryParams) {
+            Object.entries(queryParams).forEach(([key, value]) => params.append(key, value));
+        }
+        if (waitForCallback)
+            params.append('waitForCallback', 'true');
+        if (callbackTimeoutMs)
+            params.append('callbackTimeoutMs', String(callbackTimeoutMs));
+        const queryString = params.toString();
+        // Use proxy path with projectKey
+        const proxyPath = `${this.basePath}/${projectKey}/${hookId}`;
+        const url = queryString ? `${proxyPath}?${queryString}` : proxyPath;
+        // Use appropriate HTTP method - backend returns WebhookTriggerResponseDTO
+        switch (method) {
+            case 'GET':
+                return this.apiClient.get(url);
+            case 'PUT':
+                return this.apiClient.put(url, body);
+            case 'DELETE':
+                return this.apiClient.delete(url);
+            case 'POST':
+            default:
+                return this.apiClient.post(url, body);
+        }
+    }
+    // ================================
+    // Execution History (Admin)
+    // GET /hooks/executions
+    // ================================
+    /**
+     * List webhook executions (Admin)
+     * GET /hooks/executions
+     */
+    async listExecutions(options) {
+        const params = new URLSearchParams();
+        if (options?.webhookId)
+            params.append('hookId', options.webhookId);
+        if (options?.status)
+            params.append('status', options.status);
+        if (options?.fromDate)
+            params.append('dateFrom', options.fromDate);
+        if (options?.toDate)
+            params.append('dateTo', options.toDate);
+        if (options?.page)
+            params.append('page', String(options.page));
+        if (options?.limit)
+            params.append('limit', String(options.limit));
+        const queryString = params.toString();
+        const url = queryString ? `${this.basePath}/executions?${queryString}` : `${this.basePath}/executions`;
+        return this.apiClient.get(url);
+    }
+    /**
+     * Get execution by ID (Admin)
+     * Note: This endpoint doesn't exist in current backend - would need to filter by ID
+     */
+    async getExecutionById(executionId) {
+        // Filter executions by ID since direct endpoint doesn't exist
+        const result = await this.listExecutions({ page: 1, limit: 1 });
+        const execution = result.data.find(e => e.id === executionId);
+        if (!execution) {
+            throw new Error(`Execution ${executionId} not found`);
+        }
+        return execution;
+    }
+    // ================================
+    // Callback (Public - called by external systems)
+    // POST /hooks/:projectKey/executions/:executionId/callback
+    // ================================
+    /**
+     * Send callback result (for testing or manual callback trigger)
+     * This is normally called by external systems like n8n
+     *
+     * POST /hooks/:projectKey/executions/:executionId/callback
+     */
+    async sendCallback(executionId, callback, projectKey) {
+        return this.apiClient.post(`${this.basePath}/${projectKey}/executions/${executionId}/callback`, callback);
+    }
+}
+
 /**
- * PERS SDK - Main SDK class with domain managers
+ * Webhook Service - Business logic layer for webhook operations
  *
- * Main SDK interface providing clean, high-level managers for common operations
- * while maintaining full access to the underlying API client and domain services.
- *
- * The SDK follows a layered architecture:
- * - **Managers**: High-level, intuitive APIs for common operations
- * - **Domain Services**: Full-featured access for advanced use cases
- * - **API Client**: Direct REST API access for custom operations
+ * Provides higher-level operations on top of WebhookApi including:
+ * - Validation and error handling
+ * - Convenience methods for common patterns
+ * - Async workflow support with callbacks
  *
- * @group Core
- * @category SDK
+ * Note: Trigger operations require projectKey which is obtained from SDK config.
  *
- * @example Basic Setup
- * ```typescript
- * import { PersSDK } from '@explorins/pers-sdk';
- * import { BrowserFetchClientAdapter } from '@explorins/pers-sdk/platform-adapters';
+ * @group Services
+ * @category Webhook
+ */
+class WebhookService {
+    constructor(webhookApi, projectKey) {
+        this.webhookApi = webhookApi;
+        this.projectKey = projectKey;
+    }
+    // ================================
+    // Admin: Webhook Configuration
+    // ================================
+    /**
+     * Get all webhooks with optional filters
+     */
+    async getWebhooks(options) {
+        return this.webhookApi.listWebhooks(options);
+    }
+    /**
+     * Get active webhooks only
+     */
+    async getActiveWebhooks() {
+        return this.webhookApi.listWebhooks({ active: true });
+    }
+    /**
+     * Get webhook by ID
+     */
+    async getWebhookById(webhookId) {
+        return this.webhookApi.getWebhookById(webhookId);
+    }
+    /**
+     * Create a new webhook
+     */
+    async createWebhook(webhook) {
+        // Validate required fields
+        if (!webhook.name?.trim()) {
+            throw new Error('Webhook name is required');
+        }
+        if (!webhook.targetUrl?.trim()) {
+            throw new Error('Target URL is required');
+        }
+        // Validate URL format
+        try {
+            new URL(webhook.targetUrl);
+        }
+        catch {
+            throw new Error('Invalid target URL format');
+        }
+        return this.webhookApi.createWebhook(webhook);
+    }
+    /**
+     * Update a webhook
+     */
+    async updateWebhook(webhookId, webhook) {
+        // Validate URL if provided (cast to access optional property from PartialType)
+        const update = webhook;
+        if (update.targetUrl) {
+            try {
+                new URL(update.targetUrl);
+            }
+            catch {
+                throw new Error('Invalid target URL format');
+            }
+        }
+        return this.webhookApi.updateWebhook(webhookId, webhook);
+    }
+    /**
+     * Enable a webhook
+     */
+    async enableWebhook(webhookId) {
+        return this.webhookApi.updateWebhook(webhookId, { isActive: true });
+    }
+    /**
+     * Disable a webhook
+     */
+    async disableWebhook(webhookId) {
+        return this.webhookApi.updateWebhook(webhookId, { isActive: false });
+    }
+    /**
+     * Delete a webhook
+     */
+    async deleteWebhook(webhookId) {
+        return this.webhookApi.deleteWebhook(webhookId);
+    }
+    // ================================
+    // Webhook Triggering (via Proxy)
+    // Uses /hooks/:projectKey/:hookId
+    // ================================
+    /**
+     * Trigger a webhook with full control over request parameters
+     */
+    async triggerWebhook(request) {
+        return this.webhookApi.triggerWebhook(request, this.projectKey);
+    }
+    /**
+     * Simple POST trigger with JSON body
+     */
+    async post(hookId, body) {
+        return this.webhookApi.triggerWebhook({
+            hookId,
+            method: persShared.WebhookMethod.POST,
+            body
+        }, this.projectKey);
+    }
+    /**
+     * Simple GET trigger
+     */
+    async get(hookId, queryParams) {
+        return this.webhookApi.triggerWebhook({
+            hookId,
+            method: persShared.WebhookMethod.GET,
+            queryParams
+        }, this.projectKey);
+    }
+    /**
+     * Trigger and wait for async callback (for workflow systems like n8n)
+     *
+     * @param hookId - Webhook ID to trigger
+     * @param body - Request body
+     * @param timeoutMs - How long to wait for callback (default: 30000ms)
+     */
+    async triggerAndWait(hookId, body, timeoutMs = 30000) {
+        return this.webhookApi.triggerWebhook({
+            hookId,
+            method: persShared.WebhookMethod.POST,
+            body,
+            waitForCallback: true,
+            callbackTimeoutMs: timeoutMs
+        }, this.projectKey);
+    }
+    // ================================
+    // Execution History (Admin)
+    // ================================
+    /**
+     * Get execution history with filters
+     */
+    async getExecutions(options) {
+        return this.webhookApi.listExecutions(options);
+    }
+    /**
+     * Get executions for a specific webhook
+     */
+    async getWebhookExecutions(webhookId, options) {
+        return this.webhookApi.listExecutions({ ...options, webhookId });
+    }
+    /**
+     * Get failed executions
+     */
+    async getFailedExecutions(options) {
+        return this.webhookApi.listExecutions({ ...options, status: persShared.WebhookExecutionStatus.FAILED });
+    }
+    /**
+     * Get execution details by ID
+     */
+    async getExecutionById(executionId) {
+        return this.webhookApi.getExecutionById(executionId);
+    }
+    // ================================
+    // Callback (for testing/manual triggers)
+    // ================================
+    /**
+     * Send a callback result for an execution
+     * Normally this is called by external systems like n8n
+     */
+    async sendCallback(executionId, callback) {
+        return this.webhookApi.sendCallback(executionId, callback, this.projectKey);
+    }
+}
+
+/**
+ * Webhook Manager - Clean, high-level interface for webhook operations
  *
- * const sdk = new PersSDK(new BrowserFetchClientAdapter(), {
- *   environment: 'production',
- *   apiProjectKey: 'your-project-key'
- * });
- * ```
+ * Webhooks enable integration with external systems (n8n, Zapier, custom backends):
+ * - **Admin operations**: Create, configure, and manage webhook endpoints
+ * - **Trigger operations**: Programmatically trigger webhooks with payloads
+ * - **Async workflows**: Wait for callbacks from workflow systems
+ * - **Monitoring**: Track execution history
  *
- * @example Authentication Flow
- * ```typescript
- * // Login with external JWT
- * await sdk.auth.loginWithToken(firebaseJWT, 'user');
+ * ## Security Model
+ * - Admin endpoints require tenant authentication
+ * - Trigger endpoints work with user/business/tenant auth
+ * - Caller identity is passed to webhook target
  *
- * // Check authentication
- * if (await sdk.auth.isAuthenticated()) {
- *   const user = await sdk.auth.getCurrentUser();
- *   console.log('Welcome,', user.name);
- * }
- * ```
+ * @group Managers
+ * @category Webhook Management
  *
- * @example Business Operations
+ * @example Basic Webhook Operations
  * ```typescript
- * // Get active businesses
- * const businesses = await sdk.businesses.getActiveBusinesses();
+ * // Admin: Create a webhook for order processing
+ * const webhook = await sdk.webhooks.create({
+ *   name: 'Process Order',
+ *   targetUrl: 'https://n8n.example.com/webhook/orders',
+ *   method: 'POST',
+ *   headers: { 'X-Custom-Header': 'value' }
+ * });
  *
- * // Get business details
- * const business = await sdk.businesses.getBusinessById(businessId);
+ * // Trigger webhook with order data
+ * const result = await sdk.webhooks.trigger(webhook.id, {
+ *   orderId: 'order-123',
+ *   items: [{ productId: 'prod-1', quantity: 2 }]
+ * });
+ *
+ * console.log('Execution ID:', result.executionId);
  * ```
  *
- * @example Token Operations
+ * @example Async Workflow with Callback
  * ```typescript
- * // Get user's token balances
- * const tokens = await sdk.tokens.getTokens();
+ * // Trigger and wait for workflow completion (up to 30s)
+ * const result = await sdk.webhooks.triggerAndWait(
+ *   'ai-processing-webhook',
+ *   { prompt: 'Generate report for Q1' },
+ *   30000
+ * );
  *
- * // Get active credit token
- * const creditToken = await sdk.tokens.getActiveCreditToken();
+ * if (result.status === 'COMPLETED') {
+ *   console.log('AI Response:', result.body);
+ * }
  * ```
- *
- * @since 1.3.0 - Manager pattern architecture
  */
-class PersSDK {
+class WebhookManager {
+    constructor(apiClient, projectKey, events) {
+        this.apiClient = apiClient;
+        this.projectKey = projectKey;
+        this.events = events;
+        const webhookApi = new WebhookApi(apiClient);
+        this.webhookService = new WebhookService(webhookApi, projectKey);
+    }
+    // ================================
+    // Admin: Webhook Configuration
+    // ================================
     /**
-     * Creates a new PERS SDK instance
-     *
-     * Initializes all domain managers and sets up the API client with the provided
-     * HTTP client adapter and configuration.
+     * Get all webhooks with optional filters (Admin)
      *
-     * @param httpClient - Platform-specific HTTP client implementation
-     * @param config - SDK configuration options
+     * @param options - Filter and pagination options
+     * @returns Promise resolving to paginated webhooks
      *
-     * @example Browser Setup
+     * @example
      * ```typescript
-     * import { BrowserFetchClientAdapter } from '@explorins/pers-sdk/platform-adapters';
+     * // Get all webhooks
+     * const webhooks = await sdk.webhooks.getAll();
      *
-     * const sdk = new PersSDK(new BrowserFetchClientAdapter(), {
-     *   environment: 'production',
-     *   apiProjectKey: 'your-project-key'
-     * });
+     * // Get only active webhooks
+     * const active = await sdk.webhooks.getAll({ active: true });
+     *
+     * // Search by name
+     * const found = await sdk.webhooks.getAll({ search: 'order' });
      * ```
+     */
+    async getAll(options) {
+        return this.webhookService.getWebhooks(options);
+    }
+    /**
+     * Get active webhooks only (Admin)
+     */
+    async getActive() {
+        return this.webhookService.getActiveWebhooks();
+    }
+    /**
+     * Get webhook by ID (Admin)
      *
-     * @example Node.js Setup
-     * ```typescript
-     * import { NodeHttpClientAdapter } from '@explorins/pers-sdk/platform-adapters';
+     * @param webhookId - UUID of the webhook
+     * @returns Promise resolving to webhook details
+     */
+    async getById(webhookId) {
+        return this.webhookService.getWebhookById(webhookId);
+    }
+    /**
+     * Create a new webhook (Admin)
      *
-     * const sdk = new PersSDK(new NodeHttpClientAdapter(), {
-     *   environment: 'production',
-     *   apiProjectKey: 'your-project-key',
-     *   baseUrl: 'https://api.yourpers.com'
+     * @param webhook - Webhook configuration
+     * @returns Promise resolving to created webhook
+     *
+     * @example
+     * ```typescript
+     * const webhook = await sdk.webhooks.create({
+     *   name: 'Order Notifications',
+     *   targetUrl: 'https://api.example.com/webhooks/orders',
+     *   method: 'POST',
+     *   headers: {
+     *     'Authorization': 'Bearer secret-token'
+     *   },
+     *   rateLimitPerMinute: 60
      * });
      * ```
+     */
+    async create(webhook) {
+        const result = await this.webhookService.createWebhook(webhook);
+        this.events?.emitSuccess({
+            domain: 'webhook',
+            type: 'WEBHOOK_CREATED',
+            userMessage: 'Webhook created successfully',
+            details: { webhookId: result.id, name: result.name }
+        });
+        return result;
+    }
+    /**
+     * Update a webhook (Admin)
      *
-     * @example Angular Setup
+     * @param webhookId - UUID of the webhook to update
+     * @param webhook - Updated configuration (partial)
+     * @returns Promise resolving to updated webhook
+     */
+    async update(webhookId, webhook) {
+        const result = await this.webhookService.updateWebhook(webhookId, webhook);
+        this.events?.emitSuccess({
+            domain: 'webhook',
+            type: 'WEBHOOK_UPDATED',
+            userMessage: 'Webhook updated successfully',
+            details: { webhookId }
+        });
+        return result;
+    }
+    /**
+     * Enable a webhook (Admin)
+     */
+    async enable(webhookId) {
+        return this.webhookService.enableWebhook(webhookId);
+    }
+    /**
+     * Disable a webhook (Admin)
+     */
+    async disable(webhookId) {
+        return this.webhookService.disableWebhook(webhookId);
+    }
+    /**
+     * Delete a webhook (Admin)
+     *
+     * @param webhookId - UUID of the webhook to delete
+     * @returns Promise resolving to deletion confirmation
+     */
+    async delete(webhookId) {
+        const result = await this.webhookService.deleteWebhook(webhookId);
+        this.events?.emitSuccess({
+            domain: 'webhook',
+            type: 'WEBHOOK_DELETED',
+            userMessage: 'Webhook deleted successfully',
+            details: { webhookId }
+        });
+        return result;
+    }
+    // ================================
+    // Webhook Triggering
+    // ================================
+    /**
+     * Trigger a webhook with GET method
+     *
+     * Sends a GET request through the webhook proxy. Returns the full response
+     * including execution metadata and raw data from the target.
+     *
+     * @param hookId - Webhook ID to trigger
+     * @param queryParams - Optional query parameters
+     * @returns Promise resolving to trigger response with metadata and data
+     *
+     * @example
+     * ```typescript
+     * // Fetch data from external API via webhook proxy
+     * const result = await sdk.webhooks.get('user-directory-webhook');
+     * console.log('Success:', result.success);
+     * console.log('Data:', result.data); // Raw data from target
+     * ```
+     */
+    async get(hookId, queryParams) {
+        return this.webhookService.get(hookId, queryParams);
+    }
+    /**
+     * Trigger a webhook with POST method
+     *
+     * Sends data to the configured webhook target. The caller's identity
+     * (user/business/tenant) is included in the request context.
+     *
+     * @param hookId - Webhook ID to trigger
+     * @param body - Payload to send
+     * @returns Promise resolving to trigger response with execution metadata
+     *
+     * @example
+     * ```typescript
+     * const result = await sdk.webhooks.trigger('order-webhook', {
+     *   orderId: 'order-123',
+     *   action: 'created',
+     *   items: [...]
+     * });
+     *
+     * console.log('Success:', result.success);
+     * console.log('Execution ID:', result.executionId);
+     * console.log('Response:', result.data);
+     * ```
+     */
+    async trigger(hookId, body) {
+        const result = await this.webhookService.post(hookId, body);
+        this.events?.emitSuccess({
+            domain: 'webhook',
+            type: 'WEBHOOK_TRIGGERED',
+            userMessage: 'Webhook triggered',
+            details: { hookId, executionId: result.executionId }
+        });
+        return result;
+    }
+    /**
+     * Trigger a webhook and wait for async callback
+     *
+     * Use this for workflow systems (n8n, Zapier) that need time to process
+     * and return results via callback. The SDK will wait for the callback
+     * up to the specified timeout.
+     *
+     * @param hookId - Webhook ID to trigger
+     * @param body - Payload to send
+     * @param timeoutMs - Max time to wait for callback (default: 30s)
+     * @returns Promise resolving when callback received or timeout
+     *
+     * @example
+     * ```typescript
+     * // Trigger AI workflow and wait for result
+     * const result = await sdk.webhooks.triggerAndWait(
+     *   'ai-analysis-webhook',
+     *   { documentId: 'doc-123', analysisType: 'sentiment' },
+     *   60000 // Wait up to 60 seconds
+     * );
+     *
+     * if (result.success) {
+     *   console.log('Analysis:', result.data);
+     * }
+     * ```
+     */
+    async triggerAndWait(hookId, body, timeoutMs = 30000) {
+        return this.webhookService.triggerAndWait(hookId, body, timeoutMs);
+    }
+    // ================================
+    // Execution History & Monitoring
+    // ================================
+    /**
+     * Get webhook execution history (Admin)
+     *
+     * @param options - Filter and pagination options
+     * @returns Promise resolving to paginated executions
+     *
+     * @example
+     * ```typescript
+     * // Get recent failed executions
+     * const failed = await sdk.webhooks.getExecutions({ status: 'FAILED' });
+     *
+     * // Get executions for specific webhook
+     * const executions = await sdk.webhooks.getExecutions({
+     *   webhookId: 'webhook-123',
+     *   fromDate: '2024-01-01'
+     * });
+     * ```
+     */
+    async getExecutions(options) {
+        return this.webhookService.getExecutions(options);
+    }
+    /**
+     * Get execution details by ID (Admin)
+     */
+    async getExecutionById(executionId) {
+        return this.webhookService.getExecutionById(executionId);
+    }
+    /**
+     * Get the full webhook service for advanced operations
+     *
+     * @returns WebhookService instance with full API access
+     */
+    getWebhookService() {
+        return this.webhookService;
+    }
+}
+
+/**
+ * PERS Events Client
+ *
+ * Lightweight WebSocket client for real-time blockchain event streaming.
+ * Connects to the PERS WS Relay server to receive events for user's wallets.
+ *
+ * ## v1.2.0 Subscription Model
+ *
+ * JWT is used for authentication only. After connecting, you must explicitly
+ * subscribe to wallets (user SDK) or chains (admin dashboard).
+ *
+ * @example User SDK - Subscribe to specific wallets
+ * ```typescript
+ * const client = new PersEventsClient({
+ *   wsUrl: 'wss://events.pers.ninja',
+ *   autoReconnect: true
+ * });
+ *
+ * await client.connect(jwtToken);
+ *
+ * // Subscribe to user's wallets
+ * await client.subscribeWallets([
+ *   { address: '0x123...', chainId: 39123 }
+ * ]);
+ *
+ * client.on('Transfer', (event) => {
+ *   console.log(`Received ${event.data.value} tokens`);
+ * });
+ * ```
+ *
+ * @example Admin Dashboard - Subscribe to all events on chains
+ * ```typescript
+ * await client.connect(adminJwtToken);
+ *
+ * // Subscribe to all events on specific chains
+ * await client.subscribeChains([39123, 137]);
+ *
+ * client.on('*', (event) => {
+ *   console.log(`Chain ${event.chainId}: ${event.type}`);
+ * });
+ * ```
+ */
+const DEFAULT_CONFIG = {
+    autoReconnect: true,
+    maxReconnectAttempts: 10,
+    reconnectDelay: 1000,
+    connectionTimeout: 30000,
+    debug: false,
+    tokenRefresher: undefined,
+};
+class PersEventsClient {
+    constructor(config) {
+        this.ws = null;
+        this.state = 'disconnected';
+        this.reconnectAttempts = 0;
+        this.reconnectTimeout = null;
+        this.token = null;
+        // Event handlers by type
+        this.handlers = new Map();
+        this.stateHandlers = new Set();
+        // Connection info from server
+        this.connectionInfo = null;
+        // Current subscription state
+        this.subscriptionState = { wallets: [], chains: [], activeChains: [] };
+        // Pending subscription promise resolver
+        this.pendingSubscription = null;
+        // Subscriptions to restore on reconnect
+        this.savedSubscriptions = { wallets: [], chains: [] };
+        this.config = { ...DEFAULT_CONFIG, ...config };
+    }
+    /**
+     * Connect to the WS relay server
+     * @param token - JWT token for authentication (wallets no longer required in JWT)
+     */
+    async connect(token) {
+        if (this.state === 'connected' || this.state === 'connecting') {
+            this.log('Already connected or connecting');
+            return;
+        }
+        this.token = token;
+        this.setState('connecting');
+        return new Promise((resolve, reject) => {
+            // Connection timeout
+            const connectionTimeout = setTimeout(() => {
+                this.log('Connection timeout');
+                this.cleanup();
+                this.setState('error');
+                reject(new Error(`Connection timeout after ${this.config.connectionTimeout}ms`));
+            }, this.config.connectionTimeout);
+            const clearTimeoutAndResolve = () => {
+                clearTimeout(connectionTimeout);
+                resolve();
+            };
+            const clearTimeoutAndReject = (err) => {
+                clearTimeout(connectionTimeout);
+                reject(err);
+            };
+            try {
+                const url = new URL(this.config.wsUrl);
+                url.searchParams.set('token', token);
+                this.ws = new WebSocket(url.toString());
+                this.ws.onopen = () => {
+                    // Wait for server 'connected' message
+                };
+                this.ws.onmessage = (event) => {
+                    this.handleMessage(event.data, clearTimeoutAndResolve);
+                };
+                this.ws.onerror = (error) => {
+                    this.log('WebSocket error:', error);
+                    this.setState('error');
+                    clearTimeoutAndReject(new Error('Connection failed'));
+                };
+                this.ws.onclose = (event) => {
+                    this.log(`WebSocket closed: ${event.code} ${event.reason}`);
+                    // Only reject if we were still connecting
+                    if (this.state === 'connecting') {
+                        clearTimeoutAndReject(new Error(`Connection closed during handshake: ${event.code} ${event.reason}`));
+                    }
+                    this.handleDisconnect();
+                };
+            }
+            catch (err) {
+                this.log('Error creating WebSocket:', err);
+                this.setState('error');
+                clearTimeoutAndReject(err instanceof Error ? err : new Error(String(err)));
+            }
+        });
+    }
+    /**
+     * Disconnect from the server
+     */
+    disconnect() {
+        this.config.autoReconnect = false; // Prevent reconnect
+        this.cleanup();
+        this.setState('disconnected');
+    }
+    // ─────────────────────────────────────────────────────────────────────────────
+    // Subscription Methods (v1.2.0)
+    // ─────────────────────────────────────────────────────────────────────────────
+    /**
+     * Subscribe to wallet events (User SDK)
+     *
+     * Receives events only for the specified wallet addresses.
+     * Can be called multiple times to add more wallets.
+     *
+     * @param wallets - Array of wallet info (address + chainId)
+     * @returns Promise that resolves when subscription is confirmed
+     */
+    async subscribeWallets(wallets) {
+        return this.sendSubscription({ type: 'subscribe', wallets });
+    }
+    /**
+     * Subscribe to chain events (Admin Dashboard)
+     *
+     * Receives ALL events on the specified chains.
+     * Use for admin dashboards that need to monitor all activity.
+     *
+     * @param chains - Array of chain IDs to subscribe to
+     * @returns Promise that resolves when subscription is confirmed
+     */
+    async subscribeChains(chains) {
+        return this.sendSubscription({ type: 'subscribe', chains });
+    }
+    /**
+     * Unsubscribe from wallet events
+     *
+     * @param wallets - Array of wallet info to unsubscribe from
+     * @returns Promise that resolves when unsubscription is confirmed
+     */
+    async unsubscribeWallets(wallets) {
+        return this.sendSubscription({ type: 'unsubscribe', wallets });
+    }
+    /**
+     * Unsubscribe from chain events
+     *
+     * @param chains - Array of chain IDs to unsubscribe from
+     * @returns Promise that resolves when unsubscription is confirmed
+     */
+    async unsubscribeChains(chains) {
+        return this.sendSubscription({ type: 'unsubscribe', chains });
+    }
+    /**
+     * Get current subscription state
+     */
+    getSubscriptionState() {
+        return { ...this.subscriptionState };
+    }
+    // ─────────────────────────────────────────────────────────────────────────────
+    // Event Handlers
+    // ─────────────────────────────────────────────────────────────────────────────
+    /**
+     * Subscribe to blockchain events
+     * @param eventType - Event type to listen for, or '*' for all events
+     * @param handler - Event handler function
+     * @returns Unsubscribe function
+     */
+    on(eventType, handler) {
+        if (!this.handlers.has(eventType)) {
+            this.handlers.set(eventType, new Set());
+        }
+        this.handlers.get(eventType).add(handler);
+        return () => {
+            this.handlers.get(eventType)?.delete(handler);
+        };
+    }
+    /**
+     * Subscribe to connection state changes
+     */
+    onStateChange(handler) {
+        this.stateHandlers.add(handler);
+        return () => this.stateHandlers.delete(handler);
+    }
+    /**
+     * Get current connection state
+     */
+    getState() {
+        return this.state;
+    }
+    /**
+     * Get connection info (userId, initial wallets, activeChains)
+     */
+    getConnectionInfo() {
+        return this.connectionInfo;
+    }
+    // ─────────────────────────────────────────────────────────────────────────────
+    // Private methods
+    // ─────────────────────────────────────────────────────────────────────────────
+    async sendSubscription(message) {
+        if (this.state !== 'connected' || !this.ws) {
+            throw new Error('Not connected to server');
+        }
+        // Save subscriptions for reconnect
+        if (message.type === 'subscribe') {
+            if (message.wallets) {
+                this.savedSubscriptions.wallets = [
+                    ...this.savedSubscriptions.wallets,
+                    ...message.wallets.filter(w => !this.savedSubscriptions.wallets.some(sw => sw.address === w.address && sw.chainId === w.chainId))
+                ];
+            }
+            if (message.chains) {
+                this.savedSubscriptions.chains = [
+                    ...new Set([...this.savedSubscriptions.chains, ...message.chains])
+                ];
+            }
+        }
+        else if (message.type === 'unsubscribe') {
+            if (message.wallets) {
+                this.savedSubscriptions.wallets = this.savedSubscriptions.wallets.filter(sw => !message.wallets.some(w => w.address === sw.address && w.chainId === sw.chainId));
+            }
+            if (message.chains) {
+                this.savedSubscriptions.chains = this.savedSubscriptions.chains.filter(c => !message.chains.includes(c));
+            }
+        }
+        return new Promise((resolve, reject) => {
+            // Set up timeout
+            const timeout = setTimeout(() => {
+                this.pendingSubscription = null;
+                reject(new Error('Subscription timeout'));
+            }, 10000);
+            this.pendingSubscription = {
+                resolve: () => {
+                    clearTimeout(timeout);
+                    this.pendingSubscription = null;
+                    resolve(this.subscriptionState);
+                },
+                reject: (err) => {
+                    clearTimeout(timeout);
+                    this.pendingSubscription = null;
+                    reject(err);
+                }
+            };
+            this.ws.send(JSON.stringify(message));
+            this.log('Sent subscription message:', message);
+        });
+    }
+    handleMessage(data, onConnected) {
+        try {
+            const message = JSON.parse(data);
+            switch (message.type) {
+                case 'connected':
+                    this.connectionInfo = message.payload;
+                    this.reconnectAttempts = 0;
+                    this.setState('connected');
+                    this.log('Connected:', message.payload);
+                    onConnected?.();
+                    // Restore subscriptions on reconnect
+                    this.restoreSubscriptions();
+                    break;
+                case 'subscribed':
+                    this.subscriptionState = message.payload;
+                    this.log('Subscription confirmed:', message.payload);
+                    this.pendingSubscription?.resolve();
+                    break;
+                case 'unsubscribed':
+                    this.subscriptionState = message.payload;
+                    this.log('Unsubscription confirmed:', message.payload);
+                    this.pendingSubscription?.resolve();
+                    break;
+                case 'event':
+                    this.routeEvent(message.payload);
+                    break;
+                case 'ping':
+                    // Respond to server ping with pong
+                    this.sendPong();
+                    break;
+                case 'error':
+                    this.log('Server error:', message.payload);
+                    this.pendingSubscription?.reject(new Error(message.payload.message));
+                    break;
+            }
+        }
+        catch (err) {
+            this.log('Failed to parse message:', err);
+        }
+    }
+    sendPong() {
+        if (this.ws && this.ws.readyState === WebSocket.OPEN) {
+            this.ws.send(JSON.stringify({ type: 'pong' }));
+            this.log('Sent pong');
+        }
+    }
+    async restoreSubscriptions() {
+        // Restore wallet subscriptions
+        if (this.savedSubscriptions.wallets.length > 0) {
+            this.log('Restoring wallet subscriptions:', this.savedSubscriptions.wallets);
+            try {
+                await this.subscribeWallets(this.savedSubscriptions.wallets);
+            }
+            catch (err) {
+                this.log('Failed to restore wallet subscriptions:', err);
+            }
+        }
+        // Restore chain subscriptions
+        if (this.savedSubscriptions.chains.length > 0) {
+            this.log('Restoring chain subscriptions:', this.savedSubscriptions.chains);
+            try {
+                await this.subscribeChains(this.savedSubscriptions.chains);
+            }
+            catch (err) {
+                this.log('Failed to restore chain subscriptions:', err);
+            }
+        }
+    }
+    routeEvent(event) {
+        this.log('Event received:', event.type, event);
+        // Call specific type handlers
+        const typeHandlers = this.handlers.get(event.type);
+        typeHandlers?.forEach(handler => {
+            try {
+                handler(event);
+            }
+            catch (err) {
+                console.error('[PERS-Events] Handler error:', err);
+            }
+        });
+        // Call wildcard handlers
+        const wildcardHandlers = this.handlers.get('*');
+        wildcardHandlers?.forEach(handler => {
+            try {
+                handler(event);
+            }
+            catch (err) {
+                console.error('[PERS-Events] Handler error:', err);
+            }
+        });
+    }
+    handleDisconnect() {
+        this.cleanup();
+        this.setState('disconnected');
+        if (this.config.autoReconnect && this.token) {
+            if (this.reconnectAttempts < this.config.maxReconnectAttempts) {
+                this.attemptReconnect();
+            }
+            else {
+                this.log(`Max reconnect attempts (${this.config.maxReconnectAttempts}) reached. Call connect() manually to retry.`);
+                // Reset counter so manual connect() will work
+                this.reconnectAttempts = 0;
+            }
+        }
+    }
+    attemptReconnect() {
+        const delay = Math.min(this.config.reconnectDelay * Math.pow(2, this.reconnectAttempts), 30000 // Max 30 second delay
+        );
+        this.reconnectAttempts++;
+        this.log(`🔄 Reconnecting in ${delay}ms (attempt ${this.reconnectAttempts}/${this.config.maxReconnectAttempts})`);
+        this.setState('reconnecting');
+        this.reconnectTimeout = setTimeout(async () => {
+            try {
+                // Try to get fresh token if tokenRefresher is provided
+                let tokenToUse = this.token;
+                if (this.config.tokenRefresher) {
+                    try {
+                        this.log('🔄 Refreshing token before reconnect...');
+                        tokenToUse = await this.config.tokenRefresher();
+                        this.token = tokenToUse; // Update stored token
+                    }
+                    catch (refreshErr) {
+                        this.log('⚠️ Token refresh failed, using existing token:', refreshErr);
+                    }
+                }
+                if (tokenToUse) {
+                    this.log(`🔄 Attempting reconnection...`);
+                    await this.connect(tokenToUse);
+                }
+            }
+            catch (err) {
+                this.log('❌ Reconnect failed:', err);
+            }
+        }, delay);
+    }
+    cleanup() {
+        if (this.reconnectTimeout) {
+            clearTimeout(this.reconnectTimeout);
+            this.reconnectTimeout = null;
+        }
+        if (this.ws) {
+            this.ws.onopen = null;
+            this.ws.onmessage = null;
+            this.ws.onerror = null;
+            this.ws.onclose = null;
+            if (this.ws.readyState === WebSocket.OPEN) {
+                this.ws.close();
+            }
+            this.ws = null;
+        }
+    }
+    setState(state) {
+        if (this.state !== state) {
+            this.state = state;
+            this.stateHandlers.forEach(handler => handler(state));
+        }
+    }
+    log(...args) {
+        if (this.config.debug) {
+            console.log('[PERS-Events]', ...args);
+        }
+    }
+}
+/**
+ * Create a PERS Events client instance
+ */
+function createPersEventsClient(config) {
+    return new PersEventsClient(config);
+}
+
+/**
+ * Wallet Events Manager - Real-time blockchain events for user's wallets
+ *
+ * Provides automatic connection management and event routing integrated
+ * with the SDK's authentication flow and event system.
+ *
+ * Events are routed through the SDK's PersEventEmitter, so you can either:
+ * 1. Subscribe via `sdk.walletEvents.on()` for wallet-specific handling
+ * 2. Subscribe via `sdk.events.subscribe()` for unified event stream
+ *
+ * ## v1.2.0 - Subscription Model
+ *
+ * After connecting, you must explicitly subscribe to wallets or chains:
+ * - User SDK: `subscribeWallets([{ address, chainId }])`
+ * - Admin Dashboard: `subscribeChains([chainId1, chainId2])`
+ *
+ * For convenience, use `sdk.connectWalletEvents()` which auto-subscribes
+ * based on auth type.
+ *
+ * @example Manual subscription
+ * ```typescript
+ * await sdk.walletEvents.connect();
+ * await sdk.walletEvents.subscribeWallets([
+ *   { address: user.wallets[0].address, chainId: 39123 }
+ * ]);
+ *
+ * sdk.walletEvents.on('Transfer', (event) => {
+ *   console.log(`Received ${event.data.value} tokens`);
+ * });
+ * ```
+ *
+ * @example Auto-subscription (recommended)
+ * ```typescript
+ * // Auto-subscribes based on auth type (user/business/admin)
+ * await sdk.connectWalletEvents();
+ * ```
+ */
+/**
+ * Wallet Events Manager - Manages real-time blockchain event subscriptions
+ *
+ * Low-level WS client wrapper. For auto-subscription based on auth type,
+ * use `sdk.connectWalletEvents()` which handles subscription automatically.
+ */
+class WalletEventsManager {
+    constructor(apiClient, eventEmitter, config) {
+        this.apiClient = apiClient;
+        this.eventEmitter = eventEmitter;
+        this.client = null;
+        this.pendingHandlers = [];
+        this.unsubscribes = [];
+        this.config = {
+            autoReconnect: true,
+            connectionTimeout: 30000,
+            debug: false,
+            ...config,
+        };
+    }
+    /**
+     * Connect to real-time wallet events
+     *
+     * Establishes WebSocket connection to the WS relay server.
+     * After connecting, call subscribeWallets() or subscribeChains() to start
+     * receiving events.
+     *
+     * For auto-subscription, use `sdk.connectWalletEvents()` instead.
+     */
+    async connect() {
+        // Already connected?
+        if (this.client?.getState() === 'connected') {
+            return;
+        }
+        const sdkConfig = this.apiClient.getConfig();
+        const authProvider = sdkConfig.authProvider;
+        if (!authProvider) {
+            throw new Error('Not authenticated. Call sdk.auth.login() first.');
+        }
+        const token = await authProvider.getToken();
+        if (!token) {
+            throw new Error('No authentication token available. Call sdk.auth.login() first.');
+        }
+        // Resolve wsUrl: config override > SDK config > environment default
+        const wsUrl = this.config.wsUrl
+            || sdkConfig.walletEventsWsUrl
+            || buildWalletEventsWsUrl(sdkConfig.environment);
+        // Create token refresher that fetches fresh token from auth provider
+        const tokenRefresher = async () => {
+            const freshToken = await authProvider.getToken();
+            if (!freshToken) {
+                throw new Error('Failed to refresh token');
+            }
+            return freshToken;
+        };
+        this.client = new PersEventsClient({
+            wsUrl,
+            autoReconnect: this.config.autoReconnect,
+            connectionTimeout: this.config.connectionTimeout,
+            debug: this.config.debug,
+            tokenRefresher,
+        });
+        await this.client.connect(token);
+        // Clear previous unsubscribes on new connection (prevent memory leak)
+        this.unsubscribes.forEach(unsub => unsub());
+        this.unsubscribes = [];
+        // Route all events through PersEventEmitter for unified stream
+        // Note: Cast needed because web3-types uses string for event.type while pers-shared uses strict union
+        this.client.on('*', (event) => this.emitToPersEvents(event));
+        // Re-attach any handlers registered before connect
+        for (const { type, handler } of this.pendingHandlers) {
+            this.unsubscribes.push(this.client.on(type, handler));
+        }
+        this.pendingHandlers = [];
+    }
+    /**
+     * Disconnect from real-time events
+     */
+    disconnect() {
+        this.unsubscribes.forEach(unsub => unsub());
+        this.unsubscribes = [];
+        this.client?.disconnect();
+        this.client = null;
+    }
+    // ─────────────────────────────────────────────────────────────────────────────
+    // Subscription Methods (v1.2.0)
+    // ─────────────────────────────────────────────────────────────────────────────
+    /**
+     * Subscribe to wallet events
+     *
+     * Receives events only for the specified wallet addresses.
+     * Use this for user-facing SDK where you want to monitor specific wallets.
+     *
+     * @param wallets - Array of wallet info (address + chainId)
+     * @returns Promise that resolves when subscription is confirmed
+     *
+     * @example
+     * ```typescript
+     * await sdk.walletEvents.connect();
+     * await sdk.walletEvents.subscribeWallets([
+     *   { address: '0x123...', chainId: 39123 }
+     * ]);
+     * ```
+     */
+    async subscribeWallets(wallets) {
+        if (!this.client) {
+            throw new Error('Not connected. Call connect() first.');
+        }
+        return this.client.subscribeWallets(wallets);
+    }
+    /**
+     * Subscribe to chain events (Admin Dashboard)
+     *
+     * Receives ALL events on the specified chains.
+     * Use for admin dashboards that need to monitor all activity.
+     *
+     * @param chains - Array of chain IDs to subscribe to
+     * @returns Promise that resolves when subscription is confirmed
+     *
+     * @example
+     * ```typescript
+     * await sdk.walletEvents.connect();
+     * await sdk.walletEvents.subscribeChains([39123, 137]);
+     * ```
+     */
+    async subscribeChains(chains) {
+        if (!this.client) {
+            throw new Error('Not connected. Call connect() first.');
+        }
+        return this.client.subscribeChains(chains);
+    }
+    /**
+     * Unsubscribe from wallet events
+     *
+     * @param wallets - Array of wallet info to unsubscribe from
+     * @returns Promise that resolves when unsubscription is confirmed
+     */
+    async unsubscribeWallets(wallets) {
+        if (!this.client) {
+            throw new Error('Not connected. Call connect() first.');
+        }
+        return this.client.unsubscribeWallets(wallets);
+    }
+    /**
+     * Unsubscribe from chain events
+     *
+     * @param chains - Array of chain IDs to unsubscribe from
+     * @returns Promise that resolves when unsubscription is confirmed
+     */
+    async unsubscribeChains(chains) {
+        if (!this.client) {
+            throw new Error('Not connected. Call connect() first.');
+        }
+        return this.client.unsubscribeChains(chains);
+    }
+    /**
+     * Get current subscription state
+     */
+    getSubscriptionState() {
+        return this.client?.getSubscriptionState() ?? { wallets: [], chains: [], activeChains: [] };
+    }
+    // ─────────────────────────────────────────────────────────────────────────────
+    // Event Handlers
+    // ─────────────────────────────────────────────────────────────────────────────
+    /**
+     * Subscribe to blockchain events
+     *
+     * @param eventType - Event type ('Transfer', 'Approval', etc.) or '*' for all
+     * @param handler - Callback function when event is received
+     * @returns Unsubscribe function
+     *
+     * @example
+     * ```typescript
+     * const unsub = sdk.walletEvents.on('Transfer', (event) => {
+     *   console.log(`Transfer: ${event.data.from} -> ${event.data.to}`);
+     * });
+     *
+     * // Later: stop listening
+     * unsub();
+     * ```
+     */
+    on(eventType, handler) {
+        if (this.client) {
+            const unsub = this.client.on(eventType, handler);
+            this.unsubscribes.push(unsub);
+            return unsub;
+        }
+        else {
+            // Store for when connect() is called
+            this.pendingHandlers.push({ type: eventType, handler });
+            return () => {
+                const idx = this.pendingHandlers.findIndex(h => h.handler === handler);
+                if (idx !== -1)
+                    this.pendingHandlers.splice(idx, 1);
+            };
+        }
+    }
+    /**
+     * Subscribe to connection state changes
+     */
+    onStateChange(handler) {
+        if (this.client) {
+            return this.client.onStateChange(handler);
+        }
+        return () => { };
+    }
+    /**
+     * Get current connection state
+     */
+    getState() {
+        return this.client?.getState() ?? 'disconnected';
+    }
+    /**
+     * Check if connected
+     */
+    isConnected() {
+        return this.getState() === 'connected';
+    }
+    /**
+     * Get connection info (wallets, active chains)
+     */
+    getConnectionInfo() {
+        return this.client?.getConnectionInfo();
+    }
+    // ─────────────────────────────────────────────────────────────────────────────
+    // Private Methods
+    // ─────────────────────────────────────────────────────────────────────────────
+    /**
+     * Build a descriptive message for blockchain events
+     * Neutral tone - frontend will handle user-facing presentation
+     */
+    buildUserMessage(event) {
+        const { type, data } = event;
+        // Use string for switch since event types may extend beyond strict BlockchainEventType union
+        const eventType = type;
+        const from = data.from?.toLowerCase();
+        const to = data.to?.toLowerCase();
+        const shortFrom = from ? `${from.slice(0, 6)}...${from.slice(-4)}` : 'unknown';
+        const shortTo = to ? `${to.slice(0, 6)}...${to.slice(-4)}` : 'unknown';
+        // Get user's wallets to determine direction
+        const subscriptionState = this.getSubscriptionState();
+        const userWallets = subscriptionState.wallets.map(w => w.address.toLowerCase());
+        const isIncoming = to && userWallets.includes(to);
+        const isOutgoing = from && userWallets.includes(from);
+        const isMint = from === '0x0000000000000000000000000000000000000000';
+        const isBurn = to === '0x0000000000000000000000000000000000000000';
+        switch (eventType) {
+            case 'Transfer':
+                if (isMint) {
+                    return `Token minted to ${shortTo}`;
+                }
+                else if (isBurn) {
+                    return `Token burned from ${shortFrom}`;
+                }
+                else if (isIncoming) {
+                    return `Transfer received from ${shortFrom}`;
+                }
+                else if (isOutgoing) {
+                    return `Transfer sent to ${shortTo}`;
+                }
+                return `Transfer from ${shortFrom} to ${shortTo}`;
+            case 'Approval':
+                return `Approval from ${shortFrom}`;
+            case 'SmartWalletCreated':
+                return `Smart wallet created: ${shortTo}`;
+            case 'TransactionExecuted':
+                return `Transaction executed by ${shortFrom}`;
+            case 'OwnershipTransferred':
+                return `Ownership transferred from ${shortFrom} to ${shortTo}`;
+            default:
+                return `${eventType} event`;
+        }
+    }
+    /**
+     * Route blockchain event to PersEventEmitter for unified event stream
+     */
+    emitToPersEvents(event) {
+        const userMessage = this.buildUserMessage(event);
+        this.eventEmitter.emitSuccess({
+            type: `wallet_${event.type.toLowerCase()}`,
+            domain: 'wallet',
+            userMessage,
+            details: {
+                chainId: event.chainId,
+                txHash: event.txHash,
+                blockNumber: event.blockNumber,
+                timestamp: event.timestamp,
+                contractAddress: event.contractAddress,
+                ...event.data,
+            },
+        });
+    }
+}
+
+/**
+ * @fileoverview PERS SDK - Platform-agnostic TypeScript SDK with High-Level Managers
+ *
+ * @module @explorins/pers-sdk
+ * @version 1.6.4
+ * @author Explorins
+ * @license MIT
+ */
+/**
+ * PERS SDK - Main SDK class with domain managers
+ *
+ * Main SDK interface providing clean, high-level managers for common operations
+ * while maintaining full access to the underlying API client and domain services.
+ *
+ * The SDK follows a layered architecture:
+ * - **Managers**: High-level, intuitive APIs for common operations
+ * - **Domain Services**: Full-featured access for advanced use cases
+ * - **API Client**: Direct REST API access for custom operations
+ *
+ * @group Core
+ * @category SDK
+ *
+ * @example Basic Setup
+ * ```typescript
+ * import { PersSDK } from '@explorins/pers-sdk';
+ * import { BrowserFetchClientAdapter } from '@explorins/pers-sdk/platform-adapters';
+ *
+ * const sdk = new PersSDK(new BrowserFetchClientAdapter(), {
+ *   environment: 'production',
+ *   apiProjectKey: 'your-project-key'
+ * });
+ * ```
+ *
+ * @example Authentication Flow
+ * ```typescript
+ * // Login with external JWT
+ * await sdk.auth.loginWithToken(firebaseJWT, 'user');
+ *
+ * // Check authentication
+ * if (await sdk.auth.isAuthenticated()) {
+ *   const user = await sdk.auth.getCurrentUser();
+ *   console.log('Welcome,', user.name);
+ * }
+ * ```
+ *
+ * @example Business Operations
+ * ```typescript
+ * // Get active businesses
+ * const businesses = await sdk.businesses.getActiveBusinesses();
+ *
+ * // Get business details
+ * const business = await sdk.businesses.getBusinessById(businessId);
+ * ```
+ *
+ * @example Token Operations
+ * ```typescript
+ * // Get user's token balances
+ * const tokens = await sdk.tokens.getTokens();
+ *
+ * // Get active credit token
+ * const creditToken = await sdk.tokens.getActiveCreditToken();
+ * ```
+ *
+ * @since 1.3.0 - Manager pattern architecture
+ */
+class PersSDK {
+    /**
+     * Creates a new PERS SDK instance
+     *
+     * Initializes all domain managers and sets up the API client with the provided
+     * HTTP client adapter and configuration.
+     *
+     * @param httpClient - Platform-specific HTTP client implementation
+     * @param config - SDK configuration options
+     *
+     * @example Browser Setup
+     * ```typescript
+     * import { BrowserFetchClientAdapter } from '@explorins/pers-sdk/platform-adapters';
+     *
+     * const sdk = new PersSDK(new BrowserFetchClientAdapter(), {
+     *   environment: 'production',
+     *   apiProjectKey: 'your-project-key'
+     * });
+     * ```
+     *
+     * @example Node.js Setup
+     * ```typescript
+     * import { NodeHttpClientAdapter } from '@explorins/pers-sdk/platform-adapters';
+     *
+     * const sdk = new PersSDK(new NodeHttpClientAdapter(), {
+     *   environment: 'production',
+     *   apiProjectKey: 'your-project-key',
+     *   baseUrl: 'https://api.yourpers.com'
+     * });
+     * ```
+     *
+     * @example Angular Setup
      * ```typescript
      * import { AngularHttpClientAdapter } from '@explorins/pers-sdk/platform-adapters';
      *
@@ -7509,6 +8855,81 @@ class PersSDK {
         // Initialize event emitter and wire to API client for error events
         this._events = new PersEventEmitter();
         this.apiClient.setEvents(this._events);
+        // Auto-connect to wallet events on successful login (if enabled)
+        this.setupWalletEventsAutoConnect();
+    }
+    /**
+     * Setup auto-connect for wallet events on authentication
+     * @internal
+     */
+    setupWalletEventsAutoConnect() {
+        const config = this.apiClient.getConfig();
+        // Check if captureWalletEvents is enabled (default: true)
+        if (config.captureWalletEvents === false) {
+            return;
+        }
+        // Listen for login success events (both fresh login and session restoration)
+        this._events.subscribe((event) => {
+            if (event.level === 'success' && (event.type === 'LOGIN_SUCCESS' || event.type === 'session_restored')) {
+                // Auto-connect and subscribe to wallet events (fire and forget, log errors)
+                this.connectWalletEvents().catch((err) => {
+                    console.warn('[PersSDK] Failed to auto-connect wallet events:', err.message);
+                });
+            }
+            // Disconnect on logout
+            if (event.level === 'success' && event.type === 'logout_success') {
+                this.walletEvents.disconnect();
+            }
+        });
+    }
+    /**
+     * Connect to wallet events and auto-subscribe based on auth type
+     *
+     * Connects to the WebSocket relay and automatically subscribes to relevant
+     * blockchain events based on the current authentication type:
+     * - **USER**: Subscribes to all user's wallets
+     * - **BUSINESS**: Subscribes to all business's wallets
+     * - **TENANT**: Subscribes to all chains where tokens are deployed
+     *
+     * This method is called automatically on login when `captureWalletEvents` is enabled.
+     * Call manually if you need to reconnect or refresh subscriptions.
+     *
+     * @example Manual connection
+     * ```typescript
+     * await sdk.connectWalletEvents();
+     * ```
+     */
+    async connectWalletEvents() {
+        await this.walletEvents.connect();
+        // Get authType from auth provider (where it's stored during login)
+        const authProvider = this.apiClient.getConfig().authProvider;
+        const authType = authProvider?.getAuthType ? await authProvider.getAuthType() : undefined;
+        switch (authType) {
+            case persShared.AccountOwnerType.USER: {
+                const user = await this.users.getCurrentUser();
+                const wallets = user.wallets?.map(w => ({ address: w.address, chainId: w.chainId })) || [];
+                if (wallets.length > 0) {
+                    await this.walletEvents.subscribeWallets(wallets);
+                }
+                break;
+            }
+            case persShared.AccountOwnerType.BUSINESS: {
+                const business = await this.auth.getCurrentBusiness();
+                const wallets = business.wallets?.map(w => ({ address: w.address, chainId: w.chainId })) || [];
+                if (wallets.length > 0) {
+                    await this.walletEvents.subscribeWallets(wallets);
+                }
+                break;
+            }
+            case persShared.AccountOwnerType.TENANT: {
+                const tokens = await this.tokens.getTokens();
+                const chains = [...new Set(tokens.data.map(t => t.chainId))];
+                if (chains.length > 0) {
+                    await this.walletEvents.subscribeChains(chains);
+                }
+                break;
+            }
+        }
     }
     /**
      * Restore user session from stored tokens
@@ -7823,7 +9244,7 @@ class PersSDK {
      */
     get tenants() {
         if (!this._tenants) {
-            this._tenants = new TenantManager(this.apiClient);
+            this._tenants = new tenantManager.TenantManager(this.apiClient);
         }
         return this._tenants;
     }
@@ -7916,6 +9337,103 @@ class PersSDK {
         }
         return this._triggerSources;
     }
+    /**
+     * Webhook manager - High-level webhook operations
+     *
+     * Provides methods for creating webhooks, triggering them programmatically,
+     * and monitoring execution history. Supports async workflows with callbacks.
+     *
+     * @returns WebhookManager instance
+     *
+     * @example Webhook Operations
+     * ```typescript
+     * // Admin: Create a webhook
+     * const webhook = await sdk.webhooks.create({
+     *   name: 'Order Processing',
+     *   targetUrl: 'https://n8n.example.com/webhook/orders',
+     *   method: 'POST'
+     * });
+     *
+     * // Trigger webhook with payload
+     * const result = await sdk.webhooks.trigger(webhook.id, {
+     *   orderId: 'order-123',
+     *   action: 'created'
+     * });
+     *
+     * // Trigger and wait for async workflow completion
+     * const asyncResult = await sdk.webhooks.triggerAndWait(
+     *   'ai-webhook',
+     *   { prompt: 'Analyze this data' },
+     *   30000  // Wait up to 30s
+     * );
+     * ```
+     *
+     * @see {@link WebhookManager} for detailed documentation
+     */
+    get webhooks() {
+        if (!this._webhooks) {
+            const projectKey = this.apiClient.getConfig().apiProjectKey || '';
+            this._webhooks = new WebhookManager(this.apiClient, projectKey, this._events);
+        }
+        return this._webhooks;
+    }
+    /**
+     * Wallet Events Manager - Real-time blockchain events for user's wallets
+     *
+     * Provides real-time WebSocket connection to receive blockchain events
+     * for the user's wallets (transfers, approvals, NFT mints, etc.).
+     *
+     * Events are also routed through `sdk.events` for unified event handling.
+     *
+     * **Important:** Requires `walletEventsWsUrl` configuration and authentication.
+     *
+     * @returns WalletEventsManager instance
+     *
+     * @example Basic Usage
+     * ```typescript
+     * // Configure SDK with events URL
+     * sdk.configureWalletEvents({ wsUrl: 'wss://events.pers.ninja' });
+     *
+     * // Connect after authentication
+     * await sdk.auth.loginWithToken(jwt, 'user');
+     * await sdk.walletEvents.connect();
+     *
+     * // Listen for token transfers
+     * sdk.walletEvents.on('Transfer', (event) => {
+     *   if (event.data.to === myWallet) {
+     *     showNotification(`Received ${event.data.value} tokens!`);
+     *   }
+     * });
+     * ```
+     *
+     * @example Unified Event Stream
+     * ```typescript
+     * // Wallet events also flow through sdk.events
+     * sdk.events.subscribe((event) => {
+     *   if (event.domain === 'wallet') {
+     *     console.log('Wallet event:', event.type);
+     *   }
+     * });
+     * ```
+     *
+     * @see {@link WalletEventsManager} for detailed documentation
+     */
+    get walletEvents() {
+        if (!this._walletEvents) {
+            this._walletEvents = new WalletEventsManager(this.apiClient, this._events, this.walletEventsConfig);
+        }
+        return this._walletEvents;
+    }
+    /**
+     * Configure wallet events (call before accessing walletEvents)
+     *
+     * @param config - Events configuration including wsUrl
+     */
+    configureWalletEvents(config) {
+        this.walletEventsConfig = config;
+        // Reset manager so it picks up new config
+        this._walletEvents = undefined;
+    }
     /**
      * Gets the API client for direct PERS API requests
      *
@@ -7987,6 +9505,7 @@ exports.LocalStorageTokenStorage = LocalStorageTokenStorage;
 exports.MemoryTokenStorage = MemoryTokenStorage;
 exports.PersApiClient = PersApiClient;
 exports.PersEventEmitter = PersEventEmitter;
+exports.PersEventsClient = PersEventsClient;
 exports.PersSDK = PersSDK;
 exports.PurchaseManager = PurchaseManager;
 exports.RedemptionManager = RedemptionManager;
@@ -7994,14 +9513,19 @@ exports.SDK_NAME = SDK_NAME;
 exports.SDK_USER_AGENT = SDK_USER_AGENT;
 exports.SDK_VERSION = SDK_VERSION;
 exports.StaticJwtAuthProvider = StaticJwtAuthProvider;
-exports.TenantManager = TenantManager;
 exports.TokenManager = TokenManager;
 exports.TransactionManager = TransactionManager;
 exports.TriggerSourceManager = TriggerSourceManager;
 exports.UserManager = UserManager;
 exports.UserStatusManager = UserStatusManager;
+exports.WalletEventsManager = WalletEventsManager;
 exports.WebDPoPCryptoProvider = WebDPoPCryptoProvider;
+exports.WebhookApi = WebhookApi;
+exports.WebhookManager = WebhookManager;
+exports.WebhookService = WebhookService;
 exports.buildApiRoot = buildApiRoot;
+exports.buildWalletEventsWsUrl = buildWalletEventsWsUrl;
+exports.createPersEventsClient = createPersEventsClient;
 exports.createPersSDK = createPersSDK;
 exports.mergeWithDefaults = mergeWithDefaults;
-//# sourceMappingURL=pers-sdk-Co-R9M1O.cjs.map
+//# sourceMappingURL=pers-sdk-Cv7hM1I7.cjs.map