@dotcms/experiments 0.0.1-alpha.37 → 0.0.1-alpha.39

package/src/lib/components/withExperiments.d.ts

@@ -1,20 +0,0 @@
-import React, { ReactNode } from 'react';
-import { DotcmsPageProps } from '@dotcms/react';
-import { DotExperimentConfig } from '../shared/models';
-export interface PageProviderProps {
-    readonly entity: any;
-    readonly children: ReactNode;
-}
-/**
- * Wraps a given component with experiment handling capabilities using the 'useExperimentVariant' hook.
- * This HOC checks if the entity's assigned experiment variant differs from the currently displayed variant.
- * If they differ, the content is hidden until the correct variant is displayed. Once the assigned variant
- * matches the displayed variant, the content of the WrappedComponent is shown.
- *
- * @param {React.ComponentType<DotcmsPageProps>} WrappedComponent - The component to be enhanced.
- * @param {DotExperimentConfig} config - Configuration for experiment handling, including any necessary
- *        redirection functions or other settings.
- * @returns {React.FunctionComponent<DotcmsPageProps>} A component that wraps the original component,
- *          adding experiment handling based on the specified configuration.
- */
-export declare const withExperiments: (WrappedComponent: React.ComponentType<DotcmsPageProps>, config: DotExperimentConfig) => (props: DotcmsPageProps) => import("react/jsx-runtime").JSX.Element;

package/src/lib/dot-experiments.d.ts

@@ -1,289 +0,0 @@
-import { DotExperimentConfig, Experiment, Variant } from './shared/models';
-/**
- * `DotExperiments` is a Typescript class to handles all operations related to fetching, storing, parsing, and navigating
- * data for Experiments (A/B Testing).
- *
- * It requires a configuration object for instantiation, please instance it using the method `getInstance` sending
- * an object with `api-key`, `server` and `debug`.
- *
- * Here's an example of how you can instantiate DotExperiments class:
- * @example
- * ```typescript
- * const instance = DotExperiments.getInstance({
- *   server: "yourServerUrl",
- *   "api-key": "yourApiKey"
- * });
- * ```
- *
- * @export
- * @class DotExperiments
- *
- */
-export declare class DotExperiments {
-    private readonly config;
-    /**
-     * The instance of the DotExperiments class.
-     * @private
-     */
-    private static instance;
-    /**
-     * Represents the default configuration for the DotExperiment library.
-     * @property {boolean} trackPageView - Specifies whether to track page view or not. Default value is true.
-     */
-    private static readonly defaultConfig;
-    /**
-     * Represents the promise for the initialization process.
-     * @private
-     */
-    private initializationPromise;
-    /**
-     * Represents the analytics client for Analytics.
-     * @private
-     */
-    private analytics;
-    /**
-     * Class representing a database handler for IndexDB.
-     * @class
-     */
-    private persistenceHandler;
-    /**
-     * Represents the stored data in the IndexedDB.
-     * @private
-     */
-    private experimentsAssigned;
-    /**
-     * A logger utility for logging messages.
-     *
-     * @class
-     */
-    private logger;
-    /**
-     * Represents the current location.
-     * @private
-     */
-    private currentLocation;
-    /**
-     * Represents the previous location.
-     *
-     * @type {string}
-     */
-    private prevLocation;
-    private constructor();
-    /**
-     * Retrieves the array of experiments assigned to an instance of the class.
-     *
-     * @return {Experiment[]} An array containing the experiments assigned to the instance.
-     */
-    get experiments(): Experiment[];
-    /**
-     * Returns a custom redirect function. If a custom redirect function is not configured,
-     * the default redirect function will be used.
-     *
-     * @return {function} A function that accepts a URL string parameter and performs a redirect.
-     *                    If no parameter is provided, the function will not perform any action.
-     */
-    get customRedirectFn(): (url: string) => void;
-    /**
-     * Retrieves the current location.
-     *
-     * @returns {Location} The current location.
-     */
-    get location(): Location;
-    /**
-     * Retrieves instance of DotExperiments class if it doesn't exist create a new one.
-     * If the instance does not exist, it creates a new instance with the provided configuration and calls the `getExperimentData` method.
-     *
-     * @param {DotExperimentConfig} config - The configuration object for initializing the DotExperiments instance.
-     * @return {DotExperiments} - The instance of the DotExperiments class.
-     */
-    static getInstance(config?: DotExperimentConfig): DotExperiments;
-    /**
-     * Waits for the initialization process to be completed.
-     *
-     * @return {Promise<void>} A Promise that resolves when the initialization is ready.
-     */
-    ready(): Promise<void>;
-    /**
-     * This method appends variant parameters to navigation links based on the provided navClass.
-     *
-     * Note: In order for this method's functionality to apply, you need to define a class for the navigation elements (anchors)
-     * to which you would like this functionality applied and pass it as an argument when calling this method.
-     *
-     * @param {string} navClass - The class of the navigation elements to which variant parameters should be appended. Such elements should be anchors (`<a>`).
-     *
-     * @example
-     * <ul class="navbar-nav me-auto mb-2 mb-md-0">
-     *     <li class="nav-item">
-     *         <a class="nav-link " aria-current="page" href="/">Home</a>
-     *      </li>
-     *      <li class="nav-item ">
-     *         <a class="nav-link active" href="/blog">Travel Blog</a>
-     *      </li>
-     *      <li class="nav-item">
-     *         <a class="nav-link" href="/destinations">Destinations</a>
-     *      </li>
-     * </ul>
-     *
-     * dotExperiment.ready().then(() => {
-     *    dotExperiment.appendVariantParams('.navbar-nav .nav-link');
-     * });
-     * appendVariantParams('nav-item-class');
-     *
-     * @returns {void}
-     */
-    appendVariantParams(navClass: string): void;
-    /**
-     * Retrieves the current debug status.
-     *
-     * @private
-     * @returns {boolean} - The debug status.
-     */
-    getIsDebugActive(): boolean;
-    /**
-     * Updates the current location and checks if a variant should be applied.
-     * Redirects to the variant URL if necessary.
-     *
-     * @param {Location} location - The new location.
-     * @param redirectFunction
-     */
-    locationChanged(location: Location, redirectFunction?: (url: string) => void): Promise<void>;
-    /**
-     * Tracks a page view event in the analytics system.
-     *
-     * @return {void}
-     */
-    trackPageView(): void;
-    /**
-     * This method is used to retrieve the variant associated with a given URL.
-     *
-     * It checks if the URL is part of an experiment by verifying it against an experiment's regex. If the URL matches the regex of an experiment,
-     * it returns the variant attached to that experiment; otherwise, it returns null.
-     *
-     * @param {string | null} path - The URL to check for a variant. This should be the path of the URL.
-     *
-     * @returns {Variant | null} The variant associated with the URL if it exists, null otherwise.
-     */
-    getVariantFromHref(path: string | null): Variant | null;
-    /**
-     * Returns the experiment variant name as a URL search parameter.
-     *
-     * @param {string|null} path - The path to the current page.
-     * @returns {URLSearchParams} - The URL search parameters containing the experiment variant name.
-     */
-    getVariantAsQueryParam(path: string | null): URLSearchParams;
-    /**
-     * Determines whether a page view should be tracked.
-     *
-     * @private
-     * @returns {boolean} True if a page view should be tracked, otherwise false.
-     */
-    private shouldTrackPageView;
-    /**
-     * Tracks an event using the analytics service.
-     *
-     * @param {string} typeName - The type of event to track.
-     * @param {EventPayload} [payload] - Optional payload associated with the event.
-     * @return {void}
-     */
-    private track;
-    /**
-     * Initializes the application using lazy initialization. This method performs
-     * necessary setup steps and should be invoked to ensure proper execution of the application.
-     *
-     * Note: This method uses lazy initialization. Make sure to call this method to ensure
-     * the application works correctly.
-     *
-     * @return {Promise<void>} A promise that resolves when the initialization is complete.
-     */
-    private initialize;
-    /**
-     * Fetches experiments from the server.
-     *
-     * @private
-     * @returns {Promise<AssignedExperiments>} - The entity object returned from the server.
-     * @throws {Error} - If an HTTP error occurs or an error occurs during the fetch request.
-     */
-    private getExperimentsFromServer;
-    /**
-     * This method is responsible for retrieving and persisting experiment data from the server to the local indexDB database.
-     *
-     * - Checks whether making a request to the server to fetch experiment data is required.
-     * - Sends the request to the server for data if required.
-     * - Parses the fetched data to the form required for storage in the database.
-     * - Persists the data in the indexDB database.
-     *
-     * @private
-     * @method verifyExperimentData
-     * @async
-     * @throws {Error} Throws an error with details if there is any failure in loading the experiments or during their persistence in indexDB.
-     *
-     * @returns {Promise<void>} An empty promise that fulfills once the experiment data has been successfully loaded and persisted.
-     */
-    private verifyExperimentData;
-    /**
-     * Persists the parsed experiment data into the indexDB database.
-     *
-     * The method does the following:
-     * - Receives the parsed data.
-     * - Updates the creation date.
-     * - Clears existing data from the indexDB database.
-     * - Stores the new data in the indexDB database.
-     *
-     * If there are no experiments in the received data, the method will not attempt to clear or persist anything and will return immediately.
-     *.
-     *
-     * @note This method utilizes Promises for the asynchronous handling of data persistence. Errors during data persistence are caught and logged, but not re-thrown.
-     *
-     * @private
-     * @method persistExperiments
-     * @throws Nothing – Errors are caught and logged, but not re-thrown.
-     *
-     * @param experiments
-     */
-    private persistExperiments;
-    /**
-     * Initializes the database handler.
-     *
-     * This private method instantiates the class handling the IndexDB database
-     * and assigns this instance to 'persistenceHandler'.
-     *
-     * @private
-     */
-    private initializeDatabaseHandler;
-    /**
-     * Initializes the Jitsu analytics client.
-     *
-     * This private method sets up the Jitsu client responsible for sending events
-     * to the server with the provided configuration. It also uses the parsed data
-     * and registers it as global within Jitsu.
-     *
-     * @private
-     */
-    private initAnalyticsClient;
-    /**
-     * Updates the analytics client's data using the experiments data
-     * currently available in the IndexDB database, based on the current location.
-     *
-     * Retrieves and processes the experiments information according to the
-     * current location into a suitable format for `analytics.set()`.
-     *
-     * @private
-     * @method refreshAnalyticsForCurrentLocation
-     * @returns {void}
-     */
-    private refreshAnalyticsForCurrentLocation;
-    /**
-     * Determines whether analytics should be checked.
-     *
-     * @private
-     * @returns {Promise<boolean>} A boolean value indicating whether analytics should be checked.
-     */
-    private shouldFetchNewData;
-    /**
-     * Retrieves persisted data from the database.
-     *
-     * @private
-     * @returns {Promise<void>} A promise that resolves with no value.
-     */
-    private getPersistedData;
-}

package/src/lib/hooks/useExperimentVariant.d.ts

@@ -1,21 +0,0 @@
-/**
- * A React Hook that determines whether to wait for the correct variant in an A/B testing scenario.
- * This is used to avoid flickering - showing the original content before redirecting to the assigned variant.
- *
- * The hook uses the running experiment id and viewAs (containing variantId) from the provided data.
- * It then works with the DotExperimentsContext to synchronize between the assigned variant and the one requested.
- * If the hook is executed inside an editor or if no running experiment id is provided, it immediately signals not to wait for the variant.
- * Similarly, if the assigned variant matches the requested one, it signals not to wait for the variant.
- * By default, the hook signals to wait for the variant.
- *
- * @param {Object} data - An object containing the runningExperimentId and viewAs (containing variantId).
- * @returns {Object} An object with a function `shouldWaitForVariant` that, when called, returns `true` if it should wait for the correct variant, `false` otherwise.
- */
-export declare const useExperimentVariant: (data: {
-    runningExperimentId?: string;
-    viewAs: {
-        variantId: string;
-    };
-}) => {
-    shouldWaitForVariant: boolean;
-};

package/src/lib/hooks/useExperiments.d.ts

@@ -1,14 +0,0 @@
-import { DotExperiments } from '../dot-experiments';
-/**
- * Custom hook `useExperiments`.
- *
- * This hook is designed to handle changes in the location of the current DotExperiments
- * instance and set a global click handler that redirects the application when an element with an
- * assigned variant is clicked.
- *
- * It also manages adding or removing the experimentation query parameter from the URL as
- * appropriate when a click occurs.
- *
- * @returns {void}
- */
-export declare const useExperiments: (instance: DotExperiments | null) => void;

package/src/lib/shared/mocks/mock.d.ts

@@ -1,43 +0,0 @@
-import { Experiment, ExperimentEvent, IsUserIncludedApiResponse } from '../models';
-/**
- * Represents the response object for the IsUserIncluded API.
- * @typedef {Object} IsUserIncludedResponse
- * @property {IsUserIncludedApiResponse} entity - The response entity.
- * @property {string[]} errors - Array of error messages, if any.
- * @property {Object} i18nMessagesMap - Map of internationalization messages.
- * @property {string[]} messages - Array of additional messages, if any.
- */
-export declare const IsUserIncludedResponse: IsUserIncludedApiResponse;
-export declare const NewIsUserIncludedResponse: IsUserIncludedApiResponse;
-export declare const After15DaysIsUserIncludedResponse: IsUserIncludedApiResponse;
-export declare const NoExperimentsIsUserIncludedResponse: IsUserIncludedApiResponse;
-export declare const MOCK_CURRENT_TIMESTAMP = 1704096000000;
-export declare const TIME_15_DAYS_MILLISECONDS: number;
-export declare const TIME_5_DAYS_MILLISECONDS: number;
-export declare const MockDataStoredIndexDB: Experiment[];
-export declare const MockDataStoredIndexDBNew: Experiment[];
-export declare const MockDataStoredIndexDBWithNew: Experiment[];
-export declare const MockDataStoredIndexDBWithNew15DaysLater: Experiment[];
-/**
- * Represents an event that indicates the expected experiments parsed from a response to send to Analytics.
- *
- * @typedef {Object} ExpectedExperimentsParsedEvent
- * @property {ExperimentEvent[]} experiments - An array of experiment events.
- */
-export declare const ExpectedExperimentsParsedEvent: ExperimentEvent[];
-/**
- * Represents a mock location object.
- *
- * @typedef {Object} LocationMock
- * @property {string} href - The complete URL.
- *
- */
-export declare const LocationMock: Location;
-export declare const sessionStorageMock: {
-    getItem: (key: string) => string | null;
-    setItem: (key: string, value: string) => void;
-    removeItem: (key: string) => void;
-    clear: () => void;
-    key: (index: number) => string | null;
-    readonly length: number;
-};

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

@@ -1,54 +0,0 @@
-import { Experiment, ExperimentParsed, FetchExperiments } 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: FetchExperiments, 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

@@ -1,87 +0,0 @@
-/**
- * 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

@@ -1,15 +0,0 @@
-/**
- * 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/memoize.d.ts

@@ -1,7 +0,0 @@
-/**
- * Memoizes an object and returns the memoized object.
- * Mantaing the same reference if the object is the same independently if is called inside any component.
- * @param object
- * @returns
- */
-export declare function useMemoizedObject<T extends object>(object: T): T;

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

@@ -1,73 +0,0 @@
-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

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