@kitbase/events 0.1.2 → 0.1.4

package/dist/index.d.cts

@@ -77,6 +77,140 @@ interface QueueStats {
     isFlushing: boolean;
 }
 
+/**
+ * Bot detection module for filtering automated traffic
+ *
+ * Detects common automation tools, headless browsers, and bot user agents.
+ * Inspired by DataFast's bot detection approach.
+ */
+/**
+ * Bot detection result
+ */
+interface BotDetectionResult {
+    isBot: boolean;
+    reason?: string;
+    checks: {
+        webdriver: boolean;
+        phantomjs: boolean;
+        nightmare: boolean;
+        automationGlobals: boolean;
+        documentAttributes: boolean;
+        userAgentHeadless: boolean;
+        userAgentHttpClient: boolean;
+        missingUserAgent: boolean;
+        invalidEnvironment: boolean;
+    };
+}
+/**
+ * Configuration for bot detection
+ */
+interface BotDetectionConfig {
+    /**
+     * Enable bot detection.
+     * When enabled and a bot is detected, all tracking events are blocked.
+     * Set to false to disable bot detection.
+     * @default true
+     */
+    enabled?: boolean;
+    /**
+     * Check for webdriver flag (Chrome, Firefox)
+     * @default true
+     */
+    checkWebdriver?: boolean;
+    /**
+     * Check for PhantomJS
+     * @default true
+     */
+    checkPhantomJS?: boolean;
+    /**
+     * Check for Nightmare.js
+     * @default true
+     */
+    checkNightmare?: boolean;
+    /**
+     * Check for automation tool globals
+     * @default true
+     */
+    checkAutomationGlobals?: boolean;
+    /**
+     * Check document element attributes
+     * @default true
+     */
+    checkDocumentAttributes?: boolean;
+    /**
+     * Check user agent for headless browsers
+     * @default true
+     */
+    checkUserAgentHeadless?: boolean;
+    /**
+     * Check user agent for HTTP clients/bots
+     * @default true
+     */
+    checkUserAgentHttpClient?: boolean;
+    /**
+     * Additional user agent patterns to detect as bots
+     */
+    additionalBotPatterns?: string[];
+    /**
+     * Callback when a bot is detected
+     */
+    onBotDetected?: (result: BotDetectionResult) => void;
+}
+/**
+ * Detect if the current visitor is a bot
+ *
+ * @param config - Bot detection configuration
+ * @returns Bot detection result
+ *
+ * @example
+ * ```typescript
+ * const result = detectBot();
+ * if (result.isBot) {
+ *   console.log('Bot detected:', result.reason);
+ * }
+ * ```
+ */
+declare function detectBot(config?: BotDetectionConfig): BotDetectionResult;
+/**
+ * Quick check if current visitor is a bot
+ *
+ * @param config - Bot detection configuration
+ * @returns true if bot detected, false otherwise
+ *
+ * @example
+ * ```typescript
+ * if (isBot()) {
+ *   console.log('Bot detected, skipping tracking');
+ *   return;
+ * }
+ * ```
+ */
+declare function isBot(config?: BotDetectionConfig): boolean;
+/**
+ * Check a custom user agent string for bot patterns
+ * Useful for server-side bot detection
+ *
+ * @param userAgent - The user agent string to check
+ * @param additionalPatterns - Additional patterns to check
+ * @returns true if bot user agent detected
+ *
+ * @example
+ * ```typescript
+ * // Server-side usage
+ * const ua = request.headers['user-agent'];
+ * if (isUserAgentBot(ua)) {
+ *   console.log('Bot request detected');
+ * }
+ * ```
+ */
+declare function isUserAgentBot(userAgent: string, additionalPatterns?: string[]): boolean;
+/**
+ * Get the current user agent (browser only)
+ *
+ * @returns User agent string or null if not in browser
+ */
+declare function getUserAgent(): string | null;
+
 /**
  * Storage interface for anonymous ID persistence
  */
@@ -126,6 +260,11 @@ interface KitbaseConfig {
      * Enables session tracking, pageview tracking, and revenue tracking.
      */
     analytics?: AnalyticsConfig;
+    /**
+     * Bot detection configuration.
+     * When enabled, detects automated traffic and can block tracking for bots.
+     */
+    botDetection?: BotDetectionConfig;
 }
 /**
  * Tag values can be strings, numbers, or booleans
@@ -237,6 +376,12 @@ interface AnalyticsConfig {
      * @default true
      */
     autoTrackSessions?: boolean;
+    /**
+     * Enable automatic outbound link click tracking
+     * Tracks when users click links to external domains
+     * @default true
+     */
+    autoTrackOutboundLinks?: boolean;
     /**
      * Session timeout in milliseconds (default: 30 minutes)
      * @default 1800000
@@ -366,8 +511,12 @@ declare class Kitbase {
     private sessionStorageKey;
     private analyticsEnabled;
     private autoTrackPageViews;
+    private autoTrackOutboundLinks;
     private userId;
     private unloadListenerAdded;
+    private clickListenerAdded;
+    private botDetectionConfig;
+    private botDetectionResult;
     constructor(config: KitbaseConfig);
     /**
      * Initialize the anonymous ID from storage or generate a new one
@@ -510,6 +659,54 @@ declare class Kitbase {
      * @returns Duration in seconds, or null if not being timed
      */
     getEventDuration(eventName: string): number | null;
+    /**
+     * Check if the current visitor is detected as a bot
+     *
+     * @returns true if bot detected, false otherwise
+     *
+     * @example
+     * ```typescript
+     * if (kitbase.isBot()) {
+     *   console.log('Bot detected, tracking disabled');
+     * }
+     * ```
+     */
+    isBot(): boolean;
+    /**
+     * Get detailed bot detection result
+     *
+     * @returns Bot detection result with detailed checks, or null if detection not enabled
+     *
+     * @example
+     * ```typescript
+     * const result = kitbase.getBotDetectionResult();
+     * if (result?.isBot) {
+     *   console.log('Bot detected:', result.reason);
+     *   console.log('Checks:', result.checks);
+     * }
+     * ```
+     */
+    getBotDetectionResult(): BotDetectionResult | null;
+    /**
+     * Force re-run bot detection
+     * Useful if you want to check again after page state changes
+     *
+     * @returns Updated bot detection result
+     *
+     * @example
+     * ```typescript
+     * const result = kitbase.redetectBot();
+     * console.log('Is bot:', result.isBot);
+     * ```
+     */
+    redetectBot(): BotDetectionResult;
+    /**
+     * Check if bot blocking is currently active
+     * When bot detection is enabled and a bot is detected, all events are blocked.
+     *
+     * @returns true if bots are being blocked from tracking
+     */
+    isBotBlockingActive(): boolean;
     /**
      * Get offline queue statistics
      *
@@ -600,6 +797,40 @@ declare class Kitbase {
      * Setup listeners for session lifecycle management
      */
     private setupUnloadListener;
+    /**
+     * Setup outbound link click tracking
+     */
+    private setupOutboundLinkTracking;
+    /**
+     * Handle link click for outbound tracking
+     */
+    private handleLinkClick;
+    /**
+     * Get root domain from hostname (e.g., blog.example.com -> example.com)
+     */
+    private getRootDomain;
+    /**
+     * Check if two hostnames share the same root domain
+     */
+    private isSameRootDomain;
+    /**
+     * Track an outbound link click
+     *
+     * @param options - Outbound link options
+     * @returns Promise resolving to the track response
+     *
+     * @example
+     * ```typescript
+     * await kitbase.trackOutboundLink({
+     *   url: 'https://example.com',
+     *   text: 'Visit Example',
+     * });
+     * ```
+     */
+    trackOutboundLink(options: {
+        url: string;
+        text?: string;
+    }): Promise<TrackResponse>;
     /**
      * Get UTM parameters from URL
      */
@@ -723,4 +954,4 @@ declare class TimeoutError extends KitbaseError {
     constructor(message?: string);
 }
 
-export { type AnalyticsConfig, ApiError, AuthenticationError, type IdentifyOptions, Kitbase, type KitbaseConfig, KitbaseError, type OfflineConfig, type PageViewOptions, type QueueStats, type QueuedEvent, type RevenueOptions, type Session, type Storage, type TagValue, type Tags, TimeoutError, type TrackOptions, type TrackResponse, ValidationError };
+export { type AnalyticsConfig, ApiError, AuthenticationError, type BotDetectionConfig, type BotDetectionResult, type IdentifyOptions, Kitbase, type KitbaseConfig, KitbaseError, type OfflineConfig, type PageViewOptions, type QueueStats, type QueuedEvent, type RevenueOptions, type Session, type Storage, type TagValue, type Tags, TimeoutError, type TrackOptions, type TrackResponse, ValidationError, detectBot, getUserAgent, isBot, isUserAgentBot };

package/dist/index.d.ts

@@ -77,6 +77,140 @@ interface QueueStats {
     isFlushing: boolean;
 }
 
+/**
+ * Bot detection module for filtering automated traffic
+ *
+ * Detects common automation tools, headless browsers, and bot user agents.
+ * Inspired by DataFast's bot detection approach.
+ */
+/**
+ * Bot detection result
+ */
+interface BotDetectionResult {
+    isBot: boolean;
+    reason?: string;
+    checks: {
+        webdriver: boolean;
+        phantomjs: boolean;
+        nightmare: boolean;
+        automationGlobals: boolean;
+        documentAttributes: boolean;
+        userAgentHeadless: boolean;
+        userAgentHttpClient: boolean;
+        missingUserAgent: boolean;
+        invalidEnvironment: boolean;
+    };
+}
+/**
+ * Configuration for bot detection
+ */
+interface BotDetectionConfig {
+    /**
+     * Enable bot detection.
+     * When enabled and a bot is detected, all tracking events are blocked.
+     * Set to false to disable bot detection.
+     * @default true
+     */
+    enabled?: boolean;
+    /**
+     * Check for webdriver flag (Chrome, Firefox)
+     * @default true
+     */
+    checkWebdriver?: boolean;
+    /**
+     * Check for PhantomJS
+     * @default true
+     */
+    checkPhantomJS?: boolean;
+    /**
+     * Check for Nightmare.js
+     * @default true
+     */
+    checkNightmare?: boolean;
+    /**
+     * Check for automation tool globals
+     * @default true
+     */
+    checkAutomationGlobals?: boolean;
+    /**
+     * Check document element attributes
+     * @default true
+     */
+    checkDocumentAttributes?: boolean;
+    /**
+     * Check user agent for headless browsers
+     * @default true
+     */
+    checkUserAgentHeadless?: boolean;
+    /**
+     * Check user agent for HTTP clients/bots
+     * @default true
+     */
+    checkUserAgentHttpClient?: boolean;
+    /**
+     * Additional user agent patterns to detect as bots
+     */
+    additionalBotPatterns?: string[];
+    /**
+     * Callback when a bot is detected
+     */
+    onBotDetected?: (result: BotDetectionResult) => void;
+}
+/**
+ * Detect if the current visitor is a bot
+ *
+ * @param config - Bot detection configuration
+ * @returns Bot detection result
+ *
+ * @example
+ * ```typescript
+ * const result = detectBot();
+ * if (result.isBot) {
+ *   console.log('Bot detected:', result.reason);
+ * }
+ * ```
+ */
+declare function detectBot(config?: BotDetectionConfig): BotDetectionResult;
+/**
+ * Quick check if current visitor is a bot
+ *
+ * @param config - Bot detection configuration
+ * @returns true if bot detected, false otherwise
+ *
+ * @example
+ * ```typescript
+ * if (isBot()) {
+ *   console.log('Bot detected, skipping tracking');
+ *   return;
+ * }
+ * ```
+ */
+declare function isBot(config?: BotDetectionConfig): boolean;
+/**
+ * Check a custom user agent string for bot patterns
+ * Useful for server-side bot detection
+ *
+ * @param userAgent - The user agent string to check
+ * @param additionalPatterns - Additional patterns to check
+ * @returns true if bot user agent detected
+ *
+ * @example
+ * ```typescript
+ * // Server-side usage
+ * const ua = request.headers['user-agent'];
+ * if (isUserAgentBot(ua)) {
+ *   console.log('Bot request detected');
+ * }
+ * ```
+ */
+declare function isUserAgentBot(userAgent: string, additionalPatterns?: string[]): boolean;
+/**
+ * Get the current user agent (browser only)
+ *
+ * @returns User agent string or null if not in browser
+ */
+declare function getUserAgent(): string | null;
+
 /**
  * Storage interface for anonymous ID persistence
  */
@@ -126,6 +260,11 @@ interface KitbaseConfig {
      * Enables session tracking, pageview tracking, and revenue tracking.
      */
     analytics?: AnalyticsConfig;
+    /**
+     * Bot detection configuration.
+     * When enabled, detects automated traffic and can block tracking for bots.
+     */
+    botDetection?: BotDetectionConfig;
 }
 /**
  * Tag values can be strings, numbers, or booleans
@@ -237,6 +376,12 @@ interface AnalyticsConfig {
      * @default true
      */
     autoTrackSessions?: boolean;
+    /**
+     * Enable automatic outbound link click tracking
+     * Tracks when users click links to external domains
+     * @default true
+     */
+    autoTrackOutboundLinks?: boolean;
     /**
      * Session timeout in milliseconds (default: 30 minutes)
      * @default 1800000
@@ -366,8 +511,12 @@ declare class Kitbase {
     private sessionStorageKey;
     private analyticsEnabled;
     private autoTrackPageViews;
+    private autoTrackOutboundLinks;
     private userId;
     private unloadListenerAdded;
+    private clickListenerAdded;
+    private botDetectionConfig;
+    private botDetectionResult;
     constructor(config: KitbaseConfig);
     /**
      * Initialize the anonymous ID from storage or generate a new one
@@ -510,6 +659,54 @@ declare class Kitbase {
      * @returns Duration in seconds, or null if not being timed
      */
     getEventDuration(eventName: string): number | null;
+    /**
+     * Check if the current visitor is detected as a bot
+     *
+     * @returns true if bot detected, false otherwise
+     *
+     * @example
+     * ```typescript
+     * if (kitbase.isBot()) {
+     *   console.log('Bot detected, tracking disabled');
+     * }
+     * ```
+     */
+    isBot(): boolean;
+    /**
+     * Get detailed bot detection result
+     *
+     * @returns Bot detection result with detailed checks, or null if detection not enabled
+     *
+     * @example
+     * ```typescript
+     * const result = kitbase.getBotDetectionResult();
+     * if (result?.isBot) {
+     *   console.log('Bot detected:', result.reason);
+     *   console.log('Checks:', result.checks);
+     * }
+     * ```
+     */
+    getBotDetectionResult(): BotDetectionResult | null;
+    /**
+     * Force re-run bot detection
+     * Useful if you want to check again after page state changes
+     *
+     * @returns Updated bot detection result
+     *
+     * @example
+     * ```typescript
+     * const result = kitbase.redetectBot();
+     * console.log('Is bot:', result.isBot);
+     * ```
+     */
+    redetectBot(): BotDetectionResult;
+    /**
+     * Check if bot blocking is currently active
+     * When bot detection is enabled and a bot is detected, all events are blocked.
+     *
+     * @returns true if bots are being blocked from tracking
+     */
+    isBotBlockingActive(): boolean;
     /**
      * Get offline queue statistics
      *
@@ -600,6 +797,40 @@ declare class Kitbase {
      * Setup listeners for session lifecycle management
      */
     private setupUnloadListener;
+    /**
+     * Setup outbound link click tracking
+     */
+    private setupOutboundLinkTracking;
+    /**
+     * Handle link click for outbound tracking
+     */
+    private handleLinkClick;
+    /**
+     * Get root domain from hostname (e.g., blog.example.com -> example.com)
+     */
+    private getRootDomain;
+    /**
+     * Check if two hostnames share the same root domain
+     */
+    private isSameRootDomain;
+    /**
+     * Track an outbound link click
+     *
+     * @param options - Outbound link options
+     * @returns Promise resolving to the track response
+     *
+     * @example
+     * ```typescript
+     * await kitbase.trackOutboundLink({
+     *   url: 'https://example.com',
+     *   text: 'Visit Example',
+     * });
+     * ```
+     */
+    trackOutboundLink(options: {
+        url: string;
+        text?: string;
+    }): Promise<TrackResponse>;
     /**
      * Get UTM parameters from URL
      */
@@ -723,4 +954,4 @@ declare class TimeoutError extends KitbaseError {
     constructor(message?: string);
 }
 
-export { type AnalyticsConfig, ApiError, AuthenticationError, type IdentifyOptions, Kitbase, type KitbaseConfig, KitbaseError, type OfflineConfig, type PageViewOptions, type QueueStats, type QueuedEvent, type RevenueOptions, type Session, type Storage, type TagValue, type Tags, TimeoutError, type TrackOptions, type TrackResponse, ValidationError };
+export { type AnalyticsConfig, ApiError, AuthenticationError, type BotDetectionConfig, type BotDetectionResult, type IdentifyOptions, Kitbase, type KitbaseConfig, KitbaseError, type OfflineConfig, type PageViewOptions, type QueueStats, type QueuedEvent, type RevenueOptions, type Session, type Storage, type TagValue, type Tags, TimeoutError, type TrackOptions, type TrackResponse, ValidationError, detectBot, getUserAgent, isBot, isUserAgentBot };