@clianta/sdk 1.5.0 → 1.6.0

package/CHANGELOG.md

@@ -5,6 +5,42 @@ 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
+- **Public CRM API** — Frontend-safe CRM methods that don't require an API key (secured by domain whitelist):
+  - `createContact()` — Create or upsert a contact by email
+  - `updateContact()` — Update an existing contact by ID
+  - `submitForm()` — Submit a form and auto-create/update contact
+  - `logActivity()` — Append an activity to a contact
+  - `createOpportunity()` — Create an opportunity (e.g., from "Request Demo" forms)
+- **Public CRM types** — `PublicContactData`, `PublicContactUpdate`, `PublicFormSubmission`, `PublicActivityData`, `PublicOpportunityData`, `PublicCrmResult`
+- **Updated docs** — API Reference and Getting Started guides updated with public CRM usage
+
+### Changed
+- Config: improved `getDefaultApiEndpoint()` with env variable support
+- Framework integrations: minor fixes for Angular, Svelte, Vue, React
+
 ## [1.5.0] - 2026-02-28
 
 ### Security

package/dist/angular.cjs.js

@@ -1,5 +1,5 @@
 /*!
- * Clianta SDK v1.5.0
+ * Clianta SDK v1.6.0
  * (c) 2026 Clianta
  * Released under the MIT License.
  */
@@ -10,16 +10,23 @@
  * @see SDK_VERSION in core/config.ts
  */
 /** SDK Version */
-const SDK_VERSION = '1.4.0';
-/** Default API endpoint based on environment */
+const SDK_VERSION = '1.6.0';
+/** Default API endpoint — reads from env or falls back to localhost */
 const getDefaultApiEndpoint = () => {
-    if (typeof window === 'undefined')
-        return 'https://api.clianta.online';
-    const hostname = window.location.hostname;
-    if (hostname.includes('localhost') || hostname.includes('127.0.0.1')) {
-        return 'http://localhost:5000';
+    // Build-time env var (works with Next.js, Vite, CRA, etc.)
+    if (typeof process !== 'undefined' && process.env?.NEXT_PUBLIC_CLIANTA_API_ENDPOINT) {
+        return process.env.NEXT_PUBLIC_CLIANTA_API_ENDPOINT;
+    }
+    if (typeof process !== 'undefined' && process.env?.VITE_CLIANTA_API_ENDPOINT) {
+        return process.env.VITE_CLIANTA_API_ENDPOINT;
+    }
+    if (typeof process !== 'undefined' && process.env?.REACT_APP_CLIANTA_API_ENDPOINT) {
+        return process.env.REACT_APP_CLIANTA_API_ENDPOINT;
+    }
+    if (typeof process !== 'undefined' && process.env?.CLIANTA_API_ENDPOINT) {
+        return process.env.CLIANTA_API_ENDPOINT;
     }
-    return 'https://api.clianta.online';
+    return 'http://localhost:5000';
 };
 /** Core plugins enabled by default */
 const DEFAULT_PLUGINS = [
@@ -1781,7 +1788,7 @@ class PopupFormsPlugin extends BasePlugin {
             return;
         const config = this.tracker.getConfig();
         const workspaceId = this.tracker.getWorkspaceId();
-        const apiEndpoint = config.apiEndpoint || 'https://api.clianta.online';
+        const apiEndpoint = config.apiEndpoint || 'http://localhost:5000';
         try {
             const url = encodeURIComponent(window.location.href);
             const response = await fetch(`${apiEndpoint}/api/public/lead-forms/${workspaceId}?url=${url}`);
@@ -1886,7 +1893,7 @@ class PopupFormsPlugin extends BasePlugin {
         if (!this.tracker)
             return;
         const config = this.tracker.getConfig();
-        const apiEndpoint = config.apiEndpoint || 'https://api.clianta.online';
+        const apiEndpoint = config.apiEndpoint || 'http://localhost:5000';
         try {
             await fetch(`${apiEndpoint}/api/public/lead-forms/${formId}/view`, {
                 method: 'POST',
@@ -2133,7 +2140,7 @@ class PopupFormsPlugin extends BasePlugin {
         if (!this.tracker)
             return;
         const config = this.tracker.getConfig();
-        const apiEndpoint = config.apiEndpoint || 'https://api.clianta.online';
+        const apiEndpoint = config.apiEndpoint || 'http://localhost:5000';
         const visitorId = this.tracker.getVisitorId();
         // Collect form data
         const formData = new FormData(formElement);
@@ -3028,7 +3035,7 @@ class CRMClient {
      * The contact is upserted in the CRM and matching workflow automations fire automatically.
      *
      * @example
-     * const crm = new CRMClient('https://api.clianta.online', 'WORKSPACE_ID');
+     * const crm = new CRMClient('http://localhost:5000', 'WORKSPACE_ID');
      * crm.setApiKey('mm_live_...');
      *
      * await crm.sendEvent({
@@ -3685,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
@@ -3698,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');
         }
@@ -3727,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' &&
@@ -3741,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
@@ -3853,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
@@ -3866,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
@@ -3929,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
@@ -4033,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.
@@ -4168,6 +4389,86 @@ class Tracker {
         this.sessionId = this.createSessionId();
         logger.info('All user data deleted');
     }
+    // ============================================
+    // PUBLIC CRM METHODS (no API key required)
+    // ============================================
+    /**
+     * Create or update a contact by email (upsert).
+     * Secured by domain whitelist — no API key needed.
+     */
+    async createContact(data) {
+        return this.publicCrmRequest('/api/public/crm/contacts', 'POST', {
+            workspaceId: this.workspaceId,
+            ...data,
+        });
+    }
+    /**
+     * Update an existing contact by ID (limited fields only).
+     */
+    async updateContact(contactId, data) {
+        return this.publicCrmRequest(`/api/public/crm/contacts/${contactId}`, 'PUT', {
+            workspaceId: this.workspaceId,
+            ...data,
+        });
+    }
+    /**
+     * Submit a form — creates/updates contact from form data.
+     */
+    async submitForm(formId, data) {
+        const payload = {
+            ...data,
+            metadata: {
+                ...data.metadata,
+                visitorId: this.visitorId,
+                sessionId: this.sessionId,
+                pageUrl: typeof window !== 'undefined' ? window.location.href : undefined,
+                referrer: typeof document !== 'undefined' ? document.referrer || undefined : undefined,
+            },
+        };
+        return this.publicCrmRequest(`/api/public/crm/forms/${formId}/submit`, 'POST', payload);
+    }
+    /**
+     * Log an activity linked to a contact (append-only).
+     */
+    async logActivity(data) {
+        return this.publicCrmRequest('/api/public/crm/activities', 'POST', {
+            workspaceId: this.workspaceId,
+            ...data,
+        });
+    }
+    /**
+     * Create an opportunity (e.g., from "Request Demo" forms).
+     */
+    async createOpportunity(data) {
+        return this.publicCrmRequest('/api/public/crm/opportunities', 'POST', {
+            workspaceId: this.workspaceId,
+            ...data,
+        });
+    }
+    /**
+     * Internal helper for public CRM API calls.
+     */
+    async publicCrmRequest(path, method, body) {
+        const url = `${this.config.apiEndpoint}${path}`;
+        try {
+            const response = await fetch(url, {
+                method,
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify(body),
+            });
+            const data = await response.json().catch(() => ({}));
+            if (response.ok) {
+                logger.debug(`Public CRM ${method} ${path} succeeded`);
+                return { success: true, data: data.data ?? data, status: response.status };
+            }
+            logger.error(`Public CRM ${method} ${path} failed (${response.status}):`, data.message);
+            return { success: false, error: data.message, status: response.status };
+        }
+        catch (error) {
+            logger.error(`Public CRM ${method} ${path} error:`, error);
+            return { success: false, error: error.message };
+        }
+    }
     /**
      * Destroy tracker and cleanup
      */
@@ -4292,7 +4593,7 @@ if (typeof window !== 'undefined') {
  * @example
  * const instance = createCliantaTracker({
  *   projectId: 'your-project-id',
- *   apiEndpoint: 'https://api.clianta.online',
+ *   apiEndpoint: environment.cliantaApiEndpoint || 'http://localhost:5000',
  * });
  *
  * instance.tracker?.track('page_view', 'Home Page');