@levo-so/insights 0.1.61

package/dist/index.d.ts

@@ -0,0 +1,305 @@
+import { ILevoClient } from '@levo-so/core';
+import { AnalyticsInstance } from 'analytics';
+
+declare const AnalyticsEventsList: readonly ["bevy.collection.filled", "bevy.collection.submitted", "bevy.collection.view", "block.view", "blog.post.view", "event.booking.confirmed", "event.booking.initiated", "event.booking.pending", "event.coupon.applied", "event.event.view", "form.change", "form.submit", "membership.account.signin", "membership.account.signout", "membership.account.signup", "button.click", "page.bounce", "page.click", "page.copy", "page.impression", "page.scroll", "page.view", "page.selection", "user.active", "user.idle"];
+type AnalyticsEventType = (typeof AnalyticsEventsList)[number];
+declare const AnalyticsEvents: {
+    "bevy.collection.filled": "bevy.collection.filled";
+    "bevy.collection.submitted": "bevy.collection.submitted";
+    "bevy.collection.view": "bevy.collection.view";
+    "block.view": "block.view";
+    "blog.post.view": "blog.post.view";
+    "event.booking.confirmed": "event.booking.confirmed";
+    "event.booking.initiated": "event.booking.initiated";
+    "event.booking.pending": "event.booking.pending";
+    "event.coupon.applied": "event.coupon.applied";
+    "event.event.view": "event.event.view";
+    "form.change": "form.change";
+    "form.submit": "form.submit";
+    "membership.account.signin": "membership.account.signin";
+    "membership.account.signout": "membership.account.signout";
+    "membership.account.signup": "membership.account.signup";
+    "button.click": "button.click";
+    "page.bounce": "page.bounce";
+    "page.click": "page.click";
+    "page.copy": "page.copy";
+    "page.impression": "page.impression";
+    "page.scroll": "page.scroll";
+    "page.view": "page.view";
+    "page.selection": "page.selection";
+    "user.active": "user.active";
+    "user.idle": "user.idle";
+};
+declare namespace ILevoAudience {
+    interface Traits {
+        private_mode: boolean;
+        dark_mode: boolean;
+        locale: string;
+        timezone: string;
+        referrer: {
+            type: string;
+            referrer: Record<string, string>;
+            data: Record<string, string>;
+        };
+        properties: Record<string, any>;
+        withLock?: boolean;
+    }
+    type BaseProperties = Traits & {
+        resource: string;
+        identifier: string;
+    };
+    interface BlockProperties {
+        id: string;
+    }
+    interface ActivityProperties {
+        seconds_idle?: number;
+        seconds_active?: number;
+    }
+    interface ScrollProperties {
+        percent: number;
+    }
+    type Properties = Partial<BaseProperties & BlockProperties & ActivityProperties & ScrollProperties> & Partial<Omit<BaseInput, "workspace_id" | "tab_count" | "tab_id">> & Record<string, any>;
+    type EventProperties = {
+        properties: Properties;
+        traits: Traits;
+        event: AnalyticsEventType;
+        type: "track" | "page" | "identify";
+        userId: string | null;
+    };
+    type BaseInput = {
+        workspace_id: string;
+        site_id?: string;
+        hostname: string;
+        pathname: string;
+        page_title: string;
+        url: string;
+        created_at: string;
+        tab_id: string;
+        tab_count: number;
+    };
+    type WelcomeInput = Traits & BaseInput;
+    type WelcomeResponse = {
+        session: string;
+        device: string;
+    };
+    type CollectInput = BaseInput & {
+        session_id?: string;
+        device_id?: string;
+        event: AnalyticsEventType;
+        version?: number;
+        properties: Properties;
+        resource: string;
+        identifier: string | undefined;
+    };
+    type ActivityStatus = {
+        isIdle: boolean;
+        isDisabled: boolean;
+        active: number;
+        idle: number;
+    };
+}
+
+interface IInsightOptions {
+    /** Site ID for analytics tracking */
+    site?: string | null;
+    insightsUrl?: string;
+    /** Direct insights API URL for third-party mode (when reverse proxy unavailable) */
+    directInsightsUrl?: string;
+    /** Insights mode: 'auto' (default) detects via ping, 'proxy' forces reverse proxy, 'direct' forces direct API */
+    insightsMode?: "auto" | "proxy" | "direct";
+    /** Timeout for proxy ping detection in ms (default: 3000) */
+    pingTimeout?: number;
+}
+
+/**
+ * @fileoverview Levo Audience Analytics Module
+ *
+ * This module provides client-side analytics tracking for Levo-powered websites.
+ * It handles event collection, batching, cross-tab synchronization, and reliable
+ * delivery of analytics data to the Levo Insights API.
+ *
+ * ## Architecture Overview
+ *
+ * ```
+ * ┌────────────────────────────────────────────────────────────────────────┐
+ * │                           Browser Tab                                  │
+ * │  ┌──────────────┐    ┌──────────────┐    ┌──────────────────────────┐  │
+ * │  │  track()     │───▶│  EventQueue  │───▶│  /v1/insights/event/bulk │  │
+ * │  │  page()      │    │  (batching)  │    │  (sendBeacon / fetch)    │  │
+ * │  │  identify()  │    └──────────────┘    └──────────────────────────┘  │
+ * │  └──────────────┘           │                                          │
+ * │         │                   │ flush on:                                │
+ * │         │                   │ - 50 events (BATCH_SIZE)                 │
+ * │         │                   │ - 5s interval (BATCH_INTERVAL_MS)        │
+ * │         │                   │ - page exit (visibilitychange)           │
+ * │         │                   │ - beforeunload / pagehide                │
+ * │         ▼                   │                                          │
+ * │  ┌──────────────┐           │                                          │
+ * │  │ Rate Limiter │───────────┘                                          │
+ * │  │ (500/page)   │                                                      │
+ * │  └──────────────┘                                                      │
+ * └────────────────────────────────────────────────────────────────────────┘
+ *                              │
+ *                              │ BroadcastChannel
+ *                              │ (SESSION_SYNC, SESSION_REQUEST)
+ *                              ▼
+ * ┌────────────────────────────────────────────────────────────────────────┐
+ * │                         Other Browser Tabs                             │
+ * │  - Receive session/device IDs from first tab                           │
+ * │  - Skip /welcome API call if session already established               │
+ * └────────────────────────────────────────────────────────────────────────┘
+ * ```
+ *
+ * ## Key Features
+ *
+ * ### 1. Event Batching
+ * Instead of sending each event immediately (which caused 100+ requests per page),
+ * events are queued and sent in batches. This reduces:
+ * - Network requests by 50-100x
+ * - Server load
+ * - Bandwidth usage
+ *
+ * ### 2. Cross-Tab Session Synchronization
+ * Uses BroadcastChannel API to share session/device IDs across tabs:
+ * - First tab to complete /welcome broadcasts session to others
+ * - Other tabs skip /welcome API call, reducing duplicate sessions
+ * - Solves "Open in New Tab" race condition where multiple tabs would
+ *   each create separate sessions
+ *
+ * ### 3. Reliable Page Exit Handling
+ * Uses multiple mechanisms to ensure events are sent before page unload:
+ * - visibilitychange (most reliable, fires when tab hidden)
+ * - beforeunload (backup for navigation)
+ * - pagehide (backup for bfcache scenarios)
+ * - sendBeacon API (survives page unload)
+ *
+ * ### 4. Rate Limiting
+ * Prevents runaway loops or malicious spam:
+ * - Max 500 events per page
+ * - Counter resets on page navigation
+ *
+ * ## Session Flow
+ *
+ * ```
+ * Page Load
+ *     │
+ *     ▼
+ * initiate() called
+ *     │
+ *     ├── Initialize BroadcastChannel
+ *     │
+ *     ├── Request session from other tabs (SESSION_REQUEST)
+ *     │
+ *     ├── Wait 50ms for response
+ *     │       │
+ *     │       ├── If SESSION_SYNC received: Use shared session, skip /welcome
+ *     │       │
+ *     │       └── If no response: Call /welcome API
+ *     │                   │
+ *     │                   └── On success: Broadcast SESSION_SYNC to other tabs
+ *     │
+ *     └── Start tracking events
+ * ```
+ *
+ * ## API Endpoints Used
+ *
+ * - `POST /v1/insights/event/welcome` - Initial session establishment
+ *   - Called once per session (first tab only, thanks to BroadcastChannel)
+ *   - Returns session_id and device_id from HttpOnly cookies
+ *
+ * - `POST /v1/insights/event/bulk` - Batch event submission
+ *   - Receives array of CollectInput events
+ *   - Used for all event tracking (replaces individual /collect calls)
+ *
+ * ## Configuration Constants
+ *
+ * - BATCH_SIZE (50): Flush queue when this many events accumulated
+ * - BATCH_INTERVAL_MS (5000): Flush queue every 5 seconds regardless of size
+ * - MAX_EVENTS_PER_PAGE (500): Rate limit per page to prevent abuse
+ * - BROADCAST_CHANNEL_NAME ("levo_analytics"): Channel for cross-tab sync
+ *
+ * ## Browser Compatibility
+ *
+ * - BroadcastChannel: Modern browsers (Chrome 54+, Firefox 38+, Safari 15.4+)
+ *   - Gracefully degrades: If unavailable, each tab calls /welcome independently
+ *
+ * - sendBeacon: Universal support (Chrome 39+, Firefox 31+, Safari 11.1+)
+ *   - Fallback: fetch() with keepalive option
+ *
+ * @module @levo-so/core/control/audience
+ */
+
+/**
+ * Creates the Levo Audience analytics module.
+ *
+ * This factory function creates a new audience module instance tied to
+ * a specific Levo control instance and HTTP client. The module manages
+ * all analytics tracking for the page.
+ *
+ * @param core - The Levo control instance containing workspace config
+ * @param httpClient - HTTP client for making API requests
+ * @returns The audience module with tracking methods
+ *
+ * @example
+ * ```typescript
+ * const audience = createLevoAudienceModule(levoControl, httpClient);
+ *
+ * // Initialize on page load
+ * await audience.initiate({ id: 'page-123' });
+ *
+ * // Track custom events
+ * audience.track('button.click', { buttonId: 'cta-signup' });
+ *
+ * // Cleanup on unmount (optional, for SPAs)
+ * audience.destroy();
+ * ```
+ */
+declare const createLevoInsights: (client: ILevoClient, options?: IInsightOptions) => {
+    readonly insightsUrl: string;
+    /** Get the underlying analytics instance (read-only) */
+    readonly instance: AnalyticsInstance | null;
+    /** Check if session has been established (read-only) */
+    readonly is_identified: boolean;
+    /** Storage keys used by the module */
+    storage_keys: {
+        /** Legacy: Lock key for identify operation (no longer used internally) */
+        identify: string;
+        /** Key for tracking open tab count */
+        open_tabs: string;
+        /** Key for current tab ID (sessionStorage) */
+        current_tab: string;
+        /** Key for all tabs registry */
+        all_tabs: string;
+        /** Device JWT for direct mode (1yr expiry, rotated on /welcome, analytics-only scope) */
+        device_token: string;
+        /** Session JWT for direct mode (1yr expiry, rotated on /welcome, analytics-only scope) */
+        session_token: string;
+        /** Cached insights mode ('proxy' | 'direct') */
+        mode: string;
+    };
+    /** Initialize the module for a page */
+    initiate: (properties: ILevoAudience.Properties) => Promise<any>;
+    /** Identify/establish session */
+    identify: (options?: {
+        withLock?: boolean;
+    }) => Promise<void>;
+    /** Track a custom event */
+    track: <T extends ILevoAudience.Properties>(event: AnalyticsEventType, properties: T & ILevoAudience.Properties) => Promise<any>;
+    /** Track a bounce event */
+    bounce: (properties: ILevoAudience.Properties) => Promise<void>;
+    /** Cleanup the module */
+    destroy: () => void;
+};
+/**
+ * Type representing the audience module instance.
+ * Use this when you need to type a variable holding the module.
+ *
+ * @example
+ * ```typescript
+ * let audience: ILevoAudienceModule;
+ * audience = createLevoAudienceModule(core, httpClient);
+ * ```
+ */
+type ILevoInsights = ReturnType<typeof createLevoInsights>;
+
+export { type AnalyticsEventType, AnalyticsEvents, AnalyticsEventsList, type IInsightOptions, ILevoAudience, type ILevoInsights, createLevoInsights };

package/dist/index.js

@@ -0,0 +1,941 @@
+import { onUserActivity } from '@analytics/activity-utils';
+import { getVisitorSource } from '@analytics/visitor-source';
+import { listToRecord, getLevoError } from '@levo-so/core';
+import { Analytics } from 'analytics';
+import getUserLocale from 'get-user-locale';
+
+// src/index.ts
+
+// src/utils/isIncognito.ts
+var isIncognito = () => new Promise((resolve, reject) => {
+  let browserName = "Unknown";
+  function __callback(isPrivate) {
+    resolve({
+      isPrivate,
+      browserName
+    });
+  }
+  function identifyChromium() {
+    const ua = navigator.userAgent;
+    if (ua.match(/Chrome/)) {
+      if (navigator.brave !== void 0) {
+        return "Brave";
+      }
+      if (ua.match(/Edg/)) {
+        return "Edge";
+      }
+      if (ua.match(/OPR/)) {
+        return "Opera";
+      }
+      return "Chrome";
+    }
+    return "Chromium";
+  }
+  function assertEvalToString(value) {
+    return value === eval.toString().length;
+  }
+  function isSafari() {
+    const v = navigator.vendor;
+    return v !== void 0 && v.indexOf("Apple") === 0 && assertEvalToString(37);
+  }
+  function isChrome() {
+    const v = navigator.vendor;
+    return v !== void 0 && v.indexOf("Google") === 0 && assertEvalToString(33);
+  }
+  function isFirefox() {
+    return document.documentElement !== void 0 && document.documentElement.style.MozAppearance !== void 0 && assertEvalToString(37);
+  }
+  function isMSIE() {
+    return navigator.msSaveBlob !== void 0 && assertEvalToString(39);
+  }
+  function newSafariTest() {
+    const tmp_name = String(Math.random());
+    try {
+      const db = window.indexedDB.open(tmp_name, 1);
+      db.onupgradeneeded = (i) => {
+        const res = i.target?.result;
+        try {
+          res.createObjectStore("test", {
+            autoIncrement: true
+          }).put(new Blob());
+          __callback(false);
+        } catch (e) {
+          let message = e;
+          if (e instanceof Error) {
+            message = e.message ?? e;
+          }
+          if (typeof message !== "string") {
+            return __callback(false);
+          }
+          const matchesExpectedError = /BlobURLs are not yet supported/.test(message);
+          return __callback(matchesExpectedError);
+        } finally {
+          res.close();
+          window.indexedDB.deleteDatabase(tmp_name);
+        }
+      };
+    } catch (e) {
+      return __callback(false);
+    }
+  }
+  function oldSafariTest() {
+    const openDB = window.openDatabase;
+    const storage = window.localStorage;
+    try {
+      openDB(null, null, null, null);
+    } catch (e) {
+      return __callback(true);
+    }
+    try {
+      storage.setItem("test", "1");
+      storage.removeItem("test");
+    } catch (e) {
+      return __callback(true);
+    }
+    return __callback(false);
+  }
+  function safariPrivateTest() {
+    if (navigator.maxTouchPoints !== void 0) {
+      newSafariTest();
+    } else {
+      oldSafariTest();
+    }
+  }
+  function getQuotaLimit() {
+    const w = window;
+    if (w.performance !== void 0 && w.performance.memory !== void 0 && w.performance.memory.jsHeapSizeLimit !== void 0) {
+      return performance.memory.jsHeapSizeLimit;
+    }
+    return 1073741824;
+  }
+  function storageQuotaChromePrivateTest() {
+    navigator.webkitTemporaryStorage.queryUsageAndQuota(
+      (_, quota) => {
+        const quotaInMib = Math.round(quota / (1024 * 1024));
+        const quotaLimitInMib = Math.round(getQuotaLimit() / (1024 * 1024)) * 2;
+        __callback(quotaInMib < quotaLimitInMib);
+      },
+      (e) => {
+        reject(new Error(`detectIncognito somehow failed to query storage quota: ${e.message}`));
+      }
+    );
+  }
+  function oldChromePrivateTest() {
+    const fs = window.webkitRequestFileSystem;
+    const success = () => {
+      __callback(false);
+    };
+    const error = () => {
+      __callback(true);
+    };
+    fs(0, 1, success, error);
+  }
+  function chromePrivateTest() {
+    if (self.Promise !== void 0 && self.Promise.allSettled !== void 0) {
+      storageQuotaChromePrivateTest();
+    } else {
+      oldChromePrivateTest();
+    }
+  }
+  function firefoxPrivateTest() {
+    __callback(navigator.serviceWorker === void 0);
+  }
+  function msiePrivateTest() {
+    __callback(window.indexedDB === void 0);
+  }
+  function main() {
+    if (isSafari()) {
+      browserName = "Safari";
+      safariPrivateTest();
+    } else if (isChrome()) {
+      browserName = identifyChromium();
+      chromePrivateTest();
+    } else if (isFirefox()) {
+      browserName = "Firefox";
+      firefoxPrivateTest();
+    } else if (isMSIE()) {
+      browserName = "Internet Explorer";
+      msiePrivateTest();
+    } else {
+      reject(new Error("detectIncognito cannot determine the browser"));
+    }
+  }
+  main();
+});
+var isIncognito_default = isIncognito;
+
+// src/utils/getUserProperties.ts
+var getGPUInfo = () => {
+  const canvas = document.createElement("canvas");
+  const gl = canvas?.getContext("webgl") || canvas?.getContext("experimental-webgl");
+  if (!gl) {
+    return null;
+  }
+  const debugInfo = gl?.getExtension("WEBGL_debug_renderer_info");
+  return debugInfo ? gl?.getParameter(debugInfo.UNMASKED_RENDERER_WEBGL) : null;
+};
+var getUserProperties = async () => {
+  let locale = "";
+  let timezone = "";
+  let dark_mode = false;
+  let private_mode = false;
+  const properties = {};
+  if (!window) {
+    return {
+      locale,
+      timezone,
+      dark_mode,
+      private_mode,
+      properties
+    };
+  }
+  try {
+    ({ isPrivate: private_mode } = await isIncognito_default());
+  } catch (e) {
+    console.error(e);
+  }
+  try {
+    dark_mode = window.matchMedia?.("(prefers-color-scheme: dark)").matches;
+  } catch (e) {
+    console.error(e);
+  }
+  try {
+    timezone = Intl.DateTimeFormat().resolvedOptions().timeZone;
+  } catch (e) {
+    console.error(e);
+  }
+  try {
+    locale = getUserLocale();
+  } catch (e) {
+    console.error(e);
+  }
+  if (navigator && "connection" in navigator) {
+    const connection = navigator.connection || navigator?.mozConnection || navigator.webkitConnection;
+    properties.network_type = connection.effectiveType;
+  }
+  properties.width = window?.innerWidth;
+  properties.height = window?.innerHeight;
+  properties.pixel_ratio = window?.devicePixelRatio;
+  if (screen) {
+    properties.screen_width = screen?.width;
+    properties.screen_height = screen?.height;
+    properties.color_depth = screen?.colorDepth;
+    properties.orientation = screen?.orientation?.type;
+  }
+  if (navigator && "getBattery" in navigator) {
+    const battery = await navigator?.getBattery();
+    if (battery) {
+      properties.battery_level = Number((battery?.level * 100).toFixed(0));
+      properties.battery_charging = battery?.charging;
+      properties.battery_discharging_time = battery?.dischargingTime;
+      properties.battery_full_charge_capacity = battery?.fullChargeCapacity;
+      properties.battery_charging_time = battery?.chargingTime;
+    }
+  }
+  if (navigator && "deviceMemory" in navigator) {
+    properties.device_memory = navigator?.deviceMemory;
+  }
+  const supportsTouch = "ontouchstart" in window || typeof navigator?.maxTouchPoints !== "undefined" && navigator?.maxTouchPoints > 0;
+  properties.touch_supported = supportsTouch;
+  if ("hardwareConcurrency" in navigator) {
+    properties.hardware_concurrency = navigator?.hardwareConcurrency;
+  }
+  if (navigator && "mediaDevices" in navigator) {
+    const mediaDevices = navigator?.mediaDevices;
+    const devices = await mediaDevices?.enumerateDevices();
+    const hasCamera = devices.some((device) => device?.kind === "videoinput");
+    properties.camera_supported = hasCamera;
+    const hasMicrophone = devices.some((device) => device?.kind === "audioinput");
+    properties.microphone_supported = hasMicrophone;
+  }
+  properties.gpu = getGPUInfo();
+  return {
+    locale,
+    timezone,
+    dark_mode,
+    private_mode,
+    properties
+  };
+};
+var AnalyticsEventsList = [
+  // Bevy Events
+  "bevy.collection.filled",
+  "bevy.collection.submitted",
+  "bevy.collection.view",
+  // Block Events
+  "block.view",
+  // Blog Events
+  "blog.post.view",
+  // Event Events
+  "event.booking.confirmed",
+  "event.booking.initiated",
+  "event.booking.pending",
+  "event.coupon.applied",
+  "event.event.view",
+  // Form Events
+  "form.change",
+  "form.submit",
+  // Membership Events
+  "membership.account.signin",
+  "membership.account.signout",
+  "membership.account.signup",
+  // UI Events
+  "button.click",
+  "page.bounce",
+  "page.click",
+  "page.copy",
+  "page.impression",
+  "page.scroll",
+  "page.view",
+  "page.selection",
+  // User Activity Events
+  "user.active",
+  "user.idle"
+];
+var AnalyticsEvents = listToRecord(AnalyticsEventsList);
+
+// src/index.ts
+var BATCH_SIZE = 50;
+var BATCH_INTERVAL_MS = 5e3;
+var MAX_EVENTS_PER_PAGE = 500;
+var BROADCAST_CHANNEL_NAME = "levo_analytics";
+var createLevoInsights = (client, options = {}) => {
+  const { workspace, fetch: levoFetch, NODE_ENV } = client;
+  const {
+    insightsMode = "auto",
+    insightsUrl = "",
+    directInsightsUrl = "",
+    pingTimeout: providedPingTimeout = 3e3,
+    site
+  } = options;
+  const pingTimeout = Number.isFinite(providedPingTimeout) && providedPingTimeout >= 0 ? providedPingTimeout : 3e3;
+  const _IDLE_THROTTLE = 1 * 1e3;
+  const _IDLE_TIMEOUT = 60 * 1e3;
+  let instance = null;
+  let idle_listener = null;
+  const storage_keys = {
+    /** Legacy: Lock key for identify operation (no longer used internally) */
+    identify: "lock:lv_aud_identify",
+    /** Key for tracking open tab count */
+    open_tabs: "lv_insights_ot",
+    /** Key for current tab ID (sessionStorage) */
+    current_tab: "lv_insights_ct",
+    /** Key for all tabs registry */
+    all_tabs: "lv_insights_at",
+    /** Device JWT for direct mode (1yr expiry, rotated on /welcome, analytics-only scope) */
+    device_token: "lv_aud_device",
+    /** Session JWT for direct mode (1yr expiry, rotated on /welcome, analytics-only scope) */
+    session_token: "lv_aud_session",
+    /** Cached insights mode ('proxy' | 'direct') */
+    mode: "lv_aud_mode"
+  };
+  let _insightsMode = "proxy";
+  let _insightsBaseUrl = "";
+  let _localStorageAvailable = true;
+  const _memoryStorage = /* @__PURE__ */ new Map();
+  const checkLocalStorageAvailable = () => {
+    if (typeof window === "undefined" || !("localStorage" in window)) {
+      return false;
+    }
+    try {
+      const testKey = "__levo_test__";
+      window.localStorage.setItem(testKey, "test");
+      window.localStorage.removeItem(testKey);
+      return true;
+    } catch {
+      return false;
+    }
+  };
+  const getFromStorage = (key) => {
+    if (typeof window === "undefined") {
+      return _memoryStorage.get(key) || null;
+    }
+    if (_localStorageAvailable) {
+      try {
+        return window.localStorage.getItem(key);
+      } catch {
+        return _memoryStorage.get(key) || null;
+      }
+    }
+    return _memoryStorage.get(key) || null;
+  };
+  const setInStorage = (key, value) => {
+    if (typeof window === "undefined") {
+      _memoryStorage.set(key, value);
+      return;
+    }
+    if (_localStorageAvailable) {
+      try {
+        window.localStorage.setItem(key, value);
+        return;
+      } catch {
+      }
+    }
+    _memoryStorage.set(key, value);
+  };
+  const removeFromStorage = (key) => {
+    _memoryStorage.delete(key);
+    if (typeof window === "undefined" || !_localStorageAvailable) {
+      return;
+    }
+    try {
+      window.localStorage.removeItem(key);
+    } catch {
+    }
+  };
+  const getAuthHeaders = () => {
+    const headers = {};
+    if (_insightsMode === "direct") {
+      const deviceToken = getFromStorage(storage_keys.device_token);
+      const sessionToken = getFromStorage(storage_keys.session_token);
+      if (deviceToken) headers["Levo-Audience-Device"] = deviceToken;
+      if (sessionToken) headers["Levo-Audience-Session"] = sessionToken;
+    }
+    return headers;
+  };
+  const pingEndpoint = async (url, timeout) => {
+    let timeoutId = null;
+    try {
+      const controller = new AbortController();
+      timeoutId = setTimeout(() => controller.abort(), timeout);
+      const response = await fetch(url, {
+        method: "GET",
+        signal: controller.signal,
+        credentials: "omit"
+      });
+      return response.ok;
+    } catch {
+      return false;
+    } finally {
+      if (timeoutId) {
+        clearTimeout(timeoutId);
+      }
+    }
+  };
+  const detectInsightsMode = async () => {
+    if (insightsMode === "proxy") {
+      _insightsBaseUrl = insightsUrl;
+      return "proxy";
+    }
+    if (insightsMode === "direct") {
+      if (!directInsightsUrl) {
+        console.warn(
+          "[@levo-so/core] insightsMode='direct' but directInsightsUrl not set. Falling back to proxy."
+        );
+        _insightsBaseUrl = insightsUrl;
+        return "proxy";
+      }
+      _insightsBaseUrl = directInsightsUrl;
+      setInStorage(storage_keys.mode, "direct");
+      return "direct";
+    }
+    const cachedMode = getFromStorage(storage_keys.mode);
+    if (cachedMode === "proxy" || cachedMode === "direct") {
+      if (cachedMode === "direct" && !directInsightsUrl) {
+        removeFromStorage(storage_keys.mode);
+        _insightsBaseUrl = "";
+      } else {
+        const pingUrl = cachedMode === "proxy" ? `${insightsUrl}/ping` : `${directInsightsUrl}/ping`;
+        if (await pingEndpoint(pingUrl, pingTimeout)) {
+          _insightsBaseUrl = cachedMode === "proxy" ? insightsUrl : directInsightsUrl;
+          return cachedMode;
+        }
+      }
+    }
+    if (await pingEndpoint(`${insightsUrl}/ping`, pingTimeout)) {
+      setInStorage(storage_keys.mode, "proxy");
+      _insightsBaseUrl = insightsUrl;
+      return "proxy";
+    }
+    if (directInsightsUrl) {
+      setInStorage(storage_keys.mode, "direct");
+      _insightsBaseUrl = directInsightsUrl;
+      return "direct";
+    }
+    _insightsBaseUrl = insightsUrl;
+    return "proxy";
+  };
+  let _session = "";
+  let _device = "";
+  let is_identified = false;
+  let _eventCount = 0;
+  let _eventQueue = [];
+  let _flushTimer = null;
+  let _visibilityHandler = null;
+  let _beforeUnloadHandler = null;
+  let _pageHideHandler = null;
+  let _channel = null;
+  let _pendingIdentify = false;
+  const buildSessionSyncMessage = () => {
+    const message = {
+      type: "SESSION_SYNC",
+      session: _session,
+      device: _device
+    };
+    if (_insightsMode === "direct") {
+      const storedDeviceToken = getFromStorage(storage_keys.device_token);
+      const storedSessionToken = getFromStorage(storage_keys.session_token);
+      if (storedDeviceToken) message.deviceToken = storedDeviceToken;
+      if (storedSessionToken) message.sessionToken = storedSessionToken;
+    }
+    return message;
+  };
+  const initBroadcastChannel = () => {
+    if (typeof BroadcastChannel === "undefined") {
+      return;
+    }
+    try {
+      _channel = new BroadcastChannel(BROADCAST_CHANNEL_NAME);
+      _channel.onmessage = (event) => {
+        const { type, session, device, deviceToken, sessionToken } = event.data;
+        if (type === "SESSION_SYNC" && !is_identified) {
+          _session = session;
+          _device = device;
+          is_identified = true;
+          _pendingIdentify = false;
+          if (_insightsMode === "direct" && deviceToken && sessionToken) {
+            setInStorage(storage_keys.device_token, deviceToken);
+            setInStorage(storage_keys.session_token, sessionToken);
+          }
+        }
+        if (type === "SESSION_REQUEST" && is_identified) {
+          _channel?.postMessage(buildSessionSyncMessage());
+        }
+      };
+    } catch {
+    }
+  };
+  const requestSessionFromOtherTabs = () => {
+    _channel?.postMessage({ type: "SESSION_REQUEST" });
+  };
+  const broadcastSession = () => {
+    _channel?.postMessage(buildSessionSyncMessage());
+  };
+  const flushEventQueue = () => {
+    const baseUrl = _insightsBaseUrl || insightsUrl;
+    if (_eventQueue.length === 0 || !baseUrl || !workspace) {
+      return;
+    }
+    const batch = _eventQueue.map((event) => ({
+      ...event,
+      session_id: event.session_id || _session,
+      device_id: event.device_id || _device
+    }));
+    _eventQueue = [];
+    const url = `${baseUrl}/v1/insights/event/bulk?workspace=${workspace}`;
+    const headers = {
+      "Content-Type": "application/json",
+      ...getAuthHeaders()
+    };
+    if (_insightsMode === "proxy" && navigator.sendBeacon) {
+      const success = navigator.sendBeacon(url, JSON.stringify(batch));
+      if (success) {
+        return;
+      }
+    }
+    fetch(url, {
+      method: "POST",
+      body: JSON.stringify(batch),
+      headers,
+      keepalive: true,
+      credentials: _insightsMode === "proxy" ? "include" : "omit"
+    }).catch(() => {
+    });
+  };
+  const startFlushTimer = () => {
+    if (_flushTimer) {
+      return;
+    }
+    _flushTimer = setInterval(() => {
+      flushEventQueue();
+    }, BATCH_INTERVAL_MS);
+    if (typeof document !== "undefined") {
+      _visibilityHandler = () => {
+        if (document.visibilityState === "hidden") {
+          flushEventQueue();
+        }
+      };
+      _beforeUnloadHandler = () => {
+        flushEventQueue();
+      };
+      _pageHideHandler = () => {
+        flushEventQueue();
+      };
+      document.addEventListener("visibilitychange", _visibilityHandler);
+      window.addEventListener("beforeunload", _beforeUnloadHandler);
+      window.addEventListener("pagehide", _pageHideHandler);
+    }
+  };
+  const stopFlushTimer = () => {
+    if (_flushTimer) {
+      clearInterval(_flushTimer);
+      _flushTimer = null;
+    }
+    if (typeof document !== "undefined") {
+      if (_visibilityHandler) {
+        document.removeEventListener("visibilitychange", _visibilityHandler);
+        _visibilityHandler = null;
+      }
+      if (_beforeUnloadHandler) {
+        window.removeEventListener("beforeunload", _beforeUnloadHandler);
+        _beforeUnloadHandler = null;
+      }
+      if (_pageHideHandler) {
+        window.removeEventListener("pagehide", _pageHideHandler);
+        _pageHideHandler = null;
+      }
+    }
+  };
+  const queueEvent = (collectInput) => {
+    if (_eventCount >= MAX_EVENTS_PER_PAGE) {
+      console.warn(`[@levo-so/core] Event limit (${MAX_EVENTS_PER_PAGE}) reached for this page`);
+      return;
+    }
+    _eventCount++;
+    _eventQueue.push(collectInput);
+    if (_eventQueue.length >= BATCH_SIZE) {
+      flushEventQueue();
+    }
+  };
+  const getReferrer = () => {
+    if (typeof document === "undefined") {
+      return {};
+    }
+    const {
+      type,
+      referrer,
+      data = {}
+    } = getVisitorSource({
+      referrer: document.referrer,
+      currentUrl: window.location.href,
+      mapper: null
+    });
+    const dataKeys = Object.keys(data);
+    for (const key of dataKeys) {
+      if (data[key] && Array.isArray(data[key]) && data[key].length > 0) {
+        data[key] = data[key]?.[0];
+      }
+    }
+    return { type, referrer, data, raw: document.referrer };
+  };
+  const getCurrentTabId = () => {
+    try {
+      if (typeof window === "undefined" || !("sessionStorage" in window)) {
+        return "";
+      }
+      return window.sessionStorage.getItem(storage_keys.current_tab) || "";
+    } catch {
+      return "";
+    }
+  };
+  const getTabCount = () => {
+    try {
+      if (typeof window === "undefined" || !("localStorage" in window)) {
+        return 0;
+      }
+      return Number(window.localStorage.getItem(storage_keys.open_tabs)) || 0;
+    } catch {
+      return 0;
+    }
+  };
+  const getActivityStatus = () => {
+    const status = idle_listener?.getStatus();
+    if (!status) {
+      return null;
+    }
+    return {
+      status: status.isIdle ? "idle" : "active",
+      seconds: status.isIdle ? status.idle : status.active
+    };
+  };
+  const identify = async (options2) => {
+    if (!instance) {
+      return;
+    }
+    const withLock = options2?.withLock ?? true;
+    const referrer = getReferrer();
+    const traits = await getUserProperties();
+    await instance.identify("", {
+      ...traits,
+      referrer,
+      withLock
+    });
+  };
+  const request = async (url, data) => {
+    const headers = {
+      Accept: "application/json",
+      "Content-Type": "application/json",
+      ...getAuthHeaders()
+    };
+    try {
+      const response = await levoFetch.url(_insightsBaseUrl || insightsUrl, true).url(url).options({
+        keepAlive: true,
+        credentials: _insightsMode === "proxy" ? "include" : "omit"
+      }).headers(headers).post(data).json();
+      return response;
+    } catch (error) {
+      console.warn(`Analytics request failed for ${url}:`, error);
+      return null;
+    }
+  };
+  const initiate = async (properties) => {
+    if (NODE_ENV === "development") {
+      return;
+    }
+    _eventCount = 0;
+    _localStorageAvailable = checkLocalStorageAvailable();
+    _insightsMode = await detectInsightsMode();
+    initBroadcastChannel();
+    requestSessionFromOtherTabs();
+    startFlushTimer();
+    await new Promise((resolve) => setTimeout(resolve, 50));
+    const plugin = {
+      name: workspace,
+      /**
+       * Handle track events (custom events like clicks, scrolls, etc.)
+       *
+       * Enriches the event with:
+       * - Session/device IDs
+       * - Page metadata (URL, title, etc.)
+       * - Tab information
+       * - Timestamp
+       *
+       * Then queues for batched sending.
+       */
+      track: ({ payload }) => {
+        if (!insightsUrl || !workspace) {
+          return;
+        }
+        const payloadProperties = payload?.properties || {};
+        const collectInput = {
+          session_id: _session,
+          device_id: _device,
+          event: payload.event,
+          version: payload.version || 1,
+          workspace_id: workspace,
+          site_id: site || void 0,
+          properties: {
+            ...properties,
+            ...payloadProperties,
+            // Remove metadata fields from properties (they're top-level)
+            version: void 0,
+            resource: void 0,
+            identifier: void 0,
+            hostname: void 0,
+            pathname: void 0,
+            url: void 0,
+            page_title: void 0,
+            created_at: void 0
+          },
+          hostname: payload?.hostname || window.location.hostname,
+          pathname: payload?.pathname || window.location.pathname,
+          url: payload?.url || window.location.href,
+          page_title: payload?.page_title || document.title,
+          resource: payloadProperties?.resource || "page",
+          identifier: payloadProperties?.identifier || properties?.id,
+          created_at: payload?.created_at || (/* @__PURE__ */ new Date()).toISOString(),
+          tab_id: getCurrentTabId(),
+          tab_count: getTabCount()
+        };
+        queueEvent(collectInput);
+      },
+      /**
+       * Handle page view events.
+       *
+       * Called when navigating to a new page (in SPAs) or on initial load.
+       * Resets the rate limit counter and tracks a page.view event.
+       */
+      page: ({ payload }) => {
+        if (!insightsUrl) {
+          return;
+        }
+        _eventCount = 0;
+        const payloadProperties = payload?.properties || {};
+        track("page.view", {
+          ...properties,
+          ...payloadProperties,
+          title: document.title,
+          identifier: properties.id,
+          resource: "page"
+        });
+      },
+      /**
+       * Handle identify events (session establishment).
+       *
+       * This is called when identify() is invoked. It:
+       * 1. Checks if already identified (via BroadcastChannel) - if so, skip
+       * 2. Calls /welcome API to get session/device IDs
+       * 3. On success, broadcasts session to other tabs
+       *
+       * The /welcome API uses HttpOnly cookies to maintain persistent
+       * device identity across sessions.
+       */
+      identify: ({ payload }) => {
+        if (!insightsUrl || !workspace) {
+          return;
+        }
+        if (is_identified) {
+          return;
+        }
+        if (_pendingIdentify) {
+          return;
+        }
+        _pendingIdentify = true;
+        const welcomeInput = {
+          private_mode: payload.traits.private_mode,
+          dark_mode: payload.traits.dark_mode,
+          timezone: payload.traits.timezone,
+          locale: payload.traits.locale,
+          referrer: payload.traits.referrer,
+          properties: payload.traits.properties,
+          workspace_id: workspace,
+          site_id: site || void 0,
+          hostname: window.location.hostname,
+          pathname: window.location.pathname,
+          page_title: document.title,
+          url: window.location.href,
+          created_at: (/* @__PURE__ */ new Date()).toISOString(),
+          tab_id: getCurrentTabId(),
+          tab_count: getTabCount()
+        };
+        request(
+          `/v1/insights/event/welcome`,
+          welcomeInput
+        ).then((data) => {
+          if (is_identified) {
+            _pendingIdentify = false;
+            return;
+          }
+          is_identified = true;
+          _pendingIdentify = false;
+          if (data?.content?.data?.session) {
+            _session = data?.content.data.session;
+          }
+          if (data?.content?.data?.device) {
+            _device = data?.content.data.device;
+          }
+          if (_insightsMode === "direct" && data?.content?.meta) {
+            const meta = data.content.meta;
+            if (meta.device_token) {
+              setInStorage(storage_keys.device_token, meta.device_token);
+            }
+            if (meta.session_token) {
+              setInStorage(storage_keys.session_token, meta.session_token);
+            }
+          }
+          broadcastSession();
+        }).catch((e) => {
+          _pendingIdentify = false;
+          return getLevoError(e);
+        });
+      }
+    };
+    instance = Analytics({
+      app: workspace || "",
+      plugins: [plugin]
+    });
+    await identify();
+    startActivityListener();
+    return instance.page({
+      resource: "page",
+      identifier: properties.id
+    });
+  };
+  const startActivityListener = () => {
+    if (typeof document !== "undefined" && !idle_listener) {
+      idle_listener = onUserActivity({
+        timeout: _IDLE_TIMEOUT,
+        throttle: _IDLE_THROTTLE,
+        onIdle: (activeForSeconds) => {
+          track("user.idle", {
+            seconds_active: activeForSeconds
+          });
+        },
+        onWakeUp: (idleForSeconds) => {
+          track("user.active", {
+            seconds_idle: idleForSeconds
+          });
+        }
+      });
+    }
+    return null;
+  };
+  const bounce = async (properties) => {
+    const activity_status = getActivityStatus();
+    if (activity_status) {
+      if (activity_status?.status === "idle") {
+        properties.seconds_idle = activity_status.seconds;
+      } else {
+        properties.seconds_active = activity_status.seconds;
+      }
+    }
+    track("page.bounce", properties);
+  };
+  const track = async (event, properties) => {
+    if (!workspace) {
+      return;
+    }
+    if (instance) {
+      return instance.track(event, properties);
+    }
+    const collectInput = {
+      event,
+      version: properties?.version || 1,
+      properties: {
+        ...properties,
+        version: void 0,
+        resource: void 0,
+        identifier: void 0,
+        hostname: void 0,
+        pathname: void 0,
+        url: void 0,
+        page_title: void 0,
+        created_at: void 0
+      },
+      hostname: window.location.hostname,
+      pathname: window.location.pathname,
+      url: window.location.href,
+      page_title: document.title,
+      resource: properties?.resource || "page",
+      identifier: properties?.identifier || properties?.id,
+      workspace_id: workspace,
+      site_id: site || void 0,
+      created_at: (/* @__PURE__ */ new Date()).toISOString(),
+      tab_id: getCurrentTabId(),
+      tab_count: getTabCount()
+    };
+    queueEvent(collectInput);
+  };
+  const destroy = () => {
+    flushEventQueue();
+    stopFlushTimer();
+    _channel?.close();
+  };
+  return {
+    get insightsUrl() {
+      return insightsUrl;
+    },
+    /** Get the underlying analytics instance (read-only) */
+    get instance() {
+      return instance;
+    },
+    /** Check if session has been established (read-only) */
+    get is_identified() {
+      return is_identified;
+    },
+    /** Storage keys used by the module */
+    storage_keys,
+    /** Initialize the module for a page */
+    initiate,
+    /** Identify/establish session */
+    identify,
+    /** Track a custom event */
+    track,
+    /** Track a bounce event */
+    bounce,
+    /** Cleanup the module */
+    destroy
+  };
+};
+
+export { AnalyticsEvents, AnalyticsEventsList, createLevoInsights };

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@levo-so/insights",
+  "version": "0.1.61",
+  "author": "Levo Engineering <devs@theinternetfolks.com>",
+  "description": "Levo analytics",
+  "type": "module",
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist/**",
+    "!dist/**/*.d.ts.map"
+  ],
+  "scripts": {
+    "clean": "rimraf dist node_modules .turbo",
+    "check-types": "tsc --noEmit",
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "demo:serve": "python3 -m http.server 8080",
+    "demo": "pnpm build && pnpm demo:serve"
+  },
+  "dependencies": {
+    "@analytics/activity-utils": "0.2.2",
+    "@analytics/visitor-source": "0.0.7",
+    "@levo-so/core": "workspace:*",
+    "analytics": "0.8.14",
+    "get-user-locale": "2.3.2",
+    "lodash-es": "4.17.21"
+  },
+  "devDependencies": {
+    "@levo/ts-config": "workspace:*",
+    "@types/lodash-es": "4.17.12",
+    "tsup": "8.2.4",
+    "typescript": "5.9.3"
+  },
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  }
+}