@ixiam/n8n-nodes-civicrm 0.4.4 → 1.0.0

package/README.md

@@ -1,13 +1,110 @@
 # n8n-nodes-civicrm
-Community node for **CiviCRM API v4** and **Form Processor**.
+Community Node for **CiviCRM API v4** (Civi-Go compatible)  
+Developed and maintained by **Ixiam Global Solutions**.
 
-Install: Settings → Community Nodes → Install → `n8n-nodes-civicrm`
+This node enables full integration between **n8n** and **CiviCRM API v4**, supporting create/update/delete operations, smart field mapping, dynamic location types, and advanced filtering on GET operations.
 
-Credentials:
-- Base URL: `https://crm.example.org` (no trailing slash)
-- API Token: header `X-Civi-Auth: Bearer <token>`
-- Use the **Save** button to verify connectivity.
+## 🚀 Installation
 
-Entities: Contact, Event, Case, Contribution, Membership → `get|getMany|create|update|delete`
+1. In your n8n instance, go to:  
+   **Settings → Community Nodes → Install**
+2. Enter the package name:
 
-Node developed by Ixiam Global Solution: `https://www.ixiam.com'
+```
+n8n-nodes-civicrm
+```
+
+3. Approve installation and enable Community Nodes.
+
+## 🔐 Credentials
+
+The node uses **Bearer Token Authentication**.
+
+| Field | Description |
+|-------|-------------|
+| **Base URL** | The root URL of your CiviCRM instance (without trailing slash). Example: `https://crm.example.org` |
+| **API Token** | Sent as header `X-Civi-Auth: Bearer <token>` |
+
+After entering credentials, click **Save** to validate the connection.
+
+## 📦 Supported Entities
+
+The node includes full API v4 support for the following entities:
+
+| Entity | Operations |
+|--------|------------|
+| **Contact** | get, getMany, create, update, delete |
+| **Membership** | get, getMany, create, update, delete |
+| **Group** | get, getMany, create, update, delete |
+| **Relationship** | get, getMany, create, update, delete |
+| **Activity** | get, getMany, create, update, delete |
+| **Custom API Call** | full custom API4 request |
+
+## 🧩 Key Features
+
+### **1. Dynamic Field Mapping**
+Supports any standard or custom field:
+
+```
+first_name = John
+last_name = Doe
+custom_45 = Blue
+```
+
+### **2. Smart Email, Phone & Address Mapping**
+Two ways to set location-aware fields:
+
+**(A) Simple fields**
+```
+email = test@example.org
+phone.mobile = 600123456
+address.city = Barcelona
+```
+
+**(B) Dynamic prefixes matched to CiviCRM Location Types**
+```
+work.email = user@company.org
+billing.address.postal_code = 80331
+home.phone.phone_type_id = 2
+```
+
+### **3. Default Location Type selectors**
+If no prefix is used, default types are applied.
+
+### **4. Birth Date Normalization**
+Accepted input formats:
+
+- YYYY-MM-DD
+- DD/MM/YYYY
+- DD-MM-YYYY
+- YYYY/MM/DD
+- YYYY.MM.DD
+
+Auto-normalized to `YYYY-MM-DD`.
+
+### **5. GET MANY with JSON Filters**
+```
+[
+  ["first_name", "LIKE", "Ju%"],
+  ["birth_date", ">", "1990-01-01"],
+  ["gender_id", "IN", [1, 2]]
+]
+```
+
+### **6. Custom API Call Mode**
+```
+{
+  "entity": "Contact",
+  "action": "get",
+  "params": { "limit": 10 }
+}
+```
+
+## 🧑‍💻 About Ixiam Global Solutions
+
+Website: **https://www.ixiam.com**  
+Contact: **info@ixiam.com**
+
+## 📄 License
+
+MIT License

package/credentials/CiviCrmApi.credentials.ts

@@ -1,61 +1,58 @@
 import type {
-  ICredentialType,
-  INodeProperties,
-  IHttpRequestMethods,
+	ICredentialType,
+	INodeProperties,
+	IHttpRequestMethods,
 } from 'n8n-workflow';
 
 export class CiviCrmApi implements ICredentialType {
-  name = 'civiCrmApi';
-  displayName = 'CiviCRM API';
-  documentationUrl = 'https://docs.civicrm.org/dev/en/latest/api/v4/';
+	name = 'civiCrmApi';
+	displayName = 'CiviCRM API';
+	documentationUrl = 'https://docs.civicrm.org/dev/en/latest/api/';
 
-  authenticate = {
-    type: 'generic' as const,
-    properties: {
-      headers: {
-        'X-Civi-Auth': '={{"Bearer " + $credentials.apiToken}}',
-        'Content-Type': 'application/json',
-      },
-    },
-  };
+	authenticate = {
+		type: 'generic' as const,
+		properties: {
+			headers: {
+				'X-Civi-Auth': '={{"Bearer " + $credentials.apiToken}}',
+				'Content-Type': 'application/x-www-form-urlencoded',
+			},
+		},
+	};
 
-  // Button "Test" in credential UI
-  test = {
-    request: {
-      // IMPORTANT: method must be typed as IHttpRequestMethods
-      method: 'POST' as IHttpRequestMethods,
-      url: '={{$credentials.baseUrl.replace(/\\/$/, "")}}/civicrm/ajax/api4/Contact/get',
-      headers: {
-        'X-Civi-Auth': '={{"Bearer " + $credentials.apiToken}}',
-        'Content-Type': 'application/json',
-      },
-      body: {
-        entity: 'Contact',
-        action: 'get',
-        params: { limit: 1 },
-      },
-      json: true,
-    },
-  };
+	// Credential test button
+	test = {
+		request: {
+			method: 'POST' as IHttpRequestMethods,
+			url: '={{$credentials.baseUrl.replace(/\\/$/, "")}}/civicrm/ajax/api4/Contact/get',
+			headers: {
+				'X-Civi-Auth': '={{"Bearer " + $credentials.apiToken}}',
+				'Content-Type': 'application/x-www-form-urlencoded',
+			},
+			body: {
+				params: '={"limit":1}', // API4 compatible
+			},
+			json: true,
+		},
+	};
 
-  properties: INodeProperties[] = [
-    {
-      displayName: 'Base URL',
-      name: 'baseUrl',
-      type: 'string',
-      default: '',
-      required: true,
-      placeholder: 'https://crm.example.org',
-      description: 'Sin la barra final',
-    },
-    {
-      displayName: 'API Token',
-      name: 'apiToken',
-      type: 'string',
-      typeOptions: { password: true },
-      default: '',
-      required: true,
-      description: 'Se envía como X-Civi-Auth: Bearer <token>',
-    },
-  ];
+	properties: INodeProperties[] = [
+		{
+			displayName: 'Base URL',
+			name: 'baseUrl',
+			type: 'string',
+			default: '',
+			required: true,
+			placeholder: 'https://crm.example.org',
+			description: 'Base URL without a trailing slash.',
+		},
+		{
+			displayName: 'API Token',
+			name: 'apiToken',
+			type: 'string',
+			typeOptions: { password: true },
+			default: '',
+			required: true,
+			description: 'Sent as "X-Civi-Auth: Bearer &lt;token&gt;"',
+		},
+	];
 }

package/dist/credentials/CiviCrmApi.credentials.d.ts

@@ -21,11 +21,7 @@ export declare class CiviCrmApi implements ICredentialType {
                 'Content-Type': string;
             };
             body: {
-                entity: string;
-                action: string;
-                params: {
-                    limit: number;
-                };
+                params: string;
             };
             json: boolean;
         };

package/dist/credentials/CiviCrmApi.credentials.js

@@ -5,30 +5,27 @@ class CiviCrmApi {
     constructor() {
         this.name = 'civiCrmApi';
         this.displayName = 'CiviCRM API';
-        this.documentationUrl = 'https://docs.civicrm.org/dev/en/latest/api/v4/';
+        this.documentationUrl = 'https://docs.civicrm.org/dev/en/latest/api/';
         this.authenticate = {
             type: 'generic',
             properties: {
                 headers: {
                     'X-Civi-Auth': '={{"Bearer " + $credentials.apiToken}}',
-                    'Content-Type': 'application/json',
+                    'Content-Type': 'application/x-www-form-urlencoded',
                 },
             },
         };
-        // Button "Test" in credential UI
+        // Credential test button
         this.test = {
             request: {
-                // IMPORTANT: method must be typed as IHttpRequestMethods
                 method: 'POST',
                 url: '={{$credentials.baseUrl.replace(/\\/$/, "")}}/civicrm/ajax/api4/Contact/get',
                 headers: {
                     'X-Civi-Auth': '={{"Bearer " + $credentials.apiToken}}',
-                    'Content-Type': 'application/json',
+                    'Content-Type': 'application/x-www-form-urlencoded',
                 },
                 body: {
-                    entity: 'Contact',
-                    action: 'get',
-                    params: { limit: 1 },
+                    params: '={"limit":1}', // API4 compatible
                 },
                 json: true,
             },
@@ -41,7 +38,7 @@ class CiviCrmApi {
                 default: '',
                 required: true,
                 placeholder: 'https://crm.example.org',
-                description: 'Sin la barra final',
+                description: 'Base URL without a trailing slash.',
             },
             {
                 displayName: 'API Token',
@@ -50,7 +47,7 @@ class CiviCrmApi {
                 typeOptions: { password: true },
                 default: '',
                 required: true,
-                description: 'Se envía como X-Civi-Auth: Bearer <token>',
+                description: 'Sent as "X-Civi-Auth: Bearer &lt;token&gt;"',
             },
         ];
     }

package/dist/nodes/CiviCrm/CiviCrm.node.d.ts

@@ -1,12 +1,12 @@
-import type { IExecuteFunctions, ILoadOptionsFunctions, INodeExecutionData, INodePropertyOptions, INodeType, INodeTypeDescription } from 'n8n-workflow';
-/**
- * Nodo principal CiviCRM para n8n
- */
+import type { IExecuteFunctions, ILoadOptionsFunctions, INodeExecutionData, INodeType, INodeTypeDescription } from 'n8n-workflow';
 export declare class CiviCrm implements INodeType {
     description: INodeTypeDescription;
     methods: {
         loadOptions: {
-            getOptionValues(this: ILoadOptionsFunctions): Promise<INodePropertyOptions[]>;
+            loadOptionValues(this: ILoadOptionsFunctions): Promise<{
+                name: string;
+                value: number;
+            }[]>;
         };
     };
     execute(this: IExecuteFunctions): Promise<INodeExecutionData[][]>;