@algolia/n8n-nodes-algolia 0.6.0 → 0.8.0

package/README.md

@@ -16,108 +16,180 @@ Algolia is a hosted search API that provides search-as-a-service solutions. It o
 
 Follow the [installation guide](https://docs.n8n.io/integrations/community-nodes/installation/) in the n8n community nodes documentation.
 
+## Credentials
+
+To use this node, you need to authenticate with Algolia using API credentials.
+
+### Prerequisites
+
+1. [Sign up](https://dashboard.algolia.com/users/sign_up) or [log into](https://dashboard.algolia.com/users/sign_in) your Algolia account
+2. In your Algolia dashboard, go to [Settings](https://dashboard.algolia.com/account/overview) > [API Keys](https://dashboard.algolia.com/account/api-keys/all)
+3. Copy your Application ID
+4. Copy your Admin API Key
+   - Required for if you want to manage your API keys from n8n - otherwise the Write API Key should be enough)
+
+![API Keys page](assets/algolia-credentials.png)
+
+5. In n8n, create new Algolia API credentials with:
+   - **Application ID**: Your Algolia Application ID
+   - **Admin API Key**: Your Algolia Admin API Key
+
+![Credentials page](assets/n8n-credentials.png)
+
 ## Operations
 
 This node supports the following operations:
 
 <!-- THE FOLLOWING SECTION IS GENERATED BY CI. ANY CHANGES WILL BE OVERRIDDEN -->
 <!-- OPERATIONS START -->
+
 ### Advanced
-- **Get logs** - The request must be authenticated by an API key with the [`logs` ACL](https://www.algolia.com/doc/guides/security/api-keys/#access-control-list-acl).
-- **Get app task** - Checks the status of a given application task.
+
+- **Retrieve log entries** - The request must be authenticated by an API key with the [`logs` ACL](https://www.algolia.com/doc/guides/security/api-keys/#access-control-list-acl).
+- **Check application task status** - Checks the status of a given application task.
 
 ### Api Keys
-- **List api keys** - Lists all API keys associated with your Algolia application, including their permissions and restrictions.
-- **Add api key** - Creates a new API key with specific permissions and restrictions.
-- **Get api key** - Gets the permissions and restrictions of an API key.
-- **Update api key** - Replaces the permissions of an existing API key.
-- **Delete api key** - Deletes the API key.
-- **Restore api key** - Restores a deleted API key.
+
+- **List API keys** - Lists all API keys associated with your Algolia application, including their permissions and restrictions.
+- **Create an API key** - Creates a new API key with specific permissions and restrictions.
+- **Retrieve API key permissions** - Gets the permissions and restrictions of an API key.
+- **Update an API key** - Replaces the permissions of an existing API key.
+- **Delete an API key** - Deletes the API key.
+- **Restore an API key** - Restores a deleted API key.
 
 ### Clusters
-- **Assign user id** - Assigns or moves a user ID to a cluster.
-- **List user ids** - Lists the userIDs assigned to a multi-cluster application.
-- **Batch assign user ids** - Assigns multiple user IDs to a cluster.
-- **Get top user ids** - Get the IDs of the 10 users with the highest number of records per cluster.
-- **Get user id** - Returns the user ID data stored in the mapping.
-- **Remove user id** - Deletes a user ID and its associated data from the clusters.
+
+- **Assign or move a user ID** - Assigns or moves a user ID to a cluster.
+- **List user IDs** - Lists the userIDs assigned to a multi-cluster application.
+- **Assign multiple userIDs** - Assigns multiple user IDs to a cluster.
+- **Get top user IDs** - Get the IDs of the 10 users with the highest number of records per cluster.
+- **Retrieve user ID** - Returns the user ID data stored in the mapping.
+- **Delete user ID** - Deletes a user ID and its associated data from the clusters.
 - **List clusters** - Lists the available clusters in a multi-cluster setup.
-- **Search user ids** - Since it can take a few seconds to get the data from the different clusters,
-- **Has pending mappings** - To determine when the time-consuming process of creating a large batch of users or migrating users from one cluster to another is complete, this operation retrieves the status of the process.
+- **Search for user IDs** - Since it can take a few seconds to get the data from the different clusters,
+- **Get migration and user mapping status** - To determine when the time-consuming process of creating a large batch of users or migrating users from one cluster to another is complete, this operation retrieves the status of the process.
 
 ### Dictionaries
-- **Batch dictionary entries** - Adds or deletes multiple entries from your plurals, segmentation, or stop word dictionaries.
+
+- **Add or delete dictionary entries** - Adds or deletes multiple entries from your plurals, segmentation, or stop word dictionaries.
 - **Search dictionary entries** - Searches for standard and custom dictionary entries.
-- **Get dictionary settings** - Retrieves the languages for which standard dictionary entries are turned off.
-- **Set dictionary settings** - Turns standard stop word dictionary entries on or off for a given language.
-- **Get dictionary languages** - Lists supported languages with their supported dictionary types and number of custom entries.
+- **Retrieve dictionary settings** - Retrieves the languages for which standard dictionary entries are turned off.
+- **Update dictionary settings** - Turns standard stop word dictionary entries on or off for a given language.
+- **List available languages** - Lists supported languages with their supported dictionary types and number of custom entries.
 
 ### Indices
-- **Delete index** - Deletes an index and all its settings.
-- **Get settings** - Retrieves an object with non-null index settings.
-- **Set settings** - Update the specified index settings.
-- **Get task** - Checks the status of a given task.
-- **Operation index** - Copies or moves (renames) an index within the same Algolia application.
+
+- **Delete an index** - Deletes an index and all its settings.
+- **Retrieve index settings** - Retrieves an object with non-null index settings.
+- **Update index settings** - Update the specified index settings.
+- **Check task status** - Checks the status of a given task.
+- **Copy or move an index** - Copies or moves (renames) an index within the same Algolia application.
 - **List indices** - Lists all indices in the current Algolia application.
 
 ### Records
-- **Save object** - Adds a record to an index or replaces it.
-- **Get object** - Retrieves one record by its object ID.
-- **Add or update object** - If a record with the specified object ID exists, the existing record is replaced.
-- **Delete object** - Deletes a record by its object ID.
-- **Delete by** - This operation doesn't accept empty filters.
-- **Clear objects** - Deletes only the records from an index while keeping settings, synonyms, and rules.
-- **Partial update object** - Adds new attributes to a record, or updates existing ones.
-- **Batch** - Adds, updates, or deletes records in one index with a single API request.
-- **Multiple batch** - Adds, updates, or deletes records in multiple indices with a single API request.
-- **Get objects** - Retrieves one or more records, potentially from different indices.
+
+- **Add a new record (with auto-generated object ID)** - Adds a record to an index or replaces it.
+- **Retrieve a record** - Retrieves one record by its object ID.
+- **Add or replace a record** - If a record with the specified object ID exists, the existing record is replaced.
+- **Delete a record** - Deletes a record by its object ID.
+- **Delete records matching a filter** - This operation doesn't accept empty filters.
+- **Delete all records from an index** - Deletes only the records from an index while keeping settings, synonyms, and rules.
+- **Add or update attributes** - Adds new attributes to a record, or updates existing ones.
+- **Batch indexing operations on one index** - Adds, updates, or deletes records in one index with a single API request.
+- **Batch indexing operations on multiple indices** - Adds, updates, or deletes records in multiple indices with a single API request.
+- **Retrieve records** - Retrieves one or more records, potentially from different indices.
 
 ### Rules
-- **Get rule** - Retrieves a rule by its ID.
-- **Save rule** - If a rule with the specified object ID doesn't exist, it's created.
-- **Delete rule** - Deletes a rule by its ID.
-- **Save rules** - Create or update multiple rules.
-- **Clear rules** - Deletes all rules from the index.
-- **Search rules** - Searches for rules in your index.
+
+- **Retrieve a rule** - Retrieves a rule by its ID.
+- **Create or replace a rule** - If a rule with the specified object ID doesn't exist, it's created.
+- **Delete a rule** - Deletes a rule by its ID.
+- **Create or update rules** - Create or update multiple rules.
+- **Delete all rules** - Deletes all rules from the index.
+- **Search for rules** - Searches for rules in your index.
 
 ### Search
-- **Search single index** - Searches a single index and returns matching search results (_hits_).
-- **Search** - Sends multiple search requests to one or more indices.
+
+- **Search an index** - Searches a single index and returns matching search results as hits.
+- **Search multiple indices** - Sends multiple search requests to one or more indices.
 - **Search for facet values** - Searches for values of a specified facet attribute.
-- **Browse** - Retrieves records from an index, up to 1,000 per request.
+- **Browse for records** - Retrieves records from an index, up to 1,000 per request.
 
 ### Synonyms
-- **Get synonym** - Retrieves a synonym by its ID.
-- **Save synonym** - If a synonym with the specified object ID doesn't exist, Algolia adds a new one.
-- **Delete synonym** - Deletes a synonym by its ID.
-- **Save synonyms** - If a synonym with the `objectID` doesn't exist, Algolia adds a new one.
-- **Clear synonyms** - Deletes all synonyms from the index.
-- **Search synonyms** - Searches for synonyms in your index.
+
+- **Retrieve a synonym** - Retrieves a synonym by its ID.
+- **Create or replace a synonym** - If a synonym with the specified object ID doesn't exist, Algolia adds a new one.
+- **Delete a synonym** - Deletes a synonym by its ID.
+- **Create or replace synonyms** - If a synonym with the `objectID` doesn't exist, Algolia adds a new one.
+- **Delete all synonyms** - Deletes all synonyms from the index.
+- **Search for synonyms** - Searches for synonyms in your index.
 
 ### Vaults
-- **Get sources** - Retrieves all allowed IP addresses with access to your application.
-- **Replace sources** - Replaces the list of allowed sources.
-- **Append source** - Adds a source to the list of allowed sources.
-- **Delete source** - Deletes a source from the list of allowed sources. 
- <!-- OPERATIONS END -->
 
-## Credentials
+- **List allowed sources** - Retrieves all allowed IP addresses with access to your application.
+- **Replace allowed sources** - Replaces the list of allowed sources.
+- **Add a source** - Adds a source to the list of allowed sources.
+- **Delete a source** - Deletes a source from the list of allowed sources.
+<!-- OPERATIONS END -->
 
-To use this node, you need to authenticate with Algolia using API credentials.
+## Usage examples
 
-### Prerequisites
+### Batch insert into an Algolia Index
 
-1. Sign up for an [Algolia account](https://www.algolia.com)
-2. Create an application in your Algolia dashboard
+This section demonstrates how to efficiently perform batch inserts into an Algolia index using n8n.
 
-### Authentication Setup
+Batch operations are ideal for processing large datasets, as they reduce latency and improve data consistency.
 
-1. In your Algolia dashboard, go to Settings > API Keys
-2. Copy your Application ID
-3. Copy your Admin API Key (required for write operations)
-4. In n8n, create new Algolia API credentials with:
-   - **Application ID**: Your Algolia Application ID
-   - **Admin API Key**: Your Algolia Admin API Key
+<div align="center">
+
+![Batch workflow](assets/workflow-1.png)
+<i>Example of a Batch indexing operation workflow</i>
+
+</div>
+
+**Step-by-step guide:**
+
+1. Add a **webhook node** or a third-party webhook trigger node to initiate your workflow.
+
+2. Utilize a **Code node** (JavaScript or Python) to format your data for the Algolia batch insert operation.
+   - If your items already have unique identifiers, assign them to the `objectID` property.
+   - If not, Algolia will automatically generate a unique `objectID` when using the `addObject` or `partialUpdateObject` actions.
+   - To remove a record, use the `deleteObject` action.
+   - For a complete overview of available actions, refer to the [official documentation](https://www.algolia.com/doc/rest-api/search/batch#body-requests).
+
+![Batch workflow](assets/workflow-1-1.png)
+
+3. Add the Algolia node for **Batch indexing operations on one index** and connect it to your data list. As a best practice, ensure that only one item at a time enters this node.
+
+![Batch workflow](assets/workflow-1-2.png)
+
+4. Activate the workflow to begin automated batch indexing.
+
+Now, when items are added/deleted from your 3pr-party software, this workflow will make sure your index stays fresh and up to date!
+
+_API Rate limitations apply. See https://www.algolia.com/doc/guides/scaling/algolia-service-limits for more details._
+
+### Scheduled Cleanup of Deprecated Synonyms
+
+Over time, synonyms in your Algolia index might become outdated or no longer needed. With n8n, you can automate the removal of deprecated or unused synonyms to keep your index clean and relevant.
+
+<div align="center">
+
+![Synonym workflow](assets/workflow-2.png)
+<i>Example of a Batch indexing operation workflow</i>
+
+</div>
+
+**Step-by-step guide:**
+
+1. Use the **Schedule trigger** node to schedule the cleanup to run regularly (daily, weekly, etc.).
+2. Add the Algolia node to **"Search for synonyms"** in your target index.
+3. Use a code node to filter synonyms that match your criteria for deprecation or removal (for example, a custom `deprecated` tag or certain naming patterns).
+4. For each deprecated synonym, add an Algolia node to **"Delete a synonym"** by its ID.
+
+This workflow helps ensure your Algolia synonyms stay accurate and up to date.
+
+_API Rate limitations apply. See https://www.algolia.com/doc/guides/scaling/algolia-service-limits for more details._
 
 ## Compatibility
 
@@ -126,5 +198,5 @@ This node requires n8n version 1.0.0 or higher and Node.js 20.15 or higher.
 ## Resources
 
 - [n8n community nodes documentation](https://docs.n8n.io/integrations/#community-nodes)
-- [Algolia API documentation](https://www.algolia.com/doc/api-reference/)
+- [Algolia API documentation](https://www.algolia.com/doc/rest-api/search)
 - [Algolia dashboard](https://www.algolia.com/apps)

package/dist/credentials/AlgoliaApi.credentials.js

@@ -1,41 +1 @@
-'use strict';
-
-Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
-
-class AlgoliaApi {
-  constructor() {
-    this.name = "algoliaApi";
-    this.displayName = "Algolia API";
-    this.documentationUrl = "https://www.algolia.com";
-    this.properties = [
-      {
-        displayName: "Application ID",
-        name: "appId",
-        type: "string",
-        required: true,
-        default: ""
-      },
-      {
-        displayName: "Admin API Key",
-        name: "adminApiKey",
-        type: "string",
-        typeOptions: {
-          password: true
-        },
-        required: true,
-        default: ""
-      }
-    ];
-    this.authenticate = {
-      type: "generic",
-      properties: {
-        headers: {
-          "X-Algolia-Application-Id": "={{ $credentials.appId }}",
-          "X-Algolia-API-Key": "={{ $credentials.adminApiKey }}"
-        }
-      }
-    };
-  }
-}
-
-exports.AlgoliaApi = AlgoliaApi;
+"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});class e{constructor(){this.name="algoliaApi",this.displayName="Algolia API",this.documentationUrl="https://www.algolia.com",this.icon="file:./algolia.svg",this.properties=[{displayName:"Application ID",name:"appId",type:"string",required:!0,default:""},{displayName:"Admin API Key",name:"adminApiKey",type:"string",typeOptions:{password:!0},required:!0,default:""}],this.authenticate={type:"generic",properties:{headers:{"X-Algolia-Application-Id":"={{ $credentials.appId }}","X-Algolia-API-Key":"={{ $credentials.adminApiKey }}"}}}}}exports.AlgoliaApi=e;