@dotcms/analytics 0.0.1-beta.9 → 1.0.0

package/lib/dotAnalytics/plugin/identity/dot-analytics.identity.plugin.d.ts

@@ -0,0 +1,80 @@
+import { DotCMSAnalyticsConfig, DotCMSAnalyticsHookParams } from '../../shared/dot-content-analytics.model';
+
+/**
+ * Identity Plugin for DotAnalytics
+ * Handles user ID generation, session management, and activity tracking.
+ * This plugin provides consistent identity context across all analytics events.
+ *
+ * Plugin execution order:
+ * 1. Identity Plugin (this) - Injects context
+ * 2. Enricher Plugin - Adds page/device/utm data
+ * 3. Main Plugin - Sends to server
+ *
+ * @param {DotCMSAnalyticsConfig} config - Configuration object containing server URL, site key, and debug settings
+ * @returns {Object} Plugin object with methods for initialization and event processing
+ */
+export declare const dotAnalyticsIdentityPlugin: (config: DotCMSAnalyticsConfig) => {
+    name: string;
+    /**
+     * Initialize the identity plugin
+     * Sets up activity tracking for session management
+     */
+    initialize: () => Promise<void>;
+    /**
+     * Inject identity context into page events
+     * This runs BEFORE the enricher plugin
+     */
+    pageStart: ({ payload }: DotCMSAnalyticsHookParams) => {
+        context: import('../../shared/dot-content-analytics.model').DotCMSAnalyticsContext;
+        type: string;
+        properties: {
+            title: string;
+            url: string;
+            path: string;
+            hash: string;
+            search: string;
+            width: number;
+            height: number;
+            referrer?: string | undefined;
+        };
+        options: Record<string, unknown>;
+        userId: string | null;
+        anonymousId: string;
+        meta: {
+            rid: string;
+            ts: number;
+            hasCallback: boolean;
+        };
+    };
+    /**
+     * Inject identity context into track events
+     * This runs BEFORE the enricher plugin
+     */
+    trackStart: ({ payload }: DotCMSAnalyticsHookParams) => {
+        context: import('../../shared/dot-content-analytics.model').DotCMSAnalyticsContext;
+        type: string;
+        properties: {
+            title: string;
+            url: string;
+            path: string;
+            hash: string;
+            search: string;
+            width: number;
+            height: number;
+            referrer?: string | undefined;
+        };
+        options: Record<string, unknown>;
+        userId: string | null;
+        anonymousId: string;
+        meta: {
+            rid: string;
+            ts: number;
+            hasCallback: boolean;
+        };
+    };
+    /**
+     * Clean up on plugin unload
+     * Sets up cleanup handlers for activity tracking
+     */
+    loaded: () => boolean;
+};

package/lib/dotAnalytics/plugin/identity/dot-analytics.identity.plugin.js

@@ -0,0 +1,40 @@
+import { getAnalyticsContext as i } from "../../shared/dot-content-analytics.utils.js";
+import { cleanupActivityTracking as r, initializeActivityTracking as o } from "../../shared/dot-content-analytics.activity-tracker.js";
+const c = (t) => ({
+  name: "dot-analytics-identity",
+  /**
+   * Initialize the identity plugin
+   * Sets up activity tracking for session management
+   */
+  initialize: () => (o(t), Promise.resolve()),
+  /**
+   * Inject identity context into page events
+   * This runs BEFORE the enricher plugin
+   */
+  pageStart: ({ payload: e }) => {
+    const n = i(t);
+    return {
+      ...e,
+      context: n
+    };
+  },
+  /**
+   * Inject identity context into track events
+   * This runs BEFORE the enricher plugin
+   */
+  trackStart: ({ payload: e }) => {
+    const n = i(t);
+    return {
+      ...e,
+      context: n
+    };
+  },
+  /**
+   * Clean up on plugin unload
+   * Sets up cleanup handlers for activity tracking
+   */
+  loaded: () => (typeof window < "u" && (window.addEventListener("beforeunload", r), window.addEventListener("pagehide", r)), !0)
+});
+export {
+  c as dotAnalyticsIdentityPlugin
+};

package/lib/dotAnalytics/plugin/identity/dot-analytics.identity.utils.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Updates activity timestamp
+ */
+export declare const updateActivityTime: () => void;
+/**
+ * Checks if user has been inactive
+ */
+export declare const isUserInactive: () => boolean;
+/**
+ * Checks if a new day has started since session creation
+ */
+export declare const hasPassedMidnight: (sessionStartTime: number) => boolean;
+/**
+ * Gets the last activity time
+ */
+export declare const getLastActivityTime: () => number;
+/**
+ * Extracts UTM parameters from current location
+ */
+export declare const extractUTMParameters: () => Record<string, string>;
+/**
+ * Compares UTM parameters to detect campaign changes
+ */
+export declare const hasUTMChanged: (currentUTM: Record<string, string>) => boolean;

package/lib/dotAnalytics/shared/dot-content-analytics.activity-tracker.d.ts

@@ -0,0 +1,29 @@
+import { DotCMSAnalyticsConfig } from './dot-content-analytics.model';
+
+/**
+ * Updates session activity with throttling
+ */
+export declare const updateSessionActivity: () => void;
+/**
+ * Gets session information for debugging
+ */
+export declare const getSessionInfo: () => {
+    lastActivity: number;
+    isActive: boolean;
+};
+/**
+ * Initializes activity tracking
+ */
+export declare const initializeActivityTracking: (config: DotCMSAnalyticsConfig) => void;
+/**
+ * Cleans up activity tracking listeners
+ */
+export declare const cleanupActivityTracking: () => void;
+/**
+ * Checks if user has been inactive
+ */
+export declare const isUserInactive: () => boolean;
+/**
+ * Gets last activity time
+ */
+export declare const getLastActivity: () => number;

package/lib/dotAnalytics/shared/dot-content-analytics.activity-tracker.js

@@ -0,0 +1,86 @@
+import { DEFAULT_SESSION_TIMEOUT_MINUTES as c, ACTIVITY_EVENTS as r } from "./dot-content-analytics.constants.js";
+class o {
+  constructor() {
+    this.activityListeners = [], this.lastActivityTime = Date.now(), this.inactivityTimer = null, this.isThrottled = !1, this.config = null, this.ACTIVITY_THROTTLE_MS = 1e3;
+  }
+  // Throttle activity events to max 1 per second
+  /**
+   * Updates activity timestamp (throttled for performance)
+   */
+  updateActivityTime() {
+    this.lastActivityTime = Date.now(), this.inactivityTimer && clearTimeout(this.inactivityTimer), this.inactivityTimer = setTimeout(
+      () => {
+        var i;
+        (i = this.config) != null && i.debug && console.warn("DotCMS Analytics: User became inactive after timeout"), this.inactivityTimer = null;
+      },
+      c * 60 * 1e3
+    );
+  }
+  /**
+   * Checks if user has been inactive
+   */
+  isUserInactive() {
+    const i = c * 60 * 1e3;
+    return Date.now() - this.lastActivityTime > i;
+  }
+  /**
+   * Gets last activity time
+   */
+  getLastActivity() {
+    return this.lastActivityTime;
+  }
+  /**
+   * Updates session activity with throttling
+   */
+  updateSessionActivity() {
+    this.isThrottled || (this.isThrottled = !0, this.updateActivityTime(), setTimeout(() => {
+      this.isThrottled = !1;
+    }, this.ACTIVITY_THROTTLE_MS));
+  }
+  /**
+   * Initializes activity tracking with event listeners
+   */
+  initialize(i) {
+    if (this.cleanup(), this.config = i, typeof window > "u")
+      return;
+    const s = () => this.updateSessionActivity();
+    r.forEach((a) => {
+      window.addEventListener(a, s, { passive: !0 }), this.activityListeners.push(
+        () => window.removeEventListener(a, s)
+      );
+    });
+    const n = () => {
+      document.visibilityState === "visible" && (this.updateSessionActivity(), i.debug && console.warn("DotCMS Analytics: User returned to tab, session reactivated"));
+    };
+    document.addEventListener("visibilitychange", n), this.activityListeners.push(
+      () => document.removeEventListener("visibilitychange", n)
+    ), this.updateActivityTime(), i.debug && console.warn("DotCMS Analytics: Activity tracking initialized");
+  }
+  /**
+   * Cleans up all activity tracking listeners
+   */
+  cleanup() {
+    this.activityListeners.forEach((i) => i()), this.activityListeners = [], this.inactivityTimer && (clearTimeout(this.inactivityTimer), this.inactivityTimer = null), this.config = null;
+  }
+  /**
+   * Gets session information for debugging
+   */
+  getSessionInfo() {
+    return {
+      lastActivity: this.getLastActivity(),
+      isActive: !this.isUserInactive()
+    };
+  }
+}
+const t = new o(), h = () => {
+  t.updateSessionActivity();
+}, l = (e) => {
+  t.initialize(e);
+}, T = () => {
+  t.cleanup();
+};
+export {
+  T as cleanupActivityTracking,
+  l as initializeActivityTracking,
+  h as updateSessionActivity
+};

package/lib/dotAnalytics/shared/dot-content-analytics.constants.d.ts

@@ -1,13 +1,33 @@
 export declare const ANALYTICS_WINDOWS_KEY = "dotAnalytics";
 export declare const ANALYTICS_SOURCE_TYPE = "dotAnalytics";
 export declare const ANALYTICS_ENDPOINT = "/api/v1/analytics/content/event";
-export declare const ANALYTICS_PAGEVIEW_EVENT = "PAGE_REQUEST";
-export declare const ANALYTICS_TRACK_EVENT = "TRACK_EVENT";
-export declare const EXPECTED_UTM_KEYS: string[];
 /**
- * The type of event.
+ * Event Types
+ * Only two event types are supported in DotCMS Analytics
  */
-export declare enum EventType {
-    Track = "track",
-    PageView = "pageview"
-}
+export declare const EVENT_TYPES: {
+    readonly PAGEVIEW: "pageview";
+    readonly TRACK: "track";
+};
+/**
+ * Expected UTM parameter keys for campaign tracking
+ */
+export declare const EXPECTED_UTM_KEYS: readonly ["utm_source", "utm_medium", "utm_campaign", "utm_term", "utm_content", "utm_id"];
+/**
+ * Session configuration constants
+ */
+export declare const DEFAULT_SESSION_TIMEOUT_MINUTES = 30;
+export declare const SESSION_STORAGE_KEY = "dot_analytics_session_id";
+export declare const SESSION_START_KEY = "dot_analytics_session_start";
+export declare const SESSION_UTM_KEY = "dot_analytics_session_utm";
+/**
+ * User ID configuration constants
+ */
+export declare const USER_ID_KEY = "dot_analytics_user_id";
+/**
+ * Activity tracking configuration
+ * Events used to detect user activity for session management
+ * - click: Detects real user interaction with minimal performance impact
+ * - visibilitychange: Handled separately to detect tab changes
+ */
+export declare const ACTIVITY_EVENTS: readonly ["click"];

package/lib/dotAnalytics/shared/dot-content-analytics.constants.js

@@ -1,10 +1,14 @@
-const E = "dotAnalytics", c = E, a = "/api/v1/analytics/content/event", n = "PAGE_REQUEST", A = ["utm_source", "utm_medium", "utm_campaign", "utm_id"];
-var _ = /* @__PURE__ */ ((t) => (t.Track = "track", t.PageView = "pageview", t))(_ || {});
+const t = "dotAnalytics", E = t, _ = "/api/v1/analytics/content/event", c = {
+  PAGEVIEW: "pageview",
+  TRACK: "track"
+}, n = 30, s = "dot_analytics_session_id", S = "dot_analytics_user_id", T = ["click"];
 export {
-  a as ANALYTICS_ENDPOINT,
-  n as ANALYTICS_PAGEVIEW_EVENT,
-  c as ANALYTICS_SOURCE_TYPE,
-  E as ANALYTICS_WINDOWS_KEY,
-  A as EXPECTED_UTM_KEYS,
-  _ as EventType
+  T as ACTIVITY_EVENTS,
+  _ as ANALYTICS_ENDPOINT,
+  E as ANALYTICS_SOURCE_TYPE,
+  t as ANALYTICS_WINDOWS_KEY,
+  n as DEFAULT_SESSION_TIMEOUT_MINUTES,
+  c as EVENT_TYPES,
+  s as SESSION_STORAGE_KEY,
+  S as USER_ID_KEY
 };

package/lib/dotAnalytics/shared/dot-content-analytics.http.d.ts

@@ -1,9 +1,9 @@
-import { DotContentAnalyticsConfig } from './dot-content-analytics.model';
+import { DotCMSAnalyticsConfig, DotCMSAnalyticsRequestBody } from './dot-content-analytics.model';
 
 /**
  * Send an analytics event to the server
- * @param data - The event data
- * @param options - The options for the event
- * @returns A promise that resolves to the response from the server
+ * @param payload - The event payload data
+ * @param config - The analytics configuration
+ * @returns A promise that resolves when the request is complete
  */
-export declare const sendAnalyticsEventToServer: (data: Record<string, unknown>, options: DotContentAnalyticsConfig) => Promise<void>;
+export declare const sendAnalyticsEventToServer: (payload: DotCMSAnalyticsRequestBody, config: DotCMSAnalyticsConfig) => Promise<void>;

package/lib/dotAnalytics/shared/dot-content-analytics.http.js

@@ -1,22 +1,29 @@
-import { ANALYTICS_ENDPOINT as o } from "./dot-content-analytics.constants.js";
-const a = async (n, t) => {
-  const r = {
-    ...n,
-    timestamp: (/* @__PURE__ */ new Date()).toISOString(),
-    key: t.apiKey
-  };
-  t.debug && console.warn("DotAnalytics: Event sent:", r);
+import { ANALYTICS_ENDPOINT as a } from "./dot-content-analytics.constants.js";
+const i = async (o, t) => {
   try {
-    const e = await fetch(`${t.server}${o}`, {
+    const e = await fetch(`${t.server}${a}`, {
       method: "POST",
       headers: { "Content-Type": "application/json" },
-      body: JSON.stringify(r)
+      body: JSON.stringify(o)
     });
-    e.ok || console.error(`DotAnalytics: Server responded with status ${e.status}`);
+    if (!e.ok) {
+      const n = e.statusText || "Unknown Error", s = `HTTP ${e.status}: ${n}`;
+      try {
+        const r = await e.json();
+        r.message ? console.warn(`DotAnalytics: ${r.message} (${s})`) : console.warn(
+          `DotAnalytics: ${s} - No error message in response`
+        );
+      } catch (r) {
+        console.warn(
+          `DotAnalytics: ${s} - Failed to parse error response:`,
+          r
+        );
+      }
+    }
   } catch (e) {
     console.error("DotAnalytics: Error sending event:", e);
   }
 };
 export {
-  a as sendAnalyticsEventToServer
+  i as sendAnalyticsEventToServer
 };