@kitbase/events 0.1.3 → 0.1.4

package/dist/index.cjs

@@ -35,7 +35,11 @@ __export(index_exports, {
   Kitbase: () => Kitbase,
   KitbaseError: () => KitbaseError,
   TimeoutError: () => TimeoutError,
-  ValidationError: () => ValidationError
+  ValidationError: () => ValidationError,
+  detectBot: () => detectBot,
+  getUserAgent: () => getUserAgent,
+  isBot: () => isBot,
+  isUserAgentBot: () => isUserAgentBot
 });
 module.exports = __toCommonJS(index_exports);
 
@@ -449,6 +453,269 @@ var EventQueue = class {
   }
 };
 
+// src/botDetection.ts
+var AUTOMATION_GLOBALS = [
+  "__webdriver_evaluate",
+  "__selenium_evaluate",
+  "__webdriver_script_function",
+  "__webdriver_unwrapped",
+  "__fxdriver_evaluate",
+  "__driver_evaluate",
+  "_Selenium_IDE_Recorder",
+  "_selenium",
+  "calledSelenium",
+  "$cdc_asdjflasutopfhvcZLmcfl_",
+  // Chrome DevTools Protocol marker
+  "__nightmare",
+  "domAutomation",
+  "domAutomationController"
+];
+var HEADLESS_PATTERNS = [
+  "headlesschrome",
+  "phantomjs",
+  "selenium",
+  "webdriver",
+  "puppeteer",
+  "playwright"
+];
+var HTTP_CLIENT_PATTERNS = [
+  "python",
+  "curl",
+  "wget",
+  "java/",
+  "go-http",
+  "node-fetch",
+  "axios",
+  "postman",
+  "insomnia",
+  "httpie",
+  "ruby",
+  "perl",
+  "scrapy",
+  "bot",
+  "spider",
+  "crawler",
+  "slurp",
+  "googlebot",
+  "bingbot",
+  "yandexbot",
+  "baiduspider",
+  "duckduckbot",
+  "facebookexternalhit",
+  "twitterbot",
+  "linkedinbot",
+  "whatsapp",
+  "telegram",
+  "discord",
+  "slack"
+];
+var DEFAULT_BOT_DETECTION_CONFIG = {
+  enabled: true,
+  checkWebdriver: true,
+  checkPhantomJS: true,
+  checkNightmare: true,
+  checkAutomationGlobals: true,
+  checkDocumentAttributes: true,
+  checkUserAgentHeadless: true,
+  checkUserAgentHttpClient: true
+};
+function isBrowser2() {
+  return typeof window !== "undefined" && typeof document !== "undefined";
+}
+function getWindowProperty(key) {
+  try {
+    return window[key];
+  } catch {
+    return void 0;
+  }
+}
+function checkWebdriver() {
+  if (!isBrowser2()) return false;
+  try {
+    return window.navigator?.webdriver === true;
+  } catch {
+    return false;
+  }
+}
+function checkPhantomJS() {
+  if (!isBrowser2()) return false;
+  try {
+    return !!(getWindowProperty("callPhantom") || getWindowProperty("_phantom") || getWindowProperty("phantom"));
+  } catch {
+    return false;
+  }
+}
+function checkNightmare() {
+  if (!isBrowser2()) return false;
+  try {
+    return !!getWindowProperty("__nightmare");
+  } catch {
+    return false;
+  }
+}
+function checkAutomationGlobals() {
+  if (!isBrowser2()) return false;
+  try {
+    for (const global of AUTOMATION_GLOBALS) {
+      if (getWindowProperty(global) !== void 0) {
+        return true;
+      }
+    }
+    return false;
+  } catch {
+    return false;
+  }
+}
+function checkDocumentAttributes() {
+  if (!isBrowser2()) return false;
+  try {
+    const docEl = document.documentElement;
+    if (!docEl) return false;
+    return !!(docEl.getAttribute("webdriver") || docEl.getAttribute("selenium") || docEl.getAttribute("driver"));
+  } catch {
+    return false;
+  }
+}
+function checkUserAgentHeadless() {
+  if (!isBrowser2()) return false;
+  try {
+    const ua = window.navigator?.userAgent?.toLowerCase() || "";
+    if (!ua) return false;
+    for (const pattern of HEADLESS_PATTERNS) {
+      if (ua.includes(pattern)) {
+        return true;
+      }
+    }
+    return false;
+  } catch {
+    return false;
+  }
+}
+function checkUserAgentHttpClient(additionalPatterns) {
+  if (!isBrowser2()) return false;
+  try {
+    const ua = window.navigator?.userAgent?.toLowerCase() || "";
+    if (!ua) return false;
+    for (const pattern of HTTP_CLIENT_PATTERNS) {
+      if (ua.includes(pattern)) {
+        return true;
+      }
+    }
+    if (additionalPatterns) {
+      for (const pattern of additionalPatterns) {
+        if (ua.includes(pattern.toLowerCase())) {
+          return true;
+        }
+      }
+    }
+    return false;
+  } catch {
+    return false;
+  }
+}
+function checkMissingUserAgent() {
+  if (!isBrowser2()) return false;
+  try {
+    const ua = window.navigator?.userAgent;
+    return !ua || ua === "" || ua === "undefined" || ua.length < 10;
+  } catch {
+    return false;
+  }
+}
+function checkInvalidEnvironment() {
+  if (!isBrowser2()) return false;
+  try {
+    if (!window.navigator || !window.location || !window.document || typeof window.navigator !== "object" || typeof window.location !== "object" || typeof window.document !== "object") {
+      return true;
+    }
+    return false;
+  } catch {
+    return true;
+  }
+}
+function detectBot(config = {}) {
+  const mergedConfig = { ...DEFAULT_BOT_DETECTION_CONFIG, ...config };
+  const checks = {
+    webdriver: mergedConfig.checkWebdriver ? checkWebdriver() : false,
+    phantomjs: mergedConfig.checkPhantomJS ? checkPhantomJS() : false,
+    nightmare: mergedConfig.checkNightmare ? checkNightmare() : false,
+    automationGlobals: mergedConfig.checkAutomationGlobals ? checkAutomationGlobals() : false,
+    documentAttributes: mergedConfig.checkDocumentAttributes ? checkDocumentAttributes() : false,
+    userAgentHeadless: mergedConfig.checkUserAgentHeadless ? checkUserAgentHeadless() : false,
+    userAgentHttpClient: mergedConfig.checkUserAgentHttpClient ? checkUserAgentHttpClient(config.additionalBotPatterns) : false,
+    missingUserAgent: checkMissingUserAgent(),
+    invalidEnvironment: checkInvalidEnvironment()
+  };
+  let reason;
+  if (checks.webdriver) {
+    reason = "WebDriver detected";
+  } else if (checks.phantomjs) {
+    reason = "PhantomJS detected";
+  } else if (checks.nightmare) {
+    reason = "Nightmare.js detected";
+  } else if (checks.automationGlobals) {
+    reason = "Automation tool globals detected";
+  } else if (checks.documentAttributes) {
+    reason = "Automation attributes on document element";
+  } else if (checks.userAgentHeadless) {
+    reason = "Headless browser user agent detected";
+  } else if (checks.userAgentHttpClient) {
+    reason = "HTTP client/bot user agent detected";
+  } else if (checks.missingUserAgent) {
+    reason = "Missing or invalid user agent";
+  } else if (checks.invalidEnvironment) {
+    reason = "Invalid browser environment";
+  }
+  const isBot2 = Object.values(checks).some(Boolean);
+  const result = {
+    isBot: isBot2,
+    reason,
+    checks
+  };
+  if (isBot2 && config.onBotDetected) {
+    try {
+      config.onBotDetected(result);
+    } catch {
+    }
+  }
+  return result;
+}
+function isBot(config = {}) {
+  return detectBot(config).isBot;
+}
+function isUserAgentBot(userAgent, additionalPatterns) {
+  if (!userAgent || userAgent.length < 10) {
+    return true;
+  }
+  const ua = userAgent.toLowerCase();
+  for (const pattern of HEADLESS_PATTERNS) {
+    if (ua.includes(pattern)) {
+      return true;
+    }
+  }
+  for (const pattern of HTTP_CLIENT_PATTERNS) {
+    if (ua.includes(pattern)) {
+      return true;
+    }
+  }
+  if (additionalPatterns) {
+    for (const pattern of additionalPatterns) {
+      if (ua.includes(pattern.toLowerCase())) {
+        return true;
+      }
+    }
+  }
+  return false;
+}
+function getUserAgent() {
+  if (!isBrowser2()) return null;
+  try {
+    return window.navigator?.userAgent || null;
+  } catch {
+    return null;
+  }
+}
+
 // src/client.ts
 var DEFAULT_BASE_URL = "https://api.kitbase.dev";
 var TIMEOUT = 3e4;
@@ -495,8 +762,13 @@ var Kitbase = class {
   sessionStorageKey;
   analyticsEnabled;
   autoTrackPageViews;
+  autoTrackOutboundLinks;
   userId = null;
   unloadListenerAdded = false;
+  clickListenerAdded = false;
+  // Bot detection
+  botDetectionConfig;
+  botDetectionResult = null;
   constructor(config) {
     if (!config.token) {
       throw new ValidationError("API token is required", "token");
@@ -515,6 +787,7 @@ var Kitbase = class {
     this.sessionStorageKey = config.analytics?.sessionStorageKey ?? DEFAULT_SESSION_STORAGE_KEY;
     this.analyticsEnabled = config.analytics?.autoTrackSessions ?? true;
     this.autoTrackPageViews = config.analytics?.autoTrackPageViews ?? false;
+    this.autoTrackOutboundLinks = config.analytics?.autoTrackOutboundLinks ?? true;
     if (this.analyticsEnabled) {
       this.loadSession();
       this.setupUnloadListener();
@@ -522,6 +795,9 @@ var Kitbase = class {
         this.enableAutoPageViews();
       }
     }
+    if (this.autoTrackOutboundLinks && typeof window !== "undefined") {
+      this.setupOutboundLinkTracking();
+    }
     this.offlineEnabled = config.offline?.enabled ?? false;
     if (this.offlineEnabled) {
       this.queue = new EventQueue(config.offline);
@@ -532,6 +808,21 @@ var Kitbase = class {
         storageType: this.queue.getStorageType()
       });
     }
+    this.botDetectionConfig = {
+      ...DEFAULT_BOT_DETECTION_CONFIG,
+      ...config.botDetection
+    };
+    if (this.botDetectionConfig.enabled) {
+      this.botDetectionResult = detectBot(this.botDetectionConfig);
+      if (this.botDetectionResult.isBot) {
+        this.log("Bot detected", {
+          reason: this.botDetectionResult.reason,
+          checks: this.botDetectionResult.checks
+        });
+      } else {
+        this.log("Bot detection enabled, no bot detected");
+      }
+    }
   }
   /**
    * Initialize the anonymous ID from storage or generate a new one
@@ -752,6 +1043,82 @@ var Kitbase = class {
     return (Date.now() - startTime) / 1e3;
   }
   // ============================================================
+  // Bot Detection
+  // ============================================================
+  /**
+   * 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() {
+    if (!this.botDetectionConfig.enabled) {
+      return false;
+    }
+    if (!this.botDetectionResult) {
+      this.botDetectionResult = detectBot(this.botDetectionConfig);
+    }
+    return this.botDetectionResult.isBot;
+  }
+  /**
+   * 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() {
+    if (!this.botDetectionConfig.enabled) {
+      return null;
+    }
+    if (!this.botDetectionResult) {
+      this.botDetectionResult = detectBot(this.botDetectionConfig);
+    }
+    return this.botDetectionResult;
+  }
+  /**
+   * 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() {
+    this.botDetectionResult = detectBot(this.botDetectionConfig);
+    this.log("Bot detection re-run", {
+      isBot: this.botDetectionResult.isBot,
+      reason: this.botDetectionResult.reason
+    });
+    return this.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() {
+    return this.botDetectionConfig.enabled === true && this.isBot();
+  }
+  // ============================================================
   // Offline Queue
   // ============================================================
   /**
@@ -829,6 +1196,14 @@ var Kitbase = class {
    */
   async track(options) {
     this.validateTrackOptions(options);
+    if (this.isBotBlockingActive()) {
+      this.log("Event blocked - bot detected", { event: options.event });
+      return {
+        id: `blocked-bot-${Date.now()}`,
+        event: options.event,
+        timestamp: (/* @__PURE__ */ new Date()).toISOString()
+      };
+    }
     let duration;
     const startTime = this.timedEvents.get(options.event);
     if (startTime !== void 0) {
@@ -1053,6 +1428,97 @@ var Kitbase = class {
     this.unloadListenerAdded = true;
     this.log("Session lifecycle listeners added");
   }
+  /**
+   * Setup outbound link click tracking
+   */
+  setupOutboundLinkTracking() {
+    if (typeof window === "undefined" || this.clickListenerAdded) return;
+    const handleClick = (event) => {
+      const link = event.target?.closest?.("a");
+      if (link) {
+        this.handleLinkClick(link);
+      }
+    };
+    const handleKeydown = (event) => {
+      if (event.key === "Enter" || event.key === " ") {
+        const link = event.target?.closest?.("a");
+        if (link) {
+          this.handleLinkClick(link);
+        }
+      }
+    };
+    document.addEventListener("click", handleClick);
+    document.addEventListener("keydown", handleKeydown);
+    this.clickListenerAdded = true;
+    this.log("Outbound link tracking enabled");
+  }
+  /**
+   * Handle link click for outbound tracking
+   */
+  handleLinkClick(link) {
+    if (!link.href) return;
+    try {
+      const linkUrl = new URL(link.href);
+      if (linkUrl.protocol !== "http:" && linkUrl.protocol !== "https:") {
+        return;
+      }
+      const currentHost = window.location.hostname;
+      const linkHost = linkUrl.hostname;
+      if (linkHost === currentHost) {
+        return;
+      }
+      if (this.isSameRootDomain(currentHost, linkHost)) {
+        return;
+      }
+      this.trackOutboundLink({
+        url: link.href,
+        text: link.textContent?.trim() || ""
+      }).catch((err) => this.log("Failed to track outbound link", err));
+    } catch {
+    }
+  }
+  /**
+   * Get root domain from hostname (e.g., blog.example.com -> example.com)
+   */
+  getRootDomain(hostname) {
+    const parts = hostname.replace(/^www\./, "").split(".");
+    if (parts.length >= 2) {
+      return parts.slice(-2).join(".");
+    }
+    return hostname;
+  }
+  /**
+   * Check if two hostnames share the same root domain
+   */
+  isSameRootDomain(host1, host2) {
+    return this.getRootDomain(host1) === this.getRootDomain(host2);
+  }
+  /**
+   * 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',
+   * });
+   * ```
+   */
+  async trackOutboundLink(options) {
+    const session = this.getOrCreateSession();
+    return this.track({
+      channel: ANALYTICS_CHANNEL,
+      event: "outbound_link",
+      tags: {
+        __session_id: session.id,
+        __url: options.url,
+        __text: options.text || ""
+      }
+    });
+  }
   /**
    * Get UTM parameters from URL
    */
@@ -1258,6 +1724,10 @@ var Kitbase = class {
   Kitbase,
   KitbaseError,
   TimeoutError,
-  ValidationError
+  ValidationError,
+  detectBot,
+  getUserAgent,
+  isBot,
+  isUserAgentBot
 });
 //# sourceMappingURL=index.cjs.map