@li2/analytics 0.2.3 → 0.3.1-beta.0

package/dist/index.d.ts

@@ -1,9 +1,98 @@
+import { P as PageviewTracker } from './index-B3dzYzIM.js';
+export { c as PageviewBatchPayload, a as PageviewConfig, b as PageviewEvent } from './index-B3dzYzIM.js';
 export { AnalyticsSettings, AutoEvent, ConditionOperator, ConditionType, EventAction, EventActionType, EventTrigger, TriggerCondition, TriggerType } from './auto-events.js';
+export { ClickTrackerConfig } from './click-tracker/index.js';
+
+/**
+ * Batch sender for click interaction events.
+ * Same pattern as pageview BatchSender but sends to /api/v1/track/interaction.
+ */
+interface InteractionEvent {
+    /** Client-generated session ID */
+    session_id: string;
+    /** Persistent visitor ID */
+    visitor_id: string;
+    /** Li2 click ID if visitor came from short link */
+    li2_cid: string | null;
+    /** Full page URL */
+    page_url: string;
+    /** URL path only */
+    page_path: string;
+    /** Absolute X position (scroll-adjusted unless fixed) */
+    x: number;
+    /** Absolute Y position (scroll-adjusted unless fixed) */
+    y: number;
+    /** Whether clicked element has position: fixed/sticky */
+    target_fixed: boolean;
+    /** Browser viewport dimensions */
+    viewport_width: number;
+    viewport_height: number;
+    /** Total scrollable page height */
+    page_height: number;
+    /** Scroll Y at click time */
+    scroll_y: number;
+    /** Element tag name (lowercase) */
+    element_tag: string;
+    /** Element innerText (truncated to 256 chars) */
+    element_text: string;
+    /** href attribute if link element */
+    element_href: string | null;
+    /** className (truncated to 512 chars) */
+    element_class: string;
+    /** id attribute */
+    element_id: string | null;
+    /** Stable CSS selector path */
+    selector_path: string;
+    /** Interaction type (click, scroll, etc.) */
+    interaction_type: string;
+    /** Unix timestamp in milliseconds */
+    timestamp: number;
+}
+interface InteractionBatchPayload {
+    interactions: InteractionEvent[];
+}
+
+/**
+ * Element metadata extraction for click capture.
+ * Resolves clicked elements to meaningful ancestors and builds stable CSS selectors.
+ */
+interface ElementInfo {
+    /** HTML tag name (lowercase) */
+    tag: string;
+    /** innerText truncated to 256 chars */
+    text: string;
+    /** href attribute if link element */
+    href: string | null;
+    /** className truncated to 512 chars */
+    className: string;
+    /** id attribute */
+    id: string | null;
+    /** Stable CSS selector path (tag + nth-child hierarchy) */
+    selectorPath: string;
+    /** Whether element or ancestor has position: fixed/sticky */
+    isFixed: boolean;
+}
+
+/**
+ * Coordinate calculation for click capture.
+ * Handles fixed/sticky element positioning and scroll adjustment.
+ */
+interface ClickCoordinates {
+    /** Absolute X position (scroll-adjusted unless fixed) */
+    x: number;
+    /** Absolute Y position (scroll-adjusted unless fixed) */
+    y: number;
+    /** Current scroll Y at click time */
+    scrollY: number;
+    /** Total scrollable page height */
+    pageHeight: number;
+}
 
 /**
  * Li2 Analytics SDK
  * Conversion tracking for li2.ai
  */
+
 interface Li2Config {
     /** Publishable key from your organization's analytics settings */
     publishableKey?: string;
@@ -142,12 +231,66 @@ declare class Li2Analytics {
     private clickId;
     private cookieOptions;
     private autoEventTracker;
+    private clickTracker;
+    pageview: PageviewTracker | null;
     constructor(config?: Li2Config);
     private log;
     /**
      * Initialize auto-event tracking
      */
     private initAutoEventTracking;
+    /**
+     * Initialize pageview tracking from data-attributes or config.
+     * Uses dynamic import to lazy-load the pageview module only when enabled.
+     * @internal Called from auto-init block - not part of public API
+     */
+    initPageviewTracking(pageviewConfig: Record<string, string>): Promise<void>;
+    /**
+     * Enable pageview tracking programmatically (for users not using data-attributes)
+     */
+    enablePageviewTracking(options?: {
+        spaMode?: "auto" | "manual" | "disabled";
+        excludePatterns?: string[];
+        trackHashChanges?: boolean;
+        sessionTimeout?: number;
+        cookieLessMode?: boolean;
+        batchInterval?: number;
+        searchParams?: string[];
+        cookieDomain?: string;
+        cookiePath?: string;
+    }): Promise<void>;
+    /**
+     * Initialize click tracking from data-attributes.
+     * Uses dynamic import to lazy-load the click-tracker module only when enabled.
+     * @internal Called from auto-init block - not part of public API
+     */
+    initClickTracking(clickConfig: Record<string, string>): Promise<void>;
+    /**
+     * Enable click tracking programmatically (for users not using data-attributes)
+     */
+    enableClickTracking(options?: {
+        batchInterval?: number;
+        excludeSelector?: string;
+        sessionTimeout?: number;
+        cookieLessMode?: boolean;
+        cookieDomain?: string;
+        cookiePath?: string;
+    }): Promise<void>;
+    /**
+     * Manually track a pageview (convenience method)
+     */
+    trackPageview(options?: {
+        pageUrl?: string;
+        pageTitle?: string;
+        customData?: Record<string, unknown>;
+    }): void;
+    /**
+     * Track a named event (sent through the pageview pipeline with event_name set)
+     * Auto-initializes PageviewTracker if not already running.
+     */
+    trackEvent(eventName: string, options?: {
+        category?: string;
+    }): Promise<void>;
     /**
      * Set cookie options for customizing cookie behavior
      * If a clickId already exists, the cookie will be re-set with the new options
@@ -269,6 +412,22 @@ declare function identify(params: {
     customerId?: string;
     message?: string;
 }>;
+/**
+ * Track a pageview manually
+ * Convenience function that uses the singleton instance
+ */
+declare function trackPageview(options?: {
+    pageUrl?: string;
+    pageTitle?: string;
+    customData?: Record<string, unknown>;
+}): void;
+/**
+ * Track a named event
+ * Convenience function that uses the singleton instance
+ */
+declare function trackEvent(eventName: string, options?: {
+    category?: string;
+}): Promise<void>;
 
 /**
  * Initialize the server-side Li2 Analytics SDK
@@ -280,10 +439,12 @@ declare const _default: {
     getInstance: typeof getInstance;
     trackLead: typeof trackLead;
     trackSale: typeof trackSale;
+    trackEvent: typeof trackEvent;
     identify: typeof identify;
     isTrackingAvailable: typeof isTrackingAvailable;
     getClickId: typeof getClickId;
+    trackPageview: typeof trackPageview;
     initServer: typeof initServer;
 };
 
-export { type CookieOptions, Li2Analytics, type Li2Config, Li2ServerAnalytics, type Li2ServerConfig, type ServerTrackLeadParams, type ServerTrackSaleParams, type TrackLeadParams, type TrackLeadResponse, type TrackSaleParams, type TrackSaleResponse, _default as default, getClickId, getInstance, identify, init, initServer, isTrackingAvailable, trackLead, trackSale };
+export { type ClickCoordinates, type CookieOptions, type ElementInfo, type InteractionBatchPayload, type InteractionEvent, Li2Analytics, type Li2Config, Li2ServerAnalytics, type Li2ServerConfig, type ServerTrackLeadParams, type ServerTrackSaleParams, type TrackLeadParams, type TrackLeadResponse, type TrackSaleParams, type TrackSaleResponse, _default as default, getClickId, getInstance, identify, init, initServer, isTrackingAvailable, trackEvent, trackLead, trackPageview, trackSale };