@explorins/pers-sdk 2.1.11 → 2.1.15

package/dist/chunks/{pers-sdk-CJo4CCTG.js → pers-sdk-BiP7UMJ3.js}

@@ -1,14 +1,14 @@
-import { AccountOwnerType, MembershipRole } from '@explorins/pers-shared';
-import { i as isTokenExpired, E as ErrorUtils, A as AuthenticationError, a as PersApiError } from './index-CKm_V5XE.js';
+import { AccountOwnerType, MembershipRole, WebhookMethod, WebhookExecutionStatus } from '@explorins/pers-shared';
+import { i as isTokenExpired, E as ErrorUtils, A as AuthenticationError, b as PersApiError } from './index-DgTEdUgC.js';
 import { UserService, UserApi } from '../user.js';
 import { createUserStatusSDK } from '../user-status.js';
 import { a as TokenService, T as TokenApi } from './token-service-BxEO5YVN.js';
 import { B as BusinessApi, b as BusinessService, a as BusinessMembershipApi, c as BusinessMembershipService } from './business-membership-service-CFa-TI39.js';
 import { CampaignService, CampaignApi } from '../campaign.js';
 import { a as RedemptionService, R as RedemptionApi } from './redemption-service-C_UTTDag.js';
-import { a as TransactionService, T as TransactionApi } from './transaction-request.builder-DGTxGvc3.js';
+import { a as TransactionService, T as TransactionApi } from './transaction-request.builder-C3C19kCx.js';
 import { a as PaymentService, P as PurchaseApi } from './payment-service-IvM6rryM.js';
-import { a as TenantService, T as TenantApi } from './tenant-service-CsRA3O2V.js';
+import { T as TenantManager } from './tenant-manager-Bbj0bKoo.js';
 import { b as buildPaginationParams, n as normalizeToPaginated } from './pagination-utils-9vQ-Npkr.js';
 import { a as AnalyticsService, A as AnalyticsApi } from './analytics-service-vm7B7LhS.js';
 import { DonationService, DonationApi } from '../donation.js';
@@ -29,7 +29,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
@@ -51,6 +52,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
  */
@@ -1411,7 +1427,6 @@ class PersEventEmitter {
     constructor() {
         this.handlers = new Set();
         this._instanceId = ++emitterInstanceCounter;
-        console.log(`[PersEventEmitter] Instance #${this._instanceId} created`);
     }
     get instanceId() {
         return this._instanceId;
@@ -6380,89 +6395,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 TenantApi(apiClient);
-        this.tenantService = new 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
  *
@@ -7398,125 +7330,1611 @@ 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: WebhookMethod.POST,
+            body
+        }, this.projectKey);
+    }
+    /**
+     * Simple GET trigger
+     */
+    async get(hookId, queryParams) {
+        return this.webhookApi.triggerWebhook({
+            hookId,
+            method: 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: 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: 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';
-     *
-     * const sdk = new PersSDK(new BrowserFetchClientAdapter(), {
-     *   environment: 'production',
-     *   apiProjectKey: 'your-project-key'
-     * });
-     * ```
+     * // Get all webhooks
+     * const webhooks = await sdk.webhooks.getAll();
      *
-     * @example Node.js Setup
-     * ```typescript
-     * import { NodeHttpClientAdapter } from '@explorins/pers-sdk/platform-adapters';
+     * // Get only active webhooks
+     * const active = await sdk.webhooks.getAll({ active: true });
      *
-     * const sdk = new PersSDK(new NodeHttpClientAdapter(), {
-     *   environment: 'production',
-     *   apiProjectKey: 'your-project-key',
-     *   baseUrl: 'https://api.yourpers.com'
-     * });
+     * // 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 Angular Setup
-     * ```typescript
-     * import { AngularHttpClientAdapter } from '@explorins/pers-sdk/platform-adapters';
-     *
-     * constructor(private http: HttpClient) {
-     *   this.sdk = new PersSDK(new AngularHttpClientAdapter(this.http), {
-     *     environment: 'production',
-     *     apiProjectKey: 'your-project-key'
-     *   });
-     * }
-     * ```
+     * @param webhookId - UUID of the webhook
+     * @returns Promise resolving to webhook details
      */
-    constructor(httpClient, config) {
-        this.apiClient = new PersApiClient(httpClient, config);
-        // Initialize event emitter and wire to API client for error events
-        this._events = new PersEventEmitter();
-        this.apiClient.setEvents(this._events);
+    async getById(webhookId) {
+        return this.webhookService.getWebhookById(webhookId);
     }
     /**
-     * Restore user session from stored tokens
+     * Create a new webhook (Admin)
      *
-     * Call this method after SDK initialization to restore the user's session
-     * if valid tokens exist. This is useful for maintaining login state across
-     * app restarts.
+     * @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)
+     *
+     * @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';
+     *
+     * constructor(private http: HttpClient) {
+     *   this.sdk = new PersSDK(new AngularHttpClientAdapter(this.http), {
+     *     environment: 'production',
+     *     apiProjectKey: 'your-project-key'
+     *   });
+     * }
+     * ```
+     */
+    constructor(httpClient, config) {
+        this.apiClient = new PersApiClient(httpClient, config);
+        // 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 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 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 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
+     *
+     * Call this method after SDK initialization to restore the user's session
+     * if valid tokens exist. This is useful for maintaining login state across
+     * app restarts.
      *
      * **Important:** Only works for USER and BUSINESS accounts. Admin/tenant
      * accounts don't support user data fetching, so this will return null for them
@@ -7917,6 +9335,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
      *
@@ -7966,5 +9481,5 @@ function createPersSDK(httpClient, config) {
     return new PersSDK(httpClient, config);
 }
 
-export { AuthStatus as A, BusinessManager as B, CampaignManager as C, DefaultAuthProvider as D, ApiKeyApi as E, FileManager as F, LocalStorageTokenStorage as L, MemoryTokenStorage as M, PersSDK as P, RedemptionManager as R, SDK_NAME as S, TokenManager as T, UserManager as U, WebDPoPCryptoProvider as W, AuthTokenManager as a, AUTH_STORAGE_KEYS as b, createPersSDK as c, DPOP_STORAGE_KEYS as d, SDK_VERSION as e, SDK_USER_AGENT as f, PersApiClient as g, DEFAULT_PERS_CONFIG as h, buildApiRoot as i, StaticJwtAuthProvider as j, AuthApi as k, AuthService as l, mergeWithDefaults as m, DPoPManager as n, PersEventEmitter as o, AuthManager as p, UserStatusManager as q, TransactionManager as r, PurchaseManager as s, TenantManager as t, ApiKeyManager as u, AnalyticsManager as v, DonationManager as w, TriggerSourceManager as x, FileApi as y, FileService as z };
-//# sourceMappingURL=pers-sdk-CJo4CCTG.js.map
+export { AuthStatus as A, BusinessManager as B, CampaignManager as C, DefaultAuthProvider as D, FileApi as E, FileManager as F, FileService as G, ApiKeyApi as H, WebhookApi as I, WebhookService as J, PersEventsClient as K, LocalStorageTokenStorage as L, MemoryTokenStorage as M, createPersEventsClient as N, PersSDK as P, RedemptionManager as R, SDK_NAME as S, TokenManager as T, UserManager as U, WebDPoPCryptoProvider as W, AuthTokenManager as a, AUTH_STORAGE_KEYS as b, createPersSDK as c, DPOP_STORAGE_KEYS as d, SDK_VERSION as e, SDK_USER_AGENT as f, PersApiClient as g, DEFAULT_PERS_CONFIG as h, buildApiRoot as i, buildWalletEventsWsUrl as j, StaticJwtAuthProvider as k, AuthApi as l, mergeWithDefaults as m, AuthService as n, DPoPManager as o, PersEventEmitter as p, AuthManager as q, UserStatusManager as r, TransactionManager as s, PurchaseManager as t, ApiKeyManager as u, AnalyticsManager as v, DonationManager as w, TriggerSourceManager as x, WebhookManager as y, WalletEventsManager as z };
+//# sourceMappingURL=pers-sdk-BiP7UMJ3.js.map