@levo-so/insights 0.1.65 → 0.1.76

package/dist/constants/storageKeys.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Storage keys used by the insights module.
+ * These are the same keys used in createLevoInsights.
+ */
+export declare const STORAGE_KEYS: {
+    /** Legacy: Lock key for identify operation (no longer used internally) */
+    readonly identify: "lock:lv_aud_identify";
+    /** Key for tracking open tab count */
+    readonly open_tabs: "lv_insights_ot";
+    /** Key for current tab ID (sessionStorage) */
+    readonly current_tab: "lv_insights_ct";
+    /** Key for all tabs registry */
+    readonly all_tabs: "lv_insights_at";
+    /** Device JWT for direct mode (1yr expiry, rotated on /welcome, analytics-only scope) */
+    readonly device_token: "lv_aud_device";
+    /** Session JWT for direct mode (1yr expiry, rotated on /welcome, analytics-only scope) */
+    readonly session_token: "lv_aud_session";
+    /** Cached insights mode ('proxy' | 'direct') */
+    readonly mode: "lv_aud_mode";
+    /** Key to store session data **/
+    readonly session: "lv_insights_session";
+};

package/dist/index.d.ts

@@ -1,305 +1,4 @@
-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 };
+export * from './lib/insights';
+export * from './types/analytics';
+export * from './types/identity';
+export * from './types/options';