@dotcms/client 0.0.1-alpha.4 → 0.0.1-alpha.41

package/package.json

@@ -1,11 +1,13 @@
 {
   "name": "@dotcms/client",
-  "version": "0.0.1-alpha.4",
-  "type": "module",
+  "version": "0.0.1-alpha.41",
   "description": "Official JavaScript library for interacting with DotCMS REST APIs.",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/dotCMS/core.git#master"
+    "url": "git+https://github.com/dotCMS/core.git#main"
+  },
+  "scripts": {
+    "build": "nx run sdk-client:build:js; cd ../../../../dotCMS/src/main/webapp/html/js/editor-js; rm -rf src package.json *.esm.d.ts"
   },
   "keywords": [
     "dotCMS",
@@ -19,7 +21,17 @@
   "bugs": {
     "url": "https://github.com/dotCMS/core/issues"
   },
-  "homepage": "https://github.com/dotCMS/core/tree/master/core-web/libs/sdk/client/README.md",
-  "module": "./src/index.js",
-  "main": "./src/index.js"
-}
+  "homepage": "https://github.com/dotCMS/core/tree/main/core-web/libs/sdk/client/README.md",
+  "exports": {
+    "./package.json": "./package.json",
+    ".": {
+      "module": "./index.esm.js",
+      "types": "./index.esm.d.ts",
+      "import": "./index.cjs.mjs",
+      "default": "./index.cjs.js"
+    }
+  },
+  "module": "./index.esm.js",
+  "main": "./index.cjs.js",
+  "types": "./index.esm.d.ts"
+}

package/src/index.d.ts

@@ -1,2 +1,6 @@
-export * from './lib/sdk-js-client';
-export * from './lib/postMessageToEditor';
+import { ClientConfig, DotCmsClient } from './lib/client/sdk-js-client';
+import { CUSTOMER_ACTIONS, postMessageToEditor } from './lib/editor/models/client.model';
+import { CustomClientParams, DotCMSPageEditorConfig, EditorConfig } from './lib/editor/models/editor.model';
+import { destroyEditor, initEditor, isInsideEditor, updateNavigation } from './lib/editor/sdk-editor';
+import { getPageRequestParams, graphqlToPageEntity } from './lib/utils';
+export { graphqlToPageEntity, getPageRequestParams, isInsideEditor, DotCmsClient, DotCMSPageEditorConfig, CUSTOMER_ACTIONS, CustomClientParams, postMessageToEditor, EditorConfig, initEditor, updateNavigation, destroyEditor, ClientConfig };

package/src/lib/client/content/builders/collection/collection.d.ts

@@ -0,0 +1,226 @@
+import { ClientOptions } from '../../../sdk-js-client';
+import { GetCollectionResponse, BuildQuery, SortBy, GetCollectionError, OnFullfilled, OnRejected } from '../../shared/types';
+/**
+ * Creates a Builder to filter and fetch content from the content API for a specific content type.
+ *
+ * @export
+ * @class CollectionBuilder
+ * @template T Represents the type of the content type to fetch. Defaults to unknown.
+ */
+export declare class CollectionBuilder<T = unknown> {
+    #private;
+    /**
+     * Creates an instance of CollectionBuilder.
+     * @param {ClientOptions} requestOptions Options for the client request.
+     * @param {string} serverUrl The server URL.
+     * @param {string} contentType The content type to fetch.
+     * @memberof CollectionBuilder
+     */
+    constructor(requestOptions: ClientOptions, serverUrl: string, contentType: string);
+    /**
+     * Returns the sort query in the format: field order, field order, ...
+     *
+     * @readonly
+     * @private
+     * @memberof CollectionBuilder
+     */
+    private get sort();
+    /**
+     * Returns the offset for pagination.
+     *
+     * @readonly
+     * @private
+     * @memberof CollectionBuilder
+     */
+    private get offset();
+    /**
+     * Returns the full URL for the content API.
+     *
+     * @readonly
+     * @private
+     * @memberof CollectionBuilder
+     */
+    private get url();
+    /**
+     * Returns the current query built.
+     *
+     * @readonly
+     * @private
+     * @memberof CollectionBuilder
+     */
+    private get currentQuery();
+    /**
+     * Filters the content by the specified language ID.
+     *
+     * @example
+     * ```typescript
+     * const client = new DotCMSClient(config);
+     * const collectionBuilder = client.content.getCollection("Blog");
+     * collectionBuilder.language(1);
+     * ```
+     *
+     * @param {number | string} languageId The language ID to filter the content by.
+     * @return {CollectionBuilder} A CollectionBuilder instance.
+     * @memberof CollectionBuilder
+     */
+    language(languageId: number | string): this;
+    /**
+     * Setting this to true will server side render (using velocity) any widgets that are returned by the content query.
+     *
+     * More information here: {@link https://www.dotcms.com/docs/latest/content-api-retrieval-and-querying#ParamsOptional}
+     *
+     * @return {CollectionBuilder} A CollectionBuilder instance.
+     * @memberof CollectionBuilder
+     */
+    render(): this;
+    /**
+     * Sorts the content by the specified fields and orders.
+     *
+     * @example
+     * ```typescript
+     * const client = new DotCMSClient(config);
+     * const collectionBuilder = client.content.getCollection("Blog");
+     * const sortBy = [{ field: 'title', order: 'asc' }, { field: 'modDate', order: 'desc' }];
+     * collectionBuilder("Blog").sortBy(sortBy);
+     * ```
+     *
+     * @param {SortBy[]} sortBy Array of constraints to sort the content by.
+     * @return {CollectionBuilder} A CollectionBuilder instance.
+     * @memberof CollectionBuilder
+     */
+    sortBy(sortBy: SortBy[]): this;
+    /**
+     * Sets the maximum amount of content to fetch.
+     *
+     * @param {number} limit The maximum amount of content to fetch.
+     * @return {CollectionBuilder} A CollectionBuilder instance.
+     * @memberof CollectionBuilder
+     */
+    limit(limit: number): this;
+    /**
+     * Sets the page number to fetch.
+     *
+     * @param {number} page The page number to fetch.
+     * @return {CollectionBuilder} A CollectionBuilder instance.
+     * @memberof CollectionBuilder
+     */
+    page(page: number): this;
+    /**
+     * Filters the content by a Lucene query string.
+     *
+     * @param {string} query A Lucene query string.
+     * @return {CollectionBuilder} A CollectionBuilder instance.
+     * @memberof CollectionBuilder
+     */
+    query(query: string): this;
+    /**
+     * Filters the content by building a query using a QueryBuilder function.
+     *
+     * @example
+     * ```typescript
+     * const client = new DotCMSClient(config);
+     * const collectionBuilder = client.content.getCollection("Blog");
+     * collectionBuilder.query((queryBuilder) =>
+     *     queryBuilder.field('title').equals('Hello World').or().equals('Hello World 2')
+     * );
+     * ```
+     *
+     * @param {BuildQuery} buildQuery A function that receives a QueryBuilder instance and returns a valid query.
+     * @return {CollectionBuilder} A CollectionBuilder instance.
+     * @memberof CollectionBuilder
+     */
+    query(buildQuery: BuildQuery): this;
+    /**
+     * Retrieves draft content.
+     * @example
+     * ```ts
+     * const client = new DotCMSClient(config);
+     * const collectionBuilder = client.content.getCollection("Blog");
+     * collectionBuilder
+     *      .draft() // This will retrieve draft/working content
+     *      .then((response) => // Your code here })
+     *      .catch((error) => // Your code here })
+     * ```
+     *
+     * @return {CollectionBuilder} A CollectionBuilder instance.
+     * @memberof CollectionBuilder
+     */
+    draft(): this;
+    /**
+     * Filters the content by a variant ID for [Experiments](https://www.dotcms.com/docs/latest/experiments-and-a-b-testing)
+     *
+     * More information here: {@link https://www.dotcms.com/docs/latest/content-api-retrieval-and-querying#ParamsOptional}
+     *
+     * @example
+     * ```ts
+     * const client = new DotCMSClient(config);
+     * const collectionBuilder = client.content.getCollection("Blog");
+     * collectionBuilder
+     *      .variant("YOUR_VARIANT_ID")
+     *      .then((response) => // Your code here })
+     *      .catch((error) => // Your code here })
+     * ```
+     *
+     * @param {string} variantId A string that represents a variant ID.
+     * @return {CollectionBuilder} A CollectionBuilder instance.
+     * @memberof CollectionBuilder
+     */
+    variant(variantId: string): this;
+    /**
+     * Sets the depth of the relationships of the content.
+     * Specifies the depth of related content to return in the results.
+     *
+     * More information here: {@link https://www.dotcms.com/docs/latest/content-api-retrieval-and-querying#ParamsOptional}
+     *
+     * @example
+     * ```ts
+     * const client = new DotCMSClient(config);
+     * const collectionBuilder = client.content.getCollection("Blog");
+     * collectionBuilder
+     *      .depth(1)
+     *      .then((response) => // Your code here })
+     *      .catch((error) => // Your code here })
+     * ```
+     *
+     * @param {number} depth The depth of the relationships of the content.
+     * @return {CollectionBuilder} A CollectionBuilder instance.
+     * @memberof CollectionBuilder
+     */
+    depth(depth: number): this;
+    /**
+     * Executes the fetch and returns a promise that resolves to the content or rejects with an error.
+     *
+     * @example
+     * ```ts
+     * const client = new DotCMSClient(config);
+     * const collectionBuilder = client.content.getCollection("Blog");
+     * collectionBuilder
+     *      .limit(10)
+     *      .then((response) => // Your code here })
+     *      .catch((error) => // Your code here })
+     * ```
+     *
+     * @param {OnFullfilled} [onfulfilled] A callback that is called when the fetch is successful.
+     * @param {OnRejected} [onrejected] A callback that is called when the fetch fails.
+     * @return {Promise<GetCollectionResponse<T> | GetCollectionError>} A promise that resolves to the content or rejects with an error.
+     * @memberof CollectionBuilder
+     */
+    then(onfulfilled?: OnFullfilled<T>, onrejected?: OnRejected): Promise<GetCollectionResponse<T> | GetCollectionError>;
+    /**
+     * Formats the response to the desired format.
+     *
+     * @private
+     * @param {GetCollectionRawResponse<T>} data The raw response data.
+     * @return {GetCollectionResponse<T>} The formatted response.
+     * @memberof CollectionBuilder
+     */
+    private formatResponse;
+    /**
+     * Calls the content API to fetch the content.
+     *
+     * @private
+     * @return {Promise<Response>} The fetch response.
+     * @memberof CollectionBuilder
+     */
+    private fetch;
+}

package/src/lib/client/content/content-api.d.ts

@@ -0,0 +1,129 @@
+import { CollectionBuilder } from './builders/collection/collection';
+import { ClientOptions } from '../sdk-js-client';
+/**
+ * Creates a builder to filter and fetch a collection of content items.
+ * @param contentType - The content type to retrieve.
+ * @returns A CollectionBuilder instance for chaining filters and executing the query.
+ * @template T - The type of the content items (defaults to unknown).
+ *
+ * @example Fetch blog posts with async/await
+ * ```typescript
+ * const response = await client.content
+ *     .getCollection<BlogPost>('Blog')
+ *     .limit(10)
+ *     .page(2)
+ *     .sortBy([{ field: 'title', order: 'asc' }])
+ *     .query(q => q.field('author').equals('John Doe'))
+ *     .depth(1)
+ *     .fetch();
+ *
+ * console.log(response.contentlets);
+ * ```
+ *
+ * @example Fetch blog posts with Promise chain
+ * ```typescript
+ * client.content
+ *     .getCollection<BlogPost>('Blog')
+ *     .limit(10)
+ *     .page(2)
+ *     .sortBy([{ field: 'title', order: 'asc' }])
+ *     .query(q => q.field('author').equals('John Doe'))
+ *     .depth(1)
+ *     .fetch()
+ *     .then(response => console.log(response.contentlets))
+ *     .catch(error => console.error(error));
+ * ```
+ *
+ * @example Using a custom type
+ * ```typescript
+ * interface BlogPost {
+ *     summary: string;
+ *     author: string;
+ *     title: string;
+ * }
+ *
+ * const posts = await client.content
+ *     .getCollection<BlogPost>('Blog')
+ *     .limit(10)
+ *     .fetch();
+ *
+ * posts.contentlets.forEach(post => {
+ *     console.log(post.title, post.author, post.summary);
+ * });
+ * ```
+ */
+export declare class Content {
+    #private;
+    /**
+     * Creates an instance of Content.
+     * @param {ClientOptions} requestOptions - The options for the client request.
+     * @param {string} serverUrl - The server URL.
+     */
+    constructor(requestOptions: ClientOptions, serverUrl: string);
+    /**
+     * Takes a content type and returns a builder to filter and fetch the collection.
+     * @param {string} contentType - The content type to get the collection.
+     * @return {CollectionBuilder<T>} CollectionBuilder to filter and fetch the collection.
+     * @template T - Represents the type of the content type to fetch. Defaults to unknown.
+     * @memberof Content
+     *
+     * @example
+     * ```javascript
+     * // Using await and async
+     * const collectionResponse = await client.content
+     *     .getCollection('Blog')
+     *     .limit(10)
+     *     .page(2)
+     *     .sortBy([{ field: 'title', order: 'asc' }])
+     *     .query((queryBuilder) => queryBuilder.field('author').equals('John Doe'))
+     *     .depth(1);
+     * ```
+     * @example
+     * ```javascript
+     * // Using then and catch
+     * client.content
+     *      .getCollection('Blog')
+     *      .limit(10)
+     *      .page(2)
+     *      .sortBy([{ field: 'title', order: 'asc' }])
+     *      .query((queryBuilder) => queryBuilder.field('author').equals('John Doe'))
+     *      .depth(1)
+     *      .then((response) => {
+     *          console.log(response.contentlets);
+     *      })
+     *      .catch((error) => {
+     *          console.error(error);
+     *      });
+     * ```
+     * @example
+     * ```typescript
+     * // Using a specific type for your content
+     *
+     * type Blog = {
+     *     summary: string;
+     *     author: string;
+     *     title: string;
+     * };
+     *
+     * client.content
+     *     .getCollection<Blog>('Blog')
+     *     .limit(10)
+     *     .page(2)
+     *     .sortBy([{ field: 'title', order: 'asc' }])
+     *     .query((queryBuilder) => queryBuilder.field('author').equals('John Doe'))
+     *     .depth(1)
+     *     .then((response) => {
+     *         response.contentlets.forEach((blog) => {
+     *             console.log(blog.title);
+     *             console.log(blog.author);
+     *             console.log(blog.summary);
+     *         });
+     *     })
+     *     .catch((error) => {
+     *         console.error(error);
+     *     });
+     * ```
+     *
+     */
+    getCollection<T = unknown>(contentType: string): CollectionBuilder<T>;
+}

package/src/lib/client/content/shared/const.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Default variant identifier used in the application.
+ */
+export declare const DEFAULT_VARIANT_ID = "DEFAULT";
+/**
+ * Fields that should not be formatted when sanitizing the query.
+ * These fields are essential for maintaining the integrity of the content type.
+ */
+export declare const CONTENT_TYPE_MAIN_FIELDS: string[];
+/**
+ * URL endpoint for the content API search functionality.
+ */
+export declare const CONTENT_API_URL = "/api/content/_search";

package/src/lib/client/content/shared/types.d.ts

@@ -0,0 +1,138 @@
+import { Equals } from '../../../query-builder/lucene-syntax';
+import { QueryBuilder } from '../../../query-builder/sdk-query-builder';
+/**
+ * Model to sort by fields.
+ */
+export type SortBy = {
+    /**
+     * The field to sort by.
+     */
+    field: string;
+    /**
+     * The order of sorting: 'asc' for ascending, 'desc' for descending.
+     */
+    order: 'asc' | 'desc';
+};
+/**
+ * Callback to build a query.
+ *
+ * @callback BuildQuery
+ * @param {QueryBuilder} qb - The query builder instance.
+ * @returns {Equals} The built query.
+ */
+export type BuildQuery = (qb: QueryBuilder) => Equals;
+/**
+ * Main fields of a Contentlet (Inherited from the Content Type).
+ */
+export interface ContentTypeMainFields {
+    hostName: string;
+    modDate: string;
+    publishDate: string;
+    title: string;
+    baseType: string;
+    inode: string;
+    archived: boolean;
+    ownerName: string;
+    host: string;
+    working: boolean;
+    locked: boolean;
+    stInode: string;
+    contentType: string;
+    live: boolean;
+    owner: string;
+    identifier: string;
+    publishUserName: string;
+    publishUser: string;
+    languageId: number;
+    creationDate: string;
+    url: string;
+    titleImage: string;
+    modUserName: string;
+    hasLiveVersion: boolean;
+    folder: string;
+    hasTitleImage: boolean;
+    sortOrder: number;
+    modUser: string;
+    __icon__: string;
+    contentTypeIcon: string;
+    variant: string;
+}
+/**
+ * The contentlet has the main fields and the custom fields of the content type.
+ *
+ * @template T - The custom fields of the content type.
+ */
+export type Contentlet<T> = T & ContentTypeMainFields;
+/**
+ * Callback for a fulfilled promise.
+ *
+ * @template T - The type of the response.
+ * @callback OnFullfilled
+ * @param {GetCollectionResponse<T>} value - The response value.
+ * @returns {GetCollectionResponse<T> | PromiseLike<GetCollectionResponse<T>> | void} The processed response or a promise.
+ */
+export type OnFullfilled<T> = ((value: GetCollectionResponse<T>) => GetCollectionResponse<T> | PromiseLike<GetCollectionResponse<T>> | void) | undefined | null;
+/**
+ * Callback for a rejected promise.
+ *
+ * @callback OnRejected
+ * @param {GetCollectionError} error - The error object.
+ * @returns {GetCollectionError | PromiseLike<GetCollectionError> | void} The processed error or a promise.
+ */
+export type OnRejected = ((error: GetCollectionError) => GetCollectionError | PromiseLike<GetCollectionError> | void) | undefined | null;
+/**
+ * Response of the get collection method.
+ *
+ * @template T - The type of the contentlet.
+ */
+export interface GetCollectionResponse<T> {
+    /**
+     * The list of contentlets.
+     */
+    contentlets: Contentlet<T>[];
+    /**
+     * The current page number.
+     */
+    page: number;
+    /**
+     * The size of the page.
+     */
+    size: number;
+    /**
+     * The total number of contentlets.
+     */
+    total: number;
+    /**
+     * The fields by which the contentlets are sorted.
+     */
+    sortedBy?: SortBy[];
+}
+/**
+ * Raw response of the get collection method.
+ *
+ * @template T - The type of the contentlet.
+ */
+export interface GetCollectionRawResponse<T> {
+    entity: {
+        jsonObjectView: {
+            /**
+             * The list of contentlets.
+             */
+            contentlets: Contentlet<T>[];
+        };
+        /**
+         * The size of the results.
+         */
+        resultsSize: number;
+    };
+}
+/**
+ * Error object for the get collection method.
+ */
+export interface GetCollectionError {
+    /**
+     * The status code of the error.
+     */
+    status: number;
+    [key: string]: unknown;
+}

package/src/lib/client/content/shared/utils.d.ts

@@ -0,0 +1,20 @@
+/**
+ * @description
+ * Sanitizes the query for the given content type.
+ * It replaces the fields that are not content type fields with the correct format.
+ * Example: +field: -> +contentTypeVar.field:
+ *
+ * @example
+ *
+ * ```ts
+ * const query = '+field: value';
+ * const contentType = 'contentTypeVar';
+ * const sanitizedQuery = sanitizeQueryForContentType(query, contentType); // Output: '+contentTypeVar.field: value'
+ * ```
+ *
+ * @export
+ * @param {string} query - The query string to be sanitized.
+ * @param {string} contentType - The content type to be used for formatting the fields.
+ * @returns {string} The sanitized query string.
+ */
+export declare function sanitizeQueryForContentType(query: string, contentType: string): string;

package/src/lib/client/models/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * A record of HTTP status codes and their corresponding error messages.
+ *
+ * @type {Record<number, string>}
+ * @property {string} 401 - Unauthorized. Check the token and try again.
+ * @property {string} 403 - Forbidden. Check the permissions and try again.
+ * @property {string} 404 - Not Found. Check the URL and try again.
+ * @property {string} 500 - Internal Server Error. Try again later.
+ * @property {string} 502 - Bad Gateway. Try again later.
+ * @property {string} 503 - Service Unavailable. Try again later.
+ */
+export declare const ErrorMessages: Record<number, string>;

package/src/lib/client/models/types.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Represents a listener for DotcmsClientListener.
+ *
+ * @typedef {Object} DotcmsClientListener
+ * @property {string} action - The action that triggers the event.
+ * @property {string} event - The name of the event.
+ * @property {function(...args: any[]): void} callback - The callback function to handle the event.
+ */
+export type DotcmsClientListener = {
+    action: string;
+    event: string;
+    callback: (...args: any[]) => void;
+};