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

package/src/lib/client/{sdk-js-client.d.ts → sdk-js-client.ts}

@@ -1,5 +1,11 @@
 import { Content } from './content/content-api';
+import { ErrorMessages } from './models';
+import { DotcmsClientListener } from './models/types';
+
+import { isInsideEditor } from '../editor/sdk-editor';
+
 export type ClientOptions = Omit<RequestInit, 'body' | 'method'>;
+
 export interface ClientConfig {
     /**
      * The URL of the dotCMS instance.
@@ -38,6 +44,7 @@ export interface ClientConfig {
      */
     requestOptions?: ClientOptions;
 }
+
 export type PageApiOptions = {
     /**
      * The path of the page you want to retrieve.
@@ -90,6 +97,7 @@ export type PageApiOptions = {
      */
     depth?: number;
 };
+
 type NavApiOptions = {
     /**
      * The root path to begin traversing the folder tree.
@@ -123,6 +131,15 @@ type NavApiOptions = {
      */
     languageId?: number;
 };
+
+function getHostURL(url: string): URL | undefined {
+    try {
+        return new URL(url);
+    } catch (error) {
+        return undefined;
+    }
+}
+
 /**
  * `DotCmsClient` is a TypeScript class that provides methods to interact with the DotCMS REST API.
  * DotCMS is a hybrid-headless CMS and digital experience platform.
@@ -169,13 +186,49 @@ type NavApiOptions = {
  * client.editor.on('changes', (payload) => console.log('Changes detected:', payload));
  * ```
  */
-export declare class DotCmsClient {
-    #private;
+export class DotCmsClient {
     static instance: DotCmsClient;
+    #config: ClientConfig;
+    #requestOptions!: ClientOptions;
+    #listeners: DotcmsClientListener[] = [];
+
     dotcmsUrl?: string;
     content: Content;
-    constructor(config?: ClientConfig);
-    page: {
+
+    constructor(
+        config: ClientConfig = { dotcmsUrl: '', authToken: '', requestOptions: {}, siteId: '' }
+    ) {
+        if (!config.dotcmsUrl) {
+            throw new Error("Invalid configuration - 'dotcmsUrl' is required");
+        }
+
+        this.dotcmsUrl = getHostURL(config.dotcmsUrl)?.origin;
+
+        if (!this.dotcmsUrl) {
+            throw new Error("Invalid configuration - 'dotcmsUrl' must be a valid URL");
+        }
+
+        if (!config.authToken) {
+            throw new Error("Invalid configuration - 'authToken' is required");
+        }
+
+        this.#config = {
+            ...config,
+            dotcmsUrl: this.dotcmsUrl
+        };
+
+        this.#requestOptions = {
+            ...this.#config.requestOptions,
+            headers: {
+                Authorization: `Bearer ${this.#config.authToken}`,
+                ...this.#config.requestOptions?.headers
+            }
+        };
+
+        this.content = new Content(this.#requestOptions, this.#config.dotcmsUrl);
+    }
+
+    page = {
         /**
          * `page.get` is an asynchronous method of the `DotCmsClient` class that retrieves all the elements of any Page in your dotCMS system in JSON format.
          * It takes a `PageApiOptions` object as a parameter and returns a Promise that resolves to the response from the DotCMS API.
@@ -194,9 +247,51 @@ export declare class DotCmsClient {
          * client.page.get({ path: '/about-us' }).then(response => console.log(response));
          * ```
          */
-        get: (options: PageApiOptions) => Promise<unknown>;
+        get: async (options: PageApiOptions): Promise<unknown> => {
+            this.validatePageOptions(options);
+
+            const queryParamsObj: Record<string, string> = {};
+            for (const [key, value] of Object.entries(options)) {
+                if (value === undefined || key === 'path' || key === 'siteId') continue;
+
+                if (key === 'personaId') {
+                    queryParamsObj['com.dotmarketing.persona.id'] = String(value);
+                } else if (key === 'mode' && value) {
+                    queryParamsObj['mode'] = String(value);
+                } else {
+                    queryParamsObj[key] = String(value);
+                }
+            }
+
+            const queryHostId = options.siteId ?? this.#config.siteId ?? '';
+
+            if (queryHostId) {
+                queryParamsObj['host_id'] = queryHostId;
+            }
+
+            const queryParams = new URLSearchParams(queryParamsObj).toString();
+
+            const formattedPath = options.path.startsWith('/') ? options.path : `/${options.path}`;
+            const url = `${this.#config.dotcmsUrl}/api/v1/page/json${formattedPath}${
+                queryParams ? `?${queryParams}` : ''
+            }`;
+
+            const response = await fetch(url, this.#requestOptions);
+            if (!response.ok) {
+                const error = {
+                    status: response.status,
+                    message: ErrorMessages[response.status] || response.statusText
+                };
+
+                console.error(error);
+                throw error;
+            }
+
+            return response.json().then((data) => data.entity);
+        }
     };
-    editor: {
+
+    editor = {
         /**
          * `editor.on` is an asynchronous method of the `DotCmsClient` class that allows you to react to actions issued by the UVE.
          *
@@ -210,7 +305,22 @@ export declare class DotCmsClient {
          * });
          * ```
          */
-        on: (action: string, callbackFn: (payload: unknown) => void) => void;
+        on: (action: string, callbackFn: (payload: unknown) => void) => {
+            if (!isInsideEditor()) {
+                return;
+            }
+
+            if (action === 'changes') {
+                const messageCallback = (event: MessageEvent) => {
+                    if (event.data.name === 'SET_PAGE_DATA') {
+                        callbackFn(event.data.payload);
+                    }
+                };
+
+                window.addEventListener('message', messageCallback);
+                this.#listeners.push({ event: 'message', callback: messageCallback, action });
+            }
+        },
         /**
          * `editor.off` is a synchronous method of the `DotCmsClient` class that allows you to stop listening and reacting to an action issued by UVE.
          *
@@ -221,9 +331,19 @@ export declare class DotCmsClient {
          * client.editor.off('changes');
          * ```
          */
-        off: (action: string) => void;
+        off: (action: string) => {
+            const listenerIndex = this.#listeners.findIndex(
+                (listener) => listener.action === action
+            );
+            if (listenerIndex !== -1) {
+                const listener = this.#listeners[listenerIndex];
+                window.removeEventListener(listener.event, listener.callback);
+                this.#listeners.splice(listenerIndex, 1);
+            }
+        }
     };
-    nav: {
+
+    nav = {
         /**
          * `nav.get` is an asynchronous method of the `DotCmsClient` class that retrieves information about the dotCMS file and folder tree.
          * It takes a `NavApiOptions` object as a parameter (with default values) and returns a Promise that resolves to the response from the DotCMS API.
@@ -240,8 +360,34 @@ export declare class DotCmsClient {
          * client.nav.get({ path: '/about-us', depth: 2 }).then(response => console.log(response));
          * ```
          */
-        get: (options?: NavApiOptions) => Promise<unknown>;
+        get: async (
+            options: NavApiOptions = { depth: 0, path: '/', languageId: 1 }
+        ): Promise<unknown> => {
+            this.validateNavOptions(options);
+
+            // Extract the 'path' from the options and prepare the rest as query parameters
+            const { path, ...queryParamsOptions } = options;
+            const queryParamsObj: Record<string, string> = {};
+            Object.entries(queryParamsOptions).forEach(([key, value]) => {
+                if (value !== undefined) {
+                    queryParamsObj[key] = String(value);
+                }
+            });
+
+            const queryParams = new URLSearchParams(queryParamsObj).toString();
+
+            // Format the URL correctly depending on the 'path' value
+            const formattedPath = path === '/' ? '/' : `/${path}`;
+            const url = `${this.#config.dotcmsUrl}/api/v1/nav${formattedPath}${
+                queryParams ? `?${queryParams}` : ''
+            }`;
+
+            const response = await fetch(url, this.#requestOptions);
+
+            return response.json();
+        }
     };
+
     /**
      * Initializes the DotCmsClient instance with the provided configuration.
      * If an instance already exists, it returns the existing instance.
@@ -253,24 +399,44 @@ export declare class DotCmsClient {
      * const client = DotCmsClient.init({ dotcmsUrl: 'https://demo.dotcms.com', authToken: 'your-auth-token' });
      * ```
      */
-    static init(config: ClientConfig): DotCmsClient;
+    static init(config: ClientConfig): DotCmsClient {
+        if (this.instance) {
+            console.warn(
+                'DotCmsClient has already been initialized. Please use the instance to interact with the DotCMS API.'
+            );
+        }
+
+        return this.instance ?? (this.instance = new DotCmsClient(config));
+    }
+
     /**
      * Retrieves the DotCMS URL from the instance configuration.
      *
      * @returns {string} - The DotCMS URL.
      */
-    static get dotcmsUrl(): string;
+    static get dotcmsUrl(): string {
+        return (this.instance && this.instance.#config.dotcmsUrl) || '';
+    }
+
     /**
      * Throws an error if the path is not valid.
      *
      * @returns {string} - The authentication token.
      */
-    private validatePageOptions;
+    private validatePageOptions(options: PageApiOptions): void {
+        if (!options.path) {
+            throw new Error("The 'path' parameter is required for the Page API");
+        }
+    }
+
     /**
      * Throws an error if the path is not valid.
      *
      *  @returns {string} - The authentication token.
      */
-    private validateNavOptions;
+    private validateNavOptions(options: NavApiOptions): void {
+        if (!options.path) {
+            throw new Error("The 'path' parameter is required for the Nav API");
+        }
+    }
 }
-export {};

package/src/lib/editor/listeners/listeners.spec.ts

@@ -0,0 +1,119 @@
+import {
+    fetchPageDataFromInsideUVE,
+    listenEditorMessages,
+    listenHoveredContentlet,
+    preserveScrollOnIframe,
+    scrollHandler
+} from './listeners';
+
+import { CUSTOMER_ACTIONS, postMessageToEditor } from '../models/client.model';
+
+jest.mock('../models/client.model', () => ({
+    postMessageToEditor: jest.fn(),
+    CUSTOMER_ACTIONS: {
+        NAVIGATION_UPDATE: 'set-url',
+        SET_BOUNDS: 'set-bounds',
+        SET_CONTENTLET: 'set-contentlet',
+        IFRAME_SCROLL: 'scroll',
+        PING_EDITOR: 'ping-editor',
+        CONTENT_CHANGE: 'content-change',
+        GET_PAGE_DATA: 'get-page-data',
+        NOOP: 'noop'
+    }
+}));
+
+const CONTAINER_MOCK = {
+    acceptTypes: 'text/html',
+    identifier: '123',
+    maxContentlets: '1',
+    uuid: '123-456'
+};
+
+const getContentletTestElement = () => {
+    const div = document.createElement('div');
+
+    div.setAttribute('data-dot-object', 'contentlet');
+    div.setAttribute('data-dot-identifier', '123');
+    div.setAttribute('data-dot-title', 'title');
+    div.setAttribute('data-dot-inode', '123-456');
+    div.setAttribute('data-dot-type', 'CONTENT');
+    div.setAttribute('data-dot-basetype', 'WIDGET');
+    div.setAttribute('data-dot-widget-title', 'widgetTitle');
+    div.setAttribute('data-dot-on-number-of-pages', '1');
+    div.setAttribute('data-dot-container', JSON.stringify(CONTAINER_MOCK));
+    div.innerHTML = 'contentlet';
+
+    return div;
+};
+
+/**
+ * Observation: We must test the execution of methods as well.
+ */
+describe('listeners', () => {
+    it('should listen editor messages', () => {
+        const addEventListenerSpy = jest.spyOn(window, 'addEventListener');
+        listenEditorMessages();
+        expect(addEventListenerSpy).toHaveBeenCalledWith('message', expect.any(Function));
+    });
+
+    it('should listen to hovered contentlet', () => {
+        const addEventListenerSpy = jest.spyOn(document, 'addEventListener');
+
+        listenHoveredContentlet();
+
+        const target = getContentletTestElement();
+        const event = new MouseEvent('pointermove', {
+            bubbles: true,
+            cancelable: true
+        });
+
+        document.body.appendChild(target);
+        target.dispatchEvent(event);
+
+        expect(addEventListenerSpy).toHaveBeenCalledWith('pointermove', expect.any(Function));
+        expect(postMessageToEditor).toHaveBeenCalledWith({
+            action: CUSTOMER_ACTIONS.SET_CONTENTLET,
+            payload: {
+                x: expect.any(Number),
+                y: expect.any(Number),
+                width: expect.any(Number),
+                height: expect.any(Number),
+                payload: {
+                    container: CONTAINER_MOCK,
+                    contentlet: {
+                        baseType: 'WIDGET',
+                        identifier: '123',
+                        inode: '123-456',
+                        contentType: 'CONTENT',
+                        title: 'title',
+                        widgetTitle: 'widgetTitle',
+                        onNumberOfPages: '1'
+                    },
+                    vtlFiles: null
+                }
+            }
+        });
+    });
+
+    it('should handle scroll', () => {
+        const addEventListenerSpy = jest.spyOn(window, 'addEventListener');
+        scrollHandler();
+        expect(addEventListenerSpy).toHaveBeenCalledWith('scroll', expect.any(Function));
+    });
+
+    it('should preserve scroll on iframe', () => {
+        const addEventListenerSpy = jest.spyOn(window, 'addEventListener');
+        preserveScrollOnIframe();
+        expect(addEventListenerSpy).toHaveBeenCalledWith('load', expect.any(Function));
+    });
+
+    it('should get page data post message to editor', () => {
+        fetchPageDataFromInsideUVE('some-url');
+        expect(postMessageToEditor).toHaveBeenCalledWith({
+            action: CUSTOMER_ACTIONS.GET_PAGE_DATA,
+            payload: {
+                pathname: 'some-url'
+            }
+        });
+    });
+});

package/src/lib/editor/listeners/listeners.ts

@@ -0,0 +1,223 @@
+import { CUSTOMER_ACTIONS, postMessageToEditor } from '../models/client.model';
+import { DotCMSPageEditorSubscription, NOTIFY_CUSTOMER } from '../models/listeners.model';
+import {
+    findVTLData,
+    findDotElement,
+    getClosestContainerData,
+    getPageElementBound,
+    scrollIsInBottom
+} from '../utils/editor.utils';
+
+declare global {
+    interface Window {
+        lastScrollYPosition: number;
+    }
+}
+
+/**
+ * Represents an array of DotCMSPageEditorSubscription objects.
+ * Used to store the subscriptions for the editor and unsubscribe later.
+ */
+export const subscriptions: DotCMSPageEditorSubscription[] = [];
+
+/**
+ * Sets the bounds of the containers in the editor.
+ * Retrieves the containers from the DOM and sends their position data to the editor.
+ * @private
+ * @memberof DotCMSPageEditor
+ */
+function setBounds(): void {
+    const containers = Array.from(
+        document.querySelectorAll('[data-dot-object="container"]')
+    ) as HTMLDivElement[];
+    const positionData = getPageElementBound(containers);
+
+    postMessageToEditor({
+        action: CUSTOMER_ACTIONS.SET_BOUNDS,
+        payload: positionData
+    });
+}
+
+/**
+ * Listens for editor messages and performs corresponding actions based on the received message.
+ *
+ * @private
+ * @memberof DotCMSPageEditor
+ */
+export function listenEditorMessages(): void {
+    const messageCallback = (event: MessageEvent) => {
+        switch (event.data) {
+            case NOTIFY_CUSTOMER.EMA_REQUEST_BOUNDS: {
+                setBounds();
+                break;
+            }
+        }
+
+        if (event.data.name === NOTIFY_CUSTOMER.EMA_SCROLL_INSIDE_IFRAME) {
+            const direction = event.data.direction;
+
+            if (
+                (window.scrollY === 0 && direction === 'up') ||
+                (scrollIsInBottom() && direction === 'down')
+            ) {
+                // If the iframe scroll is at the top or bottom, do not send anything.
+                // This avoids losing the scrollend event.
+                return;
+            }
+
+            const scrollY = direction === 'up' ? -120 : 120;
+            window.scrollBy({ left: 0, top: scrollY, behavior: 'smooth' });
+        }
+    };
+
+    window.addEventListener('message', messageCallback);
+
+    subscriptions.push({
+        type: 'listener',
+        event: 'message',
+        callback: messageCallback
+    });
+}
+
+/**
+ * Listens for pointer move events and extracts information about the hovered contentlet.
+ *
+ * @private
+ * @memberof DotCMSPageEditor
+ */
+export function listenHoveredContentlet(): void {
+    const pointerMoveCallback = (event: PointerEvent) => {
+        const foundElement = findDotElement(event.target as HTMLElement);
+
+        if (!foundElement) return;
+
+        const { x, y, width, height } = foundElement.getBoundingClientRect();
+
+        const isContainer = foundElement.dataset?.['dotObject'] === 'container';
+
+        const contentletForEmptyContainer = {
+            identifier: 'TEMP_EMPTY_CONTENTLET',
+            title: 'TEMP_EMPTY_CONTENTLET',
+            contentType: 'TEMP_EMPTY_CONTENTLET_TYPE',
+            inode: 'TEMPY_EMPTY_CONTENTLET_INODE',
+            widgetTitle: 'TEMP_EMPTY_CONTENTLET',
+            baseType: 'TEMP_EMPTY_CONTENTLET',
+            onNumberOfPages: 1
+        };
+
+        const contentlet = {
+            identifier: foundElement.dataset?.['dotIdentifier'],
+            title: foundElement.dataset?.['dotTitle'],
+            inode: foundElement.dataset?.['dotInode'],
+            contentType: foundElement.dataset?.['dotType'],
+            baseType: foundElement.dataset?.['dotBasetype'],
+            widgetTitle: foundElement.dataset?.['dotWidgetTitle'],
+            onNumberOfPages: foundElement.dataset?.['dotOnNumberOfPages']
+        };
+
+        const vtlFiles = findVTLData(foundElement);
+        const contentletPayload = {
+            container:
+                // Here extract dot-container from contentlet if it is Headless
+                // or search in parent container if it is VTL
+                foundElement.dataset?.['dotContainer']
+                    ? JSON.parse(foundElement.dataset?.['dotContainer'])
+                    : getClosestContainerData(foundElement),
+            contentlet: isContainer ? contentletForEmptyContainer : contentlet,
+            vtlFiles
+        };
+
+        postMessageToEditor({
+            action: CUSTOMER_ACTIONS.SET_CONTENTLET,
+            payload: {
+                x,
+                y,
+                width,
+                height,
+                payload: contentletPayload
+            }
+        });
+    };
+
+    document.addEventListener('pointermove', pointerMoveCallback);
+
+    subscriptions.push({
+        type: 'listener',
+        event: 'pointermove',
+        callback: pointerMoveCallback
+    });
+}
+
+/**
+ * Attaches a scroll event listener to the window
+ * and sends a message to the editor when the window is scrolled.
+ *
+ * @private
+ * @memberof DotCMSPageEditor
+ */
+export function scrollHandler(): void {
+    const scrollCallback = () => {
+        postMessageToEditor({
+            action: CUSTOMER_ACTIONS.IFRAME_SCROLL
+        });
+        window.lastScrollYPosition = window.scrollY;
+    };
+
+    const scrollEndCallback = () => {
+        postMessageToEditor({
+            action: CUSTOMER_ACTIONS.IFRAME_SCROLL_END
+        });
+    };
+
+    window.addEventListener('scroll', scrollCallback);
+    window.addEventListener('scrollend', scrollEndCallback);
+
+    subscriptions.push({
+        type: 'listener',
+        event: 'scroll',
+        callback: scrollEndCallback
+    });
+
+    subscriptions.push({
+        type: 'listener',
+        event: 'scroll',
+        callback: scrollCallback
+    });
+}
+
+/**
+ * Restores the scroll position of the window when an iframe is loaded.
+ * Only used in VTL Pages.
+ * @export
+ * @example
+ * ```ts
+ * preserveScrollOnIframe();
+ * ```
+ */
+export function preserveScrollOnIframe(): void {
+    const preserveScrollCallback = () => {
+        window.scrollTo(0, window.lastScrollYPosition);
+    };
+
+    window.addEventListener('load', preserveScrollCallback);
+    subscriptions.push({
+        type: 'listener',
+        event: 'scroll',
+        callback: preserveScrollCallback
+    });
+}
+
+/**
+ * Sends a message to the editor to get the page data.
+ * @param {string} pathname - The pathname of the page.
+ * @private
+ * @memberof DotCMSPageEditor
+ */
+export function fetchPageDataFromInsideUVE(pathname: string) {
+    postMessageToEditor({
+        action: CUSTOMER_ACTIONS.GET_PAGE_DATA,
+        payload: {
+            pathname
+        }
+    });
+}