@dotcms/events 0.0.0-stage → 26.10.5-1-next.2827

package/src/lib/impressions/tracker.d.ts

@@ -0,0 +1,67 @@
+import type { PipelineConfig, DotCMSContentImpressionPayload } from '../pipeline/models';
+/** Callback function for impression events */
+export type ImpressionCallback = (eventName: string, payload: DotCMSContentImpressionPayload) => void;
+/** Subscription object with unsubscribe method */
+export interface ImpressionSubscription {
+    unsubscribe: () => void;
+}
+/**
+ * Tracks content impressions using IntersectionObserver and dwell time.
+ * Emits events through subscriptions when impressions are detected.
+ */
+export declare class DotCMSImpressionTracker {
+    #private;
+    constructor(config: PipelineConfig);
+    /**
+     * Subscribe to impression events
+     * @param callback - Function called when impression is detected
+     * @returns Subscription object with unsubscribe method
+     */
+    onImpression(callback: ImpressionCallback): ImpressionSubscription;
+    /** Notifies all subscribers of an impression */
+    private notifySubscribers;
+    /**
+     * Merges user config with defaults. IntersectionObserver throws on a visibility threshold
+     * outside 0 to 1, so one outside that range is clamped to it, with a warning
+     */
+    private resolveImpressionConfig;
+    /** Initializes tracking: sets up observers, finds contentlets, handles visibility/navigation */
+    initialize(): void;
+    /** Sets up IntersectionObserver with configured visibility threshold */
+    private initializeIntersectionObserver;
+    /** Finds contentlets in DOM, validates them, and starts observing (respects maxNodes limit) */
+    private findAndObserveContentletElements;
+    /**
+     * Watches for contentlets added to the DOM, and for contentlets receiving their
+     * identifier, which the renderers print after hydration (throttled for performance)
+     */
+    private initializeDynamicContentDetector;
+    /** Cancels all timers when page is hidden (prevents false impressions) */
+    private initializePageVisibilityHandler;
+    /**
+     * Resets tracking when the visitor goes to another page, or comes back to this one from the
+     * back/forward cache. It listens through onNavigation: the browser's Navigation API where
+     * there is one, which needs no patch of `history`
+     */
+    private initializePageNavigationHandler;
+    /** Forgets the page's impressions, timers and elements, so the next view counts its own */
+    private forgetPageImpressions;
+    /** Handles visibility changes: starts timer on enter, cancels on exit */
+    private processIntersectionChanges;
+    /** Starts dwell timer; fires impression if element still visible when timer expires */
+    private startImpressionDwellTimer;
+    /** Cancels active dwell timer (element left viewport before dwell time) */
+    private cancelImpressionDwellTimer;
+    /** Fires impression event with content & position data (page data added by enricher plugin) */
+    private trackAndSendImpression;
+    /** Returns skip reason if element is hidden/too small, null if trackable */
+    private shouldSkipElement;
+    /** Post-dwell check: verifies element still meets visibility threshold */
+    private isElementStillVisible;
+    /** Checks if impression already fired in current page session */
+    private hasBeenTrackedInSession;
+    /** Marks impression as tracked (prevents duplicates in same page session) */
+    private markImpressionAsTracked;
+    /** Cleanup: disconnects observers, clears timers and state */
+    cleanup(): void;
+}

package/src/lib/impressions/utils.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Utility functions for impression tracking
+ */
+/**
+ * Checks if an element meets a specific visibility threshold
+ * @param element - The HTML element to check
+ * @param threshold - The required visibility ratio (0.0 to 1.0)
+ * @returns True if the element meets or exceeds the threshold
+ */
+export declare function isElementMeetingVisibilityThreshold(element: HTMLElement, threshold: number): boolean;

package/src/lib/models.d.ts

@@ -0,0 +1,130 @@
+/** A value in a pageview's custom data. */
+export type DotCMSEventsJsonValue = string | number | boolean | null | undefined | DotCMSEventsJsonObject | DotCMSEventsJsonValue[];
+/** The custom data a pageview carries. */
+export type DotCMSEventsJsonObject = {
+    [key: string]: DotCMSEventsJsonValue;
+};
+/** Minimum level for the analytics core's console logs. */
+export type DotCMSEventsLogLevel = 'debug' | 'info' | 'warn' | 'error';
+/**
+ * Options for content impressions.
+ */
+export interface DotCMSEventsImpressionsConfig {
+    /** Share of the contentlet that must be in the viewport, from 0 to 1. Defaults to 0.5. */
+    visibilityThreshold?: number;
+    /** How long, in milliseconds, the contentlet must stay in view. Defaults to 750. */
+    dwellMs?: number;
+    /** Most contentlets tracked on a page. Defaults to 100. */
+    maxNodes?: number;
+}
+/**
+ * Options for batching.
+ */
+export interface DotCMSEventsQueueConfig {
+    /** Most events in one batch; a full batch is sent at once. Defaults to 15. */
+    eventBatchSize?: number;
+    /** Milliseconds between sends. Defaults to 5000. */
+    flushInterval?: number;
+}
+/**
+ * Options for the experiments engine.
+ */
+export interface DotCMSEventsExperimentsConfig {
+    /**
+     * How long, in milliseconds, a pageview and the experiment's hidden rows wait for the
+     * assignment before the page is shown without it. Defaults to 3000, which is also the most:
+     * the hiding rule shows the content after 3000 ms on its own, so a longer value is reduced to
+     * 3000 rather than show the original and then replace it with the variant.
+     */
+    timeout?: number;
+}
+/**
+ * Configuration for `dotEvents.init()`.
+ */
+export interface DotCMSEventsConfig {
+    /** The dotCMS origin, the same value `createDotCMSClient` takes. */
+    dotcmsUrl: string;
+    /** The site's Site Auth, from the Content Analytics app. */
+    siteAuth: string;
+    /** A pageview on load and on every History change. Defaults to `true`. */
+    autoPageView?: boolean;
+    /** Content impressions. Off by default. */
+    impressions?: DotCMSEventsImpressionsConfig | boolean;
+    /** Content clicks. Off by default. */
+    clicks?: boolean;
+    /**
+     * Experiments: `isUserIncluded`, the pageview hold, the redirect and
+     * `context.experiments`. On by default; `false` turns every part off.
+     */
+    experiments?: boolean | DotCMSEventsExperimentsConfig;
+    /** Batching, as in today's analytics config. */
+    queue?: DotCMSEventsQueueConfig | boolean;
+    /** Logs what the SDK does to the console. */
+    debug?: boolean;
+    /** Minimum log level for the analytics core. */
+    logLevel?: DotCMSEventsLogLevel;
+    /**
+     * Called when something fails where the page cannot see it: dotCMS rejects events, an events
+     * request gets no answer, or the experiments check fails. Nothing is retried, and an error
+     * this handler throws is ignored.
+     */
+    onError?: (error: DotCMSEventsError) => void;
+}
+/**
+ * What failed, for `onError`:
+ * - `REJECTED`: dotCMS answered an events request with an error, or accepted it but failed
+ *   some of its events; `status` and `detail` (its error list) say why.
+ * - `NETWORK`: an events request got no answer.
+ * - `EXPERIMENTS`: `isUserIncluded` failed; a 403 means experiments are off for the site.
+ */
+export type DotCMSEventsErrorCode = 'REJECTED' | 'NETWORK' | 'EXPERIMENTS';
+/** A failure reported to `onError`. */
+export interface DotCMSEventsError {
+    code: DotCMSEventsErrorCode;
+    message: string;
+    /** The HTTP status, when dotCMS answered. */
+    status?: number;
+    /** What dotCMS said about the failure, for `REJECTED`. */
+    detail?: unknown;
+    /** How many events the failed request carried, for `REJECTED` and `NETWORK`. */
+    events?: number;
+}
+/**
+ * The events object. There is one per page: every import gets the same instance.
+ */
+export interface DotCMSEvents {
+    /** Starts the SDK. Calling it again with the same config does nothing. */
+    init(config: DotCMSEventsConfig): void;
+    /** Sends a conversion. dotCMS records its name and the page it happened on, nothing else. */
+    conversion(name: string): void;
+    /** Sends a pageview by hand, for apps that set `autoPageView: false`. */
+    pageView(data?: DotCMSEventsJsonObject): void;
+}
+/**
+ * The page fields `experimentMarkup` and `DotCMSExperiment` read. A dotCMS page asset fits,
+ * requested for the variant in the URL's `variantName`.
+ */
+export interface DotCMSEventsExperimentPage {
+    /** The experiment running on the page, if any. */
+    runningExperimentId?: string | null;
+    /** `variantId` is the variant the server rendered; `DEFAULT` when absent. */
+    viewAs?: {
+        variantId?: string | null;
+    } | null;
+}
+/**
+ * What a page prints so its experiment runs, from `experimentMarkup`. The style and the
+ * script go before the element that wraps what the experiment varies, in the HTML the server
+ * sends: the script decides the visitor's variant while that HTML is parsed.
+ */
+export interface DotCMSEventsExperimentMarkup {
+    /** Attributes for the element that wraps what the experiment varies. */
+    attributes: {
+        'data-dot-experiment': string;
+        'data-dot-variant': string;
+    };
+    /** The rule that keeps that element hidden until the variant is decided. */
+    style: string;
+    /** The boot script's source, for an inline script element. */
+    script: string;
+}

package/src/lib/pipeline/constants.d.ts

@@ -0,0 +1,88 @@
+/** The window property that traditional pages and plain scripts reach `dotEvents` through. */
+export declare const EVENTS_WINDOW_KEY = "dotEvents";
+/**
+ * The Analytics.js name of the sender plugin. The enricher keys its hooks with it
+ * (`page:<name>`, `track:<name>`), so they run for the sender's calls only.
+ */
+export declare const SENDER_PLUGIN_NAME = "dot-events-sender";
+export declare const ANALYTICS_ENDPOINT = "/api/v1/analytics/content/event";
+/**
+ * The event types dotCMS accepts, each with its own schema. It rejects any other type, so the
+ * SDK sends no custom events.
+ */
+export declare const DotCMSPredefinedEventType: {
+    readonly PAGEVIEW: "pageview";
+    readonly CONTENT_IMPRESSION: "content_impression";
+    readonly CONTENT_CLICK: "content_click";
+    readonly CONVERSION: "conversion";
+};
+/**
+ * Type for structured events
+ */
+export type DotCMSPredefinedEventType = (typeof DotCMSPredefinedEventType)[keyof typeof DotCMSPredefinedEventType];
+/**
+ * Expected UTM parameter keys for campaign tracking
+ */
+export declare const EXPECTED_UTM_KEYS: readonly ["utm_source", "utm_medium", "utm_campaign", "utm_term", "utm_content"];
+/**
+ * Session configuration constants
+ */
+export declare const DEFAULT_SESSION_TIMEOUT_MINUTES = 30;
+/**
+ * Session storage key for session ID
+ */
+export declare const SESSION_STORAGE_KEY = "dot_events_session_id";
+/**
+ * User ID configuration constants
+ */
+export declare const USER_ID_KEY = "dot_events_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"];
+/**
+ * Default queue configuration for event batching
+ */
+export declare const DEFAULT_QUEUE_CONFIG: {
+    readonly eventBatchSize: 15;
+    readonly flushInterval: 5000;
+};
+/**
+ * Default properties that Analytics.js adds automatically
+ * These should be filtered out to only keep user-provided properties
+ */
+export declare const ANALYTICS_JS_DEFAULT_PROPERTIES: readonly ["title", "url", "path", "hash", "search", "width", "height", "referrer"];
+/**
+ * Window flag that says the SDK is active on the page. Not this package's name to change:
+ * `@dotcms/uve/internal` declares it too (`ANALYTICS_ACTIVE_WINDOW_KEY`), and the React, Vue
+ * and Angular SDKs read it to print the contentlet attributes impressions and clicks need.
+ */
+export declare const ANALYTICS_WINDOWS_ACTIVE_KEY = "__dotAnalyticsActive__";
+/**
+ * Window event sent once the SDK is active, so the renderers that read
+ * `ANALYTICS_WINDOWS_ACTIVE_KEY` render again. Shared with `@dotcms/uve/internal`
+ * (`ANALYTICS_READY_EVENT`) like that flag.
+ */
+export declare const ANALYTICS_READY_EVENT = "dotcms:analytics:ready";
+/**
+ * Queue persistence configuration constants
+ * Used for storing events in sessionStorage for traditional page navigations
+ */
+/**
+ * Session storage key for persistent tab ID
+ * This ID remains constant across page navigations within the same browser tab
+ */
+export declare const TAB_ID_STORAGE_KEY = "dot_events_tab_id";
+/**
+ * Prefix for queue storage key in sessionStorage
+ * Full key format: dot_events_queue_{tabId}
+ */
+export declare const QUEUE_STORAGE_KEY_PREFIX = "dot_events_queue";
+/**
+ * Maximum age in milliseconds for persisted events
+ * Events older than this will be discarded (24 hours)
+ */
+export declare const MAX_EVENT_AGE_MS: number;

package/src/lib/pipeline/enricher/plugin.d.ts

@@ -0,0 +1,32 @@
+import type { AnalyticsBasePayloadWithContext, AnalyticsTrackPayloadWithContext, EnrichedAnalyticsPayload, EnrichedTrackPayload } from '../models';
+/**
+ * Plugin that enriches the analytics payload data with page, UTM, and custom data.
+ * Uses Analytics.js lifecycle events to inject enriched data before the main plugin processes it.
+ *
+ * The identity plugin, registered first, injects context: { session_id, site_auth, user_id, device }.
+ * This plugin, registered after the experiments, impressions and clicks plugins, adds page, UTM
+ * and custom data. The sender, registered last, structures the events and sends them.
+ *
+ * This plugin is ONLY responsible for data enrichment - NOT for event structuring or business logic.
+ */
+export declare const enricherPlugin: () => {
+    name: string;
+    /**
+     * PAGE VIEW ENRICHMENT - Runs after identity context injection
+     * Returns enriched payload with page, utm, and custom data added
+     * @returns {EnrichedAnalyticsPayload} Enriched payload ready for event creation
+     */
+    "page:dot-events-sender": ({ payload }: {
+        payload: AnalyticsBasePayloadWithContext;
+    }) => EnrichedAnalyticsPayload;
+    /**
+     * TRACK EVENT ENRICHMENT - Runs after identity context injection
+     * Adds page data and timestamp for predefined content events.
+     * For custom events, only adds timestamp.
+     *
+     * @returns {EnrichedTrackPayload} Enriched payload ready for event structuring
+     */
+    "track:dot-events-sender": ({ payload }: {
+        payload: AnalyticsTrackPayloadWithContext;
+    }) => EnrichedTrackPayload;
+};

package/src/lib/pipeline/identity/activity.d.ts

@@ -0,0 +1,19 @@
+import { ANALYTICS_WINDOWS_ACTIVE_KEY } from '../constants';
+import type { PipelineConfig } from '../models';
+declare global {
+    interface Window {
+        [ANALYTICS_WINDOWS_ACTIVE_KEY]?: boolean;
+    }
+}
+/**
+ * Updates session activity with throttling
+ */
+export declare const updateSessionActivity: () => void;
+/**
+ * Initializes activity tracking
+ */
+export declare const initializeActivityTracking: (config: PipelineConfig) => void;
+/**
+ * Cleans up activity tracking listeners and resets analytics state
+ */
+export declare const cleanupActivityTracking: () => void;

package/src/lib/pipeline/identity/plugin.d.ts

@@ -0,0 +1,60 @@
+import type { AnalyticsBaseParams, PipelineConfig } from '../models';
+/**
+ * Identity plugin of the events pipeline.
+ * Handles user ID generation, session management, and activity tracking.
+ * This plugin provides consistent identity context across all analytics events.
+ *
+ * It runs first: events.ts registers identity, experiments, impressions, clicks, enricher and
+ * sender, in that order, and each plugin reads what the ones before it wrote.
+ *
+ * @param {PipelineConfig} 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 identityPlugin: (config: PipelineConfig) => {
+    name: string;
+    /**
+     * Initialize the identity plugin
+     * Sets up activity tracking for session management
+     */
+    initialize: () => Promise<void>;
+    /**
+     * Inject identity context into page events and updates session activity for session management
+     * This runs BEFORE the enricher plugin
+     */
+    pageStart: ({ payload }: AnalyticsBaseParams) => {
+        context: import("../models").EventContext;
+        type: "page" | "track";
+        properties: Record<string, unknown>;
+        options: Record<string, unknown>;
+        userId: string;
+        anonymousId: string;
+        meta: {
+            rid: string;
+            ts: number;
+            hasCallback: boolean;
+        };
+    };
+    /**
+     * Inject identity context into track events and updates session activity for session management
+     * This runs BEFORE the enricher plugin
+     */
+    trackStart: ({ payload }: AnalyticsBaseParams) => {
+        context: import("../models").EventContext;
+        type: "page" | "track";
+        properties: Record<string, unknown>;
+        options: Record<string, unknown>;
+        userId: string;
+        anonymousId: string;
+        meta: {
+            rid: string;
+            ts: number;
+            hasCallback: boolean;
+        };
+    };
+    /**
+     * Cleans up activity tracking when the browser discards the page. A page kept in the
+     * back/forward cache keeps it, and keeps `__dotAnalyticsActive__` set, so the
+     * renderers still print the contentlet attributes once the visitor goes back to it.
+     */
+    loaded: () => boolean;
+};

package/src/lib/pipeline/logger.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Log level type for the DotLogger
+ */
+export type LogLevel = 'debug' | 'info' | 'warn' | 'error';
+/**
+ * Custom logger for DotCMS SDK
+ * Provides structured logging with context identification and configurable log level filtering
+ *
+ * @example
+ * ```typescript
+ * const logger = new DotLogger('events', 'Impression', 'info');
+ * logger.debug('This will not show'); // Below threshold
+ * logger.info('Tracker initialized'); // Shows
+ * logger.error('Failed to track'); // Shows
+ * ```
+ */
+export declare class DotLogger {
+    #private;
+    constructor(packageName: string, context: string, minLevel?: LogLevel);
+    /**
+     * Creates the formatted prefix for log messages
+     * Format: [dotCMS packageName | Context] [LEVEL]
+     */
+    private getPrefix;
+    /**
+     * Checks if a log level should be displayed based on the minimum threshold
+     */
+    private shouldLog;
+    /**
+     * Log a DEBUG level message
+     * Used for detailed debugging information
+     */
+    debug(...args: unknown[]): void;
+    /**
+     * Log an INFO level message
+     * Used for general informational messages
+     */
+    info(...args: unknown[]): void;
+    /**
+     * Log a WARN level message
+     * Used for warning messages that don't prevent operation
+     */
+    warn(...args: unknown[]): void;
+    /**
+     * Log an ERROR level message
+     * Always logs regardless of threshold for critical errors
+     */
+    error(...args: unknown[]): void;
+    /**
+     * Create a console group for organizing related log messages
+     * Respects the minimum log level threshold
+     */
+    group(label: string): void;
+    /**
+     * End the current console group
+     * Respects the minimum log level threshold
+     */
+    groupEnd(): void;
+    /**
+     * Start a timer with the given label
+     * Useful for performance measurements
+     */
+    time(label: string): void;
+    /**
+     * End a timer and log the elapsed time
+     * Useful for performance measurements
+     */
+    timeEnd(label: string): void;
+    /**
+     * Log a message (alias for info)
+     * Provided for backward compatibility
+     */
+    log(...args: unknown[]): void;
+}