@dotcms/types 1.2.0-next.2 → 1.2.0-next.4

package/README.md

@@ -11,6 +11,7 @@ The `@dotcms/types` package contains TypeScript type definitions for the dotCMS
 - [Installation](#installation)
 - [Commonly Used Types](#commonly-used-types)
 - [Type Hierarchy (Jump to Definitions)](#type-hierarchy-jump-to-definitions)
+  - [AI Search](#ai-search)
   - [dotCMS Content & Pages](#dotcms-content--pages)
   - [Universal Visual Editor (UVE)](#universal-visual-editor-uve)
   - [Block Editor](#block-editor)
@@ -57,12 +58,42 @@ import {
   DotHttpError,
   DotErrorPage,
   DotErrorContent,
-  DotErrorNavigation
+  DotErrorNavigation,
+  DotErrorAISearch,
+  DotCMSAISearchParams,
+  DISTANCE_FUNCTIONS
 } from '@dotcms/types';
 ```
 
 ## Type Hierarchy (Jump to Definitions)
 
+### AI Search
+
+> **⚠️ Experimental:** The AI Search types are experimental and may undergo breaking changes in future releases.
+
+**AI Search Parameters:**
+
+| Type | Description |
+|------|-------------|
+| [DotCMSAISearchParams](https://github.com/dotCMS/core/blob/main/core-web/libs/sdk/types/src/lib/ai/public.ts#L85) | Complete AI search parameters including query and AI config |
+| [DotCMSAISearchQuery](https://github.com/dotCMS/core/blob/main/core-web/libs/sdk/types/src/lib/ai/public.ts#L9) | Query parameters (limit, offset, contentType, etc.) |
+| [DotCMSAIConfig](https://github.com/dotCMS/core/blob/main/core-web/libs/sdk/types/src/lib/ai/public.ts#L50) | AI configuration (threshold, distanceFunction, responseLength) |
+| [DISTANCE_FUNCTIONS](https://github.com/dotCMS/core/blob/main/core-web/libs/sdk/types/src/lib/ai/public.ts#L103) | Available distance functions for vector similarity |
+
+**AI Search Response:**
+
+| Type | Description |
+|------|-------------|
+| [DotCMSAISearchResponse](https://github.com/dotCMS/core/blob/main/core-web/libs/sdk/types/src/lib/ai/public.ts#L182) | AI search API response structure |
+| [DotCMSAISearchContentletData](https://github.com/dotCMS/core/blob/main/core-web/libs/sdk/types/src/lib/ai/public.ts#L213) | Contentlet with AI match information |
+| [DotCMSAISearchMatch](https://github.com/dotCMS/core/blob/main/core-web/libs/sdk/types/src/lib/ai/public.ts#L195) | Individual match with distance score and extracted text |
+
+**AI Search Errors:**
+
+| Type | Description |
+|------|-------------|
+| [DotErrorAISearch](https://github.com/dotCMS/core/blob/main/core-web/libs/sdk/types/src/lib/ai/public.ts#L136) | AI Search API specific error with prompt, indexName and params context |
+
 ### dotCMS Content & Pages
 
 **Page:**
@@ -166,6 +197,7 @@ import {
 | [DotErrorPage](https://github.com/dotCMS/core/blob/main/core-web/libs/sdk/types/src/lib/page/public.ts#L1253) | Page API errors with GraphQL context |
 | [DotErrorContent](https://github.com/dotCMS/core/blob/main/core-web/libs/sdk/types/src/lib/content/public.ts#L7) | Content API specific error handling |
 | [DotErrorNavigation](https://github.com/dotCMS/core/blob/main/core-web/libs/sdk/types/src/lib/nav/public.ts#L7) | Navigation API error handling |
+| [DotErrorAISearch](https://github.com/dotCMS/core/blob/main/core-web/libs/sdk/types/src/lib/ai/public.ts#L136) | AI Search API error handling with prompt and params |
 
 ## Usage Examples
 
@@ -176,7 +208,8 @@ import {
   DotHttpError,
   DotErrorPage,
   DotErrorContent,
-  DotErrorNavigation
+  DotErrorNavigation,
+  DotErrorAISearch
 } from '@dotcms/types';
 
 // Type-safe error handling
@@ -195,6 +228,13 @@ if (error instanceof DotErrorContent) {
   // Content-specific error context
   console.error(`${error.operation} failed for ${error.contentType}`);
 }
+
+if (error instanceof DotErrorAISearch) {
+  // AI Search-specific error context
+  console.error('AI Search failed for prompt:', error.prompt);
+  console.error('Index name:', error.indexName);
+  console.error('Search params:', error.params);
+}
 ```
 
 > **Note**: For complete implementation examples and usage patterns, see the [@dotcms/client](../client/README.md) package documentation.
@@ -229,6 +269,22 @@ Please ensure your code follows the existing style and includes appropriate test
 
 ## Changelog
 
+### [1.3.0]
+
+#### ✨ Added - AI Search Types (Experimental)
+
+> **⚠️ Experimental:** AI Search types are experimental and may undergo breaking changes in future releases.
+
+**New AI Search Types:**
+- `DotCMSAISearchParams` - Complete AI search parameters including query and AI config
+- `DotCMSAISearchQuery` - Query parameters (limit, offset, contentType, etc.)
+- `DotCMSAIConfig` - AI configuration (threshold, distanceFunction, responseLength)
+- `DotCMSAISearchResponse<T>` - AI search API response structure
+- `DotCMSAISearchContentletData<T>` - Contentlet with AI match information
+- `DotCMSAISearchMatch` - Individual match with distance score and extracted text
+- `DotErrorAISearch` - AI Search API specific error with prompt, indexName, and params context
+- `DISTANCE_FUNCTIONS` - Available distance functions for vector similarity (cosine, L2, inner product, etc.)
+
 ### [1.1.1]
 
 #### Added

package/index.cjs.js

@@ -248,6 +248,11 @@ class DotHttpError extends Error {
  * ```
  */
 class BaseHttpClient {
+  //  This is my proposal to add this method to the class. We will need to stream data on AI Gen/Chat
+  // abstract requestStream(
+  //     url: string,
+  //     options?: DotRequestOptions
+  // ): Promise<{ body: ReadableStream<BufferSource>; contentLength: number }>;
   /**
    * Creates a standardized HttpError from HTTP response details.
    * Handles parsing of error response body automatically.
@@ -356,8 +361,80 @@ class DotErrorNavigation extends Error {
   }
 }
 
+/**
+ * The distance functions for the search results.
+ * @public
+ * @constant DISTANCE_FUNCTIONS
+ */
+const DISTANCE_FUNCTIONS = {
+  /**
+   * The L2 distance function.
+   * @constant L2 - The L2 distance function.
+   */
+  L2: '<->',
+  /**
+   * The inner product distance function.
+   * @constant innerProduct - The inner product distance function.
+   */
+  innerProduct: '<#>',
+  cosine: '<=>',
+  /**
+   * The L1 distance function.
+   * @constant L1 - The L1 distance function.
+   */
+  L1: '<+>',
+  /**
+   * The hamming distance function.
+   * @constant hamming - The hamming distance function.
+   */
+  hamming: '<~>',
+  /**
+   * The jaccard distance function.
+   * @constant jaccard - The jaccard distance function.
+   */
+  jaccard: '<%>'
+};
+/**
+ * AI Search API specific error class
+ * Wraps HTTP errors and adds AI search-specific context including query information
+ */
+class DotErrorAISearch extends Error {
+  constructor({
+    message,
+    httpError,
+    prompt,
+    params,
+    indexName
+  }) {
+    super(message);
+    this.name = 'DotCMAISearchError';
+    this.httpError = httpError;
+    this.prompt = prompt;
+    this.params = params;
+    this.indexName = indexName;
+    // Ensure proper prototype chain for instanceof checks
+    Object.setPrototypeOf(this, DotErrorAISearch.prototype);
+  }
+  /**
+   * Serializes the error to a plain object for logging or transmission
+   */
+  toJSON() {
+    return {
+      name: this.name,
+      message: this.message,
+      httpError: this.httpError?.toJSON(),
+      prompt: this.prompt,
+      params: this.params,
+      indexName: this.indexName,
+      stack: this.stack
+    };
+  }
+}
+
 exports.BaseHttpClient = BaseHttpClient;
 exports.DEVELOPMENT_MODE = DEVELOPMENT_MODE;
+exports.DISTANCE_FUNCTIONS = DISTANCE_FUNCTIONS;
+exports.DotErrorAISearch = DotErrorAISearch;
 exports.DotErrorContent = DotErrorContent;
 exports.DotErrorNavigation = DotErrorNavigation;
 exports.DotErrorPage = DotErrorPage;

package/index.esm.js

@@ -246,6 +246,11 @@ class DotHttpError extends Error {
  * ```
  */
 class BaseHttpClient {
+  //  This is my proposal to add this method to the class. We will need to stream data on AI Gen/Chat
+  // abstract requestStream(
+  //     url: string,
+  //     options?: DotRequestOptions
+  // ): Promise<{ body: ReadableStream<BufferSource>; contentLength: number }>;
   /**
    * Creates a standardized HttpError from HTTP response details.
    * Handles parsing of error response body automatically.
@@ -354,4 +359,74 @@ class DotErrorNavigation extends Error {
   }
 }
 
-export { BaseHttpClient, DEVELOPMENT_MODE, DotCMSUVEAction, DotErrorContent, DotErrorNavigation, DotErrorPage, DotHttpError, PRODUCTION_MODE, UVEEventType, UVE_MODE };
+/**
+ * The distance functions for the search results.
+ * @public
+ * @constant DISTANCE_FUNCTIONS
+ */
+const DISTANCE_FUNCTIONS = {
+  /**
+   * The L2 distance function.
+   * @constant L2 - The L2 distance function.
+   */
+  L2: '<->',
+  /**
+   * The inner product distance function.
+   * @constant innerProduct - The inner product distance function.
+   */
+  innerProduct: '<#>',
+  cosine: '<=>',
+  /**
+   * The L1 distance function.
+   * @constant L1 - The L1 distance function.
+   */
+  L1: '<+>',
+  /**
+   * The hamming distance function.
+   * @constant hamming - The hamming distance function.
+   */
+  hamming: '<~>',
+  /**
+   * The jaccard distance function.
+   * @constant jaccard - The jaccard distance function.
+   */
+  jaccard: '<%>'
+};
+/**
+ * AI Search API specific error class
+ * Wraps HTTP errors and adds AI search-specific context including query information
+ */
+class DotErrorAISearch extends Error {
+  constructor({
+    message,
+    httpError,
+    prompt,
+    params,
+    indexName
+  }) {
+    super(message);
+    this.name = 'DotCMAISearchError';
+    this.httpError = httpError;
+    this.prompt = prompt;
+    this.params = params;
+    this.indexName = indexName;
+    // Ensure proper prototype chain for instanceof checks
+    Object.setPrototypeOf(this, DotErrorAISearch.prototype);
+  }
+  /**
+   * Serializes the error to a plain object for logging or transmission
+   */
+  toJSON() {
+    return {
+      name: this.name,
+      message: this.message,
+      httpError: this.httpError?.toJSON(),
+      prompt: this.prompt,
+      params: this.params,
+      indexName: this.indexName,
+      stack: this.stack
+    };
+  }
+}
+
+export { BaseHttpClient, DEVELOPMENT_MODE, DISTANCE_FUNCTIONS, DotCMSUVEAction, DotErrorAISearch, DotErrorContent, DotErrorNavigation, DotErrorPage, DotHttpError, PRODUCTION_MODE, UVEEventType, UVE_MODE };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dotcms/types",
-  "version": "1.2.0-next.2",
+  "version": "1.2.0-next.4",
   "keywords": [
     "dotCMS",
     "CMS",

package/src/index.d.ts

@@ -5,3 +5,4 @@ export * from './lib/page/public';
 export * from './lib/client/public';
 export * from './lib/content/public';
 export * from './lib/nav/public';
+export * from './lib/ai/public';

package/src/lib/ai/public.d.ts

@@ -0,0 +1,197 @@
+import { DotHttpError } from '../client/public';
+import { DotCMSBasicContentlet } from '../page/public';
+/**
+ * Query parameters for AI search - defines what and where to search
+ * @public
+ * @interface DotCMSAISearchQuery
+ */
+export interface DotCMSAISearchQuery {
+    /**
+     * The limit of the search results.
+     * @property {number} limit - The limit of the search results.
+     * @default 1000
+     */
+    limit?: number;
+    /**
+     * The offset of the search results.
+     * @property {number} offset - The offset of the search results.
+     * @default 0
+     */
+    offset?: number;
+    /**
+     * The site identifier.
+     * @property {string} siteId - The site identifier.
+     */
+    siteId?: string;
+    /**
+     * The content type you want to search for.
+     * @property {string} contentType - The content type you want to search for.
+     */
+    contentType?: string;
+    /**
+     * The language id to search in.
+     * @property {number | string} languageId - The language id to search in.
+     */
+    languageId?: number | string;
+}
+/**
+ * AI configuration parameters - controls how AI processes the results
+ * @public
+ * @interface DotCMSAIConfig
+ */
+export interface DotCMSAIConfig {
+    /**
+     * The threshold for the search results.
+     * @property {number} threshold - The threshold for the search results.
+     * @default 0.5
+     */
+    threshold?: number;
+    /**
+     * The distance function for the search results.
+     * Possible values:
+     *
+     * - <-> - L2 distance
+     * - <#> - (negative) inner product
+     * - <=> - cosine distance
+     * - <+> - L1 distance
+     * - <~> - Hamming distance (binary vectors)
+     * - <%> - Jaccard distance (binary vectors)
+     * @default DISTANCE_FUNCTIONS.cosine
+     * @see {@link https://platform.openai.com/docs/guides/embeddings/which-distance-function-should-i-use#which-distance-function-should-i-use} - OpenAI documentation for the distance functions
+     * @property {string} distanceFunction - The distance function for the search results.
+     */
+    distanceFunction?: (typeof DISTANCE_FUNCTIONS)[keyof typeof DISTANCE_FUNCTIONS];
+    /**
+     * The length of the response.
+     * @property {number} responseLength - The length of the response.
+     * @default 1024
+     */
+    responseLength?: number;
+}
+/**
+ * Parameters for making an AI search request to DotCMS.
+ * @public
+ * @interface DotCMSAISearchParams
+ */
+export interface DotCMSAISearchParams {
+    /**
+     * Query parameters defining what and where to search.
+     * @property {DotCMSAISearchQuery} query - The search query parameters.
+     */
+    query?: DotCMSAISearchQuery;
+    /**
+     * AI configuration parameters controlling how results are processed.
+     * @property {DotCMSAIConfig} config - The AI configuration parameters.
+     */
+    config?: DotCMSAIConfig;
+}
+/**
+ * The distance functions for the search results.
+ * @public
+ * @constant DISTANCE_FUNCTIONS
+ */
+export declare const DISTANCE_FUNCTIONS: {
+    /**
+     * The L2 distance function.
+     * @constant L2 - The L2 distance function.
+     */
+    readonly L2: "<->";
+    /**
+     * The inner product distance function.
+     * @constant innerProduct - The inner product distance function.
+     */
+    readonly innerProduct: "<#>";
+    readonly cosine: "<=>";
+    /**
+     * The L1 distance function.
+     * @constant L1 - The L1 distance function.
+     */
+    readonly L1: "<+>";
+    /**
+     * The hamming distance function.
+     * @constant hamming - The hamming distance function.
+     */
+    readonly hamming: "<~>";
+    /**
+     * The jaccard distance function.
+     * @constant jaccard - The jaccard distance function.
+     */
+    readonly jaccard: "<%>";
+};
+/**
+ * AI Search API specific error class
+ * Wraps HTTP errors and adds AI search-specific context including query information
+ */
+export declare class DotErrorAISearch extends Error {
+    readonly httpError?: DotHttpError;
+    readonly prompt?: string;
+    readonly params?: DotCMSAISearchParams;
+    readonly indexName?: string;
+    constructor({ message, httpError, prompt, params, indexName }: {
+        message: string;
+        httpError?: DotHttpError;
+        prompt?: string;
+        params?: DotCMSAISearchParams;
+        indexName?: string;
+    });
+    /**
+     * Serializes the error to a plain object for logging or transmission
+     */
+    toJSON(): {
+        name: string;
+        message: string;
+        httpError: {
+            name: string;
+            message: string;
+            status: number;
+            statusText: string;
+            data: unknown;
+            stack: string | undefined;
+        } | undefined;
+        prompt: string | undefined;
+        params: DotCMSAISearchParams | undefined;
+        indexName: string | undefined;
+        stack: string | undefined;
+    };
+}
+/**
+ * The response from the AI search.
+ * @public
+ * @interface DotCMSAISearchResponse
+ */
+export interface DotCMSAISearchResponse<T extends DotCMSBasicContentlet> {
+    /**
+     * The results from the AI search.
+     * @property {DotCMSAISearchContentletData<T>[]} dotCMSResults - The results from the AI search.
+     */
+    dotCMSResults: DotCMSAISearchContentletData<T>[];
+}
+/**
+ * The match from the AI search.
+ * @public
+ * @interface DotCMSAISearchMatch
+ */
+export interface DotCMSAISearchMatch {
+    /**
+     * The distance from the AI search.
+     * @property {number} distance - The distance from the AI search.
+     */
+    distance: number;
+    /**
+     * The extracted text from the AI search.
+     * @property {string} extractedText - The extracted text from the AI search.
+     */
+    extractedText: string;
+}
+/**
+ * The contentlet data from the AI search.
+ * @public
+ * @interface DotCMSAISearchContentletData
+ */
+export type DotCMSAISearchContentletData<T extends DotCMSBasicContentlet> = T & {
+    /**
+     * The matches from the AI search.
+     * @property {DotCMSAISearchMatch[]} matches - The matches from the AI search.
+     */
+    matches?: DotCMSAISearchMatch[];
+};