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

package/src/lib/shared/{models.ts → models.d.ts}

@@ -26,7 +26,6 @@ export interface DotExperimentConfig {
      */
     redirectFn?: (url: string) => void;
 }
-
 /**
  * Represents the configuration for the LookBackWindow.
  *
@@ -37,18 +36,15 @@ 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.
  *
@@ -59,13 +55,11 @@ 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.
  *
@@ -76,13 +70,11 @@ 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.
  *
@@ -93,38 +85,31 @@ 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.
  *
@@ -135,31 +120,23 @@ 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'
->;
-
+export type FetchExperiments = Pick<AssignedExperiments, 'excludedExperimentIdsEnded' | 'experiments'>;
 /**
  * Represents the response from backend holding information about running experiments and variant assignment.
  *
@@ -170,23 +147,19 @@ 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.
  *
@@ -197,33 +170,27 @@ 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.
  *
@@ -234,9 +201,9 @@ 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, 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

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

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

@@ -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;
+    }
+}

package/.babelrc

@@ -1,12 +0,0 @@
-{
-    "presets": [
-        [
-            "@nrwl/react/babel",
-            {
-                "runtime": "automatic",
-                "useBuiltIns": "usage"
-            }
-        ]
-    ],
-    "plugins": []
-}

package/.eslintrc.json

@@ -1,26 +0,0 @@
-{
-    "extends": ["plugin:@nrwl/nx/react", "../../../.eslintrc.base.json"],
-    "ignorePatterns": ["!**/*"],
-    "overrides": [
-        {
-            "files": ["*.ts", "*.tsx", "*.js", "*.jsx"],
-            "rules": {
-                "padding-line-between-statements": [
-                    "error",
-                    { "blankLine": "always", "prev": "const", "next": "*" },
-                    { "blankLine": "always", "prev": "*", "next": "if" },
-                    { "blankLine": "always", "prev": "if", "next": "*" },
-                    { "blankLine": "always", "prev": "*", "next": "const" }
-                ]
-            }
-        },
-        {
-            "files": ["*.ts", "*.tsx"],
-            "rules": {}
-        },
-        {
-            "files": ["*.js", "*.jsx"],
-            "rules": {}
-        }
-    ]
-}

package/jest.config.ts

@@ -1,11 +0,0 @@
-/* eslint-disable */
-export default {
-    displayName: 'sdk-experiments',
-    preset: '../../../jest.preset.js',
-    transform: {
-        '^(?!.*\\.(js|jsx|ts|tsx|css|json)$)': '@nrwl/react/plugins/jest',
-        '^.+\\.[tj]sx?$': ['babel-jest', { presets: ['@nrwl/react/babel'] }]
-    },
-    moduleFileExtensions: ['ts', 'tsx', 'js', 'jsx'],
-    coverageDirectory: '../../../coverage/libs/sdk/experiments'
-};

package/project.json

@@ -1,55 +0,0 @@
-{
-    "name": "sdk-experiments",
-    "$schema": "../../../node_modules/nx/schemas/project-schema.json",
-    "sourceRoot": "libs/sdk/experiments/src",
-    "projectType": "library",
-    "targets": {
-        "build": {
-            "executor": "@nrwl/rollup:rollup",
-            "outputs": ["{options.outputPath}"],
-            "options": {
-                "outputPath": "dist/libs/sdk/experiments",
-                "tsConfig": "libs/sdk/experiments/tsconfig.lib.json",
-                "project": "libs/sdk/experiments/package.json",
-                "entryFile": "libs/sdk/experiments/src/index.ts",
-                "external": ["react/jsx-runtime"],
-                "rollupConfig": "@nrwl/react/plugins/bundle-rollup",
-                "compiler": "babel",
-                "assets": [
-                    {
-                        "glob": "libs/sdk/experiments/README.md",
-                        "input": ".",
-                        "output": "."
-                    }
-                ]
-            }
-        },
-        "build:iife": {
-            "executor": "@nx/vite:build",
-            "outputs": ["{options.outputPath}"],
-            "options": {
-                "outputPath": "dist/libs/sdk/experiments/iife",
-                "main": "libs/sdk/experiments/src/lib/standalone.ts",
-                "tsConfig": "libs/sdk/experiments/tsconfig.lib.json"
-            }
-        },
-        "publish": {
-            "command": "node tools/scripts/publish.mjs sdk-experiments {args.ver} {args.tag}",
-            "outputPath": "dist/libs/sdk/experiments",
-            "dependsOn": ["build", "test"]
-        },
-        "nx-release-publish": {
-            "options": {
-                "packageRoot": "dist/libs/sdk/experiments"
-            }
-        },
-        "test": {
-            "executor": "@nx/jest:jest",
-            "outputs": ["{workspaceRoot}/coverage/{projectRoot}"],
-            "options": {
-                "jestConfig": "libs/sdk/experiments/jest.config.ts"
-            }
-        }
-    },
-    "tags": []
-}

package/src/lib/components/DotExperimentsProvider.spec.tsx

@@ -1,62 +0,0 @@
-import { render, waitFor } from '@testing-library/react';
-
-import * as dotcmsClient from '@dotcms/client';
-
-import { DotExperimentsProvider } from './DotExperimentsProvider';
-
-import { DotExperiments } from '../dot-experiments';
-
-jest.mock('../dot-experiments');
-jest.mock('@dotcms/client');
-
-const mockDotExperimentsInstance = {
-    getInstance: jest.fn().mockResolvedValue(true),
-    ready: jest.fn().mockResolvedValue(true),
-    locationChanged: jest.fn().mockResolvedValue(true)
-};
-
-describe('DotExperimentsProvider', () => {
-    beforeEach(() => {
-        DotExperiments.getInstance = jest.fn().mockReturnValue(mockDotExperimentsInstance);
-    });
-
-    it('initializes DotExperiments instance when not inside the editor', async () => {
-        const config = { apiKey: 'key', server: 'server', debug: true };
-
-        jest.spyOn(dotcmsClient, 'isInsideEditor').mockReturnValue(true);
-
-        const consoleWarnSpy = jest.spyOn(console, 'warn').mockImplementation();
-
-        render(
-            <DotExperimentsProvider config={config}>
-                <div>Test</div>
-            </DotExperimentsProvider>
-        );
-
-        await waitFor(() => expect(DotExperiments.getInstance).not.toHaveBeenCalled());
-
-        expect(consoleWarnSpy).toHaveBeenCalledWith(
-            'DotExperimentsProvider: DotExperiments instance not initialized because it is inside the editor.'
-        );
-
-        consoleWarnSpy.mockRestore();
-    });
-
-    it('initializes DotExperiments instance when is inside the editor', async () => {
-        const config = { apiKey: 'key', server: 'server', debug: true };
-
-        jest.spyOn(dotcmsClient, 'isInsideEditor').mockReturnValue(false);
-
-        const consoleWarnSpy = jest.spyOn(console, 'warn').mockImplementation();
-
-        render(
-            <DotExperimentsProvider config={config}>
-                <div>Test</div>
-            </DotExperimentsProvider>
-        );
-
-        await waitFor(() => expect(DotExperiments.getInstance).toHaveBeenCalled());
-
-        consoleWarnSpy.mockRestore();
-    });
-});

package/src/lib/components/withExperiments.tsx

@@ -1,52 +0,0 @@
-/* eslint-disable react-hooks/rules-of-hooks */
-import React, { ReactNode, useCallback } from 'react';
-
-import { DotcmsPageProps } from '@dotcms/react';
-
-import { DotExperimentHandlingComponent } from './DotExperimentHandlingComponent';
-import { DotExperimentsProvider } from './DotExperimentsProvider';
-
-import { DotExperimentConfig } from '../shared/models';
-import { useMemoizedObject } from '../shared/utils/memoize';
-
-export interface PageProviderProps {
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
-    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 const withExperiments = (
-    WrappedComponent: React.ComponentType<DotcmsPageProps>,
-    config: DotExperimentConfig
-) => {
-    // We need to use a custom memoization hook
-    // because the useMemo or React.memo lose the reference of the object
-    // in each render, causing the experiment handling to be reinitialized.
-    const memoizedConfig = useMemoizedObject(config);
-
-    return useCallback(
-        (props: DotcmsPageProps) => {
-            return (
-                <DotExperimentsProvider config={memoizedConfig}>
-                    <DotExperimentHandlingComponent
-                        {...props}
-                        WrappedComponent={WrappedComponent}
-                    />
-                </DotExperimentsProvider>
-            );
-        },
-        [WrappedComponent, memoizedConfig]
-    );
-};