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

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

@@ -1,9 +1,46 @@
-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, NodeOperationError } from 'n8n-workflow';
 
-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[]
+): Omit<T, K> {
+    const { ...obj } = data;
+    for (const key of keys) {
+        delete obj[key];
+    }
+    return obj;
+}
+
+/**
+ * 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
@@ -11,35 +48,68 @@ 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>
-): Promise<NodeResponse<T>> {
+    options: LimeAPIArguments
+): Promise<T> {
     try {
-        const response: T =
-            await nodeContext.helpers.requestWithAuthentication.call(
-                nodeContext,
-                LIME_CRM_API_CREDENTIAL_KEY,
-                {
-                    method: method,
-                    url: url,
-                    json: true,
-                    baseURL: await getLimeUrl(nodeContext),
-                    ...options,
-                }
-            );
-        return {
-            success: true,
-            data: response,
-        };
+        return await nodeContext.helpers.requestWithAuthentication.call(
+            nodeContext,
+            LIME_CRM_API_CREDENTIAL_KEY,
+            {
+                method: options.method,
+                url: options.url,
+                json: options.json || true,
+                baseURL: await getLimeUrl(nodeContext),
+                ...options.requestOptions,
+            }
+        );
     } catch (error) {
-        return {
-            success: false,
+        const errorContext = {
             error: error instanceof Error ? error.message : String(error),
             status: error?.cause?.status,
-            metadata: options,
+            metadata: {
+                ...options.requestOptions,
+                ...options.errorMetadata,
+            },
         };
+        throw new NodeOperationError(
+            nodeContext.getNode(),
+            JSON.stringify(errorContext)
+        );
     }
 }

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

@@ -0,0 +1,220 @@
+import { callLimeApi, getLimeobject } from '.';
+import {
+    IExecuteFunctions,
+    IBinaryData,
+    BINARY_ENCODING,
+    NodeOperationError,
+} from 'n8n-workflow';
+import { removeKeys } from './commons';
+import { getFilenameFromHeader, setFilename } from '../utils';
+
+/**
+ * Endpoint path for Lime CRM file API.
+ *
+ * @internal
+ * @group Transport
+ */
+const LIME_FILE_URL = '/api/v1/file/';
+
+/**
+ * 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;
+}
+
+/**
+ * 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;
+    content_type: string;
+    extension: string;
+    created_by: number;
+    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<FileMetadata> {
+    const url = `${LIME_FILE_URL}${id}/`;
+    const fileMetadata = await callLimeApi<FileMetadata>(nodeContext, {
+        method: 'GET',
+        url: url,
+    });
+    return removeKeys(fileMetadata, ['_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<FileMetadata> {
+    const objectResponse = await getLimeobject(nodeContext, limetype, id);
+    const fileId = objectResponse[fileTypeProperty] as string | undefined;
+
+    if (!fileId) {
+        throw new NodeOperationError(
+            nodeContext.getNode(),
+            'The specified Limeobject does not have an associated file.'
+        );
+    }
+
+    const fileMetadata = await getFileMetadata(nodeContext, fileId);
+    return removeKeys(fileMetadata, ['_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<IBinaryData> {
+    const url = `${LIME_FILE_URL}${id}/contents/`;
+
+    const response = await callLimeApi<FileApiResponse>(nodeContext, {
+        method: 'GET',
+        url: url,
+        requestOptions: {
+            encoding: null,
+            responseType: 'stream',
+            resolveWithFullResponse: true,
+        },
+        json: false,
+    });
+
+    const fileName = getFilenameFromHeader(response.headers) || `file_${id}`;
+    const binaryData = await nodeContext.helpers.prepareBinaryData(
+        response.body
+    );
+    binaryData.fileName = setFilename(binaryData, fileName);
+
+    return binaryData;
+}
+
+/**
+ * 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<IBinaryData> {
+    const limeObjectResponse = await getLimeobject(nodeContext, limetype, id);
+    const fileId = limeObjectResponse[fileTypeProperty] as string | undefined;
+
+    if (!fileId) {
+        throw new NodeOperationError(
+            nodeContext.getNode(),
+            'The specified Limeobject does not have an associated file.'
+        );
+    }
+
+    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<FileMetadata> {
+    let response: FileMetadata;
+    try {
+        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,
+                },
+            },
+        });
+    } catch (error) {
+        // Remove metadata from the response to reduce its overall size
+        throw new NodeOperationError(
+            nodeContext.getNode(),
+            JSON.parse(error).error
+        );
+    }
+
+    return removeKeys(response, ['_links']);
+}

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

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

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

@@ -1,28 +1,62 @@
 import { IAllExecuteFunctions } from 'n8n-workflow';
-import { NodeResponse } from '../../nodeResponse';
 import { callLimeApi } from './commons';
+import { APIResponsePrimitiveValue } from '../models';
 
+/**
+ * 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[];
 }
 
-export async function queryLimeObjects(
+/**
+ * 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,
-    activeObject: string
-): Promise<NodeResponse<QueryResponse>> {
+    q: string
+): Promise<QueryResponse> {
     const queryParameters = {
         q: q,
-        activeObject: activeObject,
     };
 
-    return await callLimeApi(nodeContext, 'GET', LIME_QUERY_URL, {
-        qs: queryParameters,
+    return await callLimeApi(nodeContext, {
+        method: 'GET',
+        url: LIME_QUERY_URL,
+        requestOptions: {
+            qs: queryParameters,
+        },
     });
 }