@loamly/tracker 1.6.0

package/README.md

@@ -0,0 +1,82 @@
+# @loamly/tracker
+
+**Open-source AI traffic detection for websites.**
+
+> See what AI tells your customers — and track when they click.
+
+[![npm version](https://img.shields.io/npm/v/@loamly/tracker.svg)](https://www.npmjs.com/package/@loamly/tracker)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+Part of the [Loamly](https://github.com/loamly/loamly) open-source project.
+
+---
+
+## The Problem
+
+When users copy URLs from ChatGPT, Claude, or Perplexity:
+
+- ❌ No referrer header
+- ❌ No UTM parameters
+- ❌ Analytics shows "Direct Traffic"
+
+## The Solution
+
+Loamly detects AI-referred traffic with **75-85% accuracy** using:
+
+- 🔍 Referrer detection
+- ⏱️ Navigation Timing API (paste vs click)
+- 🧠 Behavioral signals
+- 📋 Zero-party surveys
+
+## Quick Start
+
+### Script Tag
+
+```html
+<script 
+  src="https://unpkg.com/@loamly/tracker" 
+  data-api-key="your-api-key"
+></script>
+```
+
+### NPM
+
+```bash
+npm install @loamly/tracker
+```
+
+```typescript
+import loamly from '@loamly/tracker'
+
+loamly.init({ apiKey: 'your-api-key' })
+loamly.track('signup_started')
+loamly.conversion('purchase', 99.99)
+```
+
+## API
+
+| Method | Description |
+|--------|-------------|
+| `init(config)` | Initialize the tracker |
+| `pageview(url?)` | Track page view |
+| `track(event, options?)` | Track custom event |
+| `conversion(event, revenue, currency?)` | Track conversion |
+| `identify(userId, traits?)` | Identify user |
+| `getAIDetection()` | Get AI detection result |
+| `getNavigationTiming()` | Get paste vs click analysis |
+
+## Privacy
+
+- 🍪 Cookie-free
+- 📍 No IP tracking
+- 🔒 GDPR compliant
+
+## Documentation
+
+See [loamly.ai/docs](https://loamly.ai/docs) for full documentation.
+
+## License
+
+MIT © [Loamly](https://loamly.ai)
+
+

package/dist/index.cjs

@@ -0,0 +1,584 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  AI_BOT_PATTERNS: () => AI_BOT_PATTERNS,
+  AI_PLATFORMS: () => AI_PLATFORMS,
+  VERSION: () => VERSION,
+  default: () => loamly,
+  detectAIFromReferrer: () => detectAIFromReferrer,
+  detectAIFromUTM: () => detectAIFromUTM,
+  detectNavigationType: () => detectNavigationType,
+  loamly: () => loamly
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/config.ts
+var VERSION = "1.6.0";
+var DEFAULT_CONFIG = {
+  apiHost: "https://app.loamly.ai",
+  endpoints: {
+    visit: "/api/ingest/visit",
+    behavioral: "/api/ingest/behavioral",
+    session: "/api/ingest/session",
+    resolve: "/api/tracker/resolve",
+    health: "/api/tracker/health",
+    ping: "/api/tracker/ping"
+  },
+  pingInterval: 3e4,
+  // 30 seconds
+  batchSize: 10,
+  batchTimeout: 5e3,
+  sessionTimeout: 18e5,
+  // 30 minutes
+  maxTextLength: 100,
+  timeSpentThresholdMs: 5e3
+  // Only send time_spent when delta >= 5 seconds
+};
+var AI_PLATFORMS = {
+  "chatgpt.com": "chatgpt",
+  "chat.openai.com": "chatgpt",
+  "claude.ai": "claude",
+  "perplexity.ai": "perplexity",
+  "bard.google.com": "bard",
+  "gemini.google.com": "gemini",
+  "copilot.microsoft.com": "copilot",
+  "github.com/copilot": "github-copilot",
+  "you.com": "you",
+  "phind.com": "phind",
+  "poe.com": "poe"
+};
+var AI_BOT_PATTERNS = [
+  "GPTBot",
+  "ChatGPT-User",
+  "ClaudeBot",
+  "Claude-Web",
+  "PerplexityBot",
+  "Amazonbot",
+  "Google-Extended",
+  "CCBot",
+  "anthropic-ai",
+  "cohere-ai"
+];
+
+// src/detection/navigation-timing.ts
+function detectNavigationType() {
+  try {
+    const entries = performance.getEntriesByType("navigation");
+    if (!entries || entries.length === 0) {
+      return { nav_type: "unknown", confidence: 0, signals: ["no_timing_data"] };
+    }
+    const nav = entries[0];
+    const signals = [];
+    let pasteScore = 0;
+    const fetchStartDelta = nav.fetchStart - nav.startTime;
+    if (fetchStartDelta < 5) {
+      pasteScore += 0.25;
+      signals.push("instant_fetch_start");
+    } else if (fetchStartDelta < 20) {
+      pasteScore += 0.15;
+      signals.push("fast_fetch_start");
+    }
+    const dnsTime = nav.domainLookupEnd - nav.domainLookupStart;
+    if (dnsTime === 0) {
+      pasteScore += 0.15;
+      signals.push("no_dns_lookup");
+    }
+    const connectTime = nav.connectEnd - nav.connectStart;
+    if (connectTime === 0) {
+      pasteScore += 0.15;
+      signals.push("no_tcp_connect");
+    }
+    if (nav.redirectCount === 0) {
+      pasteScore += 0.1;
+      signals.push("no_redirects");
+    }
+    const timingVariance = calculateTimingVariance(nav);
+    if (timingVariance < 10) {
+      pasteScore += 0.15;
+      signals.push("uniform_timing");
+    }
+    if (!document.referrer || document.referrer === "") {
+      pasteScore += 0.1;
+      signals.push("no_referrer");
+    }
+    const confidence = Math.min(pasteScore, 1);
+    const nav_type = pasteScore >= 0.5 ? "likely_paste" : "likely_click";
+    return {
+      nav_type,
+      confidence: Math.round(confidence * 1e3) / 1e3,
+      signals
+    };
+  } catch {
+    return { nav_type: "unknown", confidence: 0, signals: ["detection_error"] };
+  }
+}
+function calculateTimingVariance(nav) {
+  const timings = [
+    nav.fetchStart - nav.startTime,
+    nav.domainLookupEnd - nav.domainLookupStart,
+    nav.connectEnd - nav.connectStart,
+    nav.responseStart - nav.requestStart
+  ].filter((t) => t >= 0);
+  if (timings.length === 0) return 100;
+  const mean = timings.reduce((a, b) => a + b, 0) / timings.length;
+  const variance = timings.reduce((sum, t) => sum + Math.pow(t - mean, 2), 0) / timings.length;
+  return Math.sqrt(variance);
+}
+
+// src/detection/referrer.ts
+function detectAIFromReferrer(referrer) {
+  if (!referrer) {
+    return null;
+  }
+  try {
+    const url = new URL(referrer);
+    const hostname = url.hostname.toLowerCase();
+    for (const [pattern, platform] of Object.entries(AI_PLATFORMS)) {
+      if (hostname.includes(pattern) || referrer.includes(pattern)) {
+        return {
+          isAI: true,
+          platform,
+          confidence: 0.95,
+          // High confidence when referrer matches
+          method: "referrer"
+        };
+      }
+    }
+    return null;
+  } catch {
+    for (const [pattern, platform] of Object.entries(AI_PLATFORMS)) {
+      if (referrer.toLowerCase().includes(pattern.toLowerCase())) {
+        return {
+          isAI: true,
+          platform,
+          confidence: 0.85,
+          method: "referrer"
+        };
+      }
+    }
+    return null;
+  }
+}
+function detectAIFromUTM(url) {
+  try {
+    const params = new URL(url).searchParams;
+    const utmSource = params.get("utm_source")?.toLowerCase();
+    if (utmSource) {
+      for (const [pattern, platform] of Object.entries(AI_PLATFORMS)) {
+        if (utmSource.includes(pattern.split(".")[0])) {
+          return {
+            isAI: true,
+            platform,
+            confidence: 0.99,
+            // Very high confidence from explicit UTM
+            method: "referrer"
+          };
+        }
+      }
+      if (utmSource.includes("ai") || utmSource.includes("llm") || utmSource.includes("chatbot")) {
+        return {
+          isAI: true,
+          platform: utmSource,
+          confidence: 0.9,
+          method: "referrer"
+        };
+      }
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}
+
+// src/utils.ts
+function generateUUID() {
+  if (typeof crypto !== "undefined" && crypto.randomUUID) {
+    return crypto.randomUUID();
+  }
+  return "xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx".replace(/[xy]/g, (c) => {
+    const r = Math.random() * 16 | 0;
+    const v = c === "x" ? r : r & 3 | 8;
+    return v.toString(16);
+  });
+}
+function getVisitorId() {
+  try {
+    const stored = localStorage.getItem("_loamly_vid");
+    if (stored) return stored;
+    const newId = generateUUID();
+    localStorage.setItem("_loamly_vid", newId);
+    return newId;
+  } catch {
+    return generateUUID();
+  }
+}
+function getSessionId() {
+  try {
+    const storedSession = sessionStorage.getItem("loamly_session");
+    const storedStart = sessionStorage.getItem("loamly_start");
+    if (storedSession && storedStart) {
+      return { sessionId: storedSession, isNew: false };
+    }
+    const newSession = generateUUID();
+    const startTime = Date.now().toString();
+    sessionStorage.setItem("loamly_session", newSession);
+    sessionStorage.setItem("loamly_start", startTime);
+    return { sessionId: newSession, isNew: true };
+  } catch {
+    return { sessionId: generateUUID(), isNew: true };
+  }
+}
+function extractUTMParams(url) {
+  const params = {};
+  try {
+    const searchParams = new URL(url).searchParams;
+    const utmKeys = ["utm_source", "utm_medium", "utm_campaign", "utm_term", "utm_content"];
+    for (const key of utmKeys) {
+      const value = searchParams.get(key);
+      if (value) params[key] = value;
+    }
+  } catch {
+  }
+  return params;
+}
+function truncateText(text, maxLength) {
+  if (text.length <= maxLength) return text;
+  return text.substring(0, maxLength - 3) + "...";
+}
+async function safeFetch(url, options, timeout = 1e4) {
+  try {
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), timeout);
+    const response = await fetch(url, {
+      ...options,
+      signal: controller.signal
+    });
+    clearTimeout(timeoutId);
+    return response;
+  } catch {
+    return null;
+  }
+}
+function sendBeacon(url, data) {
+  if (typeof navigator !== "undefined" && navigator.sendBeacon) {
+    return navigator.sendBeacon(url, JSON.stringify(data));
+  }
+  return false;
+}
+
+// src/core.ts
+var config = { apiHost: DEFAULT_CONFIG.apiHost };
+var initialized = false;
+var debugMode = false;
+var visitorId = null;
+var sessionId = null;
+var sessionStartTime = null;
+var navigationTiming = null;
+var aiDetection = null;
+function log(...args) {
+  if (debugMode) {
+    console.log("[Loamly]", ...args);
+  }
+}
+function endpoint(path) {
+  return `${config.apiHost}${path}`;
+}
+function init(userConfig = {}) {
+  if (initialized) {
+    log("Already initialized");
+    return;
+  }
+  config = {
+    ...config,
+    ...userConfig,
+    apiHost: userConfig.apiHost || DEFAULT_CONFIG.apiHost
+  };
+  debugMode = userConfig.debug ?? false;
+  log("Initializing Loamly Tracker v" + VERSION);
+  visitorId = getVisitorId();
+  log("Visitor ID:", visitorId);
+  const session = getSessionId();
+  sessionId = session.sessionId;
+  sessionStartTime = Date.now();
+  log("Session ID:", sessionId, session.isNew ? "(new)" : "(existing)");
+  navigationTiming = detectNavigationType();
+  log("Navigation timing:", navigationTiming);
+  aiDetection = detectAIFromReferrer(document.referrer) || detectAIFromUTM(window.location.href);
+  if (aiDetection) {
+    log("AI detected:", aiDetection);
+  }
+  initialized = true;
+  if (!userConfig.disableAutoPageview) {
+    pageview();
+  }
+  if (!userConfig.disableBehavioral) {
+    setupBehavioralTracking();
+  }
+  log("Initialization complete");
+}
+function pageview(customUrl) {
+  if (!initialized) {
+    log("Not initialized, call init() first");
+    return;
+  }
+  const url = customUrl || window.location.href;
+  const payload = {
+    visitor_id: visitorId,
+    session_id: sessionId,
+    url,
+    referrer: document.referrer || null,
+    title: document.title || null,
+    utm_source: extractUTMParams(url).utm_source || null,
+    utm_medium: extractUTMParams(url).utm_medium || null,
+    utm_campaign: extractUTMParams(url).utm_campaign || null,
+    user_agent: navigator.userAgent,
+    screen_width: window.screen?.width,
+    screen_height: window.screen?.height,
+    language: navigator.language,
+    timezone: Intl.DateTimeFormat().resolvedOptions().timeZone,
+    tracker_version: VERSION,
+    navigation_timing: navigationTiming,
+    ai_platform: aiDetection?.platform || null,
+    is_ai_referrer: aiDetection?.isAI || false
+  };
+  log("Pageview:", payload);
+  safeFetch(endpoint(DEFAULT_CONFIG.endpoints.visit), {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify(payload)
+  });
+}
+function track(eventName, options = {}) {
+  if (!initialized) {
+    log("Not initialized, call init() first");
+    return;
+  }
+  const payload = {
+    visitor_id: visitorId,
+    session_id: sessionId,
+    event_name: eventName,
+    event_type: "custom",
+    properties: options.properties || {},
+    revenue: options.revenue,
+    currency: options.currency || "USD",
+    url: window.location.href,
+    timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+    tracker_version: VERSION
+  };
+  log("Event:", eventName, payload);
+  safeFetch(endpoint("/api/ingest/event"), {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify(payload)
+  });
+}
+function conversion(eventName, revenue, currency = "USD") {
+  track(eventName, { revenue, currency, properties: { type: "conversion" } });
+}
+function identify(userId, traits = {}) {
+  if (!initialized) {
+    log("Not initialized, call init() first");
+    return;
+  }
+  log("Identify:", userId, traits);
+  const payload = {
+    visitor_id: visitorId,
+    session_id: sessionId,
+    user_id: userId,
+    traits,
+    timestamp: (/* @__PURE__ */ new Date()).toISOString()
+  };
+  safeFetch(endpoint("/api/ingest/identify"), {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify(payload)
+  });
+}
+function setupBehavioralTracking() {
+  let maxScrollDepth = 0;
+  let lastScrollUpdate = 0;
+  let lastTimeUpdate = Date.now();
+  let scrollTicking = false;
+  window.addEventListener("scroll", () => {
+    if (!scrollTicking) {
+      requestAnimationFrame(() => {
+        const scrollPercent = Math.round(
+          (window.scrollY + window.innerHeight) / document.documentElement.scrollHeight * 100
+        );
+        if (scrollPercent > maxScrollDepth) {
+          maxScrollDepth = scrollPercent;
+          const milestones = [25, 50, 75, 100];
+          for (const milestone of milestones) {
+            if (scrollPercent >= milestone && lastScrollUpdate < milestone) {
+              lastScrollUpdate = milestone;
+              sendBehavioralEvent("scroll_depth", { depth: milestone });
+            }
+          }
+        }
+        scrollTicking = false;
+      });
+      scrollTicking = true;
+    }
+  });
+  const trackTimeSpent = () => {
+    const now = Date.now();
+    const delta = now - lastTimeUpdate;
+    if (delta >= DEFAULT_CONFIG.timeSpentThresholdMs) {
+      lastTimeUpdate = now;
+      sendBehavioralEvent("time_spent", {
+        seconds: Math.round(delta / 1e3),
+        total_seconds: Math.round((now - (sessionStartTime || now)) / 1e3)
+      });
+    }
+  };
+  document.addEventListener("visibilitychange", () => {
+    if (document.visibilityState === "hidden") {
+      trackTimeSpent();
+    }
+  });
+  window.addEventListener("beforeunload", () => {
+    trackTimeSpent();
+    if (maxScrollDepth > 0) {
+      sendBeacon(endpoint(DEFAULT_CONFIG.endpoints.behavioral), {
+        visitor_id: visitorId,
+        session_id: sessionId,
+        event_type: "scroll_depth_final",
+        data: { depth: maxScrollDepth },
+        url: window.location.href
+      });
+    }
+  });
+  document.addEventListener("focusin", (e) => {
+    const target = e.target;
+    if (target.tagName === "INPUT" || target.tagName === "TEXTAREA" || target.tagName === "SELECT") {
+      sendBehavioralEvent("form_focus", {
+        field_type: target.tagName.toLowerCase(),
+        field_name: target.name || target.id || "unknown"
+      });
+    }
+  });
+  document.addEventListener("submit", (e) => {
+    const form = e.target;
+    sendBehavioralEvent("form_submit", {
+      form_id: form.id || form.name || "unknown",
+      form_action: form.action ? new URL(form.action).pathname : "unknown"
+    });
+  });
+  document.addEventListener("click", (e) => {
+    const target = e.target;
+    const link = target.closest("a");
+    if (link && link.href) {
+      const isExternal = link.hostname !== window.location.hostname;
+      sendBehavioralEvent("click", {
+        element: "link",
+        href: truncateText(link.href, 200),
+        text: truncateText(link.textContent || "", 100),
+        is_external: isExternal
+      });
+    }
+  });
+}
+function sendBehavioralEvent(eventType, data) {
+  const payload = {
+    visitor_id: visitorId,
+    session_id: sessionId,
+    event_type: eventType,
+    data,
+    url: window.location.href,
+    timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+    tracker_version: VERSION
+  };
+  log("Behavioral:", eventType, data);
+  safeFetch(endpoint(DEFAULT_CONFIG.endpoints.behavioral), {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify(payload)
+  });
+}
+function getCurrentSessionId() {
+  return sessionId;
+}
+function getCurrentVisitorId() {
+  return visitorId;
+}
+function getAIDetectionResult() {
+  return aiDetection;
+}
+function getNavigationTimingResult() {
+  return navigationTiming;
+}
+function isTrackerInitialized() {
+  return initialized;
+}
+function reset() {
+  log("Resetting tracker");
+  initialized = false;
+  visitorId = null;
+  sessionId = null;
+  sessionStartTime = null;
+  navigationTiming = null;
+  aiDetection = null;
+  try {
+    sessionStorage.removeItem("loamly_session");
+    sessionStorage.removeItem("loamly_start");
+  } catch {
+  }
+}
+function setDebug(enabled) {
+  debugMode = enabled;
+  log("Debug mode:", enabled ? "enabled" : "disabled");
+}
+var loamly = {
+  init,
+  pageview,
+  track,
+  conversion,
+  identify,
+  getSessionId: getCurrentSessionId,
+  getVisitorId: getCurrentVisitorId,
+  getAIDetection: getAIDetectionResult,
+  getNavigationTiming: getNavigationTimingResult,
+  isInitialized: isTrackerInitialized,
+  reset,
+  debug: setDebug
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  AI_BOT_PATTERNS,
+  AI_PLATFORMS,
+  VERSION,
+  detectAIFromReferrer,
+  detectAIFromUTM,
+  detectNavigationType,
+  loamly
+});
+/**
+ * Loamly Tracker
+ * 
+ * Open-source AI traffic detection for websites.
+ * See what AI tells your customers — and track when they click.
+ * 
+ * @module @loamly/tracker
+ * @license MIT
+ * @see https://loamly.ai
+ */
+//# sourceMappingURL=index.cjs.map