@dotcms/client 1.1.1 → 1.2.0-next.10

package/README.md

@@ -19,6 +19,7 @@ The `@dotcms/client` is a powerful JavaScript/TypeScript SDK designed to simplif
 
 > **📋 Migration Guides:**
 > - **From Alpha Version?** If you're upgrading from the alpha version of `@dotcms/client`, please see our [Migration Guide](./MIGRATION.md) for step-by-step instructions.
+> - **From v1.2.x to v1.3.0?** See the [Changelog](#v130) section below for new AI Search API features.
 > - **From v1.0.x to v1.1.1?** See the [Changelog](#v111) section below for new features and improvements.
 
 ## Table of Contents
@@ -31,6 +32,7 @@ The `@dotcms/client` is a powerful JavaScript/TypeScript SDK designed to simplif
 -   [How-to Guides](#how-to-guides)
     -   [How to Fetch Complete Pages](#how-to-fetch-complete-pages)
     -   [How to Query Content Collections](#how-to-query-content-collections)
+    -   [How to Use AI-Powered Search](#how-to-use-ai-powered-search)
     -   [How to Work with GraphQL](#how-to-work-with-graphql)
     -   [How to Use with TypeScript](#how-to-use-with-typescript)
     -   [How to Enable Page Editing](#how-to-enable-page-editing)
@@ -39,17 +41,18 @@ The `@dotcms/client` is a powerful JavaScript/TypeScript SDK designed to simplif
     -   [HTTP Client Configuration](#http-client-configuration)
     -   [page.get() Method](#pageget-method)
     -   [content.getCollection() Method](#contentgetcollection-method)
+    -   [ai.search() Method](#aisearch-method)
     -   [navigation.get() Method](#navigationget-method)
     -   [Error Handling](#error-handling)
 -   [Concepts & Architecture](#concepts--architecture)
     -   [Key Concepts](#key-concepts)
     -   [Choosing the Right Method](#choosing-the-right-method)
     -   [Architecture Overview](#architecture-overview)
--   [Support & Contributing](#support--contributing)
-    -   [dotCMS Support](#dotcms-support)
-    -   [How To Contribute](#how-to-contribute)
-    -   [Licensing Information](#licensing-information)
+-   [Support](#support)
+-   [Contributing](#contributing)
+-   [Licensing](#licensing)
 -   [Changelog](#changelog)
+    -   [v1.3.0](#v130)
     -   [v1.1.1](#v111)
 
 ## Getting Started
@@ -215,6 +218,352 @@ const products = await client.content
     .limit(10);
 ```
 
+### How to Use AI-Powered Search
+
+> [!WARNING]
+> **Experimental Feature:** The AI API is currently experimental and may undergo breaking changes in future releases. Use with caution in production environments.
+
+The `client.ai.search()` method enables semantic search using AI embeddings to find content based on meaning rather than exact keyword matches.
+
+#### Prerequisites
+
+Before using AI-powered search, ensure your dotCMS instance is properly configured:
+
+> [!IMPORTANT]
+> **Required Setup:**
+> 1. **dotAI must be activated** in your dotCMS instance
+> 2. **OpenAI API Key** must be configured in dotCMS
+> 3. **PostgreSQL 15+ with pgvector extension** must be installed
+> 4. **Content indexes** must be created and configured in dotAI
+>
+> For detailed setup instructions, see the [dotCMS dotAI documentation](https://dev.dotcms.com/docs/dotai).
+
+#### Basic AI Search
+```typescript
+// Search for content semantically related to your query
+const response = await client.ai.search(
+    'articles about machine learning',
+    'content_index'
+);
+console.log(response.results);
+```
+
+#### Customizing Search Parameters
+```typescript
+// Fine-tune search with query parameters
+const response = await client.ai.search(
+    'artificial intelligence tutorials',
+    'content_index',
+    {
+        query: {
+            limit: 20,
+            offset: 0,
+            contentType: 'BlogPost',
+            languageId: '1'
+        }
+    }
+);
+```
+
+#### Adjusting AI Configuration
+```typescript
+import { DISTANCE_FUNCTIONS } from '@dotcms/types';
+
+// Customize AI search behavior with threshold and distance function
+const response = await client.ai.search(
+    'deep learning concepts',
+    'content_index',
+    {
+        config: {
+            threshold: 0.75,              // Higher threshold = more relevant results
+            distanceFunction: DISTANCE_FUNCTIONS.cosine, // Distance calculation method
+            responseLength: 2048           // Maximum response length
+        }
+    }
+);
+```
+
+#### Complete Example with All Options
+```typescript
+// Combine query and AI parameters for precise control
+const response = await client.ai.search(
+    'best practices for content management',
+    'articles_index',
+    {
+        query: {
+            limit: 10,
+            offset: 0,
+            contentType: 'Article',
+            languageId: '1',
+            siteId: 'my-site'
+        },
+        config: {
+            threshold: 0.8,
+            distanceFunction: DISTANCE_FUNCTIONS.innerProduct,
+            responseLength: 1024
+        }
+    }
+);
+
+// Access results with match scores
+resp[onse].results.forEach(result => {
+    console.log(result.title);
+    console.log('Matches:', result.matches); // Distance and extracted text
+});
+```
+
+#### Understanding Distance Functions
+
+The SDK supports multiple distance functions for vector similarity:
+
+```typescript
+import { DISTANCE_FUNCTIONS } from '@dotcms/types';
+
+// Available distance functions:
+DISTANCE_FUNCTIONS.cosine        // '<=>' - Cosine similarity (default)
+DISTANCE_FUNCTIONS.innerProduct  // '<#>' - Inner product similarity
+DISTANCE_FUNCTIONS.L2            // '<->' - Euclidean distance
+DISTANCE_FUNCTIONS.L1            // '<+>' - Manhattan distance
+DISTANCE_FUNCTIONS.hamming       // '<~>' - Hamming distance
+DISTANCE_FUNCTIONS.jaccard       // '<%>' - Jaccard similarity
+```
+
+### How to Use with TypeScript
+
+The SDK is built with TypeScript and provides comprehensive type definitions through the `@dotcms/types` package for enhanced developer experience and type safety.
+
+#### Basic Type Usage
+
+```typescript
+import { createDotCMSClient } from '@dotcms/client';
+import type {
+    DotCMSPageAsset,
+    DotCMSPageResponse,
+    DotCMSBasicContentlet,
+    DotCMSNavigationItem,
+    DotCMSAISearchResponse,
+    DotErrorPage,
+    DotErrorContent,
+    DotErrorAISearch
+} from '@dotcms/types';
+
+const client = createDotCMSClient({
+    dotcmsUrl: 'https://your-dotcms-instance.com',
+    authToken: 'your-auth-token',
+    siteId: 'your-site-id'
+});
+```
+
+#### Typing Page Responses
+
+```typescript
+import type { DotCMSPageAsset } from '@dotcms/types';
+
+// Basic page fetch with type inference
+const { pageAsset } = await client.page.get('/about-us');
+// pageAsset is automatically typed as DotCMSPageAsset
+
+// Explicit typing
+const response: { pageAsset: DotCMSPageAsset } = await client.page.get('/about-us');
+
+// Access typed properties
+console.log(pageAsset.page.title);        // string
+console.log(pageAsset.layout.body.rows);  // Row[]
+console.log(pageAsset.viewAs.language);   // LanguageView
+```
+
+#### Typing Content Collections
+
+```typescript
+import type { DotCMSBasicContentlet } from '@dotcms/types';
+
+// Define your custom content type interface
+interface BlogPost extends DotCMSBasicContentlet {
+    title: string;
+    body: string;
+    author: string;
+    publishDate: string;
+    tags: string[];
+}
+
+// Use the generic type parameter for type-safe content
+const response = await client.content
+    .getCollection<BlogPost>('Blog')
+    .limit(10);
+
+// Now contentlets are typed as BlogPost[]
+response.contentlets.forEach(post => {
+    console.log(post.title);      // ✅ Type-safe: string
+    console.log(post.author);     // ✅ Type-safe: string
+    console.log(post.publishDate); // ✅ Type-safe: string
+});
+```
+
+#### Typing AI Search Results
+
+```typescript
+import type {
+    DotCMSAISearchResponse,
+    DotCMSBasicContentlet,
+    DISTANCE_FUNCTIONS
+} from '@dotcms/types';
+
+// Define your content type
+interface Article extends DotCMSBasicContentlet {
+    title: string;
+    content: string;
+    category: string;
+}
+
+// Type-safe AI search
+const response: DotCMSAISearchResponse<Article> = await client.ai.search<Article>(
+    'machine learning tutorials',
+    'content_index',
+    {
+        query: {
+            limit: 20,
+            contentType: 'Article'
+        },
+        config: {
+            threshold: 0.75,
+            distanceFunction: DISTANCE_FUNCTIONS.cosine
+        }
+    }
+);
+
+// Access typed results with match information
+response.results.forEach(article => {
+    console.log(article.title);           // ✅ Type-safe: string
+    console.log(article.category);        // ✅ Type-safe: string
+
+    // Access AI match data
+    article.matches?.forEach(match => {
+        console.log(match.distance);      // ✅ Type-safe: number
+        console.log(match.extractedText); // ✅ Type-safe: string
+    });
+});
+```
+
+#### Typing Navigation
+
+```typescript
+import type { DotCMSNavigationItem } from '@dotcms/types';
+
+// Navigation is automatically typed
+const nav: DotCMSNavigationItem[] = await client.navigation.get('/', {
+    depth: 2,
+    languageId: 1
+});
+
+// Access typed navigation properties
+nav.forEach(item => {
+    console.log(item.title);    // ✅ Type-safe: string
+    console.log(item.href);     // ✅ Type-safe: string
+    console.log(item.children); // ✅ Type-safe: DotCMSNavigationItem[] | undefined
+});
+```
+
+#### Type-Safe Error Handling
+
+```typescript
+import type {
+    DotHttpError,
+    DotErrorPage,
+    DotErrorContent,
+    DotErrorAISearch
+} from '@dotcms/types';
+
+try {
+    const { pageAsset } = await client.page.get('/about-us');
+} catch (error) {
+    // Type guard for specific error types
+    if (error instanceof DotErrorPage) {
+        // TypeScript knows this is DotErrorPage
+        console.error('Page error:', error.message);
+        console.error('Context:', error.context);
+        if (error.httpError) {
+            console.error('Status:', error.httpError.status); // ✅ Type-safe
+        }
+    } else if (error instanceof DotErrorContent) {
+        // TypeScript knows this is DotErrorContent
+        console.error('Content error:', error.contentType);
+        console.error('Operation:', error.operation);
+    } else if (error instanceof DotErrorAISearch) {
+        // TypeScript knows this is DotErrorAISearch
+        console.error('AI Search error:', error.prompt);
+        console.error('Parameters:', error.params);
+    }
+}
+```
+
+#### Custom Content Types with Relationships
+
+```typescript
+import type { DotCMSBasicContentlet } from '@dotcms/types';
+
+// Define related content types
+interface Author extends DotCMSBasicContentlet {
+    name: string;
+    email: string;
+    bio: string;
+}
+
+interface Category extends DotCMSBasicContentlet {
+    categoryName: string;
+    description: string;
+}
+
+// Main content type with relationships
+interface BlogPost extends DotCMSBasicContentlet {
+    title: string;
+    body: string;
+    author: Author;        // Nested type
+    category: Category;    // Nested type
+    tags: string[];
+    publishDate: string;
+}
+
+// Fetch with depth to include relationships
+const response = await client.content
+    .getCollection<BlogPost>('Blog')
+    .depth(2)
+    .limit(5);
+
+// Access nested typed properties
+response.contentlets.forEach(post => {
+    console.log(post.title);              // ✅ string
+    console.log(post.author.name);        // ✅ string
+    console.log(post.author.email);       // ✅ string
+    console.log(post.category.categoryName); // ✅ string
+});
+```
+
+#### Using with Async/Await and Promises
+
+```typescript
+import type {
+    DotCMSPageAsset,
+    GetCollectionResponse
+} from '@dotcms/types';
+
+// Async function with typed return
+async function fetchBlogPosts(): Promise<GetCollectionResponse<BlogPost>> {
+    return await client.content
+        .getCollection<BlogPost>('Blog')
+        .limit(10);
+}
+
+// Promise chain with types
+client.page.get('/about-us')
+    .then((response: { pageAsset: DotCMSPageAsset }) => {
+        console.log(response.pageAsset.page.title);
+        return response;
+    })
+    .catch((error: DotErrorPage) => {
+        console.error(error.message);
+    });
+```
+
 ### How to Work with GraphQL
 
 GraphQL allows you to fetch exactly the data you need in a single request:
@@ -421,6 +770,111 @@ getCollection<T = DotCMSBasicContentlet>(
 const blogs = await client.content.getCollection('Blog').limit(10).page(1);
 ```
 
+### ai.search() Method
+
+> [!WARNING]
+> **Experimental Feature:** The AI API is currently experimental and may undergo breaking changes in future releases. Use with caution in production environments.
+
+Performs semantic search using AI embeddings to find content based on meaning rather than exact keyword matches.
+
+> [!NOTE]
+> **Prerequisites:** This feature requires dotAI to be activated in your dotCMS instance with a configured OpenAI API key. See the [dotAI setup documentation](https://dev.dotcms.com/docs/dotai) for configuration details.
+
+```typescript
+search<T extends DotCMSBasicContentlet>(
+  prompt: string,
+  indexName: string,
+  params?: DotCMSAISearchParams
+): Promise<DotCMSAISearchResponse<T>>
+```
+
+#### Parameters
+
+| Parameter   | Type                  | Required | Description                           |
+| ----------- | --------------------- | -------- | ------------------------------------- |
+| `prompt`    | string                | ✅       | Natural language search query         |
+| `indexName` | string                | ✅       | Name of the AI search index to query  |
+| `params`    | DotCMSAISearchParams  | ❌       | Search configuration options          |
+
+#### Search Parameters (params.query)
+
+| Option        | Type             | Description                              |
+| ------------- | ---------------- | ---------------------------------------- |
+| `limit`       | number           | Maximum number of results (default: 1000) |
+| `offset`      | number           | Number of results to skip (default: 0)   |
+| `contentType` | string           | Filter by specific content type          |
+| `languageId`  | string           | Filter by language ID                    |
+| `siteId`      | string           | Filter by site ID                        |
+
+#### AI Configuration (params.config)
+
+| Option             | Type   | Description                                     |
+| ------------------ | ------ | ----------------------------------------------- |
+| `threshold`        | number | Minimum similarity score (0-1, default: 0.5)    |
+| `distanceFunction` | string | Distance calculation method (default: cosine)   |
+| `responseLength`   | number | Maximum response length (default: 1024)         |
+
+#### Response
+
+```typescript
+interface DotCMSAISearchResponse<T> {
+    results: Array<T & {
+        matches?: Array<{
+            distance: number;      // Similarity score
+            extractedText: string; // Matched text excerpt
+        }>;
+    }>;
+}
+```
+
+#### Examples
+
+**Basic Search:**
+```typescript
+const results = await client.ai.search(
+    'machine learning articles',
+    'content_index'
+);
+```
+
+**With Parameters:**
+```typescript
+import { DISTANCE_FUNCTIONS } from '@dotcms/types';
+
+const results = await client.ai.search(
+    'AI tutorials',
+    'content_index',
+    {
+        query: {
+            limit: 20,
+            contentType: 'BlogPost',
+            languageId: '1'
+        },
+        config: {
+            threshold: 0.75,
+            distanceFunction: DISTANCE_FUNCTIONS.cosine
+        }
+    }
+);
+```
+
+**Promise-Style:**
+```typescript
+client.ai.search(
+    'content management best practices',
+    'content_index',
+    {
+        query: { limit: 10 },
+        config: { threshold: 0.8 }
+    }
+).then((response) => {
+    console.log('Found:', response.results.length);
+    return response;
+}).catch((error) => {
+    console.error('Search failed:', error.message);
+});
+```
+
 ### navigation.get() Method
 
 ```typescript
@@ -458,12 +912,13 @@ The SDK provides comprehensive error handling with specific error types for diff
 
 #### Error Types
 
-| Error Type          | When It's Thrown                           | Properties                                          |
-| ------------------- | ------------------------------------------ | --------------------------------------------------- |
-| `DotHttpError`      | HTTP/network failures (4xx/5xx, timeouts) | `status`, `statusText`, `headers`, `body`           |
-| `DotErrorPage`      | Page API failures                          | `httpError?`, `context` (query, variables)         |
-| `DotErrorContent`   | Content API failures                       | `contentType`, `operation`, `httpError?`, `query?` |
-| `DotErrorNavigation`| Navigation API failures                    | `path`, `httpError?`                               |
+| Error Type           | When It's Thrown                           | Properties                                          |
+| -------------------- | ------------------------------------------ | --------------------------------------------------- |
+| `DotHttpError`       | HTTP/network failures (4xx/5xx, timeouts) | `status`, `statusText`, `headers`, `body`           |
+| `DotErrorPage`       | Page API failures                          | `httpError?`, `context` (query, variables)         |
+| `DotErrorContent`    | Content API failures                       | `contentType`, `operation`, `httpError?`, `query?` |
+| `DotErrorAISearch`   | AI Search API failures                     | `prompt`, `params`, `httpError?`                   |
+| `DotErrorNavigation` | Navigation API failures                    | `path`, `httpError?`                               |
 
 #### Basic Error Handling
 ```typescript
@@ -513,6 +968,23 @@ try {
 }
 ```
 
+#### AI Search Error Handling
+```typescript
+try {
+    const results = await client.ai.search('machine learning', 'content_index');
+} catch (error) {
+    if (error instanceof DotErrorAISearch) {
+        console.error('AI Search error:', error.message);
+        console.error('Prompt:', error.prompt);
+        console.error('Index Name:', error.indexName);
+        console.error('Parameters:', error.params);
+        if (error.httpError) {
+            console.error('HTTP status:', error.httpError.status);
+        }
+    }
+}
+```
+
 #### Promise-Style Error Handling
 ```typescript
 // Content collections support .then() with error handling
@@ -571,13 +1043,14 @@ DotHttpError: "Network request failed"
 
 ### Choosing the Right Method
 
-The dotCMS Client SDK provides three core methods for fetching data. Use this quick guide to decide which one is best for your use case:
+The dotCMS Client SDK provides four core methods for fetching data. Use this quick guide to decide which one is best for your use case:
 
-| Method                    | Use When You Need...                                          | Best For                                                                                                                                                                                         |
-| ------------------------- | ------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `client.page.get()`       | A full page with layout, containers, and related content      | **Rendering entire pages** with a single request. Ideal for headless setups, SSR/SSG frameworks, and cases where you want everything—page structure, content, and navigation—tied to a URL path. |
+| Method                           | Use When You Need...                                          | Best For                                                                                                                                                                                         |
+| -------------------------------- | ------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `client.page.get()`              | A full page with layout, containers, and related content      | **Rendering entire pages** with a single request. Ideal for headless setups, SSR/SSG frameworks, and cases where you want everything—page structure, content, and navigation—tied to a URL path. |
 | `client.content.getCollection()` | A filtered list of content items from a specific content type | Populating dynamic blocks, lists, search results, widgets, or reusable components.                                                                                                               |
-| `client.navigation.get()` | Only the site's navigation structure (folders and links)      | Standalone menus or use cases where navigation is needed outside of page context.                                                                                                                |
+| `client.ai.search()`             | Semantic/AI-powered content discovery based on natural language | **Intelligent search experiences** where users describe what they're looking for in natural language. Great for search features, content recommendations, and finding relevant content by meaning rather than exact keywords. ⚠️ **Experimental API** |
+| `client.navigation.get()`        | Only the site's navigation structure (folders and links)      | Standalone menus or use cases where navigation is needed outside of page context.                                                                                                                |
 
 #### Start with `page.get()`: The One-Request Solution
 
@@ -595,27 +1068,27 @@ Only use `content.getCollection()` or `navigation.get()` if you have advanced ne
 
 ### Architecture Overview
 
-The SDK follows a client-builder pattern with three main APIs:
+The SDK follows a client-builder pattern with four main APIs:
 
 - **Page API** (`client.page.get()`) - Fetches complete page content with layout and containers
 - **Content API** (`client.content.getCollection()`) - Builder pattern for querying content collections
+- **AI API** (`client.ai.search()`) - AI-powered semantic search using embeddings and vector similarity ⚠️ **Experimental**
 - **Navigation API** (`client.navigation.get()`) - Fetches site navigation structure
 
 All APIs support:
 - Type-safe responses with TypeScript
-- GraphQL query extensions
+- GraphQL query extensions (Page API)
 - Localization and personalization
 - Browser and Node.js compatibility
 
-## Support & Contributing
-
-### dotCMS Support
+## Support
 
 We offer multiple channels to get help with the dotCMS Client SDK:
 
 -   **GitHub Issues**: For bug reports and feature requests, please [open an issue](https://github.com/dotCMS/core/issues/new/choose) in the GitHub repository.
 -   **Community Forum**: Join our [community discussions](https://community.dotcms.com/) to ask questions and share solutions.
 -   **Stack Overflow**: Use the tag `dotcms-client` when posting questions.
+-   **Enterprise Support**: Enterprise customers can access premium support through the [dotCMS Support Portal](https://helpdesk.dotcms.com/support/).
 
 When reporting issues, please include:
 
@@ -624,11 +1097,9 @@ When reporting issues, please include:
 -   Minimal reproduction steps
 -   Expected vs. actual behavior
 
-Enterprise customers can access premium support through the [dotCMS Support Portal](https://dev.dotcms.com/docs/help).
-
-### How To Contribute
+## Contributing
 
-GitHub pull requests are the preferred method to contribute code to dotCMS. We welcome contributions to the DotCMS UVE SDK! If you'd like to contribute, please follow these steps:
+GitHub pull requests are the preferred method to contribute code to dotCMS. We welcome contributions to the dotCMS Client SDK! If you'd like to contribute, please follow these steps:
 
 1. Fork the repository [dotCMS/core](https://github.com/dotCMS/core)
 2. Create a feature branch (`git checkout -b feature/amazing-feature`)
@@ -640,6 +1111,56 @@ Please ensure your code follows the existing style and includes appropriate test
 
 ## Changelog
 
+### v1.3.0
+
+#### ✨ Added - AI Search API (Experimental)
+
+> **⚠️ Experimental Feature:** The AI API is experimental and may undergo breaking changes in future releases.
+
+**New Features:**
+- **`client.ai.search()`** - AI-powered semantic search using embeddings and vector similarity
+- Search content by meaning rather than exact keyword matches
+- Support for custom AI search indexes
+- Configurable similarity thresholds and distance functions
+- `DotErrorAISearch` error class for AI-specific error handling with prompt and index context
+
+**Prerequisites:**
+- Requires dotAI to be activated in your dotCMS instance
+- OpenAI API key must be configured
+- PostgreSQL 15+ with pgvector extension
+- Content indexes must be created in dotAI
+
+**Basic Usage:**
+```typescript
+// Semantic search with required index name
+const results = await client.ai.search(
+    'machine learning articles',
+    'content_index'
+);
+
+// With advanced configuration
+const results = await client.ai.search(
+    'AI tutorials',
+    'content_index',
+    {
+        query: {
+            limit: 20,
+            contentType: 'BlogPost'
+        },
+        config: {
+            threshold: 0.75,
+            distanceFunction: DISTANCE_FUNCTIONS.cosine
+        }
+    }
+);
+```
+
+**Key Features:**
+- Type-safe with full TypeScript support
+- Supports multiple distance functions (cosine, L2, inner product, etc.)
+- Returns match scores and extracted text excerpts
+- Integrates seamlessly with existing content workflows
+
 ### v1.1.1
 
 Version 1.1.1 introduces significant improvements to error handling and HTTP client architecture. Most applications will continue to work without changes.
@@ -748,7 +1269,7 @@ import { RequestOptions } from '@dotcms/types';
 import { DotRequestOptions } from '@dotcms/types';
 ```
 
-### Licensing Information
+## Licensing
 
 dotCMS comes in multiple editions and as such is dual-licensed. The dotCMS Community Edition is licensed under the GPL 3.0 and is freely available for download, customization, and deployment for use within organizations of all stripes. dotCMS Enterprise Editions (EE) adds several enterprise features and is available via a supported, indemnified commercial license from dotCMS. For the differences between the editions, see [the feature page](http://www.dotcms.com/cms-platform/features).