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

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

@@ -0,0 +1,499 @@
+import { IExecuteFunctions, INodeProperties } from 'n8n-workflow';
+
+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',
+    description: 'Get a list of many objects',
+    action: 'Get many objects',
+};
+
+/**
+ * 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;
+        sortDirection: 'ASC' | 'DESC';
+    }[];
+}
+
+/**
+ * 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',
+        name: 'limetype',
+        type: 'options',
+        typeOptions: {
+            loadOptionsMethod: 'getLimetypes',
+        },
+        required: true,
+        default: '',
+        description: 'The type of entity to query',
+        displayOptions: {
+            show: {
+                resource: [DATA_RESOURCE],
+                operation: ['getManyObjects'],
+            },
+        },
+    },
+    {
+        displayName: 'Response Format',
+        name: 'responseFormatInputMethod',
+        type: 'options',
+        required: true,
+        default: 'fields',
+        description: 'Select how the response should be formatted',
+        displayOptions: {
+            show: {
+                resource: [DATA_RESOURCE],
+                operation: ['getManyObjects'],
+            },
+        },
+        options: [
+            {
+                name: 'Properties',
+                value: 'fields',
+            },
+            {
+                name: 'JSON',
+                value: 'json',
+            },
+        ],
+    },
+    {
+        displayName: 'Response Format (Form Fields)',
+        name: 'responseFormatProperties',
+        type: 'fixedCollection',
+        placeholder: 'Add Property',
+        typeOptions: {
+            multipleValues: true,
+        },
+        default: {},
+        displayOptions: {
+            show: {
+                resource: [DATA_RESOURCE],
+                operation: ['getManyObjects'],
+                responseFormatInputMethod: ['fields'],
+            },
+        },
+        options: [
+            {
+                displayName: 'Property',
+                name: 'property',
+                values: [
+                    {
+                        displayName: 'Property Name',
+                        name: 'name',
+                        type: 'options',
+                        typeOptions: {
+                            sortable: true,
+                            loadOptionsMethod: 'getNoHasManyProperties',
+                            loadOptionsDependsOn: ['limetype'],
+                        },
+                        default: '',
+                        description: 'Name of the property',
+                    },
+                ],
+            },
+        ],
+    },
+    {
+        displayName: 'Response Format (JSON)',
+        name: 'responseFormatJson',
+        type: 'json',
+        required: true,
+        default: '{\n\t"object": {\n\t\t"_id": ""\n\t}\n}',
+        description:
+            'Information included in the response when using JSON format',
+        displayOptions: {
+            show: {
+                resource: [DATA_RESOURCE],
+                operation: ['getManyObjects'],
+                responseFormatInputMethod: ['json'],
+            },
+        },
+    },
+    {
+        displayName: 'Filter (JSON)',
+        name: 'filter',
+        type: 'json',
+        default: '{}',
+        description: "The filter DSL defining the query's conditions",
+        displayOptions: {
+            show: {
+                resource: [DATA_RESOURCE],
+                operation: ['getManyObjects'],
+            },
+        },
+    },
+    {
+        displayName: 'Limit',
+        name: 'limit',
+        type: 'number',
+        default: DEFAULT_API_OBJECT_LIMIT,
+        description: 'The maximum number of records to return',
+        displayOptions: {
+            show: {
+                resource: [DATA_RESOURCE],
+                operation: ['getManyObjects'],
+            },
+        },
+    },
+    {
+        displayName: 'Order By',
+        name: 'orderByInputMethod',
+        type: 'options',
+        required: true,
+        default: 'fields',
+        description: 'Select how the response should be ordered',
+        displayOptions: {
+            show: {
+                resource: [DATA_RESOURCE],
+                operation: ['getManyObjects'],
+            },
+        },
+        options: [
+            {
+                name: 'Form Fields',
+                value: 'fields',
+            },
+            {
+                name: 'JSON',
+                value: 'json',
+            },
+        ],
+    },
+    {
+        displayName: 'Order By (Form Fields)',
+        name: 'orderByProperties',
+        type: 'fixedCollection',
+        placeholder: 'Add Property',
+        typeOptions: {
+            multipleValues: true,
+        },
+        default: {},
+        description:
+            'The list of properties by which to order the query results',
+        displayOptions: {
+            show: {
+                resource: [DATA_RESOURCE],
+                operation: ['getManyObjects'],
+                orderByInputMethod: ['fields'],
+            },
+        },
+        options: [
+            {
+                name: 'orderByFields',
+                displayName: 'Order By Fields',
+                values: [
+                    {
+                        displayName: 'Property Name',
+                        name: 'propertyName',
+                        type: 'options',
+                        required: true,
+                        typeOptions: {
+                            sortable: true,
+                            loadOptionsMethod: 'getNoHasManyProperties',
+                            loadOptionsDependsOn: ['limetype'],
+                        },
+                        default: '',
+                        description: 'Name of the property to order by',
+                    },
+                    {
+                        displayName: 'Sort Direction',
+                        name: 'sortDirection',
+                        type: 'options',
+                        default: 'ASC',
+                        description: 'Ordering direction',
+                        options: [
+                            { name: 'Ascending', value: 'ASC' },
+                            { name: 'Descending', value: 'DESC' },
+                        ],
+                    },
+                ],
+            },
+        ],
+    },
+    {
+        displayName: 'Order By (JSON)',
+        name: 'orderByJson',
+        type: 'json',
+        required: true,
+        default: '[\n\t{\n\t\t"_id": "ASC"\n\t}\n]',
+        description: 'Provide ordering in JSON',
+        displayOptions: {
+            show: {
+                resource: [DATA_RESOURCE],
+                operation: ['getManyObjects'],
+                orderByInputMethod: ['json'],
+            },
+        },
+    },
+];
+
+/**
+ * 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: '' };
+    for (const { name } of properties) {
+        if (name) object[name] = '';
+    }
+    return { object };
+}
+
+/**
+ * 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) => ({
+            [field.propertyName]: field.sortDirection,
+        }));
+    return orderBy || [{ _id: 'ASC' }];
+}
+
+/**
+ * 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 | 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: parsedFilter,
+            limit: currentLimit,
+            offset: currentOffset,
+            orderBy: orderBy,
+        });
+
+        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(
+        'responseFormatInputMethod',
+        i
+    ) as string;
+    const orderByInputMethod = this.getNodeParameter(
+        'orderByInputMethod',
+        i
+    ) as string;
+    const filter = this.getNodeParameter('filter', i) as string;
+    const limit = this.getNodeParameter(
+        'limit',
+        i,
+        DEFAULT_API_OBJECT_LIMIT
+    ) as number;
+
+    let response;
+    if (responseFormatInputMethod === 'fields') {
+        const properties = this.getNodeParameter(
+            'responseFormatProperties',
+            i
+        ) as { property: [{ name: string }] };
+        response = createResponseFormatObject(properties.property);
+    } else if (responseFormatInputMethod === 'json') {
+        response = this.getNodeParameter('responseFormatJson', i) as string;
+        response = JSON.parse(response);
+    }
+
+    let orderBy;
+    if (orderByInputMethod === 'fields') {
+        const orderByCollection = this.getNodeParameter(
+            'orderByProperties',
+            i
+        ) as OrderByCollection;
+        orderBy = getOrderBy(orderByCollection);
+    } else if (orderByInputMethod === 'json') {
+        orderBy = this.getNodeParameter('orderByJson', i) as string;
+        orderBy = JSON.parse(orderBy);
+    }
+
+    return await fetchLimeObjects.call(
+        this,
+        limetype,
+        response,
+        filter,
+        limit,
+        orderBy
+    );
+}

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

@@ -0,0 +1,162 @@
+import {
+    IExecuteFunctions,
+    INodeProperties,
+    NodeOperationError,
+} from 'n8n-workflow';
+import { getFileContent, getFileContentByLimetype } from '../../../transport';
+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',
+    description: 'Get the file data for one specific file',
+    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',
+        name: 'source',
+        type: 'options',
+        required: true,
+        placeholder: 'Add Source',
+        displayOptions: {
+            show: {
+                resource: [DATA_RESOURCE],
+                operation: ['getSingleFile'],
+            },
+        },
+        options: [
+            {
+                name: 'File ID',
+                value: 'byFile',
+                description: 'Get file by its ID',
+            },
+            {
+                name: 'Limeobject ID',
+                value: 'byLimeobject',
+                description: "Get file by it's associated Limeobject ID",
+            },
+        ],
+        default: 'byFile',
+    },
+    {
+        displayName: 'Limetype',
+        name: 'limetype',
+        type: 'options',
+        typeOptions: {
+            loadOptionsMethod: 'getLimetypes',
+        },
+        required: true,
+        default: '',
+        description: 'The type of entity associated with the file',
+        displayOptions: {
+            show: {
+                resource: [DATA_RESOURCE],
+                operation: ['getSingleFile'],
+                source: ['byLimeobject'],
+            },
+        },
+    },
+    {
+        displayName: 'Identifier',
+        name: 'identifier',
+        type: 'string',
+        required: true,
+        default: '',
+        description: 'The ID of the file or Limeobject to retrieve',
+        displayOptions: {
+            show: {
+                resource: [DATA_RESOURCE],
+                operation: ['getSingleFile'],
+            },
+        },
+        placeholder: 'e.g., 12345',
+    },
+    {
+        displayName: 'File type property',
+        name: 'property',
+        type: 'options',
+        typeOptions: {
+            loadOptionsMethod: 'getFileProperties',
+            loadOptionsDependsOn: ['limetype'],
+        },
+        required: true,
+        default: '',
+        description: 'The type of entity associated with the file',
+        displayOptions: {
+            show: {
+                resource: [DATA_RESOURCE],
+                operation: ['getSingleFile'],
+                source: ['byLimeobject'],
+            },
+        },
+    },
+];
+
+/**
+ * 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);
+        return {
+            json: {},
+            binary: { data: fileResponse },
+        };
+    }
+    if (source == 'byLimeobject') {
+        const limetype = this.getNodeParameter('limetype', i) as string;
+        const property = this.getNodeParameter('property', i) as string;
+
+        const fileResponse = await getFileContentByLimetype(
+            this,
+            limetype,
+            id,
+            property
+        );
+
+        return {
+            json: {},
+            binary: {
+                data: fileResponse,
+            },
+        };
+    }
+
+    throw new NodeOperationError(
+        this.getNode(),
+        `The source "${source}" is not supported!`
+    );
+}