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

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

@@ -0,0 +1,119 @@
+import { DotLogger } from './logger';
+import type { LogLevel } from './logger';
+import type { AnalyticsBasePayloadWithContext, PipelineConfig, EventContext, DotCMSBrowserData, DotCMSEventDeviceData, DotCMSEventUtmData, EnrichedAnalyticsPayload } from './models';
+export { cleanupActivityTracking, initializeActivityTracking, updateSessionActivity } from './identity/activity';
+/**
+ * Generates a random ID from the current time and Math.random: unique enough for session and
+ * user ids, but not cryptographically secure.
+ * @internal This function is for internal use only and should not be used outside of the SDK.
+ * @param prefix - The prefix for the generated ID
+ * @returns A unique ID string with the given prefix
+ */
+export declare const generateSecureId: (prefix: string) => string;
+/**
+ * Safe sessionStorage wrapper with error handling
+ */
+export declare const safeSessionStorage: {
+    getItem: (key: string) => string | null;
+    setItem: (key: string, value: string) => void;
+    removeItem: (key: string) => void;
+};
+/**
+ * Gets or generates a user ID from localStorage.
+ * @internal This function is for internal use only.
+ * @returns The user ID string
+ */
+export declare const getUserId: () => string;
+/**
+ * Gets session ID with comprehensive lifecycle management.
+ * Returns existing valid session ID or creates a new one if needed.
+ * @internal This function is for internal use only.
+ *
+ * Session validation criteria:
+ * 1. User is still active (< 30 min inactivity)
+ * 2. Session hasn't passed midnight (UTC)
+ *
+ * @returns The session ID string
+ */
+export declare const getSessionId: () => string;
+/**
+ * Gets analytics context with user and session identification.
+ * Used by the identity plugin to inject context into analytics events.
+ *
+ * @param config - The analytics configuration object
+ * @returns The analytics context with site_auth, session_id, user_id and device
+ */
+export declare const getEventContext: (config: PipelineConfig) => EventContext;
+/**
+ * Configuration result with warnings for analytics setup
+ */
+export interface AnalyticsConfigResult {
+    config: PipelineConfig;
+    warnings?: string[];
+    missingAttributes?: string[];
+    hasIssues: boolean;
+}
+/**
+ * Gets current device data for analytics.
+ * Combines static browser data with dynamic viewport information.
+ * Used by the identity plugin to inject device data into context.
+ *
+ * @returns Device data with screen resolution, language, and viewport dimensions
+ */
+export declare const getDeviceDataForContext: () => DotCMSEventDeviceData;
+/**
+ * Retrieves the browser event data - optimized but accurate.
+ * @internal This function is for internal use only.
+ * @param location - The Location object to extract data from
+ * @returns Browser event data with all relevant information
+ */
+export declare const getBrowserEventData: (location: Location) => DotCMSBrowserData;
+/**
+ * Extracts and transforms UTM parameters from the URL - cached for performance.
+ * Returns UTM data in DotCMS format (without 'utm_' prefix).
+ * @internal This function is for internal use only.
+ * @param location - The Location object to extract UTM parameters from
+ * @returns DotCMSEventUtmData object with transformed UTM parameters (source, medium, campaign, etc.)
+ */
+export declare const extractUTMParameters: (location: Location) => DotCMSEventUtmData;
+/**
+ * Gets local time in ISO format without milliseconds.
+ * Used by enricher plugins to add local_time to events.
+ *
+ * @returns Local time string in ISO 8601 format with timezone offset (e.g., "2024-01-01T12:00:00-05:00")
+ */
+export declare const getLocalTime: () => string;
+/**
+ * Optimized payload enrichment using existing analytics.js data.
+ * Filters out Analytics.js default properties and only keeps user-provided properties in custom.
+ * Used by the enricher plugin to transform Analytics.js payload into DotCMS event format.
+ *
+ * @param payload - The Analytics.js payload with context already injected by identity plugin
+ * @param location - The Location object to extract page data from (defaults to window.location)
+ * @returns Enriched payload with page, UTM, custom data, and local_time (device is in context)
+ */
+export declare const enrichPagePayloadOptimized: (payload: AnalyticsBasePayloadWithContext, location?: Location) => EnrichedAnalyticsPayload;
+/**
+ * Checks if code is running in a browser environment
+ * @returns true if window and document are available
+ */
+export declare const isBrowser: () => boolean;
+/**
+ * Runs a callback when the browser discards the page. A page it keeps in the back/forward
+ * cache (`pagehide` with `persisted`) comes back as it was when the visitor returns, with its
+ * listeners and observers, so it is left alone. `beforeunload` is not used: it fires before the
+ * page goes into that cache too.
+ *
+ * @param discarded - Called on the `pagehide` that discards the page
+ */
+export declare const onPageDiscard: (discarded: () => void) => void;
+/**
+ * Creates a logger with plugin-specific prefix and configurable log level
+ * @param pluginName - Name of the plugin (e.g., 'Click', 'Impression')
+ * @param config - Analytics configuration with debug flag and optional logLevel
+ * @returns DotLogger instance with configured log level
+ */
+export declare const createPluginLogger: (pluginName: string, config: {
+    debug: boolean;
+    logLevel?: LogLevel;
+}) => DotLogger;

package/src/lib/react/DotCMSExperiment.d.ts

@@ -0,0 +1,36 @@
+import type { DotCMSEventsExperimentPage } from '../models';
+import type { ReactElement, ReactNode } from 'react';
+export interface DotCMSExperimentProps {
+    /**
+     * The page asset, requested for the variant in the URL's `variantName`. The component reads
+     * the experiment running on it and the variant the server rendered.
+     */
+    page: DotCMSEventsExperimentPage | null | undefined;
+    /** Nonce for the inline style and script, on pages with a nonce-based Content-Security-Policy. */
+    nonce?: string;
+    /** Class for the element that wraps the content. */
+    className?: string;
+    /** What the experiment varies: the page's layout, or content the view renders itself. */
+    children: ReactNode;
+}
+/**
+ * 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>
+ * ```
+ */
+export declare const DotCMSExperiment: ({ page, nonce, className, children }: DotCMSExperimentProps) => ReactElement;

package/src/markup.d.ts

@@ -0,0 +1,7 @@
+/**
+ * `@dotcms/events/markup`: what a page prints so its experiment runs, for any framework that
+ * renders HTML on the server. It has its own entry so the SDK, which every page loads, never
+ * references the boot script builder.
+ */
+export { experimentMarkup } from './lib/experiments/markup';
+export type { DotCMSEventsExperimentMarkup, DotCMSEventsExperimentPage } from './lib/models';

package/src/react.d.ts

@@ -0,0 +1,8 @@
+/**
+ * `@dotcms/events/react`: `DotCMSExperiment`, which prints the markup for React. The only
+ * entry that imports React. It brings the markup and never the SDK, which loads with
+ * `dotEvents.init`.
+ */
+export { DotCMSExperiment } from './lib/react/DotCMSExperiment';
+export type { DotCMSExperimentProps } from './lib/react/DotCMSExperiment';
+export type { DotCMSEventsExperimentPage } from './lib/models';