@li2/analytics 0.3.0-beta.0 → 0.3.1-beta.0

package/dist/index-B3dzYzIM.d.mts

@@ -0,0 +1,122 @@
+/** Configuration for PageviewTracker */
+interface PageviewConfig {
+    /** API endpoint base URL */
+    apiUrl: string;
+    /** Publishable key for authentication */
+    publishableKey: string;
+    /** Enable/disable pageview tracking */
+    enabled: boolean;
+    /** SPA detection mode: 'auto' | 'manual' | 'disabled' */
+    spaMode: 'auto' | 'manual' | 'disabled';
+    /** Batch send interval in milliseconds (default: 5000) */
+    batchInterval: number;
+    /** Max pageviews per batch (default: 50) */
+    batchSize: number;
+    /** URL patterns to exclude from tracking (glob-like) */
+    excludePatterns: string[];
+    /** Track hash changes as separate pageviews (default: false) */
+    trackHashChanges: boolean;
+    /** Session timeout in minutes (default: 30) */
+    sessionTimeout: number;
+    /** Cookie-less mode: use only sessionStorage (default: false) */
+    cookieLessMode: boolean;
+    /** Enable debug logging (default: false) */
+    debug: boolean;
+    /** Respect Do Not Track header (default: true) */
+    respectDnt: boolean;
+    /** Cookie domain (default: auto-detect) */
+    cookieDomain?: string;
+    /** Cookie path (default: '/') */
+    cookiePath: string;
+    /** Search query URL parameters to detect (default: ['q', 'query', 'search', 's']) */
+    searchParams: string[];
+}
+/** A single pageview event to be sent to the server */
+interface PageviewEvent {
+    /** 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;
+    /** Document title */
+    page_title: string;
+    /** Previous page URL (internal referrer) */
+    page_referrer: string;
+    /** URL hash/fragment */
+    page_hash: string;
+    /** Search query (if detected from URL params) */
+    search_query: string | null;
+    /** Unix timestamp in milliseconds */
+    timestamp: number;
+    /** Time spent on previous page in milliseconds */
+    time_on_page: number | null;
+    /** Screen dimensions */
+    screen_width: number;
+    screen_height: number;
+    viewport_width: number;
+    viewport_height: number;
+    /** Event name (when this record represents a named event, not a pageview) */
+    event_name?: string;
+    /** Event category for grouping (optional, only with event_name) */
+    event_category?: string;
+}
+/** Batch payload sent to the server */
+interface PageviewBatchPayload {
+    pageviews: PageviewEvent[];
+}
+
+declare class PageviewTracker {
+    private config;
+    private pageDetector;
+    private sessionManager;
+    private batchSender;
+    private enabled;
+    private lastPageUrl;
+    private lastPageTimestamp;
+    constructor(config: Partial<PageviewConfig> & Pick<PageviewConfig, 'apiUrl' | 'publishableKey'>);
+    /** Start tracking pageviews */
+    start(): void;
+    /** Stop tracking pageviews */
+    stop(): void;
+    /** Enable pageview tracking */
+    enable(): void;
+    /** Disable pageview tracking */
+    disable(): void;
+    /** Force start a new session */
+    newSession(): void;
+    /** Manually track a pageview (for advanced use cases) */
+    trackPageview(options?: {
+        pageUrl?: string;
+        pageTitle?: string;
+        customData?: Record<string, unknown>;
+    }): void;
+    /** Track a named event (sent through the pageview pipeline with event_name set) */
+    trackEvent(eventName: string, options?: {
+        category?: string;
+    }): void;
+    /** Handle page change event from PageDetector */
+    private handlePageChange;
+    /** Build a PageviewEvent from current state */
+    private buildPageviewEvent;
+    /** Track the current page (called on init) */
+    private trackCurrentPage;
+    /** Check if a path matches any exclude pattern */
+    private isExcluded;
+    /** Extract search query from URL params */
+    private extractSearchQuery;
+    /**
+     * Get Li2 click ID from existing SDK cookie management.
+     * Priority: URL param `uid` → cookie `li_cid` → legacy cookie `li2_id`
+     * This matches the exact resolution order in li2-analytics/src/index.ts
+     */
+    private getLi2Cid;
+    /** Debug logger */
+    private log;
+}
+
+export { PageviewTracker as P, type PageviewConfig as a, type PageviewEvent as b, type PageviewBatchPayload as c };

package/dist/index-B3dzYzIM.d.ts

@@ -0,0 +1,122 @@
+/** Configuration for PageviewTracker */
+interface PageviewConfig {
+    /** API endpoint base URL */
+    apiUrl: string;
+    /** Publishable key for authentication */
+    publishableKey: string;
+    /** Enable/disable pageview tracking */
+    enabled: boolean;
+    /** SPA detection mode: 'auto' | 'manual' | 'disabled' */
+    spaMode: 'auto' | 'manual' | 'disabled';
+    /** Batch send interval in milliseconds (default: 5000) */
+    batchInterval: number;
+    /** Max pageviews per batch (default: 50) */
+    batchSize: number;
+    /** URL patterns to exclude from tracking (glob-like) */
+    excludePatterns: string[];
+    /** Track hash changes as separate pageviews (default: false) */
+    trackHashChanges: boolean;
+    /** Session timeout in minutes (default: 30) */
+    sessionTimeout: number;
+    /** Cookie-less mode: use only sessionStorage (default: false) */
+    cookieLessMode: boolean;
+    /** Enable debug logging (default: false) */
+    debug: boolean;
+    /** Respect Do Not Track header (default: true) */
+    respectDnt: boolean;
+    /** Cookie domain (default: auto-detect) */
+    cookieDomain?: string;
+    /** Cookie path (default: '/') */
+    cookiePath: string;
+    /** Search query URL parameters to detect (default: ['q', 'query', 'search', 's']) */
+    searchParams: string[];
+}
+/** A single pageview event to be sent to the server */
+interface PageviewEvent {
+    /** 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;
+    /** Document title */
+    page_title: string;
+    /** Previous page URL (internal referrer) */
+    page_referrer: string;
+    /** URL hash/fragment */
+    page_hash: string;
+    /** Search query (if detected from URL params) */
+    search_query: string | null;
+    /** Unix timestamp in milliseconds */
+    timestamp: number;
+    /** Time spent on previous page in milliseconds */
+    time_on_page: number | null;
+    /** Screen dimensions */
+    screen_width: number;
+    screen_height: number;
+    viewport_width: number;
+    viewport_height: number;
+    /** Event name (when this record represents a named event, not a pageview) */
+    event_name?: string;
+    /** Event category for grouping (optional, only with event_name) */
+    event_category?: string;
+}
+/** Batch payload sent to the server */
+interface PageviewBatchPayload {
+    pageviews: PageviewEvent[];
+}
+
+declare class PageviewTracker {
+    private config;
+    private pageDetector;
+    private sessionManager;
+    private batchSender;
+    private enabled;
+    private lastPageUrl;
+    private lastPageTimestamp;
+    constructor(config: Partial<PageviewConfig> & Pick<PageviewConfig, 'apiUrl' | 'publishableKey'>);
+    /** Start tracking pageviews */
+    start(): void;
+    /** Stop tracking pageviews */
+    stop(): void;
+    /** Enable pageview tracking */
+    enable(): void;
+    /** Disable pageview tracking */
+    disable(): void;
+    /** Force start a new session */
+    newSession(): void;
+    /** Manually track a pageview (for advanced use cases) */
+    trackPageview(options?: {
+        pageUrl?: string;
+        pageTitle?: string;
+        customData?: Record<string, unknown>;
+    }): void;
+    /** Track a named event (sent through the pageview pipeline with event_name set) */
+    trackEvent(eventName: string, options?: {
+        category?: string;
+    }): void;
+    /** Handle page change event from PageDetector */
+    private handlePageChange;
+    /** Build a PageviewEvent from current state */
+    private buildPageviewEvent;
+    /** Track the current page (called on init) */
+    private trackCurrentPage;
+    /** Check if a path matches any exclude pattern */
+    private isExcluded;
+    /** Extract search query from URL params */
+    private extractSearchQuery;
+    /**
+     * Get Li2 click ID from existing SDK cookie management.
+     * Priority: URL param `uid` → cookie `li_cid` → legacy cookie `li2_id`
+     * This matches the exact resolution order in li2-analytics/src/index.ts
+     */
+    private getLi2Cid;
+    /** Debug logger */
+    private log;
+}
+
+export { PageviewTracker as P, type PageviewConfig as a, type PageviewEvent as b, type PageviewBatchPayload as c };

package/dist/index.d.mts

@@ -1,6 +1,92 @@
-import { P as PageviewTracker } from './index-DEfkJIjF.mjs';
-export { c as PageviewBatchPayload, a as PageviewConfig, b as PageviewEvent } from './index-DEfkJIjF.mjs';
+import { P as PageviewTracker } from './index-B3dzYzIM.mjs';
+export { c as PageviewBatchPayload, a as PageviewConfig, b as PageviewEvent } from './index-B3dzYzIM.mjs';
 export { AnalyticsSettings, AutoEvent, ConditionOperator, ConditionType, EventAction, EventActionType, EventTrigger, TriggerCondition, TriggerType } from './auto-events.mjs';
+export { ClickTrackerConfig } from './click-tracker/index.mjs';
+
+/**
+ * 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
@@ -145,6 +231,7 @@ declare class Li2Analytics {
     private clickId;
     private cookieOptions;
     private autoEventTracker;
+    private clickTracker;
     pageview: PageviewTracker | null;
     constructor(config?: Li2Config);
     private log;
@@ -172,6 +259,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 +284,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 +421,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 +439,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 +447,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 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 };

package/dist/index.d.ts

@@ -1,6 +1,92 @@
-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';
+
+/**
+ * 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
@@ -145,6 +231,7 @@ declare class Li2Analytics {
     private clickId;
     private cookieOptions;
     private autoEventTracker;
+    private clickTracker;
     pageview: PageviewTracker | null;
     constructor(config?: Li2Config);
     private log;
@@ -172,6 +259,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 +284,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 +421,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 +439,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 +447,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 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 };