@clianta/sdk 1.6.0 → 1.6.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (31) hide show
  1. package/README.md +250 -384
  2. package/dist/angular.cjs.js +10 -1333
  3. package/dist/angular.cjs.js.map +1 -1
  4. package/dist/angular.d.ts +0 -122
  5. package/dist/angular.esm.js +10 -1333
  6. package/dist/angular.esm.js.map +1 -1
  7. package/dist/clianta.cjs.js +10 -1335
  8. package/dist/clianta.cjs.js.map +1 -1
  9. package/dist/clianta.esm.js +11 -1334
  10. package/dist/clianta.esm.js.map +1 -1
  11. package/dist/clianta.umd.js +10 -1335
  12. package/dist/clianta.umd.js.map +1 -1
  13. package/dist/clianta.umd.min.js +2 -2
  14. package/dist/clianta.umd.min.js.map +1 -1
  15. package/dist/index.d.ts +11 -1033
  16. package/dist/react.cjs.js +10 -1333
  17. package/dist/react.cjs.js.map +1 -1
  18. package/dist/react.d.ts +0 -122
  19. package/dist/react.esm.js +10 -1333
  20. package/dist/react.esm.js.map +1 -1
  21. package/dist/svelte.cjs.js +10 -1333
  22. package/dist/svelte.cjs.js.map +1 -1
  23. package/dist/svelte.d.ts +0 -122
  24. package/dist/svelte.esm.js +10 -1333
  25. package/dist/svelte.esm.js.map +1 -1
  26. package/dist/vue.cjs.js +10 -1333
  27. package/dist/vue.cjs.js.map +1 -1
  28. package/dist/vue.d.ts +0 -122
  29. package/dist/vue.esm.js +10 -1333
  30. package/dist/vue.esm.js.map +1 -1
  31. package/package.json +2 -2
package/README.md CHANGED
@@ -1,21 +1,22 @@
1
1
  # Clianta SDK
2
2
 
3
- Professional CRM and tracking SDK for lead generation with **automated email triggers** and workflows. Works with any website or JavaScript framework.
3
+ Client-side tracking and CRM SDK for lead generation. Installs on your customer's website and automatically tracks visitors, captures forms, identifies leads, and writes data to your CRM — all from the frontend, no API key required.
4
4
 
5
5
  ## ✨ Key Features
6
6
 
7
- - 📊 **Visitor & Event Tracking** - Track page views, clicks, forms, and custom events
8
- - 👥 **CRM Management** - Contacts, companies, opportunities, tasks, and activities
9
- - 🤖 **Event Triggers & Automation** - Automated emails, tasks, and webhooks (like Salesforce & HubSpot)
10
- - 📧 **Email Notifications** - Send automated emails based on CRM actions
11
- - 🔒 **GDPR Compliant** - Built-in consent management
12
- - 🔍 **Read-Back APIs** - Fetch visitor profiles, activity, timeline, and engagement metrics
13
- - ⚡ **Framework Support** - React, Vue, Angular, Svelte, Next.js, or vanilla JavaScript
7
+ - 📊 **Auto-Tracking** — Page views, clicks, forms, scroll depth, downloads, engagement, exit intent, errors, performance
8
+ - 🔍 **Auto-Identify** — Detects email fields in forms and links anonymous visitors to CRM contacts
9
+ - 🏢 **Group & Alias** — Associate visitors with companies (`group()`) and merge identities across devices (`alias()`)
10
+ - 📱 **Screen Views** — Track mobile-first PWA / SPA screens with `screen()`
11
+ - 🔧 **Event Middleware** — Intercept, transform, or drop events before they're sent with `use()`
12
+ - 📝 **Public CRM API** — Create contacts, submit forms, log activities, create opportunities — secured by domain whitelist
13
+ - 🔒 **GDPR Compliant** — Built-in consent management with event buffering, anonymous mode, cookie-less mode
14
+ - ⚡ **Framework Support** — React, Next.js, Vue, Angular, Svelte, or vanilla JS
15
+ - 🛡️ **Error Boundary** — React ErrorBoundary ensures SDK crashes never break your client's app
16
+ - 📦 **~8KB gzipped** — Lightweight, zero dependencies
14
17
 
15
18
  ## Installation
16
19
 
17
- ### NPM / Yarn (React, Next.js, Vue)
18
-
19
20
  ```bash
20
21
  npm install @clianta/sdk
21
22
  # or
@@ -32,187 +33,168 @@ yarn add @clianta/sdk
32
33
 
33
34
  ## Quick Start
34
35
 
35
- ### Script Tag (Any Website)
36
-
37
- ```html
38
- <!-- Add before </head> -->
39
- <script src="https://cdn.clianta.online/sdk/v1/clianta.min.js"></script>
40
- <script>
41
- clianta('YOUR_WORKSPACE_ID', {
42
- apiEndpoint: 'https://api.clianta.online'
43
- });
44
- </script>
45
- ```
46
-
47
- ### NPM Module
48
-
49
- ```typescript
50
- import { clianta } from '@clianta/sdk';
51
-
52
- const tracker = clianta('YOUR_WORKSPACE_ID', {
53
- apiEndpoint: 'https://api.clianta.online',
54
- debug: true,
55
- });
56
-
57
- // Track events
58
- tracker.track('button_click', 'Signup Button', { location: 'hero' });
59
-
60
- // Identify users
61
- tracker.identify('user@example.com', { firstName: 'John' });
62
- ```
63
-
64
- ---
65
-
66
- ## Framework Guides
67
-
68
- ### Next.js (App Router)
69
-
70
- Create a provider component:
36
+ ### React / Next.js (Recommended)
71
37
 
72
38
  ```tsx
73
- // components/CliantaProvider.tsx
74
- 'use client';
75
-
76
- import { useEffect } from 'react';
77
- import { clianta } from '@clianta/sdk';
39
+ // clianta.config.ts
40
+ import type { CliantaConfig } from '@clianta/sdk';
78
41
 
79
- export function CliantaProvider({ children }: { children: React.ReactNode }) {
80
- useEffect(() => {
81
- const tracker = clianta(process.env.NEXT_PUBLIC_WORKSPACE_ID!, {
82
- apiEndpoint: process.env.NEXT_PUBLIC_API_ENDPOINT,
83
- debug: process.env.NODE_ENV === 'development',
84
- });
85
-
86
- return () => { tracker.flush(); };
87
- }, []);
42
+ const config: CliantaConfig = {
43
+ projectId: 'YOUR_WORKSPACE_ID',
44
+ debug: process.env.NODE_ENV === 'development',
45
+ };
88
46
 
89
- return <>{children}</>;
90
- }
47
+ export default config;
91
48
  ```
92
49
 
93
- Use in your layout:
94
-
95
50
  ```tsx
96
51
  // app/layout.tsx
97
- import { CliantaProvider } from '@/components/CliantaProvider';
52
+ import { CliantaProvider } from '@clianta/sdk/react';
53
+ import cliantaConfig from '../clianta.config';
98
54
 
99
55
  export default function RootLayout({ children }: { children: React.ReactNode }) {
100
56
  return (
101
57
  <html lang="en">
102
58
  <body>
103
- <CliantaProvider>{children}</CliantaProvider>
59
+ <CliantaProvider config={cliantaConfig} onError={(err) => console.error(err)}>
60
+ {children}
61
+ </CliantaProvider>
104
62
  </body>
105
63
  </html>
106
64
  );
107
65
  }
108
66
  ```
109
67
 
110
- Environment variables (`.env.local`):
111
-
112
- ```bash
113
- NEXT_PUBLIC_WORKSPACE_ID=your-workspace-id
114
- NEXT_PUBLIC_API_ENDPOINT=https://api.clianta.online
115
- ```
116
-
117
- ---
118
-
119
- ### React (Vite / CRA)
120
-
121
68
  ```tsx
122
- // App.tsx
123
- import { useEffect } from 'react';
124
- import { clianta } from '@clianta/sdk';
69
+ // Any component
70
+ import { useClianta, useCliantaReady } from '@clianta/sdk/react';
125
71
 
126
- function App() {
127
- useEffect(() => {
128
- const tracker = clianta(import.meta.env.VITE_WORKSPACE_ID, {
129
- apiEndpoint: import.meta.env.VITE_API_ENDPOINT,
130
- });
72
+ function PricingPage() {
73
+ const tracker = useClianta();
74
+ const { isReady } = useCliantaReady();
131
75
 
132
- return () => { tracker.flush(); };
133
- }, []);
76
+ const handleClick = () => {
77
+ tracker?.track('button_click', 'Get Started', { plan: 'pro' });
78
+ };
134
79
 
135
- return <div>Your App</div>;
80
+ return <button onClick={handleClick}>Get Started</button>;
136
81
  }
137
82
  ```
138
83
 
139
- Track events in components:
84
+ ### NPM Module (Vanilla)
140
85
 
141
- ```tsx
86
+ ```typescript
142
87
  import { clianta } from '@clianta/sdk';
143
88
 
144
- function SignupButton() {
145
- const handleClick = () => {
146
- const tracker = clianta(import.meta.env.VITE_WORKSPACE_ID);
147
- tracker.track('button_click', 'Signup CTA', { location: 'navbar' });
148
- };
89
+ const tracker = clianta('YOUR_WORKSPACE_ID', {
90
+ debug: true,
91
+ });
149
92
 
150
- return <button onClick={handleClick}>Sign Up</button>;
151
- }
93
+ tracker.track('button_click', 'Signup Button', { location: 'hero' });
94
+ tracker.identify('user@example.com', { firstName: 'John' });
152
95
  ```
153
96
 
154
- ---
97
+ ### Script Tag (Any Website)
155
98
 
156
- ### Vue.js
99
+ ```html
100
+ <script src="https://cdn.clianta.online/sdk/v1/clianta.min.js"></script>
101
+ <script>
102
+ var tracker = clianta('YOUR_WORKSPACE_ID');
103
+ </script>
104
+ ```
157
105
 
158
- ```typescript
159
- // plugins/clianta.ts
160
- import { clianta } from '@clianta/sdk';
106
+ **WordPress**: Add to `Appearance > Theme Editor > header.php` before `</head>`
107
+ **Webflow**: Add to `Project Settings > Custom Code > Head Code`
108
+ **Shopify**: Add to `Online Store > Themes > Edit Code > theme.liquid`
161
109
 
162
- export default {
163
- install(app: any) {
164
- const tracker = clianta(import.meta.env.VITE_WORKSPACE_ID, {
165
- apiEndpoint: import.meta.env.VITE_API_ENDPOINT,
166
- });
110
+ ---
167
111
 
168
- app.config.globalProperties.$clianta = tracker;
169
- app.provide('clianta', tracker);
170
- }
171
- };
112
+ ## Framework Integrations
113
+
114
+ ### Vue 3
115
+
116
+ ```typescript
117
+ // main.ts
118
+ import { createApp } from 'vue';
119
+ import { CliantaPlugin } from '@clianta/sdk/vue';
120
+ import App from './App.vue';
121
+
122
+ const app = createApp(App);
123
+ app.use(CliantaPlugin, {
124
+ projectId: 'YOUR_WORKSPACE_ID',
125
+ });
126
+ app.mount('#app');
172
127
  ```
173
128
 
174
129
  ```vue
175
130
  <script setup>
176
- import { inject } from 'vue';
177
- const tracker = inject('clianta');
131
+ import { useClianta, useCliantaTrack } from '@clianta/sdk/vue';
178
132
 
179
- const trackClick = () => {
180
- tracker.track('button_click', 'CTA Clicked');
181
- };
133
+ const tracker = useClianta();
134
+ const track = useCliantaTrack();
135
+
136
+ track('button_click', 'CTA Clicked', { page: 'home' });
182
137
  </script>
183
138
  ```
184
139
 
185
- ---
140
+ ### Angular
141
+
142
+ ```typescript
143
+ // clianta.service.ts
144
+ import { Injectable, OnDestroy } from '@angular/core';
145
+ import { createCliantaTracker, type CliantaTrackerInstance } from '@clianta/sdk/angular';
186
146
 
187
- ### Plain HTML / WordPress / Webflow
147
+ @Injectable({ providedIn: 'root' })
148
+ export class CliantaService implements OnDestroy {
149
+ private instance: CliantaTrackerInstance;
188
150
 
189
- ```html
190
- <!DOCTYPE html>
191
- <html>
192
- <head>
193
- <title>My Website</title>
194
-
195
- <!-- Clianta SDK -->
196
- <script src="https://cdn.clianta.online/sdk/v1/clianta.min.js"></script>
197
- <script>
198
- var tracker = clianta('YOUR_WORKSPACE_ID', {
199
- apiEndpoint: 'https://api.clianta.online'
151
+ constructor() {
152
+ this.instance = createCliantaTracker({
153
+ projectId: environment.cliantaProjectId,
200
154
  });
201
- </script>
202
- </head>
203
- <body>
204
- <button onclick="tracker.track('button_click', 'CTA Clicked')">
205
- Click Me
206
- </button>
207
- </body>
208
- </html>
155
+ }
156
+
157
+ get tracker() { return this.instance.tracker; }
158
+
159
+ track(eventType: string, eventName: string, props?: Record<string, unknown>) {
160
+ this.instance.tracker?.track(eventType, eventName, props);
161
+ }
162
+
163
+ ngOnDestroy() { this.instance.destroy(); }
164
+ }
209
165
  ```
210
166
 
211
- **WordPress**: Add to `Appearance > Theme Editor > header.php` before `</head>`
167
+ ### Svelte
212
168
 
213
- **Webflow**: Add to `Project Settings > Custom Code > Head Code`
169
+ ```svelte
170
+ <!-- +layout.svelte -->
171
+ <script>
172
+ import { initClianta } from '@clianta/sdk/svelte';
173
+ import { setContext } from 'svelte';
214
174
 
215
- **Shopify**: Add to `Online Store > Themes > Edit Code > theme.liquid`
175
+ const clianta = initClianta({
176
+ projectId: 'YOUR_WORKSPACE_ID',
177
+ });
178
+
179
+ setContext('clianta', clianta);
180
+ </script>
181
+
182
+ <slot />
183
+ ```
184
+
185
+ ```svelte
186
+ <!-- Any component -->
187
+ <script>
188
+ import { getContext } from 'svelte';
189
+ const clianta = getContext('clianta');
190
+
191
+ function handleClick() {
192
+ clianta.track('button_click', 'CTA', { page: 'home' });
193
+ }
194
+ </script>
195
+
196
+ <button on:click={handleClick}>Click Me</button>
197
+ ```
216
198
 
217
199
  ---
218
200
 
@@ -220,44 +202,30 @@ const trackClick = () => {
220
202
 
221
203
  ```typescript
222
204
  const tracker = clianta('WORKSPACE_ID', {
223
- // API endpoint (required for self-hosted)
224
- apiEndpoint: 'https://api.clianta.online',
225
-
226
- // Debug mode (console logging)
227
205
  debug: false,
228
-
229
- // Auto track page views
230
206
  autoPageView: true,
231
-
232
- // Plugins to enable
207
+
233
208
  plugins: [
234
209
  'pageView', // Page views with SPA support
235
- 'forms', // Auto-detect forms
236
- 'scroll', // Scroll depth tracking
210
+ 'forms', // Auto-detect & identify from forms
211
+ 'scroll', // Scroll depth (25%, 50%, 75%, 100%)
237
212
  'clicks', // Button/CTA clicks
238
- 'engagement', // User engagement
239
- 'downloads', // File downloads
213
+ 'engagement', // User engagement detection
214
+ 'downloads', // File download tracking
240
215
  'exitIntent', // Exit intent detection
241
- 'errors', // JavaScript errors (optional)
242
- 'performance', // Web Vitals (optional)
216
+ 'errors', // JavaScript error tracking
217
+ 'performance', // Web Vitals (LCP, FCP, CLS)
243
218
  ],
244
-
245
- // Session timeout (30 min default)
246
- sessionTimeout: 30 * 60 * 1000,
247
-
248
- // Events per batch
219
+
249
220
  batchSize: 10,
250
-
251
- // Flush interval (ms)
252
221
  flushInterval: 5000,
253
-
254
- // GDPR Consent Configuration
222
+ sessionTimeout: 30 * 60 * 1000,
223
+
255
224
  consent: {
256
- waitForConsent: true, // Buffer events until consent
257
- anonymousMode: true, // Use anonymous ID until consent
225
+ waitForConsent: true,
226
+ anonymousMode: true,
258
227
  },
259
-
260
- // Cookie-less mode (GDPR friendly)
228
+
261
229
  cookielessMode: false,
262
230
  });
263
231
  ```
@@ -266,23 +234,24 @@ const tracker = clianta('WORKSPACE_ID', {
266
234
 
267
235
  ## API Reference
268
236
 
269
- ### `tracker.track(eventType, eventName, properties?)`
270
-
271
- Track custom events:
237
+ ### Tracking
272
238
 
273
239
  ```typescript
274
- tracker.track('button_click', 'Add to Cart', {
275
- productId: '123',
276
- price: 29.99,
277
- });
278
- ```
240
+ // Custom events
241
+ tracker.track('purchase', 'Order Completed', { orderId: '123', value: 99.99 });
242
+
243
+ // Page views (auto-tracked, or manual)
244
+ tracker.page('Pricing Page', { plan: 'enterprise' });
279
245
 
280
- ### `tracker.identify(email, traits?)`
246
+ // Screen views (mobile PWAs / SPAs)
247
+ tracker.screen('Dashboard', { section: 'analytics' });
248
+ ```
281
249
 
282
- Identify a visitor:
250
+ ### Identification
283
251
 
284
252
  ```typescript
285
- tracker.identify('john@example.com', {
253
+ // Identify visitor by email → creates/links CRM contact
254
+ const contactId = await tracker.identify('john@example.com', {
286
255
  firstName: 'John',
287
256
  lastName: 'Doe',
288
257
  company: 'Acme Inc',
@@ -290,281 +259,178 @@ tracker.identify('john@example.com', {
290
259
  });
291
260
  ```
292
261
 
293
- ### `tracker.page(name?, properties?)`
294
-
295
- Track page views manually:
262
+ ### Company Association (ABM)
296
263
 
297
264
  ```typescript
298
- tracker.page('Pricing Page', { plan: 'enterprise' });
299
- ```
300
-
301
- ### `tracker.consent(state)`
302
-
303
- Update consent state (GDPR):
304
-
305
- ```typescript
306
- tracker.consent({
307
- analytics: true,
308
- marketing: false,
309
- personalization: true,
265
+ // Associate visitor with a company
266
+ tracker.group('company-123', {
267
+ name: 'Acme Inc',
268
+ industry: 'SaaS',
269
+ employees: 200,
270
+ plan: 'enterprise',
310
271
  });
272
+ // All subsequent events include groupId
311
273
  ```
312
274
 
313
- ### `tracker.getConsentState()`
314
-
315
- Get current consent:
275
+ ### Identity Merging
316
276
 
317
277
  ```typescript
318
- const state = tracker.getConsentState();
319
- // { analytics: true, marketing: false, personalization: false }
320
- ```
321
-
322
- ### `tracker.deleteData()`
278
+ // Merge anonymous visitor with a known user (cross-device)
279
+ await tracker.alias('known-user-456');
323
280
 
324
- Delete all stored data (GDPR right-to-erasure):
325
-
326
- ```typescript
327
- tracker.deleteData();
281
+ // Or merge two specific IDs
282
+ await tracker.alias('new-id', 'old-anonymous-id');
328
283
  ```
329
284
 
330
- ### `tracker.debug(enabled)`
331
-
332
- Toggle debug mode:
285
+ ### Event Middleware
333
286
 
334
287
  ```typescript
335
- tracker.debug(true); // Enable console logging
336
- ```
337
-
338
- ### `tracker.getVisitorId()` / `tracker.getSessionId()`
339
-
340
- Get current IDs:
288
+ // Strip PII before sending events
289
+ tracker.use((event, next) => {
290
+ delete event.properties.email;
291
+ delete event.properties.phone;
292
+ next(); // pass through — or don't call next() to drop the event
293
+ });
341
294
 
342
- ```typescript
343
- const visitorId = tracker.getVisitorId();
344
- const sessionId = tracker.getSessionId();
295
+ // Add custom context to all events
296
+ tracker.use((event, next) => {
297
+ event.properties.appVersion = '2.1.0';
298
+ event.properties.environment = 'production';
299
+ next();
300
+ });
345
301
  ```
346
302
 
347
- ### `tracker.flush()`
348
-
349
- Force send queued events:
303
+ ### Lifecycle
350
304
 
351
305
  ```typescript
352
- await tracker.flush();
353
- ```
354
-
355
- ### `tracker.reset()`
306
+ // Wait for SDK to be ready
307
+ tracker.onReady(() => {
308
+ console.log('Clianta SDK initialized!');
309
+ });
356
310
 
357
- Reset visitor (for logout):
311
+ // Check if ready synchronously
312
+ if (tracker.isReady()) {
313
+ tracker.track('ready_check', 'SDK Ready');
314
+ }
358
315
 
359
- ```typescript
360
- tracker.reset();
316
+ // React hook
317
+ const { isReady, tracker } = useCliantaReady();
361
318
  ```
362
319
 
363
- ---
364
-
365
- ## Read-Back APIs
366
-
367
- ### Frontend (Own Visitor Data)
320
+ ### Public CRM API
368
321
 
369
- Fetch the current visitor's data directly from the SDK:
322
+ Write CRM data directly from the frontend — no API key needed, secured by domain whitelist:
370
323
 
371
324
  ```typescript
372
- // Get visitor's CRM profile
373
- const profile = await tracker.getVisitorProfile();
374
- console.log(profile?.firstName, profile?.email, profile?.leadScore);
375
-
376
- // Get recent activity (paginated)
377
- const activity = await tracker.getVisitorActivity({ limit: 20 });
378
- activity?.data.forEach(event => {
379
- console.log(event.eventType, event.eventName, event.timestamp);
325
+ // Create or upsert a contact
326
+ await tracker.createContact({
327
+ email: 'lead@example.com',
328
+ firstName: 'Jane',
329
+ source: 'website',
380
330
  });
381
331
 
382
- // Get visitor journey timeline
383
- const timeline = await tracker.getVisitorTimeline();
384
- console.log('Total sessions:', timeline?.totalSessions);
385
- console.log('Time on site:', timeline?.totalTimeSpentSeconds, 'sec');
386
-
387
- // Get engagement metrics
388
- const engagement = await tracker.getVisitorEngagement();
389
- console.log('Score:', engagement?.engagementScore);
390
- ```
391
-
392
- ### Server-Side (Full CRM Access via API Key)
393
-
394
- ```typescript
395
- import { CRMClient } from '@clianta/sdk';
396
-
397
- const crm = new CRMClient('https://api.clianta.online', 'workspace-id');
398
- crm.setApiKey('mm_live_xxxxx');
399
-
400
- // Look up contact by email
401
- const contact = await crm.getContactByEmail('user@example.com');
402
-
403
- // Get contact's activity history
404
- const activity = await crm.getContactActivity(contact.data._id, { limit: 50 });
405
-
406
- // Get engagement metrics
407
- const engagement = await crm.getContactEngagement(contact.data._id);
408
-
409
- // Search contacts
410
- const results = await crm.searchContacts('john', { status: 'lead' });
411
-
412
- // Manage webhooks
413
- const webhooks = await crm.listWebhooks();
414
- await crm.createWebhook({ url: 'https://example.com/hook', events: ['contact.created'] });
415
- ```
416
-
417
- ---
418
-
419
- ## GDPR Compliance
420
-
421
- ### Wait for Consent
422
-
423
- Buffer all events until user grants consent:
424
-
425
- ```typescript
426
- const tracker = clianta('WORKSPACE_ID', {
427
- consent: {
428
- waitForConsent: true,
429
- },
332
+ // Submit a form (auto-creates/updates contact)
333
+ await tracker.submitForm('contact-form', {
334
+ email: 'visitor@example.com',
335
+ firstName: 'Alex',
336
+ message: 'I want a demo',
430
337
  });
431
338
 
432
- // Events are buffered...
433
- tracker.track('page_view', 'Home');
339
+ // Log an activity
340
+ await tracker.logActivity({
341
+ contactId: 'contact-123',
342
+ type: 'meeting',
343
+ subject: 'Product Demo',
344
+ });
434
345
 
435
- // User accepts cookies
436
- tracker.consent({ analytics: true });
437
- // Buffered events are now sent
346
+ // Create an opportunity
347
+ await tracker.createOpportunity({
348
+ title: 'Enterprise Deal',
349
+ contactEmail: 'lead@example.com',
350
+ value: 50000,
351
+ pipelineId: 'pipeline-1',
352
+ });
438
353
  ```
439
354
 
440
- ### Anonymous Mode
441
-
442
- Track without persistent visitor ID until consent:
355
+ ### Consent & GDPR
443
356
 
444
357
  ```typescript
358
+ // Wait for consent — events are buffered until granted
445
359
  const tracker = clianta('WORKSPACE_ID', {
446
- consent: {
447
- anonymousMode: true,
448
- },
360
+ consent: { waitForConsent: true },
449
361
  });
450
362
 
451
- // Uses temporary anon_xxx ID
452
- tracker.track('page_view', 'Home');
363
+ tracker.track('page_view', 'Home'); // buffered
453
364
 
454
- // User accepts - upgrades to persistent ID
455
- tracker.consent({ analytics: true });
456
- ```
365
+ // User accepts cookies
366
+ tracker.consent({ analytics: true, marketing: false });
367
+ // → buffered events flush automatically
457
368
 
458
- ### Cookie-less Mode
369
+ // Get current consent state
370
+ const state = tracker.getConsentState();
459
371
 
460
- No persistent storage (session only):
372
+ // Delete all stored data (GDPR right-to-erasure)
373
+ tracker.deleteData();
461
374
 
462
- ```typescript
463
- const tracker = clianta('WORKSPACE_ID', {
464
- cookielessMode: true,
465
- });
466
- // Visitor ID stored in sessionStorage only
375
+ // Cookie-less mode (session only, no persistent storage)
376
+ const tracker = clianta('WORKSPACE_ID', { cookielessMode: true });
467
377
  ```
468
378
 
469
- ### Data Deletion
470
-
471
- Allow users to delete their data:
379
+ ### Utility
472
380
 
473
381
  ```typescript
474
- function handleDeleteDataRequest() {
475
- tracker.deleteData();
476
- showConfirmation('Your data has been deleted');
477
- }
382
+ tracker.getVisitorId(); // Current anonymous visitor ID
383
+ tracker.getSessionId(); // Current session ID
384
+ tracker.getWorkspaceId(); // Workspace this tracker belongs to
385
+ await tracker.flush(); // Force send queued events
386
+ tracker.reset(); // Reset visitor (for logout)
387
+ tracker.debug(true); // Enable console logging
478
388
  ```
479
389
 
480
390
  ---
481
391
 
482
392
  ## TypeScript
483
393
 
484
- Full TypeScript support included:
394
+ Full TypeScript support with type exports:
485
395
 
486
396
  ```typescript
487
397
  import {
488
398
  clianta,
489
399
  type TrackerCore,
490
- type MorrisBConfig,
400
+ type CliantaConfig,
491
401
  type ConsentState,
492
402
  type TrackingEvent,
403
+ type GroupTraits,
404
+ type MiddlewareFn,
405
+ type PublicContactData,
406
+ type PublicFormSubmission,
407
+ type PublicCrmResult,
493
408
  } from '@clianta/sdk';
494
409
  ```
495
410
 
496
411
  ---
497
412
 
498
- ## Event Triggers & Automation
413
+ ## What Gets Auto-Tracked
499
414
 
500
- Automate your workflows with event-driven triggers. Send emails, create tasks, or call webhooks when specific actions occur.
415
+ Once installed, the SDK automatically captures (no code needed):
501
416
 
502
- ### Quick Example
417
+ | Event | Data Collected |
418
+ |-------|---------------|
419
+ | **Page Views** | URL, title, referrer, SPA navigation |
420
+ | **Form Submissions** | All form fields, auto-identifies by email |
421
+ | **Scroll Depth** | 25%, 50%, 75%, 100% milestones |
422
+ | **Button Clicks** | Element text, ID, CSS selector |
423
+ | **Downloads** | File URL, extension, click source |
424
+ | **Engagement** | Time on page, active vs idle |
425
+ | **Exit Intent** | Mouse leaving viewport (desktop) |
426
+ | **Errors** | Error message, stack trace, URL |
427
+ | **Performance** | LCP, FCP, CLS, TTFB (Web Vitals) |
503
428
 
504
- ```typescript
505
- import { CRMClient } from '@clianta/sdk';
506
-
507
- const crm = new CRMClient(
508
- 'https://api.clianta.online',
509
- 'your-workspace-id',
510
- 'your-auth-token'
511
- );
512
-
513
- // Send welcome email when a contact is created
514
- await crm.createEventTrigger({
515
- name: 'Welcome Email',
516
- eventType: 'contact.created',
517
- actions: [
518
- {
519
- type: 'send_email',
520
- to: '{{contact.email}}',
521
- subject: 'Welcome to Our Platform!',
522
- body: 'Hello {{contact.firstName}}, welcome aboard!',
523
- }
524
- ],
525
- isActive: true,
526
- });
527
-
528
- // Create task when high-value opportunity is created
529
- await crm.triggers.createTaskTrigger({
530
- name: 'Follow-up Task',
531
- eventType: 'opportunity.created',
532
- taskTitle: 'Call {{contact.firstName}} about {{opportunity.title}}',
533
- priority: 'high',
534
- dueDays: 1,
535
- conditions: [
536
- { field: 'value', operator: 'greater_than', value: 10000 }
537
- ],
538
- });
539
- ```
540
-
541
- ### Supported Event Types
542
-
543
- - **Contact Events**: `contact.created`, `contact.updated`, `contact.deleted`
544
- - **Opportunity Events**: `opportunity.created`, `opportunity.won`, `opportunity.stage_changed`
545
- - **Task Events**: `task.created`, `task.completed`, `task.overdue`
546
- - **Activity Events**: `activity.logged`, `form.submitted`
547
-
548
- ### Action Types
549
-
550
- 1. **Send Email** - Automated email notifications with template variables
551
- 2. **Create Task** - Auto-create follow-up tasks
552
- 3. **Webhook** - Call external services (Slack, Zapier, etc.)
553
- 4. **Update Contact** - Automatically update contact fields
554
-
555
- 📚 **[Full Event Triggers Documentation](./docs/EVENT_TRIGGERS.md)**
429
+ Every event is enriched with: `visitorId`, `sessionId`, `contactId` (if identified), `groupId` (if grouped), UTM parameters, device info, and `websiteDomain`.
556
430
 
557
431
  ---
558
432
 
559
- ## Self-Hosted
560
-
561
- For self-hosted deployments, configure the API endpoint:
562
433
 
563
- ```typescript
564
- const tracker = clianta('WORKSPACE_ID', {
565
- apiEndpoint: 'https://your-backend.com',
566
- });
567
- ```
568
434
 
569
435
  ---
570
436