@dotcms/client 1.0.0 → 1.0.1

package/src/lib/client/content/builders/collection/{collection.d.ts → collection.ts}

@@ -1,5 +1,19 @@
-import { GetCollectionResponse, BuildQuery, SortBy, GetCollectionError, OnFullfilled, OnRejected } from '../../shared/types';
+import { CONTENT_API_URL } from '../../shared/const';
+import {
+    GetCollectionResponse,
+    BuildQuery,
+    SortBy,
+    GetCollectionRawResponse,
+    GetCollectionError,
+    OnFullfilled,
+    OnRejected
+} from '../../shared/types';
+import { sanitizeQueryForContentType } from '../../shared/utils';
+import { Equals } from '../query/lucene-syntax';
+import { QueryBuilder } from '../query/query';
+
 export type ClientOptions = Omit<RequestInit, 'body' | 'method'>;
+
 /**
  * Creates a Builder to filter and fetch content from the content API for a specific content type.
  *
@@ -7,8 +21,22 @@ export type ClientOptions = Omit<RequestInit, 'body' | 'method'>;
  * @class CollectionBuilder
  * @template T Represents the type of the content type to fetch. Defaults to unknown.
  */
-export declare class CollectionBuilder<T = unknown> {
-    #private;
+export class CollectionBuilder<T = unknown> {
+    #page = 1;
+    #limit = 10;
+    #depth = 0;
+    #render = false;
+    #sortBy?: SortBy[];
+    #contentType: string;
+    #defaultQuery: Equals;
+    #query?: Equals;
+    #rawQuery?: string;
+    #languageId: number | string = 1;
+    #draft = false;
+
+    #serverUrl: string;
+    #requestOptions: ClientOptions;
+
     /**
      * Creates an instance of CollectionBuilder.
      * @param {ClientOptions} requestOptions Options for the client request.
@@ -16,7 +44,15 @@ export declare class CollectionBuilder<T = unknown> {
      * @param {string} contentType The content type to fetch.
      * @memberof CollectionBuilder
      */
-    constructor(requestOptions: ClientOptions, serverUrl: string, contentType: string);
+    constructor(requestOptions: ClientOptions, serverUrl: string, contentType: string) {
+        this.#requestOptions = requestOptions;
+        this.#serverUrl = serverUrl;
+        this.#contentType = contentType;
+
+        // Build the default query with the contentType field
+        this.#defaultQuery = new QueryBuilder().field('contentType').equals(this.#contentType);
+    }
+
     /**
      * Returns the sort query in the format: field order, field order, ...
      *
@@ -24,7 +60,10 @@ export declare class CollectionBuilder<T = unknown> {
      * @private
      * @memberof CollectionBuilder
      */
-    private get sort();
+    private get sort() {
+        return this.#sortBy?.map((sort) => `${sort.field} ${sort.order}`).join(',');
+    }
+
     /**
      * Returns the offset for pagination.
      *
@@ -32,7 +71,10 @@ export declare class CollectionBuilder<T = unknown> {
      * @private
      * @memberof CollectionBuilder
      */
-    private get offset();
+    private get offset() {
+        return this.#limit * (this.#page - 1);
+    }
+
     /**
      * Returns the full URL for the content API.
      *
@@ -40,7 +82,10 @@ export declare class CollectionBuilder<T = unknown> {
      * @private
      * @memberof CollectionBuilder
      */
-    private get url();
+    private get url() {
+        return `${this.#serverUrl}${CONTENT_API_URL}`;
+    }
+
     /**
      * Returns the current query built.
      *
@@ -48,7 +93,10 @@ export declare class CollectionBuilder<T = unknown> {
      * @private
      * @memberof CollectionBuilder
      */
-    private get currentQuery();
+    private get currentQuery() {
+        return this.#query ?? this.#defaultQuery;
+    }
+
     /**
      * Filters the content by the specified language ID.
      *
@@ -63,7 +111,12 @@ export declare class CollectionBuilder<T = unknown> {
      * @return {CollectionBuilder} A CollectionBuilder instance.
      * @memberof CollectionBuilder
      */
-    language(languageId: number | string): this;
+    language(languageId: number | string): this {
+        this.#languageId = languageId;
+
+        return this;
+    }
+
     /**
      * Setting this to true will server side render (using velocity) any widgets that are returned by the content query.
      *
@@ -72,7 +125,12 @@ export declare class CollectionBuilder<T = unknown> {
      * @return {CollectionBuilder} A CollectionBuilder instance.
      * @memberof CollectionBuilder
      */
-    render(): this;
+    render(): this {
+        this.#render = true;
+
+        return this;
+    }
+
     /**
      * Sorts the content by the specified fields and orders.
      *
@@ -88,7 +146,12 @@ export declare class CollectionBuilder<T = unknown> {
      * @return {CollectionBuilder} A CollectionBuilder instance.
      * @memberof CollectionBuilder
      */
-    sortBy(sortBy: SortBy[]): this;
+    sortBy(sortBy: SortBy[]): this {
+        this.#sortBy = sortBy;
+
+        return this;
+    }
+
     /**
      * Sets the maximum amount of content to fetch.
      *
@@ -96,7 +159,12 @@ export declare class CollectionBuilder<T = unknown> {
      * @return {CollectionBuilder} A CollectionBuilder instance.
      * @memberof CollectionBuilder
      */
-    limit(limit: number): this;
+    limit(limit: number): this {
+        this.#limit = limit;
+
+        return this;
+    }
+
     /**
      * Sets the page number to fetch.
      *
@@ -104,7 +172,12 @@ export declare class CollectionBuilder<T = unknown> {
      * @return {CollectionBuilder} A CollectionBuilder instance.
      * @memberof CollectionBuilder
      */
-    page(page: number): this;
+    page(page: number): this {
+        this.#page = page;
+
+        return this;
+    }
+
     /**
      * Filters the content by a Lucene query string.
      *
@@ -113,6 +186,7 @@ export declare class CollectionBuilder<T = unknown> {
      * @memberof CollectionBuilder
      */
     query(query: string): this;
+
     /**
      * Filters the content by building a query using a QueryBuilder function.
      *
@@ -130,6 +204,33 @@ export declare class CollectionBuilder<T = unknown> {
      * @memberof CollectionBuilder
      */
     query(buildQuery: BuildQuery): this;
+    query(arg: unknown): this {
+        if (typeof arg === 'string') {
+            this.#rawQuery = arg;
+
+            return this;
+        }
+
+        if (typeof arg !== 'function') {
+            throw new Error(
+                `Parameter for query method should be a buildQuery function or a string.\nExample:\nclient.content.getCollection('Activity').query((queryBuilder) => queryBuilder.field('title').equals('Hello World'))\nor\nclient.content.getCollection('Activity').query('+Activity.title:"Hello World"') \nSee documentation for more information.`
+            );
+        }
+
+        const builtQuery = arg(new QueryBuilder());
+
+        // This can be use in Javascript so we cannot rely on the type checking
+        if (builtQuery instanceof Equals) {
+            this.#query = builtQuery.raw(this.currentQuery.build());
+        } else {
+            throw new Error(
+                'Provided query is not valid. A query should end in an equals method call.\nExample:\n(queryBuilder) => queryBuilder.field("title").equals("Hello World")\nSee documentation for more information.'
+            );
+        }
+
+        return this;
+    }
+
     /**
      * Retrieves draft content.
      * @example
@@ -145,7 +246,12 @@ export declare class CollectionBuilder<T = unknown> {
      * @return {CollectionBuilder} A CollectionBuilder instance.
      * @memberof CollectionBuilder
      */
-    draft(): this;
+    draft(): this {
+        this.#draft = true;
+
+        return this;
+    }
+
     /**
      * Filters the content by a variant ID for [Experiments](https://www.dotcms.com/docs/latest/experiments-and-a-b-testing)
      *
@@ -165,7 +271,12 @@ export declare class CollectionBuilder<T = unknown> {
      * @return {CollectionBuilder} A CollectionBuilder instance.
      * @memberof CollectionBuilder
      */
-    variant(variantId: string): this;
+    variant(variantId: string): this {
+        this.#query = this.currentQuery.field('variant').equals(variantId);
+
+        return this;
+    }
+
     /**
      * Sets the depth of the relationships of the content.
      * Specifies the depth of related content to return in the results.
@@ -186,7 +297,16 @@ export declare class CollectionBuilder<T = unknown> {
      * @return {CollectionBuilder} A CollectionBuilder instance.
      * @memberof CollectionBuilder
      */
-    depth(depth: number): this;
+    depth(depth: number): this {
+        if (depth < 0 || depth > 3) {
+            throw new Error('Depth value must be between 0 and 3');
+        }
+
+        this.#depth = depth;
+
+        return this;
+    }
+
     /**
      * Executes the fetch and returns a promise that resolves to the content or rejects with an error.
      *
@@ -205,7 +325,30 @@ export declare class CollectionBuilder<T = unknown> {
      * @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>;
+    then(
+        onfulfilled?: OnFullfilled<T>,
+        onrejected?: OnRejected
+    ): Promise<GetCollectionResponse<T> | GetCollectionError> {
+        return this.fetch().then(async (response) => {
+            const data = await response.json();
+            if (response.ok) {
+                const formattedResponse = this.formatResponse<T>(data);
+
+                const finalResponse =
+                    typeof onfulfilled === 'function'
+                        ? onfulfilled(formattedResponse)
+                        : formattedResponse;
+
+                return finalResponse;
+            } else {
+                return {
+                    status: response.status,
+                    ...data
+                };
+            }
+        }, onrejected);
+    }
+
     /**
      * Formats the response to the desired format.
      *
@@ -214,7 +357,25 @@ export declare class CollectionBuilder<T = unknown> {
      * @return {GetCollectionResponse<T>} The formatted response.
      * @memberof CollectionBuilder
      */
-    private formatResponse;
+    private formatResponse<T>(data: GetCollectionRawResponse<T>): GetCollectionResponse<T> {
+        const contentlets = data.entity.jsonObjectView.contentlets;
+        const total = data.entity.resultsSize;
+
+        const mappedResponse: GetCollectionResponse<T> = {
+            contentlets,
+            total,
+            page: this.#page,
+            size: contentlets.length
+        };
+
+        return this.#sortBy
+            ? {
+                  ...mappedResponse,
+                  sortedBy: this.#sortBy
+              }
+            : mappedResponse;
+    }
+
     /**
      * Calls the content API to fetch the content.
      *
@@ -222,5 +383,35 @@ export declare class CollectionBuilder<T = unknown> {
      * @return {Promise<Response>} The fetch response.
      * @memberof CollectionBuilder
      */
-    private fetch;
+    private fetch(): Promise<Response> {
+        const finalQuery = this.currentQuery
+            .field('languageId')
+            .equals(this.#languageId.toString())
+            .field('live')
+            .equals((!this.#draft).toString())
+            .build();
+
+        const sanitizedQuery = sanitizeQueryForContentType(finalQuery, this.#contentType);
+
+        const query = this.#rawQuery ? `${sanitizedQuery} ${this.#rawQuery}` : sanitizedQuery;
+
+        return fetch(this.url, {
+            ...this.#requestOptions,
+            method: 'POST',
+            headers: {
+                ...this.#requestOptions.headers,
+                'Content-Type': 'application/json'
+            },
+            body: JSON.stringify({
+                query,
+                render: this.#render,
+                sort: this.sort,
+                limit: this.#limit,
+                offset: this.offset,
+                depth: this.#depth
+                //userId: This exist but we currently don't use it
+                //allCategoriesInfo: This exist but we currently don't use it
+            })
+        });
+    }
 }

package/src/lib/client/content/builders/query/lucene-syntax/{Equals.d.ts → Equals.ts}

@@ -1,6 +1,17 @@
 import { Field } from './Field';
 import { NotOperand } from './NotOperand';
 import { Operand } from './Operand';
+
+import {
+    OPERAND,
+    buildExcludeField,
+    buildField,
+    buildNotOperand,
+    buildOperand,
+    buildRawEquals,
+    sanitizeQuery
+} from '../utils';
+
 /**
  * 'Equal' Is a Typescript class that provides the ability to use terms in the lucene query string.
  * A term is a value used to search for a specific value in a document. It can be a word or a phrase.
@@ -10,10 +21,13 @@ import { Operand } from './Operand';
  * @export
  * @class Equal
  */
-export declare class Equals {
-    #private;
-    private query;
-    constructor(query: string);
+export class Equals {
+    #query = '';
+
+    constructor(private query: string) {
+        this.#query = this.query;
+    }
+
     /**
      * This method appends to the query a term that should be excluded in the search.
      *
@@ -27,7 +41,10 @@ export declare class Equals {
      * @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
      */
-    excludeField(field: string): Field;
+    excludeField(field: string): Field {
+        return buildExcludeField(this.#query, field);
+    }
+
     /**
      * This method appends to the query a field that should be included in the search.
      *
@@ -40,7 +57,10 @@ export declare class Equals {
      * @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
      */
-    field(field: string): Field;
+    field(field: string): Field {
+        return buildField(this.#query, field);
+    }
+
     /**
      * This method appends to the query an operand to use logic operators in the query.
      *
@@ -54,7 +74,10 @@ export declare class Equals {
      * @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
      */
-    or(): Operand;
+    or(): Operand {
+        return buildOperand(this.#query, OPERAND.OR);
+    }
+
     /**
      * This method appends to the query an operand to use logic operators in the query.
      *
@@ -67,7 +90,10 @@ export declare class Equals {
      * @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
      */
-    and(): Operand;
+    and(): Operand {
+        return buildOperand(this.#query, OPERAND.AND);
+    }
+
     /**
      * This method appends to the query an operand to use logic operators in the query.
      *
@@ -80,7 +106,10 @@ export declare class Equals {
      * @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
      */
-    not(): NotOperand;
+    not(): NotOperand {
+        return buildNotOperand(this.#query);
+    }
+
     /**
      * This method allows to pass a raw query string to the query builder.
      * This raw query should end in a Lucene Equal.
@@ -97,7 +126,10 @@ export declare class Equals {
      * @return {*}  {Equal} - An instance of a Lucene Equal. A term is a value used to search for a specific value in a document.
      * @memberof QueryBuilder
      */
-    raw(query: string): Equals;
+    raw(query: string): Equals {
+        return buildRawEquals(this.#query, query);
+    }
+
     /**
      * This method returns the final query string.
      *
@@ -110,5 +142,7 @@ export declare class Equals {
      * @return {*}  {string} - The final query string.
      * @memberof Equal
      */
-    build(): string;
+    build(): string {
+        return sanitizeQuery(this.#query);
+    }
 }

package/src/lib/client/content/builders/query/lucene-syntax/{Field.d.ts → Field.ts}

@@ -1,4 +1,7 @@
 import { Equals } from './Equals';
+
+import { buildEquals } from '../utils';
+
 /**
  * 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.
@@ -6,15 +9,18 @@ import { Equals } from './Equals';
  * @export
  * @class Field
  */
-export declare class Field {
-    #private;
-    private query;
+export class Field {
+    #query = '';
+
     /**
      * Creates an instance of the `Field` class.
      *
      * @param {string} query - The initial query string.
      */
-    constructor(query: string);
+    constructor(private query: string) {
+        this.#query = this.query;
+    }
+
     /**
      * Appends a term to the query that should be included in the search.
      *
@@ -28,5 +34,7 @@ export declare class Field {
      * @return {Equals} - An instance of `Equals`.
      * @memberof Field
      */
-    equals(term: string): Equals;
+    equals(term: string): Equals {
+        return buildEquals(this.#query, term);
+    }
 }

package/src/lib/client/content/builders/query/lucene-syntax/{NotOperand.d.ts → NotOperand.ts}

@@ -1,14 +1,20 @@
 import { Equals } from './Equals';
+
+import { buildEquals } from '../utils';
+
 /**
  * 'NotOperand' Is a Typescript class that provides the ability to use the NOT operand in the lucene query string.
  *
  * @export
  * @class NotOperand
  */
-export declare class NotOperand {
-    #private;
-    private query;
-    constructor(query: string);
+export class NotOperand {
+    #query = '';
+
+    constructor(private query: string) {
+        this.#query = this.query;
+    }
+
     /**
      * This method appends to the query a term that should be included in the search.
      *
@@ -22,5 +28,7 @@ export declare class NotOperand {
      * @return {*}  {Equals} - An instance of Equals.
      * @memberof NotOperand
      */
-    equals(term: string): Equals;
+    equals(term: string): Equals {
+        return buildEquals(this.#query, term);
+    }
 }

package/src/lib/client/content/builders/query/lucene-syntax/{Operand.d.ts → Operand.ts}

@@ -1,5 +1,8 @@
 import { Equals } from './Equals';
 import { Field } from './Field';
+
+import { buildExcludeField, buildField, buildEquals } from '../utils';
+
 /**
  * 'Operand' Is a Typescript class that provides the ability to use operands in the lucene query string.}
  * An operand is a logical operator used to join two or more conditions in a query.
@@ -7,10 +10,13 @@ import { Field } from './Field';
  * @export
  * @class Operand
  */
-export declare class Operand {
-    #private;
-    private query;
-    constructor(query: string);
+export class Operand {
+    #query = '';
+
+    constructor(private query: string) {
+        this.#query = this.query;
+    }
+
     /**
      * This method appends to the query a term that should be excluded in the search.
      *
@@ -20,7 +26,10 @@ export declare class Operand {
      * @return {*}  {Field} - An instance of a Lucene Field. A field is a key used to search for a specific value in a document.
      * @memberof Operand
      */
-    excludeField(field: string): Field;
+    excludeField(field: string): Field {
+        return buildExcludeField(this.#query, field);
+    }
+
     /**
      * This method appends to the query a field that should be included in the search.
      *
@@ -30,7 +39,10 @@ export declare class Operand {
      * @return {*}  {Field} -  An instance of a Lucene Field. A field is a key used to search for a specific value in a document.
      * @memberof Operand
      */
-    field(field: string): Field;
+    field(field: string): Field {
+        return buildField(this.#query, field);
+    }
+
     /**
      * This method appends to the query a term that should be included in the search.
      *
@@ -40,5 +52,7 @@ export declare class Operand {
      * @return {*}  {Equals} - An instance of Equals.
      * @memberof Operand
      */
-    equals(term: string): Equals;
+    equals(term: string): Equals {
+        return buildEquals(this.#query, term);
+    }
 }