@dotcms/react - npm Package Compare versions

Comparing version 1.2.0 to 1.2.1-next.1

src/lib/next/hooks/useAISearch.d.ts

+import { DotCMSBasicContentlet } from '@dotcms/types';
+import { DotCMSAISearchProps, DotCMSAISearchValue } from '../shared/types';
+/**
+ * Hook to search for contentlets using AI.
+ * @template T - The type of the contentlet.
+ * @param client - The client to use for the search.
+ * @param indexName - The name of the index to search in.
+ * @param params - The parameters for the search.
+ * @returns The search results.
+ *
+ * @example
+ * ```typescript
+ * const { results, status, search, reset } = useAISearch<BlogPost>({
+ *   client: dotCMSClient,
+ *   indexName: 'blog-search-index',
+ *   params: {
+ *     query: {
+ *       limit: 10,
+ *       offset: 0,
+ *       contentType: 'Blog'
+ *     },
+ *     config: {
+ *       threshold: 0.5,
+ *       responseLength: 1024
+ *     }
+ *   }
+ * });
+ * ```
+ */
+export declare const useAISearch: <T extends DotCMSBasicContentlet>({ client, indexName, params }: DotCMSAISearchProps) => DotCMSAISearchValue<T>;

src/lib/next/shared/types.d.ts

+import { createDotCMSClient } from '@dotcms/client';
+import { DotCMSAISearchContentletData, DotCMSAISearchParams, DotCMSAISearchResponse, DotCMSBasicContentlet, DotCMSEntityStatus } from '@dotcms/types';
+/**
+ * Return type of the AI Search context
+ * @interface DotCMSAISearchContextValue
+ * @template T - The content type extending DotCMSBasicContentlet
+ */
+export interface DotCMSAISearchValue<T extends DotCMSBasicContentlet> {
+    response: DotCMSAISearchResponse<T> | null;
+    results: DotCMSAISearchContentletData<T>[];
+    status: DotCMSEntityStatus;
+    search: (prompt: string) => Promise<void>;
+    reset: () => void;
+}
+/**
+ * Props for the DotCMSAISearchProvider
+ * @interface DotCMSAISearchProviderProps
+ * @template T - The content type extending DotCMSBasicContentlet
+ */
+export interface DotCMSAISearchProps {
+    client: ReturnType<typeof createDotCMSClient>;
+    indexName: string;
+    params: DotCMSAISearchParams;
+}

package.json

 {
   "name": "@dotcms/react",
-  "version": "1.2.0",
+  "version": "1.2.1-next.1",
   "peerDependencies": {
@@ -54,2 +54,2 @@ "react": ">=18",
   "types": "./index.esm.d.ts"
-}
+}

README.md

@@ -23,2 +23,3 @@ # dotCMS React SDK
     -   [useDotCMSShowWhen](#usedotcmsshowwhen)
+    -   [useAISearch](#useaisearch)
 -   [Troubleshooting](#troubleshooting)
@@ -447,2 +448,137 @@ -   [Common Issues & Solutions](#common-issues--solutions)
 
+### useAISearch
+
+`useAISearch` is a hook that enables AI-powered semantic search capabilities for your dotCMS content. It manages search state, handles API calls, and provides real-time status updates.
+
+| Param       | Type                    | Required | Description                                                                    |
+| ----------- | ----------------------- | -------- | ------------------------------------------------------------------------------ |
+| `client`    | `DotCMSClient`          | ✅       | The dotCMS client instance created with `createDotCMSClient()`                |
+| `indexName` | `string`                | ✅       | Name of the AI search index to query                                           |
+| `params`    | `DotCMSAISearchParams`  | ✅       | Search configuration including query params (limit, offset) and AI config      |
+
+#### Return Value
+
+The hook returns an object with the following properties:
+
+| Property   | Type                                     | Description                                                    |
+| ---------- | ---------------------------------------- | -------------------------------------------------------------- |
+| `response` | `DotCMSAISearchResponse<T> \| null`      | Full search response including metadata and results            |
+| `results`  | `DotCMSAISearchContentletData<T>[] \| undefined` | Array of search results with match scores          |
+| `status`   | `DotCMSEntityStatus`                      | Current state: `IDLE`, `LOADING`, `SUCCESS`, or `ERROR`        |
+| `search`   | `(prompt: string) => Promise<void>`      | Function to execute a search with a text prompt                |
+| `reset`    | `() => void`                             | Function to reset search state to idle                         |
+
+#### Usage
+
+```tsx
+'use client';
+
+import { useState } from 'react';
+import { useAISearch } from '@dotcms/react';
+import type { DotCMSBasicContentlet } from '@dotcms/types';
+import { dotCMSClient } from '@/lib/dotCMSClient';
+
+interface BlogPost extends DotCMSBasicContentlet {
+    body: string;
+    author: string;
+}
+
+const AISearchComponent = () => {
+    const [searchQuery, setSearchQuery] = useState('');
+
+    const { results, status, search, reset } = useAISearch<BlogPost>({
+        client: dotCMSClient,
+        indexName: 'blog-search-index',
+        params: {
+            query: {
+                limit: 10,
+                offset: 0,
+                contentType: 'Blog'
+            },
+            config: {
+                threshold: 0.5,
+                responseLength: 1024
+            }
+        }
+    });
+
+    const handleSearch = async () => {
+        if (searchQuery.trim()) {
+            await search(searchQuery);
+        }
+    };
+
+    const handleReset = () => {
+        setSearchQuery('');
+        reset();
+    };
+
+    return (
+        <div className="search-container">
+            <div className="search-bar">
+                <input
+                    type="text"
+                    value={searchQuery}
+                    onChange={(e) => setSearchQuery(e.target.value)}
+                    placeholder="Search with AI..."
+                />
+                <button onClick={handleSearch} disabled={status.state === 'LOADING'}>
+                    {status.state === 'LOADING' ? 'Searching...' : 'Search'}
+                </button>
+                <button onClick={handleReset}>Reset</button>
+            </div>
+
+            {status.state === 'ERROR' && (
+                <div className="error">
+                    Error: {status.error.message}
+                </div>
+            )}
+
+            {status.state === 'SUCCESS' && results && (
+                <div className="results">
+                    <h2>Found {results.length} results</h2>
+                    {results.map((result) => (
+                        <article key={result.identifier}>
+                            <h3>{result.title}</h3>
+                            <p>Author: {result.author}</p>
+                            {result.matches?.map((match, idx) => (
+                                <div key={idx} className="match">
+                                    <span>Relevance: {match.distance.toFixed(2)}</span>
+                                    <p>{match.extractedText}</p>
+                                </div>
+                            ))}
+                        </article>
+                    ))}
+                </div>
+            )}
+        </div>
+    );
+};
+
+export default AISearchComponent;
+```
+
+#### Features
+
+- **Automatic State Management**: Handles loading, success, error, and idle states
+- **Type-Safe Results**: Generic typing ensures type safety for your content types
+- **Search Validation**: Automatically validates and trims search prompts
+- **Configurable Parameters**: Support for pagination, thresholds, and AI configuration
+- **Error Handling**: Provides detailed error information through status state
+- **Reset Capability**: Easy state reset for clearing search results
+
+#### Configuration Options
+
+**Query Parameters (`params.query`):**
+- `limit`: Maximum number of results (default: 1000)
+- `offset`: Number of results to skip (default: 0)
+- `siteId`: Filter by specific site
+- `contentType`: Filter by content type
+- `languageId`: Filter by language
+
+**AI Configuration (`params.config`):**
+- `threshold`: Minimum similarity score (default: 0.5)
+- `distanceFunction`: Vector distance algorithm (default: cosine)
+- `responseLength`: Maximum response text length (default: 1024)
+
 ## Troubleshooting
@@ -449,0 +585,0 @@

src/index.d.ts

@@ -8,1 +8,3 @@ export { DotCMSLayoutBody } from './lib/next/components/DotCMSLayoutBody/DotCMSLayoutBody';
 export { DotCMSLayoutBodyProps } from './lib/next/components/DotCMSLayoutBody/DotCMSLayoutBody';
+export { useAISearch } from './lib/next/hooks/useAISearch';
+export type { DotCMSAISearchValue, DotCMSAISearchProps } from './lib/next/shared/types';

New alerts

Network access

Supply chain risk

This module accesses the network.

Found 1 instance in 1 package

Uses eval

Supply chain risk

Package uses dynamic code execution (e.g., eval()), which is a dangerous practice. This can prevent the code from running in certain environments and increases the risk that the code may contain exploits or malicious behavior.

Found 1 instance in 1 package

Long strings

Supply chain risk

Contains long string literals, which may be a sign of obfuscated or packed code.

Found 1 instance in 1 package

No v1

Quality

Package is not semver >=1. This means it is not stable and does not support ^ ranges.

Found 1 instance in 1 package

URL strings

Supply chain risk

Package contains fragments of external URLs or IP addresses, which the package may be accessing at runtime.

Found 1 instance in 1 package

Fixed alerts

Network access

Supply chain risk

This module accesses the network.

Found 1 instance in 1 package

Uses eval

Supply chain risk

Package uses dynamic code execution (e.g., eval()), which is a dangerous practice. This can prevent the code from running in certain environments and increases the risk that the code may contain exploits or malicious behavior.

Found 1 instance in 1 package

Long strings

Supply chain risk

Contains long string literals, which may be a sign of obfuscated or packed code.

Found 1 instance in 1 package

URL strings

Supply chain risk

Package contains fragments of external URLs or IP addresses, which the package may be accessing at runtime.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

314541

18.77%

Number of package files

35

6.06%

Lines of code

7721

19%

Number of lines in readme file

753

22.04%

Worsened metrics

Number of low quality alerts

1

Infinity%

Number of low supply chain risk alerts

58

56.76%

No dependency changes