@clianta/sdk 1.4.0 → 1.5.1

package/dist/index.d.ts

@@ -225,7 +225,7 @@ declare 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({
@@ -477,6 +477,86 @@ declare class CRMClient {
     }): Promise<ApiResponse<{
         messageId: string;
     }>>;
+    /**
+     * Get a contact by email address.
+     * Returns the first matching contact from a search query.
+     */
+    getContactByEmail(email: string): Promise<ApiResponse<PaginatedResponse<Contact>>>;
+    /**
+     * Get activity timeline for a contact
+     */
+    getContactActivity(contactId: string, params?: {
+        page?: number;
+        limit?: number;
+        type?: string;
+        startDate?: string;
+        endDate?: string;
+    }): Promise<ApiResponse<PaginatedResponse<Activity>>>;
+    /**
+     * Get engagement metrics for a contact (via their linked visitor data)
+     */
+    getContactEngagement(contactId: string): Promise<ApiResponse<{
+        totalTimeOnSiteSeconds: number;
+        averageSessionDurationSeconds: number;
+        totalPageViews: number;
+        totalSessions: number;
+        engagementScore: number;
+        lastActiveAt: string;
+    }>>;
+    /**
+     * Get a full timeline for a contact including events, activities, and opportunities
+     */
+    getContactTimeline(contactId: string, params?: {
+        page?: number;
+        limit?: number;
+    }): Promise<ApiResponse<PaginatedResponse<{
+        type: 'event' | 'activity' | 'opportunity' | 'note';
+        title: string;
+        description?: string;
+        timestamp: string;
+        metadata?: Record<string, unknown>;
+    }>>>;
+    /**
+     * Search contacts with advanced filters
+     */
+    searchContacts(query: string, filters?: {
+        status?: string;
+        lifecycleStage?: string;
+        source?: string;
+        tags?: string[];
+        page?: number;
+        limit?: number;
+    }): Promise<ApiResponse<PaginatedResponse<Contact>>>;
+    /**
+     * List all webhook subscriptions
+     */
+    listWebhooks(params?: {
+        page?: number;
+        limit?: number;
+    }): Promise<ApiResponse<PaginatedResponse<{
+        _id: string;
+        url: string;
+        events: string[];
+        isActive: boolean;
+        createdAt: string;
+    }>>>;
+    /**
+     * Create a new webhook subscription
+     */
+    createWebhook(data: {
+        url: string;
+        events: string[];
+        secret?: string;
+    }): Promise<ApiResponse<{
+        _id: string;
+        url: string;
+        events: string[];
+        isActive: boolean;
+    }>>;
+    /**
+     * Delete a webhook subscription
+     */
+    deleteWebhook(webhookId: string): Promise<ApiResponse<void>>;
     /**
      * Get all event triggers
      */
@@ -528,6 +608,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 {
@@ -631,8 +713,34 @@ 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>;
+    /** Create or update a contact by email (upsert) */
+    createContact(data: PublicContactData): Promise<PublicCrmResult>;
+    /** Update an existing contact by ID (limited fields) */
+    updateContact(contactId: string, data: PublicContactUpdate): Promise<PublicCrmResult>;
+    /** Submit a form — creates/updates contact from form data */
+    submitForm(formId: string, data: PublicFormSubmission): Promise<PublicCrmResult>;
+    /** Log an activity linked to a contact (append-only) */
+    logActivity(data: PublicActivityData): Promise<PublicCrmResult>;
+    /** Create an opportunity (e.g., from "Request Demo" forms) */
+    createOpportunity(data: PublicOpportunityData): Promise<PublicCrmResult>;
 }
 interface Contact {
     _id?: string;
@@ -892,11 +1000,139 @@ interface TriggerExecution {
     /** Execution timestamp */
     executedAt: string;
 }
-
-/**
- * Clianta SDK - Main Tracker Class
- * @see SDK_VERSION in core/config.ts
- */
+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 ContactTimelineOptions {
+    page?: number;
+    limit?: number;
+    includeEvents?: boolean;
+    includeActivities?: boolean;
+    includeOpportunities?: boolean;
+}
+interface PublicContactData {
+    email: string;
+    firstName?: string;
+    lastName?: string;
+    company?: string;
+    jobTitle?: string;
+    phone?: string;
+    source?: string;
+    tags?: string[];
+    customFields?: Record<string, unknown>;
+}
+interface PublicContactUpdate {
+    firstName?: string;
+    lastName?: string;
+    company?: string;
+    jobTitle?: string;
+    phone?: string;
+    tags?: string[];
+    customFields?: Record<string, unknown>;
+}
+interface PublicActivityData {
+    contactId: string;
+    type: 'call' | 'email' | 'meeting' | 'note' | 'other';
+    title: string;
+    description?: string;
+    direction?: 'inbound' | 'outbound';
+    duration?: number;
+    emailSubject?: string;
+    metadata?: Record<string, unknown>;
+}
+interface PublicOpportunityData {
+    title: string;
+    contactId: string;
+    pipelineId: string;
+    stageId: string;
+    value?: number;
+    currency?: string;
+    description?: string;
+    expectedCloseDate?: string;
+    customFields?: Record<string, unknown>;
+}
+interface PublicFormSubmission {
+    fields: Record<string, unknown>;
+    metadata?: {
+        visitorId?: string;
+        sessionId?: string;
+        pageUrl?: string;
+        referrer?: string;
+    };
+}
+interface PublicCrmResult {
+    success: boolean;
+    data?: Record<string, unknown>;
+    error?: string;
+    status?: number;
+}
 
 /**
  * Main Clianta Tracker Class
@@ -915,6 +1151,8 @@ declare class Tracker implements TrackerCore {
     private contactId;
     /** Pending identify retry on next flush */
     private pendingIdentify;
+    /** Registered event schemas for validation */
+    private eventSchemas;
     constructor(workspaceId: string, userConfig?: CliantaConfig);
     /**
      * Create visitor ID based on storage mode
@@ -952,6 +1190,35 @@ declare class Tracker implements TrackerCore {
      * Convenience proxy to CRMClient.sendEvent() — requires apiKey in config.
      */
     sendEvent(payload: InboundEventPayload): Promise<InboundEventResult>;
+    /**
+     * 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).
+     */
+    getVisitorProfile(): Promise<VisitorProfile | null>;
+    /**
+     * Get the current visitor's recent activity/events.
+     * Returns paginated list of tracking events for this visitor.
+     */
+    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.
+     * Includes top pages, sessions, time spent, and recent activities.
+     */
+    getVisitorTimeline(): Promise<VisitorTimeline | null>;
+    /**
+     * Get engagement metrics for the current visitor.
+     * Includes time on site, page views, bounce rate, and engagement score.
+     */
+    getVisitorEngagement(): Promise<EngagementMetrics | null>;
     /**
      * Retry pending identify call
      */
@@ -968,6 +1235,22 @@ declare class Tracker implements TrackerCore {
      * Toggle debug mode
      */
     debug(enabled: boolean): void;
+    /**
+     * Register a schema for event validation.
+     * When debug mode is enabled, events will be validated against registered schemas.
+     *
+     * @example
+     * tracker.registerEventSchema('purchase', {
+     *   productId: 'string',
+     *   price: 'number',
+     *   quantity: 'number',
+     * });
+     */
+    registerEventSchema(eventType: string, schema: Record<string, 'string' | 'number' | 'boolean' | 'object' | 'array'>): void;
+    /**
+     * Validate event properties against a registered schema (debug mode only)
+     */
+    private validateEventSchema;
     /**
      * Get visitor ID
      */
@@ -996,6 +1279,31 @@ declare class Tracker implements TrackerCore {
      * Delete all stored user data (GDPR right-to-erasure)
      */
     deleteData(): void;
+    /**
+     * Create or update a contact by email (upsert).
+     * Secured by domain whitelist — no API key needed.
+     */
+    createContact(data: PublicContactData): Promise<PublicCrmResult>;
+    /**
+     * Update an existing contact by ID (limited fields only).
+     */
+    updateContact(contactId: string, data: PublicContactUpdate): Promise<PublicCrmResult>;
+    /**
+     * Submit a form — creates/updates contact from form data.
+     */
+    submitForm(formId: string, data: PublicFormSubmission): Promise<PublicCrmResult>;
+    /**
+     * Log an activity linked to a contact (append-only).
+     */
+    logActivity(data: PublicActivityData): Promise<PublicCrmResult>;
+    /**
+     * Create an opportunity (e.g., from "Request Demo" forms).
+     */
+    createOpportunity(data: PublicOpportunityData): Promise<PublicCrmResult>;
+    /**
+     * Internal helper for public CRM API calls.
+     */
+    private publicCrmRequest;
     /**
      * Destroy tracker and cleanup
      */
@@ -1133,4 +1441,4 @@ declare const SDK_VERSION = "1.4.0";
 declare function clianta(workspaceId: string, config?: CliantaConfig): TrackerCore;
 
 export { CRMClient, ConsentManager, EventTriggersManager, SDK_VERSION, Tracker, clianta, clianta as default };
-export type { Activity, ApiResponse, CliantaConfig, Company, ConsentChangeCallback, ConsentConfig, ConsentManagerConfig, ConsentState, Contact, ContactUpdateAction, EmailAction, EmailTemplate, EventTrigger, EventType, InboundEventPayload, InboundEventResult, InboundEventType, Opportunity, PaginatedResponse, Pipeline, PipelineStage, Plugin, PluginName, StoredConsent, Task, TaskAction, TrackerCore, TrackingEvent, TriggerAction, TriggerCondition, TriggerEventType, TriggerExecution, UserTraits, WebhookAction };
+export type { Activity, ApiResponse, CliantaConfig, Company, ConsentChangeCallback, ConsentConfig, ConsentManagerConfig, ConsentState, Contact, ContactTimelineOptions, ContactUpdateAction, EmailAction, EmailTemplate, EngagementMetrics, EventTrigger, EventType, InboundEventPayload, InboundEventResult, InboundEventType, Opportunity, PaginatedResponse, Pipeline, PipelineStage, Plugin, PluginName, PublicActivityData, PublicContactData, PublicContactUpdate, PublicCrmResult, PublicFormSubmission, PublicOpportunityData, StoredConsent, Task, TaskAction, TrackerCore, TrackingEvent, TriggerAction, TriggerCondition, TriggerEventType, TriggerExecution, UserTraits, VisitorActivity, VisitorActivityOptions, VisitorProfile, VisitorTimeline, WebhookAction };