@li2/analytics 0.2.2 → 0.3.0-beta.0

package/dist/index-DEfkJIjF.d.mts

@@ -0,0 +1,114 @@
+/** 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;
+}
+/** 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;
+    /** 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-DEfkJIjF.d.ts

@@ -0,0 +1,114 @@
+/** 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;
+}
+/** 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;
+    /** 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,9 +1,12 @@
+import { P as PageviewTracker } from './index-DEfkJIjF.mjs';
+export { c as PageviewBatchPayload, a as PageviewConfig, b as PageviewEvent } from './index-DEfkJIjF.mjs';
 export { AnalyticsSettings, AutoEvent, ConditionOperator, ConditionType, EventAction, EventActionType, EventTrigger, TriggerCondition, TriggerType } from './auto-events.mjs';
 
 /**
  * Li2 Analytics SDK
  * Conversion tracking for li2.ai
  */
+
 interface Li2Config {
     /** Publishable key from your organization's analytics settings */
     publishableKey?: string;
@@ -142,12 +145,41 @@ declare class Li2Analytics {
     private clickId;
     private cookieOptions;
     private autoEventTracker;
+    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>;
+    /**
+     * Manually track a pageview (convenience method)
+     */
+    trackPageview(options?: {
+        pageUrl?: string;
+        pageTitle?: string;
+        customData?: Record<string, unknown>;
+    }): 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 +301,15 @@ 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;
 
 /**
  * Initialize the server-side Li2 Analytics SDK
@@ -283,7 +324,8 @@ declare const _default: {
     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 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 };

package/dist/index.d.ts

@@ -1,9 +1,12 @@
+import { P as PageviewTracker } from './index-DEfkJIjF.js';
+export { c as PageviewBatchPayload, a as PageviewConfig, b as PageviewEvent } from './index-DEfkJIjF.js';
 export { AnalyticsSettings, AutoEvent, ConditionOperator, ConditionType, EventAction, EventActionType, EventTrigger, TriggerCondition, TriggerType } from './auto-events.js';
 
 /**
  * Li2 Analytics SDK
  * Conversion tracking for li2.ai
  */
+
 interface Li2Config {
     /** Publishable key from your organization's analytics settings */
     publishableKey?: string;
@@ -142,12 +145,41 @@ declare class Li2Analytics {
     private clickId;
     private cookieOptions;
     private autoEventTracker;
+    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>;
+    /**
+     * Manually track a pageview (convenience method)
+     */
+    trackPageview(options?: {
+        pageUrl?: string;
+        pageTitle?: string;
+        customData?: Record<string, unknown>;
+    }): 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 +301,15 @@ 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;
 
 /**
  * Initialize the server-side Li2 Analytics SDK
@@ -283,7 +324,8 @@ declare const _default: {
     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 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 };