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

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

@@ -11,19 +11,19 @@ export interface ClientConfig {
      */
     dotcmsUrl: string;
     /**
-     * The id of the site you want to interact with.
+     * The id of the site you want to interact with. If not  provided, it will use the default site.
      *
-     * @description to get the site id, go to the site you want to interact with and copy the id from the History tab
+     * 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}
-     * @required
+     * @optional
      */
     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}
+     * 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
      */
@@ -38,59 +38,65 @@ export interface ClientConfig {
      */
     requestOptions?: ClientOptions;
 }
-type PageApiOptions = {
+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.
      *
-     * @type {number}
+     * 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.
+     * The mode of the page you want to retrieve. If not provided, will use the default mode of the site.
      *
-     * @type {number}
+     * More information here: {@link https://www.dotcms.com/docs/latest/page-viewing-modes}
+     * @type {string}
+     * @optional
      */
-    mode?: string;
+    mode?: 'EDIT_MODE' | 'PREVIEW_MODE' | 'LIVE_MODE';
     /**
-     * The language id of the page you want to retrieve. If not provided will use the default language of the site.
-     *
+     * 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
+     * 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)
-     *
+     * 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;
@@ -102,35 +108,66 @@ type NavApiOptions = {
      * `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.
- * It requires a configuration object on instantiation, which includes the DotCMS URL, site ID, and authentication token.
+ * 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<unknown> - Retrieves all the elements of any Page in your dotCMS system in JSON format.
+ * @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' });
  *
- * @method nav.get(options: NavApiOptions = { depth: 0, path: '/', languageId: 1 }): Promise<unknown> - Retrieves information about the dotCMS file and folder tree.
+ * // 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;
@@ -151,6 +188,11 @@ export declare class DotCmsClient {
          * @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>;
     };
@@ -159,15 +201,25 @@ export declare class DotCmsClient {
          * `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 action - The name of the name emitted by UVE
-         * @param callbackFn - The function to execute when the UVE emits the action
+         * @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 an synchronous method of the `DotCmsClient` class that allows you to stop listening and reacting to an action issued by UVE.
+         * `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 action
+         * 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;
     };
@@ -182,12 +234,43 @@ export declare class DotCmsClient {
          * @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

@@ -10,7 +10,7 @@ declare global {
  */
 export declare const subscriptions: DotCMSPageEditorSubscription[];
 /**
- * Listens for editor messages and performs corresding actions based on the received message.
+ * Listens for editor messages and performs corresponding actions based on the received message.
  *
  * @private
  * @memberof DotCMSPageEditor
@@ -35,6 +35,10 @@ 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;
 /**

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

@@ -1,29 +1,54 @@
 import { DotCMSPageEditorConfig } from './models/editor.model';
 /**
- *
  * 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;
 /**
  * Checks if the code is running inside an editor.
+ *
  * @returns {boolean} Returns true if the code is running inside an editor, otherwise false.
+ * @example
+ * ```ts
+ * if (isInsideEditor()) {
+ *     console.log('Running inside the editor');
+ * } else {
+ *     console.log('Running outside the editor');
+ * }
+ * ```
  */
 export declare function isInsideEditor(): boolean;
 /**
  * Initializes the DotCMS page editor.
  *
- * @param conf - Optional configuration for the 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 class to empty contentlets.
+ * 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;

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

@@ -2,6 +2,11 @@
  * Bound information for a contentlet.
  *
  * @interface ContentletBound
+ * @property {number} x - The x-coordinate of the contentlet.
+ * @property {number} y - The y-coordinate of the contentlet.
+ * @property {number} width - The width of the contentlet.
+ * @property {number} height - The height of the contentlet.
+ * @property {string} payload - The payload data of the contentlet in JSON format.
  */
 interface ContentletBound {
     x: number;
@@ -14,6 +19,12 @@ interface ContentletBound {
  * Bound information for a container.
  *
  * @interface ContainerBound
+ * @property {number} x - The x-coordinate of the container.
+ * @property {number} y - The y-coordinate of the container.
+ * @property {number} width - The width of the container.
+ * @property {number} height - The height of the container.
+ * @property {string} payload - The payload data of the container in JSON format.
+ * @property {ContentletBound[]} contentlets - An array of contentlets within the container.
  */
 interface ContainerBound {
     x: number;
@@ -27,25 +38,44 @@ interface ContainerBound {
  * Calculates the bounding information for each page element within the given containers.
  *
  * @export
- * @param {HTMLDivElement[]} containers
- * @return {*} An array of objects containing the bounding information for each page element.
+ * @param {HTMLDivElement[]} containers - An array of HTMLDivElement representing the containers.
+ * @return {ContainerBound[]} An array of objects containing the bounding information for each page element.
+ * @example
+ * ```ts
+ * const containers = document.querySelectorAll('.container');
+ * const bounds = getPageElementBound(containers);
+ * console.log(bounds);
+ * ```
  */
 export declare function getPageElementBound(containers: HTMLDivElement[]): ContainerBound[];
 /**
- * An array of objects containing the bounding information for each contentlet inside a container.
+ * Calculates the bounding information for each contentlet inside a container.
  *
  * @export
- * @param {DOMRect} containerRect
- * @param {HTMLDivElement[]} contentlets
- * @return {*}
+ * @param {DOMRect} containerRect - The bounding rectangle of the container.
+ * @param {HTMLDivElement[]} contentlets - An array of HTMLDivElement representing the contentlets.
+ * @return {ContentletBound[]} An array of objects containing the bounding information for each contentlet.
+ * @example
+ * ```ts
+ * const containerRect = container.getBoundingClientRect();
+ * const contentlets = container.querySelectorAll('.contentlet');
+ * const bounds = getContentletsBound(containerRect, contentlets);
+ * console.log(bounds); // Element bounds within the container
+ * ```
  */
 export declare function getContentletsBound(containerRect: DOMRect, contentlets: HTMLDivElement[]): ContentletBound[];
 /**
  * Get container data from VTLS.
  *
  * @export
- * @param {HTMLElement} container
- * @return {*}
+ * @param {HTMLElement} container - The container element.
+ * @return {object} An object containing the container data.
+ * @example
+ * ```ts
+ * const container = document.querySelector('.container');
+ * const data = getContainerData(container);
+ * console.log(data);
+ * ```
  */
 export declare function getContainerData(container: HTMLElement): {
     acceptTypes: string;
@@ -57,8 +87,14 @@ export declare function getContainerData(container: HTMLElement): {
  * Get the closest container data from the contentlet.
  *
  * @export
- * @param {Element} element
- * @return {*}
+ * @param {Element} element - The contentlet element.
+ * @return {object | null} An object containing the closest container data or null if no container is found.
+ * @example
+ * ```ts
+ * const contentlet = document.querySelector('.contentlet');
+ * const data = getClosestContainerData(contentlet);
+ * console.log(data);
+ * ```
  */
 export declare function getClosestContainerData(element: Element): {
     acceptTypes: string;
@@ -70,14 +106,54 @@ export declare function getClosestContainerData(element: Element): {
  * Find the closest contentlet element based on HTMLElement.
  *
  * @export
- * @param {(HTMLElement | null)} element
- * @return {*}
+ * @param {HTMLElement | null} element - The starting element.
+ * @return {HTMLElement | null} The closest contentlet element or null if not found.
+ * @example
+ * const element = document.querySelector('.some-element');
+ * const contentlet = findDotElement(element);
+ * console.log(contentlet);
  */
 export declare function findDotElement(element: HTMLElement | null): HTMLElement | null;
+/**
+ * Find the closest VTL file element based on HTMLElement.
+ *
+ * @export
+ * @param {HTMLElement | null} element - The starting element.
+ * @return {HTMLElement | null} The closest VTL file element or null if not found.
+ * @example
+ * const element = document.querySelector('.some-element');
+ * const vtlFile = findDotVTLElement(element);
+ * console.log(vtlFile);
+ */
 export declare function findDotVTLElement(element: HTMLElement | null): HTMLElement | null;
+/**
+ * Find VTL data within a target element.
+ *
+ * @export
+ * @param {HTMLElement} target - The target element to search within.
+ * @return {Array<{ inode: string, name: string }> | null} An array of objects containing VTL data or null if none found.
+ * @example
+ * ```ts
+ * const target = document.querySelector('.target-element');
+ * const vtlData = findVTLData(target);
+ * console.log(vtlData);
+ * ```
+ */
 export declare function findVTLData(target: HTMLElement): {
     inode: string | undefined;
     name: string | undefined;
 }[] | null;
+/**
+ * Check if the scroll position is at the bottom of the page.
+ *
+ * @export
+ * @return {boolean} True if the scroll position is at the bottom, otherwise false.
+ * @example
+ * ```ts
+ * if (scrollIsInBottom()) {
+ *     console.log('Scrolled to the bottom');
+ * }
+ * ```
+ */
 export declare function scrollIsInBottom(): boolean;
 export {};

package/src/lib/query-builder/lucene-syntax/Equals.d.ts

@@ -17,7 +17,11 @@ export declare class Equals {
     /**
      * This method appends to the query a term that should be excluded in the search.
      *
-     * Ex: "-myValue"
+     * @example
+     * ```ts
+     * const equals = new Equals("+myField: myValue");
+     * equals.excludeField("myField2").equals("myValue2"); // Current query: "+myField: myValue -myField2: myValue2"
+     * ```
      *
      * @param {string} field - The field that should be excluded in the search.
      * @return {*}  {Field} - An instance of a Lucene Field. A field is a key used to search for a specific value in a document.
@@ -27,8 +31,11 @@ export declare class Equals {
     /**
      * This method appends to the query a field that should be included in the search.
      *
-     * Ex: "+myField:"
-     *
+     * @example
+     * ```ts
+     * const equals = new Equals("+myField: myValue");
+     * equals.field("myField2").equals("myValue2");  // Current query: "+myField: myValue +myField2: myValue2"
+     *```
      * @param {string} field - The field that should be included in the search.
      * @return {*}  {Field} - An instance of a Lucene Field. A field is a key used to search for a specific value in a document.
      * @memberof Equal
@@ -37,7 +44,12 @@ export declare class Equals {
     /**
      * This method appends to the query an operand to use logic operators in the query.
      *
-     * Ex: "OR"
+     * @example
+     * @example
+     * ```ts
+     * const equals = new Equals("+myField: myValue");
+     * equals.or().field("myField2").equals("myValue2"); // Current query: "+myField: myValue OR +myField2: myValue2"
+     * ```
      *
      * @return {*}  {Operand} - An instance of a Lucene Operand. An operand is a logical operator used to combine terms or phrases in a query.
      * @memberof Equal
@@ -46,7 +58,11 @@ export declare class Equals {
     /**
      * This method appends to the query an operand to use logic operators in the query.
      *
-     * Ex: "AND"
+     * @example
+     * ```ts
+     * const equals = new Equals("+myField: myValue");
+     * equals.and().field("myField2").equals("myValue2"); // Current query: "+myField: myValue AND +myField2: myValue2"
+     * ```
      *
      * @return {*}  {Operand} - An instance of a Lucene Operand. An operand is a logical operator used to combine terms or phrases in a query.
      * @memberof Equal
@@ -55,7 +71,11 @@ export declare class Equals {
     /**
      * This method appends to the query an operand to use logic operators in the query.
      *
-     * Ex: "NOT"
+     * @example
+     * ```ts
+     * const equals = new Equals("+myField: myValue");
+     * equals.not().field("myField").equals("myValue2"); // Current query: "+myField: myValue NOT +myField: myValue2"
+     * ```
      *
      * @return {*}  {NotOperand} - An instance of a Lucene Not Operand. A not operand is a logical operator used to exclude terms or phrases in a query.
      * @memberof Equal
@@ -66,7 +86,12 @@ export declare class Equals {
      * This raw query should end in a Lucene Equal.
      * This method is useful when you want to append a complex query or an already written query to the query builder.
      *
-     * Ex: "+myField: value AND (someOtherValue OR anotherValue)"
+     * @example
+     * ```ts
+     * // This builds the follow raw query "+myField: value AND (someOtherValue OR anotherValue)"
+     * const equals = new Equals("+myField: value");
+     * equals.raw("+myField2: value2"); // Current query: "+myField: value +myField2: anotherValue"
+     * ```
      *
      * @param {string} query - A raw query string.
      * @return {*}  {Equal} - An instance of a Lucene Equal. A term is a value used to search for a specific value in a document.
@@ -76,6 +101,12 @@ export declare class Equals {
     /**
      * This method returns the final query string.
      *
+     * @example
+     * ```ts
+     * const equals = new Equals("+myField: myValue");
+     * equals.field("myField2").equals("myValue2").build(); // Returns "+myField: myValue +myField2: myValue2"
+     * ```
+     *
      * @return {*}  {string} - The final query string.
      * @memberof Equal
      */

package/src/lib/query-builder/lucene-syntax/Field.d.ts

@@ -1,6 +1,6 @@
 import { Equals } from './Equals';
 /**
- * 'Field' class is used to build a query with a field.
+ * The `Field` class is used to build a query with a specific field.
  * A Lucene Field is a key used to search for a specific value in a document.
  *
  * @export
@@ -9,14 +9,23 @@ import { Equals } from './Equals';
 export declare class Field {
     #private;
     private query;
+    /**
+     * Creates an instance of the `Field` class.
+     *
+     * @param {string} query - The initial query string.
+     */
     constructor(query: string);
     /**
-     * This method appends to the query a term that should be included in the search..
+     * Appends a term to the query that should be included in the search.
      *
-     * Ex: myValue or "My value"
+     * @example
+     * ```typescript
+     * const field = new Field("+myField");
+     * field.equals("myValue");
+     * ```
      *
      * @param {string} term - The term that should be included in the search.
-     * @return {*}  {Equals} - An instance of Equals.
+     * @return {Equals} - An instance of `Equals`.
      * @memberof Field
      */
     equals(term: string): Equals;

package/src/lib/query-builder/lucene-syntax/NotOperand.d.ts

@@ -12,7 +12,11 @@ export declare class NotOperand {
     /**
      * This method appends to the query a term that should be included in the search.
      *
-     * Ex: myValue or "My value"
+     * @example
+     * ```typescript
+     * const notOperand = new NotOperand("+myField");
+     * notOperand.equals("myValue");
+     * ```
      *
      * @param {string} term - The term that should be included in the search.
      * @return {*}  {Equals} - An instance of Equals.