@clianta/sdk 1.5.1 → 1.6.0

package/CHANGELOG.md

@@ -5,6 +5,26 @@ All notable changes to the Clianta SDK will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.6.0] - 2026-03-01
+
+### Added
+- **`group()` method** — Associate visitors with a company/account. The `groupId` is attached to all subsequent `track()` calls, enabling ABM (Account-Based Marketing) use cases
+- **`alias()` method** — Merge two visitor identities (e.g., anonymous visitor → logged-in user). Supports cross-device identity resolution
+- **`screen()` method** — Track screen views for mobile-first PWAs and SPAs. Semantic equivalent of `page()` for app screens
+- **Event middleware API** — `use((event, next) => { ... })` to intercept, transform, or drop events before they're sent. Supports chaining multiple middleware functions
+- **`onReady()` callback** — Register callbacks that fire when the SDK is fully initialized. If already ready, fires immediately
+- **`isReady()` method** — Check initialization state synchronously
+- **React `ErrorBoundary`** — `CliantaProvider` now wraps children in an ErrorBoundary to prevent SDK errors from crashing the host application
+- **React `useCliantaReady()` hook** — Returns `{ isReady, tracker }` for components that need to wait for initialization
+- **React `onError` prop** — `CliantaProvider` accepts an `onError` callback for custom error handling
+- **New types** — `GroupTraits`, `MiddlewareFn` exported from main SDK entry
+
+### Changed
+- `TrackerCore` interface expanded with `group()`, `alias()`, `screen()`, `use()`, `onReady()`, `isReady()` methods
+- React `CliantaContext` now provides `{ tracker, isReady }` instead of just `tracker`
+- `track()` now runs events through the middleware pipeline before queueing
+- Events include `groupId` field when visitor is associated with a group
+
 ## [1.5.1] - 2026-02-28
 
 ### Added

package/dist/angular.cjs.js

@@ -1,5 +1,5 @@
 /*!
- * Clianta SDK v1.5.1
+ * Clianta SDK v1.6.0
  * (c) 2026 Clianta
  * Released under the MIT License.
  */
@@ -10,7 +10,7 @@
  * @see SDK_VERSION in core/config.ts
  */
 /** SDK Version */
-const SDK_VERSION = '1.4.0';
+const SDK_VERSION = '1.6.0';
 /** Default API endpoint — reads from env or falls back to localhost */
 const getDefaultApiEndpoint = () => {
     // Build-time env var (works with Next.js, Vite, CRA, etc.)
@@ -3692,6 +3692,85 @@ class CRMClient {
     }
 }
 
+/**
+ * Privacy-safe visitor API client.
+ * All methods return data for the current visitor only (no cross-visitor access).
+ */
+class VisitorClient {
+    constructor(transport, workspaceId, visitorId) {
+        this.transport = transport;
+        this.workspaceId = workspaceId;
+        this.visitorId = visitorId;
+    }
+    /** Update visitorId (e.g. after reset) */
+    setVisitorId(id) {
+        this.visitorId = id;
+    }
+    basePath() {
+        return `/api/public/track/visitor/${this.workspaceId}/${this.visitorId}`;
+    }
+    /**
+     * Get the current visitor's profile from the CRM.
+     * Returns visitor data and linked contact info if identified.
+     */
+    async getProfile() {
+        const result = await this.transport.fetchData(`${this.basePath()}/profile`);
+        if (result.success && result.data) {
+            logger.debug('Visitor profile fetched:', result.data);
+            return result.data;
+        }
+        logger.warn('Failed to fetch visitor profile:', result.error);
+        return null;
+    }
+    /**
+     * Get the current visitor's recent activity/events.
+     * Returns paginated list of tracking events.
+     */
+    async getActivity(options) {
+        const params = {};
+        if (options?.page)
+            params.page = options.page.toString();
+        if (options?.limit)
+            params.limit = options.limit.toString();
+        if (options?.eventType)
+            params.eventType = options.eventType;
+        if (options?.startDate)
+            params.startDate = options.startDate;
+        if (options?.endDate)
+            params.endDate = options.endDate;
+        const result = await this.transport.fetchData(`${this.basePath()}/activity`, params);
+        if (result.success && result.data) {
+            return result.data;
+        }
+        logger.warn('Failed to fetch visitor activity:', result.error);
+        return null;
+    }
+    /**
+     * Get a summarized journey timeline for the current visitor.
+     * Includes top pages, sessions, time spent, and recent activities.
+     */
+    async getTimeline() {
+        const result = await this.transport.fetchData(`${this.basePath()}/timeline`);
+        if (result.success && result.data) {
+            return result.data;
+        }
+        logger.warn('Failed to fetch visitor timeline:', result.error);
+        return null;
+    }
+    /**
+     * Get engagement metrics for the current visitor.
+     * Includes time on site, page views, bounce rate, and engagement score.
+     */
+    async getEngagement() {
+        const result = await this.transport.fetchData(`${this.basePath()}/engagement`);
+        if (result.success && result.data) {
+            return result.data;
+        }
+        logger.warn('Failed to fetch visitor engagement:', result.error);
+        return null;
+    }
+}
+
 /**
  * Clianta SDK - Main Tracker Class
  * @see SDK_VERSION in core/config.ts
@@ -3705,10 +3784,16 @@ class Tracker {
         this.isInitialized = false;
         /** contactId after a successful identify() call */
         this.contactId = null;
+        /** groupId after a successful group() call */
+        this.groupId = null;
         /** Pending identify retry on next flush */
         this.pendingIdentify = null;
         /** Registered event schemas for validation */
         this.eventSchemas = new Map();
+        /** Event middleware pipeline */
+        this.middlewares = [];
+        /** Ready callbacks */
+        this.readyCallbacks = [];
         if (!workspaceId) {
             throw new Error('[Clianta] Workspace ID is required');
         }
@@ -3734,6 +3819,8 @@ class Tracker {
         this.visitorId = this.createVisitorId();
         this.sessionId = this.createSessionId();
         logger.debug('IDs created', { visitorId: this.visitorId, sessionId: this.sessionId });
+        // Initialize visitor API client
+        this.visitor = new VisitorClient(this.transport, this.workspaceId, this.visitorId);
         // Security warnings
         if (this.config.apiEndpoint.startsWith('http://') &&
             typeof window !== 'undefined' &&
@@ -3748,6 +3835,16 @@ class Tracker {
         this.initPlugins();
         this.isInitialized = true;
         logger.info('SDK initialized successfully');
+        // Fire ready callbacks
+        for (const cb of this.readyCallbacks) {
+            try {
+                cb();
+            }
+            catch (e) {
+                logger.error('onReady callback error:', e);
+            }
+        }
+        this.readyCallbacks = [];
     }
     /**
      * Create visitor ID based on storage mode
@@ -3860,6 +3957,10 @@ class Tracker {
         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
@@ -3873,8 +3974,11 @@ class Tracker {
             logger.debug('Event dropped (no consent):', eventName);
             return;
         }
-        this.queue.push(event);
-        logger.debug('Event tracked:', eventName, properties);
+        // Run event through middleware pipeline
+        this.runMiddleware(event, () => {
+            this.queue.push(event);
+            logger.debug('Event tracked:', eventName, properties);
+        });
     }
     /**
      * Track a page view
@@ -3936,80 +4040,47 @@ class Tracker {
     }
     /**
      * Get the current visitor's profile from the CRM.
-     * Returns visitor data and linked contact info if identified.
-     * Only returns data for the current visitor (privacy-safe for frontend).
+     * @deprecated Use `tracker.visitor.getProfile()` instead.
      */
     async getVisitorProfile() {
         if (!this.isInitialized) {
             logger.warn('SDK not initialized');
             return null;
         }
-        const result = await this.transport.fetchData(`/api/public/track/visitor/${this.workspaceId}/${this.visitorId}/profile`);
-        if (result.success && result.data) {
-            logger.debug('Visitor profile fetched:', result.data);
-            return result.data;
-        }
-        logger.warn('Failed to fetch visitor profile:', result.error);
-        return null;
+        return this.visitor.getProfile();
     }
     /**
      * Get the current visitor's recent activity/events.
-     * Returns paginated list of tracking events for this visitor.
+     * @deprecated Use `tracker.visitor.getActivity()` instead.
      */
     async getVisitorActivity(options) {
         if (!this.isInitialized) {
             logger.warn('SDK not initialized');
             return null;
         }
-        const params = {};
-        if (options?.page)
-            params.page = options.page.toString();
-        if (options?.limit)
-            params.limit = options.limit.toString();
-        if (options?.eventType)
-            params.eventType = options.eventType;
-        if (options?.startDate)
-            params.startDate = options.startDate;
-        if (options?.endDate)
-            params.endDate = options.endDate;
-        const result = await this.transport.fetchData(`/api/public/track/visitor/${this.workspaceId}/${this.visitorId}/activity`, params);
-        if (result.success && result.data) {
-            return result.data;
-        }
-        logger.warn('Failed to fetch visitor activity:', result.error);
-        return null;
+        return this.visitor.getActivity(options);
     }
     /**
      * Get a summarized journey timeline for the current visitor.
-     * Includes top pages, sessions, time spent, and recent activities.
+     * @deprecated Use `tracker.visitor.getTimeline()` instead.
      */
     async getVisitorTimeline() {
         if (!this.isInitialized) {
             logger.warn('SDK not initialized');
             return null;
         }
-        const result = await this.transport.fetchData(`/api/public/track/visitor/${this.workspaceId}/${this.visitorId}/timeline`);
-        if (result.success && result.data) {
-            return result.data;
-        }
-        logger.warn('Failed to fetch visitor timeline:', result.error);
-        return null;
+        return this.visitor.getTimeline();
     }
     /**
      * Get engagement metrics for the current visitor.
-     * Includes time on site, page views, bounce rate, and engagement score.
+     * @deprecated Use `tracker.visitor.getEngagement()` instead.
      */
     async getVisitorEngagement() {
         if (!this.isInitialized) {
             logger.warn('SDK not initialized');
             return null;
         }
-        const result = await this.transport.fetchData(`/api/public/track/visitor/${this.workspaceId}/${this.visitorId}/engagement`);
-        if (result.success && result.data) {
-            return result.data;
-        }
-        logger.warn('Failed to fetch visitor engagement:', result.error);
-        return null;
+        return this.visitor.getEngagement();
     }
     /**
      * Retry pending identify call
@@ -4040,6 +4111,149 @@ class Tracker {
         logger.enabled = enabled;
         logger.info(`Debug mode ${enabled ? 'enabled' : 'disabled'}`);
     }
+    // ============================================
+    // GROUP, ALIAS, SCREEN
+    // ============================================
+    /**
+     * Associate the current visitor with a group (company/account).
+     * The groupId will be attached to all subsequent track() calls.
+     */
+    group(groupId, traits = {}) {
+        if (!groupId) {
+            logger.warn('groupId is required for group()');
+            return;
+        }
+        this.groupId = groupId;
+        logger.info('Visitor grouped:', groupId);
+        this.track('group', 'Group Identified', {
+            groupId,
+            ...traits,
+        });
+    }
+    /**
+     * Merge two visitor identities.
+     * Links `previousId` (typically the anonymous visitor) to `newId` (the known user).
+     * If `previousId` is omitted, the current visitorId is used.
+     */
+    async alias(newId, previousId) {
+        if (!newId) {
+            logger.warn('newId is required for alias()');
+            return false;
+        }
+        const prevId = previousId || this.visitorId;
+        logger.info('Aliasing visitor:', { from: prevId, to: newId });
+        try {
+            const url = `${this.config.apiEndpoint}/api/public/track/alias`;
+            const response = await fetch(url, {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify({
+                    workspaceId: this.workspaceId,
+                    previousId: prevId,
+                    newId,
+                }),
+            });
+            if (response.ok) {
+                logger.info('Alias successful');
+                return true;
+            }
+            logger.error('Alias failed:', response.status);
+            return false;
+        }
+        catch (error) {
+            logger.error('Alias request failed:', error);
+            return false;
+        }
+    }
+    /**
+     * Track a screen view (for mobile-first PWAs and SPAs).
+     * Similar to page() but semantically for app screens.
+     */
+    screen(name, properties = {}) {
+        this.track('screen_view', name, {
+            ...properties,
+            screenName: name,
+        });
+    }
+    // ============================================
+    // MIDDLEWARE
+    // ============================================
+    /**
+     * Register event middleware.
+     * Middleware functions receive the event and a `next` callback.
+     * Call `next()` to pass the event through, or don't call it to drop the event.
+     *
+     * @example
+     * tracker.use((event, next) => {
+     *   // Strip PII from events
+     *   delete event.properties.email;
+     *   next(); // pass it through
+     * });
+     */
+    use(middleware) {
+        this.middlewares.push(middleware);
+        logger.debug('Middleware registered');
+    }
+    /**
+     * Run event through the middleware pipeline.
+     * Executes each middleware in order; if any skips `next()`, the event is dropped.
+     */
+    runMiddleware(event, finalCallback) {
+        if (this.middlewares.length === 0) {
+            finalCallback();
+            return;
+        }
+        let index = 0;
+        const middlewares = this.middlewares;
+        const next = () => {
+            index++;
+            if (index < middlewares.length) {
+                try {
+                    middlewares[index](event, next);
+                }
+                catch (e) {
+                    logger.error('Middleware error:', e);
+                    finalCallback();
+                }
+            }
+            else {
+                finalCallback();
+            }
+        };
+        try {
+            middlewares[0](event, next);
+        }
+        catch (e) {
+            logger.error('Middleware error:', e);
+            finalCallback();
+        }
+    }
+    // ============================================
+    // LIFECYCLE
+    // ============================================
+    /**
+     * Register a callback to be invoked when the SDK is fully initialized.
+     * If already initialized, the callback fires immediately.
+     */
+    onReady(callback) {
+        if (this.isInitialized) {
+            try {
+                callback();
+            }
+            catch (e) {
+                logger.error('onReady callback error:', e);
+            }
+        }
+        else {
+            this.readyCallbacks.push(callback);
+        }
+    }
+    /**
+     * Check if the SDK is fully initialized and ready.
+     */
+    isReady() {
+        return this.isInitialized;
+    }
     /**
      * Register a schema for event validation.
      * When debug mode is enabled, events will be validated against registered schemas.