@dotcms/experiments 1.4.0-next.1 → 1.4.0-next.3

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

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

@@ -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,17 +0,0 @@
-import { DotCMSPageAsset } from '@dotcms/types';
-/**
- * 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: DotCMSPageAsset) => {
-    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/constants.d.ts

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

@@ -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/models.d.ts

@@ -1,209 +0,0 @@
-/**
- * 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[];
-    /**
-     * The ids of the experiments that are excluded in the request and have ended.
-     */
-    excludedExperimentIdsEnded: string[];
-}
-/**
- * Represents the response from the backend when fetching an experiment and the excludedExperimentIdsEnded.
- */
-export type FetchExperiments = Pick<AssignedExperiments, 'excludedExperimentIdsEnded' | 'experiments'>;
-/**
- * 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 {};