@clianta/sdk 1.7.2 → 1.7.3

package/dist/clianta.umd.js

@@ -1,5 +1,5 @@
 /*!
- * Clianta SDK v1.7.2
+ * Clianta SDK v1.7.3
  * (c) 2026 Clianta
  * Released under the MIT License.
  */
@@ -226,8 +226,9 @@
         /**
          * Send identify request.
          * Returns contactId from the server response so the Tracker can store it.
+         * Retries on 5xx with exponential backoff (same policy as sendEvents).
          */
-        async sendIdentify(data) {
+        async sendIdentify(data, attempt = 1) {
             const url = `${this.config.apiEndpoint}/api/public/track/identify`;
             try {
                 const response = await this.fetchWithTimeout(url, {
@@ -245,16 +246,26 @@
                         contactId: body.contactId ?? undefined,
                     };
                 }
-                if (response.status >= 500) {
-                    logger.warn(`Identify server error (${response.status})`);
-                }
-                else {
-                    logger.error(`Identify failed with status ${response.status}:`, body.message);
+                // Server error — retry with exponential backoff
+                if (response.status >= 500 && attempt < this.config.maxRetries) {
+                    const backoff = this.config.retryDelay * Math.pow(2, attempt - 1);
+                    logger.warn(`Identify server error (${response.status}), retrying in ${backoff}ms...`);
+                    await this.delay(backoff);
+                    return this.sendIdentify(data, attempt + 1);
                 }
+                logger.error(`Identify failed with status ${response.status}:`, body.message);
                 return { success: false, status: response.status };
             }
             catch (error) {
-                logger.error('Identify request failed:', error);
+                // Network error — retry if still online
+                const isOnline = typeof navigator === 'undefined' || navigator.onLine;
+                if (isOnline && attempt < this.config.maxRetries) {
+                    const backoff = this.config.retryDelay * Math.pow(2, attempt - 1);
+                    logger.warn(`Identify network error, retrying in ${backoff}ms (${attempt}/${this.config.maxRetries})...`);
+                    await this.delay(backoff);
+                    return this.sendIdentify(data, attempt + 1);
+                }
+                logger.error('Identify request failed after retries:', error);
                 return { success: false, error: error };
             }
         }
@@ -572,9 +583,6 @@
             // Ignore
         }
     }
-    // ============================================
-    // URL UTILITIES
-    // ============================================
     /**
      * Extract UTM parameters from URL
      */
@@ -731,8 +739,9 @@
                 flushInterval: config.flushInterval ?? 5000,
                 maxQueueSize: config.maxQueueSize ?? MAX_QUEUE_SIZE,
                 storageKey: config.storageKey ?? STORAGE_KEYS.EVENT_QUEUE,
+                persistMode: config.persistMode ?? 'session',
             };
-            this.persistMode = config.persistMode || 'session';
+            this.persistMode = this.config.persistMode;
             this.isOnline = typeof navigator === 'undefined' || navigator.onLine;
             // Restore persisted queue
             this.restoreQueue();
@@ -796,9 +805,11 @@
                 // Send to backend
                 const result = await this.transport.sendEvents(events);
                 if (!result.success) {
-                    // Re-queue events on failure (at the front)
+                    // Re-queue events on failure (at the front), capped at maxQueueSize
                     logger.warn('Flush failed, re-queuing events');
-                    this.queue.unshift(...events);
+                    const availableSpace = this.config.maxQueueSize - this.queue.length;
+                    const eventsToRequeue = events.slice(0, Math.max(0, availableSpace));
+                    this.queue.unshift(...eventsToRequeue);
                     this.persistQueue(this.queue);
                 }
                 else {
@@ -1245,7 +1256,7 @@
             if (this.trackedForms.has(form))
                 return;
             this.trackedForms.add(form);
-            const formId = form.id || form.name || `form-${Math.random().toString(36).substr(2, 9)}`;
+            const formId = form.id || form.name || `form-${Math.random().toString(36).substring(2, 11)}`;
             // Track form view
             this.track('form_view', 'Form Viewed', {
                 formId,
@@ -1889,27 +1900,22 @@
             super.destroy();
         }
         loadShownForms() {
-            try {
-                const stored = localStorage.getItem('clianta_shown_forms');
-                if (stored) {
+            const stored = getLocalStorage('clianta_shown_forms');
+            if (stored) {
+                try {
                     const data = JSON.parse(stored);
                     this.shownForms = new Set(data.forms || []);
                 }
-            }
-            catch (e) {
-                // Ignore storage errors
+                catch {
+                    // Ignore parse errors
+                }
             }
         }
         saveShownForms() {
-            try {
-                localStorage.setItem('clianta_shown_forms', JSON.stringify({
-                    forms: Array.from(this.shownForms),
-                    timestamp: Date.now(),
-                }));
-            }
-            catch (e) {
-                // Ignore storage errors
-            }
+            setLocalStorage('clianta_shown_forms', JSON.stringify({
+                forms: Array.from(this.shownForms),
+                timestamp: Date.now(),
+            }));
         }
         async fetchForms() {
             if (!this.tracker)
@@ -1928,7 +1934,7 @@
                 }
             }
             catch (error) {
-                console.error('[Clianta] Failed to fetch forms:', error);
+                logger.error('Failed to fetch popup forms:', error);
             }
         }
         shouldShowForm(form) {
@@ -1939,7 +1945,7 @@
             }
             else if (form.showFrequency === 'once_per_session') {
                 const sessionKey = `clianta_form_${form._id}_shown`;
-                if (sessionStorage.getItem(sessionKey))
+                if (getSessionStorage(sessionKey))
                     return false;
             }
             return true;
@@ -2011,7 +2017,7 @@
             // Mark as shown
             this.shownForms.add(form._id);
             this.saveShownForms();
-            sessionStorage.setItem(`clianta_form_${form._id}_shown`, 'true');
+            setSessionStorage(`clianta_form_${form._id}_shown`, 'true');
             // Track view
             await this.trackFormView(form._id);
             // Render form
@@ -2327,17 +2333,17 @@
                             const redirect = new URL(form.redirectUrl, window.location.origin);
                             const isSameOrigin = redirect.origin === window.location.origin;
                             const isSafeProtocol = redirect.protocol === 'https:' || redirect.protocol === 'http:';
-                            if (isSameOrigin || isSafeProtocol) {
+                            if (isSameOrigin && isSafeProtocol) {
                                 setTimeout(() => {
                                     window.location.href = redirect.href;
                                 }, 1500);
                             }
                             else {
-                                console.warn('[Clianta] Blocked unsafe redirect URL:', form.redirectUrl);
+                                logger.warn('Blocked unsafe redirect URL:', form.redirectUrl);
                             }
                         }
                         catch {
-                            console.warn('[Clianta] Invalid redirect URL:', form.redirectUrl);
+                            logger.warn('Invalid redirect URL:', form.redirectUrl);
                         }
                     }
                     // Close after delay
@@ -2350,7 +2356,7 @@
                 }
             }
             catch (error) {
-                console.error('[Clianta] Form submit error:', error);
+                logger.error('Form submit error:', error);
                 if (submitBtn) {
                     submitBtn.disabled = false;
                     submitBtn.textContent = form.submitButtonText || 'Subscribe';
@@ -2421,7 +2427,7 @@
         'token', 'jwt', 'auth', 'user', 'session', 'credential', 'account',
     ];
     /** JWT/user object fields containing email */
-    const EMAIL_CLAIMS = ['email', 'sub', 'preferred_username', 'user_email', 'mail', 'emailAddress', 'e_mail'];
+    const EMAIL_CLAIMS = ['email', 'preferred_username', 'user_email', 'mail', 'emailAddress', 'e_mail'];
     /** Full name fields */
     const NAME_CLAIMS = ['name', 'full_name', 'display_name', 'displayName'];
     /** First name fields */
@@ -3365,6 +3371,7 @@
             this.queue = new EventQueue(this.transport, {
                 batchSize: this.config.batchSize,
                 flushInterval: this.config.flushInterval,
+                persistMode: this.config.persistMode,
             });
             // Get or create visitor and session IDs based on mode
             this.visitorId = this.createVisitorId();
@@ -3481,10 +3488,13 @@
                 logger.warn('SDK not initialized, event dropped');
                 return;
             }
+            const utmParams = getUTMParams();
             const event = {
                 workspaceId: this.workspaceId,
                 visitorId: this.visitorId,
                 sessionId: this.sessionId,
+                contactId: this.contactId ?? undefined,
+                groupId: this.groupId ?? undefined,
                 eventType: eventType,
                 eventName,
                 url: typeof window !== 'undefined' ? window.location.href : '',
@@ -3495,18 +3505,14 @@
                     websiteDomain: typeof window !== 'undefined' ? window.location.hostname : undefined,
                 },
                 device: getDeviceInfo(),
-                ...getUTMParams(),
+                utmSource: utmParams.utmSource,
+                utmMedium: utmParams.utmMedium,
+                utmCampaign: utmParams.utmCampaign,
+                utmTerm: utmParams.utmTerm,
+                utmContent: utmParams.utmContent,
                 timestamp: new Date().toISOString(),
                 sdkVersion: SDK_VERSION,
             };
-            // Attach contactId if known (from a prior identify() call)
-            if (this.contactId) {
-                event.contactId = this.contactId;
-            }
-            // Attach groupId if known (from a prior group() call)
-            if (this.groupId) {
-                event.groupId = this.groupId;
-            }
             // Validate event against registered schema (debug mode only)
             this.validateEventSchema(eventType, properties);
             // Check consent before tracking
@@ -3967,6 +3973,1189 @@
         }
     }
 
+    /**
+     * Clianta SDK - Event Triggers Manager
+     * Manages event-driven automation and email notifications
+     */
+    /**
+     * Event Triggers Manager
+     * Handles event-driven automation based on CRM actions
+     *
+     * Similar to:
+     * - Salesforce: Process Builder, Flow Automation
+     * - HubSpot: Workflows, Email Sequences
+     * - Pipedrive: Workflow Automation
+     */
+    class EventTriggersManager {
+        constructor(apiEndpoint, workspaceId, authToken) {
+            this.triggers = new Map();
+            this.listeners = new Map();
+            this.apiEndpoint = apiEndpoint;
+            this.workspaceId = workspaceId;
+            this.authToken = authToken;
+        }
+        /**
+         * Set authentication token
+         */
+        setAuthToken(token) {
+            this.authToken = token;
+        }
+        /**
+         * Make authenticated API request
+         */
+        async request(endpoint, options = {}) {
+            const url = `${this.apiEndpoint}${endpoint}`;
+            const headers = {
+                'Content-Type': 'application/json',
+                ...(options.headers || {}),
+            };
+            if (this.authToken) {
+                headers['Authorization'] = `Bearer ${this.authToken}`;
+            }
+            try {
+                const response = await fetch(url, {
+                    ...options,
+                    headers,
+                });
+                const data = await response.json();
+                if (!response.ok) {
+                    return {
+                        success: false,
+                        error: data.message || 'Request failed',
+                        status: response.status,
+                    };
+                }
+                return {
+                    success: true,
+                    data: data.data || data,
+                    status: response.status,
+                };
+            }
+            catch (error) {
+                return {
+                    success: false,
+                    error: error instanceof Error ? error.message : 'Network error',
+                    status: 0,
+                };
+            }
+        }
+        // ============================================
+        // TRIGGER MANAGEMENT
+        // ============================================
+        /**
+         * Get all event triggers
+         */
+        async getTriggers() {
+            return this.request(`/api/workspaces/${this.workspaceId}/triggers`);
+        }
+        /**
+         * Get a single trigger by ID
+         */
+        async getTrigger(triggerId) {
+            return this.request(`/api/workspaces/${this.workspaceId}/triggers/${triggerId}`);
+        }
+        /**
+         * Create a new event trigger
+         */
+        async createTrigger(trigger) {
+            const result = await this.request(`/api/workspaces/${this.workspaceId}/triggers`, {
+                method: 'POST',
+                body: JSON.stringify(trigger),
+            });
+            // Cache the trigger locally if successful
+            if (result.success && result.data?._id) {
+                this.triggers.set(result.data._id, result.data);
+            }
+            return result;
+        }
+        /**
+         * Update an existing trigger
+         */
+        async updateTrigger(triggerId, updates) {
+            const result = await this.request(`/api/workspaces/${this.workspaceId}/triggers/${triggerId}`, {
+                method: 'PUT',
+                body: JSON.stringify(updates),
+            });
+            // Update cache if successful
+            if (result.success && result.data?._id) {
+                this.triggers.set(result.data._id, result.data);
+            }
+            return result;
+        }
+        /**
+         * Delete a trigger
+         */
+        async deleteTrigger(triggerId) {
+            const result = await this.request(`/api/workspaces/${this.workspaceId}/triggers/${triggerId}`, {
+                method: 'DELETE',
+            });
+            // Remove from cache if successful
+            if (result.success) {
+                this.triggers.delete(triggerId);
+            }
+            return result;
+        }
+        /**
+         * Activate a trigger
+         */
+        async activateTrigger(triggerId) {
+            return this.updateTrigger(triggerId, { isActive: true });
+        }
+        /**
+         * Deactivate a trigger
+         */
+        async deactivateTrigger(triggerId) {
+            return this.updateTrigger(triggerId, { isActive: false });
+        }
+        // ============================================
+        // EVENT HANDLING (CLIENT-SIDE)
+        // ============================================
+        /**
+         * Register a local event listener for client-side triggers
+         * This allows immediate client-side reactions to events
+         */
+        on(eventType, callback) {
+            if (!this.listeners.has(eventType)) {
+                this.listeners.set(eventType, new Set());
+            }
+            this.listeners.get(eventType).add(callback);
+            logger.debug(`Event listener registered: ${eventType}`);
+        }
+        /**
+         * Remove an event listener
+         */
+        off(eventType, callback) {
+            const listeners = this.listeners.get(eventType);
+            if (listeners) {
+                listeners.delete(callback);
+            }
+        }
+        /**
+         * Emit an event (client-side only)
+         * This will trigger any registered local listeners
+         */
+        emit(eventType, data) {
+            logger.debug(`Event emitted: ${eventType}`, data);
+            const listeners = this.listeners.get(eventType);
+            if (listeners) {
+                listeners.forEach(callback => {
+                    try {
+                        callback(data);
+                    }
+                    catch (error) {
+                        logger.error(`Error in event listener for ${eventType}:`, error);
+                    }
+                });
+            }
+        }
+        /**
+         * Check if conditions are met for a trigger
+         * Supports dynamic field evaluation including custom fields and nested paths
+         */
+        evaluateConditions(conditions, data) {
+            if (!conditions || conditions.length === 0) {
+                return true; // No conditions means always fire
+            }
+            return conditions.every(condition => {
+                // Support dot notation for nested fields (e.g., 'customFields.industry')
+                const fieldValue = condition.field.includes('.')
+                    ? this.getNestedValue(data, condition.field)
+                    : data[condition.field];
+                const targetValue = condition.value;
+                switch (condition.operator) {
+                    case 'equals':
+                        return fieldValue === targetValue;
+                    case 'not_equals':
+                        return fieldValue !== targetValue;
+                    case 'contains':
+                        return String(fieldValue).includes(String(targetValue));
+                    case 'greater_than':
+                        return Number(fieldValue) > Number(targetValue);
+                    case 'less_than':
+                        return Number(fieldValue) < Number(targetValue);
+                    case 'in':
+                        return Array.isArray(targetValue) && targetValue.includes(fieldValue);
+                    case 'not_in':
+                        return Array.isArray(targetValue) && !targetValue.includes(fieldValue);
+                    default:
+                        return false;
+                }
+            });
+        }
+        /**
+         * Execute actions for a triggered event (client-side preview)
+         * Note: Actual execution happens on the backend
+         */
+        async executeActions(trigger, data) {
+            logger.info(`Executing actions for trigger: ${trigger.name}`);
+            for (const action of trigger.actions) {
+                try {
+                    await this.executeAction(action, data);
+                }
+                catch (error) {
+                    logger.error(`Failed to execute action:`, error);
+                }
+            }
+        }
+        /**
+         * Execute a single action
+         */
+        async executeAction(action, data) {
+            switch (action.type) {
+                case 'send_email':
+                    await this.executeSendEmail(action, data);
+                    break;
+                case 'webhook':
+                    await this.executeWebhook(action, data);
+                    break;
+                case 'create_task':
+                    await this.executeCreateTask(action, data);
+                    break;
+                case 'update_contact':
+                    await this.executeUpdateContact(action, data);
+                    break;
+                default:
+                    logger.warn(`Unknown action type:`, action);
+            }
+        }
+        /**
+         * Execute send email action (via backend API)
+         */
+        async executeSendEmail(action, data) {
+            logger.debug('Sending email:', action);
+            const payload = {
+                to: this.replaceVariables(action.to, data),
+                subject: action.subject ? this.replaceVariables(action.subject, data) : undefined,
+                body: action.body ? this.replaceVariables(action.body, data) : undefined,
+                templateId: action.templateId,
+                cc: action.cc,
+                bcc: action.bcc,
+                from: action.from,
+                delayMinutes: action.delayMinutes,
+            };
+            await this.request(`/api/workspaces/${this.workspaceId}/emails/send`, {
+                method: 'POST',
+                body: JSON.stringify(payload),
+            });
+        }
+        /**
+         * Execute webhook action
+         */
+        async executeWebhook(action, data) {
+            logger.debug('Calling webhook:', action.url);
+            const body = action.body ? this.replaceVariables(action.body, data) : JSON.stringify(data);
+            await fetch(action.url, {
+                method: action.method,
+                headers: {
+                    'Content-Type': 'application/json',
+                    ...action.headers,
+                },
+                body,
+            });
+        }
+        /**
+         * Execute create task action
+         */
+        async executeCreateTask(action, data) {
+            logger.debug('Creating task:', action.title);
+            const dueDate = action.dueDays
+                ? new Date(Date.now() + action.dueDays * 24 * 60 * 60 * 1000).toISOString()
+                : undefined;
+            await this.request(`/api/workspaces/${this.workspaceId}/tasks`, {
+                method: 'POST',
+                body: JSON.stringify({
+                    title: this.replaceVariables(action.title, data),
+                    description: action.description ? this.replaceVariables(action.description, data) : undefined,
+                    priority: action.priority,
+                    dueDate,
+                    assignedTo: action.assignedTo,
+                    relatedContactId: typeof data.contactId === 'string' ? data.contactId : undefined,
+                }),
+            });
+        }
+        /**
+         * Execute update contact action
+         */
+        async executeUpdateContact(action, data) {
+            const contactId = data.contactId || data._id;
+            if (!contactId) {
+                logger.warn('Cannot update contact: no contactId in data');
+                return;
+            }
+            logger.debug('Updating contact:', contactId);
+            await this.request(`/api/workspaces/${this.workspaceId}/contacts/${contactId}`, {
+                method: 'PUT',
+                body: JSON.stringify(action.updates),
+            });
+        }
+        /**
+         * Replace variables in a string template
+         * Supports syntax like {{contact.email}}, {{opportunity.value}}
+         */
+        replaceVariables(template, data) {
+            return template.replace(/\{\{([^}]+)\}\}/g, (match, path) => {
+                const value = this.getNestedValue(data, path.trim());
+                return value !== undefined ? String(value) : match;
+            });
+        }
+        /**
+         * Get nested value from object using dot notation
+         * Supports dynamic field access including custom fields
+         */
+        getNestedValue(obj, path) {
+            return path.split('.').reduce((current, key) => {
+                return current !== null && current !== undefined && typeof current === 'object'
+                    ? current[key]
+                    : undefined;
+            }, obj);
+        }
+        /**
+         * Extract all available field paths from a data object
+         * Useful for dynamic field discovery based on platform-specific attributes
+         * @param obj - The data object to extract fields from
+         * @param prefix - Internal use for nested paths
+         * @param maxDepth - Maximum depth to traverse (default: 3)
+         * @returns Array of field paths (e.g., ['email', 'contact.firstName', 'customFields.industry'])
+         */
+        extractAvailableFields(obj, prefix = '', maxDepth = 3) {
+            if (maxDepth <= 0)
+                return [];
+            const fields = [];
+            for (const key in obj) {
+                if (!obj.hasOwnProperty(key))
+                    continue;
+                const value = obj[key];
+                const fieldPath = prefix ? `${prefix}.${key}` : key;
+                fields.push(fieldPath);
+                // Recursively traverse nested objects
+                if (value !== null && typeof value === 'object' && !Array.isArray(value)) {
+                    const nestedFields = this.extractAvailableFields(value, fieldPath, maxDepth - 1);
+                    fields.push(...nestedFields);
+                }
+            }
+            return fields;
+        }
+        /**
+         * Get available fields from sample data
+         * Helps with dynamic field detection for platform-specific attributes
+         * @param sampleData - Sample data object to analyze
+         * @returns Array of available field paths
+         */
+        getAvailableFields(sampleData) {
+            return this.extractAvailableFields(sampleData);
+        }
+        // ============================================
+        // HELPER METHODS FOR COMMON PATTERNS
+        // ============================================
+        /**
+         * Create a simple email trigger
+         * Helper method for common use case
+         */
+        async createEmailTrigger(config) {
+            return this.createTrigger({
+                name: config.name,
+                eventType: config.eventType,
+                conditions: config.conditions,
+                actions: [
+                    {
+                        type: 'send_email',
+                        to: config.to,
+                        subject: config.subject,
+                        body: config.body,
+                    },
+                ],
+                isActive: true,
+            });
+        }
+        /**
+         * Create a task creation trigger
+         */
+        async createTaskTrigger(config) {
+            return this.createTrigger({
+                name: config.name,
+                eventType: config.eventType,
+                conditions: config.conditions,
+                actions: [
+                    {
+                        type: 'create_task',
+                        title: config.taskTitle,
+                        description: config.taskDescription,
+                        priority: config.priority,
+                        dueDays: config.dueDays,
+                    },
+                ],
+                isActive: true,
+            });
+        }
+        /**
+         * Create a webhook trigger
+         */
+        async createWebhookTrigger(config) {
+            return this.createTrigger({
+                name: config.name,
+                eventType: config.eventType,
+                conditions: config.conditions,
+                actions: [
+                    {
+                        type: 'webhook',
+                        url: config.webhookUrl,
+                        method: config.method || 'POST',
+                    },
+                ],
+                isActive: true,
+            });
+        }
+    }
+
+    /**
+     * Clianta SDK - CRM API Client
+     * @see SDK_VERSION in core/config.ts
+     */
+    /**
+     * CRM API Client for managing contacts and opportunities
+     */
+    class CRMClient {
+        constructor(apiEndpoint, workspaceId, authToken, apiKey) {
+            this.apiEndpoint = apiEndpoint;
+            this.workspaceId = workspaceId;
+            this.authToken = authToken;
+            this.apiKey = apiKey;
+            this.triggers = new EventTriggersManager(apiEndpoint, workspaceId, authToken);
+        }
+        /**
+         * Set authentication token for API requests (user JWT)
+         */
+        setAuthToken(token) {
+            this.authToken = token;
+            this.apiKey = undefined;
+            this.triggers.setAuthToken(token);
+        }
+        /**
+         * Set workspace API key for server-to-server requests.
+         * Use this instead of setAuthToken when integrating from an external app.
+         */
+        setApiKey(key) {
+            this.apiKey = key;
+            this.authToken = undefined;
+        }
+        /**
+         * Validate required parameter exists
+         * @throws {Error} if value is null/undefined or empty string
+         */
+        validateRequired(param, value, methodName) {
+            if (value === null || value === undefined || value === '') {
+                throw new Error(`[CRMClient.${methodName}] ${param} is required`);
+            }
+        }
+        /**
+         * Make authenticated API request
+         */
+        async request(endpoint, options = {}) {
+            const url = `${this.apiEndpoint}${endpoint}`;
+            const headers = {
+                'Content-Type': 'application/json',
+                ...(options.headers || {}),
+            };
+            if (this.apiKey) {
+                headers['X-Api-Key'] = this.apiKey;
+            }
+            else if (this.authToken) {
+                headers['Authorization'] = `Bearer ${this.authToken}`;
+            }
+            try {
+                const response = await fetch(url, {
+                    ...options,
+                    headers,
+                });
+                const data = await response.json();
+                if (!response.ok) {
+                    return {
+                        success: false,
+                        error: data.message || 'Request failed',
+                        status: response.status,
+                    };
+                }
+                return {
+                    success: true,
+                    data: data.data || data,
+                    status: response.status,
+                };
+            }
+            catch (error) {
+                return {
+                    success: false,
+                    error: error instanceof Error ? error.message : 'Network error',
+                    status: 0,
+                };
+            }
+        }
+        // ============================================
+        // INBOUND EVENTS API (API-key authenticated)
+        // ============================================
+        /**
+         * Send an inbound event from an external app (e.g. user signup on client website).
+         * Requires the client to be initialized with an API key via setApiKey() or the constructor.
+         *
+         * The contact is upserted in the CRM and matching workflow automations fire automatically.
+         *
+         * @example
+         * const crm = new CRMClient('http://localhost:5000', 'WORKSPACE_ID');
+         * crm.setApiKey('mm_live_...');
+         *
+         * await crm.sendEvent({
+         *   event: 'user.registered',
+         *   contact: { email: 'alice@example.com', firstName: 'Alice' },
+         *   data: { plan: 'free', signupSource: 'homepage' },
+         * });
+         */
+        async sendEvent(payload) {
+            const url = `${this.apiEndpoint}/api/public/events`;
+            const headers = { 'Content-Type': 'application/json' };
+            if (this.apiKey) {
+                headers['X-Api-Key'] = this.apiKey;
+            }
+            else if (this.authToken) {
+                headers['Authorization'] = `Bearer ${this.authToken}`;
+            }
+            try {
+                const response = await fetch(url, {
+                    method: 'POST',
+                    headers,
+                    body: JSON.stringify(payload),
+                });
+                const data = await response.json();
+                if (!response.ok) {
+                    return {
+                        success: false,
+                        contactCreated: false,
+                        event: payload.event,
+                        error: data.error || 'Request failed',
+                    };
+                }
+                return {
+                    success: data.success,
+                    contactCreated: data.contactCreated,
+                    contactId: data.contactId,
+                    event: data.event,
+                };
+            }
+            catch (error) {
+                return {
+                    success: false,
+                    contactCreated: false,
+                    event: payload.event,
+                    error: error instanceof Error ? error.message : 'Network error',
+                };
+            }
+        }
+        // ============================================
+        // CONTACTS API
+        // ============================================
+        /**
+         * Get all contacts with pagination
+         */
+        async getContacts(params) {
+            const queryParams = new URLSearchParams();
+            if (params?.page)
+                queryParams.set('page', params.page.toString());
+            if (params?.limit)
+                queryParams.set('limit', params.limit.toString());
+            if (params?.search)
+                queryParams.set('search', params.search);
+            if (params?.status)
+                queryParams.set('status', params.status);
+            const query = queryParams.toString();
+            const endpoint = `/api/workspaces/${this.workspaceId}/contacts${query ? `?${query}` : ''}`;
+            return this.request(endpoint);
+        }
+        /**
+         * Get a single contact by ID
+         */
+        async getContact(contactId) {
+            this.validateRequired('contactId', contactId, 'getContact');
+            return this.request(`/api/workspaces/${this.workspaceId}/contacts/${contactId}`);
+        }
+        /**
+         * Create a new contact
+         */
+        async createContact(contact) {
+            return this.request(`/api/workspaces/${this.workspaceId}/contacts`, {
+                method: 'POST',
+                body: JSON.stringify(contact),
+            });
+        }
+        /**
+         * Update an existing contact
+         */
+        async updateContact(contactId, updates) {
+            this.validateRequired('contactId', contactId, 'updateContact');
+            return this.request(`/api/workspaces/${this.workspaceId}/contacts/${contactId}`, {
+                method: 'PUT',
+                body: JSON.stringify(updates),
+            });
+        }
+        /**
+         * Delete a contact
+         */
+        async deleteContact(contactId) {
+            this.validateRequired('contactId', contactId, 'deleteContact');
+            return this.request(`/api/workspaces/${this.workspaceId}/contacts/${contactId}`, {
+                method: 'DELETE',
+            });
+        }
+        // ============================================
+        // OPPORTUNITIES API
+        // ============================================
+        /**
+         * Get all opportunities with pagination
+         */
+        async getOpportunities(params) {
+            const queryParams = new URLSearchParams();
+            if (params?.page)
+                queryParams.set('page', params.page.toString());
+            if (params?.limit)
+                queryParams.set('limit', params.limit.toString());
+            if (params?.pipelineId)
+                queryParams.set('pipelineId', params.pipelineId);
+            if (params?.stageId)
+                queryParams.set('stageId', params.stageId);
+            const query = queryParams.toString();
+            const endpoint = `/api/workspaces/${this.workspaceId}/opportunities${query ? `?${query}` : ''}`;
+            return this.request(endpoint);
+        }
+        /**
+         * Get a single opportunity by ID
+         */
+        async getOpportunity(opportunityId) {
+            return this.request(`/api/workspaces/${this.workspaceId}/opportunities/${opportunityId}`);
+        }
+        /**
+         * Create a new opportunity
+         */
+        async createOpportunity(opportunity) {
+            return this.request(`/api/workspaces/${this.workspaceId}/opportunities`, {
+                method: 'POST',
+                body: JSON.stringify(opportunity),
+            });
+        }
+        /**
+         * Update an existing opportunity
+         */
+        async updateOpportunity(opportunityId, updates) {
+            return this.request(`/api/workspaces/${this.workspaceId}/opportunities/${opportunityId}`, {
+                method: 'PUT',
+                body: JSON.stringify(updates),
+            });
+        }
+        /**
+         * Delete an opportunity
+         */
+        async deleteOpportunity(opportunityId) {
+            return this.request(`/api/workspaces/${this.workspaceId}/opportunities/${opportunityId}`, {
+                method: 'DELETE',
+            });
+        }
+        /**
+         * Move opportunity to a different stage
+         */
+        async moveOpportunity(opportunityId, stageId) {
+            return this.request(`/api/workspaces/${this.workspaceId}/opportunities/${opportunityId}/move`, {
+                method: 'POST',
+                body: JSON.stringify({ stageId }),
+            });
+        }
+        // ============================================
+        // COMPANIES API
+        // ============================================
+        /**
+         * Get all companies with pagination
+         */
+        async getCompanies(params) {
+            const queryParams = new URLSearchParams();
+            if (params?.page)
+                queryParams.set('page', params.page.toString());
+            if (params?.limit)
+                queryParams.set('limit', params.limit.toString());
+            if (params?.search)
+                queryParams.set('search', params.search);
+            if (params?.status)
+                queryParams.set('status', params.status);
+            if (params?.industry)
+                queryParams.set('industry', params.industry);
+            const query = queryParams.toString();
+            const endpoint = `/api/workspaces/${this.workspaceId}/companies${query ? `?${query}` : ''}`;
+            return this.request(endpoint);
+        }
+        /**
+         * Get a single company by ID
+         */
+        async getCompany(companyId) {
+            return this.request(`/api/workspaces/${this.workspaceId}/companies/${companyId}`);
+        }
+        /**
+         * Create a new company
+         */
+        async createCompany(company) {
+            return this.request(`/api/workspaces/${this.workspaceId}/companies`, {
+                method: 'POST',
+                body: JSON.stringify(company),
+            });
+        }
+        /**
+         * Update an existing company
+         */
+        async updateCompany(companyId, updates) {
+            return this.request(`/api/workspaces/${this.workspaceId}/companies/${companyId}`, {
+                method: 'PUT',
+                body: JSON.stringify(updates),
+            });
+        }
+        /**
+         * Delete a company
+         */
+        async deleteCompany(companyId) {
+            return this.request(`/api/workspaces/${this.workspaceId}/companies/${companyId}`, {
+                method: 'DELETE',
+            });
+        }
+        /**
+         * Get contacts belonging to a company
+         */
+        async getCompanyContacts(companyId, params) {
+            const queryParams = new URLSearchParams();
+            if (params?.page)
+                queryParams.set('page', params.page.toString());
+            if (params?.limit)
+                queryParams.set('limit', params.limit.toString());
+            const query = queryParams.toString();
+            const endpoint = `/api/workspaces/${this.workspaceId}/companies/${companyId}/contacts${query ? `?${query}` : ''}`;
+            return this.request(endpoint);
+        }
+        /**
+         * Get deals/opportunities belonging to a company
+         */
+        async getCompanyDeals(companyId, params) {
+            const queryParams = new URLSearchParams();
+            if (params?.page)
+                queryParams.set('page', params.page.toString());
+            if (params?.limit)
+                queryParams.set('limit', params.limit.toString());
+            const query = queryParams.toString();
+            const endpoint = `/api/workspaces/${this.workspaceId}/companies/${companyId}/deals${query ? `?${query}` : ''}`;
+            return this.request(endpoint);
+        }
+        // ============================================
+        // PIPELINES API
+        // ============================================
+        /**
+         * Get all pipelines
+         */
+        async getPipelines() {
+            return this.request(`/api/workspaces/${this.workspaceId}/pipelines`);
+        }
+        /**
+         * Get a single pipeline by ID
+         */
+        async getPipeline(pipelineId) {
+            return this.request(`/api/workspaces/${this.workspaceId}/pipelines/${pipelineId}`);
+        }
+        /**
+         * Create a new pipeline
+         */
+        async createPipeline(pipeline) {
+            return this.request(`/api/workspaces/${this.workspaceId}/pipelines`, {
+                method: 'POST',
+                body: JSON.stringify(pipeline),
+            });
+        }
+        /**
+         * Update an existing pipeline
+         */
+        async updatePipeline(pipelineId, updates) {
+            return this.request(`/api/workspaces/${this.workspaceId}/pipelines/${pipelineId}`, {
+                method: 'PUT',
+                body: JSON.stringify(updates),
+            });
+        }
+        /**
+         * Delete a pipeline
+         */
+        async deletePipeline(pipelineId) {
+            return this.request(`/api/workspaces/${this.workspaceId}/pipelines/${pipelineId}`, {
+                method: 'DELETE',
+            });
+        }
+        // ============================================
+        // TASKS API
+        // ============================================
+        /**
+         * Get all tasks with pagination
+         */
+        async getTasks(params) {
+            const queryParams = new URLSearchParams();
+            if (params?.page)
+                queryParams.set('page', params.page.toString());
+            if (params?.limit)
+                queryParams.set('limit', params.limit.toString());
+            if (params?.status)
+                queryParams.set('status', params.status);
+            if (params?.priority)
+                queryParams.set('priority', params.priority);
+            if (params?.contactId)
+                queryParams.set('contactId', params.contactId);
+            if (params?.companyId)
+                queryParams.set('companyId', params.companyId);
+            if (params?.opportunityId)
+                queryParams.set('opportunityId', params.opportunityId);
+            const query = queryParams.toString();
+            const endpoint = `/api/workspaces/${this.workspaceId}/tasks${query ? `?${query}` : ''}`;
+            return this.request(endpoint);
+        }
+        /**
+         * Get a single task by ID
+         */
+        async getTask(taskId) {
+            return this.request(`/api/workspaces/${this.workspaceId}/tasks/${taskId}`);
+        }
+        /**
+         * Create a new task
+         */
+        async createTask(task) {
+            return this.request(`/api/workspaces/${this.workspaceId}/tasks`, {
+                method: 'POST',
+                body: JSON.stringify(task),
+            });
+        }
+        /**
+         * Update an existing task
+         */
+        async updateTask(taskId, updates) {
+            return this.request(`/api/workspaces/${this.workspaceId}/tasks/${taskId}`, {
+                method: 'PUT',
+                body: JSON.stringify(updates),
+            });
+        }
+        /**
+         * Mark a task as completed
+         */
+        async completeTask(taskId) {
+            return this.request(`/api/workspaces/${this.workspaceId}/tasks/${taskId}/complete`, {
+                method: 'PATCH',
+            });
+        }
+        /**
+         * Delete a task
+         */
+        async deleteTask(taskId) {
+            return this.request(`/api/workspaces/${this.workspaceId}/tasks/${taskId}`, {
+                method: 'DELETE',
+            });
+        }
+        // ============================================
+        // ACTIVITIES API
+        // ============================================
+        /**
+         * Get activities for a contact
+         */
+        async getContactActivities(contactId, params) {
+            const queryParams = new URLSearchParams();
+            if (params?.page)
+                queryParams.set('page', params.page.toString());
+            if (params?.limit)
+                queryParams.set('limit', params.limit.toString());
+            if (params?.type)
+                queryParams.set('type', params.type);
+            const query = queryParams.toString();
+            const endpoint = `/api/workspaces/${this.workspaceId}/contacts/${contactId}/activities${query ? `?${query}` : ''}`;
+            return this.request(endpoint);
+        }
+        /**
+         * Get activities for an opportunity/deal
+         */
+        async getOpportunityActivities(opportunityId, params) {
+            const queryParams = new URLSearchParams();
+            if (params?.page)
+                queryParams.set('page', params.page.toString());
+            if (params?.limit)
+                queryParams.set('limit', params.limit.toString());
+            if (params?.type)
+                queryParams.set('type', params.type);
+            const query = queryParams.toString();
+            const endpoint = `/api/workspaces/${this.workspaceId}/opportunities/${opportunityId}/activities${query ? `?${query}` : ''}`;
+            return this.request(endpoint);
+        }
+        /**
+         * Create a new activity
+         */
+        async createActivity(activity) {
+            // Determine the correct endpoint based on related entity
+            let endpoint;
+            if (activity.opportunityId) {
+                endpoint = `/api/workspaces/${this.workspaceId}/opportunities/${activity.opportunityId}/activities`;
+            }
+            else if (activity.contactId) {
+                endpoint = `/api/workspaces/${this.workspaceId}/contacts/${activity.contactId}/activities`;
+            }
+            else {
+                endpoint = `/api/workspaces/${this.workspaceId}/activities`;
+            }
+            return this.request(endpoint, {
+                method: 'POST',
+                body: JSON.stringify(activity),
+            });
+        }
+        /**
+         * Update an existing activity
+         */
+        async updateActivity(activityId, updates) {
+            return this.request(`/api/workspaces/${this.workspaceId}/activities/${activityId}`, {
+                method: 'PATCH',
+                body: JSON.stringify(updates),
+            });
+        }
+        /**
+         * Delete an activity
+         */
+        async deleteActivity(activityId) {
+            return this.request(`/api/workspaces/${this.workspaceId}/activities/${activityId}`, {
+                method: 'DELETE',
+            });
+        }
+        /**
+         * Log a call activity
+         */
+        async logCall(data) {
+            return this.createActivity({
+                type: 'call',
+                title: `${data.direction === 'inbound' ? 'Inbound' : 'Outbound'} Call`,
+                direction: data.direction,
+                duration: data.duration,
+                outcome: data.outcome,
+                description: data.notes,
+                contactId: data.contactId,
+                opportunityId: data.opportunityId,
+            });
+        }
+        /**
+         * Log a meeting activity
+         */
+        async logMeeting(data) {
+            return this.createActivity({
+                type: 'meeting',
+                title: data.title,
+                duration: data.duration,
+                outcome: data.outcome,
+                description: data.notes,
+                contactId: data.contactId,
+                opportunityId: data.opportunityId,
+            });
+        }
+        /**
+         * Add a note to a contact or opportunity
+         */
+        async addNote(data) {
+            return this.createActivity({
+                type: 'note',
+                title: 'Note',
+                description: data.content,
+                contactId: data.contactId,
+                opportunityId: data.opportunityId,
+            });
+        }
+        // ============================================
+        // EMAIL TEMPLATES API
+        // ============================================
+        /**
+         * Get all email templates
+         */
+        async getEmailTemplates(params) {
+            const queryParams = new URLSearchParams();
+            if (params?.page)
+                queryParams.set('page', params.page.toString());
+            if (params?.limit)
+                queryParams.set('limit', params.limit.toString());
+            const query = queryParams.toString();
+            const endpoint = `/api/workspaces/${this.workspaceId}/email-templates${query ? `?${query}` : ''}`;
+            return this.request(endpoint);
+        }
+        /**
+         * Get a single email template by ID
+         */
+        async getEmailTemplate(templateId) {
+            return this.request(`/api/workspaces/${this.workspaceId}/email-templates/${templateId}`);
+        }
+        /**
+         * Create a new email template
+         */
+        async createEmailTemplate(template) {
+            return this.request(`/api/workspaces/${this.workspaceId}/email-templates`, {
+                method: 'POST',
+                body: JSON.stringify(template),
+            });
+        }
+        /**
+         * Update an email template
+         */
+        async updateEmailTemplate(templateId, updates) {
+            return this.request(`/api/workspaces/${this.workspaceId}/email-templates/${templateId}`, {
+                method: 'PUT',
+                body: JSON.stringify(updates),
+            });
+        }
+        /**
+         * Delete an email template
+         */
+        async deleteEmailTemplate(templateId) {
+            return this.request(`/api/workspaces/${this.workspaceId}/email-templates/${templateId}`, {
+                method: 'DELETE',
+            });
+        }
+        /**
+         * Send an email using a template
+         */
+        async sendEmail(data) {
+            return this.request(`/api/workspaces/${this.workspaceId}/emails/send`, {
+                method: 'POST',
+                body: JSON.stringify(data),
+            });
+        }
+        // ============================================
+        // READ-BACK / DATA RETRIEVAL API
+        // ============================================
+        /**
+         * Get a contact by email address.
+         * Returns the first matching contact from a search query.
+         */
+        async getContactByEmail(email) {
+            this.validateRequired('email', email, 'getContactByEmail');
+            const queryParams = new URLSearchParams({ search: email, limit: '1' });
+            return this.request(`/api/workspaces/${this.workspaceId}/contacts?${queryParams.toString()}`);
+        }
+        /**
+         * Get activity timeline for a contact
+         */
+        async getContactActivity(contactId, params) {
+            this.validateRequired('contactId', contactId, 'getContactActivity');
+            const queryParams = new URLSearchParams();
+            if (params?.page)
+                queryParams.set('page', params.page.toString());
+            if (params?.limit)
+                queryParams.set('limit', params.limit.toString());
+            if (params?.type)
+                queryParams.set('type', params.type);
+            if (params?.startDate)
+                queryParams.set('startDate', params.startDate);
+            if (params?.endDate)
+                queryParams.set('endDate', params.endDate);
+            const query = queryParams.toString();
+            const endpoint = `/api/workspaces/${this.workspaceId}/contacts/${contactId}/activities${query ? `?${query}` : ''}`;
+            return this.request(endpoint);
+        }
+        /**
+         * Get engagement metrics for a contact (via their linked visitor data)
+         */
+        async getContactEngagement(contactId) {
+            this.validateRequired('contactId', contactId, 'getContactEngagement');
+            return this.request(`/api/workspaces/${this.workspaceId}/contacts/${contactId}/engagement`);
+        }
+        /**
+         * Get a full timeline for a contact including events, activities, and opportunities
+         */
+        async getContactTimeline(contactId, params) {
+            this.validateRequired('contactId', contactId, 'getContactTimeline');
+            const queryParams = new URLSearchParams();
+            if (params?.page)
+                queryParams.set('page', params.page.toString());
+            if (params?.limit)
+                queryParams.set('limit', params.limit.toString());
+            const query = queryParams.toString();
+            const endpoint = `/api/workspaces/${this.workspaceId}/contacts/${contactId}/timeline${query ? `?${query}` : ''}`;
+            return this.request(endpoint);
+        }
+        /**
+         * Search contacts with advanced filters
+         */
+        async searchContacts(query, filters) {
+            const queryParams = new URLSearchParams();
+            queryParams.set('search', query);
+            if (filters?.status)
+                queryParams.set('status', filters.status);
+            if (filters?.lifecycleStage)
+                queryParams.set('lifecycleStage', filters.lifecycleStage);
+            if (filters?.source)
+                queryParams.set('source', filters.source);
+            if (filters?.tags)
+                queryParams.set('tags', filters.tags.join(','));
+            if (filters?.page)
+                queryParams.set('page', filters.page.toString());
+            if (filters?.limit)
+                queryParams.set('limit', filters.limit.toString());
+            const qs = queryParams.toString();
+            const endpoint = `/api/workspaces/${this.workspaceId}/contacts${qs ? `?${qs}` : ''}`;
+            return this.request(endpoint);
+        }
+        // ============================================
+        // WEBHOOK MANAGEMENT API
+        // ============================================
+        /**
+         * List all webhook subscriptions
+         */
+        async listWebhooks(params) {
+            const queryParams = new URLSearchParams();
+            if (params?.page)
+                queryParams.set('page', params.page.toString());
+            if (params?.limit)
+                queryParams.set('limit', params.limit.toString());
+            const query = queryParams.toString();
+            return this.request(`/api/workspaces/${this.workspaceId}/webhooks${query ? `?${query}` : ''}`);
+        }
+        /**
+         * Create a new webhook subscription
+         */
+        async createWebhook(data) {
+            return this.request(`/api/workspaces/${this.workspaceId}/webhooks`, {
+                method: 'POST',
+                body: JSON.stringify(data),
+            });
+        }
+        /**
+         * Delete a webhook subscription
+         */
+        async deleteWebhook(webhookId) {
+            this.validateRequired('webhookId', webhookId, 'deleteWebhook');
+            return this.request(`/api/workspaces/${this.workspaceId}/webhooks/${webhookId}`, {
+                method: 'DELETE',
+            });
+        }
+        // ============================================
+        // EVENT TRIGGERS API (delegated to triggers manager)
+        // ============================================
+        /**
+         * Get all event triggers
+         */
+        async getEventTriggers() {
+            return this.triggers.getTriggers();
+        }
+        /**
+         * Create a new event trigger
+         */
+        async createEventTrigger(trigger) {
+            return this.triggers.createTrigger(trigger);
+        }
+        /**
+         * Update an event trigger
+         */
+        async updateEventTrigger(triggerId, updates) {
+            return this.triggers.updateTrigger(triggerId, updates);
+        }
+        /**
+         * Delete an event trigger
+         */
+        async deleteEventTrigger(triggerId) {
+            return this.triggers.deleteTrigger(triggerId);
+        }
+    }
+
     /**
      * Clianta SDK
      * Client-side tracking SDK for CRM — tracks visitors, identifies contacts,
@@ -4076,6 +5265,7 @@
         }
     }
 
+    exports.CRMClient = CRMClient;
     exports.ConsentManager = ConsentManager;
     exports.SDK_VERSION = SDK_VERSION;
     exports.Tracker = Tracker;