@clianta/sdk 1.3.0 → 1.5.0

package/dist/react.d.ts

@@ -1,6 +1,36 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import { ReactNode } from 'react';
 
+/**
+ * Clianta SDK - CRM API Client
+ * @see SDK_VERSION in core/config.ts
+ */
+
+type InboundEventType = 'user.registered' | 'user.updated' | 'user.subscribed' | 'user.unsubscribed' | 'contact.created' | 'contact.updated' | 'purchase.completed';
+interface InboundEventPayload {
+    /** Event type (e.g. "user.registered") */
+    event: InboundEventType;
+    /** Contact data — at least email or phone is required */
+    contact: {
+        email?: string;
+        phone?: string;
+        firstName?: string;
+        lastName?: string;
+        company?: string;
+        jobTitle?: string;
+        tags?: string[];
+    };
+    /** Optional extra data stored as customFields on the contact */
+    data?: Record<string, unknown>;
+}
+interface InboundEventResult {
+    success: boolean;
+    contactCreated: boolean;
+    contactId?: string;
+    event: string;
+    error?: string;
+}
+
 /**
  * Clianta SDK - Type Definitions
  * @see SDK_VERSION in core/config.ts
@@ -10,8 +40,10 @@ interface CliantaConfig {
     projectId?: string;
     /** Backend API endpoint URL */
     apiEndpoint?: string;
-    /** Auth token for server-side API access */
+    /** Auth token for server-side API access (user JWT) */
     authToken?: string;
+    /** Workspace API key for server-to-server access (use instead of authToken for external apps) */
+    apiKey?: string;
     /** Enable debug mode with verbose logging */
     debug?: boolean;
     /** Automatically track page views on load and navigation */
@@ -32,6 +64,8 @@ interface CliantaConfig {
     useCookies?: boolean;
     /** Cookie-less mode: use sessionStorage only (no persistent storage) */
     cookielessMode?: boolean;
+    /** Queue persistence mode: 'session' (default), 'local' (survives browser restart), 'none' */
+    persistMode?: 'session' | 'local' | 'none';
 }
 type PluginName = 'pageView' | 'forms' | 'scroll' | 'clicks' | 'engagement' | 'downloads' | 'exitIntent' | 'errors' | 'performance' | 'popupForms';
 interface ConsentConfig {
@@ -64,8 +98,8 @@ interface UserTraits {
 interface TrackerCore {
     /** Track a custom event */
     track(eventType: EventType | string, eventName: string, properties?: Record<string, unknown>): void;
-    /** Identify a visitor */
-    identify(email: string, traits?: UserTraits): void;
+    /** Identify a visitor — returns the contactId if successful */
+    identify(email: string, traits?: UserTraits): Promise<string | null>;
     /** Track a page view */
     page(name?: string, properties?: Record<string, unknown>): void;
     /** Update consent state */
@@ -88,6 +122,94 @@ interface TrackerCore {
     deleteData(): void;
     /** Get current consent state */
     getConsentState(): ConsentState;
+    /** Get the current visitor's profile from the CRM */
+    getVisitorProfile(): Promise<VisitorProfile | null>;
+    /** Get the current visitor's recent activity */
+    getVisitorActivity(options?: VisitorActivityOptions): Promise<{
+        data: VisitorActivity[];
+        pagination: {
+            page: number;
+            limit: number;
+            total: number;
+            pages: number;
+        };
+    } | null>;
+    /** Get a summarized journey timeline for the current visitor */
+    getVisitorTimeline(): Promise<VisitorTimeline | null>;
+    /** Get engagement metrics for the current visitor */
+    getVisitorEngagement(): Promise<EngagementMetrics | null>;
+    /** Send a server-side inbound event (requires apiKey in config) */
+    sendEvent(payload: InboundEventPayload): Promise<InboundEventResult>;
+}
+interface VisitorProfile {
+    visitorId: string;
+    contactId?: string;
+    email?: string;
+    firstName?: string;
+    lastName?: string;
+    company?: string;
+    jobTitle?: string;
+    phone?: string;
+    status?: string;
+    lifecycleStage?: string;
+    tags?: string[];
+    leadScore?: number;
+    firstSeen?: string;
+    lastSeen?: string;
+    sessionCount?: number;
+    pageViewCount?: number;
+    totalTimeSpent?: number;
+    customFields?: Record<string, unknown>;
+}
+interface VisitorActivity {
+    _id?: string;
+    eventType: string;
+    eventName: string;
+    url: string;
+    properties?: Record<string, unknown>;
+    timestamp: string;
+}
+interface VisitorTimeline {
+    visitorId: string;
+    contactId?: string;
+    firstSeen: string;
+    lastSeen: string;
+    totalSessions: number;
+    totalPageViews: number;
+    totalEvents: number;
+    totalTimeSpentSeconds: number;
+    averageSessionDurationSeconds: number;
+    topPages: Array<{
+        url: string;
+        views: number;
+        avgTimeSeconds?: number;
+    }>;
+    recentActivities: VisitorActivity[];
+    devices: Array<{
+        userAgent: string;
+        lastSeen: string;
+    }>;
+}
+interface EngagementMetrics {
+    visitorId: string;
+    totalTimeOnSiteSeconds: number;
+    averageSessionDurationSeconds: number;
+    totalPageViews: number;
+    totalSessions: number;
+    engagementScore: number;
+    bounceRate: number;
+    lastActiveAt: string;
+    topEvents: Array<{
+        eventType: string;
+        count: number;
+    }>;
+}
+interface VisitorActivityOptions {
+    page?: number;
+    limit?: number;
+    eventType?: string;
+    startDate?: string;
+    endDate?: string;
 }
 
 interface CliantaProviderProps {