@dotcms/client 0.0.1-alpha.9 → 0.0.1-beta.2

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

@@ -0,0 +1,276 @@
+import { Content } from './content/content-api';
+export type ClientOptions = Omit<RequestInit, 'body' | 'method'>;
+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. If not  provided, it will use the default site.
+     *
+     * More information here: {@link https://www.dotcms.com/docs/latest/multi-site-management}
+     *
+     * @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}
+     * @optional
+     */
+    siteId?: string;
+    /**
+     * The authentication token to use for the requests.
+     *
+     * @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 {ClientOptions}
+     * @optional
+     */
+    requestOptions?: ClientOptions;
+}
+export 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.
+     *
+     * More information here: {@link https://www.dotcms.com/docs/latest/multi-site-management}
+     * @type {string}
+     * @optional
+     */
+    siteId?: string;
+    /**
+     * The mode of the page you want to retrieve. If not provided, will use the default mode of the site.
+     *
+     * More information here: {@link https://www.dotcms.com/docs/latest/page-viewing-modes}
+     * @type {string}
+     * @optional
+     */
+    mode?: 'EDIT_MODE' | 'PREVIEW_MODE' | 'LIVE';
+    /**
+     * The language id of the page you want to retrieve. If not provided, will use the default language of the site.
+     * @type {number}
+     * @optional
+     */
+    language_id?: number;
+    /**
+     * The id of the persona you want to retrieve the page for.
+     *
+     * More information here: {@link https://www.dotcms.com/docs/latest/personas}
+     * @type {string}
+     * @optional
+     */
+    personaId?: string;
+    /**
+     * If you want to fire the rules set on the page.
+     *
+     * More information here: {@link https://www.dotcms.com/docs/latest/adding-rules-to-pages}
+     *
+     * @type {boolean}
+     * @optional
+     */
+    fireRules?: boolean;
+    /**
+     * Allows access to related content via the Relationship fields of contentlets on a Page; 0 (default).
+     * @type {number}
+     * @optional
+     */
+    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}
+     * @optional
+     */
+    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}
+     * @optional
+     */
+    languageId?: number;
+};
+/**
+ * `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.
+ *
+ * @class DotCmsClient
+ * @property {ClientConfig} config - The configuration object for the DotCMS client.
+ * @property {Content} content - Provides methods to interact with content in DotCMS.
+ *
+ * @method constructor(config: ClientConfig) - Constructs a new instance of the DotCmsClient class.
+ *
+ * @method page.get(options: PageApiOptions): Promise<PageApiResponse> - Retrieves all the elements of any Page in your dotCMS system in JSON format.
+ * The Page API enables you to retrieve page information, layout, template, content blocks, and more.
+ * @see {@link https://www.dotcms.com/docs/latest/page-rest-api-layout-as-a-service-laas}
+ *
+ * @method nav.get(options: NavApiOptions = { depth: 0, path: '/', languageId: 1 }): Promise<NavApiResponse> - Retrieves information about the dotCMS file and folder tree.
+ * The Navigation API allows you to fetch the site structure and menu items.
+ * @see {@link https://www.dotcms.com/docs/latest/navigation-rest-api}
+ *
+ * @method content.get(options: ContentApiOptions): Promise<ContentApiResponse> - Retrieves content items based on specified criteria.
+ * The Content API allows you to query and retrieve content by ID, inode, or using Lucene queries.
+ * @see {@link https://www.dotcms.com/docs/latest/content-api-retrieval-and-querying}
+ *
+ * @method editor.on(action: string, callbackFn: (payload: unknown) => void) - Allows you to react to actions issued by the Universal Visual Editor (UVE).
+ * @method editor.off(action: string) - Stops listening to an action issued by UVE.
+ *
+ * @static
+ * @method init(config: ClientConfig): DotCmsClient - Initializes and returns a DotCmsClient instance.
+ * @method dotcmsUrl: string - Retrieves the DotCMS URL from the instance configuration.
+ *
+ * @example <caption>Basic usage</caption>
+ * ```javascript
+ * const client = DotCmsClient.init({ dotcmsUrl: 'https://demo.dotcms.com', authToken: 'your-auth-token' });
+ *
+ * // Get a page
+ * client.page.get({ path: '/about-us' }).then(response => console.log(response));
+ *
+ * // Get navigation
+ * client.nav.get({ path: '/about-us', depth: 2 }).then(response => console.log(response));
+ *
+ * // Get content
+ * client.content.get({ query: '+contentType:Blog +languageId:1', limit: 10 }).then(response => console.log(response));
+ *
+ * // Listen to editor changes
+ * client.editor.on('changes', (payload) => console.log('Changes detected:', payload));
+ * ```
+ */
+export declare class DotCmsClient {
+    #private;
+    static instance: DotCmsClient;
+    dotcmsUrl?: string;
+    content: Content;
+    constructor(config?: ClientConfig);
+    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.
+         * @example
+         * ```ts
+         * const client = new DotCmsClient({ dotcmsUrl: 'https://your.dotcms.com', authToken: 'your-auth-token', siteId: 'your-site-id' });
+         * client.page.get({ path: '/about-us' }).then(response => console.log(response));
+         * ```
+         */
+        get: (options: PageApiOptions) => Promise<unknown>;
+    };
+    editor: {
+        /**
+         * `editor.on` is an asynchronous method of the `DotCmsClient` class that allows you to react to actions issued by the UVE.
+         *
+         *  NOTE: This is being used by the development team - This logic is probably varied or moved to another function/object.
+         * @param {string} action - The name of the action emitted by UVE.
+         * @param {function} callbackFn - The function to execute when the UVE emits the action.
+         * @example
+         * ```ts
+         * client.editor.on('changes', (payload) => {
+         *     console.log('Changes detected:', payload);
+         * });
+         * ```
+         */
+        on: (action: string, callbackFn: (payload: unknown) => void) => void;
+        /**
+         * `editor.off` is a synchronous method of the `DotCmsClient` class that allows you to stop listening and reacting to an action issued by UVE.
+         *
+         * NOTE: This is being used by the development team - This logic is probably varied or moved to another function/object.
+         * @param {string} action - The name of the action to stop listening to.
+         * @example
+         * ```ts
+         * client.editor.off('changes');
+         * ```
+         */
+        off: (action: string) => void;
+    };
+    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.
+         * @example
+         * ```ts
+         * const client = new DotCmsClient({ dotcmsUrl: 'https://your.dotcms.com', authToken: 'your-auth-token', siteId: 'your-site-id' }});
+         * client.nav.get({ path: '/about-us', depth: 2 }).then(response => console.log(response));
+         * ```
+         */
+        get: (options?: NavApiOptions) => Promise<unknown>;
+    };
+    /**
+     * Initializes the DotCmsClient instance with the provided configuration.
+     * If an instance already exists, it returns the existing instance.
+     *
+     * @param {ClientConfig} config - The configuration object for the DotCMS client.
+     * @returns {DotCmsClient} - The initialized DotCmsClient instance.
+     * @example
+     * ```ts
+     * const client = DotCmsClient.init({ dotcmsUrl: 'https://demo.dotcms.com', authToken: 'your-auth-token' });
+     * ```
+     */
+    static init(config: ClientConfig): DotCmsClient;
+    /**
+     * Retrieves the DotCMS URL from the instance configuration.
+     *
+     * @returns {string} - The DotCMS URL.
+     */
+    static get dotcmsUrl(): string;
+    /**
+     * Throws an error if the path is not valid.
+     *
+     * @returns {string} - The authentication token.
+     */
+    private validatePageOptions;
+    /**
+     * Throws an error if the path is not valid.
+     *
+     *  @returns {string} - The authentication token.
+     */
+    private validateNavOptions;
+}
+export {};

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

@@ -0,0 +1,45 @@
+import { DotCMSPageEditorSubscription } from '../models/listeners.model';
+/**
+ * Represents an array of DotCMSPageEditorSubscription objects.
+ * Used to store the subscriptions for the editor and unsubscribe later.
+ */
+export declare const subscriptions: DotCMSPageEditorSubscription[];
+/**
+ * Listens for editor messages and performs corresponding actions based on the received message.
+ *
+ * @private
+ * @memberof DotCMSPageEditor
+ */
+export declare function listenEditorMessages(): void;
+/**
+ * Listens for pointer move events and extracts information about the hovered contentlet.
+ *
+ * @private
+ * @memberof DotCMSPageEditor
+ */
+export declare function listenHoveredContentlet(): void;
+/**
+ * Attaches a scroll event listener to the window
+ * and sends a message to the editor when the window is scrolled.
+ *
+ * @private
+ * @memberof DotCMSPageEditor
+ */
+export declare function scrollHandler(): void;
+/**
+ * Restores the scroll position of the window when an iframe is loaded.
+ * Only used in VTL Pages.
+ * @export
+ * @example
+ * ```ts
+ * preserveScrollOnIframe();
+ * ```
+ */
+export declare function preserveScrollOnIframe(): void;
+/**
+ * Sends a message to the editor to get the page data.
+ * @param {string} pathname - The pathname of the page.
+ * @private
+ * @memberof DotCMSPageEditor
+ */
+export declare function fetchPageDataFromInsideUVE(pathname: string): void;

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

@@ -0,0 +1,98 @@
+import { editContentlet, initInlineEditing, reorderMenu } from '../sdk-editor';
+declare global {
+    interface Window {
+        dotUVE: DotUVE;
+    }
+}
+export declare const INITIAL_DOT_UVE: DotUVE;
+/**
+ * Actions send to the dotcms editor
+ *
+ * @export
+ * @enum {number}
+ */
+export declare enum CLIENT_ACTIONS {
+    /**
+     * Tell the dotcms editor that page change
+     */
+    NAVIGATION_UPDATE = "set-url",
+    /**
+     * Send the element position of the rows, columnsm containers and contentlets
+     */
+    SET_BOUNDS = "set-bounds",
+    /**
+     * Send the information of the hovered contentlet
+     */
+    SET_CONTENTLET = "set-contentlet",
+    /**
+     * Tell the editor that the page is being scrolled
+     */
+    IFRAME_SCROLL = "scroll",
+    /**
+     * Tell the editor that the page has stopped scrolling
+     */
+    IFRAME_SCROLL_END = "scroll-end",
+    /**
+     * Ping the editor to see if the page is inside the editor
+     */
+    PING_EDITOR = "ping-editor",
+    /**
+     * Tell the editor to init the inline editing editor.
+     */
+    INIT_INLINE_EDITING = "init-inline-editing",
+    /**
+     * Tell the editor to open the Copy-contentlet dialog
+     * To copy a content and then edit it inline.
+     */
+    COPY_CONTENTLET_INLINE_EDITING = "copy-contentlet-inline-editing",
+    /**
+     * Tell the editor to save inline edited contentlet
+     */
+    UPDATE_CONTENTLET_INLINE_EDITING = "update-contentlet-inline-editing",
+    /**
+     * Tell the editor to trigger a menu reorder
+     */
+    REORDER_MENU = "reorder-menu",
+    /**
+     * Tell the editor to send the page info to iframe
+     */
+    GET_PAGE_DATA = "get-page-data",
+    /**
+     * Tell the editor an user send a graphql query
+     */
+    CLIENT_READY = "client-ready",
+    /**
+     * Tell the editor to edit a contentlet
+     */
+    EDIT_CONTENTLET = "edit-contentlet",
+    /**
+     * Tell the editor to do nothing
+     */
+    NOOP = "noop"
+}
+/**
+ * Post message props
+ *
+ * @export
+ * @template T
+ * @interface PostMessageProps
+ */
+type PostMessageProps<T> = {
+    action: CLIENT_ACTIONS;
+    payload?: T;
+};
+/**
+ * Post message to dotcms page editor
+ *
+ * @export
+ * @template T
+ * @param {PostMessageProps<T>} message
+ */
+export declare function postMessageToEditor<T = unknown>(message: PostMessageProps<T>): void;
+export interface DotUVE {
+    editContentlet: typeof editContentlet;
+    initInlineEditing: typeof initInlineEditing;
+    reorderMenu: typeof reorderMenu;
+    lastScrollYPosition: number;
+}
+export {};

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

@@ -0,0 +1,62 @@
+/**
+ * @description Custom client parameters for fetching data.
+ */
+export type CustomClientParams = {
+    depth: string;
+};
+/**
+ * @description Union type for fetch configurations.
+ * @typedef {GraphQLFetchConfig | PageAPIFetchConfig} DotCMSFetchConfig
+ */
+export type EditorConfig = {
+    params: CustomClientParams;
+} | {
+    query: string;
+};
+/**
+ * Represents the configuration options for the DotCMS page editor.
+ * @export
+ * @interface DotCMSPageEditorConfig
+ */
+export interface DotCMSPageEditorConfig {
+    /**
+     * The pathname of the page being edited. Optional.
+     * @type {string}
+     */
+    pathname: string;
+    /**
+     *
+     * @type {DotCMSFetchConfig}
+     * @memberof DotCMSPageEditorConfig
+     * @description The configuration custom params for data fetching on Edit Mode.
+     * @example <caption>Example with Custom GraphQL query</caption>
+     * const config: DotCMSPageEditorConfig = {
+     *   editor: { query: 'query { ... }' }
+     * };
+     *
+     * @example <caption>Example usage with Custom Page API parameters</caption>
+     * const config: DotCMSPageEditorConfig = {
+     *   editor: { params: { depth: '2' } }
+     * };
+     */
+    editor?: EditorConfig;
+    /**
+     * The reload function to call when the page is reloaded.
+     * @deprecated In future implementation we will be listening for the changes from the editor to update the page state so reload will not be needed.
+     * @type {Function}
+     */
+    onReload?: () => void;
+}
+/**
+ * Configuration for reordering a menu.
+ */
+export interface ReorderMenuConfig {
+    /**
+     * The starting level of the menu to be reordered.
+     */
+    startLevel: number;
+    /**
+     * The depth of the menu levels to be reordered.
+     */
+    depth: number;
+}

package/src/lib/editor/models/inline-event.model.d.ts

@@ -0,0 +1,9 @@
+export type INLINE_EDITING_EVENT_KEY = 'BLOCK_EDITOR' | 'WYSIWYG';
+export interface InlineEditorData {
+    inode: string;
+    language: number;
+    contentType: string;
+    fieldName: string;
+    content: Record<string, unknown>;
+}
+export type InlineEditEventData = InlineEditorData;

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

@@ -4,24 +4,34 @@
  * @export
  * @enum {number}
  */
-export enum NOTIFY_CUSTOMER {
+export declare enum NOTIFY_CLIENT {
     /**
      * Request to page to reload
      */
-    EMA_RELOAD_PAGE = 'ema-reload-page',
+    UVE_RELOAD_PAGE = "uve-reload-page",
     /**
      * Request the bounds for the elements
      */
-    EMA_REQUEST_BOUNDS = 'ema-request-bounds',
+    UVE_REQUEST_BOUNDS = "uve-request-bounds",
     /**
      * Received pong from the editor
      */
-    EMA_EDITOR_PONG = 'ema-editor-pong'
+    UVE_EDITOR_PONG = "uve-editor-pong",
+    /**
+     * Received scroll event trigger from the editor
+     */
+    UVE_SCROLL_INSIDE_IFRAME = "uve-scroll-inside-iframe",
+    /**
+     * Set the page data
+     */
+    UVE_SET_PAGE_DATA = "uve-set-page-data",
+    /**
+     * Copy contentlet inline editing success
+     */
+    UVE_COPY_CONTENTLET_INLINE_EDITING_SUCCESS = "uve-copy-contentlet-inline-editing-success"
 }
-
 type ListenerCallbackMessage = (event: MessageEvent) => void;
 type ListenerCallbackPointer = (event: PointerEvent) => void;
-
 /**
  * Listener for the dotcms editor
  *
@@ -32,7 +42,6 @@ interface DotCMSPageEditorListener {
     event: string;
     callback: ListenerCallbackMessage | ListenerCallbackPointer;
 }
-
 /**
  * Observer for the dotcms editor
  *
@@ -42,5 +51,5 @@ interface DotCMSPageEditorObserver {
     type: 'observer';
     observer: MutationObserver;
 }
-
 export type DotCMSPageEditorSubscription = DotCMSPageEditorListener | DotCMSPageEditorObserver;
+export {};

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

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1,92 @@
+import { DotCMSPageEditorConfig, ReorderMenuConfig } from './models/editor.model';
+import { INLINE_EDITING_EVENT_KEY, InlineEditEventData } from './models/inline-event.model';
+import { Contentlet } from '../client/content/shared/types';
+/**
+ * Updates the navigation in the editor.
+ *
+ * @param {string} pathname - The pathname to update the navigation with.
+ * @memberof DotCMSPageEditor
+ * @example
+ * updateNavigation('/home'); // Sends a message to the editor to update the navigation to '/home'
+ */
+export declare function updateNavigation(pathname: string): void;
+/**
+ * You can use this function to edit a contentlet in the editor.
+ *
+ * Calling this function inside the editor, will prompt the UVE to open a dialog to edit the contentlet.
+ *
+ * @export
+ * @template T
+ * @param {Contentlet<T>} contentlet - The contentlet to edit.
+ */
+export declare function editContentlet<T>(contentlet: Contentlet<T>): void;
+/**
+ * Initializes the inline editing in the editor.
+ *
+ * @export
+ * @param {INLINE_EDITING_EVENT_KEY} type
+ * @param {InlineEditEventData} eventData
+ * @return {*}
+ *
+ *  * @example
+ * ```html
+ * <div onclick="initInlineEditing('BLOCK_EDITOR', { inode, languageId, contentType, fieldName, content })">
+ *      ${My Content}
+ * </div>
+ * ```
+ */
+export declare function initInlineEditing(type: INLINE_EDITING_EVENT_KEY, data?: InlineEditEventData): void;
+export declare function reorderMenu(config?: ReorderMenuConfig): void;
+/**
+ * @deprecated Use `getUVEState` function on {@link https://npmjs.com/package/@dotcms/uve|@dotcms/uve} instead, this function will be removed on future versions.
+ *
+ * Checks if the code is running inside the DotCMS Universal Visual Editor (UVE).
+ *
+ * The function checks three conditions:
+ * 1. If window is defined (for SSR environments)
+ * 2. If the page is not in preview mode
+ * 3. If the current window is embedded in a parent frame
+ *
+ * @returns {boolean} Returns true if running inside the UVE editor, false if running standalone or in preview mode
+ * @example
+ * ```ts
+ * // Check if code is running in editor before initializing editor-specific features
+ * if (isInsideEditor()) {
+ *     initEditor(config);
+ * } else {
+ *     initStandaloneMode();
+ * }
+ * ```
+ */
+export declare function isInsideEditor(): boolean;
+export declare function initDotUVE(): void;
+/**
+ * Initializes the DotCMS page editor.
+ *
+ * @param {DotCMSPageEditorConfig} config - Optional configuration for the editor.
+ * @example
+ * ```ts
+ * const config = { pathname: '/home' };
+ * initEditor(config); // Initializes the editor with the provided configuration
+ * ```
+ */
+export declare function initEditor(config: DotCMSPageEditorConfig): void;
+/**
+ * Destroys the editor by removing event listeners and disconnecting observers.
+ *
+ * @example
+ * ```ts
+ * destroyEditor(); // Cleans up the editor by removing all event listeners and disconnecting observers
+ * ```
+ */
+export declare function destroyEditor(): void;
+/**
+ * Adds a style class to empty contentlets.
+ *
+ * @export
+ * @example
+ * ```ts
+ * addClassToEmptyContentlets(); // Adds the 'empty-contentlet' class to all contentlets that have no height
+ * ```
+ */
+export declare function addClassToEmptyContentlets(): void;