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

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

@@ -0,0 +1,84 @@
+import { Content } from './content/content-api';
+import { NavigationClient } from './navigation/navigation-api';
+import { PageClient } from './page/page-api';
+/**
+ * Options for configuring fetch requests, excluding body and method properties.
+ */
+export type RequestOptions = Omit<RequestInit, 'body' | 'method'>;
+/**
+ * Configuration options for the DotCMS client.
+ */
+export interface DotCMSClientConfig {
+    /**
+     * The URL of the dotCMS instance.
+     * Ensure to include the protocol (http or https).
+     * @example `https://demo.dotcms.com`
+     */
+    dotcmsUrl: string;
+    /**
+     * The authentication token for requests.
+     * Obtainable from the dotCMS UI.
+     */
+    authToken: string;
+    /**
+     * The id of the site you want to interact with. Defaults to the default site if not provided.
+     */
+    siteId?: string;
+    /**
+     * Additional options for the fetch request.
+     * @example `{ headers: { 'Content-Type': 'application/json' } }`
+     */
+    requestOptions?: RequestOptions;
+}
+/**
+ * Client for interacting with the DotCMS REST API.
+ * Provides access to content, page, and navigation functionality.
+ */
+declare class DotCMSClient {
+    private config;
+    private requestOptions;
+    /**
+     * Client for content-related operations.
+     */
+    content: Content;
+    /**
+     * Client for page-related operations.
+     */
+    page: PageClient;
+    /**
+     * Client for navigation-related operations.
+     */
+    nav: NavigationClient;
+    /**
+     * Creates a new DotCMS client instance.
+     *
+     * @param config - Configuration options for the client
+     * @throws Warning if dotcmsUrl is invalid or authToken is missing
+     */
+    constructor(config?: DotCMSClientConfig);
+    /**
+     * Creates request options with authentication headers.
+     *
+     * @param config - The client configuration
+     * @returns Request options with authorization headers
+     */
+    private createAuthenticatedRequestOptions;
+}
+/**
+ * Creates and returns a new DotCMS client instance.
+ *
+ * @param config - Configuration options for the client
+ * @returns A configured DotCMS client instance
+ * @example
+ * ```typescript
+ * const client = dotCMSCreateClient({
+ *   dotcmsUrl: 'https://demo.dotcms.com',
+ *   authToken: 'your-auth-token'
+ * });
+ *
+ * // Use the client to fetch content
+ * const pages = await client.page.get('/about-us');
+ * ```
+ */
+export declare const createDotCMSClient: (clientConfig: DotCMSClientConfig) => DotCMSClient;
+export {};

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

@@ -0,0 +1,226 @@
+import { ClientOptions } from '../../../../deprecated/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/builders/query/lucene-syntax/Equals.d.ts

@@ -0,0 +1,114 @@
+import { Field } from './Field';
+import { NotOperand } from './NotOperand';
+import { Operand } from './Operand';
+/**
+ * '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.
+ *
+ * Ex: myValue or "My Value"
+ *
+ * @export
+ * @class Equal
+ */
+export declare class Equals {
+    #private;
+    private query;
+    constructor(query: string);
+    /**
+     * This method appends to the query a term that should be excluded in the search.
+     *
+     * @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.
+     * @memberof Equal
+     */
+    excludeField(field: string): Field;
+    /**
+     * This method appends to the query a field that should be included in the search.
+     *
+     * @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
+     */
+    field(field: string): Field;
+    /**
+     * This method appends to the query an operand to use logic operators in the query.
+     *
+     * @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
+     */
+    or(): Operand;
+    /**
+     * This method appends to the query an operand to use logic operators in the query.
+     *
+     * @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
+     */
+    and(): Operand;
+    /**
+     * This method appends to the query an operand to use logic operators in the query.
+     *
+     * @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
+     */
+    not(): NotOperand;
+    /**
+     * This method allows to pass a raw query string to the query builder.
+     * 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.
+     *
+     * @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.
+     * @memberof QueryBuilder
+     */
+    raw(query: string): 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
+     */
+    build(): string;
+}

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

@@ -0,0 +1,32 @@
+import { Equals } from './Equals';
+/**
+ * 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
+ * @class Field
+ */
+export declare class Field {
+    #private;
+    private query;
+    /**
+     * Creates an instance of the `Field` class.
+     *
+     * @param {string} query - The initial query string.
+     */
+    constructor(query: string);
+    /**
+     * Appends a term to the query that should be included in the search.
+     *
+     * @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`.
+     * @memberof Field
+     */
+    equals(term: string): Equals;
+}

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

@@ -0,0 +1,26 @@
+import { Equals } from './Equals';
+/**
+ * '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);
+    /**
+     * This method appends to the query a term that should be included in the search.
+     *
+     * @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.
+     * @memberof NotOperand
+     */
+    equals(term: string): Equals;
+}

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

@@ -0,0 +1,44 @@
+import { Equals } from './Equals';
+import { Field } from './Field';
+/**
+ * '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.
+ *
+ * @export
+ * @class Operand
+ */
+export declare class Operand {
+    #private;
+    private query;
+    constructor(query: string);
+    /**
+     * This method appends to the query a term that should be excluded in the search.
+     *
+     * Ex: "-myValue"
+     *
+     * @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.
+     * @memberof Operand
+     */
+    excludeField(field: string): Field;
+    /**
+     * This method appends to the query a field that should be included in the search.
+     *
+     * Ex: "+myField:"
+     *
+     * @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 Operand
+     */
+    field(field: string): Field;
+    /**
+     * This method appends to the query a term that should be included in the search.
+     *
+     * Ex: myValue or "My value"
+     *
+     * @param {string} term - The term that should be included in the search.
+     * @return {*}  {Equals} - An instance of Equals.
+     * @memberof Operand
+     */
+    equals(term: string): Equals;
+}

package/src/lib/client/content/builders/query/lucene-syntax/index.d.ts

@@ -0,0 +1,4 @@
+export * from './Equals';
+export * from './Field';
+export * from './NotOperand';
+export * from './Operand';

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

@@ -0,0 +1,76 @@
+import { Equals, Field } from './lucene-syntax/index';
+/**
+ * 'QueryBuilder' Is a Typescript class that provides the ability to build a query string using the Lucene syntax in a more readable way.
+ * @example
+ * ```ts
+ *  const qb = new QueryBuilder();
+ *  const query = qb
+ *          .field('contentType')
+ *          .equals('Blog')
+ *          .field('conhost')
+ *          .equals('my-super-cool-site')
+ *          .build(); // Output: `+contentType:Blog +conhost:my-super-cool-site"`
+ * ```
+ *
+ * @example
+ * ```ts
+ *  const qb = new QueryBuilder();
+ *  const query = qb
+ *          .field('contentType')
+ *          .equals('Blog')
+ *          .field('title')
+ *          .equals('Football')
+ *          .excludeField('summary')
+ *          .equals('Lionel Messi')
+ *          .build(); // Output: `+contentType:Blog +title:Football -summary:"Lionel Messi"`
+ * ```
+ * @export
+ * @class QueryBuilder
+ */
+export declare class QueryBuilder {
+    #private;
+    /**
+     * This method appends to the query a field that should be included in the search.
+     *
+     * @example
+     * ```ts
+     * const qb = new QueryBuilder();
+     * qb.field("+myField: ", "myValue"); // Current query: "+myField: myValue"
+     * ```
+     *
+     * @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 QueryBuilder
+     */
+    field(field: string): Field;
+    /**
+     * This method appends to the query a field that should be excluded from the search.
+     *
+     * @example
+     * ```ts
+     * const qb = new QueryBuilder();
+     * qb.excludeField("myField").equals("myValue"); // Current query: "-myField: myValue"
+     * ```
+     *
+     * @param {string} field - The field that should be excluded from the search.
+     * @return {*}  {Field} -  An instance of a Lucene Exclude Field. An exclude field is a key used to exclude for a specific value in a document.
+     * @memberof QueryBuilder
+     */
+    excludeField(field: string): Field;
+    /**
+     * This method allows to pass a raw query string to the query builder.
+     * This raw query should end in Equals.
+     * This method is useful when you want to append a complex query or an already written query to the query builder.
+     *
+     * @example
+     * ```ts
+     * const qb = new QueryBuilder();
+     * qb.raw("+myField: value AND (someOtherValue OR anotherValue)"); // Current query: "+myField: value AND (someOtherValue OR anotherValue)"
+     * ```
+     *
+     * @param {string} query - A raw query string.
+     * @return {*}  {Equals} - An instance of Equals. A term is a value used to search for a specific value in a document.
+     * @memberof QueryBuilder
+     */
+    raw(query: string): Equals;
+}