@limetech/n8n-nodes-lime 2.6.0 → 2.7.0-dev.1

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

@@ -0,0 +1,364 @@
+import {
+    IDataObject,
+    IExecuteFunctions,
+    INode,
+    INodeProperties,
+    LoggerProxy as Logger,
+    NodeOperationError,
+} from 'n8n-workflow';
+import { DATA_RESOURCE } from '../../../models';
+import {
+    BulkImportJobPayload,
+    createBulkImportJob,
+    uploadBulkImportData,
+} from '../../../transport';
+import {
+    BulkImportPayloadObject,
+    waitForBulkImportJob,
+} from '../../../transport/bulkimport';
+
+/**
+ * Description and metadata for the "Bulk import objects" operation in Lime CRM.
+ *
+ * @public
+ */
+export const description = {
+    name: 'Create or update many objects (deprecated)',
+    value: 'startBulkImport',
+    description:
+        'Create or update multiple objects via a bulk import. Skipping business logic.',
+    action: 'Create or update many objects (deprecated)',
+};
+
+/**
+ * Node properties for the "Bulk import objects" 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:
+            '<h1>Deprecated</h1>' +
+            'This action is deprecated and will be removed very soon. ' +
+            'Please use the new "Create or Update Many Objects (Alpha)" operation instead.',
+        name: 'deprecatedNotice',
+        type: 'callout',
+        displayOptions: {
+            show: {
+                resource: [DATA_RESOURCE],
+                operation: ['startBulkImport'],
+            },
+        },
+        default: undefined,
+    },
+    {
+        displayName: 'Limetype',
+        name: 'limetype',
+        type: 'options',
+        typeOptions: {
+            loadOptionsMethod: 'getLimetypes',
+        },
+        required: true,
+        default: '',
+        description: 'The type of object to update',
+        displayOptions: {
+            show: {
+                resource: [DATA_RESOURCE],
+                operation: ['startBulkImport'],
+            },
+        },
+    },
+    {
+        displayName: 'Matching Property',
+        name: 'matchingProperty',
+        type: 'options',
+        typeOptions: {
+            loadOptionsMethod: 'getNoHasManyProperties',
+            loadOptionsDependsOn: ['limetype'],
+        },
+        required: true,
+        default: '',
+        description:
+            'The property to use to match existing objects. Must be a unique property.',
+        displayOptions: {
+            show: {
+                resource: [DATA_RESOURCE],
+                operation: ['startBulkImport'],
+            },
+        },
+    },
+    {
+        displayName: 'Input Type',
+        name: 'inputType',
+        type: 'options',
+        options: [
+            {
+                name: 'Simple Fields',
+                value: 'simple',
+                description: 'Define fields using the UI',
+            },
+            {
+                name: 'JSON Object',
+                value: 'json',
+                description: 'Define fields using JSON',
+            },
+        ],
+        default: 'simple',
+        description: 'How to input the data',
+        displayOptions: {
+            show: {
+                resource: [DATA_RESOURCE],
+                operation: ['startBulkImport'],
+            },
+        },
+    },
+    {
+        displayName: 'Data',
+        name: 'jsonData',
+        type: 'json',
+        default:
+            '{\n  "name": "Updated Company Name",\n  "phone": "+987654321"\n}',
+        description:
+            'Key-value pairs for fields to update. Property names must match the Lime CRM field names.',
+        typeOptions: {
+            alwaysOpenEditWindow: true,
+        },
+        displayOptions: {
+            show: {
+                resource: [DATA_RESOURCE],
+                operation: ['startBulkImport'],
+                inputType: ['json'],
+            },
+        },
+    },
+    {
+        displayName: 'Fields',
+        name: 'simpleFields',
+        placeholder: 'Add Field',
+        type: 'fixedCollection',
+        typeOptions: {
+            multipleValues: true,
+            sortable: true,
+        },
+        default: {},
+        displayOptions: {
+            show: {
+                resource: [DATA_RESOURCE],
+                operation: ['startBulkImport'],
+                inputType: ['simple'],
+            },
+        },
+        options: [
+            {
+                name: 'field',
+                displayName: 'Field',
+                values: [
+                    {
+                        displayName: 'Field Name',
+                        name: 'fieldName',
+                        type: 'options',
+                        typeOptions: {
+                            loadOptionsMethod: 'getNoHasManyProperties',
+                            loadOptionsDependsOn: ['limetype'],
+                        },
+                        default: '',
+                        description: 'The name of the field',
+                    },
+                    {
+                        displayName: 'Field Value',
+                        name: 'fieldValue',
+                        type: 'string',
+                        default: '',
+                        description: 'The value of the field',
+                    },
+                    {
+                        displayName: 'Relation Lookup',
+                        name: 'fieldNameDotLookup',
+                        type: 'options',
+                        typeOptions: {
+                            loadOptionsMethod:
+                                'getRelationPropertiesWithLookupField',
+                            loadOptionsDependsOn: ['limetype'],
+                        },
+                        default: '',
+                        description:
+                            'For relation fields: select which property on the related object to use for matching. Leave empty for non-relation fields.',
+                    },
+                ],
+            },
+        ],
+    },
+];
+
+/**
+ * Extract properties to import from JSON input.
+ * @param jsonData
+ */
+function getPropertiesFromJson(jsonData: string): string[] {
+    const parsed = JSON.parse(jsonData);
+    return Object.keys(parsed);
+}
+
+/**
+ * Extract properties to import from simple fields input.
+ * Validates that relation lookups match their field names.
+ * @param simpleFields
+ * @param getNode
+ */
+function getPropertiesFromSimpleFields(
+    simpleFields: IDataObject[],
+    getNode: () => INode
+): string[] {
+    const propertiesToImport: string[] = [];
+
+    for (const field of simpleFields) {
+        const fieldName = field.fieldName as string;
+        const fieldNameDotLookup = field.fieldNameDotLookup as string;
+
+        if (fieldNameDotLookup) {
+            const [relationField] = fieldNameDotLookup.split('.');
+
+            if (relationField !== fieldName) {
+                throw new NodeOperationError(
+                    getNode(),
+                    `Relation lookup "${fieldNameDotLookup}" does not match field name "${fieldName}".`
+                );
+            }
+            propertiesToImport.push(fieldNameDotLookup);
+        } else {
+            propertiesToImport.push(fieldName);
+        }
+    }
+
+    return propertiesToImport;
+}
+
+/**
+ * Build a payload object from simple fields.
+ * @param simpleFields
+ */
+function buildPayloadFromSimpleFields(
+    simpleFields: IDataObject[]
+): BulkImportPayloadObject {
+    const obj: BulkImportPayloadObject = { values: {} };
+
+    for (const field of simpleFields) {
+        const fieldName = field.fieldName as string;
+        const fieldValue = field.fieldValue as string;
+
+        obj.values[fieldName] = fieldValue;
+    }
+
+    return obj;
+}
+
+/**
+ * Execute the "Bulk import objects" operation for Lime CRM.
+ *
+ * @remarks
+ * This method creates a bulk import job and uploads data.
+ *
+ * @param i - The index of the current item in the workflow execution
+ *
+ * @returns The bulk import job status and summary
+ *
+ * @public
+ */
+export async function execute(
+    this: IExecuteFunctions,
+    i: number
+): Promise<IDataObject | undefined> {
+    if (i > 0) {
+        return undefined;
+    }
+
+    const limetype = this.getNodeParameter('limetype', i) as string;
+    const matchingProperty = this.getNodeParameter(
+        'matchingProperty',
+        i
+    ) as string;
+    const inputType = this.getNodeParameter('inputType', i) as string;
+    const items = this.getInputData();
+
+    Logger.info(
+        `Preparing bulk import of ${items.length} objects for limetype: ${limetype}`
+    );
+
+    // Step 1: Compute the properties to import based on the first item
+    const propertiesToImport =
+        inputType === 'json'
+            ? getPropertiesFromJson(
+                  this.getNodeParameter('jsonData', 0) as string
+              )
+            : getPropertiesFromSimpleFields(
+                  this.getNodeParameter(
+                      'simpleFields.field',
+                      0,
+                      []
+                  ) as IDataObject[],
+                  this.getNode.bind(this)
+              );
+
+    Logger.info(`Properties to import: ${propertiesToImport.join(', ')}`);
+
+    // Step 2: Prepare the body for all items
+    const body: BulkImportPayloadObject[] = items.map((_, idx) => {
+        if (inputType === 'json') {
+            return JSON.parse(this.getNodeParameter('jsonData', idx) as string);
+        }
+        return buildPayloadFromSimpleFields(
+            this.getNodeParameter(
+                'simpleFields.field',
+                idx,
+                []
+            ) as IDataObject[]
+        );
+    });
+
+    // Step 3: Create the bulk import job
+    const jobPayload: BulkImportJobPayload = {
+        mode: 'create_or_update',
+        limetype,
+        matchingProperty,
+        properties: propertiesToImport,
+    };
+
+    const jobResponse = await createBulkImportJob(this, jobPayload);
+    const jobId = jobResponse.id;
+
+    // Step 4: Upload the data file
+    await uploadBulkImportData(this, jobId, body);
+
+    // Step 5: Poll for completion
+    const finalStatus = await waitForBulkImportJob(this, jobId, 2500);
+
+    if (finalStatus.status === 'failed') {
+        throw new NodeOperationError(
+            this.getNode(),
+            'The bulk import job failed',
+            {
+                message: 'The bulk import job failed due to a server error.',
+                description: `Bulk import job with ID ${jobId} has failed. Check the Lime CRM server for more details.`,
+            }
+        );
+    }
+
+    // Step 6: Return the results summary
+    return {
+        jobId,
+        status: finalStatus.status,
+        summary: finalStatus.result || {
+            total: 0,
+            created: 0,
+            updated: 0,
+            skipped: 0,
+            failed: 0,
+        },
+    };
+}

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

@@ -22,3 +22,20 @@ export * as getManyObjects from './getManyObjects.operation';
  * @group Resources
  */
 export * as getSingleFile from './getSingleFile.operation';
+/**
+ * @group Resources
+ */
+export * as createManyObjects from './createManyObjects.operation';
+/**
+ * @group Resources
+ */
+export * as updateManyObjects from './updateManyObjects.operation';
+/**
+ * @group Resources
+ */
+export * as createOrUpdateManyObjects from './createOrUpdateManyObjects.operation';
+/**
+ * @group Resources
+ * @deprecated Use createManyObjects, updateManyObjects, or createOrUpdateManyObjects instead.
+ */
+export * as startBulkImport from './deprecated-startBulkImport.operation';

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

@@ -0,0 +1,44 @@
+import { IDataObject, IExecuteFunctions, INodeProperties } from 'n8n-workflow';
+import {
+    getBulkImportProperties,
+    executeBulkImport,
+} from './bulkImportCommons';
+
+/**
+ * Description and metadata for the "Update many objects" operation in Lime CRM.
+ *
+ * @public
+ */
+export const description = {
+    name: 'Update Many Objects (Alpha)',
+    value: 'updateManyObjects',
+    description:
+        'Update multiple existing objects via bulk import. Skips business logic.',
+    action: 'Update many objects (alpha)',
+};
+
+/**
+ * Node properties for the "Update many objects" operation.
+ *
+ * @public
+ */
+export const properties: INodeProperties[] = getBulkImportProperties(
+    'updateManyObjects',
+    true // Matching property needed for update
+);
+
+/**
+ * Execute the "Update many objects" operation for Lime CRM.
+ *
+ * @param i - The index of the current item in the workflow execution
+ *
+ * @returns The bulk import job status and summary
+ *
+ * @public
+ */
+export async function execute(
+    this: IExecuteFunctions,
+    i: number
+): Promise<IDataObject | undefined> {
+    return executeBulkImport(this, i, 'update');
+}

package/nodes/lime-crm/transport/bulkimport.ts

@@ -0,0 +1,271 @@
+import {
+    IExecuteFunctions,
+    LoggerProxy as Logger,
+    NodeApiError,
+} from 'n8n-workflow';
+import { callLimeApi } from './commons';
+import { LIME_CRM_API_CREDENTIAL_KEY } from '../models';
+
+/**
+ * Endpoint path for Lime CRM bulk import API.
+ *
+ * @internal
+ * @group Transport
+ */
+const BULK_IMPORT_URL = 'limepkg-mbeku-bulk-import/bulk-imports/';
+
+/**
+ * Response from creating a bulk import job.
+ *
+ * @property id - The unique ID of the bulk import job
+ * @property createdBy - The ID of the user who created the job
+ * @property fileId - The ID of the uploaded file (if any)
+ * @property status - The current status of the job (`waiting_for_data`, `ready`, `failed`, `succeeded`)
+ * @property startedAt - Timestamp when the job started (if any)
+ * @property endedAt - Timestamp when the job ended (if any)
+ * @property metadata - Metadata about the job configuration
+ * @property metadata.limetype - The Lime type being imported
+ * @property metadata.properties - Array of property names being imported
+ * @property metadata.mode - Import mode
+ * @property metadata.matchingProperty - Property used for matching existing records
+ * @property result - Summary of the job results (if finished)
+ * @property result.total - Total number of records processed
+ * @property result.created - Number of records created
+ * @property result.updated - Number of records updated
+ * @property result.skipped - Number of records skipped
+ * @property result.failed - Number of records failed
+ * @property extras - Optional extra metadata from the server/job runner
+ * @property extras.task_id - Optional background task id (snake_case)
+ * @property extras.taskId - Optional background task id (camelCase)
+ *
+ * @public
+ * @group Transport
+ */
+export interface BulkImportJobResponse {
+    id: string;
+    createdBy: number;
+    fileId: number | null;
+    status: 'waiting_for_data' | 'ready' | 'failed' | 'succeeded';
+    startedAt: string | null;
+    endedAt: string | null;
+    metadata: {
+        limetype: string;
+        properties: string[];
+        mode: BulkImportMode;
+        matchingProperty: string;
+    };
+    result: null | {
+        total: number;
+        created: number;
+        updated: number;
+        skipped: number;
+        failed: number;
+    };
+    extras: null | {
+        task_id?: string;
+        taskId?: string;
+    };
+}
+
+/**
+ * The mode for a bulk import operation.
+ *
+ * @public
+ * @group Transport
+ */
+export type BulkImportMode = 'create' | 'update' | 'create_or_update';
+
+/**
+ * Payload for creating a bulk import job.
+ *
+ * @property limetype - The Limetype to import objects into
+ * @property properties - List of property names to import
+ * @property mode - The import mode
+ * @property matchingProperty - Property to use for matching existing records (required for 'update' and 'create_or_update' modes)
+ *
+ * @public
+ * @group Transport
+ */
+export interface BulkImportJobPayload {
+    limetype: string;
+    properties: string[];
+    mode: BulkImportMode;
+    matchingProperty?: string;
+}
+
+/**
+ * Object representing a single object to import.
+ *
+ * @property values - Key-value pairs of property names and their values
+ * @property extras - (Optional) Additional informational data for the import
+ *
+ * @public
+ * @group Transport
+ */
+export interface BulkImportPayloadObject {
+    values: Record<string, unknown>;
+    extras?: Record<string, unknown>;
+}
+
+/**
+ * Create a new bulk import job in Lime CRM.
+ *
+ * @param context - The n8n execution context
+ * @param payload - The bulk import job configuration
+ *
+ * @returns Promise resolving to the created job response with id and status
+ *
+ * @public
+ * @group Transport
+ */
+export async function createBulkImportJob(
+    context: IExecuteFunctions,
+    payload: BulkImportJobPayload
+): Promise<BulkImportJobResponse> {
+    Logger.info(
+        `Creating bulk import job at ${BULK_IMPORT_URL} with payload: ${JSON.stringify(payload)}`
+    );
+    try {
+        const response = await callLimeApi<BulkImportJobResponse>(context, {
+            method: 'POST',
+            url: BULK_IMPORT_URL,
+            requestOptions: {
+                body: payload,
+            },
+        });
+        if (!response.success) {
+            throw new NodeApiError(context.getNode(), {
+                message: 'The bulk import job was rejected by the server.',
+                description: `${JSON.stringify(response.data)}`,
+            });
+        }
+        Logger.info(
+            `Created bulk import job at ${BULK_IMPORT_URL} with payload: ${JSON.stringify(payload)}`
+        );
+
+        return response.data;
+    } catch (error) {
+        Logger.error(
+            `Failed to create bulk import job at ${BULK_IMPORT_URL} with payload: ${JSON.stringify(payload)}`
+        );
+        throw error;
+    }
+}
+
+/**
+ * Upload data to an existing bulk import job.
+ *
+ * @param context - The n8n execution context
+ * @param jobId - The ID of the bulk import job
+ * @param data - Array of objects to import
+ *
+ * @returns Promise resolving when upload is complete
+ *
+ * @public
+ * @group Transport
+ */
+export async function uploadBulkImportData(
+    context: IExecuteFunctions,
+    jobId: string,
+    data: unknown
+): Promise<void> {
+    // Get the base URL for constructing the full endpoint
+    const credentials = await context.getCredentials(
+        LIME_CRM_API_CREDENTIAL_KEY
+    );
+    const baseUrl = credentials.url as string;
+    const fullUrl = `${baseUrl}/${BULK_IMPORT_URL}${jobId}`;
+
+    const message = `Uploading data to: ${fullUrl} for job ID: ${jobId}`;
+    Logger.info(message);
+
+    const jsonData = JSON.stringify(data);
+    const messageData = `First element of uploaded data: ${jsonData[0]}`;
+    Logger.info(messageData);
+    const formData = {
+        file: {
+            value: Buffer.from(jsonData, 'utf8'),
+            options: {
+                filename: 'import-data.json',
+                contentType: 'application/json',
+            },
+        },
+    };
+
+    Logger.info(`Uploading bulk import data to ${fullUrl}`);
+
+    await context.helpers.requestWithAuthentication.call(
+        context,
+        LIME_CRM_API_CREDENTIAL_KEY,
+        {
+            method: 'POST',
+            url: fullUrl,
+            formData,
+        }
+    );
+
+    Logger.info(`Successfully uploaded data for job ID: ${jobId}`);
+}
+
+/**
+ * Get the status of a bulk import job.
+ *
+ * @param context - The n8n execution context
+ * @param jobId - The ID of the bulk import job
+ *
+ * @returns Promise resolving to the job status response
+ *
+ * @public
+ * @group Transport
+ */
+export async function getBulkImportJobStatus(
+    context: IExecuteFunctions,
+    jobId: string
+): Promise<BulkImportJobResponse> {
+    Logger.info(`Fetching status for bulk import job ID: ${jobId}`);
+    const response = await callLimeApi<BulkImportJobResponse>(context, {
+        method: 'GET',
+        url: `${BULK_IMPORT_URL}${jobId}`,
+    });
+
+    if (!response.success) {
+        throw new NodeApiError(context.getNode(), {
+            message: 'The bulk import job status could not be retrieved.',
+            description: `${JSON.stringify(response)}`,
+        });
+    }
+
+    return response.data;
+}
+
+/**
+ * Poll a bulk import job until it completes.
+ *
+ * @param context - The n8n execution context
+ * @param jobId - The ID of the bulk import job
+ * @param pollIntervalMs - Milliseconds to wait between polls (default: 2500)
+ *
+ * @returns Promise resolving to the final job status response
+ *
+ * @public
+ * @group Transport
+ */
+export async function waitForBulkImportJob(
+    context: IExecuteFunctions,
+    jobId: string,
+    pollIntervalMs: number = 2500
+): Promise<BulkImportJobResponse> {
+    let status = 'running';
+    let response: BulkImportJobResponse;
+
+    while (['waiting_for_data', 'ready', 'running'].includes(status)) {
+        // Wait before polling
+        await new Promise((resolve) => setTimeout(resolve, pollIntervalMs));
+
+        Logger.info(`Polling bulk import job ID: ${jobId}`);
+        response = await getBulkImportJobStatus(context, jobId);
+        status = response.status;
+    }
+
+    return response!;
+}

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

@@ -41,3 +41,11 @@ export {
     fetchSingleUserById,
     fetchSingleUserByLimeobjectId,
 } from './users';
+export {
+    BulkImportJobResponse,
+    BulkImportJobPayload,
+    createBulkImportJob,
+    uploadBulkImportData,
+    getBulkImportJobStatus,
+    waitForBulkImportJob,
+} from './bulkimport';