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

package/nodes/lime-crm/resources/data/operations/{getManyObjects.ts → getManyObjects.operation.ts}

@@ -1,8 +1,13 @@
 import { IExecuteFunctions, INodeProperties } from 'n8n-workflow';
 
-import { queryLimeobjects } from '../../../transport';
-import { DATA_RESOURCE } from '../../../commons';
+import { IncludedProperties, queryLimeobjects } from '../../../transport';
+import { DATA_RESOURCE, DEFAULT_API_OBJECT_LIMIT } from '../../../models';
 
+/**
+ * Description and metadata for the "Get Many Objects" operation in Lime CRM.
+ *
+ * @public
+ */
 export const description = {
     name: 'Get Many Objects',
     value: 'getManyObjects',
@@ -10,14 +15,54 @@ export const description = {
     action: 'Get many objects',
 };
 
-const BATCHSIZE = 50;
+/**
+ * Maximum number of objects to fetch in a single API request.
+ * @internal
+ */
+const BATCHSIZE = 200;
 
+/**
+ * Structure of the response format when querying Lime CRM objects.
+ *
+ * @remarks
+ * This is used to define which properties are included in the API response.
+ * The keys of the `object` correspond to property names of the entity,
+ * and the values are initialized as empty strings.
+ *
+ * @example
+ * {
+ *   object: {
+ *     _id: '',
+ *     name: '',
+ *     phone: ''
+ *   }
+ * }
+ *
+ * @internal
+ */
 interface ResponseFormat {
     object: {
         [key: string]: string;
     };
 }
 
+/**
+ * Defines a collection of properties to order query results by.
+ *
+ * @remarks
+ * Each entry specifies a property name and the direction in which the results
+ * should be sorted. Multiple fields can be provided to perform multi-level sorting.
+ *
+ * @example
+ * {
+ *   orderByFields: [
+ *     { propertyName: 'name', sortDirection: 'ASC' },
+ *     { propertyName: 'createdAt', sortDirection: 'DESC' }
+ *   ]
+ * }
+ *
+ * @internal
+ */
 interface OrderByCollection {
     orderByFields: {
         propertyName: string;
@@ -25,6 +70,21 @@ interface OrderByCollection {
     }[];
 }
 
+/**
+ * Node properties for the "Get Many Objects" operation.
+ *
+ * @param {string} limetype - The type of entity to query. Loaded from available Limetypes
+ * @param {'fields' | 'json'} responseFormatInputMethod - How to format the response
+ * @param {Array<{ name: string }>} responseFormatProperties - The properties to include if using 'fields'
+ * @param {string} responseFormatJson - JSON defining the response structure if using 'json'
+ * @param {string} filter - JSON defining filtering conditions
+ * @param {number} limit - Maximum number of objects to return
+ * @param {'fields' | 'json'} orderByInputMethod - How to specify ordering
+ * @param {OrderByCollection} orderByProperties - Order by fields if using 'fields'
+ * @param {string} orderByJson - JSON defining ordering if using 'json'
+ *
+ * @public
+ */
 export const properties: INodeProperties[] = [
     {
         displayName: 'Limetype',
@@ -137,7 +197,7 @@ export const properties: INodeProperties[] = [
         displayName: 'Limit',
         name: 'limit',
         type: 'number',
-        default: 50,
+        default: DEFAULT_API_OBJECT_LIMIT,
         description: 'The maximum number of records to return',
         displayOptions: {
             show: {
@@ -238,7 +298,30 @@ export const properties: INodeProperties[] = [
     },
 ];
 
-function _createResponseFormatObject(
+/**
+ * Create the response format object when using 'fields' mode.
+ *
+ * @remarks
+ * This function takes an array of property descriptors (each with a `name` field)
+ * and constructs a response object suitable for Lime CRM queries. It initializes
+ * each property with an empty string, ensuring that all requested fields are
+ * included in the response, even if the values are not yet set.
+ *
+ * Additionally, it always includes a default `_id` field in the response object,
+ * which is typically required by Lime CRM for object identification.
+ *
+ * Example:
+ * ```ts
+ * createResponseFormatObject([{ name: 'name' }, { name: 'email' }]);
+ * // Returns: { object: { _id: '', name: '', email: '' } }
+ * ```
+ *
+ * @param properties - Array of property descriptors.
+ * @returns The ResponseFormat object.
+ *
+ * @internal
+ */
+function createResponseFormatObject(
     properties: { name: string }[] = []
 ): ResponseFormat {
     const object: Record<string, string> = { _id: '' };
@@ -248,7 +331,34 @@ function _createResponseFormatObject(
     return { object };
 }
 
-function _getOrderBy(orderByCollection: OrderByCollection) {
+/**
+ * Generate the ordering array for Lime CRM queries.
+ *
+ * @remarks
+ * This function transforms a user-provided `OrderByCollection` object into the
+ * format required by the Lime CRM API. Each property in `orderByFields` is
+ * converted into a key-value pair where the key is the property name and the
+ * value is the sort direction ('ASC' or 'DESC').
+ *
+ * If no `orderByFields` are provided, it defaults to ordering by `_id` ascending.
+ *
+ * Example:
+ * ```ts
+ * getOrderBy({
+ *   orderByFields: [
+ *     { propertyName: 'name', sortDirection: 'ASC' },
+ *     { propertyName: 'createdAt', sortDirection: 'DESC' },
+ *   ]
+ * });
+ * // Returns: [{ name: 'ASC' }, { createdAt: 'DESC' }]
+ * ```
+ *
+ * @param orderByCollection - Collection of order-by fields provided by the user.
+ * @returns An array of objects representing the order-by configuration for Lime CRM.
+ *
+ * @internal
+ */
+function getOrderBy(orderByCollection: OrderByCollection) {
     const orderBy =
         orderByCollection.orderByFields &&
         orderByCollection.orderByFields.map((field) => ({
@@ -257,57 +367,86 @@ function _getOrderBy(orderByCollection: OrderByCollection) {
     return orderBy || [{ _id: 'ASC' }];
 }
 
-async function _fetchLimeObjectsInBatches(
+/**
+ * Fetch Lime CRM objects in batches to handle large result sets or unlimited queries.
+ *
+ * @remarks
+ * This function retrieves objects from Lime CRM for a given limetype by performing
+ * multiple sequential API calls, each fetching up to BATCHSIZE records.
+ *
+ * @param limetype - The type of Lime CRM entity to fetch
+ * @param responseFormat - The format in which objects should be returned, defining which properties are included
+ * @param filter - JSON string representing the filter conditions for the query
+ * @param limit - Maximum number of objects to fetch in this request
+ * @param orderBy - Array of objects defining the sorting of the results
+ *
+ * @returns Array of fetched objects or an error response as an array.
+ */
+async function fetchLimeObjects(
     this: IExecuteFunctions,
     limetype: string,
     responseFormat: ResponseFormat,
     filter: string,
-    limit: number,
-    orderBy: Array<{ [key: string]: 'ASC' | 'DESC' }>
-) {
-    if (limit <= BATCHSIZE) {
+    limit: number | null,
+    orderBy: Record<string, 'ASC' | 'DESC'>[]
+): Promise<IncludedProperties[]> {
+    const allResults: IncludedProperties[] = [];
+    const parsedFilter = JSON.parse(filter);
+    const unlimited = limit === null || limit === 0;
+    const targetLimit = unlimited ? Infinity : limit;
+
+    let fetched = 0;
+    let currentOffset = 0;
+
+    while (fetched < targetLimit) {
+        const currentLimit =
+            targetLimit === Infinity
+                ? BATCHSIZE
+                : Math.min(BATCHSIZE, targetLimit - fetched);
+
         const q = JSON.stringify({
             limetype,
             responseFormat: responseFormat,
-            filter: JSON.parse(filter),
-            limit: limit,
-            offset: 0,
+            filter: parsedFilter,
+            limit: currentLimit,
+            offset: currentOffset,
             orderBy: orderBy,
         });
-        return queryLimeobjects(this, q);
-    } else {
-        let allResults: unknown[] = [];
-        let fetched = 0;
-        let currentOffset = 0;
-        while (fetched < limit) {
-            const currentLimit = Math.min(BATCHSIZE, limit - fetched);
-            const q = JSON.stringify({
-                limetype,
-                responseFormat: responseFormat,
-                filter: JSON.parse(filter),
-                limit: currentLimit,
-                offset: currentOffset,
-                orderBy,
-            });
-            const batch = await queryLimeobjects(this, q);
-            if (!batch.success) {
-                return batch;
-            }
-            const collected = batch.data.objects.length;
-            if (!batch || collected === 0) break;
-            allResults = [...allResults, ...batch.data.objects];
-            fetched += collected;
-            currentOffset += collected;
 
-            if (collected < currentLimit) break;
-        }
-        return {
-            success: true,
-            data: allResults,
-        };
+        const batch = await queryLimeobjects(this, q);
+
+        const collected = batch.objects.length;
+        if (collected === 0) break;
+
+        allResults.push(...batch.objects);
+
+        fetched += collected;
+        currentOffset += collected;
+
+        if (collected < currentLimit) break;
     }
+
+    return allResults;
 }
 
+/**
+ * Execute the "Get Many Objects" operation for Lime CRM.
+ *
+ * @remarks
+ * Retrieves multiple Lime CRM objects of the selected limetype with optional filtering, ordering, and response formatting.
+ * The method supports batch fetching if the requested limit exceeds 50 records.
+ *
+ * Steps performed by the method:
+ * 1. Determine the limetype and response format (fields or JSON) from {@link properties}.
+ * 2. Determine ordering (fields or JSON) from {@link properties}.
+ * 3. Fetch data from Lime CRM, handling batching if necessary.
+ *
+ * @param i - The index of the current item in the workflow execution
+ *
+ * @returns The fetched Lime objects as per the requested response format.
+ *
+ * @public
+ */
 export async function execute(this: IExecuteFunctions, i: number) {
     const limetype = this.getNodeParameter('limetype', i) as string;
     const responseFormatInputMethod = this.getNodeParameter(
@@ -319,7 +458,11 @@ export async function execute(this: IExecuteFunctions, i: number) {
         i
     ) as string;
     const filter = this.getNodeParameter('filter', i) as string;
-    const limit = this.getNodeParameter('limit', i, 50) as number;
+    const limit = this.getNodeParameter(
+        'limit',
+        i,
+        DEFAULT_API_OBJECT_LIMIT
+    ) as number;
 
     let response;
     if (responseFormatInputMethod === 'fields') {
@@ -327,7 +470,7 @@ export async function execute(this: IExecuteFunctions, i: number) {
             'responseFormatProperties',
             i
         ) as { property: [{ name: string }] };
-        response = _createResponseFormatObject(properties.property);
+        response = createResponseFormatObject(properties.property);
     } else if (responseFormatInputMethod === 'json') {
         response = this.getNodeParameter('responseFormatJson', i) as string;
         response = JSON.parse(response);
@@ -339,13 +482,13 @@ export async function execute(this: IExecuteFunctions, i: number) {
             'orderByProperties',
             i
         ) as OrderByCollection;
-        orderBy = _getOrderBy(orderByCollection);
+        orderBy = getOrderBy(orderByCollection);
     } else if (orderByInputMethod === 'json') {
         orderBy = this.getNodeParameter('orderByJson', i) as string;
         orderBy = JSON.parse(orderBy);
     }
 
-    return await _fetchLimeObjectsInBatches.call(
+    return await fetchLimeObjects.call(
         this,
         limetype,
         response,

package/nodes/lime-crm/resources/data/operations/{getSingleFile.ts → getSingleFile.operation.ts}

@@ -4,8 +4,13 @@ import {
     NodeOperationError,
 } from 'n8n-workflow';
 import { getFileContent, getFileContentByLimetype } from '../../../transport';
-import { DATA_RESOURCE } from '../../../commons';
+import { DATA_RESOURCE } from '../../../models';
 
+/**
+ * Description and metadata for the "Get Single File" operation in Lime CRM.
+ *
+ * @public
+ */
 export const description = {
     name: 'Get Single File',
     value: 'getSingleFile',
@@ -13,6 +18,16 @@ export const description = {
     action: 'Get single file',
 };
 
+/**
+ * Node properties for the "Get Single File" operation.
+ *
+ * @param {('byFile' | 'byLimeobject')} source - Determines if the file should be fetched by its file ID or by its associated Limeobject ID
+ * @param {string} limetype - Required if fetching by Limeobject. Specifies the type of Lime CRM entity associated with the file
+ * @param {string} identifier - The ID of the file or the associated Limeobject to retrieve
+ * @param {string} property - Required if fetching by Limeobject. Specifies the file type property to fetch
+ *
+ * @public
+ */
 export const properties: INodeProperties[] = [
     {
         displayName: 'Get by',
@@ -94,19 +109,31 @@ export const properties: INodeProperties[] = [
     },
 ];
 
+/**
+ * Execute the "Get Single File" operation for Lime CRM.
+ *
+ * @remarks
+ * This method retrieves file data from Lime CRM based on the selected source:
+ * - 'byFile': Fetches the file using its unique file ID.
+ * - 'byLimeobject': Fetches the file using an associated Limeobject ID and the specified file type property.
+ *
+ * The method returns an object containing the JSON response and the file's binary data.
+ *
+ * @param i - The index of the current item in the workflow execution
+ *
+ * @returns An object containing `json` and `binary` fields with the file data.
+ *
+ * @public
+ */
 export async function execute(this: IExecuteFunctions, i: number) {
     const source = this.getNodeParameter('source', i) as string;
     const id = this.getNodeParameter('identifier', i) as string;
 
     if (source == 'byFile') {
         const fileResponse = await getFileContent(this, id);
-        if (!fileResponse.success) {
-            return { json: fileResponse };
-        }
-
         return {
-            json: { success: fileResponse.success },
-            binary: { data: fileResponse.data },
+            json: {},
+            binary: { data: fileResponse },
         };
     }
     if (source == 'byLimeobject') {
@@ -119,14 +146,11 @@ export async function execute(this: IExecuteFunctions, i: number) {
             id,
             property
         );
-        if (!fileResponse.success) {
-            return { json: fileResponse };
-        }
 
         return {
-            json: { success: fileResponse.success },
+            json: {},
             binary: {
-                data: fileResponse.data,
+                data: fileResponse,
             },
         };
     }

package/nodes/lime-crm/resources/data/operations/{getSingleObject.ts → getSingleObject.operation.ts}

@@ -1,9 +1,14 @@
 import { IExecuteFunctions, INodeProperties } from 'n8n-workflow';
 
-import { getLimeobject } from '../../../transport';
-import { DATA_RESOURCE } from '../../../commons';
-import { getFileProperties, processFileResponse } from '../../../commons/files';
+import { getLimeobject, getProperties } from '../../../transport';
+import { DATA_RESOURCE } from '../../../models';
+import { getFilePropertiesNames, processFileResponse } from '../../../utils';
 
+/**
+ * Description and metadata for the "Get Single Object" operation in Lime CRM.
+ *
+ * @public
+ */
 export const description = {
     name: 'Get Single Object',
     value: 'getSingleObject',
@@ -11,6 +16,15 @@ export const description = {
     action: 'Get single object',
 };
 
+/**
+ * Node properties for the "Get Single Object" operation.
+ *
+ * @param {string} limetype - The type of entity to retrieve. Loaded from available Limetypes
+ * @param {string} objectId - The ID of the object to retrieve
+ * @param {boolean} includeFileContent - Whether to include file binary data for Limetypes that have file properties. Ignored for Limetypes without file properties
+ *
+ * @public
+ */
 export const properties: INodeProperties[] = [
     {
         displayName: 'Limetype',
@@ -62,6 +76,24 @@ export const properties: INodeProperties[] = [
     },
 ];
 
+/**
+ * Execute the "Get Single Object" operation for Lime CRM.
+ *
+ * @remarks
+ * This method retrieves a single Lime CRM object identified by its object ID and Limetype.
+ * If `includeFileContent` is true, it also retrieves binary data for any file properties of the object.
+ *
+ * The method performs the following steps:
+ * 1. Retrieves the `limetype`, `objectId`, and `includeFileContent` from {@link properties}.
+ * 2. Calls {@link getLimeobject} to fetch the object from Lime CRM.
+ * 3. If the object has file properties and `includeFileContent` is true, it retrieves file data using {@link getFilePropertiesNames} and {@link processFileResponse}.
+ *
+ * @param i - The index of the current item in the workflow execution
+ *
+ * @returns The Lime object data, optionally including file binary content.
+ *
+ * @public
+ */
 export async function execute(this: IExecuteFunctions, i: number) {
     const limetype = this.getNodeParameter('limetype', i) as string;
     const objectId = this.getNodeParameter('objectId', i) as string;
@@ -71,13 +103,14 @@ export async function execute(this: IExecuteFunctions, i: number) {
     ) as boolean;
 
     const limeObjectResponse = await getLimeobject(this, limetype, objectId);
-    if (!limeObjectResponse.success) return { json: limeObjectResponse };
 
-    const fileProperties = await getFileProperties(this, limetype);
+    const propertiesResponse = await getProperties(this, limetype);
+
+    const fileProperties = getFilePropertiesNames(propertiesResponse);
     return processFileResponse(
         this,
         fileProperties,
-        limeObjectResponse.data,
+        limeObjectResponse,
         includeFileContent
     );
 }

package/nodes/lime-crm/resources/data/operations/index.ts

@@ -0,0 +1,24 @@
+/**
+ * @group Resources
+ */
+export * as createSingleObject from './createSingleObject.operation';
+/**
+ * @group Resources
+ */
+export * as getSingleObject from './getSingleObject.operation';
+/**
+ * @group Resources
+ */
+export * as updateSingleObject from './updateSingleObject.operation';
+/**
+ * @group Resources
+ */
+export * as deleteSingleObject from './deleteSingleObject.operation';
+/**
+ * @group Resources
+ */
+export * as getManyObjects from './getManyObjects.operation';
+/**
+ * @group Resources
+ */
+export * as getSingleFile from './getSingleFile.operation';

package/nodes/lime-crm/resources/data/operations/updateSingleObject.operation.ts

@@ -1,13 +1,19 @@
 import { IDataObject, IExecuteFunctions, INodeProperties } from 'n8n-workflow';
-import { updateLimeobject } from '../../../transport';
-import { DATA_RESOURCE } from '../../../commons';
+import { getProperties, updateLimeobject } from '../../../transport';
+import { DATA_RESOURCE } from '../../../models';
 import {
-    getFileProperties,
+    adaptProperty,
+    getFilePropertiesNames,
+    getPropertyType,
     processFileResponse,
     setFileProperties,
-} from '../../../commons/files';
+} from '../../../utils';
 
-// Input fields for update operation
+/**
+ * Description and metadata for the "Update Single Object" operation in Lime CRM.
+ *
+ * @public
+ */
 export const description = {
     name: 'Update Single Object',
     value: 'updateSingleObject',
@@ -15,6 +21,17 @@ export const description = {
     action: 'Update single object',
 };
 
+/**
+ * Node properties for the "Update Single Object" operation.
+ *
+ * @param {string} limetype - The type of entity to update. Loaded from available Limetypes
+ * @param {string} id - The ID of the object to update
+ * @param {'simple' | 'json'} inputType - How the object data is provided: 'simple' for form inputs, 'json' for raw JSON
+ * @param {IDataObject} simpleFields - Used if `inputType` is 'simple'. List of field name/value pairs to update
+ * @param {string} jsonData - Used if `inputType` is 'json'. Full object data in JSON format
+ *
+ * @public
+ */
 export const properties: INodeProperties[] = [
     {
         displayName: 'Limetype',
@@ -118,7 +135,7 @@ export const properties: INodeProperties[] = [
                         name: 'fieldName',
                         type: 'options',
                         typeOptions: {
-                            loadOptionsMethod: 'getLimetypeProperties',
+                            loadOptionsMethod: 'getNoHasManyProperties',
                             loadOptionsDependsOn: ['limetype'],
                         },
                         default: '',
@@ -137,6 +154,27 @@ export const properties: INodeProperties[] = [
     },
 ];
 
+/**
+ * Execute the "Update Single Object" operation for Lime CRM.
+ *
+ * @remarks
+ * This method updates a single Lime CRM object identified by its ID and Limetype.
+ * It supports two input methods:
+ * - 'simple': key-value pairs provided via the UI
+ * - 'json': full object data in JSON format
+ *
+ * The method performs the following steps:
+ * 1. Retrieves the `limetype`, `id`, and input data from {@link properties}.
+ * 2. Collects and prepares any file properties using {@link getFilePropertiesNames} and {@link setFileProperties}.
+ * 3. Calls {@link updateLimeobject} to update the object in Lime CRM.
+ * 4. Processes the response, including file properties, using {@link processFileResponse}.
+ *
+ * @param i - The index of the current item in the workflow execution
+ *
+ * @returns The updated Lime object data, optionally including file binary content.
+ *
+ * @public
+ */
 export async function execute(this: IExecuteFunctions, i: number) {
     const limetype = this.getNodeParameter('limetype', i) as string;
     const id = this.getNodeParameter('id', i) as string;
@@ -144,6 +182,8 @@ export async function execute(this: IExecuteFunctions, i: number) {
 
     let body: IDataObject = {};
 
+    const properties = await getProperties(this, limetype);
+
     if (inputType === 'json') {
         const jsonData = this.getNodeParameter('jsonData', i) as string;
         body = JSON.parse(jsonData);
@@ -154,19 +194,18 @@ export async function execute(this: IExecuteFunctions, i: number) {
             []
         ) as IDataObject[];
         for (const field of simpleFields) {
-            body[field.fieldName as string] = field.fieldValue;
+            const fieldName = field.fieldName as string;
+            const fieldValue = field.fieldValue as string;
+            body[fieldName] = adaptProperty(
+                fieldValue,
+                getPropertyType(fieldName, properties)
+            );
         }
     }
 
-    const fileProperties = await getFileProperties(this, limetype);
+    const fileProperties = getFilePropertiesNames(properties);
 
-    const setFilePropertiesResponse = await setFileProperties(
-        this,
-        i,
-        fileProperties,
-        body
-    );
-    if (!setFilePropertiesResponse.success) return setFilePropertiesResponse;
+    await setFileProperties(this, i, fileProperties, body);
 
     const updateLimeobjectResponse = await updateLimeobject(
         this,
@@ -174,12 +213,11 @@ export async function execute(this: IExecuteFunctions, i: number) {
         id,
         body
     );
-    if (!updateLimeobjectResponse.success) return updateLimeobjectResponse;
 
     const response = await processFileResponse(
         this,
         fileProperties,
-        updateLimeobjectResponse.data
+        updateLimeobjectResponse
     );
     return response.json;
 }