n8n-nodes-meilisearch 0.1.2 → 0.1.5

package/README.md

@@ -1,21 +1,26 @@
 # n8n-nodes-meilisearch
 
-This is an n8n community node. It lets you use the meilisearch REST API in your n8n workflows.
+A comprehensive n8n community node for interacting with the Meilisearch REST API. This node provides full coverage of Meilisearch operations including document management, index operations, search functionality, task management, and more.
 
-[Meilisearch](https://meilisearch.com) 
-An open-source, lightning-fast, and hyper-relevant search engine that fits effortlessly into your apps, websites, and workflow.
+## About Meilisearch
 
-[meilisearch API Docs](https://docs.meilisearch.com/reference/api/overview.html)
+[Meilisearch](https://meilisearch.com) is an open-source, lightning-fast, and hyper-relevant search engine that fits effortlessly into your apps, websites, and workflows. It provides a RESTful API for managing search indexes, documents, and performing lightning-fast searches.
 
-[n8n](https://n8n.io/) is a [fair-code licensed](https://docs.n8n.io/reference/license/) workflow automation platform.
+## About n8n
 
-[Installation](#installation)  
-[Operations](#operations)  
-[Credentials](#credentials)
-[Compatibility](#compatibility)  
-[Usage](#usage) 
-[Resources](#resources)  
-[Version history](#version-history) 
+[n8n](https://n8n.io/) is a [fair-code licensed](https://docs.n8n.io/reference/license/) workflow automation platform that allows you to connect different services and automate tasks.
+
+## Table of Contents
+
+- [Installation](#installation)
+- [Operations](#operations)
+- [Credentials](#credentials)
+- [Compatibility](#compatibility)
+- [Usage](#usage)
+- [Examples](#examples)
+- [Resources](#resources)
+- [Version History](#version-history)
+- [Contributing](#contributing) 
 
 ## Installation
 
@@ -23,55 +28,134 @@ Follow the [installation guide](https://docs.n8n.io/integrations/community-nodes
 
 ## Operations
 
--  Documents
-   -  Add or replace documents
-   -  Add or update documents
-   -  Delete batch of documents by UID
-   -  Delete all documents in an index
-   -  Get documents
-   -  Get one document by UID
--  General
-   -  Create a dump
-   -  Get all index stats
-   -  Get health
-   -  Get version information
--  Indexes
-   -  Create an index
-   -  Get stats of an index
-   -  List indexes
-   -  Search index
-   -  Swap indexes
--  Keys
-   -  Create a new key
-   -  Delete a key by its uid or key
-   -  Get a single key by its uid or key
-   -  Get many api keys
-   -  Update a key by its uid or key
--  Search
-   -  Search an index (Also found in indexes section)
--  Settings
-   -  Get the settings of an index
-   -  Reset the settings of an index
-   -  Update the settings of an index
--  Tasks
-   -  Cancel tasks
-   -  Delete tasks
-   -  Get all tasks
-   -  Get one task by UID
+This node supports all major Meilisearch API operations organized by resource type:
+
+### Documents
+- **Add or Replace Documents** - Add new documents or replace existing ones in an index
+  - Optional: Wait for task completion with configurable polling
+  - Optional: Primary key field mapping for flexible document structures
+- **Add or Update Documents** - Add new documents or update existing ones (partial updates)
+  - Optional: Wait for task completion with configurable polling
+  - Optional: Primary key field mapping for flexible document structures
+- **Delete Batch of Documents** - Delete multiple documents by their UIDs
+- **Delete All Documents** - Remove all documents from an index
+- **Get Documents** - Retrieve multiple documents with pagination and filtering support
+- **Get One Document** - Retrieve a single document by its UID
+
+### General
+- **Create a Dump** - Generate a database dump for backup or migration
+- **Get All Index Stats** - Retrieve statistics about all indexes and the database
+- **Get Health** - Check the health status of your Meilisearch instance
+- **Get Version** - Get the version information of your Meilisearch instance
+
+### Indexes
+- **Create an Index** - Create a new search index with optional primary key
+- **Get Stats of an Index** - Retrieve detailed statistics for a specific index
+- **List Indexes** - List all indexes with pagination support
+- **Search Index** - Perform a search query on an index (also available in Search resource)
+- **Swap Indexes** - Swap documents, settings, and task history between index pairs
+
+### Keys
+- **Create an API Key** - Create a new API key with specific permissions
+- **Delete an API Key** - Delete a key by its UID or key value
+- **Get an API Key** - Retrieve details of a specific API key
+- **Get API Keys** - List all API keys (returns 20 most recently created)
+- **Update an API Key** - Update permissions or expiration of an existing key
+
+### Search
+- **Search Index** - Perform advanced searches with filtering, faceting, highlighting, and more
+- **Multi-Search** - Perform multiple searches across different indexes in a single request
+
+### Settings
+- **Get Index Settings** - Retrieve all settings for an index
+- **Reset Index Settings** - Reset all settings to their default values
+- **Update Index Settings** - Update searchable attributes, ranking rules, typo tolerance, synonyms, and more
+
+### Tasks
+- **Get All Tasks** - List all tasks with filtering options (by status, type, index, date, etc.)
+- **Get a Single Task** - Retrieve details of a specific task by UID
+- **Wait for Task** - Poll a task until completion (succeeded, failed, or canceled) with exponential backoff
+- **Cancel Tasks** - Cancel enqueued or processing tasks
+- **Delete Tasks** - Delete finished tasks (succeeded, failed, or canceled)
 
 ## Credentials
 
-By [providing Meilisearch with a master key at launch](https://docs.meilisearch.com/learn/security/master_api_keys.html#protecting-a-meilisearch-instance), you protect your instance from unauthorized requests. The provided master key must be at least 16 bytes. From then on, you must include the `Authorization` header along with a valid API key to access protected routes (all routes except /health.)
+### Setting Up Credentials
+
+1. **Host URL**: Enter your Meilisearch instance URL (e.g., `https://your-meilisearch-instance.com` or `http://localhost:7700`)
+2. **API Key**: Provide your Meilisearch API key
+
+### Security Notes
+
+By [providing Meilisearch with a master key at launch](https://docs.meilisearch.com/learn/security/master_api_keys.html#protecting-a-meilisearch-instance), you protect your instance from unauthorized requests. The provided master key must be at least 16 bytes. From then on, you must include the `Authorization` header along with a valid API key to access protected routes (all routes except `/health`).
 
-The credentials type provided in this node send an `Authorization` header with the key you provide. e.g. `Authorization: Bearer YOURKEY`
+The credentials type provided in this node automatically sends an `Authorization` header with the key you provide:
+```
+Authorization: Bearer YOURKEY
+```
+
+### Credential Testing
+
+The credentials are tested against the `/version` endpoint. You can save your credentials regardless of the test result, but ensure your API key has the necessary permissions for the operations you plan to use.
 
 ## Compatibility
 
-This is subject to change.
+- **n8n**: Compatible with n8n version 2.1.0 and above (tested with 2.1.4)
+- **Meilisearch**: Compatible with Meilisearch v1.0.0 and above
+- **Node.js**: Requires Node.js 16.x or higher
+- **TypeScript**: Built with TypeScript 5.3.3
+
+*Note: Compatibility is subject to change with future updates.*
 
 ## Usage
 
-Use as you would any node- I tried to include useful descriptions and hints for all fields.
+### Basic Workflow
+
+1. Add the Meilisearch node to your workflow
+2. Configure your credentials (Host URL and API Key)
+3. Select the resource type (Documents, Indexes, Search, etc.)
+4. Choose the operation you want to perform
+5. Fill in the required parameters
+6. Execute the workflow
+
+### Tips
+
+- **Index UID Fields**: When your API key has proper permissions, index UID fields will show as dropdowns with available indexes
+- **JSON Input**: For document operations, you can use n8n expressions:
+  - `{{ $json }}` - For a single object (recommended)
+  - `{{ JSON.stringify($json) }}` - For stringified JSON
+  - `{{ JSON.stringify($input.all().map(j => j.json)) }}` - For multiple items
+- **Primary Key Field Mapping**: If your documents use a different field name than the index's primary key, specify it in the "Primary Key Field" option. The node will automatically map it to the correct field name.
+- **Wait for Completion**: Enable "Wait for Completion" on document operations to automatically poll until the task completes. Choose between fixed interval or exponential backoff polling.
+- **Task Management**: Many operations return a task UID. Use the "Wait for Task" operation or enable "Wait for Completion" on document operations to automatically wait for tasks to finish.
+- **Field Hints**: Most fields include helpful hints and examples in their descriptions
+
+### Common Patterns
+
+#### Adding Documents
+1. Use "Documents" → "Add or Replace Documents" or "Add or Update Documents"
+2. Select your index from the dropdown
+3. Provide documents using `{{ $json }}` for a single object or `{{ JSON.stringify($input.all().map(j => j.json)) }}` for multiple items
+4. (Optional) Specify "Primary Key Field" if your documents use a different field name than the index's primary key
+5. (Optional) Enable "Wait for Completion" to automatically wait for the task to finish
+
+#### Searching
+1. **Single Index Search**: Use "Search" → "Search Index" or "Indexes" → "Search Index"
+   - Select your index
+   - Enter your search query
+   - Configure additional fields like filters, facets, pagination, etc.
+2. **Multi-Index Search**: Use "Search" → "Multi-Search"
+   - Add multiple queries, each targeting a different index
+   - Configure search parameters per query (filters, facets, pagination, etc.)
+   - Get results from multiple indexes in a single request
+
+#### Waiting for Task Completion
+1. **Automatic (Recommended)**: Enable "Wait for Completion" on document operations (Add/Replace/Update Documents)
+   - Configure polling interval and timeout
+   - Choose between fixed interval or exponential backoff
+2. **Manual**: Use "Tasks" → "Wait for Task" operation
+   - Provide the task UID from a previous operation
+   - Configure polling settings
 
 ## Updating
 
@@ -118,24 +202,111 @@ else
 fi
 ```
 
+## Examples
+
+### Example 1: Adding Documents to an Index
+
+```json
+{
+  "resource": "documents",
+  "operation": "addOrReplaceDocuments",
+  "uid": "movies",
+  "documentsJson": "[{\"id\": 1, \"title\": \"Inception\", \"year\": 2010}, {\"id\": 2, \"title\": \"The Matrix\", \"year\": 1999}]"
+}
+```
+
+### Example 2: Searching with Filters
+
+```json
+{
+  "resource": "search",
+  "operation": "search",
+  "uid": "movies",
+  "additionalFields": {
+    "query": "sci-fi",
+    "filter": "year > 2000",
+    "limit": 20
+  }
+}
+```
+
+### Example 3: Checking Task Status
+
+```json
+{
+  "resource": "tasks",
+  "operation": "getTask",
+  "uid": 12345
+}
+```
+
 ## Resources
 
-* [n8n community nodes documentation](https://docs.n8n.io/integrations/community-nodes/)
-* [n8n-nodes-meilisearch repository](https://github.com/Bwilliamson55/n8n-nodes-meilisearch)
-* [Official Meilisearch API Reference](https://www.meilisearch.com/docs/reference/api/overview)
-* [Official Meilisearch Docs](https://www.meilisearch.com/docs/learn/what_is_meilisearch/overview)
-
-## Version history
-
-- 0.1.0 - Initial release
-  - Almost all API endpoints accounted for in node operations
-    - TODO: 
-      - multi-search, 
-      - index settings sub-routes, 
-      - (Done in 0.1.1) auto-populating options where possible
-        - Due to the very dynamic permissions, getting options has a high chance of failure. For MVP I opted to skip loading options dynamically, such as index names. 
-    - Currently index settings can be interacted with, but as the entire settings object for each index
-- 0.1.1 - QOL Updates
-  - When adding or updating documents, the "Documents JSON" field is now far more forgiving. Very broken JSON will throw an error before sending as well.
-  - Some array type input fields are now also validated and transformed as JSON
-	- UID fields will be a dropdown when credentials have the proper permissions
+### Documentation
+- [n8n Community Nodes Documentation](https://docs.n8n.io/integrations/community-nodes/)
+- [Official Meilisearch API Reference](https://www.meilisearch.com/docs/reference/api/overview)
+- [Official Meilisearch Documentation](https://www.meilisearch.com/docs/learn/what_is_meilisearch/overview)
+- [Meilisearch Tasks Documentation](https://www.meilisearch.com/docs/learn/async/working_with_tasks)
+
+### Repository
+- [n8n-nodes-meilisearch GitHub Repository](https://github.com/Bwilliamson55/n8n-nodes-meilisearch)
+
+### Support
+- [Meilisearch Discord](https://discord.gg/meilisearch)
+- [n8n Community Forum](https://community.n8n.io/)
+
+## Version History
+
+### 0.1.4 (Current)
+- **Multi-Search Support**: Added "Multi-Search" operation to search across multiple indexes in a single request
+  - Full support for all search parameters per query (filters, facets, pagination, etc.)
+  - Configure multiple queries with different indexes and parameters
+- **Fixed 415 Errors**: Resolved Content-Type header issues in search and multi-search operations
+- **Enhanced Body Parameter Handling**: Improved request body construction for POST operations
+
+### 0.1.3
+- **Wait for Task Completion**: Added automatic task polling for document operations
+  - Configurable polling intervals with exponential backoff option
+  - Fixed interval or exponential backoff modes
+  - Configurable timeout and max polling interval
+- **Wait for Task Operation**: New standalone operation to poll any task until completion
+- **Primary Key Field Mapping**: Automatic field mapping for documents with different primary key field names
+  - Validates that specified field exists in all documents
+  - Automatically transforms documents to match index's primary key field
+- **Enhanced JSON Input**: Improved support for object inputs (e.g., `{{ $json }}`)
+- **Better Error Messages**: More detailed JSON validation errors with position information
+- **Updated Dependencies**: Upgraded to n8n-workflow 2.2.1, TypeScript 5.3.3, and other dependencies
+
+### 0.1.2
+- Previous stable version
+
+### 0.1.1 - QOL Updates
+- Improved JSON validation for document operations with better error messages
+- Array type input fields now validated and transformed as JSON
+- UID fields display as dropdowns when credentials have proper permissions
+- Enhanced field descriptions and hints
+
+### 0.1.0 - Initial Release
+- Comprehensive coverage of Meilisearch API endpoints
+- Support for Documents, General, Indexes, Keys, Search, Settings, and Tasks resources
+- Auto-populating options for index UIDs (when permissions allow)
+- Full settings management (as entire settings object)
+
+### Known Limitations & Planned Features
+- **Index Settings Sub-routes**: Currently supports full settings object only (sub-routes planned for future version)
+- See [PLANNING.md](./PLANNING.md) for detailed roadmap
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.
+
+### Development Setup
+
+1. Clone the repository
+2. Install dependencies: `npm install`
+3. Build the project: `npm run build`
+4. Run linting: `npm run lint`
+
+### Reporting Issues
+
+If you encounter any issues or have feature requests, please open an issue on the [GitHub repository](https://github.com/Bwilliamson55/n8n-nodes-meilisearch/issues).

package/dist/nodes/Meilisearch/DocumentsDescription.d.ts

@@ -1,5 +1,5 @@
 import { type INodeProperties } from 'n8n-workflow';
-export declare function validateJSON(json: string | undefined): any;
+export declare function validateJSON(json: string | undefined | any): any;
 export declare const documentsOperations: INodeProperties[];
 export declare const documentsFields: INodeProperties[];
 export declare const documentsAdditionalFields: INodeProperties[];