n8n-nodes-clientify 0.2.0 → 0.2.1

package/README.md

@@ -126,6 +126,8 @@ This node dynamically supports **26 operations** from the Clientify MCP API:
 
 **NEW in v0.2.0!** The Clientify Trigger node enables automatic workflow execution when events occur in Clientify CRM.
 
+📚 **For complete trigger documentation with payload examples and webhook URLs, see [TRIGGERS_REFERENCE.md](TRIGGERS_REFERENCE.md)**
+
 ### Available Triggers
 
 #### 👥 Contact Triggers

package/dist/README.md

@@ -0,0 +1,514 @@
+# n8n-nodes-clientify
+
+[![npm version](https://badge.fury.io/js/n8n-nodes-clientify.svg)](https://www.npmjs.com/package/n8n-nodes-clientify)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+Official n8n node for integrating with Clientify CRM via Model Context Protocol (MCP). This node provides seamless access to all Clientify CRM operations including contacts, companies, deals, tasks, and more.
+
+## Table of Contents
+
+- [Installation](#installation)
+- [Prerequisites](#prerequisites)
+- [Configuration](#configuration)
+- [Available Operations](#available-operations)
+- [Trigger Events](#trigger-events)
+- [Usage Examples](#usage-examples)
+- [Troubleshooting](#troubleshooting)
+- [Support](#support)
+- [License](#license)
+
+## Installation
+
+### In n8n (GUI)
+
+1. Go to **Settings** → **Community Nodes**
+2. Click **Install**
+3. Enter: `n8n-nodes-clientify`
+4. Click **I understand the risks** and then **Install**
+5. **Restart n8n** (important - the node won't appear until you restart)
+
+### Via npm (Command Line)
+
+```bash
+cd ~/.n8n/nodes
+npm install n8n-nodes-clientify
+# Restart n8n
+```
+
+### Docker
+
+If running n8n in Docker, ensure you persist the nodes directory:
+
+```yaml
+volumes:
+  - n8n_data:/home/node/.n8n
+```
+
+Or enable auto-reinstall on restart:
+
+```yaml
+environment:
+  - N8N_REINSTALL_MISSING_PACKAGES=true
+```
+
+## Prerequisites
+
+- **n8n version:** 0.180.0 or higher
+- **Node.js version:** 20.15 or higher
+- **Clientify Account:** Active Clientify CRM account with API access
+- **Authentication Token:** JWT token from Clientify MCP server
+
+## Configuration
+
+### Step 1: Obtain Your Clientify MCP Token
+
+1. Log into your Clientify account
+2. Navigate to API settings or contact your Clientify administrator
+3. Generate or copy your MCP authentication token (JWT format)
+
+### Step 2: Add Credentials in n8n
+
+1. In n8n, go to **Credentials** → **New**
+2. Search for **"Clientify MCP API"**
+3. Enter your **Authentication Token** (JWT)
+4. Click **Save**
+
+### Step 3: Use the Node
+
+1. In your workflow, click **+** to add a node
+2. Search for **"Clientify"**
+3. Select the **Clientify** node
+4. Choose your saved credentials
+5. Select an operation from the dropdown
+6. Configure the parameters for your operation
+
+## Available Operations
+
+This node dynamically supports **26 operations** from the Clientify MCP API:
+
+### 📊 Companies
+- **List Companies** - Retrieve all companies with pagination
+- **Get Company** - Get detailed information for a specific company by ID
+- **Create Company** - Create a new company in the CRM
+- **Update Company** - Update an existing company
+- **Delete Company** - Remove a company from the CRM
+- **Search Companies** - Search for companies by criteria
+
+### 👥 Contacts
+- **List Contacts** - Retrieve all contacts or search for specific contacts
+- **Get Contact** - Get detailed information for a specific contact by ID
+- **Create Contact** - Create a new contact in the CRM
+- **Update Contact** - Update an existing contact
+- **Delete Contact** - Remove a contact from the CRM
+
+### 💼 Deals
+- **List Deals** - Retrieve all deals with filtering and pagination
+- **List Deals By Stage** - Filter deals by pipeline stage
+- **Get Deal** - Get detailed information for a specific deal by ID
+- **Create Deal** - Create a new deal/opportunity
+- **Update Deal** - Update an existing deal
+- **Delete Deal** - Remove a deal from the CRM
+- **Mark Deal Won** - Mark a deal as won/closed successfully
+- **Mark Deal Lost** - Mark a deal as lost/closed unsuccessfully
+
+### ✅ Tasks
+- **List Tasks** - Retrieve all tasks with pagination
+- **Get Task** - Get detailed information for a specific task by ID
+- **Create Task** - Create a new task/activity
+- **List Activity Types** - Get available activity types for tasks
+
+### ⚙️ Configuration & Utilities
+- **List Pipelines** - Retrieve all available sales pipelines
+- **Get Current User** - Get information about the authenticated user
+- **Get Current Time** - Get current date/time with timezone awareness
+
+## Trigger Events
+
+**NEW in v0.2.0!** The Clientify Trigger node enables automatic workflow execution when events occur in Clientify CRM.
+
+📚 **For complete trigger documentation with payload examples and webhook URLs, see [TRIGGERS_REFERENCE.md](TRIGGERS_REFERENCE.md)**
+
+### Available Triggers
+
+#### 👥 Contact Triggers
+- **Contact Created** - Fires when a new contact is added to Clientify
+- **Contact Updated** - Fires when contact details are modified
+- **Contact Deleted** - Fires when a contact is removed
+
+#### 📊 Company Triggers
+- **Company Created** - Fires when a new company is added to Clientify
+- **Company Updated** - Fires when company details are modified
+- **Company Deleted** - Fires when a company is removed
+
+#### 💼 Deal Triggers
+- **Deal Created** - Fires when a new deal is created
+- **Deal Updated** - Fires when deal details are modified
+- **Deal Won** - Fires when a deal is marked as won
+- **Deal Lost** - Fires when a deal is marked as lost
+- **Deal Stage Changed** - Fires when a deal moves to a different pipeline stage
+- **Deal Deleted** - Fires when a deal is removed
+
+#### ✅ Task Triggers
+- **Task Created** - Fires when a new task is created
+- **Task Completed** - Fires when a task is marked as completed
+- **Task Due Soon** - Fires when a task is approaching its due date
+- **Task Overdue** - Fires when a task passes its due date
+
+### Setting Up Webhooks
+
+1. **Add Clientify Trigger node** to your workflow in n8n
+2. **Select the event** you want to listen for (e.g., "Contact Created")
+3. **Save and activate** the workflow to generate webhook URL
+4. **Copy the webhook URL** from the trigger node
+5. **Configure webhook in Clientify:**
+   - Go to Clientify Settings → Webhooks
+   - Add new webhook
+   - Paste the n8n webhook URL
+   - Select the corresponding event type
+   - Save the webhook configuration
+
+### Webhook Data Structure
+
+When a webhook triggers your workflow, the data is automatically flattened for easy access:
+
+**Contact Created Example:**
+```json
+{
+  "event": "contact.created",
+  "timestamp": "2025-10-02T15:30:00Z",
+  "contact_id": 12345,
+  "first_name": "John",
+  "last_name": "Doe",
+  "email": "john.doe@example.com",
+  "phone": "+1234567890",
+  "company_id": 456,
+  "company_name": "Acme Corp"
+}
+```
+
+**Deal Won Example:**
+```json
+{
+  "event": "deal.won",
+  "timestamp": "2025-10-02T17:00:00Z",
+  "deal_id": 98765,
+  "title": "Enterprise License Sale",
+  "value": 50000,
+  "currency": "USD",
+  "contact_id": 12345,
+  "contact_name": "John Doe",
+  "company_id": 789,
+  "company_name": "New Corp"
+}
+```
+
+## Usage Examples
+
+### Example 1: List All Contacts
+
+Retrieve a paginated list of all contacts in your CRM.
+
+**Configuration:**
+- **Operation:** `List Contacts`
+- **Parameters:** Leave empty for all contacts, or add filters
+
+**Output:** Array of contact objects with names, emails, phone numbers, and IDs.
+
+```json
+[
+  {
+    "id": 123,
+    "first_name": "John",
+    "last_name": "Doe",
+    "email": "john.doe@example.com",
+    "phone": "+1234567890",
+    "company_id": 456
+  }
+]
+```
+
+---
+
+### Example 2: Create a New Company
+
+Add a new company to your Clientify CRM.
+
+**Configuration:**
+- **Operation:** `Create Company`
+- **Parameters:**
+  - **name** (required): `Acme Corporation`
+  - **domain**: `acme.com`
+  - **industry**: `Technology`
+  - **description**: `Leading software provider`
+
+**Output:** Created company object with assigned ID.
+
+```json
+{
+  "id": 789,
+  "name": "Acme Corporation",
+  "domain": "acme.com",
+  "industry": "Technology",
+  "created_at": "2025-10-01T12:00:00Z"
+}
+```
+
+---
+
+### Example 3: Update a Deal and Mark as Won
+
+Update deal details and mark it as successfully closed.
+
+**Workflow:**
+1. **First Node:** Get the deal you want to update
+   - **Operation:** `Get Deal`
+   - **deal_id:** `{{$json.deal_id}}`
+
+2. **Second Node:** Update the deal
+   - **Operation:** `Update Deal`
+   - **deal_id:** `{{$json.id}}`
+   - **value:** `50000`
+   - **notes:** `Final negotiations completed`
+
+3. **Third Node:** Mark as won
+   - **Operation:** `Mark Deal Won`
+   - **deal_id:** `{{$json.id}}`
+
+---
+
+### Example 4: Search Companies and Create Contacts
+
+Find a company by name and create a new contact associated with it.
+
+**Workflow:**
+1. **Search Companies:**
+   - **Operation:** `Search Companies`
+   - **query:** `Acme`
+
+2. **Create Contact:**
+   - **Operation:** `Create Contact`
+   - **first_name:** `Jane`
+   - **last_name:** `Smith`
+   - **email:** `jane.smith@acme.com`
+   - **company_id:** `{{$json.id}}` (from previous node)
+
+---
+
+### Example 5: List All Deals in a Specific Pipeline Stage
+
+Retrieve deals that are in the "Negotiation" stage.
+
+**Configuration:**
+- **Operation:** `List Deals By Stage`
+- **Parameters:**
+  - **stage:** `Negotiation`
+
+**Use Case:** Create automated alerts when deals reach certain stages, or generate reports on pipeline health.
+
+---
+
+### Example 6: Auto-Send Welcome Email (Using Trigger)
+
+**NEW in v0.2.0!** Automatically send a welcome email when a new contact is created.
+
+**Workflow:**
+1. **Clientify Trigger**
+   - Event: `Contact Created`
+
+2. **Send Email**
+   - To: `{{$json.email}}`
+   - Subject: `Welcome {{$json.first_name}}!`
+   - Body: Welcome message
+
+3. **Create Task**
+   - Title: `Follow up with {{$json.first_name}} {{$json.last_name}}`
+   - Contact ID: `{{$json.contact_id}}`
+   - Due: 3 days from now
+
+**Result:** When someone creates a contact "Jane Smith" in Clientify:
+- Jane automatically receives welcome email
+- Follow-up task is created for sales team
+- All happens instantly without manual intervention
+
+---
+
+### Example 7: Deal Won Notification (Using Trigger)
+
+**NEW in v0.2.0!** Notify your team when a deal is won.
+
+**Workflow:**
+1. **Clientify Trigger**
+   - Event: `Deal Won`
+
+2. **Slack** (or Email)
+   - Message: `🎉 Deal Won! {{$json.title}} - ${{$json.value}} - {{$json.contact_name}}`
+   - Channel: `#sales-wins`
+
+3. **Clientify** (Action Node)
+   - Operation: `Create Task`
+   - Title: `Onboard {{$json.contact_name}}`
+   - Deal ID: `{{$json.deal_id}}`
+
+**Result:** When a deal is marked as won:
+- Team gets instant Slack notification
+- Onboarding task is automatically created
+- No manual steps required
+
+---
+
+## Troubleshooting
+
+### Node Doesn't Appear After Installation
+
+**Problem:** The Clientify node doesn't show up in the node panel after installing.
+
+**Solution:**
+1. **Restart n8n completely** (required for new nodes)
+2. Clear your browser cache (Ctrl+Shift+Delete or Cmd+Shift+Delete)
+3. Search for "Clientify" (not the package name) in the node search
+4. Verify installation in **Settings → Community Nodes**
+
+### Authentication Errors
+
+**Problem:** "Authentication failed" or 401/403 errors.
+
+**Solution:**
+1. Verify your JWT token is valid and not expired
+2. Check that the token has the correct permissions in Clientify
+3. Ensure you're using the Clientify MCP token (not a regular API key)
+4. Try creating a new credential with a fresh token
+
+### "Missing required parameter" Errors
+
+**Problem:** Operation fails with missing parameter errors.
+
+**Solution:**
+1. Check which fields are marked as **required** (indicated by red asterisk)
+2. Some operations require specific IDs (contact_id, company_id, etc.)
+3. Use `Get` operations first to retrieve IDs, then pass them to `Update` or `Delete` operations
+4. Review the parameter descriptions for expected format
+
+### Operations Return Empty Results
+
+**Problem:** List operations return no results even though data exists.
+
+**Solution:**
+1. Check pagination parameters (page, page_size)
+2. Verify your token has permission to access the requested resources
+3. Try without filters first to confirm data access
+4. Check the Clientify web UI to confirm data exists
+
+### Node Execution Fails in Docker
+
+**Problem:** Node fails with "package not found" errors in Docker environments.
+
+**Solution:**
+1. Ensure nodes directory is persisted in volumes:
+   ```yaml
+   volumes:
+     - n8n_data:/home/node/.n8n
+   ```
+2. Or enable auto-reinstall:
+   ```yaml
+   environment:
+     - N8N_REINSTALL_MISSING_PACKAGES=true
+   ```
+3. Restart the container after installing the node
+
+### Rate Limiting Errors
+
+**Problem:** "Too many requests" or 429 errors.
+
+**Solution:**
+1. Add delay between operations using n8n's **Wait** node
+2. Reduce the frequency of scheduled workflows
+3. Batch operations where possible
+4. Contact Clientify support to increase rate limits if needed
+
+## Parameter Reference
+
+### Common Parameters
+
+Most operations support these common parameters:
+
+- **page** (number): Page number for pagination (default: 1)
+- **page_size** (number): Number of results per page (default: 20, max: 100)
+- **sort_by** (string): Field to sort by (e.g., "created_at", "name")
+- **sort_order** (string): Sort direction ("asc" or "desc")
+
+### ID Parameters
+
+Operations that work with specific records require an ID parameter:
+
+- **company_id** (number): Unique identifier for a company
+- **contact_id** (number): Unique identifier for a contact
+- **deal_id** (number): Unique identifier for a deal
+- **task_id** (number): Unique identifier for a task
+
+## Advanced Usage
+
+### Combining Multiple Operations
+
+Create powerful workflows by chaining operations:
+
+```
+Trigger → Search Companies → Create Contact → Create Deal → Create Task
+```
+
+### Error Handling
+
+Use n8n's built-in error handling:
+
+1. Enable **"Continue On Fail"** in node settings
+2. Add an **IF** node to check for errors
+3. Route errors to notification nodes (Email, Slack, etc.)
+
+### Data Transformation
+
+Use n8n's **Code** or **Function** nodes to transform data between operations:
+
+```
+List Contacts → Code Node (transform) → External API
+```
+
+## Development & Contribution
+
+This is an official Clientify node. Contributions are welcome!
+
+**Repository:** https://github.com/contacteitor/clientify_n8n
+
+**Report Issues:** https://github.com/contacteitor/clientify_n8n/issues
+
+**Documentation:** See the repository for full documentation
+
+## Support
+
+- **Issues & Bugs:** https://github.com/contacteitor/clientify_n8n/issues
+- **Email:** develop@clientify.com
+- **Clientify Documentation:** https://mcp.clientify.com/docs
+
+## Version History
+
+- **v0.2.0** (2025-10-02): Trigger support added
+  - **NEW:** Clientify Trigger node for webhook events
+  - 16 trigger events (contact, company, deal, task)
+  - Automatic workflow execution on Clientify events
+  - Flattened webhook payload for easy data access
+
+- **v0.1.0** (2025-10-01): Initial release
+  - 26 MCP operations supported
+  - Dynamic field generation from MCP API
+  - Full CRUD operations for contacts, companies, deals, tasks
+  - Pipeline and user management
+
+## License
+
+MIT License - see [LICENSE](LICENSE) file for details.
+
+Copyright (c) 2025 Clientify
+
+---
+
+**Made with ❤️ by Clientify**
+
+*This is an official Clientify node. n8n is a trademark of its respective owner.*