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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dotcms/client",
-  "version": "0.0.1-alpha.37",
+  "version": "0.0.1-alpha.38",
   "description": "Official JavaScript library for interacting with DotCMS REST APIs.",
   "repository": {
     "type": "git",

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

@@ -1,27 +1,48 @@
 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 an specific content type
+ * 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
+ * @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);
     /**
-     * This method returns the sort query in this format: field order, field order, ...
+     * 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();
     /**
-     * This method returns the current query built
+     * Returns the current query built.
      *
      * @readonly
      * @private
@@ -29,120 +50,177 @@ export declare class CollectionBuilder<T = unknown> {
      */
     private get currentQuery();
     /**
-     * Takes a language id and filters the content by that language.
-     *
-     * The language id defaults to 1
+     * Filters the content by the specified language ID.
      *
-     *
-     * @param {number | string} languageId The language id to filter the content by
-     * @return {CollectionBuilder} CollectionBuilder - A CollectionBuilder instance
+     * @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;
     /**
-     * The retrieved content will have the rendered HTML
+     * 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} CollectionBuilder - A CollectionBuilder instance
+     * @return {CollectionBuilder} A CollectionBuilder instance.
      * @memberof CollectionBuilder
      */
     render(): this;
     /**
-     * Takes an array of constrains to sort the content by field an specific order
+     * Sorts the content by the specified fields and orders.
      *
      * @example
-     * ```javascript
-     * // This will sort the content by title in ascending order
-     * // and by modDate in descending order
-     *  const sortBy = [{ field: 'title', order: 'asc' }, { field: 'modDate', order: 'desc' }]
-     *
-     *  client.content.getCollection("Blog").sortBy(sortBy)
-     *```
-     *
-     * @param {SortBy[]} sortBy Array of constrains to sort the content by
-     * @return {CollectionBuilder} CollectionBuilder - A CollectionBuilder instance
+     * ```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;
     /**
-     * Takes a number that represents the max amount of content to fetch
+     * Sets the maximum amount of content to fetch.
      *
-     * `limit` is set to 10 by default
-     *
-     * @param {number} limit The max amount of content to fetch
-     * @return {CollectionBuilder} CollectionBuilder - A CollectionBuilder instance
+     * @param {number} limit The maximum amount of content to fetch.
+     * @return {CollectionBuilder} A CollectionBuilder instance.
      * @memberof CollectionBuilder
      */
     limit(limit: number): this;
     /**
-     * Takes a number that represents the page to fetch
+     * Sets the page number to fetch.
      *
-     * @param {number} page The page to fetch
-     * @return {CollectionBuilder} CollectionBuilder - A CollectionBuilder instance
+     * @param {number} page The page number to fetch.
+     * @return {CollectionBuilder} A CollectionBuilder instance.
      * @memberof CollectionBuilder
      */
     page(page: number): this;
     /**
-     * Takes a string that represents a {@link https://www.dotcms.com/docs/latest/content-search-syntax#Lucene Lucene Query} that is used to filter the content to fetch.
-     *
-     * The string is not validated, so be cautious when using it.
+     * Filters the content by a Lucene query string.
      *
-     * @param {string} query A {@link https://www.dotcms.com/docs/latest/content-search-syntax#Lucene Lucene Query} String
-     * @return {CollectionBuilder} CollectionBuilder - A CollectionBuilder instance
+     * @param {string} query A Lucene query string.
+     * @return {CollectionBuilder} A CollectionBuilder instance.
      * @memberof CollectionBuilder
      */
     query(query: string): this;
     /**
-     * Takes a function that recieves a QueryBuilder to buid a query for content filtering.
+     * Filters the content by building a query using a QueryBuilder function.
+     *
      * @example
-     *```javascript
-     * // This will filter the content by title equals 'Hello World' or 'Hello World 2'
-     * client.content.getCollection("Activity").query((queryBuilder) =>
+     * ```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} CollectionBuilder - A CollectionBuilder instance
+     * ```
+     *
+     * @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;
     /**
-     * The retrieved content will be draft content
-     *
-     * The default value is false to fetch content that is not on draft
-     *
-     * @return {CollectionBuilder} CollectionBuilder - A CollectionBuilder instance
+     * 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;
     /**
-     * Takes a string that represents a variant ID of content created with the {@link https://www.dotcms.com/docs/latest/experiments-and-a-b-testing A/B Testing} feature
+     * Filters the content by a variant ID for [Experiments](https://www.dotcms.com/docs/latest/experiments-and-a-b-testing)
      *
-     * `variantId` defaults to "DEFAULT" to fetch content that is not part of an A/B test
+     * More information here: {@link https://www.dotcms.com/docs/latest/content-api-retrieval-and-querying#ParamsOptional}
      *
-     * @param {string} variantId A string that represents a variant ID
-     * @return {CollectionBuilder} CollectionBuilder - A CollectionBuilder instance
+     * @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;
     /**
-     * Takes a number that represents the depth of the relationships of a content
+     * Sets the depth of the relationships of the content.
+     * Specifies the depth of related content to return in the results.
      *
-     * The `depth` is set to 0 by default and the max supported value is 3.
+     * More information here: {@link https://www.dotcms.com/docs/latest/content-api-retrieval-and-querying#ParamsOptional}
      *
-     * @param {number} depth The depth of the relationships of a content
-     * @return {CollectionBuilder} CollectionBuilder - A CollectionBuilder instance
+     * @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 to an error
+     * Executes the fetch and returns a promise that resolves to the content or rejects with an error.
      *
-     * @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 to 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

@@ -1,16 +1,71 @@
 import { CollectionBuilder } from './builders/collection/collection';
 import { ClientOptions } from '../sdk-js-client';
 /**
- * Content classs exposes the content api methods
+ * 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).
  *
- * @export
- * @class Content
+ * @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
+     * 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
@@ -42,7 +97,7 @@ export declare class Content {
      * ```
      * @example
      * ```typescript
-     * // Using an specific type for your content
+     * // Using a specific type for your content
      *
      * type Blog = {
      *     summary: string;
@@ -69,10 +124,6 @@ export declare class Content {
      *     });
      * ```
      *
-     * @param {string} contentType The content type to get the collection
-     * @return {CollectionBuilder} CollectionBuilder to filter and fetch the collection
-     * @template T Represents the type of the content type to fetch. Defaults to unknown
-     * @memberof Content
      */
     getCollection<T = unknown>(contentType: string): CollectionBuilder<T>;
 }

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

@@ -1,3 +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

@@ -1,10 +1,29 @@
 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;
@@ -38,25 +57,82 @@ export interface ContentTypeMainFields {
     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

@@ -1,12 +1,20 @@
 /**
+ * @description
  * Sanitizes the query for the given content type.
- * It replaces the fields that are not contentType fields with the correct format.
+ * 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
- * @param {string} contentType
- * @return {*}  {string}
+ * @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

@@ -1 +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

@@ -1,3 +1,11 @@
+/**
+ * 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;