@dotcms/client 0.0.1-alpha.1 → 0.0.1-alpha.11

package/src/lib/client/sdk-js-client.ts

@@ -0,0 +1,297 @@
+export interface ClientConfig {
+    /**
+     * The URL of the dotCMS instance.
+     *
+     * @description This is the URL of the dotCMS instance you want to interact with. Ensure to include the protocol (http or https).
+     * @example `https://demo.dotcms.com`
+     * @type {string}
+     * @required
+     */
+    dotcmsUrl: string;
+    /**
+     * The id of the site you want to interact with.
+     *
+     * @description to get the site id, go to the site you want to interact with and copy the id from the History tab
+     *
+     * @type {string}
+     * @required
+     */
+    siteId?: string;
+    /**
+     * The authentication token to use for the requests. If not provided, it will fallback to default site.
+     *
+     * @description you can get the auth token from our UI {@link https://www.dotcms.com/docs/latest/rest-api-authentication#creating-an-api-token-in-the-ui}
+     *
+     * @type {string}
+     * @required
+     */
+    authToken: string;
+    /**
+     * Additional options to pass to the fetch request.
+     *
+     * @description These options will be used in the fetch request. Any option can be specified except for 'body' and 'method' which are omitted.
+     * @example `{ headers: { 'Content-Type': 'application/json' } }`
+     * @type {Omit<RequestInit, 'body' | 'method'>}
+     * @optional
+     */
+    requestOptions?: Omit<RequestInit, 'body' | 'method'>;
+}
+
+type PageApiOptions = {
+    /**
+     * The path of the page you want to retrieve.
+     *
+     * @type {string}
+     */
+    path: string;
+    /**
+     * The id of the site you want to interact with. If not provided, the one from the config will be used.
+     *
+     * @type {number}
+     */
+    siteId?: string;
+    /**
+     * The mode of the page you want to retrieve. If not provided will use the default mode of the site.
+     *
+     * @type {number}
+     */
+    mode?: string;
+    /**
+     * The language id of the page you want to retrieve. If not provided will use the default language of the site.
+     *
+     * @type {number}
+     */
+    language_id?: number;
+    /**
+     * The id of the persona you want to retrieve the page for.
+     *
+     * @type {string}
+     */
+    personaId?: string;
+    /**
+     * If you want to fire the rules set on the page
+     *
+     * @type {boolean}
+     */
+    fireRules?: boolean;
+    /**
+     * Allows access to related content via the Relationship fields of contentlets on a Page; 0 (default)
+     *
+     * @type {number}
+     */
+    depth?: number;
+};
+
+type NavApiOptions = {
+    /**
+     * The root path to begin traversing the folder tree.
+     *
+     * @example
+     * `/api/v1/nav/` starts from the root of the site
+     * @example
+     * `/about-us` starts from the "About Us" folder
+     *
+     * @type {string}
+     */
+    path: string;
+    /**
+     * The depth of the folder tree to return.
+     * @example
+     * `1` returns only the element specified in the path.
+     * @example
+     * `2` returns the element specified in the path, and if that element is a folder, returns all direct children of that folder.
+     * @example
+     * `3` returns all children and grandchildren of the element specified in the path.
+     *
+     * @type {number}
+     */
+    depth?: number;
+    /**
+     * The language ID of content to return.
+     * @example
+     * `1` (or unspecified) returns content in the default language of the site.
+     *
+     * @link https://www.dotcms.com/docs/latest/system-language-properties#DefaultLanguage
+     * @link https://www.dotcms.com/docs/latest/adding-and-editing-languages#LanguageID
+     * @type {number}
+     */
+    languageId?: number;
+};
+
+function isValidUrl(url: string): boolean {
+    try {
+        new URL(url);
+
+        return true;
+    } catch (error) {
+        return false;
+    }
+}
+
+/**
+ * `DotCmsClient` is a TypeScript class that provides methods to interact with the DotCMS REST API.
+ * It requires a configuration object on instantiation, which includes the DotCMS URL, site ID, and authentication token.
+ *
+ * @class DotCmsClient
+ *
+ * @property {ClientConfig} config - The configuration object for the DotCMS client.
+ *
+ * @method constructor(config: ClientConfig) - Constructs a new instance of the DotCmsClient class.
+ *
+ * @method page.get(options: PageApiOptions): Promise<unknown> - Retrieves all the elements of any Page in your dotCMS system in JSON format.
+ *
+ * @method nav.get(options: NavApiOptions = { depth: 0, path: '/', languageId: 1 }): Promise<unknown> - Retrieves information about the dotCMS file and folder tree.
+ *
+ */
+export class DotCmsClient {
+    private config: ClientConfig;
+    private requestOptions!: Omit<RequestInit, 'body' | 'method'>;
+
+    constructor(
+        config: ClientConfig = { dotcmsUrl: '', authToken: '', requestOptions: {}, siteId: '' }
+    ) {
+        if (!config.dotcmsUrl) {
+            throw new Error("Invalid configuration - 'dotcmsUrl' is required");
+        }
+
+        if (!isValidUrl(config.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;
+
+        this.requestOptions = {
+            ...this.config.requestOptions,
+            headers: {
+                Authorization: `Bearer ${this.config.authToken}`,
+                ...this.config.requestOptions?.headers
+            }
+        };
+    }
+
+    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.
+         *
+         * The Page API enables you to retrieve all the elements of any Page in your dotCMS system.
+         * The elements may be retrieved in JSON format.
+         *
+         * @link https://www.dotcms.com/docs/latest/page-rest-api-layout-as-a-service-laas
+         * @async
+         * @param {PageApiOptions} options - The options for the Page API call.
+         * @returns {Promise<unknown>} - A Promise that resolves to the response from the DotCMS API.
+         * @throws {Error} - Throws an error if the options are not valid.
+         */
+        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);
+
+            return response.json();
+        }
+    };
+
+    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.
+         *
+         * The navigation REST API enables you to retrieve information about the dotCMS file and folder tree through REST API calls.
+         * @link https://www.dotcms.com/docs/latest/navigation-rest-api
+         * @async
+         * @param {NavApiOptions} options - The options for the Nav API call. Defaults to `{ depth: 0, path: '/', languageId: 1 }`.
+         * @returns {Promise<unknown>} - A Promise that resolves to the response from the DotCMS API.
+         * @throws {Error} - Throws an error if the options are not valid.
+         */
+        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();
+        }
+    };
+
+    private validatePageOptions(options: PageApiOptions): void {
+        if (!options.path) {
+            throw new Error("The 'path' parameter is required for the Page API");
+        }
+    }
+
+    private validateNavOptions(options: NavApiOptions): void {
+        if (!options.path) {
+            throw new Error("The 'path' parameter is required for the Nav API");
+        }
+    }
+}
+
+/**
+ * `dotcmsClient` is an object that provides a method to initialize the DotCMS SDK client.
+ * It has a single method `init` which takes a configuration object and returns an instance of the `DotCmsClient` class.
+ *
+ * @namespace dotcmsClient
+ *
+ * @method init(config: ClientConfig): DotCmsClient - Initializes the SDK client.
+ */
+export const dotcmsClient = {
+    /**
+     * `init` is a method of the `dotcmsClient` object that initializes the SDK client.
+     * It takes a configuration object as a parameter and returns an instance of the `DotCmsClient` class.
+     *
+     * @method init
+     * @param {ClientConfig} config - The configuration object for the DotCMS client.
+     * @returns {DotCmsClient} - An instance of the {@link DotCmsClient} class.
+     */
+    init: (config: ClientConfig): DotCmsClient => {
+        return new DotCmsClient(config);
+    }
+};

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

@@ -0,0 +1,58 @@
+import {
+    listenEditorMessages,
+    listenHoveredContentlet,
+    pingEditor,
+    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',
+        NOOP: 'noop'
+    }
+}));
+
+/**
+ * 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();
+        expect(addEventListenerSpy).toHaveBeenCalledWith('pointermove', expect.any(Function));
+    });
+
+    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 send ping to editor', () => {
+        pingEditor();
+        expect(postMessageToEditor).toHaveBeenCalledWith({
+            action: CUSTOMER_ACTIONS.PING_EDITOR
+        });
+    });
+});

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

@@ -0,0 +1,195 @@
+import { CUSTOMER_ACTIONS, postMessageToEditor } from '../models/client.model';
+import { DotCMSPageEditorConfig } from '../models/editor.model';
+import { DotCMSPageEditorSubscription, NOTIFY_CUSTOMER } from '../models/listeners.model';
+import {
+    findVTLData,
+    findContentletElement,
+    getClosestContainerData,
+    getPageElementBound
+} from '../utils/editor.utils';
+
+declare global {
+    interface Window {
+        lastScrollYPosition: number;
+    }
+}
+
+/**
+ * Default reload function that reloads the current window.
+ */
+const defaultReloadFn = () => window.location.reload();
+
+/**
+ * Configuration object for the DotCMSPageEditor.
+ */
+let pageEditorConfig: DotCMSPageEditorConfig = {
+    onReload: defaultReloadFn
+};
+
+export function setPageEditorConfig(config: DotCMSPageEditorConfig) {
+    pageEditorConfig = config;
+}
+
+/**
+ * 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() {
+    const containers = Array.from(
+        document.querySelectorAll('[data-dot-object="container"]')
+    ) as HTMLDivElement[];
+    const positionData = getPageElementBound(containers);
+
+    postMessageToEditor({
+        action: CUSTOMER_ACTIONS.SET_BOUNDS,
+        payload: positionData
+    });
+}
+
+/**
+ * Reloads the page and triggers the onReload callback if it exists in the config object.
+ */
+function reloadPage() {
+    pageEditorConfig?.onReload();
+}
+
+/**
+ * Listens for editor messages and performs corresponding actions based on the received message.
+ *
+ * @private
+ * @memberof DotCMSPageEditor
+ */
+export function listenEditorMessages() {
+    const messageCallback = (event: MessageEvent) => {
+        switch (event.data) {
+            case NOTIFY_CUSTOMER.EMA_REQUEST_BOUNDS: {
+                setBounds();
+                break;
+            }
+
+            case NOTIFY_CUSTOMER.EMA_RELOAD_PAGE: {
+                reloadPage();
+                break;
+            }
+        }
+    };
+
+    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() {
+    const pointerMoveCallback = (event: PointerEvent) => {
+        const target = findContentletElement(event.target as HTMLElement);
+        if (!target) return;
+        const { x, y, width, height } = target.getBoundingClientRect();
+
+        const vtlFiles = findVTLData(target);
+        const contentletPayload = {
+            container:
+                // Here extract dot-container from contentlet if is Headless
+                // or search in parent container if is VTL
+                target.dataset?.['dotContainer']
+                    ? JSON.parse(target.dataset?.['dotContainer'])
+                    : getClosestContainerData(target),
+            contentlet: {
+                identifier: target.dataset?.['dotIdentifier'],
+                title: target.dataset?.['dotTitle'],
+                inode: target.dataset?.['dotInode'],
+                contentType: target.dataset?.['dotType'],
+                onNumberOfPages: target.dataset?.['dotOnNumberOfPages']
+            },
+            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() {
+    const scrollCallback = () => {
+        postMessageToEditor({
+            action: CUSTOMER_ACTIONS.IFRAME_SCROLL
+        });
+        window.lastScrollYPosition = window.scrollY;
+    };
+
+    window.addEventListener('scroll', scrollCallback);
+
+    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
+ */
+export function preserveScrollOnIframe() {
+    const preserveScrollCallback = () => {
+        window.scrollTo(0, window.lastScrollYPosition);
+    };
+
+    window.addEventListener('load', preserveScrollCallback);
+    subscriptions.push({
+        type: 'listener',
+        event: 'scroll',
+        callback: preserveScrollCallback
+    });
+}
+
+/**
+ * Sends a ping message to the editor.
+ *
+ */
+export function pingEditor() {
+    postMessageToEditor({
+        action: CUSTOMER_ACTIONS.PING_EDITOR
+    });
+}

package/src/lib/{postMessageToEditor.d.ts → editor/models/client.model.ts}

@@ -4,25 +4,31 @@
  * @export
  * @enum {number}
  */
-export declare enum CUSTOMER_ACTIONS {
+export enum CUSTOMER_ACTIONS {
     /**
      * Tell the dotcms editor that page change
      */
-    SET_URL = "set-url",
+    NAVIGATION_UPDATE = 'set-url',
     /**
      * Send the element position of the rows, columnsm containers and contentlets
      */
-    SET_BOUNDS = "set-bounds",
+    SET_BOUNDS = 'set-bounds',
     /**
      * Send the information of the hovered contentlet
      */
-    SET_CONTENTLET = "set-contentlet",
+    SET_CONTENTLET = 'set-contentlet',
     /**
      * Tell the editor that the page is being scrolled
      */
-    IFRAME_SCROLL = "scroll",
-    NOOP = "noop"
+    IFRAME_SCROLL = 'scroll',
+    /**
+     * Ping the editor to see if the page is inside the editor
+     */
+    PING_EDITOR = 'ping-editor',
+
+    NOOP = 'noop'
 }
+
 /**
  * Post message props
  *
@@ -34,6 +40,7 @@ type PostMessageProps<T> = {
     action: CUSTOMER_ACTIONS;
     payload?: T;
 };
+
 /**
  * Post message to dotcms page editor
  *
@@ -41,5 +48,6 @@ type PostMessageProps<T> = {
  * @template T
  * @param {PostMessageProps<T>} message
  */
-export declare function postMessageToEditor<T = unknown>(message: PostMessageProps<T>): void;
-export {};
+export function postMessageToEditor<T = unknown>(message: PostMessageProps<T>) {
+    window.parent.postMessage(message, '*');
+}

package/src/lib/editor/models/editor.model.ts

@@ -0,0 +1,17 @@
+/**
+ *
+ * Represents the configuration options for the DotCMS page editor.
+ * @export
+ * @interface DotCMSPageEditorConfig
+ */
+export interface DotCMSPageEditorConfig {
+    /**
+     * A callback function that will be called when the page editor needs to be reloaded.
+     */
+    onReload: () => void;
+
+    /**
+     * The pathname of the page being edited. Optional.
+     */
+    pathname?: string;
+}

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

@@ -0,0 +1,46 @@
+/**
+ * Actions received from the dotcms editor
+ *
+ * @export
+ * @enum {number}
+ */
+export enum NOTIFY_CUSTOMER {
+    /**
+     * Request to page to reload
+     */
+    EMA_RELOAD_PAGE = 'ema-reload-page',
+    /**
+     * Request the bounds for the elements
+     */
+    EMA_REQUEST_BOUNDS = 'ema-request-bounds',
+    /**
+     * Received pong from the editor
+     */
+    EMA_EDITOR_PONG = 'ema-editor-pong'
+}
+
+type ListenerCallbackMessage = (event: MessageEvent) => void;
+type ListenerCallbackPointer = (event: PointerEvent) => void;
+
+/**
+ * Listener for the dotcms editor
+ *
+ * @interface DotCMSPageEditorListener
+ */
+interface DotCMSPageEditorListener {
+    type: 'listener';
+    event: string;
+    callback: ListenerCallbackMessage | ListenerCallbackPointer;
+}
+
+/**
+ * Observer for the dotcms editor
+ *
+ * @interface DotCMSPageEditorObserver
+ */
+interface DotCMSPageEditorObserver {
+    type: 'observer';
+    observer: MutationObserver;
+}
+
+export type DotCMSPageEditorSubscription = DotCMSPageEditorListener | DotCMSPageEditorObserver;

package/src/lib/editor/sdk-editor-vtl.ts

@@ -0,0 +1,32 @@
+import {
+    listenEditorMessages,
+    listenHoveredContentlet,
+    pingEditor,
+    preserveScrollOnIframe,
+    scrollHandler
+} from './listeners/listeners';
+import { isInsideEditor } from './sdk-editor';
+
+declare global {
+    interface Window {
+        lastScrollYPosition: number;
+    }
+}
+
+/**
+ * This is the main entry point for the SDK VTL.
+ * This is added to VTL Script in the EditPage
+ *
+ * @remarks
+ * This module sets up the necessary listeners and functionality for the SDK VTL.
+ * It checks if the script is running inside the editor and then initializes the client by pinging the editor,
+ * listening for editor messages, hovered contentlet changes, and content changes.
+ *
+ */
+if (isInsideEditor()) {
+    pingEditor();
+    listenEditorMessages();
+    scrollHandler();
+    preserveScrollOnIframe();
+    listenHoveredContentlet();
+}