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

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

@@ -1,17 +1,52 @@
 import { callLimeApi, getLimeobject } from '.';
-import { IExecuteFunctions, IBinaryData, BINARY_ENCODING } from 'n8n-workflow';
-import { NodeResponse } from '../../nodeResponse';
+import {
+    IExecuteFunctions,
+    IBinaryData,
+    BINARY_ENCODING,
+    NodeOperationError,
+} from 'n8n-workflow';
 import { removeKeys } from './commons';
-import { getFilenameFromHeader, setFilename } from '../commons';
-
+import { getFilenameFromHeader, setFilename } from '../utils';
+
+/**
+ * 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,135 +56,165 @@ 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<FileMetadata> {
     const url = `${LIME_FILE_URL}${id}/`;
-    const response = await callLimeApi<FileMetadata>(nodeContext, 'GET', url);
-    if (!response.success) {
-        return response;
-    }
-
-    return {
-        success: true,
-        data: removeKeys(response.data, ['_links']),
-    };
+    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<NodeResponse<FileMetadata>> {
+): Promise<FileMetadata> {
     const objectResponse = await getLimeobject(nodeContext, limetype, id);
-    if (!objectResponse.success) {
-        return objectResponse;
-    }
-    const fileId = objectResponse.data[fileTypeProperty] as string | undefined;
+    const fileId = objectResponse[fileTypeProperty] as string | undefined;
 
     if (!fileId) {
-        return {
-            success: false,
-            error: 'The specified Limeobject does not have an associated file.',
-        };
-    }
-
-    const metadataResponse = await getFileMetadata(nodeContext, fileId);
-    if (!metadataResponse.success) {
-        return metadataResponse;
+        throw new NodeOperationError(
+            nodeContext.getNode(),
+            'The specified Limeobject does not have an associated file.'
+        );
     }
 
-    return {
-        success: true,
-        data: removeKeys(metadataResponse.data, ['_links']),
-    };
+    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<NodeResponse<IBinaryData>> {
+): Promise<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,
+    });
 
-    const fileName =
-        getFilenameFromHeader(response.data.headers) || `file_${id}`;
+    const fileName = getFilenameFromHeader(response.headers) || `file_${id}`;
     const binaryData = await nodeContext.helpers.prepareBinaryData(
-        response.data.body
+        response.body
     );
     binaryData.fileName = setFilename(binaryData, fileName);
 
-    return {
-        success: true,
-        data: binaryData,
-    };
+    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<NodeResponse<IBinaryData>> {
-    const objectResponse = await getLimeobject(nodeContext, limetype, id);
-    if (!objectResponse.success) {
-        return objectResponse;
-    }
-    const fileId = objectResponse.data[fileTypeProperty] as string | undefined;
+): Promise<IBinaryData> {
+    const limeObjectResponse = await getLimeobject(nodeContext, limetype, id);
+    const fileId = limeObjectResponse[fileTypeProperty] as string | undefined;
 
     if (!fileId) {
-        return {
-            success: false,
-            error: 'The specified Limeobject does not have an associated file.',
-        };
+        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<NodeResponse<FileMetadata>> {
-    const response = await callLimeApi<FileMetadata>(
-        nodeContext,
-        'POST',
-        LIME_FILE_URL,
-        {
-            body: Buffer.from(binary.data, BINARY_ENCODING),
-            headers: {
-                'Content-Disposition': `;filename*="UTF-8''${encodeURIComponent(binary.fileName || fallbackFileName)}"`,
-                'Content-Type': binary.mimeType,
+): 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,
+                },
             },
-        }
-    );
-
-    // Remove metadata from the response to reduce its overall size
-    if (!response.success) {
-        return { success: false, error: response.error };
+        });
+    } catch (error) {
+        // Remove metadata from the response to reduce its overall size
+        throw new NodeOperationError(
+            nodeContext.getNode(),
+            JSON.parse(error).error
+        );
     }
 
-    return {
-        success: true,
-        data: removeKeys(response.data, ['_links']),
-    };
+    return removeKeys(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';
 
+/**
+ * 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<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,
+        },
     });
 }