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

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

@@ -1,9 +1,27 @@
-import { LIME_CRM_API_CREDENTIAL_KEY } from '../commons';
-import { IAllExecuteFunctions } from 'n8n-workflow';
-import { NodeResponse } from '../../nodeResponse';
+import { LIME_CRM_API_CREDENTIAL_KEY } from '../models';
+import { IAllExecuteFunctions, JsonObject } from 'n8n-workflow';
+import { WorkflowErrorContext, handleWorkflowError } from '../utils';
+import { APIResponse, SuccessResponse } from '../../response';
 
-type HTTPMethod = 'GET' | 'POST' | 'PUT' | 'DELETE';
+/**
+ * HTTP methods supported by the Lime CRM API.
+ *
+ * @group Transport
+ * @public
+ */
+export type HTTPMethod = 'GET' | 'POST' | 'PUT' | 'DELETE';
 
+/**
+ * Return a copy of the given object with specified keys removed.
+ *
+ * @param data - The source object
+ * @param keys - An array of keys to remove from the object
+ *
+ * @returns A new object with the specified keys omitted
+ *
+ * @public
+ * @group Transport
+ */
 export function removeKeys<T extends object, K extends keyof T>(
     data: T,
     keys: K[]
@@ -15,6 +33,26 @@ export function removeKeys<T extends object, K extends keyof T>(
     return obj;
 }
 
+export function prepareResponseWithoutKeys<T extends object, K extends keyof T>(
+    response: SuccessResponse<T>,
+    keys: K[]
+): SuccessResponse<Omit<T, K>> {
+    return {
+        success: true,
+        data: removeKeys(response.data, keys),
+    };
+}
+
+/**
+ * Retrieve the base URL for the Lime CRM API from stored credentials.
+ *
+ * @param context - The n8n execution context
+ *
+ * @returns The Lime CRM API base URL as a string
+ *
+ * @internal
+ * @group Transport
+ */
 async function getLimeUrl(context: IAllExecuteFunctions): Promise<string> {
     const credentials = await context.getCredentials(
         LIME_CRM_API_CREDENTIAL_KEY
@@ -22,24 +60,55 @@ async function getLimeUrl(context: IAllExecuteFunctions): Promise<string> {
     return credentials.url as string;
 }
 
+/**
+ * CallLimeAPI arguments wrapped in a single interface to enable keyword-style
+ * arguments.
+ *
+ * @property method - The HTTP method to use (GET, POST, etc.)
+ * @property url - The API endpoint URL (relative path)
+ * @property requestOptions - Optional additional request options (headers, body, query, etc.)
+ * @property json - Whether to parse the response as JSON.
+ * @property errorMetadata - Additional information we want to pass to message in case of error
+ *
+ * @public
+ * @group Transport
+ */
+
+interface LimeAPIArguments {
+    method: HTTPMethod;
+    url: string;
+    requestOptions?: Record<string, unknown>;
+    json?: boolean;
+    errorMetadata?: Record<string, unknown>;
+}
+
+/**
+ * Make an authenticated HTTP request to the Lime CRM API and returns a structured response.
+ *
+ * @typeParam T - The expected type of the API response data
+ * @param nodeContext - The n8n execution context
+ * @param options - {@link LimeAPIArguments} object
+ *
+ * @returns API data or response details
+ *
+ * @public
+ * @group Transport
+ */
 export async function callLimeApi<T>(
     nodeContext: IAllExecuteFunctions,
-    method: HTTPMethod,
-    url: string,
-    options?: Record<string, unknown>,
-    json = true
-): Promise<NodeResponse<T>> {
+    options: LimeAPIArguments
+): Promise<APIResponse<T>> {
     try {
-        const response: T =
+        const response =
             await nodeContext.helpers.requestWithAuthentication.call(
                 nodeContext,
                 LIME_CRM_API_CREDENTIAL_KEY,
                 {
-                    method: method,
-                    url: url,
-                    json: json,
+                    method: options.method,
+                    url: options.url,
+                    json: options.json || true,
                     baseURL: await getLimeUrl(nodeContext),
-                    ...options,
+                    ...options.requestOptions,
                 }
             );
         return {
@@ -47,11 +116,14 @@ export async function callLimeApi<T>(
             data: response,
         };
     } catch (error) {
-        return {
-            success: false,
-            error: error instanceof Error ? error.message : String(error),
+        const errorContext: WorkflowErrorContext = {
+            message: error instanceof Error ? error.message : String(error),
             status: error?.cause?.status,
-            metadata: options,
+            metadata: {
+                ...options.requestOptions,
+                ...options.errorMetadata,
+            } as JsonObject,
         };
+        return handleWorkflowError(nodeContext, errorContext, true);
     }
 }

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

@@ -1,17 +1,51 @@
 import { callLimeApi, getLimeobject } from '.';
 import { IExecuteFunctions, IBinaryData, BINARY_ENCODING } from 'n8n-workflow';
-import { NodeResponse } from '../../nodeResponse';
-import { removeKeys } from './commons';
-import { getFilenameFromHeader, setFilename } from '../commons';
-
+import { prepareResponseWithoutKeys } from './commons';
+import {
+    getFilenameFromHeader,
+    handleWorkflowError,
+    setFilename,
+} from '../utils';
+import { APIResponse } from '../../response';
+/**
+ * Endpoint path for Lime CRM file API.
+ *
+ * @internal
+ * @group Transport
+ */
 const LIME_FILE_URL = '/api/v1/file/';
 
-interface FileApiResponse {
+/**
+ * Response from Lime file API containing HTTP headers and raw file body.
+ *
+ * @property headers - HTTP headers returned by the API
+ * @property body - Raw file body as a Buffer
+ *
+ * @public
+ * @group Transport
+ */
+export interface FileApiResponse {
     headers: Record<string, string | string[] | undefined>;
     body: Buffer;
 }
 
-interface FileMetadata {
+/**
+ * Metadata about a file stored in Lime CRM.
+ *
+ * @property filename - Name of the file
+ * @property id - File ID in Lime CRM
+ * @property size - File size in bytes
+ * @property content_type - MIME type of the file
+ * @property extension - File extension
+ * @property created_by - ID of the user who created the file
+ * @property locked_by - ID of the user who locked the file
+ * @property last_modified - Last modified timestamp
+ * @property _links - Optional links returned by Lime API
+ *
+ * @public
+ * @group Transport
+ */
+export type FileMetadata = {
     filename: string;
     id: number;
     size: number;
@@ -21,74 +55,101 @@ interface FileMetadata {
     locked_by: number;
     last_modified: string;
     _links?: { [key: string]: { href: string } };
-}
-
+};
+
+/**
+ * Retrieve metadata for a file by its ID.
+ *
+ * @param nodeContext - n8n execution context
+ * @param id - The ID of the file
+ * @returns File metadata
+ *
+ * @public
+ * @group Transport
+ */
 export async function getFileMetadata(
     nodeContext: IExecuteFunctions,
     id: string | number
-): Promise<NodeResponse<FileMetadata>> {
+): Promise<APIResponse<FileMetadata>> {
     const url = `${LIME_FILE_URL}${id}/`;
-    const response = await callLimeApi<FileMetadata>(nodeContext, 'GET', url);
-    if (!response.success) {
-        return response;
-    }
+    const fileMetadataResponse = await callLimeApi<FileMetadata>(nodeContext, {
+        method: 'GET',
+        url: url,
+    });
 
-    return {
-        success: true,
-        data: removeKeys(response.data, ['_links']),
-    };
+    if (!fileMetadataResponse.success) return fileMetadataResponse;
+
+    return prepareResponseWithoutKeys(fileMetadataResponse, ['_links']);
 }
 
+/**
+ * Retrieve file metadata for a specific property of a Lime object.
+ *
+ * @param nodeContext - n8n execution context
+ * @param limetype - Name of the Limetype
+ * @param id - The Lime object ID
+ * @param fileTypeProperty - The property name holding the file reference
+ * @returns File metadata
+ *
+ * @public
+ * @group Transport
+ */
 export async function getFileMetadataByLimeobject(
     nodeContext: IExecuteFunctions,
     limetype: string,
     id: string,
     fileTypeProperty: string
-): Promise<NodeResponse<FileMetadata>> {
+): Promise<APIResponse<FileMetadata>> {
     const objectResponse = await getLimeobject(nodeContext, limetype, id);
-    if (!objectResponse.success) {
-        return objectResponse;
-    }
+    if (!objectResponse.success) return objectResponse;
+
     const fileId = objectResponse.data[fileTypeProperty] as string | undefined;
 
     if (!fileId) {
-        return {
-            success: false,
-            error: 'The specified Limeobject does not have an associated file.',
-        };
+        return handleWorkflowError(
+            nodeContext,
+            {
+                message:
+                    'The specified Limeobject does not have an associated file',
+            },
+            true
+        );
     }
 
-    const metadataResponse = await getFileMetadata(nodeContext, fileId);
-    if (!metadataResponse.success) {
-        return metadataResponse;
-    }
+    const fileMetadataResponse = await getFileMetadata(nodeContext, fileId);
+    if (!fileMetadataResponse.success) return fileMetadataResponse;
 
-    return {
-        success: true,
-        data: removeKeys(metadataResponse.data, ['_links']),
-    };
+    return prepareResponseWithoutKeys(fileMetadataResponse, ['_links']);
 }
 
+/**
+ * Download file content by file ID and prepare binary data for n8n nodes.
+ *
+ * @param nodeContext - n8n execution context
+ * @param id - The ID of the file
+ * @returns prepared binary data
+ *
+ * @public
+ * @group Transport
+ */
 export async function getFileContent(
     nodeContext: IExecuteFunctions,
     id: string | number
-): Promise<NodeResponse<IBinaryData>> {
+): Promise<APIResponse<IBinaryData>> {
     const url = `${LIME_FILE_URL}${id}/contents/`;
 
-    const response = await callLimeApi<FileApiResponse>(
-        nodeContext,
-        'GET',
-        url,
-        {
+    const response = await callLimeApi<FileApiResponse>(nodeContext, {
+        method: 'GET',
+        url: url,
+        requestOptions: {
             encoding: null,
             responseType: 'stream',
             resolveWithFullResponse: true,
         },
-        false
-    );
-    if (!response.success) {
-        return response;
-    }
+        json: false,
+    });
+
+    if (!response.success) return response;
 
     const fileName =
         getFilenameFromHeader(response.data.headers) || `file_${id}`;
@@ -103,53 +164,82 @@ export async function getFileContent(
     };
 }
 
+/**
+ * Download file content for a specific property of a Lime object.
+ *
+ * @param nodeContext - n8n execution context
+ * @param limetype - Name of the Limetype
+ * @param id - The Lime object ID
+ * @param fileTypeProperty - The property name holding the file reference
+ * @returns Prepared binary data
+ *
+ * @public
+ * @group Transport
+ */
 export async function getFileContentByLimetype(
     nodeContext: IExecuteFunctions,
     limetype: string,
     id: string,
     fileTypeProperty: string
-): Promise<NodeResponse<IBinaryData>> {
-    const objectResponse = await getLimeobject(nodeContext, limetype, id);
-    if (!objectResponse.success) {
-        return objectResponse;
-    }
-    const fileId = objectResponse.data[fileTypeProperty] as string | undefined;
+): Promise<APIResponse<IBinaryData>> {
+    const limeObjectResponse = await getLimeobject(nodeContext, limetype, id);
+    if (!limeObjectResponse.success) return limeObjectResponse;
+
+    const fileId = limeObjectResponse.data[fileTypeProperty] as
+        | string
+        | undefined;
 
     if (!fileId) {
-        return {
-            success: false,
-            error: 'The specified Limeobject does not have an associated file.',
-        };
+        return handleWorkflowError(
+            nodeContext,
+            {
+                message:
+                    'The specified Limeobject does not have an associated file.',
+            },
+            true
+        );
     }
 
     return await getFileContent(nodeContext, fileId);
 }
 
+/**
+ * Create a file in Lime CRM using binary data.
+ *
+ * @param nodeContext - n8n execution context
+ * @param binary - The binary data to upload
+ * @param fallbackFileName - File name to use if `binary.fileName` is missing
+ * @returns Created file metadata
+ *
+ * @public
+ * @group Transport
+ */
 export async function createFile(
     nodeContext: IExecuteFunctions,
     binary: IBinaryData,
     fallbackFileName: string
-): Promise<NodeResponse<FileMetadata>> {
-    const response = await callLimeApi<FileMetadata>(
-        nodeContext,
-        'POST',
-        LIME_FILE_URL,
-        {
+): Promise<APIResponse<FileMetadata>> {
+    const response = await callLimeApi<FileMetadata>(nodeContext, {
+        method: 'POST',
+        url: LIME_FILE_URL,
+        requestOptions: {
             body: Buffer.from(binary.data, BINARY_ENCODING),
             headers: {
                 'Content-Disposition': `;filename*="UTF-8''${encodeURIComponent(binary.fileName || fallbackFileName)}"`,
                 'Content-Type': binary.mimeType,
             },
-        }
-    );
-
-    // Remove metadata from the response to reduce its overall size
-    if (!response.success) {
-        return { success: false, error: response.error };
-    }
+        },
+    });
+    if (!response.success)
+        return {
+            success: false,
+            data: {
+                error: {
+                    message: response.data.error.message,
+                    status: response.data.error.status,
+                },
+            },
+        };
 
-    return {
-        success: true,
-        data: removeKeys(response.data, ['_links']),
-    };
+    return prepareResponseWithoutKeys(response, ['_links']);
 }

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

@@ -1,25 +1,43 @@
+export { HTTPMethod, callLimeApi, removeKeys } from './commons';
 export {
-    getSubscription,
-    deleteSubscription,
-    createSubscription,
-    listSubscriptionsWithExistingData,
-} from './webhooks';
-export { getLimetypesFromApi, getProperties } from './limetypes';
-
+    FileApiResponse,
+    FileMetadata,
+    createFile,
+    getFileContent,
+    getFileContentByLimetype,
+    getFileMetadata,
+    getFileMetadataByLimeobject,
+} from './files';
 export {
+    FetchManyLimeobjectsApiResponse,
+    LimeobjectCrmApiResponse,
     createLimeobject,
     deleteLimeobject,
     updateLimeobject,
     getLimeobject,
-    fetchManyLimeobjects,
 } from './limeobjects';
-export { startCreateOrUpdateObjectsTask } from './erpConnector';
-export { queryLimeobjects } from './limeQuery';
 export {
-    createFile,
-    getFileContent,
-    getFileContentByLimetype,
-    getFileMetadata,
-    getFileMetadataByLimeobject,
-} from './files';
-export { callLimeApi } from './commons';
+    IncludedProperties,
+    QueryResponse,
+    queryLimeobjects,
+} from './limeQuery';
+export {
+    LimetypeCrmApiResponse,
+    LimetypePropertiesApiResponse,
+    LimetypePropertyApiResponse,
+    LimetypesCrmApiResponse,
+    getLimetypesFromApi,
+    getProperties,
+} from './limetypes';
+export {
+    ApiResponseWebhook,
+    createSubscription,
+    deleteSubscription,
+    getSubscription,
+    listSubscriptionsWithExistingData,
+} from './webhooks';
+export {
+    fetchManyUsers,
+    fetchSingleUserById,
+    fetchSingleUserByLimeobjectId,
+} from './users';

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

@@ -1,26 +1,62 @@
 import { IAllExecuteFunctions } from 'n8n-workflow';
-import { NodeResponse } from '../../nodeResponse';
 import { callLimeApi } from './commons';
-
+import { APIResponsePrimitiveValue } from '../models';
+import { APIResponse } from '../../response';
+/**
+ * Endpoint path for Lime CRM Lime Query API.
+ *
+ * @internal
+ * @group Transport
+ */
 const LIME_QUERY_URL = '/api/v1/query/';
 
-interface IncludedProperties {
-    [key: string]: IncludedProperties | string | number | boolean | null;
+/**
+ * Structure of included properties returned by a query.
+ *
+ * The properties can themselves contain nested objects, primitive values, or nulls.
+ *
+ * @public
+ * @group Transport
+ */
+export interface IncludedProperties {
+    [key: string]: IncludedProperties | APIResponsePrimitiveValue;
 }
 
+/**
+ * The structure of a Lime CRM query API response.
+ *
+ * @property objects - An array of returned Limeobjects with their properties represented by a {@link IncludedProperties}
+ *
+ * @public
+ * @group Transport
+ */
 export interface QueryResponse {
     objects: IncludedProperties[];
 }
 
+/**
+ * Execute a Lime CRM query through the API.
+ *
+ * @param nodeContext - The n8n execution context
+ * @param q - The query string to execute
+ * @returns Query results
+ *
+ * @public
+ * @group Transport
+ */
 export async function queryLimeobjects(
     nodeContext: IAllExecuteFunctions,
     q: string
-): Promise<NodeResponse<QueryResponse>> {
+): Promise<APIResponse<QueryResponse>> {
     const queryParameters = {
         q: q,
     };
 
-    return await callLimeApi(nodeContext, 'GET', LIME_QUERY_URL, {
-        qs: queryParameters,
+    return await callLimeApi(nodeContext, {
+        method: 'GET',
+        url: LIME_QUERY_URL,
+        requestOptions: {
+            qs: queryParameters,
+        },
     });
 }