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

package/.babelrc

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

package/.eslintrc.json

@@ -0,0 +1,26 @@
+{
+    "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

@@ -0,0 +1,11 @@
+/* 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dotcms/experiments",
-  "version": "0.0.1-alpha.38",
+  "version": "0.0.1-alpha.39",
   "description": "Official JavaScript library to use Experiments with DotCMS.",
   "repository": {
     "type": "git",
@@ -25,10 +25,6 @@
   "peerDependencies": {
     "react": ">=18",
     "react-dom": ">=18",
-    "@dotcms/client": "0.0.1-alpha.38"
-  },
-  "module": "./index.esm.js",
-  "type": "module",
-  "main": "./index.esm.js",
-  "types": "./index.esm.d.ts"
-}
+    "@dotcms/client": "0.0.1-alpha.39"
+  }
+}

package/project.json

@@ -0,0 +1,55 @@
+{
+    "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/{DotExperimentHandlingComponent.d.ts → DotExperimentHandlingComponent.tsx}

@@ -1,8 +1,11 @@
-/// <reference types="react" />
 import { DotcmsPageProps } from '@dotcms/react';
+
+import { useExperimentVariant } from '../hooks/useExperimentVariant';
+
 interface ExperimentHandlingProps extends DotcmsPageProps {
     WrappedComponent: React.ComponentType<DotcmsPageProps>;
 }
+
 /**
  * A React functional component that conditionally renders a WrappedComponent based on the
  * experiment variant state. It uses the `useExperimentVariant` hook to determine if there's a
@@ -17,5 +20,19 @@ interface ExperimentHandlingProps extends DotcmsPageProps {
  * @returns {React.ReactElement} A React element that either renders the WrappedComponent hidden or visible
  *          based on the experiment variant.
  */
-export declare const DotExperimentHandlingComponent: React.FC<ExperimentHandlingProps>;
-export {};
+export const DotExperimentHandlingComponent: React.FC<ExperimentHandlingProps> = ({
+    WrappedComponent,
+    ...props
+}) => {
+    const { shouldWaitForVariant } = useExperimentVariant(props.pageContext.pageAsset);
+
+    if (shouldWaitForVariant) {
+        return (
+            <div style={{ visibility: 'hidden' }}>
+                <WrappedComponent {...props} />
+            </div>
+        );
+    }
+
+    return <WrappedComponent {...props} />;
+};

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

@@ -0,0 +1,62 @@
+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/{DotExperimentsProvider.d.ts → DotExperimentsProvider.tsx}

@@ -1,9 +1,17 @@
-import { ReactElement, ReactNode } from 'react';
+import { ReactElement, ReactNode, useEffect, useState } from 'react';
+
+import { isInsideEditor } from '@dotcms/client';
+
+import DotExperimentsContext from '../contexts/DotExperimentsContext';
+import { DotExperiments } from '../dot-experiments';
+import { useExperiments } from '../hooks/useExperiments';
 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.
@@ -43,5 +51,35 @@ interface DotExperimentsProviderProps {
  * @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 {};
+export const DotExperimentsProvider = ({
+    children,
+    config
+}: DotExperimentsProviderProps): ReactElement => {
+    const [instance, setInstance] = useState<DotExperiments | null>(null);
+
+    // Run Experiments detection
+    useExperiments(instance);
+
+    // Initialize the DotExperiments instance
+    useEffect(() => {
+        const insideEditor = isInsideEditor();
+
+        if (!insideEditor) {
+            const dotExperimentsInstance = DotExperiments.getInstance(config);
+
+            dotExperimentsInstance.ready().then(() => {
+                setInstance(dotExperimentsInstance);
+            });
+        } else {
+            if (config.debug) {
+                console.warn(
+                    'DotExperimentsProvider: DotExperiments instance not initialized because it is inside the editor.'
+                );
+            }
+        }
+    }, [config]);
+
+    return (
+        <DotExperimentsContext.Provider value={instance}>{children}</DotExperimentsContext.Provider>
+    );
+};

package/src/lib/components/withExperiments.tsx

@@ -0,0 +1,52 @@
+/* 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]
+    );
+};

package/src/lib/contexts/DotExperimentsContext.spec.tsx

@@ -0,0 +1,42 @@
+import { renderHook } from '@testing-library/react-hooks';
+import { ReactNode, useContext } from 'react';
+
+import DotExperimentsContext from './DotExperimentsContext';
+
+import { DotExperiments } from '../dot-experiments';
+
+jest.mock('../dot-experiments', () => {
+    return jest.fn().mockImplementation(() => {
+        return {};
+    });
+});
+
+describe('useDotExperimentsContext', () => {
+    it('returns the context value null', () => {
+        const mockContextValue = null;
+
+        const { result } = renderHook(() => useContext(DotExperimentsContext), {
+            wrapper: ({ children }: { children: ReactNode }) => (
+                <DotExperimentsContext.Provider value={mockContextValue}>
+                    {children}
+                </DotExperimentsContext.Provider>
+            )
+        });
+
+        expect(result.current).toEqual(mockContextValue);
+    });
+
+    it('returns the context value DotExperiment', () => {
+        const mockContextValue = {} as DotExperiments;
+
+        const { result } = renderHook(() => useContext(DotExperimentsContext), {
+            wrapper: ({ children }: { children: ReactNode }) => (
+                <DotExperimentsContext.Provider value={mockContextValue}>
+                    {children}
+                </DotExperimentsContext.Provider>
+            )
+        });
+
+        expect(result.current).toEqual(mockContextValue);
+    });
+});

package/src/lib/contexts/{DotExperimentsContext.d.ts → DotExperimentsContext.tsx}

@@ -1,5 +1,7 @@
-/// <reference types="react" />
+import { createContext } from 'react';
+
 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.
@@ -9,5 +11,6 @@ import { DotExperiments } from '../dot-experiments';
  *
  * @see {@link https://reactjs.org/docs/context.html|React Context}
  */
-declare const DotExperimentsContext: import("react").Context<DotExperiments | null>;
+const DotExperimentsContext = createContext<DotExperiments | null>(null);
+
 export default DotExperimentsContext;

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

@@ -0,0 +1,285 @@
+/* eslint-disable @typescript-eslint/ban-ts-comment */
+import fakeIndexedDB from 'fake-indexeddb';
+import fetchMock from 'fetch-mock';
+
+import { DotExperiments } from './dot-experiments';
+import { API_EXPERIMENTS_URL, EXPERIMENT_QUERY_PARAM_KEY } from './shared/constants';
+import {
+    After15DaysIsUserIncludedResponse,
+    IsUserIncludedResponse,
+    LocationMock,
+    MOCK_CURRENT_TIMESTAMP,
+    MockDataStoredIndexDB,
+    MockDataStoredIndexDBWithNew,
+    MockDataStoredIndexDBWithNew15DaysLater,
+    NewIsUserIncludedResponse,
+    NoExperimentsIsUserIncludedResponse,
+    sessionStorageMock,
+    TIME_15_DAYS_MILLISECONDS,
+    TIME_5_DAYS_MILLISECONDS
+} from './shared/mocks/mock';
+import { DotExperimentConfig } from './shared/models';
+
+jest.spyOn(Date, 'now').mockImplementation(() => MOCK_CURRENT_TIMESTAMP);
+
+// Jitsu SDK Mock
+jest.mock('@jitsu/sdk-js', () => ({
+    jitsuClient: jest.fn(() => ({
+        set: jest.fn(),
+        track: jest.fn().mockResolvedValue(true)
+    }))
+}));
+
+// SessionStorage mock
+global.sessionStorage = sessionStorageMock;
+
+// IndexDB Mock
+Object.defineProperty(window, 'indexedDB', {
+    writable: true,
+    value: fakeIndexedDB
+});
+
+if (!globalThis.structuredClone) {
+    globalThis.structuredClone = function (obj) {
+        return JSON.parse(JSON.stringify(obj));
+    };
+}
+
+// Windows Mock
+global.window = Object.create(window);
+Object.defineProperty(window, 'location', {
+    value: {
+        href: 'http://localhost:8080/',
+        origin: 'http://localhost:8080'
+    }
+});
+
+describe('DotExperiments', () => {
+    const configMock: DotExperimentConfig = {
+        apiKey: 'yourApiKey',
+        server: 'http://localhost:8080/',
+        debug: false,
+        trackPageView: true
+    };
+
+    describe('DotExperiments Instance and Initialization', () => {
+        beforeEach(() => {
+            // destroy the instance of the singleton
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            (DotExperiments as any).instance = null;
+        });
+        it('should throw an error if config is not provided', () => {
+            expect(() => DotExperiments.getInstance()).toThrow(
+                'Configuration is required to create a new instance.'
+            );
+        });
+
+        it('should instantiate the class when getInstance is called with config', () => {
+            const dotExperimentsInstance = DotExperiments.getInstance(configMock);
+
+            expect(dotExperimentsInstance).toBeInstanceOf(DotExperiments);
+        });
+
+        it('should throw an error if server is not provided in config', () => {
+            expect(() =>
+                // @ts-ignore
+                DotExperiments.getInstance({ 'api-key': 'api-key-test', debug: true })
+            ).toThrow('`server` must be provided and should not be empty!');
+        });
+
+        it('should throw an error if api-key is not provided in config', () => {
+            expect(() =>
+                // @ts-ignore
+                DotExperiments.getInstance({ server: 'http://server-test.com', debug: true })
+            ).toThrow('`apiKey` must be provided and should not be empty!');
+        });
+
+        it('should return false if the debug inactive', async () => {
+            const instance = DotExperiments.getInstance(configMock);
+
+            expect(instance.getIsDebugActive()).toBe(false);
+        });
+
+        it('should not call to trackPageView if you send the flag', async () => {
+            const config: DotExperimentConfig = { ...configMock, trackPageView: false };
+
+            fetchMock.post(`${configMock.server}/${API_EXPERIMENTS_URL}`, {
+                status: 200,
+                body: IsUserIncludedResponse,
+                headers: {
+                    Accept: 'application/json',
+                    'Content-Type': 'application/json'
+                }
+            });
+
+            const instance = DotExperiments.getInstance(config);
+
+            const spyTrackPageView = jest.spyOn(instance, 'trackPageView');
+
+            expect(spyTrackPageView).not.toHaveBeenCalled();
+
+            await instance.locationChanged(LocationMock).then(() => {
+                expect(spyTrackPageView).not.toHaveBeenCalled();
+            });
+        });
+
+        it('should not call to trackPageView if you dont have experiment to track', async () => {
+            const config: DotExperimentConfig = { ...configMock, trackPageView: false };
+
+            fetchMock.post(
+                `${configMock.server}/${API_EXPERIMENTS_URL}`,
+                {
+                    status: 200,
+                    body: NoExperimentsIsUserIncludedResponse,
+                    headers: {
+                        Accept: 'application/json',
+                        'Content-Type': 'application/json'
+                    }
+                },
+                { overwriteRoutes: true }
+            );
+
+            const instance = DotExperiments.getInstance(config);
+
+            const spyTrackPageView = jest.spyOn(instance, 'trackPageView');
+
+            expect(spyTrackPageView).not.toHaveBeenCalled();
+
+            await instance.locationChanged(LocationMock).then(() => {
+                expect(spyTrackPageView).not.toHaveBeenCalled();
+            });
+        });
+
+        it('should return a a string with the query params of variant by the url given', async () => {
+            const config: DotExperimentConfig = { ...configMock, trackPageView: false };
+
+            fetchMock.post(
+                `${configMock.server}/${API_EXPERIMENTS_URL}`,
+                {
+                    status: 200,
+                    body: IsUserIncludedResponse,
+                    headers: {
+                        Accept: 'application/json',
+                        'Content-Type': 'application/json'
+                    }
+                },
+                { overwriteRoutes: true }
+            );
+
+            const instance = DotExperiments.getInstance(config);
+
+            await instance.ready();
+
+            const EMPTY_URL = '';
+
+            const expected1 = new URLSearchParams({});
+
+            expect(instance.getVariantAsQueryParam(EMPTY_URL)).toStrictEqual(expected1);
+
+            const URL_WITH_EXPERIMENT = '/blog';
+
+            const expected2 = new URLSearchParams({
+                [EXPERIMENT_QUERY_PARAM_KEY]:
+                    IsUserIncludedResponse.entity.experiments[0].variant.name
+            });
+
+            expect(instance.getVariantAsQueryParam(URL_WITH_EXPERIMENT)).toStrictEqual(expected2);
+
+            const URL_NO_EXPERIMENT = '/destinations';
+
+            const expected3 = new URLSearchParams({});
+
+            expect(instance.getVariantAsQueryParam(URL_NO_EXPERIMENT)).toStrictEqual(expected3);
+        });
+    });
+
+    describe('Class interactions', () => {
+        beforeEach(() => {
+            fetchMock.restore();
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            (DotExperiments as any).instance = null;
+        });
+
+        it('should simulate the changes of the data in first run, after 5 days and 15 days.', async () => {
+            // First time the user enter to the page
+
+            fetchMock.post(`${configMock.server}/${API_EXPERIMENTS_URL}`, {
+                status: 200,
+                body: IsUserIncludedResponse,
+                headers: {
+                    Accept: 'application/json',
+                    'Content-Type': 'application/json'
+                }
+            });
+
+            const instance = DotExperiments.getInstance(configMock);
+
+            const spyTrackPageView = jest.spyOn(instance, 'trackPageView');
+
+            await instance.ready().then(() => {
+                const experiments = instance.experiments;
+
+                expect(experiments.length).toBe(1);
+                expect(experiments).toEqual(MockDataStoredIndexDB);
+
+                expect(spyTrackPageView).toBeCalledTimes(1);
+            });
+
+            // Second time the user enter to the page
+            // change the time 5 days later
+            jest.spyOn(Date, 'now').mockImplementation(
+                () => MOCK_CURRENT_TIMESTAMP + TIME_5_DAYS_MILLISECONDS
+            );
+
+            fetchMock.post(
+                `${configMock.server}/${API_EXPERIMENTS_URL}`,
+                {
+                    status: 200,
+                    body: NewIsUserIncludedResponse,
+                    headers: {
+                        Accept: 'application/json',
+                        'Content-Type': 'application/json'
+                    }
+                },
+                { overwriteRoutes: true }
+            );
+
+            await instance.locationChanged(LocationMock).then(() => {
+                // get the experiments stored in the indexDB
+                const experiments = instance.experiments;
+
+                expect(experiments.length).toBe(1);
+                expect(experiments).toEqual(MockDataStoredIndexDBWithNew);
+                expect(spyTrackPageView).toBeCalledTimes(2);
+            });
+
+            fetchMock.post(
+                `${configMock.server}/${API_EXPERIMENTS_URL}`,
+                {
+                    status: 200,
+                    body: After15DaysIsUserIncludedResponse,
+                    headers: {
+                        Accept: 'application/json',
+                        'Content-Type': 'application/json'
+                    }
+                },
+                { overwriteRoutes: true }
+            );
+
+            // Third try, after 15 days
+            const location = { ...LocationMock, href: 'http://localhost/destinations' };
+
+            jest.spyOn(Date, 'now').mockImplementation(
+                () => MOCK_CURRENT_TIMESTAMP + TIME_15_DAYS_MILLISECONDS
+            );
+            await instance.locationChanged(location).then(() => {
+                // get the experiments stored in the indexDB
+                const experiments = instance.experiments;
+
+                expect(experiments.length).toBe(1);
+                expect(experiments).toEqual(MockDataStoredIndexDBWithNew15DaysLater);
+                expect(spyTrackPageView).toBeCalledTimes(3);
+            });
+        });
+    });
+});