@dotcms/analytics 0.0.1-beta.9 → 1.0.0

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

@@ -1,11 +1,15 @@
-import { ANALYTICS_PAGEVIEW_EVENT, EventType, EXPECTED_UTM_KEYS } from './dot-content-analytics.constants';
+import { EVENT_TYPES } from './dot-content-analytics.constants';
 
+declare global {
+    interface Window {
+        __dotAnalyticsCleanup?: () => void;
+    }
+}
 /**
- * Configuration interface for DotAnalytics SDK.
- *
- * @interface DotAnalyticsConfig
+ * Configuration interface for DotCMS Analytics SDK.
+ * Contains all necessary settings for initializing and configuring the analytics client.
  */
-export interface DotContentAnalyticsConfig {
+export interface DotCMSAnalyticsConfig {
     /**
      * The URL of the Analytics server endpoint.
      */
@@ -19,125 +23,336 @@ export interface DotContentAnalyticsConfig {
      */
     autoPageView?: boolean;
     /**
-     * The API key for authenticating with the Analytics service.
+     * The site key for authenticating with the Analytics service.
      */
-    apiKey: string;
+    siteKey: string;
     /**
      * Custom redirect function handler.
      * When provided, this function will be called instead of the default browser redirect
      * for handling URL redirections.
-     *
-     * @param {string} url - The URL to redirect to
      */
     redirectFn?: (url: string) => void;
 }
-type UTMParams = {
-    [key in (typeof EXPECTED_UTM_KEYS)[number] as key extends `utm_${infer U}` ? U : never]?: string;
-};
-interface BaseEventData {
-    anonymousId?: string;
-    src: string;
-    utc_time: string;
-    local_tz_offset: number;
-    doc_path: string;
-    doc_host: string;
+/**
+ * Supported event types in DotCMS Analytics.
+ * Only two event types are supported: pageview and track.
+ */
+export type DotCMSEventType = (typeof EVENT_TYPES)[keyof typeof EVENT_TYPES];
+/**
+ * Base structure for all analytics events.
+ * All events share this common structure.
+ */
+export interface DotCMSEventBase {
+    /** The type of event being tracked */
+    event_type: DotCMSEventType;
+    /** Local timestamp when the event occurred */
+    local_time: string;
+}
+/**
+ * Pageview-specific analytics event structure.
+ * Contains data specific to page view tracking.
+ */
+export interface DotCMSPageViewEvent extends DotCMSEventBase {
+    event_type: 'pageview';
+    /** Pageview-specific event data with structured format */
+    data: {
+        /** Page data associated with the event */
+        page: DotCMSPageData;
+        /** Device and browser information */
+        device: DotCMSDeviceData;
+        /** UTM parameters for campaign tracking (optional) */
+        utm?: DotCMSUtmData;
+    };
+}
+/**
+ * Track-specific analytics event structure.
+ * Contains data specific to custom event tracking.
+ */
+export interface DotCMSTrackEvent extends DotCMSEventBase {
+    event_type: 'track';
+    /** Track-specific event data with flexible structure */
+    data: Record<string, unknown>;
+}
+/**
+ * Union type for all possible analytics events.
+ */
+export type DotCMSEvent = DotCMSPageViewEvent | DotCMSTrackEvent;
+/**
+ * Analytics request body for page view events in DotCMS.
+ * Structure sent to the DotCMS analytics server for page tracking.
+ */
+export interface DotCMSPageViewRequestBody {
+    /** Context information shared across all events */
+    context: DotCMSAnalyticsContext;
+    /** Array of pageview analytics events to be tracked */
+    events: DotCMSPageViewEvent[];
+}
+/**
+ * Analytics request body for track events in DotCMS.
+ * Structure sent to the DotCMS analytics server for custom event tracking.
+ */
+export interface DotCMSTrackRequestBody {
+    /** Context information shared across all events */
+    context: DotCMSAnalyticsContext;
+    /** Array of track analytics events to be tracked */
+    events: DotCMSTrackEvent[];
 }
-export interface BrowserEventData {
+/**
+ * Union type for all possible request bodies.
+ */
+export type DotCMSAnalyticsRequestBody = DotCMSPageViewRequestBody | DotCMSTrackRequestBody;
+/**
+ * Enriched payload structure returned by the enricher plugin.
+ * Contains pre-structured events and context for direct use in analytics requests.
+ */
+export interface DotCMSEnrichedPayload {
+    /** Analytics context shared across events */
+    context: DotCMSAnalyticsContext;
+    /** Array of pre-structured analytics events */
+    events: DotCMSEvent[];
+}
+/**
+ * Browser event data collected from the user's session in DotCMS.
+ * Contains comprehensive information about the user's browser environment,
+ * page context, and session details for analytics tracking.
+ */
+export interface DotCMSBrowserEventData {
+    /** UTC timestamp when the event occurred */
     utc_time: string;
+    /** Local timezone offset in minutes */
     local_tz_offset: number;
-    screen_resolution: string;
-    vp_size: string;
-    userAgent: string;
-    user_language: string;
-    doc_encoding: string;
-    doc_path: string;
-    doc_host: string;
-    doc_protocol: string;
+    /** Screen resolution as a string (e.g., "1920x1080") */
+    screen_resolution: string | undefined;
+    /** Viewport size as a string (e.g., "1200x800") */
+    vp_size: string | undefined;
+    /** User's preferred language */
+    user_language: string | undefined;
+    /** Document encoding */
+    doc_encoding: string | undefined;
+    /** Document path */
+    doc_path: string | undefined;
+    /** Document host */
+    doc_host: string | undefined;
+    /** Document protocol (http/https) */
+    doc_protocol: string | undefined;
+    /** Document hash fragment */
     doc_hash: string;
+    /** Document search parameters */
     doc_search: string;
-    referrer: string;
-    page_title: string;
-    utm: UTMParams;
+    /** Referrer URL */
+    referrer: string | undefined;
+    /** Page title */
+    page_title: string | undefined;
+    /** Current page URL */
+    url: string | undefined;
+    /** UTM parameters for campaign tracking */
+    utm: Record<string, string>;
 }
-export interface PageViewEvent extends BaseEventData, BrowserEventData {
-    event_type: typeof ANALYTICS_PAGEVIEW_EVENT;
+/**
+ * The payload structure for DotCMS analytics events.
+ * This interface represents the complete data structure that flows through
+ * the analytics pipeline, including original event data and enriched context.
+ *
+ * This is the internal payload used by Analytics.js and our plugins.
+ */
+export interface DotCMSAnalyticsPayload {
+    /** The event name or identifier */
+    event: string;
+    /** Additional properties associated with the event */
+    properties: Record<string, unknown>;
+    /** Configuration options for the event */
+    options: Record<string, unknown>;
+    /** Analytics context shared across events */
+    context?: DotCMSAnalyticsContext;
+    /** Page data for the current page */
+    page?: DotCMSPageData;
+    /** Device and browser information */
+    device?: DotCMSDeviceData;
+    /** UTM parameters for campaign tracking */
+    utm?: DotCMSUtmData;
+    /** Local timestamp when the event occurred */
+    local_time: string;
 }
-export interface TrackEvent {
-    event_type: 'track';
-    custom_event: string;
-    [key: string]: unknown;
+/**
+ * Parameters passed to DotCMS Analytics plugin methods.
+ * Contains the configuration and payload data needed for processing analytics events.
+ */
+export interface DotCMSAnalyticsParams {
+    /** Configuration for the analytics client */
+    config: DotCMSAnalyticsConfig;
+    /** The event payload to be processed */
+    payload: DotCMSAnalyticsPayload;
 }
-export interface TrackPayload extends DotAnalyticsPayload {
-    type: EventType.Track;
-    properties: Record<string, unknown> & {
-        title: string;
-        url: string;
-        path: string;
-        hash: string;
-        search: string;
-        width: number;
-        height: number;
-        source: string;
-    };
+/**
+ * Main interface for the DotCMS Analytics SDK.
+ * Provides the core methods for tracking page views and custom events.
+ */
+export interface DotCMSAnalytics {
+    /**
+     * Track a page view event.
+     */
+    pageView: () => void;
+    /**
+     * Track a custom event.
+     * @param eventName - The name/type of the event to track
+     * @param payload - Optional additional data to include with the event
+     */
+    track: (eventName: string, payload?: Record<string, unknown>) => void;
 }
-export interface PageViewPayload extends DotAnalyticsPayload {
-    type: EventType.PageView;
-    properties: {
-        title: string;
-        url: string;
-        path: string;
-        hash: string;
-        search: string;
-        width: number;
-        height: number;
-        source: string;
-    };
+/**
+ * Analytics context shared across all events in DotCMS.
+ * Contains session and user identification data that provides
+ * continuity across multiple analytics events.
+ */
+export interface DotCMSAnalyticsContext {
+    /** The site key for the DotCMS instance */
+    site_key: string;
+    /** Unique session identifier */
+    session_id: string;
+    /** Unique user identifier */
+    user_id: string;
 }
 /**
- * The payload for a track event.
+ * Device and browser information for DotCMS analytics tracking.
+ * Contains technical details about the user's device and browser environment.
  */
-export interface DotAnalyticsPayload {
+export interface DotCMSDeviceData {
+    /** Screen resolution as a string (e.g., "1920x1080") */
+    screen_resolution: string | undefined;
+    /** User's preferred language */
+    language: string | undefined;
+    /** Viewport width in pixels */
+    viewport_width: string | undefined;
+    /** Viewport height in pixels */
+    viewport_height: string | undefined;
+}
+/**
+ * UTM (Urchin Tracking Module) parameters for DotCMS campaign tracking.
+ * Contains marketing campaign attribution data extracted from URL parameters.
+ */
+export interface DotCMSUtmData {
+    /** The marketing medium (e.g., email, social, cpc) */
+    medium?: string;
+    /** The traffic source (e.g., google, newsletter) */
+    source?: string;
+    /** The campaign name */
+    campaign?: string;
+    /** The campaign term or keyword */
+    term?: string;
+    /** The campaign content or ad variation */
+    content?: string;
+    /** The campaign ID for tracking specific campaigns */
+    id?: string;
+}
+/**
+ * Page data structure for DotCMS analytics.
+ * Contains comprehensive information about the current page and its context
+ * within the DotCMS environment.
+ */
+export interface DotCMSPageData {
+    /** The current page URL */
+    url: string | undefined;
+    /** Document encoding */
+    doc_encoding: string | undefined;
+    /** Document hash fragment */
+    doc_hash: string;
+    /** Document protocol (http/https) */
+    doc_protocol: string | undefined;
+    /** Document search parameters */
+    doc_search: string;
+    /** Document host domain */
+    doc_host: string | undefined;
+    /** Document path */
+    doc_path: string | undefined;
+    /** Page title */
+    title: string | undefined;
+    /** Language identifier */
+    language_id?: string;
+    /** Persona identifier */
+    persona?: string;
+}
+/**
+ * Analytics.js hook parameter types for DotCMS.
+ * Represents the payload structure used by Analytics.js lifecycle hooks
+ * for intercepting and modifying analytics events.
+ */
+export interface DotCMSAnalyticsHookPayload {
+    /** The type of analytics event */
     type: string;
+    /** Properties associated with the event */
     properties: {
+        /** Page title */
         title: string;
+        /** Page URL */
         url: string;
+        /** Page path */
         path: string;
+        /** URL hash fragment */
         hash: string;
+        /** URL search parameters */
         search: string;
+        /** Viewport width */
         width: number;
+        /** Viewport height */
         height: number;
-        source: string;
+        /** Referrer URL */
+        referrer?: string;
     };
-    event: string;
+    /** Configuration options for the event */
     options: Record<string, unknown>;
+    /** User identifier */
     userId: string | null;
-    anonymousId: string | null;
-}
-/**
- * Add ServerEvent type for HTTP layer
- */
-export interface ServerEvent extends Record<string, unknown> {
-    timestamp: string;
-    key: string;
-}
-/**
- * Interface for the AnalyticsTracker.
- */
-export interface DotContentAnalyticsCustomHook {
-    track: (eventName: string, payload?: Record<string, unknown>) => void;
+    /** Anonymous user identifier */
+    anonymousId: string;
+    /** Metadata about the event */
+    meta: {
+        /** Request identifier */
+        rid: string;
+        /** Timestamp */
+        ts: number;
+        /** Whether the event has a callback function */
+        hasCallback: boolean;
+    };
 }
 /**
- * Params for the DotAnalytics plugin
+ * Analytics.js instance structure for DotCMS.
+ * Represents the internal structure of an Analytics.js instance,
+ * providing access to plugins, storage, and event configuration.
  */
-export interface DotAnalyticsParams {
-    config: DotContentAnalyticsConfig;
-    payload: DotAnalyticsPayload;
+export interface DotCMSAnalyticsInstance {
+    /** Available plugins and their configurations */
+    plugins: Record<string, unknown>;
+    /** Storage mechanisms for analytics data */
+    storage: Record<string, unknown>;
+    /** Event configuration */
+    events: {
+        /** Core event types */
+        core: string[];
+        /** Plugin-specific event types */
+        plugins: string[];
+    };
 }
 /**
- * Shared interface for the DotAnalytics plugin
+ * Parameters passed to Analytics.js hook functions in DotCMS.
+ * Contains all the context and data needed for Analytics.js lifecycle hooks
+ * to process and modify analytics events.
  */
-export interface DotAnalytics {
-    pageView: (payload?: Record<string, unknown>) => void;
-    track: (eventName: string, payload?: Record<string, unknown>) => void;
+export interface DotCMSAnalyticsHookParams {
+    /** The event payload data */
+    payload: DotCMSAnalyticsHookPayload;
+    /** The analytics instance */
+    instance: DotCMSAnalyticsInstance;
+    /** Global configuration settings */
+    config: Record<string, unknown>;
+    /** Available plugins and their status */
+    plugins: Record<string, {
+        /** Whether the plugin is enabled */
+        enabled: boolean;
+        /** Whether the plugin is initialized */
+        initialized: boolean;
+        /** Whether the plugin is loaded */
+        loaded: boolean;
+        /** Plugin-specific configuration */
+        config: Record<string, unknown>;
+    }>;
 }
-export {};

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

@@ -1,48 +1,105 @@
-import { BrowserEventData, DotContentAnalyticsConfig } from './dot-content-analytics.model';
+import { DotCMSAnalyticsConfig, DotCMSAnalyticsContext, DotCMSAnalyticsPayload, DotCMSBrowserEventData, DotCMSDeviceData, DotCMSPageData, DotCMSUtmData } from './dot-content-analytics.model';
+import { PageData } from 'analytics';
 
+export { cleanupActivityTracking, getLastActivity, getSessionInfo, initializeActivityTracking, isUserInactive, updateSessionActivity } from './dot-content-analytics.activity-tracker';
 /**
- * Retrieves analytics attributes from a given script element.
- *
- * @return {DotAnalyticsConfig | null} - The analytics attributes or null if there are no valid attributes present.
+ * Generates a cryptographically secure random ID
+ */
+export declare const generateSecureId: (prefix: string) => string;
+/**
+ * Safe sessionStorage wrapper with error handling
  */
-export declare const getDataAnalyticsAttributes: (location: Location) => DotContentAnalyticsConfig;
+export declare const safeSessionStorage: {
+    getItem: (key: string) => string | null;
+    setItem: (key: string, value: string) => void;
+};
 /**
- * Retrieves the analytics script tag from the document.
+ * Gets or generates a user ID
+ */
+export declare const getUserId: () => string;
+/**
+ * Gets session ID with comprehensive lifecycle management
+ * Returns existing valid session ID or creates a new one if needed
  *
- * @returns {HTMLScriptElement} - The analytics script tag.
+ * Session validation criteria:
+ * 1. User is still active (< 30 min inactivity)
+ * 2. Session hasn't passed midnight (UTC)
+ * 3. UTM parameters haven't changed
+ */
+export declare const getSessionId: () => string;
+/**
+ * Gets analytics context with user and session identification
+ */
+export declare const getAnalyticsContext: (config: DotCMSAnalyticsConfig) => DotCMSAnalyticsContext;
+/**
+ * Retrieves analytics attributes from a given script element.
+ */
+export declare const getDataAnalyticsAttributes: () => DotCMSAnalyticsConfig;
+/**
+ * Gets the analytics script tag from the DOM
  */
 export declare const getAnalyticsScriptTag: () => HTMLScriptElement;
 /**
- * Retrieves the browser event data.
- *
- * @param {Location} location - The location object.
- * @returns {BrowserEventData} - The browser event data.
+ * Retrieves the browser event data - optimized but accurate.
  */
-export declare const getBrowserEventData: (location: Location) => BrowserEventData;
+export declare const getBrowserEventData: (location: Location) => DotCMSBrowserEventData;
 /**
- * Extracts UTM parameters from a given URL location.
- *
- * @param {Location} location - The location object containing the URL.
- * @returns {Record<string, string>} - An object containing the extracted UTM parameters.
+ * Extracts UTM parameters from the URL - cached for performance
  */
 export declare const extractUTMParameters: (location: Location) => Record<string, string>;
 /**
- * A function to redirect the user to a new URL.
- *
- * @param {string} href - The URL to redirect to.
- * @returns {void}
+ * Default redirect function
  */
 export declare const defaultRedirectFn: (href: string) => string;
 /**
- * Checks if the current environment is inside the dotCMS editor.
- *
- * @returns {boolean} - True if inside the editor, false otherwise.
+ * Gets local time in ISO format without milliseconds
  */
-export declare const isInsideEditor: () => boolean;
+export declare const getLocalTime: () => string;
 /**
- * Creates an analytics instance.
- *
- * @param {DotContentAnalyticsConfig} config - The configuration object for the analytics instance.
- * @returns {Analytics | null} - The analytics instance or null if there is an error.
+ * Gets page data from browser event data and payload
+ */
+export declare const getPageData: (browserData: DotCMSBrowserEventData, payload: DotCMSAnalyticsPayload) => PageData;
+/**
+ * Gets device data from browser event data
+ */
+export declare const getDeviceData: (browserData: DotCMSBrowserEventData) => DotCMSDeviceData;
+/**
+ * Gets UTM data from browser event data
+ */
+export declare const getUtmData: (browserData: DotCMSBrowserEventData) => DotCMSUtmData;
+/**
+ * Enriches payload with UTM data
+ */
+export declare const enrichWithUtmData: (payload: DotCMSAnalyticsPayload) => DotCMSAnalyticsPayload;
+/**
+ * Optimized payload enrichment using existing analytics.js data
+ * Reuses payload.properties data instead of recalculating from DOM when available
+ * Maintains the same output structure as the original function
+ */
+export declare const enrichPagePayloadOptimized: (payload: DotCMSAnalyticsPayload, location?: Location) => {
+    local_time: string;
+    utm?: DotCMSUtmData | undefined;
+    page: DotCMSPageData;
+    device: DotCMSDeviceData;
+    event: string;
+    properties: Record<string, unknown>;
+    options: Record<string, unknown>;
+    context?: DotCMSAnalyticsContext | undefined;
+};
+/**
+ * @deprecated Use enrichPagePayloadOptimized instead to avoid data duplication
+ * Legacy function that enriches page payload with all data in one call
+ * This function duplicates data already available in analytics.js payload
  */
-export declare const createAnalyticsInstance: (config: DotContentAnalyticsConfig) => import('analytics').AnalyticsInstance | null;
+export declare const enrichPagePayload: (payload: DotCMSAnalyticsPayload, location?: Location) => {
+    payload: {
+        local_time: string;
+        utm?: DotCMSUtmData | undefined;
+        page: PageData;
+        device: DotCMSDeviceData;
+        event: string;
+        properties: Record<string, unknown>;
+        options: Record<string, unknown>;
+        context?: DotCMSAnalyticsContext | undefined;
+    };
+};