@limetech/n8n-nodes-lime 0.4.0 → 2.3.1-dev.1

package/nodes/lime-crm/LimeCrmNode.node.ts

@@ -4,33 +4,74 @@ import {
     INodeProperties,
     INodeType,
     INodeTypeDescription,
-    NodeConnectionType,
+    NodeConnectionTypes,
     NodePropertyTypes,
 } from 'n8n-workflow';
 
-import {
-    erpConnectorFields,
-    erpConnectorOperations,
-} from './resources/erpConnector';
-import { limeTypeFields, limeTypeOperations } from './resources/limeType';
-import { limeObjectFields, limeObjectOperations } from './resources/limeObject';
-import { queryFields, queryOperations } from './resources/limeQuery';
+import { metadataFields, metadataOperations } from './resources/metadata';
+import { adminFields, adminOperations } from './resources/admin';
+import { dataFields, dataOperations } from './resources/data';
 
 import {
-    LIMEOBJECT_RESOURCE,
-    LIMETYPE_RESOURCE,
+    ADMIN_RESOURCE,
+    DATA_RESOURCE,
+    METADATA_RESOURCE,
     LIME_CRM_API_CREDENTIAL_KEY,
-    ERP_CONNECTOR_RESOURCE,
-    LIME_QUERY_RESOURCE,
-} from './commons';
+} from './models';
 
 import {
-    getEntitiesForErpSystem,
-    getLimeTypeProperties,
-    getLimeTypes,
+    getFileProperties,
+    getLimetypeProperties,
+    getLimetypes,
+    getNoHasManyProperties,
 } from './methods';
 
+/**
+ * Representation of a function that executes a specific Lime CRM operation.
+ *
+ * This function type is used by the Lime CRM node to dynamically invoke
+ * the appropriate handler (e.g., metadata or data operations) during node execution.
+ *
+ * @param this - The n8n {@link IExecuteFunctions} context, providing access to
+ * node parameters, credentials, and helper methods.
+ * @param args - The arguments used for the operation.
+ * @param args.operation - The name of the operation to execute (e.g., "getAll", "create").
+ * @param args.i - The index of the current item being processed in the n8n execution loop.
+ *
+ * @returns A promise that resolves with the result of the operation.
+ *
+ * @public
+ * @group Node Definition
+ */
+type OperationFn = (
+    this: IExecuteFunctions,
+    args: { operation: string; i: number }
+) => Promise<unknown>;
+
+/**
+ * The main n8n node for interacting with the Lime CRM API.
+ *
+ * Provides two resource groups:
+ * - **Metadata**: Allows interaction with the structure of available Limetypes and their properties.
+ * - **Data**: Enables operations on Lime CRM data objects.
+ *
+ * The node dynamically loads available Lime CRM resources and properties and routes
+ * executions to the appropriate operation handlers.
+ *
+ * @remarks
+ * This node uses {@link metadataOperations} and {@link dataOperations} to process workflow executions
+ * based on the selected resource and operation.
+ *
+ * @public
+ * @group Node Definition
+ */
 export class LimeCrmNode implements INodeType {
+    /**
+     * Node configuration and metadata, defining available resources, operations, and credentials.
+     * Describes how the Lime CRM node appears and behaves in the n8n editor.
+     *
+     * @see {@link https://docs.n8n.io/integrations/creating-nodes/#node-description}
+     */
     description: INodeTypeDescription = {
         displayName: 'Lime CRM',
         name: 'limeCrm',
@@ -43,14 +84,15 @@ export class LimeCrmNode implements INodeType {
         defaults: {
             name: 'Lime CRM',
         },
-        inputs: [NodeConnectionType.Main],
-        outputs: [NodeConnectionType.Main],
+        inputs: [NodeConnectionTypes.Main],
+        outputs: [NodeConnectionTypes.Main],
         credentials: [
             {
                 name: LIME_CRM_API_CREDENTIAL_KEY,
                 required: true,
             },
         ],
+        usableAsTool: true,
         properties: [
             {
                 displayName: 'Resource',
@@ -59,89 +101,104 @@ export class LimeCrmNode implements INodeType {
                 noDataExpression: true,
                 options: [
                     {
-                        name: 'Lime Type',
-                        value: LIMETYPE_RESOURCE,
-                        description: 'Work with entity type definitions',
-                    },
-                    {
-                        name: 'Lime Object',
-                        value: LIMEOBJECT_RESOURCE,
-                        description: 'Work with actual data records',
+                        name: 'Metadata',
+                        value: METADATA_RESOURCE,
+                        description:
+                            'Work with the structure of available ' +
+                            'Limetypes and their properties',
                     },
                     {
-                        name: 'ERP Connector',
-                        value: ERP_CONNECTOR_RESOURCE,
-                        description: 'Integrate data between ERP and Lime CRM',
+                        name: 'Data',
+                        value: DATA_RESOURCE,
+                        description: 'Work with CRM data',
                     },
                     {
-                        name: 'Lime Query',
-                        value: LIME_QUERY_RESOURCE,
-                        description:
-                            'Easily gather a particular set of limeobjects',
+                        name: 'Admin',
+                        value: ADMIN_RESOURCE,
+                        description: 'Work with administrative data',
                     },
                 ],
-                default: LIMEOBJECT_RESOURCE,
+                default: DATA_RESOURCE,
             },
 
-            ...(limeTypeFields as INodeProperties[]),
-            ...(limeObjectFields as INodeProperties[]),
-            ...(erpConnectorFields as INodeProperties[]),
-            ...(queryFields as INodeProperties[]),
+            ...(metadataFields as INodeProperties[]),
+            ...(dataFields as INodeProperties[]),
+            ...(adminFields as INodeProperties[]),
         ],
     };
 
+    /**
+     * Methods used by the Lime CRM node to load dynamic options in the n8n UI.
+     *
+     * @remarks
+     * These functions are used to populate dropdowns and lists in the node's
+     * parameter editor. For details, see:
+     * - {@link getLimetypes}
+     * - {@link getFileProperties}
+     * - {@link getLimetypeProperties}
+     * - {@link getNoHasManyProperties}
+     */
     methods = {
         loadOptions: {
-            getEntitiesForErpSystem,
-            getLimeTypes,
-            getLimeTypeProperties,
+            getLimetypes,
+            getLimetypeProperties,
+            getFileProperties,
+            getNoHasManyProperties,
         },
     };
 
+    /**
+     * Execute the selected operation for the configured resource.
+     *
+     * Routes the execution to either {@link metadataOperations} or {@link dataOperations},
+     * based on the user’s selection in the n8n UI.
+     *
+     * @returns A two-dimensional array of execution data for downstream nodes.
+     *
+     * @throws Error - Will throw an error if execution fails and `continueOnFail` is not enabled
+     */
     async execute(this: IExecuteFunctions): Promise<INodeExecutionData[][]> {
         const items = this.getInputData();
-        const returnData = [];
+        let returnData: INodeExecutionData[] = [];
 
         const resource = this.getNodeParameter('resource', 0) as string;
         const operation = this.getNodeParameter('operation', 0) as string;
 
+        let operationFn: OperationFn | undefined;
+        switch (resource) {
+            case METADATA_RESOURCE: {
+                operationFn = metadataOperations;
+                break;
+            }
+            case DATA_RESOURCE: {
+                operationFn = dataOperations;
+                break;
+            }
+            case ADMIN_RESOURCE: {
+                operationFn = adminOperations;
+                break;
+            }
+        }
+
         for (let i = 0; i < items.length; i++) {
-            let responseData;
+            if (!operationFn) continue;
             try {
-                if (resource === LIMETYPE_RESOURCE) {
-                    responseData = await limeTypeOperations.call(this, {
-                        operation,
-                        i,
-                    });
-                } else if (resource === LIMEOBJECT_RESOURCE) {
-                    responseData = await limeObjectOperations.call(this, {
-                        operation,
-                        i,
-                    });
-                } else if (resource === ERP_CONNECTOR_RESOURCE) {
-                    responseData = await erpConnectorOperations.call(this, {
-                        operation,
-                        i,
-                    });
-                } else if (resource === LIME_QUERY_RESOURCE) {
-                    responseData = await queryOperations.call(this, {
-                        operation,
-                        i,
-                    });
+                const responseData = (await operationFn.call(this, {
+                    operation,
+                    i,
+                })) as INodeExecutionData | INodeExecutionData[] | undefined;
+                if (responseData !== undefined) {
+                    returnData = returnData.concat(responseData);
                 }
-
-                returnData.push({ json: responseData });
             } catch (error) {
                 if (this.continueOnFail()) {
-                    returnData.push({
-                        error: error.message,
-                        json: { error: error.message },
-                    });
+                    returnData.push({ json: {}, error: error.message });
                     continue;
                 }
                 throw error;
             }
         }
+
         return [this.helpers.returnJsonArray(returnData)];
     }
 }

package/nodes/lime-crm/LimeCrmTrigger.node.ts

@@ -7,11 +7,11 @@ import {
     IWebhookResponseData,
     NodeOperationError,
     LoggerProxy as Logger,
-    NodeConnectionType,
+    NodeConnectionTypes,
 } from 'n8n-workflow';
 
-import { getWebhook, LIME_CRM_API_CREDENTIAL_KEY } from './commons';
-import { getLimeTypes } from './methods';
+import { LIME_CRM_API_CREDENTIAL_KEY } from './models';
+import { getLimetypes } from './methods';
 import {
     createSubscription,
     deleteSubscription,
@@ -19,9 +19,32 @@ import {
     listSubscriptionsWithExistingData,
 } from './transport';
 
-import { verifyHmac } from './commons/hmac';
+import { getWebhook, verifyHmac } from './utils';
 
+/**
+ * Trigger node for handling incoming webhooks from **Lime CRM**.
+ *
+ * This node subscribes to events in Lime (such as record creation, update, or deletion)
+ * and triggers workflows in n8n when those events occur.
+ *
+ * @remarks
+ * - Automatically manages webhook subscriptions in Lime CRM (create, check, delete).
+ * - Verifies incoming webhook authenticity using HMAC signatures.
+ * - Returns the received payload as JSON to connected nodes.
+ *
+ * @public
+ * @group Node Definition
+ *
+ * @see {@link getSubscription} - Fetches an existing webhook subscription
+ * @see {@link listSubscriptionsWithExistingData} - Checks for existing subscriptions matching the same target URL and events
+ * @see {@link createSubscription} - Creates a new webhook subscription in Lime
+ * @see {@link deleteSubscription} - Removes an existing webhook subscription
+ */
 export class LimeCrmTrigger implements INodeType {
+    /**
+     * Definition of the node’s metadata, input/output configuration,
+     * authentication requirements, and event subscription options.
+     */
     description: INodeTypeDescription = {
         displayName: 'Lime CRM Trigger',
         name: 'limeCrmTrigger',
@@ -30,12 +53,12 @@ export class LimeCrmTrigger implements INodeType {
         version: 1,
         description:
             'Trigger which handles webhooks coming from Lime, e.g when ' +
-            'LimeObject is updated',
+            'an object is updated',
         defaults: {
             name: 'Lime CRM Trigger',
         },
         inputs: [],
-        outputs: [NodeConnectionType.Main],
+        outputs: [NodeConnectionTypes.Main],
         credentials: [
             {
                 name: LIME_CRM_API_CREDENTIAL_KEY,
@@ -68,18 +91,18 @@ export class LimeCrmTrigger implements INodeType {
                         displayName: 'Event',
                         values: [
                             {
-                                displayName: 'Lime Type',
-                                name: 'limeType',
+                                displayName: 'Limetype',
+                                name: 'limetype',
                                 type: 'options',
                                 typeOptions: {
-                                    loadOptionsMethod: 'getLimeTypes',
+                                    loadOptionsMethod: 'getLimetypes',
                                 },
                                 default: '',
                                 description:
-                                    'Lime Type to subscribe to events for',
+                                    'Limetype to subscribe to events for',
                             },
                             {
-                                displayName: 'Event Type',
+                                displayName: 'Event',
                                 name: 'eventType',
                                 type: 'options',
                                 options: [
@@ -87,44 +110,49 @@ export class LimeCrmTrigger implements INodeType {
                                         name: 'New',
                                         value: 'new',
                                         description:
-                                            'When a new record is created',
+                                            'When a new object is created',
                                     },
                                     {
                                         name: 'Update',
                                         value: 'update',
-                                        description: 'When a record is updated',
+                                        description:
+                                            'When an object is updated',
                                     },
                                     {
                                         name: 'Delete',
                                         value: 'delete',
-                                        description: 'When a record is deleted',
+                                        description:
+                                            'When an object is deleted',
                                     },
                                 ],
                                 default: 'new',
-                                description: 'Type of event to subscribe to',
+                                description: 'Event to subscribe to',
                             },
                         ],
                     },
                 ],
             },
-            {
-                displayName: 'Name',
-                name: 'name',
-                type: 'string',
-                default: '',
-                placeholder: 'my-lime-webhook',
-                required: true,
-                description: 'Name for this webhook subscription',
-            },
         ],
     };
 
+    /**
+     * Methods used to dynamically load options in the node UI. For details, see:
+     *
+     * - {@link getLimetypes}
+     */
     methods = {
         loadOptions: {
-            getLimeTypes,
+            getLimetypes,
         },
     };
 
+    /**
+     * Webhook lifecycle management methods:
+     *
+     * - checkExists - Verifies whether the webhook already exists in Lime CRM
+     * - create - Creates a new webhook subscription in Lime CRM if one does not exist
+     * - delete - Deletes the existing webhook subscription in Lime CRM
+     */
     webhookMethods = {
         default: {
             async checkExists(this: IHookFunctions): Promise<boolean> {
@@ -134,20 +162,18 @@ export class LimeCrmTrigger implements INodeType {
                     return false;
                 }
 
-                const response = await getSubscription(this, webhook);
-                if (!response.success) {
-                    if (response.status === 404) {
+                try {
+                    await getSubscription(this, webhook);
+                } catch (error) {
+                    if (error.cause?.status === 404) {
                         delete webhook.data.webhookId;
                         delete webhook.data.webhookEvents;
                         return false;
                     }
                     Logger.warn(
-                        `There was en error while getting a webhook from Lime CRM: ${response.error}`
-                    );
-                    throw new NodeOperationError(
-                        this.getNode(),
-                        response.error
+                        `There was en error while getting a webhook from Lime CRM: ${error}`
                     );
+                    throw new NodeOperationError(this.getNode(), error);
                 }
                 return true;
             },
@@ -165,17 +191,10 @@ export class LimeCrmTrigger implements INodeType {
                 // Check if a webhook already exists in order to not duplicate it in Lime
                 // This is a different check then 'checkExists' which only takes an ID,
                 // but it's only suited for production environment
-
                 const existingSubscriptionResponse =
                     await listSubscriptionsWithExistingData(this, webhook);
-                if (!existingSubscriptionResponse.success) {
-                    throw new NodeOperationError(
-                        this.getNode(),
-                        existingSubscriptionResponse.error
-                    );
-                }
 
-                if (existingSubscriptionResponse.data.length === 0) {
+                if (existingSubscriptionResponse.length === 0) {
                     const credentials = await this.getCredentials(
                         LIME_CRM_API_CREDENTIAL_KEY
                     );
@@ -189,15 +208,8 @@ export class LimeCrmTrigger implements INodeType {
                         webhookCreateData
                     );
 
-                    if (!createSubscriptionResponse.success) {
-                        throw new NodeOperationError(
-                            this.getNode(),
-                            createSubscriptionResponse.error
-                        );
-                    }
-
-                    const subscriptionId = createSubscriptionResponse.data.id;
-                    const events = createSubscriptionResponse.data.events;
+                    const subscriptionId = createSubscriptionResponse.id;
+                    const events = createSubscriptionResponse.events;
 
                     webhook.data.webhookId = subscriptionId;
                     webhook.data.webhookEvents = events;
@@ -206,7 +218,7 @@ export class LimeCrmTrigger implements INodeType {
                     );
                     return true;
                 } else {
-                    const limeWebhook = existingSubscriptionResponse.data[0];
+                    const limeWebhook = existingSubscriptionResponse[0];
                     webhook.data.webhookId = limeWebhook.id;
                     webhook.data.webhookEvents = limeWebhook.events;
                     Logger.info(
@@ -224,8 +236,9 @@ export class LimeCrmTrigger implements INodeType {
                     { ...webhook }
                 );
                 if (webhook.data.webhookId !== undefined) {
-                    const response = await deleteSubscription(this, webhook);
-                    if (!response.success) {
+                    try {
+                        await deleteSubscription(this, webhook);
+                    } catch {
                         Logger.error(
                             `Failed to delete webhook with ID: ${webhook.data.webhookId}`,
                             {
@@ -243,6 +256,26 @@ export class LimeCrmTrigger implements INodeType {
         },
     };
 
+    /**
+     * Main webhook handler — called when Lime CRM sends an event to this node.
+     *
+     * @returns The formatted webhook response data ready for n8n workflow processing.
+     *
+     * @throws NodeOperationError if authentication fails or webhook data is invalid.
+     *
+     * @example
+     * ```ts
+     * // Example webhook body:
+     * {
+     *   "event": "deal.new",
+     *   "body": {
+     *     "id": 1001,
+     *     "limetype": "deal",
+     *     "values": { "company": 1001, "coworker": 1001, "probability": 0, ... }
+     *   }
+     * }
+     * ```
+     */
     async webhook(this: IWebhookFunctions): Promise<IWebhookResponseData> {
         const webhook = getWebhook(this);
         Logger.info('Webhook received. Starting webhook processing...', {

package/nodes/lime-crm/index.ts

@@ -0,0 +1,9 @@
+export * from './utils';
+export * from './methods';
+export * from './models';
+export * from './resources/data';
+export * from './resources/metadata';
+export * from './resources/admin';
+export * from './transport';
+export * from './LimeCrmNode.node';
+export * from './LimeCrmTrigger.node';

package/nodes/lime-crm/methods/getLimetypeProperties.ts

@@ -0,0 +1,110 @@
+import {
+    ILoadOptionsFunctions,
+    INodePropertyOptions,
+    LoggerProxy as Logger,
+} from 'n8n-workflow';
+import { getProperties } from '../transport/';
+
+/**
+ * Fetch all properties for a specific Lime type.
+ *
+ * This is an internal helper function used by other load-options methods.
+ * It calls the Lime API to retrieve properties for the selected Limetype.
+ *
+ * @param nodeContext - The n8n load options context
+ * @returns An array of properties if successful, or an empty array otherwise.
+ *
+ * @internal
+ * @group Load Options Methods
+ */
+async function fetchAllProperties(nodeContext: ILoadOptionsFunctions) {
+    const limetype = nodeContext.getNodeParameter('limetype', '') as string;
+    Logger.info(`Fetching file properties for Lime type: ${limetype}`);
+    if (!limetype) return [];
+    try {
+        return await getProperties(nodeContext, limetype);
+    } catch (error) {
+        Logger.warn(`There was a problem with fetching properties: ${error}`);
+        return [];
+    }
+}
+
+/**
+ * Gets property options from a specific Limetype
+ *
+ * It's not meant to be used directly in 'loadOptionsMethod'
+ *
+ * This function fetches properties for the specified Limetype and optionally filters them
+ * based on allowed types.
+ *
+ * @param [loader] - The n8n load options context
+ * @param [allowedTypes] - Optional set of property types to filter by
+ * @param [forbiddenType] - Optional set of property types to exclude
+ * @returns Array of formatted property options
+ *
+ * @public
+ * @group Load Options Methods
+ */
+export async function getFilteredLimetypeProperties(
+    loader: ILoadOptionsFunctions,
+    allowedTypes?: Set<string>,
+    forbiddenType?: Set<string>
+): Promise<INodePropertyOptions[]> {
+    const properties = await fetchAllProperties(loader);
+
+    return properties
+        .filter(
+            (property) =>
+                (!allowedTypes || allowedTypes.has(property.type)) &&
+                (!forbiddenType || !forbiddenType.has(property.type))
+        )
+        .map((property) => ({
+            name: (property.localname as string) || (property.name as string),
+            value: property.name as string,
+            description: `Type: ${property.type as string} | Name: ${property.name as string}${(property.required as boolean) ? ' (Required)' : ''}`,
+            type: property.type,
+        }))
+        .sort((a, b) => a.name.localeCompare(b.name));
+}
+
+/**
+ * Get all property options for the current Limetype.
+ *
+ * @returns Array of property options for the current Limetype.
+ *
+ * @public
+ * @group Load Options Methods
+ */
+export async function getLimetypeProperties(
+    this: ILoadOptionsFunctions
+): Promise<INodePropertyOptions[]> {
+    return getFilteredLimetypeProperties(this);
+}
+
+/**
+ * Get only file property options for the current Limetype.
+ *
+ * @returns Array of file property options
+ *
+ * @public
+ * @group Load Options Methods
+ */
+export async function getFileProperties(
+    this: ILoadOptionsFunctions
+): Promise<INodePropertyOptions[]> {
+    return getFilteredLimetypeProperties(this, new Set(['file']));
+}
+
+/**
+ * Get property options excluding those of type 'hasmany'.
+ *
+ * @returns Array of property options excluding 'hasmany' types
+ *
+ * @public
+ * @group Load Options Methods
+ */
+export async function getNoHasManyProperties(
+    this: ILoadOptionsFunctions
+): Promise<INodePropertyOptions[]> {
+    return getFilteredLimetypeProperties(this, undefined, new Set(['hasmany']));
+}

package/nodes/lime-crm/methods/getLimetypes.ts

@@ -0,0 +1,26 @@
+import { ILoadOptionsFunctions, INodePropertyOptions } from 'n8n-workflow';
+import { getLimetypesFromApi } from '../transport';
+
+/**
+ * Load available Limetypes from the API
+ *
+ * @returns Array of Limetypes options
+ *
+ * @public
+ * @group Load Options Methods
+ */
+export async function getLimetypes(
+    this: ILoadOptionsFunctions
+): Promise<INodePropertyOptions[]> {
+    const data: INodePropertyOptions[] = [];
+    const response = await getLimetypesFromApi(this);
+
+    for (const limetype of response) {
+        data.push({
+            name: limetype.localname?.singular || limetype.name,
+            value: limetype.name,
+            description: limetype.name,
+        });
+    }
+    return data.sort((a, b) => a.name.localeCompare(b.name));
+}

package/nodes/lime-crm/methods/index.ts

@@ -1,3 +1,7 @@
-export { getEntitiesForErpSystem } from './getEntitiesForErpSystem';
-export { getLimeTypes } from './getLimeTypes';
-export { getLimeTypeProperties } from './getLimeTypeProperties';
+export { getLimetypes } from './getLimetypes';
+export {
+    getFileProperties,
+    getFilteredLimetypeProperties,
+    getLimetypeProperties,
+    getNoHasManyProperties,
+} from './getLimetypeProperties';