@limetech/n8n-nodes-lime 0.5.0 → 2.5.0-dev.1

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

@@ -8,9 +8,10 @@ import {
     NodeOperationError,
     LoggerProxy as Logger,
     NodeConnectionTypes,
+    NodeApiError,
 } from 'n8n-workflow';
 
-import { getWebhook, LIME_CRM_API_CREDENTIAL_KEY } from './commons';
+import { LIME_CRM_API_CREDENTIAL_KEY } from './models';
 import { getLimetypes } from './methods';
 import {
     createSubscription,
@@ -19,9 +20,32 @@ import {
     listSubscriptionsWithExistingData,
 } from './transport';
 
-import { verifyHmac } from './commons';
+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',
@@ -112,12 +136,24 @@ export class LimeCrmTrigger implements INodeType {
         ],
     };
 
+    /**
+     * Methods used to dynamically load options in the node UI. For details, see:
+     *
+     * - {@link getLimetypes}
+     */
     methods = {
         loadOptions: {
             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> {
@@ -127,20 +163,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 NodeApiError(this.getNode(), error);
                 }
                 return true;
             },
@@ -158,14 +192,13 @@ 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
-                    );
+                    throw new NodeApiError(this.getNode(), {
+                        message:
+                            existingSubscriptionResponse.data.error.message,
+                    });
                 }
 
                 if (existingSubscriptionResponse.data.length === 0) {
@@ -183,10 +216,10 @@ export class LimeCrmTrigger implements INodeType {
                     );
 
                     if (!createSubscriptionResponse.success) {
-                        throw new NodeOperationError(
-                            this.getNode(),
-                            createSubscriptionResponse.error
-                        );
+                        throw new NodeApiError(this.getNode(), {
+                            message:
+                                createSubscriptionResponse.data.error.message,
+                        });
                     }
 
                     const subscriptionId = createSubscriptionResponse.data.id;
@@ -217,8 +250,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}`,
                             {
@@ -236,6 +270,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

@@ -5,14 +5,30 @@ import {
 } from 'n8n-workflow';
 import { getProperties } from '../transport/';
 
-async function _getProperties(nodeContext: ILoadOptionsFunctions) {
+/**
+ * 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 [];
-
-    const response = await getProperties(nodeContext, limetype);
-
-    return response.success ? response.data : [];
+    try {
+        const response = await getProperties(nodeContext, limetype);
+        if (!response.success) return [];
+        return response.data;
+    } catch (error) {
+        Logger.warn(`There was a problem with fetching properties: ${error}`);
+        return [];
+    }
 }
 
 /**
@@ -27,13 +43,16 @@ async function _getProperties(nodeContext: ILoadOptionsFunctions) {
  * @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 _getProperties(loader);
+    const properties = await fetchAllProperties(loader);
 
     return properties
         .filter(
@@ -44,22 +63,48 @@ export async function getFilteredLimetypeProperties(
         .map((property) => ({
             name: (property.localname as string) || (property.name as string),
             value: property.name as string,
-            description: `Type: ${property.type as string}${(property.required as boolean) ? ' (Required)' : ''}`,
-        }));
+            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[]> {

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

@@ -2,20 +2,26 @@ import { ILoadOptionsFunctions, INodePropertyOptions } from 'n8n-workflow';
 import { getLimetypesFromApi } from '../transport';
 
 /**
- * Load available Lime types from the API
+ * 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);
-    if (response.success && response.data) {
-        for (const limetype of response.data) {
-            data.push({
-                name: limetype.localname?.singular || limetype.name,
-                value: limetype.name,
-            });
-        }
+    if (!response.success) return [];
+
+    for (const limetype of response.data) {
+        data.push({
+            name: limetype.localname?.singular || limetype.name,
+            value: limetype.name,
+            description: limetype.name,
+        });
     }
-    return data;
+    return data.sort((a, b) => a.name.localeCompare(b.name));
 }

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

@@ -1,7 +1,12 @@
-export { getEntitiesForErpSystem } from './getEntitiesForErpSystem';
 export { getLimetypes } from './getLimetypes';
 export {
     getFileProperties,
+    getFilteredLimetypeProperties,
     getLimetypeProperties,
     getNoHasManyProperties,
 } from './getLimetypeProperties';
+export {
+    getCreateMappingColumns,
+    getUpdateMappingColumns,
+    parseResourceMapperFields,
+} from './resourceMapping';

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

@@ -0,0 +1,141 @@
+import {
+    FieldType,
+    ILoadOptionsFunctions,
+    ResourceMapperFields,
+    LoggerProxy as Logger,
+    IExecuteFunctions,
+    IDataObject,
+    ResourceMapperValue,
+} from 'n8n-workflow';
+import { getProperties } from '../transport';
+import { LimetypeProperty } from '../models';
+
+/**
+ * A map of Lime CRM field types to n8n native types
+ */
+const LimeCrmTypeToFieldType = new Map(
+    Object.entries({
+        option: 'options',
+        yesno: 'boolean',
+        decimal: 'number',
+        number: 'number',
+    })
+);
+
+/**
+ * Function which maps Lime CRM to n8n types using the map above. If the type
+ * is not declared in a map, string is used.
+ * @param limeCrmType
+ * @returns n8n native {@link FieldType}
+ */
+function mapLimeCrmType(limeCrmType: string): FieldType {
+    return (LimeCrmTypeToFieldType.get(limeCrmType) as FieldType) || 'string';
+}
+
+/**
+ * Get a `length` addition to the input headers when there's a string field
+ *
+ * @param property - a {@link LimetypeProperty}
+ * @returns a string with length wrapped in quotes or an empty string
+ */
+function getPropertyLength(property: LimetypeProperty): string {
+    return property.type === 'string' ? `(${property.length})` : '';
+}
+
+/**
+ * Base function to get the description of ResourceMapper fields
+ * @param nodeContext
+ * @param mode - either `create` or `update` - based on this flag a `required`
+ * @param limetype - name of a limetype we are creating or updating
+ * property is set
+ */
+async function getMappingColumns(
+    nodeContext: ILoadOptionsFunctions,
+    mode: 'create' | 'update',
+    limetype: string
+): Promise<ResourceMapperFields> {
+    const propertiesResponse = await getProperties(nodeContext, limetype);
+    if (!propertiesResponse.success) {
+        Logger.error(
+            `There was an error with fetching properties: ${JSON.stringify(propertiesResponse.data)}`
+        );
+        return {
+            fields: [],
+        };
+    }
+    const noRelationProperties = propertiesResponse.data.filter(
+        (property) => property.type !== 'hasmany'
+    );
+
+    const fields = noRelationProperties.map((property) => {
+        const propertyLengthDescription = getPropertyLength(property);
+        return {
+            id: property.name,
+            displayName: `${property.localname} [${property.type}${propertyLengthDescription}]`,
+            required: mode === 'create' ? property.required : false,
+            defaultMatch: false,
+            display: true,
+            type: mapLimeCrmType(property.type),
+            options:
+                property.type === 'option' && property.options
+                    ? property.options
+                          .filter((option) => !option.inactive)
+                          .map((option) => {
+                              return {
+                                  value: option.key,
+                                  name: option.text,
+                              };
+                          })
+                    : undefined,
+        };
+    });
+    return {
+        fields: fields.sort((a, b) => {
+            if (a.required !== b.required) {
+                return a.required ? -1 : 1;
+            }
+            return a.displayName.localeCompare(b.displayName);
+        }),
+    };
+}
+
+/**
+ * Parse resource mapper fields from n8n workflow
+ * @param context - Node execution context
+ * @param i - The index of the current item in the workflow execution
+ * @param inputName - name of the resource mapper input
+ * @returns IDataObject - parsed data from resource mapper
+ */
+
+export function parseResourceMapperFields(
+    context: IExecuteFunctions,
+    i: number,
+    inputName: string
+): IDataObject {
+    const propertiesInput = context.getNodeParameter(
+        inputName,
+        i
+    ) as ResourceMapperValue;
+
+    return propertiesInput.value as IDataObject;
+}
+
+/**
+ * Method for getting resource mapper fields in `create` mode
+ */
+export async function getCreateMappingColumns(
+    this: ILoadOptionsFunctions
+): Promise<ResourceMapperFields> {
+    const limetype = this.getNodeParameter('limetype') as string;
+    return getMappingColumns(this, 'create', limetype);
+}
+
+/**
+ * Method for getting resource mapper fields in `update` mode
+ */
+export async function getUpdateMappingColumns(
+    this: ILoadOptionsFunctions
+): Promise<ResourceMapperFields> {
+    const limetype = this.getNodeParameter('limetype') as string;
+    return getMappingColumns(this, 'update', limetype);
+}

package/nodes/lime-crm/models/constants.ts

@@ -0,0 +1,73 @@
+// Credentials
+
+/**
+ * Credential name for Lime CRM API nodes.
+ *
+ * @public
+ * @group Models
+ */
+export const LIME_CRM_API_CREDENTIAL_KEY = 'limeCrmApi';
+
+// Resources
+
+/**
+ * Resource name for administrative data operations.
+ *
+ * @public
+ * @group Models
+ */
+export const ADMIN_RESOURCE = 'admin';
+
+/**
+ * Resource name for main data operations.
+ *
+ * @public
+ * @group Models
+ */
+export const DATA_RESOURCE = 'data';
+
+/**
+ * Resource name for metadata-related operations.
+ *
+ * @public
+ * @group Models
+ */
+export const METADATA_RESOURCE = 'metadata';
+
+/**
+ * Resource name for ERP connector-related operations.
+ *
+ * @internal
+ * @group Models
+ */
+export const ERP_CONNECTOR_RESOURCE = 'erpConnector';
+
+// Types
+
+/**
+ * Helper type used when none value was provided in N8N form
+ * @public
+ * @group Models
+ */
+export type NullOptionType = '';
+
+/**
+ * Wrapper for generic return type of Lime CRM API values
+ */
+export type APIResponsePrimitiveValue = string | boolean | number | null;
+
+/**
+ * Wrapper for types of Lime CRM API values
+ */
+export type APIResponseValue =
+    | APIResponsePrimitiveValue
+    | APIResponsePrimitiveValue[]
+    | Record<string, APIResponsePrimitiveValue>;
+
+// API
+/**
+ * Default limit when working with Lime CRM API
+ * @public
+ * @group Models
+ */
+export const DEFAULT_API_OBJECT_LIMIT = 50;

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

@@ -0,0 +1,21 @@
+export {
+    LIME_CRM_API_CREDENTIAL_KEY,
+    ADMIN_RESOURCE,
+    DATA_RESOURCE,
+    METADATA_RESOURCE,
+    ERP_CONNECTOR_RESOURCE,
+    DEFAULT_API_OBJECT_LIMIT,
+    NullOptionType,
+    APIResponseValue,
+    APIResponsePrimitiveValue,
+} from './constants';
+export { Limetype, LimetypeLocalName, LimetypeProperty } from './limetype';
+export { Limeobject } from './limeobject';
+export {
+    CreateWebhook,
+    Webhook,
+    WebhookContext,
+    WebhookFunctions,
+} from './webhook';
+export { User, UserLoginType, UserType } from './users';
+export { YES_NO_PROPERTY_TYPE, PropertyTypeMap } from './propertyTypes';

package/nodes/lime-crm/models/limeobject.ts

@@ -0,0 +1,13 @@
+import { APIResponseValue } from './constants';
+
+/**
+ * Representation of a Limeobject returned by the Lime CRM API.
+ *
+ * @property id_ - The unique ID of the Limeobject
+ *
+ * @public
+ * @group Models
+ */
+export type Limeobject = {
+    id_: number;
+} & Record<string, APIResponseValue>;

package/nodes/lime-crm/models/limetype.ts

@@ -0,0 +1,65 @@
+import { APIResponseValue } from './constants';
+
+/**
+ * Limetype option used only for fields with `option` type.
+ * @property key - ID of an option, used as a value for POST/PUT requests in API
+ * @property text - display name of an option
+ * @property inactive - flag describing whether the property is used or not
+ */
+type LimetypePropertyOption = {
+    key: string;
+    text: string;
+    inactive: boolean;
+};
+
+/**
+ * Representation of a property of a Limetype.
+ *
+ * @property name - The internal name of the property
+ * @property localname - The display name of the property
+ * @property type - The type of the property (e.g., string, file, hasmany)
+ * @property required - describes whether a property is required or not
+ * @property options - a set of {@link LimetypePropertyOption} used only for
+ * fields with type `option`.
+ *
+ * @public
+ * @group Models
+ */
+export type LimetypeProperty = {
+    name: string;
+    localname: string;
+    type: string;
+    required: boolean;
+    length?: number;
+    options?: LimetypePropertyOption[];
+} & Record<string, APIResponseValue>;
+
+/**
+ * Localized names for a Limetype.
+ *
+ * @property singular - Singular display name
+ * @property plural - Plural display name
+ *
+ * @public
+ * @group Models
+ */
+export type LimetypeLocalName = {
+    singular: string;
+    plural: string;
+};
+
+/**
+ * Representation of a Limetype.
+ *
+ * @property name - Internal name of the Limetype
+ * @property localname - Localized names
+ * @property properties - List of properties of this Limetype
+ *
+ * @public
+ * @group Models
+ */
+export type Limetype = {
+    name: string;
+    localname: LimetypeLocalName;
+    properties: LimetypeProperty[];
+} & Record<string, APIResponseValue>;

package/nodes/lime-crm/models/propertyTypes.ts

@@ -0,0 +1,13 @@
+/**
+ * Module for defining Lime CRM types which will need to be adapted to the
+ * proper format later on.
+ */
+
+export const YES_NO_PROPERTY_TYPE = 'yesno';
+
+/**
+ * A map of <Lime CRM Type>:<The type required in JSON format>
+ */
+export type PropertyTypeMap = {
+    YES_NO_PROPERTY_TYPE: boolean;
+};