@dotcms/events 0.0.0-stage → 26.10.5-1-alpha.0

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

@@ -0,0 +1,64 @@
+import type { ContentletData, PipelineConfig } from '../pipeline/models';
+import type { AnalyticsPlugin } from 'analytics';
+/**
+ * Creates a throttled version of a callback function
+ * Ensures the callback is executed at most once every `limitMs` milliseconds
+ * @param callback - The function to throttle
+ * @param limitMs - The time limit in milliseconds
+ * @param options - `trailing`: instead of dropping the calls made inside the window, run the
+ * last one when the window ends
+ * @returns A throttled function
+ */
+export declare function createThrottle<T extends (...args: unknown[]) => void>(callback: T, limitMs: number, options?: {
+    trailing?: boolean;
+}): (...args: Parameters<T>) => void;
+/**
+ * Extracts the contentlet identifier from a DOM element
+ * @param element - The HTML element containing data attributes
+ * @returns The contentlet identifier or null if not found
+ */
+export declare function extractContentletIdentifier(element: HTMLElement): string | null;
+/**
+ * Extracts all contentlet data from a DOM element's data attributes
+ * @param element - The HTML element containing data attributes
+ * @returns Complete contentlet data object
+ */
+export declare function extractContentletData(element: HTMLElement): ContentletData;
+/**
+ * Initial scan delay for DOM readiness
+ * Allows React/Next.js to finish rendering before scanning for contentlets
+ */
+export declare const INITIAL_SCAN_DELAY_MS = 100;
+/**
+ * Finds all contentlet elements in the DOM
+ * @returns Array of contentlet HTMLElements
+ */
+export declare const findContentlets: () => HTMLElement[];
+/**
+ * Creates a MutationObserver that watches for contentlet changes in the DOM
+ * @param callback - Function to call when mutations are detected
+ * @param debounceMs - Debounce time in milliseconds (default: 250ms)
+ * @param options - `identifiers`: also call back when a contentlet receives its
+ * `data-dot-identifier`. The renderers print it after hydration, usually within
+ * milliseconds of the contentlet itself, so calls inside the window are not dropped: the
+ * last one runs when it ends.
+ * @returns Configured and active MutationObserver
+ */
+export declare const createContentletObserver: (callback: () => void, debounceMs?: number, options?: {
+    identifiers?: boolean;
+}) => MutationObserver;
+/**
+ * Cleans up a content tracker when the browser discards the page. A page kept in the
+ * back/forward cache keeps its tracker, which works again when the visitor goes back to it.
+ * @param cleanup - Function to call when the page is discarded
+ */
+export declare const setupPluginCleanup: (cleanup: () => void) => void;
+/**
+ * Gets enhanced tracking plugins based on configuration
+ * Returns content impression and click tracking plugins if enabled
+ * @param config - Analytics configuration
+ * @param impressionPlugin - Impression tracking plugin factory
+ * @param clickPlugin - Click tracking plugin factory
+ * @returns Array of enabled tracking plugins
+ */
+export declare const getEnhancedTrackingPlugins: (config: PipelineConfig, impressionPlugin: (config: PipelineConfig) => AnalyticsPlugin, clickPlugin: (config: PipelineConfig) => AnalyticsPlugin) => AnalyticsPlugin[];

package/src/lib/contentlets/viewport.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Where a contentlet sits in the viewport, which both content trackers measure.
+ * Pure functions without class dependencies for better testability and reusability
+ */
+import type { ViewportMetrics } from '../pipeline/models';
+/**
+ * Calculates the visibility ratio of an element in the viewport
+ * @param element - The HTML element to check
+ * @returns A number between 0 and 1 representing the visible percentage
+ */
+export declare function calculateElementVisibilityRatio(element: HTMLElement): number;
+/**
+ * Calculates the offset percentage of an element from the top of the viewport
+ * @param element - The HTML element to check
+ * @returns Percentage value (can be negative if above viewport)
+ */
+export declare function calculateViewportOffset(element: HTMLElement): number;
+/**
+ * Gets comprehensive viewport metrics for an element
+ * @param element - The HTML element to analyze
+ * @returns Object containing offset percentage and visibility ratio
+ */
+export declare function getViewportMetrics(element: HTMLElement): ViewportMetrics;

package/src/lib/events.d.ts

@@ -0,0 +1,17 @@
+import type { ExperimentPages } from './experiments/engine';
+import type { DotCMSEvents, DotCMSEventsConfig } from './models';
+/**
+ * Starts the SDK: what `dotEvents.init` does, with how the pages mark their experiment. Apps call
+ * `dotEvents.init`, for pages that print the experiment markup; the script dotCMS injects into
+ * traditional pages calls this with `contentlets`, since those pages carry dotCMS's contentlet
+ * wrappers instead. Not exported by the package.
+ *
+ * @param config - The app's config
+ * @param pages - How the pages mark what their experiment varies
+ */
+export declare const initEvents: (config: DotCMSEventsConfig, pages: ExperimentPages) => void;
+/**
+ * The events SDK. There is one object per page: every import gets the same instance,
+ * configured by the one `init` call.
+ */
+export declare const dotEvents: DotCMSEvents;

package/src/lib/experiments/api.d.ts

@@ -0,0 +1,9 @@
+import type { IsUserIncludedResult } from './models';
+/**
+ * Asks dotCMS which running experiments the visitor is in.
+ *
+ * @param dotcmsUrl - The dotCMS origin, without a trailing slash
+ * @param exclude - Experiments already evaluated, so the server skips them
+ * @returns `ok` with the entity, `disabled` on a 403 (Experiments off), or `failed`
+ */
+export declare const fetchIsUserIncluded: (dotcmsUrl: string, exclude: string[]) => Promise<IsUserIncludedResult>;

package/src/lib/experiments/boot.d.ts

@@ -0,0 +1,53 @@
+import { decideVariant } from './decision';
+/**
+ * What the boot script needs, embedded as JSON because the function runs detached.
+ */
+export interface ExperimentBootConfig {
+    id: string;
+    rendered: string;
+    assignmentsKey: string;
+    disabledUntilKey: string;
+    bootKey: string;
+    styleId: string;
+    revealRule: string;
+    param: string;
+    defaultVariant: string;
+    quietMs: number;
+}
+/**
+ * Applies, while the HTML is parsed and before the app's scripts load, what `decide` says from
+ * what the engine stored on an earlier page: it shows the content, or stops the page and
+ * replaces it with the assigned variant. It never calls dotCMS: when nothing is stored, the
+ * content stays hidden and the engine decides once it loads.
+ *
+ * It is printed into the page with `Function.prototype.toString`, next to `decideVariant`, so
+ * it must not reference anything outside itself: the decision arrives as `decide`, and every
+ * value in `config`.
+ *
+ * @param decide - `decideVariant`, the decision the engine makes too
+ * @param config - The page's experiment and the shared names
+ * @param w - The window, a parameter so tests can pass their own
+ */
+export declare function dotcmsExperimentBoot(decide: typeof decideVariant, config: ExperimentBootConfig, w?: Window): void;
+/** The page's experiment, as the markup passes it to `buildExperimentBootScript`. */
+export interface ExperimentBootOptions {
+    /** The experiment running on the page. */
+    experimentId: string;
+    /** The variant the server rendered. */
+    variant: string;
+}
+/**
+ * Builds the configuration the boot script runs with.
+ *
+ * @param options - The experiment and the variant the server rendered
+ * @returns The configuration
+ */
+export declare const createExperimentBootConfig: ({ experimentId, variant }: ExperimentBootOptions) => ExperimentBootConfig;
+/**
+ * Builds the inline script printed before an experiment's content, right after the rule
+ * that hides it: the boot function, called with the decision function and its config.
+ *
+ * @param options - The experiment and the variant the server rendered
+ * @returns The script's source
+ */
+export declare const buildExperimentBootScript: (options: ExperimentBootOptions) => string;

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

@@ -0,0 +1,46 @@
+/**
+ * Attribute on the element that wraps what an experiment varies, with the experiment's id.
+ * `DotCMSExperiment` and `experimentMarkup` put it there; the engine reads it.
+ */
+export declare const EXPERIMENT_ATTRIBUTE = "data-dot-experiment";
+/** Attribute with the variant the server rendered in that element. */
+export declare const VARIANT_ATTRIBUTE = "data-dot-variant";
+/** Name dotCMS gives the original variant. */
+export declare const DEFAULT_VARIANT = "DEFAULT";
+/** Query parameter the page API reads to render a variant. */
+export declare const VARIANT_QUERY_PARAM = "variantName";
+/** Endpoint that assigns the visitor to the running experiments. */
+export declare const IS_USER_INCLUDED_PATH = "/api/v1/experiments/isUserIncluded";
+/**
+ * How long an experiment's content may stay hidden while its variant is decided. Past it the
+ * hiding rule shows the content, the boot script no longer redirects, and the engine's default
+ * wait ends.
+ */
+export declare const DECISION_TIMEOUT_MS = 3000;
+/** Default wait for the assignment on the pages the engine decides itself. */
+export declare const DEFAULT_ASSIGNMENT_TIMEOUT_MS = 3000;
+/** The request itself may run longer than the wait, so the next page can use its answer. */
+export declare const IS_USER_INCLUDED_REQUEST_TIMEOUT_MS = 10000;
+export declare const ONE_DAY_MS: number;
+/** How long the page being replaced keeps its new requests waiting. */
+export declare const QUIET_MS = 5000;
+/**
+ * Rule printed before an experiment's content: the marked element stays hidden until the
+ * variant is decided, and shows on its own after `DECISION_TIMEOUT_MS` if nothing decides it
+ * (JavaScript off, SDK missing).
+ */
+export declare const HIDING_RULE: string;
+export declare const STORAGE_KEYS: {
+    /** localStorage: assignments and the experiment ids already evaluated. */
+    readonly assignments: "dot_events_experiments";
+    /** localStorage: until when the site answered 403 (Experiments off). */
+    readonly disabledUntil: "dot_events_experiments_off_until";
+    /** sessionStorage: this tab already asked `isUserIncluded`. */
+    readonly checkedThisTab: "dot_events_experiments_checked";
+    /** sessionStorage: the cumulative `context.experiments` of the analytics session. */
+    readonly sessionExperiments: "dot_events_session_experiments";
+};
+/** Window property where the boot script leaves its decision on the page it ran on. */
+export declare const BOOT_STATE_KEY = "__dotEventsExperimentBoot";
+/** Id of the style element that reveals decided content. */
+export declare const REVEAL_STYLE_ID = "dotcms-experiment-reveal";

package/src/lib/experiments/decision.d.ts

@@ -0,0 +1,53 @@
+/**
+ * What to do with an experiment's content on the current page, from what is stored:
+ *
+ * - `unknown`: nothing is stored about the experiment; dotCMS has to be asked.
+ * - `excluded`: experiments are off, or the visitor was evaluated and is not in this one.
+ * - `assigned`: the server rendered the visitor's variant.
+ * - `ignored`: the visitor has another variant and the URL already asks for it, so the route
+ *   does not pass `variantName` to its page request; loading the URL again would loop.
+ * - `redirect`: the visitor has another variant, at `url`.
+ */
+export type VariantDecision = {
+    kind: 'unknown';
+} | {
+    kind: 'excluded';
+} | {
+    kind: 'assigned';
+    variant: string;
+} | {
+    kind: 'ignored';
+    variant: string;
+} | {
+    kind: 'redirect';
+    variant: string;
+    url: string;
+};
+/** What `decideVariant` reads. */
+export interface VariantDecisionInput {
+    /** The experiment the page runs. */
+    experimentId: string;
+    /** The variant the server rendered. */
+    rendered: string;
+    /** The current URL. */
+    href: string;
+    /** The stored assignments, as parsed from storage: any shape is tolerated. */
+    stored: unknown;
+    /** Experiments are off (a 403 in the last day). */
+    disabled: boolean;
+    /** The current time, in ms. */
+    now: number;
+    /** The query parameter that selects a variant. */
+    param: string;
+    /** The name of the original variant. */
+    defaultVariant: string;
+}
+/**
+ * Decides an experiment's content from what is stored. It is pure, and the boot script prints
+ * it with `Function.prototype.toString`, so it must not reference anything outside itself:
+ * the engine and the boot script run this same function.
+ *
+ * @param input - The page's experiment, the URL, the stored assignments and the shared names
+ * @returns What to do with the content
+ */
+export declare function decideVariant(input: VariantDecisionInput): VariantDecision;

package/src/lib/experiments/dom.d.ts

@@ -0,0 +1,62 @@
+import type { PageExperimentMark } from './models';
+/**
+ * Reads the experiments the current page renders, from their marks: each experiment and
+ * rendered variant once, in document order.
+ *
+ * @returns The experiments and the variants the server rendered
+ */
+export declare const readPageExperiments: () => PageExperimentMark[];
+/**
+ * Calls back when marks are inserted or rewritten, so the engine decides content that arrives
+ * after its first decision: Suspense content that streams in, or a route that changes only its
+ * query and keeps its elements.
+ *
+ * @param changed - Called once per batch of DOM changes that touches a mark
+ * @returns Stops observing
+ */
+export declare const observeMarks: (changed: () => void) => (() => void);
+/**
+ * Shows rows the renderer hid. With an id and a variant, only that experiment's rows rendered
+ * with that variant, so a route kept in the page with another render stays hidden; without an
+ * id, all of them (engine off, inside UVE).
+ *
+ * The rule beats the renderer's hiding rule through `:root` and `!important`, whatever the
+ * order of the two in the document.
+ *
+ * @param experimentId - The experiment whose rows to show
+ * @param variant - The variant they were rendered with
+ */
+export declare const revealRows: (experimentId?: string, variant?: string) => void;
+/**
+ * Hides the contentlet wrappers dotCMS prints on the pages it renders: they hold what a variant
+ * changes. Like the markup's rule, it shows them on its own after `DECISION_TIMEOUT_MS`.
+ */
+export declare const hideContentlets: () => void;
+/**
+ * Shows the contentlet wrappers `hideContentlets` hid, and asks the impression tracker to scan
+ * again for them.
+ */
+export declare const revealContentlets: () => void;
+/**
+ * The variant a page dotCMS rendered shows: the one its contentlet wrappers carry in
+ * `data-dot-variant`, or, when the variant changes none of them (or the wrappers are not
+ * parsed yet), the one its URL asks for. dotCMS renders the variant `variantName` names.
+ *
+ * @param href - The page's URL
+ * @returns The rendered variant
+ */
+export declare const readRenderedVariant: (href: string) => string;
+/**
+ * Holds the page's new `fetch` calls, except `keepalive` ones (an analytics flush), for
+ * `QUIET_MS`. A page being replaced runs until the variant's document arrives, and a hydrated
+ * app goes on prefetching its links; held, they do not compete with the variant's server render.
+ * A held call never settles, and after `QUIET_MS` only new calls go out.
+ */
+export declare const holdRequests: () => void;
+/**
+ * Replaces the page with a variant's URL: stops its loading, navigates, and holds its new
+ * requests, as the boot script does when it decides from storage.
+ *
+ * @param url - The variant's URL
+ */
+export declare const leavePageFor: (url: string) => void;

package/src/lib/experiments/engine.d.ts

@@ -0,0 +1,66 @@
+import type { DotCMSEventsError } from '../models';
+import type { DotCMSEventContextExperiment } from '../pipeline/models';
+/** What the engine decided for the current page. */
+export interface PageDecision {
+    /** True when the engine navigated to the assigned variant; the pageview is dropped. */
+    redirected: boolean;
+    /**
+     * True when the visitor went to another page while this one was decided; its pageview is
+     * dropped, and the other page is decided and counted on its own.
+     */
+    left?: true;
+}
+/**
+ * How the pages mark what their experiment varies. `markup`: the element `experimentMarkup`
+ * and `DotCMSExperiment` print, on headless apps. `contentlets`: the contentlet wrappers dotCMS
+ * prints on the pages it renders, which carry the rendered variant in `data-dot-variant`; the
+ * experiment comes from the `isExperimentPage` rule `isUserIncluded` returns.
+ */
+export type ExperimentPages = 'markup' | 'contentlets';
+/** The experiments engine behind `dotEvents`. */
+export interface ExperimentsEngine {
+    /**
+     * On `contentlets` pages, decides from storage while the page's head is parsed: it replaces
+     * the page with the assigned variant before it paints, or, on a first visit, hides the
+     * contentlets until `isUserIncluded` answers. Does nothing on `markup` pages.
+     *
+     * @returns True when it replaced the page
+     */
+    prepare(): boolean;
+    /** Starts the assignment check, when one is due. */
+    start(): void;
+    /**
+     * Decides the current page: reveal its rows, or redirect to the assigned variant. From then
+     * on it also decides the marks that arrive later, as content streams in.
+     */
+    decide(): Promise<PageDecision>;
+    /**
+     * The session's cumulative `context.experiments`, while the page on screen runs an
+     * experiment the visitor is in; none on any other page.
+     */
+    contextExperiments(sessionId: string): DotCMSEventContextExperiment[];
+    /** Stops watching the page: for marks that arrive later, and for its navigations. */
+    stop(): void;
+}
+interface EngineOptions {
+    dotcmsUrl: string;
+    timeoutMs: number;
+    log: (...args: unknown[]) => void;
+    /** Reports a setup mistake; prints only in debug, like `log`. */
+    warn: (message: string) => void;
+    /** Reports a failed experiments check to the app's `onError`. */
+    onError?: (error: DotCMSEventsError) => void;
+    /** Replaces the page with a variant's URL (`leavePageFor`); a parameter so specs can watch it. */
+    navigate?: (url: string) => void;
+    /** How the pages mark their experiment; `markup` by default. */
+    pages?: ExperimentPages;
+}
+/**
+ * Creates the engine that assigns the visitor, holds and releases pageviews, redirects to
+ * the assigned variant and fills `context.experiments`.
+ *
+ * @param options - dotCMS origin, the assignment timeout and a logger
+ * @returns The engine
+ */
+export declare const createExperimentsEngine: ({ dotcmsUrl, timeoutMs, log, warn, onError, navigate, pages }: EngineOptions) => ExperimentsEngine;
+export {};

package/src/lib/experiments/markup.d.ts

@@ -0,0 +1,17 @@
+import type { DotCMSEventsExperimentMarkup, DotCMSEventsExperimentPage } from '../models';
+/**
+ * Builds what a page prints so its experiment runs: the attributes for the element that wraps
+ * what the experiment varies, the rule that keeps it hidden, and the boot script that decides
+ * the visitor's variant while the HTML is parsed. Render it on the server, with the style and
+ * the script before the element. `DotCMSExperiment` (`@dotcms/events/react`) does it for React.
+ *
+ * @param page - The page asset, requested for the variant in the URL's `variantName`
+ * @returns The markup, or null when no experiment runs on the page
+ *
+ * @example
+ * ```ts
+ * const markup = experimentMarkup(pageAsset);
+ * // <style>{markup.style}</style><script>{markup.script}</script><div {...markup.attributes}>…</div>
+ * ```
+ */
+export declare const experimentMarkup: (page: DotCMSEventsExperimentPage | null | undefined) => DotCMSEventsExperimentMarkup | null;

package/src/lib/experiments/models.d.ts

@@ -0,0 +1,62 @@
+/** A variant, as `isUserIncluded` returns it. */
+export interface DotCMSExperimentVariant {
+    name: string;
+    url: string;
+}
+/** An experiment the visitor was assigned to, as `isUserIncluded` returns it. */
+export interface DotCMSAssignedExperiment {
+    id: string;
+    name: string;
+    runningId: string;
+    pageUrl: string;
+    lookBackWindow: {
+        expireMillis: number;
+        value: string;
+    };
+    regexs: {
+        isExperimentPage: string;
+        isTargetPage: string | null;
+    };
+    variant: DotCMSExperimentVariant;
+}
+/** The `entity` of the `isUserIncluded` response. */
+export interface DotCMSIsUserIncludedEntity {
+    experiments: DotCMSAssignedExperiment[];
+    includedExperimentIds: string[];
+    excludedExperimentIds: string[];
+    excludedExperimentIdsEnded: string[];
+}
+/** An assignment kept in localStorage, with the moment it stops being valid. */
+export type StoredExperiment = DotCMSAssignedExperiment & {
+    expiresAt: number;
+};
+/** What the engine keeps in localStorage between visits. */
+export interface StoredAssignments {
+    fetchedAt: number;
+    experiments: StoredExperiment[];
+    /** Every experiment already evaluated, assigned or not, sent back as `exclude`. */
+    evaluatedIds: string[];
+}
+/** The result of asking `isUserIncluded`. */
+export type IsUserIncludedResult = {
+    status: 'ok';
+    entity: DotCMSIsUserIncludedEntity;
+} | {
+    status: 'disabled';
+} | {
+    status: 'failed';
+    httpStatus?: number;
+};
+/** The experiment a page carries in its marks. */
+export interface PageExperimentMark {
+    experimentId: string;
+    variant: string;
+}
+/**
+ * What the boot script leaves on `window[BOOT_STATE_KEY]` when it replaces the page with the
+ * assigned variant, so the engine neither redirects again nor sends that page's pageview.
+ */
+export interface ExperimentBootState {
+    /** The variant's URL. */
+    redirectedTo: string;
+}

package/src/lib/experiments/plugin.d.ts

@@ -0,0 +1,27 @@
+import type { ExperimentsEngine } from './engine';
+import type { EventContext } from '../pipeline/models';
+interface PayloadWithContext {
+    context?: EventContext;
+    [key: string]: unknown;
+}
+/**
+ * Analytics.js plugin that adds the session's `context.experiments` to every event sent from
+ * a page that runs an experiment the visitor is in. The engine's `isUserIncluded` check starts
+ * in `init`, before Analytics.js loads.
+ *
+ * It must come right after the identity plugin, which creates `context`.
+ *
+ * @param engine - The experiments engine
+ * @returns The plugin
+ */
+export declare const experimentsPlugin: (engine: ExperimentsEngine) => {
+    name: string;
+    pageStart: ({ payload }: {
+        payload: PayloadWithContext;
+    }) => PayloadWithContext;
+    trackStart: ({ payload }: {
+        payload: PayloadWithContext;
+    }) => PayloadWithContext;
+    loaded: () => boolean;
+};
+export {};

package/src/lib/experiments/store.d.ts

@@ -0,0 +1,54 @@
+import type { DotCMSIsUserIncludedEntity, StoredAssignments } from './models';
+import type { DotCMSEventContextExperiment } from '../pipeline/models';
+/**
+ * Loads the stored assignments, without the ones whose look-back window has passed.
+ *
+ * @returns The assignments, or null when there are none
+ */
+export declare const loadAssignments: () => StoredAssignments | null;
+/**
+ * Merges an `isUserIncluded` answer into the stored assignments and saves them.
+ * Ended experiments drop out; every evaluated experiment is remembered, so a visitor
+ * left out by traffic allocation is not evaluated again.
+ *
+ * @param entity - The response entity
+ * @param previous - What was stored before the request
+ * @returns The assignments now stored
+ */
+export declare const saveAssignments: (entity: DotCMSIsUserIncludedEntity, previous: StoredAssignments | null) => StoredAssignments;
+/**
+ * Tells whether this tab should ask `isUserIncluded`: once per tab session, when nothing
+ * is stored, or when the stored answer is older than a day.
+ *
+ * @param stored - The current assignments
+ * @returns True when a request is due
+ */
+export declare const isCheckDue: (stored: StoredAssignments | null) => boolean;
+/** Records that this tab asked `isUserIncluded`. */
+export declare const markCheckedThisTab: () => void;
+/** Tells whether the site answered 403 in the last day. */
+export declare const isDisabledForNow: () => boolean;
+/** Remembers a 403 for a day, so sites without Experiments stop paying for the call. */
+export declare const disableForADay: () => void;
+/**
+ * Returns the experiments the visitor reached in this analytics session. A new session
+ * starts empty.
+ *
+ * @param sessionId - The analytics session id
+ * @returns The cumulative `context.experiments`
+ */
+export declare const getSessionExperiments: (sessionId: string) => DotCMSEventContextExperiment[];
+/**
+ * Adds an experiment to the session's `context.experiments`, replacing an older entry
+ * for the same experiment.
+ *
+ * @param sessionId - The analytics session id
+ * @param entry - The experiment the visitor reached
+ */
+export declare const joinSessionExperiment: (sessionId: string, entry: DotCMSEventContextExperiment) => void;
+/**
+ * Removes ended experiments from the session's `context.experiments`.
+ *
+ * @param endedIds - Ids `isUserIncluded` reported as ended
+ */
+export declare const leaveEndedExperiments: (endedIds: string[]) => void;

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

@@ -0,0 +1,28 @@
+/**
+ * Impression tracking configuration constants
+ */
+/**
+ * Default minimum percentage of element that must be visible (0.0 to 1.0)
+ */
+export declare const DEFAULT_IMPRESSION_VISIBILITY_THRESHOLD = 0.5;
+/**
+ * Default minimum time in milliseconds element must be visible
+ */
+export declare const DEFAULT_IMPRESSION_DWELL_MS = 750;
+/**
+ * Default maximum number of elements to track (performance limit)
+ */
+export declare const DEFAULT_IMPRESSION_MAX_NODES = 100;
+/**
+ * Default impression tracking configuration
+ */
+export declare const DEFAULT_IMPRESSION_CONFIG: {
+    readonly visibilityThreshold: 0.5;
+    readonly dwellMs: 750;
+    readonly maxNodes: 100;
+};
+/**
+ * Event type for content impressions
+ * Must match DotCMSPredefinedEventType.CONTENT_IMPRESSION
+ */
+export declare const IMPRESSION_EVENT_TYPE = "content_impression";

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

@@ -0,0 +1,38 @@
+import type { PipelineConfig } from '../pipeline/models';
+import type { AnalyticsInstance } from 'analytics';
+/**
+ * Impressions plugin of the events pipeline.
+ * Handles automatic tracking of content visibility and impressions.
+ *
+ * This plugin initializes the impression tracker which:
+ * - Uses IntersectionObserver to detect when contentlets are visible
+ * - Tracks dwell time (how long elements are visible)
+ * - Fires 'content-impression' events via instance.track()
+ * - Deduplicates impressions per session
+ *
+ * Analytics.js runs the plugins in the order events.ts registers them: identity, experiments,
+ * impressions, clicks, enricher, sender. This one hooks into no event: its tracker fires
+ * events through instance.track(), which runs them through the other plugins like any event.
+ *
+ * Note: This plugin is only registered if config.impressions is enabled.
+ * See getEnhancedTrackingPlugins() for conditional loading logic.
+ *
+ * @param {PipelineConfig} config - Configuration with impressions settings
+ * @returns {Object} Plugin object with lifecycle methods
+ */
+export declare const impressionsPlugin: (config: PipelineConfig) => {
+    name: string;
+    /**
+     * Initialize impression tracking
+     * Called when Analytics.js initializes the plugin with instance context
+     * @param instance - Analytics.js instance with track method
+     */
+    initialize: ({ instance }: {
+        instance: AnalyticsInstance;
+    }) => Promise<void>;
+    /**
+     * Setup cleanup handlers when plugin is loaded
+     * Called after Analytics.js completes plugin loading
+     */
+    loaded: () => boolean;
+};