@dotcms/client 1.2.0 → 1.2.1

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

@@ -0,0 +1,77 @@
+import { DotCMSClientConfig, DotRequestOptions, DotHttpClient, DotCMSAISearchParams, DotCMSBasicContentlet } from '@dotcms/types';
+import { AISearch } from './search/search';
+import { BaseApiClient } from '../base/base-api';
+/**
+ * Client for interacting with the DotCMS AI API.
+ * Provides methods to interact with AI features.
+ * @experimental This client is experimental and may be subject to change.
+ */
+export declare class AIClient extends BaseApiClient {
+    /**
+     * Creates a new AIClient instance.
+     *
+     * @param {DotCMSClientConfig} config - Configuration options for the DotCMS client
+     * @param {DotRequestOptions} requestOptions - Options for fetch requests including authorization headers
+     * @param {DotHttpClient} httpClient - HTTP client for making requests
+     * @example
+     * ```typescript
+     * const aiClient = new AIClient(
+     *   {
+     *     dotcmsUrl: 'https://demo.dotcms.com',
+     *     authToken: 'your-auth-token',
+     *     siteId: 'demo.dotcms.com'
+     *   },
+     *   {
+     *     headers: {
+     *       Authorization: 'Bearer your-auth-token'
+     *     }
+     *   },
+     *   httpClient
+     * );
+     * ```
+     */
+    constructor(config: DotCMSClientConfig, requestOptions: DotRequestOptions, httpClient: DotHttpClient);
+    /**
+     * Performs an AI-powered search.
+     *
+     * @param params - Search parameters with query and AI configuration
+     * @returns Promise with search results
+     * @experimental This method is experimental and may be subject to change.
+     * @template T - The type of the contentlet.
+     * @param prompt - The prompt for the search.
+     * @param indexName - The name of the index you want to search in.
+     * @param params - Search parameters with query and AI configuration.
+     * @example
+     * @example
+     * ```typescript
+     * const response = await client.ai.search('machine learning articles', 'content_index', {
+     *   query: {
+     *     limit: 20,
+     *     contentType: 'BlogPost',
+     *     languageId: "1" // or 1
+     *   },
+     *   config: {
+     *     threshold: 0.7
+     *   }
+     * });
+     * ```
+     * @example
+     * ```typescript
+     * client.ai.search('machine learning articles', 'content_index', {
+     *   query: {
+     *     limit: 20,
+     *     contentType: 'BlogPost',
+     *     languageId: "1" // or 1
+     *   },
+     *   config: {
+     *     threshold: 0.7,
+     *     distanceFunction: DISTANCE_FUNCTIONS.cosine
+     *   }
+     * }).then((response) => {
+     *   console.log(response.results);
+     * }).catch((error) => {
+     *   console.error(error);
+     * });
+     */
+    search<T extends DotCMSBasicContentlet>(prompt: string, indexName: string, params?: DotCMSAISearchParams): AISearch<T>;
+}

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

@@ -0,0 +1,65 @@
+import { DotCMSAISearchParams, DotCMSBasicContentlet, DotCMSClientConfig, DotErrorAISearch, DotHttpClient, DotRequestOptions, DotCMSAISearchResponse } from '@dotcms/types';
+import { BaseApiClient } from '../../base/base-api';
+import { OnFullfilled, OnRejected } from '../shared/types';
+/**
+ * Class for executing AI searches.
+ *
+ * @template T - The type of the contentlet.
+ * @param config - The configuration for the client.
+ * @param requestOptions - The request options for the client.
+ * @param httpClient - The HTTP client for the client.
+ * @param params - The parameters for the search.
+ * @param prompt - The prompt for the search.
+ */
+export declare class AISearch<T extends DotCMSBasicContentlet> extends BaseApiClient {
+    #private;
+    constructor(config: DotCMSClientConfig, requestOptions: DotRequestOptions, httpClient: DotHttpClient, prompt: string, indexName: string, params?: DotCMSAISearchParams);
+    /**
+     * Executes the AI search and returns a promise with the search results.
+     *
+     * @param onfulfilled - Callback function to handle the search results.
+     * @param onrejected - Callback function to handle the search error.
+     * @returns Promise with the search results or the error.
+     * @example
+     * ```typescript
+     * const results = await client.ai.search('machine learning articles', 'content_index', {
+     *   query: {
+     *     limit: 20,
+     *     contentType: 'BlogPost',
+     *     languageId: '1' // or 1
+     *   },
+     *   config: {
+     *     threshold: 0.7
+     *   }
+     * });
+     * ```
+     * @example
+     * ```typescript
+     * client.ai.search('machine learning articles', 'content_index', {
+     *   query: {
+     *     limit: 20,
+     *     contentType: 'BlogPost',
+     *     languageId: '1' // or 1
+     *   },
+     *   config: {
+     *     threshold: 0.7
+     *   }
+     * }).then((results) => {
+     *   console.log(results);
+     * }).catch((error) => {
+     *   console.error(error);
+     * });
+     * ```
+     */
+    then(onfulfilled?: OnFullfilled<T>, onrejected?: OnRejected): Promise<DotCMSAISearchResponse<T> | DotErrorAISearch>;
+    private fetch;
+    /**
+     * Builds URLSearchParams from the SDK interface, mapping to backend parameter names.
+     * Only includes parameters that have values.
+     *
+     * @param params - Search parameters with SDK naming
+     * @returns URLSearchParams with backend parameter names
+     * @private
+     */
+    private buildSearchParams;
+}

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

@@ -0,0 +1,16 @@
+/**
+ * Default values for AI configuration
+ */
+export declare const DEFAULT_AI_CONFIG: {
+    readonly threshold: 0.5;
+    readonly distanceFunction: "<=>";
+    readonly responseLength: 1024;
+};
+/**
+ * Default values for search query
+ */
+export declare const DEFAULT_QUERY: {
+    readonly limit: 1000;
+    readonly offset: 0;
+    readonly indexName: "default";
+};

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

@@ -0,0 +1,18 @@
+import { DotCMSAISearchResponse, DotCMSBasicContentlet, DotErrorAISearch } from '@dotcms/types';
+/**
+ * Callback for a fulfilled promise.
+ *
+ * @template T - The type of the response.
+ * @callback OnFullfilled
+ * @param {DotCMSAISearchResponse} value - The response value.
+ * @returns {DotCMSAISearchResponse | PromiseLike<DotCMSAISearchResponse>} The processed response or a promise.
+ */
+export type OnFullfilled<T extends DotCMSBasicContentlet> = ((value: DotCMSAISearchResponse<T>) => DotCMSAISearchResponse<T> | PromiseLike<DotCMSAISearchResponse<T>>) | undefined | null;
+/**
+ * Callback for a rejected promise.
+ *
+ * @callback OnRejected
+ * @param {DotErrorAISearch} error - The AI search error object.
+ * @returns {DotErrorAISearch | PromiseLike<DotErrorAISearch>} The processed error or a promise.
+ */
+export type OnRejected = ((error: DotErrorAISearch) => DotErrorAISearch | PromiseLike<DotErrorAISearch>) | undefined | null;

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

@@ -0,0 +1,42 @@
+import { DotCMSClientConfig, DotHttpClient, DotRequestOptions } from '@dotcms/types';
+/**
+ * Base class for all DotCMS API clients.
+ * Provides common constructor parameters and properties that all API clients need.
+ * Uses JavaScript private fields (#) for true runtime privacy.
+ */
+export declare abstract class BaseApiClient {
+    #private;
+    /**
+     * Creates a new API client instance.
+     *
+     * @param {DotCMSClientConfig} config - Configuration options for the DotCMS client
+     * @param {DotRequestOptions} requestOptions - Options for fetch requests including authorization headers
+     * @param {DotHttpClient} httpClient - HTTP client for making requests
+     */
+    constructor(config: DotCMSClientConfig, requestOptions: DotRequestOptions | undefined, httpClient: DotHttpClient);
+    /**
+     * Gets the request options including authorization headers.
+     * @protected
+     */
+    protected get requestOptions(): DotRequestOptions;
+    /**
+     * Gets the DotCMS client configuration.
+     * @protected
+     */
+    protected get config(): DotCMSClientConfig;
+    /**
+     * Gets the HTTP client for making requests.
+     * @protected
+     */
+    protected get httpClient(): DotHttpClient;
+    /**
+     * Gets the DotCMS URL from config.
+     * @protected
+     */
+    protected get dotcmsUrl(): string;
+    /**
+     * Gets the site ID from config.
+     * @protected
+     */
+    protected get siteId(): string;
+}

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

@@ -1,4 +1,5 @@
 import { DotCMSClientConfig } from '@dotcms/types';
+import { AIClient } from './ai/ai-api';
 import { Content } from './content/content-api';
 import { NavigationClient } from './navigation/navigation-api';
 import { PageClient } from './page/page-api';
@@ -22,6 +23,11 @@ declare class DotCMSClient {
      * Client for navigation-related operations.
      */
     nav: NavigationClient;
+    /**
+     * Client for AI-related operations.
+     * @experimental This client is experimental and may be subject to change.
+     */
+    ai: AIClient;
     /**
      * Creates a new DotCMS client instance.
      *

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

@@ -1,4 +1,5 @@
 import { DotHttpClient, DotRequestOptions, DotCMSClientConfig, DotErrorContent } from '@dotcms/types';
+import { BaseApiClient } from '../../../base/base-api';
 import { GetCollectionResponse, BuildQuery, SortBy, OnFullfilled, OnRejected } from '../../shared/types';
 /**
  * Creates a Builder to filter and fetch content from the content API for a specific content type.
@@ -7,7 +8,7 @@ import { GetCollectionResponse, BuildQuery, SortBy, OnFullfilled, OnRejected } f
  * @class CollectionBuilder
  * @template T Represents the type of the content type to fetch. Defaults to unknown.
  */
-export declare class CollectionBuilder<T = unknown> {
+export declare class CollectionBuilder<T = unknown> extends BaseApiClient {
     #private;
     /**
      * Creates an instance of CollectionBuilder.
@@ -42,14 +43,6 @@ export declare class CollectionBuilder<T = unknown> {
      * @memberof CollectionBuilder
      */
     private get url();
-    /**
-     * Returns the site ID from the configuration.
-     *
-     * @readonly
-     * @private
-     * @memberof CollectionBuilder
-     */
-    private get siteId();
     /**
      * Returns the current query built.
      *
@@ -256,7 +249,7 @@ export declare class CollectionBuilder<T = unknown> {
      *
      * @example
      * // For draft content without site constraint:
-     * // Returns: "+contentType:Blog +languageId:1 +live:false"
+     * // Returns: "+contentType:Blog +languageId:1 +(live:false AND working:true AND deleted:false)"
      *
      * @example
      * // For content with explicit exclusion of current site (site ID 123):

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

@@ -1,5 +1,6 @@
 import { DotRequestOptions, DotHttpClient, DotCMSClientConfig } from '@dotcms/types';
 import { CollectionBuilder } from './builders/collection/collection';
+import { BaseApiClient } from '../base/base-api';
 /**
  * Creates a builder to filter and fetch a collection of content items.
  * @param contentType - The content type to retrieve.
@@ -49,12 +50,11 @@ import { CollectionBuilder } from './builders/collection/collection';
  * });
  * ```
  */
-export declare class Content {
-    #private;
+export declare class Content extends BaseApiClient {
     /**
      * Creates an instance of Content.
+     * @param {DotCMSClientConfig} config - Configuration options for the DotCMS client
      * @param {DotRequestOptions} requestOptions - The options for the client request.
-     * @param {string} serverUrl - The server URL.
      * @param {DotHttpClient} httpClient - HTTP client for making requests.
      */
     constructor(config: DotCMSClientConfig, requestOptions: DotRequestOptions, httpClient: DotHttpClient);

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

@@ -1,8 +1,13 @@
 import { DotCMSClientConfig, DotCMSNavigationRequestParams, DotRequestOptions, DotCMSNavigationItem, DotHttpClient } from '@dotcms/types';
-export declare class NavigationClient {
-    private requestOptions;
+import { BaseApiClient } from '../base/base-api';
+export declare class NavigationClient extends BaseApiClient {
     private BASE_URL;
-    private httpClient;
+    /**
+     * Creates a new NavigationClient instance.
+     * @param {DotCMSClientConfig} config - Configuration options for the DotCMS client
+     * @param {DotRequestOptions} requestOptions - Options for fetch requests including authorization headers
+     * @param {DotHttpClient} httpClient - HTTP client for making requests
+     */
     constructor(config: DotCMSClientConfig, requestOptions: DotRequestOptions, httpClient: DotHttpClient);
     /**
      * Retrieves information about the dotCMS file and folder tree.

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

@@ -1,29 +1,10 @@
 import { DotCMSClientConfig, DotCMSPageRequestParams, DotCMSPageResponse, DotCMSExtendedPageResponse, DotCMSComposedPageResponse, DotHttpClient, DotRequestOptions } from '@dotcms/types';
+import { BaseApiClient } from '../base/base-api';
 /**
  * Client for interacting with the DotCMS Page API.
  * Provides methods to retrieve and manipulate pages.
  */
-export declare class PageClient {
-    /**
-     * Request options including authorization headers.
-     * @private
-     */
-    private requestOptions;
-    /**
-     * Site ID for page requests.
-     * @private
-     */
-    private siteId;
-    /**
-     * DotCMS URL for page requests.
-     * @private
-     */
-    private dotcmsUrl;
-    /**
-     * HTTP client for making requests.
-     * @private
-     */
-    private httpClient;
+export declare class PageClient extends BaseApiClient {
     /**
      * Creates a new PageClient instance.
      *

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

@@ -1,4 +1,4 @@
-import { DotHttpClient, DotGraphQLApiResponse } from '@dotcms/types';
+import { DotGraphQLApiResponse, DotHttpClient } from '@dotcms/types';
 /**
  * Builds a GraphQL query for retrieving page content from DotCMS.
  *

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

@@ -0,0 +1,25 @@
+/**
+ * Utility functions for AI search parameter mapping and processing
+ */
+/**
+ * Appends mapped parameters to URLSearchParams based on a mapping configuration.
+ * Only includes parameters that have defined values.
+ *
+ * @param searchParams - The URLSearchParams object to append to
+ * @param sourceObject - The source object containing values
+ * @param mapping - Array of [targetKey, sourceKey] pairs for parameter mapping, or [key] to use same key
+ * @example
+ * ```typescript
+ * const params = new URLSearchParams();
+ * const query = { limit: 10, offset: 0, siteId: 'default', indexName: 'content' };
+ * const mapping = [
+ *   ['searchLimit', 'limit'],    // Maps limit -> searchLimit
+ *   ['searchOffset', 'offset'],  // Maps offset -> searchOffset
+ *   ['site', 'siteId'],          // Maps siteId -> site
+ *   ['indexName']                // Uses indexName -> indexName (same key)
+ * ];
+ * appendMappedParams(params, query, mapping);
+ * // Results in: searchLimit=10&searchOffset=0&site=default&indexName=content
+ * ```
+ */
+export declare function appendMappedParams<T extends object>(searchParams: URLSearchParams, sourceObject: T, mapping: Array<Array<string>>): void;