@dotcms/experiments 0.0.1-alpha

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

@@ -0,0 +1,201 @@
+/**
+ * Represents the configuration for the SDK experiment.
+ *
+ * @interface DotExperimentConfig
+ */
+export interface DotExperimentConfig {
+    /**
+     * This is `Analytics Key` provided by Analytics Integration App at DotCMS.
+     */
+    apiKey: string;
+    /**
+     * The URL of the Public DotCMS Host server for the SDK to connect to.
+     */
+    server: string;
+    /**
+     * A flag that determines whether the experiment is in debug mode or not. When in debug mode, the SDK could provide more logging information.
+     */
+    debug: boolean;
+    /**
+     * An optional property. True by default to automatically track page views. It's useful for understanding user behavior in the experiment.
+     */
+    trackPageView?: boolean;
+    /**
+     * An optional property. It is a function that handles URL redirections. When supplied, the SDK will call this function instead of using the default browser redirect when it's necessary to redirect the page.
+     * @param url
+     */
+    redirectFn?: (url: string) => void;
+}
+/**
+ * Represents the configuration for the LookBackWindow.
+ *
+ * @interface LookBackWindow
+ */
+export interface LookBackWindow {
+    /**
+     * Defines the time period in milliseconds when the LookBackWindow should expire.
+     */
+    expireMillis: number;
+    /**
+     * A value indicating the expiration timestamp of the experiment.
+     */
+    expireTime?: number;
+    /**
+     * Represents the associated value with the LookBackWindow.
+     */
+    value: string;
+}
+/**
+ * Represents the configurations for checking whether the current page is an Experiment page, or a target.
+ *
+ * @interface Regexs
+ */
+interface Regexs {
+    /**
+     * A regular expression for validating if the page is an Experiment page.
+     */
+    isExperimentPage: string;
+    /**
+     * A regular expression for validating if the page is the target page. This can be null.
+     */
+    isTargetPage: string | null;
+}
+/**
+ * Represents a variant that is applied when a request is made.
+ *
+ * @interface Variant
+ */
+export interface Variant {
+    /**
+     * The name of the variant.
+     */
+    name: string;
+    /**
+     * The fully qualified URL where the variant is being applied, with query parameters already set.
+     */
+    url: string;
+}
+/**
+ * Represents an experiment with all its configurations.
+ *
+ * @interface Experiment
+ */
+export interface Experiment {
+    /**
+     * The unique identifier for the experiment.
+     */
+    id: string;
+    /**
+     * The lookback window object for the experiment.
+     */
+    lookBackWindow: LookBackWindow;
+    /**
+     * The name of the experiment.
+     */
+    name: string;
+    /**
+     * The URL of the page where the experiment is applied.
+     */
+    pageUrl: string;
+    /**
+     * The object containing regular expressions for validating pages.
+     */
+    regexs: Regexs;
+    /**
+     * The unique running identifier for the experiment.
+     */
+    runningId: string;
+    /**
+     * The variant applied to the user making the request.
+     */
+    variant: Variant;
+}
+/**
+ * Represents the experiments assigned and their details.
+ *
+ * @interface AssignedExperiments
+ */
+export interface AssignedExperiments {
+    /**
+     * The ids of the experiments that are excluded in the assignment.
+     */
+    excludedExperimentIds: string[];
+    /**
+     * An array representing the assigned experiments.
+     */
+    experiments: Experiment[];
+    /**
+     * The ids of the experiments included in the assignment.
+     */
+    includedExperimentIds: string[];
+}
+/**
+ * Represents the response from backend holding information about running experiments and variant assignment.
+ *
+ * @interface IsUserIncludedApiResponse
+ */
+export interface IsUserIncludedApiResponse {
+    /**
+     * The object holding all experiment-related information.
+     */
+    entity: AssignedExperiments;
+    /**
+     * An array holding possible error messages.
+     */
+    errors: string[];
+    /**
+     * A map that holds internationalization (i18n) messages.
+     */
+    i18nMessagesMap: Record<string, string>;
+    /**
+     * An array of generic messages.
+     */
+    messages: string[];
+}
+/**
+ * Represents a single experiment event.
+ *
+ * @interface ExperimentEvent
+ */
+export interface ExperimentEvent {
+    /**
+     * The name or identifier of the experiment.
+     */
+    experiment: string;
+    /**
+     * The unique running identifier of the experiment.
+     */
+    runningId: string;
+    /**
+     * A flag that determines if the current page is the one where the experiment is conducted.
+     */
+    isExperimentPage: boolean;
+    /**
+     * A flag that determines if the current page is the target page of the experiment.
+     */
+    isTargetPage: boolean;
+    /**
+     * Represents the time period for which the experiment is valid or should be considered.
+     */
+    lookBackWindow: string;
+    /**
+     * Represents the variant of the experiment to specify different versions of an experiment.
+     */
+    variant: string;
+}
+/**
+ * Represents parsed data of an experiment that is ready to be sent to Analytics.
+ *
+ * @interface ExperimentParsed
+ */
+export interface ExperimentParsed {
+    /**
+     * The URL of the experiment. It helps track the location or origin of the experiment.
+     */
+    href: string;
+    /**
+     * An array holding details of individual experiments being conducted.
+     */
+    experiments: ExperimentEvent[];
+}
+export {};

package/src/lib/shared/parser/parser.d.ts

@@ -0,0 +1,54 @@
+import { Experiment, ExperimentParsed } from '../models';
+/**
+ * This arrow function parses a given set of assigned experiments for analytics.
+ *
+ * This process involves iterating over the experiments, which are currently in the "Running" state as received from the DotCMS endpoint,
+ * analyzing each experiment's relevant data such as running ID, variant name, and look back window value.
+ * It also performs regular expression verification for both 'isExperimentPage' and 'isTargetPage' against the current URL.
+ *
+ * The parsed data is useful for tracking and understanding the user's interaction with the experiment-targeted components during their visit.
+ *
+ * Contains an object with experiments information.
+ *
+ * @param experiments
+ * @param {Location} location - This parameter is the object representing the current location (URL) of the user.
+ * Mostly employed for matching the regular expressions to detect whether the current page is an 'ExperimentPage' or a 'TargetPage'.
+ *
+ * @returns {ExperimentParsed} - The function returns an object with the original URL and an array of each experiment's comprehensive detail.
+ * The return object is suitable for further analytical operations. Each experiment's detail includes the experiment ID, running ID, variant name,
+ * look back window value, and booleans that represent whether current URL is 'isExperimentPage' or 'isTargetPage' for the respective experiment.
+ */
+export declare const parseDataForAnalytics: (experiments: Experiment[], location: Location) => ExperimentParsed;
+/**
+ * This utility function performs regular expression (regex) matching on a supplied URL.
+ *
+ * @param {string | null} regexToCheck - The regular expression to match against the URL.
+ * @param {string} href - This is the target URL, which is aimed to be matched against the provided regular expression.
+ * @returns {boolean} -The function returns a Boolean value.
+ */
+export declare const verifyRegex: (regexToCheck: string | null, href: string) => boolean;
+/**
+ * This function merges newly fetched data with the data stored from IndexedDB, preparing it for re-storage in IndexedDB.
+ *
+ * @param { AssignedExperiments | null } fetchExperiments - The experiment data fetched from the API.
+ * @param { AssignedExperiments | null } storedExperiments - The experiment data currently stored in IndexedDB.
+ *
+ * @returns { AssignedExperiments } - The parsed experiment data ready for storing.
+ *
+ * Following cases are handled -
+ * 1) When new Data is received without Old data. This is assumed to be the first time data is received.
+ * 2) When only old data is received, implying that the timestamp hasn't expired and the data is available in IndexedDB.
+ *    The data is verified and any expired experiment is removed before being assigned to dataToStorage.
+ * 3) When both old data and new data is present. This implies that the record existed in IndexedDB but was fetched because the flag had expired.
+ *    Additional operations are performed to add expiry time to experiments, merging all experiments, and storing them.
+ *
+ * There could be scenarios where none of these conditions are met, in that case, dataToStorage will be the default empty object.
+ */
+export declare const parseData: (fetchExperiments: Experiment[] | undefined, storedExperiments: Experiment[] | undefined) => Experiment[];
+/**
+ * Retrieves the array of experiment IDs from the given AssignedExperiments..
+ *
+ * @returns {string[]} Returns an array of experiment IDs if available, otherwise an empty array.
+ * @param experiments
+ */
+export declare const getExperimentsIds: (experiments: Experiment[]) => string[];

package/src/lib/shared/persistence/index-db-database-handler.d.ts

@@ -0,0 +1,87 @@
+/**
+ * Represents the configuration for a database connection.
+ * @interface
+ */
+interface DbConfig {
+    db_name: string;
+    db_store: string;
+    db_key_path: string;
+}
+/**
+ * The `DatabaseHandler` class offers specific methods to store and get data
+ * from IndexedDB.
+ *
+ * @example
+ * // To fetch data from the IndexedDB
+ * const data = await DatabaseHandler.getData();
+ *
+ * @example
+ * // To store an object of type AssignedExperiments to IndexedDB
+ * await DatabaseHandler.persistData(anAssignedExperiment);
+ *
+ * @example
+ * // To get an object of type AssignedExperiments to IndexedDB
+ * await DatabaseHandler.persistData(anAssignedExperiment);
+ *
+ */
+export declare class IndexDBDatabaseHandler {
+    private config;
+    constructor(config: DbConfig);
+    /**
+     * Saves the provided data to indexDB.
+     *
+     * @async
+     * @param {AssignedExperiments} data - The data to be saved.
+     * @returns {Promise<any>} - The result of the save operation.
+     */
+    persistData<T>(data: T): Promise<IDBValidKey>;
+    /**
+     * Retrieves data from the database using a specific key.
+     *
+     * @async
+     * @returns {Promise<any>} A promise that resolves with the data retrieved from the database.
+     */
+    getData<T>(): Promise<T>;
+    /**
+     * Deletes all the data from the IndexedDB store.
+     *
+     * @async
+     * @returns {Promise<void>} - The result of the delete operation.
+     */
+    clearData(): Promise<void>;
+    /**
+     * Sets the flag indicating that the experiment has already been checked.
+     *
+     * @function setFlagExperimentAlreadyChecked
+     * @returns {void}
+     */
+    setFlagExperimentAlreadyChecked(): void;
+    /**
+     * Sets the fetch expired time in the local storage.
+     *
+     * @return {void}
+     */
+    setFetchExpiredTime(): void;
+    /**
+     * Builds an error message based on the provided error object.
+     * @param {DOMException | null} error - The error object to build the message from.
+     * @returns {string} The constructed error message.
+     */
+    private getOnErrorMessage;
+    /**
+     * Creates or opens a IndexedDB database with the specified version.
+     *
+     *
+     * @returns {Promise<IDBDatabase>} A promise that resolves to the opened database.
+     * The promise will be rejected with an error message if there was a database error.
+     */
+    private openDB;
+    /**
+     * Retrieves the result of a database request from an Event object.
+     *
+     * @param {Event} event - The Event object containing the database request.
+     * @returns {IDBDatabase} - The result of the database request, casted as an IDBDatabase object.
+     */
+    private getRequestResult;
+}
+export {};

package/src/lib/shared/utils/DotLogger.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Logger for the dotCMS SDK
+ */
+export declare class DotLogger {
+    private readonly isDebug;
+    private readonly packageName;
+    constructor(isDebug: boolean, packageName: string);
+    group(label: string): void;
+    groupEnd(): void;
+    time(label: string): void;
+    timeEnd(label: string): void;
+    log(message: string): void;
+    warn(message: string): void;
+    error(message: string): void;
+}

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

@@ -0,0 +1,73 @@
+import { DotExperimentConfig, Experiment, Variant } from '../models';
+/**
+ * Returns the first script element that includes the experiment script identifier.
+ *
+ * @return {HTMLScriptElement|undefined} - The found script element or undefined if none is found.
+ */
+export declare const getExperimentScriptTag: () => HTMLScriptElement;
+/**
+ * Retrieves experiment attributes from a given script element.
+ *
+ *
+ * @return {DotExperimentConfig | null} - The experiment attributes or null if there are no valid attributes present.
+ */
+export declare const getDataExperimentAttributes: (location: Location) => DotExperimentConfig | null;
+/**
+ * Retrieves the data attributes from the experiment script tag.
+ *
+ * @example
+ * Given the custom script tag in your HTML:
+ * <script src="/dot-experiments.iife.js"
+ *        defer=""
+ *        data-experiment-api-key="api-token"
+ *        data-experiment-server="http://localhost:8080/"
+ *        data-experiment-debug>
+ * </script>
+ *
+ * @returns {DotExperimentConfig | null} The data attributes of the experiment script tag, or null if no experiment script is found.
+ */
+export declare const getScriptDataAttributes: (location: Location) => DotExperimentConfig | null;
+/**
+ * Checks the flag indicating whether the experiment has already been checked.
+ *
+ * @function checkFlagExperimentAlreadyChecked
+ * @returns {boolean} - returns true if experiment has already been checked, otherwise false.
+ */
+export declare const checkFlagExperimentAlreadyChecked: () => boolean;
+/**
+ * Checks if the data needs to be invalidated based on the creation date.
+ *
+ * @returns {boolean} - True if the data needs to be invalidated, false otherwise.
+ */
+export declare const isDataCreateValid: () => boolean;
+/**
+ * Ad to an absolute path the baseUrl depending on the location.
+ *
+ * @param {string | null} absolutePath - The absolute path of the URL.
+ * @param {Location} location - The location object representing the current URL.
+ * @returns {string | null} - The full URL or null if absolutePath is null.
+ */
+export declare const getFullUrl: (location: Location, absolutePath: string | null) => string | null;
+/**
+ * Updates the URL with the queryParam with the experiment variant name.
+ *
+ * @param {Location|string} location - The current location object or the URL string.
+ * @param {Variant} variant - The experiment variant to update the URL with.
+ * @returns {string} The updated URL string.
+ */
+export declare const updateUrlWithExperimentVariant: (location: Location | string, variant: Variant | null) => string;
+/**
+ * Check if two arrays of Experiment objects are equal.
+ *
+ * @param {Experiment[]} obj1 - The first array of Experiment objects.
+ * @param {Experiment[]} obj2 - The second array of Experiment objects.
+ * @return {boolean} - True if the arrays are equal, false otherwise.
+ */
+export declare const objectsAreEqual: (obj1: Experiment[], obj2: Experiment[]) => boolean;
+/**
+ * A function to redirect the user to a new URL.
+ *
+ * @param {string} href - The URL to redirect to.
+ * @returns {void}
+ */
+export declare const defaultRedirectFn: (href: string) => string;

package/src/lib/standalone.d.ts

@@ -0,0 +1,7 @@
+import { DotExperiments } from './dot-experiments';
+import { EXPERIMENT_WINDOWS_KEY } from './shared/constants';
+declare global {
+    interface Window {
+        [EXPERIMENT_WINDOWS_KEY]: DotExperiments;
+    }
+}