@dotcms/experiments 0.0.1-alpha

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@dotcms/experiments",
+  "version": "0.0.1-alpha",
+  "description": "Official JavaScript library to use Experiments with DotCMS.",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/dotCMS/core.git#master"
+  },
+  "keywords": [
+    "dotCMS",
+    "CMS",
+    "Content Management",
+    "A/B testing",
+    "Experiments"
+  ],
+  "author": "dotcms <dev@dotcms.com>",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/dotCMS/core/issues"
+  },
+  "homepage": "https://github.com/dotCMS/core/tree/master/core-web/libs/sdk/experiments/README.md",
+  "dependencies": {
+    "@jitsu/sdk-js": "^3.1.5"
+  },
+  "peerDependencies": {
+    "react": ">=18",
+    "react-dom": ">=18",
+    "@dotcms/client": "0.0.1-alpha.12"
+  },
+  "module": "./index.esm.js",
+  "type": "module",
+  "main": "./index.esm.js"
+}

package/src/index.d.ts

@@ -0,0 +1,3 @@
+export * from './lib/hooks/useExperiments';
+export * from './lib/components/DotExperimentsProvider';
+export * from './lib/contexts/DotExperimentsContext';

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

@@ -0,0 +1,47 @@
+import { ReactElement, ReactNode } from 'react';
+import { DotExperimentConfig } from '../shared/models';
+interface DotExperimentsProviderProps {
+    children?: ReactNode;
+    config: DotExperimentConfig;
+}
+/**
+ * `DotExperimentsProvider` is a component that uses React's Context API to provide
+ * an instance of `DotExperiments` to all of its descendants.
+ *
+ *
+ * @component
+ * @example
+ * ```jsx
+ *
+ * // Your application component
+ * function App() {
+ *
+ * // Configuration options could be taken from environment variables or can send you own.
+ *  const experimentConfig = {
+ *     apiKey: process.env.NEXT_PUBLIC_EXPERIMENTS_API_KEY ,
+ *     server: process.env.NEXT_PUBLIC_DOTCMS_HOST ,
+ *     debug: process.env.NEXT_PUBLIC_EXPERIMENTS_DEBUG,
+ *     redirectFn: YourRedirectFunction
+ *   };
+ *
+ *   return (
+ *     <DotExperimentsProvider config={experimentConfig}>
+ *       <Header>
+ *           <Navigation items={nav} />
+ *         </Header>
+ *       <DotcmsLayout  entity={{...}} config={{...}} />
+ *     </DotExperimentsProvider>
+ *   );
+ * }
+ * ```
+ *
+ * @param {object} props - The properties that define the `DotExperimentsProvider`.
+ * @param {ReactNode} props.children - The descendants of this provider, which will
+ *   have access to the provided `DotExperiments` instance.
+ * @param {DotExperimentConfig} props.config - The configuration object for `DotExperiments`.
+ *
+ * @returns {ReactElement} The provider component, which should wrap the components
+ * that need access to the `DotExperiments` instance.
+ */
+export declare const DotExperimentsProvider: ({ children, config }: DotExperimentsProviderProps) => ReactElement;
+export {};

package/src/lib/contexts/DotExperimentsContext.d.ts

@@ -0,0 +1,12 @@
+import { DotExperiments } from '../dot-experiments';
+/**
+ * `DotExperimentsContext` is a React context that is designed to provide an instance of
+ * `DotExperiments` to all of the components within its tree that are Consumers of this context.
+ *
+ * The context is created with a default value of `null`. It is meant to be provided a real value
+ * using the `DotExperimentsProvider` component.
+ *
+ * @see {@link https://reactjs.org/docs/context.html|React Context}
+ */
+declare const DotExperimentsContext: import("react").Context<DotExperiments | null>;
+export default DotExperimentsContext;

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

@@ -0,0 +1,289 @@
+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/useExperiments.d.ts

@@ -0,0 +1,14 @@
+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/constants.d.ts

@@ -0,0 +1,95 @@
+/**
+ * The key for identifying the Window key for SdkExperiment.
+ *
+ * @constant {string}
+ */
+export declare const EXPERIMENT_WINDOWS_KEY = "dotExperiment";
+/**
+ * The default variant name for an experiment.
+ *
+ * @type {string}
+ * @constant
+ */
+export declare const EXPERIMENT_DEFAULT_VARIANT_NAME = "DEFAULT";
+/**
+ * The key used to store or retrieve the information in the SessionStore
+ *
+ * @constant {string}
+ */
+export declare const EXPERIMENT_QUERY_PARAM_KEY = "variantName";
+/**
+ * The key used to store or retrieve the information in the SessionStore
+ * indicating whether an experiment has already been checked.
+ *
+ * @constant {string}
+ */
+export declare const EXPERIMENT_ALREADY_CHECKED_KEY = "experimentAlreadyCheck";
+/**
+ * EXPERIMENT_FETCH_EXPIRE_TIME is a constant that represents the name of the variable used to store
+ * the expire time for experiment fetching. It is a string value 'experimentFetchExpireTime'.
+ *
+ * @constant {string}
+ */
+export declare const EXPERIMENT_FETCH_EXPIRE_TIME_KEY = "experimentFetchExpireTime";
+/**
+ * The duration in milliseconds for which data should be stored in the local storage.
+ *
+ * @type {number}
+ * @constant
+ * @default 86400000 (A day)
+ *
+ */
+export declare const LOCAL_STORAGE_TIME_DURATION_MILLISECONDS: number;
+/**
+ * The name of the experiment script file.
+ *
+ * @constant {string}
+ */
+export declare const EXPERIMENT_SCRIPT_FILE_NAME = "dot-experiments.min.iife.js";
+/**
+ * The prefix used for the experiment script data attributes.
+ *
+ * @constant {string}
+ */
+export declare const EXPERIMENT_SCRIPT_DATA_PREFIX = "data-experiment-";
+/**
+ * Array containing the allowed data attributes for an experiment.
+ *
+ * @type {Array.<string>}
+ * @constant
+ */
+export declare const EXPERIMENT_ALLOWED_DATA_ATTRIBUTES: string[];
+/**
+ * API_EXPERIMENTS_URL
+ *
+ * The URL of the endpoint to check if a user is included in experiments.
+ *
+ * @type {string}
+ * @constant
+ */
+export declare const API_EXPERIMENTS_URL = "api/v1/experiments/isUserIncluded";
+/**
+ * The name of the experiment database store in indexDB.
+ *
+ * @type {string}
+ * @constant
+ */
+export declare const EXPERIMENT_DB_STORE_NAME = "dotExperimentStore";
+/**
+ * The path to the key in the database IndexDB representing the running experiment data.
+ * @type {string}
+ */
+export declare const EXPERIMENT_DB_KEY_PATH = "running_experiment";
+/**
+ * Enumeration of debug levels.
+ *
+ * @enum {string}
+ * @readonly
+ */
+export declare enum DEBUG_LEVELS {
+    NONE = "NONE",
+    DEBUG = "DEBUG",
+    WARN = "WARN",
+    ERROR = "ERROR"
+}
+export declare const PAGE_VIEW_EVENT_NAME = "pageview";

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

@@ -0,0 +1,41 @@
+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 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;
+};