@li2/analytics 0.3.0-beta.0 → 0.3.2

package/dist/index.d.ts

@@ -1,6 +1,72 @@
-import { P as PageviewTracker } from './index-DEfkJIjF.js';
-export { c as PageviewBatchPayload, a as PageviewConfig, b as PageviewEvent } from './index-DEfkJIjF.js';
+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';
+export { E as ElementInfo } from './element-resolver-BnZ_ItHT.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[];
+}
+
+/**
+ * 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
@@ -145,6 +211,7 @@ declare class Li2Analytics {
     private clickId;
     private cookieOptions;
     private autoEventTracker;
+    private clickTracker;
     pageview: PageviewTracker | null;
     constructor(config?: Li2Config);
     private log;
@@ -172,6 +239,23 @@ declare class Li2Analytics {
         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)
      */
@@ -180,6 +264,13 @@ declare class Li2Analytics {
         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
@@ -310,6 +401,13 @@ declare function trackPageview(options?: {
     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
@@ -321,6 +419,7 @@ declare const _default: {
     getInstance: typeof getInstance;
     trackLead: typeof trackLead;
     trackSale: typeof trackSale;
+    trackEvent: typeof trackEvent;
     identify: typeof identify;
     isTrackingAvailable: typeof isTrackingAvailable;
     getClickId: typeof getClickId;
@@ -328,4 +427,4 @@ declare const _default: {
     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, trackPageview, trackSale };
+export { type ClickCoordinates, type CookieOptions, 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 };