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

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

@@ -0,0 +1,300 @@
+import { callLimeApi } from './commons';
+import {
+    IAllExecuteFunctions,
+    LoggerProxy as Logger,
+    NodeApiError,
+} from 'n8n-workflow';
+import {
+    User,
+    UserType,
+    DEFAULT_API_OBJECT_LIMIT,
+    NullOptionType,
+    Limetype,
+} from '../models';
+import { getLimetypesFromApi } from './limetypes';
+import { queryLimeobjects, QueryResponse } from './limeQuery';
+import { getLimeobject } from './limeobjects';
+import { APIResponse } from '../../response';
+import { handleWorkflowError } from '../../errorHandling';
+const USERS_URL = 'api/v1/admin/users/';
+
+type UserQueryParameters = {
+    active?: boolean;
+    user_type?: UserType;
+    _limit: number;
+};
+
+/**
+ * Finds limetype that has a property of type 'user'.
+ * There should only be one such limetype in the system.
+ *
+ * @param limetypes - Array of limetype objects to search through
+ * @returns The first limetype with a 'user' property, or undefined if not found
+ * @internal
+ */
+function findCoworkerLimetype(limetypes: Limetype[]): Limetype | undefined {
+    for (const limetype of limetypes) {
+        for (const property of limetype.properties) {
+            if (property.type === 'user') {
+                Logger.info('Found coworker limetype');
+                return limetype;
+            }
+        }
+    }
+    Logger.warn('No coworker limetype found');
+    return undefined;
+}
+
+/**
+ * Retrieves the coworker limetype from the API.
+ *
+ * @param nodeContext - The n8n execution context
+ * @returns The coworker limetype object
+ * @throws NodeApiError if no coworker limetype is found
+ * @internal
+ */
+async function findCoworker(
+    nodeContext: IAllExecuteFunctions
+): Promise<APIResponse<Limetype>> {
+    const response = await getLimetypesFromApi(nodeContext);
+    if (!response.success) {
+        return response;
+    }
+    const coworker = findCoworkerLimetype(response.data);
+    if (!coworker) {
+        return handleWorkflowError(
+            nodeContext,
+            {
+                message: `No limetype with 'user' property found to get coworker`,
+            },
+            true
+        );
+    }
+    return {
+        success: true,
+        data: coworker,
+    };
+}
+
+/**
+ * Fetches coworker data for a given user.
+ *
+ * @param nodeContext - The n8n execution context
+ * @param coworker - The limetype definition for the coworker
+ * @param userId - The ID of the user whose coworker data is to be fetched
+ * @returns The coworker data response from the Lime Query API
+ * @throws NodeApiError' property is found in the coworker limetype
+ * @internal
+ */
+async function getCoworker(
+    nodeContext: IAllExecuteFunctions,
+    coworker: Limetype,
+    userId: string | number
+): Promise<APIResponse<QueryResponse>> {
+    // 'hasmany' properties are not supported in the response format of Lime Query API
+    const properties = Object.fromEntries(
+        coworker.properties
+            .filter((prop) => prop.type !== 'hasmany')
+            .map((prop) => [prop.name, ''])
+    );
+
+    const userProperty = coworker.properties.find(
+        (prop) => prop.type === 'user'
+    );
+    if (!userProperty) {
+        throw new NodeApiError(nodeContext.getNode(), {
+            message: `No property of type 'user' found in ${coworker.name} limetype`,
+        });
+    }
+
+    const responseFormat = {
+        object: properties,
+    };
+    const filter = {
+        key: userProperty.name,
+        op: '=',
+        exp: userId,
+    };
+    const q = JSON.stringify({
+        limetype: coworker.name,
+        responseFormat: responseFormat,
+        filter: filter,
+    });
+
+    return await queryLimeobjects(nodeContext, q);
+}
+
+/**
+ * Fetch the Lime CRM users with given parameters.
+ *
+ * @param nodeContext - The n8n execution context
+ * @param active - flag used to filtering by active or inactive users
+ * @param userType - a type of a user defined in the {@link UserType} class
+ * @param limit - max number of users returned by the API call, default is 50
+ * @param withCoworker - whether to include coworker data linked to the user
+ *
+ * @returns List of {@link User} objects
+ * @public
+ * @group Transport
+ */
+
+export async function fetchManyUsers(
+    nodeContext: IAllExecuteFunctions,
+    active: boolean | NullOptionType = '',
+    userType: UserType | NullOptionType = '',
+    limit: number = DEFAULT_API_OBJECT_LIMIT,
+    withCoworker: boolean = false
+): Promise<APIResponse<User[]>> {
+    const queryParams: UserQueryParameters = {
+        _limit: limit,
+    };
+    if (active !== '') {
+        queryParams.active = active;
+    }
+    if (userType !== '') {
+        queryParams.user_type = userType;
+    }
+
+    const response = await callLimeApi<User[]>(nodeContext, {
+        method: 'GET',
+        url: USERS_URL,
+        requestOptions: {
+            qs: queryParams,
+        },
+    });
+
+    if (!response.success || !withCoworker) return response;
+
+    const coworkerLimetypeResponse = await findCoworker(nodeContext);
+    if (!coworkerLimetypeResponse.success) return coworkerLimetypeResponse;
+
+    const coworkerLimetype = coworkerLimetypeResponse.data;
+
+    const usersWithCoworkers: User[] = [];
+    for (const user of response.data) {
+        const coworkerResponse = await getCoworker(
+            nodeContext,
+            coworkerLimetype,
+            user.id
+        );
+        if (!coworkerResponse.success) return coworkerResponse;
+        usersWithCoworkers.push({
+            ...user,
+            [coworkerLimetype.name]: coworkerResponse.data.objects[0] || null,
+        });
+    }
+
+    return {
+        success: true,
+        data: usersWithCoworkers,
+    };
+}
+
+/**
+ * Fetch the single Lime CRM User by ID.
+ *
+ * @param nodeContext - The n8n execution context
+ * @param id - Lime CRM user's ID
+ * @param withCoworker - whether to include coworker data linked to the user
+ *
+ * @returns A {@link User} object
+ * @public
+ * @group Transport
+ */
+
+export async function fetchSingleUserById(
+    nodeContext: IAllExecuteFunctions,
+    id: string,
+    withCoworker: boolean = false
+): Promise<APIResponse<User>> {
+    const url = `${USERS_URL}${id}`;
+    const userResponse = await callLimeApi<User>(nodeContext, {
+        method: 'GET',
+        url: url,
+        errorMetadata: {
+            user_id: id,
+        },
+    });
+
+    if (!userResponse.success || !withCoworker) return userResponse;
+    const coworkerLimetypeResponse = await findCoworker(nodeContext);
+    if (!coworkerLimetypeResponse.success) return coworkerLimetypeResponse;
+
+    const coworkerResponse = await getCoworker(
+        nodeContext,
+        coworkerLimetypeResponse.data,
+        id
+    );
+    if (!coworkerResponse.success) return coworkerResponse;
+
+    return {
+        ...userResponse,
+        [coworkerLimetypeResponse.data.name]:
+            coworkerResponse.data.objects[0] || null,
+    };
+}
+
+/**
+ * Fetch a single Lime CRM User by the related limeobject ID.
+ *
+ * This function retrieves a user based on the ID of a related limeobject.
+ * It could be only one object related to the user in the system, most often it is the
+ * 'coworker' limetype. The corresponding limetype is determined automatically.
+ *
+ * @param nodeContext - The n8n execution context
+ * @param id - The ID of the coworker limeobject
+ * @param withCoworker - Whether to include coworker data linked to the user (default: false)
+ *
+ * @returns A {@link User} object, optionally with coworker data
+ * @public
+ * @group Transport
+ */
+export async function fetchSingleUserByLimeobjectId(
+    nodeContext: IAllExecuteFunctions,
+    id: string,
+    withCoworker: boolean = false
+): Promise<APIResponse<User>> {
+    const coworkerLimetypeResponse = await findCoworker(nodeContext);
+    if (!coworkerLimetypeResponse.success) return coworkerLimetypeResponse;
+
+    const coworkerLimetype = coworkerLimetypeResponse.data;
+
+    const coworkerResponse = await getLimeobject(
+        nodeContext,
+        coworkerLimetype.name,
+        id
+    );
+    if (!coworkerResponse.success) return coworkerResponse;
+
+    const userProperty = coworkerLimetype.properties.find(
+        (prop) => prop.type === 'user'
+    );
+    if (!userProperty) {
+        return handleWorkflowError(
+            nodeContext,
+            {
+                message: `No property of type 'user' found in ${coworkerLimetype.name} limetype`,
+            },
+            true
+        );
+    }
+
+    const url = `${USERS_URL}${coworkerResponse.data[userProperty.name]}`;
+    const userResponse = await callLimeApi<User>(nodeContext, {
+        method: 'GET',
+        url: url,
+        errorMetadata: {
+            user_id: id,
+        },
+    });
+
+    if (!userResponse.success || !withCoworker) return userResponse;
+
+    return {
+        success: true,
+        data: {
+            ...userResponse.data,
+            [coworkerLimetype.name]: coworkerResponse.data || null,
+        },
+    };
+}

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

@@ -1,12 +1,29 @@
-import { Webhook } from '../commons';
 import { callLimeApi } from '.';
 import { IAllExecuteFunctions } from 'n8n-workflow';
-import { NodeResponse } from '../../nodeResponse';
-import { CreateWebhook } from '../commons/webhook';
+import { CreateWebhook, Webhook } from '../models';
+import { APIResponse } from '../../response';
 
+/**
+ * Endpoint path for Lime CRM Subscription API.
+ *
+ * @internal
+ * @group Transport
+ */
 const SUBSCRIPTION_URL = 'api/v1/subscription/';
 
-interface ApiResponseWebhook {
+/**
+ * Representation of response format for a Lime CRM webhook subscription.
+ *
+ * @property {string} id - Unique identifier of the subscription
+ * @property {string} name - Name of the subscription
+ * @property {boolean} enabled - Whether the subscription is currently enabled
+ * @property {string[]} events - List of events the subscription is listening for
+ * @property {string} target_url - Target URL for the webhook
+ *
+ * @public
+ * @group Transport
+ */
+export interface ApiResponseWebhook {
     id: string;
     name: string;
     enabled: boolean;
@@ -14,61 +31,104 @@ interface ApiResponseWebhook {
     target_url: string;
 }
 
+/**
+ * Retrieve details of a specific subscription from Lime CRM.
+ *
+ * @param nodeContext - The n8n node execution context
+ * @param webhook - The webhook object containing subscription details
+ *
+ * @returns The subscription information from Lime CRM.
+ *
+ * @public
+ * @group Transport
+ */
 export async function getSubscription(
     nodeContext: IAllExecuteFunctions,
     webhook: Webhook
-): Promise<NodeResponse<ApiResponseWebhook>> {
-    return await callLimeApi(
-        nodeContext,
-        'GET',
-        `${SUBSCRIPTION_URL}${webhook.data.webhookId}`
-    );
+): Promise<APIResponse<ApiResponseWebhook>> {
+    return await callLimeApi(nodeContext, {
+        method: 'GET',
+        url: `${SUBSCRIPTION_URL}${webhook.data.webhookId}`,
+    });
 }
 
+/**
+ * List all active subscriptions that match the given webhook events and target URL.
+ *
+ * @param nodeContext - The n8n node execution context
+ * @param webhook - The webhook instance containing event and URL information
+ *
+ * @returns Array of subscription objects from Lime CRM.
+ *
+ * @public
+ * @group Transport
+ */
 export async function listSubscriptionsWithExistingData(
     nodeContext: IAllExecuteFunctions,
     webhook: Webhook
-): Promise<NodeResponse<ApiResponseWebhook[]>> {
-    return await callLimeApi(nodeContext, 'GET', SUBSCRIPTION_URL, {
-        qs: {
-            events: webhook.events.join(','),
-            target_url: webhook.url,
-            enabled: true,
+): Promise<APIResponse<ApiResponseWebhook[]>> {
+    return await callLimeApi(nodeContext, {
+        method: 'GET',
+        url: SUBSCRIPTION_URL,
+        requestOptions: {
+            qs: {
+                events: webhook.events.join(','),
+                target_url: webhook.url,
+                enabled: true,
+            },
         },
     });
 }
 
+/**
+ * Creates a new webhook subscription in Lime CRM.
+ *
+ * @param nodeContext - The n8n node execution context.
+ * @param webhook - The webhook configuration to create.
+ *
+ * @returns The newly created subscription object.
+ *
+ * @public
+ * @group Transport
+ */
 export async function createSubscription(
     nodeContext: IAllExecuteFunctions,
     webhook: CreateWebhook
-): Promise<NodeResponse<ApiResponseWebhook>> {
-    return await callLimeApi(nodeContext, 'POST', SUBSCRIPTION_URL, {
-        body: {
-            events: webhook.events,
-            target_url: webhook.url,
-            name: webhook.name,
-            secret: webhook.secret,
+): Promise<APIResponse<ApiResponseWebhook>> {
+    return await callLimeApi(nodeContext, {
+        method: 'POST',
+        url: SUBSCRIPTION_URL,
+        requestOptions: {
+            body: {
+                events: webhook.events,
+                target_url: webhook.url,
+                name: webhook.name,
+                secret: webhook.secret,
+            },
         },
     });
 }
 
+/**
+ * Delete a webhook subscription from Lime CRM.
+ *
+ * @param nodeContext - The n8n node execution context
+ * @param webhook - The webhook object identifying the subscription to delete
+ *
+ * @returns Response indicating success or failure of the deletion.
+ *
+ * @public
+ * @group Transport
+ */
 export async function deleteSubscription(
     nodeContext: IAllExecuteFunctions,
     webhook: Webhook
-): Promise<NodeResponse<void>> {
-    const response: NodeResponse<void> = await callLimeApi(
-        nodeContext,
-        'DELETE',
-        `${SUBSCRIPTION_URL}${webhook.data.webhookId}/`
-    );
-
-    if (response.success) return response;
-
-    return {
-        ...response,
-        metadata: {
-            ...response.metadata,
+): Promise<APIResponse<void>> {
+    return await callLimeApi(nodeContext, {
+        method: 'DELETE',
+        url: `${SUBSCRIPTION_URL}${webhook.data.webhookId}/`,
+        errorMetadata: {
             id: webhook.data.webhookId,
         },
-    };
+    });
 }

package/nodes/lime-crm/{commons → utils}/files.ts

@@ -4,19 +4,20 @@ import {
     IExecuteFunctions,
     LoggerProxy as Logger,
 } from 'n8n-workflow';
-import {
-    createFile,
-    getFileContent,
-    getFileMetadata,
-    getProperties,
-} from '../transport';
-import { NodeResponse } from '../../nodeResponse';
-
-type FileResponse<T> = {
-    json: NodeResponse<T>;
-    binary?: Record<string, IBinaryData>;
-};
+import { createFile, getFileContent, getFileMetadata } from '../transport';
+import { APIResponse, FileAPIResponse } from '../../response';
+import { LimetypeProperty } from '../models';
 
+/**
+ * Set a default file name if missing.
+ *
+ * @param preparedBinaryData - The binary data object
+ * @param responseFileName -The fallback file name to assign if the binary data has no name
+ *
+ * @returns Set filename
+ * @public
+ * @group Utils
+ */
 export const setFilename = (
     preparedBinaryData: IBinaryData,
     responseFileName: string
@@ -28,6 +29,16 @@ export const setFilename = (
     return preparedBinaryData.fileName;
 };
 
+/**
+ * Extract a filename from the `Content-Disposition` HTTP header.
+ *
+ * @param headers - An object containing HTTP headers, where the key may be either
+ * `'content-disposition'` or `'Content-Disposition'`
+ *
+ * @returns Filename or `null` if the header does not contain one
+ * @public
+ * @group Utils
+ */
 export function getFilenameFromHeader(
     headers: Record<string, string | string[] | undefined>
 ): string | null {
@@ -63,16 +74,23 @@ export function getFilenameFromHeader(
     return null;
 }
 
-export async function getFileProperties(
-    nodeContext: IExecuteFunctions,
-    limetype: string,
+/**
+ * Retrieve all file properties names for a given Limetype
+ * and optionally filter by a set of allowed property names.
+ *
+ * @param properties - the {@link LimeTypeProperty} object array fetched from Lime CRM
+ * @param allowedProperties - An optional set of property names to include in the result
+ *
+ * @returns A set containing the names of all matching file-type properties.
+ * @public
+ * @group Utils
+ */
+export function getFilePropertiesNames(
+    properties: LimetypeProperty[],
     allowedProperties?: Set<string>
-): Promise<Set<string>> {
-    const response = await getProperties(nodeContext, limetype);
-
-    if (!response.success) return new Set();
+): Set<string> {
     return new Set(
-        response.data
+        properties
             .filter(
                 (property) =>
                     property.type === 'file' &&
@@ -82,12 +100,28 @@ export async function getFileProperties(
     );
 }
 
+/**
+ * Iterate through all file properties, checks whether
+ * the corresponding values represent valid binary data, and uploads them.
+ * When a file is successfully uploaded, its property value is replaced with the returned file ID.
+ *
+ * @param context - The n8n node execution context
+ * @param i - The index of the current item being processed
+ * @param fileProperties - A set of Limeobject property names that are of type `'file'`
+ * @param definedProperties - An object containing property values
+ *
+ * @returns A response object indicating whether the operation succeeded and containing
+ * the updated properties.
+ *
+ * @public
+ * @group Utils
+ */
 export async function setFileProperties(
     context: IExecuteFunctions,
     i: number,
     fileProperties: Set<string>,
     definedProperties: IDataObject
-): Promise<NodeResponse<IDataObject>> {
+): Promise<APIResponse<IDataObject>> {
     for (const fileProperty of fileProperties) {
         if (!(fileProperty in definedProperties)) continue;
         let binaryData: IBinaryData;
@@ -105,6 +139,7 @@ export async function setFileProperties(
             );
             continue;
         }
+
         const response = await createFile(
             context,
             binaryData,
@@ -121,12 +156,25 @@ export async function setFileProperties(
     };
 }
 
+/**
+ * Update file properties with a file metadata and optionally retrieves file content.
+ *
+ * @param nodeContext - The n8n node execution context
+ * @param fileProperties - A set of file property names to process
+ * @param data - The record data containing property values to process
+ * @param includeFileContent - Whether to include the actual file content in the response. Defaults to `false`
+ *
+ * @returns A {@link FileAPIResponse} object containing updated JSON data and, if requested, the associated binary files.
+ *
+ * @public
+ * @group Utils
+ */
 export async function processFileResponse<T extends Record<string, unknown>>(
     nodeContext: IExecuteFunctions,
     fileProperties: Set<string>,
     data: T,
     includeFileContent: boolean = false
-): Promise<FileResponse<T>> {
+): Promise<FileAPIResponse<T>> {
     let updatedData = { ...data };
     const binaryData: Record<string, IBinaryData> = {};
     for (const fileProperty of fileProperties) {
@@ -136,7 +184,9 @@ export async function processFileResponse<T extends Record<string, unknown>>(
             data[fileProperty] as string
         );
         if (!fileMetadataResponse.success)
-            return { json: fileMetadataResponse };
+            return {
+                json: fileMetadataResponse,
+            };
 
         updatedData = {
             ...updatedData,
@@ -144,12 +194,15 @@ export async function processFileResponse<T extends Record<string, unknown>>(
         };
 
         if (includeFileContent) {
-            const fileResponse = await getFileContent(
+            const fileContentResponse = await getFileContent(
                 nodeContext,
                 fileMetadataResponse.data.id
             );
-            if (!fileResponse.success) return { json: fileResponse };
-            binaryData[fileProperty] = fileResponse.data;
+            if (fileContentResponse.success) {
+                binaryData[fileProperty] = fileContentResponse.data;
+            } else {
+                return { json: fileContentResponse };
+            }
         }
     }
     return {

package/nodes/lime-crm/utils/hmac.ts

@@ -0,0 +1,35 @@
+import { createHmac } from 'node:crypto';
+
+/**
+ * Generate an HMAC SHA-256 hash for the given data using the provided key.
+ *
+ * @param key - The secret key used to generate the HMAC
+ * @param data - The data to hash
+ * @returns The generated HMAC string in the format `sha256=<digest>`.
+ *
+ * @internal
+ * @group Utils
+ */
+function generateHmac(key: string, data: Buffer): string {
+    return 'sha256=' + createHmac('sha256', key).update(data).digest('hex');
+}
+
+/**
+ * Verify that a given HMAC matches the expected value for the provided data and key.
+ *
+ * @param key - The secret key used to generate the HMAC
+ * @param data - The data to verify against
+ * @param comparedHmac - The HMAC value to compare with
+ *
+ * @returns `true` if the HMAC matches, otherwise `false`.
+ *
+ * @public
+ * @group Utils
+ */
+export function verifyHmac(
+    key: string,
+    data: Buffer,
+    comparedHmac: string
+): boolean {
+    return generateHmac(key, data) === comparedHmac;
+}

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

@@ -0,0 +1,10 @@
+export {
+    setFilename,
+    getFilenameFromHeader,
+    getFilePropertiesNames,
+    processFileResponse,
+    setFileProperties,
+} from './files';
+export { verifyHmac } from './hmac';
+export { getWebhook } from './webhook';
+export { handleWorkflowError, WorkflowErrorContext } from '../../errorHandling';