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

package/markup.cjs.default.js

@@ -0,0 +1 @@
+exports._default = require('./markup.cjs.js').default;

package/markup.cjs.js

@@ -0,0 +1,161 @@
+'use strict';
+
+var decision = require('./decision.cjs.js');
+
+/**
+ * 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
+ */
+function dotcmsExperimentBoot(decide, config, w = window) {
+    const reveal = () => {
+        const doc = w.document;
+        const Sheet = w.CSSStyleSheet;
+        // An adopted style sheet where the browser has them: no Content-Security-Policy blocks
+        // a change through the CSSOM, while it blocks a style element without the page's nonce
+        if ('adoptedStyleSheets' in doc && typeof Sheet === 'function') {
+            try {
+                const sheet = new Sheet();
+                const sheets = Array.prototype.slice.call(doc.adoptedStyleSheets);
+                sheet.replaceSync(config.revealRule);
+                sheets.push(sheet);
+                doc.adoptedStyleSheets = sheets;
+                return;
+            }
+            catch {
+                // A style element instead
+            }
+        }
+        let style = doc.getElementById(config.styleId);
+        if (!style) {
+            style = doc.createElement('style');
+            style.id = config.styleId;
+            doc.head.appendChild(style);
+        }
+        style.appendChild(doc.createTextNode(config.revealRule));
+    };
+    try {
+        // Inside the UVE editor nothing is decided and nothing stays hidden
+        if (w.parent !== w) {
+            reveal();
+            return;
+        }
+        const read = (key) => {
+            try {
+                return JSON.parse(w.localStorage.getItem(key) || 'null');
+            }
+            catch {
+                return null;
+            }
+        };
+        const now = Date.now();
+        const decision = decide({
+            experimentId: config.id,
+            rendered: config.rendered,
+            href: w.location.href,
+            stored: read(config.assignmentsKey),
+            disabled: Number(read(config.disabledUntilKey) || 0) > now,
+            now,
+            param: config.param,
+            defaultVariant: config.defaultVariant
+        });
+        // A new visitor: the engine asks dotCMS once it loads
+        if (decision.kind === 'unknown') {
+            return;
+        }
+        if (decision.kind !== 'redirect') {
+            reveal();
+            return;
+        }
+        const state = { redirectedTo: decision.url };
+        w[config.bootKey] = state;
+        // No more parsing, scripts or images on the page being replaced. It still runs until
+        // the variant's document arrives: its new requests are held, except keepalive ones (an
+        // analytics flush). A held request never settles; after quietMs, fetch works again
+        // for new calls only.
+        w.stop();
+        w.location.replace(decision.url);
+        const send = w.fetch;
+        w.fetch = (input, init) => init && init.keepalive
+            ? send.call(w, input, init)
+            : new Promise(() => undefined);
+        w.setTimeout(() => {
+            w.fetch = send;
+        }, config.quietMs);
+    }
+    catch {
+        // Storage blocked: the engine decides when it loads
+    }
+}
+/** Escapes a value for a CSS attribute selector in double quotes. */
+const escapeAttribute = (value) => value.replace(/["\\]/g, '\\$&');
+/**
+ * Builds the configuration the boot script runs with.
+ *
+ * @param options - The experiment and the variant the server rendered
+ * @returns The configuration
+ */
+const createExperimentBootConfig = ({ experimentId, variant }) => ({
+    id: experimentId,
+    rendered: variant,
+    assignmentsKey: decision.STORAGE_KEYS.assignments,
+    disabledUntilKey: decision.STORAGE_KEYS.disabledUntil,
+    bootKey: decision.BOOT_STATE_KEY,
+    styleId: decision.REVEAL_STYLE_ID,
+    // Keyed by the rendered variant too: a route kept in the page with another render stays hidden
+    revealRule: `:root [${decision.EXPERIMENT_ATTRIBUTE}="${escapeAttribute(experimentId)}"][${decision.VARIANT_ATTRIBUTE}="${escapeAttribute(variant)}"]{visibility:visible !important;animation:none !important}`,
+    param: decision.VARIANT_QUERY_PARAM,
+    defaultVariant: decision.DEFAULT_VARIANT,
+    quietMs: decision.QUIET_MS
+});
+/**
+ * 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
+ */
+const buildExperimentBootScript = (options) => {
+    // `<` is escaped so no value can close the script element
+    const json = JSON.stringify(createExperimentBootConfig(options)).replace(/</g, '\\u003c');
+    return `(${dotcmsExperimentBoot.toString()})(${decision.decideVariant.toString()}, ${json});`;
+};
+
+/**
+ * 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>
+ * ```
+ */
+const experimentMarkup = (page) => {
+    const experimentId = page?.runningExperimentId;
+    if (!experimentId) {
+        return null;
+    }
+    const variant = page?.viewAs?.variantId || decision.DEFAULT_VARIANT;
+    return {
+        attributes: { [decision.EXPERIMENT_ATTRIBUTE]: experimentId, [decision.VARIANT_ATTRIBUTE]: variant },
+        style: decision.HIDING_RULE,
+        script: buildExperimentBootScript({ experimentId, variant })
+    };
+};
+
+exports.experimentMarkup = experimentMarkup;

package/markup.cjs.mjs

@@ -0,0 +1,2 @@
+export * from './markup.cjs.js';
+export { _default as default } from './markup.cjs.default.js';

package/markup.d.ts

@@ -0,0 +1 @@
+export * from "./src/markup";

package/markup.esm.js

@@ -0,0 +1,159 @@
+import { d as decideVariant, S as STORAGE_KEYS, B as BOOT_STATE_KEY, R as REVEAL_STYLE_ID, E as EXPERIMENT_ATTRIBUTE, V as VARIANT_ATTRIBUTE, b as VARIANT_QUERY_PARAM, D as DEFAULT_VARIANT, Q as QUIET_MS, H as HIDING_RULE } from './decision.esm.js';
+
+/**
+ * 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
+ */
+function dotcmsExperimentBoot(decide, config, w = window) {
+    const reveal = () => {
+        const doc = w.document;
+        const Sheet = w.CSSStyleSheet;
+        // An adopted style sheet where the browser has them: no Content-Security-Policy blocks
+        // a change through the CSSOM, while it blocks a style element without the page's nonce
+        if ('adoptedStyleSheets' in doc && typeof Sheet === 'function') {
+            try {
+                const sheet = new Sheet();
+                const sheets = Array.prototype.slice.call(doc.adoptedStyleSheets);
+                sheet.replaceSync(config.revealRule);
+                sheets.push(sheet);
+                doc.adoptedStyleSheets = sheets;
+                return;
+            }
+            catch {
+                // A style element instead
+            }
+        }
+        let style = doc.getElementById(config.styleId);
+        if (!style) {
+            style = doc.createElement('style');
+            style.id = config.styleId;
+            doc.head.appendChild(style);
+        }
+        style.appendChild(doc.createTextNode(config.revealRule));
+    };
+    try {
+        // Inside the UVE editor nothing is decided and nothing stays hidden
+        if (w.parent !== w) {
+            reveal();
+            return;
+        }
+        const read = (key) => {
+            try {
+                return JSON.parse(w.localStorage.getItem(key) || 'null');
+            }
+            catch {
+                return null;
+            }
+        };
+        const now = Date.now();
+        const decision = decide({
+            experimentId: config.id,
+            rendered: config.rendered,
+            href: w.location.href,
+            stored: read(config.assignmentsKey),
+            disabled: Number(read(config.disabledUntilKey) || 0) > now,
+            now,
+            param: config.param,
+            defaultVariant: config.defaultVariant
+        });
+        // A new visitor: the engine asks dotCMS once it loads
+        if (decision.kind === 'unknown') {
+            return;
+        }
+        if (decision.kind !== 'redirect') {
+            reveal();
+            return;
+        }
+        const state = { redirectedTo: decision.url };
+        w[config.bootKey] = state;
+        // No more parsing, scripts or images on the page being replaced. It still runs until
+        // the variant's document arrives: its new requests are held, except keepalive ones (an
+        // analytics flush). A held request never settles; after quietMs, fetch works again
+        // for new calls only.
+        w.stop();
+        w.location.replace(decision.url);
+        const send = w.fetch;
+        w.fetch = (input, init) => init && init.keepalive
+            ? send.call(w, input, init)
+            : new Promise(() => undefined);
+        w.setTimeout(() => {
+            w.fetch = send;
+        }, config.quietMs);
+    }
+    catch {
+        // Storage blocked: the engine decides when it loads
+    }
+}
+/** Escapes a value for a CSS attribute selector in double quotes. */
+const escapeAttribute = (value) => value.replace(/["\\]/g, '\\$&');
+/**
+ * Builds the configuration the boot script runs with.
+ *
+ * @param options - The experiment and the variant the server rendered
+ * @returns The configuration
+ */
+const createExperimentBootConfig = ({ experimentId, variant }) => ({
+    id: experimentId,
+    rendered: variant,
+    assignmentsKey: STORAGE_KEYS.assignments,
+    disabledUntilKey: STORAGE_KEYS.disabledUntil,
+    bootKey: BOOT_STATE_KEY,
+    styleId: REVEAL_STYLE_ID,
+    // Keyed by the rendered variant too: a route kept in the page with another render stays hidden
+    revealRule: `:root [${EXPERIMENT_ATTRIBUTE}="${escapeAttribute(experimentId)}"][${VARIANT_ATTRIBUTE}="${escapeAttribute(variant)}"]{visibility:visible !important;animation:none !important}`,
+    param: VARIANT_QUERY_PARAM,
+    defaultVariant: DEFAULT_VARIANT,
+    quietMs: QUIET_MS
+});
+/**
+ * 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
+ */
+const buildExperimentBootScript = (options) => {
+    // `<` is escaped so no value can close the script element
+    const json = JSON.stringify(createExperimentBootConfig(options)).replace(/</g, '\\u003c');
+    return `(${dotcmsExperimentBoot.toString()})(${decideVariant.toString()}, ${json});`;
+};
+
+/**
+ * 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>
+ * ```
+ */
+const experimentMarkup = (page) => {
+    const experimentId = page?.runningExperimentId;
+    if (!experimentId) {
+        return null;
+    }
+    const variant = page?.viewAs?.variantId || DEFAULT_VARIANT;
+    return {
+        attributes: { [EXPERIMENT_ATTRIBUTE]: experimentId, [VARIANT_ATTRIBUTE]: variant },
+        style: HIDING_RULE,
+        script: buildExperimentBootScript({ experimentId, variant })
+    };
+};
+
+export { experimentMarkup };

package/package.json

@@ -1,6 +1,79 @@
 {
   "name": "@dotcms/events",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "26.10.5-1-alpha.0",
+  "description": "Official JavaScript library for dotCMS events: pageviews, conversions, content clicks and impressions, and experiments.",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/dotCMS/core.git#main"
+  },
+  "peerDependencies": {
+    "@dotcms/uve": "26.10.5-1",
+    "react": ">=18"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    }
+  },
+  "dependencies": {
+    "@analytics/queue-utils": "^0.1.3",
+    "@analytics/router-utils": "^0.1.1",
+    "analytics": "^0.8.0"
+  },
+  "devDependencies": {
+    "@dotcms/types": "26.10.5-1"
+  },
+  "keywords": [
+    "dotCMS",
+    "CMS",
+    "Content Management",
+    "Analytics",
+    "Experiments",
+    "Events",
+    "Tracking"
+  ],
+  "exports": {
+    "./package.json": "./package.json",
+    ".": {
+      "types": "./index.d.ts",
+      "module": "./index.esm.js",
+      "import": "./index.cjs.mjs",
+      "default": "./index.cjs.js"
+    },
+    "./markup": {
+      "types": "./markup.d.ts",
+      "module": "./markup.esm.js",
+      "import": "./markup.cjs.mjs",
+      "default": "./markup.cjs.js"
+    },
+    "./react": {
+      "types": "./react.d.ts",
+      "module": "./react.esm.js",
+      "import": "./react.cjs.mjs",
+      "default": "./react.cjs.js"
+    }
+  },
+  "typesVersions": {
+    "*": {
+      ".": [
+        "./src/index.d.ts"
+      ],
+      "markup": [
+        "./src/markup.d.ts"
+      ],
+      "react": [
+        "./src/react.d.ts"
+      ]
+    }
+  },
+  "author": "dotcms <dev@dotcms.com>",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/dotCMS/core/issues"
+  },
+  "homepage": "https://github.com/dotCMS/core/tree/main/core-web/libs/sdk/events/README.md",
+  "sideEffects": false,
+  "module": "./index.esm.js",
+  "main": "./index.cjs.js",
+  "types": "./index.d.ts"
+}

package/react.cjs.default.js

@@ -0,0 +1 @@
+exports._default = require('./react.cjs.js').default;

package/react.cjs.js

@@ -0,0 +1,39 @@
+'use strict';
+
+var jsxRuntime = require('react/jsx-runtime');
+var markup = require('./markup.cjs.js');
+require('./decision.cjs.js');
+
+/**
+ * Runs the page's experiment on its content. On a page that runs an experiment, it wraps the
+ * content in an element marked with the experiment and the variant the server rendered, keeps
+ * it hidden, and prints the script that decides the visitor's variant while the HTML loads.
+ * `dotEvents` then shows the content, or the page is replaced with the assigned variant. On any
+ * other page it renders the content alone.
+ *
+ * It has no hooks, so it also renders in a server component, which keeps the script builder
+ * out of the client bundle.
+ *
+ * @param props - The page asset, an optional nonce and class, and the content
+ * @returns The content, marked and hidden until its variant is decided on an experiment page
+ *
+ * @example
+ * ```tsx
+ * <DotCMSExperiment page={pageAsset}>
+ *     <DotCMSLayoutBody page={pageAsset} components={pageComponents} />
+ * </DotCMSExperiment>
+ * ```
+ */
+const DotCMSExperiment = ({ page, nonce, className, children }) => {
+    const markup$1 = markup.experimentMarkup(page);
+    // A fragment, so the component always returns an element: its type reads plainly, and
+    // JSX accepts it with every @types/react version
+    if (!markup$1) {
+        return jsxRuntime.jsx(jsxRuntime.Fragment, { children: children });
+    }
+    // Browsers hide a nonce from the DOM once they apply it, which hydration reads as a mismatch
+    const nonceProps = nonce ? { nonce, suppressHydrationWarning: true } : {};
+    return (jsxRuntime.jsxs(jsxRuntime.Fragment, { children: [jsxRuntime.jsx("style", { ...nonceProps, children: markup$1.style }), jsxRuntime.jsx("script", { ...nonceProps, dangerouslySetInnerHTML: { __html: markup$1.script } }), jsxRuntime.jsx("div", { className: className, ...markup$1.attributes, children: children })] }));
+};
+
+exports.DotCMSExperiment = DotCMSExperiment;

package/react.cjs.mjs

@@ -0,0 +1,2 @@
+export * from './react.cjs.js';
+export { _default as default } from './react.cjs.default.js';

package/react.d.ts

@@ -0,0 +1 @@
+export * from "./src/react";

package/react.esm.js

@@ -0,0 +1,37 @@
+import { jsx, Fragment, jsxs } from 'react/jsx-runtime';
+import { experimentMarkup } from './markup.esm.js';
+import './decision.esm.js';
+
+/**
+ * Runs the page's experiment on its content. On a page that runs an experiment, it wraps the
+ * content in an element marked with the experiment and the variant the server rendered, keeps
+ * it hidden, and prints the script that decides the visitor's variant while the HTML loads.
+ * `dotEvents` then shows the content, or the page is replaced with the assigned variant. On any
+ * other page it renders the content alone.
+ *
+ * It has no hooks, so it also renders in a server component, which keeps the script builder
+ * out of the client bundle.
+ *
+ * @param props - The page asset, an optional nonce and class, and the content
+ * @returns The content, marked and hidden until its variant is decided on an experiment page
+ *
+ * @example
+ * ```tsx
+ * <DotCMSExperiment page={pageAsset}>
+ *     <DotCMSLayoutBody page={pageAsset} components={pageComponents} />
+ * </DotCMSExperiment>
+ * ```
+ */
+const DotCMSExperiment = ({ page, nonce, className, children }) => {
+    const markup = experimentMarkup(page);
+    // A fragment, so the component always returns an element: its type reads plainly, and
+    // JSX accepts it with every @types/react version
+    if (!markup) {
+        return jsx(Fragment, { children: children });
+    }
+    // Browsers hide a nonce from the DOM once they apply it, which hydration reads as a mismatch
+    const nonceProps = nonce ? { nonce, suppressHydrationWarning: true } : {};
+    return (jsxs(Fragment, { children: [jsx("style", { ...nonceProps, children: markup.style }), jsx("script", { ...nonceProps, dangerouslySetInnerHTML: { __html: markup.script } }), jsx("div", { className: className, ...markup.attributes, children: children })] }));
+};
+
+export { DotCMSExperiment };

package/src/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * `@dotcms/events`: the `dotEvents` object and the types its methods and options use.
+ *
+ * Every page loads this entry, so it holds the SDK and no markup: what a page prints so its
+ * experiment runs comes from `./markup` and `./react`.
+ */
+export { dotEvents } from './lib/events';
+export type { DotCMSEvents, DotCMSEventsConfig, DotCMSEventsError, DotCMSEventsErrorCode, DotCMSEventsExperimentsConfig, DotCMSEventsImpressionsConfig, DotCMSEventsJsonObject, DotCMSEventsJsonValue, DotCMSEventsLogLevel, DotCMSEventsQueueConfig } from './lib/models';

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

@@ -0,0 +1,14 @@
+/**
+ * Event type for content clicks
+ * Must match DotCMSPredefinedEventType.CONTENT_CLICK
+ */
+export declare const CLICK_EVENT_TYPE = "content_click";
+/**
+ * Default debounce time in milliseconds for clicks
+ */
+export declare const DEFAULT_CLICK_THROTTLE_MS = 300;
+/**
+ * CSS selector for clickable elements to track
+ * Only clicks on <a> and <button> elements are tracked
+ */
+export declare const CLICKABLE_ELEMENTS_SELECTOR = "a, button";

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

@@ -0,0 +1,35 @@
+import type { PipelineConfig } from '../pipeline/models';
+import type { AnalyticsInstance } from 'analytics';
+/**
+ * Clicks plugin of the events pipeline.
+ * Handles automatic tracking of clicks on content elements.
+ *
+ * This plugin initializes the click tracker which:
+ * - Listens for clicks once, on the document, in the capture phase
+ * - Reports clicks on <a> or <button> elements inside a contentlet, the innermost one
+ * - Extracts contentlet data, its position when clicked, and element metadata
+ * - Throttles clicks per contentlet to prevent duplicates
+ * - Fires 'content_click' events via subscription callback
+ *
+ * Note: This plugin is only registered if config.clicks is enabled.
+ * See getEnhancedTrackingPlugins() for conditional loading logic.
+ *
+ * @param {PipelineConfig} config - Configuration with clicks settings
+ * @returns {Object} Plugin object with lifecycle methods
+ */
+export declare const clicksPlugin: (config: PipelineConfig) => {
+    name: string;
+    /**
+     * Initialize click 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;
+};

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

@@ -0,0 +1,42 @@
+import type { PipelineConfig, DotCMSContentClickPayload } from '../pipeline/models';
+/** Callback function for click events */
+export type ClickCallback = (eventName: string, payload: DotCMSContentClickPayload) => void;
+/** Subscription object with unsubscribe method */
+export interface ClickSubscription {
+    unsubscribe: () => void;
+}
+/**
+ * Tracks clicks on the links and buttons inside contentlets, through one click listener on the
+ * document, in the capture phase. A click finds its contentlet with `closest`, so:
+ * - nothing scans or observes the page, and a contentlet added at any time counts;
+ * - an app's `stopPropagation()` cannot hide a click from the tracker;
+ * - a click inside nested contentlets counts once, for the innermost;
+ * - clicks on the same contentlet within 300 ms count once.
+ *
+ * @example
+ * ```typescript
+ * const tracker = new DotCMSClickTracker(config);
+ * const subscription = tracker.onClick((eventName, payload) => {
+ *   console.log('Click detected:', payload);
+ * });
+ * tracker.initialize();
+ * // Later: subscription.unsubscribe();
+ * ```
+ */
+export declare class DotCMSClickTracker {
+    #private;
+    constructor(config: PipelineConfig);
+    /**
+     * Subscribe to click events
+     * @param callback - Function called when click is detected
+     * @returns Subscription object with unsubscribe method
+     */
+    onClick(callback: ClickCallback): ClickSubscription;
+    /** Starts listening for clicks; without a document, as on the server, it does nothing */
+    initialize(): void;
+    /**
+     * Stops listening for clicks. Should be called when the plugin is disabled or the page is
+     * discarded.
+     */
+    cleanup(): void;
+}

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

@@ -0,0 +1,13 @@
+import type { DotCMSContentClickPayload } from '../pipeline/models';
+import type { createPluginLogger } from '../pipeline/utils';
+/**
+ * Handles click events on elements within a contentlet.
+ * The tracker passes the contentlet the click landed in: the innermost one around the clicked
+ * link or button.
+ *
+ * @param event - The mouse event
+ * @param contentletElement - The contentlet container element
+ * @param trackCallback - Callback to execute if the click is valid
+ * @param logger - Logger instance for debug messages
+ */
+export declare const handleContentletClick: (event: MouseEvent, contentletElement: HTMLElement, trackCallback: (eventName: string, payload: DotCMSContentClickPayload) => void, logger: ReturnType<typeof createPluginLogger>) => void;

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

@@ -0,0 +1,36 @@
+/**
+ * Default debounce time in milliseconds for MutationObserver
+ */
+export declare const CONTENTLET_OBSERVER_DEBOUNCE_MS = 250;
+/**
+ * CSS class selector for contentlet elements
+ *
+ * @important This constant is intentionally duplicated in @dotcms/react SDK
+ * (core-web/libs/sdk/react/src/lib/next/components/Contentlet/Contentlet.tsx), whose renderers
+ * print the class, and dotCMS prints it on traditional pages too. Both constants MUST have the
+ * same value ('dotcms-contentlet') for content tracking to find React-rendered contentlets.
+ *
+ * This duplication is intentional to keep the SDKs independent:
+ * - @dotcms/events works without React
+ * - @dotcms/react works without events
+ * - When both are used together, they must share the same class name
+ *
+ * If you need to change this value, you MUST update it in both locations:
+ * 1. This file (@dotcms/events)
+ * 2. Contentlet.tsx in @dotcms/react
+ *
+ * @see core-web/libs/sdk/react/src/lib/next/components/Contentlet/Contentlet.tsx
+ */
+export declare const CONTENTLET_CLASS = "dotcms-contentlet";
+/**
+ * Attribute that carries a contentlet's identifier (`dataset['dotIdentifier']`). The page
+ * renderers print it only once analytics is active, after hydration, so it can land after
+ * the contentlet itself.
+ */
+export declare const CONTENTLET_IDENTIFIER_ATTRIBUTE = "data-dot-identifier";
+/**
+ * Window event that asks the content trackers to scan for contentlets again. Sent when
+ * contentlets that were hidden become visible, which changes no DOM node the trackers watch
+ * (an experiment's rows are revealed through a style rule).
+ */
+export declare const CONTENTLET_RESCAN_EVENT = "dotcms:events:rescan";